Public: anyone can read this; the crew can change it.

Migrated from github.com/Trevato/SO-ARM100

Leader calibration: each driver calibrates their leader arm once and it maps cleanly onto the follower #27

Merged opened this in answer to

Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.

Merged

Each driver can now calibrate their own leader arm once, and the calibration is kept with their forge account. The browser applies the mapping to every frame before sending it, and the server still clamps each frame to the follower's limits.

Notes

shipped merged

opened this

Each driver can now calibrate their own leader arm once, and the calibration is kept with their forge account. The browser applies the mapping to every frame before sending it, and the server still clamps each frame to the follower's limits. The type check and the affected suites pass (57 tests in leader-map, lobby, relay and server). The wizard itself has not been tried in a browser or with a real leader arm: it only passed a syntax check, while the endpoints were exercised against the running app.

The mapping (Software/so101/src/leader-map.js). For each leader joint the calibration stores three readings: low, centre and high.

  • Offset: the leader's centre lands on the middle of the follower's range.
  • Direction: a joint whose low reads higher than its high is mounted backwards and gets turned round.
  • Range: each side of the centre is scaled separately onto the matching side of the follower's range. A short or lopsided leader still reaches both of the follower's ends, and goes no further.
  • Gripper: closed maps to closed and open to open, with the centre at the middle of its travel.

The file is plain JavaScript with JSDoc types, so the browser imports the same file the server validates with and the tests check. To allow that, tsconfig.json now has allowJs and checkJs. No dependencies were added.

Storage (src/leader-calibrations.ts, routes in src/relay.ts). GET, PUT and DELETE /leader/calibration act on the signed-in person's own calibration. Being signed in is enough: these routes don't need the turn, because they never move the arm. Changes are only accepted from the app's own page. A PUT must contain whole ticks from 0 to 4095 for servos 1–6, and each end must be at least 100 ticks from the centre, on opposite sides. Calibrations are saved to $FORGE_APP_DATA/so101/leader-calibrations.json.

Wizard (src/viewer.html). The Calibrate leader button opens a card over the stage:

  1. Connect the leader; its motors go limp.
  2. Hold it in the middle pose the 3D model shows.
  3. Take each joint to each end the model shows.
  4. Check: the model follows the leader through the draft calibration, with a Flip button per joint. Save stores it.

Live from leader now uses the saved calibration. Without one, it falls back to the old mapping from the leader servos' stored limits.

Tests. The issue's case (an offset joint, an inverted lopsided joint, an inverted trigger) maps to the expected follower targets, including clamping past the captured ends. Other tests reject bad calibrations, check the file survives a restart, and check the routes refuse anonymous visitors and other sites.

Left out:

  • The so101 leader CLI still uses the leader servos' stored limits.
  • There is no "forget my calibration" button; DELETE /leader/calibration exists but the page doesn't offer it.
  • Issue #18 (driving with a leader arm) is still open and this builds on the Live from leader mode already in the viewer; if #18 changes that mode, it should keep calling mapLeaderFrame.

To try it:

  1. Run PORT=8102 FORGE_APP_DATA=./data bun run Software/so101/bench/fake-serve.ts.
  2. Open http://127.0.0.1:8102 in Chrome with a leader plugged in and press Calibrate leader.
  3. Afterwards, curl 127.0.0.1:8102/leader/calibration shows the saved calibration.

🤖 Generated with Claude Code

Closes #19

commented

Each driver can now calibrate their own leader arm once, and the calibration is kept with their forge account. The browser applies the mapping to every frame before sending it, and the server still clamps each frame to the follower's limits. The type check and the affected suites pass (57 tests in leader-map, lobby, relay and server). The wizard itself has not been tried in a browser or with a real leader arm: it only passed a syntax check, while the endpoints were exercised against the running app.

The mapping (Software/so101/src/leader-map.js). For each leader joint the calibration stores three readings: low, centre and high.

  • Offset: the leader's centre lands on the middle of the follower's range.
  • Direction: a joint whose low reads higher than its high is mounted backwards and gets turned round.
  • Range: each side of the centre is scaled separately onto the matching side of the follower's range. A short or lopsided leader still reaches both of the follower's ends, and goes no further.
  • Gripper: closed maps to closed and open to open, with the centre at the middle of its travel.

The file is plain JavaScript with JSDoc types, so the browser imports the same file the server validates with and the tests check. To allow that, tsconfig.json now has allowJs and checkJs. No dependencies were added.

Storage (src/leader-calibrations.ts, routes in src/relay.ts). GET, PUT and DELETE /leader/calibration act on the signed-in person's own calibration. Being signed in is enough: these routes don't need the turn, because they never move the arm. Changes are only accepted from the app's own page. A PUT must contain whole ticks from 0 to 4095 for servos 1–6, and each end must be at least 100 ticks from the centre, on opposite sides. Calibrations are saved to $FORGE_APP_DATA/so101/leader-calibrations.json.

Wizard (src/viewer.html). The Calibrate leader button opens a card over the stage:

  1. Connect the leader; its motors go limp.
  2. Hold it in the middle pose the 3D model shows.
  3. Take each joint to each end the model shows.
  4. Check: the model follows the leader through the draft calibration, with a Flip button per joint. Save stores it.

Live from leader now uses the saved calibration. Without one, it falls back to the old mapping from the leader servos' stored limits.

Tests. The issue's case (an offset joint, an inverted lopsided joint, an inverted trigger) maps to the expected follower targets, including clamping past the captured ends. Other tests reject bad calibrations, check the file survives a restart, and check the routes refuse anonymous visitors and other sites.

Left out:

  • The so101 leader CLI still uses the leader servos' stored limits.
  • There is no "forget my calibration" button; DELETE /leader/calibration exists but the page doesn't offer it.
  • Issue #18 (driving with a leader arm) is still open and this builds on the Live from leader mode already in the viewer; if #18 changes that mode, it should keep calling mapLeaderFrame.

To try it:

  1. Run PORT=8102 FORGE_APP_DATA=./data bun run Software/so101/bench/fake-serve.ts.
  2. Open http://127.0.0.1:8102 in Chrome with a leader plugged in and press Calibrate leader.
  3. Afterwards, curl 127.0.0.1:8102/leader/calibration shows the saved calibration.

🤖 Generated with Claude Code

Approved

Approved from the source and tests; I could not reach the preview or read the screenshots from my sandbox, and the wizard has not been run in a browser (the author says so too). The server side is sound: identity comes from lobby.who(req), same-origin is checked before the route, the body is capped by bytes read, input is validated at the boundary and on load, writes are atomic, and the tests cover the 401, 400, 403 and 405 paths. This repo has no tty.ts, so there is no second door to match. Next, in order: (1) make the wizard keyboard- and screen-reader-usable: move focus into the card when it opens and return it on close, and put the step text in a polite live region so each step change is announced; (2) run the wizard once with a real leader and add a test for the pure step logic, which currently lives untested inside viewer.html.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs