Skip to content

feat: add contact protection SDK support and zero-g disable guard - #50

Open
X-F-R wants to merge 1 commit into
mainfrom
feat/contact-protection-sdk
Open

X-F-R wants to merge 1 commit into
mainfrom
feat/contact-protection-sdk

Conversation

@X-F-R

@X-F-R X-F-R commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Summary

Expose the firmware 1.13.0 contact-protection commands through the SDK, add a quick-start example, and make zero-gravity hand-guiding safe against an accidental disable().

Changes

  • Add typed methods for 0x16–0x1C: set_contact_config, contact_on, contact_off, contact_calibrate, contact_clear, contact_resume, get_contact_state, set_contact_mode, get_contact_mode.
  • get_contact_state / get_contact_mode return the standard Msg envelope; phase/response names are decoded in the SDK.
  • Validate the 7-joint vectors and thresholds locally, and refuse to arm the compiled-in generic thresholds unless allow_default_thresholds=True is explicit.
  • set_contact_mode() accepts the documented "hold" / "warn" / "hard-only" names as well as the raw 0-2 values.
  • Add protocol constants, error-code text, command-coverage entries and FakeTransport emulation for 0x16–0x1C.
  • Add examples/11_contact.py (studio ready pose → calibrate → hand push → clear) and document the surface in the EN/ZH README, developer guide and examples README.
  • disable() is now refused while the zero-g keep-alive is active: zero-g holds the arm with gravity feedforward plus light damping, so disabling there collapses it. Call zero_g_stop() first; emergency_stop() remains always reachable.

Testing

Offline, exactly as CI runs them:

$ PYTHONPATH=src python3 -m pytest tests/ -q
55 passed

$ PYTHONPATH=src python3 -m unittest discover -s tests
Ran 7 tests in 0.209s
OK

Real arm (Litearm1.13.0-7J, /dev/ttyACM0): exercised contact arm/calibrate/latch/clear/resume, zero-g enter/exit, movej/move_l/move_p/move_path/move_c, home, move_js, send_mit/send_mit_all/joint_follow, park, and emergency_stop/reset/disable. The zero-g disable() now raises host-side with the arm staying enabled in ZERO_G; after zero_g_stop() the arm holds normally. Final state: enabled at the studio ready pose with contact ARMED.

Issues

None.

Checklist

  • The title follows Conventional Commits and matches the commit subject.
  • The body is written in English.
  • Tests were run and the result is stated above.
  • Human-facing documents are paired with .zh-CN.md and keep the language switcher.
  • No secrets, credentials, or private URLs are included.
  • No issue is fully resolved here, so no Closes line is used.

Expose the firmware 1.13.0 contact-protection commands (0x16-0x1C):
set_contact_config/contact_on/contact_off, contact_calibrate,
contact_clear, contact_resume, get_contact_state, set_contact_mode and
get_contact_mode. Contact state/mode reads return Msg envelopes.

- Validate vectors and thresholds locally; refuse to arm the uncalibrated
  generic table unless allow_default_thresholds=True.
- Accept the documented response names ("hold"/"warn"/"hard-only") in
  set_contact_mode alongside the raw 0-2 values.
- Emulate 0x16-0x1C in FakeTransport and add offline tests.
- Add examples/11_contact.py and document the surface in the EN/ZH
  README, developer guide and examples README.
- Refuse disable() while the zero-g keep-alive is active: disabling there
  drops the gravity feedforward and hold torque, so the arm collapses.
  Call zero_g_stop() first; emergency_stop() remains always reachable.

Tests: pytest 55 passed; python -m unittest discover -s tests runs the
7 CI tests OK. On a real Litearm1.13.0-7J arm, contact arm/calibrate/
latch/clear/resume, zero-g enter/exit, movej/move_l/move_p/move_path/
move_c, home, move_js, send_mit/send_mit_all/joint_follow, park and
emergency_stop/reset/disable were exercised; the arm ends enabled at the
studio ready pose with contact ARMED.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant