View telemetry

Result: open a log and verify that its display corresponds to the actual mechanism. The viewer reads files; it never connects to servos, commands hardware or predicts PID tuning results.

Install and open logs

From the project root, using Python 3.12:

python3.12 -m venv tools/simulation/.venv
tools/simulation/.venv/bin/python -m pip install -r tools/simulation/requirements.txt
mkdir -p logs/motion

py -3.12 -m venv tools/simulation/.venv
.\tools\simulation\.venv\Scripts\python.exe -m pip install -r tools/simulation/requirements.txt
New-Item -ItemType Directory -Force logs/motion | Out-Null

Watch the log directory in one terminal:

tools/simulation/.venv/bin/python tools/simulation/viewer.py live logs/motion --model so101

.\tools\simulation\.venv\Scripts\python.exe tools/simulation/viewer.py live logs/motion --model so101

An empty directory waits for its first recording. Start hardware control in another terminal; the viewer follows the new log and switches to subsequent sessions. It looks for .ndjson files in that directory, not its subdirectories. Closing the viewer does not stop hardware control.

To view a completed session, replace EVENTS.ndjson with its path:

tools/simulation/.venv/bin/python tools/simulation/viewer.py play EVENTS.ndjson --model so101

.\tools\simulation\.venv\Scripts\python.exe tools/simulation/viewer.py play EVENTS.ndjson --model so101

Select --model so101 for SO-101 or --model so102 for SO-102. SO-102 is the default. Models and meshes are bundled. A named-pose POSES.json is not a viewer log: replay it through the controller, then open the resulting event log.

Check the position mapping

Calibration and display mapping are separate:

angle = referenceRadians + (counts − referenceCount) × radiansPerCount

Logged counts already include the servo’s position correction; do not subtract it again.

SO-101 is labelled reference pose assumed: this is an assumption, not detected alignment. The gripper uses encoder angle, not normalized 0–100 opening. The SO-102 map binds the original arm’s specific offsets.

After recalibration, match the physical reference to URDF angles. Check a second pose and the sign of a small manual movement at each joint; one matching pose cannot verify scale or direction. Minimum and maximum encoder counts do not derive these angles automatically.

For a custom version 2 map, copy tools/simulation/so101-encoder-map.json or tools/simulation/encoder-angle-map.json, edit it and provide its path:

tools/simulation/.venv/bin/python tools/simulation/viewer.py play EVENTS.ndjson --model so101 --mapping MY_MAP.json

.\tools\simulation\.venv\Scripts\python.exe tools/simulation/viewer.py play EVENTS.ndjson --model so101 --mapping MY_MAP.json

MY_MAP.json is your map with correct model, joints, fixedJoints and optional encoderCalibration. Every model joint must be mapped or fixed. Changing only calibration-check fields does not correct physical angle conversion. Selecting a viewer model does not change the hardware controller or its gravity model.

Interpret the display

Measured pose and the cyan reference are different. Detailed C2 feedback contains the intermediate planned trajectory; compact C1 contains measurements only, so comparison uses the commanded destination. Error relative to the final destination during movement is not tracking error relative to the plan.

The viewer does not recreate missing measurements. Stale data is labelled; commands alone cannot refresh it. Charts retain up to 20 seconds. Playback holds the last frame without automatically looping; reopen a replaced or truncated file.

Keys: 1–6 select a motor; G reference overlay; C charts; J joints; M/R measured/reference pose; F quality; H help. The grid is visual, without collisions. Geometry is reproduced with simulator contacts and gravity disabled.

Check: the model matches the arm, two physical poses and joint directions display correctly, and you understand the feedback type. Correct the mapping before judging control performance if these checks fail.

Documentation home · Source revision: a995f77. Extension 9.0.