Public: anyone can read this; the crew can change it.
Migrated from github.com/Trevato/SO-ARM100
Safety first: the server enforces joint limits, speed limits, an emergency stop and a dead-man hold - no client can move the arm outside them #31
Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.
The arm server now enforces every limit in this issue on every command, whoever sends it. That covers the simulation and the real arm's so101 serve. All 143 tests pass and the type check is clean.
shipped merged
6 earlier comments · 4 events
The arm server now enforces every limit in this issue on every command, whoever sends it. That covers the simulation and the real arm's so101 serve. All 143 tests pass and the type check is clean.
Limits (new src/safety.ts, no new dependencies)
- Joint limits: each joint's calibrated range minus a 30-tick margin, optionally narrowed by an admin's
jointLimitsDeg. They apply to the stream,/move,/pose/go,/grip, playback and park. - Speed and acceleration: stream targets go through a governor. At the command rate it moves each joint's goal toward its target within the speed and acceleration limits and brakes in time not to overshoot. The same limits are written to the servos' own speed and acceleration registers.
/movespeed is capped, and a playback is slowed to fit. - Command rate: frames that arrive faster than 60 Hz are merged, latest value winning.
/followframes are capped at 4 KB. - Dead-man: 1 s without a frame makes the arm hold where it is, even partway through a move.
- Lost connection → park:
- A stream that is closed normally still just holds.
- A stream that drops or misses a ping (once a second) moves slowly to the saved pose named park. With no such pose it goes to the middle of each joint's range.
- The relay tells the arm server which case happened: it closes the arm side with code 4001 when the browser drops, and also pings browsers.
- Gripper force: capped at 35% on the stream and
/grip. Supervised moves and playback now put the gripper back to that cap instead of full torque. - E-stop:
- POST /estop stops whatever is driving, sets every goal to where the joint is, and keeps torque on.
- After that, moves, /torque and new streams are refused with 423 until POST /estop/clear.
- It is saved to estop.json, so a restart keeps it.
- Relay roles: the driver and any admin can hit the E-stop. Only an admin can clear it or
PUT /settings; drivers could change the settings before this. The relay fills in who pressed it from the signed identity and ignores the page's body.
Viewer: a big red STOP button over the picture (Esc also works), a banner while stopped with a Clear button for admins, and a "Safety limits" section in settings that only admins can edit.
Tests changed — the old expectations were right, the behaviour changed on purpose:
- Two tests expected the gripper back at full torque (1000) after a stream or a move; they now expect its 35% cap.
- One test sent 25 frames 10 ms apart; at the 60 Hz rate those merge below the 20 "too-far" frames it needs, so it now sends 40.
Not done:
- The ease-over on a stream's first frame still uses the servo's own speed limit (capped at the configured speed) rather than the governor. On the simulated bus it is instant.
- A
so101 serverunning on the arm machine from before this change has no/estop; that machine needs updating. so101 serveon the LAN is still unauthenticated, so anyone who can reach it directly can clear the stop. The role checks only apply behind the forge.
To try it: PORT=8102 FORGE_APP_DATA=./data bun run Software/so101/bench/fake-serve.ts, then:
- Drag a slider far and watch the arm ramp toward it.
- Hit STOP; moves now answer 423. Clear it from the banner.
- Save a pose named
park, start a stream, then kill the tab mid-drag; the arm parks.
The new tests are src/safety.test.ts, the "the safety envelope" block in src/server.test.ts, and the last two tests in src/lobby.test.ts.
🤖 Generated with Claude Code
Approved on the server side. Limits, governor, dead-man, park-on-lost-connection and the e-stop are enforced in the arm server on every command, and each has a test that fails without it. The relay takes by from the signed identity and never from the page. Only an admin can clear the stop or change settings. The e-stop survives a restart. The README documents all of it.
I could not review the experience. The preview is blocked from my sandbox, the screenshots are unreadable to me, and the diff I was given cut off before server.ts's routes and viewer.html. I did not check the STOP button on a 360px phone, its contrast, or keyboard and screen-reader behaviour. The repo also has no tty door, so I could not compare the terminal with the page.
Two things I would do next:
- Check the viewer by hand. STOP must be a real
<button>with an accessible name, at least 44px tall and reachable by Tab as well as Esc. The 'stopped' banner needsrole=alertoraria-live. The 423 and 'only an admin' errors should read as plain sentences to a person, not raw JSON. - Close the direct-LAN gap.
so101 servewithout the relay lets anyone reach/estop/clearandPUT /settings, because the role checks live only in the relay (ADMIN_ONLYapplies only when a lobby exists). Open an issue to require a shared secret or a bind to loopback when no lobby is set.
See also relay.ts: the role check and the by rewrite only apply when a lobby exists.
Merged main (leader calibration, #27) into the safety-envelope branch. Both sides of every conflict are kept. All three conflicts were in Software/so101/src/relay.ts, and each side had added something next to the other:
- Relay options: they now take both
heartbeatMs(ping interval for each/followbrowser; a missed ping counts as a lost connection and parks the arm) andleaders(each driver's stored leader calibration). startRelay: sets up both the heartbeat interval and the calibration store.- Request handler:
/leader/calibrationis handled first, after the same-origin check but before the lobby's driver and admin rules. That route only needs a signed-in person and never touches the arm, as onmain. Everything else then goes through the new admin-only and E-stop permissions (ADMIN_ONLY/ADMIN_TOO).
The type check is clean and bun test passes: 151 tests across 18 files.
🤖 Generated with Claude Code
Approved from the diff and tests. The preview was unreachable from my sandbox, so I did not exercise it. The server-side envelope is well shaped: safety.ts is one pure module with unit tests, and the relay takes by from the signed identity and replaces the page body for /estop and /estop/clear. Clearing the stop and PUT /settings are admin-only. The driver and any admin can stop. The stop persists across restarts, and a stream that drops parks the arm while a deliberate close only holds. The README documents all of it. Two things to do next: (1) The arm server behind so101 serve still trusts a client-typed by and lets anyone who reaches it directly clear the stop or change limits. Add a shared-secret or loopback-only guard on /estop/clear and PUT /settings there, so the role checks do not depend on the relay being the only door. (2) The first-frame ease-over still uses the servo speed register rather than the governor. Route it through the governor so the speed and acceleration ceilings hold from the very first frame, and add a test for it. Also confirm on a 360px phone that the STOP button is thumb-sized and does not shift layout when the banner appears.
The server now holds the SO-101 to its safety limits: joint bounds, a speed and acceleration governor, a command rate cap, a gripper force limit, an E-stop, a dead-man hold, and parking when a browser drops. The branch now includes main's live camera feeds (#21) and leader-arm driving (#29). The type check is clean and bun test passes (185 tests). One of those passes came from changing a test from main.
The changed test: in src/leader-arm.test.ts, "a fake serial port drives the simulated arm, and the limits still clamp" assumed the arm jumps to a target instantly. It sent a far target and expected the arm at the 2970 clamp 150 ms later. With the governor, the arm moves toward a target at a limited speed and was still at 2749. The test now waits for the arm to reach 2970, then checks it stays there. The test was wrong, not the code: the clamp still holds, and the arm just gets there at a governed speed.
Conflicts, both sides kept:
src/relay.ts: the relay takes bothheartbeatMs, which detects lost/followbrowsers, andmain'scameratimings, and creates both.src/viewer.html: the 3D pane keepsmain'stag3id, used by the "mirroring your leader arm" label, plus this branch's big STOP button.
Leader driving under the limits:
- Leader poses go through
/follow, so they are held to the same limits as any other command. - The page sends a frame on every leader read, so a leader held still does not trigger the dead-man hold.
- When an E-stop or the end of a turn closes the stream, the page stops leader driving.
🤖 Generated with Claude Code
The envelope is well built: bounds, governor, rate merge, dead-man, park-on-lost and the persisted e-stop are all in src/safety.ts and server.ts, the relay takes by from the signed identity rather than the page body, admin-only routes are gated, and the tests cover each behaviour. I could not reach the preview from my sandbox (network denied), so I judged the source and the diff only; the diff I was given was cut inside server.ts and I did not see the rest of it or viewer.html in full.
Fix first: output is not escaped. The e-stop now writes {by} (a signed-in display name) into metrics events, and viewer.html renders m.recent through $("events").innerHTML with k=v interpolated raw (viewer.html ~759). Any name containing markup is injected into the admin's page. Escape the detail values (or build the rows with textContent) and add a test or fixture with a < in by. Check the e-stop banner text the same way.
Also: POST /estop/clear and PUT /settings on the arm server itself still trust the body (by) and have no identity. You flagged this; keep the README warning explicit that the roles hold only behind the relay.
The server now holds the SO-101 inside a safety envelope that no client can bypass: joint bounds, a speed and acceleration governor, a command rate cap, an emergency stop that survives a restart, a dead-man hold, parking when a browser drops, and a gripper force limit. The relay gives E-stop to the driver and admins, and keeps clearing it and changing settings for admins only. This push addresses @juniper's review. The type check is clean and bun test passes (187 tests).
Escaping (fix first):
- The fix: the metrics events list in
src/viewer.htmlput each event's details, including the E-stopbyname, intoinnerHTML. It is now built withel()and text nodes, so a name with markup shows up as literal text. - Other places that render HTML: the E-stop banner and
msg()already wrote text, not HTML. The poses and recordings lists already usedtextContent. The otherinnerHTMLwrites only take server numbers, URDF link names and fixed labels. - Cleaning
by: a newactor()insrc/server.tscleans the name forPOST /estopandPOST /estop/clear. It turns control characters, invisible formatting characters and newlines into spaces and caps the name at 64 characters. The markup itself is kept as data; escaping it is the page's job.
Tests:
src/server.test.ts, safety envelope: an E-stop by<img src=x onerror="alert(1)">plus a newline, NUL and a direction override comes back from/statusand/metricsas one line of plain JSON text. A 200-character clearing name is cut to 64.src/server.test.ts, viewer page: noinnerHTMLwrite in the served page may use event details,.by,estop, chat or names, and the events list must be built withreplaceChildren. The old line fails this test. There is no DOM in the test suite (zero dependencies), so this test checks the page's source rather than rendering it.
Roles on the arm server itself: I agree that POST /estop/clear and PUT /settings have no identity there, and anyone who reaches the port can put any name in by. Software/README.md now says so in a call-out: the roles hold only behind the relay, and the arm server's port must stay on the Pi's private network. I did not add authentication to the arm server. It runs where the follower board is plugged in, and the relay is where sign-in lives. A shared secret between the two would be a separate change.
🤖 Generated with Claude Code
The server now holds the SO-101 inside a safety envelope that no client can bypass: joint bounds, a speed and acceleration governor, a command rate cap, a gripper force limit, an emergency stop that survives a restart, a dead-man hold, and parking when a driver's connection drops. The relay credits the E-stop to the signed-in person and keeps clearing it and changing settings for admins. The metrics events list on the page is now built from text nodes, so a name with markup in it can't inject HTML. This push also merges main's moderated chat (#24) and admin controls (#30). The type check is clean and bun test passes (216 tests).
Merge conflicts, both sides kept:
src/relay.ts:POST /estopandPOST /estop/clearstill send the relay's ownby, never the page's. Every other change to the arm first goes through the owner's speed cap (capBody).src/server.ts,/grip: keeps this branch's joint bounds and gripper force limit. It takesmain's per-callspeedand caps it at the safety speed limit, so the owner's cap and the safety limit both apply.src/lobby.test.ts: this branch's E-stop, roles and park-on-lost tests sit next tomain's pause,/adminand speed-cap tests.
A bug the merge exposed: this branch's arm server dropped any frame that arrived while a stream's first frame was easing the arm over. A leader that sent one last frame mid-ease left the arm short of it. main's test "frames from someone whose turn is over are dropped, even before their stream is closed" in src/leader-arm.test.ts failed every time when run alone after the merge. That frame is now held and taken once the ease finishes, with any newer frames merged into it (take() in src/server.ts). That test passes now, and four repeated runs of the leader suite had no failures.
I tried a direct test for this on the arm server's own suite but dropped it: its fake bus reaches every goal instantly, so there is never an easing window to send a frame into. The leader-arm test is the regression test for it.
🤖 Generated with Claude Code
Approved on the diff and the tests; I could not load the preview from my sandbox (network denied), so I did not see the STOP button on a 360px phone myself. What I read holds: the relay sets by from the signed identity and ignores the page body; clearing the stop and PUT /settings are admin-only; the driver and any admin can E-stop; a stream closed on purpose only holds while a dropped one parks; the metrics list is now built from text nodes; the safety module is small, has no new dependency, and the README says how to use it and warns that roles hold only behind the relay. There is no tty.ts in this repo, so there is no second door to mirror.
Two things I would do next:
- Put a shared secret between the relay and the arm server so /estop/clear and PUT /settings are not open to anything that reaches the arm server port. Today the safety is a network rule written in the README, not code.
- Check the STOP button as a person would: at least 44px by 44px on a 360px phone, a visible focus ring and an accessible name, with Esc not firing while someone types in the chat box. Announce the stopped banner with role=alert so a screen reader hears it.
The server now enforces the safety envelope on every command, whoever sends it. That covers joint limits, top speed, acceleration, command rate, hold after silence and gripper force. Only an admin can change those limits. An emergency stop halts whatever is driving the arm and holds it with torque on until an admin clears it; the driver or any admin can press it. If a driver's browser drops in the middle of a stream, the arm moves slowly to a park pose. A stream the page closes on purpose leaves the arm holding where it is. The relay takes the name of whoever pressed the E-stop from the signed identity, not from the page. Event details and E-stop names go onto the page as text nodes, never as HTML.
This update merges main: guest usernames and bans (#38), more than one camera (#28) and the phone layout (#39). Things to look at:
relay.ts:
- The new /join route sits in front of the admin-only and driver-or-admin route checks.
- lobby.refusal(who, req) now takes the request, so bans by address apply.
- Camera routing comes from main's CameraHub, which replaces the two fixed camera feeds; the E-stop's lost-driver heartbeat is kept.
- Gzip for static files sits in front of the speed cap. Who stopped or cleared the arm is still filled in by the relay.
viewer.html(main's phone layout):
- The red E-stop moved into the status strip and uses main's .estop style. It answers to Esc and shows "Stopped" while held. The plain Stop (space) is now an ordinary button beside it.
- The safety limits and joint limits are a card in the Admin tab, under the trims.
- Main locked the zone and trim controls to the driver. I locked them, and the limits, to admins instead, because the server only accepts settings changes from an admin. The note telling the owner to take control first is gone.
- The Controls tab follows whose turn it is, not whether the E-stop is on.
- Fix in my own branch:
eStop()called astopLivethat had never existed, so the E-stop button threw an error after stopping the arm. It now stops a leader-arm drive that is running. - Tests:
lobby.test.ts,server.test.tsandREADME.mdkeep both sides' additions.
bun x tsc --noEmit is clean and bun test passes (254 tests). To try it on the preview, start a turn and press Stop in the strip, or Esc. The arm then refuses every move, and only the owner sees "Clear the stop" in the banner. The limits are under Admin → Safety limits.
🤖 Generated with Claude Code
The server now enforces the safety envelope on every command, whoever sends it. That covers joint limits, top speed, acceleration, command rate, hold after silence and gripper force. Only an admin can change those limits. An emergency stop halts whatever is driving the arm and holds it with torque on until an admin clears it; the driver or any admin can press it. If a driver's browser drops in the middle of a stream, the arm moves slowly to a park pose. A stream the page closes on purpose leaves the arm holding where it is. The relay takes the name of whoever pressed the E-stop from the signed identity, not from the page.
This update merges main again, bringing in the word filter and pause/ban moderation (#42) and the hosted app's link to the real arm and camera (#43). The only conflict was in Software/README.md, where both sides added a bullet at the same spot: the E-stop bullet and the word-filter bullet are both kept. The earlier merge had already brought in guest names, bans, more than one camera and the phone layout:
- E-stop button: it sits in the status strip and answers to Esc. The plain Stop (space) is an ordinary button beside it.
- Admin tab: a "Safety limits" card holds the speed and joint limits. The zone, trims and limits can be changed only by admins, which matches what the server enforces.
- Fix:
eStop()no longer calls astopLivethat never existed; it now stops a leader-arm drive that is running.
bun x tsc --noEmit is clean and bun test passes (262 tests). To try it on the preview, start a turn and press Stop in the strip, or Esc. The arm then refuses every move, and only the owner sees "Clear the stop" in the banner. The limits are under Admin → Safety limits.
🤖 Generated with Claude Code
Approved from the source and tests; my sandbox could not reach the preview host, so I did not exercise it live. The relay takes the E-stop actor from the signed identity and ignores the page body. Clearing the stop and PUT /settings are admin-only in the relay. By is sanitised and rendered as text. The envelope is covered by safety.test.ts, server.test.ts and lobby.test.ts, and the README documents it, including the warning that roles hold only behind the relay. Next two things: (1) give the arm server a shared secret with the relay so /estop/clear and PUT /settings are not open to anyone who reaches its port; (2) add a keyboard-and-screen-reader pass on the STOP button and stop banner (role=alert, focus on Clear) and check the 360px layout on a real phone.
The arm server now enforces every limit in this issue on every command, whoever sends it. That covers the simulation and the real arm's
so101 serve. All 143 tests pass and the type check is clean.Limits (new
src/safety.ts, no new dependencies)jointLimitsDeg. They apply to the stream,/move,/pose/go,/grip, playback and park./movespeed is capped, and a playback is slowed to fit./followframes are capped at 4 KB.- A stream that is closed normally still just holds. - A stream that drops or misses a ping (once a second) moves slowly to the saved pose named
park. With no such pose it goes to the middle of each joint's range. - The relay tells the arm server which case happened: it closes the arm side with code 4001 when the browser drops, and also pings browsers./grip. Supervised moves and playback now put the gripper back to that cap instead of full torque.-
POST /estopstops whatever is driving, sets every goal to where the joint is, and keeps torque on. - After that, moves,/torqueand new streams are refused with 423 untilPOST /estop/clear. - It is saved toestop.json, so a restart keeps it.PUT /settings; drivers could change the settings before this. The relay fills in who pressed it from the signed identity and ignores the page's body.Viewer: a big red STOP button over the picture (Esc also works), a banner while stopped with a Clear button for admins, and a "Safety limits" section in settings that only admins can edit.
Tests changed — the old expectations were right, the behaviour changed on purpose:
Not done:
so101 serverunning on the arm machine from before this change has no/estop; that machine needs updating.so101 serveon the LAN is still unauthenticated, so anyone who can reach it directly can clear the stop. The role checks only apply behind the forge.To try it:
PORT=8102 FORGE_APP_DATA=./data bun run Software/so101/bench/fake-serve.ts, then:park, start a stream, then kill the tab mid-drag; the arm parks.The new tests are
src/safety.test.ts, the "the safety envelope" block insrc/server.test.ts, and the last two tests insrc/lobby.test.ts.🤖 Generated with Claude Code
Closes #11