ROS2

To get started with our integrations with ROS and Foxglove, ensure you have followed all the instructions on the Installation page page and have the following:

• A computer running Linux Ubuntu 22.04 and installed:
  • ROS2 Humble
  • Calyo SENSUS ROS
  • Calyo SENSUS 3RDPARTY

On the computer, you have installed ROS2 and the Calyo packages. Complete the following:

First source your ROS2 installation:

source /opt/ros/<ros-version>/setup.bash

Once you have installed the packages and sourced the ROS2 installation, you will have the calyosensus_ros (or calyosensus_ros_cuda) package available. To check this, run:

Check calyosensus ros packages installed

ros2 pkg list | grep calyosensus

This should return the relevant calyosensus_ros package for your system:

calyosensus_ros

Following the ROS convention, the calyosensus_ros node can be configured to run either as a 'talker' or a 'listener'. This is determined solely based on the reader type of the pipelines in the configuration file. If the reader type is RosReader, the node will launch as a listener, meaning that it will wait to receive messages on a certain topic over the ROS network. If the reader is any other type, but the writer is RosWriter, the node will begin generating data according to the pipeline in the configuration file and publish it to a certain topic over the ROS network.

Launching the node always involves the following command:

Launching the ros node

ros2 launch calyosensus_ros run_with_config.launch.py sensus_config:=<your-config-file.yaml>

Talker

To make a simple 'talker' application, we need to create a config file that specifies the Writer to be a "RosWriter".

Example talker config

type: calyosensus
pipelines:
  - id: raw_signal_capture
    reader:
      type: DeviceReader
      serial_number: any
      num_cycles: 10
      max_distance: 8.0
    writer:
      type: RosWriter
      topic_name: calyo_raw_data
      frame_id: calyo_frame
    processor:
      type:
        # no processing, just transmit raw data
        stage: passthrough

In this example, we set up a reader of type "DeviceReader" to stream live data from a connected sensor, and we chose "RosWriter" so that we can publish the raw data over ROS. To run it in a terminal:

Run the talker example

ros2 launch calyosensus_ros run_with_config.launch.py sensus_config:=./talker-example.yaml

In another terminal, check that data is being published using the ROS CLI:

Test the publisher

ros2 topic list # should see 'calyo_raw_data'
ros2 topic echo /calyo_raw_data # should see realtime data being streamed 

Listener

To create a 'listener' application, we need to create a config file that, this time, specifies the Reader to be a "RosReader".

Example listener config

type: calyosensus
pipelines:
  - id: raw_signal_capture
    reader:
      type: RosReader
      topic_name: calyo_raw_data
    writer:
      type: RosWriter
      topic_name: calyo_pointcloud
      frame_id: calyo_frame
    processor:
      type:
        stage: pointcloud_generation
        imaging_options:
          dimensions: 3
          algorithm: resolution

In this example, we set up the 'RosReader' with the same topic name as was being published before. This means that we effectively have two instances of the sensus software, one publishing the data from a live stream of a connected sensor, and the other receiving the data, applying some processing (generating 3-D point clouds), and publishing the result to a new topic "calyo_pointcloud". This demonstrates how the ROS2 ecosystem can be leveraged to deploy SENSUS on a distributed robotic network.

To test the listener, run the original talker example in a terminal, and then in a new terminal run the listener example.

Run the listener example

ros2 launch calyosensus_ros run_with_config.launch.py sensus_config:=./listener-example.yaml

In another terminal, check that data is being published using the ROS CLI:

Test the publisher

ros2 topic list # should see both 'calyo_raw_data' and 'calyo_pointcloud'
ros2 topic echo /calyo_pointcloud # should now see realtime pointcloud data being streamed

Multiple Pipelines

Just as with sensus-sdk, configuration here supports multiple pipelines. There is one caveat that, in the case of the listener, all pipelines must be connected together - that is: all pipelines must either be RosReader or be downstream of that pipeline, having FrameBufferReader with source set to the id of the Ros pipeline.

ROS2 Message Types

In keeping with the ROS ethos, the sensus-ros software supports the built-in message types for all pipelines. This, however, presents a difficulty because there is additional metadata generated by the sensor which can be important, depending on what you want to do, but the built-in message types do not support arbitrary extra fields. While it is possible to compose custom message types (as we have done) this comes at the expense of portability, as many popular toolboxes and visualisers rely on common data types.

Calyo sensor metadata

# AcquisitionInfo.msg
builtin_interfaces/Time time_stamp
float32 centre_frequency
uint32 num_time_points
uint32 num_signals
uint32 num_cycles
uint32 sample_rate
float32 temperature
string description

To resolve this, the calyosensus_ros node supports two "schemas" which can be supplied as a configuration argument in the yaml:

• composite (default): the custom calyo datatypes will be used, ensuring each message has a complete dataset
• split: the software will publish to two topics (%topic_name%/data and %topic_name%/meta) so that the sensor data may be consumed in a common format, and the metadata handled differently or discarded

The below table shows the mapping between pipeline stages and ros messages:

Stage	Composite Type	Split Types	CV encoding
passthrough	calyo_msgs/msg/CalyoMat2	sensor_msgs/msg/Image calyo_msgs/msg/AcquisitionInfo	mono8
signal_reconstruction	calyo_msgs/msg/CalyoMat2	sensor_msgs/msg/Image calyo_msgs/msg/AcquisitionInfo	32FC2
filtered_spectrum	calyo_msgs/msg/CalyoMat2	sensor_msgs/msg/Image calyo_msgs/msg/AcquisitionInfo	32FC2
filtered_signals	calyo_msgs/msg/CalyoMat2	sensor_msgs/msg/Image calyo_msgs/msg/AcquisitionInfo	32FC2
image_generation	calyo_msgs/msg/CalyoMat2	sensor_msgs/msg/Image calyo_msgs/msg/AcquisitionInfo	32FC1
log_conversion	calyo_msgs/msg/CalyoMat2	sensor_msgs/msg/Image calyo_msgs/msg/AcquisitionInfo	32FC1
pointcloud_generation	calyo_msgs/msg/CalyoPointCloud	sensor_msgs/msg/PointCloud2 calyo_msgs/msg/AcquisitionInfo	N/A
dbscan	calyo_msgs/msg/CalyoPointCloud	sensor_msgs/msg/PointCloud2 calyo_msgs/msg/AcquisitionInfo	N/A

For more info about pipeline stages see the Configuration Reference

Visualisation

We recommend Foxglove for visualisation. To see a tutorial on setting up, go to our Foxglove Integration Tutorial.

The usual ROS2 tools like RViz can also be used to visualise the SENSUS data with the "split" message schema.