Documentation

ROS 2 Getting Started Guide

Learn the essentials of using Formant in your ROS2 enviroment

Suggest Edits

You can use the ROS 2 adapter to enable the Formant agent to ingest ROS 2 data.

Install the adapter

Native installation

We recommend using a native installation, unless you are using ROS 2 from within a Docker container. If you are, please refer to our section below on installing in a Docker environment.

  1. Download the Adapter: Get the latest ROS 2 adapter from the releases page: https://github.com/FormantIO/ros2-adapter/releases

  2. Add to Formant: Follow the instructions at https://docs.formant.io/docs/add-an-adapter to add the adapter to your organization and then add to your device. Use the exec command ./start.sh when prompted (you will be prompted to for an exec command when you are adding the adapter zip file to your organization).

Docker installation

If you are running ROS 2 in a Docker container, then you will need to install the ROS 2 adapter into that Docker container. We recommend editing your Dockerfile and installing the adapter into the container at that step.

  1. Dockerfile Integration: Install the ROS 2 adapter (https://github.com/FormantIO/ros2-adapter) directly into your ROS 2 Docker container via your Dockerfile.

  2. Start the Adapter: Run start.sh within the Docker container to initiate the ROS 2 adapter.

  3. Add to Formant: Follow the instructions at https://docs.formant.io/docs/add-an-adapter but use the exec command sleep_forever.sh instead of start.sh.

🚧

Ensure the ROS 2 adapter can communicate with the Formant agent on your host machine

Mount the directory /var/lib/formant (containing agent.sock) into your ROS2 Docker container. You can do this by appending -v /var/lib/formant:/var/lib/formant to your Docker run command, or by editing a Docker compose file.

Example Dockerfile ROS2 Integration

Below is an example Dockerfile that installs the ROS 2 adapter directly into the Docker image. The ROS 2 adapter can be directly installed into your Docker image in the same fashion. You will still need to run ./start.sh from within your Docker container each time you start to image to run the ROS 2 adapter. 

FROM osrf/ros:humble-desktop

RUN apt update && apt install -y python3-pip
RUN pip3 install formant

WORKDIR /
RUN git clone https://github.com/FormantIO/ros2-adapter.git
WORKDIR /ros2-adapter
RUN pip3 install -r requirements.txt

Update adapter configuration

All of the following steps will require you to adjust the ROS 2 adapter configuration. We walk you through how to get to that configuration in this section.

  1. In Formant, in the upper-left corner, open the menu and click Settings >> Devices.

  2. Click on the device you want to configure. Under the General tab, scroll down to Adapter Configuration.

  3. Click the gear icon next to the ros2-adapter listing to open its configuration menu.

Configure a telemetry stream

In this section, we cover how to ingest data from a ROS topic into Formant. Once you complete this step, you will have successfully configured a telemetry stream. If you are looking to configure a real-time stream for teleoperation, such as a video stream, then we recommend setting up a video topic in this step.

  1. In the adapter configuration settings, find the Subscribers section. Click Add...

  2. Configure the subscriber as follows:

PropertyUsage
Ros2 topic (required)The topic to subscribe to. (E.g., /cmd_vel)
Ros2 message paths (optional)Specific fields of a ROS message to ingest.

For example, to ingest only the linear.x component of a Twist message, enter linear.x
Ros2 message type (required)Format: ros2_pkg/msgs/msg_name (e.g., geometry_msgs/msg/Twist)
Ros2 qos profile (optional)Only needed if not default.
Formant stream (optional)Name of the stream to generate in Formant (auto-generated if not specified)

Configure real-time video

When you configure a stream in the ROS 2 adapter, it is not real-time by default. This step will allow you to configure a video stream to come through into Formant in realtime, which can be used during teleoperation.

  1. Create a subscriber for an Image or CompressedImage topic (as seen in the section above).

  2. Follow the instructions in Add a teleoperation image stream: API stream, using the stream name you entered when creating the subscriber.

Configure a publisher (e.g., teleop button)

  1. Create a button on your teleoperation interface.
  2. In the ROS 2 adapter settings, find the Publishers section. Click Add...
  3. Configure the publisher as follows:
PropertyUsage
Formant streamName of the API button stream.
Formant datapoint type (optional)
ROS 2 TopicROS 2 topic to which to publish values.
ROS 2 Message TypeFormat: rospkg/Msg/message_name (e.g., std_msgs/msg/Bool)

Once saved, you can start a teleoperation session with your device, and you will be able to send messages to the ROS 2 topic you specified by pressing the button you created in your teleoperation interface.

👋

If you notice an issue with this page or need help, please reach out to us! Use the 'Did this page help you?' buttons below, or get in contact with our Customer Success team via the Intercom messenger in the bottom-right corner of this page, or at [email protected].

Updated 7 days ago