|
|
|
|
|
|
|
|
Set up ROS 2 communication with the robot#
🏁 Goal of this guide
By the end of this guide, you will know how to set up ROS 2 communication between your developer computer and the robot using the PAL Connection CLI.
Pre-requisites#
Ensure that you have followed the steps to setup the PAL OS Docker image (Developing with the PAL Developer Docker image).
Establish a ROS 2 connection with the robot#
In ROS 2 it is possible to set up remote communication between a robot and the PAL OS Docker image (or another development environment). For this communication to be successful, the only requirement is that the robot and the development computer have an IP route between them (this can be easily checked with a standard ping command), either by cable or wireless. This is normally achieved by connecting them to the same network, but depending on your network configuration, it may also be possible to set up communication through different subnets and even through a VPN. It only depends on the configuration of the routers you are using for communication.
For more details on network configuration of the robot see the section Network configuration.
Cyclone DDS is the default RMW in ROS 2 Humble. In its default config, it will use multicast for discovery, making it unreliable in almost all network configurations. To avoid this, a custom configuration has been created for both the PAL OS Docker image and robots. This configuration sets up explicit peer-to-peer discovery using unicast traffic. The PAL Connection CLI is used to connect to a robot. This page will go through the different steps to ensure the configuration is set up correctly.
Container setup#
The necessary config is installed by default in the PAL OS Docker image, so every newly created docker container will have all you need to connect to your robot.
However, in case the packages are not installed, they can be installed with the following command:
sudo apt update
sudo apt install pal-alum-cyclone-dev-cfg pal-alum-pal-connection-cli
The new Cyclone config ensures all DDS traffic is contained to localhost by default for safety reasons. You should not see any changes to the behavior of ROS 2 inside the container.
Robot setup#
All the robots come with the Cyclone Robot Config already preinstalled. Please make sure the robot is up to date before proceeding. To ensure that, you can simply execute inside the robot:
sudo apt update
sudo apt upgrade
This configuration works in all the possible connection modes of the robot:
Direct cable: the PC is on the laptop tray connected to any of the robot Ethernet ports.
Hotspot: the robot was configured to generate its own wifi network (as explained in Network configuration) and the PC is connected to it.
Using your network infrastructure: in this setup, the robot and your development PC are connected through Wifi or Ethernet to your network. In this scenario, both will have an assigned IP, as if they were normal computers. Please take into account there is no need for them to be connected in the same way. For example, the PC may be connected through Ethernet and the Robot through wifi. The only consideration is that they must be able to ping each other, as explained above.
IMPORTANT: Without using the PAL Connection CLI, the topics are not accessible from outside the robot even if you set the same ROS_DOMAIN_ID in the development PC. If you haven’t configured properly your container, you will be unable to see any topics! This will be the case even if you are directly plugged into the robot. This is not the default behavior of ROS 2 Humble that you may find in the documentation, so please be extremely mindful when changing connection settings and always refer to this documentation.
Connect to the robot#
To connect to a robot use the PAL Connection CLI from inside a PAL OS Docker image.
pal connection start [robot_address] [network_interface] [ros_domain_id]
All the arguments are optional, meaning the CLI will ask for them when needed
and properly fail or give warning on incorrect input. You can pass directly the
arguments you already know to avoid being prompted for them, but they must be
provided in the order you see above. For example, you can provide only the robot
address and you will be prompted for the remaining arguments, but you cannot provide
only the ROS_DOMAIN_ID.
Important
At the moment the PAL connection CLI is not compatible with Ubuntu 24. Please use the steps in section PAL Connection Script to connect to the robot.
The CLI tool makes Cyclone DDS connection deterministic, meaning that if it doesn’t fail, a successful connection is always established.
The arguments that the CLI is expecting are:
robot_address: The IP address or the DNS-solvable hostname of the robot.The hostname must be resolvable from your development environment, which depends on the network DNS configuration. If you haven’t configured explicitly the DNS to handle this, you probably should use the IP of the robot directly.
network_interface: The specific network interface to use for the connection. You can check all the interfaces withip a.Please note that you have to choose the network interface that has connectivity with the robot. Check if you are connected to the network through cable or wifi and adapt the interface accordingly. Typically, the wifi interface is called something like
wlan0orwlo1and the cable interface likeenp3s0. In case you are in doubt, you can simply leave it blank and the CLI will choose the fastest interface automatically.The connection script will ensure that the robot is reachable by the hostname or IP you specified through the selected interface. If you receive an error message like:
[ERROR] - There is no connectivity to [robot_address] through [network_interface]
Please check the robot is on and properly connected to the network. This error means that your PC is unable to ping the robot.
ros_domain_id: TheROS_DOMAIN_IDthe robot is currently using. The CLI will automatically check if this is the ID that the nodes in the robot are indeed using. If that not the case, you will get an error like:[WARNING] - There is not any ROS 2 node in [robot_address] using ROS_DOMAIN_ID=[ros_domain_id]. No topics will be visible
This means that there isn’t any node in the robot using the
ROS_DOMAIN_IDyou specified. This is only a warning because it could also mean that the nodes of the robot are stopped (maybe the robot is still booting up) and the connection would work upon starting them.If after ensuring there are nodes running in the robot you still get this error (and thus the topic list is empty), please check the
ROS_DOMAIN_IDunder/etc/ros_domain_idin the robot.
After a successful connection the terminal should look like the image below.
This means a Cyclone connection has been successfully established with your robot.
You can now for example see the topics in your development environment with ros2 topic list.
Important
The script ensures a connection that is specific to this bash session. If you want to see the topics in another bash session, the connection script has to be run again in the new session.
Important
Please ensure ROS_LOCALHOST_ONLY environment variable is NOT set, especially that it is
not in your .bashrc file. Everything is handled by the config package
and this environment variable can lead to connection and simulation issues.
Disconnecting from the robot#
To disconnect from the robot, you can simply run exit in the bash session where you ran
the connection CLI. This will stop the Cyclone connection and you will no longer be able to
see the topics.
PAL Connection Script#
The PAL Connection CLI is a wrapper around the PAL connection script. The connection script can be run directly with the ROS 2 command below. This is useful when using Ubuntu 24 as this is not supported yet by the Connection CLI.
ros2 run cyclone_dev_cfg pal_connect.sh [network_interface] [robot_address]
Once the connection is established please ensure the ROS_DOMAIN_ID is set correctly.
Troubleshooting#
Check that you can ping the robot:
ping <your_robot_ip>If the ping is unsuccessful, please check the robot IP on the robot using
ip a. You should be able to see an IP under the appropriate network interface (normally,wlan0). Note down that IP, and try to ping it again from your development environment.If the normal ping was successful but you cannot yet see the topics, you can try a DDS ping:
On the robot:
ddsperf sanityOn the development environment:
ddsperf sanity
If you don’t see a connection being established, but the normal ping was successful, please ensure the configuration packages are properly installed. Also, ensure the environment variable
ROS_LOCALHOST_ONLYis not set, as it can interfere with the connection script. You can unset it with:unset ROS_LOCALHOST_ONLY. Ensure it is not being set in your.bashrcfile.If you still cannot see a successful DDS ping, ensure the robot is using the appropriate network interface for DDS communication. You can view and edit it by executing
sudo vim $CYCLONEDDS_URIon the robot and assigning the highest priority to the needed interface. Generally, there are two cases:Direct connection through cable: Disable WiFi on the robot using
sudo ip link set wlan0 downor change the br0 to have the highest priority.WiFi: This should work out of the box, both through hotspot and over the network (including using VPN). However, if the WiFi connection is not fast enough, topics may take a while (even up to 1 minute) to appear.
If a connection was established (you were able to see a DDS discovery in both the robot and your PC), but you still don’t see the topics, the issue might be that the
ROS_DOMAIN_IDis not matching.If a connection was established (you were able to see a DDS discovery in both the robot and your PC), but you still don’t see the topics after a little while, you can try stopping the ROS 2 daemon:
ros2 daemon stop.If during the use of the PAL Connection CLI you get a permission error, it might be the case that you are using Ubuntu 24. This is a known issue and you can use the steps in section PAL Connection Script to connect to the robot.