Repository navigation
fix: refuse the handover when the approach never moved - #78
Conversation
A force-carrying approach that stops within `no_bite_mm` (0.5 mm) of where it started was being reported as `stalled=True` and handed over to the pure-torque hold. That is not contact: at 2 N the approach budget is 0.18 N*m, below the measured 1.8-2.0 N breakaway, so the jaws never leave static friction. The hold then applies 0.20 N*m with no position or velocity term, and across a free stroke that torque accelerates the jaws into the runaway watch -- the "fast close" seen on the bench. The stall verdict now compares the stopped pose with the pose the approach began at. Inside `no_bite_mm` the move is flagged `no_bite` instead of `stalled`: `grasp()` releases in place, sends no hold frame and returns `ok=False, no_bite=True, cycles=0`. Real contact delta above the threshold is unchanged, as is the empty-jaw `reached` path. The fake motor gained `breakaway_tau_nm` so the regression is reproducible in simulation.
X-F-R
left a comment
There was a problem hiding this comment.
Cross-checked against the mirrored C++ PR (#59); the law, the threshold and the hand-over ordering match. I ran the suite locally (476 passed) — no blocking issues. A few points, roughly by importance:
1. The regression test cannot reproduce the runaway it is named after (tests/test_actions.py:1895)
BREAKAWAY_NM = 0.22 is above the 2 N hold torque (0.20 Nm), so pre-fix the hold could not move the jaw either: the old code returns ok=True, stalled=True, not a powered stroke. The test does fail pre-fix, but it only proves the refusal — not that the refusal prevents the 19 mm walk.
Putting the breakaway inside the measured 1.8–2.0 N band (e.g. 0.19 Nm) and giving the fake some creep_rad_s_per_nm (a pure-torque hold only moves in the fake with creep — see TestHoldTravelGuard.CREEP) reproduces the real path. I checked against this PR:
breakaway_tau_nm=0.19, creep_rad_s_per_nm=5.0, no_bite_mm=0(simulating pre-fix) →ok=True stalled=True cycles=10, jaws end on the closed stop after the whole 120 mm stroke;- the same parameters with the fix →
ok=False no_bite=True cycles=0, jaws stay at the start.
2. examples/grasp_test.py — the bench tool behind this report — does not know the new flag
_report(:277) does not printno_bite._hold_problem(:319) reports "the hold phase ended abnormally (err=0)";no_biteis a clean refusal, not a fault._judge_empty(:340) says "the closing leg ran out of frames while still travelling" — the opposite of a zero-displacement stop.
Whoever runs this next will be pointed the wrong way. Worth handling no_bite explicitly.
3. The refusal applies at every setpoint — intended?
test_a_workpiece_at_the_start_is_refused_as_well encodes a 20 N grasp failing when the part sits at the start pose. Two real sequences hit that: a part already against the open jaw, and a re-grasp in place after release(abort=True) (which sends no opening move).
The dangerous 0.9x/1.0x gap only exists when the approach budget is within ~10% of the breakaway. At 20 N the budget is 1.8 Nm, ~9x the measured breakaway, so a zero-displacement stop there is almost certainly contact. If the conservative behaviour is deliberate, please call out the re-grasp-after-abort consequence in the docs; otherwise consider gating the refusal on the budget being near the breakaway (e.g. a configurable upper bound).
4. Residual gap: a start within reach_tol of the target bypasses the check entirely
judge_stall (src/litegrip/actions.py:1583) is false when the approach starts within reach_tol of the target, so no_bite can never be set there. With a start 0.05 mm from the closed stop and a budget below the breakaway I measured ok=True, reached=True, no_bite=False, cycles=4 — the hand-over this PR is meant to prevent still happens. It is bounded by hold_runaway_rad, but the README's "the hold is never entered" / "stalled and reached are both False on this path" is too absolute for this window.
5. Smaller items
README.md:379/README.zh-CN.md:327: theno_bitebullet sits under "A fourth combination is a failure"; it is a fifth combination. The C++ PR introduces it as "A fifth one is a refusal" — worth mirroring.LiteGrip.grasp's docstring (src/litegrip/gripper.py:1390) andactions.grasp's docstring still only documentreleased/travel_guard;no_biteappears only in the README.- The new branch (
src/litegrip/actions.py:884) duplicates the generic "neither reached nor stalled" refusal just below it. Sharing the result construction would keep the two paths from drifting.
Review feedback (X-F-R): the refusal applied at every setpoint, so a part already against the open jaw — or a re-grasp in place after release(abort=True), which sends no opening move — was refused even at 20 N, where a zero-displacement stop is contact, not a budget that cannot break away. MotionConfig.breakaway_nm (0.2 Nm, the bracket measured on 2026-10-29) now gates the verdict: only a budget below it turns a zero-displacement stop into no_bite. Above it the stop stays `stalled` and is held, which is the setpoint the caller asked for with nothing ahead of the jaws to run into. The regression test now reproduces the runaway it is named after: a fake with breakaway 0.19 Nm and creep, run with no_bite_mm=0 (the pre-fix behaviour), walks the jaws >10 mm under the hold; the same bench with the refusal on does not move them at all. examples/grasp_test.py reports no_bite as the refusal it is instead of "the closing leg ran out of frames" or "err=0". Both refusal paths share one result constructor, the grasp docstrings name the new field, and the READMEs call it the fifth combination, state the gate, and note the reach_tol edge.
|
Thanks — all five points are addressed in 1. The regression test now reproduces the walkAgreed,
So the pair now demonstrates the refusal preventing the walk, not just the refusal. (Note: in a 0.2 s hold the old path walks ~15 mm here, not the bench's 19 mm — the assertion is 2.
|
| setpoint | budget × 0.9 | verdict on a zero-displacement stop |
|---|---|---|
| 2.0 N | 0.18 Nm | no_bite — under the breakaway, so "not moving" says nothing |
| 2.2 N | 0.198 Nm | no_bite — the 0.9× gap is exactly what we guard |
| 2.5 N | 0.225 Nm | stalled — above the breakaway, so contact is the reading |
| 20 N | 1.8 Nm | stalled → normal hand-over |
breakaway_nm = 0.2 is the measured value (0.18 Nm could not move the jaw, 0.20 Nm walked 19 mm). Tests: test_the_setpoint_above_the_breakaway_still_grasps (3 N), test_a_workpiece_at_the_start_is_contact_above_the_breakaway (20 N block at start + 0.001·travel → stalled, ok, cycles > 0) and test_a_workpiece_at_the_start_is_refused_below_the_breakaway (2 N → no_bite, no hold frames). Both READMEs document the gate and the 2.5 N remedy.
4. The reach_tol window is documented rather than extended
Your measurement is right and I chose not to widen the check: with reach_tol = 0.02 rad (~0.9 mm) the residual window is bounded by hold_runaway_rad = 0.05 rad, and extending no_bite past judge_stall would mean re-deriving the stall judgement for a case the guard already contains. Instead the comment above judge_stall and both READMEs now say: a start within reach_tol of the closed stop never reaches the stall judgement, reports reached, and the hold has no free stroke to walk — the "hold is never entered" / "stalled and reached are both False" statements now apply to the wider case, with this window called out as an edge.
5. Smaller items
- Fifth-combination wording fixed in both READMEs ("A fourth combination is a failure… Then a fifth one is a refusal:"), and the grasp row in the field tables mentions the gate.
LiteGrip.graspandactions.graspdocstrings now documentno_bite, including the budget gate and the "refuses the hand-over, drop torque, report failure" contract.- The two refusals share
_refused_handover(move, force, *, no_bite=False)instead of duplicating theGraspResultconstruction.
Tests: python3 -m unittest discover -s tests -t tests → Ran 478 tests in 9.736s / OK (skipped=12); python3 -m pytest -q → 466 passed, 12 skipped, 57 subtests passed; markdownlint on both READMEs → 0 issues. CI test is green.
|
🎉 This PR is included in version 1.2.1 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
Summary
A force-carrying approach that stops without ever having moved from where it started was reported as
stalled=Trueand handed over to the pure-torque hold. That is not contact: at a 2 N setpoint the approach budget is 0.18 N·m, below the 1.8–2.0 N breakaway measured on the bench, so the jaws never leave static friction. The hold then applies 0.20 N·m withkp = kd = 0; over a free stroke that torque is the only thing acting on the jaw and it accelerates until the runaway watch fires — the "fast close" seen after a release-and-regrasp.The stall verdict now compares the stopped pose with the pose the approach began at.
Changes
MotionConfig.no_bite_mm(default0.5): how close to the approach's start pose counts as "never moved". 0.5 mm sits under the bench's ~0.0103 rad (≈0.76 mm) stick-slip dead band, so a jaw that broke free and then stalled is still read as contact.MoveResult.no_bite/GraspResult.no_bite: set when the force-carrying approach stopped inside that threshold.stalledandreachedare bothFalseon this path.grasp()now checksno_bitebefore the generic "neither reached nor stalled" branch: it releases in place, sends no hold frame, and returnsok=False, no_bite=True, cycles=0.tests/fake_can.py:FakeMotor(breakaway_tau_nm=...)— below that torque the jaw does not move unless it is already moving, so the refusal is reproducible in simulation.tests/test_actions.py:TestTheApproachRefusesToHandOverWithoutBite— a setpoint below the breakaway is refused (no hold frame, last framekp == 0.0), a setpoint above it still grasps, and a part sitting at the start pose is refused too (the documented trade-off).README.md/README.zh-CN.md: the new field on both result types, a results-section bullet forok=False, no_bite=True, the refusal in thegrasp()row, andno_bite_mmin the config table.Testing
Issues
No tracking issue — this reproduces the bench report of a fast close after release-and-regrasp on 2026-10-30.