Add a ROS localization stream

📘

This page assumes knowledge of ROS.

In Formant, ROS data which relates to a robot's position and surroundings is encapsulated in a single data type called localization.

Localization combines map, path, point cloud, laser scan, odometry, pose, and goal into a single telemetry stream:

ROS message typeFormant data type
nav_msgs/OccupancyGrid
nav_msgs/Path
sensor_msgs/PointCloud2
sensor_msgs/LaserScan
nav_msgs/Odometry
geometry_msgs/PoseStamped
Localization

This guide will teach you how to ingest ROS localization data into Formant.

Step 1: Create a ROS localization stream

  1. In Formant, in the upper-left corner, open the menu and click Settings.
  2. Click Devices, and then click on the device you want to configure.
  3. Click the Telemetry tab, and then click Add Stream.
  4. Click ROS Localization. This will open the New ROS Localization Stream configuration window:
ROS localization telemetry stream configuration
PropertyUsage
Telemetry stream nameGive the stream a name.
On demandIf ON, this stream will store data locally on your device, and only upload data to Formant when you click Retrieve on-demand data. Rate limit controls the rate at which datapoints are added to the on-device buffer. For more information, see On demand streams.

If OFF, this stream will ingest periodically. Rate limit controls the rate of data ingestion.
Video encodingOnly applicable for sensor_msgs/Image and sensor_msgs/CompressedImage streams. Choose whether you want images ingested on this stream to be encoded as a video.
Validation schemaOnly applicable for JSON and text streams. Choose a configuration schema for this stream.
Base reference frameUsed to visualize localization state without ingesting the entire transform tree.
Odometry topicSpecify the odometry topic with type nav_mags/Odometry which estimates the position and velocity of the robot with type. Usually /odom.

There are additional considerations when configuring an odometry topic for teleoperation. For more information, see Add a navigation stream.
Map topicSpecify an occupancy grid with type nav_mags/OccupancyGrid with information about the robot's surroundings, sometimes found on /map.
Point cloud topicsSpecify the sensor_msgs/PointCloud2 or sensor_msgs/LaserScan topics (separated by comma) to be part of the localization stream. Formant requires .pcd format for point clouds.

There are additional considerations when configuring a point cloud topic for teleoperation. For more information, see Add a navigation stream.
PathSpecify the ROS topic that indicates the path with type nav_msgs/Path of the robot. The relevant topic name often varies by planner.
GoalSpecify the goal topic with type geometry_msgs/PoseStamped to display the goal of the robot. This topic also varies by planner.
Publish goalThis section is configured for teleoperation. We'll discuss this in Add a navigation stream.
Cancel goalThis section is configured for teleoperation. We'll discuss this in Add a navigation stream.
Add tags (e.g. key: value) (optional)Add tags to each datapoint of this stream. For more information on tags, see Configure access levels.
Rate limit (Hz) (optional)If On demand is ON: Set the rate at which data is added to the on-device buffer. Data in the on-device buffer will be ingested by the agent when you click Retrieve on-demand data. For more information, see On demand streams.

If On demand is OFF: Set the rate at which data is ingested.

The default rate is 0.5 Hz.
  1. When you're finished configuring your stream, click Done, and then Save.

Step 2: Add stream to a view

Once you've added a stream to your device, your next step is to add it to a view in Formant.

Add the streams you want to visualize, and then move on to Viewing data in Formant.

👋

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].