> ## Documentation Index
> Fetch the complete documentation index at: https://docs.edgeimpulse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ROS 2 (edgeimpulse_ros)

[ROS 2 (Robot Operating System)](https://www.ros.org/) is the open-source framework that most modern robots are built on. It lets the many parts of a robot - sensing, perception, decision-making, and motion - share information and work together in real time.

[`edgeimpulse_ros`](https://github.com/edgeimpulse/edgeimpulse-ros) is an open-source ROS 2 package that plugs an Edge Impulse model straight into your robot's software. It runs a Linux `.eim` binary inside a ROS 2 node so that whatever your model understands - objects, categories, or anomalies - becomes available to the rest of your robot with no hand-written glue code.

<Frame caption="Edge Impulse vision models running on ROS 2 robots">
  <img src="https://mintcdn.com/edgeimpulse/b5-ul7shu7FpiXoC/.assets/images/robotics/ei_ros2_robot_arm.png?fit=max&auto=format&n=b5-ul7shu7FpiXoC&q=85&s=b199501941ff0378afdb62b593fcf329" width="1600" height="858" data-path=".assets/images/robotics/ei_ros2_robot_arm.png" />
</Frame>

The node is a pure inference processor: images in, `vision_msgs` out.

```
camera driver → edgeimpulse_detector (decode → preprocess → Edge Impulse runner → convert) → vision_msgs topics
```

Because it subscribes to a standard `sensor_msgs/Image` topic, it drops straight into the pipeline you already have, and it works with QoS, `image_transport`, namespaces, and multi-camera setups.

## Highlights

* **Camera-agnostic**: Subscribe to any image topic with configurable QoS; optional `CompressedImage` input.
* **Handles the hard encodings**: Decodes `bgr8`, `rgb8`, `mono8/16`, `bgra8`, `rgba8`, `yuyv`, `uyvy`, and `nv12/nv21` natively.
* **Correct timestamps**: The source image's stamp and `frame_id` propagate to every output, so TF and sensor fusion keep working.
* **Every image model type**: Object detection, image classification, FOMO, and visual anomaly detection (FOMO-AD).
* **Accurate coordinates**: Detections are mapped from model-input space back to the original image resolution (crop/pad/squash aware).
* **Idiomatic messages**: `vision_msgs/Detection2DArray` and `Classification`, plus latched `VisionInfo`/`LabelInfo`.
* **Observability built in**: An optional annotated debug image and a `diagnostic_msgs/DiagnosticArray` with FPS, latency, and model health.

## Prerequisites

* A ROS 2 workspace running **Jazzy** or **Rolling** (which ship `vision_msgs` 4.x). Humble support is on the roadmap but not yet validated in CI.
* The Edge Impulse Linux **Python** SDK installed in the same interpreter as ROS, along with OpenCV and NumPy. The SDK imports `pyaudio` at load time (even for image models), so `portaudio19-dev` is required to build it.
* A model exported from your Edge Impulse project as a [Linux `.eim` binary](/studio/projects/deployment#deploy-as-a-linux-eim-binary) that matches your device architecture. You can [train a model in Edge Impulse Studio](https://studio.edgeimpulse.com) or start from a public project.

Install the ROS dependencies and the Edge Impulse Linux SDK for your platform:

<Tabs>
  <Tab title="Ubuntu">
    On a standard Ubuntu machine (Ubuntu 24.04 pairs with ROS 2 Jazzy), use `apt` and `pip`. On Ubuntu 24.04 the system Python is [externally managed (PEP 668)](https://peps.python.org/pep-0668/), so install the SDK into your user site with `--break-system-packages`:

    ```bash theme={"system"}
    sudo apt update
    sudo apt install ros-$ROS_DISTRO-vision-msgs ros-$ROS_DISTRO-diagnostic-msgs \
                     ros-$ROS_DISTRO-v4l2-camera \
                     python3-opencv python3-numpy portaudio19-dev

    pip install --user --break-system-packages edge_impulse_linux pyaudio
    ```

    Use the **x86-64** (or **aarch64** on Arm-based machines) `.eim` build from the Studio.
  </Tab>

  <Tab title="Qualcomm Linux">
    On Qualcomm Linux devices (for example the RB3 Gen 2 / QRB boards), ROS 2 and the perception stack are provided by the platform. Install the ROS message packages and the Edge Impulse SDK into the platform's Python interpreter:

    ```bash theme={"system"}
    sudo apt install ros-$ROS_DISTRO-vision-msgs ros-$ROS_DISTRO-diagnostic-msgs \
                     python3-opencv python3-numpy portaudio19-dev

    pip install --user --break-system-packages edge_impulse_linux pyaudio
    ```

    Use the **aarch64** `.eim` build from the Studio. The onboard camera driver [`qrb_ros_camera`](https://github.com/quic/qrb_ros_camera) publishes NV12 frames — `edgeimpulse_ros` decodes NV12 directly, so no colour-conversion node is required (see [NV12 and Qualcomm QRB cameras](#nv12-and-qualcomm-qrb-cameras) below).
  </Tab>
</Tabs>

## Get started in five minutes

Install the package into your ROS 2 workspace, then run the bundled webcam demo:

```bash theme={"system"}
# In your ROS 2 workspace
colcon build --packages-select edgeimpulse_ros
source install/setup.bash

# One-command demo with a USB camera (needs ros-$ROS_DISTRO-v4l2-camera)
ros2 launch edgeimpulse_ros edgeimpulse_with_camera.launch.py \
  model_path:=/absolute/path/to/model.eim \
  publish_debug_image:=true
```

Then watch the results flow:

```bash theme={"system"}
ros2 topic echo /edgeimpulse_detector/detections
ros2 run rqt_image_view rqt_image_view /edgeimpulse_detector/debug_image
```

## Use your existing camera node

Already have a camera node? Skip the demo launch and point the detector at your existing topic:

```bash theme={"system"}
ros2 launch edgeimpulse_ros edgeimpulse_detector.launch.py \
  model_path:=/path/to/model.eim \
  image_topic:=/camera/image_raw \
  image_qos:=sensor_data
```

The input topic, QoS, resize mode, confidence threshold, and debug overlay are all ROS 2 parameters, with ready-to-use launch files and a documented config file, so you can configure the node without editing code.

## NV12 and Qualcomm QRB cameras

Qualcomm's `qrb_ros_camera` publishes NV12 frames. `edgeimpulse_ros` can decode NV12 (and NV21/YUYV) directly to BGR inside the node, so you can point it straight at the camera:

```bash theme={"system"}
ros2 launch edgeimpulse_ros edgeimpulse_detector.launch.py \
  model_path:=/path/to/model.eim \
  image_topic:=/qrb_camera/image \
  image_qos:=sensor_data
```

## Visual anomaly detection

FOMO-AD models are well suited to quality control and "something's wrong here" monitoring. `edgeimpulse_ros` publishes the spatial anomaly grid as boxes on `~/detections` and the peak anomaly score on `~/anomaly`, and overlays the flagged regions on the debug image.

## Learn more

* **Tutorial series**: [Robotics with Edge Impulse and ROS 2](/tutorials/topics/robotics-series/robotics-series) - end-to-end tutorials that build on this package.
  * [Run Edge Impulse Object Detection with ROS 2](/tutorials/topics/robotics-series/edgeimpulse-ros2-integration) - the shared `edgeimpulse_ros` detector reference used across the series.
  * [Run Edge Impulse Vision on a JetBot with Rubik Pi](/tutorials/topics/robotics-series/wheeled-robot-ros2-integration) - perception on a JetBot-class mobile robot.
  * [Build a Mobile Inspection System with Edge Impulse and ROS 2](/tutorials/topics/robotics-series/wheeled-inspection-system) - a rover-style inspection architecture.
  * [Run Edge Impulse Pick and Place with UNO Q Braccio](/tutorials/topics/robotics-series/robotic-arm-ros2-integration) - trigger robotic-arm sorting from detections.
* **GitHub**: [github.com/edgeimpulse/edgeimpulse-ros](https://github.com/edgeimpulse/edgeimpulse-ros) - setup steps, launch files, examples, and configuration.
* **Deploy a model**: [Deploy as a Linux `.eim` binary](/studio/projects/deployment#deploy-as-a-linux-eim-binary).
* **Train a model**: [Edge Impulse Studio](https://studio.edgeimpulse.com).

`edgeimpulse_ros` is open source under the BSD-3-Clause-Clear license.