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.
- {litegrip_python-1.2.1/src/litegrip_python.egg-info → litegrip_python-1.3.1}/PKG-INFO +33 -10
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/README.md +32 -9
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/pyproject.toml +1 -1
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/__init__.py +22 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/actions.py +112 -11
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/can/controller.py +50 -11
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/gripper.py +55 -12
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/teleop.py +352 -39
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/zenoh_link.py +61 -21
- {litegrip_python-1.2.1 → litegrip_python-1.3.1/src/litegrip_python.egg-info}/PKG-INFO +33 -10
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip_python.egg-info/SOURCES.txt +1 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_actions.py +149 -5
- litegrip_python-1.3.1/tests/test_can_poll_drain.py +151 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_teleop.py +351 -25
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/LICENSE +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/setup.cfg +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/calibration_normal.json +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/calibration_reverse.json +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/can/__init__.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/can/motor.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/can/protocol.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/can/transport.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/constants.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/exceptions.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/factory_calibration.json +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/models.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/protocols/__init__.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/protocols/can_bus.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/py.typed +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip/trajectory.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip_python.egg-info/dependency_links.txt +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip_python.egg-info/requires.txt +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/src/litegrip_python.egg-info/top_level.txt +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_bus_limits.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_calibration.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_can_stream_silence.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_enable.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_example_hold_force.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_example_teleop.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_examples_bootstrap.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_iface_mtu.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_protocol.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_send_failure_reports_its_cause.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_state_staleness.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_trajectory.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_transport_send.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_version.py +0 -0
- {litegrip_python-1.2.1 → litegrip_python-1.3.1}/tests/test_write_zero.py +0 -0
- {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.
|
|
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.
|
|
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
|
|
569
|
-
`torque_limit_nm` and
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
the
|
|
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.
|
|
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
|
|
541
|
-
`torque_limit_nm` and
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
the
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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 =
|
|
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
|
-
#
|
|
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,
|
|
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 =
|
|
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 =
|
|
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 =
|
|
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
|
|
244
|
-
|
|
245
|
-
|
|
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
|
|
269
|
+
The MotorState updated by the newest relevant frame, or None if no
|
|
270
|
+
relevant frame arrived.
|
|
249
271
|
"""
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
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
|
-
|
|
316
|
-
if
|
|
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
|