场景 - Qualcomm Dragonwing Documentation

QIR SDK 支持三种场景，它们共享相同的底层工作流 — 为设备配置、安装 QIR SDK、配置 ROS 2 Jazzy 并运行示例。下面的每个标签页都会打开该场景的工作流图和一个该场景的端到端示例。请参阅开始页面上的设备、操作系统和场景选择器。

前提条件

一台受支持的开发套件。请参阅开始页面上的设备矩阵。
一台 Ubuntu 24.04 主机（推荐）。Windows 和 macOS 主机可以用于 Qualcomm Linux 刷写。
一根 USB Type-C 电缆、您套件的电源以及 Wi-Fi 或以太网网络访问。
如果您计划使用调试 UART，需要一个串行控制台工具（例如 minicom）。

场景工作流

按您的场景选择相应的标签页。在每个标签页中，工作流图显示该场景所增加的阶段，可运行示例则用一个可用的示例走完整个流程。

评估
开发
生产

使用评估场景以最小的投入证明 Qualcomm Dragonwing™ 开发套件或 Ventuno Q 开发板可以运行您的目标工作负载。该路径始终使用预构建的二进制文件：刷入的机器人镜像（Qualcomm Linux）或通过 apt 安装的 qirp-sdk（Ubuntu），以及来自 QIR SDK 目录的现成示例应用。

工作流图

以下图展示了在两种操作系统中评估工作流的通用阶段。

运行示例工作流

按操作系统的标签页操作，得到一个真实、最小化的序列，最后现成示例会在设备上运行。

Qualcomm Linux
Ubuntu

下载机器人镜像

从 CodeLinaro 下载适合您机器的 qli-2.1-qcom-robotics-image.zip。URL 模式为

https://artifacts.codelinaro.org/artifactory/qli-ci/flashable-binaries/meta-qcom-robotics/qcom-robotics-distro/<machine>/qli-2.1-qcom-robotics-image.zip

，其中 <machine> 是 iq-9075-evk 或 iq-8275-evk。

wget https://artifacts.codelinaro.org/artifactory/qli-ci/flashable-binaries/meta-qcom-robotics/qcom-robotics-distro/iq-9075-evk/qli-2.1-qcom-robotics-image.zip
unzip qli-2.1-qcom-robotics-image.zip
cd images/iq-9075-evk

使用 QDL 刷写机器人镜像

将设备置于紧急下载 (EDL) 模式，配置 Universal Flash Storage (UFS)，刷写安全岛 (SAIL) 固件，然后使用 Qualcomm® Device Loader (qdl) 工具刷写机器人镜像。

cd qcom-robotics-image-iq-9075-evk.rootfs.qcomflash
<qdl_dir>/qdl --storage ufs prog_firehose_ddr.elf rawprogram*.xml patch*.xml

当最后一行显示 partition 1 is now bootable 时，刷写完成。将 SW2-3 DIP 开关拨下，然后重新给设备上电。

在设备上设置 QIR SDK 和 ROS2 环境

启动两个终端，并在每个终端中运行以下命令。

ssh root@[ip-addr]

SSH Session

source /usr/share/qirp-setup.sh

运行系统监控 ROS 节点

在终端 1 中运行系统监控 ROS 节点。

SSH Session

ros2 run qrb_ros_system_monitor qrb_ros_system_monitor

输出类似于：

[INFO] [1754041095.755470762] [cpu_monitor]: CPU Monitor start
[INFO] [1754041095.775654235] [memory_monitor]: Memory Monitor start
[INFO] [1754041095.783700187] [temperature_monitor]: Temperature Monitor start
[INFO] [1754041095.791240297] [disk_monitor]: DISK Monitor start
[INFO] [1754041095.798755668] [swap_monitor]: Swap Monitor start
[INFO] [1754041095.804467314] [battery_monitor]: Battery Monitor start
[INFO] [1754041095.809501190] [system_info_server]: System info server start

查看系统信息

在终端 2 中，使用 ros2 topic list 检查 ROS 话题。

SSH Session

ros2 topic list

Output

/battery
/cpu
/disk
/memory
/parameter_events
/rosout
/swap
/temperature

使用 ros2 topic echo /cpu 检查 CPU 信息：

SSH Session

ros2 topic echo /cpu

Output

usage: 8.870357513427734
user: 2263131
nice: 17852
system: 12022972
idle: 3165299899
iowait: 235972
irq: 11140524
softirq: 4153651
steal: 294225
guest: 0
guest_nice: 0
---

刷写 Ubuntu 并连接 Wi-Fi

为您的套件刷写 Ubuntu 镜像，然后通过 Wi-Fi 连接。

sudo nmcli dev wifi list
sudo nmcli dev wifi connect <WiFi-SSID> password <WiFi-password>

对于 VENTUNO Q，您可以使用 App Lab 来设置连接和网络。

添加 ROS 2 和 Qualcomm 包源

sudo add-apt-repository ppa:ubuntu-qcom-iot/qcom-ppa
sudo add-apt-repository ppa:ubuntu-qcom-iot/qirp

安装 QIR SDK 并运行示例

在您的设备上安装 qirp-sdk（server 镜像）或 qirp-sdk-desktop（desktop 镜像），设置运行时环境并运行系统监控示例应用。

sudo apt install qirp-sdk        # Server
# or
sudo apt install qirp-sdk-desktop  # Desktop

source /opt/ros/jazzy/setup.bash
ros2 run qrb_ros_system_monitor qrb_ros_system_monitor

在第二个 shell 中，按需获取此节点的话题并检查系统状态。

source /opt/ros/jazzy/setup.bash
ros2 topic list
# You can now echo system monitor, for example, /cpu
ros2 topic echo /cpu

Output

usage: 8.870357513427734
user: 2263131
nice: 17852
system: 12022972
idle: 3165299899
iowait: 235972
irq: 11140524
softirq: 4153651
steal: 294225
guest: 0
guest_nice: 0
---

使用开发场景从运行示例过渡到编写自己的示例。该路径在评估基线之上增加了 QIR SDK 交叉编译工具链、ROS 2 构建步骤和部署步骤。

工作流图

以下图展示了开发工作流的各个阶段。

运行示例工作流

按操作系统标签页操作，进行真正的交叉编译或设备端构建序列。

Qualcomm Linux
Ubuntu

Source QIR SDK 环境

在主机上解压 QIR SDK 工具链并 source 设置脚本。

cd <decompressed_workspace>/images/iq-9075-evk/qirpsdk_artifacts/iq-9075-evk/
tar -zxvf qirp-sdk_<qirp_version>.tar.gz
cd qirp-sdk
source setup.sh

获取、修改并交叉编译 talker

克隆 ROS 2 demos 仓库，编辑 talker.cpp 中的消息内容，然后使用 QIR SDK 工具链构建。

git clone https://github.com/ros2/demos.git -b jazzy
cd demos/demo_nodes_cpp
vim src/topics/talker.cpp +46

将第 46 行改为：

msg_->data = "Hello World : Qualcomm : " + std::to_string(count_++);

构建：

colcon build --merge-install --packages-up-to demo_nodes_cpp --cmake-args ${CMAKE_ARGS}

在设备上部署并运行

打包构建输出，推送到设备，解压到 /usr/ros/jazzy/，然后在两个 SSH 会话中运行 talker 和 listener。

cd demo_nodes_cpp/install
tar -czvf demo_nodes_cpp.tar.gz lib share
scp demo_nodes_cpp.tar.gz root@<ip-addr>:/opt/

在设备上：

mount -o remount,rw /usr
tar --no-overwrite-dir --no-same-owner -zxf /opt/demo_nodes_cpp.tar.gz -C /usr/ros/jazzy/
source /usr/share/qirp-setup.sh
ros2 run demo_nodes_cpp talker      # in one SSH session
ros2 run demo_nodes_cpp listener    # in a second SSH session

当 talker 打印 Publishing: 'Hello World : Qualcomm : N' 而 listener 回显 I heard: [Hello World : Qualcomm : N] 时，即已完成。

安装 ROS 2 构建依赖

在 Ubuntu 设备上，为 sample_resnet101 安装 ROS 2 构建依赖。

sudo apt install ros-jazzy-rclpy \
  ros-jazzy-sensor-msgs \
  ros-jazzy-std-msgs \
  ros-jazzy-cv-bridge \
  ros-jazzy-ament-index-python \
  ros-jazzy-qrb-ros-tensor-list-msgs \
  python3-opencv \
  python3-numpy \
  ros-jazzy-image-publisher \
  ros-jazzy-qrb-ros-nn-inference \
  ros-jazzy-qrb-ros-camera

从源码克隆并构建示例

mkdir -p ~/qrb_ros_ws/src && cd ~/qrb_ros_ws/src
git clone https://github.com/qualcomm-qrb-ros/qrb_ros_samples.git
cd ~/qrb_ros_ws/src/qrb_ros_samples/ai_vision/sample_resnet101
colcon build
source install/setup.bash

启动示例

ros2 launch sample_resnet101 launch_with_image_publisher.py

当 /resnet101_output 输出分类标签（Ubuntu）时，即已完成。

当您的团队拥有一款要向终端客户发布搭载 Qualcomm Dragonwing™ 平台的产品设计时，使用生产场景。该场景添加了可重复的构建流水线、按技术领域固定所依赖的 QRB ROS 包版本，以及在每次发布前运行的验证。Yocto 构建生成您所发布的确切镜像和 QIR SDK 产物；Debian 打包路径生成您的设备集群安装的确切 .deb 文件。

工作流图

以下图展示了生产工作流的各阶段，从完成的开发到经过验证的发布。

按技术领域的生产关注点

QRB ROS 堆栈分为四个技术领域 — 视觉、多媒体、AI 推理和零拷贝，以及工具。固定属于每个领域的包，然后在切分发布之前使用相应的回归示例验证该领域。

视觉

视觉生产涵盖摄像头、深度传感器和 2D 激光雷达。下表列出了视觉领域的 QRB ROS 包、匹配的回归示例和生产关注点。

QRB ROS 包	回归示例	生产关注点
`qrb_ros_camera`	`sample_object_detection`	固定 CSI 或 GMSL 传感器驱动版本。在 Qualcomm Linux 上，`qrb_ros_camera` 依赖于 CamX 相机堆栈——将 CamX 版本与内核一起冻结。
`qrb_ros_image_resize`	`sample_resnet101`（预处理节点）	确认调整大小的输出与您的模型预期的张量形状匹配。此处的偏差会静默地降低准确性。
`orbbec_camera`	`follow-me`	锁定与驱动一起验证过的 Orbbec Gemini 固件版本。升级固件时重新构建驱动。
`rplidar-ros2`	`cartographer_node`	锁定 RPLIDAR 固件版本。`rplidar-ros2` 在 A1/A2/A3/S1/S2/S3 之间的行为不同——在您的产品实际发布的型号上进行验证。

多媒体

多媒体生产涵盖视频采集与编码、音频管道和色彩空间转换。下表列出了多媒体领域的包、示例和关注点。

QRB ROS 包	回归示例	生产关注点
`qrb_ros_video`	`qrb_ros_video` 平台示例	确认编解码器许可（H.264、H.265）覆盖您的部署地区。固定 `iris-video-dlkm` 内核模块版本。
`qrb_ros_audio_service`	`qrb_ros_audio_service` 平台示例	固定采样率、声道数和声学回声消除 (AEC) 或降噪的默认设置。音频漂移是无声的——在发布前捕获参考录音。
`qrb_ros_colorspace_convert`	`qrb_ros_colorspace_convert` 平台示例	在 Ubuntu 上，桌面镜像变体不包含色彩空间包。如果您的管道需要色彩空间转换，请固定 server 变体（`qirp-sdk`）。

AI 推理和零拷贝

AI 推理生产涵盖模型加载、执行以及将 AI 管道保持在 Qualcomm 硬件缓冲区内的零拷贝传输。下表列出了 AI 推理和零拷贝领域的包、示例和关注点。

QRB ROS 包	回归示例	生产关注点
`qrb_ros_nn_inference`	`sample_resnet101`、`sample_object_detection`	固定与您编译的模型文件匹配的 Qualcomm® AI Engine Direct SDK (QNN) 运行时版本。将 `.bin` 上下文二进制文件嵌入到镜像或签名的空中升级载荷中。
`qrb_ros_transport`	`qrb_ros_benchmark`	验证零拷贝传输（ROS 增强提案 (REP) 2007）与您的自定义节点协同工作。Qualcomm 硬件缓冲区要求 `qrb_ros_transport` 所记录的对齐方式。

工具

工具生产涵盖开发工具链、设备端诊断和您用于捕获回归的性能监控器。下表列出了工具领域的包和关注点。

QRB ROS 包或资产	用途	生产关注点
`qrb_ros_system_monitor`	发布用于设备端诊断的系统状态话题。	将系统状态话题接入您的设备集群遥测，以便您能够调试现场故障。
`qrb_ros_benchmark`	对 ROS 2 组件的吞吐量和延迟进行基准测试。	在回归 CI 中自动化 `qrb_ros_benchmark` 运行。为每个模型的延迟和吞吐量设定明确的界限；当越过界限时使构建失败。
QIR SDK 交叉编译工具链	用于构建 `aarch64-oe-linux` 二进制文件的主机侧工具链。	将工具链打包在您的开发容器镜像中，以便每个工程师都针对完全相同的版本进行构建。
单命令设置脚本	在设备上 `source /usr/share/qirp-setup.sh`。	将该脚本烘焙到镜像中，并让任何自定义 launch 文件基于其副作用（环境变量、`ROS_DOMAIN_ID`）进行门控。

覆盖层是可选的 Qualcomm Linux 路径，它可以在无需重新刷机的情况下将运行中的设备上的基础机器人镜像扩展为专有堆栈。已经构建 qcom-robotics-proprietary-image 的生产团队不需要覆盖层。对于确实需要覆盖层路径的团队，请参见 QIR SDK 用户指南 (Linux)。

运行示例工作流

按操作系统的标签页操作，进行真正的 KAS 构建（Qualcomm Linux）或 Debian 打包设置（Ubuntu）。

Qualcomm Linux (Yocto)
Ubuntu（Debian 打包）

设置构建主机并安装 KAS

sudo apt update
sudo apt install build-essential chrpath cpio debianutils diffstat \
    file gawk gcc git iputils-ping libacl1 locales python3 python3-git \
    python3-jinja2 python3-pexpect python3-pip python3-subunit socat \
    texinfo unzip wget xz-utils zstd gfortran pipx
sudo locale-gen en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
sudo ln -sf /bin/bash /bin/sh
pipx ensurepath
pipx install kas

克隆机器人层并构建镜像

git clone https://github.com/qualcomm-linux/meta-qcom-robotics-sdk -b qli-2.1

kas build \
  meta-qcom-robotics-sdk/ci/iq-9075-evk.yml:\
meta-qcom-robotics-sdk/ci/qcom-robotics-distro.yml:\
meta-qcom-robotics-sdk/ci/qcom-robotics-proprietary-image.yml:\
meta-qcom-robotics-sdk/ci/linux-qcom-6.18.yml

构建会将可刷写的镜像写入到 build/tmp/deploy/images/<MACHINE>/<TARGET>-<MACHINE>.rootfs.qcomflash。

生成 QIR SDK 产物

kas build \
  meta-qcom-robotics-sdk/ci/iq-9075-evk.yml:\
meta-qcom-robotics-sdk/ci/qcom-robotics-distro.yml:\
meta-qcom-robotics-sdk/ci/qcom-robotics-image.yml:\
meta-qcom-robotics-sdk/ci/linux-qcom-6.18.yml \
  -c generate_qirp_sdk

产物位于 build/tmp/deploy/qirpsdk_artifacts/<MACHINE>/qirp_sdk.tar.gz。

刷写并验证

使用与评估场景相同的命令序列，用 qdl 刷写 .qcomflash 镜像，然后重新运行 qrb_ros_system_monitor 以确认功能一致。

在您的 Ubuntu 镜像中跟踪 Qualcomm PPA

将 ppa:ubuntu-qcom-iot/qcom-ppa 和 ppa:ubuntu-qcom-iot/qirp 烘焙到您的 Ubuntu 镜像 recipe 或 preseed 中，以便设备自动接收更新。

将 QIR SDK 包固定到正确的变体

在 server 镜像上发布 qirp-sdk，在 desktop 镜像上发布 qirp-sdk-desktop。

发布并验证

将您的 ROS 2 节点作为 .deb 文件从私有 apt 仓库或 PPA 发布，然后运行以下命令以刷新设备上的 QIR SDK 而不破坏任何自定义 launch 文件：

 sudo apt update && sudo apt upgrade qirp-sdk

当您的构建流水线为每个受支持的机器生成目标镜像或包，并且自定义镜像通过评估场景示例时，流程即完成。

后续步骤

端到端示例 — 针对图像分类和手部检测的演练，包含已发布的输入图像。

​前提条件

​场景工作流

​工作流图

​运行示例工作流

​工作流图

​运行示例工作流

​工作流图

​按技术领域的生产关注点

​视觉

​多媒体

​AI 推理和零拷贝

​工具

​运行示例工作流

​后续步骤

前提条件

场景工作流

工作流图

运行示例工作流

工作流图

运行示例工作流

工作流图

按技术领域的生产关注点

视觉

多媒体

AI 推理和零拷贝

工具

运行示例工作流

后续步骤