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

Migrated from github.com/Trevato/SO-ARM100

PUT /servo-params writes one joint's P/D/I and dead zones within safe ranges, only while nobody drives, and can put the factory values back #461

Merged opened this

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

Merged

PUT /servo-params and POST /servo-params/factory are added on the arm server. The new tests pass, along with the existing server and relay tests (89 in total). I did not run the full bun --cwd Software/so101 test, so the forge's check on the push is the first full run.

Notes

shipped merged

opened this

PUT /servo-params and POST /servo-params/factory are added on the arm server. The new tests pass, along with the existing server and relay tests (89 in total). I did not run the full bun --cwd Software/so101 test, so the forge's check on the push is the first full run. tsc reports no errors in the files I touched.

  • Write:

- The body is {id, P?, D?, I?, cwDeadZone?, ccwDeadZone?, minStartupForce?}, and it must name at least one value. - Values must be whole numbers inside the ranges in TUNABLE in src/servo-params.ts: P 1–64, D 0–64, I 0–32, each dead zone 0–8, minStartupForce 0–100. - A bad id, a value out of range, or any other key (including Torque_Limit) gets a 400 and nothing is written. - Please check these ranges. I chose them as conservative limits for a tuning start; the issue gave none. They are not from the servo datasheet. - Writes use the Lock dance in bus.write, then the servo is read back and returned.

  • Torque restore: the Lock dance switches torque off. If the joint had torque, the code puts it back at the position the joint rests in. I added that, and the issue didn't ask for it.
  • Refusals:

- Both routes take the same turn claim a move uses. They answer 409 while a stream, move, playback or recording drives, and 423 on an E-stop or hold. - Anything that holds a turn drives through the arm server, so I treated it the same as any other driver and did not check turns separately. - A refusal is checked before anything is written.

  • Factory values:

- They are kept in servo-factory.json next to the settings. The first complete read of each servo is recorded, and later reads never replace it. - GET /servo-params records them, and so does the first write, so a baseline exists before any change. - POST /servo-params/factory {"id"} writes those values back. It answers 409 if none were recorded for that id.

  • Log: each write adds a "servo params" (or "servo params factory") entry to the machine log.
  • Owner-only: in src/relay.ts both routes are owner-only. Everyone else, signed in or not, gets a 404.
  • Tests:

- src/servo-params-write.test.ts covers a write with its read-back and log entry, the factory restore, the out-of-range and unknown-key refusals, and the 409 and 423 refusals. - src/admin-relay.test.ts covers the relay's 404 for non-owners.

Closes #450

2 earlier comments · 2 events
commented

PUT /servo-params and POST /servo-params/factory are added on the arm server. The new tests pass, along with the existing server and relay tests (89 in total). I did not run the full bun --cwd Software/so101 test, so the forge's check on the push is the first full run. tsc reports no errors in the files I touched.

  • Write:

- The body is {id, P?, D?, I?, cwDeadZone?, ccwDeadZone?, minStartupForce?}, and it must name at least one value. - Values must be whole numbers inside the ranges in TUNABLE in src/servo-params.ts: P 1–64, D 0–64, I 0–32, each dead zone 0–8, minStartupForce 0–100. - A bad id, a value out of range, or any other key (including Torque_Limit) gets a 400 and nothing is written. - Please check these ranges. I chose them as conservative limits for a tuning start; the issue gave none. They are not from the servo datasheet. - Writes use the Lock dance in bus.write, then the servo is read back and returned.

  • Torque restore: the Lock dance switches torque off. If the joint had torque, the code puts it back at the position the joint rests in. I added that, and the issue didn't ask for it.
  • Refusals:

- Both routes take the same turn claim a move uses. They answer 409 while a stream, move, playback or recording drives, and 423 on an E-stop or hold. - Anything that holds a turn drives through the arm server, so I treated it the same as any other driver and did not check turns separately. - A refusal is checked before anything is written.

  • Factory values:

- They are kept in servo-factory.json next to the settings. The first complete read of each servo is recorded, and later reads never replace it. - GET /servo-params records them, and so does the first write, so a baseline exists before any change. - POST /servo-params/factory {"id"} writes those values back. It answers 409 if none were recorded for that id.

  • Log: each write adds a "servo params" (or "servo params factory") entry to the machine log.
  • Owner-only: in src/relay.ts both routes are owner-only. Everyone else, signed in or not, gets a 404.
  • Tests:

- src/servo-params-write.test.ts covers a write with its read-back and log entry, the factory restore, the out-of-range and unknown-key refusals, and the 409 and 423 refusals. - src/admin-relay.test.ts covers the relay's 404 for non-owners.

Changes requested — before the latest push

Fix first: PUT/POST /servo-params/factory read the bus (readServoParams for recordFactory) BEFORE claim("move"). While a stream, playback or recording drives, this request still talks to the bus mid-drive, and an E-stop/hold 423 happens after a bus read. GET /servo-params refuses with 409 first for exactly this reason. Move the claim above the baseline read (claim, then try/finally release around read + validate + write), and add a test that a refused PUT performs no bus reads (fake.reads or equivalent), not only no writes. Validate the body before touching the bus too.

Second: the README documents none of this (no mention of servo-params, the ranges, the factory restore, or that it is owner-only). Add a short section. The ranges in TUNABLE are admitted to be guesses, not from the datasheet; say so in the README or cite a source. Also no tty door was considered: say in the README whether the terminal offers it, or why not.

Minor: the unbraced block under case GET /servo-params is oddly indented; wrap it like the PUT case. The torque-restore (re-enable at current position) is unrequested scope; keep only if tested — no test covers it.

commented

I've made all the changes from the review and pushed them to the same branch. The servo-params, server, readme and admin-relay tests pass, and tsc reports nothing in the files I touched. I haven't run the full suite.

  • Order of checks: PUT /servo-params and POST /servo-params/factory now check the body, then claim the arm, then touch the bus. The baseline read, the write and the read-back all run inside the claim, which is released in a finally. A refused request (400, 409 or 423) reads nothing from the bus.
  • No-read test: FakeBus now counts read packets in reads. The tests assert that reads doesn't change on a bad body, while a stream drives, and on an E-stop. The E-stop case covers both routes.
  • Torque restore: I kept it and added a test. A joint that held torque gets torque back with its goal set to where it rests.
  • Layout: the GET /servo-params case is now braced like the PUT case.
  • README: a new "Tuning the servos" section in Software/README.md covers the routes, the ranges, the factory file, the refusals and that it's owner-only. It says plainly that the ranges are conservative guesses, not from the Feetech datasheet.
  • Terminal: the README says the terminal doesn't offer it. The terminal speaks the room's chat and turns, not the arm server's registers. I also think a register write should be a deliberate HTTP call by the owner, not something typed in a shared room. If you'd rather have a terminal command, say so; it would be a separate small pull.
Approved — before the latest push

Approved. Preview: an anonymous PUT /servo-params and POST /servo-params/factory both answer 404, as intended. The body is validated and the arm claimed before the bus is read, Torque_Limit is unreachable, the factory baseline is recorded before the first write, and tests cover the write, the factory restore, the 400s, the 409/423 refusals and the relay 404s. Next: (1) if writeServoParams throws after the Lock dance has switched torque off (a failed write or read-back), the joint stays limp. Restore torque in a finally, with a test. (2) The ranges are guesses by the builder's own admission, so have the owner confirm them against the datasheet before tuning. Also, the terminal does not offer this, which the README says plainly. It is an owner-only HTTP call and the page does not offer it either, so I accept that.

commented

I merged main into the branch and pushed it. Software/README.md was the only file with a conflict. The related tests pass (104 pass, 0 fail), but I did not run the full suite.

main added a relay-side "Servo factory baseline" section, and mine is "Tuning the servos". I kept both sections. I added one sentence to the baseline section, saying that the arm server keeps its own servo-factory.json and POST /servo-params/factory writes that one back.

  • Two baseline files: the relay's file is under FORGE_APP_DATA and the arm server's is next to its settings, so they don't clash. Both stay.
  • Restore source: the restore uses the arm server's file, not the relay's. If you want the restore to use the relay's baseline instead, that is a separate change.
  • Type check: tsc reports src/servo-baseline.ts(10,15) (TS1294, erasableSyntaxOnly). That file came in from main and I didn't touch it.
Approved

Approved. Both new routes are owner-only at the relay (anonymous PUT on the preview gets 404, / answers 200). The body is validated before the arm is claimed, and the claim comes before any bus read, so a refused request reads nothing. The tests assert that with the new FakeBus read counter. Torque is restored where the joint rests, and Torque_Limit is unreachable. The README is honest that the ranges are guesses. Not exercised: the owner path in the preview, since I have no owner identity. The terminal gap is a deliberate, documented choice for an owner-only arm-server register write, and adding it would be new scope under this direction, so I did not block on it.

Two things to do next:

  1. Replace the guessed TUNABLE ranges with datasheet or bench-measured limits.
  2. Make the restore use one baseline. Today the relay and the arm server each keep a servo-factory.json, and the arm-server file is recorded from whatever the first read sees, which may already be a tuned state.
Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs