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

# QRB ROS Transport

`qrb_ros_transport` 是面向 Qualcomm 机器人平台的零拷贝 ROS 2 传输。它基于 [REP 2007](https://ros.org/reps/rep-2007.html)（类型适配）实现，允许 ROS 节点声明自定义消息类型可与标准类型互换——因此中间件可以直接传递摄像头 ISP 写入的 DMA‑buf 文件描述符，而不是序列化并复制像素负载。

```mermaid theme={null}
flowchart LR
    subgraph stock["Stock image_transport"]
        A1[Camera Node<br/>CPU] -->|serialize| B1[memcpy<br/>CPU]
        B1 -->|copy bytes| C1[Consumer Node<br/>CPU/GPU/NPU]
    end
    subgraph qrb["qrb_ros_transport"]
        A2[Camera ISP] -->|DMA-buf fd| B2[Consumer Node<br/>GPU/NPU/EVA]
    end
```

在标准路径中，每个订阅者都会收到帧的独立副本，而每个副本都是一次 CPU memcpy。在 QRB 路径中，生产者和所有消费者共享同一个 DMA 缓冲区——在 ROS 计算图中传递的是 fd，而不是像素。

## 支持的适配类型

| QRB 适配类型                                                                                                                                                                                                    | 标准 ROS 接口                                                                                                                 |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| [`qrb_ros::transport::type::Image`](https://github.com/qualcomm-qrb-ros/qrb_ros_transport/blob/main/qrb_ros_transport_image_type/include/qrb_ros_transport_image_type/image.hpp)                            | [`sensor_msgs::msg::Image`](https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/Image.msg)             |
| [`qrb_ros::transport::type::PointCloud2`](https://github.com/qualcomm-qrb-ros/qrb_ros_transport/blob/main/qrb_ros_transport_point_cloud2_type/include/qrb_ros_transport_point_cloud2_type/point_cloud2.hpp) | [`sensor_msgs::msg::PointCloud2`](https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/PointCloud2.msg) |

<Note>
  上游也存在 [`Imu` 适配类型](https://github.com/qualcomm-qrb-ros/qrb_ros_transport/blob/main/qrb_ros_transport_imu_type/include/qrb_ros_transport_imu_type/imu.hpp)，但通过它生产数据需要 `qrb_sensor_client` 以及 RB3 Gen2 套件上特定的 ICM-42688 IMU。如果您正好有这套硬件，请参见 [`qrb_ros_imu`](https://github.com/qualcomm-qrb-ros/qrb_ros_imu)。对于典型用例，带宽收益体现在 `Image` 和 `PointCloud2` 上——IMU 负载非常小，零拷贝带来的收益不大。
</Note>

## 支持的目标

| 硬件                               |
| -------------------------------- |
| Qualcomm Dragonwing™ IQ‑9075 EVK |

<Note>
  上游 `qrb_ros_transport` README 目前未列出 IQ‑8275 EVK。构建之前，请在[上游仓库](https://github.com/qualcomm-qrb-ros/qrb_ros_transport)中查看最新的受支持目标。
</Note>

## 与标准 `image_transport` 对比

标准 `image_transport` / `sensor_msgs::Image` 总是将负载序列化到 ROS 消息中，并将其复制到每个订阅者的缓冲区。这对于小话题和驻留在 CPU 中的数据没有问题，但当生产者是将帧写入 DMA 内存的硬件模块（摄像头 ISP 是常见情况）、而消费者是另一个硬件模块（GPU 做颜色转换、NPU 做推理、EVA 做计算机视觉运算）时，这就是无谓的开销。`qrb_ros_transport` 正是为这种硬件到硬件的场景而生——像素留在 DMA 内存中，移动的只有 fd。

如果话题的两端都是 CPU 代码，那么标准 `image_transport` 已经够用且更简单。零拷贝的收益随（负载大小 × 订阅者数量 × 跨越的节点边界数量）而扩大。

## 安装

<Info>
  这些步骤需要 **Qualcomm® IoT 平台上的 Ubuntu** 和 **ROS 2 Jazzy**。如果尚未安装，请从[在 Qualcomm IoT 平台上安装 Ubuntu](https://ubuntu.com/download/qualcomm-iot)和[安装 ROS Jazzy](https://docs.ros.org/en/jazzy/index.html) 开始。对于 Qualcomm Linux，请改用 [QIRP SDK](https://docs.qualcomm.com/bundle/publicresource/topics/80-70018-265/introduction_1.html?vproduct=1601111740013072\&version=1.4\&facet=Qualcomm%20Intelligent%20Robotics%20Product%20\(QIRP\)%20SDK)。
</Info>

<Steps>
  <Step title="添加 Qualcomm IoT PPA">
    ```bash theme={null}
    sudo add-apt-repository ppa:ubuntu-qcom-iot/qcom-ppa
    sudo add-apt-repository ppa:ubuntu-qcom-iot/qirp
    sudo apt update
    ```
  </Step>

  <Step title="安装 Debian 软件包">
    ```bash theme={null}
    sudo apt install ros-jazzy-qrb-ros-transport-*
    ```
  </Step>
</Steps>

## 用法

将适配类型添加为依赖项，然后像针对任何有类型的 ROS 消息一样编写代码——其余的由中间件处理。

<CodeGroup>
  ```xml package.xml theme={null}
  <depend>qrb_ros_transport_image_type</depend>
  ```

  ```cmake CMakeLists.txt theme={null}
  find_package(ament_cmake_auto REQUIRED)
  ament_auto_find_build_dependencies()
  ```

  ```cpp publisher.cpp theme={null}
  #include "qrb_ros_transport_image_type/image.hpp"

  // Create message
  auto msg = std::make_unique<qrb_ros::transport::type::Image>();
  msg->header   = std_msgs::msg::Header();
  msg->width    = width;
  msg->height   = height;
  msg->encoding = "nv12";

  // Allocate dmabuf for message
  auto dmabuf = lib_mem_dmabuf::DmaBuffer::alloc(size, "/dev/dma_heap/system");
  // ... populate dmabuf ...
  msg->dmabuf = dmabuf;

  // Publish — no memcpy: subscribers receive the fd, not the payload
  pub->publish(std::move(msg));
  ```
</CodeGroup>

<AccordionGroup>
  <Accordion title="从源码构建" icon="hammer">
    安装开发依赖项：

    ```bash theme={null}
    sudo add-apt-repository ppa:ubuntu-qcom-iot/qcom-noble-ppa
    sudo add-apt-repository ppa:ubuntu-qcom-iot/qirp
    sudo apt update

    sudo apt install ros-dev-tools \
      ros-jazzy-lib-mem-dmabuf \
      ros-jazzy-qrb-sensor-client \
      ros-jazzy-pcl-conversions
    ```

    使用 `colcon` 克隆并构建：

    ```bash theme={null}
    source /opt/ros/jazzy/setup.bash
    git clone https://github.com/qualcomm-qrb-ros/qrb_ros_transport.git
    colcon build
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="它是如何构建的" icon="layer-group">
    `qrb_ros_transport` 建立在同一组织的两个上游软件包之上：

    ```mermaid theme={null}
    flowchart TB
        L["<b>lib_mem_dmabuf</b><br/>userspace DMA-buf helper<br/>(alloc, mmap, fd passing)"]
        D["<b>dmabuf_transport</b><br/>portable REP 2007 adapted types<br/>(Image, PointCloud2)"]
        Q["<b>qrb_ros_transport</b><br/>Qualcomm-optimized<br/>(Image, PointCloud2, Imu adapter)"]
        L --> D
        D --> Q
        classDef portable fill:#F4EFFA,stroke:#31017D,color:#31017D,stroke-width:1.5px;
        classDef silicon fill:#31017D,stroke:#31017D,color:#fff,stroke-width:1.5px;
        class L,D portable;
        class Q silicon;
    ```

    使用 `qrb_ros_transport` 时您不会直接与这两者交互——它们会被间接引入。此处提供链接是为想了解完整技术栈、或需要将代码移植到具有 DMA-heap 支持的非 Qualcomm Linux SoC 的读者准备的：

    * [`dmabuf_transport`](https://github.com/qualcomm-qrb-ros/dmabuf_transport) — `Image` 和 `PointCloud2` 的可移植 REP 2007 适配类型。可在任何具有 DMA heap 的 Linux 5.12+ SoC 上运行。
    * [`lib_mem_dmabuf`](https://github.com/qualcomm-qrb-ros/lib_mem_dmabuf) — 用户空间 C++ DMA-buf 分配库。只有在进行非 ROS 互操作（GStreamer、V4L2、自定义驱动、OpenGL ES）时才直接使用。
  </Accordion>
</AccordionGroup>

## 相关内容

* 使用 `qrb_ros_transport` 作为摄像头路径的示例管线：[QRB ROS 示例](./qrb-ros-samples)。
* 上游源码和最新文档：[`qualcomm-qrb-ros/qrb_ros_transport`](https://github.com/qualcomm-qrb-ros/qrb_ros_transport)。