Optional 1-DoF jaw on the hardware gripper

[Nick Hehr (HipsterBrown)]

Stacked on #39. Review that one first — this targets gripper-inputs, so GitHub shows only the hardware commits and will retarget to main when #39 merges.

Why

#39 made the simulated gripper's jaw a real degree of freedom and measured what the motion planner does with it: nothing on an unobstructed plan, and 4.3%-19.9% of the jaw's range under obstruction, in both directions.

On a simulated gripper that's a curiosity. On hardware holding a part, it's the grip loosening mid-trajectory. This adds the same articulated_jaw attribute to devrel:so101:gripper (default false), plus the three things hardware forces that simulation didn't.

The three decisions, and why they went this way

Refusing planner jaw commands while holding — but only ones that move the jaw. The obvious version of this guard breaks pick-and-place. builtin.go:687-689 skips a component in a trajectory step only when len(inputs) == 0, never when the inputs are unchanged, so a 1-DoF gripper appears in every step of every plan carrying its current value. An unconditional refusal fails every arm move made while carrying a part. So a batch whose steps are all within 0.01 rad of current returns early without commanding the servo, and only a genuine jaw command is refused.

A 50 ms position cache. Every CurrentInputs is a DoCommand round trip plus a serial read on the bus the five arm servos share — and the 3D viewer polls it continuously to animate the jaw. Measured: 200 polls inside the TTL cost 0 bus reads. Invalidated at the top of servoDo (a deny-list, so a future servo command defaults to invalidating), with a generation counter because the lock is released across the read.

Last-known-good on a failed read. framesystem.CurrentInputs hard-errors the entire machine's frame system if a DoF-bearing component errors, so one dropped serial frame would abort every arm move. A failed read serves the last good value and warns; it only errors if no read has ever succeeded.

Also implements IsHoldingSomething, which was a stub that always answered "not holding" — the guard above reads from it.

Where to focus review

• GoToInputs's ordering — validate everything, detect a no-op, then check holding. The sequence is the safety property, not an implementation detail.
• Locking. The cache has its own jawMu because Open/Grab hold g.mu across moveToPercent and sync.Mutex isn't reentrant. jawMu is never held across a DoCommand, so a viewer poll can't block behind a 2000 ms servo_wait_stop. The only order is g.mu -> jawMu.
• The default path. articulated_jaw: false must behave exactly as before; a test pins that construction issues only the capabilities probe.

Testing

go test ./... green, -race clean, go vet clean. No hardware required — the gripper's only hardware path is arm.DoCommand, so the existing fake-arm harness covers all of it.

Every guard was mutation-tested: broken deliberately, confirmed to fail with the intended diagnostic, reverted. Two worth noting, because both passed for the wrong reason until fixed:

• The grasp threshold was only ever exercised with closedPosition = 0, so dropping the subtraction entirely left the suite green. There's now a calibrated-offset case.
• Review caught a TOCTOU: the no-op and holding decisions were computed before taking g.mu, so an Open holding that lock for up to 2000 ms meant both were decided against a stale jaw. Both now happen inside the critical section.

Verified separately and committed as tests: 10 arm moves x 40 trajectory steps while holding all succeed with zero bus writes, while the same fixture still refuses a genuine jaw command.

Known limitations, documented not fixed

• Geometries() still reads the bus uncached and falls back to "closed" on failure. Out of scope here; worth a follow-up since it's the weaker policy of the two.
• GoToInputs isn't constrained to the calibrated openPosition/closedPosition, so the planner can drive the jaw further open than Open() will. Matches the simulated gripper. Flagging for a decision rather than changing it unilaterally.
• A Stop arriving during the pre-move phase isn't latched. Fixing it would suppress legitimate cache stores; commented in place.

🤖 Generated with Claude Code