Scenarios - Qualcomm Dragonwing Documentation

The QIR SDK supports three scenarios that share the same underlying workflow — provision the device, install the QIR SDK, configure ROS 2 Jazzy, and run a sample. Each of the following tabs opens the workflow diagram and an end-to-end example for that scenario. See the device, operating system, and scenario selectors on the Start page.

Prerequisites

A supported development kit. See the device matrix on the Start page.
An Ubuntu 24.04 host (recommended). Windows and macOS hosts work for Qualcomm Linux flashing.
A USB Type-C cable, the power supply for your kit, and network access on Wi-Fi or Ethernet.
A serial-console tool (for example, minicom) if you plan to use the debug UART.

Scenario workflow

Follow the tab that matches your scenario. Within each tab, the workflow diagram shows the stages that scenario adds, and the runnable example walks the full sequence with a single working sample.

Evaluate
Development
Production

Use the Evaluate scenario to prove that a Qualcomm Dragonwing™ development kit or the Ventuno Q board can run your target workload with the smallest possible commitment. The path stays on prebuilt binaries: a flashed robotics image (Qualcomm Linux) or an apt-installed qirp-sdk (Ubuntu), and stock sample applications from the QIR SDK catalog.

Workflow diagram

The following diagram shows the common stages of the Evaluate workflow across both operating systems.

Run an example workflow

Follow the OS tab for a real, minimal sequence that ends with a stock sample running on the device.

Qualcomm Linux
Ubuntu

Download the robotics image

Download qli-2.1-qcom-robotics-image.zip for your machine from CodeLinaro. The URL pattern is

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

, where <machine> is iq-9075-evk or 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

Flash the robotics image with QDL

Put the device in Emergency Download (EDL) mode, provision Universal Flash Storage (UFS), flash the security island (SAIL) firmware, then flash the robotics image with the Qualcomm® Device Loader (qdl) tool.

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

Flashing is complete when the final line reads partition 1 is now bootable. Toggle the SW2-3 DIP switch down and power-cycle the device.

Set up QIR SDK and ROS2 environment on the device

Start two terminals, and run the following commands in each terminal.

ssh root@[ip-addr]

SSH Session

source /usr/share/qirp-setup.sh

Run the system monitor ROS node

In terminal 1, run the system monitor ROS node.

SSH Session

ros2 run qrb_ros_system_monitor qrb_ros_system_monitor

The output looks like this:

[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

Check the system information

In terminal 2, check the ROS topics with ros2 topic list.

SSH Session

ros2 topic list

Output

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

Check the CPU information with ros2 topic echo /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
---

Flash Ubuntu and connect to Wi-Fi

Flash the Ubuntu image for your kit, then connect over Wi-Fi.

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

For VENTUNO Q, you can use the App Lab to set up the connection and network.

Add the ROS 2 and Qualcomm package sources

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

Install the QIR SDK and run the sample

Install qirp-sdk (server image) or qirp-sdk-desktop (desktop image) on your device, set up the runtime environment and run the system monitor sample application.

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

In a second shell, get the topics of this node and check system status as needed.

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

Use the Development scenario to move from running samples to writing your own. The path adds the QIR SDK cross-compile toolchain, a ROS 2 build step, and a deploy step on top of the Evaluate baseline.

Workflow diagram

The following diagram shows the stages of the Development workflow.

Run an example workflow

Follow the OS tab for a real cross-compile or on-device build sequence.

Qualcomm Linux
Ubuntu

Source the QIR SDK environment

Extract the QIR SDK toolchain on the host and source the setup script.

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

Fetch, modify, and cross-compile the talker

Clone the ROS 2 demos repository, edit the message payload in talker.cpp, then build with the QIR SDK toolchain.

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

Change line 46 to:

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

Build:

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

Deploy and run on the device

Package the build output, push it to the device, extract it into /usr/ros/jazzy/, then run the talker and listener in two SSH sessions.

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

On the device:

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

You are done when the talker prints Publishing: 'Hello World : Qualcomm : N' and the listener echoes I heard: [Hello World : Qualcomm : N].

Install ROS 2 build dependencies

On the Ubuntu device, install the ROS 2 build dependencies for sample_resnet101.

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

Clone and build the sample from source

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

Launch the sample

ros2 launch sample_resnet101 launch_with_image_publisher.py

You are done when /resnet101_output streams classification labels (Ubuntu).

Use the Production scenario when your team owns a product design that ships a Qualcomm Dragonwing™ platform to end customers. The scenario adds a repeatable build pipeline, per-technology-area pinning of the QRB ROS packages you rely on, and the validation you run before every release. The Yocto build produces the exact image and QIR SDK artifacts you ship; the Debian packaging path produces the exact .deb files your fleet installs.

Workflow diagram

The following diagram shows the stages of the Production workflow, from finished development through validated release.

Production concerns by technology area

The QRB ROS stack groups into four technology areas — Vision, Multimedia, AI inference and Zero-copy, and Tooling. Pin the packages that belong to each area, then validate the area with the corresponding regression sample before you cut a release.

Vision

Vision production covers cameras, depth sensors, and 2D lidar. The following table lists the QRB ROS packages, matching regression samples, and production concerns for the Vision area.

QRB ROS package	Regression sample	Production concerns
`qrb_ros_camera`	`sample_object_detection`	Pin the CSI or GMSL sensor driver version. On Qualcomm Linux, `qrb_ros_camera` depends on the CamX camera stack — freeze the CamX release together with the kernel.
`qrb_ros_image_resize`	`sample_resnet101` (preprocess node)	Confirm the resize output matches the tensor shape your model expects. A drift here silently degrades accuracy.
`orbbec_camera`	`follow-me`	Lock the Orbbec Gemini firmware version validated against the driver. Rebuild the driver when you bump firmware.
`rplidar-ros2`	`cartographer_node`	Lock the RPLIDAR firmware version. `rplidar-ros2` behavior differs between A1/A2/A3/S1/S2/S3 — validate on the exact model your product ships.

Multimedia

Multimedia production covers video capture and encode, audio pipelines, and color-space conversion. The following table lists the packages, samples, and concerns for the Multimedia area.

QRB ROS package	Regression sample	Production concerns
`qrb_ros_video`	`qrb_ros_video` platform sample	Confirm codec licensing (H.264, H.265) covers your deployment region. Pin the `iris-video-dlkm` kernel module version.
`qrb_ros_audio_service`	`qrb_ros_audio_service` platform sample	Fix sample rate, channel count, and acoustic echo cancellation (AEC) or noise-suppression defaults. Audio drift is silent — capture reference recordings before ship.
`qrb_ros_colorspace_convert`	`qrb_ros_colorspace_convert` platform sample	On Ubuntu, the desktop image variant excludes color-space packages. Pin the server variant (`qirp-sdk`) if your pipeline needs color-space conversion.

AI inference and Zero-copy

AI inference production covers model loading, execution, and the zero-copy transport that keeps AI pipelines within Qualcomm hardware buffers. The following table lists the packages, samples, and concerns for the AI inference and Zero-copy area.

QRB ROS package	Regression sample	Production concerns
`qrb_ros_nn_inference`	`sample_resnet101`, `sample_object_detection`	Pin the Qualcomm® AI Engine Direct SDK (QNN) runtime version that matches your compiled model files. Bake `.bin` context binaries into the image or a signed over-the-air payload.
`qrb_ros_transport`	`qrb_ros_benchmark`	Verify zero-copy transport (ROS Enhancement Proposal (REP) 2007) works with your custom nodes. Qualcomm hardware buffers require the alignment `qrb_ros_transport` documents.

Tooling

Tooling production covers the development toolchain, on-device diagnostics, and the performance monitors you use to catch regressions. The following table lists the packages and concerns for the Tooling area.

QRB ROS package or asset	Purpose	Production concerns
`qrb_ros_system_monitor`	Publishes system status topics for on-device diagnostics.	Route the system-status topics into your fleet telemetry so you can debug field failures.
`qrb_ros_benchmark`	Benchmarks ROS 2 component throughput and latency.	Automate `qrb_ros_benchmark` runs in regression CI. Set explicit bounds on per-model latency and throughput; fail the build when a bound is crossed.
QIR SDK cross-compile toolchain	Host-side toolchain for building `aarch64-oe-linux` binaries.	Ship the toolchain inside your development container image so every engineer builds against the exact same version.
Single-command setup script	`source /usr/share/qirp-setup.sh` on the device.	Bake the script into the image and gate any custom launch files on its side effects (environment variables, `ROS_DOMAIN_ID`).

Overlays are an optional Qualcomm Linux path that expands a base robotics image into the proprietary stack on a running device without reflashing. Production teams that already build qcom-robotics-proprietary-image do not need overlays. For teams that do want the overlay path, see the QIR SDK user guide (Linux).

Run an example workflow

Follow the OS tab for a real KAS build (Qualcomm Linux) or Debian packaging setup (Ubuntu).

Qualcomm Linux (Yocto)
Ubuntu (Debian packaging)

Set up the build host and install 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

Clone the robotics layer and build the image

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

The build writes the flashable image to build/tmp/deploy/images/<MACHINE>/<TARGET>-<MACHINE>.rootfs.qcomflash.

Generate the QIR SDK artifacts

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

The artifacts land at build/tmp/deploy/qirpsdk_artifacts/<MACHINE>/qirp_sdk.tar.gz.

Flash and validate

Flash the .qcomflash image with qdl using the same command sequence as the Evaluate scenario, then re-run qrb_ros_system_monitor to confirm parity.

Track the Qualcomm PPA in your Ubuntu image

Bake ppa:ubuntu-qcom-iot/qcom-ppa and ppa:ubuntu-qcom-iot/qirp into your Ubuntu image recipe or preseed so devices receive updates automatically.

Pin the QIR SDK package to the correct variant

Ship qirp-sdk on server images and qirp-sdk-desktop on desktop images.

Publish and validate

Publish your ROS 2 nodes as .deb files from a private apt repository or PPA, then run the following command to refresh the QIR SDK on the device without breaking any custom launch files:

 sudo apt update && sudo apt upgrade qirp-sdk

The procedure is complete when your build pipeline produces the target image or package for every supported machine and the custom image passes the Evaluate scenario sample.

Next steps

End-to-end samples — walkthroughs for image classification and hand detection with published input images.

​Prerequisites

​Scenario workflow

​Workflow diagram

​Run an example workflow

​Workflow diagram

​Run an example workflow

​Workflow diagram

​Production concerns by technology area

​Vision

​Multimedia

​AI inference and Zero-copy

​Tooling

​Run an example workflow

​Next steps

Prerequisites

Scenario workflow

Workflow diagram

Run an example workflow

Workflow diagram

Run an example workflow

Workflow diagram

Production concerns by technology area

Vision

Multimedia

AI inference and Zero-copy

Tooling

Run an example workflow

Next steps