View source for Software Development Guide


== Overview ==
This guide describes two examples of what is involved when developing a YARP-based component that is compliant with the DREAM standards for software engineering. 


The first example, <code>protoComponent</code>, implements some very simple image processing and analysis (binary segmentation using a supplied threshold and then count the number of foreground pixels).


The second example, <code>protoComponentGUI</code>, explains how to write a component that implements a simple graphic use interface.  In this case, the GUI allows the user to set the threshold with a slider widget and then sends the threshold to   <code>protoComponent</code>.  It receives some statistics from <code>protoComponent</code>, specifically the number of foreground pixels and the current time, and writes them to a text display. It also receives the binary image from   <code>protoComponent</code> and displays it along with the original colour image that it receives from the source that also feeds  <code>protoComponent</code>.


Both examples are accompanied by a test application, again adhering to the DREAM standards.


=== File Organization ===
As noted in the [[Mandatory Standards for File Organization]],  the implementation of a typical DREAM component comprises four files. These are the interface file, two implementation files, and the application file:


* The interface file is a header file, e.g. <code>protoComponent.h</code>, with the class declarations and method prototype declarations but no method implementations (C++) or the function prototype declarations (C).  It also contains the Doxygen documentation comments explaining the purpose and usage of the component (see [[Mandatory Standards for Internal Documentation]]).


*The implementation files contains the source code for the implementation of each class method (C++) or the source code of each function (C).   For convenience, the implementation is separated in two files:


# <code>protoComponentConfiguration.cpp</code> contains the code that handles the component’s configuration and coordination functionality.
# <code>protoComponentComputation.cpp</code> contains the code that handles the component’s computation and communication functionality.


* The application file, e.g.  <code>protoComponentMain.cpp</code>,  contains the <code> main()</code>  function that instantiates the module object and calls the <code>runModule</code> method to effect the configuration, coordination, computation, and communication for that component.


Therefore,  the four <code>protoComponent</code> files are:

 protoComponent.h 
 protoComponentMain.cpp
 protoComponentConfiguration.cpp 
 protoComponentComputation.cpp

and the four <code>protoComponentGUI</code> files are:

 protoComponentGUI.h 
 protoComponentGUIMain.cpp
 protoComponentGUIConfiguration.cpp 
 protoComponentGUIComputation.cpp


=== Code Location ===

All the code for these examples is available in the DREAM software repository.  For convenience, you can also review the code here:

* [[The protoComponent Example | <code>protoComponent</code> source code]]
* [[The protoComponentTEST Example | <code>protoComponentTEST.xml</code> application]]
* [[The protoComponentGUI  Example | <code>protoComponentGUI</code> source code]]
* [[The protoComponentGUITEST Example | <code>protoComponentGUITEST.xml</code> application]]


=== Guide Structure ===

There are four main parts to this guide, in addition to this overview, some focussing on the <code>protoComponent</code> example and others on the <code>protoComponentGUI</code> example.


====  Component Configuration and Coordination: the <code>RFModule</code> Class ====

We begin with the functionality associated with configuration and coordination, i.e. with the <code>protoComponentConfiguration.cpp</code> and  <code>protoComponent.h</code> files.  This functionality revolves around the <code>RFModule</code> class.  The <code>protoComponentGUIConfiguration.cpp</code> and  <code>protoComponentGUI.h</code> files have essentially the same structure.


This section also deals with the  <code>main()</code> function, i.e. with the  <code>protoComponentApplication.cpp</code> file.   It shows how to instantiate a module derived from the <code>RFModule</code> class, set the default configuration file and path for the resource finder, and run the module.  This allows the component to be configured using the resource finder.  


Once this is done, the derived module then instantiates a <code>Thread</code>  or a  <code>RateThread</code> object and launches it, passing it as arguments all the relevant resources (e.g. port names and parameter values) located by the resource finder.


Finally, it is also responsible for shutting down the thread gracefully by stopping the thread, interrupting any port communications, and closing the ports.


====  Component  Computation and Communication: the <code>Thread</code> and  <code>RateThread</code> Classes  ====

We then address the functionality associated with computation and communication, i.e. with the  <code>protoComponentComputation.cpp</code> and  <code>protoComponent.h</code> files.   This functionality revolves around the  <code>Thread</code>  and  <code>RateThread</code> classes: how to access the parameters passed to it from the derived <code>RFModule</code> object and how to perform some useful work.


====   GUI Component Computation and Communication: the <code>FLTK</code> and  <code>guiUtilities</code> Libraries  ====

We now show how you can write your own graphic user interface for the <code>protoComponent</code> component.   This will be implemented as a separate stand-along component <code>protoComponentGUI</code>. As noted above, the functionality associated with configuration and coordination, i.e. with the <code>protoComponentGUIConfiguration.cpp</code> and  <code>protoComponentGUI.h</code> files, is essentially the same as for the <code>protoComponent</code> example. Again, this functionality revolves around the <code>RFModule</code> class.


Instead, this section addresses the functionality associated with computation and communication, i.e. with the  <code> protoComponentGUIComputation.cpp </code> and  <code>protoComponent.h </code> files.   Again, the functionality revolves around the  <code>Thread</code>  and  <code>RateThread</code> classes but here we explain how to configure the graphic user interface with the ''FLTK'' and  ''guiUtilities'' libraries.


==== Test Applications  ====

This section describes two test applications.   


The first test application shows how to configure and run a simple application to use the <code>protoComponent</code> by connecting it to other components that provide input images and display the output images. This application uses <code>yarpview</code> modules to view the images. The threshold is modified online by sending commands  to <code>protoComponent</code> from the command line in a terminal window.


The second test application shows how to configure and run a simple application to use <code> protoComponent</code>  and <code> protoComponentGUI</code> together.  In this case, the images are displayed in the GUI rather than <code>yarpview</code> displays and the threshold is modified interactively using the GUI controls.


==  Component Configuration and Coordination: The <code>RFModule</code> Class ==

The starting point in writing any DREAM component is to develop a sub-class of the [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1RFModule.html  yarp::os::RFModule] class.  


First, we define a sub-class, or derived class, of the <code>yarp::os::RFModule</code> class.  The module's variables - ''and specifically the module's parameters and ports'' - go in the private data members part and you need to override three methods:

* <code>bool configure(); </code>
* <code>bool interruptModule(); </code>
* <code>bool close(); </code>

We will see later that there are three other methods which can be useful to override:

* <code>bool respond();</code>
* <code>double getPeriod(); </code>
* <code>bool updateModule();</code>

In the following, we assume we are writing a module named <code>protoComponent</code>.  This module will be implemented as a sub-class [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1RFModule.html yarp::os::RFModule] called <code>ProtoComponent</code> (it is a capital P because it is a sub-class).  For convenience, the header comments have been removed.

 /** @file protoComponent.h  Interface file for the example DREAM component */
 
 #include <iostream>
 #include <string>
 
 #include <yarp/sig/all.h>
 #include <yarp/os/all.h>
 #include <yarp/os/RFModule.h>
 #include <yarp/os/Network.h>
 #include <yarp/os/Thread.h>
  
 using namespace std;
 using namespace yarp::os; 
 using namespace yarp::sig;
   
 class ProtoComponentThread : public Thread {
 
 private:
 
    /* class variables */
 
    bool               debug;
    int                x, y;
    PixelRgb           rgbPixel;
    ImageOf<PixelRgb> *image;
    int               *thresholdValue;   
    VectorOf<int>     *thresholdVector;
    int               numberOfForegroundPixels;
 
    /* thread parameters: they are pointers so that they refer to the original variables in protoComponent */
 
    BufferedPort<ImageOf<PixelRgb> > *imagePortIn;
    BufferedPort<VectorOf<int> >     *thresholdPortIn; 
    BufferedPort<ImageOf<PixelRgb> > *imagePortOut; 
    BufferedPort<Bottle>             *statisticsPortOut; 
   
 
   public:
  
     /* class methods */
  
     ProtoComponentThread(BufferedPort<ImageOf<PixelRgb> > *imageIn, 
                          BufferedPort<VectorOf<int> >     *thresholdIn, 
                          BufferedPort<ImageOf<PixelRgb> > *imageOut,
                          BufferedPort<Bottle>             *statisticsOut, 
                          int *threshold );
     bool threadInit();     
     void threadRelease();
     void run(); 
 };
 
 
 class ProtoComponent:public RFModule {
 
    /* module parameters */
 
    string moduleName;
    string imageInputPortName;
    string thresholdInputPortName;
    string imageOutputPortName;
    string statisticsOutputPortName;  
    string handlerPortName;
    string cameraConfigFilename;
    float  fxLeft,  fyLeft;          // focal length
    float  fxRight, fyRight;         // focal length
    float  cxLeft,  cyLeft;          // coordinates of the principal point
    float  cxRight, cyRight;         // coordinates of the principal point
    int    thresholdValue;
 
    /* class variables */
 
    BufferedPort<ImageOf<PixelRgb> > imageIn;       // example image input port
    BufferedPort<VectorOf<int> >     thresholdIn;   // example vector input port 
    BufferedPort<ImageOf<PixelRgb> > imageOut;      // example image output port
    BufferedPort<Bottle>             statisticsOut; // example bottle output port
    Port handlerPort;                               // a port to handle interactive messages (also uses bottles)
 
    /* pointer to a new thread to be created and started in configure() and stopped in close() */
 
    ProtoComponentThread *protoComponentThread;
 
 public:
   
    bool configure(yarp::os::ResourceFinder &rf); // configure all the module parameters and return true if successful
    bool interruptModule();                       // interrupt, e.g., the ports 
    bool close();                                 // close and shut down the module
    bool respond(const Bottle& command, Bottle& reply);
    double getPeriod(); 
    bool updateModule();
 }; 

Here we deal with the various issues of implementing the module, particularly configuration of the component from external parameters and files, and run-time interaction.


The actual work to be done by the component is accomplished by another sub-class  of a <code>Thread</code> class.  The definition of this sub-class is also included in the interface header file, e.g. <code>protoComponent.h</code> but the implementation is effected in a separate source file, e.g. <code>protoComponentComputation.cpp</code>.


Perhaps the trickiest part of writing the software to implement a component is understanding the way that the <code>RFModule</code> and <code>Thread</code> share the work between them and how they interact.  That's exactly what we will explain in to following, once we have covered how the <code>RFModule</code> object handles all the configuration and coordination functionality.


First, some clarification. By ''configuration'' we mean the ability to specify the way that a given component is used.  There are two aspects to this: 
# How the component is presented (i.e. which particular interfaces are used: the names of ports used, the name of the configuration file, the path to the configuration file, the name of the component, and the name of the robot) and 
# The component parameters that govern its behaviour (e.g. thresholds, set-points, and data files)
We refer to these collectively as resources.  Typically, the configuration file name, the configuration file path (called the context), the component name, and the robot name are specified as command-line parameters, while all the remaining resources, including the names of the ports, are typically specified in the configuration file.  


Note that ''all'' resources are handled the same way using the ''ResourceFinder'' which not only greatly simplifies the process of finding the resources but also simplifies the process of parsing them.


It's worth noting that parameters that are specified in the configuration file can also be specified in the command-line if you wish.  The reverse is also true, with some restrictions (e.g. it only makes sense to specify the configuration file and the configuration file path on the command-line).  Finally, modules should be written so that default values are provided for all resources so that the module can be launched without any parameters. Again, the ResourceFinder makes it easy to arrange this.


Right now, what's important to grasp is that all these configuration issues are implemented by 


* '''Instantiating your component as a derived sub-class of <code>RFModule</code> in the <code>main()</code> function (e.g. in <code>protoComponentMain.cpp</code>),

* '''Preparing the ''ResourceFinder'' in the <code>main()</code> function by setting the default configuration file and its path,''' 

* '''Overriding the <code>yarp::os::RFModule::configure()</code> method (e.g. in <code>protoComponentConfiguration.cpp</code>) to parse all the parameters from the command-line and the configuration file.'''

* '''Launching your component by calling the <code>yarp::os::RFModule::runModule()</code> method from <code>main()</code>,


The following sections explain the implementation details of each aspect of this set-up and configuration.  


=== Instantiating a Derived Sub-Class of <code>RFModule</code>, Configuring the Resource Finder, and Running the Module ===

The  <code>main()</code> function in the  <code>protoComponentMain.cpp</code> file is responsible for instantiating a module derived from the <code>RFModule</code> class, setting the default configuration file and path for the resource finder, and running the module.  This allows the component to be configured using the resource finder (something that is actually accomplished by the code in <code>protoComponentConfiguration.cpp</code>).  

 /* protoComponentMain.cpp Application file for the example DREAM component */
 
 int main(int argc, char * argv[])
 {
   /* initialize yarp network */ 
   
   Network yarp;
  
   /* create your module */
  
   ProtoComponent protoComponent; 
  
   /* prepare and configure the resource finder */
  
   ResourceFinder rf;
   rf.setVerbose(true);
   rf.setDefaultConfigFile("protoComponent.ini");          // can be overridden by --from parameter
   rf.setDefaultContext("protoComponent/configuration");   // can be overridden by --context parameter
   rf.configure("DREAM_ROOT", argc, argv);                 // environment variable with root of configuration path
   
   /* run the module: runModule() calls configure first and, if successful, it then runs */
  
   protoComponent.runModule(rf);
  
   return 0;
 }

There are a few important points to notice in the code above.   


* Initialization of the configuration file in the resource finder object

* Initialization of the path to the configuration file in the resource finder object

* Initialization of the environmental variable that defines the root of the configuration path in the resource finder object

* The <code>runModule</code> method is called  to launch the module and do the configuration using the resource finder object passed as an argument


The first two require some additional explanation which we provide next.  


==== Configuration File ====

Configuration can be changed by changing configuration files. The configuration file which the component reads can be specified as a command line option.

 --from protoComponent.ini

The component should set a default configuration file using <code>yarp::os::ResourceFinder::setDefaultConfigFile("protoComponent.ini")</code>. This should be done in the <code>main()</code> function before running the module.


The value set by this method is overridden by the <code>--from</code> parameter (specified either during the command-line invocation or in the component configuration file; the command-line has priority over the configuration file if both are specified). 


The .ini file should usually be placed in the <code>$DREAM_ROOT/release/components/protoComponent/config</code> sub-directory.


==== Context ====

The relative path from <code>$DREAM_ROOT/release</code>  to the directory containing the configuration file is specified from the command line by  

 --context  components/protoComponent/config

The module should set a default context using  <code>yarp::os::ResourceFinder::setDefaultContext("components/protoComponent/config")</code>.  
This should be done in the <code>main()</code> function  in <code>protoComponentMain.cpp</code> before launching the component.


This is overridden by the <code>--context</code> parameter (again, specified either during the command-line invocation or in the component configuration file; the command-line has priority over the configuration file if both are specified).


=== Configuration: Overriding the <code>yarp::os::RFModule::configure()</code> method  ===

The method that overrides <code>yarp::os::RFModule::configure()</code> is defined in <code>protoComponentConfiguration.cpp</code>.  It uses the resource finder to parse all the parameters from the command-line and the configuration file and assign values appropriately.


The key thing to keep in mind here is that it must be possible to  ''externally'' reconfigure how the component interfaces with other components without having to modify any source code.   This is why so much information is required when starting up the component and why the resource finder is so useful and important.


==== Module Name and Port Names ====

You should ensure that it is possible to specify the names of any ports created by a module via configuration.  There are two aspects to this: the stem of the port name and the port name itself.  


A command-line option of 

 --name altName

sets the name of the module and will cause the module to use "/altName" as a stem for all port names provided the port names are generated using the <code>yarp::os::RFModule::getName()</code> method.  Note that he leading "/" prefix has to be added explicitly to the module name to create the port name.


The module should set a default name (and, hence, a default stem) using  <code>yarp::os::RFModule::setName("protoComponent")</code>. 


This is overridden by the <code>--name</code> parameter but you must check for this parameter and call <code>setName()</code> accordingly, e.g.

 string moduleName;
  
 moduleName = rf.check("name", 
              Value("protoComponent"), 
              "module name (string)").asString();    
 
 setName(moduleName.c_str());  // do this before processing any port name parameters

The port names should be specified as parameters, typically as key-value pairs in the <code>.ini</code> configuration file, e.g. 

 imageInputPort    /image:i
 imageOutputPort   /image:o

These key-value pairs can also be specified as command-line parameters, viz: 
<code>--imageInputPort /image:i  --imageOutputPort /image:o</code>


The component should set a default port name using  the ResourceFinder, e.g using <code>yarp::os::ResourceFinder::check();</code>

For example

 string inputPortName  = "/";
        inputPortName += getName(
                         rf.check("imageInputPort",
                         Value("/image:i"),
                         "Input image port (string)").asString()
                         );

will assign to <code>inputPortName</code> the value <code>/altName/image:i</code> if <code>--name altName</code> is specified as a parameter.  Otherwise, it would assign <code>/protoComponent/image:i</code>  On the other hand, it would assign <code>/protoComponent/altImage:i</code> if the key-value pair <code>myInputPort /altImage:i</code> was specified (either in the <code>.ini</code> file or as a command-line parameter) but not the <code>--name altName</code>


When providing the names of ports as parameter values (whether as a default value in <code>ResourceFinder::check</code>, as a value in the key-value list in the <code>.ini</code> configuration file, or as a command line argument), you always include the leading <code>/</code>.


All this code goes in the <code>configure()</code> method in <code>protoComponentConfiguration.cpp</code>.


==== Which Parameters Are Parsed Automatically? ====

Parsing the <code>--from</code> and <code>--context</code> parameters is handled automatically by the <code>RFModule</code> but <code>--name</code> and <code>--robot</code> must be handled explicitly.


As noted above, you would handle the <code>--name</code> parameter by using <code>ResourcFinder::check()</code> to parse it and get the parameter value, then user <code>setName()</code> to set it.  You should do this before proceeding to process any port name parameters, otherwise the wrong stem will be used when constructing the port names from the parameter values.


==== Configuration File Parameters ====

The configuration file, typically named <code>protoComponent.ini</code> and located in the <code>$DREAM_ROOT/release/components/protoComponent/config</code> directory, contains a key-value list: a list of pairs of keywords (configuration parameter names) and values (configuration parameter values), e.g.

 imageInputPort   /altImage:i
 imageOutputPort  /altImage:o
 threshold 9
 ...

These parameters are parsed using the [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1ResourceFinder.html <code>ResourceFinder</code>] within an <code>RFModule</code> object (i.e. by methods inherited by your module such as
[http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1Searchable.html <code>yarp::os::Searchable::check()</code>]).


Typically, key-value pairs specify the parameters and their values that govern the behaviour of the module, as well as the names of the module ports, should you wish to rename them.


==== Other Configuration Files ====

Apart from processing the parameters in the configuration file <code>protoComponent.ini</code>, it's often necessary to access configuration
data in other files. For example, you might want to read the intrinsic camera parameters from a camera calibration file.
Let's assume this configuration file is called <code>cameras.ini</code> and we wish to extract the principal points of the left and right cameras.  The coordinates of the principle points, and other intrinsic camera parameters, are stored as a sequence of key-value pairs:

 cx 157.858
 cy 113.51 

Matters are somewhat complicated by the fact that we need to read two sets of coordinates, one for the left camera and one for the right.  ''Both'' sets have the same key associated with them so the left and right camera parameters, including the principal point coordinates, are typically listed under different ''group'' headings, viz.

 [CAMERA_CALIBRATION_RIGHT]
 ...
 cx 157.858
 cy 113.51
 ...
  
 [CAMERA_CALIBRATION_LEFT]
 ...
 cx 174.222
 cy 141.757
 ...

So, to read these two pairs of coordinates, we need to 

* find the name of the file (e.g. <code>cameras.ini</code>)
* locate the file (i.e. get its full path)
* open the file and read its content
* find the <code>CAMERA_CALIBRATION_RIGHT</code> and <code>CAMERA_CALIBRATION_LEFT</code> groups
* read the respective <code>cx</code> and <code>cy</code> key values.


All of this is accomplished straightforwardly with the [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1ResourceFinder.html  <code>ResourceFinder</code>] and [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1Property.html <code>Property</code>] classes.


The first step is to get the name of the configuration file.  This will typically be one of the key-value pairs in the module 
configuration file <code>protoComponent.ini</code>, e.g. 

 cameraConfig cameras.ini

so that it can be read in exactly the same way as the other parameters in the previous section, e.g. using [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1Searchable.html#a109f36a33b39972b0797110304380003 <code>yarp::os::Searchable::check()</code>].


The full path can then be determined by the [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1ResourceFinder.html#a73f64f1a452732ef8beb60984af0a99b <code>yarp::os::ResourceFinder::findFile()</code>] method.


The contents of this file can then be read into a [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1Property.html <code>Property</code>] object using the [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1Property.html#a8048b872a66d398d1baed6aed1f301b2 <code>yarp:os:Property::fromConfigFile()</code>] method.


Locating the required group (e.g. <code>CAMERA_CALIBRATION_LEFT</code>) is accomplished with the [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1Property.html#aa819ea2ae0d680a2e2bf899c22900e5b <code>yarp: os:Property::findGroup()</code>] method.    


This method returns a [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1Bottle.html <code>Bottle</code>] with the full key-value list under this group.  This list can then be searched for the required key and value using the [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1Searchable.html#a109f36a33b39972b0797110304380003 <code>yarp::os::Searchable::check()</code>] method, as before.


Please refer to the [[The protoComponent Example | <code>protoComponent</code> source code]] for further details.


=== An Example of how to Configure the Component ===

The following simple module shows how to handle the foregoing configuration issues.

 /** @file protoComponent.h  Interface file for the example DREAM component */
 
 #include <iostream>
 #include <string>
 
 #include <yarp/sig/all.h>
 #include <yarp/os/all.h>
 #include <yarp/os/RFModule.h>
 #include <yarp/os/Network.h>
 #include <yarp/os/Thread.h>
  
 using namespace std;
 using namespace yarp::os; 
 using namespace yarp::sig;
   
 class ProtoComponentThread : public Thread {
 
 private:
 
    /* class variables */
 
     bool               debug;
    int                x, y;
    PixelRgb           rgbPixel;
    ImageOf<PixelRgb> *image;
    int               *thresholdValue;   
    VectorOf<int>     *thresholdVector;
    int               numberOfForegroundPixels;
 
    /* thread parameters: they are pointers so that they refer to the original variables in protoComponent */
 
    BufferedPort<ImageOf<PixelRgb> > *imagePortIn;
    BufferedPort<VectorOf<int> >     *thresholdPortIn; 
    BufferedPort<ImageOf<PixelRgb> > *imagePortOut; 
    BufferedPort<Bottle>             *statisticsPortOut; 
 
   public:
  
     /* class methods */
  
     ProtoComponentThread(BufferedPort<ImageOf<PixelRgb> > *imageIn, 
                          BufferedPort<VectorOf<int> >     *thresholdIn, 
                          BufferedPort<ImageOf<PixelRgb> > *imageOut,
                          BufferedPort<Bottle>             *statisticsOut, 
                          int *threshold );
     bool threadInit();     
     void threadRelease();
     void run(); 
 };
 
 
 class ProtoComponent:public RFModule {
 
    /* module parameters */
 
    string moduleName;
    string imageInputPortName;
    string thresholdInputPortName;
    string imageOutputPortName;
    string statisticsOutputPortName;  
    string handlerPortName;
    string cameraConfigFilename;
    float  fxLeft,  fyLeft;          // focal length
    float  fxRight, fyRight;         // focal length
    float  cxLeft,  cyLeft;          // coordinates of the principal point
    float  cxRight, cyRight;         // coordinates of the principal point
    int    thresholdValue;
 
    /* class variables */
 
    BufferedPort<ImageOf<PixelRgb> > imageIn;       // example image input port
    BufferedPort<VectorOf<int> >     thresholdIn;   // example vector input port 
    BufferedPort<ImageOf<PixelRgb> > imageOut;      // example image output port
    BufferedPort<Bottle>             statisticsOut; // example bottle output port
    Port handlerPort;                               // a port to handle interactive messages (also uses bottles)
 
    /* pointer to a new thread to be created and started in configure() and stopped in close() */
 
    ProtoComponentThread *protoComponentThread;
 
 public:
   
    bool configure(yarp::os::ResourceFinder &rf); // configure all the module parameters and return true if successful
    bool interruptModule();                       // interrupt, e.g., the ports 
    bool close();                                 // close and shut down the module
    bool respond(const Bottle& command, Bottle& reply);
    double getPeriod(); 
    bool updateModule();
 }; 

 /* protoComponentConfiguration.cpp  Implementation file for the example DREAM component */
  
 /* 
  * Configure method ... use it to do component coordination, 
  * i.e. to configure your component at runtime
  */
 
 bool ProtoComponent::configure(yarp::os::ResourceFinder &rf)
 {    
    /* Process all parameters from both command-line and .ini file */
 
    /* get the module name which will form the stem of all module port names */
 
    moduleName            = rf.check("name", 
                            Value("protoComponent"), 
                            "module name (string)").asString();
 
    /*
     * before continuing, set the module name before getting any other parameters, 
     * specifically the port names which are dependent on the module name
     */
   
    setName(moduleName.c_str());
 
    /* now, get the rest of the parameters */
 
    /* get the name of the input and output ports, automatically prefixing the module name by using getName() */
 
    imageInputPortName    =      "/";
    imageInputPortName   +=      getName(
                                 rf.check("imageInputPort", 
                                 Value("/image:i"),
                                 "Input image port (string)").asString()
                                 );
    
    thresholdInputPortName =     "/";
    thresholdInputPortName +=    getName(
                                 rf.check("thresholdInputPort", 
                                 Value("/threshold:i"),
                                 "Threshold input port (string)").asString()
                                 );
 
    imageOutputPortName   =      "/";
    imageOutputPortName  +=      getName(
                                 rf.check("imageOutputPort", 
                                 Value("/image:o"),
                                 "Output image port (string)").asString()
                                 );
 
    statisticsOutputPortName   = "/";
    statisticsOutputPortName  += getName(
                                 rf.check("statisticsOutputPort", 
                                 Value("/statistics:o"),
                                 "Output image port (string)").asString()
                                 );
 
 
    /* get the threshold value */
 
    thresholdValue        = rf.check("threshold",
                            Value(8),
                            "Key value (int)").asInt();
 
    
    /* 
     * get the cameraConfig file and read the required parameter values cx, cy 
     * in both the groups [CAMERA_CALIBRATION_LEFT] and [CAMERA_CALIBRATION_RIGHT]
     */
 
    cameraConfigFilename  = rf.check("cameraConfig", 
                            Value("cameras.ini"), 
                            "camera configuration filename (string)").asString();
 
    cameraConfigFilename = (rf.findFile(cameraConfigFilename.c_str())).c_str();
 
    Property cameraProperties;
 
    if (cameraProperties.fromConfigFile(cameraConfigFilename.c_str()) == false) {
       cout << "protoComponent: unable to read camera configuration file" << cameraConfigFilename << endl;
       return 0;
    }
    else {
       cxLeft  = (float) cameraProperties.findGroup("CAMERA_CALIBRATION_LEFT").check("cx", Value(160.0), "cx left").asDouble();
       cyLeft  = (float) cameraProperties.findGroup("CAMERA_CALIBRATION_LEFT").check("cy", Value(120.0), "cy left").asDouble();
       cxRight = (float) cameraProperties.findGroup("CAMERA_CALIBRATION_RIGHT").check("cx", Value(160.0), "cx right").asDouble();
       cyRight = (float) cameraProperties.findGroup("CAMERA_CALIBRATION_RIGHT").check("cy", Value(120.0), "cy right").asDouble();
    }
 
 
    /* do all initialization here */
      
    /* open ports  */ 
        
    if (!imageIn.open(imageInputPortName.c_str())) {
       cout << getName() << ": unable to open port " << imageInputPortName << endl;
       return false;  // unable to open; let RFModule know so that it won't run
    }
 
    if (!thresholdIn.open(thresholdInputPortName.c_str())) {
       cout << getName() << ": unable to open port " << thresholdInputPortName << endl;
       return false;  // unable to open; let RFModule know so that it won't run
    }
 
 
    if (!imageOut.open(imageOutputPortName.c_str())) {
       cout << getName() << ": unable to open port " << imageOutputPortName << endl;
       return false;  // unable to open; let RFModule know so that it won't run
    }
 
    if (!statisticsOut.open(statisticsOutputPortName.c_str())) {
       cout << getName() << ": unable to open port " << statisticsOutputPortName << endl;
       return false;  // unable to open; let RFModule know so that it won't run
    }
 
 
    /*
     * attach a port of the same name as the module (prefixed with a /) to the module
     * so that messages received from the port are redirected to the respond method
     */
 
    handlerPortName =  "/";
    handlerPortName += getName();         // use getName() rather than a literal 
  
    if (!handlerPort.open(handlerPortName.c_str())) {           
       cout << getName() << ": Unable to open port " << handlerPortName << endl;  
       return false;
    }
 
    attach(handlerPort);                  // attach to port
  
    /* create the thread and pass pointers to the module parameters */
 
    protoComponentThread = new ProtoComponentThread(&imageIn, &thresholdIn, &imageOut, &statisticsOut, &thresholdValue);
 
    /* now start the thread to do the work */
 
    protoComponentThread->start(); // this calls threadInit() and it if returns true, it then calls run()
  
    return true ;      // let the RFModule know everything went well
                       // so that it will then run the module
 }

 /* protoComponentMain.cpp Application file for the example DREAM component */
  
 #include "protoComponent.h" 
  
 int main(int argc, char * argv[])
 {
   /* initialize yarp network */ 
   
   Network yarp;
  
   /* create your module */
  
   ProtoComponent protoComponent; 
  
   /* prepare and configure the resource finder */
  
   ResourceFinder rf;
   rf.setVerbose(true);
   rf.setDefaultConfigFile("protoComponent.ini");          // can be overridden by --from parameter
   rf.setDefaultContext("protoComponent/configuration");   // can be overridden by --context parameter
   rf.configure("DREAM_ROOT", argc, argv);                 // environment variable with root of configuration path
   
   /* run the module: runModule() calls configure first and, if successful, it then runs */
  
   protoComponent.runModule(rf);
  
   return 0;
 }


=== Doing Some Work: Instantiating and starting the <code>protoComponentThread</code> ===

Once the configuration is done (in <code>protoComponentConfiguration.cpp</code>), the derived module then instantiates a <code>Thread</code>  (or  <code>RateThread</code>) object and launches it (again, this is done in <code>protoComponentConfiguration.cpp</code>), passing to it as arguments all the relevant resources, e.g. port names and parameter values, located by the resource finder.


In the example above, this we done as follows.

    /* create the thread and pass pointers to the module parameters */
 
    protoComponentThread = new ProtoComponentThread(&imageIn, &thresholdIn, &imageOut, &statisticsOut, &thresholdValue);
 
    /* now start the thread to do the work */
 
    protoComponentThread->start(); // this calls threadInit() and it if returns true, it then calls run()

=== Graceful Shut-down ===

To achieve clean shutdown, two <code>RFModule</code> methods, <code>yarp::os::RFModule::interruptModule()</code> and <code>yarp::os::RFModule::close()</code>, should be overridden. 


The <code>interruptModule()</code> method will be called when it is desired that <code>updateModule()</code> finish up. When it has indeed finished, <code>close()</code> will be called. 


The <code>interruptModule()</code> method should first call the <code>stop()</code> method for the thread (e.g.  <code>protoComponentThread->stop();<code>) and then call the <code>interrupt</code> method for each of the ports that it opened in the <code>configure()</code> method. For example:
    
 bool ProtoComponent::interruptModule()
 {
    protoComponentThread->stop();
 
    imageIn.interrupt();
    thresholdIn.interrupt();
    imageOut.interrupt();
    handlerPort.interrupt();
 
    return true;
 }
 
 bool ProtoComponent::close()
 { 
    imageIn.close();
    thresholdIn.close();
    imageOut.close();
    handlerPort.close();
 
    return true;
 } 

The order in which you do this is very important: first <code>stop()</code> the thread, then <code>interrupt()</code> the ports, then <code>close()</code> the ports. Getting this out of sequence causes problems when shutting down a component and it will often hang, requiring you to kill the process.
 

For <code>yarp::os::RFModule</code>, the method <code>yarp::os::RFModule::updateModule()</code> will be called from the main control thread until it returns false. After that a clean shutdown will be initiated. The period with which it is called is determined by the method <code>yarp::os::RFModule::getPeriod()</code>. Neither method need necessarily be overridden.  The default methods provide the required functionality.  

 /* Called periodically every getPeriod() seconds */
 
 bool ProtoComponent::updateModule()
 {
    return true;
 }
 
 double ProtoComponent::getPeriod()
 {
    /* module periodicity (seconds), called implicitly by protoComponent */
     
    return 0.1;
 }

Note that the <code>updateModule()</code> method is not meant to run code that that implements the algorithm encapsulated in the module.   Instead <code>updateModule()</code> is meant to be used as a periodic mechanism to check in on the operation of the thread that implements  the module (e.g. gather interim statistics, change parameter settings, etc.).   The <code>updateModule()</code> is called periodically by the RFModule object, with the period being determined by the <code>getPeriod()</code> method.  Both <code>updateModule()</code> and <code>getPeriod()</code> can be overridden in your implementation of <code>myModule</code>.

== Component  Computation and Communication: the <code>Thread</code> and  <code>RateThread</code> Classes  ==

Here we finally explain how to get the component to do some work: the functionality associated with computation and communication. This is defined in the  <code>protoComponentComputation.cpp</code> file.   This functionality revolves around the  <code>Thread</code>  and  <code>RateThread</code> classes: how to access the parameters passed to it from the derived <code>RFModule</code> object, how to perform some useful work.


=== Using Threads to Implement Your Algorithm ===

For the module to actually do anything, it should start or stop threads using the YARP [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1Thread.html  Thread] and [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1RateThread.html RateThread] classes. Typically, these threads are started and stopped in the <code>configure</code> and <code>close</code> methods of the RFModule class. If you are writing a control loop or an algorithm that requires precise scheduling your should use the [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1RateThread.html RateThread] class.


Just as the starting point in writing a component for the DREAM repository is to develop a sub-class of the [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1RFModule.html  yarp::os::RFModule] class, '''the starting point for implementing the algorithm within that component is to develop a sub-class of either [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1Thread.html Thread] or [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1RateThread.html RateThread]'''. 


In the following, we will explain how to do it with [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1Thread.html Thread]; it's straightforward to extend this to [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1RateThread.html RateThread]: effectively, you provide an argument with the <code>RateThread</code> instantiation specifying the period with which the thread should be spawned; the thread just runs once so that you don't have to check <code>isStopping()</code> to see if the thread should end as in the [http://wiki.icub.org/yarpdoc/classyarp_1_1os_1_1Thread.html Thread] example below.


'''Perhaps one of the best ways of thinking about this is to view it as a two levels of encapsulation, one with <code>RFModule</code>, and another with <code>Thread</code>; the former deals with the configuration of the module and the latter dealing with the execution of the algorithm.'''  The only tricky part is that somehow these two objects have to communicate with one another.  


You need to know three things (two of which  we can covered already):


# The thread is instantiated and started in the <code>configure()</code> method.  
# The thread is stopped in the <code>close()</code> method.   
# When the thread is instantiated, you pass the module parameters to it as a set of arguments (for the constructor).


Let's begin with the definition of a thread <code>ProtoComponent</code> (capital P because we are going to create a sub-class) and then turn our attention to how it is used by <code>protoComponent</code>.


=== An Example of how to use the <code>Thread</code> Class ===

First, we define a sub-class, or derived class, of the <code>yarp::os::Thread</code> class.  The algorithm's variables - ''and specifically the thread's parameters and ports'' - go in the private data members part and you need to override four methods:


# <code>ProtoComponentThread::ProtoComponentThread();           // the constructor</code>
# <code>bool threadInit();                                    // initialize variables and return true if successful</code>
# <code>void run();                                           // do the work</code>
# <code>void threadRelease();                                 // close and shut down the thread</code>


There are a number of important points to note.


First, the variables in the <code>ProtoComponentThread</code> class which represent the thread's parameters and port should be pointer types and the constructor parameters should initialize them.  In turn, the arguments of the <code>protoComponentThread</code> object instantiation in the <code>configure()</code> should be the addresses of (pointers to) the module parameters and ports in the <code>protoComponentThread</code> object.  In this way, the thread's parameter and port variables are just references to the original module parameters and ports that were initialized in the <code>configure</code> method of the <code>protoComponent</code> object.


Second, <code>threadInit()</code> returns <code>true</code> if the initialization was successful, otherwise it should return <code>false</code>.  This is significant because if it returns <code>false</code> the thread will not subsequently be run.


Third, '''the <code>run()</code> method is where the algorithm is implemented.''' Typically, it will run continuously until some stopping condition is met.  This stopping condition should include the return value of a call to the <code>yarp::os::Thread::isStopping()</code> method which flags whether or not the thread is to terminate.  In turn, the value of  <code>yarp::os::Thread::isStopping()</code> is determined by the  <code>yarp::os::Thread::stop()</code> method which, as we saw already, is called in <code>protoComponent.close()</code>.


The following is an example declaration and definition of the <code>ProtoComponentThread</code> class taken from <code>protoComponent.h</code>

 /** @file protoComponent.h  Interface file for the example DREAM component */
  
 #include <yarp/os/Thread.h>
  
 using namespace std;
 using namespace yarp::os; 
 using namespace yarp::sig;
   
 class ProtoComponentThread : public Thread {
 
 private:
 
    /* class variables */
 
    bool               debug;
    int                x, y;
    PixelRgb           rgbPixel;
    ImageOf<PixelRgb> *image;
    int               *thresholdValue;   
    VectorOf<int>     *thresholdVector;
    int               numberOfForegroundPixels;
 
    /* thread parameters: they are pointers so that they refer to the original variables in protoComponent */
 
    BufferedPort<ImageOf<PixelRgb> > *imagePortIn;
    BufferedPort<VectorOf<int> >     *thresholdPortIn; 
    BufferedPort<ImageOf<PixelRgb> > *imagePortOut; 
    BufferedPort<Bottle>             *statisticsPortOut; 
   
 
   public:
  
     /* class methods */
  
     ProtoComponentThread(BufferedPort<ImageOf<PixelRgb> > *imageIn, 
                          BufferedPort<VectorOf<int> >     *thresholdIn, 
                          BufferedPort<ImageOf<PixelRgb> > *imageOut,
                          BufferedPort<Bottle>             *statisticsOut, 
                          int *threshold );
     bool threadInit();     
     void threadRelease();
     void run(); 
 };

 /* protoComponentComputation.cpp Implementation file for the computation and communication aspects of protoComponent */
 
 ProtoComponentThread::ProtoComponentThread(BufferedPort<ImageOf<PixelRgb> > *imageIn, 
                                            BufferedPort<VectorOf<int> >     *thresholdIn, 
                                            BufferedPort<ImageOf<PixelRgb> > *imageOut,
                                            BufferedPort<Bottle>             *statisticsOut, 
                                            int *threshold)
 {
    imagePortIn       = imageIn;
    thresholdPortIn   = thresholdIn;
    imagePortOut      = imageOut; 
    statisticsPortOut = statisticsOut;
    thresholdValue    = threshold;
 }
 
 bool ProtoComponentThread::threadInit() 
 {
    /* initialize variables and create data-structures if needed */
 
    debug = false;
 
    return true;
 } 
 
 void ProtoComponentThread::run(){
 
    /* 
     * do some work ....
     * for example, convert the input image to a binary image using the threshold provided 
     */ 
    
    unsigned char value;
    double start;
  
    start = yarp::os::Time::now(); // start time
 
    while (isStopping() != true) { // the thread continues to run until isStopping() returns true
   
       if (debug)
          cout << "protoComponentThread: threshold value is " << *thresholdValue << endl;
       
       /* read image ... block until image is received */
 
       do {
          image = imagePortIn->read(true);
       } while ((image == NULL) && (isStopping() != true));  // exit loop if shutting down;
       
       if (isStopping()) break; // abort this loop to avoid make sure we don't continue and possibly use NULL images 
 
 
       /* read threshold ... block if threshold is not received */
       /*
       do {
          thresholdVector = thresholdPortIn->read(false);
       } while ((thresholdVector == NULL) && (isStopping() != true));  // exit loop if shutting down;
       */
   
       /* read threshold ... do not block if threshold is not received */
 
       thresholdVector = thresholdPortIn->read(false);
     
       if (thresholdVector != NULL) {
             *thresholdValue = (int) (*thresholdVector)[0];
       }
 
 
       if (debug)
          cout << "protoComponentThread: threshold value is " << *thresholdValue << endl;
       
 
       /* write out the binary image */
 
       ImageOf<PixelRgb> &binary_image = imagePortOut->prepare();
       binary_image.resize(image->width(),image->height());
 
       numberOfForegroundPixels = 0;
 
       for (x=0; x<image->width(); x++) {
          for (y=0; y<image->height(); y++) {
 
              rgbPixel = image->safePixel(x,y);
 
              if (((rgbPixel.r + rgbPixel.g + rgbPixel.b)/3) > *thresholdValue) {
                 value = (unsigned char) 255;
                 numberOfForegroundPixels++;
              }
              else {
                 value = (unsigned char) 0;
              }
 
              rgbPixel.r = value;
              rgbPixel.g = value;
              rgbPixel.b = value;
 
              binary_image(x,y) = rgbPixel;
           }
        }
        
        imagePortOut->write();
 
        /* write out the image statistics */
 
        Bottle &statisticsMessage = statisticsPortOut->prepare();
 
        statisticsMessage.clear();
 
        statisticsMessage.addInt((int)(yarp::os::Time::now()-start));
        statisticsMessage.addString("seconds elapsed");
        statisticsMessage.addString(" - foreground pixel count is");
        statisticsMessage.addInt(numberOfForegroundPixels);
        statisticsPortOut->write();
    }
 }
 
 void ProtoComponentThread::threadRelease() 
 {
    /* for example, delete dynamically created data-structures */
 }

== Run-time Interaction ==

=== The <code>respond()</code> Method ===

Often, it is very useful for a user or another module to send commands to control the behaviour of the module, e.g. interactively changing parameter values. 


We accomplish this functionality for the <code>yarp::os::RFModule</code> by overridding the <code>yarp::os::RFModule::respond()</code> method which can then be configured to receive messages from either a port (typically named <code>/protoComponent</code>) or the terminal. This is effected by the <code>yarp::os::RFModule::attach(port)</code> and <code>yarp::os::RFModule::attachTerminal()</code> methods, respectively. Attaching both the port and the terminal means that commands from both sources are then handled in the same way.

=== An Example of how to change module parameters at run-time===

In the following example, we handle three commands:

* help
* quit
* set 
** set thr <n>   ... set the threshold
:(where <n> is an integer number)


Apart from the way that the commands are parsed and the form of the reply, the key thing to note here is the fact that the value of <code>MyModule::thresholdValue</code> is updated. Since <code>myThread</code> references this variable, it too is updated and the updated value is used in the thread. 

 bool MyModule::respond(const Bottle& command, Bottle& reply) 
 {
   string helpMessage =  string(getName().c_str()) + 
                         " commands are: \n" +  
                         "quit \n" + 
                         "set thr <n> ... set the threshold \n" + 
                         "(where <n> is an integer number) \n";
 
   reply.clear(); 
 
   if (command.get(0).asString()=="quit") {
        reply.addString("quitting");
        return false;     
    }
    else if (command.get(0).asString()=="help") {
       cout << helpMessage;
       reply.addString("ok");
    }
    else if (command.get(0).asString()=="set") {
       if (command.get(1).asString()=="thr") {
          thresholdValue = command.get(2).asInt(); // set parameter value
          reply.addString("ok");
       }
    }
    return true;
 }

 
However, for any of this to work, we have to set up a port in the first place.  We put port declaration in the private data member part of <code>MyModule</code> class

 string handlerPortName;
 Port handlerPort;      //a port to handle messages 

and open it in the <code>configure()</code> method, viz.

 /*
  * attach a port of the same name as the module (prefixed with a /) to the module
  * so that messages received from the port are redirected to the respond method
  */
 
 handlerPortName =  "/";
 handlerPortName += getName();         // use getName() rather than a literal 
  
 if (!handlerPort.open(handlerPortName.c_str())) {           
    cout << getName() << ": Unable to open port " << handlerPortName << endl;  
    return false;
 }
 
 attach(handlerPort);                  // attach to port
  
 attachTerminal();                     // attach to terminal

Interrupt it in the <code>interrupt()</code> method, viz.

 handlerPort.interrupt();

Close it in the <code>close()</code> method, viz.

 handlerPort.close();


=== Remote Connection ===

Note that the <code>handlerport</code> can be used not only by other modules but also interactively by a user through the <code>yarp rpc</code> directive, viz.:

 yarp rpc /myModule

This opens a connection from a terminal to the port and allows the user to then type in commands and receive replies from the <code>respond()</code> method.


== Documentation and Coding Guidelines ==

DREAM code follows a set of mandatory and recommended software engineering standards as set out  in Deliverable D3.2.
The mandatory standards are contained in Appendices A, B, and C (File Organization, Internal Documentation, and Component Functionality, respectively), as well as Section 4 on Testing.
The recommended standards are contained in Appendices D  and E (Programming Style and Programming Practice, respectively).

* [[Mandatory Standards for File Organization]]
* [[Mandatory Standards for Internal Documentation]]
* [[Mandatory Standards for Component Functionality]]
* [[Mandatory Standards for Testing]]
* [[Recommended Standards for Programming Style]]
* [[Recommended Standards for Programming Practice]]

Please take the time to read through these documents.  '''All components to be included in the standard DREAM release version have to comply with the mandatory standards.'''

== Application Description ==

DREAM applications, i.e. collections of inter-connected YARP modules, are described in XML and launched using an automatically-generated GUI.  Refer to [[Managing Applications]] for more details on how to write these application descriptions.

An application description containing an example invocation of the <code>myModule</code> with some command-line parameters is shown below.


 <application>
 
 <name>Test myModule</name>
 
 <dependencies>
    <port>/robot/cam/left</port>
 </dependencies> 
 
 <module>
    <name>myModule</name>
    <parameters>--threshold 128</parameters>
    <node>dream1</node>
    <tag>myModule</tag>
 </module> 
 
 <module>
    <name>yarpview</name>
    <parameters>--name /rgbImage --x 000 --y 0 --synch</parameters>
    <node>dream1</node>
    <tag>left_image</tag>
 </module>   
 
 <module>
    <name>yarpview</name>
    <parameters>--name /binaryImage --x 350 --y 0 --synch</parameters>
    <node>dream1</node>
    <tag>right_image</tag>
 </module> 
 
 <connection>
   <from>/robot/cam/left</from>
   <to>/myModule/image:i</to>
   <protocol>tcp</protocol>
 </connection>
 
 <connection>
   <from>/robot/cam/left</from>
   <to>/rgbImage</to>
   <protocol>tcp</protocol>
 </connection> 
 
 <connection>
   <from>/myModule/image:o</from>
   <to>/binaryImage</to>
   <protocol>tcp</protocol>
 </connection> 
 
 </application>
 

To run the application, follow the instruction in the [[Software Users Guide]].


== Resources ==

* [http://wiki.icub.org/yarp/specs/dox/user/html/index.html YARP home page]

* [http://wiki.icub.org/yarpdoc/yarp_resource_finder_tutorials.html Tutorial on the YARP Resource Finder Class]

* [http://wiki.icub.org/iCub/dox/html/module_standards.html Module Standards]

* [[Resource finder overview]]

* [http://wiki.icub.org/iCub/dox/html/icub_resource_finder_basic.html How to organize the command line parameters of your modules]

* [http://wiki.icub.org/iCub/dox/html/icub_resource_finder_advanced.html Organizing Parameters: Advanced Tutorial]

* [http://wiki.icub.org/iCub/dox/html/icub_tutorial_module.html Using the module helper class to write a program]

* [http://wiki.icub.org/yarpdoc/d9/d26/classyarp_1_1os_1_1RFModule.html RFModule Class Reference]

* [http://wiki.icub.org/yarpdoc/d1/d03/classyarp_1_1os_1_1Module.html Module Class Reference]

* [http://wiki.icub.org/iCub/dox/html/coding_standards.html Coding and Documentation Standards]

* [http://wiki.icub.org/iCub/dox/html/group__icub__exampleModule.html exampleModule]

* [[Cluster management]]

* [http://wiki.icub.org/iCub/dox/html/group__icub__exampleApplication.html exampleApplication]