Repository HOWTO

AIRLab stores the source code of the software developed in the Lab in this Subversion repository. In order to ease code reuse, usage of such repository must be done according to some criteria and rules. This page describes them.

Contents of the repository

The repository is subdivided into two separate sections:

1. generic_libraries containing software packages that implement robot functionalities, in the form of libraries for general use. Each library must take the form of a stand-alone software package with its own Makefile, to be compiled separately from any software which uses it. A generic library is not intended to be used "as is". Instead, you have to set up one or more ROS nodes that use the library (see below). The source code for a "generic" ROS node template of this kind may be provided as part of the library.
2. specific_modules, containing software packages that are dedicated to specific robots (or other devices). Each package can comprise the following elements:
   1. Special-purpose software libraries which are dedicated only to the device and provide functionalities that are too specialized to be useful for inclusion in the generic_libraries section.
   2. ROS nodes implementing one or more of the functionalities of the device, ready for integration into larger ROS systems but not able to operate on their own as ROS systems. It is mandatory that each of these ROS nodes take the form of a ROS wrapper node: i.e., a node that gives access to the functionalities provided by a library to other ROS nodes by exchange of ROS messages. If suitable predefined ROS message formats are not available, the wrapper node must also define suitable new formats. The libraries that the wrapper node act as an interface to can be the special-purpose ones defined for the device that the node also refers to, or generic libraries.
   3. Complete ROS packages implementing the functionalities of the device. A ROS package is able to operate on its own as a ROS system (in particular, it includes including its own launchfiles), and uses one or more ROS nodes.

Please note that ROS wrapper nodes are the only allowed method to access both generic and special-purpose libraries.

Structure of the repository

The following is a template for the structure of the generic_libraries part of the AIRLab Subversion source code repository. Elements in italic are examples (i.e., actual software modules developed in AIRLab).

• generic_libraries
  • behavior
    • brian
  • controller
    • airlab_joypad
  • fuzzy
    • fuzzy
  • obstacle
  • motor_control
  • multi_robot
    • scare
  • odometry
  • planning
    • spike
  • play_media
  • pose
    • airlab_artoolkitplus
  • safety
    • airlab_remote
  • sensor
    • imu
      • airlab_Xsense
    • laser
      • airlab_hokuyo
    • sonar
      • airlab_sonar_board
    • vision
      • airlab_prosilica

The following is an example of the type of content of the specific modules section of the AIRLab Subversion source code repository. It refers to the Lurch autonomous wheelchair robot.

• specific_modules
  • ...
  • wheelchair
    • audio
    • brian (uses "brian" generic library)
    • emergency_batt_level (uses "airlab_remote" generic library)
    • fuzzy (uses "fuzzy" generic library)
    • hokuyo (uses "airlab_hokuyo" generic library)
    • joypad (uses "airlab_joypad" generic library)
    • misc
    • motor
    • odometry
    • pose
    • shared
    • sonar (uses "airlab_sonar_board" generic library)
    • spike (uses "spike" generic library)
    • wheelchair (robot coordinator module)
    • wheelchair_imu (uses "airlab_xsense" generic library)
    • wheelchair_motor
    • wheelchair_vision (uses "airlab_artoolkitplus" generic library)
  • ...

Rules to use the repository

Whoever develops software for AIRLab must comply with the following criteria for software design and inclusion in the Subversion repository.

Everything must be sufficiently documented. Software is considered "sufficiently documented" if the following condition is verified.

Any person with generic experience in robotics and programming but no idea whatsoever of what the software does must be able, after reading only the files available within the software (including accompanying documents and comments at the head of source code files), to do all of the following:

• understand what the software is for;
• understand what each individual file belonging to the software is for;
• understand how the functionalities of the software can be used (by other software);
• compile the software.

A valid test application must be provided. The test application provided with the software is considered "valid" if the following condition is verified.

Any person with generic experience in robotics and programming but no idea whatsoever of what the software does must be able, after reading only the documentation provided with the software, to do all of the following:

• compile and run the test application;
• configure the test application (if required);
• understand the functioning of the test application and interpret its output;
• verify, using only the test application, if every functionality of the software is correctly operating.

The test application must reside in a directory dedicated to it (within the software) and must have its own makefile. It must be possible to remove the directory of the test application without any effect on the software.