XGO Duck AI 版本与安装 · XGO-Duck

XGO Duck AI 在 Arduino UNO Q 上提供语音聊天、USB 摄像头、音频、可选 ToF 测距及运动控制。本指南适用于版本 0.2.36；实际设备功能以安装版本和外设为准。

需要什么	入口
账号绑定、唤醒和语音	AI 绑定与语音聊天
摄像头、补光灯、监听和拍照	驾驶舱与音视频
摄像头、ToF 和扬声器线束	摄像头和 ToF 实物接线图
蓝牙手柄连接与控制	AI 版手柄控制
ToF 测距与前向限速	ToF 测距与前向限制
基础装配、控制和校准	七步开发者图文指南

与其他运行时的区别

版本	日常入口和功能
`master` 基础版	通过 `http://<板子IP>:9527/` 使用网页运动控制、舵机设置和校准。
`ai-chat-audio-video-tof` AI 版	通过 `http://<板子IP>/` 进入驾驶舱及 AI 绑定；运动控制仍在 `:9527`。提供语音聊天、USB 音视频和可选 ToF。

AI 版的运动控制基线对应主分支 b401d85，采用逐关节 Set center & hold 流程设置硬件中点。升级时应使用完整匹配的 App，并阅读下方的数据迁移说明。

安装前准备

准备运行官方 Debian 13 的 Arduino UNO Q、扩展板、电池、舵机、USB 数据线和运行 Arduino App Lab 的电脑。首次安装需要联网下载依赖。
语音聊天需要 USB 麦克风和扬声器；摄像头与 VL53L5CX ToF 可用于视频和测距。整机套件包含这些模块，基础款不含；详见套件清单。多个独立 USB 外设需要 Hub 时，准备能供电的 USB-C Host Hub；组合线束可将摄像头 USB 直连 UNO Q，见实物接线图。
先按图文指南完成板子联网，记录 IP，确认能通过 Wi-Fi SSH 和 App Lab Network 连接。硬件支持安装会切换 USB Host 并断开电脑的 USB/ADB 连接。
更新旧机器人前扶稳并卸力，停止旧 App，备份该机器人的 App 目录和 data/。Router 设置由 App 共用，配置前先停止正在运行的 App。

导入并首次启动 AI App

下载 AI 版专用安装包，并可用配套 SHA-256 文件校验：

XGO Duck AI App Lab 安装包.zipZIP · 点击在新窗口打开

打开

安装包 SHA-256 校验文件.sha256SHA256 · 点击在新窗口打开

打开

安装包 SHA-256：0205e57b0c91d273e12522b009d47b09ca65ce820cb0e66fa25fe2e3420a775c。

App Lab 中选择 Apps → Import App → Import from computer，导入下载的 ZIP 后先保持 App 停止。
从板子的 Debian 主机通过 Wi-Fi SSH，以 arduino 用户进入实际 App 目录，执行以下命令。目录名仅为示例，以实际导入结果为准；第二条命令设置共享 Router 的 Bridge 速率为 2 Mbps。
```
cd ~/ArduinoApps/xgoduck_ai
bash tools/install-ai-support.sh
sudo bash tools/router-2m.sh
```
保持联网，在 App Lab 通过 Network 连接板子，打开 XGO Duck AI 并点击 Run。首次运行可能编译并上传 STM32 程序，需等待依赖和应用启动。
打开 http://<板子IP>/，在驾驶舱选择服务区域并完成账号绑定。首次初始化和成功 Run 后，后续通电会自动准备 USB Host 并启动 App；建议实际验证一次重启。

安装脚本会准备主机依赖、USB Host、驾驶舱和开机自启。安装与数据迁移按完整说明执行。

AI 辅助安装

也可使用AI 辅助安装提示词。安装和启动后仍需按顺序完成舵机编号、装配、标定试走、账号绑定及选择智能体；已完成的步骤可跳过。登录密码应由本人在受信任的终端输入，不要写进 Wiki 或日志。

核对板级 core 与工具链

首次启动前，可在板端以 arduino 用户运行 arduino-cli core list。本版本的 sketch/sketch.yaml 指定 arduino:zephyr 1.0.0；缺失或版本不一致时，安装并复查：

arduino-cli core install arduino:zephyr@1.0.0
arduino-cli core list

ARM64 构建工具链按 provenance/toolchain.json 固定为 1.0.1。若板端下载失败，可先在电脑下载该文件所列的 Linux ARM64 压缩包并核对大小、SHA-256，再通过 SCP 传到板端，按安装说明在 App 目录执行准备脚本。编译成功并不代表上传时一定使用了正确 core，需分别核对。

旧版数据与校准

新版 ZIP 不包含各机器人的运行数据。更新同一只鸭子前备份原目录；按需保留身份、音量和手柄设置，切勿复制其他机器人的绑定身份或校准。若旧版 data/zero_pos.json 包含非 2047 的软件零位，新版会要求完成 15 个关节的硬件中点校准；旧文件保留备份，但新版不再直接加载其零位。不要通过修改文件跳过迁移。具体条件和处理方式见AI 安装说明：硬件中点校准。