Repository navigation
feat: add SDK-local kinematics and guarded pose PTP - #48
Conversation
yd-sl
left a comment
There was a problem hiding this comment.
Review — validated on a real arm
Tested commit 672ffc5 on a real 7J LiteArm (firmware Litearm1.11.1-7J), plus the offline suite.
What works
- Local FK matches firmware
get_tcpon hardware: 7.6e-8 m position, 1.1e-7 rotation. The packaged URDF is consistent with the board. - At the singular boot pose (
sigma_min=0.019)move_pose()correctly refuses before sending anything (reason=near_singular). After a deliberate slow escape (movej_sync, J4 -> -1.0 rad,speed=0.1), sigma was 0.0717. move_pose()increments of 2 / 5 / 10 mm all passed preflight and arrived without faults. Measured tip error 0.68 / 1.12 / 0.73 mm; sigma stayed 0.072-0.077; self-clearance 22.4 mm.- The fail-closed design (fresh
status_seq, live runtime limits, path sampling, branch-jump guard, collision/clearance/sigma checks) behaves as described.
Findings
1. Motion lock coverage is incomplete — arm.py:2347, 2364, 2382, 2390
The PR description says "Positive motion APIs are serialized through one re-entrant lock", but home(), move_js(), send_mit() and send_mit_all() are not decorated with _serialize_positive_motion. Reproduced with the fake transport: while one thread holds _motion_serial (simulating an in-flight move_pose preflight), home() / move_js() / send_mit() still transmitted 0x2A / 0x03 / 0x04; only movej() blocked until the lock was released. A concurrent home() can therefore invalidate the read state -> preflight -> one frame atomicity that the guard relies on. Either decorate these too, or explicitly narrow the claim/docs to the discrete PTP/Cartesian entry points.
2. examples/10_local_kinematics.py:46-47 has an enable race
The example calls enable() and immediately move_pose(). The enabled flag takes 17.6-48.5 ms to appear on hardware (already documented in Arm.enable()), while _fresh_state() (kinematics.py:317) waits for only one new status frame. Reproduced deterministically by delaying the enabled bit in the fake status stream: the call raises InvalidCommandError: move_pose 要求机械臂已使能 with no motion frame sent. Poll get_state().enabled before calling move_pose().
3. Arrival accuracy is not the IK tolerance
The IK tolerance is 0.5 mm / 0.005 rad, but final accuracy is governed by the firmware arrival criterion; measured tip error was 0.7-1.1 mm. Worth stating explicitly in the move_pose() docs so callers do not expect 0.5 mm.
4. Package size (non-blocking)
The 9 STL collision meshes add ~62 MB to git and the wheel. Default install remains pyserial-only, but consider decimation or a separate data package.
Test notes
764 passed, 22 skipped. One timing-sensitive failure intests/test_cart_protocol.py::test_poll_cart_does_not_steal_a_frame_from_a_running_entryunder the full suite only; it passes standalone, as a file, and onmain, so it appears unrelated to this PR.- The cross-repo
kin.cFK/Jacobian consistency test passed here.
Not covered
- Self-collision / soft-limit / start-drift rejections were exercised offline only; no dangerous configurations were constructed on hardware.
- External obstacles (people, bench, fixtures) are out of scope, as stated in the PR.
Overall: solid implementation and a real-hardware PASS. Items 1 and 2 should be addressed before merge.
672ffc5 to
18afde8
Compare
|
@yd-sl 感谢真机 review,指出的两个阻塞项已在
同时已 rebase 到最新 |
|
🎉 This PR is included in version 1.4.0 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
Summary
arm.kinematics.fk(),jacobian(),ik(), andmove_pose()using Pinocchio and the packaged LiteArm URDFArm.ik()andArm.get_tcp()as firmware-remote APIs, and keeplitearm.exact_ikas the velocity-level differential IK APIminimum_distance(q)roboticsdependency groupGuarded pose PTP
arm.kinematics.move_pose()solves IK locally, then sends exactly one existingCMD_MOVE_J_SYNC (0x07)target. STM32 remains responsible for synchronized S-curve execution and joint velocity, acceleration, and jerk limits.Before sending a motion frame it:
sigma_min >= 0.05Positive motion APIs are serialized through one re-entrant lock, including
home,move_js,send_mit,send_mit_all, andjoint_follow.emergency_stop()anddisable()deliberately bypass it.Review follow-up
Addressed the hardware review in
18afde8:main(5643e47) without restoring the full test suite intentionally removed upstreamHardware review already confirmed local FK agreement (about
7.6e-8 mposition and1.1e-7rotation), singularity rejection, successful 2/5/10 mm guarded moves, and fail-closed behavior. Observed final TCP error was about 0.7-1.1 mm; this is recorded as informative test data, not a universal accuracy specification.Compatibility
Arm.ik(),get_tcp(),movej(),movej_sync(), andmove_p()signatures remain unchangedpyserial; local robotics is installed withlitearm-python[robotics]2.2.0Verification
6 passed7 passed43 passed, 5 subtests passedkin.cat fixed and 20 deterministic random configurationsCMD_MOVE_J_SYNCand neverCMD_GET_IKSafety boundary
This detects robot self-collision only. It does not model people, workbenches, tooling fixtures, or other external obstacles. A singular boot pose is intentionally rejected by
move_pose(); operators must first leave it with a deliberately slow joint-space move in a clear workspace.