×

Arduino VENTUNO Q 开发路线全解:App Lab / SBC / 纯开发者三条路径、32 篇官方教程与 Bridge/ROS 2 工具链

2026-11-19


Arduino VENTUNO Q 开发路线全解:App Lab / SBC / 纯开发者三条路径、32 篇官方教程与 Bridge/ROS 2 工具链







Arduino VENTUNO Q

Arduino × Qualcomm · 边缘 AI 开发平台

Arduino VENTUNO Q:一颗 QCS8275 跑 Ubuntu 与 40 dense TOPS AI,一颗 STM32H5F5 跑 Zephyr 实时控制,中间用 RPC Bridge 打通。

这块板值得看的不是「40 TOPS」一个数字,而是双脑架构、App Lab 工具链、官方模型库与 ROS 2 桥接能不能把「感知—决策—执行」放进同一台设备。

一、三条上手路线:先选一条,不要混着走

VENTUNO Q 的文档把上手方式分成三条:App Lab 一键跑、SBC 裸机模式、刷 Ubuntu 的纯开发者模式。三条路线解决的是不同问题,第一次上手建议按顺序走,不要同时装三种工具链。

VENTUNO Q 三条上手路线
图 1:App Lab 适合验证 AI 与做 demo,SBC 模式适合当 Linux 主机,纯开发者模式适合接管系统与自研栈。
路线 适合谁 入口 能用到什么
A. App Lab 一键跑 第一次接触、做 demo、教学 First Setup → Examples → Run 预置 App、Bricks、AI 模型、板载 IDE
B. SBC 裸机模式 把板子当 Linux 主机、接屏做 Kiosk SBC Mode Setup + User Manual HDMI/键鼠、Ubuntu 桌面、App Lab
C. 纯开发者模式 已有自研栈、要接管系统 EDL 刷 Ubuntu → SSH/ADB → 自装工具 完整 Ubuntu、Docker、VS Code、Python

配套的必读顺序是:User Manual → Power Specifications → NPU Guide → Bridge → 按场景选 AI Workflows 或 Robotics。先看供电规格,是为了避免在供电不足的情况下刷机或跑满载模型。

二、App Lab 的工程结构:Sketch、Python 与 Bricks

App Lab 是预装在板上的开发环境,一个 App 由三部分组成:跑在 MCU 上的 Sketch、跑在 Ubuntu 上的 Python,以及可复用的 Bricks。点一次 Run,工具会编译 Sketch、构建 Linux 侧、部署并启动。

组成部分 位置 运行位置 负责什么
Sketch sketch/sketch.ino STM32H5F5 实时 I/O、电机、CAN-FD、PWM、GPIO
Python python/main.py Ubuntu / QCS8275 AI 推理、网络、业务逻辑、UI
Bricks 工程内引用 两侧均可 AI、Web、IoT 的可复用模块
自定义 Brick 工程内新增 按实现 把常用能力封装成可复用组件

Bricks 是 App Lab 的核心抽象。官方提供 AI 模型、Web 服务、IoT 连接等 Brick,也可以自己写 Custom Brick。工程结构固定,意味着同一套代码可以在不同 VENTUNO Q 之间迁移。

三、路线 A:App Lab 一键跑

步骤 做什么 检查点
1 USB-C 供电,等待板子启动 电源指示灯、板载 UI 是否正常
2 按 First Setup 连接 App Lab 电脑能找到板子,网络配置完成
3 打开 Examples,跑一个现成 App App 能启动,日志无报错
4 打开摄像头相关示例 CSI 相机出图,NPU 推理正常
5 修改 Python 或 Sketch 的一个参数 重新 Run 后行为变化
6 保存工程,导出或分享 工程结构完整,依赖可复现

第一次跑示例时,优先选不依赖外部硬件的 App;确认板子、网络、摄像头与 NPU 都正常后,再接入电机、CAN 或传感器。如果示例跑不起来,先看供电与日志,不要急着刷系统。

四、路线 B:SBC 裸机模式

步骤 做什么 说明
1 接 HDMI 显示器、键鼠 HDMI 与 DSI 复用,接 HDMI 时 DSI 不可用
2 USB-C 或 DC 供电 满载建议用 DC 12–24V
3 进入 Ubuntu 桌面 标准 Linux 桌面环境
4 在板内打开 App Lab 不依赖外部电脑
5 配置网络与显示 Wi-Fi、2.5GbE、分辨率

SBC 模式适合做 Kiosk、数字标牌、边缘网关的早期验证。它和普通 Ubuntu 主机没有本质区别,但要注意 HDMI/DSI 复用与 6GHz 频段的合规配置。

五、路线 C:纯开发者模式

步骤 做什么 工具 / 注意
1 阅读 Power Specifications 确认供电能力,避免刷机中断
2 进入 EDL 模式 按官方按键与启动模式说明操作
3 用 arduino-flasher-cli 刷 Ubuntu 官方镜像,刷写过程不要断电
4 SSH 或 ADB 连接 板内已装 Docker 与 apt
5 安装 VS Code、Python、ROS 2 按项目需要选择
6 接管系统服务 systemd、网络、显示、摄像头
7 做自己的 OTA 与恢复方案 保留 EDL 刷机路径作为兜底

纯开发者模式适合已有自研栈的团队。刷机前先确认镜像版本与板子硬件版本匹配,刷机后先跑一次官方示例,确认 NPU 与摄像头正常,再装自己的依赖。

六、Bridge 与 RPC:Linux 和 MCU 怎么互相调用

Bridge 不是串口 AT 指令,而是 MsgPack-RPC。板内有 arduino-router 服务,Linux 侧用 arduino-router-bridge,MCU 侧用 Arduino_RouterBridge,双方通过 Bridge.call() 与 Bridge.provide() 暴露函数。

组件 位置 作用
arduino-router 板内服务 RPC 路由
arduino-router-bridge Python 侧 Linux 调用 MCU / 反向调用
Arduino_RouterBridge MCU 侧 C++ 库 提供与调用函数
Bridge.call() 两侧 API 调用对方暴露的函数
Bridge.provide() 两侧 API 把自己函数暴露给对方
Arduino_RouterBridge_ROS MCU 侧 在 Sketch 里直接写 ROS 2 节点

典型用法:Linux 侧把视觉结果通过 Bridge.call() 传给 MCU,MCU 更新电机目标;MCU 侧把编码器或急停状态通过 Bridge.provide() 暴露给 Linux。这样既保留 Linux 的 AI 能力,又保留 MCU 的确定性。

七、Arduino IDE 与 Zephyr:只开发 MCU

项目 说明
开发环境 Arduino IDE 2.x(Beta)
板级核心 Arduino Q Board Core(基于 Zephyr)
可开发内容 数字/模拟口、ADC/DAC、PWM、UART/I2C/SPI、MCU 侧 Wi-Fi
不能开发 NPU、Linux 侧摄像头、本地大模型
适合场景 电机控制、传感器采集、实时逻辑

只用 Arduino IDE 的路线适合传统嵌入式工程师:不碰 Ubuntu,不装 Docker,但也就用不到 40 TOPS 的 NPU。需要 AI 时仍然要回到 App Lab 或 Linux 侧。

八、AI Workflows:12 篇官方教程覆盖的五条路径

AI 是这块板的核心卖点,官方把教程集中在 AI Workflows 分类,共 12 篇。这些教程覆盖的不是一个工具,而是五条不同的模型上板路径,选错路径会直接导致性能误判。

教程 路径 关键点
Understanding and Using the NPU 总览 NPU 与 CPU/GPU 的分工、三条上 NPU 的路径、Burst/Default 功耗模式
Getting Started with Qualcomm AI Hub AI Hub 预优化模型导出、参考 demo、实时摄像头
Running Local LLMs llama.cpp 跑 Adreno GPU,可切 GenieX/NPU 对比
LLM/VLM on NPU with GenieX GenieX NPU 推理、VLM、OpenAI 兼容 API
ONNX Runtime QNN EP ONNX Runtime + QNN EP 上 NPU,含动态 shape 修复
Running Ollama CPU Ollama 跑 CPU,不是 NPU
Edge Impulse 自训模型 视觉/音频/传感模型训练、量化、回板
Face Detection 视觉 demo face_det_lite 实时人脸检测
Face Mesh 视觉 demo mediapipe_face 468 点人脸网格
Eye Gaze Tracking 视觉 demo 双眼注视方向估计
Semantic Segmentation 视觉 demo SegFormer 实时语义分割
Installing OpenClaw Agent OpenClaw + Telegram bot + 模型/API Key
VENTUNO Q 的五条模型上板路径
图 2:AI Hub、GenieX、ONNX Runtime QNN EP、llama.cpp GPU、Ollama CPU 是五条不同路径,不能把它们的速度混在一起比较。

最容易踩的坑是 Ollama:它跑在 CPU 上,速度与 NPU 路线没有可比性。要让模型吃 NPU,走 GenieX、ONNX Runtime QNN EP 或 AI Hub 导出的预优化模型。

九、模型库与运行时:开箱能跑什么

类别 官方预置 / 支持 运行时
LLM Qwen 3 4B GenieX / llama.cpp / AI Hub
VLM Qwen 2.5 7B、Qwen 3 4B GenieX / llama.cpp
小型语言模型 Gemma 4 E2B / E4B GenieX / AI Hub
语音识别 Whisper AI Hub / ONNX
语音合成 Melo TTS、Piper TTS AI Hub / ONNX
视觉检测 YOLOX small、MediaPipe 手势 AI Hub / QNN
自定义模型 Edge Impulse 训练与量化 App Lab Brick / 独立 Linux
Agent 框架 OpenClaw Linux 侧 Python 服务

官方模型库会持续增加。选型时先确认目标模型是否在 AI Hub 的预优化列表里;不在列表里的模型,需要自己走 ONNX → QNN 转换,工作量与算子覆盖要提前评估。

十、ROS 2 Jazzy 与 ros2ino:MCU 草图直接发 ROS 话题

VENTUNO Q 官方支持 ROS 2 Jazzy,并提供 RGB 相机、RGBD 相机、LiDAR 三条感知教程。更有意思的是 ros2ino:通过 Arduino_RouterBridge_ROS,可以在 MCU Sketch 里直接发布/订阅 ROS 2 话题。

教程 / 组件 内容 用途
Getting Started with ROS 2 装 ROS 2 Jazzy、turtlesim、第一个 pub/sub 确认 ROS 2 环境
RGB Cameras with ROS 2 USB 摄像头 + CSI 相机 → 图像话题 视觉感知
RGBD Cameras with ROS 2 RealSense SDK + ROS wrapper、点云、RViz2 深度感知
LiDAR with ROS 2 RPLidar / LDROBOT → /scan 避障与 2D 建图
Arduino_RouterBridge_ROS MCU 侧 ROS 2 库,ros2ino 命名空间 Sketch 直接发话题
arduino_router_ros ROS 2 侧 arduino_proxy 节点 把 MCU 接进 ROS 2 图

ros2ino 的价值是省掉一个桥接节点:MCU 采集的传感器数据、电机状态可以直接变成 ROS 2 话题,不需要在 Linux 侧再写一层转发。这套思路也可以移植到 RK3588 + STM32 的自研架构。

十一、官方 GitHub 仓库与文档源

仓库 作用 许可
arduino/arduino-app-lab App Lab IDE 本体(Wails 跨平台) 开源
arduino/app-bricks-py 官方 Brick 的 Python 实现 开源
arduino/arduino-router 板内 RPC router 服务 开源
arduino/arduino-router-bridge-py Python 侧 Bridge 库 开源
arduino-libraries/Arduino_RouterBridge MCU 侧 Bridge C++ 库 MPL-2.0
arduino-libraries/Arduino_RouterBridge_ROS MCU 侧 ROS 2 库(ros2ino) MPL-2.0(WIP)
arduino/arduino_router_ros ROS 2 侧 arduino_proxy 节点 开源
arduino/arduino-flasher-cli EDL 刷机 CLI 开源
arduino/docs-content 官方文档 Markdown 源,可提 PR CC BY-SA 4.0
官方教程分类与数量
图 3:资料整理时点可逐条核对的 32 篇教程,按 First Steps、Guides、AI Workflows、Linux、Robotics、Use Cases 分类。

文档源是公开的,遇到错误可以直接提 PR。对做二次开发或写内部培训材料的团队,docs-content 比抓网页更可靠,也方便固定版本。

十二、学习顺序与 8 个常见坑

坑 / 顺序 现象 处理
先刷机后看文档 供电不足、刷写中断 先读 Power Specifications,再刷
把 Ollama 当 NPU 速度远低于预期 改用 GenieX / ONNX QNN / AI Hub
M.2 当系统盘 无法启动 系统留 eMMC,M.2 只做数据盘
CSI 数量按 5 路算 相机无法同时出图 3 路板载与 2 路 JMEDIA 是复用
HDMI + DSI 双屏 DSI 无输出 两者共用 DSI 线,先定方案
CAN 直接接电机 通信失败 只有 1 路带 PHY,其余需外加收发器
用开发板直接量产 认证/散热/供货不合格 转生产级 SoM
忽略 6GHz 合规 整机认证不过 按地区复核频段与功率

推荐顺序:User Manual → Power Specifications → First Setup → NPU Guide → Bridge → 按场景选 AI Workflows 或 Robotics。每一步都跑一个最小示例,确认环境正常再往下走。

常见问题(FAQ)

Q1:第一次上手应该走哪条路线?

A:先用 App Lab。接 USB-C 供电,按 First Setup 连上 App Lab,从 Examples 里跑一个现成 App,确认板子、摄像头、网络与 NPU 都正常,再决定往 SBC 或纯开发者模式走。一上来就刷 Ubuntu、装 Docker,会把排障变量放得太多。

Q2:App Lab 的工程为什么有三个部分?

A:一个 App 由 sketch/sketch.ino、python/main.py 与 Bricks 组成:Sketch 跑在 STM32H5 上,负责实时 I/O;Python 跑在 Ubuntu 侧,负责 AI、网络与业务;Bricks 是可复用的 AI/Web/IoT 模块。点一次 Run,工具会依次编译 Sketch、构建 Linux 侧、部署并启动。

Q3:Bridge 是串口协议吗?

A:不是简单的串口 AT 指令。Linux 与 MCU 之间走 MsgPack-RPC,板内有 arduino-router 服务,Python 侧用 arduino-router-bridge,MCU 侧用 Arduino_RouterBridge。调用方式是 Bridge.call() 与 Bridge.provide(),可以把 MCU 的函数暴露给 Linux,也可以反向调用。

Q4:只想写 Arduino Sketch,不碰 Linux,可以吗?

A:可以。装 Arduino Q Board Core(基于 Zephyr),用 Arduino IDE 2.x 单独开发 MCU,数字/模拟口、ADC/DAC、PWM、UART/I2C/SPI 都能用。但 NPU、摄像头与本地大模型跑在 Linux 侧,纯 Sketch 路线用不到这部分能力。

Q5:Ollama 在 VENTUNO Q 上跑的是 NPU 吗?

A:不是。官方教程明确 Ollama 跑在 CPU 上。要让模型上 NPU,走 GenieX、ONNX Runtime 的 QNN EP,或用 Qualcomm AI Hub 导出预优化模型。把 Ollama 的 tokens/s 当成 NPU 性能,是最常见的误判。

Q6:llama.cpp 用的是 GPU 还是 NPU?

A:官方 llama.cpp 教程走 Adreno GPU;同一模型可以再切到 GenieX/NPU 做对比。两条路径的量化格式、算子覆盖与速度不同,不能把 GPU 的数字直接当 NPU 成绩。

Q7:ROS 2 一定要在 Linux 侧写节点吗?

A:不一定。官方提供 Arduino_RouterBridge_ROS 与 ros2ino 命名空间,可以在 MCU Sketch 里直接发布/订阅 ROS 2 话题,Linux 侧由 arduino_proxy 节点接进 ROS 2 图。VENTUNO Q 是目前官方说明里唯一支持这套用法的板子。

Q8:官方教程到底有多少篇?

A:按资料整理时点可逐条核对的链接是 32 篇,分为 First Steps 5 篇、Guides 4 篇、AI Workflows 12 篇、Linux 2 篇、Robotics 4 篇、Use Cases 4 篇,另有 RetroArch 1 篇。官方文档仍在更新,数量会继续增加。

Q9:刷机刷坏了怎么恢复?

A:用 EDL 模式配合 arduino-flasher-cli 重新刷 Ubuntu 镜像。官方有单独的 Flashing the Ubuntu Image 教程,刷机前先看 Power Specifications,避免供电不足导致刷写中断。

联系我们 · Arduino / 高通平台评估与方案对接

深圳市爱派派智能科技有限公司(爱派派智能)

地址:深圳市坪山区创新广场C栋1805

电话:18681465731

联系人:李先生

官网:https://ai-paipai.com

说明:参数来自 Arduino 官方数据表、商店页与文档,配图为自绘;价格、库存与交期以官方商店为准。

↑