Ingesting ROS2 Data with the Formant ROS2 Adapter

📘

Prerequisite: Adapters

If you are unfamiliar with Adapters, first familiarize yourself by visiting Adapters.

📘

Want the code?

View the adapter on Github for a full readme and the code for the adapters.

This adapter allows robots running the Formant Agent to automatically ingest ROS2 information. This document provides a guide on how to configure the adapter and use it to stream data from ROS2 topics to Formant streams and to control your robot using ROS2 services.

Configuration

The adapter can be configured by editing the config.json file in the formant_ros2_adapter/scripts directory, or by pasting full adapter configuration into the "blob data" section of the Formant Agent's configuration page.

A full example configuration is provided at config_example.json.

The full configuration schema is available here.

Adapter configuration is split into five sections: subscribers, publishers, service_clients, localization, transform_tree, and numeric_sets.

Subscribers

The subscribers section defines a list of ROS2 topics that the adapter will subscribe to, and the Formant streams that they will be mapped to. Each subscriber configuration has the following parameters:

Example:

"ros2_adapter_configuration": {
    "subscribers": [
        {
            "ros2_topic": "/example_topic",
            "ros2_message_type": "example_msgs/msg/ExampleType",
            "formant_stream": "example.stream",
            "ros2_message_paths": [
                {
                    "path": "example_path",
                    "tags": {
                        "example_key": "example_value"
                    }
                }
            ]
        }
    ]
}

Publishers

The publishers section defines a list of ROS2 topics that the adapter will publish to, and the Formant streams that they will be mapped to.

The Formant application can send a message on a stream from either:

1. A teleoperation control, such as a button, slider, joystick, or image click
2. A command

In either of these cases, the name of the configured Formant control input must match the formant_stream parameter in the adapter.

Example

"ros2_adapter_configuration": {
    "publishers": [
        {
            "formant_stream": "example.stream",
            "ros2_topic": "/example_topic",
            "ros2_message_type": "example_msgs/msg/ExampleType",
        }
    ]
}

Service Clients

The service_clients section defines a list of ROS2 services that the adapter will call, and the Formant streams that they will be mapped to.

Formant commands can be mapped to services by setting the formant_stream parameter to the name of the configured Formant command.

Services with zero or one parameter can be called using the following logic:

1. If the service has zero parameters, a command with any parameter (or no parameters) will call it
2. If the service has one numeric parameter, a command with a single numeric parameter will call it
3. If the service has one string parameter, a command with a single string parameter will call it
4. If the service has one boolean parameter:
   1. If the command has no parameters, it will call the service with "true"
   2. If the command has a parameter that maps to a boolean value, it will call the command with that value
      1. True parameters include ["true", "True", "TRUE", "t", "T", "1"]
      2. False parameters include ["false", "False", "FALSE", "f", "F", "0"]

Example

"ros2_adapter_configuration": {
    "service_clients": [
        {
            "formant_stream": "example.stream",
            "ros2_service": "/example_service",
            "ros2_service_type": "example_services/srv/ExampleService",
        }
    ]
}

Localization

The Formant localization datapoint includes many fields which are all aggregated to create a single aligned world perspective.

The localization section defines a list of ROS2 topics that the adapter will subscribe to, and the Formant localization datapoint fields that they will be mapped to.

This datapoint uses a special localization manager to aggregate the data from all of the configured topics. It is built to publish only the necessary data in order to save bandwidth.

This configuration section also maps incoming navigation controls such as waypoints from the localization UI to ROS2 topics.

Example

{
  "ros2_adapter_configuration": {
    "localization": {
      "formant_stream": "example.localization",
      "base_reference_frame": "map",
      "odometry_subscriber_ros2_topic": "/odom",
      "map_subscriber_ros2_topic": "/map",
      "point_cloud_subscriber_ros2_topics": ["/scan", "/stereo/depth/points"],
      "path_subscriber_ros2_topic": "/plan",
      "goal_subscriber_ros2_topic": "/goal_pose",
      "goal_publisher_ros2_topic": "/goal_pose",
      "cancel_goal_publisher_ros2_topic": "/move_base/cancel"
    }
  }
}

Transform Tree

The Formant transform tree datapoint includes the trasnform tree from /tf and /tf_static rooted at a specific base_reference_frame(e.g. base_link)

The transform_tree section requires a base_reference_frame to root the tree

Example

{
  "ros2_adapter_configuration": {
    "transform_tree": {
      "base_reference_frame": "base_link"
    }
  }
}

Numeric Sets

Example

"ros2_adapter_configuration": {
    "numeric_sets": [
        {
            "formant_stream": "example.numeric_set",
            "ros2_subscribers": [
                {
                    "ros2_topic": "/example_topic",
                    "ros2_message_path": "example_numeric_value_path_1",
                    "label": "example label 1",
                    "unit": "units"
                },
                {
                    "ros2_topic": "/example_topic",
                    "ros2_message_path": "example_numeric_value_path_2",
                    "label": "example label 1",
                    "unit": "units"
                },
            ]
        }
    ]
}

ROS2 adapter functionality

For a full list of Formant telemetry types, see: https://formant.readme.io/docs/how-telemetry-streams-work

For a list of what is currently supported by the Formant ROS2 Adapter:

Basic datapoints

• Numeric (UInt, Int, and Float types) :heavy_check_mark:
• Text (String, Char) :heavy_check_mark:
• Bitset (Bool) :heavy_check_mark:
• Location (NavSatFix) :heavy_check_mark:
• Battery (Battery) :heavy_check_mark:

All other input types will be ingested as JSON.

Input from multiple fields

• Bitset (multiple Bool inputs) :heavy_check_mark:
• Numeric Set (multiple UInt, Int, or Float inputs) :heavy_check_mark:

Rich datapoints

• Point Clouds (PointCloud2, LaserScan) :heavy_check_mark:
• Compressed Images :heavy_check_mark:
• Raw Images (into video) :heavy_check_mark:
• Video clips
• Localization (Map, Odometry, Path, etc.) :heavy_check_mark:
• Transform Tree (/tf, /tf_static) :heavy_check_mark:

Type conversions

Topics will automatically be ingested as their corresponding Formant type:

Stream name will be automatically configured from the topic if it is not set. (e.g. "/base/cmd_vel" -> "base.cmd_vel") The "stream" configuration can be set to change the stream name of ingested datapoints manually.

Running the adapter

The repo can either be zipped and configured as an adapter in Formant with "Exec command" ./start.sh, or can be run manually.

If you use custom messages, you must update the start.sh script to source your workspace.