[wish][doc] documentation of controlboardwrapper2 device

[traversaro]

More of a wish then a bug, but I was using a bit the controlboardwrapper2 device and its behaviour with respect to input configuration is quite a black magic (even checking on the open(..) source code!).
When you have some time @barbalberto could you push some documentation on the used parameters? Thanks a lot!

Some random points that would be nice to be addressed in documentation:

• is subdevice parameter supported or is supported only for running legacy code in iCub_SIM?

[traversaro]

Just to add a real bug: documentation for ControlBoardWrapper class is missing from the doxygen documentation. I guess there is some DOXYGEN_SHOULD_SKIP_THIS around.

[barbalberto]

It was added mainly to support the iCub_SIM, it is usable but it actually checks for a subset of parameter slightly different than the standard way.
The best would be to make the 2 ways uniform.

[traversaro]

I understand. What is the standard way of spawning a controlboardwrapper2 wrapping a given device using (yarp|icubmod)dev? (The "controlboard" equivalent of this camera configuration file: https://github.com/robotology/icub-main/blob/master/app/robots/iCubGenova01/camera/dragonfly2_config_left.ini )

[barbalberto]

One example is the following:

<device name="left_arm_mc_wrapper" type="controlboardwrapper2"> 
<param name="threadrate">  10  </param>    rate of the thread refreshing data
<paramlist name="networks">    list of subdevices
  <elem name="left_arm_joints">  0  7  0  7 </elem>  mapping of joints: wrapper start, wrapper end, device start, device end
  <elem name="left_hand_joints"> 8 15  0  7 </elem>  same as previous line
</paramlist>

<param name="name">   /icub/left_arm        </param>  name of the output port (full name)
<param name="joints"> 16            </param>  total number of joints, must match the sums of joint lists in the network group

<action phase="startup" level="5" type="attach">   FOR ROBOTiNTERFACE ONLY, tells to call attach function on start-up
  <paramlist name="networks">
      <elem name="left_arm_joints">  left_arm_mc </elem>   list of devices to attach to, names must match the corresponding     <device name> tag used to create the device
      <elem name="left_hand_joints"> left_hand_mc </elem>
    </paramlist>
</action>

If you are using .ini files (not robotInteface) substitute the paramlists with group like this:

networks (left_arm_joints left_hand_joints)
joints 16
left_arm_joints 0 7 0 7
left_hand_joints 8 15 0 7

Note: in this case you have to call the attach method with the proper PolyDriverList set in place.

If you are running it from terminal, you can only use --subdevice option.
In this case, all the network part in not necessary (because you can attach only 1 ubdevice) parameter and the total number of joints is called TotalJoints intead of joints

I know this device is kind of complex, if you need more information please tell me.

[traversaro]

Mhh I got the basic understanding. The subdevice mode is quite clean, and I guess we can get rid of the TotalJoints option by appropriately calling the getAxes method of the opened device, am I right?

We could then use this simple mode in gazebo_yarp_controlboard configuration to get rid of a lot of duplication that we have in configuration files at the moment.
cc @EnricoMingo robotology/gazebo-yarp-plugins#142

[barbalberto]

Well ... yes and no
+1 for the getaxes, I've not thought about this option. sounds good since subdevice option is meant to be used with just 1 subdevice. I'll check in the code if it is feasible

In order to use the --subdevice for gazebo plugins there are 2 thing to take into account:

1. the plugin needs to be a fully featured yarp plugin because they will be opened by the yarp facory and not anymore from the gazebo directly. This can be done, the plugin system is working fine now, it only means they will need a .ini file (another one describing the plugin) and placed in yarp_data_dirs folder and installed correctly (some more CMake magic)
2. if I remember correcty we need the pointer of the device class to be shared with Gazebo main simulation, if we use the --subdevice way of creating device we lose the access to the subdevice, we only have access to the wrapper. This may have changed wee the improvement of the gazebo plugins, so maybe it can be done, we need to check better because this is the key point.

[traversaro]

Mhh I did not want to to invoke the device through yarpdev, the current way of loading gazebo plugins is ok (they are added to the factory in the Load method of the Gazebo plugin). I just wanted to clean up the configuration files that are quite messy.
For example this is the configuration file for iCub left_leg [1]:

[include "gazebo_icub_robotname.ini"]

[WRAPPER]
# name of the wrapper device to be instatiated by the factory
device controlboardwrapper2
# rate of output streaming from ports in ms
threadrate 10
# output port name (a leading '/' will be added by code)
name ${gazeboYarpPluginsRobotName}/left_arm
# Total number of joints
joints 7
# list of MotorControl device to use
networks ( left_arm )
# for each network specify the joint map
left_arm  0 6 0 6
# Verbose output (on if present, off if commented out)
#verbose


# Specify configuration of MotorControl devices
[left_arm]
# name of the device to be instatiated by the factory
device gazebo_controlboard
#jointNames list
jointNames l_shoulder_pitch l_shoulder_roll l_shoulder_yaw l_elbow l_wrist_prosup l_wrist_pitch l_wrist_yaw
name left_arm


#PIDs:
# this information is used to set the PID values in simulation for GAZEBO, we need only the first three values
[GAZEBO_PIDS]
#Left Arm
Pid0 100.0 10.0 10.0 9999 9999 9 9
Pid1 100.0 10.0 10.0 9999 9999 9 9
Pid2 100.0 10.0 10.0 9999 9999 9 9
Pid3 100.0 10.0 10.0 9999 9999 9 9
Pid4 100.0 10.0 10.0 9999 9999 9 9
Pid5 100.0 10.0 10.0 9999 9999 9 9
Pid6 100.0 10.0 10.0 9999 9999 9 9

[GAZEBO_VELOCITY_PIDS]
#Left Arm
Pid0 500.0 2.0 0.1 9999 9999 9 9
Pid1 500.0 2.0 0.1 9999 9999 9 9
Pid2 500.0 2.0 0.1 9999 9999 9 9
Pid3 300.0 0.1 0.01 9999 9999 9 9
Pid4 300.0 0.1 0.01 9999 9999 9 9
Pid5 300.0 0.1 0.01 9999 9999 9 9
Pid6 300.0 0.1 0.01 9999 9999 9 9

This is quite confusing for the user because information is quite redundant: left_arm is repeated 4 times, the number of joints is repeated 3 times, and all the times this joint number is redundant because it is already defined in the jointNames variable. This duplication is quite confusing for the users, even because most of the parameters of the controlboardwrapper are undocumented.

I guess we can support this way of writing configuration files by adding some code for avoiding explicitly creating/attaching the gazebo_controlboard device it the subdevice parameters is passed. There is no problem in doing this, I already do the same thing in the gazebo_yarp_imu
plugin.
[1] : https://github.com/robotology-playground/icub-gazebo/blob/master/icub/conf/gazebo_icub_left_arm.ini

[barbalberto]

Documentation now is in doxygen with examples and quite accurate.
Can we close this?

[traversaro]

I remember that at some point you wrote the documentation. But I can't find the device documented in http://www.yarp.it/group__dev__impl__wrapper.html .

Something went wrong in doxygen generation?
This class seems not to be a device, but it appears to have the controlboardwrapper documentation: http://www.yarp.it/classyarp_1_1dev_1_1impl_1_1MultiJointData.html .

[barbalberto]

Yes, it looks like the documentation was generated in the wrong place :-(
should be fixed by eb9878, waiting for online doxygen updated to close the issue