diff --git a/docs/icub-ergocub_ros2/index.md b/docs/icub-ergocub_ros2/index.md new file mode 100644 index 000000000..a6250ffee --- /dev/null +++ b/docs/icub-ergocub_ros2/index.md @@ -0,0 +1,64 @@ +# Using `iCub` and `ergoCub` with ROS 2 + +!!! note + We illustrate in this documentation how to control `iCub` and `ergoCub` **physical robots** using ROS 2 (simulation models are not covered). + +!!! 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) ROS 1 support was deprecated. + +## Overwiew + +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-ROS 2 compatibility. The devices are in the form of NWS/NWC that read/write information from/to ROS 2 topics and make them available via the YARP API. Starting from the distro [`v2024.11.1`](../sw_versioning_table/2024.11.1.md), the devices can be built with `robotology-superbuild` by enabling the `ROBOTOLOGY_USES_ROS2` CMake option. + +## Publishing `iCub/ergoCub`'s joints state: the `controlBoard_nws_ros2` module + +### Modules description + +`controlBoard_nws_ros2` is the controlBoard network wrapper server for ROS 2. As per the `controlBoard_nws_yarp`, this device publishes the joint position information on ROS 2 topics instead of YARP ports. The device uses the [yarpDeviceParamParserGenerator](https://yarp.it/latest/group__yarpDeviceParamParserGenerator.html) with its list of [required parameters](https://yarp.it/latest/classControlBoard__nws__ros2__ParamsParser.html). + +### Using `controlBoard_nws_ros2` + +The NWS/NWC for YARP and ROS 2 are organized into separate wrappers. In this way, it is possible to attach multiple wrappers to the same device (`controlBoard_nws_yarp` for YARP, `controlBoard_nws_ros2` for ROS 2) and include them to the same configuration file used to launch the `yarprobotinterface`. + +#### ergoCub + +All ergoCub robots have the configuration files to enable this module under [robots-configuration](https://github.com/robotology/robots-configuration) repository. To activate them, run the `yarprobotinterface` with the following option: + +```sh +yarprobotinterface --enable_tags "(enable_ros2)" +``` + +#### iCub + +For iCub robots, instead, the module can be activated using an `xml` file, for example this `alljoints-mc_nws_ros2.xml`: + +```xml + + + + + icub_cb_node + /joint_states + + alljoints-mc_remapper + + + +``` + +!!! warning + Not all iCub configuration files have been modified to support ROS 2. If you didn't find those files within your robot name folder under `robots-configuration`, please don't hesitate to file an [issue](https://github.com/robotology/robots-configuration/issues). + +With this kind of file, the positions of all the joints specified in the `alljoints-mc_remapper` are published on the `/joint_states` ROS 2 topic. + +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 launched devices, you have to modify the `icub_all.xml` (or any file that is launched with your `yarprobotinterface`) to include the line: + +```xml + +``` + +## xcub-moveit2 + +[`xcub-moveit2`](https://github.com/icub-tech-iit/xcub-moveit2) contains ROS 2 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. diff --git a/docs/icub_ros/index.md b/docs/icub_ros/index.md deleted file mode 100644 index a770f9b92..000000000 --- a/docs/icub_ros/index.md +++ /dev/null @@ -1,40 +0,0 @@ -# Using `iCub` with ROS -This page centralises different resources showing how to control `iCub` using ROS. - -!!! warning - At the moment we support ROS 1 only. - -## Required setup -Make sure that you read [YARP's documentation about ROS](https://yarp.it/latest/group__nws__and__nwc__architecture.html#autotoc_md58). - -## Using ROS TF to manage the coordinate transforms - -### What is ROS TF? -[ROS TF2](http://wiki.ros.org/tf2) is a package used to keep track of the different sets of coordinates in a robot, and easily switch between them. It can for instance be used to transform the coordinates of an object in `iCub`'s depth image to coordinates that can be used by the `cartesianInterface`. - -To keep track of the various sets of coordinates, ROS TF requires 2 things: -- a `URDF` file that describes the physical properties and the structure of all the pieces ("links") that make up the robot. This can be found in [the icub-model repository](https://github.com/robotology/icub-models/) -- something to periodically publish the state of all the joints (in `iCub`'s case, that means the angles that all the motors are currently at). This is provided by the `controlboardwrapper2` or `controlBoard_nws_ros` modules. - -## Publishing `iCub`'s joints state: the `controlboardwrapper2` and `controlBoard_nws_ros` modules - -### Modules description -The piece of software that can be used to publish the joint position information exposed by a YARP device for YARP <= 3.4 (so for any robotology distro <= 2021.08) is the `controlboardwrapper2` (see [this page](http://www.yarp.it/v3.4/classControlBoardWrapper.html#details)). This is exactly the same device used to publish joint information on YARP ports, but that can be configured also to publish on ROS topics via the ROS group. - -However, notice that `controlboardwrapper2` device is deprecated in the new YARP 3.5 relese (that will be use in robotology distros from >= 2021.11), and its functionality is going to be replaced by middleware-specific devices. In particular [`controlBoard_nws_yarp`](http://www.yarp.it/v3.5/classControlBoard__nws__yarp.html) for YARP, [`controlBoard_nws_ros`](http://www.yarp.it/v3.5/classControlBoard__nws__ros.html) for ROS(1) and [`controlBoard_nws_ros2`](https://github.com/robotology-playground/yarp-ros2/tree/master/src/devices/controlBoard_nws_ros2) for ROS2 (still unreleased work in progress). See [this page](https://yarp.it/latest/group__nws__and__nwc__architecture.html) and [this issue](https://github.com/robotology/yarp/discussions/2441) for architecture details on the changes in YARP 3.5 . - -### Using `controlboardwrapper2` -The module can be activated using an `xml` file such as [`icub_ros_wrapper.xml`](https://github.com/robotology/robots-configuration/blob/v1.21.0/iCubLondon01/wrappers/motorControl/icub_ros_wrapper.xml). In general all the `xml` configuration files related to YARP devices are only meant to be used by applications that use the `libYARP_robotinterface` YARP library, i.e. either the `yarprobotinteface` tool (unfortunaly docs are missing for this tool, see [this issue](https://github.com/robotology/yarp/issues/870)) or the `gazebo_yarp_robotinterface` Gazebo plugin. - -More in particular, the `icub_ros_wrapper.xml` 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 `icub_all.xml` (or any file that is launched with your `yarprobotinterface` when you launch the iCub) to include the line: - -```xml - -``` -see for example [this file](https://github.com/robotology/robots-configuration/blob/v1.21.0/iCubGenova04/icub_wbd.xml#L120). - -If this does not work, there may be two main pitfalls to be aware of: - -To make sure that the `controlboardwrapper2` is able to publish correctly on ROS, you need to make the `yarpserver` aware of the ROS name server, as described in the `Required setup` section. This can be done in several ways, but the most common way is to launch `yarpserver` with the `--ros` option (after making sure that `ROS_MASTER_URI` is set on the machine in which you launch `yarpserver --ros`). - -The joint values are read directly via `C++` YARP devices interfaces from the `controlboard` YARP devices, and which devices are connected to the `controlboardwrapper2` devices are specified in the child elements of the `` tag (see [this line](https://github.com/robotology/robots-configuration/blob/v1.21.0/iCubLondon01/wrappers/motorControl/icub_ros_wrapper.xml#L25)). In particular, the value of each `elem` tag (such as `head_mc` in ` head_mc `) should correspond to a device instantance name instantiated earlier by the `yarprobotinterface`. For example, `head_mc` corresponds to the instance created by [this file](https://github.com/robotology/robots-configuration/blob/v1.21.0/iCubLondon01/hardware/motorControl/icub_head.xml#L4). If some devices are not found, it is possible that some of this names need to be fixed. diff --git a/docs/icub_sw.md b/docs/icub_sw.md index 68d6fa23e..67aaba185 100644 --- a/docs/icub_sw.md +++ b/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 or ergoCub with ROS 2`](./icub-ergocub_ros2/index.md) - [`iCub Force Control`](./icub_force_control/icub-force-control.md) - [`Sensor Interfaces`](./robot_sensors/index.md) - [`Tactile Sensors`](./tactile_sensors/index.md) diff --git a/mkdocs.yml b/mkdocs.yml index aa9bd2df5..16a30b614 100644 --- a/mkdocs.yml +++ b/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 or ergoCub with ROS 2: icub-ergocub_ros2/index.md - iCub Force Control: icub_force_control/icub-force-control.md - Sensor interfaces: - Summary: robot_sensors/index.md