AmazingHand PWM 灵巧手 — 全流程使用教程

配套交付包： delivery_package.zip

从上位机手势指令到手势追踪,一条龙使用教程。适用硬件:ESP32-S3 + 8 路 PWM 舵机(差动驱动)。
版本:2026-08-20 · 配套固件:ESP-IDF 组件化版(AmazingHand_Serial)

第 0 章教程导航

本教程按先后顺序组织。先看清你要走哪条路线,再跳到对应章节。

路线	用途	前置要求	章节
A. 上位机手势指令	点按钮/敲命令让机械手做手势(石头/剪刀/布/真棒…)	Python + 烧录固件	第 1-4 章
B. GUI 内置手势追踪	摄像头跟随手部动作,机械手实时复现(简化版,无 IK)	A + 64位Python + mediapipe	第 1-4 章 + 5.1
C. dora 官方 IK 追踪	官方完整链路:摄像头→IK→8关节角→舵机(完整版)	A + Rust + uv + dora	第 1-4 章 + 5.2

推荐路线:

第一次用 → 走 A,先确认固件和接线没问题。
想快速看摄像头跟随 → 走 B(轻量,几分钟装好)。
要正式、完整的追踪 → 走 C(官方链路,精度最高)。

三条路线的硬件共用,环境只有路线 C 需要额外装 Rust/uv/dora。

第 1 章环境准备

按先后顺序安装。路线 A/B 只需要第 1.1 节;路线 C 还需要第 1.2 节。

1.1 上位机环境(路线 A/B 必需)

① 64 位 Python 3.12

必须 64 位。mediapipe 0.10.14 只提供 64 位 Windows wheel,32 位装不上; 这也是 GUI 双击闪退的常见原因。

推荐安装到 D:\Python312-64bit(本机已有该路径)。
安装时勾选 Add to PATH。
验证(64 位):

bash

py -3.12-64 -c "import sys; print('64bit' if sys.maxsize > 2**32 else '32bit')"
# 输出: 64bit

② 安装上位机依赖

项目根目录(包含 hand_gui.py 的目录):

bash

pip install -r requirements.txt     # 只需 pyserial

③ 追踪附加依赖(路线 B 用)

项目根目录运行:

bash

setup_tracking.bat

它会自动:找 64 位 Python → 建 tracking_env 虚拟环境 → 安装 requirements-tracking.txt (mediapipe==0.10.14、numpy<2、scipy、opencv、Pillow、pyserial)→ 验证 mediapipe。

或手动安装:

bash

D:\Python312-64bit\python.exe -m pip install -r requirements-tracking.txt

1.2 dora 官方 IK 环境(路线 C 必需)

客户安装:双击 ..\02_hand_tracking\Demo\Windows_Scripts_CN\1-安装环境.bat(英文版为 ..\02_hand_tracking\Demo\Windows_Deploy_Scripts\1-Install_Env.bat),自动安装全部依赖: Rust 工具链、uv(Python 包管理)、dora-cli。

装完后关掉终端重新打开一次,让 PATH 生效。详细依赖(版本、手动安装方式)见维护文档,无需客户处理。

第 2 章硬件接线

2.1 硬件清单

硬件	说明
ESP32-S3 开发板	YX-ESP32-S3 或同类
8 路 PWM 舵机	模拟舵机,差动驱动
舵机转接板	舵机 → 8 路 PWM 输出
独立 5V 电源	至少 5V 3A,舵机瞬态电流大
USB 数据线	ESP32-S3 Type-C → PC
摄像头	内置或 USB 摄像头(追踪用)

2.2 GPIO 映射

转接板 PWM1-8 → ESP32-S3 GPIO:

转接板	GPIO	手指
PWM1	4	食指关节 1
PWM2	5	食指关节 2
PWM3	6	中指关节 1
PWM4	7	中指关节 2
PWM5	15	无名指关节 1
PWM6	16	无名指关节 2
PWM7	17	拇指关节 1
PWM8	18	拇指关节 2

左右手共用同一套 GPIO。左手/右手由软件切换(第 4 章),不用改接线。

2.3 供电要求

舵机用独立 5V 电源(至少 3A),不要只靠 USB 供电。
舵机瞬间电流冲击可能把 ESP32 拉复位(现象:ESP32 反复重启)。此时断电重启 ESP32。

2.4 接线步骤

8 路舵机 → 转接板 PWM1-8
转接板 → ESP32-S3 对应 GPIO(上表)
ESP32-S3 Type-C → PC
摄像头接 PC(追踪用)

详细接线/电路图见 ESP32开发板电路图/ 目录。

第 3 章前置条件:固件烧录

舵机要能响应,必须先烧固件。固件位于 esp-idf\AmazingHand_Serial\。

3.1 ESP-IDF 版编译(推荐)

用 Espressif IDE 打开 AmazingHand_Serial 工程:

设置目标芯片(首次):
```
idf.py set-target esp32s3
```
编译:
```
idf.py build
```
烧录(Windows 用 COM 口,如 COM3):
```
idf.py -p COM3 flash
```

3.2 烧录后验证

串口监控(波特率 115200):

idf.py -p COM3 monitor

应看到启动日志:

AmazingHand Serial Control Ready (ESP-IDF)
Protocol: 115200-8N1 [0xAA CMD LEN DATA CKSUM]

串口波特率已由固件/脚本统一配置(115200),客户无需手动设置。

注:通常设备交付时固件已烧录好,这一步仅在新固件/重新烧录时执行。

第 4 章初步运行:上位机手势指令

前置:固件已烧录(第 3 章)、ESP32 已通电、串口线已接。先看设备管理器确认 COM 口。

4.1 GUI 可视化(推荐)

方式 A:运行打包 exe

双击 dist/AmazingHand控制台.exe(不含追踪,追踪需源码方式)。

方式 B:从源码运行

bash

# 项目根目录,先激活追踪环境(装了 mediapipe)或任意带 pyserial 的 Python
tracking_env\Scripts\python hand_gui.py

GUI 使用步骤

选串口:顶部下拉框选 ESP32 的 COM 口。
点「连接」:状态灯变绿,日志显示"已连接",自动发 NOP 链路测试。
手势命令:点「石头」「剪刀」「布」「真棒」「OK」「捏合」「指向」等,机械手执行。
左右手:勾选「右手」/「左手」切换拇指镜像方向。
舵机直驱:拖 8 个滑块,实时控制单个舵机角度(0-180°)。
手指差动控制(推荐):每根手指两个进度条——「弯曲◀▶伸直」反向差动、「右摆◀▶左摆」同向摆动。两自由度独立,同步驱动。
重复/停止:重复上一次手势 / 立即中断。
通信日志:底部实时显示收发帧和响应。

4.2 命令行测试(serial_test.py)

项目根目录:

bash

# 链路测试(先确认能通)
python serial_test.py COM3 nop

# 手势
python serial_test.py COM3 rock         # 石头
python serial_test.py COM3 thumbs_up    # 真棒
python serial_test.py COM3 index        # 指向
python serial_test.py COM3 open         # 张开
python serial_test.py COM3 close        # 握拳

# 单舵机直驱
python serial_test.py COM3 servo 1 90   # 舵机1 → 90°

# 全部归中
python serial_test.py COM3 mid

# 设左右手
python serial_test.py COM3 hand L
python serial_test.py COM3 hand R

# 扫频/自检
python serial_test.py COM3 sweep 1      # 舵机1 扫频
python serial_test.py COM3 test         # 全部舵机逐个测试

4.3 验证

点手势后舵机应执行对应动作;串口日志返回 ACK 和 DONE。
响应码:0x00=OK,0x01=无效命令,0x02=参数错误,0x03=忙,0x10=完成。
如果舵机完全不动:见第 6 章常见问题(先查供电/串口)。

手势命令与串口协议完整速查见第 7 章。

第 5 章进阶教程:手势追踪

前置:第 1-4 章已完成(固件烧录、串口能控制、摄像头就位)。本章两条路,选一条走。

5.1 GUI 内置追踪(轻量版)

适合:快速演示,免装 dora。摄像头 → 直接映射到差动舵机,无 IK。

前置

64 位 Python + setup_tracking.bat(第 1.1 节)。
摄像头可用。

运行

bash

# 项目根目录,用追踪环境启动 GUI
tracking_env\Scripts\python hand_gui.py

选串口 → 「连接」。
滚动到「手势追踪 (MediaPipe 摄像头)」面板。
选摄像头号(默认 0)→ 点「开始追踪」。
把手放进画面,机械手跟随手部弯曲/伸直。

原理

mediapipe 0.10.14 提取 4 指指尖 3D 向量(手部坐标系)。
hand_tracking.py 的 tips_to_angles() 把每指映射为差动角度:
- flex(弯曲/伸直):三指用 z 分量,拇指用 y 分量;
- base(左右摆):固定 90(暂未做左右摆)。
GUI 内置 EMA 平滑(alpha=0.4)+ 60ms 节流,避免抖动。

局限

无 IK:直接把指尖映射到角度,精度不如官方链路。
左右摆暂缓:base 固定 90,不做左右摆动。
适合演示/原型,正式用推荐 5.2。

5.2 dora 官方 IK 追踪(完整版)

适合:正式使用。官方链路:摄像头 → mediapipe → MuJoCo+mink IK → 8 关节角 → AHControl(Rust)→ ESP32 → PWM 舵机。

前置

完整环境(Rust + uv + dora,第 1.2 节)。
固件烧录(第 3 章)。
数据流 yml 已写好 PWM 波特率(115200),无需手动改。

第一步:部署(推荐一键脚本)

双击 ..\02_hand_tracking\Demo\Windows_Scripts_CN\3-部署代码.bat(英文版为 ..\02_hand_tracking\Demo\Windows_Deploy_Scripts\3-Deploy_Demo.bat),自动完成: 建 Python 环境、编译 AHControl(Rust)、安装 AHSimulation/HandTracking(mediapipe)。

首次部署需几分钟。脚本已内置环境变量处理,无需手动设置。

第二步:运行

双击 ..\02_hand_tracking\Demo\Windows_Scripts_CN\4-运行代码.bat(英文版为 ..\02_hand_tracking\Demo\Windows_Deploy_Scripts\4-Run_Demo.bat),按菜单选择:

1 - 模拟仿真（摄像头手势追踪）
2 - 真实硬件（SCS0009 总线舵机）
3 - PWM 舵机（ESP32 直驱）   ← 选 3

再选手型:1 右手 / 2 左手。脚本自动 dora build + dora run。

摄像头窗口打开,把手放进画面 → 3D 仿真手指跟随 → 机械手跟随。
停止:Ctrl+C(或关闭窗口)。

左右手切换

在运行菜单里选择手型即可(第 5.2 节第二步):选 1 右手 或 2 左手。

切换后脚本会自动重新构建对应数据流,等构建完成再动摄像头前的操作即可。

运行日志怎么看

运行窗口里 AHControl 节点会持续输出日志。重点看这一行:

[ACK-STATS] sent N frames, ESP32 acked M frames

M ≈ N(例如 sent 300 frames, ESP32 acked 300 frames)→ 正常,ESP32 每帧都收到。
M = 0 → ESP32 没收到数据,检查串口/供电(见第 6 章)。

只要这一行在正常增长,就说明舵机链路是通的,剩下的就是摄像头跟不跟得上的问题。

第 6 章常见问题(运行途中)

本节只列使用过程中最容易遇到、自己就能解决的问题。按现象快速定位。

6.1 舵机完全不动

按顺序排查:

供电:舵机是否接了独立电源(5V 3A 以上)?只靠 USB 供电时,舵机可能不动或 ESP32 反复重启。→ 断电重启 ESP32。
串口:COM 口选对了吗?设备管理器 → 端口(COM 和 LPT)看 ESP32 对应的口。有没有别的程序(如串口助手)占用?→ 关掉占用程序。
接线:转接板 PWM1-8 是否接对 GPIO?舵机信号线是否插紧?

6.2 摄像头没画面

Windows 首次运行会弹摄像头权限 → 点「允许」。
如果之前选了"否":设置 → 隐私和安全性 → 相机 → 允许桌面应用访问相机,然后重新运行。

6.3 摄像头有画面,但手不跟随 / 跟随迟钝

确认摄像头正对手,光线充足,手在画面里完整可见。
动慢一点、幅度大一点。太快或幅度太小,追踪可能跟不上。
3D 仿真窗口里手指动了吗?
- 动了:追踪链路正常,问题在舵机/串口,看 6.1。
- 没动:是追踪节点没识别到手,调整姿势/光线重试。

6.4 手型反了 / 拇指方向反

左手/右手选错了?在运行菜单中选择对应手型。
上位机 GUI 里勾「右手」/「左手」切换。

6.5 左右手切换后不生效

切换手型后,dora 需要重新构建数据流:运行菜单选好手型后会自动 dora build,等它完成即可。

6.6 运行中途画面卡住 / 日志停住

可能是摄像头被其它应用占用(视频会议、另一个脚本),关掉后重试。
或按 Ctrl+C 停止,重新运行。

6.7 换了 USB 口 / 重启电脑后找不到串口

COM 口号可能变了。设备管理器确认新的 COM 号,重跑 2-配置串口.bat(或 2-Setup_Serial.bat)选一次口,再运行。

6.8 还不行?

把运行终端的日志截图发给维护方,并说明:在哪个步骤、什么操作、看到什么现象。
关键日志:启动时的 [CONFIG] 行、运行中的 [ACK-STATS] 行(ESP32 acked M frames 的 M 是否接近 N)。

第 7 章命令速查(附录)

完整协议说明见同目录 用户手册.md。这里给速查表。

7.1 手势命令

手势	HEX	ACK	DONE
NOP	`AA 00 00 00`	`BB 00 00 00`	—
石头	`AA 01 00 01`	`BB 01 00 01`	`BB 01 10 11`
剪刀	`AA 02 00 02`	`BB 02 00 02`	`BB 02 10 12`
布	`AA 03 00 03`	`BB 03 00 03`	`BB 03 10 13`
真棒	`AA 04 00 04`	`BB 04 00 04`	`BB 04 10 14`
嘲讽1(摇食指)	`AA 05 00 05`	`BB 05 00 05`	`BB 05 10 15`
嘲讽2(无名指)	`AA 06 00 06`	`BB 06 00 06`	`BB 06 10 16`
张开	`AA 07 00 07`	`BB 07 00 07`	`BB 07 10 17`
握拳	`AA 08 00 08`	`BB 08 00 08`	`BB 08 10 18`
OK	`AA 09 00 09`	`BB 09 00 09`	`BB 09 10 19`
捏合	`AA 0A 00 0A`	`BB 0A 00 0A`	`BB 0A 10 1A`
指向	`AA 0C 00 0C`	`BB 0C 00 0C`	`BB 0C 10 1C`

7.2 控制命令

命令	HEX	说明
重复	`AA FE 00 FE`	重复上次手势
停止	`AA FF 00 FF`	立即中断
设右手	`AA F1 01 01 F1`	—
设左手	`AA F1 01 02 F2`	—
直驱	`AA F0 08 [8×角度] CKSUM`	8 字节角度

7.3 帧格式

帧头(0xAA) + 命令(CMD) + 长度(LEN) + 数据(DATA) + 校验和(CKSUM)
CKSUM = CMD ^ LEN ^ DATA[0] ^ ... ^ DATA[N-1]
响应: 帧头(0xBB) + CMD + STATUS + (CMD^STATUS)

7.4 上位机工具

工具	命令	用途
GUI	`tracking_env\Scripts\python hand_gui.py`	可视化手势 + 直驱 + 差动 + 追踪
打包 exe	`dist/AmazingHand控制台.exe`	免装 Python 可视化(无追踪)
命令行	`python serial_test.py COMx <cmd>`	自动化测试

7.5 追踪数据流文件(PWM 版)

用途	文件
左手 PWM 追踪	`dataflow_tracking_real_left_pwm.yml`
右手 PWM 追踪	`dataflow_tracking_real_right_pwm.yml`
左手 PWM 配置	`AHControl/config/l_hand_pwm.toml`
右手 PWM 配置	`AHControl/config/r_hand_pwm.toml`

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

串口通信

AmazingHand PWM 灵巧手 — 全流程使用教程 ​

第 0 章 教程导航 ​

第 1 章 环境准备 ​

1.1 上位机环境(路线 A/B 必需) ​

① 64 位 Python 3.12 ​

② 安装上位机依赖 ​

③ 追踪附加依赖(路线 B 用) ​

1.2 dora 官方 IK 环境(路线 C 必需) ​

第 2 章 硬件接线 ​

2.1 硬件清单 ​

2.2 GPIO 映射 ​

2.3 供电要求 ​

2.4 接线步骤 ​

第 3 章 前置条件:固件烧录 ​

3.1 ESP-IDF 版编译(推荐) ​

3.2 烧录后验证 ​

第 4 章 初步运行:上位机手势指令 ​

4.1 GUI 可视化(推荐) ​

方式 A:运行打包 exe ​

方式 B:从源码运行 ​

GUI 使用步骤 ​

4.2 命令行测试(serial_test.py) ​

4.3 验证 ​

第 5 章 进阶教程:手势追踪 ​

5.1 GUI 内置追踪(轻量版) ​

前置 ​

运行 ​

原理 ​

局限 ​

5.2 dora 官方 IK 追踪(完整版) ​

前置 ​

第一步:部署(推荐一键脚本) ​

第二步:运行 ​

左右手切换 ​

运行日志怎么看 ​

第 6 章 常见问题(运行途中) ​

6.1 舵机完全不动 ​

6.2 摄像头没画面 ​

6.3 摄像头有画面,但手不跟随 / 跟随迟钝 ​

6.4 手型反了 / 拇指方向反 ​

6.5 左右手切换后不生效 ​

6.6 运行中途画面卡住 / 日志停住 ​

6.7 换了 USB 口 / 重启电脑后找不到串口 ​

6.8 还不行? ​

第 7 章 命令速查(附录) ​

7.1 手势命令 ​

7.2 控制命令 ​

7.3 帧格式 ​

7.4 上位机工具 ​

7.5 追踪数据流文件(PWM 版) ​

AmazingHand PWM 灵巧手 — 全流程使用教程

第 0 章教程导航

第 1 章环境准备

1.1 上位机环境(路线 A/B 必需)

① 64 位 Python 3.12

② 安装上位机依赖

③ 追踪附加依赖(路线 B 用)

1.2 dora 官方 IK 环境(路线 C 必需)

第 2 章硬件接线

2.1 硬件清单

2.2 GPIO 映射

2.3 供电要求

2.4 接线步骤

第 3 章前置条件:固件烧录

3.1 ESP-IDF 版编译(推荐)

3.2 烧录后验证

第 4 章初步运行:上位机手势指令

4.1 GUI 可视化(推荐)

方式 A:运行打包 exe

方式 B:从源码运行

GUI 使用步骤

4.2 命令行测试(serial_test.py)

4.3 验证

第 5 章进阶教程:手势追踪

5.1 GUI 内置追踪(轻量版)

前置

运行

原理

局限

5.2 dora 官方 IK 追踪(完整版)

前置

第一步:部署(推荐一键脚本)

第二步:运行

左右手切换

运行日志怎么看

第 6 章常见问题(运行途中)

6.1 舵机完全不动

6.2 摄像头没画面

6.3 摄像头有画面,但手不跟随 / 跟随迟钝

6.4 手型反了 / 拇指方向反

6.5 左右手切换后不生效

6.6 运行中途画面卡住 / 日志停住

6.7 换了 USB 口 / 重启电脑后找不到串口

6.8 还不行?

第 7 章命令速查(附录)

7.1 手势命令

7.2 控制命令

7.3 帧格式

7.4 上位机工具

7.5 追踪数据流文件(PWM 版)