Getting Started¶

Run commands from the repository root unless a step explicitly changes directory.

1. Prepare the Hardware¶

The standard research-preview tracker uses five ICM-20948 nodes: chest, upper_arm, forearm, palm, and finger. A four-node minimum configuration can omit finger; in that mode claw falls back to keyboard control with 1 and 2 in 0.2 steps.

Review Hardware, the normalized BOM/body-tracker-bom.csv, and the wearing videos in Media Assets before powering boards.

2. Flash the Firmware¶

Install ESP-IDF 5.5.x for ESP32-C3, configure local Wi-Fi with idf.py menuconfig, then build and flash each node:

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

Replace /dev/ttyACM0 with the enumerated serial port. Do not commit local Wi-Fi credentials or generated build directories.

3. Discover and Inspect Nodes¶

In live mode, nodes announce their UDP/TCP ports and firmware version. Before calibration, verify:

Field	Expected check
`role`	Bound to one of `chest`, `upper_arm`, `forearm`, `palm`, `finger`.
`seq`	Increases per node; gaps indicate packet loss.
`sensor_time_us`	Monotonic per node in v2 packets.
`time_sync_valid`	True after accepted TCP time-sync samples.
`sample_age_ms`	Low and stable enough for a common timeline.

Use fake addresses in documentation and issues, for example 192.0.2.10; never paste real Wi-Fi passwords, MAC addresses, or private network captures.

4. Choose the Wearing Side¶

Select exactly one active side for a session:

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

Use left for left-arm sessions. The choice controls role binding, mirrored sideways directions, joint-angle signs, visualization, and output metadata. The first public version supports one active side per session.

5. Wear the IMUs¶

Mount nodes rigidly so they cannot rotate or slide during calibration:

Role	Placement	Orientation note
`chest`	Front torso	Defines `body_rh`: X forward, Y left, Z up.
`upper_arm`	Middle upper arm	Keep a repeatable visible board direction; recalibrate after changes.
`forearm`	Middle forearm	Keep a repeatable visible board direction; avoid elbow and wrist joints.
`palm`	Back of hand	Prefer local +X from wrist toward fingertips.
`finger`	Finger segment	Prefer local +X from wrist toward fingertip.

The body calibration estimates mounting alignment, but it cannot correct a loose strap or an IMU that slips during motion.

6. Calibrate¶

First calibrate each IMU as a sensor, including magnetometer calibration when used. Then perform body calibration with all nodes worn:

arm naturally down;
arm forward and level;
arm sideways and level, palm down;
roll-axis motion;
palm/finger straight reference for palm roll/pitch and claw=1.

The visualizer shows countdown, sample count, quaternion angular standard deviation, variance, and failure hints. Calibration snapshots record wear_side, frame=body_rh, role IDs, body lengths, and reference poses.

7. View the Body Tracker¶

The demo replays sanitized input through the same mocap solver and visualizer:

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

This requires a desktop OpenGL environment. The replay contains no real device identifiers, Wi-Fi credentials, or private calibration files.

For live visualization, replace --replay ... with --wear-side right or --wear-side left after nodes are online and calibrated. Missing nodes are marked invalid; finger absence only disables sensor-based claw.

8. Record and Replay¶

Use three terminals:

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

The local status page is http://127.0.0.1:8766. In live mode, the bridge owns the UDP input; do not run another live receiver on the same UDP port.

JSONL replay stores calibration snapshots and frame timing so the same file can be used by the visualizer, WebSocket hub, ROS 2 adapter, and Unity client.

Troubleshooting¶

Symptom	First check
Device not discovered	Confirm Wi-Fi SSID, subnet, power, firmware version, and firewall rules.
Flash fails	Check serial permissions, boot mode, cable, port name, and ESP-IDF target.
Timestamp invalid	Confirm v2 firmware and monotonic `sensor_time_us`.
Sync error high	Check RTT, packet loss, power stability, and Wi-Fi congestion.
Calibration variance high	Tighten straps, repeat the pose, keep the arm still during static capture.
Side looks mirrored	Confirm `--wear-side` and role binding before recalibrating.
Finger missing	Use keyboard `1`/`2` claw fallback or bind a `finger` node.
Status page unavailable	Confirm the hub is running on `127.0.0.1:8766`.

The project does not currently send robot joint angles. Treat all physical motion as an experimental workflow with appropriate mechanical safety limits.