QIR ROS SDK（Advantech QIR ROS Kit）

本文件介紹我們所提供的 qir_ros_base / QIR ROS SDK 容器化開發與範例框架。
此框架可協助使用者在研華 Qualcomm 平台上快速執行 QIR ROS 2 官方範例，並可在相同框架基礎上進一步開發自己的應用程式（App）。

提示

• 第一次執行範例時，系統可能會自動下載或安裝所需資源，例如 Qualcomm Neural Processing SDK 模型、資料集或相依套件。這屬於正常現象，因此第一次執行可能需要較長的時間。

資訊

版本資訊（預設環境）
QIR ROS SDK：v2.4.3
ROS 2：Jazzy

---

1. QIR ROS SDK 簡介

QIR ROS SDK 是一套針對 Qualcomm Snapdragon / QRB 平台最佳化的硬體加速 ROS 2 套件。透過 Hexagon / Qualcomm Neural Processing Engine（SNPE）與 QNN 引擎使用 Qualcomm NPU 硬體加速，提供高效能的機器人演算法，包括電腦視覺、AI 感知、OCR、深度估測與模擬工作流程等。

在研華 Qualcomm 平台上，QIR ROS SDK 透過 Docker 容器提供穩定一致的執行環境，降低系統相依性衝突，讓開發者能更專注於應用程式部署。

---

2. 為什麼使用此套件（優勢與 qir_ros_base 提供的功能）

qir_ros_base 提供一套可直接使用的 QIR ROS SDK 開發環境，並以 Docker 容器的形式封裝。

此環境可協助使用者快速評估 Qualcomm 機器人相關功能，並在一致且可重現的環境基礎上開發自己的應用程式。

主要優勢包括：

• 快速啟動：無需花費大量時間進行複雜的驅動程式與 SDK 環境設定，即可快速執行 QIR ROS 範例。

• 可重現的開發環境：透過一致的容器化工作流程，降低不同系統環境之間的差異。

• 降低環境設定成本：常用的相依套件與執行環境需求已整合於容器工作流程中。

• 提供客製化開發基礎：使用者可在既有框架上進一步整合自己的 Pipeline 與應用程式。

• 更容易進行故障排除與維護：環境變更彼此隔離，使版本更新與回復更容易管理。

參考資料：QIR ROS SDK Documentation

---

3. 安裝位置與結構

注意

請確認目標系統符合以下條件：

• 研華平台
• 至少 20 GB 的可用磁碟空間
• 需要可正常使用的網路連線
• Ubuntu OS 請使用英文語系環境

資訊

Host 相依套件檢查（Qualcomm AI Runtime - QAIRT）

• 若要使用 AI 與 NPU 功能，請確認 Host 系統已安裝 Qualcomm AI Runtime（QAIRT）。否則將無法存取 NPU 硬體資源。
• **Host 端確認方式：**檢查 /usr/lib/libQnnHtp.so 函式庫檔案是否存在。

ls -l /usr/lib/libQnnHtp.so 

依照安裝程式說明選擇並安裝 QIR ROS Development Environment 功能後，可在以下位置找到相關套件：

• QIR ROS Kit 根目錄：

  • /usr/local/Advantech/ros/container/ros-demokit/qir_ros_kit

主要內容如下：

• 啟動入口：

  • launch_qir.sh

• 範例應用程式：

  • apps/basic_examples（QIR 官方基礎範例）

  • apps/advanced_examples（進階整合範例）

• 開發框架：

  • apps/develop（開發容器的使用方式與範本說明）

---

4. 使用方式：透過單一指令啟動範例

概述

User
  │
  ▼
launch_qir.sh
  │
  ▼
Docker Container (QIR ROS environment)
  │
  ├─ (first run / as needed) install_app.sh: download/install required assets & models
  │
  └─ (every run) run_app.sh: start the example (e.g., ros2 launch ...)

使用方式如下：

cd /usr/local/Advantech/ros/container/ros-demokit/qir_ros_kit

./launch_qir.sh <app_folder> [optional parameters...]

• <app_folder> 為 apps/ 目錄下的相對路徑，例如：

  • basic_examples/ocr_service

  • basic_examples/sample_object_detection

  • basic_examples/simulation_sample_pick_and_place

快速啟動範例如下：

./launch_qir.sh basic_examples/sample_object_detection

提示

ROS_DOMAIN_ID（預設值：55）

• 此套件預設使用 ROS_DOMAIN_ID=55。

• 如需修改，請編輯 launch_qir.sh 中的 ROS_DOMAIN_ID 設定。

---

5. 基本範例（QIR 官方範例）

以下範例位於：

• /usr/local/Advantech/ros/container/ros-demokit/qir_ros_kit/apps/basic_examples

主要用途：

• 快速驗證 QIR NPU 硬體加速與官方節點是否能在目標平台上正常執行。

• 作為後續開發的起點，可沿用相同的啟動與安裝框架進一步擴充功能。

5.0 YOLOv8 範例前置需求（模型匯出說明）

注意

由於 YOLOv8 的授權限制，本套件不包含預先轉換完成的 YOLOv8 模型檔案（yolov8_det.bin 與 yolov8_seg.bin）。

在啟動 sample_object_detection 或 sample_object_segmentation 之前，使用者必須自行匯出模型檔案，並將其放置到對應範例的目錄中。

前置需求

1. 建立 Qualcomm 帳號，並透過 Qualcomm AI Hub 申請 api_token。
2. 詳細前置需求請參考 Qualcomm 官方文件：

• Object Detection Prerequisites
• Object Segmentation Prerequisites

在 Host 系統上匯出模型

# 安裝 Python virtual environment 相依套件
sudo apt update
sudo apt install -y python3.12-venv

# 建立並啟用 Python virtual environment
python3 -m venv qai_env
source qai_env/bin/activate

# 安裝必要的 Python 套件
pip install --upgrade pip
pip install qai_hub_models
pip install ultralytics

# 使用 API token 設定 Qualcomm AI Hub
qai-hub configure --api_token <YOUR_API_TOKEN>

# 匯出 YOLOv8 Detection 模型
python3 -m qai_hub_models.models.yolov8_det.export --target-runtime tflite --device "Dragonwing IQ-9075 EVK"

# 匯出 YOLOv8 Segmentation 模型
python3 -m qai_hub_models.models.yolov8_seg.export --target-runtime tflite --device "Dragonwing IQ-9075 EVK"

將轉換完成的模型移至 App 目錄

成功匯出模型後，請將產生的 .bin 檔案複製到對應的 model/ 目錄：

1. Detection Model：

   • 將 yolov8_det.bin 複製至：
     /usr/local/Advantech/ros/container/ros-demokit/qir_ros_kit/apps/basic_examples/sample_object_detection/model/

2. Segmentation Model：

   • 將 yolov8_seg.bin 複製至：
     /usr/local/Advantech/ros/container/ros-demokit/qir_ros_kit/apps/basic_examples/sample_object_segmentation/model/

5.1 ocr_service

• 用途：使用 Qualcomm NPU 對輸入影像串流執行光學字元辨識（OCR），即時偵測並擷取文字內容。

• 執行：

  ./launch_qir.sh basic_examples/ocr_service

• 官方文件：

  • Qualcomm ocr_service

5.2 sample_object_detection

注意

需要 yolov8_det.bin 模型檔案。請先完成5.0 YOLOv8 範例前置需求（模型匯出說明）

• 用途：透過 Qualcomm NPU 加速的神經網路模型執行即時 2D 物件偵測。

• 執行：

  ./launch_qir.sh basic_examples/sample_object_detection

• 官方文件：

  • Qualcomm detect-objects-with-sample_object_detection

5.3 sample_object_segmentation

注意

需要 yolov8_seg.bin 模型檔案。請先完成5.0 YOLOv8 範例前置需求（模型匯出說明）

• 用途：使用 Qualcomm NPU 執行 Instance / Semantic Segmentation，提供像素層級的物件邊界資訊，可用於進階空間感知。

• 執行：

  ./launch_qir.sh basic_examples/sample_object_segmentation

• 官方文件：

  • Qualcomm sample_object_segmentation

5.4 sample_depth_estimation

• 用途：使用 Qualcomm NPU 進行單目或雙目視覺深度估測，推算每個像素的深度資訊，可應用於障礙物迴避與 3D 感知。

• 執行：

  ./launch_qir.sh basic_examples/sample_depth_estimation

• 官方文件：

  • Qualcomm sample_depth_estimation

5.5 simulation_sample_pick_and_place

• 用途：在 Gazebo 中執行模擬工作流程，展示機器手臂運動規劃與 Pick-and-Place 任務執行。

• 執行：

  ./launch_qir.sh basic_examples/simulation_sample_pick_and_place

• 官方文件：

  • Qualcomm simulation_sample_pick_and_place

5.6 simulation_follow_me

• 用途：透過模擬場景展示目標人物偵測、視覺追蹤，以及機器人自主跟隨導航。

• 執行：

  ./launch_qir.sh basic_examples/simulation_follow_me

• 官方文件：

  • Qualcomm simulation_follow_me

---

6. 建立自己的應用程式

在每個 App 目錄中，都可以找到以下檔案：

• install_app.sh：用於執行安裝與環境準備步驟，例如下載所需資源、安裝相依套件及初始化環境。

• run_app.sh：用於設定啟動與執行指令，通常為 ros2 launch ...。

您可以依照以下方式建立自己的 App：

1. 複製現有的範例目錄，或使用 apps/develop 作為範本。

2. 將所需的環境設定與安裝步驟加入 install_app.sh。

3. 將 ROS 2 的啟動與執行指令加入 run_app.sh。

4. 使用相同的入口指令啟動您的 App：

   ./launch_qir.sh <your_app_path>