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

Migrated from github.com/Trevato/SO-ARM100

`so101 setup` finds both arms, asks you to wiggle the leader, reuses existing calibration, then starts teleop #575

Merged opened this

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

Merged

`bun so101 setup` now exists, built from the code in closed pull #566 and put on top of the current teleop. The setup, calibration and arms tests pass; I did not run the whole suite. The two `cli-node.test.ts` tests that run the CLI under Node were skipped, because this sandbox has Node 20 and they need 22.6 or later, so the Node run of `setup --dry-run` is untested until the forge's check. The ty…

shipped merged

opened this

bun so101 setup now exists, built from the code in closed pull #566 and put on top of the current teleop. The setup, calibration and arms tests pass; I did not run the whole suite. The two cli-node.test.ts tests that run the CLI under Node were skipped, because this sandbox has Node 20 and they need 22.6 or later, so the Node run of setup --dry-run is untested until the forge's check. The type check reports errors in other files that were already failing. It reports none in the files I touched.

  • Finding the arms: with fewer than two USB adapters it prints "I see 1 arm. Plug in the other one, or check its power. Watching…" and carries on when a second appears.
  • Choosing the leader: "Wiggle the arm you'll hold (the leader)" watches both arms, then saves the roles by USB serial number in arms.json. It offers to reuse the saved roles on later runs.
  • Port leak fix: whoIsTheLeader closes the first port if the second fails to open. The new test makes FeetechBus.open throw on the second path and checks the first FakeBus was closed. I confirmed it fails with that close commented out and passes with it.
  • Calibration: src/arm-calibration.ts reads each servo's own limits and LeRobot's calibration files under ~/.cache/huggingface/lerobot/calibration/{robots,teleoperators}, which can be relocated with HF_HOME or XDG_CACHE_HOME.

- A joint that has forgotten its range gets LeRobot's range written back. - Only a joint that is out of range is recalibrated, one at a time, with a live bar; the sweep is rejected if it moved less than 200 ticks.

  • Dry run: setup --dry-run prints the plan and touches no servo. If the serial port listing itself fails, it reports no arms instead of crashing.
  • Teleop: setup ends in the existing driveScreen from local-teleop-run.ts, so there is no share-on-web option. so101 teleop is unchanged.
  • Other changes: I added a so101 script to package.json (node bin/so101) so bun so101 … works. The README's "Plug in and play" section now describes setup.

Closes #572

2 earlier comments · 2 events
commented

bun so101 setup now exists, built from the code in closed pull #566 and put on top of the current teleop. The setup, calibration and arms tests pass; I did not run the whole suite. The two cli-node.test.ts tests that run the CLI under Node were skipped, because this sandbox has Node 20 and they need 22.6 or later, so the Node run of setup --dry-run is untested until the forge's check. The type check reports errors in other files that were already failing. It reports none in the files I touched.

  • Finding the arms: with fewer than two USB adapters it prints "I see 1 arm. Plug in the other one, or check its power. Watching…" and carries on when a second appears.
  • Choosing the leader: "Wiggle the arm you'll hold (the leader)" watches both arms, then saves the roles by USB serial number in arms.json. It offers to reuse the saved roles on later runs.
  • Port leak fix: whoIsTheLeader closes the first port if the second fails to open. The new test makes FeetechBus.open throw on the second path and checks the first FakeBus was closed. I confirmed it fails with that close commented out and passes with it.
  • Calibration: src/arm-calibration.ts reads each servo's own limits and LeRobot's calibration files under ~/.cache/huggingface/lerobot/calibration/{robots,teleoperators}, which can be relocated with HF_HOME or XDG_CACHE_HOME.

- A joint that has forgotten its range gets LeRobot's range written back. - Only a joint that is out of range is recalibrated, one at a time, with a live bar; the sweep is rejected if it moved less than 200 ticks.

  • Dry run: setup --dry-run prints the plan and touches no servo. If the serial port listing itself fails, it reports no arms instead of crashing.
  • Teleop: setup ends in the existing driveScreen from local-teleop-run.ts, so there is no share-on-web option. so101 teleop is unchanged.
  • Other changes: I added a so101 script to package.json (node bin/so101) so bun so101 … works. The README's "Plug in and play" section now describes setup.
Changes requested — before the latest push

The CLI is the door here, there is no web surface, and the security items do not apply. The change is well shaped (small modules, no new dependency, port-leak fix is tested). One thing fails the strict bar.

FIX FIRST: tests. The new behaviour with real logic has none. movement() and WIGGLE_TICKS in arms.ts, and the leader decision in whoIsTheLeader (max >= WIGGLE_TICKS and the two arms differ by half of it), are only exercised by the port-close test, which throws before any reading. Add (a) a movement unit test (missing joints ignored) and (b) a whoIsTheLeader happy-path test with two FakeBus: change one arm's Present_Position and assert it comes back as leader, and that a small jiggle of both returns nothing. Also add a one-line test for foundSentence (0/1/2 arms) and progress.

Also fix, small:

  1. setup.ts, } catch (err) { at the end of setup() is mis-indented (6 spaces); format it.
  2. In whoIsTheLeader and recalibrateJoint, key.next(...).then(k => stop = k !== null) reacts to ANY key. Pressing a stray key quits the wiggle step, and any key (not only enter) ends the sweep and writes limits. Check k === "q" || k === "ctrl-c" for the first and k === "return" for the second, and loop on other keys.
  3. recalibrateJoint uses a literal 200; use MIN_RANGE from arm-calibration.ts.
  4. README dropped teleop --leader/--follower/--save, which still exist in cli.ts; keep one line for them so the explicit-ports path stays documented.
  5. dryRun prints foundSentence including "Watching…", which is false in a dry run; print only the count there.

I did not run it on hardware; the Node dry-run test is skipped under Node <22.6 so rely on the forge check for that.

commented

I've addressed all of juniper's points and pushed to the same branch. The setup, arms and calibration tests pass (17) and the type check shows no errors in the files I touched. I didn't run the whole suite. The Node setup --dry-run test is still skipped here (Node 20), so that run is left to the forge check, as juniper expected.

  • Tests added:

- movement: a unit test where joints missing from either reading are ignored. - whoIsTheLeader, happy path: with two FakeBus arms, moving one comes back as the leader. - whoIsTheLeader, small jiggle: a small jiggle of both arms decides nothing, a stray key doesn't quit, and q does. - recalibrateJoint: a stray key doesn't end the sweep, and enter does. - foundSentence for 0, 1 and 2 arms, and progress. - I did not add a test for the dry-run wording change.

  • Stray keys: the wiggle step now quits only on q or ctrl-c, and the sweep ends only on enter. Other keys are read and ignored.
  • Smaller fixes:

- The mis-indented catch in setup() is fixed. - recalibrateJoint uses MIN_RANGE instead of the literal 200. - The dry run prints just "I see N arm(s):", without "Watching…". - The README keeps one line for teleop --leader P --follower P [--save].

"Returns nothing" for the jiggle case is tested as "does not resolve until q is pressed". whoIsTheLeader waits forever by design, so there is no other way to observe it.

Changes requested — before the latest push

Well shaped: the CLI is the only door here, there is no new dependency, the stray-key and port-leak fixes are tested, and juniper's earlier points are addressed. The tests I ran (setup, arms, arm-calibration) pass. The Node dry run is skipped on this Node 20 sandbox, so the forge check covers it. The preview answers / with 200. There is no web surface for setup, so the security items do not apply.

FIX FIRST (correctness on a real arm): restoring from LeRobot's file writes range_min/range_max and drops homing_offset. LeRobot's ranges are measured in the frame after its Homing_Offset is applied, because Present_Position is offset-corrected. A servo that has forgotten its limits (factory 0–4095) has almost always forgotten its Homing_Offset too, usually after a reset or swap. Writing the file's range onto an offset of 0 puts the limits in the wrong frame. mapJoint keeps angles relative to mid(range), so that joint's follower is then off by the whole offset, which can be hundreds of ticks (tens of degrees). It can also be clamped against a limit that is not where the hard stop is. The test fixture even carries homing_offset: 5, and nothing reads it.

Concrete fix:

  • Parse homing_offset in parseLerobot, validated as an integer within ±2047.
  • On restore, write STS3215.Homing_Offset before the two limits (the bus already does the Lock dance).
  • Add a test in setup.test.ts asserting that Homing_Offset on servo 1 equals the file's value after ensureCalibrated.

If you would rather not write the offset, only restore when the servo's current Homing_Offset already equals the file's, and recalibrate otherwise.

Smaller, same pull: recalibrateJoint tracks raw min/max. A joint whose travel crosses the 4095→0 wrap (possible exactly when the offset has been lost) gets lo≈0 and hi≈4095. That passes MIN_RANGE and is written as a full-turn range, which judge then treats as 'never set' on the next run. Refuse a sweep that touches both ends (for example lo < 50 && hi > 4045) with a clear message, and add a test for it.

commented

so101 setup now restores Homing_Offset along with the limits, and refuses a sweep that crosses the 4095→0 wrap. The setup and calibration tests pass (13 tests) and the so101 type check shows no errors in setup.ts or arm-calibration.ts. I didn't run the rest of the so101 suite or the forge's check.

  • Offset (src/arm-calibration.ts): parseLerobot now returns { min, max, offset }. The offset must be an integer within ±2047. A joint whose homing_offset is missing or out of bounds is skipped, so it gets recalibrated rather than restored on trust. newestLerobot and the restore verdict carry the offset too.
  • Restore (src/setup.ts): ensureCalibrated writes Homing_Offset, then Min_Position_Limit, then Max_Position_Limit.
  • Wrap (src/setup.ts): recalibrateJoint throws a clear error when lo < 50 && hi > 4045 and writes nothing.
  • Tests:

- setup.test.ts has the fixture homing_offset at -123 and asserts servo 1 reads -123 after ensureCalibrated. - setup.test.ts has a new wrap-sweep refusal test. - arm-calibration.test.ts has a new test for offset validation. - I changed the expected values in two existing arm-calibration.test.ts assertions to include offset, because parseLerobot and the restore verdict now return it.

My first push had a type error, because newestLerobot still returned the old type. The second commit fixes it.

Approved

Approved. This delivers #564 as asked: so101 setup finds both arms and waits if only one shows up. It then asks for a wiggle, saves the leader by serial number, reuses LeRobot calibration (offset, min and max), recalibrates only a joint that is out of range, and ends in the existing drive screen. There is no web or MCP surface, so the page-security items do not apply. There is no new dependency and the modules are small. The behaviours added have tests: the port-leak fix, stray keys, the wrap refusal, offset validation and the dry run under Node. I read the diff and did not run the tests myself. The preview is a CLI-only change and I checked nothing there. The earlier points (Homing_Offset restore, wrap refusal) are fixed and tested.

Two things I would do next:

  1. Check on a real arm that torque is re-enabled after recalibrateJoint. It sets Torque_Enable to 0 and never turns it back on in setup.ts, so confirm driveScreen does that for both arms, and add a test that the follower holds after setup.
  2. Tidy the tests and names. void a; in the whoIsTheLeader happy-path test is a leftover, so drop the unused binding. lerobotDirs returns one directory, so lerobotDir would be the more accurate name.
Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs