From 50e2395d9fc8a43c577255fd6a35a3ddc92a7359 Mon Sep 17 00:00:00 2001 From: Silvio Traversaro Date: Wed, 10 Feb 2021 11:08:14 +0100 Subject: [PATCH] Update README.md --- plugins/robotinterface/README.md | 82 +++++++++++++++++++++++++++++++- 1 file changed, 80 insertions(+), 2 deletions(-) diff --git a/plugins/robotinterface/README.md b/plugins/robotinterface/README.md index 049ab6ea6..30e5734d1 100644 --- a/plugins/robotinterface/README.md +++ b/plugins/robotinterface/README.md @@ -1,5 +1,83 @@ gazebo_yarp_robotinterface ========================== -The `gazebo_yarp_robotinterface` plugin permits to load several [YARP devices]() that can be attached to YARP devices -already opened by other Gazebo-YARP plugins using the same XML format used by the [`yarprobotinterface`](http://www.yarp.it/git-master/yarprobotinterface.html) tool and the [`libYARP_robotinterface` C++ library](https://github.com/robotology/yarp/tree/master/src/libYARP_robotinterface). \ No newline at end of file +The `gazebo_yarp_robotinterface` plugin permits to load several [YARP devices](http://www.yarp.it/git-master/note_devices.html) that can be attached to YARP devices +already opened by other Gazebo-YARP plugins using the same XML format used by the [`yarprobotinterface`](http://www.yarp.it/git-master/yarprobotinterface.html) tool and the [`libYARP_robotinterface` C++ library](https://github.com/robotology/yarp/tree/master/src/libYARP_robotinterface). + +## Usage + +### Add the plugin in the SDF model +The `gazebo_yarp_robotinterface` plugin can be used by including in any SDF model: +~~~xml + + + + + + + + + + + model://RobotInterfaceConfigurationFile.xml + + +~~~ + +**Warning: the `gazebo_yarp_robotinterface` plugin is only able to be attached to YARP devices that have been already created once the `gazebo_yarp_robotinterface` plugin has been spawned, so it is a good practice to always include it as last tag in a model.** + +### Example of the robotinterface XML file + +The file specified in `yarpRobotInterfaceConfigurationFile` is a XML file specified according to the `yarprobotinterface` format, for example: +~~~xml + + + + + + + + + 10 + this_is_a_string/param> + + + + + + yarp_device_name_of_device_to_which_to_attach + + + + + + + +~~~ + + +### How to specify existing YARP devices to which to attach + +The main use of the `gazebo_yarp_robotinterface` plugin is to spawn YARP devices that are **attached** to YARP devices that have been already spawned by other `gazebo-yarp-plugins`. For this reason, it is necessary to have a way to specify to which YARP devices a device spawned by `gazebo_yarp_robotinterface` is attached, i.e. the values of each element in the `` list under the `` element. In this content, we call this "device instance identified" as **YARP device instance name**, as for devices spawned by the XML of robotinterface, this is specified by the `name` attribute of the `device` tag. It is important not to confuse this with the **YARP device type name**, that is instead the name that identifies the type of plugin that is spawned, i.e. the `type` attribute of the `device` tag. + +The `gazebo_yarp_robotinterface` can be attached to any YARP device created by any plugin inside the model, or in any plugin contained in any nested sensor or model. + +For historic reason, not all the `gazebo-yarp-plugins` support specifying the **YARP device instance name** for the device that they spawn to permit to use them with the `gazebo_yarp_robotinterface` plugin. If you need to have this functionality in a specific plugin, feel free to open an issue. + +**Warning: as the YARP device instance name is specified without any specific Gazebo model or sensor namespace, it is important to use the `gazebo_yarp_robotinterface` plugin that all the YARP devices contained in the model have a unique YARP device instance name. If this is not the case, the plugin will print a clear error and exit without starting.** + +The plugins that spawn YARP devices in a way that they can be then attached to the yarprobotinterface as specified in the following table, together with the details with which the **YARP device instance name** can be specified: + +| Plugin | Details | +|:----------:|:----------------------------------------------------:| +| `gazebo_yarp_controlboard` | This plugin can create multiple YARP devices that expose joint-level motor and control interfaces such as [`yarp::dev::IPositionControl`](https://www.yarp.it/git-master/classyarp_1_1dev_1_1IPositionControl.html), [`yarp::dev::ITorqueControl`](https://www.yarp.it/git-master/classyarp_1_1dev_1_1ITorqueControl.html) and [`yarp::dev::ITorqueControl`](https://www.yarp.it/git-master/classyarp_1_1dev_1_1IEncoders.html). For this plugin, the **YARP device instance name** for each created device is specified with the `networks` parameter list in the plugin configuration. | +| `gazebo_yarp_depthcamera` | This plugin can create a YARP device that expose a depth-camera interface. For this plugin, the **YARP device instance name** can be specified by the `yarpDeviceName` parameter in the plugin configuration. | +| `gazebo_yarp_lasersensor` | This plugin can create a YARP device that expose a laser-seensor interface. For this plugin, the **YARP device instance name** can be specified by the `yarpDeviceName` parameter in the plugin configuration. | +| `gazebo_yarp_doublelaser` | This plugin can create a YARP device network wrapper server that expose two existing laser sensors. For this plugin, the **YARP device instance name** can be specified by the `yarpDeviceName` parameter in the plugin configuration. | + + + + + +