[cao-xiao-hao]

Summary

A failed MIT frame now reports the cause and the type it actually has, instead of one fixed message that guessed.

GripperActions._emit() is the chokepoint for every frame the engine sends, and it turned a failed send_mit_frame() into CommandError("MIT 帧下发失败（未连接或未使能）"). On the bench this shipped a lie: the CAN interface went ENETDOWN part-way through a move, is_connected and is_enabled were both True at the instant the exception was raised, and the real cause — OSError(100, 'Network is down') — existed only as a log.warning attached to no exception, so a caller with no log handler saw the false message and nothing else.

README.md's error table already says what these are: a CAN write that fails mid-session is CommError, and not connected / not enabled is what NotInitializedError exists for. CommandError is for a rejected command. The code now matches the table.

Note for callers: this breaks catching CommandError around a motion call — such a caller now sees CommError or NotInitializedError instead. Both are LiteGripError subclasses, so catching the base still works. Publishes as a patch under this policy.

Changes

• src/litegrip/protocols/can_bus.py — LiteGripCAN.control_mit() / control_mit_stream() keep the failure in a new last_send_error property (the exception itself, type included; cleared on success, NotInitializedError when nothing is registered). The False return and the warning are unchanged.
• src/litegrip/gripper.py — new LiteGrip.last_send_error. send_mit_frame() passes the bus reason up, and supplies its own NotInitializedError when _can is None or the gripper is not enabled; the two messages are now single-sourced with _check_connected() / _check_enabled().
• src/litegrip/actions.py — _emit() raises NotInitializedError for a missing connection or enable, CommError carrying the reason for a transport failure, and says "原因未记录" when nothing recorded one. The original exception rides along as __cause__.
• src/litegrip/trajectory.py — the replay abort keeps its TrajectoryError type but carries the send's own reason instead of "未连接或未使能?".
• src/litegrip/teleop.py — the slave loop's first-failure warning names the reason rather than listing both possibilities. The loop still just counts; a lost frame must not abort it.
• tests/fake_can.py — FakeLiteGripCAN mirrors the new attribute and gains a send_error knob, so a test can make a send fail with a reason.
• Both READMEs document last_send_error and the typed report.
• Tests: tests/test_send_failure_reports_its_cause.py (13 cases, all three layers) and one in tests/test_teleop.py.

Testing

From /home/qaz/litegrip-python:

$ python3 -m unittest discover -s tests -t tests
Ran 454 tests in 9.783s

OK (skipped=12)

Baseline on the same machine before this branch: Ran 440 tests ... OK (skipped=12). The 14 added are the 13 in the new module and the 1 in test_teleop.py.

Each new case was checked against the unmodified code — with src/ stashed, all 13 error out; with only teleop.py stashed, the teleop case fails with the old line (the motor is not enabled or the CAN write failed). Nothing is skipped or weakened.

Markdown lint runs clean with the CI version:

$ npx --yes markdownlint-cli2@0.23.3 "README.md" "readme_zn.md"
Summary: 0 issues in 0 files

Issues

Closes #65

[github-actions]

🎉 This PR is included in version 1.0.3 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀