litegrip-python 1.2.1__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.
Files changed (48) hide show
  1. {litegrip_python-1.2.1/src/litegrip_python.egg-info → litegrip_python-1.3.0}/PKG-INFO +28 -8
  2. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/README.md +27 -7
  3. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/pyproject.toml +1 -1
  4. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/__init__.py +22 -0
  5. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/gripper.py +55 -12
  6. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/teleop.py +352 -39
  7. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/zenoh_link.py +61 -21
  8. {litegrip_python-1.2.1 → litegrip_python-1.3.0/src/litegrip_python.egg-info}/PKG-INFO +28 -8
  9. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_teleop.py +351 -25
  10. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/LICENSE +0 -0
  11. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/setup.cfg +0 -0
  12. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/actions.py +0 -0
  13. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/calibration_normal.json +0 -0
  14. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/calibration_reverse.json +0 -0
  15. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/can/__init__.py +0 -0
  16. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/can/controller.py +0 -0
  17. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/can/motor.py +0 -0
  18. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/can/protocol.py +0 -0
  19. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/can/transport.py +0 -0
  20. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/constants.py +0 -0
  21. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/exceptions.py +0 -0
  22. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/factory_calibration.json +0 -0
  23. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/models.py +0 -0
  24. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/protocols/__init__.py +0 -0
  25. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/protocols/can_bus.py +0 -0
  26. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/py.typed +0 -0
  27. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip/trajectory.py +0 -0
  28. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip_python.egg-info/SOURCES.txt +0 -0
  29. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip_python.egg-info/dependency_links.txt +0 -0
  30. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip_python.egg-info/requires.txt +0 -0
  31. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/src/litegrip_python.egg-info/top_level.txt +0 -0
  32. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_actions.py +0 -0
  33. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_bus_limits.py +0 -0
  34. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_calibration.py +0 -0
  35. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_can_stream_silence.py +0 -0
  36. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_enable.py +0 -0
  37. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_example_hold_force.py +0 -0
  38. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_example_teleop.py +0 -0
  39. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_examples_bootstrap.py +0 -0
  40. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_iface_mtu.py +0 -0
  41. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_protocol.py +0 -0
  42. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_send_failure_reports_its_cause.py +0 -0
  43. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_state_staleness.py +0 -0
  44. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_trajectory.py +0 -0
  45. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_transport_send.py +0 -0
  46. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_version.py +0 -0
  47. {litegrip_python-1.2.1 → litegrip_python-1.3.0}/tests/test_write_zero.py +0 -0
  48. {litegrip_python-1.2.1 → 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.2.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
@@ -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.
@@ -533,9 +541,9 @@ with LiteGrip("can0") as slave:
533
541
 
534
542
  | Method | What it does |
535
543
  | --- | --- |
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. |
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. |
537
545
  | `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. |
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. |
539
547
 
540
548
  The link is a point-to-point **zenoh** session, an optional dependency:
541
549
 
@@ -565,11 +573,23 @@ python3 examples/teleop.py --mode slave --channel can0 --fake-leader --torque-li
565
573
  - **The leader holds its jaws under gain until the follower reports ready**, so the operator
566
574
  cannot push the target out from under a follower that is still travelling. `ready_timeout_s`
567
575
  (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.
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.
573
593
  - **A follower that loses the leader holds its position, it does not go slack.** After
574
594
  `watchdog_s` (default `0.2`) without a fresh frame, `stale` goes true and the jaws stay put.
575
595
  - **The follower feeds the leader's velocity forward** by differencing successive frames, so it
@@ -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.
@@ -505,9 +513,9 @@ with LiteGrip("can0") as slave:
505
513
 
506
514
  | Method | What it does |
507
515
  | --- | --- |
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. |
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. |
509
517
  | `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. |
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. |
511
519
 
512
520
  The link is a point-to-point **zenoh** session, an optional dependency:
513
521
 
@@ -537,11 +545,23 @@ python3 examples/teleop.py --mode slave --channel can0 --fake-leader --torque-li
537
545
  - **The leader holds its jaws under gain until the follower reports ready**, so the operator
538
546
  cannot push the target out from under a follower that is still travelling. `ready_timeout_s`
539
547
  (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.
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.
545
565
  - **A follower that loses the leader holds its position, it does not go slack.** After
546
566
  `watchdog_s` (default `0.2`) without a fresh frame, `stale` goes true and the jaws stay put.
547
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.2.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",
@@ -47,14 +47,19 @@ from .actions import (
47
47
  _check_calibrated,
48
48
  clamp_to_travel,
49
49
  )
50
- from .teleop import (DEFAULT_ALIGN_SPEED_MM_S, DEFAULT_DQ_MAX, DEFAULT_GRIP_ID,
50
+ from .teleop import (DEFAULT_ALIGN_SPEED_MM_S, DEFAULT_DQ_MAX,
51
+ DEFAULT_FEEDBACK_DAMPING, DEFAULT_FEEDBACK_GAIN_NM_PER_N,
52
+ DEFAULT_FEEDBACK_MAX_TAU_NM, DEFAULT_FEEDBACK_THRESHOLD_N,
53
+ DEFAULT_FEEDBACK_TIMEOUT_S, DEFAULT_GRIP_ID,
51
54
  DEFAULT_GRIP_PORT, DEFAULT_LEAD_CAP_MM,
52
55
  DEFAULT_READY_PERIOD_S, DEFAULT_READY_TIMEOUT_S,
53
- DEFAULT_READY_TOLERANCE_MM, DEFAULT_TORQUE_LIMIT_NM)
56
+ DEFAULT_READY_TOLERANCE_MM, DEFAULT_TORQUE_LIMIT_NM,
57
+ TORQUE_GUARD_HOLD)
54
58
 
55
59
 
56
60
  def _zenoh_transport(role: str, key: str, port: int, host: Optional[str],
57
- ready_key: Optional[str] = None) -> "TeleopTransport":
61
+ ready_key: Optional[str] = None,
62
+ feedback_key: Optional[str] = None) -> "TeleopTransport":
58
63
  """Build a point-to-point zenoh transport, or explain how to get one.
59
64
 
60
65
  zenoh is an optional dependency, so a bare ``import`` failure is turned into
@@ -68,7 +73,7 @@ def _zenoh_transport(role: str, key: str, port: int, host: Optional[str],
68
73
  "the zenoh teleoperation link needs the optional zenoh dependency — "
69
74
  "install it with `pip install litegrip-python[zenoh]`") from e
70
75
  return ZenohTeleopTransport(role, key, port=port, host=host,
71
- ready_key=ready_key)
76
+ ready_key=ready_key, feedback_key=feedback_key)
72
77
 
73
78
 
74
79
  # The calibration the SDK ships for the unit it ships with. This is the
@@ -2193,11 +2198,18 @@ class LiteGrip:
2193
2198
  watchdog_s: float = 0.2,
2194
2199
  dq_max: float = DEFAULT_DQ_MAX,
2195
2200
  torque_limit_nm: float = DEFAULT_TORQUE_LIMIT_NM,
2201
+ torque_guard_action: str = TORQUE_GUARD_HOLD,
2196
2202
  lead_cap_mm: float = DEFAULT_LEAD_CAP_MM, # [遥操对齐块]
2197
2203
  require_ready: bool = True,
2198
2204
  ready_timeout_s: float = DEFAULT_READY_TIMEOUT_S,
2199
2205
  ready_tolerance_mm: float = DEFAULT_READY_TOLERANCE_MM,
2200
2206
  ready_period_s: float = DEFAULT_READY_PERIOD_S,
2207
+ force_feedback: bool = False,
2208
+ feedback_gain_nm_per_n: float = DEFAULT_FEEDBACK_GAIN_NM_PER_N,
2209
+ feedback_threshold_n: float = DEFAULT_FEEDBACK_THRESHOLD_N,
2210
+ feedback_max_tau_nm: float = DEFAULT_FEEDBACK_MAX_TAU_NM,
2211
+ feedback_damping: float = DEFAULT_FEEDBACK_DAMPING,
2212
+ feedback_timeout_s: float = DEFAULT_FEEDBACK_TIMEOUT_S,
2201
2213
  rate_hz: float = 50.0,
2202
2214
  ) -> dict:
2203
2215
  """Start leader/follower teleoperation on this gripper.
@@ -2234,8 +2246,13 @@ class LiteGrip:
2234
2246
  dq_max: Slave only — ceiling in rad/s on the leader velocity fed
2235
2247
  forward to the follower. ``0`` disables the feedforward.
2236
2248
  torque_limit_nm: Slave only — ceiling in Nm on the follower's own
2237
- torque; held over it the follower releases in place. ``0``
2238
- disables the guard. See :class:`~litegrip.GripperTeleop`.
2249
+ torque; held over it the follower acts per
2250
+ ``torque_guard_action``. ``0`` disables the guard. See
2251
+ :class:`~litegrip.GripperTeleop`.
2252
+ torque_guard_action: Slave only — ``"hold"`` (default) keeps
2253
+ pressing with a bounded pure-torque frame so a grasp survives;
2254
+ ``"release"`` drops to zero stiffness and lets go, the previous
2255
+ behaviour.
2239
2256
  lead_cap_mm: Slave only — ceiling in mm on how far the *align*
2240
2257
  command may lead the measured position, which bounds the align
2241
2258
  torque. The follow loop is not capped. ``0`` disables the cap.
@@ -2249,6 +2266,17 @@ class LiteGrip:
2249
2266
  ready_tolerance_mm: Slave only — arrival tolerance for announcing
2250
2267
  ready, in mm of travel.
2251
2268
  ready_period_s: Slave only — how often to republish the ready state.
2269
+ force_feedback: Send the follower's squeeze back and render it on
2270
+ the leader as resistance. Needs the zenoh link (the UDP master
2271
+ is publish-only and silently runs without it).
2272
+ feedback_gain_nm_per_n: Leader torque per newton of follower
2273
+ squeeze above the threshold. ``0`` disables it.
2274
+ feedback_threshold_n: Follower squeeze below which the leader feels
2275
+ nothing.
2276
+ feedback_max_tau_nm: Ceiling on the leader's rendered resistance.
2277
+ feedback_damping: Leader damping applied only during contact.
2278
+ feedback_timeout_s: Age past which the force is ignored and both
2279
+ torque and damping drop to zero.
2252
2280
  rate_hz: Loop rate.
2253
2281
 
2254
2282
  Returns:
@@ -2264,7 +2292,7 @@ class LiteGrip:
2264
2292
  positive.
2265
2293
  """
2266
2294
  from .teleop import (GripperTeleop, TeleopBusyError, check_ready,
2267
- ready_topic, teleop_topic)
2295
+ feedback_topic, ready_topic, teleop_topic)
2268
2296
  from .teleop import UdpTeleopTransport
2269
2297
 
2270
2298
  self._check_connected()
@@ -2286,6 +2314,11 @@ class LiteGrip:
2286
2314
  try:
2287
2315
  key = teleop_topic(grip_id)
2288
2316
  ready_key = ready_topic(grip_id)
2317
+ # Declared on every session, even with the feature off: the leader's
2318
+ # zenoh endpoint is resident and its key set cannot change later.
2319
+ # An unused key costs nothing and a later session that enables
2320
+ # feedback then just works.
2321
+ feedback_key = feedback_topic(grip_id)
2289
2322
  created_transport = None
2290
2323
  if transport is None:
2291
2324
  if link == "zenoh":
@@ -2295,10 +2328,11 @@ class LiteGrip:
2295
2328
  # 已死的端点 ⇒ 此后每一轮都在往死会话里 put。(真机实测:
2296
2329
  # 第一次配对正常,之后每次从端 0 帧。)常驻端点的生命周期
2297
2330
  # 只归 `disconnect()` → `_close_teleop_pub()`。
2298
- transport = self._open_teleop_pub(port, key, ready_key)
2331
+ transport = self._open_teleop_pub(port, key, ready_key,
2332
+ feedback_key)
2299
2333
  else:
2300
2334
  transport = _zenoh_transport("slave", key, port, host,
2301
- ready_key)
2335
+ ready_key, feedback_key)
2302
2336
  created_transport = transport
2303
2337
  elif link == "udp":
2304
2338
  if host is None:
@@ -2324,10 +2358,18 @@ class LiteGrip:
2324
2358
  align_speed_mm_s=align_speed_mm_s, # [遥操对齐块]
2325
2359
  watchdog_s=watchdog_s, dq_max=dq_max,
2326
2360
  torque_limit_nm=torque_limit_nm, lead_cap_mm=lead_cap_mm, # [遥操对齐块]
2361
+ torque_guard_action=torque_guard_action,
2327
2362
  ready_topic=ready_key, require_ready=require_ready,
2328
2363
  ready_timeout_s=ready_timeout_s,
2329
2364
  ready_tolerance_mm=ready_tolerance_mm,
2330
- ready_period_s=ready_period_s)
2365
+ ready_period_s=ready_period_s,
2366
+ force_feedback=force_feedback,
2367
+ feedback_topic=feedback_key,
2368
+ feedback_gain_nm_per_n=feedback_gain_nm_per_n,
2369
+ feedback_threshold_n=feedback_threshold_n,
2370
+ feedback_max_tau_nm=feedback_max_tau_nm,
2371
+ feedback_damping=feedback_damping,
2372
+ feedback_timeout_s=feedback_timeout_s)
2331
2373
  manager.start()
2332
2374
  except BaseException:
2333
2375
  self._release_session("teleop")
@@ -2337,7 +2379,8 @@ class LiteGrip:
2337
2379
  return manager.status()
2338
2380
 
2339
2381
  def _open_teleop_pub(self, port: int, key: str,
2340
- ready_key: Optional[str] = None) -> "TeleopTransport":
2382
+ ready_key: Optional[str] = None,
2383
+ feedback_key: Optional[str] = None) -> "TeleopTransport":
2341
2384
  """Return the leader's resident publisher, building it on first use.
2342
2385
 
2343
2386
  ⚠ **Resident, not per session.** Rebuilding the zenoh listener on every
@@ -2349,7 +2392,7 @@ class LiteGrip:
2349
2392
  """
2350
2393
  if self._teleop_pub is None:
2351
2394
  self._teleop_pub = _zenoh_transport("master", key, port, None,
2352
- ready_key)
2395
+ ready_key, feedback_key)
2353
2396
  return self._teleop_pub
2354
2397
 
2355
2398
  def _close_teleop_pub(self) -> None: