---
updatedAt: 2025-11-11T01:46:01.000Z
agentTools:
  projectIndex: https://docs.formant.io/llms.txt
---

# 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:

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        ROS message type
      </th>

      <th>
        Formant data type
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `nav_msgs/OccupancyGrid`
        `nav_msgs/Path`
        `sensor_msgs/PointCloud2`
        `sensor_msgs/LaserScan`
        `nav_msgs/Odometry`
        `geometry_msgs/PoseStamped`
      </td>

      <td>
        Localization
      </td>
    </tr>
  </tbody>
</Table>

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:

<Image alt="ROS localization telemetry stream configuration" align="center" width="500px" src="https://files.readme.io/d8218554fac284c0e467903c1087247e47d4b2e2632116180ba3d122c735f374-Screenshot_2025-02-05_at_3.54.41_PM.png">
  ROS localization telemetry stream configuration.
</Image>

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Property
      </th>

      <th>
        Usage
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Telemetry stream name
      </td>

      <td>
        Give the stream a name.
      </td>
    </tr>

    <tr>
      <td>
        On demand
      </td>

      <td>
        If **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](https://docs.formant.io/docs/on-demand-streams).  

        If **OFF**, this stream will ingest periodically. `Rate limit` controls the rate of data ingestion.
      </td>
    </tr>

    <tr>
      <td>
        Video encoding
      </td>

      <td>
        Only 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.
      </td>
    </tr>

    <tr>
      <td>
        Validation schema
      </td>

      <td>
        Only applicable for JSON and text streams. Choose a configuration schema for this stream.
      </td>
    </tr>

    <tr>
      <td>
        ROS version
      </td>

      <td>
        The ROS version of the node publishing the topic.
      </td>
    </tr>

    <tr>
      <td>
        Base reference frame
      </td>

      <td>
        Reference frame in your transform tree you want to use as the base frame. Enter the name of a reference frame, not a ROS topic (e.g., `map`).
      </td>
    </tr>

    <tr>
      <td>
        Odometry topic
      </td>

      <td>
        Specify the odometry topic with type `nav_mags/Odometry` which estimates the position and velocity of the robot with type. Usually `/odom`.  

        Odometry streams can be configured to send data to the Formant UI in real-time, as well as being ingested to the Formant cloud. For more information, see [Add a realtime odometry stream](https://docs.formant.io/docs/getting-started-add-a-realtime-odometry-stream).
      </td>
    </tr>

    <tr>
      <td>
        Map topic
      </td>

      <td>
        Specify an occupancy grid with type `nav_mags/OccupancyGrid` with information about the robot's surroundings.
      </td>
    </tr>

    <tr>
      <td>
        Point cloud topics
      </td>

      <td>
        Specify 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.  

        Point cloud streams can be configured to send data to the Formant UI in real-time, as well as being ingested to the Formant cloud. For more information, see [Teleoperation: Add a point cloud stream](https://docs.formant.io/docs/getting-started-add-a-point-cloud-stream).
      </td>
    </tr>

    <tr>
      <td>
        Path
      </td>

      <td>
        Specify the ROS topic that indicates the path with type `nav_msgs/Path` of the robot. The relevant topic name often varies by planner.
      </td>
    </tr>

    <tr>
      <td>
        Goal
      </td>

      <td>
        Specify the goal topic with type `geometry_msgs/PoseStamped` to display the goal of the robot. This topic also varies by planner.
      </td>
    </tr>

    <tr>
      <td>
        Publish goal
      </td>

      <td>
        This section is configured for teleoperation. We'll discuss this in [Add a navigation stream](https://docs.formant.io/docs/add-a-navigation-stream).
      </td>
    </tr>

    <tr>
      <td>
        Cancel goal
      </td>

      <td>
        This section is configured for teleoperation. We'll discuss this in [Add a navigation stream](https://docs.formant.io/docs/add-a-navigation-stream).
      </td>
    </tr>

    <tr>
      <td>
        Add tags (e.g. `key: value`) (optional)
      </td>

      <td>
        Add tags to each datapoint of this stream. For more information on tags, see [Configure access levels](https://docs.formant.io/docs/configure-access-levels).
      </td>
    </tr>

    <tr>
      <td>
        Rate limit (Hz) (optional)
      </td>

      <td>
        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](https://docs.formant.io/docs/on-demand-streams).  

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

        The default rate is 0.5 Hz.
      </td>
    </tr>
  </tbody>
</Table>

5. 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](docs:viewing-data-in-formant).

<Callout icon="👋" theme="default">
  ### 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 [support@formant.io](mailto:support@formant.io).
</Callout>