快速开始

除非步骤明确切换目录，所有命令默认从仓库根目录执行。

1. 准备硬件

标准 research preview 配置使用五个 ICM-20948 节点：chest、upper_arm、forearm、 palm 和 finger。四节点最小配置可以省略 finger；此时 claw 使用键盘 1、2 按 0.2 步进控制。

上电前先阅读硬件、规范化 BOM/body-tracker-bom.csv，以及媒体素材 中的佩戴视频。

2. 烧录固件

安装适用于 ESP32-C3 的 ESP-IDF 5.5.x，通过 idf.py menuconfig 配置本地 Wi-Fi，然后为每个 节点编译烧录：

cd SOFTWARE/ESP32C3固件
source "$HOME/esp/v5.5.2/esp-idf/export.sh"
idf.py build
idf.py -p /dev/ttyACM0 flash
idf.py -p /dev/ttyACM0 monitor

将 /dev/ttyACM0 替换为实际串口。不要提交本地 Wi-Fi 凭据或构建目录。

3. 发现并检查节点

实时模式下，节点会广播自己的 UDP/TCP 端口和固件版本。校准前至少检查：

字段

预期检查

role

绑定到 chest、upper_arm、forearm、palm、finger 之一。

seq

每个节点独立递增；跳变表示丢包。

sensor_time_us

v2 数据包中每个节点单调递增。

time_sync_valid

TCP 时间同步采样被接受后为 true。

sample_age_ms

足够低且稳定，才能用于共同时间轴。

文档和 issue 中只使用假地址，例如 192.0.2.10；不要粘贴真实 Wi-Fi 密码、MAC 地址或私有网络包。

4. 选择佩戴侧

每次会话只选择一个激活侧：

python3 SOFTWARE/人体动捕/mocap_viz.py --wear-side right

左臂会话使用 left。这个选择会影响角色绑定、左右方向镜像、关节角符号、可视化和输出元数据。 首个公开版本每次只支持一个激活侧。

5. 佩戴 IMU

节点必须刚性固定，校准和运动时不能相对身体滑动或旋转：

角色

位置

朝向注意

chest

胸前躯干

定义 body_rh：X 前、Y 左、Z 上。

upper_arm

大臂中段

保持可重复的可见板方向；明显改变后重新校准。

forearm

小臂中段

保持可重复的可见板方向；避开肘和腕。

palm

手背

尽量让局部 +X 从手腕指向指尖。

finger

手指段

尽量让局部 +X 从手腕指向指尖。

人体校准会估计安装对准，但无法修正松动绑带或运动中滑动的 IMU。

6. 校准

先单独校准每个 IMU 的传感器精度，必要时进行磁力计标定；然后全部佩戴后做人体校准：

  1. 手臂自然下垂；

  2. 手臂向前平举；

  3. 手臂侧平举、手心向下；

  4. Roll 轴动作；

  5. 手掌/手指伸直参考，用于手掌 roll/pitch 和 claw=1。

可视化界面会显示倒计时、样本数、四元数角距离标准差、方差和失败提示。校准快照记录 wear_side、frame=body_rh、角色 ID、人体长度和参考姿态。

7. 查看 Body Tracker

demo 会将脱敏记录送入同一套动捕解算和可视化：

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -r SOFTWARE/人体动捕/requirements.txt
python3 SOFTWARE/人体动捕/mocap_viz.py --replay examples/demo_replay.jsonl

该模式需要桌面 OpenGL 环境。回放文件不包含真实设备 ID、Wi-Fi 凭据或私有校准文件。

实时查看时，在节点在线且完成校准后，将 --replay ... 换成 --wear-side right 或 --wear-side left。缺失节点会被标记为无效；缺少 finger 只会禁用传感器 claw。

8. 录制和回放

打开三个终端：

python3 -m pip install -r SOFTWARE/信息中枢/requirements.txt
python3 SOFTWARE/信息中枢/mocap_ws_hub.py --status-hz 50

python3 SOFTWARE/信息中枢/mocap_hub_bridge.py \
  --replay examples/demo_replay.jsonl

python3 SOFTWARE/信息中枢/examples/ws_subscriber.py

本地状态页位于 http://127.0.0.1:8766。实时模式下 bridge 独占 UDP 输入，不能同时启动另一个 绑定同一 UDP 端口的实时接收程序。

JSONL 回放内嵌校准快照和帧时间，之后同一文件可以被可视化、WebSocket 信息中枢、ROS 2 适配器 和 Unity 客户端消费。

故障排查

现象

优先检查

发现不了设备

Wi-Fi SSID、子网、电源、固件版本和防火墙。

烧录失败

串口权限、启动模式、数据线、端口名和 ESP-IDF target。

时间戳异常

确认使用 v2 固件，且 sensor_time_us 单调递增。

同步误差高

RTT、丢包、电源稳定性和 Wi-Fi 拥塞。

校准方差高

收紧绑带，重复姿态，静态采集时保持手臂不动。

左右手反了

先确认 --wear-side 和角色绑定，再重新校准。

finger 缺失

使用键盘 1/2 的 claw 后备控制，或绑定 finger 节点。

状态页打不开

确认信息中枢运行在 127.0.0.1:8766。

当前工程不发送机器人关节角。所有真实运动都应视为实验流程，并在机械安全范围内进行。