Repository navigation
fix: refuse the handover when the approach never moved - #59
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 Nm, below the measured 1.8-2.0 N breakaway, so the jaws never leave static friction. The hold then applies 0.20 Nm 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`: `hand_over()` drops the torque in place, sends no hold frame and returns `ok = false, no_bite = true, cycles = 0`. Real contact beyond 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 Python PR (#78); the law, the threshold and the hand-over ordering match. I built and ran the suite locally (14/14 ctest, markdownlint clean) — no blocking issues. A few points, roughly by importance:
1. The regression test cannot reproduce the runaway it is named after (test/test_motion.cpp:1071)
kBreakawayNm = 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 the travel-guard tests) reproduces the real path. I checked against the Python twin with the same model:
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 stroke;- the same parameters with the fix →
ok=false no_bite=true cycles=0, jaws stay at the start.
2. 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).
3. Residual gap: a start within reach_tol of the target bypasses the check entirely
judge_stall (src/motion.cpp:685) 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 the Python twin reports 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.
4. README flag list still says three
README.md:462 and README.zh-CN.md:408 still read "Three flags explain a failure" / "三个标志解释失败", but no_bite is now the fourth bullet under that heading. Please bump the count (or drop the number).
5. Smaller items
- Public API docs:
include/litegrip/gripper.hpp:167(grasp()) still only mentionstravel_guard;no_biteis documented only inmotion.hppand the README. MoveResult::no_biteis inserted beforestate(include/litegrip/motion.hpp:328), while the Python twin appends it at the end. Either way this is an ABI break, but appending also preserves positional aggregate initialisation for existing downstream code — consider moving it to the end of the struct.- The new branch (
src/motion.cpp:1055) 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. Both refusal paths share one result constructor, MoveResult::no_bite and GraspResult::no_bite sit last in their structs so positional aggregate initialisation still compiles, gripper.hpp names 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 demonstrates the refusal preventing the walk, not only the refusal. (In a 0.2 s hold the old path walks ~15 mm here rather than the bench's 19 mm; the assertion is 2. The refusal is gated on the budget being near the breakawayTook the "gate it" option — at 20 N a zero-displacement stop is almost certainly contact. New
3. The
|
|
🎉 This PR is included in version 1.1.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 on 2026-10-29, where the jaws walked 19 mm under the setpoint.This is the C++ port of nexform-tech/litegrip-python#78; the law, the threshold and the tests mirror it.
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.move_to_limit()splits the stall verdict: withinno_bite_mmof the leg's start it setsno_biteand warns on stderr with the budget and the start pose; otherwise it setsstalledas before.hand_over()checksno_bitebefore the generic "neither reached nor stalled" branch: it drops the torque in place, sends no hold frame, and returnsok = false, no_bite = true, cycles = 0.test/test_motion.cpp:FakeMotor/FakeIo/GraspBenchgainedbreakaway_tau_nm— below that torque a jaw at rest does not move, so the refusal is reproducible in simulation. New tests: a setpoint below the breakaway is refused (no hold frame, last framekp == 0), a setpoint above it still grasps, and a workpiece 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, the flag list, 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.