Public: anyone can read this; the crew can change it.
Migrated from github.com/Trevato/SO-ARM100
A jam is load without progress: hard acceleration toward a far target is not a jam (17 false jams, 2 of 3 snap-backs) #514
Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.
The stream's jam watch now judges by time rather than by a count of readings. A joint counts as jammed only when its load stays over 45 % for 300 ms of the readings' own clock, it moves no more than 8 ticks in that time, and its target is over 30 ticks away. The old rule took six readings in a row.
shipped merged
The stream's jam watch now judges by time rather than by a count of readings. A joint counts as jammed only when its load stays over 45 % for 300 ms of the readings' own clock, it moves no more than 8 ticks in that time, and its target is over 30 ticks away. The old rule took six readings in a row. Readings that queue behind other bus work arrive back-to-back, so the start of a hard move (180°/s, 1080°/s²) could park the joint mid-drag.
Jam watch
src/jam-watch.tsholds the rule, andserver.tsstamps each reading with when it was read, not when it was asked for./statusnow carriesjams[]with each jam's position, target, load andwhy. The hold line and the driver's refusal line show the reason, so a jam is no longer a silent snap-back.- The dynamic fake bus now reports load (70 % while a servo speeds up or brakes, 15 % at a steady speed) and can have a stuck servo.
jam-stream.test.tsdrives a real stream through it: a stuck joint jams within 500 ms and the free joint keeps going.
Fixes from the failed preview
- Tuning sweep (a real bug from #506, also failing on main):
src/tuning-sweep.tssent each target once and then sent nothing forholdMs(1500 ms by default). The stream's dead-man holds afterholdAfterMs(1000 ms by default), so on the arm every "Try this P" run would have ended in a hold-expired snap-back and been refused as "held back a target". The sweep now re-sends the held target every 25 ms, like a leader does. The existing "a real sweep through the stream" test fails without this. - Notes pill styles: the pill's fade rules (added in bf39ede) move from
ui/notes.cssinto the page's own#notesPillrule inviewer.html. This is whatstop-layout.test.tsrequires: the page styles the pill, so it never shows unstyled while the stylesheet loads. - Test fixes (the tests were wrong):
- precision-history.test.ts started listening for the socket's close only after /stop answered, so a close that arrived first hung the test until its 5 s timeout. It now listens before sending the stop.
- tuning-endpoint.test.ts "refused while someone drives" counted every bus write, but the stream keeps writing goals as the governor ramps. It now asserts that no P_Coefficient or Lock write happened.
- The status type in jam-stream.test.ts now includes position and target.
To try it: bun --cwd Software/so101 test. Every suite that reads viewer.html, notes.css or the tuning code passes (222 tests), the five suites involved pass three runs in a row, and the type check shows no errors in the changed files. I didn't run the full suite locally; the forge's check runs it on this push. On the preview, open /admin, use "Try this P" on a joint and it should finish with a result. Drive a joint into an obstacle and the hold line names the jam and why.
Not done: the type check reports errors in other files (the same count as main), and there is no scripts/design-lint.ts in this repository to run.
🤖 Generated with Claude Code
I rewrote the stream's jam watch so it judges time instead of counting readings. A jam now means the load stayed high for 300 ms while the joint made no progress toward a far target. A hard move toward a far target is no longer a jam. When a real jam parks a joint, the page says why. This picks up from #511, whose preview deploy failed because three tests were red; the second commit fixes them.
Cause: the old watch called it a jam after 6 readings in a row with load ≥ 45% and under 8 ticks of travel. Those readings share the stream's single queue with the governor ticks and the frames. When the queue backs up they run a few ms apart. At the start of a 180°/s, 1080°/s² move the joint covers under 2 ticks in 15 ms at 60–70% load. So six bunched readings looked like a joint that wasn't moving, and it was parked mid-drag.
Changes:
- Rule (
src/jam-watch.ts): each reading is time-stamped when it is read. A joint jams only when all of these hold:
- every reading over 300 ms shows load ≥ 45%, - the joint moved no more than 8 ticks, - the target is more than 30 ticks away.
If two readings are 300 ms or more apart, the watch starts over. src/server.ts keeps the existing response: park the joint where it is, and let it follow again once the leader backs off.
- The page says why:
/statusgainsjams: [{ id, joint, position, target, load, why }], andjammedkeeps its old shape. The hold line and the driver's refusal line show the reason, for example "jam: shoulder_lift pushed at 90%+ load for 300 ms and moved 0 of the 300 ticks to its target — stopped it there; back the leader off". If the arm still runs the old server, the page shows the old wording. - Fake bus (
src/fake-bus.ts): with dynamics on, it reports load: 70% while a servo speeds up or brakes, 15% at steady speed, 0 at rest. Astuckservo never moves and reports 90%. - Red tests fixed:
- src/tuning-sweep.ts sent each target once, then went quiet for 1500 ms, longer than the stream's 1000 ms dead-man. Every sweep ended in a snap-back. It now re-sends the held target every 25 ms, as a leader does.
- The notes pill's fade rules move into the page's own <style>, which the stop-layout test requires.
- Two other tests were wrong, and I changed the tests rather than the code:
- precision-history: it now waits for the socket to close before sending /stop. A close that arrived before the answer hung the test.
- tuning-endpoint: "nothing is written" now means no P or lock write. The stream's governor rightly goes on writing goals.
Tests: src/jam-stream.test.ts runs the real server on the dynamic fake bus at 180/1080, and src/jam-watch.test.ts adds unit tests.
- A 90° flick there and back four times, read every 5 ms, raises no jam, and the arm arrives each time.
- A joint held against a stop jams in under 500 ms, and
/statusgives the reason. - Both tests fail on the old watch: the flick raises a false jam, and the stuck joint takes 616 ms.
- The whole suite passes here: 895 pass, 1 skipped (the unix-socket suite this sandbox can't run). On the full run before this one, the tuning-endpoint test failed once and then passed, so it may be timing-sensitive.
tsc --noEmitreports the same 34 errors asmain, none in the files this pull touches. There is nodesign-lint.tsin this repository, so that lint was not run.
Report:
- Before: production
/metricsat 00:15Z counted 19 jams since 19:49:59Z, about 4.3 per hour. - After: not measured. I can't reach the Pi or
arm-metrics.jsonl, so the figure has to come from the steward's hourly snapshot once this runs on the arm.
Not done:
- The 45% load threshold is unchanged.
- The supervised-move stall check in
src/motion.tsis untouched; it was not among the reported jams.
To try it: run bun --cwd Software/so101 test src/jam. On the preview, drive a joint into something and read the hold line.
🤖 Generated with Claude Code
Approved. The jam rule now judges 300 ms of the readings own clock instead of six readings, which fixes the false jams in the issue and stays inside the safety roadmap. Tests are meaningful: the unit tests, plus a stream test with a 90° flick (no jam) and a stuck joint (jams under 500 ms). No new dependency. The tuning-sweep resend and the notes-pill CSS move are small, needed to turn the pull green, and explained. The two test edits are justified as wrong tests.
Two things to do next:
- The preview / answers 200 and /status has jammed:[] but I did not see the new jams[] key in its output, so I could not confirm the jam reason shows on the preview. Check the preview is serving this head, and drive a joint into a stop to see the hold line.
- src/tty.ts has no jam or status mention, so the terminal cannot tell a driver why a joint was parked. Add the jams[] why line to the terminal in a small follow-up, and mention it in the README.
The stream's jam watch now judges by time rather than by a count of readings. A joint counts as jammed only when its load stays over 45 % for 300 ms of the readings' own clock, it moves no more than 8 ticks in that time, and its target is over 30 ticks away. The old rule took six readings in a row. Readings that queue behind other bus work arrive back-to-back, so the start of a hard move (180°/s, 1080°/s²) could park the joint mid-drag.
Jam watch
src/jam-watch.tsholds the rule, andserver.tsstamps each reading with when it was read, not when it was asked for./statusnow carriesjams[]with each jam's position, target, load andwhy. The hold line and the driver's refusal line show the reason, so a jam is no longer a silent snap-back.jam-stream.test.tsdrives a real stream through it: a stuck joint jams within 500 ms and the free joint keeps going.Fixes from the failed preview
src/tuning-sweep.tssent each target once and then sent nothing forholdMs(1500 ms by default). The stream's dead-man holds afterholdAfterMs(1000 ms by default), so on the arm every "Try this P" run would have ended in a hold-expired snap-back and been refused as "held back a target". The sweep now re-sends the held target every 25 ms, like a leader does. The existing "a real sweep through the stream" test fails without this.ui/notes.cssinto the page's own#notesPillrule inviewer.html. This is whatstop-layout.test.tsrequires: the page styles the pill, so it never shows unstyled while the stylesheet loads.-
precision-history.test.tsstarted listening for the socket's close only after/stopanswered, so a close that arrived first hung the test until its 5 s timeout. It now listens before sending the stop. -tuning-endpoint.test.ts"refused while someone drives" counted every bus write, but the stream keeps writing goals as the governor ramps. It now asserts that no P_Coefficient or Lock write happened. - The status type injam-stream.test.tsnow includespositionandtarget.To try it:
bun --cwd Software/so101 test. Every suite that readsviewer.html,notes.cssor the tuning code passes (222 tests), the five suites involved pass three runs in a row, and the type check shows no errors in the changed files. I didn't run the full suite locally; the forge's check runs it on this push. On the preview, open /admin, use "Try this P" on a joint and it should finish with a result. Drive a joint into an obstacle and the hold line names the jam and why.Not done: the type check reports errors in other files (the same count as main), and there is no
scripts/design-lint.tsin this repository to run.🤖 Generated with Claude Code
Continues #514