SCS0009 手势追踪（官方 dora Demo）

本页介绍 SCS0009 总线舵机版的官方手势追踪链路：摄像头 → MediaPipe → MuJoCo IK → AHControl（Rust）→ SCS0009。PWM 版追踪见 PWM 手势追踪。

下面的脚本 1 → 4 以 Windows 一键脚本为例，脚本位于 AmazingHand-main/Demo/Windows_Deploy_Scripts/；Linux 与 macOS 的脚本位置和差异见文末。按编号顺序执行即可。

硬件准备

硬件	要求
灵巧手本体	右手 / 左手 / 双手
舵机驱动板	外接，USB 连电脑
电源	外接电源，至少 5V 4A（或按驱动板要求使用 7–12V 输入）；USB 供电不足
摄像头	电脑自带或 USB 摄像头

模型文件可在 Onshape 查看或自行下载（含 URDF）。

灵巧手的 MuJoCo 模型

环境安装（脚本 1）

Windows 一键部署脚本目录

双击 1-Install_Env.bat，自动完成：

检查 MSVC 构建工具（cl.exe）——Rust 编译必需。缺失时会提示安装 Visual Studio 2022 Build Tools，勾选"使用 C++ 的桌面开发"，装完重开终端。
安装 Rust（rustup + stable-msvc 工具链）
配置 cargo 清华镜像源（C:\Users\<你的用户名>\.cargo\config.toml），加速 crate 下载
安装 uv（Python 包管理器）
安装 dora-cli 0.5.0（cargo install，首次编译约 10~20 分钟，耐心等待）
安装 dora-rs pip 包（可选，会装进虚拟环境）

重要：脚本结束后关闭并重新打开终端，让环境变量生效。安装过程可能因网络较慢，请耐心等待，不要中途关闭。

环境安装备选（脚本不可用时）

Rust：https://www.rust-lang.org/tools/install
- Windows 用 rustup-init.exe，选默认 MSVC 工具链
- 环境变量：%USERPROFILE%\.cargo\bin 加入 PATH
uv：PowerShell 执行 irm https://astral.sh/uv/install.ps1 | iex。
- 环境变量：%USERPROFILE%\.local\bin 加入 PATH
dora-cli：cargo install dora-cli --version 0.5.0

cargo 清华镜像设置（~/.cargo/config.toml）

bash

[source.crates-io]
replace-with = "tuna"

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

[registries.tuna]
index = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

[http]
check-revoke = false

用 sparse 稀疏索引（如上），不要用 git 仓库镜像——git 方式首次要下载约 1GB 索引，容易卡死在 Updating 'tuna' index。

接线方式

舵机驱动板 USB 连电脑，外接电源（至少 5V 4A，或按驱动板要求使用 7–12V）
电脑端找到端口号：设备管理器 → 端口(COM和LPT)，如 COM11

配置串口（脚本 2）

双击 2-Setup_Serial.bat（实际逻辑在 2-Setup_Serial.ps1）：

提示"请将舵机驱动板连接到电脑"→ 回车开始检测
自动列出检测到的 COM 端口（带设备名）
单个端口时回车确认，多个端口时输入编号
自动写入 3 个 dataflow yml 的 --serialport 和 AHControl\src\main.rs 的默认端口
原文件自动备份为 .bak

如果重新插拔 USB，端口号可能变化，需重新运行本脚本。

代码部署（脚本 3）

双击 3-Deploy_Demo.bat，自动完成：

启动 dora 守护进程（dora up）
创建 Python 3.12 虚拟环境（uv venv --python 3.12）
激活虚拟环境
编译 AHControl Rust 节点（cargo build --release，首次约 10 分钟）
同步 AHSimulation、HandTracking 依赖（uv sync）
强制安装 mediapipe==0.10.14

部署只需执行一次。之后重复运行会提示是否重建虚拟环境。

运行代码（脚本 4）

双击 4-Run_Demo.bat，出现交互菜单：

bash

============================================
   请选择运行模式：
============================================
    1 - 模拟仿真（摄像头手势追踪）
    2 - 真实硬件
    q - 退出
============================================
  请输入序号 [1/2/q]:

选 1：模拟环境，摄像头手势驱动两只仿真手
选 2：进入子菜单，选右手 / 左手 / 双手

bash

============================================
   真实硬件 - 请选择灵巧手：
============================================
    1 - 右手
    2 - 左手
    3 - 左右双手
    b - 返回上级菜单
============================================

选好后自动执行 dora build + dora run。摄像头窗口弹出，对着摄像头做手势，灵巧手实时跟随。Ctrl+C 停止，数据流结束后按回车返回主菜单，可再选其它模式或 q 退出。

首次运行时 Windows 可能拦截摄像头权限，点击"允许"即可。

项目清理（脚本 0）

双击 0-Cleanup_Project.bat，输入 Y 确认后自动清理：

停止 dora 守护进程
删除 3 个虚拟环境（.venv）
删除 Rust 编译产物（AmazingHand-main/Demo/target）
删除 pycache、.bak 备份、日志、AmazingHand-main/Demo/out（dora 日志目录）
恢复默认端口（--serialport /dev/ttyACM0），去掉本机串口残留

清理后可把整个 AmazingHand-main 文件夹拷给他人，干净无残留。新机器上按 1 → 2 → 3 → 4 顺序执行即可。

Linux 与 macOS 差异

一键脚本同样提供 Linux 和 macOS 版本，目录分别为 AmazingHand-main/Demo/Linux_Deploy_Scripts/ 和 AmazingHand-main/Demo/Mac_Deploy_Scripts/。第 1–4 步的流程与 Windows 相同，下面只列系统差异。

脚本执行权限（Linux / macOS）

从 Windows 或压缩包拷贝后，脚本的 +x 执行位会丢失，首次运行前先执行：

bash

cd "AmazingHand-main/Demo/Linux_Deploy_Scripts"   # macOS 改为 Mac_Deploy_Scripts
chmod +x *.sh

之后用 ./脚本名 运行；不要用 bash 脚本名，否则会跳过脚本内的交互提示。

Linux（Ubuntu）

串口权限：sudo usermod -aG dialout $USER，注销并重新登录；临时可用 sudo chmod 666 /dev/ttyACM*。
设备名：/dev/ttyUSB*（CH340 / CP2102）或 /dev/ttyACM*（板载 USB 串口）。
摄像头：设置 → 隐私 → 相机，允许应用访问；确认没有其他程序占用摄像头。
虚拟机：先把 USB 摄像头连接到虚拟机；若 OpenCV 报 can't open camera by index 或 select() timeout，在虚拟机设置中切换 USB 控制器 2.0 / 3.1 并重启；必要时 sudo usermod -aG video $USER。
中文路径：项目路径尽量使用英文，避免 MuJoCo / MediaPipe 加载模型失败。

Linux 一键部署

Linux 下 main.rs 的串口默认值示例

macOS

串口：使用 /dev/cu.*，不要用 /dev/tty.*；ls /dev/cu.* 查看设备名。
串口权限：sudo chmod 666 /dev/cu.usbmodem*，或在“系统设置 → 隐私与安全性 → 输入监控”中允许终端。
摄像头：首次运行允许终端访问相机；也可在“系统设置 → 隐私与安全性 → 相机”中修改。
Apple Silicon：首次 cargo build 编译 dora 依赖较慢属正常；若提示“无法验证开发者”，到“隐私与安全性”中点击“仍要打开”。

macOS 一键部署

手动安装（不使用一键脚本）

如果脚本不可用，可按官方 Demo 手动部署：

获取代码：克隆仓库或下载 AmazingHand.zip，进入 AmazingHand-main/Demo/。
安装环境：Rust（rustup）、uv、dora-cli；PowerShell/Bash 重新打开使 PATH 生效。安装细节见上方环境安装（脚本 1）。

创建环境并安装依赖：

bash

uv venv --python 3.12
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate

cd AHControl
cargo build --release
cd ..
cd AHSimulation
uv sync
cd ..
cd HandTracking
uv sync
cd ..

构建 Python 节点依赖

配置串口：编辑 dataflow_tracking_real_right.yml / _left.yml / _2hands.yml 中的 --serialport，改成实际 COM 口或 /dev/ttyUSB0、/dev/cu.usbserial-*。

构建并运行：

bash

# 仿真
dora build dataflow_tracking_simu.yml --uv
dora run dataflow_tracking_simu.yml --uv

# 真实硬件（右手；左手/双手替换文件名）
dora build dataflow_tracking_real_right.yml --uv
dora run dataflow_tracking_real_right.yml --uv

# 简单角度示例
dora build dataflow_angle_simu.yml --uv
dora run dataflow_angle_simu.yml --uv

构建并启动真实硬件数据流

MuJoCo 仿真与摄像头追踪窗口

常见问题：mediapipe 需 0.10.14（Python 3.12）；dora 版本不兼容时按 pyproject.toml/日志对齐；缺 OpenCV 时安装 opencv-contrib-python；摄像头权限、虚拟机 USB 直通、中文路径都会影响模型加载。具体排查见常见问题与注意事项。

更详细的官方 Demo 说明见 AmazingHand-main/Demo/README.md；各系统的一键部署步骤已合并到本页。

代码结构说明

Demo 目录

text

AmazingHand-main/Demo/
├── AHControl/                Rust 节点：串口控制舵机，config/ 下为舵机 ID 与偏移
├── AHSimulation/             Python 节点：MuJoCo 仿真与逆运动学
├── HandTracking/             Python 节点：MediaPipe 手部关键点识别
├── dataflow_*.yml            dora 数据流编排
├── Windows_Deploy_Scripts/   Windows 一键部署脚本
├── Linux_Deploy_Scripts/     Linux 一键部署脚本
├── Mac_Deploy_Scripts/       macOS 一键部署脚本
└── docs/                     官方多语言部署教程

各 dataflow 对应关系

数据流文件	用途
`dataflow_tracking_simu.yml`	摄像头手势追踪，仅驱动 MuJoCo 仿真手
`dataflow_tracking_real_right.yml`	摄像头手势追踪，驱动真实右手
`dataflow_tracking_real_left.yml`	摄像头手势追踪，驱动真实左手
`dataflow_tracking_real_2hands.yml`	摄像头手势追踪，同时驱动左右手
`dataflow_angle_simu.yml`	直接给关节角度，验证仿真与逆运动学

数据流原理

bash

摄像头 → HandTracking（MediaPipe 识别手势）
              ↓ 手部关键点坐标
         AHSimulation（MuJoCo 仿真 + 逆运动学）
              ↓ 关节目标角度
         AHControl（串口 → 舵机驱动板 → 灵巧手）

端口配置位置

三个 dataflow_tracking_real_*.yml 的 args: 行：--serialport COMxx
AHControl\src\main.rs 的 default_value = "COMxx"（串口参数默认值）
AHControl\config\*.toml：舵机型号、ID、偏移量（一般不用改）

常见问题与注意事项

1. cargo 卡在 `Updating 'tuna' index`

原因：镜像配置用了 git 仓库方式（.../git/crates.io-index.git），首次要下载 1GB+ 索引
解决：C:\Users\<你的用户名>\.cargo\config.toml 改为 sparse 稀疏索引（见上文“cargo 清华镜像设置”），或直接重跑 1-Install_Env.bat

2. mediapipe 缺 solutions 子模块 / 安装损坏

bash

uv pip uninstall mediapipe

bash

uv pip install mediapipe==0.10.14

必须在虚拟环境激活状态下执行（在 Demo 目录）
3-Deploy_Demo.bat 已自动做这一步兜底

3. dora 版本不兼容（message v0.8.0 vs v0.7.0）

dora 消息格式版本不匹配的错误日志

症状：version mismatch: message format v0.8.0 is not compatible with expected message format v0.7.0
原因：dora-cli 版本与 dora-node-api 不匹配。必须统一为 0.5.0
- 检查：dora --version 应输出 dora-cli 0.5.0、dora-message: 0.8.0
- 修复：cargo install dora-cli --version 0.5.0 --force
- 若 PATH 里有多个 dora（如 C:\Users\<用户名>\.dora\bin 的旧版），确保 .cargo\bin 排在前面，或删除旧版

4. MuJoCo / mediapipe 加载模型失败（中文路径）

症状：ParseXML: Error opening file '...\scene.xml' 或 Can't find file: ....tflite
原因：MuJoCo 3.x / mediapipe 的 C++ 加载器在 Windows 上打不开含中文的绝对路径（如 D:\中文目录...）
本项目已内置修复：
- AHSimulation\AHSimulation\mj_mink_*.py 加载模型前切换工作目录
- HandTracking\mediapipe_patch.py 用 8.3 短路径 + 相对路径绕过
不要删除这些修复代码

5. 摄像头权限

首次运行弹窗选择"允许"
设置 → 隐私 → 相机 → 允许桌面应用访问

6. 端口号每次变化

重新插拔 USB 后 COM 号可能变，重跑 2-Setup_Serial.bat

7. 缺少 openCV

缺少 cv2 模块的错误日志

bash

python -m pip install opencv-contrib-python numpy mediapipe -i https://mirrors.aliyun.com/pypi/simple/

（在 HandTracking 目录、激活虚拟环境后执行）

1. 安装 LeRobot 环境

2. 查看串口设备端口号

3. 校准机械臂

4. 遥操作

5. 连接摄像头的遥操作

6. 采集数据集(真机)

7. 训练模型

8. 模型推理

基础知识

专题与进阶

1. 安装 LeRobot 环境

3. 查看串口设备端口号

4. 校准机械臂

5. 遥操作

6. 连接摄像头的遥操作

7. 采集数据集(真机)

8. 训练模型

9. 模型推理

Jetson AGX Orin 开发者套件

Jetson Orin Nano 开发者套件

PC 端

I2C 通信

串口通信

SCS0009 手势追踪（官方 dora Demo） ​

硬件准备 ​

环境安装（脚本 1） ​

环境安装备选（脚本不可用时） ​

cargo 清华镜像设置（~/.cargo/config.toml） ​

接线方式 ​

配置串口（脚本 2） ​

代码部署（脚本 3） ​

运行代码（脚本 4） ​

项目清理（脚本 0） ​

Linux 与 macOS 差异 ​

脚本执行权限（Linux / macOS） ​

Linux（Ubuntu） ​

macOS ​

手动安装（不使用一键脚本） ​

代码结构说明 ​

Demo 目录 ​

各 dataflow 对应关系 ​

数据流原理 ​

端口配置位置 ​

常见问题与注意事项 ​

1. cargo 卡在 Updating 'tuna' index ​

2. mediapipe 缺 solutions 子模块 / 安装损坏 ​

3. dora 版本不兼容（message v0.8.0 vs v0.7.0） ​

4. MuJoCo / mediapipe 加载模型失败（中文路径） ​

5. 摄像头权限 ​

6. 端口号每次变化 ​

7. 缺少 openCV ​

相关页面 ​

SCS0009 手势追踪（官方 dora Demo）

硬件准备

环境安装（脚本 1）

环境安装备选（脚本不可用时）

cargo 清华镜像设置（~/.cargo/config.toml）

接线方式

配置串口（脚本 2）

代码部署（脚本 3）

运行代码（脚本 4）

项目清理（脚本 0）

Linux 与 macOS 差异

脚本执行权限（Linux / macOS）

Linux（Ubuntu）

macOS

手动安装（不使用一键脚本）

代码结构说明

Demo 目录

各 dataflow 对应关系

数据流原理

端口配置位置

常见问题与注意事项

1. cargo 卡在 `Updating 'tuna' index`

2. mediapipe 缺 solutions 子模块 / 安装损坏

3. dora 版本不兼容（message v0.8.0 vs v0.7.0）

4. MuJoCo / mediapipe 加载模型失败（中文路径）

5. 摄像头权限

6. 端口号每次变化

7. 缺少 openCV

相关页面