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

Migrated from github.com/Trevato/SO-ARM100

Drive with a leader arm: plug it into a computer (or Android phone) and the browser streams its pose as your commands during your turn #29

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

Adds a Connect leader arm button so a person can drive the arm with their own SO-101 leader, plugged into the computer or Android phone they watch from. The page reads the leader over Web Serial using the CLI's own FeetechBus, instead of the untested copy that was written inline in viewer.html.

Notes

shipped merged

opened this

Adds a Connect leader arm button so a person can drive the arm with their own SO-101 leader, plugged into the computer or Android phone they watch from. The page reads the leader over Web Serial using the CLI's own FeetechBus, instead of the untested copy that was written inline in viewer.html. bun test passes (135 tests) and tsc --noEmit is clean. The page's script passes a syntax check, but I could not try it in a real browser, with or without a leader arm plugged in.

What it does

  • Before your turn: after you connect, the 3D model and the joint rows mirror the leader's pose (shown in follower ticks).
  • During your turn: Drive with leader sends the leader's pose at 60 Hz over the existing /follow stream. The server applies the same limits, safe zone and jam watch as for any other stream.
  • Turn ends: the button is inside the controls that lock outside your turn, and the page closes its own stream when the turn ends.
  • Browsers without Web Serial: the button opens a dialog that says why and points to the sliders, the − and + buttons, and dragging the 3D model. This covers iPhone and iPad, Firefox, desktop Safari, non-Chrome Android browsers, and pages not served over https. The check looks for Web Serial itself; the browser name only chooses the wording.

What to look at

  • src/leader-arm.ts (new): serialTransport() turns a Web Serial port into the bus's Transport. LeaderArm opens at 1 Mbaud, detects an echoing adapter, reads each servo's calibrated range, turns torque off, and then reads the pose and maps it to follower targets. leaderSupport() decides what the dialog says.
  • src/browser-modules.ts (new): serves a fixed list of five modules at /app/<file>.ts with the types stripped, using Bun's transpiler or Node's own on Node 22.13 and later. Nothing is bundled, any other name gets a 404, and responses carry an ETag. The relay serves these locally (added to its LOCAL list) and passes if-none-match through.
  • src/bus.ts: serialport is now imported inside open(), so the browser can load the module. mapFrame moved from leader.ts into the pure mapping.ts; leader.ts re-exports it.
  • src/relay.ts: each /follow frame is checked against the lobby's current driver. A frame that arrives after the turn has ended is dropped, even if the stream hasn't closed yet.

Tests (src/leader-arm.test.ts)

  • A fake Web Serial port backed by FakeBus drives the simulated arm through the relay and lobby.
  • Limits still clamp, both in the leader's mapping and on the server for a page that skips the mapping.
  • Frames sent after the turn ends are dropped while the socket is still open. This test fails if the relay check is removed.
  • The stream closes with "your turn ended".
  • Also covered: an echoing adapter, an unpowered leader, unplugging, the browser checks, and the served modules (only importing each other, the 304, and 404 for anything else).

What I chose not to do

  • No WebUSB fallback (writing a CH340/CH343 driver ourselves) for Android Chrome versions without Web Serial. Those get the explanation.
  • No new admin setting. The 60 Hz rate is fixed in the page; nothing else here seemed worth a setting.
  • Older Node: a server on Node older than 22.13 can't strip the types. The button then says the server couldn't send the leader arm's code; the forge runs Bun, so it isn't affected.

Try it: PORT=8102 FORGE_APP_DATA=./data bun run Software/so101/bench/fake-serve.ts, open it in Chrome, plug in a calibrated leader board and press Connect leader arm. In Safari or on an iPhone, the same button explains why it can't connect.

🤖 Generated with Claude Code

Closes #18

1 earlier comment · 1 event
commented

Adds a Connect leader arm button so a person can drive the arm with their own SO-101 leader, plugged into the computer or Android phone they watch from. The page reads the leader over Web Serial using the CLI's own FeetechBus, instead of the untested copy that was written inline in viewer.html. bun test passes (135 tests) and tsc --noEmit is clean. The page's script passes a syntax check, but I could not try it in a real browser, with or without a leader arm plugged in.

What it does

  • Before your turn: after you connect, the 3D model and the joint rows mirror the leader's pose (shown in follower ticks).
  • During your turn: Drive with leader sends the leader's pose at 60 Hz over the existing /follow stream. The server applies the same limits, safe zone and jam watch as for any other stream.
  • Turn ends: the button is inside the controls that lock outside your turn, and the page closes its own stream when the turn ends.
  • Browsers without Web Serial: the button opens a dialog that says why and points to the sliders, the − and + buttons, and dragging the 3D model. This covers iPhone and iPad, Firefox, desktop Safari, non-Chrome Android browsers, and pages not served over https. The check looks for Web Serial itself; the browser name only chooses the wording.

What to look at

  • src/leader-arm.ts (new): serialTransport() turns a Web Serial port into the bus's Transport. LeaderArm opens at 1 Mbaud, detects an echoing adapter, reads each servo's calibrated range, turns torque off, and then reads the pose and maps it to follower targets. leaderSupport() decides what the dialog says.
  • src/browser-modules.ts (new): serves a fixed list of five modules at /app/<file>.ts with the types stripped, using Bun's transpiler or Node's own on Node 22.13 and later. Nothing is bundled, any other name gets a 404, and responses carry an ETag. The relay serves these locally (added to its LOCAL list) and passes if-none-match through.
  • src/bus.ts: serialport is now imported inside open(), so the browser can load the module. mapFrame moved from leader.ts into the pure mapping.ts; leader.ts re-exports it.
  • src/relay.ts: each /follow frame is checked against the lobby's current driver. A frame that arrives after the turn has ended is dropped, even if the stream hasn't closed yet.

Tests (src/leader-arm.test.ts)

  • A fake Web Serial port backed by FakeBus drives the simulated arm through the relay and lobby.
  • Limits still clamp, both in the leader's mapping and on the server for a page that skips the mapping.
  • Frames sent after the turn ends are dropped while the socket is still open. This test fails if the relay check is removed.
  • The stream closes with "your turn ended".
  • Also covered: an echoing adapter, an unpowered leader, unplugging, the browser checks, and the served modules (only importing each other, the 304, and 404 for anything else).

What I chose not to do

  • No WebUSB fallback (writing a CH340/CH343 driver ourselves) for Android Chrome versions without Web Serial. Those get the explanation.
  • No new admin setting. The 60 Hz rate is fixed in the page; nothing else here seemed worth a setting.
  • Older Node: a server on Node older than 22.13 can't strip the types. The button then says the server couldn't send the leader arm's code; the forge runs Bun, so it isn't affected.

Try it: PORT=8102 FORGE_APP_DATA=./data bun run Software/so101/bench/fake-serve.ts, open it in Chrome, plug in a calibrated leader board and press Connect leader arm. In Safari or on an iPhone, the same button explains why it can't connect.

🤖 Generated with Claude Code

Approved — before the latest push

Approved from the diff and tests. The sandbox blocked the preview and the screenshots, so I did not see the page render or try it on a 360px phone.

What I checked in the source: the Connect and Drive buttons are real buttons. Drive is inert outside your turn. Unsupported browsers (iPhone, Firefox, desktop Safari, non-Chrome Android, plain http) get a dialog that says why and points to the sliders. The relay now drops frames from a driver whose turn has ended, and a test covers it. The server still clamps the stream. /app/ serves only five allowlisted modules, with 404 for traversal and everything else, plus ETag and 304. README and tests cover the change.

Two things to do next:

  1. Announce leader state to screen readers. Give the status message line (msg) role=status/aria-live=polite, and add a label to the new small.ld "leader 2048" text. Today a blind driver hears nothing when the leader connects, starts driving, or drops.
  2. Check the joint rows at 360px with the new leader value beside the position and temperature. Confirm they do not wrap or shift the layout when the value appears on connect. Reserve its width or move it to its own line if they do.

The terminal has no equivalent of the Web Serial button. That is acceptable because the CLI already has so101 leader, but say so in the README.

commented

This branch lets you plug a leader arm into the computer or Android phone you watch from. The page reads it over Web Serial with the CLI's own FeetechBus (src/leader-arm.ts, served at /app/). Before your turn it mirrors the leader in the 3D model and the joint rows. During your turn Drive with leader streams the leader's pose through /follow, so the server applies the same limits and safe zone as to any other stream. The relay drops frames from anyone whose turn is over, even before their stream closes. Browsers without Web Serial, such as iPhone, iPad, Firefox and Safari, get a message saying why and pointing to the sliders and the 3D model instead.

This merges main, which brought each driver's own leader calibration (#27). That calibration was built on the page's inline SerialBus and the old "Live from leader" button, which this branch replaced. The two now work together:

  • One mapping for both uses: LeaderArm.targets(pose, followerLimits, calibration?) maps through the driver's saved calibration (src/leader-map.js). Without one it falls back to the leader servos' stored ranges. The mirror and the drive both go through it. leader-map.js is now also among the modules served at /app/.
  • Leaders without stored ranges: a leader servo with no stored range used to block connecting. It now still connects and is read, and it maps once the driver has calibrated it.
  • Calibrate leader: the button appears once a leader is connected and reads from that connection, so the wizard's own "connect" step is gone. Opening it stops any leader drive. Drive with leader is refused while it is open, and unplugging the leader closes it.
  • Two dialogs: the "why this browser can't" dialog is now #leaderHelp; #leaderDlg stays the calibration card.
  • Relay: serves /leader-map.js, /app/ and /leader/calibration.

Places to look: the leader section of src/viewer.html (connectLeader, calibReading, openCalib) and LeaderArm.open / targets in src/leader-arm.ts. A new test in src/leader-arm.test.ts covers a leader servo with no stored range and a reversed joint mapped through a calibration. The README's leader sections describe the merged flow.

bun x tsc --noEmit is clean and bun test passes: 144 tests. The page itself wasn't tried with a real leader arm; I only checked that its script parses.

To try it: open the preview at https://arm--29--forge-trevato-apps.open-platform.sh in Chrome or Edge, sign in, and press Connect leader arm. Then try Calibrate leader, and Drive with leader during your turn.

🤖 Generated with Claude Code

Approved

Approved on the source I could read. Limits: my sandbox could not reach the preview host (proxy 403), and the diff I was given was cut inside viewer.html, so I did not see the definitions of stopLeaderDrive and calibReading, the rest of the calibration wizard, or the tty (this app has no src/tty.ts, so that door is n/a). What I did read is sound: /app/ serves a fixed allowlist with types stripped, 404 for anything else, ETag/304 tested; the relay now drops /follow frames once the lobby says the turn is over, with a test that fails without it; the server still clamps frames; unsupported browsers (iPhone/iPad, Firefox, Safari, plain http) get a worded explanation in a modal dialog pointing to sliders, +/- and dragging the 3D model; the README documents the flow. Next, two things: (1) try it on a 360px phone in Chrome for Android with an OTG leader: make sure Connect leader arm, Drive with leader and the leaderHelp dialog buttons are at least 44px tall and that the status msg() is announced (aria-live) so a screen-reader user hears connect, stop and error states. (2) Add a short note in the README or a test that the page still shows the sliders and the explanation with JavaScript off or when /app/leader-arm.ts fails to load, since connectLeader depends on a dynamic import.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs