Installing the Adapter Natively

We recommend using a native installation if you are not using ROS2 from within a docker container. If you are, please refer to our section below on installing in a docker enviroment.

1. Download the Adapter: Get the latest ros2 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).

ROS2 Adapter Docker Installation

If you are running ros2 in a docker container, then you will need to install the ros2 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 ros2 adapter (https://github.com/FormantIO/ros2-adapter) directly into your ROS2 Docker container via your Dockerfile.

2. Start the Adapter: Run start.sh within the Docker container to initiate the ros2 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.

Important Note: Ensure the ros2 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 ros2 adapter directly into the Docker image. The ROS2 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 ros2 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

Updating Your Adapter Configuration

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

1. Navigate to Settings: In app.formant.io, go to your device's settings, then the "General" tab. Scroll down to "Adapter Configuration."

2. Open Configuration: Click the gear icon next to the "ros2-adapter" listing to open its configuration menu.

Configuring Your First 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 realtime stream for teleop, such as teleop video, then we recommend setting up a video topic in this step.

1. Goto Subscribers settings: In the adapter configuration settings, find the "Subscribers" section.

2. Add Subscriber:

   • Click "Add..."
   • Ros2 topic (required): The topic to subscribe to. (E.g., /cmd_vel)
   • Ros2 message paths (optional): Ingest specific fields only. (E.g. linear.x from a Twist message.)
   • 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): The Formant stream name (auto-generated if not specified).

Configuring Realtime Video

When you configure a stream in the ROS2 adapter, it is not realtime by default. This step will allow you to configure a video stream to come through into Formant in realtime, which can be used in Teleop.

1. Subscribe to Image Topic: Create a subscriber for an Image or CompressedImage topic.

2. Teleop Settings:

   • Go to your teleop settings and add an image.
   • Select "Add from API."
   • Image stream name = the stream you ingest images into.
   • Select enable encoding for video.
   • Save.

Configuring Your First Publisher (e.g., Teleop Button)

1. Create API Button: In teleop settings, add an API button. (You can find instructions on adding a button to teleop here.)

2. Add Publisher: In ros2 adapter settings:

   • Formant stream (required): The API button's name.
   • Formant datapoint type (optional):
   • Ros2 topic (required): Topic to publish to.
   • Ros2 message type (required): Format: rospkg/Msg/message_name (e.g., std_msgs/msg/Bool)
   • Ros2 qos profile (optional): Only needed if not default.

Once saved, you can start a teleop session with your device, and you will be able to send messages to the ros2 topic you specified by pressing the button in the Formant UI.