Ingesting ROS topic data
This section is for ROS users
If you do not use ROS, feel free to move on to the next section: Ingesting from Python.
ROS ingestion overview
ROS is a first-class citizen in Formant. By adding a telemetry stream with a ROS source, you can ingest data directly from ROS without having to write and maintain any additional code on your robot-side application.
Catkin workspace configuration is required for custom messages to work
Before configuring a custom ROS message, the catkin workspace path must be available to the Formant agent. See our Environment variables for the Formant Agent reference if you are stuck here.
Adding a new ROS topic telemetry stream
To add a ROS topic stream,
- Open the Formant sidebar using the button in the top left of the screen
- Select Settings ⇒ Devices ⇒ Click on the device name
- Click the "Telemetry" tab
- Click "Add stream"
- Choose "ROS Topic"

ROS Topic stream configuration
Enter the ROS topic name in the "Ingestion topic" field. Be sure to prefix it with a "/".
The "Ingestion topic" dropdown will auto-fill with detected ROS topics from the host system the device being configured is running on.
It's possible to add more than one ROS topic to a single configuration with the "Add ROS topic" button in the top-right. This is rare, but can be useful in situations where you want to draw messages from multiple topic sources into a single stream.
Ingesting from standard topic types
Here is a mapping from ROS topic type to Formant datapoint type.
ROS message type | Formant datapoint type |
---|---|
std_msgs/String std_msgs/Char | Text |
std_msgs/UInt8 std_msgs/UInt16 std_msgs/UInt32 std_msgs/UInt64 std_msgs/Int8 std_msgs/Int16 std_msgs/Int32 std_msgs/Int64 std_msgs/Float32 std_msgs/Float64 | Numeric |
std_msgs/Bool | Bitset |
sensor_msgs/NavSatFix | Location |
sensor_msgs/BatteryState | Battery |
sensor_msgs/Image sensor_msgs/CompressedImage | Image |
sensor_msgs/Image sensor_msgs/CompressedImage (encoding enabled) | Video |
sensor_msgs/PointCloud2 sensor_msgs/LaserScan | Point cloud |
All other ROS types | JSON |
To ingest any of the data for the types above, simply add the ROS topic, save, and the data will be automatically ingested by the Formant agent as the corresponding Formant datapoint type.
ROS array elements can be ingested by indexing into the array as field.arr[x][y] format when configuring ROS topic. It can be as complex as you want field.arr[x][y].subfield.arr2[i].
Ingesting from custom messages
If you have a catkin workspace configured, custom messages will be converted to Json datapoints before ingestion.
Streaming video from ROS
If the stream being configured is of type sensor_msgs/Image
or sensor_msgs/CompressedImage
, and you wish for it to be ingested as video data, make sure to toggle "Video encoding" to on:

Supported input formats for streaming video using sensor_msgs/Image
messages
sensor_msgs/Image
messagesFor a sensor_msgs/Image
topic to be a valid input to Formant's automatic video encoding, it must have a value for the encoding
field that matches one of the following exactly:
Value of message.encoding |
---|
rgb8 rgba8 bgr8 bgra8 mono8 mono16 8UC1 yuv422 |
If your encoding
value is unsupported, you may be able to adjust the encoding
field of the sensor_msgs/Image
message, without changing the underlying data. In some cases, you will need to transform both the data and the "encoding" property to supported values. Please contact us if you run into these issues.
Updated 1 day ago