Skip to content

Networking documentation #129

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Parent: Reorg and Ros2 Humble
merged 6 commits into from
Jul 7, 2023
Merged

Networking documentation #129

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c2f3c80
Networking documentation
roni-kreinin Jul 6, 2023
a4bdb0e
Sensor links
roni-kreinin Jul 6, 2023
f167c83
Formatting
roni-kreinin Jul 6, 2023
7f40598
Upgrading to Humble
roni-kreinin Jul 6, 2023
61c6a76
Minor typo fixes
luis-camero Jul 7, 2023
5a2dab1
Merge branch 'ros2-humble' into rkreinin/networking
roni-kreinin Jul 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions docs/ros/api/mcu_api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@ toc_min_heading_level: 2
toc_max_heading_level: 4
---


## MCU topics

| Topic | Message type | Publisher | Description | QoS |
Expand All @@ -25,5 +24,3 @@ toc_max_heading_level: 4
| Service | Service type | Server | Description | QoS |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------------------------------------ | :------------- |
| platform/mcu/configure | [clearpath_platform_msgs/ConfigureMcu](https://github.com/clearpathrobotics/clearpath_msgs/blob/main/clearpath_platform_msgs/srv/ConfigureMcu.srv) | MCU node | Configure MCU domain ID and namespace | System default |


78 changes: 38 additions & 40 deletions docs/ros/api/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,31 +6,29 @@ toc_min_heading_level: 2
toc_max_heading_level: 4
---


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 {#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
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](https://docs.ros.org/en/humble/Concepts/About-Quality-of-Service-Settings.html).

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.
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
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
stored 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.
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](https://docs.ros.org/en/humble/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-compatibilities) 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 (CLI).
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
Expand All @@ -42,29 +40,29 @@ 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*
- **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.
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*
- **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
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.

Expand All @@ -74,25 +72,25 @@ Not all sensor drivers use this QoS profile. Always check the QoS profile before

#### Transient Local

* **History**: *Keep Last*
* **Depth**: *10*
* **Reliability**: *Reliable*
* **Durability**: *Transient Local*
* **Deadline**: *System Default*
* **Lifespan**: *System Default*
* **Liveliness**: *Automatic*
* **Lease Duration**: *System Default*
- **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
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, to differentiate them from another robot that
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.
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](../config/yaml) file.
will be `a200_0001`. This can be overwritten in the [robot.yaml](../config/yaml) file.
2 changes: 0 additions & 2 deletions docs/ros/api/platform_api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,5 +29,3 @@ toc_max_heading_level: 4
| tf_static | [tf2_msgs/TFMessage](https://github.com/ros2/geometry2/blob/humble/tf2_msgs/msg/TFMessage.msg) | Various nodes | Static link transforms | [Transient Local](overview#transient-local) |
| twist_marker_server/cmd_vel | [geometry_msgs/Twist](https://github.com/ros2/common_interfaces/blob/humble/geometry_msgs/msg/Twist.msg) | Twist Marker Server | Velocity commands from twist marker | [System Default](overview#system-default) |
| /rosout | [rcl_interfaces/Log](https://github.com/ros2/rcl_interfaces/blob/humble/rcl_interfaces/msg/Log.msg) | Various nodes | System Logs | [Transient Local](overview#transient-local) |


46 changes: 22 additions & 24 deletions docs/ros/api/sensors_api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,47 +6,45 @@ toc_min_heading_level: 2
toc_max_heading_level: 4
---


## 2D Lidar topics

| Topic | Message type | Description | QoS |
| :------------------------------ | :----------------------------------------------------------------------------------------------------------- | :-------------- | :---------------------------------------- |
| platform/sensors/lidar2d_#/scan | [sensor_msgs/LaserScan](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/LaserScan.msg) | Lidar scan data | [System Default](overview#system-default) |
| Topic | Message type | Description | QoS |
| :------------------------------- | :----------------------------------------------------------------------------------------------------------- | :-------------- | :---------------------------------------- |
| platform/sensors/lidar2d\_#/scan | [sensor_msgs/LaserScan](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/LaserScan.msg) | Lidar scan data | [System Default](overview#system-default) |

## 3D Lidar topics

| Topic | Message type | Description | QoS |
| :-------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :-------------------- | :---------------------------------------- |
| platform/sensors/lidar3d_#/points | [sensor_msgs/PointCloud2](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/PointCloud2.msg) | Lidar pointcloud data | [System Default](overview#system-default) |
| platform/sensors/lidar3d_#/scan | [sensor_msgs/LaserScan](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/LaserScan.msg) | Lidar scan data | [System Default](overview#system-default) |
| Topic | Message type | Description | QoS |
| :--------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :-------------------- | :---------------------------------------- |
| platform/sensors/lidar3d\_#/points | [sensor_msgs/PointCloud2](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/PointCloud2.msg) | Lidar pointcloud data | [System Default](overview#system-default) |
| platform/sensors/lidar3d\_#/scan | [sensor_msgs/LaserScan](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/LaserScan.msg) | Lidar scan data | [System Default](overview#system-default) |

## Camera topics

| Topic | Message type | Description | QoS |
| :------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :-------------- | :---------------------------------------- |
| platform/sensors/camera_#/color/image | [sensor_msgs/Image](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Image.msg) | Raw RGB image | [System Default](overview#system-default) |
| platform/sensors/camera_#/color/camera_info | [sensor_msgs/CameraInfo](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/CameraInfo.msg) | Camera Info | [System Default](overview#system-default) |
| platform/sensors/camera_#/depth/image | [sensor_msgs/Image](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Image.msg) | Raw depth image | [System Default](overview#system-default) |
| platform/sensors/camera_#/depth/camera_info | [sensor_msgs/CameraInfo](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/CameraInfo.msg) | Camera Info | [System Default](overview#system-default) |
| platform/sensors/camera_#/points | [sensor_msgs/PointCloud2](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/PointCloud2.msg) | Pointcloud data | [System Default](overview#system-default) |
| platform/sensors/camera_#/imu | [sensor_msgs/Imu](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Imu.msg) | IMU data | [System Default](overview#system-default) |
| platform/sensors/camera\_#/color/image | [sensor_msgs/Image](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Image.msg) | Raw RGB image | [System Default](overview#system-default) |
| platform/sensors/camera\_#/color/camera_info | [sensor_msgs/CameraInfo](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/CameraInfo.msg) | Camera Info | [System Default](overview#system-default) |
| platform/sensors/camera\_#/depth/image | [sensor_msgs/Image](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Image.msg) | Raw depth image | [System Default](overview#system-default) |
| platform/sensors/camera\_#/depth/camera_info | [sensor_msgs/CameraInfo](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/CameraInfo.msg) | Camera Info | [System Default](overview#system-default) |
| platform/sensors/camera\_#/points | [sensor_msgs/PointCloud2](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/PointCloud2.msg) | Pointcloud data | [System Default](overview#system-default) |
| platform/sensors/camera\_#/imu | [sensor_msgs/Imu](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Imu.msg) | IMU data | [System Default](overview#system-default) |

## IMU topics

| Topic | Message type | Description | QoS |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | :---------------------------------------- |
| platform/sensors/imu_#/data_raw | [sensor_msgs/Imu](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Imu.msg) | Raw IMU orientation, angular velocity, and linear acceleration data | [Sensor Data](overview#sensor-data) |
| platform/sensors/imu_#/data | [sensor_msgs/Imu](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Imu.msg) | Filtered IMU orientation, angular velocity, and linear acceleration data | [System Default](overview#system-default) |
| platform/sensors/imu_#/mag | [sensor_msgs/MagneticField](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/MagneticField.msg) | IMU magnetic field data | [System Default](overview#system-default) |
| Topic | Message type | Description | QoS |
| :------------------------------- | :------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | :---------------------------------------- |
| platform/sensors/imu\_#/data_raw | [sensor_msgs/Imu](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Imu.msg) | Raw IMU orientation, angular velocity, and linear acceleration data | [Sensor Data](overview#sensor-data) |
| platform/sensors/imu\_#/data | [sensor_msgs/Imu](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Imu.msg) | Filtered IMU orientation, angular velocity, and linear acceleration data | [System Default](overview#system-default) |
| platform/sensors/imu\_#/mag | [sensor_msgs/MagneticField](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/MagneticField.msg) | IMU magnetic field data | [System Default](overview#system-default) |

## GPS topics

| Topic | Message type | Description | QoS |
| :------------------------- | :----------------------------------------------------------------------------------------------------------- | :--------------------- | :---------------------------------------- |
| platform/sensors/gps_#/fix | [sensor_msgs/NavSatFix](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/NavSatFix.msg) | Navsat Fix information | [System Default](overview#system-default) |

| Topic | Message type | Description | QoS |
| :-------------------------- | :----------------------------------------------------------------------------------------------------------- | :--------------------- | :---------------------------------------- |
| platform/sensors/gps\_#/fix | [sensor_msgs/NavSatFix](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/NavSatFix.msg) | Navsat Fix information | [System Default](overview#system-default) |

:::note
The '#' in the topic represents the index of the sensor. Indexing begins at 0 and will increment for
each new sensor of that type that is added. Internal sensors such as IMU's will be indexed first.
:::
:::
Loading