Skip to content

fix: refuse the handover when the approach never moved - #59

Merged
cao-xiao-hao merged 2 commits into
mainfrom
fix/refuse-handover-when-the-approach-never-moved
Oct 30, 2026
Merged

cao-xiao-hao merged 2 commits into
mainfrom
fix/refuse-handover-when-the-approach-never-moved

Conversation

@cao-xiao-hao

Copy link
Copy Markdown
Contributor

Summary

A force-carrying approach that stops without ever having moved from where it started was reported as stalled = true and 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 with kp = 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 (default 0.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. stalled and reached are both false on this path.
  • move_to_limit() splits the stall verdict: within no_bite_mm of the leg's start it sets no_bite and warns on stderr with the budget and the start pose; otherwise it sets stalled as before.
  • hand_over() checks no_bite before the generic "neither reached nor stalled" branch: it drops the torque in place, sends no hold frame, and returns ok = false, no_bite = true, cycles = 0.
  • test/test_motion.cpp: FakeMotor/FakeIo/GraspBench gained breakaway_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 frame kp == 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 for ok = false, no_bite = true, the refusal in the grasp() row, the flag list, and no_bite_mm in the config table.

Testing

$ cmake --build build -j 4
[100%] Built target test_motion

$ cd build && ctest --output-on-failure
      Start  1: test_version
 1/14 Test  #1: test_version .....................   Passed    0.00 sec
 2/14 Test  #2: test_headers .....................   Passed    0.00 sec
 3/14 Test  #3: test_protocol ....................   Passed    0.00 sec
 4/14 Test  #4: test_motor .......................   Passed    0.00 sec
 5/14 Test  #5: test_golden ......................   Passed    0.00 sec
 6/14 Test  #6: test_transport ...................   Passed    0.00 sec
 7/14 Test  #7: test_json ........................   Passed    0.00 sec
 8/14 Test  #8: test_calibration .................   Passed    0.00 sec
 9/14 Test  #9: test_bus .........................   Passed    0.00 sec
10/14 Test #10: test_safety ......................   Passed    0.00 sec
11/14 Test #11: test_gripper .....................   Passed    0.00 sec
12/14 Test #12: test_motion ......................   Passed    0.11 sec
13/14 Test #13: test_probe .......................   Passed    0.00 sec
14/14 Test #14: test_control_loop ................   Passed    3.18 sec

100% tests passed out of 14

Issues

No tracking issue — this reproduces the bench report of a fast close after release-and-regrasp on 2026-10-30.

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.
@cao-xiao-hao
cao-xiao-hao requested review from X-F-R and yd-sl October 30, 2026 06:43

@X-F-R X-F-R left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 mentions travel_guard; no_bite is documented only in motion.hpp and the README.
  • MoveResult::no_bite is inserted before state (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.
@cao-xiao-hao

Copy link
Copy Markdown
Contributor Author

Thanks — all five points are addressed in 814da0a. Details per point:

1. The regression test now reproduces the walk

Agreed, 0.22 was the wrong side of the measured band. The pair now uses kBreakawayNm = 0.19 and kNoBiteCreepRadSPerNm = 5.0 (FakeIo/FakeMotor take a breakaway_tau_nm that zeroes the velocity while |kp*(q-pos)+tau_ff| < breakaway, after the creep line):

  • test_the_old_handover_walks_the_jaws_across_the_free_stroke — GraspConfig with no_bite_mm = 0.0 (pre-fix behaviour) and creep: stalled == true, no_bite == false, cycles > 0, jaws travel > 10 mm of the stroke;
  • test_the_refusal_stops_that_stroke_before_it_starts — default config, same plant: ok == false, no_bite == true, neither stalled nor reached, cycles == 0, travel < no_bite_mm, no hold frame with tau_ff != 0, last frame kp == 0.0.

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 > 10 mm and the bench figure is in the comment.)

2. The refusal is gated on the budget being near the breakaway

Took the "gate it" option — at 20 N a zero-displacement stop is almost certainly contact. New MotionConfig::breakaway_nm = 0.2; the flag is set only when force_n * UnitConversion::kNToNm * press_safety < breakaway_nm and the approach moved less than no_bite_mm. At the edges:

setpoint budget × 0.9 verdict on a zero-displacement stop
2.0 N 0.18 Nm no_bite
2.2 N 0.198 Nm no_bite
2.5 N 0.225 Nm stalled → normal hand-over
20 N 1.8 Nm stalled → normal hand-over

0.2 Nm is the measured value (0.18 Nm could not move the jaw, 0.20 Nm walked 19 mm). Tests: test_an_approach_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), 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.

3. The reach_tol window is documented rather than extended

Your measurement matches the Python twin 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. The comment above judge_stall and both READMEs now state that 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 on this path" statements now carry that window as a named edge.

4. Flag count fixed

README.md now reads "Four flags explain a failure: …" and README.zh-CN.md "四个标志解释失败:", with no_bite as the fourth bullet.

5. Smaller items

  • include/litegrip/gripper.hpp grasp() doc now documents no_bite, the budget gate and the "refuses the hand-over, drops torque, reports failure" contract.
  • MoveResult::no_bite and GraspResult::no_bite are moved to the end of their structs, with a comment saying why: the ABI break is unavoidable, but appending keeps positional aggregate initialisation compiling for existing downstream code.
  • The two refusals now share one lambda (refused(bool no_bite)) that builds the GraspResult, so the new branch and the generic "neither reached nor stalled" branch cannot drift.

One note: markdownlint still reports a single MD013 on README.zh-CN.md (long line) — it is pre-existing at HEAD too and CI lints only README.md, so I left it.

Tests: ctest → 100% tests passed out of 14 (test_motion 0.11 s); README.md markdownlint → clean. CI test is green.

@cao-xiao-hao
cao-xiao-hao merged commit 5439d59 into main Oct 30, 2026
1 check passed
@cao-xiao-hao
cao-xiao-hao deleted the fix/refuse-handover-when-the-approach-never-moved branch October 30, 2026 08:15
@github-actions

Copy link
Copy Markdown

🎉 This PR is included in version 1.1.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

released Shipped in a release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants