This module reads the raw tactile sensor values, compensates for the (thermal) drift of the sensors (basically it is a high pass filter) and writes the compensated values on output ports.

Collaboration diagram for skinManager:

This module reads the raw tactile sensor values, compensates for the (thermal) drift of the sensors (basically it is a high pass filter) and writes the compensated values on output ports.

The module can manage many input ports at the same time (see parameter "inputPorts"). For each input port the compensated tactile data are written on the corresponding output port (see parameter "outputPorts"). Optionally, the module also can apply a smoothing filter (low pass filter) and/or a binarization filter to the data. The skinManagerGui can be used to control and monitor an instance of the skinManager module. If the 3d position of the tactile sensors is provided, then this module computes the skinContacts (see library skinDynLib), which can be used by wholeBodyDynamics to compute the contact forces.

Description

When launched the module executes the skin sensor calibration, assuming that the sensors are not in contact with anything during this phase. The calibration resets the taxel baselines, gathers the sensor data for 5 sec, computes the mean (i.e. the baseline) and the 95 percentile (i.e. the touch threshold) for every taxel.

After the calibration the module starts reading the raw data, computing the difference between the read values and the baseline, and outputs the results. If no touch is detected (i.e. the compensated values are under the touch threshold) then the baseline is updated in order to follow the drift (if any).

The binarization filter is really simple. Every taxel has a touch threshold, given by its 95% percentile plus a safety threshold (2 by default). If the read value is greater than the corrisponding touch threshold the output is set to 100, otherwise to 0. The binarization filter can be used for stressing the touch detection, especially in cases where the touch is very light.

The smoothing filter performs an exponential moving average in order to reduce the sensor noise. The intensity of the filter can be tuned by setting the parameter alpha, also called "smoothing factor". The smoothed output is a weighted average of the current input and the previous output: y(t) = (1-alpha)*x(t) + alpha*y(t-1)

If the module is properly configured then it performs contact clustering, that is it determines how many contacts are detected by the tactile sensors. When tactile sensors that are neighbors detect contact, they are clustered together. When tactile sensors that are not neighbors detect contact, they are considered as independent contacts. The result of this operation is a skinContactList (see skinDynLib) that is written on the output port "\moduleName\skin_events:o". Tipically this port is connected to an input port of the module wholeBodyDynamics which uses this data to estimate the contact forces.

Libraries

YARP.

Parameters

Command-line Parameters

The following key-value pairs can be specified as command-line parameters by prefixing – to the key (e.g. –from file.ini). The value part can be changed to suit your needs; the default values are shown below.

from [driftCompLeft.ini]
specifies the configuration file
context [skinGui]
specifies the sub-path from $ICUB_ROOT/app to the configuration file
name [skinManager]

specifies the name of the module (used to form the stem of module port names)
robot [icub]

specifies the name of the robot (used only to distiguish the simulator and the real robot)

Configuration File Parameters

The following key-value pairs can be specified as parameters in the configuration file (they can also be specified as command-line parameters if you so wish). The value part can be changed to suit your needs; the default values are shown below.

inputPorts [emptyList]
list of the input ports from which the module has to read the tactile data. For each input port there has to be a corresponding output port specified in the "outputPorts" parameter.
outputPorts [emptyList]
list of the output ports on which the module has to write the compensated tactile data. For each output port there has to be a corresponding input port specified in the "inputPorts" parameter.
period [20]
period of the compensating thread expressed in ms.
minBaseline [3]

if the baseline of one sensor (at least) reaches this value, then a warning message is sent on the info output port.
zeroUpRawData [false]
if true the input tactile data are considered from zero up, otherwise from 255 down
binarization [not active]
if specified the output tactile data are binarized: 0 indicates no touch, whereas 100 indicates touch
smoothFilter [not active]
if specified the output tactile data are filtered with an exponential moving average (where alpha is the smooth factor): \t- y(t) = (1-alpha)*x(t) + alpha*y(t-1)
smoothFactor [0.5]
alpha value of the smoothing filter, in [0, 1] where 0 is no smoothing at all and 1 is the max smoothing possible.

An optional section called SKIN_EVENTS may be specified in the configuration file. These are the parameters of this section:

bodyParts [emptyList]
list of the body parts corresponding to the specified inputPorts (see common.h in skinDynLib for the definition of BodyPart). For each input port there has to be a body part, e.g. UNKNOWN_BODY_PART, HEAD, TORSO, LEFT_ARM, RIGHT_ARM, LEFT_LEG, RIGHT_LEG.
skinParts [emptyList]
list of the skin part corresponding to the specified inputPorts (see skinDynLib for the definition of SkinPart). For each input port there has to be a skin part, e.g. UNKNOWN_SKIN_PART, HAND, FOREARM, UPPER_ARM.
linkList [emptyList]
list of the link number corresponding to the specified inputPorts. For each input port there has to be a link number (2: upperArm link, 4: forearm link, 6: hand link).
taxelPositionFiles [emptyList]
list of the files containing the 3D positions and orientations of the tactile sensors for each input port. The files contains a set of parameters used for configuring the correspondent skinPart (iCub::skinDynLib::skinPart , see skinDynLib for a definition of this class). Further, there is a group called [calibration] containing one line for each tactile sensor. In each line there are 6 values, the first three are the position, the last three are the orientation. For each input port there has to be a taxel position file (which may not exist because of missing calibration procedure for that skin part).
maxNeighborDist 0.015
maximum distance between two neighbor tactile sensors (in meters).

Ports Accessed

All the ports listed in the "inputPorts" parameter and the corresponding rpc ports. For instance if in the "inputPorts" parameter it is specified the port

/icub/skin/right_hand

then also the port

/icub/skin/right_hand/rpc:i

will be accessed.

Ports Created

Output ports

Every port specified in the "outputPorts" parameter: outputs a yarp::sig::Vector containing the compensated tactile data.
"/"+moduleName+"/monitor:o":
outputs a yarp::os::Bottle containing streaming information regarding the compensation status (used to communicate with the skinManagerGui). The first value is the data frequency, while all the following ones represent the drift compensated so far for each taxel.
"/"+moduleName+"/info:o":
outputs a yarp::os::Bottle containing occasional information regarding the compensation status such as warning or error messages (used to communicate with the skinManagerGui). Possible messages may regard an error in the sensor reading or an excessive drift of the baseline of a taxel.
"/"+moduleName+"/skin_events:o":
outputs a iCub::skinDynLib::skinContactList containing the list of contacts.

Input ports

For each port specified in the "inputPorts" parameter a local port is created with the name "/"+moduleName+index+"/input", where "index" is an increasing counter starting from 0.
"/"+moduleName+"/rpc:i": input port to control the module (alternatively the skinManagerGui can be used). This port accepts a yarp::os::yarp::os::Bottle that contains one of these commands:
- "calib": force the sensor calibration
- "get touch thr": return a yarp::os::yarp::os::Bottle containing the 95 percentile values of the tactile sensors
- "set binarization": enable or disable the binarization (specifying the value on/off)
- "get binarization": get the binarization filter state (on, off)
- "set smooth filter": enable or disable the smooth filter (specifying the value on/off)
- "get smooth filter": get the smooth filter state (on, off)
- "set smooth factor": set the value of the smooth factor (in [0,1])
- "get smooth factor": get the smooth factor value
- "set threshold": set the safety threshold that is added to the touch thresholds (int in [0, 254])
- "get threshold": get the safety threshold that is added to the touch thresholds (int in [0, 254])
- "set gain": set the compensation gain
- "get gain": get the compensation gain
- "set contact gain": set the contact compensation gain
- "get contact gain": get the contact compensation gain
- "is calibrating": tell whether the skin calibration is in progress
- "get pose": get taxel pose(s) with input params: body part, skin part, taxel index (if taxel index is not specified return all taxel positions),
- "set pose": set taxel pose(s) with input params: body part, skin part, taxel index, pose(s) (if taxel index is not specified set all taxel positions),
- "get info": get information about the module (module name, robot name, input ports, num of taxels)
- "help": get a list of the commands accepted by this module
- "quit": quit the module
All the commands accepted by this module are defined in rpcSkinManager.h .

Input Data Files

None.

Output Data Files

None.

Configuration Files

None.

Tested OS

Linux and Windows.

Example Instantiation of the Module

skinManager –context skinGui –from driftCompRight.ini

Author: Andrea Del Prete (andre.nosp@m.a.de.nosp@m.lpret.nosp@m.e@ii.nosp@m.t.it), Alexander Schmitz, Francesco Giovannini (franc.nosp@m.esco.nosp@m..giov.nosp@m.anni.nosp@m.ni@ii.nosp@m.t.it)

CopyPolicy: Released under the terms of the GNU GPL v2.0.

This file can be edited at ICUB_HOME/main/src/modules/skinManager/include/iCub/skinManager/skinManager.h.