Skip to content

feat: add an interactive API smoke test and harden grasp handover - #85

Closed
thetooler wants to merge 1 commit into
nexform-tech:mainfrom
thetooler:feat/api-smoke-test
Closed

thetooler wants to merge 1 commit into
nexform-tech:mainfrom
thetooler:feat/api-smoke-test

Conversation

@thetooler

Copy link
Copy Markdown
Contributor

Summary

This branch adds an interactive bench smoke test and fixes the two stale-state paths that the bench work exposed on 2026-11-18.

  • examples/api_test.py — read-only-by-default menu over the high-level calls (get_state, enable, open, close, goto, grasp, release, stop, disable). Motion requires --yes; the UI is Chinese and every SDK name stays verbatim.
  • MotorController.poll() drains all queued status frames and lets the newest one define the state, instead of reading one (old) frame per call.
  • GripperActions._fresh_state() sends a 0xCC request before a motion and refuses to plan from a stale cache. It is used by the move ramp, release, and both hold reads.
  • Force-approach handover now needs a true stop: in addition to the existing 20 % window threshold, MotionConfig.stall_speed_mm_s (2 mm/s) requires the window's average speed to be below 2 mm/s.

Why

On the bench, a grasp(5 N, hold_s=2) left the last hold torque on the bus. The status cache still held the position from the start of the hold (78 mm) while the jaws were at 26 mm; a following open() scheduled its ramp from the cache, commanded ~0.7 rad of error on the first frame, and the jaws left at 23 rad/s out of a 20 mm/s move.

Separately, a force-budgeted approach that crawls (about 8 mm/s against a 50 mm/s schedule) was classified as stalled by the 20 % window criterion and handed to the torque-only hold while still in free travel; the hold then accelerated the jaws across the stroke.

Behaviour

  • Status reads are current: the drain runs non-blocking after the first frame; timeout_s only applies to the wait for that first frame.
  • A motion never starts from a stale cache. If the bus does not answer the 0xCC request and the cache is stale, the call raises CommError instead of guessing.
  • open / close / goto / release and the ordinary 20 % stall criterion are otherwise unchanged.
  • The fakes gained speed_cap_rad_s and freeze_position_while_idle so both regressions are hardware-free.

Tests

  • python3 -m unittest discover -s tests -t tests — 505 tests pass.
  • New regressions: tests/test_can_poll_drain.py (the newest queued frame wins), TestForceApproachNeedsATrueStop (a slow creep is not handed over mid-travel), TestMotionRefreshesAnIdleBus (a hand-moved jaw while the bus was idle).
  • A characterization run with the new threshold disabled hands the hold over 58 mm before the object; with the threshold it waits for the stop.
  • Bench: read-only smoke passes; the 2.5 N false-stop below is reproduced with the bench script; 3 N ends in the safe refusal path. A 5 N bench run under this change is still pending.

Known limitation

A free creep below 2 mm/s can still be mistaken for a stop. It is reproducible at 2.5 N: the approach creeps at about 1.9 mm/s, the hold takes over 9.5 mm before the closed stop, and the torque-only hold then pulls the jaws forward. A stricter package (0.5 mm/s threshold, two confirm windows, and a relaxed frame ceiling for slow approaches) was evaluated but is not part of this change. The 2 mm/s value is a policy threshold, not a measured hardware constant; breakaway_nm (0.2 Nm) is the measured one.

🤖 Generated with Claude Code

Add examples/api_test.py, a read-only-by-default bench menu for the
high-level calls (read, enable, open, close, goto, grasp, release, stop,
disable).  Motion requires --yes; the UI is Chinese and keeps every SDK
name verbatim.

Fix the stale-state paths found on the bench on 2026-11-18:

* MotorController.poll() now drains every queued status frame and lets the
  newest one define the state.  A burst of control frames (a hold slice, a
  ramp step) left older answers queued; reading one frame returned an old
  position, and the age was stamped when it was read, so it looked fresh.
  A ramp could start from the pose the jaws held seconds earlier.
* GripperActions._fresh_state() requests a status frame (0xCC) before every
  motion and refuses to plan from a stale cache.  It is used by the move
  ramp, release, and both hold reads.

Make the force-approach handover wait for a true stop.  Besides the existing
20 % window threshold, MotionConfig.stall_speed_mm_s (2 mm/s) requires the
window's average speed to be below 2 mm/s: a force-budgeted approach that
crawls (~8 mm/s on this bench) is not contact, and handing it to the
torque-only hold accelerates the jaws across the free stroke.

The fakes gain a speed cap and an idle-position freeze.  Regressions cover
the drained queue, a slow creep that must not be handed over mid-travel, and
an idle bus that must be refreshed before a move.  Both READMEs document the
new threshold.

Known limitation: a free creep below 2 mm/s can still be mistaken for a stop
(reproduced at 2.5 N, ~1.9 mm/s: the hold took over 9.5 mm before the closed
stop).  A 0.5 mm/s threshold plus two confirm windows and a relaxed frame
ceiling was considered but is not part of this change.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant