litegrip-python 1.2.0__tar.gz → 1.3.0__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.0/src/litegrip_python.egg-info → litegrip_python-1.3.0}/PKG-INFO +52 -11
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/README.md +51 -10
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/pyproject.toml +1 -1
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/__init__.py +22 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/actions.py +125 -16
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/gripper.py +61 -13
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/teleop.py +352 -39
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/zenoh_link.py +61 -21
- {litegrip_python-1.2.0 → litegrip_python-1.3.0/src/litegrip_python.egg-info}/PKG-INFO +52 -11
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_actions.py +120 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_teleop.py +351 -25
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/LICENSE +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/setup.cfg +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/calibration_normal.json +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/calibration_reverse.json +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/can/__init__.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/can/controller.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/can/motor.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/can/protocol.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/can/transport.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/constants.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/exceptions.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/factory_calibration.json +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/models.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/protocols/__init__.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/protocols/can_bus.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/py.typed +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip/trajectory.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip_python.egg-info/SOURCES.txt +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip_python.egg-info/dependency_links.txt +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip_python.egg-info/requires.txt +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/src/litegrip_python.egg-info/top_level.txt +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_bus_limits.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_calibration.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_can_stream_silence.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_enable.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_example_hold_force.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_example_teleop.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_examples_bootstrap.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_iface_mtu.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_protocol.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_send_failure_reports_its_cause.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_state_staleness.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_trajectory.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_transport_send.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_version.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/tests/test_write_zero.py +0 -0
- {litegrip_python-1.2.0 → litegrip_python-1.3.0}/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.0
|
|
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). `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). 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.
|
|
@@ -387,8 +395,8 @@ What it *means*, and what to check, is per action:
|
|
|
387
395
|
|
|
388
396
|
| Type | Fields | `bool()` is |
|
|
389
397
|
| --- | --- | --- |
|
|
390
|
-
| `MoveResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `limit_rad`, `final_cmd_rad`, `steps`, `protected`, `released` | `ok` |
|
|
391
|
-
| `GraspResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `force_n`, `cycles`, `travel_guard`, `released` | `ok` |
|
|
398
|
+
| `MoveResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `limit_rad`, `final_cmd_rad`, `steps`, `protected`, `released`, `no_bite` | `ok` |
|
|
399
|
+
| `GraspResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `force_n`, `cycles`, `travel_guard`, `released`, `no_bite` | `ok` |
|
|
392
400
|
| `ReleaseResult` | `ok`, `state`, `opened_mm`, `target_rad`, `aborted` | `ok` |
|
|
393
401
|
| `EnableResult` | `ok`, `state`, `tries` | `ok` |
|
|
394
402
|
|
|
@@ -414,6 +422,25 @@ A fourth combination is a failure, and new in this version:
|
|
|
414
422
|
`cycles=0`. Nothing was gripped. If you see this, the closing leg is being starved — a stale
|
|
415
423
|
state read, or friction the mechanism's own budget cannot overcome.
|
|
416
424
|
|
|
425
|
+
A fifth is a refusal:
|
|
426
|
+
|
|
427
|
+
- **`grasp()` with `ok=False, no_bite=True`** means the approach carried its force but never moved
|
|
428
|
+
the jaws: it stopped within `MotionConfig.no_bite_mm` (0.5 mm) of where it started *and* its
|
|
429
|
+
budget (`force_n × 0.1 × press_safety`) was below `MotionConfig.breakaway_nm` (0.2 N·m on this
|
|
430
|
+
unit, so setpoints up to 2.2 N). That is not contact — it is a budget that cannot break static
|
|
431
|
+
friction — and it is exactly the case where handing over the hold would send a jaw with a free
|
|
432
|
+
stroke ahead of it into the torque-only frames and let it accelerate. So the hold is never
|
|
433
|
+
entered, the call releases in place, and `cycles` is 0. `stalled` and `reached` are both `False`
|
|
434
|
+
on this path. The remedy is a setpoint above the breakaway (~2.5 N here), not a longer hold.
|
|
435
|
+
Above the breakaway a zero-displacement stop *is* contact and is held normally: a part already
|
|
436
|
+
against the open jaw, or a re-grasp in place after `release(abort=True)`, still grips.
|
|
437
|
+
|
|
438
|
+
Two edges worth knowing. An approach that starts within `reach_tol` (0.9 mm) of the closed stop
|
|
439
|
+
gets no stall verdict at all — it reports `reached` instead, and the hold has nothing to run
|
|
440
|
+
because the jaws are already on the end stop. And the refusal is about the budget, not the part:
|
|
441
|
+
if a grippy part sits at the start pose *and* the setpoint is below the breakaway, the grasp is
|
|
442
|
+
refused rather than risked.
|
|
443
|
+
|
|
417
444
|
- **`grasp()` ended by a release** returns `released=True`: `ok=True` when the opening completed,
|
|
418
445
|
`ok=False` when it was an E-stop (`release(abort=True)`), which sends no opening move. `reached`
|
|
419
446
|
and `stalled` still describe the closing leg; `state` is the pose after the release.
|
|
@@ -475,6 +502,8 @@ with LiteGrip("can0") as gripper:
|
|
|
475
502
|
| `max_lead_mm` | `4.0` | cap on how far the command may lead the measured position, on moves that carry no force setpoint |
|
|
476
503
|
| `stop_lead_mm` | `0.7` | the same cap on the approach to a stop, so the pressing torque stays bounded |
|
|
477
504
|
| `press_safety` | `0.9` | fraction of the setpoint a force-carrying approach may spend |
|
|
505
|
+
| `no_bite_mm` | `0.5` | a force-carrying approach that stops this close to its start pose is refused, not read as contact (see `grasp()` above) |
|
|
506
|
+
| `breakaway_nm` | `0.2` | measured static-friction breakaway; only a budget below it makes a zero-displacement stop a refusal rather than contact |
|
|
478
507
|
| `reach_tol` | `0.02` | position tolerance for `reached`, radians |
|
|
479
508
|
| `stop_tol` | `0.03` | how close to the calibrated stop the jaw must park to count as pressed home |
|
|
480
509
|
| `settle_s` | `0.3` | time spent holding the target after the ramp |
|
|
@@ -512,9 +541,9 @@ with LiteGrip("can0") as slave:
|
|
|
512
541
|
|
|
513
542
|
| Method | What it does |
|
|
514
543
|
| --- | --- |
|
|
515
|
-
| `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. |
|
|
544
|
+
| `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. |
|
|
516
545
|
| `teleop_stop(timeout=2.0)` → `dict` | Stops the loop and leaves the jaws holding. |
|
|
517
|
-
| `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. |
|
|
546
|
+
| `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. |
|
|
518
547
|
|
|
519
548
|
The link is a point-to-point **zenoh** session, an optional dependency:
|
|
520
549
|
|
|
@@ -544,11 +573,23 @@ python3 examples/teleop.py --mode slave --channel can0 --fake-leader --torque-li
|
|
|
544
573
|
- **The leader holds its jaws under gain until the follower reports ready**, so the operator
|
|
545
574
|
cannot push the target out from under a follower that is still travelling. `ready_timeout_s`
|
|
546
575
|
(default `10.0`) bounds the wait; `require_ready=False` restores the immediate hand-back.
|
|
547
|
-
- **An optional torque guard
|
|
548
|
-
`torque_limit_nm` and
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
the
|
|
576
|
+
- **An optional torque guard stops a follower that is pressing too hard.** Set
|
|
577
|
+
`torque_limit_nm` and, after 60 ms over the limit, the follower stops following and **keeps
|
|
578
|
+
pressing with that torque** (`kp=kd=0`, `tau=±torque_limit_nm`, signed by the torque measured
|
|
579
|
+
at the trip) so a clamped part is not pushed open; it re-arms once the leader has reopened.
|
|
580
|
+
`torque_guard_action="release"` restores the previous behaviour — zero stiffness and damping
|
|
581
|
+
*in place* — which lets the part push the jaws straight open. The default is `0` — **the guard
|
|
582
|
+
is off unless you ask for it**. Pick the value per machine: it depends on how fragile the part
|
|
583
|
+
between the jaws is.
|
|
584
|
+
- **The follower's squeeze can be felt on the leader.** With `force_feedback=True` the follower
|
|
585
|
+
publishes `force_n` on `litearm/v4/{grip_id}/gripper_feedback` (positive means closing,
|
|
586
|
+
normalised for the mount) and the leader renders resistance at
|
|
587
|
+
`min(max(0, force_n - feedback_threshold_n) * feedback_gain_nm_per_n, feedback_max_tau_nm)`,
|
|
588
|
+
directed against closing. Defaults: threshold `2.0` N, gain `0.10` Nm/N, cap `1.0` Nm.
|
|
589
|
+
Damping (`0.1`) applies only while the force is fresh; torque and damping both drop to zero
|
|
590
|
+
after `feedback_timeout_s` (`0.3`). It is off by default and needs the zenoh link — a UDP
|
|
591
|
+
leader is publish-only, so it runs without feedback. The key is additive, so an older peer
|
|
592
|
+
simply runs position-only teleoperation.
|
|
552
593
|
- **A follower that loses the leader holds its position, it does not go slack.** After
|
|
553
594
|
`watchdog_s` (default `0.2`) without a fresh frame, `stale` goes true and the jaws stay put.
|
|
554
595
|
- **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). `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). 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.
|
|
@@ -359,8 +367,8 @@ What it *means*, and what to check, is per action:
|
|
|
359
367
|
|
|
360
368
|
| Type | Fields | `bool()` is |
|
|
361
369
|
| --- | --- | --- |
|
|
362
|
-
| `MoveResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `limit_rad`, `final_cmd_rad`, `steps`, `protected`, `released` | `ok` |
|
|
363
|
-
| `GraspResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `force_n`, `cycles`, `travel_guard`, `released` | `ok` |
|
|
370
|
+
| `MoveResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `limit_rad`, `final_cmd_rad`, `steps`, `protected`, `released`, `no_bite` | `ok` |
|
|
371
|
+
| `GraspResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `force_n`, `cycles`, `travel_guard`, `released`, `no_bite` | `ok` |
|
|
364
372
|
| `ReleaseResult` | `ok`, `state`, `opened_mm`, `target_rad`, `aborted` | `ok` |
|
|
365
373
|
| `EnableResult` | `ok`, `state`, `tries` | `ok` |
|
|
366
374
|
|
|
@@ -386,6 +394,25 @@ A fourth combination is a failure, and new in this version:
|
|
|
386
394
|
`cycles=0`. Nothing was gripped. If you see this, the closing leg is being starved — a stale
|
|
387
395
|
state read, or friction the mechanism's own budget cannot overcome.
|
|
388
396
|
|
|
397
|
+
A fifth is a refusal:
|
|
398
|
+
|
|
399
|
+
- **`grasp()` with `ok=False, no_bite=True`** means the approach carried its force but never moved
|
|
400
|
+
the jaws: it stopped within `MotionConfig.no_bite_mm` (0.5 mm) of where it started *and* its
|
|
401
|
+
budget (`force_n × 0.1 × press_safety`) was below `MotionConfig.breakaway_nm` (0.2 N·m on this
|
|
402
|
+
unit, so setpoints up to 2.2 N). That is not contact — it is a budget that cannot break static
|
|
403
|
+
friction — and it is exactly the case where handing over the hold would send a jaw with a free
|
|
404
|
+
stroke ahead of it into the torque-only frames and let it accelerate. So the hold is never
|
|
405
|
+
entered, the call releases in place, and `cycles` is 0. `stalled` and `reached` are both `False`
|
|
406
|
+
on this path. The remedy is a setpoint above the breakaway (~2.5 N here), not a longer hold.
|
|
407
|
+
Above the breakaway a zero-displacement stop *is* contact and is held normally: a part already
|
|
408
|
+
against the open jaw, or a re-grasp in place after `release(abort=True)`, still grips.
|
|
409
|
+
|
|
410
|
+
Two edges worth knowing. An approach that starts within `reach_tol` (0.9 mm) of the closed stop
|
|
411
|
+
gets no stall verdict at all — it reports `reached` instead, and the hold has nothing to run
|
|
412
|
+
because the jaws are already on the end stop. And the refusal is about the budget, not the part:
|
|
413
|
+
if a grippy part sits at the start pose *and* the setpoint is below the breakaway, the grasp is
|
|
414
|
+
refused rather than risked.
|
|
415
|
+
|
|
389
416
|
- **`grasp()` ended by a release** returns `released=True`: `ok=True` when the opening completed,
|
|
390
417
|
`ok=False` when it was an E-stop (`release(abort=True)`), which sends no opening move. `reached`
|
|
391
418
|
and `stalled` still describe the closing leg; `state` is the pose after the release.
|
|
@@ -447,6 +474,8 @@ with LiteGrip("can0") as gripper:
|
|
|
447
474
|
| `max_lead_mm` | `4.0` | cap on how far the command may lead the measured position, on moves that carry no force setpoint |
|
|
448
475
|
| `stop_lead_mm` | `0.7` | the same cap on the approach to a stop, so the pressing torque stays bounded |
|
|
449
476
|
| `press_safety` | `0.9` | fraction of the setpoint a force-carrying approach may spend |
|
|
477
|
+
| `no_bite_mm` | `0.5` | a force-carrying approach that stops this close to its start pose is refused, not read as contact (see `grasp()` above) |
|
|
478
|
+
| `breakaway_nm` | `0.2` | measured static-friction breakaway; only a budget below it makes a zero-displacement stop a refusal rather than contact |
|
|
450
479
|
| `reach_tol` | `0.02` | position tolerance for `reached`, radians |
|
|
451
480
|
| `stop_tol` | `0.03` | how close to the calibrated stop the jaw must park to count as pressed home |
|
|
452
481
|
| `settle_s` | `0.3` | time spent holding the target after the ramp |
|
|
@@ -484,9 +513,9 @@ with LiteGrip("can0") as slave:
|
|
|
484
513
|
|
|
485
514
|
| Method | What it does |
|
|
486
515
|
| --- | --- |
|
|
487
|
-
| `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. |
|
|
516
|
+
| `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. |
|
|
488
517
|
| `teleop_stop(timeout=2.0)` → `dict` | Stops the loop and leaves the jaws holding. |
|
|
489
|
-
| `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. |
|
|
518
|
+
| `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. |
|
|
490
519
|
|
|
491
520
|
The link is a point-to-point **zenoh** session, an optional dependency:
|
|
492
521
|
|
|
@@ -516,11 +545,23 @@ python3 examples/teleop.py --mode slave --channel can0 --fake-leader --torque-li
|
|
|
516
545
|
- **The leader holds its jaws under gain until the follower reports ready**, so the operator
|
|
517
546
|
cannot push the target out from under a follower that is still travelling. `ready_timeout_s`
|
|
518
547
|
(default `10.0`) bounds the wait; `require_ready=False` restores the immediate hand-back.
|
|
519
|
-
- **An optional torque guard
|
|
520
|
-
`torque_limit_nm` and
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
the
|
|
548
|
+
- **An optional torque guard stops a follower that is pressing too hard.** Set
|
|
549
|
+
`torque_limit_nm` and, after 60 ms over the limit, the follower stops following and **keeps
|
|
550
|
+
pressing with that torque** (`kp=kd=0`, `tau=±torque_limit_nm`, signed by the torque measured
|
|
551
|
+
at the trip) so a clamped part is not pushed open; it re-arms once the leader has reopened.
|
|
552
|
+
`torque_guard_action="release"` restores the previous behaviour — zero stiffness and damping
|
|
553
|
+
*in place* — which lets the part push the jaws straight open. The default is `0` — **the guard
|
|
554
|
+
is off unless you ask for it**. Pick the value per machine: it depends on how fragile the part
|
|
555
|
+
between the jaws is.
|
|
556
|
+
- **The follower's squeeze can be felt on the leader.** With `force_feedback=True` the follower
|
|
557
|
+
publishes `force_n` on `litearm/v4/{grip_id}/gripper_feedback` (positive means closing,
|
|
558
|
+
normalised for the mount) and the leader renders resistance at
|
|
559
|
+
`min(max(0, force_n - feedback_threshold_n) * feedback_gain_nm_per_n, feedback_max_tau_nm)`,
|
|
560
|
+
directed against closing. Defaults: threshold `2.0` N, gain `0.10` Nm/N, cap `1.0` Nm.
|
|
561
|
+
Damping (`0.1`) applies only while the force is fresh; torque and damping both drop to zero
|
|
562
|
+
after `feedback_timeout_s` (`0.3`). It is off by default and needs the zenoh link — a UDP
|
|
563
|
+
leader is publish-only, so it runs without feedback. The key is additive, so an older peer
|
|
564
|
+
simply runs position-only teleoperation.
|
|
524
565
|
- **A follower that loses the leader holds its position, it does not go slack.** After
|
|
525
566
|
`watchdog_s` (default `0.2`) without a fresh frame, `stale` goes true and the jaws stay put.
|
|
526
567
|
- **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.0"
|
|
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",
|
|
@@ -151,6 +151,37 @@ class MotionConfig:
|
|
|
151
151
|
# 照设定的力往下发。
|
|
152
152
|
press_safety: float = 0.9 # 预算余量:撞上时实测力落在设定值之下
|
|
153
153
|
|
|
154
|
+
# ── 带设定力的接近段「从起点就没动过」的判据 mm ───────────────────
|
|
155
|
+
# 位置窗口判据只能看见「没动」,可「没动」有三种:真顶到工件、顶到限位、
|
|
156
|
+
# 以及**这一段的力矩预算低于静摩擦,压根没能脱离**。第三种最危险:它会被
|
|
157
|
+
# 当成接触,交接给纯力矩的保力段 —— 那一段没有位置项也没有速度项,而保力
|
|
158
|
+
# 的力矩是设定值的 1.0 倍、接近段只有 0.9 倍,多出来的这一成正好越过脱离
|
|
159
|
+
# 力,于是夹爪带着设定力在自由行程里一路加速(2026-10-29 实测:2 N 夹取
|
|
160
|
+
# 的接近段压 0.18 Nm 原地不动,接手的保力段压 0.20 Nm 推了 19 mm)。
|
|
161
|
+
#
|
|
162
|
+
# 所以带设定力的接近段里,位移小于这个值的停住,且预算压不出脱离力(见
|
|
163
|
+
# ``breakaway_nm``)时**不算接触**:报「没能脱离静摩擦」(``MoveResult.no_bite``)、
|
|
164
|
+
# 撤力、不交接。代价是「工件就贴在起点旁边、夹爪还没走开就顶上了」也按这个
|
|
165
|
+
# 处理 —— 那一次夹取会报失败,而反过来放行会把一次误判变成一次带力冲程,
|
|
166
|
+
# 两边代价不对称,所以选失败。
|
|
167
|
+
#
|
|
168
|
+
# 0.5 mm 是台架闭合侧粘滑死区(约 0.0103 rad ≈ 0.76 mm)的下面:比死区更短
|
|
169
|
+
# 的「顶住」读数本来就分辨不出来,真工件也做不到停在这么窄的缝里。
|
|
170
|
+
no_bite_mm: float = 0.5
|
|
171
|
+
|
|
172
|
+
# ── 脱离力:判断「没动」是哪一种的力矩门槛 ────────────────────────
|
|
173
|
+
# 上面那条判据只在**这一段的预算本来就压不出脱离力**时才成立。预算远高于
|
|
174
|
+
# 脱离力时,夹爪没动几乎只可能是顶上了东西 —— 那正是「夹住了」,该交接,
|
|
175
|
+
# 保力段照着设定值压,不会跑。所以判据再收紧一层:只有预算
|
|
176
|
+
# (``force_n × 0.1 × press_safety``) 低于这个值,零位移才判 ``no_bite``;
|
|
177
|
+
# 否则照旧 ``stalled``。少了这一层,20 N 夹一个已经贴在张开侧的工件、或者
|
|
178
|
+
# ``release(abort=True)`` 之后原地重夹(那一次松开不发张开指令),都会被拒。
|
|
179
|
+
#
|
|
180
|
+
# 0.2 Nm 就是这台机器上实测的脱离力(2026-10-29:接近段 0.18 Nm 原地不动,
|
|
181
|
+
# 保力段 0.20 Nm 推走 19 mm,落在 1.8–2.0 N 之间)。换成设定值:≤ 2.2 N 的
|
|
182
|
+
# 夹取预算不到它,零位移判拒夹;≥ 2.5 N 的预算在它之上,零位移判顶住东西。
|
|
183
|
+
breakaway_nm: float = 0.2
|
|
184
|
+
|
|
154
185
|
# ── 行进段堵转保护(≈7 N) ────────────────────────────────────────
|
|
155
186
|
# 普通移动(``press=True`` 的 open/close)行进段的领先上限是 max_lead_mm,
|
|
156
187
|
# 一旦夹爪在半路被硬挡,``kp × 领先上限`` ≈ 7.6 N·m 会一直压着;而位置
|
|
@@ -276,6 +307,11 @@ class MoveResult:
|
|
|
276
307
|
# 只有 ``grasp()`` 的带力接近段会检查它:那一段走的不是用户要的终点,而是
|
|
277
308
|
# 夹取的第一步,松开请求意味着「别夹了」。``grasp()`` 据此改走张开。
|
|
278
309
|
release_requested: bool = False
|
|
310
|
+
# 带设定力的接近段**从起点就没动过**:停住时离起始位置还不到
|
|
311
|
+
# :attr:`MotionConfig.no_bite_mm`。这不是接触 —— 也可能是力矩预算低于静
|
|
312
|
+
# 摩擦、夹爪压根没能脱离(判据和代价见 ``MotionConfig.no_bite_mm``)。置位
|
|
313
|
+
# 时 ``stalled`` 为 False,``grasp()`` 不交接、直接撤力返回。
|
|
314
|
+
no_bite: bool = False
|
|
279
315
|
|
|
280
316
|
def __bool__(self) -> bool:
|
|
281
317
|
return self.ok
|
|
@@ -302,6 +338,11 @@ class GraspResult:
|
|
|
302
338
|
# 请求后先完成松开(张开到 ``max(当前, 夹取点) + 余量``),再返回。与
|
|
303
339
|
# ``travel_guard`` 的区别是这不是故障 —— 松开是用户要的正常收尾。
|
|
304
340
|
released: bool = False
|
|
341
|
+
# 接近段从起点就没能推动夹爪:位移小于 ``MotionConfig.no_bite_mm``,设定值
|
|
342
|
+
# 的 0.9 倍力矩压不出脱离静摩擦需要的力。这一条**不交接**,保力段一帧都不
|
|
343
|
+
# 发 —— 交过去它会在自由行程里一路加速(见 ``MotionConfig.no_bite_mm``)。
|
|
344
|
+
# 置位时 ``stalled`` / ``reached`` 都是 False,``cycles`` 为 0。
|
|
345
|
+
no_bite: bool = False
|
|
305
346
|
|
|
306
347
|
def __bool__(self) -> bool:
|
|
307
348
|
return self.ok
|
|
@@ -790,6 +831,14 @@ class GripperActions:
|
|
|
790
831
|
排程由摩擦和读数延迟定。两条都没成立时**如实报 ``ok=False``** 并撤力
|
|
791
832
|
返回(``reached`` / ``stalled`` 都是 ``False``,``cycles=0``),不放跑。
|
|
792
833
|
|
|
834
|
+
还有一条不算交接:**从起点就没动过**。带设定力的接近段如果停住时离它
|
|
835
|
+
自己的起点不到 :attr:`MotionConfig.no_bite_mm`(0.5 mm),而且这一段的
|
|
836
|
+
预算(``force_n × 0.1 × press_safety``)低于
|
|
837
|
+
:attr:`MotionConfig.breakaway_nm`(0.2 Nm,实测脱离力),那它不是顶到
|
|
838
|
+
工件,而是压根没脱离静摩擦 —— 交过去的话保力段 1.0 倍的力矩正好越过
|
|
839
|
+
脱离力,夹爪会在自由行程里带着设定力一路走。这一条报 ``no_bite=True``、
|
|
840
|
+
``cycles=0``、撤力返回,一帧保力都不发(见 :attr:`MotionConfig.no_bite_mm`)。
|
|
841
|
+
|
|
793
842
|
保力段是纯力矩源,没有位置指令可夹,所以它有自己的一条护栏
|
|
794
843
|
(:attr:`MotionConfig.hold_runaway_rad`):越出闭合侧标定限位太多就撤力
|
|
795
844
|
返回,结果里 ``ok=False`` / ``travel_guard=True``。正常夹取不会触发。
|
|
@@ -804,8 +853,9 @@ class GripperActions:
|
|
|
804
853
|
Returns:
|
|
805
854
|
:class:`GraspResult`。夹住工件时 ``stalled=True`` 且
|
|
806
855
|
``reached=False``(压不到空载目标位置是正常的)。闭合段结束时夹爪
|
|
807
|
-
既没到位也没堵转时 ``ok=False``、``cycles=0`` ——
|
|
808
|
-
|
|
856
|
+
既没到位也没堵转时 ``ok=False``、``cycles=0`` —— 见上。接近段没能
|
|
857
|
+
脱离静摩擦时 ``ok=False``、``no_bite=True``、``cycles=0``。被松开
|
|
858
|
+
结束时 ``released=True``:正常松开 ``ok=True``,急停 ``ok=False``。
|
|
809
859
|
|
|
810
860
|
Raises:
|
|
811
861
|
CommandError: ``force_n`` / ``hold_s`` 不是有限数。两条都不是
|
|
@@ -854,6 +904,21 @@ class GripperActions:
|
|
|
854
904
|
if req is not None:
|
|
855
905
|
return self._grasp_ends_with_release(req, move, force, cycles=0)
|
|
856
906
|
|
|
907
|
+
if move.no_bite:
|
|
908
|
+
# 接近段从起点就没动过:可能是工件就在那里,也可能是设定值的
|
|
909
|
+
# 0.9 倍力矩压不出脱离静摩擦需要的力。两者在电机看来一模一样,
|
|
910
|
+
# 而接手的是纯力矩的保力段(没有位置、没有限速,力矩还比接近段
|
|
911
|
+
# 高一成)—— 猜错的代价是一次带力冲程,猜对(拒夹)的代价只是
|
|
912
|
+
# 一次报失败。所以宁可报失败,也不交接。
|
|
913
|
+
self._release(move.state.position_rad)
|
|
914
|
+
log.warning(
|
|
915
|
+
"夹取未交接:接近段从起点就没能推动夹爪(设定 %.1f N,预算 "
|
|
916
|
+
"%.3f Nm,停在 %.1f mm,目标是闭合端)。保力段是纯力矩源,"
|
|
917
|
+
"交过去会在自由行程里一路加速 —— 撤力返回,不下发保力。",
|
|
918
|
+
force, force * UnitConversion.N_TO_NM * cfg.press_safety,
|
|
919
|
+
move.state.position_mm)
|
|
920
|
+
return self._refused_handover(move, force, no_bite=True)
|
|
921
|
+
|
|
857
922
|
if not (move.reached or move.stalled):
|
|
858
923
|
# 既没到位也没顶上东西 —— 夹爪还在自由行程里,而位置环是此刻
|
|
859
924
|
# 唯一拦着它的东西(kp × 领先 + kd × 速度误差)。保力段的帧里
|
|
@@ -865,16 +930,7 @@ class GripperActions:
|
|
|
865
930
|
"%+.5f rad,目标 %+.5f rad)—— 它还在自由行程里,而保"
|
|
866
931
|
"力段没有位置项也没有速度项,交过去会一路加速。撤力返回。",
|
|
867
932
|
move.state.position_rad, move.target_rad)
|
|
868
|
-
return
|
|
869
|
-
ok=False,
|
|
870
|
-
reached=move.reached,
|
|
871
|
-
stalled=move.stalled,
|
|
872
|
-
state=move.state,
|
|
873
|
-
target_rad=move.target_rad,
|
|
874
|
-
force_n=force,
|
|
875
|
-
cycles=0,
|
|
876
|
-
travel_guard=False,
|
|
877
|
-
)
|
|
933
|
+
return self._refused_handover(move, force)
|
|
878
934
|
|
|
879
935
|
# 交接点:带力接近段的终点(夹爪「声明」抓住的位置),不是随后被
|
|
880
936
|
# 20 N 压实后停下的位置。松开的基准取它,见 _do_release。
|
|
@@ -915,6 +971,31 @@ class GripperActions:
|
|
|
915
971
|
self._grip_rad = None
|
|
916
972
|
self._hold_done.set()
|
|
917
973
|
|
|
974
|
+
@staticmethod
|
|
975
|
+
def _refused_handover(
|
|
976
|
+
move: MoveResult,
|
|
977
|
+
force: float,
|
|
978
|
+
*,
|
|
979
|
+
no_bite: bool = False,
|
|
980
|
+
) -> GraspResult:
|
|
981
|
+
"""交接被拒时的 :class:`GraspResult`:一帧保力都没发。
|
|
982
|
+
|
|
983
|
+
两条拒绝路径 —— 接近段从起点就没动过(``no_bite``),和闭合段结束时
|
|
984
|
+
既没到位也没堵转 —— 结果形状完全一样,只有 ``no_bite`` 不同。放在一处
|
|
985
|
+
构造,免得将来改了字段只改到一条(见 ``grasp()`` 里的两处调用)。
|
|
986
|
+
"""
|
|
987
|
+
return GraspResult(
|
|
988
|
+
ok=False,
|
|
989
|
+
reached=move.reached,
|
|
990
|
+
stalled=move.stalled,
|
|
991
|
+
state=move.state,
|
|
992
|
+
target_rad=move.target_rad,
|
|
993
|
+
force_n=force,
|
|
994
|
+
cycles=0,
|
|
995
|
+
travel_guard=False,
|
|
996
|
+
no_bite=no_bite,
|
|
997
|
+
)
|
|
998
|
+
|
|
918
999
|
def _grasp_ends_with_release(
|
|
919
1000
|
self,
|
|
920
1001
|
req: _ReleaseRequest,
|
|
@@ -1529,6 +1610,11 @@ class GripperActions:
|
|
|
1529
1610
|
# 整段斜坡都是「不动」。`home()` 紧跟在 `close()` 之后(两个都瞄着闭合
|
|
1530
1611
|
# 端,只剩一点点齿隙)就是这个形状。压紧路径不受影响:那里目标在限位
|
|
1531
1612
|
# 外侧,「到了还不动」正是要判的堵转。
|
|
1613
|
+
# 带设定力的接近段里,这一条还留了个小口子:起点落在 ``reach_tol``
|
|
1614
|
+
# (0.02 rad ≈ 0.9 mm)以内时不判堵转,于是 ``no_bite`` 也设不上 ——
|
|
1615
|
+
# 但那时 ``reached`` 为真、夹爪已经在闭合端 0.9 mm 之内,保力段前面
|
|
1616
|
+
# 没有自由行程可跑,交过去最多把最后那点缝隙压到限位上。所以这条口子
|
|
1617
|
+
# 不补,README 说的是「从起点就没动过」不是「任何情况下都不交接」。
|
|
1532
1618
|
judge_stall = press or dist_mm > cfg.reach_tol * gcfg.rad_to_mm
|
|
1533
1619
|
|
|
1534
1620
|
# 两档领先上限:行进段用 max_lead_mm 破静摩擦,贴近限位后收窄到
|
|
@@ -1558,6 +1644,7 @@ class GripperActions:
|
|
|
1558
1644
|
|
|
1559
1645
|
hist = [before.position_rad]
|
|
1560
1646
|
stalled = False
|
|
1647
|
+
no_bite = False # 带力接近段从起点就没动过(见上)
|
|
1561
1648
|
protected = False
|
|
1562
1649
|
release_requested = False # 松开请求叫停了带力接近段
|
|
1563
1650
|
over_torque = 0 # 连续过阈的采样点数
|
|
@@ -1653,10 +1740,31 @@ class GripperActions:
|
|
|
1653
1740
|
if (judge_stall and win_delta is not None
|
|
1654
1741
|
and (press or in_ramp)
|
|
1655
1742
|
and win_delta < win_thresh_rad):
|
|
1656
|
-
|
|
1657
|
-
|
|
1658
|
-
|
|
1659
|
-
|
|
1743
|
+
# 「没动」不等于「顶到工件」:带设定力时,从起点起就没挪过位的
|
|
1744
|
+
# 停住也可能是这一段压不出脱离静摩擦的力矩。这一条不能当接触,
|
|
1745
|
+
# 否则交接给纯力矩的保力段就是一次带力冲程(见
|
|
1746
|
+
# ``MotionConfig.no_bite_mm``)。但只有预算本来就在脱离力之下时
|
|
1747
|
+
# 才这么判 —— 预算远高于脱离力还没动,那是真顶上了东西
|
|
1748
|
+
# (见 ``MotionConfig.breakaway_nm``)。
|
|
1749
|
+
if (force_n is not None
|
|
1750
|
+
and force_n * UnitConversion.N_TO_NM * cfg.press_safety
|
|
1751
|
+
< cfg.breakaway_nm
|
|
1752
|
+
and abs(pos - before.position_rad)
|
|
1753
|
+
< cfg.no_bite_mm / gcfg.rad_to_mm):
|
|
1754
|
+
no_bite = True
|
|
1755
|
+
log.warning(
|
|
1756
|
+
"接近段没能脱离静摩擦:预算 %.3f Nm 下,夹爪从 %+.5f rad "
|
|
1757
|
+
"起只挪了 %.2f mm 就停住(目标 %+.5f rad,还差 %.1f mm)。"
|
|
1758
|
+
"「没动」也可能是力矩不够,不是顶到工件 —— 不交接、撤力。",
|
|
1759
|
+
force_n * UnitConversion.N_TO_NM * cfg.press_safety,
|
|
1760
|
+
before.position_rad,
|
|
1761
|
+
abs(pos - before.position_rad) * gcfg.rad_to_mm,
|
|
1762
|
+
target, abs(pos - target) * gcfg.rad_to_mm)
|
|
1763
|
+
else:
|
|
1764
|
+
stalled = True
|
|
1765
|
+
log.info("堵转:最近 %d 次采样(%.2f s)净位移仅 %.5f rad "
|
|
1766
|
+
"(< %.5f),停在 %+.5f rad",
|
|
1767
|
+
win, win_s, win_delta, win_thresh_rad, pos)
|
|
1660
1768
|
break
|
|
1661
1769
|
|
|
1662
1770
|
# 行进段堵转力矩保护(≈7 N):与位置窗口判据**互补** —— 位置窗口对
|
|
@@ -1703,6 +1811,7 @@ class GripperActions:
|
|
|
1703
1811
|
steps=last_i,
|
|
1704
1812
|
protected=protected,
|
|
1705
1813
|
release_requested=release_requested,
|
|
1814
|
+
no_bite=no_bite,
|
|
1706
1815
|
)
|
|
1707
1816
|
|
|
1708
1817
|
def _hold_force(
|