Difference between revisions of "Repository HOWTO"

From AIRWiki
Jump to: navigation, search
m (→‎Rules to use the repository)
m (→‎Structure of the Development repository)
 
(37 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
=Contents of the repository=
+
AIRLab stores software and other material in a Subversion repository, described by page [[AIRLab Repository]]. Within such repository, a specific section, called '''Development''', is dedicated to storing readily available modular software compatible with [[ROS HOWTO | ROS]]. In order to ease code reuse, users of this repository must strictly comply with the '''criteria and rules''' described by this page.
−
AIRLab stores the source code of the software developed in the Lab in [https://svn.ws.dei.polimi.it/showproject.plp?p=airlab this Subversion repository].
+
−
In order to ease code reuse, usage of such repository must be done according to some rules. This page illustrates the rules.
+
  
 +
=Contents of the Development repository=
 
The repository is subdivided into two separate sections:
 
The repository is subdivided into two separate sections:
−
#'''generic_libraries''' containing software packages that implement single robot functionalities in the form of libraries for general use. Each library must be a stand-alone package with its own Makefile, to be compiled separately. 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. The source code for a "generic" ROS node template of this kind may be provided within the library.
+
#'''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.
−
#'''specific_modules''', containing software packages that are dedicated to specific robots (or other devices). Each package can take one of the following forms:
+
#'''Specific_Modules''', containing software packages that are dedicated to specific robots (or other devices). Each package comprises one or more of the following elements:
−
##A complete [[ROS_HOWTO | ROS package]] implementing all the functionalities of the device, able to operate on its own as a ROS system (including launchfiles);
+
::*''Special-purpose software libraries'' specifically dedicated to one robot or device. They provide functionalities that are too specialized for inclusion in the "Generic_Libraries" section.
−
##One or more [[ROS_HOWTO | ROS nodes]] implementing one of the functionalities of the device, ready for integration into larger ROS systems but not able to operate on their own as ROS systems;
+
::*[[ROS_HOWTO | ROS nodes]] implementing one or more of the functionalities of the device. It is '''mandatory''' that each of these nodes takes the form of a '''ROS wrapper node''': i.e., a node that does ''not'' contain data processing code, and uses instead an external library to do the processing. Such library can be a special-purpose one defined within the same module of the node, or one of the generic libraries available in the AIRLab repository. The wrapper node must give access to its capabilities to other ROS nodes through the exchange of ROS messages. If suitable predefined ROS message formats are not available, the wrapper node must also include the files that define new, suitable ROS message formats.
−
##a special-purpose ''software library'' which is dedicated to the device, the function of which is too specialized for inclusion in the ''generic_libraries'' section of the repository. In this case it is '''mandatory''' to provide, along with the library, a ''ROS wrapper'' in the form of one or more ROS nodes: the ROS wrapper is the '''only''' allowed method to access the library.
+
::*[[ROS_HOWTO | ROS packages]] implementing the functionalities of the device that the element of Specific_Modules refers to. A ROS package uses one or more of the ROS nodes defined by the module, combining them with other files (e.g., ROS "launchfiles") to define a working ROS system dedicated to managing the device.
  
−
=Structure of the repository=
+
Please note that ROS wrapper nodes are the '''only''' allowed method to access both generic and special-purpose libraries.
−
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'''
+
=Structure of the Development repository=
−
**behavior
+
As already mentioned, the Development repository includes two subdirectories: Generic_Libraries and Specific_Modules.
−
***''brian''
+
The first one contains one subdirectory for each software library, as shown by this example:
−
**controller
+
 
−
***''airlab_joypad''
+
*'''Generic_Libraries'''
 +
**WHATSTHIS.txt
 +
**...
 +
**brian
 +
***WHATSTHIS.txt
 +
***''(library components)''
 +
**...
 
**fuzzy
 
**fuzzy
−
***''fuzzy''
+
***WHATSTHIS.txt
−
**obstacle
+
***''(library components)''
−
**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.
+
In every directory must be present a text file called '''WHATSTHIS.txt''' that describes the contents of the directory. Every time the contents of the directory are changed, it is '''mandatory''' to check if the contents of WHATSTHIS.txt have to be updated, and perform the required changes '''immediately'''.
 +
 
 +
The Specific_Modules subdirectory of the Development repository includes one subdirectory for each special-purpose software modules. The following is an example of the type of content it includes: it shows the software module dedicated to the [[Lurch]] autonomous wheelchair robot and some of its submodules (e.g., the one which generates motor commands).
  
−
*'''specific_modules'''
+
*'''Specific_Modules'''
 +
**WHATSTHIS.txt
 
**...
 
**...
−
**''wheelchair''
+
**wheelchair
−
***audio
+
***WHATSTHIS.txt
−
***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
 
***motor
 +
****WHATSTHIS.txt
 +
****''(submodule components)''
 
***odometry
 
***odometry
−
***pose
+
****WHATSTHIS.txt
−
***shared
+
****''(submodule components)''
−
***sonar (uses "airlab_sonar_board" generic library)
+
***...''(other submodules of module wheelchair)''
−
***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=
+
=Rules to use the Development repository=
 
Whoever develops software for AIRLab must comply with the following criteria for software design and inclusion in the Subversion 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.'''
+
'''Rule 1: everything must be sufficiently documented.'''
−
Software is considered "sufficiently documented" if the following condition is verified.
+
Software is considered "sufficiently documented" only 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:
+
::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:
 
::* understand what the software is for;
 
::* understand what the software is for;
 
::* understand what each individual file belonging to the software is for;
 
::* understand what each individual file belonging to the software is for;
 +
::* understand how to configure the software (if applicable);
 
::* understand how the functionalities of the software can be used (by other software);
 
::* understand how the functionalities of the software can be used (by other software);
 
::* compile the software.
 
::* compile the software.
  
−
'''A valid test application must be provided.'''
+
'''Rule 2: a valid test application must be provided.'''
−
A test application must be present in a separate directory (called ''test_application'') within the software. It must be possible to remove such directory without altering the functionalities of the software, and without damaging the possibility to compile the software. The test application is considered "valid" if the following condition is verified.
+
A test application must be provided with the software. Such application is considered "valid" only 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:  
 
::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;
 
::* compile and run the test application;
−
::* configure the test application (if required);
+
::* understand how to configure the test application (if applicable);
 
::* understand the functioning of the test application and interpret its output;
 
::* 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.
+
::* 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. Compilation of the test application must be independent from compilation of the software. It must be possible to remove the directory of the test application without any effect on the software.

Latest revision as of 14:26, 5 April 2013

AIRLab stores software and other material in a Subversion repository, described by page AIRLab Repository. Within such repository, a specific section, called Development, is dedicated to storing readily available modular software compatible with ROS. In order to ease code reuse, users of this repository must strictly comply with the criteria and rules described by this page.

Contents of the Development 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 comprises one or more of the following elements:
  • Special-purpose software libraries specifically dedicated to one robot or device. They provide functionalities that are too specialized for inclusion in the "Generic_Libraries" section.
  • ROS nodes implementing one or more of the functionalities of the device. It is mandatory that each of these nodes takes the form of a ROS wrapper node: i.e., a node that does not contain data processing code, and uses instead an external library to do the processing. Such library can be a special-purpose one defined within the same module of the node, or one of the generic libraries available in the AIRLab repository. The wrapper node must give access to its capabilities to other ROS nodes through the exchange of ROS messages. If suitable predefined ROS message formats are not available, the wrapper node must also include the files that define new, suitable ROS message formats.
  • ROS packages implementing the functionalities of the device that the element of Specific_Modules refers to. A ROS package uses one or more of the ROS nodes defined by the module, combining them with other files (e.g., ROS "launchfiles") to define a working ROS system dedicated to managing the device.

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

Structure of the Development repository

As already mentioned, the Development repository includes two subdirectories: Generic_Libraries and Specific_Modules. The first one contains one subdirectory for each software library, as shown by this example:

  • Generic_Libraries
    • WHATSTHIS.txt
    • ...
    • brian
      • WHATSTHIS.txt
      • (library components)
    • ...
    • fuzzy
      • WHATSTHIS.txt
      • (library components)
    • ...

In every directory must be present a text file called WHATSTHIS.txt that describes the contents of the directory. Every time the contents of the directory are changed, it is mandatory to check if the contents of WHATSTHIS.txt have to be updated, and perform the required changes immediately.

The Specific_Modules subdirectory of the Development repository includes one subdirectory for each special-purpose software modules. The following is an example of the type of content it includes: it shows the software module dedicated to the Lurch autonomous wheelchair robot and some of its submodules (e.g., the one which generates motor commands).

  • Specific_Modules
    • WHATSTHIS.txt
    • ...
    • wheelchair
      • WHATSTHIS.txt
      • motor
        • WHATSTHIS.txt
        • (submodule components)
      • odometry
        • WHATSTHIS.txt
        • (submodule components)
      • ...(other submodules of module wheelchair)
    • ...

Rules to use the Development repository

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

Rule 1: everything must be sufficiently documented. Software is considered "sufficiently documented" only 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:
  • understand what the software is for;
  • understand what each individual file belonging to the software is for;
  • understand how to configure the software (if applicable);
  • understand how the functionalities of the software can be used (by other software);
  • compile the software.

Rule 2: a valid test application must be provided. A test application must be provided with the software. Such application is considered "valid" only 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;
  • understand how to configure the test application (if applicable);
  • 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. Compilation of the test application must be independent from compilation of the software. It must be possible to remove the directory of the test application without any effect on the software.

Retrieved from "https://airwiki.elet.polimi.it/index.php?title=Repository_HOWTO&oldid=16167"