litegrip-python 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

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/__init__.py CHANGED
@@ -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",
litegrip/actions.py CHANGED
@@ -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
- 时 ``released=True``:正常松开 ``ok=True``,急停 ``ok=False``。
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 GraspResult(
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
- stalled = True
1657
- log.info("堵转:最近 %d 次采样(%.2f s)净位移仅 %.5f rad "
1658
- "(< %.5f),停在 %+.5f rad",
1659
- win, win_s, win_delta, win_thresh_rad, pos)
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(
litegrip/gripper.py CHANGED
@@ -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
@@ -1393,7 +1398,12 @@ class LiteGrip:
1393
1398
  it closed onto an object, which is the expected outcome.
1394
1399
  ``released=True`` means the grasp ended because a release was
1395
1400
  requested: ``ok=True`` for a normal release, ``ok=False`` for
1396
- an abort.
1401
+ an abort. ``no_bite=True`` (with ``ok=False``, ``cycles=0``)
1402
+ means the approach never moved the jaws and its torque budget
1403
+ was below the breakaway: the hold was **not** entered, because
1404
+ handing a jaw with a free stroke ahead of it to the torque-only
1405
+ hold would power it across the gap. See
1406
+ ``MotionConfig.no_bite_mm`` and ``.breakaway_nm``.
1397
1407
  """
1398
1408
  self._check_connected()
1399
1409
  return self._actions.grasp(force_n, hold_s, progress=progress)
@@ -2188,11 +2198,18 @@ class LiteGrip:
2188
2198
  watchdog_s: float = 0.2,
2189
2199
  dq_max: float = DEFAULT_DQ_MAX,
2190
2200
  torque_limit_nm: float = DEFAULT_TORQUE_LIMIT_NM,
2201
+ torque_guard_action: str = TORQUE_GUARD_HOLD,
2191
2202
  lead_cap_mm: float = DEFAULT_LEAD_CAP_MM, # [遥操对齐块]
2192
2203
  require_ready: bool = True,
2193
2204
  ready_timeout_s: float = DEFAULT_READY_TIMEOUT_S,
2194
2205
  ready_tolerance_mm: float = DEFAULT_READY_TOLERANCE_MM,
2195
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,
2196
2213
  rate_hz: float = 50.0,
2197
2214
  ) -> dict:
2198
2215
  """Start leader/follower teleoperation on this gripper.
@@ -2229,8 +2246,13 @@ class LiteGrip:
2229
2246
  dq_max: Slave only — ceiling in rad/s on the leader velocity fed
2230
2247
  forward to the follower. ``0`` disables the feedforward.
2231
2248
  torque_limit_nm: Slave only — ceiling in Nm on the follower's own
2232
- torque; held over it the follower releases in place. ``0``
2233
- 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.
2234
2256
  lead_cap_mm: Slave only — ceiling in mm on how far the *align*
2235
2257
  command may lead the measured position, which bounds the align
2236
2258
  torque. The follow loop is not capped. ``0`` disables the cap.
@@ -2244,6 +2266,17 @@ class LiteGrip:
2244
2266
  ready_tolerance_mm: Slave only — arrival tolerance for announcing
2245
2267
  ready, in mm of travel.
2246
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.
2247
2280
  rate_hz: Loop rate.
2248
2281
 
2249
2282
  Returns:
@@ -2259,7 +2292,7 @@ class LiteGrip:
2259
2292
  positive.
2260
2293
  """
2261
2294
  from .teleop import (GripperTeleop, TeleopBusyError, check_ready,
2262
- ready_topic, teleop_topic)
2295
+ feedback_topic, ready_topic, teleop_topic)
2263
2296
  from .teleop import UdpTeleopTransport
2264
2297
 
2265
2298
  self._check_connected()
@@ -2281,6 +2314,11 @@ class LiteGrip:
2281
2314
  try:
2282
2315
  key = teleop_topic(grip_id)
2283
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)
2284
2322
  created_transport = None
2285
2323
  if transport is None:
2286
2324
  if link == "zenoh":
@@ -2290,10 +2328,11 @@ class LiteGrip:
2290
2328
  # 已死的端点 ⇒ 此后每一轮都在往死会话里 put。(真机实测:
2291
2329
  # 第一次配对正常,之后每次从端 0 帧。)常驻端点的生命周期
2292
2330
  # 只归 `disconnect()` → `_close_teleop_pub()`。
2293
- transport = self._open_teleop_pub(port, key, ready_key)
2331
+ transport = self._open_teleop_pub(port, key, ready_key,
2332
+ feedback_key)
2294
2333
  else:
2295
2334
  transport = _zenoh_transport("slave", key, port, host,
2296
- ready_key)
2335
+ ready_key, feedback_key)
2297
2336
  created_transport = transport
2298
2337
  elif link == "udp":
2299
2338
  if host is None:
@@ -2319,10 +2358,18 @@ class LiteGrip:
2319
2358
  align_speed_mm_s=align_speed_mm_s, # [遥操对齐块]
2320
2359
  watchdog_s=watchdog_s, dq_max=dq_max,
2321
2360
  torque_limit_nm=torque_limit_nm, lead_cap_mm=lead_cap_mm, # [遥操对齐块]
2361
+ torque_guard_action=torque_guard_action,
2322
2362
  ready_topic=ready_key, require_ready=require_ready,
2323
2363
  ready_timeout_s=ready_timeout_s,
2324
2364
  ready_tolerance_mm=ready_tolerance_mm,
2325
- 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)
2326
2373
  manager.start()
2327
2374
  except BaseException:
2328
2375
  self._release_session("teleop")
@@ -2332,7 +2379,8 @@ class LiteGrip:
2332
2379
  return manager.status()
2333
2380
 
2334
2381
  def _open_teleop_pub(self, port: int, key: str,
2335
- ready_key: Optional[str] = None) -> "TeleopTransport":
2382
+ ready_key: Optional[str] = None,
2383
+ feedback_key: Optional[str] = None) -> "TeleopTransport":
2336
2384
  """Return the leader's resident publisher, building it on first use.
2337
2385
 
2338
2386
  ⚠ **Resident, not per session.** Rebuilding the zenoh listener on every
@@ -2344,7 +2392,7 @@ class LiteGrip:
2344
2392
  """
2345
2393
  if self._teleop_pub is None:
2346
2394
  self._teleop_pub = _zenoh_transport("master", key, port, None,
2347
- ready_key)
2395
+ ready_key, feedback_key)
2348
2396
  return self._teleop_pub
2349
2397
 
2350
2398
  def _close_teleop_pub(self) -> None: