Software Development Guide

1 Overview
2 Component Configuration and Coordination: The RFModule Class
3 Component Computation and Communication: the Thread and RateThread Classes
- 3.1 Using Threads to Implement Your Algorithm
- 3.2 An Example of how to use the Thread Class
4 Run-time Interaction
5 Documentation and Coding Guidelines
6 Application Description
7 Resources

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, protoComponent, 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, protoComponentGUI, 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 protoComponent. It receives some statistics from protoComponent, specifically the number of foreground pixels and the current time, and writes them to a text display. It also receives the binary image from protoComponent and displays it along with the original colour image that it receives from the source that also feeds protoComponent.

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. protoComponent.h, 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:

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

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

Therefore, the four protoComponent files are:

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

and the four protoComponentGUI 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:

Guide Structure

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

Component Configuration and Coordination: the `RFModule` Class

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

This section also deals with the main() function, i.e. with the protoComponentApplication.cpp file. It shows how to instantiate a module derived from the RFModule 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 Thread or a RateThread 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 `Thread` and `RateThread` Classes

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

GUI Component Computation and Communication: the `FLTK` and `guiUtilities` Libraries

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

Instead, this section addresses the functionality associated with computation and communication, i.e. with the protoComponentGUIComputation.cpp and protoComponent.h files. Again, the functionality revolves around the Thread and RateThread 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 protoComponent by connecting it to other components that provide input images and display the output images. This application uses yarpview modules to view the images. The threshold is modified online by sending commands to protoComponent from the command line in a terminal window.

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

Component Configuration and Coordination: The `RFModule` Class

The starting point in writing any DREAM component is to develop a sub-class of the yarp::os::RFModule class.

First, we define a sub-class, or derived class, of the yarp::os::RFModule 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:

bool configure();
bool interruptModule();
bool close();

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

bool respond();
double getPeriod();
bool updateModule();

In the following, we assume we are writing a module named protoComponent. This module will be implemented as a sub-class yarp::os::RFModule called ProtoComponent (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 Thread class. The definition of this sub-class is also included in the interface header file, e.g. protoComponent.h but the implementation is effected in a separate source file, e.g. protoComponentComputation.cpp.

Perhaps the trickiest part of writing the software to implement a component is understanding the way that the RFModule and Thread 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 RFModule 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 RFModule in the main() function (e.g. in protoComponentMain.cpp),

Preparing the ResourceFinder in the main() function by setting the default configuration file and its path,

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

Launching your component by calling the yarp::os::RFModule::runModule() method from main(),

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

Instantiating a Derived Sub-Class of `RFModule`, Configuring the Resource Finder, and Running the Module

The main() function in the protoComponentMain.cpp file is responsible for instantiating a module derived from the RFModule 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 protoComponentConfiguration.cpp).

/* 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 runModule 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 yarp::os::ResourceFinder::setDefaultConfigFile("protoComponent.ini"). This should be done in the main() function before running the module.

The value set by this method is overridden by the --from 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 $DREAM_ROOT/release/components/protoComponent/config sub-directory.

Context

The relative path from $DREAM_ROOT/release 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 yarp::os::ResourceFinder::setDefaultContext("components/protoComponent/config"). This should be done in the main() function in protoComponentMain.cpp before launching the component.

This is overridden by the --context 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 `yarp::os::RFModule::configure()` method

The method that overrides yarp::os::RFModule::configure() is defined in protoComponentConfiguration.cpp. 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 yarp::os::RFModule::getName() 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 yarp::os::RFModule::setName("protoComponent").

This is overridden by the --name parameter but you must check for this parameter and call setName() 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 .ini configuration file, e.g.

imageInputPort    /image:i
imageOutputPort   /image:o

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

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

For example

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

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

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

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

Which Parameters Are Parsed Automatically?

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

As noted above, you would handle the --name parameter by using ResourcFinder::check() to parse it and get the parameter value, then user setName() 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 protoComponent.ini and located in the $DREAM_ROOT/release/components/protoComponent/config 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 ResourceFinder within an RFModule object (i.e. by methods inherited by your module such as yarp::os::Searchable::check()).

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 protoComponent.ini, 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 cameras.ini 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. cameras.ini)
locate the file (i.e. get its full path)
open the file and read its content
find the CAMERA_CALIBRATION_RIGHT and CAMERA_CALIBRATION_LEFT groups
read the respective cx and cy key values.

All of this is accomplished straightforwardly with the ResourceFinder and Property 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 protoComponent.ini, 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 yarp::os::Searchable::check().

The full path can then be determined by the yarp::os::ResourceFinder::findFile() method.

The contents of this file can then be read into a Property object using the yarp:os:Property::fromConfigFile() method.

Locating the required group (e.g. CAMERA_CALIBRATION_LEFT) is accomplished with the yarp: os:Property::findGroup() method.

This method returns a Bottle with the full key-value list under this group. This list can then be searched for the required key and value using the yarp::os::Searchable::check() method, as before.

Please refer to the protoComponent 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 `protoComponentThread`

Once the configuration is done (in protoComponentConfiguration.cpp), the derived module then instantiates a Thread (or RateThread) object and launches it (again, this is done in protoComponentConfiguration.cpp), 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 RFModule methods, yarp::os::RFModule::interruptModule() and yarp::os::RFModule::close(), should be overridden.

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

The interruptModule() method should first call the stop() method for the thread (e.g. protoComponentThread->stop();) and then call the interrupt method for each of the ports that it opened in the configure() 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 stop() the thread, then interrupt() the ports, then close() 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 yarp::os::RFModule, the method yarp::os::RFModule::updateModule() 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 yarp::os::RFModule::getPeriod(). 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 updateModule() method is not meant to run code that that implements the algorithm encapsulated in the module. Instead updateModule() 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 updateModule() is called periodically by the RFModule object, with the period being determined by the getPeriod() method. Both updateModule() and getPeriod() can be overridden in your implementation of myModule.

Component Computation and Communication: the `Thread` and `RateThread` 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 protoComponentComputation.cpp file. This functionality revolves around the Thread and RateThread classes: how to access the parameters passed to it from the derived RFModule 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 Thread and RateThread classes. Typically, these threads are started and stopped in the configure and close methods of the RFModule class. If you are writing a control loop or an algorithm that requires precise scheduling your should use the RateThread class.

Just as the starting point in writing a component for the DREAM repository is to develop a sub-class of the yarp::os::RFModule class, the starting point for implementing the algorithm within that component is to develop a sub-class of either Thread or RateThread.

In the following, we will explain how to do it with Thread; it's straightforward to extend this to RateThread: effectively, you provide an argument with the RateThread instantiation specifying the period with which the thread should be spawned; the thread just runs once so that you don't have to check isStopping() to see if the thread should end as in the 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 RFModule, and another with Thread; 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 configure() method.
The thread is stopped in the close() 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 ProtoComponent (capital P because we are going to create a sub-class) and then turn our attention to how it is used by protoComponent.

An Example of how to use the `Thread` Class

First, we define a sub-class, or derived class, of the yarp::os::Thread 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:

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

There are a number of important points to note.

First, the variables in the ProtoComponentThread 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 protoComponentThread object instantiation in the configure() should be the addresses of (pointers to) the module parameters and ports in the protoComponentThread 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 configure method of the protoComponent object.

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

Third, the run() 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 yarp::os::Thread::isStopping() method which flags whether or not the thread is to terminate. In turn, the value of yarp::os::Thread::isStopping() is determined by the yarp::os::Thread::stop() method which, as we saw already, is called in protoComponent.close().

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

/** @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 `respond()` 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 yarp::os::RFModule by overridding the yarp::os::RFModule::respond() method which can then be configured to receive messages from either a port (typically named /protoComponent) or the terminal. This is effected by the yarp::os::RFModule::attach(port) and yarp::os::RFModule::attachTerminal() 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 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 ProtoComponent::thresholdValue is updated. Since protoComponent references this variable, it too is updated and the updated value is used in the thread.

bool ProtoComponent::respond(const Bottle& command, Bottle& reply) 
{
  string helpMessage =  string(getName().c_str()) + 
                        " commands are: \n" +  
                        "help \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("command is: set thr <n>");
   }
   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 the port declaration in the private data member part of ProtoComponent class

   string handlerPortName;
   ...
   Port handlerPort;                               // a port to handle interactive messages (also uses bottles)

and open it in the configure() 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

Interrupt it in the interrupt() method, viz.

   handlerPort.interrupt();

Close it in the close() method, viz.

   handlerPort.close();

Remote Connection

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

yarp rpc /protoComponent

This opens a connection from a terminal to the port and allows the user to then type in commands and receive replies from the respond() 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).

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 myModule 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.