litegrip-python 1.1.3__py3-none-any.whl → 1.2.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 +2 -0
- litegrip/actions.py +435 -37
- litegrip/gripper.py +123 -51
- litegrip/models.py +11 -9
- litegrip/teleop.py +1 -1
- {litegrip_python-1.1.3.dist-info → litegrip_python-1.2.0.dist-info}/METADATA +89 -17
- {litegrip_python-1.1.3.dist-info → litegrip_python-1.2.0.dist-info}/RECORD +10 -10
- {litegrip_python-1.1.3.dist-info → litegrip_python-1.2.0.dist-info}/WHEEL +0 -0
- {litegrip_python-1.1.3.dist-info → litegrip_python-1.2.0.dist-info}/licenses/LICENSE +0 -0
- {litegrip_python-1.1.3.dist-info → litegrip_python-1.2.0.dist-info}/top_level.txt +0 -0
litegrip/__init__.py
CHANGED
|
@@ -75,6 +75,7 @@ from .actions import (
|
|
|
75
75
|
MoveProgress,
|
|
76
76
|
MoveResult,
|
|
77
77
|
GraspResult,
|
|
78
|
+
ReleaseResult,
|
|
78
79
|
HoldResult,
|
|
79
80
|
EnableResult,
|
|
80
81
|
WriteZeroResult,
|
|
@@ -210,6 +211,7 @@ __all__ = [
|
|
|
210
211
|
"MoveProgress",
|
|
211
212
|
"MoveResult",
|
|
212
213
|
"GraspResult",
|
|
214
|
+
"ReleaseResult",
|
|
213
215
|
"HoldResult",
|
|
214
216
|
"EnableResult",
|
|
215
217
|
"WriteZeroResult",
|
litegrip/actions.py
CHANGED
|
@@ -64,6 +64,7 @@ from __future__ import annotations
|
|
|
64
64
|
|
|
65
65
|
import logging
|
|
66
66
|
import math
|
|
67
|
+
import threading
|
|
67
68
|
import time
|
|
68
69
|
from dataclasses import dataclass, field
|
|
69
70
|
from typing import TYPE_CHECKING, Callable, Optional, Tuple
|
|
@@ -108,6 +109,10 @@ class MotionConfig:
|
|
|
108
109
|
sample_interval: float = 0.05 # 20 Hz 堵转采样间隔 s
|
|
109
110
|
settle_s: float = 0.3 # 斜坡后原地保目标时长 s(不判堵转)
|
|
110
111
|
reach_tol: float = 0.02 # 到位容差 rad(闭合侧死区 0.0103)
|
|
112
|
+
# release() 在夹取进行中等待「夹取线程做完松开」的超时 s。10 s 足够覆盖
|
|
113
|
+
# 默认 50 mm/s 下 10 mm 的张开斜坡(0.2 s)加上交接前保力片的收尾;等不到
|
|
114
|
+
# 就返回 ok=False,不让调用方(往往是 UI 线程或急停按钮)无限期卡住。
|
|
115
|
+
release_wait_s: float = 10.0
|
|
111
116
|
|
|
112
117
|
# ── open/close 顶限位 ──────────────────────────────────────────────
|
|
113
118
|
# 这几个数只影响**目标的排程**和接近段的领先:真正下发的指令被
|
|
@@ -267,6 +272,10 @@ class MoveResult:
|
|
|
267
272
|
# 指令停在 ``实测位置 + 领先上限`` 上,留着它驱动器会按约 6.6 N·m 一直压着。
|
|
268
273
|
# 只报「撤了力」,不改变 ``ok``。
|
|
269
274
|
released: bool = False
|
|
275
|
+
# 这次移动被松开请求(``release()`` / ``request_release()``)从半路叫停。
|
|
276
|
+
# 只有 ``grasp()`` 的带力接近段会检查它:那一段走的不是用户要的终点,而是
|
|
277
|
+
# 夹取的第一步,松开请求意味着「别夹了」。``grasp()`` 据此改走张开。
|
|
278
|
+
release_requested: bool = False
|
|
270
279
|
|
|
271
280
|
def __bool__(self) -> bool:
|
|
272
281
|
return self.ok
|
|
@@ -289,6 +298,31 @@ class GraspResult:
|
|
|
289
298
|
# 这一路守的是保力段的越位。正常夹取不会置位:夹着工件时夹爪停在工件上,
|
|
290
299
|
# 空载时顶到真限位就停。置位说明闭合侧没有东西拦着它。
|
|
291
300
|
travel_guard: bool = False
|
|
301
|
+
# 这次夹取是被 ``release()`` / ``request_release()`` 结束的:夹取线程收到
|
|
302
|
+
# 请求后先完成松开(张开到 ``max(当前, 夹取点) + 余量``),再返回。与
|
|
303
|
+
# ``travel_guard`` 的区别是这不是故障 —— 松开是用户要的正常收尾。
|
|
304
|
+
released: bool = False
|
|
305
|
+
|
|
306
|
+
def __bool__(self) -> bool:
|
|
307
|
+
return self.ok
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
@dataclass
|
|
311
|
+
class ReleaseResult:
|
|
312
|
+
"""一次松开(:meth:`GripperActions.release`)的结果。
|
|
313
|
+
|
|
314
|
+
``opened_mm`` 是这一次松开**指令目标**的开口量(mm,从闭合零点算起,
|
|
315
|
+
与 :attr:`GripperState.position_mm` 同一个口径),不是「又张开了多少」;
|
|
316
|
+
夹爪实际停在哪看 ``state.position_mm``。``aborted=True`` 表示这是一次急停
|
|
317
|
+
(``abort=True``):只撤力、不发张开运动,此时 ``opened_mm`` 是撤力那一刻
|
|
318
|
+
的开口量,``target_rad`` 是撤力那一刻的位置。
|
|
319
|
+
"""
|
|
320
|
+
|
|
321
|
+
ok: bool # 松开是否完成(急停与超时为 False)
|
|
322
|
+
state: GripperState # 松开结束时的状态
|
|
323
|
+
opened_mm: float # 目标开口量 mm(急停:撤力时的开口量)
|
|
324
|
+
target_rad: float # 张开斜坡的目标位置 rad
|
|
325
|
+
aborted: bool = False # 这是急停(只撤力,不张开)
|
|
292
326
|
|
|
293
327
|
def __bool__(self) -> bool:
|
|
294
328
|
return self.ok
|
|
@@ -305,11 +339,22 @@ class HoldResult:
|
|
|
305
339
|
cycles: int # 保力片数
|
|
306
340
|
state: Optional[GripperState] # 最后一次状态
|
|
307
341
|
guarded: bool = False # 是否被位置护栏中止(详见 GraspResult)
|
|
342
|
+
# 保力被松开请求叫停(详见 GraspResult.released)。请求没被消费,仍留在
|
|
343
|
+
# ``_release_req`` 里,由 ``grasp()`` 取走并执行张开/急停。
|
|
344
|
+
release_requested: bool = False
|
|
308
345
|
|
|
309
346
|
def __bool__(self) -> bool:
|
|
310
347
|
return self.ok
|
|
311
348
|
|
|
312
349
|
|
|
350
|
+
@dataclass(frozen=True)
|
|
351
|
+
class _ReleaseRequest:
|
|
352
|
+
"""一条待执行的松开请求:从夹取线程之外递进来的,只由它自己消费。"""
|
|
353
|
+
|
|
354
|
+
clearance_mm: float
|
|
355
|
+
abort: bool
|
|
356
|
+
|
|
357
|
+
|
|
313
358
|
@dataclass
|
|
314
359
|
class EnableResult:
|
|
315
360
|
"""enable 的结果。"""
|
|
@@ -346,15 +391,13 @@ class WriteZeroResult:
|
|
|
346
391
|
def _check_calibrated(config: GripperConfig) -> None:
|
|
347
392
|
"""确认配置真的带上了标定,并有一段非零行程。
|
|
348
393
|
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
配置里所有方向都是猜的,必须拦住。
|
|
394
|
+
两种限位顺序都合法,所以这里**不**看谁大谁小 —— 只看有没有标定过的实数。
|
|
395
|
+
没标定的配置里所有方向都是猜的,必须拦住。
|
|
352
396
|
"""
|
|
353
397
|
if not config.calibrated:
|
|
354
398
|
raise CommandError(
|
|
355
399
|
"配置尚未标定:pos_closed_rad / pos_open_rad 还是占位默认值,"
|
|
356
|
-
"无法判断方向。先 load_calibration()
|
|
357
|
-
"CALIB_TEMPLATES[\"reverse\"])或跑一次 zero()。")
|
|
400
|
+
"无法判断方向。先 load_calibration() 或跑一次 zero()。")
|
|
358
401
|
if abs(config.pos_closed_rad - config.pos_open_rad) <= 1e-6:
|
|
359
402
|
raise CommandError(
|
|
360
403
|
f"行程为零:pos_closed_rad={config.pos_closed_rad} 与 "
|
|
@@ -651,6 +694,31 @@ class GripperActions:
|
|
|
651
694
|
self._g = gripper
|
|
652
695
|
self.config = config if config is not None else MotionConfig()
|
|
653
696
|
|
|
697
|
+
# 松开的跨线程协调。``release()`` 可以从任意线程调用,而帧只能由夹取
|
|
698
|
+
# 线程发(同一根 CAN 上两个线程各发各的,斜坡的领先上限就不再成立)。
|
|
699
|
+
# 所以跨线程时调用方只**记下请求**,夹取线程在每一帧之前查一次;松开
|
|
700
|
+
# 完成后夹取线程记下结果、置 ``_hold_done``,调用方据此返回。
|
|
701
|
+
#
|
|
702
|
+
# 这把锁只保护下面这几个字段,**不碰 CAN**:``request_release()`` 在
|
|
703
|
+
# 调用方线程里拿它,夹取线程每 5 ms 拿一次 —— 两边都只做几次赋值。
|
|
704
|
+
# 千万别把 ``_io_lock`` 也套进来(那是帧的锁,见 LiteGrip)。
|
|
705
|
+
self._release_lock = threading.Lock()
|
|
706
|
+
# 「没有夹取在跑」时为 set。release() 用它判断有没有夹取可等,也用它
|
|
707
|
+
# 等夹取线程把松开做完。用 Event 而不是 Condition:等待方只关心「完没
|
|
708
|
+
# 完」,不关心完成了几次。
|
|
709
|
+
self._hold_done = threading.Event()
|
|
710
|
+
self._hold_done.set()
|
|
711
|
+
# 进行中的那条请求(``_ReleaseRequest``)与它的结果。请求只由夹取线程
|
|
712
|
+
# 消费;结果在 ``_hold_done`` 置位之前写入,等待方醒来一定看得到。
|
|
713
|
+
self._release_req: Optional[_ReleaseRequest] = None
|
|
714
|
+
self._release_result: Optional[ReleaseResult] = None
|
|
715
|
+
# 交接点(带力接近段结束、保力接手处)的实测位置。松开的基准是**夹取
|
|
716
|
+
# 声明的位置**,不是夹爪被力压实后停下的位置:真机上 20 N 会把它往里
|
|
717
|
+
# 多推几毫米,从「停下处」再张 10 mm 就少松了那几毫米 —— 这正是
|
|
718
|
+
# console(litegrip-studio)的 BackOff 要修的那件事。``None`` = 还没
|
|
719
|
+
# 交接(例如接近途中就要求松开)。
|
|
720
|
+
self._grip_rad: Optional[float] = None
|
|
721
|
+
|
|
654
722
|
# ═══════════════════════════════════════════════════════════════════
|
|
655
723
|
# 六个接口
|
|
656
724
|
# ═══════════════════════════════════════════════════════════════════
|
|
@@ -729,13 +797,15 @@ class GripperActions:
|
|
|
729
797
|
Args:
|
|
730
798
|
force_n: 夹持力 N,``None`` = 用 :attr:`MotionConfig.force_n`。
|
|
731
799
|
按 SDK 近似换算 1 N = 0.1 Nm。
|
|
732
|
-
hold_s: 保力时长 s。``0`` =
|
|
800
|
+
hold_s: 保力时长 s。``0`` = 一直保到出错、被护栏中止、收到
|
|
801
|
+
``release()`` / ``request_release()`` 的松开请求,或 Ctrl+C。
|
|
733
802
|
progress: 进度回调。
|
|
734
803
|
|
|
735
804
|
Returns:
|
|
736
805
|
:class:`GraspResult`。夹住工件时 ``stalled=True`` 且
|
|
737
806
|
``reached=False``(压不到空载目标位置是正常的)。闭合段结束时夹爪
|
|
738
|
-
既没到位也没堵转时 ``ok=False``、``cycles=0`` ——
|
|
807
|
+
既没到位也没堵转时 ``ok=False``、``cycles=0`` —— 见上。被松开结束
|
|
808
|
+
时 ``released=True``:正常松开 ``ok=True``,急停 ``ok=False``。
|
|
739
809
|
|
|
740
810
|
Raises:
|
|
741
811
|
CommandError: ``force_n`` / ``hold_s`` 不是有限数。两条都不是
|
|
@@ -758,48 +828,238 @@ class GripperActions:
|
|
|
758
828
|
gcfg = self._g.config
|
|
759
829
|
_check_calibrated(gcfg)
|
|
760
830
|
|
|
761
|
-
#
|
|
762
|
-
#
|
|
763
|
-
#
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
#
|
|
772
|
-
#
|
|
773
|
-
#
|
|
774
|
-
#
|
|
775
|
-
#
|
|
776
|
-
self.
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
831
|
+
# 新的一次夹取从干净的状态开始:上一次夹取遗留的松开请求**必须**清掉,
|
|
832
|
+
# 否则一个为上一次夹取按下的「松开」会把它自己还没开始的夹取杀掉。
|
|
833
|
+
# 结果也清掉,免得这一次的 release() 拿到上一次的返回值。
|
|
834
|
+
with self._release_lock:
|
|
835
|
+
self._release_req = None
|
|
836
|
+
self._release_result = None
|
|
837
|
+
self._grip_rad = None
|
|
838
|
+
self._hold_done.clear()
|
|
839
|
+
try:
|
|
840
|
+
# 闭合段瞄的是**闭合侧标定限位本身**,不是 limit_target 在限位内侧
|
|
841
|
+
# 留的那 5% 行程。留白那几毫米是自由行程:夹爪到了点上、前面什么
|
|
842
|
+
# 都没有,保力段随后只能用纯力矩把它推过去 —— 那是真机上「末端飞
|
|
843
|
+
# 快一下」的一半来源。瞄限位时夹爪是顶在东西上或停在限位上的,交
|
|
844
|
+
# 接从静止开始。``target_rad`` 会强制 press=False,ok 与 reached 的
|
|
845
|
+
# 判据都不动。
|
|
846
|
+
move = self._move_to_limit(
|
|
847
|
+
"close", cfg.grasp_speed_mm_s,
|
|
848
|
+
target_rad=gcfg.pos_closed_rad,
|
|
849
|
+
force_n=force, progress=progress)
|
|
850
|
+
|
|
851
|
+
# 接近途中就要求松开:还没有交接点,基准退化成当前位置。请求在
|
|
852
|
+
# ``_move_to_limit`` 里被看到(带力段每帧查一次),这里取走并执行。
|
|
853
|
+
req = self._take_release_request()
|
|
854
|
+
if req is not None:
|
|
855
|
+
return self._grasp_ends_with_release(req, move, force, cycles=0)
|
|
856
|
+
|
|
857
|
+
if not (move.reached or move.stalled):
|
|
858
|
+
# 既没到位也没顶上东西 —— 夹爪还在自由行程里,而位置环是此刻
|
|
859
|
+
# 唯一拦着它的东西(kp × 领先 + kd × 速度误差)。保力段的帧里
|
|
860
|
+
# 这两项全没有,交过去就是把设定力矩直接接到一个还在走的夹爪
|
|
861
|
+
# 上:真机实测速度从被速度环限住的 0.82 rad/s 跳到 5.12 rad/s,
|
|
862
|
+
# 且到 hold_s 用完还在加速。宁可如实报失败,也不交。
|
|
863
|
+
self._release(move.state.position_rad)
|
|
864
|
+
log.warning("夹取未交接:闭合段结束时夹爪既未到位也未堵转(停在 "
|
|
865
|
+
"%+.5f rad,目标 %+.5f rad)—— 它还在自由行程里,而保"
|
|
866
|
+
"力段没有位置项也没有速度项,交过去会一路加速。撤力返回。",
|
|
867
|
+
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
|
+
)
|
|
878
|
+
|
|
879
|
+
# 交接点:带力接近段的终点(夹爪「声明」抓住的位置),不是随后被
|
|
880
|
+
# 20 N 压实后停下的位置。松开的基准取它,见 _do_release。
|
|
881
|
+
# 「记交接点」和「查请求」必须在同一把锁里:否则请求可能正好落在
|
|
882
|
+
# 两者之间 —— 请求已经递进来,而这一段却没看见它。
|
|
883
|
+
with self._release_lock:
|
|
884
|
+
if self._release_req is None:
|
|
885
|
+
self._grip_rad = move.state.position_rad
|
|
886
|
+
req = None
|
|
887
|
+
else:
|
|
888
|
+
req = self._release_req
|
|
889
|
+
self._release_req = None
|
|
890
|
+
if req is not None:
|
|
891
|
+
return self._grasp_ends_with_release(req, move, force, cycles=0)
|
|
892
|
+
|
|
893
|
+
hold = self._hold_force(force, hold_s, progress=progress)
|
|
894
|
+
if hold.release_requested:
|
|
895
|
+
req = self._take_release_request()
|
|
896
|
+
if req is None: # 兜底:请求不该凭空消失
|
|
897
|
+
req = _ReleaseRequest(10.0, False)
|
|
898
|
+
return self._grasp_ends_with_release(
|
|
899
|
+
req, move, force, cycles=hold.cycles)
|
|
781
900
|
return GraspResult(
|
|
782
|
-
ok=
|
|
901
|
+
ok=hold.ok,
|
|
783
902
|
reached=move.reached,
|
|
784
903
|
stalled=move.stalled,
|
|
785
|
-
state=move.state,
|
|
904
|
+
state=hold.state if hold.state is not None else move.state,
|
|
786
905
|
target_rad=move.target_rad,
|
|
787
906
|
force_n=force,
|
|
788
|
-
cycles=
|
|
789
|
-
travel_guard=
|
|
907
|
+
cycles=hold.cycles,
|
|
908
|
+
travel_guard=hold.guarded,
|
|
790
909
|
)
|
|
791
|
-
|
|
910
|
+
finally:
|
|
911
|
+
# 一次夹取结束 = 没有夹取可松开了。两件事在同一把锁里做,等待方
|
|
912
|
+
# 醒来时请求一定已经清掉、结果一定已经写好。
|
|
913
|
+
with self._release_lock:
|
|
914
|
+
self._release_req = None
|
|
915
|
+
self._grip_rad = None
|
|
916
|
+
self._hold_done.set()
|
|
917
|
+
|
|
918
|
+
def _grasp_ends_with_release(
|
|
919
|
+
self,
|
|
920
|
+
req: _ReleaseRequest,
|
|
921
|
+
move: MoveResult,
|
|
922
|
+
force: float,
|
|
923
|
+
*,
|
|
924
|
+
cycles: int,
|
|
925
|
+
) -> GraspResult:
|
|
926
|
+
"""夹取线程执行一条松开请求,并把结果折成 :class:`GraspResult`。
|
|
927
|
+
|
|
928
|
+
正常松开 ``ok=True``;急停 ``ok=False``。两者都是 ``released=True`` ——
|
|
929
|
+
夹取是被松开结束的,不是故障。结果先记进 ``_release_result`` 再让
|
|
930
|
+
``grasp()`` 的 ``finally`` 置 ``_hold_done``,等待中的 ``release()``
|
|
931
|
+
因此一定拿得到它。
|
|
932
|
+
"""
|
|
933
|
+
result = self._do_release(req)
|
|
934
|
+
with self._release_lock:
|
|
935
|
+
self._release_result = result
|
|
792
936
|
return GraspResult(
|
|
793
|
-
ok=
|
|
937
|
+
ok=result.ok,
|
|
794
938
|
reached=move.reached,
|
|
795
939
|
stalled=move.stalled,
|
|
796
|
-
state=
|
|
940
|
+
state=result.state,
|
|
797
941
|
target_rad=move.target_rad,
|
|
798
942
|
force_n=force,
|
|
799
|
-
cycles=
|
|
800
|
-
travel_guard=
|
|
943
|
+
cycles=cycles,
|
|
944
|
+
travel_guard=False,
|
|
945
|
+
released=True,
|
|
801
946
|
)
|
|
802
947
|
|
|
948
|
+
def release(
|
|
949
|
+
self,
|
|
950
|
+
clearance_mm: float = 10.0,
|
|
951
|
+
*,
|
|
952
|
+
abort: bool = False,
|
|
953
|
+
timeout_s: Optional[float] = None,
|
|
954
|
+
) -> ReleaseResult:
|
|
955
|
+
"""松开:结束进行中的 ``grasp()`` 保力并张开夹爪。
|
|
956
|
+
|
|
957
|
+
可以从**任意线程**调用,包括 ``grasp(hold_s=0)`` 还堵在另一个线程里的
|
|
958
|
+
时候。这条限制不是礼貌,是正确性:帧只能由夹取线程发 —— 两个线程各自
|
|
959
|
+
往同一根 CAN 上发斜坡,各自的领先上限就都不成立了;而保力段是纯力矩
|
|
960
|
+
帧,中间插进来的位置帧会把它交接时的连续爬升打断。所以:
|
|
961
|
+
|
|
962
|
+
- **有夹取在跑**:本方法只记下请求(参数取第一次那条;``abort=True``
|
|
963
|
+
会压过排队中的普通松开),然后等夹取线程做完松开。夹取线程在接近段/保力段的**每一帧之前**查请求,5 ms
|
|
964
|
+
内就能看到;它自己完成张开(或急停)并记下结果,本方法醒来返回它。
|
|
965
|
+
等满 ``timeout_s``(``None`` = :attr:`MotionConfig.release_wait_s`)
|
|
966
|
+
还没等到,返回 ``ok=False`` 并记一条 warning —— 不在这里抢着发帧。
|
|
967
|
+
- **没有夹取在跑**:就在调用方线程里直接做这一次松开。
|
|
968
|
+
|
|
969
|
+
``abort=True`` 是急停:**只撤力、不发张开运动**,尽快返回。``abort``
|
|
970
|
+
与普通松开走同一条等待路径,差别只在夹取线程做什么。
|
|
971
|
+
|
|
972
|
+
连续调用是安全的:同一个夹取里第二次 ``release()`` 不会再多张开一次
|
|
973
|
+
(它等到第一次的结果直接返回);没有夹取时每次都按「当前位置 + 余量」
|
|
974
|
+
张开,本来就不会抛「没有夹取」。
|
|
975
|
+
|
|
976
|
+
张开逻辑与 console 的 BackOff 一致:基准是**交接点**(``grasp()`` 里
|
|
977
|
+
``move.state.position_rad``)而不是力压实后停下的位置,目标是
|
|
978
|
+
``max(当前, 交接点) + clearance_mm``,再夹到标定张开限位;走的是既有的
|
|
979
|
+
有界位置斜坡(:meth:`_move_to_limit`),没有阶跃指令。还没交接就要求
|
|
980
|
+
松开时,基准退化成当前位置。张开速度用
|
|
981
|
+
:attr:`MotionConfig.grasp_speed_mm_s` —— 松开是夹取的收尾动作,与闭合
|
|
982
|
+
段同一速度;``open()`` 的 ``speed_mm_s`` 默认值相同(都是 50 mm/s)。
|
|
983
|
+
|
|
984
|
+
Args:
|
|
985
|
+
clearance_mm: 在基准位置上再张开的余量 mm,必须是非负有限数。
|
|
986
|
+
abort: 急停:只撤力,不张开。
|
|
987
|
+
timeout_s: 等待夹取线程完成的超时 s,``None`` = 配置值。
|
|
988
|
+
|
|
989
|
+
Returns:
|
|
990
|
+
:class:`ReleaseResult`。
|
|
991
|
+
|
|
992
|
+
Raises:
|
|
993
|
+
CommandError: ``clearance_mm`` 不是非负有限数;没有夹取在跑且配置
|
|
994
|
+
尚未标定(方向是猜的,不给它发运动)。
|
|
995
|
+
NotInitializedError: 没有夹取在跑、夹爪未连接或未使能 —— 原样抛出
|
|
996
|
+
底层记下的那一条。
|
|
997
|
+
"""
|
|
998
|
+
if timeout_s is not None and not math.isfinite(timeout_s):
|
|
999
|
+
raise CommandError(
|
|
1000
|
+
f"松开等待超时必须是有限秒数:timeout_s={timeout_s!r}。"
|
|
1001
|
+
"NaN 会让等待的截止时间没有意义。")
|
|
1002
|
+
req = self._check_release_args(clearance_mm, abort)
|
|
1003
|
+
with self._release_lock:
|
|
1004
|
+
active = not self._hold_done.is_set()
|
|
1005
|
+
if active:
|
|
1006
|
+
if self._release_req is None:
|
|
1007
|
+
self._release_req = req
|
|
1008
|
+
elif req.abort and not self._release_req.abort:
|
|
1009
|
+
# 急停压过已经排队的一次普通松开:排队中的请求还没执行,
|
|
1010
|
+
# 换成撤力。反过来不行 —— 已经叫了急停就不要又被一次普通
|
|
1011
|
+
# 松开带回张开运动。
|
|
1012
|
+
self._release_req = req
|
|
1013
|
+
else:
|
|
1014
|
+
# 已经有一条请求在排队:参数取第一条,第二次只是「再催
|
|
1015
|
+
# 一次」。两次同时到达也不会张开两次。
|
|
1016
|
+
req = self._release_req
|
|
1017
|
+
|
|
1018
|
+
if not active:
|
|
1019
|
+
return self._do_release(req)
|
|
1020
|
+
|
|
1021
|
+
wait_s = (self.config.release_wait_s
|
|
1022
|
+
if timeout_s is None else float(timeout_s))
|
|
1023
|
+
if wait_s <= 0.0 or not self._hold_done.wait(wait_s):
|
|
1024
|
+
log.warning("松开等待超时:%.1f s 内夹取线程没有完成松开"
|
|
1025
|
+
"(abort=%s)—— 返回 ok=False,不在这里抢着发帧。",
|
|
1026
|
+
wait_s, req.abort)
|
|
1027
|
+
return self._release_timeout_result(req)
|
|
1028
|
+
|
|
1029
|
+
with self._release_lock:
|
|
1030
|
+
outcome = self._release_result
|
|
1031
|
+
leftover = self._release_req
|
|
1032
|
+
if leftover is not None:
|
|
1033
|
+
self._release_req = None
|
|
1034
|
+
if outcome is not None:
|
|
1035
|
+
return outcome
|
|
1036
|
+
# 夹取在请求落地前就自然结束了(例如 hold_s 刚好到点):此刻已经没有
|
|
1037
|
+
# 夹取可等,就在本线程里把这次松开做掉,而不是把请求吞掉。
|
|
1038
|
+
return self._do_release(leftover if leftover is not None else req)
|
|
1039
|
+
|
|
1040
|
+
def request_release(self, clearance_mm: float = 10.0, *,
|
|
1041
|
+
abort: bool = False) -> bool:
|
|
1042
|
+
"""非阻塞版 :meth:`release`:只记请求,返回「有没有夹取可松开」。
|
|
1043
|
+
|
|
1044
|
+
有夹取在跑时置上请求并返回 ``True``;没有就返回 ``False``。它**从不**
|
|
1045
|
+
碰 CAN,也不获取 ``_io_lock`` —— 给 UI 线程、信号处理、E-stop 回调这类
|
|
1046
|
+
不能等总线的地方用。实际张开发帧由夹取线程在下一帧之前接手。
|
|
1047
|
+
|
|
1048
|
+
重复调用安全:已经有一条请求在排队时,保留第一条的参数;唯一的例外是
|
|
1049
|
+
``abort=True`` 会压过排队中的普通松开(急停优先)。
|
|
1050
|
+
|
|
1051
|
+
Raises:
|
|
1052
|
+
CommandError: ``clearance_mm`` 不是非负有限数(与有没有夹取无关)。
|
|
1053
|
+
"""
|
|
1054
|
+
req = self._check_release_args(clearance_mm, abort)
|
|
1055
|
+
with self._release_lock:
|
|
1056
|
+
if self._hold_done.is_set():
|
|
1057
|
+
return False
|
|
1058
|
+
if (self._release_req is None
|
|
1059
|
+
or (req.abort and not self._release_req.abort)):
|
|
1060
|
+
self._release_req = req
|
|
1061
|
+
return True
|
|
1062
|
+
|
|
803
1063
|
def ramp_to(
|
|
804
1064
|
self,
|
|
805
1065
|
target_rad: float,
|
|
@@ -956,6 +1216,118 @@ class GripperActions:
|
|
|
956
1216
|
# 引擎
|
|
957
1217
|
# ═══════════════════════════════════════════════════════════════════
|
|
958
1218
|
|
|
1219
|
+
def _check_release_args(self, clearance_mm: float,
|
|
1220
|
+
abort: bool) -> _ReleaseRequest:
|
|
1221
|
+
"""校验松开参数并折成请求。NaN / 负数在这里拒绝,不是夹到 0。"""
|
|
1222
|
+
if not math.isfinite(clearance_mm) or clearance_mm < 0.0:
|
|
1223
|
+
raise CommandError(
|
|
1224
|
+
f"松开的余量必须是**非负有限数**:clearance_mm="
|
|
1225
|
+
f"{clearance_mm!r}。负余量是「再夹进去一点」,不是松开;NaN "
|
|
1226
|
+
"进了位置算术会变成 NaN 目标。")
|
|
1227
|
+
return _ReleaseRequest(float(clearance_mm), bool(abort))
|
|
1228
|
+
|
|
1229
|
+
def _release_pending(self) -> bool:
|
|
1230
|
+
"""有没有一条还没被夹取线程消费的松开请求(只碰松开锁)。"""
|
|
1231
|
+
with self._release_lock:
|
|
1232
|
+
return self._release_req is not None
|
|
1233
|
+
|
|
1234
|
+
def _take_release_request(self) -> Optional[_ReleaseRequest]:
|
|
1235
|
+
"""取走并清空待执行的松开请求;没有就返回 ``None``。
|
|
1236
|
+
|
|
1237
|
+
只由夹取线程调用(``_hold_force`` / ``_move_to_limit`` 只查不取)。
|
|
1238
|
+
"""
|
|
1239
|
+
with self._release_lock:
|
|
1240
|
+
req = self._release_req
|
|
1241
|
+
self._release_req = None
|
|
1242
|
+
return req
|
|
1243
|
+
|
|
1244
|
+
def _do_release(self, req: _ReleaseRequest) -> ReleaseResult:
|
|
1245
|
+
"""执行一条松开请求:急停只撤力,普通松开走有界斜坡张开。
|
|
1246
|
+
|
|
1247
|
+
基准与 console(litegrip-studio)的 BackOff 同一条:从**交接点**再张
|
|
1248
|
+
``clearance_mm``,而不是从力压实后停下的位置。真机上设定力会把夹爪往
|
|
1249
|
+
工件里多推几毫米,从停下处再张 10 mm 就少松了那几毫米 —— console 那
|
|
1250
|
+
个按钮要修的正是这件事。``max(当前, 交接点)`` 是因为夹爪也可能被外力
|
|
1251
|
+
(或回弹的工件)推到更外面,那时取更远的那端。还没交接时
|
|
1252
|
+
``_grip_rad is None``,基准就是当前位置。
|
|
1253
|
+
|
|
1254
|
+
目标再经 :func:`clamp_to_travel` 夹到标定行程内 —— 也就是最多张到标定
|
|
1255
|
+
张开限位,不会因为余量大就越过去。运动是既有的有界斜坡
|
|
1256
|
+
(:meth:`_move_to_limit`,``target_rad`` 语义),不是阶跃指令。
|
|
1257
|
+
"""
|
|
1258
|
+
cfg = self.config
|
|
1259
|
+
g = self._g
|
|
1260
|
+
gcfg = g.config
|
|
1261
|
+
# 急停不要求标定:标定坏了、文件没加载,也拦不住一次撤力。普通松开
|
|
1262
|
+
# 是一次位置运动,方向来自标定,未标定时拒绝。
|
|
1263
|
+
if not req.abort:
|
|
1264
|
+
_check_calibrated(gcfg)
|
|
1265
|
+
st = g.get_state()
|
|
1266
|
+
pos = st.position_rad
|
|
1267
|
+
|
|
1268
|
+
if req.abort:
|
|
1269
|
+
# 急停:一帧 ``kp=kd=tau=0`` 就够停下力矩,随后立刻返回。不发张开
|
|
1270
|
+
# 运动 —— 调用方按的是「别动了」,不是「张到某处」。一帧而不是
|
|
1271
|
+
# _release() 的整段:那一段要 0.2 s,急停的每一毫秒都要。
|
|
1272
|
+
self._emit(pos, 0.0, 0.0, kp=0.0, kd=0.0)
|
|
1273
|
+
log.info("急停松开:已撤力(撤力时实测夹持力 %.1f N),不发张开运动",
|
|
1274
|
+
st.force_n)
|
|
1275
|
+
return ReleaseResult(
|
|
1276
|
+
ok=False,
|
|
1277
|
+
state=g.get_state(wait=False),
|
|
1278
|
+
opened_mm=st.position_mm,
|
|
1279
|
+
target_rad=pos,
|
|
1280
|
+
aborted=True,
|
|
1281
|
+
)
|
|
1282
|
+
|
|
1283
|
+
s = gcfg.close_sign
|
|
1284
|
+
current_mm = (gcfg.pos_closed_rad - pos) * s * gcfg.rad_to_mm
|
|
1285
|
+
with self._release_lock:
|
|
1286
|
+
grip_rad = self._grip_rad
|
|
1287
|
+
base_mm = current_mm
|
|
1288
|
+
if grip_rad is not None:
|
|
1289
|
+
grip_mm = (gcfg.pos_closed_rad - grip_rad) * s * gcfg.rad_to_mm
|
|
1290
|
+
base_mm = max(current_mm, grip_mm)
|
|
1291
|
+
if grip_mm < current_mm:
|
|
1292
|
+
log.info("松开:夹爪已被推外 %.1f mm(夹取点 %.1f mm,现在 "
|
|
1293
|
+
"%.1f mm),从更外的位置起算", current_mm - grip_mm,
|
|
1294
|
+
grip_mm, current_mm)
|
|
1295
|
+
target_mm = base_mm + req.clearance_mm
|
|
1296
|
+
target_rad = gcfg.pos_closed_rad - s * target_mm / gcfg.rad_to_mm
|
|
1297
|
+
target_rad = clamp_to_travel(gcfg, target_rad)
|
|
1298
|
+
# 报告用的是夹过之后的目标开口量:被标定张开限位夹住时,实际能张到
|
|
1299
|
+
# 的只有那么多。
|
|
1300
|
+
opened_mm = (gcfg.pos_closed_rad - target_rad) * s * gcfg.rad_to_mm
|
|
1301
|
+
|
|
1302
|
+
log.info("松开:从 %.1f mm 再张开 %.1f mm → 目标 %.1f mm(%.5f rad)",
|
|
1303
|
+
base_mm, req.clearance_mm, opened_mm, target_rad)
|
|
1304
|
+
move = self._move_to_limit("open", cfg.grasp_speed_mm_s,
|
|
1305
|
+
target_rad=target_rad)
|
|
1306
|
+
return ReleaseResult(
|
|
1307
|
+
ok=move.ok,
|
|
1308
|
+
state=move.state,
|
|
1309
|
+
opened_mm=opened_mm,
|
|
1310
|
+
target_rad=move.target_rad,
|
|
1311
|
+
aborted=False,
|
|
1312
|
+
)
|
|
1313
|
+
|
|
1314
|
+
def _release_timeout_result(self, req: _ReleaseRequest) -> ReleaseResult:
|
|
1315
|
+
"""等夹取线程超时后的结果:报 ``ok=False``,状态尽力读一次。
|
|
1316
|
+
|
|
1317
|
+
``wait=False`` 的读数拿的是缓存,不为了这条失败路径去等一帧新状态。
|
|
1318
|
+
"""
|
|
1319
|
+
try:
|
|
1320
|
+
st = self._g.get_state(wait=False)
|
|
1321
|
+
except LiteGripError: # 总线已经报错时也要有结果
|
|
1322
|
+
st = GripperState()
|
|
1323
|
+
return ReleaseResult(
|
|
1324
|
+
ok=False,
|
|
1325
|
+
state=st,
|
|
1326
|
+
opened_mm=st.position_mm,
|
|
1327
|
+
target_rad=st.position_rad,
|
|
1328
|
+
aborted=req.abort,
|
|
1329
|
+
)
|
|
1330
|
+
|
|
959
1331
|
def _emit(self, q: float, dq: float = 0.0, tau: float = 0.0,
|
|
960
1332
|
kp: Optional[float] = None, kd: Optional[float] = None) -> float:
|
|
961
1333
|
"""下发一帧 MIT 并等待一帧的时间。
|
|
@@ -1187,6 +1559,7 @@ class GripperActions:
|
|
|
1187
1559
|
hist = [before.position_rad]
|
|
1188
1560
|
stalled = False
|
|
1189
1561
|
protected = False
|
|
1562
|
+
release_requested = False # 松开请求叫停了带力接近段
|
|
1190
1563
|
over_torque = 0 # 连续过阈的采样点数
|
|
1191
1564
|
prev_sample_pos = before.position_rad
|
|
1192
1565
|
st = before
|
|
@@ -1196,6 +1569,17 @@ class GripperActions:
|
|
|
1196
1569
|
clamped_once = False # 本次移动只记一条封顶 debug 日志
|
|
1197
1570
|
|
|
1198
1571
|
for i in range(1, ceiling + 1):
|
|
1572
|
+
# 松开请求在**每一帧之前**查,不是按采样或按片查:5 ms 一帧,请求
|
|
1573
|
+
# 落下来最多一帧就被看到。只对带设定力的接近段生效 —— 这一段的
|
|
1574
|
+
# 终点是用户要的夹取,松开请求的意思就是「别夹了」,继续走完再撤
|
|
1575
|
+
# 是另一回事;而 open/close/ramp_to 有自己的终点,不该被松开请求
|
|
1576
|
+
# 从半路叫停。
|
|
1577
|
+
if force_n is not None and self._release_pending():
|
|
1578
|
+
release_requested = True
|
|
1579
|
+
log.info("带力接近段中止:收到松开请求,上一条指令停在 %+.5f rad"
|
|
1580
|
+
"(目标 %+.5f);改由 grasp() 执行松开。",
|
|
1581
|
+
last_cmd, target)
|
|
1582
|
+
break
|
|
1199
1583
|
st = g.get_state(wait=False)
|
|
1200
1584
|
pos = st.position_rad
|
|
1201
1585
|
# 排程相位。不带力时按计时切 —— ``ramp_steps`` 就是排程跑完的那一
|
|
@@ -1318,6 +1702,7 @@ class GripperActions:
|
|
|
1318
1702
|
final_cmd_rad=last_cmd,
|
|
1319
1703
|
steps=last_i,
|
|
1320
1704
|
protected=protected,
|
|
1705
|
+
release_requested=release_requested,
|
|
1321
1706
|
)
|
|
1322
1707
|
|
|
1323
1708
|
def _hold_force(
|
|
@@ -1360,7 +1745,10 @@ class GripperActions:
|
|
|
1360
1745
|
每个回读片。配置没标定时不启用 —— 占位限位描述的不是真实行程。经
|
|
1361
1746
|
``grasp()`` 进来时标定一定在:它的闭合段先过 ``_move_to_limit``。
|
|
1362
1747
|
|
|
1363
|
-
``hold_s <= 0``
|
|
1748
|
+
``hold_s <= 0`` 表示不限时长(直到出错、被护栏中止、收到松开请求或
|
|
1749
|
+
Ctrl+C)。松开请求在**每一帧之前**(5 ms)查一次,不按
|
|
1750
|
+
:attr:`MotionConfig.hold_interval` 的 0.2 s 片查 —— 请求一到就停保力,
|
|
1751
|
+
结果里 ``release_requested=True``,张开/急停由 ``grasp()`` 接手。
|
|
1364
1752
|
|
|
1365
1753
|
Returns:
|
|
1366
1754
|
:class:`HoldResult`。
|
|
@@ -1405,6 +1793,16 @@ class GripperActions:
|
|
|
1405
1793
|
# 用上一次读到的位置当 q 下发(kp=0 时 q 不产生任何力,只是给下游
|
|
1406
1794
|
# 一个不越位的指令),每帧把力矩朝设定值推一步,再回读状态查故障
|
|
1407
1795
|
for _ in range(frames_per_slice):
|
|
1796
|
+
# 松开请求在**每一帧之前**查,不是一片查一次:一片 0.2 s,
|
|
1797
|
+
# 按片查就意味着松开按钮最多要等 200 ms 才生效;按帧查是
|
|
1798
|
+
# 一帧(5 ms)。请求不在这里消费,留在 _release_req 里由
|
|
1799
|
+
# grasp() 取走 —— 这一层只负责「停下保力」,张开/急停的语义
|
|
1800
|
+
# 属于 grasp()。
|
|
1801
|
+
if self._release_pending():
|
|
1802
|
+
log.info("保力中止:收到松开请求(已保 %d 片),交给 grasp() "
|
|
1803
|
+
"执行松开", cycles)
|
|
1804
|
+
return HoldResult(ok=False, cycles=cycles, state=st,
|
|
1805
|
+
release_requested=True)
|
|
1408
1806
|
tau_cmd = _toward(tau_cmd, target_nm, step_nm)
|
|
1409
1807
|
self._emit(pos, 0.0, tau_cmd, kp=0.0, kd=0.0)
|
|
1410
1808
|
cycles += 1
|
litegrip/gripper.py
CHANGED
|
@@ -42,6 +42,7 @@ from .actions import (
|
|
|
42
42
|
MotionConfig,
|
|
43
43
|
MoveProgress,
|
|
44
44
|
MoveResult,
|
|
45
|
+
ReleaseResult,
|
|
45
46
|
WriteZeroResult,
|
|
46
47
|
_check_calibrated,
|
|
47
48
|
clamp_to_travel,
|
|
@@ -73,23 +74,21 @@ def _zenoh_transport(role: str, key: str, port: int, host: Optional[str],
|
|
|
73
74
|
# The calibration the SDK ships for the unit it ships with. This is the
|
|
74
75
|
# *standard* value: a no-argument load_calibration() reads it and nothing else.
|
|
75
76
|
# A calibration measured on the buyer's machine is never picked up by accident
|
|
76
|
-
# — name it with ``path
|
|
77
|
+
# — name it with ``path=`` or ``LITEGRIP_CALIB``.
|
|
77
78
|
_FACTORY_CALIB = _os.path.join(_os.path.dirname(__file__), "factory_calibration.json")
|
|
78
79
|
|
|
79
|
-
#
|
|
80
|
-
#
|
|
81
|
-
#
|
|
82
|
-
#
|
|
83
|
-
#
|
|
84
|
-
# the
|
|
85
|
-
#
|
|
86
|
-
# gripper.load_calibration(CALIB_TEMPLATES["reverse"]) # by path
|
|
87
|
-
# gripper.load_template("reverse") # or by name
|
|
80
|
+
# Calibration templates kept for backward compatibility. They are
|
|
81
|
+
# **deprecated**: shipped grippers have one mounting, which the factory
|
|
82
|
+
# calibration already describes, so new code uses a no-argument
|
|
83
|
+
# load_calibration() or an explicit ``path=``. Each template is a pair of
|
|
84
|
+
# nominal limits whose *ordering* still declares a direction (the "normal" one
|
|
85
|
+
# closes at the larger rad value); they are a labelling seed, not a per-unit
|
|
86
|
+
# calibration, so run zero() to measure the real travel.
|
|
88
87
|
#
|
|
89
88
|
# They deliberately carry no `channel`, `can_id`, `mst_id` or gain values: a
|
|
90
89
|
# template declares a *direction*, and adopting a device identity or a tuned
|
|
91
|
-
# kp/kd from it would silently rewrite what the caller set.
|
|
92
|
-
#
|
|
90
|
+
# kp/kd from it would silently rewrite what the caller set. list_templates()
|
|
91
|
+
# is likewise deprecated and kept only so existing callers keep working.
|
|
93
92
|
CALIB_TEMPLATES = {
|
|
94
93
|
"normal": _os.path.join(_os.path.dirname(__file__), "calibration_normal.json"),
|
|
95
94
|
"reverse": _os.path.join(_os.path.dirname(__file__), "calibration_reverse.json"),
|
|
@@ -179,9 +178,11 @@ def default_calib_path(channel: str = DefaultParams.CAN_CHANNEL) -> str:
|
|
|
179
178
|
|
|
180
179
|
|
|
181
180
|
def list_templates() -> List[str]:
|
|
182
|
-
"""The calibration template names, in declaration order
|
|
181
|
+
"""The legacy calibration template names, in declaration order.
|
|
183
182
|
|
|
184
|
-
|
|
183
|
+
**Deprecated.** Kept for backward compatibility; shipped grippers have
|
|
184
|
+
one mounting and the factory calibration already describes it. Returns
|
|
185
|
+
the historical names so existing callers keep working.
|
|
185
186
|
"""
|
|
186
187
|
return list(CALIB_TEMPLATES)
|
|
187
188
|
|
|
@@ -280,13 +281,10 @@ class LiteGrip:
|
|
|
280
281
|
so the gripper goes limp when the object is released. Set ``False``
|
|
281
282
|
to leave the motor enabled after disconnecting.
|
|
282
283
|
mount:
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
needs. ``None`` (default) loads nothing; call
|
|
288
|
-
:meth:`load_calibration` yourself. This *declares* the mount; read
|
|
289
|
-
the resulting direction back from :attr:`GripperConfig.mount`.
|
|
284
|
+
**Deprecated.** Kept for backward compatibility. Shipped grippers
|
|
285
|
+
have one mounting, which the factory calibration already describes;
|
|
286
|
+
leave this ``None`` (the default) and call :meth:`load_calibration`
|
|
287
|
+
yourself.
|
|
290
288
|
|
|
291
289
|
The gripper works as a context manager::
|
|
292
290
|
|
|
@@ -384,12 +382,11 @@ class LiteGrip:
|
|
|
384
382
|
|
|
385
383
|
@property
|
|
386
384
|
def mount(self) -> Optional[str]:
|
|
387
|
-
"""
|
|
385
|
+
"""The legacy mount label, or ``None`` while uncalibrated.
|
|
388
386
|
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
rewrites the travel.
|
|
387
|
+
**Deprecated.** Kept for backward compatibility. Shipped grippers
|
|
388
|
+
have one mounting, so a calibrated unit reports ``"normal"``. Read
|
|
389
|
+
the limits from :attr:`GripperConfig` when you need the travel.
|
|
393
390
|
"""
|
|
394
391
|
return self._config.mount
|
|
395
392
|
|
|
@@ -937,7 +934,7 @@ class LiteGrip:
|
|
|
937
934
|
print(" 夹爪将自动缓慢移动。到达极限时按 Enter 确认。")
|
|
938
935
|
|
|
939
936
|
s = self._config.close_sign
|
|
940
|
-
print(f"
|
|
937
|
+
print(f" 方向:闭合时 rad {'增大' if s > 0 else '减小'}(由当前标定限位推出)")
|
|
941
938
|
print()
|
|
942
939
|
|
|
943
940
|
def _step_to_limit(direction: str, sign: float, label: str) -> float:
|
|
@@ -1118,15 +1115,13 @@ class LiteGrip:
|
|
|
1118
1115
|
|
|
1119
1116
|
Three ways to say which file, and they are mutually exclusive:
|
|
1120
1117
|
|
|
1121
|
-
* ``template
|
|
1122
|
-
(:func:`list_templates`).
|
|
1123
|
-
|
|
1124
|
-
|
|
1125
|
-
request for reverse with normal is the one failure the name exists
|
|
1126
|
-
to prevent.
|
|
1118
|
+
* ``template=...`` — **deprecated**, kept for backward compatibility.
|
|
1119
|
+
A name from :data:`CALIB_TEMPLATES` (:func:`list_templates`).
|
|
1120
|
+
Strict: if that template cannot be read this raises instead of
|
|
1121
|
+
falling back to the factory file.
|
|
1127
1122
|
* ``path=...`` — an explicit file, which may be anywhere (including a
|
|
1128
1123
|
template's path). Falls back to the built-in factory calibration
|
|
1129
|
-
if it cannot be read.
|
|
1124
|
+
if it cannot be read, and may still return True when it does.
|
|
1130
1125
|
* neither — the factory calibration the SDK ships, and nothing else.
|
|
1131
1126
|
A calibration measured on this machine is never picked up by
|
|
1132
1127
|
accident: name it with ``path=``, or point ``LITEGRIP_CALIB`` at it
|
|
@@ -1134,8 +1129,8 @@ class LiteGrip:
|
|
|
1134
1129
|
|
|
1135
1130
|
The factory file declares ``channel: can0``, so a ``can1`` unit gets
|
|
1136
1131
|
nothing from a no-argument load — it fails loudly rather than
|
|
1137
|
-
silently adopting ``can0``'s
|
|
1138
|
-
|
|
1132
|
+
silently adopting ``can0``'s calibration. Give it a calibration
|
|
1133
|
+
with ``path=`` or ``LITEGRIP_CALIB``.
|
|
1139
1134
|
|
|
1140
1135
|
Any file in ``~/.litegrip`` that this load passed over is named in a
|
|
1141
1136
|
warning, with the call that would use it.
|
|
@@ -1143,9 +1138,8 @@ class LiteGrip:
|
|
|
1143
1138
|
Call this after :meth:`connect` but before :meth:`enable`.
|
|
1144
1139
|
|
|
1145
1140
|
The limits in the file decide the direction: whichever of the two is
|
|
1146
|
-
numerically larger is the closed side
|
|
1147
|
-
|
|
1148
|
-
is logged.
|
|
1141
|
+
numerically larger is the closed side, and the direction a file
|
|
1142
|
+
implies is logged.
|
|
1149
1143
|
|
|
1150
1144
|
Args:
|
|
1151
1145
|
path: JSON file path.
|
|
@@ -1209,9 +1203,9 @@ class LiteGrip:
|
|
|
1209
1203
|
if strict:
|
|
1210
1204
|
raise CommandError(
|
|
1211
1205
|
f"标定模板 {template!r} 读不出来({sources[0]})。不作出厂"
|
|
1212
|
-
f"回退 ——
|
|
1206
|
+
f"回退 —— 出厂文件的限位方向未必与所点名的模板一致。")
|
|
1213
1207
|
log.warning("No calibration found (tried: %s). "
|
|
1214
|
-
"Run zero() first, or
|
|
1208
|
+
"Run zero() first, or restore the factory calibration.",
|
|
1215
1209
|
", ".join(sources))
|
|
1216
1210
|
return False
|
|
1217
1211
|
|
|
@@ -1262,16 +1256,19 @@ class LiteGrip:
|
|
|
1262
1256
|
loaded_from,
|
|
1263
1257
|
abs(self._config.pos_open_rad - self._config.pos_closed_rad)
|
|
1264
1258
|
* self._config.rad_to_mm,
|
|
1265
|
-
"
|
|
1259
|
+
"闭合时 rad 增大" if s > 0 else "闭合时 rad 减小")
|
|
1266
1260
|
return True
|
|
1267
1261
|
|
|
1268
1262
|
def load_template(self, name: str) -> bool:
|
|
1269
|
-
"""Load a
|
|
1263
|
+
"""Load a legacy calibration template by name.
|
|
1264
|
+
|
|
1265
|
+
**Deprecated.** Kept for backward compatibility; shipped grippers
|
|
1266
|
+
have one mounting and the factory calibration describes it. New code
|
|
1267
|
+
uses :meth:`load_calibration` with no arguments or ``path=``.
|
|
1270
1268
|
|
|
1271
|
-
Names come from :func:`list_templates` (``"normal"`` / ``"reverse"``).
|
|
1272
1269
|
Thin wrapper over ``load_calibration(template=name)`` so the name is
|
|
1273
|
-
resolved in one place; see that method for
|
|
1274
|
-
|
|
1270
|
+
resolved in one place; see that method for the template's strict
|
|
1271
|
+
fallback behavior.
|
|
1275
1272
|
|
|
1276
1273
|
Args:
|
|
1277
1274
|
name: Template name.
|
|
@@ -1385,18 +1382,93 @@ class LiteGrip:
|
|
|
1385
1382
|
|
|
1386
1383
|
Args:
|
|
1387
1384
|
force_n: Gripping force in N; ``None`` = ``MotionConfig.force_n``.
|
|
1388
|
-
hold_s: Hold time in seconds; ``0`` = hold until a fault
|
|
1389
|
-
Ctrl+C
|
|
1385
|
+
hold_s: Hold time in seconds; ``0`` = hold until a fault,
|
|
1386
|
+
Ctrl+C, or a :meth:`release` / :meth:`request_release` from
|
|
1387
|
+
another thread.
|
|
1390
1388
|
progress: Optional progress callback.
|
|
1391
1389
|
|
|
1392
1390
|
Returns:
|
|
1393
1391
|
:class:`~litegrip.actions.GraspResult` — truthy when the hold
|
|
1394
1392
|
ended normally. ``stalled=True`` with ``reached=False`` means
|
|
1395
1393
|
it closed onto an object, which is the expected outcome.
|
|
1394
|
+
``released=True`` means the grasp ended because a release was
|
|
1395
|
+
requested: ``ok=True`` for a normal release, ``ok=False`` for
|
|
1396
|
+
an abort.
|
|
1396
1397
|
"""
|
|
1397
1398
|
self._check_connected()
|
|
1398
1399
|
return self._actions.grasp(force_n, hold_s, progress=progress)
|
|
1399
1400
|
|
|
1401
|
+
def release(
|
|
1402
|
+
self,
|
|
1403
|
+
clearance_mm: float = 10.0,
|
|
1404
|
+
*,
|
|
1405
|
+
abort: bool = False,
|
|
1406
|
+
timeout_s: Optional[float] = None,
|
|
1407
|
+
) -> ReleaseResult:
|
|
1408
|
+
"""End an in-progress :meth:`grasp` and open the jaws — thread-safe.
|
|
1409
|
+
|
|
1410
|
+
Call it from any thread, including while ``grasp(hold_s=0)`` is blocked
|
|
1411
|
+
in another one. The grasp thread owns the CAN frames, so this method
|
|
1412
|
+
never sends any itself while a grasp is running: it records the request
|
|
1413
|
+
and waits for the grasp thread to finish releasing, then returns that
|
|
1414
|
+
outcome.
|
|
1415
|
+
|
|
1416
|
+
With no grasp running it performs the release in the calling thread.
|
|
1417
|
+
|
|
1418
|
+
The jaws open from the pose where the grip was **declared** (the end of
|
|
1419
|
+
the force-carrying approach), not from where the set force pressed them
|
|
1420
|
+
to: a 20 N grip drives a few millimetres further in, and opening from
|
|
1421
|
+
there would free that much less. The target is
|
|
1422
|
+
``max(current, grip) + clearance_mm``, clamped to the calibrated open
|
|
1423
|
+
limit, reached by the same bounded position ramp as every other move —
|
|
1424
|
+
never a step command.
|
|
1425
|
+
|
|
1426
|
+
``abort=True`` is the E-stop form: it drops the torque and sends no
|
|
1427
|
+
opening move, returning as soon as the grasp thread has done so.
|
|
1428
|
+
|
|
1429
|
+
Calling it twice is safe: a second call during the same grasp joins the
|
|
1430
|
+
first and returns its outcome instead of opening again.
|
|
1431
|
+
|
|
1432
|
+
Args:
|
|
1433
|
+
clearance_mm: Extra opening beyond the grip pose, in mm; must be a
|
|
1434
|
+
non-negative finite number.
|
|
1435
|
+
abort: E-stop: torque off only, no opening move.
|
|
1436
|
+
timeout_s: How long to wait for the grasp thread; ``None`` =
|
|
1437
|
+
:attr:`MotionConfig.release_wait_s` (10 s). On timeout the
|
|
1438
|
+
result is ``ok=False`` and a warning is logged.
|
|
1439
|
+
|
|
1440
|
+
Returns:
|
|
1441
|
+
:class:`~litegrip.actions.ReleaseResult`.
|
|
1442
|
+
|
|
1443
|
+
Raises:
|
|
1444
|
+
CommandError: ``clearance_mm`` is not a non-negative finite number,
|
|
1445
|
+
or no grasp is running and the config is uncalibrated.
|
|
1446
|
+
NotInitializedError: no grasp is running and the gripper is not
|
|
1447
|
+
connected/enabled.
|
|
1448
|
+
"""
|
|
1449
|
+
self._check_connected()
|
|
1450
|
+
return self._actions.release(clearance_mm, abort=abort,
|
|
1451
|
+
timeout_s=timeout_s)
|
|
1452
|
+
|
|
1453
|
+
def request_release(self, clearance_mm: float = 10.0, *,
|
|
1454
|
+
abort: bool = False) -> bool:
|
|
1455
|
+
"""Non-blocking form of :meth:`release`; never touches the CAN bus.
|
|
1456
|
+
|
|
1457
|
+
Records the request if a grasp is running and returns ``True``; returns
|
|
1458
|
+
``False`` when there is no grasp to release. Safe for a UI thread, a
|
|
1459
|
+
signal handler or an E-stop callback: it takes only the release lock,
|
|
1460
|
+
never ``_io_lock``, and sends no frame. The grasp thread performs the
|
|
1461
|
+
release before its next frame (within 5 ms).
|
|
1462
|
+
|
|
1463
|
+
Args:
|
|
1464
|
+
clearance_mm: Extra opening beyond the grip pose, in mm.
|
|
1465
|
+
abort: E-stop: torque off only, no opening move.
|
|
1466
|
+
|
|
1467
|
+
Returns:
|
|
1468
|
+
True if a grasp was active and the request was recorded.
|
|
1469
|
+
"""
|
|
1470
|
+
return self._actions.request_release(clearance_mm, abort=abort)
|
|
1471
|
+
|
|
1400
1472
|
def zero(self) -> CalibrationData:
|
|
1401
1473
|
"""Full calibration: probe both mechanical limits and save.
|
|
1402
1474
|
|
|
@@ -1756,8 +1828,8 @@ class LiteGrip:
|
|
|
1756
1828
|
|
|
1757
1829
|
A stall only says "something stopped me", never *which* end was hit —
|
|
1758
1830
|
both ends are hard stops. So the direction is not discovered here: it
|
|
1759
|
-
comes from :attr:`GripperConfig.close_sign
|
|
1760
|
-
|
|
1831
|
+
comes from :attr:`GripperConfig.close_sign`, and this routine
|
|
1832
|
+
preserves it.
|
|
1761
1833
|
|
|
1762
1834
|
Safety: at a hard stop the encoder keeps creeping (backlash, elastic
|
|
1763
1835
|
deformation, micro-slip), so the position-based stall test alone can
|
|
@@ -1792,7 +1864,7 @@ class LiteGrip:
|
|
|
1792
1864
|
self._can.update_state(timeout_s=0.1)
|
|
1793
1865
|
init_pos = self._can.get_position()
|
|
1794
1866
|
print(f"标定开始 初始位置: {init_pos:.4f} rad "
|
|
1795
|
-
f"
|
|
1867
|
+
f"(方向:闭合时 rad {'增大' if s > 0 else '减小'})")
|
|
1796
1868
|
|
|
1797
1869
|
def _find_limit(direction: str) -> float:
|
|
1798
1870
|
sign = s if direction == "close" else -s
|
litegrip/models.py
CHANGED
|
@@ -155,24 +155,26 @@ class GripperConfig:
|
|
|
155
155
|
def close_sign(self) -> float:
|
|
156
156
|
"""Which way the motor counts when the jaws close.
|
|
157
157
|
|
|
158
|
-
``+1.0`` when closing means increasing radians (the
|
|
159
|
-
``-1.0``
|
|
160
|
-
calibrated limits, so direction is data, not
|
|
161
|
-
it is only meaningful once :attr:`calibrated`
|
|
158
|
+
``+1.0`` when closing means increasing radians (the shipped
|
|
159
|
+
mounting), ``-1.0`` when the limits run the other way. Derived from
|
|
160
|
+
the ordering of the two calibrated limits, so direction is data, not
|
|
161
|
+
a separate switch — and it is only meaningful once :attr:`calibrated`
|
|
162
|
+
is True.
|
|
162
163
|
"""
|
|
163
164
|
return 1.0 if self.pos_closed_rad >= self.pos_open_rad else -1.0
|
|
164
165
|
|
|
165
166
|
@property
|
|
166
167
|
def mount(self) -> Optional[str]:
|
|
167
|
-
"""``"normal"`` / ``"reverse"``
|
|
168
|
+
"""Legacy mount label (``"normal"`` / ``"reverse"``), or ``None``.
|
|
169
|
+
|
|
170
|
+
**Deprecated.** Kept for backward compatibility. Shipped grippers
|
|
171
|
+
have one mounting; on a calibrated unit this reports ``"normal"``.
|
|
172
|
+
Read ``pos_closed_rad`` / ``pos_open_rad`` directly when you need the
|
|
173
|
+
travel.
|
|
168
174
|
|
|
169
175
|
``None`` while :attr:`calibrated` is False: the placeholder defaults
|
|
170
176
|
also happen to order close above open, so reporting ``"normal"``
|
|
171
177
|
before a calibration has been loaded would be a claim, not a reading.
|
|
172
|
-
Handy for a caller that has to show the operator which way this unit
|
|
173
|
-
is mounted. Compare with the ``mount=`` argument of
|
|
174
|
-
:class:`~litegrip.LiteGrip`, which *declares* a mount by loading a
|
|
175
|
-
template rather than reading one back.
|
|
176
178
|
"""
|
|
177
179
|
if not self.calibrated:
|
|
178
180
|
return None
|
litegrip/teleop.py
CHANGED
|
@@ -543,7 +543,7 @@ def check_ready(cfg: Any) -> None:
|
|
|
543
543
|
raise TeleopNotReady(
|
|
544
544
|
"gripper is not calibrated: pos_closed_rad / pos_open_rad are still "
|
|
545
545
|
"placeholder defaults and the direction is a guess. Run "
|
|
546
|
-
"load_calibration()
|
|
546
|
+
"load_calibration(), or zero() first.")
|
|
547
547
|
if abs(float(cfg.pos_closed_rad) - float(cfg.pos_open_rad)) <= 1e-6:
|
|
548
548
|
raise TeleopNotReady(
|
|
549
549
|
"zero travel: pos_closed_rad equals pos_open_rad — recalibrate.")
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: litegrip-python
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.2.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
|
|
@@ -99,8 +99,8 @@ with LiteGrip("can0") as gripper: # connect() on entry, disconnect()
|
|
|
99
99
|
Two things to know before going further:
|
|
100
100
|
|
|
101
101
|
- **The factory calibration is the default.** A no-argument `load_calibration()` reads the
|
|
102
|
-
calibration file shipped inside the SDK, which describes the shipped units
|
|
103
|
-
|
|
102
|
+
calibration file shipped inside the SDK, which describes the shipped units. You name a
|
|
103
|
+
different file only when you have one — see [Calibration](#calibration).
|
|
104
104
|
- **Nothing moves before a calibration is loaded.** Every motion method raises `CommandError` on
|
|
105
105
|
an uncalibrated config, because the placeholder limits describe no real travel.
|
|
106
106
|
|
|
@@ -119,9 +119,9 @@ LiteGrip(channel="can0", can_id=0x08, mst_id=None, canfd_mode=None,
|
|
|
119
119
|
|
|
120
120
|
- `channel` — CAN interface name. Every LiteGrip shares CAN ID `0x08`, so the channel is the only
|
|
121
121
|
identity key when two sit on one machine.
|
|
122
|
-
- `mount` —
|
|
123
|
-
|
|
124
|
-
|
|
122
|
+
- `mount` — **deprecated**, kept only for backward compatibility. Shipped grippers have one
|
|
123
|
+
mounting, and the factory calibration already describes it; leave it unset and use a
|
|
124
|
+
no-argument `load_calibration()`.
|
|
125
125
|
- `mst_id` — master ID; `None` auto-detects it.
|
|
126
126
|
- `config` / `motion_config` — replace the two dataclasses up front instead of editing them after
|
|
127
127
|
construction.
|
|
@@ -134,7 +134,7 @@ LiteGrip(channel="can0", can_id=0x08, mst_id=None, canfd_mode=None,
|
|
|
134
134
|
| `config` | `GripperConfig` — limits, scale, gains |
|
|
135
135
|
| `motion_config` | `MotionConfig` — every tunable; settable as a whole or field by field |
|
|
136
136
|
| `actions` | `GripperActions` — the engine the high-level methods forward to |
|
|
137
|
-
| `mount` | `"normal"
|
|
137
|
+
| `mount` | **Deprecated**, kept for compatibility; always `"normal"` on a calibrated shipped unit, `None` until calibrated |
|
|
138
138
|
| `is_connected`, `is_enabled` | Session state |
|
|
139
139
|
| `last_send_error` | Why the last `send_mit_frame` did not send, or `None`. The exception the send reported — an `OSError` from the transport, or the `NotInitializedError` naming the step that was skipped. |
|
|
140
140
|
| `session` | The CAN session, for advanced use |
|
|
@@ -202,7 +202,9 @@ 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,
|
|
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). |
|
|
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
|
+
| `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). |
|
|
206
208
|
| `goto(position_mm, kp=None, kd=None, duration=0.5)` → `MoveResult` | Ramp to a position in millimetres. |
|
|
207
209
|
| `goto_rad(position_rad, kp=None, kd=None, dq_target=0.0, tau_feedforward=0.0, duration=0.5)` → `MoveResult` | The same in radians. `dq_target` and `tau_feedforward` must be 0: the ramp derives the velocity feed-forward from its own schedule, so both are refused with `CommandError` rather than ignored. |
|
|
208
210
|
| `move_to(target_rad, kp=None, kd=None, tau_feedforward=0.0, duration=1.0)` → `MoveResult` | The same as `goto_rad`, with a longer default `duration`. |
|
|
@@ -232,6 +234,18 @@ and the hold frames carry `kp = kd = 0`, so the drive's output *is* the feed-for
|
|
|
232
234
|
`force_n × 0.1 Nm`. That is what makes the force independent of the workpiece: as a soft object
|
|
233
235
|
yields, the jaws follow it and the grip stays at the setpoint.
|
|
234
236
|
|
|
237
|
+
**The hold is ended by `release()`, and only by it.** A `grasp(hold_s=0)` keeps sending hold frames
|
|
238
|
+
until something stops it; there is no separate "stop pressing, stay where you are" call. `release()`
|
|
239
|
+
opens from the pose the grip was *declared* at — the end of the force-carrying approach — by
|
|
240
|
+
`clearance_mm` more, not from wherever the set force pressed the jaws to: a 20 N grip drives a few
|
|
241
|
+
millimetres further in, and opening from there would free that much less. The target is
|
|
242
|
+
`max(current, grip pose) + clearance_mm`, clamped to the calibrated open stop and reached by the
|
|
243
|
+
same bounded ramp as every other move. Because a grasp may be holding in one thread while the caller
|
|
244
|
+
wants it to stop from another, `release()` never sends frames from the caller's thread: it records
|
|
245
|
+
the request, the grasp thread sees it before its next frame (5 ms) and performs the opening, and the
|
|
246
|
+
caller gets that result. `request_release()` is the same without the wait, for threads that must not
|
|
247
|
+
block. `abort=True` drops the torque and sends no opening move — the E-stop form.
|
|
248
|
+
|
|
235
249
|
**A force is only meaningful against something.** There is no call that applies a force at the
|
|
236
250
|
current position, and that is deliberate. Such a call cannot tell whether anything is between the
|
|
237
251
|
jaws, and the hold frames give the drive no position or velocity error to work against — with
|
|
@@ -278,7 +292,7 @@ it and nothing else:
|
|
|
278
292
|
from litegrip import LiteGrip
|
|
279
293
|
|
|
280
294
|
with LiteGrip("can0") as gripper:
|
|
281
|
-
gripper.load_calibration() # the shipped file, describing
|
|
295
|
+
gripper.load_calibration() # the shipped file, describing the shipped unit
|
|
282
296
|
gripper.enable()
|
|
283
297
|
```
|
|
284
298
|
|
|
@@ -286,8 +300,8 @@ with LiteGrip("can0") as gripper:
|
|
|
286
300
|
| --- | --- |
|
|
287
301
|
| `load_calibration()` → `bool` | The shipped factory calibration, plus `LITEGRIP_CALIB` when that is set (the env var wins). |
|
|
288
302
|
| `load_calibration(path="/abs/file.json")` → `bool` | That file. Falls back to the factory file only if the path cannot deliver a usable calibration, and warns on a channel mismatch. |
|
|
289
|
-
| `load_calibration(template="normal")` / `load_template(name)` → `bool` |
|
|
290
|
-
| `list_templates()` → `List[str]` | `['normal', 'reverse']
|
|
303
|
+
| `load_calibration(template="normal")` / `load_template(name)` → `bool` | **Deprecated**, kept only for backward compatibility; new code uses a no-argument `load_calibration()` or `path=`. |
|
|
304
|
+
| `list_templates()` → `List[str]` | **Deprecated**, kept for compatibility; still returns `['normal', 'reverse']`. |
|
|
291
305
|
| `default_calib_path(channel="can0")` → `str` | Where a calibration is saved: `~/.litegrip/<channel>_calibration.json`, or `$LITEGRIP_CALIB` when set. |
|
|
292
306
|
| `save_calibration(path=None)` → `str` | Writes the current config to that path. |
|
|
293
307
|
| `zero()` → `CalibrationData` | Probes both mechanical stops, derives the scale, saves the result. |
|
|
@@ -311,7 +325,60 @@ What follows from that:
|
|
|
311
325
|
the one per-unit measurement no calibration file carries, and it matters only when you re-probe.
|
|
312
326
|
- The factory file declares `channel: can0`, so a `can1` unit has no implicit source and fails
|
|
313
327
|
loudly — `load_calibration()` returns `False` — rather than silently adopting `can0`'s
|
|
314
|
-
|
|
328
|
+
calibration. Name its own `zero()` back as shown in the next section.
|
|
329
|
+
|
|
330
|
+
### Using your own calibration file
|
|
331
|
+
|
|
332
|
+
`zero()`, `calibrate_guided()`, and `calibrate_manual()` write their result to
|
|
333
|
+
`~/.litegrip/<channel>_calibration.json`. A no-argument `load_calibration()` **does not read
|
|
334
|
+
it**; the next run must name it explicitly.
|
|
335
|
+
|
|
336
|
+
The most direct way is to pass the save location back to `load_calibration()`:
|
|
337
|
+
|
|
338
|
+
```python
|
|
339
|
+
from litegrip import LiteGrip, default_calib_path
|
|
340
|
+
|
|
341
|
+
path = default_calib_path("can0") # ~/.litegrip/can0_calibration.json
|
|
342
|
+
with LiteGrip("can0") as gripper:
|
|
343
|
+
if not gripper.load_calibration(path=path):
|
|
344
|
+
raise RuntimeError(f"cannot load calibration: {path}")
|
|
345
|
+
gripper.enable()
|
|
346
|
+
gripper.open()
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
For several grippers, or to avoid repeating the path in every script, point an environment
|
|
350
|
+
variable at it; this covers every channel at once:
|
|
351
|
+
|
|
352
|
+
```bash
|
|
353
|
+
export LITEGRIP_CALIB="$HOME/.litegrip/can0_calibration.json"
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
```python
|
|
357
|
+
gripper.load_calibration() # reads LITEGRIP_CALIB first, then the factory file
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
Three rules decide whether the file is read:
|
|
361
|
+
|
|
362
|
+
- **`path=` accepts any JSON path.** It is not limited to `<channel>_calibration.json`; that
|
|
363
|
+
name is only the default destination of `save_calibration()`. A no-argument load does not
|
|
364
|
+
read that directory or guess file names, so do not rename a calibration and expect it to
|
|
365
|
+
be picked up.
|
|
366
|
+
- **The `channel` inside `LITEGRIP_CALIB` must match this instance.** If it does not, a
|
|
367
|
+
no-argument load skips the file and falls back to the factory one, so a `can1` unit never
|
|
368
|
+
silently adopts `can0`'s calibration. `path=` does not skip it; it only warns.
|
|
369
|
+
- **`path=` falls back to the factory calibration when it cannot read the file, and may still
|
|
370
|
+
return `True`.** Do not trust the return value alone: `Calibration loaded from <path>` in
|
|
371
|
+
the log names the file actually read, or check the values below.
|
|
372
|
+
|
|
373
|
+
Verify the loaded calibration before commanding motion:
|
|
374
|
+
|
|
375
|
+
```python
|
|
376
|
+
cfg = gripper.config
|
|
377
|
+
print(cfg.calibrated) # must be True
|
|
378
|
+
print(abs(cfg.pos_open_rad - cfg.pos_closed_rad) * cfg.rad_to_mm) # travel, mm
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
With `calibrated=False`, every motion method raises `CommandError`, so this check is also the gate before motion.
|
|
315
382
|
|
|
316
383
|
### Reading the results
|
|
317
384
|
|
|
@@ -321,7 +388,8 @@ What it *means*, and what to check, is per action:
|
|
|
321
388
|
| Type | Fields | `bool()` is |
|
|
322
389
|
| --- | --- | --- |
|
|
323
390
|
| `MoveResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `limit_rad`, `final_cmd_rad`, `steps`, `protected`, `released` | `ok` |
|
|
324
|
-
| `GraspResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `force_n`, `cycles`, `travel_guard` | `ok` |
|
|
391
|
+
| `GraspResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `force_n`, `cycles`, `travel_guard`, `released` | `ok` |
|
|
392
|
+
| `ReleaseResult` | `ok`, `state`, `opened_mm`, `target_rad`, `aborted` | `ok` |
|
|
325
393
|
| `EnableResult` | `ok`, `state`, `tries` | `ok` |
|
|
326
394
|
|
|
327
395
|
**Read `ok`.** Three combinations look alarming and are correct:
|
|
@@ -346,6 +414,10 @@ A fourth combination is a failure, and new in this version:
|
|
|
346
414
|
`cycles=0`. Nothing was gripped. If you see this, the closing leg is being starved — a stale
|
|
347
415
|
state read, or friction the mechanism's own budget cannot overcome.
|
|
348
416
|
|
|
417
|
+
- **`grasp()` ended by a release** returns `released=True`: `ok=True` when the opening completed,
|
|
418
|
+
`ok=False` when it was an E-stop (`release(abort=True)`), which sends no opening move. `reached`
|
|
419
|
+
and `stalled` still describe the closing leg; `state` is the pose after the release.
|
|
420
|
+
|
|
349
421
|
Stalling far from the limit gives `ok=False`: something blocked the travel. The diagnostic fields
|
|
350
422
|
— `final_cmd_rad`, `steps`, `state` — are what you log when it is false.
|
|
351
423
|
|
|
@@ -397,6 +469,7 @@ with LiteGrip("can0") as gripper:
|
|
|
397
469
|
| `force_n` | `20.0` | default `grasp` force |
|
|
398
470
|
| `force_ramp_n_s` | `20.0` | rate the held force climbs to its setpoint, N/s |
|
|
399
471
|
| `hold_interval` | `0.2` | force-hold slice length, seconds |
|
|
472
|
+
| `release_wait_s` | `10.0` | how long `release()` waits for the grasp thread when `timeout_s` is not given |
|
|
400
473
|
| `hold_runaway_rad` | `0.05` | past the closed stop by this much, the force hold drops the torque and stops |
|
|
401
474
|
| `margin` | `0.05` | fraction of travel kept in reserve from the stop by the `limit_target` helper; no shipped call reaches it |
|
|
402
475
|
| `max_lead_mm` | `4.0` | cap on how far the command may lead the measured position, on moves that carry no force setpoint |
|
|
@@ -528,8 +601,8 @@ python3 examples/trajectory.py --play pick --repeat 3
|
|
|
528
601
|
- **A capture that did not fill raises** rather than returning a short recording as if it were
|
|
529
602
|
whole.
|
|
530
603
|
- **Record without zero-gravity when something else drives.** `record_start(zero_gravity=False)`
|
|
531
|
-
only *reads* state, so the caller may run a `grasp()` or a move sequence
|
|
532
|
-
capture it.
|
|
604
|
+
only *reads* state, so the caller may run a `grasp()` (ended with `release()`) or a move sequence
|
|
605
|
+
from another thread and capture it.
|
|
533
606
|
- `LITEGRIP_TRAJ_DIR` moves the trajectory directory. Recording, replay and teleop are mutually
|
|
534
607
|
exclusive and raise `TrajectoryBusyError` / `TeleopBusyError`; `disconnect()` stops whichever is
|
|
535
608
|
running.
|
|
@@ -584,10 +657,9 @@ the config as their first argument rather than being called on the gripper.
|
|
|
584
657
|
| `CommandError` naming a calibration | No calibration loaded for this channel. Call `load_calibration()`. |
|
|
585
658
|
| `ConnectError`, or no status frame ever | `can0` is down, or the bitrate is not 1 Mbit/s. See step 2. |
|
|
586
659
|
| `HardwareError` from `enable()` | The motor never reported `err == 1`. Check power, then `clear_fault()`. |
|
|
587
|
-
| The jaws move the wrong way | The unit is reverse-mounted, not normal. Construct with `mount="reverse"`. |
|
|
588
660
|
| `close()` returns `ok=False` | The jaw parked further than `stop_tol` from the limit. The gap comes from `zero()` probing harder than `close()` presses, so raising `stop_lead_mm` barely moves it — check that the calibration describes the real travel, and raise `stop_tol` if the unit is genuinely parked on the stop. |
|
|
589
661
|
| `travel_guard` is set | The runaway watch tripped: the jaw walked past the closed-side stop while a force was held — an empty `grasp()` does this when the stop is not where the calibration says. Check the calibration describes the real travel, and that nothing has removed the stop. The jaws are now outside the calibrated travel: `disable()`, push them back clear of the stop by hand, then `enable()`, before commanding anything else. |
|
|
590
|
-
| A `can1` unit's `load_calibration()` returns `False` | A no-argument load reads the factory file, which declares `channel: can0`, so this unit has no implicit source.
|
|
662
|
+
| A `can1` unit's `load_calibration()` returns `False` | A no-argument load reads the factory file, which declares `channel: can0`, so this unit has no implicit source. Name its own file with `path=` or `LITEGRIP_CALIB`; see [Using your own calibration file](#using-your-own-calibration-file). |
|
|
591
663
|
| The held force sags below the setpoint | You changed the hold gains, or something is back-driving the jaws faster than the feed-forward. `hold_kp` / `hold_kd` are deprecated and ignored. |
|
|
592
664
|
| `import litegrip` loads older code than the checkout you are reading | An installed copy does not update itself across `git pull`. Check `litegrip.__file__`, or `pip install -e .` in the checkout. |
|
|
593
665
|
|
|
@@ -1,14 +1,14 @@
|
|
|
1
|
-
litegrip/__init__.py,sha256=
|
|
2
|
-
litegrip/actions.py,sha256=
|
|
1
|
+
litegrip/__init__.py,sha256=1emjAg7k1jLYsmFWVAg7r6jfJV6eZViYDnyRMcofCNM,9386
|
|
2
|
+
litegrip/actions.py,sha256=auXmndmdnZ8UlwQD920t8GwmYrZlG5ewWG8ev-SJoQw,102100
|
|
3
3
|
litegrip/calibration_normal.json,sha256=rL9XGWD-aATZWUqE3MSXuQ2wR_Oz1L0EF78kJgQpnd0,209
|
|
4
4
|
litegrip/calibration_reverse.json,sha256=HVweCi6LVBy7QQGxHa5NeaJfoOAfnzPMmVtXXIiCE74,209
|
|
5
5
|
litegrip/constants.py,sha256=A1-gt-bEk4xsX00LJtE-0uQQu-Brz8LRIJOAVQfBpfg,6660
|
|
6
6
|
litegrip/exceptions.py,sha256=2fQtANhxat0lVbhhU_SD-6nTcA4r-NLCpfmd06TGe3U,1144
|
|
7
7
|
litegrip/factory_calibration.json,sha256=j4kbECLTXRPyfrApraDm2PlNRa1w7mnuhO6sQVQXSxU,345
|
|
8
|
-
litegrip/gripper.py,sha256=
|
|
9
|
-
litegrip/models.py,sha256=
|
|
8
|
+
litegrip/gripper.py,sha256=EQzTB8ygmeMqVFP3SBU_pKcPn9N15SbYv63zmyLX_Zg,123795
|
|
9
|
+
litegrip/models.py,sha256=oS36QK78uiDQFEydupfHMjIk02je75SFC6hvfW2abtM,7669
|
|
10
10
|
litegrip/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
11
|
-
litegrip/teleop.py,sha256=
|
|
11
|
+
litegrip/teleop.py,sha256=1a0MUvpjMaHhjcTO9_T8OHzG-r-zlHGuk54OTMUJAbg,71719
|
|
12
12
|
litegrip/trajectory.py,sha256=n1m97jADWvyk6FdUQGA69g8D2mFwD0bg0o5Zh9Mrpgg,44081
|
|
13
13
|
litegrip/zenoh_link.py,sha256=t9NzlDhG0vJmUuw6B0B7WkXSNgxDH5EhiKIJAmuHDaY,16264
|
|
14
14
|
litegrip/can/__init__.py,sha256=MmK9W41RVx8tmwBMUbezlBbeMUC34pgsw6LveKQ8FKg,1019
|
|
@@ -18,8 +18,8 @@ litegrip/can/protocol.py,sha256=dt69WYOtVGSlmNv_Vxszt4YLkazUvl4dWs4S75wgZqg,1195
|
|
|
18
18
|
litegrip/can/transport.py,sha256=4-0XjPpguEaFVMVHsD5iLBTjgKN8Cb-X1MYTZJkvhPE,14188
|
|
19
19
|
litegrip/protocols/__init__.py,sha256=aregvFK6W76DGGrKCS1tccWsqWWCFBROXZPQ9CcPI1k,304
|
|
20
20
|
litegrip/protocols/can_bus.py,sha256=UhGhVMrgQ--hC-hZNvPscrT2sjdMX3rgspOdCeKXAnY,26383
|
|
21
|
-
litegrip_python-1.
|
|
22
|
-
litegrip_python-1.
|
|
23
|
-
litegrip_python-1.
|
|
24
|
-
litegrip_python-1.
|
|
25
|
-
litegrip_python-1.
|
|
21
|
+
litegrip_python-1.2.0.dist-info/licenses/LICENSE,sha256=yVuuHRzgI17MzTVgt3LsHvuX80innw--CmNPDCzO_iw,11358
|
|
22
|
+
litegrip_python-1.2.0.dist-info/METADATA,sha256=uWOXBHS15P2Wgz4JKAfozOqvPiClQ31dykNg-dMlMSc,43779
|
|
23
|
+
litegrip_python-1.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
24
|
+
litegrip_python-1.2.0.dist-info/top_level.txt,sha256=P4onDW9LkBEwiiQw4u1ui2fZSjQ4_XL5RZeCUh7RGoE,9
|
|
25
|
+
litegrip_python-1.2.0.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|
|
File without changes
|