Recent changes to CustomSensorMotor

CustomSensorMotor modified by Tomassino Ferrauto

Tomassino Ferrauto — Fri, 20 Nov 2015 10:21:48 -0000

CustomSensorMotor modified by Tomassino Ferrauto

Tomassino Ferrauto — Tue, 17 Nov 2015 13:59:21 -0000

--- v23
+++ v24
@@ -8,93 +8,97 @@

 Creating Custom Sensors or Motors
 =======
-FARSA provide many ready to use sensors and motors for each supported robot type as well as additional sensors and motors that can be used with different type of robots. Some of these sensors also perform a pre-processing of the information that can be extracted from the physical sensors. These sensors and motors istantiated and used by simply listing the required sensors and motors in the configuration file. In some case, however, you might want to implement a new type of sensor or motor for your experiment, or you might want to implement a new version of an existing sensor that preprocesses the sensory information in a different way with respect to existing sensors. 
-
-Each sensor updates the state of a certain number of sensory units or sensory neurons. For example the infrared sensor of the ePuck operate by updating a block of 8 sensory units of the robot controller that encode the state of the 8 infrared sensors distributed around the circular body of the robot. Each motor update the state of one or more robot actuator on the basis of the state of one or more motor units or motor neurons of the robot controller. For example the EpuckWheelVelocityMotor updates the desired speed of the two motors controlling the two corresponding wheels on the basis of the state of two motor units or motor neurons of the robot controller. The interface between the sensors and motors and the robots' controllers is handled by the *NeuronsIterator* class. The sensory and motor units are divided in blocks that have the same name of the sensor that is uded to update them or of the motor that use them to set the state of the corresponding robot actuators. The *NeuronsIterator* class include the following functions:
-* *setCurrentBlock()* - Select the block to be read or written. 
-* *setInput()* - sets the value of the current element.
-* *getOutput()* - reads the value of the current element.
-* *setGraphicProperties* - sets the graphical properties of the element that are used by the graphic interface.
-* *nextNeuron* - sets the next unit of the current block.  
-
-Sensors and motors are components that are istantiated at runtime and that can be implemented within FARSA or within an experimental plugin that is compiled indendently from FARSA. Sensors and motors that are implemented in plugins should include the FARSA_PLUGIN_ and the FARSA_REGISTER_CLASS macro declaration (for more information see  [this page]([PluginsAndRegistration])).
-
-Sensors that can be used with different robots are declared as subclass of the general *Sensor* class. Sensors that can be used only with a specific robotic platform are declared instead as sub-class of more specific classes (named KheperaSensor, EpuckSensor, MarXbotSensor and iCubSensor).  Similarly, motors that can be used with differen robots are declared as subclass of the general "Motor" class, while other motors are declared as subclass of more specific motor classes (named KheperaMotor, EpuckMotor, MarXbotMotor, and iCubMotor). 
+
+FARSA provide many ready to use sensors and motors for each supported robot type as well as additional sensors and motors that can be used with different kinds of robots. Some sensors also perform a pre-processing of the information that is extracted from the physical sensors. These sensors and motors are istantiated and used by simply listing the required ones in the configuration file. In some cases, however, you might want to implement a new type of sensor or motor for your experiment, or you might want to implement a new version of an existing sensor that preprocesses the sensory information in a different way with respect to existing sensors.
+
+Each sensor updates the state of a certain number of sensory units or sensory neurons. For example the infrared sensor of the ePuck operates by updating a block of 8 sensory units of the robot controller that encode the state of the 8 infrared sensors distributed around the circular body of the robot. Each motor updates the state of one or more robot actuator on the basis of the state of one or more motor units or motor neurons of the robot controller. For example the *EpuckWheelVelocityMotor* updates the desired speed of the two motors controlling the two corresponding wheels on the basis of the state of two motor units or motor neurons of the robot controller. The interface between the sensors and motors and the robots' controllers is handled by the *NeuronsIterator* class. The sensory and motor units are divided in blocks that have the same name of the sensor that is used to update them or of the motor that use them to set the state of the corresponding robot actuators. The *NeuronsIterator* class include the following functions:
+
+* *setCurrentBlock()* - selects the block to be read or written;
+* *setInput()* - sets the value of the current element;
+* *getOutput()* - reads the value of the current element;
+* *setGraphicProperties()* - sets the graphical properties of the element that are used by the graphic interface;
+* *nextNeuron()* - sets the next unit of the current block;
+
+Sensors and motors are components that can be implemented within an experimental plugin that is compiled indendently from FARSA. Like all components implemented in a plugin, they should make use of the FARSA_PLUGIN_\* and the FARSA_REGISTER_CLASS macros (for more information see  [this page]([PluginsAndRegistration])).
+
+Sensors that can be used with different robots are declared as subclasses of the general *Sensor* class. Sensors that can be used only with a specific robotic platform are declared instead as subclasses of more specific classes (named *KheperaSensor*, *EpuckSensor*, *MarXbotSensor* and *iCubSensor*). Similarly, motors that can be used with differen robots are declared as subclasses of the general *Motor* class, while other motors are declared as subclasses of more specific motor classes (named *KheperaMotor*, *EpuckMotor*, *MarXbotMotor*, and *iCubMotor*).

 A Simple Sensor
 -------

-Below we illustrate the implementation of a simple sensor, named MinimalSensor, that creates 3 sensory units and simply set their state to 0.5 each time step. The source code included in this example, therefore, should be present in any other sensor with the exception of the instruction that assign the fixed value to the sensory units.
-
-The declaration of the sensor class, included below, specifies that the sensor is a subclass of the general Sensor class (i.e. that can be used on any type robot).  The declaration specifies the sensor functions and create a pointer to the *neuronsIterator* resource (called m_neuronsIterator) that contains the state of the sensory units to be updated and a string containing the name of the *neuronsIterator* resource.
-
-We assume that this sensor will be placed inside an experimental plugin. Consequently the declaration include the FARSA_PLUGIN_API and FARSA_REGISTER_CLASS macro instructions.
+Below we illustrate the implementation of a simple sensor, named *MinimalSensor*, that creates 3 sensory units and simply sets their state to 0.5 each time step. The source code included in this example, therefore, can be used as a template for other sensors (with the exception of the instructions that assign the fixed value to the sensory units).
+
+The declaration of the sensor class, included below, shows that the sensor is a subclass of the general *Sensor* class (i.e. that can be used on any type of robot). The class has two data members: a pointer to the *neuronsIterator* resource (called *m_neuronsIterator*) that contains the state of the sensory units to be updated and a string containing the name of the *neuronsIterator* resource.
+
+We assume that this sensor will be placed inside an experimental plugin. Consequently the declaration includes the FARSA_PLUGIN_API and FARSA_REGISTER_CLASS macros.

 ~~~~~~~
 :::C++
 class FARSA_PLUGIN_API MinimalSensor : public Sensor
 {
-
-FARSA_REGISTER_CLASS (Sensor)
-
+    FARSA_REGISTER_CLASS(Sensor)
 public:
-   MinimalSensor(ConfigurationParameters& params, QString prefix);
-   ~MinimalSensor();
-   virtual void save(ConfigurationParameters& params, QString prefix);
-   static void describe(QString type);
-   virtual void update();
-   virtual int size();
+    MinimalSensor(ConfigurationParameters& params, QString prefix);
+    ~MinimalSensor();
+    virtual void save(ConfigurationParameters& params, QString prefix);
+    static void describe(QString type);
+    virtual void update();
+    virtual int size();
 protected:
-   virtual void resourceChanged(QString resourceName, ResourceChangeType changeType);
-   ResourceVector<real> m_additionalInputs;
-   const QString m_neuronsIteratorResource;
-   NeuronsIterator* m_neuronsIterator;
+    virtual void resourceChanged(QString resourceName, ResourceChangeType changeType);
+    const QString m_neuronsIteratorResource;
+    NeuronsIterator* m_neuronsIterator;
 };
 ~~~~~~~

-As all components, the sensor can include a *describe()* and *configure()* function that can be used to describe the function of the component and eventually to define component dependent parameters. In this simple case we do not need parameters, so we simply include a *describe()* function
-
-~~~~~~~
+The *Sensor* class (as well as *Motor*) inherits from *ParameterSettableInConstructor*. This means that the constructor has to take two parameters and that *describe()* has to be present. The only configuration parameter that this class expects is the name of the resource of the *neuronsIterator* (in the majority of the cases this parameter does not need to be changed).
+
+~~~~~~~
+:::C++
 void MinimalSensor::describe(QString type)
 {
-   // Calling parent function
-   Sensor::describe(type);
-
-   // Describing our parameters
-   Descriptor d = addTypeDescription(type, "It simply set 3 sensory units to 0.5", "This is an exemplificative sensor that create three sensory units and simply set them to a costant 0.5 value every time");
-}
-~~~~~~~
-
-The constructor of the MinimalSensor class is use to initialize to NULL the pointers to the needed resources and eventually to initialize other sensor dependent variables. In this example we just need to initialize to NULL the pointer to the neuronIterator resource.The destructor is empty since the sensor does not create any additional resource that need to be destroyed when the sensor class is destroyed. Sensors might need to access to the robot resource, the arena resource, or other resources. In the case of sensors that are robot independent (i.e. that are declared as a sub-class of the general Sensor class) and that are used in multirobots experiment multirobot it is important to keep in mind that the sensor should to the right robot of the team. This can be done by specifying different names for each robot during the robots initializations and by using the *actualResourceNameForMultirobot()* function to recover the appropriate robot.
-
-~~~~~~~
+    // Calling parent function
+    Sensor::describe(type);
+
+    // Describing our parameters
+    Descriptor d = addTypeDescription(type, "It simply set 3 sensory units to 0.5", "This is an exemplificative sensor that create three sensory units and simply set them to a costant 0.5 value every time");
+    d.describeString("neuronsIterator").def("neuronsIterator").help("The name of the resource associated with the neural network iterator (default is \"neuronsIterator\")");
+}
+~~~~~~~
+
+The constructor of the *MinimalSensor* class reads the configuration parameter with the name of the resource of the *neuronsIterator* and declares which resources the class will use. In the case of sensors that are used in multirobots experiments, it is important to keep in mind that the sensor should refer to the right robot of the team. This means that, in case of resources that refer to a specific robot, the name of the resource must be mangled so that it refers to the correct robot in the team. This is done by *actualResourceNameForMultirobot()*, which takes the generic resource name and returns the name the sensor should use. In the example below the function is applied to the name of the *neuronsIterator* resource.
+
+~~~~~~~
+:::C++
 MinimalSensor::MinimalSensor(ConfigurationParameters& params, QString prefix) :
-   MinimalSensor(params, prefix),
-   m_neuronsIterator(NULL)
-
-{
+    Sensor(params, prefix),
+    m_neuronsIteratorResource(actualResourceNameForMultirobot(ConfigurationHelper::getString(params, prefix + "neuronsIterator", "neuronsIterator"))),
+    m_neuronsIterator(NULL)
+{
+    addUsableResource(m_neuronsIteratorResource);
 }

 MinimalSensor::~MinimalSensor()
 {
-   // Nothing to do here
-}
-~~~~~~~
-
-The *size()* function specify and return the number of sensory units created and update by the sensor, 3 in our example. The number returned should be constant.
-
-~~~~~~~
+}
+~~~~~~~
+
+The *size()* function returns the number of sensory units created and updated by the sensor, 3 in our example. The value returned should be constant for the whole lifetime of the Sensor instance.
+
+~~~~~~~
+:::C++
 int MinimalSensor::size()
 {
-   return 3;
-}
-~~~~~~~
-
-The *resourceChanged()* function is use to initialize the pointers to the required resources and to set the label of the corresponding sensory units which is used by the graphic interface to display the elements of the robots' controller. In the case of this example the label of the three sensory units created by the sensor will be "m0", "m1", and "m2". The *setGraphicProperties()* function is also used to specify the range of the units and the colour with which the unit state will be displayed by the View->Neurons-Monitor graphic widget of Total99. 
-
-The *resourceChanged* function is called every time a resource used by the sensor changes (for more information see [this page]([Resources])). To avoid inconsistencies, this implementation check whether the notification concern a resource that has been deleted.
-
-~~~~~~~
+    return 3;
+}
+~~~~~~~
+
+The *resourceChanged()* function is used to initialize the pointers to the required resources and to set the label of the corresponding sensory units which is used by the graphic interface to display the elements of the robots' controller. In this example the label of the three sensory units created by the sensor will be "m0", "m1", and "m2". The *setGraphicProperties()* function is also used to specify the range of the units and the colour with which the unit state will be displayed by the "Neurons Monitor" graphic widget of *Evonet*.
+
+The *resourceChanged()* function is called every time a resource used by the sensor changes (for more information see [this page]([Resources])). To avoid inconsistencies, this implementation checks whether the notification concerns a resource that has been deleted.
+
+~~~~~~~
+:::C++
 void MinimalSensor::resourceChanged(QString resourceName, ResourceChangeType changeType)
 {
     if (changeType == Deleted) {
@@ -114,55 +118,55 @@
 }
 ~~~~~~~

-The *update()* function take care of updating the state of the sensory units. This function is called every time step, consequently the sensory units are update every time step. In this case the state of the three sensory units is simply set to 0.5. The *checkAllNeededResourcesExist()* is a helper function that checks whether all the resources the sensor has declared to use already exists. Its main purpouse is to prevent NULL pointer dereference errors when a resource pointer is stored in the *resourceChanged* callback instead of being accessed via the *getResource* method (as, in this case, *m_neuronsIterator*). Before actually setting the input of the controller, the *setCurrentBlock* function of the *NeuronsIterator* object is called to declare which is the block of sensory units that is going to be filled. As already explained above, the name of the block corresponding to the current sensor has the same name as the sensor itself (the name is returned by the *name* function). Afterwards, the *setInput()* function is used to set the value of the current element and *nextNeuron* is called to pass to the subsequent element. 
+The *update()* function takes care of updating the state of the sensory units. This function is called every time step, consequently the sensory units are update every time step. In this case the state of the three sensory units is simply set to 0.5. The *checkAllNeededResourcesExist()* is a helper function that checks whether all the resources the sensor has declared to use already exists. Its main purpouse is to prevent NULL pointer dereference errors when a resource pointer is stored in the *resourceChanged* callback instead of being accessed via the *getResource* method (as, in this case, *m_neuronsIterator*). Before actually setting the input of the controller, the *setCurrentBlock()* function of the *NeuronsIterator* object is called to declare which is the block of sensory units that is going to be filled. The name of the block corresponding to the current sensor has the same name as the sensor itself (i.e. the name is returned by the *name()* function). Afterwards, the *setInput()* function is used to set the value of the current element and *nextNeuron()* is called to pass to the subsequent element.

 ~~~~~~~
 :::C++
 void MinimalSensor::update()
 {
-   checkAllNeededResourcesExist();
-
-   ResourcesLocker locker(this);
-
-   m_neuronsIterator->setCurrentBlock(name());
-   for (unsigned int i = 0; i < m_additionalInputs.size(); i++, m_neuronsIterator->nextNeuron()) {
-       m_neuronsIterator->setInput(0.5);
-   }
+    checkAllNeededResourcesExist();
+
+    ResourcesLocker locker(this);
+
+    m_neuronsIterator->setCurrentBlock(name());
+    for (unsigned int i = 0; i < m_additionalInputs.size(); i++, m_neuronsIterator->nextNeuron()) {
+        m_neuronsIterator->setInput(0.5);
+    }
 }
 ~~~~~~~

 A Robot-Specific Sensor
 -------

-If the sensor you have to implement could be used by a specific robotic platform only, you need to declare it as sub-class of a specific robot sensor class (e.g. *EpuckSensor*, *KheperaSensor*, *MarXbotSensor* or *iCubSensor*). In this case, in the case of multiple robotic experiment you do not need to select the right robot, since this is handled automatically by these classes. Moreover you do not need to explicitly check the resources, since also this is handled automatically.
-
-As an example, here we enclose the source code of the *KheperaProximityIRSensor* class. Since this sensors is included inside FARSA, its declaration do not include the macro instructions that specify that it is a plugin and that it should be registered in the plugin lists, as for the case of the MinimalSensor described above.
-
-This sensor set the activation state of the 8 sensory units encoding the state of the corresponding infrared sensors of the Khepera on the basis of the whether the virtual rays departing from each simulated sensor intersect an object of the environment and on the basis of the distance between the sensor and the intersection point. This calculation is made by the *proximityIRSensorController()->activation()* function of the robot class that is called in the *update()* function of the sensor. 
-
-Notice also how the state of the sensor calculated by the *proximityIRSensorController()->activation()* is not assigned directly to the corresponding sensory unit but is first passed to the *applyNoise()* function that returns a value perturbed by noise. The *applyNoise()* function also receive as parameter the maximum and minimum value that the sensory unit can assume and truncates the value returned when it exceed the limits specified as a result of the noise application. The *applyNoise()* function can be applied to all sensors and motors and is indeed included in most of the sensors and motors implemented in FARSA. The type of noise added can be specified in the *noiseType* and *noiseRange* parameters of each sensor and motor. For more information on this function see the [API documentation]([APIDoc]). In the case of custom sensor that you implemented, you should remember to use the *applyNoise()* function if you want to apply noise. Otherwise the parameters *noiseType* and *noiseRange* will not have any effect.
+If the sensor you have to implement could be used by a specific robotic platform only, you can declare it as sub-class of a specific robot sensor class (e.g. *EpuckSensor*, *KheperaSensor*, *MarXbotSensor* or *iCubSensor*). In this case, the name of the *neuronsIterator* resource as well as the name of the *robot* resources are automatically modified so that they refer to the correct robot.
+
+As an example, here we enclose the source code of the *KheperaProximityIRSensor* class. Since this sensors is included inside FARSA, its declaration do not include the macro instructions that specify that it is a component and that it should be registered in the components lists, as for the case of the *MinimalSensor* described above.
+
+This sensor sets the activation state of the 8 sensory units encoding the state of the corresponding infrared sensors of the Khepera on the basis of whether the virtual rays departing from each simulated sensor intersects an object of the environment and on the basis of the distance between the sensor and the intersection point. This calculation is made by the *proximityIRSensorController()->activation()* function of the robot class that is called in the *update()* function of the sensor.
+
+Notice also how the state of the sensor calculated by the *proximityIRSensorController()->activation()* is not assigned directly to the corresponding sensory unit but it is first passed to the *applyNoise()* function that returns a value perturbed by noise. The *applyNoise()* function also receive as parameters the maximum and minimum value that the sensory unit can assume and truncates the value returned when it exceeds the limits specified as a result of the noise application. The *applyNoise()* function can be applied to all sensors and motors and is indeed included in most of the sensors and motors implemented in FARSA. The type of noise added can be specified in the *noiseType* and *noiseRange* parameters of each sensor and motor. For more information on this function see the [API documentation]([APIDoc]). In the case of custom sensors that you implemented, you should remember to use the *applyNoise()* function if you want to apply noise. Otherwise the parameters *noiseType* and *noiseRange* will not have any effect.

 ~~~~~~~
 :::C++
 class KheperaProximityIRSensor : public KheperaSensor
 {
 public:
-   KheperaProximityIRSensor(ConfigurationParameters& params, QString prefix);
-   virtual ~KheperaProximityIRSensor();
-   virtual void save(ConfigurationParameters& params, QString prefix);
-   static void describe(QString type);
-   virtual void update();
-   virtual int size();
+    KheperaProximityIRSensor(ConfigurationParameters& params, QString prefix);
+    virtual ~KheperaProximityIRSensor();
+    virtual void save(ConfigurationParameters& params, QString prefix);
+    static void describe(QString type);
+    virtual void update();
+    virtual int size();
 private:
-   virtual void resourceChanged(QString resourceName, ResourceChangeType changeType);
-   PhyKhepera* m_robot;
-   NeuronsIterator* m_neuronsIterator;
+    virtual void resourceChanged(QString resourceName, ResourceChangeType changeType);
+    PhyKhepera* m_robot;
+    NeuronsIterator* m_neuronsIterator;
 };

-KheperaProximityIRSensor::KheperaProximityIRSensor(ConfigurationParameters& params, QString prefix) :
-   KheperaSensor(params, prefix),
-   m_robot(NULL),
-   m_neuronsIterator(NULL)
+KheperaProximityIRSensor::KheperaProximityIRSensor(ConfigurationParameters& params, QString prefix)
+    : KheperaSensor(params, prefix)
+    , m_robot(NULL)
+    , m_neuronsIterator(NULL)
 {
 }

@@ -172,154 +176,152 @@

 void KheperaProximityIRSensor::save(ConfigurationParameters& params, QString prefix)
 {
-   // Calling parent function
-   KheperaSensor::save(params, prefix);
-
-   // Saving parameters
-   params.startObjectParameters(prefix, "KheperaProximityIRSensor", this);
+    // Calling parent function
+    KheperaSensor::save(params, prefix);
+
+    // Saving parameters
+    params.startObjectParameters(prefix, "KheperaProximityIRSensor", this);
 }

 void KheperaProximityIRSensor::describe(QString type)
 {
-   // Calling parent function
-   KheperaSensor::describe(type);
-
-   // Describing our parameters
-   Descriptor d = addTypeDescription(type, "The infrared proximity sensors of the Khepera robot", "The infrared proximity sensors of the Khepera II robot. These are the very short range IR sensors all around the base");
+    // Calling parent function
+    KheperaSensor::describe(type);
+
+    // Describing our parameters
+    Descriptor d = addTypeDescription(type, "The infrared proximity sensors of the Khepera robot", "The infrared proximity sensors of the Khepera II robot. These are the very short range IR sensors all around the base");
 }

 void KheperaProximityIRSensor::update()
 {
-   checkAllNeededResourcesExist();
-
-   ResourcesLocker locker( this );
-
-   m_neuronsIterator->setCurrentBlock(name());
-   for (int i = 0; i < size(); i++, m_neuronsIterator->nextNeuron()) {
-       // Setting the input of the controller after applying noise
-       m_neuronsIterator->setInput(applyNoise(m_robot->proximityIRSensorController()->activation(i), 0.0, 1.0));
+    checkAllNeededResourcesExist();
+
+    ResourcesLocker locker( this );
+
+    m_neuronsIterator->setCurrentBlock(name());
+    for (int i = 0; i < size(); i++, m_neuronsIterator->nextNeuron()) {
+        // Setting the input of the controller after applying noise
+        m_neuronsIterator->setInput(applyNoise(m_robot->proximityIRSensorController()->activation(i), 0.0, 1.0));
+    }
+}
+
+int KheperaProximityIRSensor::size()
+{
+    return 8;
+}
+
+void KheperaProximityIRSensor::resourceChanged(QString resourceName, ResourceChangeType changeType)
+{
+    KheperaSensor::resourceChanged(resourceName, changeType);
+
+    if (changeType == Deleted) {
+        return;
+    }
+
+    if (resourceName == m_kheperaResource) {
+        m_robot = getResource<PhyKhepera>();
+
+        m_robot->proximityIRSensorController()->setEnabled(true); // Eanbling sensors
+    } else if (resourceName == m_neuronsIteratorResource) {
+        m_neuronsIterator = getResource<NeuronsIterator>();
+        m_neuronsIterator->setCurrentBlock(name());
+        for (int i = 0; i < size(); i++, m_neuronsIterator->nextNeuron()) {
+            m_neuronsIterator->setGraphicProperties("ir" + QString::number(i), 0.0, 1.0, Qt::red);
    }
-}
-
-int KheperaProximityIRSensor::size()
-{
-   return 8;
-}
-
-void KheperaProximityIRSensor::resourceChanged(QString resourceName, ResourceChangeType changeType)
-{
-   KheperaSensor::resourceChanged(resourceName, changeType);
-
-   if (changeType == Deleted) {
-       return;
-   }
-
-   if (resourceName == m_kheperaResource) {
-       m_robot = getResource<PhyKhepera>();
-
-       m_robot->proximityIRSensorController()->setEnabled(true); // Eanbling sensors
-   } else if (resourceName == m_neuronsIteratorResource) {
-       m_neuronsIterator = getResource<NeuronsIterator>();
-       m_neuronsIterator->setCurrentBlock(name());
-       for (int i = 0; i < size(); i++, m_neuronsIterator->nextNeuron()) {
-           m_neuronsIterator->setGraphicProperties("ir" + QString::number(i), 0.0, 1.0, Qt::red);
-       }
-   } else {
-       Logger::info("Unknown resource " + resourceName + " for " + name());
-   }
+    } else {
+        Logger::info("Unknown resource " + resourceName + " for " + name());
+    }
 }
 ~~~~~~~

 A Simple Motor
 -------

-The implementation of motors is very similar to that of sensors. The only difference that in the *update()* function the state of the motor units is read through the *getOutput()* method of *NeuronsIterator* and then used to set the state of the robot actuators (e.g. to set the force applied to a motorized joint, to turn the robots' led on or off etc.). As an example, below we report the FakeMotor motor, that is robot independent, and that do not really change the actuators of the robot but simply store the output of the robots' controller into a vector resource called additionalOutput. This is a resource, costituted by a vector of number, that is declared in the *shareResourcesWith()* function. 
+The implementation of motors is very similar to that of sensors. The only difference is that in the *update()* function the state of the motor units is read through the *getOutput()* method of *NeuronsIterator* and then used to set the state of the robot actuators (e.g. to set the force applied by a motorized joint, to turn the robots' led on or off etc.). As an example, below we report the *FakeMotor* motor, that is robot independent, and that do not really change the actuators of the robot but simply store the output of the robots' controller into a vector resource called *additionalOutputs*. This is a resource, costituted by a vector of numbers, that is declared in the *shareResourcesWith()* function.

 ~~~~~~~
 :::C++
 class FakeMotor : public Motor
 {
 public:
-   FakeMotor(ConfigurationParameters& params, QString prefix);
-   ~FakeMotor();
-   virtual void save(ConfigurationParameters& params, QString prefix);
-   static void describe(QString type);
-   virtual void update();
-   virtual int size();
-   virtual void shareResourcesWith(ResourcesUser* other);
+    FakeMotor(ConfigurationParameters& params, QString prefix);
+    ~FakeMotor();
+    virtual void save(ConfigurationParameters& params, QString prefix);
+    static void describe(QString type);
+    virtual void update();
+    virtual int size();
+    virtual void shareResourcesWith(ResourcesUser* other);
 protected:
-   void resourceChanged(QString resourceName, ResourceChangeType changeType);
-   ResourceVector<real> m_additionalOutputs;
-   const QString m_neuronsIteratorResource;
-   const QString m_additionalOutputsResource;
-   NeuronsIterator* m_neuronsIterator;
+    void resourceChanged(QString resourceName, ResourceChangeType changeType);
+    ResourceVector<real> m_additionalOutputs;
+    const QString m_neuronsIteratorResource;
+    const QString m_additionalOutputsResource;
+    NeuronsIterator* m_neuronsIterator;
 };

-FakeMotor::FakeMotor(ConfigurationParameters& params, QString prefix) :
-   Motor(params, prefix),
-   m_additionalOutputs(ConfigurationHelper::getUnsignedInt(params, prefix + "additionalOutputs", 1)),
-   m_neuronsIteratorResource(actualResourceNameForMultirobot(ConfigurationHelper::getString(params, prefix + "neuronsIterator", "neuronsIterator"))),
-   m_additionalOutputsResource(actualResourceNameForMultirobot(ConfigurationHelper::getString(params, prefix + "additionalOutputsResource", "additionalOutputs"))),
-   m_neuronsIterator(NULL)
-{
-   usableResources(QStringList() << m_neuronsIteratorResource << m_additionalOutputsResource);
-
-   for (unsigned int i = 0; i < m_additionalOutputs.size(); i++) {
-       m_additionalOutputs[i] = 0.0;
-   }
+FakeMotor::FakeMotor(ConfigurationParameters& params, QString prefix)
+    : Motor(params, prefix)
+    , m_additionalOutputs(ConfigurationHelper::getUnsignedInt(params, prefix + "additionalOutputs", 1))
+    , m_neuronsIteratorResource(actualResourceNameForMultirobot(ConfigurationHelper::getString(params, prefix + "neuronsIterator", "neuronsIterator")))
+    , m_additionalOutputsResource(actualResourceNameForMultirobot(ConfigurationHelper::getString(params, prefix + "additionalOutputsResource", "additionalOutputs")))
+    , m_neuronsIterator(NULL)
+{
+    usableResources(QStringList() << m_neuronsIteratorResource << m_additionalOutputsResource);
+
+    for (unsigned int i = 0; i < m_additionalOutputs.size(); i++) {
+        m_additionalOutputs[i] = 0.0;
+    }
 }

 FakeMotor::~FakeMotor()
 {
-   try {
-       deleteResource(m_additionalOutputsResource);
-   } catch (...) {
-   }
+    try {
+        deleteResource(m_additionalOutputsResource);
+    } catch (...) {
+    }
 }

 [... save and describe skipped ...]

 void FakeMotor::update()
 {
-   checkAllNeededResourcesExist();
-
-   ResourcesLocker locker(this);
-
-   m_neuronsIterator->setCurrentBlock(name());
-   for (unsigned int i = 0; i < m_additionalOutputs.size(); i++, m_neuronsIterator->nextNeuron()) {
-       m_additionalOutputs[i] = m_neuronsIterator->getOutput();
-   }
+    checkAllNeededResourcesExist();
+
+    ResourcesLocker locker(this);
+
+    m_neuronsIterator->setCurrentBlock(name());
+    for (unsigned int i = 0; i < m_additionalOutputs.size(); i++, m_neuronsIterator->nextNeuron()) {
+        m_additionalOutputs[i] = m_neuronsIterator->getOutput();
+    }
 }

 int FakeMotor::size()
 {
-   return m_additionalOutputs.size();
+    return m_additionalOutputs.size();
 }

 void FakeMotor::shareResourcesWith(ResourcesUser* other)
 {
-   Motor::shareResourcesWith(other);
-
-   declareResource(m_additionalOutputsResource, &m_additionalOutputs);
+    Motor::shareResourcesWith(other);
+
+    declareResource(m_additionalOutputsResource, &m_additionalOutputs);
 }

 void FakeMotor::resourceChanged(QString resourceName, ResourceChangeType changeType)
 {
-   if (changeType == Deleted) {
-       resetNeededResourcesCheck();
-       return;
-   }
-
-   if (resourceName == m_neuronsIteratorResource) {
-       m_neuronsIterator = getResource<NeuronsIterator>();
-       m_neuronsIterator->setCurrentBlock(name());
-       for(int i = 0; i < size(); i++, m_neuronsIterator->nextNeuron()) {
-           m_neuronsIterator->setGraphicProperties("Fk" + QString::number(i), 0.0, 1.0, Qt::red);
-       }
-   } else if (resourceName != m_additionalOutputsResource) {
-       Logger::info("Unknown resource " + resourceName + " for " + name());
-   }
-}
-~~~~~~~
-
-
+    if (changeType == Deleted) {
+        resetNeededResourcesCheck();
+        return;
+    }
+
+    if (resourceName == m_neuronsIteratorResource) {
+        m_neuronsIterator = getResource<NeuronsIterator>();
+        m_neuronsIterator->setCurrentBlock(name());
+        for(int i = 0; i < size(); i++, m_neuronsIterator->nextNeuron()) {
+            m_neuronsIterator->setGraphicProperties("Fk" + QString::number(i), 0.0, 1.0, Qt::red);
+        }
+    } else if (resourceName != m_additionalOutputsResource) {
+        Logger::info("Unknown resource " + resourceName + " for " + name());
+    }
+}
+~~~~~~~

CustomSensorMotor modified by Tomassino Ferrauto

Tomassino Ferrauto — Sat, 14 Nov 2015 08:52:42 -0000

CustomSensorMotor modified by Tomassino Ferrauto

Tomassino Ferrauto — Fri, 13 Nov 2015 10:31:36 -0000

CustomSensorMotor modified by Tomassino Ferrauto

Tomassino Ferrauto — Thu, 12 Nov 2015 10:36:32 -0000

--- v20
+++ v21
@@ -1,4 +1,4 @@
-[Prev: Writing tests for evolutionary experiments]([EvorobotExperimentTest]) |  | [Next: Implementing a new world object]([NewWObject])
+[Prev: Writing tests for evolutionary experiments]([EvorobotExperimentTest]) | [Up: Home]([Home]) | [Next: Implementing a new world object]([NewWObject])
  -------|--------|----------
         |        |

CustomSensorMotor modified by Tomassino Ferrauto

Tomassino Ferrauto — Thu, 12 Nov 2015 10:21:26 -0000

--- v19
+++ v20
@@ -1,3 +1,11 @@
+[Prev: Writing tests for evolutionary experiments]([EvorobotExperimentTest]) |  | [Next: Implementing a new world object]([NewWObject])
+ -------|--------|----------
+        |        |
+
+**Table of contents**
+
+[TOC]
+
 Creating Custom Sensors or Motors
 =======
 FARSA provide many ready to use sensors and motors for each supported robot type as well as additional sensors and motors that can be used with different type of robots. Some of these sensors also perform a pre-processing of the information that can be extracted from the physical sensors. These sensors and motors istantiated and used by simply listing the required sensors and motors in the configuration file. In some case, however, you might want to implement a new type of sensor or motor for your experiment, or you might want to implement a new version of an existing sensor that preprocesses the sensory information in a different way with respect to existing sensors.

CustomSensorMotor modified by Stefano Nolfi

Stefano Nolfi — Thu, 29 Oct 2015 14:21:19 -0000

--- v18
+++ v19
@@ -1,4 +1,4 @@
-Creating custom sensors or motors
+Creating Custom Sensors or Motors
 =======
 FARSA provide many ready to use sensors and motors for each supported robot type as well as additional sensors and motors that can be used with different type of robots. Some of these sensors also perform a pre-processing of the information that can be extracted from the physical sensors. These sensors and motors istantiated and used by simply listing the required sensors and motors in the configuration file. In some case, however, you might want to implement a new type of sensor or motor for your experiment, or you might want to implement a new version of an existing sensor that preprocesses the sensory information in a different way with respect to existing sensors.

@@ -13,7 +13,7 @@

 Sensors that can be used with different robots are declared as subclass of the general *Sensor* class. Sensors that can be used only with a specific robotic platform are declared instead as sub-class of more specific classes (named KheperaSensor, EpuckSensor, MarXbotSensor and iCubSensor).  Similarly, motors that can be used with differen robots are declared as subclass of the general "Motor" class, while other motors are declared as subclass of more specific motor classes (named KheperaMotor, EpuckMotor, MarXbotMotor, and iCubMotor). 

-A simple sensor
+A Simple Sensor
 -------

 Below we illustrate the implementation of a simple sensor, named MinimalSensor, that creates 3 sensory units and simply set their state to 0.5 each time step. The source code included in this example, therefore, should be present in any other sensor with the exception of the instruction that assign the fixed value to the sensory units.
@@ -123,7 +123,7 @@
 }
 ~~~~~~~

-A Robot-Specific Custom sensor
+A Robot-Specific Sensor
 -------

 If the sensor you have to implement could be used by a specific robotic platform only, you need to declare it as sub-class of a specific robot sensor class (e.g. *EpuckSensor*, *KheperaSensor*, *MarXbotSensor* or *iCubSensor*). In this case, in the case of multiple robotic experiment you do not need to select the right robot, since this is handled automatically by these classes. Moreover you do not need to explicitly check the resources, since also this is handled automatically.
@@ -225,7 +225,7 @@
 A Simple Motor
 -------

-The implementation of motors is very similar to that of sensors. The only difference that in the *update()* function the state of the motor units is read through the *getOutput()* method of *NeuronsIterator* and then used to set the state of the robot actuators (e.g. to set the force applied to a motorized joint, to turn the robots' led on or off etc.). As an example, below we report the FakeMotor motor, that is robot independent, and that do not really change the actuators of the robot but simply store the output of the robots' controller into a vector resource called additionalOutput, 
+The implementation of motors is very similar to that of sensors. The only difference that in the *update()* function the state of the motor units is read through the *getOutput()* method of *NeuronsIterator* and then used to set the state of the robot actuators (e.g. to set the force applied to a motorized joint, to turn the robots' led on or off etc.). As an example, below we report the FakeMotor motor, that is robot independent, and that do not really change the actuators of the robot but simply store the output of the robots' controller into a vector resource called additionalOutput. This is a resource, costituted by a vector of number, that is declared in the *shareResourcesWith()* function. 

 ~~~~~~~
 :::C++
@@ -315,225 +315,3 @@
 ~~~~~~~

-
-*NoisyDevice*
--------
-
-*NoisyDevice* is a component that provides some basic functions to apply noise to values depending on configuration parameters. The component reads two configuration parameters, *noiseType* and  *noiseRange* that allows to set the kind of noise and the noise range respectively. Subclasses should then use the *applyNoise()* function whenever they want to apply noise to a value. The function takes three parameters, namely the value to which noise is to be applied, the mininum allowed value (if the result after the application of noise is below the minimum value, it is truncated to it) and the maximum allowed value (if the result after the application of noise is anove the maximum value, it is truncated to it) and returns the value after noise has been applied. The [API documentation]([APIDoc]) provides more details on this class and the supported noise distributions.
-
-As already said, all sensors and motors inherit from *NoisyDevice*. In case of exceptions, the documentation of the sensor or motor that does not apply noise or uses a different policy clearly states what is the behavior.
-
-
-Fake sensor
--------
-
-In this section we will analyse one sensor that is availabel with FARSA, named *FakeSensor*. This sensor defines a resource that is a vector of floating point values and then, at each timestep, sets the inputs in the controller using values from the vector. It is meant to be used for ad-hoc inputs or for quick tests before developing a proper sensor. Afterward, we will breifly show how to implement a sensor for a particular robot: in this case it is possible to use robot-specific base classes to reduce the amount of work that needs to be done.
-
-Here is the *FakeSensor* class declaration:
-
-~~~~~~~
-:::C++
-class FakeSensor : public Sensor
-{
-public:
-   FakeSensor(ConfigurationParameters& params, QString prefix);
-   ~FakeSensor();
-   virtual void save(ConfigurationParameters& params, QString prefix);
-   static void describe(QString type);
-   virtual void update();
-   virtual int size();
-   virtual void shareResourcesWith(ResourcesUser* other);
-protected:
-   virtual void resourceChanged(QString resourceName, ResourceChangeType changeType);
-   ResourceVector<real> m_additionalInputs;
-   const QString m_neuronsIteratorResource;
-   const QString m_additionalInputsResource;
-   NeuronsIterator* m_neuronsIterator;
-};
-~~~~~~~
-
-The two functions that are reimplemented from Sensor are *update* and *size*, The former is called at each step to feed the controller with inputs, the latter returns the number of elements of the sensor. The value returned by *size* must always stay the same. All the other functions are standard component functions (the constructor with two parameters, *save*, *describe*) or come from *ConcurrentResourcesUser* (*shareResourcesWith* and *resourceChanged*). The data members are the vector with values used as the controller input (*m_additionalInputs*), the name of two resources (*m_neuronsIteratorResource* and *m_additionalInputsResource*) and the *NeuronsIterator* instance (*m_neuronsIterator*). We will now describe each function (skipping the *describe* and *save* functions that are standard component functions)
-
-~~~~~~~
-:::C++
-FakeSensor::FakeSensor(ConfigurationParameters& params, QString prefix) :
-   Sensor(params, prefix),
-   m_additionalInputs(ConfigurationHelper::getUnsignedInt(params, prefix + "additionalInputs", 1)),
-   m_neuronsIteratorResource(actualResourceNameForMultirobot(ConfigurationHelper::getString(params, prefix + "neuronsIterator", "neuronsIterator"))),
-   m_additionalInputsResource(actualResourceNameForMultirobot(ConfigurationHelper::getString(params, prefix + "additionalInputsResource", "additionalInputs"))),
-   m_neuronsIterator(NULL)
-{
-   usableResources(QStringList() << m_neuronsIteratorResource << m_additionalInputsResource);
-
-   for (unsigned int i = 0; i < m_additionalInputs.size(); i++) {
-       m_additionalInputs[i] = 0.0;
-   }
-}
-~~~~~~~
-
-The constructor reads parameters, declares the resources that this sensor will use and clears the vector of values to use as the controller inputs. There are two things worth noting. The first one is the use of the *actualResourceNameForMultirobot* function. This function should be used to mangle the name of resources so that they are unique to the robot to which the sensor is attached. In case of multirobot setups, in fact, the sensor will be created once for each robot. In this case it is important to give unique names to different resources because each robot has, for example, its own vector of values. The second thing to notice is that the constructor does not declare the resource. This is done in the *shareResourcesWith* function, as explained in the [page on resources usage]([Resources]).
-
-~~~~~~~
-:::C++
-FakeSensor::~FakeSensor()
-{
-   try {
-       deleteResource(m_additionalInputsResource);
-   } catch (...) {
-   }
-}
-~~~~~~~
-
-The destructor simply removes the resource associated with the vector of values. The *try* ... *catch* clause is there to prevent exceptions being thrown from a destructor (in case the resource was deleted by someone else).
-
-~~~~~~~
-:::C++
-void FakeSensor::update()
-{
-   checkAllNeededResourcesExist();
-
-   ResourcesLocker locker(this);
-
-   m_neuronsIterator->setCurrentBlock(name());
-   for (unsigned int i = 0; i < m_additionalInputs.size(); i++, m_neuronsIterator->nextNeuron()) {
-       m_neuronsIterator->setInput(m_additionalInputs[i]);
-   }
-}
-~~~~~~~
-
-The *update* function is responsible of setting the input of the controller. *checkAllNeededResourcesExist* is a helper function that checks whether all the resources the sensor has declared to use already exists. Its main purpouse is to prevent NULL pointer dereference errors when a resource pointer is stored in the *resourceChanged* callback instead of being accessed via the *getResource* method (as, in this case, *m_neuronsIterator*). Before actually setting the input of the controller, the *setCurrentBlock* function of the *NeuronsIterator* object is called to declare which is the block of inputs that is going to be filled. As already explained above, the name of the block corresponding to the current sensor has the same name as the sensor itself (the name is returned by the *name* function). Afterwards, the *setInput* function is used to set the value of the current element and *nextNeuron* is called to pass to the subsequent element. Notice that in this case the sensor does not apply noise (take a look at the source code of the *KheperaProximityIRSensor::update* function below for an example of how noise is applied).
-
-~~~~~~~
-:::C++
-int FakeSensor::size()
-{
-   return m_additionalInputs.size();
-}
-~~~~~~~
-
-As already explained, this function simply returns the number of input elements in the sensor.
-
-~~~~~~~
-:::C++
-void FakeSensor::shareResourcesWith(ResourcesUser* other)
-{
-   Sensor::shareResourcesWith(other);
-
-   declareResource(m_additionalInputsResource, &m_additionalInputs);
-}
-~~~~~~~
-
-As already anticipated, this function has been implemented to be able to declare the resource corresponding to the vector of elements to be used as inputs.
-
-~~~~~~~
-:::C++
-void FakeSensor::resourceChanged(QString resourceName, ResourceChangeType changeType)
-{
-   if (changeType == Deleted) {
-       resetNeededResourcesCheck();
-       return;
-   }
-
-   if (resourceName == m_neuronsIteratorResource) {
-       m_neuronsIterator = getResource<NeuronsIterator>();
-       m_neuronsIterator->setCurrentBlock(name());
-       for(int i = 0; i < size(); i++, m_neuronsIterator->nextNeuron()) {
-           m_neuronsIterator->setGraphicProperties("Fk" + QString::number(i), 0.0, 1.0, Qt::red);
-       }
-   } else if (resourceName != m_additionalInputsResource) {
-       Logger::info("Unknown resource " + resourceName + " for " + name());
-   }
-}
-~~~~~~~
-
-The *resourceChanged* function is the callback called whenever a resource the sensor is using changes, as explained in [this page]([Resources]). This implementation first checks if the notification is about a resource that has been deleted: in this case a flag needs to be reset so that the *checkAllNeededResourcesExist* (called in the *update* method) will perform a full check the next time it is called. After that it makes sure that the resource that has changed is not unexpected (the check is redundant and only there to asses FARSA internals work as expected) and then, if the resource that changed is the *NeuronsIterator* instance, it sets the graphical properties of elements (again, first *setCurrentBlock* is called, followed by various calls to *setGraphicProperties* and *nextNeuron*).
-
-
-
-
-
-
-
-Custom motor: robot-specific classes
--------
-
-As for sensors, also in the case of motors there are classes you can inherit from that are robot-specific (at the time of writing, they are *EpuckMotor*, *KheperaMotor*, *MarXbotMotor* or *iCubMotor*). These same considerations done for robot-specific sensors also apply here. As an example, here is the code of the *KheperaProximityIRSensor* class:
-
-~~~~~~~
-:::C++
-class KheperaWheelVelocityMotor : public KheperaMotor
-{
-public:
-   KheperaWheelVelocityMotor(ConfigurationParameters& params, QString prefix);
-   virtual ~KheperaWheelVelocityMotor();
-   virtual void save(ConfigurationParameters& params, QString prefix);
-   static void describe(QString type);
-   virtual void update();
-   virtual int size();
-private:
-   virtual void resourceChanged(QString resourceName, ResourceChangeType changeType);
-   PhyKhepera* m_robot;
-   NeuronsIterator* m_neuronsIterator;
-};
-
-KheperaWheelVelocityMotor::KheperaWheelVelocityMotor(ConfigurationParameters& params, QString prefix) :
-   KheperaMotor(params, prefix),
-   m_robot(NULL),
-   m_neuronsIterator(NULL)
-{
-}
-
-KheperaWheelVelocityMotor::~KheperaWheelVelocityMotor()
-{
-}
-
-[... save and describe skipped ...]
-
-void KheperaWheelVelocityMotor::update()
-{
-   checkAllNeededResourcesExist();
-
-   ResourcesLocker locker( this );
-
-   // Getting limit velocities for wheels
-   double minSpeed1;
-   double minSpeed2;
-   double maxSpeed1;
-   double maxSpeed2;
-   m_robot->wheelsController()->getSpeedLimits(minSpeed1, minSpeed2, maxSpeed1, maxSpeed2);
-
-   // Computing desired wheel velocities
-   m_neuronsIterator->setCurrentBlock(name());
-   const double v1 = (maxSpeed1 - minSpeed1) * applyNoise(m_neuronsIterator->getOutput(), 0.0, -1.0) + minSpeed1;
-   m_neuronsIterator->nextNeuron();
-   const double v2 = (maxSpeed2 - minSpeed2) * applyNoise(m_neuronsIterator->getOutput(), 0.0, -1.0) + minSpeed2;
-
-   m_robot->wheelsController()->setSpeeds(v1, v2);
-}
-
-int KheperaWheelVelocityMotor::size()
-{
-   return 2;
-}
-
-void KheperaWheelVelocityMotor::resourceChanged(QString resourceName, ResourceChangeType changeType)
-{
-   KheperaMotor::resourceChanged(resourceName, changeType);
-
-   if (changeType == Deleted) {
-       return;
-   }
-
-   if (resourceName == m_kheperaResource) {
-       m_robot = getResource<PhyKhepera>();
-   } else if (resourceName == m_neuronsIteratorResource) {
-       m_neuronsIterator = getResource<NeuronsIterator>();
-       m_neuronsIterator->setCurrentBlock(name());
-       for (int i = 0; i < size(); i++, m_neuronsIterator->nextNeuron()) {
-           m_neuronsIterator->setGraphicProperties("W" + QString::number(i), 0.0, 1.0, Qt::red);
-       }
-   } else {
-       Logger::info("Unknown resource " + resourceName + " for " + name());
-   }
-}
-~~~~~~~

CustomSensorMotor modified by Stefano Nolfi

Stefano Nolfi — Thu, 29 Oct 2015 14:16:11 -0000

--- v17
+++ v18
@@ -131,6 +131,8 @@
 As an example, here we enclose the source code of the *KheperaProximityIRSensor* class. Since this sensors is included inside FARSA, its declaration do not include the macro instructions that specify that it is a plugin and that it should be registered in the plugin lists, as for the case of the MinimalSensor described above.

 This sensor set the activation state of the 8 sensory units encoding the state of the corresponding infrared sensors of the Khepera on the basis of the whether the virtual rays departing from each simulated sensor intersect an object of the environment and on the basis of the distance between the sensor and the intersection point. This calculation is made by the *proximityIRSensorController()->activation()* function of the robot class that is called in the *update()* function of the sensor. 
+
+Notice also how the state of the sensor calculated by the *proximityIRSensorController()->activation()* is not assigned directly to the corresponding sensory unit but is first passed to the *applyNoise()* function that returns a value perturbed by noise. The *applyNoise()* function also receive as parameter the maximum and minimum value that the sensory unit can assume and truncates the value returned when it exceed the limits specified as a result of the noise application. The *applyNoise()* function can be applied to all sensors and motors and is indeed included in most of the sensors and motors implemented in FARSA. The type of noise added can be specified in the *noiseType* and *noiseRange* parameters of each sensor and motor. For more information on this function see the [API documentation]([APIDoc]). In the case of custom sensor that you implemented, you should remember to use the *applyNoise()* function if you want to apply noise. Otherwise the parameters *noiseType* and *noiseRange* will not have any effect.

 ~~~~~~~
 :::C++

CustomSensorMotor modified by Stefano Nolfi

Stefano Nolfi — Thu, 29 Oct 2015 13:57:29 -0000

--- v16
+++ v17
@@ -18,12 +18,17 @@

 Below we illustrate the implementation of a simple sensor, named MinimalSensor, that creates 3 sensory units and simply set their state to 0.5 each time step. The source code included in this example, therefore, should be present in any other sensor with the exception of the instruction that assign the fixed value to the sensory units.

-The declaration of the sensor class, included below, specifies that the sensor is a subclass of the general Sensor class (i.e. that can be used on any type robot).  The declaration specifies the sensor functions and create a pointer to the *neuronsIterator* resource (called m_neuronsIterator) that contains the state of the sensory units to be updated. A CHE SERVE const QString m_neuronsIteratorResource ?
-
-~~~~~~~
-:::C++
-class MinimalSensor : public Sensor
-{
+The declaration of the sensor class, included below, specifies that the sensor is a subclass of the general Sensor class (i.e. that can be used on any type robot).  The declaration specifies the sensor functions and create a pointer to the *neuronsIterator* resource (called m_neuronsIterator) that contains the state of the sensory units to be updated and a string containing the name of the *neuronsIterator* resource.
+
+We assume that this sensor will be placed inside an experimental plugin. Consequently the declaration include the FARSA_PLUGIN_API and FARSA_REGISTER_CLASS macro instructions.
+
+~~~~~~~
+:::C++
+class FARSA_PLUGIN_API MinimalSensor : public Sensor
+{
+
+FARSA_REGISTER_CLASS (Sensor)
+
 public:
    MinimalSensor(ConfigurationParameters& params, QString prefix);
    ~MinimalSensor();
@@ -31,7 +36,6 @@
    static void describe(QString type);
    virtual void update();
    virtual int size();
-   virtual void shareResourcesWith(ResourcesUser* other);
 protected:
    virtual void resourceChanged(QString resourceName, ResourceChangeType changeType);
    ResourceVector<real> m_additionalInputs;
@@ -122,8 +126,11 @@
 A Robot-Specific Custom sensor
 -------

-QUESTA PARTE NON MI E' CHIARA
-If the sensor you have to implement could be used by a specific robotic platform only, you need to declare it as sub-class of a specific robot sensor class (e.g. *EpuckSensor*, *KheperaSensor*, *MarXbotSensor* or *iCubSensor*). These classes define two parameters, one for the name of the resource of the robot and one for the name of the resource of the *NeuronsIterator* instance. Both are mangled using *actualResourceNameForMultirobot*, so you can use the values of those parameters directly (the classes also declare that both resources are used). Moreover these classes also call *resetNeededResourcesCheck* when necessary (make sure you call the parent implementation of *resourceChanged*). For everything else you should proceed as described in the example above. As an example, here is the code of the *KheperaProximityIRSensor* class:
+If the sensor you have to implement could be used by a specific robotic platform only, you need to declare it as sub-class of a specific robot sensor class (e.g. *EpuckSensor*, *KheperaSensor*, *MarXbotSensor* or *iCubSensor*). In this case, in the case of multiple robotic experiment you do not need to select the right robot, since this is handled automatically by these classes. Moreover you do not need to explicitly check the resources, since also this is handled automatically.
+
+As an example, here we enclose the source code of the *KheperaProximityIRSensor* class. Since this sensors is included inside FARSA, its declaration do not include the macro instructions that specify that it is a plugin and that it should be registered in the plugin lists, as for the case of the MinimalSensor described above.
+
+This sensor set the activation state of the 8 sensory units encoding the state of the corresponding infrared sensors of the Khepera on the basis of the whether the virtual rays departing from each simulated sensor intersect an object of the environment and on the basis of the distance between the sensor and the intersection point. This calculation is made by the *proximityIRSensorController()->activation()* function of the robot class that is called in the *update()* function of the sensor. 

 ~~~~~~~
 :::C++
@@ -307,8 +314,6 @@

-**NOTE** Examples lack the FARSA_PLUGIN_* and the FARSA_REGISTER_CLASS macros because they are taken from the core libraries of FARSA. When implementing sensors and motors in a plugin, remember to follow the guidelines in [this page]([PluginsAndRegistration]).
-
 *NoisyDevice*
 -------

CustomSensorMotor modified by Stefano Nolfi

Stefano Nolfi — Thu, 29 Oct 2015 11:43:44 -0000

--- v15
+++ v16
@@ -53,7 +53,7 @@
 }
 ~~~~~~~

-The constructor of the MinimalSensor class is use to initialize to NULL the pointers to the needed resources and eventually to initialize other sensor dependent variables. In this example we just need to initialize to NULL the pointer to the neuronIterator resource.The destructor is empty since the sensor does not create any additional resource that need to be destroyed when the sensor class is destroyed. Sensors might need to access to the robot resource, the arena resource, or other resources. In the case of multirobot experiments it is important to keep in mind that the sensor should access to a specific robot. This can be done by specifying different names to each robot during the robots initialization and by using the *actualResourceNameForMultirobot()* function.
+The constructor of the MinimalSensor class is use to initialize to NULL the pointers to the needed resources and eventually to initialize other sensor dependent variables. In this example we just need to initialize to NULL the pointer to the neuronIterator resource.The destructor is empty since the sensor does not create any additional resource that need to be destroyed when the sensor class is destroyed. Sensors might need to access to the robot resource, the arena resource, or other resources. In the case of sensors that are robot independent (i.e. that are declared as a sub-class of the general Sensor class) and that are used in multirobots experiment multirobot it is important to keep in mind that the sensor should to the right robot of the team. This can be done by specifying different names for each robot during the robots initializations and by using the *actualResourceNameForMultirobot()* function to recover the appropriate robot.

 ~~~~~~~
 MinimalSensor::MinimalSensor(ConfigurationParameters& params, QString prefix) :