litegrip-python 1.2.1__tar.gz → 1.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. {litegrip_python-1.2.1/src/litegrip_python.egg-info → litegrip_python-1.3.1}/PKG-INFO +33 -10
  2. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/README.md +32 -9
  3. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/pyproject.toml +1 -1
  4. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/__init__.py +22 -0
  5. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/actions.py +112 -11
  6. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/can/controller.py +50 -11
  7. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/gripper.py +55 -12
  8. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/teleop.py +352 -39
  9. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/zenoh_link.py +61 -21
  10. {litegrip_python-1.2.1 → litegrip_python-1.3.1/src/litegrip_python.egg-info}/PKG-INFO +33 -10
  11. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip_python.egg-info/SOURCES.txt +1 -0
  12. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_actions.py +149 -5
  13. litegrip_python-1.3.1/tests/test_can_poll_drain.py +151 -0
  14. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_teleop.py +351 -25
  15. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/LICENSE +0 -0
  16. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/setup.cfg +0 -0
  17. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/calibration_normal.json +0 -0
  18. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/calibration_reverse.json +0 -0
  19. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/can/__init__.py +0 -0
  20. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/can/motor.py +0 -0
  21. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/can/protocol.py +0 -0
  22. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/can/transport.py +0 -0
  23. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/constants.py +0 -0
  24. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/exceptions.py +0 -0
  25. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/factory_calibration.json +0 -0
  26. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/models.py +0 -0
  27. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/protocols/__init__.py +0 -0
  28. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/protocols/can_bus.py +0 -0
  29. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/py.typed +0 -0
  30. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/trajectory.py +0 -0
  31. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip_python.egg-info/dependency_links.txt +0 -0
  32. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip_python.egg-info/requires.txt +0 -0
  33. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip_python.egg-info/top_level.txt +0 -0
  34. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_bus_limits.py +0 -0
  35. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_calibration.py +0 -0
  36. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_can_stream_silence.py +0 -0
  37. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_enable.py +0 -0
  38. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_example_hold_force.py +0 -0
  39. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_example_teleop.py +0 -0
  40. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_examples_bootstrap.py +0 -0
  41. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_iface_mtu.py +0 -0
  42. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_protocol.py +0 -0
  43. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_send_failure_reports_its_cause.py +0 -0
  44. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_state_staleness.py +0 -0
  45. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_trajectory.py +0 -0
  46. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_transport_send.py +0 -0
  47. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_version.py +0 -0
  48. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_write_zero.py +0 -0
  49. {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_zenoh_link.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: litegrip-python
3
- Version: 1.2.1
3
+ Version: 1.3.1
4
4
  Summary: Python SDK for the LiteGrip lightweight robotic gripper series
5
5
  Author: NEXFORM ROBOTICS
6
6
  License-Expression: Apache-2.0
@@ -202,7 +202,7 @@ young. Ask both when the difference matters.
202
202
  | `open(speed_mm_s=None, *, progress=None)` → `MoveResult` | Ramps toward the calibrated open-side stop. With `GripperConfig.work_stroke_mm` set it stops at that opening instead — the shipped calibration sets `80.0` against the unit's 85 mm of travel, so a plain `open()` ends 5 mm short of the open end. |
203
203
  | `close(speed_mm_s=None, *, progress=None)` → `MoveResult` | The same, toward the closed side. `work_stroke_mm` is an open-side number and does not change where a close ends. |
204
204
  | `home()` → `MoveResult` | Ramps to the calibrated closed position. |
205
- | `grasp(force_n=None, hold_s=0.0, *, progress=None)` → `GraspResult` | Closes onto the object — or onto the closed-side calibrated stop if there is nothing there — then ramps to and holds `force_n` N. The closing leg carries `force_n` as its torque budget, so meeting the object presses no harder than the setpoint. The hold takes over only once the jaw is stopped: it is `stalled=True` (something is between the jaws) or `reached=True` (the jaws closed empty). A stop that came **without the jaw ever moving from where the approach began**, with a budget below `MotionConfig.breakaway_nm`, is not treated as contact — the budget simply cannot break static friction — so the call releases in place and returns `no_bite=True` instead of handing over the hold. `hold_s=0` holds until a fault, the runaway watch, Ctrl+C, or a `release()` / `request_release()` from another thread — which ends the grasp with `released=True`. `force_n=None` uses `MotionConfig.force_n` (20 N). |
205
+ | `grasp(force_n=None, hold_s=0.0, *, progress=None)` → `GraspResult` | Closes onto the object — or onto the closed-side calibrated stop if there is nothing there — then ramps to and holds `force_n` N. The closing leg carries `force_n` as its torque budget, so meeting the object presses no harder than the setpoint. The hold takes over only once the jaw is stopped: it is `stalled=True` (something is between the jaws) or `reached=True` (the jaws closed empty). In the force approach `stalled=True` also requires the window's average speed to be under `MotionConfig.stall_speed_mm_s` (2 mm/s), so a jaw that is still creeping is not mistaken for contact and handed to the torque-only hold. A stop that came **without the jaw ever moving from where the approach began**, with a budget below `MotionConfig.breakaway_nm`, is not treated as contact — the budget simply cannot break static friction — so the call releases in place and returns `no_bite=True` instead of handing over the hold. `hold_s=0` holds until a fault, the runaway watch, Ctrl+C, or a `release()` / `request_release()` from another thread — which ends the grasp with `released=True`. `force_n=None` uses `MotionConfig.force_n` (20 N). |
206
206
  | `release(clearance_mm=10.0, *, abort=False, timeout_s=None)` → `ReleaseResult` | Ends an in-progress `grasp()` and opens the jaws from the pose where the grip was declared, by `clearance_mm` more, clamped to the calibrated open stop. Safe to call from any thread while `grasp(hold_s=0)` is blocked in another: it queues the request, the grasp thread performs the opening, and the call returns that outcome. With no grasp running it opens from the current position in the calling thread. `abort=True` is the E-stop form: torque off, no opening move, `ok=False`. A second call during the same grasp joins the first. |
207
207
  | `request_release(clearance_mm=10.0, *, abort=False)` → `bool` | Non-blocking form of `release()`: records the request if a grasp is running and returns `True`, else `False`. Never sends a frame, so it is safe for a UI thread, a signal handler or an E-stop callback. The grasp thread acts on it before its next frame (within 5 ms). |
208
208
  | `goto(position_mm, kp=None, kd=None, duration=0.5)` → `MoveResult` | Ramp to a position in millimetres. |
@@ -259,6 +259,14 @@ the closed-side stop) and stops there before the hold takes over.
259
259
  - **The jaws stay compliant.** An external push back-drives them while the motor keeps pushing
260
260
  with `force_n`, and an empty `grasp()` closes onto the mechanical stop at that force. That is
261
261
  the price of a force that does not drift when the workpiece moves.
262
+ - **Below about 2.2 N the jaws may not close at all**, so keep `force_n` at 3 N or more. The
263
+ closing leg's torque budget *is* the setpoint, and the mechanism needs about 0.2 Nm — 2.2 N of
264
+ setpoint — to break away from static friction. Under that the approach never moves, and
265
+ `grasp()` refuses the hand-over rather than reading the stillness as contact: `ok=False`,
266
+ `no_bite=True`, torque dropped, no hold frames. That refusal is the safe answer to a grip that
267
+ could not have closed; the alternative, handing over to a hold that presses at a slightly higher
268
+ torque, walks the jaws across the free stroke. Between 2.2 N and about 3 N it closes, but on this
269
+ bench the grip is marginal, so 3 N is the number to ask for.
262
270
  - **Below about 3.7 N the approach speed becomes the limit**, because one frame of travel at
263
271
  `grasp_speed_mm_s` already spends the whole torque budget. Cap the travel time with
264
272
  `grasp_speed_mm_s` rather than asking for a force the mechanism's own friction absorbs.
@@ -407,7 +415,10 @@ What it *means*, and what to check, is per action:
407
415
  A fourth combination is a failure, and new in this version:
408
416
 
409
417
  - **`grasp()` with `ok=False, reached=False, stalled=False`** means the closing leg ran out of
410
- frames without reaching the stop and without stalling — the jaw is still in free travel. The
418
+ frames without reaching the stop and without stalling — the jaw is still in free travel. A
419
+ slow creep lands here too: the window's net displacement is small, but its average speed is
420
+ still above `MotionConfig.stall_speed_mm_s` (2 mm/s), so it never counts as a stop and the leg
421
+ runs to its frame ceiling. The
411
422
  hold is *not* entered: its frames carry no position and no velocity term, so handing a moving
412
423
  jaw over to them leaves the feed-forward torque as the only thing acting on it, and the jaw
413
424
  accelerates until the runaway watch releases it. The call releases in place instead and reports
@@ -533,9 +544,9 @@ with LiteGrip("can0") as slave:
533
544
 
534
545
  | Method | What it does |
535
546
  | --- | --- |
536
- | `teleop_start(mode, *, transport=None, link="zenoh", host=None, port=17448, grip_id="gripA", kp=None, kd=None, align=True, watchdog_s=0.2, dq_max=10.0, torque_limit_nm=0.0, require_ready=True, ...)` → `dict` | Starts the background loop for `mode="master"` or `"slave"`. Both ends must share `grip_id` and be connected and enabled first. |
547
+ | `teleop_start(mode, *, transport=None, link="zenoh", host=None, port=17448, grip_id="gripA", kp=None, kd=None, align=True, watchdog_s=0.2, dq_max=10.0, torque_limit_nm=0.0, torque_guard_action="hold", require_ready=True, force_feedback=False, feedback_gain_nm_per_n=0.10, ...)` → `dict` | Starts the background loop for `mode="master"` or `"slave"`. Both ends must share `grip_id` and be connected and enabled first. |
537
548
  | `teleop_stop(timeout=2.0)` → `dict` | Stops the loop and leaves the jaws holding. |
538
- | `teleop_status()` → `dict` | `active`, `mode`, `frames`, `last_frame_age_ms`, `stale`, `openness`, `position_mm`, `force_n`, `loop_hz`, `rejected`, `send_failed`, `fault`, `torque_nm`, `over_torque`, `torque_trips`, `ready`, and more. |
549
+ | `teleop_status()` → `dict` | `active`, `mode`, `frames`, `last_frame_age_ms`, `stale`, `openness`, `position_mm`, `force_n`, `loop_hz`, `rejected`, `send_failed`, `fault`, `torque_nm`, `over_torque`, `torque_trips`, `ready`, `feedback_force_n`, `feedback_tau_nm`, `feedback_rx`, `feedback_tx`, and more. |
539
550
 
540
551
  The link is a point-to-point **zenoh** session, an optional dependency:
541
552
 
@@ -565,11 +576,23 @@ python3 examples/teleop.py --mode slave --channel can0 --fake-leader --torque-li
565
576
  - **The leader holds its jaws under gain until the follower reports ready**, so the operator
566
577
  cannot push the target out from under a follower that is still travelling. `ready_timeout_s`
567
578
  (default `10.0`) bounds the wait; `require_ready=False` restores the immediate hand-back.
568
- - **An optional torque guard releases a follower that is pressing too hard.** Set
569
- `torque_limit_nm` and it goes to zero stiffness and damping *in place* after 60 ms over the
570
- limit, then re-arms once the leader has reopened. The default is `0` — **the guard is off
571
- unless you ask for it**. Pick the value per machine: it depends on how fragile the part between
572
- the jaws is.
579
+ - **An optional torque guard stops a follower that is pressing too hard.** Set
580
+ `torque_limit_nm` and, after 60 ms over the limit, the follower stops following and **keeps
581
+ pressing with that torque** (`kp=kd=0`, `tau=±torque_limit_nm`, signed by the torque measured
582
+ at the trip) so a clamped part is not pushed open; it re-arms once the leader has reopened.
583
+ `torque_guard_action="release"` restores the previous behaviour — zero stiffness and damping
584
+ *in place* — which lets the part push the jaws straight open. The default is `0` — **the guard
585
+ is off unless you ask for it**. Pick the value per machine: it depends on how fragile the part
586
+ between the jaws is.
587
+ - **The follower's squeeze can be felt on the leader.** With `force_feedback=True` the follower
588
+ publishes `force_n` on `litearm/v4/{grip_id}/gripper_feedback` (positive means closing,
589
+ normalised for the mount) and the leader renders resistance at
590
+ `min(max(0, force_n - feedback_threshold_n) * feedback_gain_nm_per_n, feedback_max_tau_nm)`,
591
+ directed against closing. Defaults: threshold `2.0` N, gain `0.10` Nm/N, cap `1.0` Nm.
592
+ Damping (`0.1`) applies only while the force is fresh; torque and damping both drop to zero
593
+ after `feedback_timeout_s` (`0.3`). It is off by default and needs the zenoh link — a UDP
594
+ leader is publish-only, so it runs without feedback. The key is additive, so an older peer
595
+ simply runs position-only teleoperation.
573
596
  - **A follower that loses the leader holds its position, it does not go slack.** After
574
597
  `watchdog_s` (default `0.2`) without a fresh frame, `stale` goes true and the jaws stay put.
575
598
  - **The follower feeds the leader's velocity forward** by differencing successive frames, so it
@@ -174,7 +174,7 @@ young. Ask both when the difference matters.
174
174
  | `open(speed_mm_s=None, *, progress=None)` → `MoveResult` | Ramps toward the calibrated open-side stop. With `GripperConfig.work_stroke_mm` set it stops at that opening instead — the shipped calibration sets `80.0` against the unit's 85 mm of travel, so a plain `open()` ends 5 mm short of the open end. |
175
175
  | `close(speed_mm_s=None, *, progress=None)` → `MoveResult` | The same, toward the closed side. `work_stroke_mm` is an open-side number and does not change where a close ends. |
176
176
  | `home()` → `MoveResult` | Ramps to the calibrated closed position. |
177
- | `grasp(force_n=None, hold_s=0.0, *, progress=None)` → `GraspResult` | Closes onto the object — or onto the closed-side calibrated stop if there is nothing there — then ramps to and holds `force_n` N. The closing leg carries `force_n` as its torque budget, so meeting the object presses no harder than the setpoint. The hold takes over only once the jaw is stopped: it is `stalled=True` (something is between the jaws) or `reached=True` (the jaws closed empty). A stop that came **without the jaw ever moving from where the approach began**, with a budget below `MotionConfig.breakaway_nm`, is not treated as contact — the budget simply cannot break static friction — so the call releases in place and returns `no_bite=True` instead of handing over the hold. `hold_s=0` holds until a fault, the runaway watch, Ctrl+C, or a `release()` / `request_release()` from another thread — which ends the grasp with `released=True`. `force_n=None` uses `MotionConfig.force_n` (20 N). |
177
+ | `grasp(force_n=None, hold_s=0.0, *, progress=None)` → `GraspResult` | Closes onto the object — or onto the closed-side calibrated stop if there is nothing there — then ramps to and holds `force_n` N. The closing leg carries `force_n` as its torque budget, so meeting the object presses no harder than the setpoint. The hold takes over only once the jaw is stopped: it is `stalled=True` (something is between the jaws) or `reached=True` (the jaws closed empty). In the force approach `stalled=True` also requires the window's average speed to be under `MotionConfig.stall_speed_mm_s` (2 mm/s), so a jaw that is still creeping is not mistaken for contact and handed to the torque-only hold. A stop that came **without the jaw ever moving from where the approach began**, with a budget below `MotionConfig.breakaway_nm`, is not treated as contact — the budget simply cannot break static friction — so the call releases in place and returns `no_bite=True` instead of handing over the hold. `hold_s=0` holds until a fault, the runaway watch, Ctrl+C, or a `release()` / `request_release()` from another thread — which ends the grasp with `released=True`. `force_n=None` uses `MotionConfig.force_n` (20 N). |
178
178
  | `release(clearance_mm=10.0, *, abort=False, timeout_s=None)` → `ReleaseResult` | Ends an in-progress `grasp()` and opens the jaws from the pose where the grip was declared, by `clearance_mm` more, clamped to the calibrated open stop. Safe to call from any thread while `grasp(hold_s=0)` is blocked in another: it queues the request, the grasp thread performs the opening, and the call returns that outcome. With no grasp running it opens from the current position in the calling thread. `abort=True` is the E-stop form: torque off, no opening move, `ok=False`. A second call during the same grasp joins the first. |
179
179
  | `request_release(clearance_mm=10.0, *, abort=False)` → `bool` | Non-blocking form of `release()`: records the request if a grasp is running and returns `True`, else `False`. Never sends a frame, so it is safe for a UI thread, a signal handler or an E-stop callback. The grasp thread acts on it before its next frame (within 5 ms). |
180
180
  | `goto(position_mm, kp=None, kd=None, duration=0.5)` → `MoveResult` | Ramp to a position in millimetres. |
@@ -231,6 +231,14 @@ the closed-side stop) and stops there before the hold takes over.
231
231
  - **The jaws stay compliant.** An external push back-drives them while the motor keeps pushing
232
232
  with `force_n`, and an empty `grasp()` closes onto the mechanical stop at that force. That is
233
233
  the price of a force that does not drift when the workpiece moves.
234
+ - **Below about 2.2 N the jaws may not close at all**, so keep `force_n` at 3 N or more. The
235
+ closing leg's torque budget *is* the setpoint, and the mechanism needs about 0.2 Nm — 2.2 N of
236
+ setpoint — to break away from static friction. Under that the approach never moves, and
237
+ `grasp()` refuses the hand-over rather than reading the stillness as contact: `ok=False`,
238
+ `no_bite=True`, torque dropped, no hold frames. That refusal is the safe answer to a grip that
239
+ could not have closed; the alternative, handing over to a hold that presses at a slightly higher
240
+ torque, walks the jaws across the free stroke. Between 2.2 N and about 3 N it closes, but on this
241
+ bench the grip is marginal, so 3 N is the number to ask for.
234
242
  - **Below about 3.7 N the approach speed becomes the limit**, because one frame of travel at
235
243
  `grasp_speed_mm_s` already spends the whole torque budget. Cap the travel time with
236
244
  `grasp_speed_mm_s` rather than asking for a force the mechanism's own friction absorbs.
@@ -379,7 +387,10 @@ What it *means*, and what to check, is per action:
379
387
  A fourth combination is a failure, and new in this version:
380
388
 
381
389
  - **`grasp()` with `ok=False, reached=False, stalled=False`** means the closing leg ran out of
382
- frames without reaching the stop and without stalling — the jaw is still in free travel. The
390
+ frames without reaching the stop and without stalling — the jaw is still in free travel. A
391
+ slow creep lands here too: the window's net displacement is small, but its average speed is
392
+ still above `MotionConfig.stall_speed_mm_s` (2 mm/s), so it never counts as a stop and the leg
393
+ runs to its frame ceiling. The
383
394
  hold is *not* entered: its frames carry no position and no velocity term, so handing a moving
384
395
  jaw over to them leaves the feed-forward torque as the only thing acting on it, and the jaw
385
396
  accelerates until the runaway watch releases it. The call releases in place instead and reports
@@ -505,9 +516,9 @@ with LiteGrip("can0") as slave:
505
516
 
506
517
  | Method | What it does |
507
518
  | --- | --- |
508
- | `teleop_start(mode, *, transport=None, link="zenoh", host=None, port=17448, grip_id="gripA", kp=None, kd=None, align=True, watchdog_s=0.2, dq_max=10.0, torque_limit_nm=0.0, require_ready=True, ...)` → `dict` | Starts the background loop for `mode="master"` or `"slave"`. Both ends must share `grip_id` and be connected and enabled first. |
519
+ | `teleop_start(mode, *, transport=None, link="zenoh", host=None, port=17448, grip_id="gripA", kp=None, kd=None, align=True, watchdog_s=0.2, dq_max=10.0, torque_limit_nm=0.0, torque_guard_action="hold", require_ready=True, force_feedback=False, feedback_gain_nm_per_n=0.10, ...)` → `dict` | Starts the background loop for `mode="master"` or `"slave"`. Both ends must share `grip_id` and be connected and enabled first. |
509
520
  | `teleop_stop(timeout=2.0)` → `dict` | Stops the loop and leaves the jaws holding. |
510
- | `teleop_status()` → `dict` | `active`, `mode`, `frames`, `last_frame_age_ms`, `stale`, `openness`, `position_mm`, `force_n`, `loop_hz`, `rejected`, `send_failed`, `fault`, `torque_nm`, `over_torque`, `torque_trips`, `ready`, and more. |
521
+ | `teleop_status()` → `dict` | `active`, `mode`, `frames`, `last_frame_age_ms`, `stale`, `openness`, `position_mm`, `force_n`, `loop_hz`, `rejected`, `send_failed`, `fault`, `torque_nm`, `over_torque`, `torque_trips`, `ready`, `feedback_force_n`, `feedback_tau_nm`, `feedback_rx`, `feedback_tx`, and more. |
511
522
 
512
523
  The link is a point-to-point **zenoh** session, an optional dependency:
513
524
 
@@ -537,11 +548,23 @@ python3 examples/teleop.py --mode slave --channel can0 --fake-leader --torque-li
537
548
  - **The leader holds its jaws under gain until the follower reports ready**, so the operator
538
549
  cannot push the target out from under a follower that is still travelling. `ready_timeout_s`
539
550
  (default `10.0`) bounds the wait; `require_ready=False` restores the immediate hand-back.
540
- - **An optional torque guard releases a follower that is pressing too hard.** Set
541
- `torque_limit_nm` and it goes to zero stiffness and damping *in place* after 60 ms over the
542
- limit, then re-arms once the leader has reopened. The default is `0` — **the guard is off
543
- unless you ask for it**. Pick the value per machine: it depends on how fragile the part between
544
- the jaws is.
551
+ - **An optional torque guard stops a follower that is pressing too hard.** Set
552
+ `torque_limit_nm` and, after 60 ms over the limit, the follower stops following and **keeps
553
+ pressing with that torque** (`kp=kd=0`, `tau=±torque_limit_nm`, signed by the torque measured
554
+ at the trip) so a clamped part is not pushed open; it re-arms once the leader has reopened.
555
+ `torque_guard_action="release"` restores the previous behaviour — zero stiffness and damping
556
+ *in place* — which lets the part push the jaws straight open. The default is `0` — **the guard
557
+ is off unless you ask for it**. Pick the value per machine: it depends on how fragile the part
558
+ between the jaws is.
559
+ - **The follower's squeeze can be felt on the leader.** With `force_feedback=True` the follower
560
+ publishes `force_n` on `litearm/v4/{grip_id}/gripper_feedback` (positive means closing,
561
+ normalised for the mount) and the leader renders resistance at
562
+ `min(max(0, force_n - feedback_threshold_n) * feedback_gain_nm_per_n, feedback_max_tau_nm)`,
563
+ directed against closing. Defaults: threshold `2.0` N, gain `0.10` Nm/N, cap `1.0` Nm.
564
+ Damping (`0.1`) applies only while the force is fresh; torque and damping both drop to zero
565
+ after `feedback_timeout_s` (`0.3`). It is off by default and needs the zenoh link — a UDP
566
+ leader is publish-only, so it runs without feedback. The key is additive, so an older peer
567
+ simply runs position-only teleoperation.
545
568
  - **A follower that loses the leader holds its position, it does not go slack.** After
546
569
  `watchdog_s` (default `0.2`) without a fresh frame, `stale` goes true and the jaws stay put.
547
570
  - **The follower feeds the leader's velocity forward** by differencing successive frames, so it
@@ -14,7 +14,7 @@ name = "litegrip-python"
14
14
  # Python repositories the placeholder has to be plain `0.0.0`. The nearby
15
15
  # `0.0.0+semantic-release` spelling is valid PEP 440 but PyPI rejects local version
16
16
  # labels, so it would only move the failure to upload time.
17
- version = "1.2.1"
17
+ version = "1.3.1"
18
18
  description = "Python SDK for the LiteGrip lightweight robotic gripper series"
19
19
  readme = "README.md"
20
20
  requires-python = ">=3.10"
@@ -144,14 +144,25 @@ from .teleop import (
144
144
  DEFAULT_READY_TOLERANCE_MM,
145
145
  DEFAULT_READY_PERIOD_S,
146
146
  DEFAULT_READY_TIMEOUT_S,
147
+ DEFAULT_FEEDBACK_GAIN_NM_PER_N,
148
+ DEFAULT_FEEDBACK_THRESHOLD_N,
149
+ DEFAULT_FEEDBACK_MAX_TAU_NM,
150
+ DEFAULT_FEEDBACK_DAMPING,
151
+ DEFAULT_FEEDBACK_TIMEOUT_S,
152
+ TORQUE_GUARD_HOLD,
153
+ TORQUE_GUARD_RELEASE,
147
154
  FRAME_SIZE,
148
155
  READY_FRAME_SIZE,
156
+ FEEDBACK_FRAME_SIZE,
149
157
  encode_frame,
150
158
  decode_frame,
151
159
  encode_ready_frame,
152
160
  decode_ready_frame,
161
+ encode_feedback_frame,
162
+ decode_feedback_frame,
153
163
  teleop_topic,
154
164
  ready_topic,
165
+ feedback_topic,
155
166
  )
156
167
 
157
168
  # ── Trajectory record and replay ────────────────────────────────────────
@@ -268,14 +279,25 @@ __all__ = [
268
279
  "DEFAULT_READY_TOLERANCE_MM",
269
280
  "DEFAULT_READY_PERIOD_S",
270
281
  "DEFAULT_READY_TIMEOUT_S",
282
+ "DEFAULT_FEEDBACK_GAIN_NM_PER_N",
283
+ "DEFAULT_FEEDBACK_THRESHOLD_N",
284
+ "DEFAULT_FEEDBACK_MAX_TAU_NM",
285
+ "DEFAULT_FEEDBACK_DAMPING",
286
+ "DEFAULT_FEEDBACK_TIMEOUT_S",
287
+ "TORQUE_GUARD_HOLD",
288
+ "TORQUE_GUARD_RELEASE",
271
289
  "FRAME_SIZE",
272
290
  "READY_FRAME_SIZE",
291
+ "FEEDBACK_FRAME_SIZE",
273
292
  "encode_frame",
274
293
  "decode_frame",
275
294
  "encode_ready_frame",
276
295
  "decode_ready_frame",
296
+ "encode_feedback_frame",
297
+ "decode_feedback_frame",
277
298
  "teleop_topic",
278
299
  "ready_topic",
300
+ "feedback_topic",
279
301
  # Teleoperation — zenoh link (resolved lazily; needs litegrip-python[zenoh])
280
302
  "ZenohTeleopTransport",
281
303
  "Listener",
@@ -46,6 +46,11 @@ ROS 2 桥接、RPC 服务、产品代码都能直接调 :attr:`LiteGrip.actions`
46
46
  闭合侧有约 0.010 rad 的机械死区,慢速粘滑时单点忽大忽小。斜坡走完的保压段
47
47
  不判(那时夹爪本来就该不动)。
48
48
 
49
+ 带设定力的接近段还多一条**真停**条件:窗口平均速度低于
50
+ :attr:`MotionConfig.stall_speed_mm_s` 才算停住。这一段的实际速度本来就可能被
51
+ 力矩预算和摩擦压到指令速度的 20% 以下,只按比例判会把「慢」当成「顶住」,
52
+ 把纯力矩保力段接到还在走的夹爪上。
53
+
49
54
  保力段(``grasp`` 的第二段)反过来:只下发前馈力矩,不给位置/速度增益。
50
55
  力控要的是力,带增益就会随夹爪的位移衰减,详见
51
56
  :meth:`GripperActions._hold_force`。
@@ -133,6 +138,16 @@ class MotionConfig:
133
138
  stall_cycles: int = 5 # 窗口采样点数
134
139
  stall_ratio: float = 0.2 # 窗口净位移 / 本该走的距离
135
140
  stall_delta: float = 0.0015 # 阈值下限 rad
141
+ # 带设定力接近段判「真停」的速度下限 mm/s。这一段是位置帧,但预算和摩擦
142
+ # 会把实际速度压到指令的 20% 以下 —— 那不是接触。窗口平均速度必须低于
143
+ # 这个值才允许交接给纯力矩保力段。2026-11-18 台架:5 N 接近段约 8 mm/s,
144
+ # 0.25 s 只走 2 mm,被 20% 阈值判成堵转;保力段随后把它加速到 7 rad/s,
145
+ # 从 78 mm 冲到 26 mm 的工件上。
146
+ # 已知边界:自由蠕动低于这个值时仍可能被当成停住(2.5 N、约 1.9 mm/s
147
+ # 可复现)。2.5 N 低于 README 的 3 N 建议值(2.2 N 以下闭不上,2.2–3 N
148
+ # 勉强),属于不进保力段的边缘档位;支持范围内这条门槛留了 2 倍余量
149
+ # (5 N 接近段仍约 8 mm/s)。降到 0.5 mm/s 会让真接触也迟迟判不出来。
150
+ stall_speed_mm_s: float = 2.0
136
151
 
137
152
  # ── 力矩 / 指令上限 ────────────────────────────────────────────────
138
153
  max_lead_mm: float = 4.0 # 行进段领先上限 mm(≈ kp × 上限)
@@ -247,6 +262,15 @@ class MotionConfig:
247
262
  monotonic_fn: Callable[[], float] = field(
248
263
  default=time.monotonic, repr=False, compare=False)
249
264
 
265
+ def __post_init__(self) -> None:
266
+ """拒绝会静默失效的交接速度门槛。"""
267
+ if (not math.isfinite(self.stall_speed_mm_s)
268
+ or self.stall_speed_mm_s < 0.0):
269
+ raise ValueError(
270
+ "MotionConfig.stall_speed_mm_s 必须是非负有限数:"
271
+ f"{self.stall_speed_mm_s!r}。负值会让窗口平均速度永远高于"
272
+ "门槛,接近段对任何速度都不判真停。")
273
+
250
274
 
251
275
  # ═══════════════════════════════════════════════════════════════════════════
252
276
  # 结果类型
@@ -822,7 +846,9 @@ class GripperActions:
822
846
  它才一路走到底。
823
847
 
824
848
  **交接只在「到位或顶上东西」时发生**(``reached or stalled``)。这两条
825
- 在真机上是同一件事的两面:夹爪都停着。这不是保守,是唯一的正确条件 ——
849
+ 在真机上是同一件事的两面:夹爪都停着。带设定力的接近段里,「顶上」还要
850
+ 过一条真停条件:窗口平均速度低于 :attr:`MotionConfig.stall_speed_mm_s`
851
+ —— 慢速蠕动不算接触(见该字段)。这不是保守,是唯一的正确条件 ——
826
852
  保力段是纯力矩源,帧里没有位置项也没有速度项,把它接到一个**还在自由
827
853
  行程里**的夹爪上,位置环一撤它就只有加速这一条路(2026-10-13 实测:
828
854
  0.82 rad/s → 5.12 rad/s,312 mm/s,且到 ``hold_s`` 用完仍在加速)。
@@ -863,6 +889,9 @@ class GripperActions:
863
889
  的力矩预算(:func:`force_approach_terms`)整段变成 NaN,NaN 的
864
890
  ``hold_s`` 会让保力段一帧不保就返回 —— 偏偏报「成功」。
865
891
  一直保力请用 ``hold_s=0``,不是 ``inf``。
892
+ CommError: 接近段或进入保力段前要状态帧失败。保力**中途**的状态帧
893
+ 失败不抛出:撤力后返回 ``ok=False``(``cycles=0``),避免把最后
894
+ 那档力矩留在总线上。
866
895
  """
867
896
  cfg = self.config
868
897
  force = cfg.force_n if force_n is None else force_n
@@ -946,7 +975,25 @@ class GripperActions:
946
975
  if req is not None:
947
976
  return self._grasp_ends_with_release(req, move, force, cycles=0)
948
977
 
949
- hold = self._hold_force(force, hold_s, progress=progress)
978
+ try:
979
+ hold = self._hold_force(force, hold_s, progress=progress)
980
+ except CommError as exc:
981
+ # 保力段每片都要刷新状态;总线在这期间断了。最后那档力矩不能
982
+ # 留在总线上,调用方也不该以为保力正常结束 —— 撤力后按失败返回。
983
+ log.warning("保力中断:%s —— 撤力并返回 ok=False", exc)
984
+ try:
985
+ self._release(move.state.position_rad)
986
+ except LiteGripError as rel_exc:
987
+ log.warning("保力中断后的撤力也失败:%s", rel_exc)
988
+ return GraspResult(
989
+ ok=False,
990
+ reached=move.reached,
991
+ stalled=move.stalled,
992
+ state=move.state,
993
+ target_rad=move.target_rad,
994
+ force_n=force,
995
+ cycles=0,
996
+ )
950
997
  if hold.release_requested:
951
998
  req = self._take_release_request()
952
999
  if req is None: # 兜底:请求不该凭空消失
@@ -1343,7 +1390,11 @@ class GripperActions:
1343
1390
  # 是一次位置运动,方向来自标定,未标定时拒绝。
1344
1391
  if not req.abort:
1345
1392
  _check_calibrated(gcfg)
1346
- st = g.get_state()
1393
+ # 急停不要求新状态:零增益帧里 q 不产生任何力,缓存位置就够。反过来,
1394
+ # 要求先答一帧会把撤力拖到重试之后,电机不答时甚至一帧都发不出去 ——
1395
+ # 总线还通、电机不说话,正是急停最需要撤力的工况。
1396
+ st = (g.get_state(wait=False) if req.abort
1397
+ else self._fresh_state())
1347
1398
  pos = st.position_rad
1348
1399
 
1349
1400
  if req.abort:
@@ -1464,6 +1515,40 @@ class GripperActions:
1464
1515
  self._emit(pos, 0.0, 0.0, kp=0.0, kd=0.0)
1465
1516
  return frames
1466
1517
 
1518
+ def _fresh_state(self) -> GripperState:
1519
+ """Read a status snapshot that a frame actually answered, or refuse.
1520
+
1521
+ A DM motor answers control frames; when nothing is being sent it says
1522
+ nothing, and ``get_state(wait=True)`` returns the cache after ~50 ms.
1523
+ Planning a ramp from that cache is how a jaw that was moved while the
1524
+ bus was idle made the first frame demand the whole error: on 2026-11-18
1525
+ the cache said 78 mm, the jaws were at 26 mm, and ``open()`` left at
1526
+ 23 rad/s out of a 20 mm/s move.
1527
+
1528
+ ``refresh_status()`` (0xCC) asks an idle motor to speak. A cached
1529
+ snapshot — even one younger than :data:`STALE_AFTER_S` — is not enough
1530
+ to plan motion from: at 20 mm/s, half a second of silence is 10 mm of
1531
+ unknown. Retry the request a few times and raise :class:`CommError` if
1532
+ no frame answered.
1533
+
1534
+ Raises:
1535
+ CommError: the 0xCC request could not be sent, or the motor did not
1536
+ answer it with a status frame.
1537
+ """
1538
+ sent_ok = False
1539
+ last: Optional[GripperState] = None
1540
+ for _ in range(3):
1541
+ sent_ok = self._g.refresh_status() or sent_ok
1542
+ last = self._g.get_state() # waits up to 50 ms for a frame
1543
+ if last.fresh:
1544
+ return last
1545
+ age = ("无" if last is None or last.data_age_s is None
1546
+ else "%.1f s" % last.data_age_s)
1547
+ raise CommError(
1548
+ "状态帧请求%s,电机没有回应(缓存 age=%s)—— 拒绝从缓存规划运动;"
1549
+ "检查 CAN 链路和电机供电。"
1550
+ % ("" if sent_ok else "发不出去", age))
1551
+
1467
1552
  def _move_to_limit(
1468
1553
  self,
1469
1554
  toward: str,
@@ -1552,7 +1637,7 @@ class GripperActions:
1552
1637
  target, limit, _margin_rad, _travel = limit_target(
1553
1638
  gcfg, toward, cfg.margin)
1554
1639
 
1555
- before = g.get_state()
1640
+ before = self._fresh_state()
1556
1641
  dist_rad = target - before.position_rad
1557
1642
  dist_mm = abs(dist_rad) * gcfg.rad_to_mm
1558
1643
  sign = 1.0 if dist_rad >= 0 else -1.0
@@ -1592,11 +1677,15 @@ class GripperActions:
1592
1677
  win_s = win * sample_every * interval
1593
1678
  win_expect_rad = speed_rad_s * win_s
1594
1679
  win_thresh_rad = max(cfg.stall_delta, cfg.stall_ratio * win_expect_rad)
1680
+ # 带设定力接近段的“真停”下限:窗口平均速度低于它才算停住。
1681
+ stall_speed_rad_s = cfg.stall_speed_mm_s / gcfg.rad_to_mm
1595
1682
  # 帧数上界。不带力的移动按排程走,排程跑完就是它的终止条件之一;带设定
1596
1683
  # 力的接近段不行 —— 领先被预算压小(见 force_approach_terms),夹爪追不
1597
1684
  # 追得上排程由摩擦和读数延迟定,``ramp_steps`` 到了它可能还差几十毫米。
1598
1685
  # 所以这一段的帧数只是兜底,上界取「按仍然算进展的最慢速度走完全程要几
1599
- # 帧」:比这更慢时堵转判据必然已经在 win_s 内触发,这个上界到不了。
1686
+ # 帧」。比这根速度还慢、但窗口平均又高于 stall_speed_mm_s 的蠕动会走到
1687
+ # 这个上界,按「既没到位也没堵转」拒夹;只有低于 stall_speed_mm_s 的
1688
+ # 才算真停、才允许交接。
1600
1689
  ceiling = total_steps
1601
1690
  if force_n is not None:
1602
1691
  floor_rad_s = win_thresh_rad / win_s if win_s > 0.0 else 0.0
@@ -1737,9 +1826,16 @@ class GripperActions:
1737
1826
  # 夹爪到了那里就该顶着不动 —— 那里的「不动」正是我们要的堵转。而且
1738
1827
  # 越位量(5% 行程)往往短于一个采样窗口,只在斜坡段判会永远判不到,
1739
1828
  # 动作得白跑完保压段。
1829
+ # 带设定力的接近段:窗口位移小还不够 —— 实际速度被预算/摩擦压到
1830
+ # 指令的 20% 以下是常态,那不是停住。再看一眼窗口平均速度,低于
1831
+ # stall_speed_mm_s 才算真停,才允许交接给纯力矩保力段。
1832
+ moving = (force_n is not None and win_delta is not None
1833
+ and win_s > 0.0
1834
+ and win_delta / win_s > stall_speed_rad_s)
1740
1835
  if (judge_stall and win_delta is not None
1741
1836
  and (press or in_ramp)
1742
- and win_delta < win_thresh_rad):
1837
+ and win_delta < win_thresh_rad
1838
+ and not moving):
1743
1839
  # 「没动」不等于「顶到工件」:带设定力时,从起点起就没挪过位的
1744
1840
  # 停住也可能是这一段压不出脱离静摩擦的力矩。这一条不能当接触,
1745
1841
  # 否则交接给纯力矩的保力段就是一次带力冲程(见
@@ -1763,8 +1859,9 @@ class GripperActions:
1763
1859
  else:
1764
1860
  stalled = True
1765
1861
  log.info("堵转:最近 %d 次采样(%.2f s)净位移仅 %.5f rad "
1766
- "(< %.5f),停在 %+.5f rad",
1767
- win, win_s, win_delta, win_thresh_rad, pos)
1862
+ "(< %.5f,平均 %.2f mm/s),停在 %+.5f rad",
1863
+ win, win_s, win_delta, win_thresh_rad,
1864
+ win_delta / win_s * gcfg.rad_to_mm, pos)
1768
1865
  break
1769
1866
 
1770
1867
  # 行进段堵转力矩保护(≈7 N):与位置窗口判据**互补** —— 位置窗口对
@@ -1790,7 +1887,7 @@ class GripperActions:
1790
1887
  if protected:
1791
1888
  self._release(pos)
1792
1889
 
1793
- st = g.get_state() # 阻塞等一帧新状态再判到位
1890
+ st = self._fresh_state() # 要一帧答过的读数再判到位
1794
1891
  reached = abs(st.position_rad - target) < cfg.reach_tol
1795
1892
  if press:
1796
1893
  # 顶到限位(堵转 + 停在标定限位附近)才算成功;半路撞工件
@@ -1859,6 +1956,10 @@ class GripperActions:
1859
1956
  :attr:`MotionConfig.hold_interval` 的 0.2 s 片查 —— 请求一到就停保力,
1860
1957
  结果里 ``release_requested=True``,张开/急停由 ``grasp()`` 接手。
1861
1958
 
1959
+ Raises:
1960
+ CommError: 状态帧在保力期间没有得到回应。``grasp()`` 会撤力并把它
1961
+ 转成 ``ok=False``,不把异常抛给调用方。
1962
+
1862
1963
  Returns:
1863
1964
  :class:`HoldResult`。
1864
1965
  """
@@ -1880,7 +1981,7 @@ class GripperActions:
1880
1981
  # 的片里就成了 4 N 一级的台阶,不是爬升。
1881
1982
  step_nm = cfg.force_ramp_n_s * cfg.frame_interval * UnitConversion.N_TO_NM
1882
1983
  cycles = 0
1883
- st = g.get_state()
1984
+ st = self._fresh_state()
1884
1985
  pos = st.position_rad
1885
1986
  # 进入保力:从飞行中的力矩接着爬,交接才连续。飞行力矩已经越过设定值时
1886
1987
  # 直接从设定值起步(那一步是往下走到设定值,不是往上,不构成冲击)。
@@ -1916,7 +2017,7 @@ class GripperActions:
1916
2017
  self._emit(pos, 0.0, tau_cmd, kp=0.0, kd=0.0)
1917
2018
  cycles += 1
1918
2019
 
1919
- st = g.get_state()
2020
+ st = self._fresh_state()
1920
2021
  if st.error_code != 1:
1921
2022
  log.warning("保力中断:状态帧 err=%d"
1922
2023
  "(1=使能中;0=被禁用;其他=故障)", st.error_code)
@@ -19,7 +19,7 @@ import time
19
19
  from typing import Dict, Optional
20
20
 
21
21
  from ..exceptions import CANTimeoutError
22
- from .transport import CanTransport
22
+ from .transport import CanFrame, CanTransport
23
23
  from .protocol import (
24
24
  BROADCAST_ID,
25
25
  ControlMode,
@@ -42,6 +42,11 @@ from .motor import MotorState, MotorParams, MotorType
42
42
 
43
43
  log = logging.getLogger("litegrip.can.controller")
44
44
 
45
+ # ``poll()`` drains the RX queue so the newest state wins. Cap the drain so a
46
+ # bus that never goes quiet cannot hold a caller indefinitely; the remainder
47
+ # stays queued for the next poll.
48
+ MAX_DRAIN_FRAMES = 256
49
+
45
50
 
46
51
  class MotorController:
47
52
  """Manages DM motors over a CAN transport.
@@ -240,17 +245,45 @@ class MotorController:
240
245
 
241
246
  # ── polling ──────────────────────────────────────────────────────────
242
247
 
243
- def poll(self, timeout_s: float = 0.0) -> Optional[MotorState]:
244
- """Poll for one CAN frame. If it's a status frame for a registered
245
- motor, decode it and update that MotorState.
248
+ def poll(self, timeout_s: float = 0.0,
249
+ max_frames: int = MAX_DRAIN_FRAMES) -> Optional[MotorState]:
250
+ """Read every status frame already queued; the newest state wins.
251
+
252
+ The motor answers each control frame with a status frame. A caller
253
+ that sends a burst (a force-hold slice, a ramp step) and polls once per
254
+ burst leaves the rest of the answers in the socket buffer; reading one
255
+ frame then returns an *old* position, and the age is stamped when the
256
+ frame is read — so the stale reading looks fresh. On 2026-11-18 that
257
+ made a position ramp start from the pose the jaws had at the start of a
258
+ hold: the first frame demanded ~0.7 rad of error and the jaws left at
259
+ 23 rad/s out of a 20 mm/s move.
260
+
261
+ ``timeout_s`` only applies to the wait for the first frame; the drain
262
+ after it is non-blocking. Parameter responses and foreign frames are
263
+ discarded without stopping the drain. At most ``max_frames`` frames
264
+ are drained per call (default :data:`MAX_DRAIN_FRAMES`), so a bus that
265
+ never goes quiet cannot hold the caller indefinitely; anything left
266
+ stays queued for the next poll.
246
267
 
247
268
  Returns:
248
- The MotorState that was updated, or None if no relevant frame arrived.
269
+ The MotorState updated by the newest relevant frame, or None if no
270
+ relevant frame arrived.
249
271
  """
250
- frame = self._transport.recv(timeout_s=timeout_s)
251
- if frame is None:
252
- return None
253
-
272
+ updated: Optional[MotorState] = None
273
+ first = True
274
+ for _ in range(max(1, int(max_frames))):
275
+ frame = self._transport.recv(
276
+ timeout_s=timeout_s if first else 0.0)
277
+ first = False
278
+ if frame is None:
279
+ return updated
280
+ motor = self._apply_status_frame(frame)
281
+ if motor is not None:
282
+ updated = motor
283
+ return updated
284
+
285
+ def _apply_status_frame(self, frame: CanFrame) -> Optional[MotorState]:
286
+ """Decode one received frame into its motor state, if it is one."""
254
287
  # Match frame.can_id against registered motors' mst_id
255
288
  motor = self._motors.get(frame.can_id)
256
289
  if motor is None:
@@ -306,14 +339,20 @@ class MotorController:
306
339
  timeout_s: float = 1.0) -> bool:
307
340
  """Poll until at least one new status frame arrives for the given motor.
308
341
 
342
+ ``poll()`` drains every queued frame and reports only the motor updated
343
+ by the newest one. On a bus with several registered motors that is not
344
+ necessarily ``motor`` — another motor's frame may be drained last — so
345
+ the target's ``rx_count``, not the returned motor, decides whether its
346
+ update was seen.
347
+
309
348
  Returns:
310
349
  True if a frame was received, False on timeout.
311
350
  """
312
351
  prev_rx = motor.rx_count
313
352
  deadline = time.monotonic() + timeout_s
314
353
  while time.monotonic() < deadline:
315
- updated = self.poll(timeout_s=0.01)
316
- if updated is motor and motor.rx_count > prev_rx:
354
+ self.poll(timeout_s=0.01)
355
+ if motor.rx_count > prev_rx:
317
356
  return True
318
357
  time.sleep(0.001)
319
358
  return False