Add ROS2 documentation #379
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,50 @@ | ||||||
| # Using `iCub` and `ergoCub` with ROS2 | ||||||
| This page centralises different resources showing how to control `iCub` and `ergoCub` using ROS2. | ||||||
|
|
||||||
| !!! info | ||||||
| As the last supported **ROS 1** distribution (ROS Noetic Ninjemys) is reaching its End of Life (EOL) on May 2025, with the distro release [`v2024.11.1`](../sw_versioning_table/2024.11.1.md) ROS1 support was deprecated. | ||||||
|
|
||||||
| ## Overwiew | ||||||
| Make sure that you read [YARP's documentation about ROS](https://yarp.it/latest/group__nws__and__nwc__architecture.html#autotoc_md58). | ||||||
|
|
||||||
| All the YARP [Network Wrapper Server (NWS) and Network Wrapper Client (NWC)](https://www.yarp.it/latest//group__nws__and__nwc__architecture.html) devices that use ROS 2 can be found under [`yarp-devices-ros2`](https://github.com/robotology/yarp-devices-ros2) repository. | ||||||
|
|
||||||
| `yarp-devices-ros2` contains the devices and utilities for YARP-ROS2 compatibility. The devices are in the form of NWS/NWC that read and/or write information from ROS2 topics and make them available via the YARP API. Starting from the distro [`v2024.11.1`](../sw_versioning_table/2024.11.1.md), it could be compiled within the robotology-superbuild by enabling the `ROBOTOLOGY_USES_ROS2` CMake option . | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ## Publishing `iCub/ergoCub`'s joints state: the `controlBoard_nws_ros2` module | ||||||
|
There was a problem hiding this comment. Perhaps we should explain that this just applies to real robots, while we could have a different section for simulated robots? There was a problem hiding this comment. Do you mean the entire documentation or a specific paragraph? There was a problem hiding this comment. At least the paragraph it seems to me that it only applies to real robot, right? I am not sure about the rest of the documentation, but if also the rest it does only apply to real robots and not simulated ones, I think it may be worth mentioning it. There was a problem hiding this comment. Maybe I'm wrong, but after reading the entire page I added it seems that it could be applied to both real and simulated robots. The only difference between the two it's the usage of There was a problem hiding this comment.
Exactly. I may be wrong, but I am not sure this is step that is obvious for the target reader of this documentation (for example, I am afraid it would not be obvious that how "yarprobotinterface --enable_tags "(enable_ros2)" needs to be translated in the case of simulated robots, see also robotology/gz-sim-yarp-plugins#163 . So either we document this, or we just clearly state that the documentation is just targeting real robots. There was a problem hiding this comment. As far as I understand, the enable/disable_tags are not available for simulation models yet (correct me if I'm wrong). If it's so, I prefer to specify that the documentation refers to the real robots. There was a problem hiding this comment. Yes they are not supported in gz-sim at the moment, any solution is fine for me. |
||||||
|
|
||||||
| ### Modules description | ||||||
|
|
||||||
| `controlBoard_nws_ros2` is the controlBoard network wrapper server for ROS2. As per the controlBoard_nws_yarp, this device can be used to publish the joint position information on ROS2 topics instead of YARP ports. The device uses the [yarpDeviceParamParserGenerator](https://yarp.it/latest/group__yarpDeviceParamParserGenerator.html) and [here](https://yarp.it/latest/classControlBoard__nws__ros2__ParamsParser.html) there is the list of the required parameters. | ||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. If we keep YARP devices names with |
||||||
|
|
||||||
| ### Using `controlBoard_nws_ros2` | ||||||
|
|
||||||
| The module can be activated using an `xml` file, for example this `alljoints-mc_nws_ros2.xml`: | ||||||
|
|
||||||
| ```xml | ||||||
| <?xml version="1.0" encoding="UTF-8"?> | ||||||
| <!DOCTYPE devices PUBLIC "-//YARP//DTD yarprobotinterface 3.0//EN" "http://www.yarp.it/DTD/yarprobotinterfaceV3.0.dtd"> | ||||||
|
|
||||||
| <device xmlns:xi="http://www.w3.org/2001/XInclude" name="alljoints-mc_nws_ros2" type="controlBoard_nws_ros2"> | ||||||
| <param name="node_name"> ergocub_cb_node </param> | ||||||
| <param name="topic_name"> /joint_states </param> | ||||||
| <action phase="startup" level="15" type="attach"> | ||||||
| <param name="device"> alljoints-mc_remapper </param> | ||||||
| </action> | ||||||
| <action phase="shutdown" level="20" type="detach" /> | ||||||
| </device> | ||||||
| ``` | ||||||
|
|
||||||
| With this kind of file, the positions of all the joints specified in the `alljoints-mc_remapper` are published on the `/joint_states` ROS2 topic. | ||||||
|
|
||||||
| More in particular, this file is meant to be used as part of the same `yarprobotinterface` with which you launch the robot. To include it among the devices that you launch with it, you should modify the `ergocub_all.xml`/`icub_all.xml` (or any file that is launched with your `yarprobotinterface` when you launch the robot) to include the line: | ||||||
|
|
||||||
| ```xml | ||||||
| <xi:include href="wrappers/motorControl/alljoints-mc_nws_ros2.xml" /> | ||||||
| ``` | ||||||
|
|
||||||
| Moreover, the NWS/NWC for YARP and ROS2 are organized into separate wrappers. In this way, it is possible to attach multiple wrappers to the same device, so a `controlBoard_nws_yarp` for YARP and a `controlBoard_nws_ros2` for ROS2, and include them to the same configuration file used to launch the yarprobotinterface. | ||||||
|
There was a problem hiding this comment. At least for ergocub, I think this section may be confusing. All ergoCub robots already have this files defined in their configuration files, so what users needs to do is to run the yarprobotinterface of the robot with the option The situation is a bit different for iCub, where not all iCubs configuration files have been modified to support ROS 2 . Perhaps we can have two different sections, one for ergoCub and one for iCub, and the instructions on the in-detailed modifications of the conf files are just there for iCub? Perhaps we could also suggest users to open an issue in https://github.com/robotology/robots-configuration if they want to use their iCub robots with ROS 2, so that we can direct them in contributing their modified files to the main repo instead of keeping their configuration files forked? |
||||||
|
|
||||||
| ## xcub-moveit2 | ||||||
|
|
||||||
| [`xcub-moveit2`](https://github.com/icub-tech-iit/xcub-moveit2) contains ROS2 packages to control a YARP-based robot (iCub/ergoCub) with MoveIt2 platform. Check it out [here](https://github.com/icub-tech-iit/xcub-moveit2/blob/master/README.md) for more details. | ||||||
traversaro marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -301,7 +301,7 @@ nav: | |||||
| - Encoders and Joint limits (manual): icub_testing/encoders_manual.md | ||||||
| - Configure IP on a setup for ETH boards: | ||||||
| - Configure IP on a setup for ETH boards: configure_static_ip/configure-static-ip.md | ||||||
| - Using iCub/ergoCub with ROS2: icub-ergocub_ros2/index.md | ||||||
|
There was a problem hiding this comment.
Suggested change
Nitpick, I think explicitly writing "or" is more readable. |
||||||
| - iCub Force Control: icub_force_control/icub-force-control.md | ||||||
| - Sensor interfaces: | ||||||
| - Summary: robot_sensors/index.md | ||||||
|
|
||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I am not sure this link is particularly useful, what do you think?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would get rid of it.