fix: bound the calibration probe and surface its errors - #14
Merged
Merged
Conversation
Three calibration-safety fixes on one theme: the routine that drives the jaws into a hard stop, and the calibration files it reads and writes, must not damage the gripper and must not hide a mistake. The probe advanced its target unconditionally (`target += sign * step_rad`), so once the jaws reached a stop the command kept leading further every cycle and `kp * error` kept growing until the structure gave way. The position-based stall test cannot catch that: at a stop the encoder still creeps (backlash, elastic deformation, micro-slip). The target is now re-derived from the measured position each cycle, capping the lead at one step (pressing torque <= kp * step_rad), and the probe aborts the moment `|tau|` reaches the new `tau_limit` (2.0 Nm) -- a guard that does not depend on the stall counter. `calibrate()`'s two back-offs get the same treatment instead of a half-second unguarded `goto_rad(..., kp=80)`. Probe defaults move to kp=20 / step=0.05, the values `zero()` already used. `save_calibration` stamped `"mst_id": 0` when the id was unknown. Reading that file back installed a CAN RX filter of 0x000, so every motor reply was dropped and `enable()` failed after its whole retry loop. The key is now omitted while unknown, and a falsy id in an existing file keeps auto-detect. The package installed a `NullHandler`, hiding its own WARNING that a calibration file belongs to another channel -- a safety signal the user has to see. With no handler, `logging.lastResort` prints it to stderr.
|
🎉 This PR is included in version 0.5.2 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
This was referenced Sep 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three calibration-safety fixes with one theme: the routine that drives the jaws into a hard stop, and the calibration files it reads and writes, must not damage the gripper and must not hide a mistake.
The probe used to advance its target unconditionally (
target += sign * step_rad). Once the jaws reached a stop the command kept leading further every cycle, sokp * errorkept growing until the structure gave way. The position-based stall test cannot stop that on hardware: at a stop the encoder still creeps (backlash, elastic deformation, micro-slip), sodelta < stall_deltanever holds. Two independent guards now bound it. This is the failure mode that broke a jaw during calibration on 2026-09-29.The other two fixes make a calibration mistake visible instead of silent: an unknown motor id written as
0bricked the nextenable(), and the package's ownNullHandlerswallowed the warning that a calibration file belongs to another channel.Bundled in one PR because all three are "calibration must be safe and honest"; each is a
fix:so the release is a single patch. Splitting is easy if you prefer separate PRs.Changes
src/litegrip/gripper.py—calibrate()/calibrate_guided(): re-derive the probe target from the measured position each cycle (lead <=step_rad), so the pressing torque is at mostkp * step_rad; addtau_limit(default 2.0 Nm) and abort the probe the moment|tau|reaches it. Replacecalibrate()'s two half-second unguardedgoto_rad(..., kp=80)back-offs with a_bounded_movethat uses the same lead and torque guards. Probe defaults move tokp=20,step_rad=0.05,stall_delta=0.0015,stall_cycles=5,max_iter=200— the valueszero()already used.src/litegrip/gripper.py—save_calibration()omitsmst_idwhile the id is unknown instead of writing0;load_calibration()treats a falsycan_id/mst_idas "unknown" so it keeps auto-detect rather than pinning the RX filter to 0x000.src/litegrip/actions.py— theMotionConfigprobe defaults above, pluscalib_tau_limit;GripperActions.zero()passes it through.src/litegrip/__init__.py— drop theNullHandler(logging.lastResortnow shows WARNING and above) with a comment saying why.tests/test_calibration.py—TestCalibrateCommandLeadIsBounded,TestCalibrateTorqueCeiling(a fake motor that keeps creeping at the stop, so only the torque ceiling can end the probe),TestMasterIdIsNotPinned,TestLibraryDoesNotSilenceItsOwnLogs.README.md/readme_zn.md— updatedcalib_*table rows and thezero()vscalibrate()note.Testing
The probe guard is covered by the fake-motor suite only. The
tau_limitabort was not re-run on real hardware in this PR; it is a new ceiling on top of the lead bound, so the tested behaviour is at least as safe as the validated one.Issues
None — the repository has no issue tracker entries, matching the previous PRs.