Skip to content

feat: add thread-safe release api for ending a grasp - #58

Merged
cao-xiao-hao merged 3 commits into
mainfrom
feat/release-api
Oct 29, 2026
Merged

cao-xiao-hao merged 3 commits into
mainfrom
feat/release-api

Conversation

@cao-xiao-hao

Copy link
Copy Markdown
Contributor

Summary

grasp(force_n, hold_s = 0) holds until a fault, so there was no way to end a grip from another thread short of a disconnect. This adds the release API the Python SDK already has, so both SDKs behave the same.

  • release(clearance_mm = 10.0, abort = false, timeout_s = nullopt) -> ReleaseResult
  • request_release(clearance_mm = 10.0, abort = false) -> bool (queue only, never sends a frame)
  • GraspResult::released, ReleaseResult, MotionConfig::release_wait_s

Also two unrelated packaging fixes found while preparing the repo for publishing.

Changes

  • Add ReleaseCoordinator: cross-thread request/result hand-off. The mutex guards only its own fields and never the bus. The grasp thread checks for a request before every frame (5 ms); the caller waits on the condition variable and receives the published result.
  • grasp() ends on a release request: during the force-carrying approach it aborts the leg before hand-over, during the hold it drops the setpoint, and both perform the opening. The hand-over pose and the pending request are read in one critical section so a request landing at the hand-over cannot be missed.
  • The opening target is max(current, hand-over pose) + clearance_mm, clamped to the calibrated open stop and run on the existing bounded ramp.
  • abort = true is the E-stop form: one zero-gain frame, no opening move. An abort overrides a normal release that is still queued (never the reverse).
  • With no grasp running, release() opens in the calling thread; a non-finite timeout_s or a negative/non-finite clearance throws CommandError before anything is sent.
  • Rename the private protective release(pos, source) to drop_torque so it cannot be confused with the public API.
  • Tests: cross-thread end of a hold_s = 0 grip, release during the approach, abort form, no-grasp form, request-queue rules, timeout and negative timeout, argument validation.
  • Docs: both READMEs get the new methods, ReleaseResult, release_wait_s, an "Ending a grip" section, a troubleshooting row and the layers-table entry.
  • package.xml: license was MIT while LICENSE is Apache-2.0; the maintainer was a TODO placeholder.
  • test/generate_golden.py: SDK_ROOT pointed at a non-existent ../litegrip_driver, so the regeneration command documented in the README could not run. It now prefers a sibling litegrip-python/src checkout and falls back to an installed package.

Testing

$ cmake --build build -j8
[100%] Built target test_motion

$ ctest --test-dir build --output-on-failure
100% tests passed out of 14
Total Test time (real) =   3.29 sec

test/generate_golden.py was run against the current Python SDK; the regenerated golden_generated.hpp is byte-identical (no diff).

No hardware was used: every test runs against the fake plant.

Issues

None.

grasp() with hold_s = 0 holds until a fault, which leaves no way to end
the grip short of a disconnect. release() and request_release() close
that gap, ported from the Python SDK so the two agree:

- ReleaseCoordinator hands a request between threads without ever
  touching the bus: the grasp thread checks it before every frame and
  performs the opening, the caller waits for the published result.
- The opening starts from the hand-over pose, not from where the set
  force pressed the jaws to, and runs on the same bounded ramp.
- abort = true drops the torque and sends no opening move; it also
  overrides a normal release that is still queued.
- With no grasp running, release() opens in the calling thread.

Tests cover the cross-thread hold, a release during the approach, the
abort form, the no-grasp form, the request queue rules, a timeout, and
the argument checks. Both READMEs document the new API.
@cao-xiao-hao
cao-xiao-hao merged commit 4f863f1 into main Oct 29, 2026
1 check passed
@cao-xiao-hao
cao-xiao-hao deleted the feat/release-api branch October 29, 2026 09:42
@github-actions

Copy link
Copy Markdown

🎉 This PR is included in version 1.1.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

@github-actions github-actions Bot added the released Shipped in a release label Oct 29, 2026
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.

1 participant