Add ROS2 documentation #379

martinaxgloria · 2024-12-13T15:05:37Z

This PR aims to:

Remove the documentation about the ROS1 support (deprecated);
Add the documentation about the ROS2 support based on what was documented previously (I added an admonition at the top of the page, saying that we are not supporting ROS1 anymore) and a brief paragraph with the xcub-moveit2 link to the documentation.

traversaro · 2024-12-13T15:07:56Z

docs/icub-ergocub_ros2/index.md

+    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).


I am not sure this link is particularly useful, what do you think?

I would get rid of it.

traversaro · 2024-12-13T15:08:14Z

docs/icub-ergocub_ros2/index.md

+
+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 .


Suggested change

`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 .

`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 can be compiled within the robotology-superbuild by enabling the `ROBOTOLOGY_USES_ROS2` CMake option .

traversaro · 2024-12-13T15:09:41Z

Style comment: unless used in code, the suggested spelling is ROS 2, not ROS2 (see https://shouldiputaspacebetweenrosand2.com/).

docs/icub-ergocub_ros2/index.md

traversaro · 2024-12-13T15:12:03Z

docs/icub-ergocub_ros2/index.md

+
+### 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.


Suggested change

`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.

`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.

If we keep YARP devices names with fixed font, we can do it consistently.

traversaro · 2024-12-13T15:26:04Z

docs/icub-ergocub_ros2/index.md

+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.


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 yarprobotinterface --enable_tags "(enable_ros2)", see robotology/robots-configuration#641 and robotology/robots-configuration#663 .

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?

traversaro · 2024-12-13T15:26:44Z

docs/icub_sw.md

@@ -15,7 +15,7 @@
 - [`Standard Calibration Types`](./robot_calibration_types/standard_calibration_types.md)
 - [`iCub 3 Calibration Types`](./robot_calibration_types/icub3_calibration_types.md)
 - [`Configure IP on a setup for ETH boards`](./configure_static_ip/configure-static-ip.md)
- [`Using iCub with ROS`](./icub_ros/index.md)
+- [`Using iCub/ergoCub with ROS2`](./icub-ergocub_ros2/index.md)


Suggested change

- [`Using iCub/ergoCub with ROS2`](./icub-ergocub_ros2/index.md)

- [`Using iCub or ergoCub with ROS2`](./icub-ergocub_ros2/index.md)

Nitpick, I think explicitly writing "or" is more readable.

traversaro · 2024-12-13T15:26:54Z

mkdocs.yml

@@ -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 with ROS: icub_ros/index.md
+      - Using iCub/ergoCub with ROS2: icub-ergocub_ros2/index.md


Suggested change

- Using iCub/ergoCub with ROS2: icub-ergocub_ros2/index.md

- Using iCub or ergoCub with ROS2: icub-ergocub_ros2/index.md

Nitpick, I think explicitly writing "or" is more readable.

traversaro · 2024-12-13T15:29:37Z

docs/icub-ergocub_ros2/index.md

+
+`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 .
+
+## Publishing `iCub/ergoCub`'s joints state: the `controlBoard_nws_ros2` module


Perhaps we should explain that this just applies to real robots, while we could have a different section for simulated robots?

Do you mean the entire documentation or a specific paragraph?

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.

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 controlBoard_nws_ros2 since in simulation it is required to modify the urdf for passing the proper XML to the yri plugin (cc @Nicogene)

The only difference between the two it's the usage of controlBoard_nws_ros2 since in simulation it is required to modify the urdf for passing the proper XML to the yri plugin (cc @Nicogene)

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.

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.

Yes they are not supported in gz-sim at the moment, any solution is fine for me.

martinaxgloria · 2024-12-16T16:36:00Z

I think I addressed the requested changes via 31775e4

pattacini · 2024-12-16T16:45:39Z

Thanks @martinaxgloria
I'll wait for @traversaro's final pass before proceeding.

pattacini

Fine by me!
I've pushed some inline mods to make it read a bit more smoothly.

A general comment when working with links: try to avoid attaching links to words like here or the like.

docs/icub-ergocub_ros2/index.md

pattacini · 2024-12-17T07:32:12Z

Hi @traversaro, if the PR looks good to you I'll be happy to merge it!

docs/icub-ergocub_ros2/index.md

traversaro · 2024-12-17T07:51:30Z

Sure, I had missed the sentence on real robots.

Add ros2 documentation

c604ee1

martinaxgloria requested a review from pattacini as a code owner December 13, 2024 15:05

martinaxgloria self-assigned this Dec 13, 2024

martinaxgloria requested review from traversaro and Nicogene December 13, 2024 15:05

traversaro reviewed Dec 13, 2024

View reviewed changes

docs/icub-ergocub_ros2/index.md Outdated Show resolved Hide resolved

traversaro reviewed Dec 13, 2024

View reviewed changes

martinaxgloria mentioned this pull request Dec 16, 2024

Update yarp-devices-ros2 installation documentation icub-tech-iit/xcub-moveit2#34

Merged

Address requested changes

31775e4

martinaxgloria force-pushed the feat/ros2_doc branch from 6765e5b to 31775e4 Compare December 16, 2024 16:34

martinaxgloria requested a review from traversaro December 16, 2024 16:35

pattacini approved these changes Dec 17, 2024

View reviewed changes

pattacini added 7 commits December 17, 2024 08:30

Update docs/icub-ergocub_ros2/index.md

eca3aea

Update docs/icub-ergocub_ros2/index.md

136c908

Update docs/icub-ergocub_ros2/index.md

786c957

Update docs/icub-ergocub_ros2/index.md

0206a3b

Update docs/icub-ergocub_ros2/index.md

8f109b1

Update docs/icub-ergocub_ros2/index.md

25c5476

Update docs/icub-ergocub_ros2/index.md

48a2e44

pattacini reviewed Dec 17, 2024

View reviewed changes

docs/icub-ergocub_ros2/index.md Outdated Show resolved Hide resolved

Update docs/icub-ergocub_ros2/index.md

7ef941d

traversaro approved these changes Dec 17, 2024

View reviewed changes

pattacini merged commit 52ba64e into icub-tech-iit:master Dec 17, 2024
1 check passed

martinaxgloria deleted the feat/ros2_doc branch December 17, 2024 08:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add ROS2 documentation #379

Add ROS2 documentation #379

martinaxgloria commented Dec 13, 2024

traversaro Dec 13, 2024

pattacini Dec 13, 2024

traversaro Dec 13, 2024

traversaro commented Dec 13, 2024

traversaro Dec 13, 2024

traversaro Dec 13, 2024

traversaro Dec 13, 2024 •

edited

Loading

traversaro Dec 13, 2024

traversaro Dec 13, 2024

traversaro Dec 13, 2024

martinaxgloria Dec 16, 2024

traversaro Dec 16, 2024

martinaxgloria Dec 16, 2024

traversaro Dec 16, 2024

martinaxgloria Dec 16, 2024

traversaro Dec 16, 2024

martinaxgloria commented Dec 16, 2024

pattacini commented Dec 16, 2024

pattacini left a comment

pattacini commented Dec 17, 2024

traversaro commented Dec 17, 2024


		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 .


		### 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.

	- [`Using iCub/ergoCub with ROS2`](./icub-ergocub_ros2/index.md)
	- [`Using iCub or ergoCub with ROS2`](./icub-ergocub_ros2/index.md)

	- Using iCub/ergoCub with ROS2: icub-ergocub_ros2/index.md
	- Using iCub or ergoCub with ROS2: icub-ergocub_ros2/index.md


		`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 .

		## Publishing `iCub/ergoCub`'s joints state: the `controlBoard_nws_ros2` module

Add ROS2 documentation #379

Add ROS2 documentation #379

Conversation

martinaxgloria commented Dec 13, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

traversaro commented Dec 13, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

traversaro Dec 13, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

martinaxgloria commented Dec 16, 2024

pattacini commented Dec 16, 2024

pattacini left a comment

Choose a reason for hiding this comment

pattacini commented Dec 17, 2024

traversaro commented Dec 17, 2024

traversaro Dec 13, 2024 •

edited

Loading