Formant ROS 2 Adapter

This adapter allows the Formant Agent to bi-directionally connect Formant streams with ROS 2 topics and services, and to set Formant application configuration parameters as ROS 2 parameters.

Configuration

The adapter can be configured by either 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

The subscribers section defines a list of ROS 2 topics that the adapter will subscribe to, and the Formant streams that they will be mapped to.

Parameter	Description
ros2_topic	The ROS 2 topic to pull messages from
ros2_message_type	The type of message to accept
formant_stream	The name of the Formant stream to ingest to
ros2_message_paths	The list of paths configurations to ingest data from
ros2_message_paths/path	The path within the ROS 2 message
ros2_message_paths/tags	The tag set to ingest data with
ros2_qos_profile	The Quality of Service profile for the messages

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"
                    }
                }
            ],
            "ros2_qos_profile": "SYSTEM_DEFAULT"
        }
    ]
}

Publishers

The publishers section defines a list of ROS 2 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.

Parameter	Description
formant_stream	The name of the Formant stream to publish data from
ros2_topic	The name of the ROS 2 topic to publish data to
ros2_message_type	The type of ROS 2 topic to publish data to
ros2_qos_profile	The Quality of Service profile for the messages

Example

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

Service Clients

The service_clients section defines a list of ROS 2 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"]

Parameter	Description
formant_stream	The name of the Formant stream to accept commands from
ros2_service	The name of the ROS 2 service to call
ros2_service_type	The type of ROS 2 service to call

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 ROS 2 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 ROS 2 topics.

Parameter	Description
formant_stream	The name of the Formant stream to ingest to
base_reference_frame	The base reference frame to use
odometry_subscriber_ros2_topic	The odometry ROS 2 topic name
map_subscriber_ros2_topic	The map ROS 2 topic name
point_cloud_subscriber_ros2_topics	A list of ROS 2 topics to ingest point clouds from
path_subscriber_ros2_topic	The ROS 2 topic to ingest path messages from
goal_subscriber_ros2_topic	The ROS 2 topic to ingest goal messages from
goal_publisher_ros2_topic	The ROS 2 topic to publish goal messages from waypoint UI clicks to
cancel_goal_publisher_ros2_topic	The ROS 2 topic to publish waypoint cancellation messages to

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": [
        {"ros2_topic": "/scan"},
        {"ros2_topic": "/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

Parameter	Description
base_reference_frame	The base reference frame to use for the transform tree

Example

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

Numeric Sets

Parameter	Description
formant_stream	The name of the Formant stream to ingest a numeric set to
ros2_subscribers	The list of subscriber configurations to pull numeric data from
ros2_subscribers/ros2_topic	The ROS 2 topic to pull numeric data from
ros2_subscribers/ros2_message_path	The ROS 2 message path to use to select data from messages on the topic
ros2_subscribers/label	The text to use for the label of this value in the numeric set
ros2_subscribers/unit	The text to use for the unit of this value in the numeric set

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 ROS 2 Adapter:

Basic datapoints

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

All other input types will be ingested as JSON.

Input from multiple fields

• Bitset (multiple Bool inputs) ✔️
• Numeric Set (multiple UInt, Int, or Float inputs) ✔️

Rich datapoints

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

Type conversions

Topics will automatically be ingested as their corresponding Formant type:

ROS topic type	Formant datapoint type
Bool, message with bool-valued message paths	bitset
Char, String	text
Float, Int, Uint	numeric
NavSatFix	location
LaserScan, PointCloud2	point cloud
CompressedImage	image, video

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.

Quality of Service profiles

The adapter currently supports selecting from a set of predefined Quality of Service profiles for publishers and subscribers, based on these default profiles: https://docs.ros.org/en/rolling/Concepts/About-Quality-of-Service-Settings.html#qos-profiles

The possible configuration options are:

• SYSTEM_DEFAULT

• SENSOR_DATA

• SERVICES_DEFAULT

• PARAMETERS

• PARAMETER_EVENTS

• ACTION_STATUS_DEFAULT (reliable reliability, transient local durability)

• EXAMPLE_CUSTOM (keep all history)

The EXAMPLE_CUSTOM option shows how additional custom profiles can be created in the code of the adapter.

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.

As a ROS 2 Package

Choose where you would like to have your workspace if you do not already have one created. If one already exists, skip the first command.

mkdir -p colcon_ws/src

cd colcon_ws/src

git clone <URL for this Repo>

cd ../..

source /opt/ros/<Desired Distro>/setup.bash # (this adapter is meant to work with any ROS2 distribution eloquent+)

colcon build OR colcon build --packages-select formant_ros2_adapter if you have other ROS 2 packages in your workspace that you don't want to build concurrently.

NOTE: If you have custom messages that are not a part of the same workspace as this ros2-adapter, then source them at this point.

source install/setup.bash

ros2 launch formant_ros2_adapter formant_ros2_adapter.launch.py

NOTE: This is untested with ROS 2 Humble NOTE: This is untested with fastdds