ROS 2 Robot API

The ROS 2 API is a standard naming scheme for ROS 2 topics and services. Every supported Clearpath robot uses this API, making it easy to use the robots interchangeably.

QoS Profiles

Topics and services in ROS 2 use Quality of Service (QoS) profiles to change communication policies. The QoS profile of a topic or service has several policies such as history, depth, reliability, durability, and more. For more details on QoS settings, visit the ROS 2 documentation.

For Clearpath platforms, the main policies that may change between different topics and services are reliability and durability. For reliability there are two options: Best Effort, and Reliable. A Best Effort reliability suggests that an attempt will be made to publish the data, but if the network is not robust then the data may be lost. On the other hand, Reliable guarantees that the data will be received. This may require that the data be sent multiple times.

The durability of a QoS profile can be either Transient Local or Volatile. Transient Local means that data for published messages will be stored by the publisher even after it has been published. A new subscriber will receive the data even if a lot of time has passed since it was originally published. This durability is typically used for data that only needs to be published once, such as the robot description. The other durability policy is Volatile which does not store old messages. The messages are published and only active subscribers will receive the data. New subscribers will have to wait for the next message to be published. Most topics will use a Volatile durability policy.

It is important to check for QoS compatibility when interacting with ROS 2. Mixing of QoS policies when publishing or subscribing to topics can lead to incompatibility. For example, subscribing to a Best Effort publisher with a Reliable subscriber is not compatible and will result in no data being received on the subscriber. The easiest way to check the QoS profile of a topic is to use the ROS 2 command line interface.

ros2 topic info /topic_name -v

Common QoS profiles

The following are some common QoS profiles used by Clearpath platforms.

System Default

• History: Keep Last
• Depth: 10
• Reliability: Reliable
• Durability: Volatile
• Deadline: System Default
• Lifespan: System Default
• Liveliness: Automatic
• Lease Duration: System Default

The System Default QoS profile is the most common profile used by most topics.

Sensor Data

• History: Keep Last
• Depth: 5
• Reliability: Best Effort
• Durability: Volatile
• Deadline: System Default
• Lifespan: System Default
• Liveliness: Automatic
• Lease Duration: System Default

The Sensor Data QoS Profile uses a Best Effort reliability to send the latest data as soon as possible, without bothering to resend data that was not received. This is mostly used by the MCU and sensor drivers.

note

Not all sensor drivers use this QoS profile. Always check the QoS profile before trying to subscribe to the topic.

Transient Local

• History: Keep Last
• Depth: 10
• Reliability: Reliable
• Durability: Transient Local
• Deadline: System Default
• Lifespan: System Default
• Liveliness: Automatic
• Lease Duration: System Default

The Transient Local QoS Profile offers a Transient Local durability, and is typically used by topics that only want to send messages once. For Clearpath platforms, this includes the robot description topic and the /rosout topic which offers system logs.

Namespacing

Namespacing is the method of adding a prefix to a robot's nodes and topics; this helps differentiate them from another robot that may be on the same network. For example, every robot will have a cmd_vel topic for commanding velocity. If both robots used the same topic, then they would both drive when a message is published to that topic. By namespacing, we can remap the topic to robot1/cmd_vel and robot2/cmd_vel for each respective robot.

By default, the namespace of the robot will be obtained from the serial number of the robot. If your serial number is cpr-a200-0001, then your namespace will be a200_0001. This can be overwritten in the robot.yaml file.