litegrip-python 1.1.2__tar.gz → 1.2.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.1.2 → litegrip_python-1.2.0}/PKG-INFO +98 -22
  2. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/README.md +94 -18
  3. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/pyproject.toml +5 -5
  4. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/__init__.py +2 -0
  5. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/actions.py +435 -37
  6. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/gripper.py +123 -51
  7. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/models.py +11 -9
  8. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/teleop.py +1 -1
  9. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip_python.egg-info/PKG-INFO +98 -22
  10. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_actions.py +233 -3
  11. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_calibration.py +1 -1
  12. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/LICENSE +0 -0
  13. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/setup.cfg +0 -0
  14. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/calibration_normal.json +0 -0
  15. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/calibration_reverse.json +0 -0
  16. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/can/__init__.py +0 -0
  17. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/can/controller.py +0 -0
  18. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/can/motor.py +0 -0
  19. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/can/protocol.py +0 -0
  20. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/can/transport.py +0 -0
  21. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/constants.py +0 -0
  22. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/exceptions.py +0 -0
  23. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/factory_calibration.json +0 -0
  24. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/protocols/__init__.py +0 -0
  25. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/protocols/can_bus.py +0 -0
  26. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/py.typed +0 -0
  27. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/trajectory.py +0 -0
  28. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip/zenoh_link.py +0 -0
  29. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip_python.egg-info/SOURCES.txt +0 -0
  30. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip_python.egg-info/dependency_links.txt +0 -0
  31. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip_python.egg-info/requires.txt +0 -0
  32. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/src/litegrip_python.egg-info/top_level.txt +0 -0
  33. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_bus_limits.py +0 -0
  34. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_can_stream_silence.py +0 -0
  35. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_enable.py +0 -0
  36. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_example_hold_force.py +0 -0
  37. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_example_teleop.py +0 -0
  38. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_examples_bootstrap.py +0 -0
  39. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_iface_mtu.py +0 -0
  40. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_protocol.py +0 -0
  41. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_send_failure_reports_its_cause.py +0 -0
  42. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_state_staleness.py +0 -0
  43. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_teleop.py +0 -0
  44. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_trajectory.py +0 -0
  45. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_transport_send.py +0 -0
  46. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_version.py +0 -0
  47. {litegrip_python-1.1.2 → litegrip_python-1.2.0}/tests/test_write_zero.py +0 -0
  48. {litegrip_python-1.1.2 → litegrip_python-1.2.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.1.2
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
@@ -12,14 +12,14 @@ Classifier: Intended Audience :: Developers
12
12
  Classifier: Operating System :: POSIX :: Linux
13
13
  Classifier: Programming Language :: Python :: 3
14
14
  Classifier: Programming Language :: Python :: 3 :: Only
15
- Classifier: Programming Language :: Python :: 3.8
16
- Classifier: Programming Language :: Python :: 3.9
17
15
  Classifier: Programming Language :: Python :: 3.10
18
16
  Classifier: Programming Language :: Python :: 3.11
19
17
  Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
20
  Classifier: Topic :: Scientific/Engineering
21
21
  Classifier: Typing :: Typed
22
- Requires-Python: >=3.8
22
+ Requires-Python: >=3.10
23
23
  Description-Content-Type: text/markdown
24
24
  License-File: LICENSE
25
25
  Provides-Extra: zenoh
@@ -43,13 +43,17 @@ below is the real one, with its default.
43
43
  | --- | --- |
44
44
  | Motor | Damiao DM4310, CAN ID `0x08`, MIT mode, classic CAN at 1 Mbit/s |
45
45
  | Host | Linux with SocketCAN — this is the only supported platform |
46
- | Python | 3.8 or newer |
46
+ | Python | 3.10 or newer |
47
47
  | Dependencies | none: standard library only |
48
48
  | Optional | `litegrip-python[zenoh]` — the point-to-point teleoperation link |
49
49
 
50
50
  ## 1. Install
51
51
 
52
- Install it from a checkout:
52
+ ```bash
53
+ pip install litegrip-python
54
+ ```
55
+
56
+ Or install from a checkout:
53
57
 
54
58
  ```bash
55
59
  git clone https://github.com/nexform-tech/litegrip-python.git
@@ -95,8 +99,8 @@ with LiteGrip("can0") as gripper: # connect() on entry, disconnect()
95
99
  Two things to know before going further:
96
100
 
97
101
  - **The factory calibration is the default.** A no-argument `load_calibration()` reads the
98
- calibration file shipped inside the SDK, which describes the shipped units (normal mount). You
99
- name a different file only when you have one — see [Calibration](#calibration).
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).
100
104
  - **Nothing moves before a calibration is loaded.** Every motion method raises `CommandError` on
101
105
  an uncalibrated config, because the placeholder limits describe no real travel.
102
106
 
@@ -115,9 +119,9 @@ LiteGrip(channel="can0", can_id=0x08, mst_id=None, canfd_mode=None,
115
119
 
116
120
  - `channel` — CAN interface name. Every LiteGrip shares CAN ID `0x08`, so the channel is the only
117
121
  identity key when two sit on one machine.
118
- - `mount` — `"normal"` or `"reverse"`, loading that template's limits. The shipped units are
119
- normal mount, which is what the factory calibration describes, so leave it unset unless a unit
120
- is reverse-mounted (its jaws open when you `close()`).
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()`.
121
125
  - `mst_id` — master ID; `None` auto-detects it.
122
126
  - `config` / `motion_config` — replace the two dataclasses up front instead of editing them after
123
127
  construction.
@@ -130,7 +134,7 @@ LiteGrip(channel="can0", can_id=0x08, mst_id=None, canfd_mode=None,
130
134
  | `config` | `GripperConfig` — limits, scale, gains |
131
135
  | `motion_config` | `MotionConfig` — every tunable; settable as a whole or field by field |
132
136
  | `actions` | `GripperActions` — the engine the high-level methods forward to |
133
- | `mount` | `"normal"`, `"reverse"`, or `None` until calibrated (derived from the limits) |
137
+ | `mount` | **Deprecated**, kept for compatibility; always `"normal"` on a calibrated shipped unit, `None` until calibrated |
134
138
  | `is_connected`, `is_enabled` | Session state |
135
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. |
136
140
  | `session` | The CAN session, for advanced use |
@@ -198,7 +202,9 @@ young. Ask both when the difference matters.
198
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. |
199
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. |
200
204
  | `home()` → `MoveResult` | Ramps to the calibrated closed position. |
201
- | `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, or Ctrl+C. `force_n=None` uses `MotionConfig.force_n` (20 N). |
205
+ | `grasp(force_n=None, hold_s=0.0, *, progress=None)` → `GraspResult` | Closes onto the object — or onto the closed-side calibrated stop if there is nothing there — then ramps to and holds `force_n` N. The closing leg carries `force_n` as its torque budget, so meeting the object presses no harder than the setpoint. The hold takes over only once the jaw is stopped: it is `stalled=True` (something is between the jaws) or `reached=True` (the jaws closed empty). `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). |
202
208
  | `goto(position_mm, kp=None, kd=None, duration=0.5)` → `MoveResult` | Ramp to a position in millimetres. |
203
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. |
204
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`. |
@@ -228,6 +234,18 @@ and the hold frames carry `kp = kd = 0`, so the drive's output *is* the feed-for
228
234
  `force_n × 0.1 Nm`. That is what makes the force independent of the workpiece: as a soft object
229
235
  yields, the jaws follow it and the grip stays at the setpoint.
230
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
+
231
249
  **A force is only meaningful against something.** There is no call that applies a force at the
232
250
  current position, and that is deliberate. Such a call cannot tell whether anything is between the
233
251
  jaws, and the hold frames give the drive no position or velocity error to work against — with
@@ -274,7 +292,7 @@ it and nothing else:
274
292
  from litegrip import LiteGrip
275
293
 
276
294
  with LiteGrip("can0") as gripper:
277
- gripper.load_calibration() # the shipped file, describing a normal-mount unit
295
+ gripper.load_calibration() # the shipped file, describing the shipped unit
278
296
  gripper.enable()
279
297
  ```
280
298
 
@@ -282,8 +300,8 @@ with LiteGrip("can0") as gripper:
282
300
  | --- | --- |
283
301
  | `load_calibration()` → `bool` | The shipped factory calibration, plus `LITEGRIP_CALIB` when that is set (the env var wins). |
284
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. |
285
- | `load_calibration(template="normal")` / `load_template(name)` → `bool` | The limits of that template, whatever channel it is on. Strict: an unknown name raises `CommandError`. |
286
- | `list_templates()` → `List[str]` | `['normal', 'reverse']` — every name the SDK accepts, for a UI to offer. A module-level function, imported by name. |
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']`. |
287
305
  | `default_calib_path(channel="can0")` → `str` | Where a calibration is saved: `~/.litegrip/<channel>_calibration.json`, or `$LITEGRIP_CALIB` when set. |
288
306
  | `save_calibration(path=None)` → `str` | Writes the current config to that path. |
289
307
  | `zero()` → `CalibrationData` | Probes both mechanical stops, derives the scale, saves the result. |
@@ -307,7 +325,60 @@ What follows from that:
307
325
  the one per-unit measurement no calibration file carries, and it matters only when you re-probe.
308
326
  - The factory file declares `channel: can0`, so a `can1` unit has no implicit source and fails
309
327
  loudly — `load_calibration()` returns `False` — rather than silently adopting `can0`'s
310
- direction. Give it a template, or a `zero()` of its own named back as above.
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.
311
382
 
312
383
  ### Reading the results
313
384
 
@@ -317,7 +388,8 @@ What it *means*, and what to check, is per action:
317
388
  | Type | Fields | `bool()` is |
318
389
  | --- | --- | --- |
319
390
  | `MoveResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `limit_rad`, `final_cmd_rad`, `steps`, `protected`, `released` | `ok` |
320
- | `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` |
321
393
  | `EnableResult` | `ok`, `state`, `tries` | `ok` |
322
394
 
323
395
  **Read `ok`.** Three combinations look alarming and are correct:
@@ -342,6 +414,10 @@ A fourth combination is a failure, and new in this version:
342
414
  `cycles=0`. Nothing was gripped. If you see this, the closing leg is being starved — a stale
343
415
  state read, or friction the mechanism's own budget cannot overcome.
344
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
+
345
421
  Stalling far from the limit gives `ok=False`: something blocked the travel. The diagnostic fields
346
422
  — `final_cmd_rad`, `steps`, `state` — are what you log when it is false.
347
423
 
@@ -393,6 +469,7 @@ with LiteGrip("can0") as gripper:
393
469
  | `force_n` | `20.0` | default `grasp` force |
394
470
  | `force_ramp_n_s` | `20.0` | rate the held force climbs to its setpoint, N/s |
395
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 |
396
473
  | `hold_runaway_rad` | `0.05` | past the closed stop by this much, the force hold drops the torque and stops |
397
474
  | `margin` | `0.05` | fraction of travel kept in reserve from the stop by the `limit_target` helper; no shipped call reaches it |
398
475
  | `max_lead_mm` | `4.0` | cap on how far the command may lead the measured position, on moves that carry no force setpoint |
@@ -524,8 +601,8 @@ python3 examples/trajectory.py --play pick --repeat 3
524
601
  - **A capture that did not fill raises** rather than returning a short recording as if it were
525
602
  whole.
526
603
  - **Record without zero-gravity when something else drives.** `record_start(zero_gravity=False)`
527
- only *reads* state, so the caller may run a `grasp()` or a move sequence from another thread and
528
- 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.
529
606
  - `LITEGRIP_TRAJ_DIR` moves the trajectory directory. Recording, replay and teleop are mutually
530
607
  exclusive and raise `TrajectoryBusyError` / `TeleopBusyError`; `disconnect()` stops whichever is
531
608
  running.
@@ -580,10 +657,9 @@ the config as their first argument rather than being called on the gripper.
580
657
  | `CommandError` naming a calibration | No calibration loaded for this channel. Call `load_calibration()`. |
581
658
  | `ConnectError`, or no status frame ever | `can0` is down, or the bitrate is not 1 Mbit/s. See step 2. |
582
659
  | `HardwareError` from `enable()` | The motor never reported `err == 1`. Check power, then `clear_fault()`. |
583
- | The jaws move the wrong way | The unit is reverse-mounted, not normal. Construct with `mount="reverse"`. |
584
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. |
585
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. |
586
- | 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. Give it a template, or name its own file with `path=` or `LITEGRIP_CALIB`. |
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). |
587
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. |
588
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. |
589
665
 
@@ -15,13 +15,17 @@ below is the real one, with its default.
15
15
  | --- | --- |
16
16
  | Motor | Damiao DM4310, CAN ID `0x08`, MIT mode, classic CAN at 1 Mbit/s |
17
17
  | Host | Linux with SocketCAN — this is the only supported platform |
18
- | Python | 3.8 or newer |
18
+ | Python | 3.10 or newer |
19
19
  | Dependencies | none: standard library only |
20
20
  | Optional | `litegrip-python[zenoh]` — the point-to-point teleoperation link |
21
21
 
22
22
  ## 1. Install
23
23
 
24
- Install it from a checkout:
24
+ ```bash
25
+ pip install litegrip-python
26
+ ```
27
+
28
+ Or install from a checkout:
25
29
 
26
30
  ```bash
27
31
  git clone https://github.com/nexform-tech/litegrip-python.git
@@ -67,8 +71,8 @@ with LiteGrip("can0") as gripper: # connect() on entry, disconnect()
67
71
  Two things to know before going further:
68
72
 
69
73
  - **The factory calibration is the default.** A no-argument `load_calibration()` reads the
70
- calibration file shipped inside the SDK, which describes the shipped units (normal mount). You
71
- name a different file only when you have one — see [Calibration](#calibration).
74
+ calibration file shipped inside the SDK, which describes the shipped units. You name a
75
+ different file only when you have one — see [Calibration](#calibration).
72
76
  - **Nothing moves before a calibration is loaded.** Every motion method raises `CommandError` on
73
77
  an uncalibrated config, because the placeholder limits describe no real travel.
74
78
 
@@ -87,9 +91,9 @@ LiteGrip(channel="can0", can_id=0x08, mst_id=None, canfd_mode=None,
87
91
 
88
92
  - `channel` — CAN interface name. Every LiteGrip shares CAN ID `0x08`, so the channel is the only
89
93
  identity key when two sit on one machine.
90
- - `mount` — `"normal"` or `"reverse"`, loading that template's limits. The shipped units are
91
- normal mount, which is what the factory calibration describes, so leave it unset unless a unit
92
- is reverse-mounted (its jaws open when you `close()`).
94
+ - `mount` — **deprecated**, kept only for backward compatibility. Shipped grippers have one
95
+ mounting, and the factory calibration already describes it; leave it unset and use a
96
+ no-argument `load_calibration()`.
93
97
  - `mst_id` — master ID; `None` auto-detects it.
94
98
  - `config` / `motion_config` — replace the two dataclasses up front instead of editing them after
95
99
  construction.
@@ -102,7 +106,7 @@ LiteGrip(channel="can0", can_id=0x08, mst_id=None, canfd_mode=None,
102
106
  | `config` | `GripperConfig` — limits, scale, gains |
103
107
  | `motion_config` | `MotionConfig` — every tunable; settable as a whole or field by field |
104
108
  | `actions` | `GripperActions` — the engine the high-level methods forward to |
105
- | `mount` | `"normal"`, `"reverse"`, or `None` until calibrated (derived from the limits) |
109
+ | `mount` | **Deprecated**, kept for compatibility; always `"normal"` on a calibrated shipped unit, `None` until calibrated |
106
110
  | `is_connected`, `is_enabled` | Session state |
107
111
  | `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. |
108
112
  | `session` | The CAN session, for advanced use |
@@ -170,7 +174,9 @@ young. Ask both when the difference matters.
170
174
  | `open(speed_mm_s=None, *, progress=None)` → `MoveResult` | Ramps toward the calibrated open-side stop. With `GripperConfig.work_stroke_mm` set it stops at that opening instead — the shipped calibration sets `80.0` against the unit's 85 mm of travel, so a plain `open()` ends 5 mm short of the open end. |
171
175
  | `close(speed_mm_s=None, *, progress=None)` → `MoveResult` | The same, toward the closed side. `work_stroke_mm` is an open-side number and does not change where a close ends. |
172
176
  | `home()` → `MoveResult` | Ramps to the calibrated closed position. |
173
- | `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, or Ctrl+C. `force_n=None` uses `MotionConfig.force_n` (20 N). |
177
+ | `grasp(force_n=None, hold_s=0.0, *, progress=None)` → `GraspResult` | Closes onto the object — or onto the closed-side calibrated stop if there is nothing there — then ramps to and holds `force_n` N. The closing leg carries `force_n` as its torque budget, so meeting the object presses no harder than the setpoint. The hold takes over only once the jaw is stopped: it is `stalled=True` (something is between the jaws) or `reached=True` (the jaws closed empty). `hold_s=0` holds until a fault, the runaway watch, Ctrl+C, or a `release()` / `request_release()` from another thread — which ends the grasp with `released=True`. `force_n=None` uses `MotionConfig.force_n` (20 N). |
178
+ | `release(clearance_mm=10.0, *, abort=False, timeout_s=None)` → `ReleaseResult` | Ends an in-progress `grasp()` and opens the jaws from the pose where the grip was declared, by `clearance_mm` more, clamped to the calibrated open stop. Safe to call from any thread while `grasp(hold_s=0)` is blocked in another: it queues the request, the grasp thread performs the opening, and the call returns that outcome. With no grasp running it opens from the current position in the calling thread. `abort=True` is the E-stop form: torque off, no opening move, `ok=False`. A second call during the same grasp joins the first. |
179
+ | `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). |
174
180
  | `goto(position_mm, kp=None, kd=None, duration=0.5)` → `MoveResult` | Ramp to a position in millimetres. |
175
181
  | `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. |
176
182
  | `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`. |
@@ -200,6 +206,18 @@ and the hold frames carry `kp = kd = 0`, so the drive's output *is* the feed-for
200
206
  `force_n × 0.1 Nm`. That is what makes the force independent of the workpiece: as a soft object
201
207
  yields, the jaws follow it and the grip stays at the setpoint.
202
208
 
209
+ **The hold is ended by `release()`, and only by it.** A `grasp(hold_s=0)` keeps sending hold frames
210
+ until something stops it; there is no separate "stop pressing, stay where you are" call. `release()`
211
+ opens from the pose the grip was *declared* at — the end of the force-carrying approach — by
212
+ `clearance_mm` more, not from wherever the set force pressed the jaws to: a 20 N grip drives a few
213
+ millimetres further in, and opening from there would free that much less. The target is
214
+ `max(current, grip pose) + clearance_mm`, clamped to the calibrated open stop and reached by the
215
+ same bounded ramp as every other move. Because a grasp may be holding in one thread while the caller
216
+ wants it to stop from another, `release()` never sends frames from the caller's thread: it records
217
+ the request, the grasp thread sees it before its next frame (5 ms) and performs the opening, and the
218
+ caller gets that result. `request_release()` is the same without the wait, for threads that must not
219
+ block. `abort=True` drops the torque and sends no opening move — the E-stop form.
220
+
203
221
  **A force is only meaningful against something.** There is no call that applies a force at the
204
222
  current position, and that is deliberate. Such a call cannot tell whether anything is between the
205
223
  jaws, and the hold frames give the drive no position or velocity error to work against — with
@@ -246,7 +264,7 @@ it and nothing else:
246
264
  from litegrip import LiteGrip
247
265
 
248
266
  with LiteGrip("can0") as gripper:
249
- gripper.load_calibration() # the shipped file, describing a normal-mount unit
267
+ gripper.load_calibration() # the shipped file, describing the shipped unit
250
268
  gripper.enable()
251
269
  ```
252
270
 
@@ -254,8 +272,8 @@ with LiteGrip("can0") as gripper:
254
272
  | --- | --- |
255
273
  | `load_calibration()` → `bool` | The shipped factory calibration, plus `LITEGRIP_CALIB` when that is set (the env var wins). |
256
274
  | `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. |
257
- | `load_calibration(template="normal")` / `load_template(name)` → `bool` | The limits of that template, whatever channel it is on. Strict: an unknown name raises `CommandError`. |
258
- | `list_templates()` → `List[str]` | `['normal', 'reverse']` — every name the SDK accepts, for a UI to offer. A module-level function, imported by name. |
275
+ | `load_calibration(template="normal")` / `load_template(name)` → `bool` | **Deprecated**, kept only for backward compatibility; new code uses a no-argument `load_calibration()` or `path=`. |
276
+ | `list_templates()` → `List[str]` | **Deprecated**, kept for compatibility; still returns `['normal', 'reverse']`. |
259
277
  | `default_calib_path(channel="can0")` → `str` | Where a calibration is saved: `~/.litegrip/<channel>_calibration.json`, or `$LITEGRIP_CALIB` when set. |
260
278
  | `save_calibration(path=None)` → `str` | Writes the current config to that path. |
261
279
  | `zero()` → `CalibrationData` | Probes both mechanical stops, derives the scale, saves the result. |
@@ -279,7 +297,60 @@ What follows from that:
279
297
  the one per-unit measurement no calibration file carries, and it matters only when you re-probe.
280
298
  - The factory file declares `channel: can0`, so a `can1` unit has no implicit source and fails
281
299
  loudly — `load_calibration()` returns `False` — rather than silently adopting `can0`'s
282
- direction. Give it a template, or a `zero()` of its own named back as above.
300
+ calibration. Name its own `zero()` back as shown in the next section.
301
+
302
+ ### Using your own calibration file
303
+
304
+ `zero()`, `calibrate_guided()`, and `calibrate_manual()` write their result to
305
+ `~/.litegrip/<channel>_calibration.json`. A no-argument `load_calibration()` **does not read
306
+ it**; the next run must name it explicitly.
307
+
308
+ The most direct way is to pass the save location back to `load_calibration()`:
309
+
310
+ ```python
311
+ from litegrip import LiteGrip, default_calib_path
312
+
313
+ path = default_calib_path("can0") # ~/.litegrip/can0_calibration.json
314
+ with LiteGrip("can0") as gripper:
315
+ if not gripper.load_calibration(path=path):
316
+ raise RuntimeError(f"cannot load calibration: {path}")
317
+ gripper.enable()
318
+ gripper.open()
319
+ ```
320
+
321
+ For several grippers, or to avoid repeating the path in every script, point an environment
322
+ variable at it; this covers every channel at once:
323
+
324
+ ```bash
325
+ export LITEGRIP_CALIB="$HOME/.litegrip/can0_calibration.json"
326
+ ```
327
+
328
+ ```python
329
+ gripper.load_calibration() # reads LITEGRIP_CALIB first, then the factory file
330
+ ```
331
+
332
+ Three rules decide whether the file is read:
333
+
334
+ - **`path=` accepts any JSON path.** It is not limited to `<channel>_calibration.json`; that
335
+ name is only the default destination of `save_calibration()`. A no-argument load does not
336
+ read that directory or guess file names, so do not rename a calibration and expect it to
337
+ be picked up.
338
+ - **The `channel` inside `LITEGRIP_CALIB` must match this instance.** If it does not, a
339
+ no-argument load skips the file and falls back to the factory one, so a `can1` unit never
340
+ silently adopts `can0`'s calibration. `path=` does not skip it; it only warns.
341
+ - **`path=` falls back to the factory calibration when it cannot read the file, and may still
342
+ return `True`.** Do not trust the return value alone: `Calibration loaded from <path>` in
343
+ the log names the file actually read, or check the values below.
344
+
345
+ Verify the loaded calibration before commanding motion:
346
+
347
+ ```python
348
+ cfg = gripper.config
349
+ print(cfg.calibrated) # must be True
350
+ print(abs(cfg.pos_open_rad - cfg.pos_closed_rad) * cfg.rad_to_mm) # travel, mm
351
+ ```
352
+
353
+ With `calibrated=False`, every motion method raises `CommandError`, so this check is also the gate before motion.
283
354
 
284
355
  ### Reading the results
285
356
 
@@ -289,7 +360,8 @@ What it *means*, and what to check, is per action:
289
360
  | Type | Fields | `bool()` is |
290
361
  | --- | --- | --- |
291
362
  | `MoveResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `limit_rad`, `final_cmd_rad`, `steps`, `protected`, `released` | `ok` |
292
- | `GraspResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `force_n`, `cycles`, `travel_guard` | `ok` |
363
+ | `GraspResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `force_n`, `cycles`, `travel_guard`, `released` | `ok` |
364
+ | `ReleaseResult` | `ok`, `state`, `opened_mm`, `target_rad`, `aborted` | `ok` |
293
365
  | `EnableResult` | `ok`, `state`, `tries` | `ok` |
294
366
 
295
367
  **Read `ok`.** Three combinations look alarming and are correct:
@@ -314,6 +386,10 @@ A fourth combination is a failure, and new in this version:
314
386
  `cycles=0`. Nothing was gripped. If you see this, the closing leg is being starved — a stale
315
387
  state read, or friction the mechanism's own budget cannot overcome.
316
388
 
389
+ - **`grasp()` ended by a release** returns `released=True`: `ok=True` when the opening completed,
390
+ `ok=False` when it was an E-stop (`release(abort=True)`), which sends no opening move. `reached`
391
+ and `stalled` still describe the closing leg; `state` is the pose after the release.
392
+
317
393
  Stalling far from the limit gives `ok=False`: something blocked the travel. The diagnostic fields
318
394
  — `final_cmd_rad`, `steps`, `state` — are what you log when it is false.
319
395
 
@@ -365,6 +441,7 @@ with LiteGrip("can0") as gripper:
365
441
  | `force_n` | `20.0` | default `grasp` force |
366
442
  | `force_ramp_n_s` | `20.0` | rate the held force climbs to its setpoint, N/s |
367
443
  | `hold_interval` | `0.2` | force-hold slice length, seconds |
444
+ | `release_wait_s` | `10.0` | how long `release()` waits for the grasp thread when `timeout_s` is not given |
368
445
  | `hold_runaway_rad` | `0.05` | past the closed stop by this much, the force hold drops the torque and stops |
369
446
  | `margin` | `0.05` | fraction of travel kept in reserve from the stop by the `limit_target` helper; no shipped call reaches it |
370
447
  | `max_lead_mm` | `4.0` | cap on how far the command may lead the measured position, on moves that carry no force setpoint |
@@ -496,8 +573,8 @@ python3 examples/trajectory.py --play pick --repeat 3
496
573
  - **A capture that did not fill raises** rather than returning a short recording as if it were
497
574
  whole.
498
575
  - **Record without zero-gravity when something else drives.** `record_start(zero_gravity=False)`
499
- only *reads* state, so the caller may run a `grasp()` or a move sequence from another thread and
500
- capture it.
576
+ only *reads* state, so the caller may run a `grasp()` (ended with `release()`) or a move sequence
577
+ from another thread and capture it.
501
578
  - `LITEGRIP_TRAJ_DIR` moves the trajectory directory. Recording, replay and teleop are mutually
502
579
  exclusive and raise `TrajectoryBusyError` / `TeleopBusyError`; `disconnect()` stops whichever is
503
580
  running.
@@ -552,10 +629,9 @@ the config as their first argument rather than being called on the gripper.
552
629
  | `CommandError` naming a calibration | No calibration loaded for this channel. Call `load_calibration()`. |
553
630
  | `ConnectError`, or no status frame ever | `can0` is down, or the bitrate is not 1 Mbit/s. See step 2. |
554
631
  | `HardwareError` from `enable()` | The motor never reported `err == 1`. Check power, then `clear_fault()`. |
555
- | The jaws move the wrong way | The unit is reverse-mounted, not normal. Construct with `mount="reverse"`. |
556
632
  | `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. |
557
633
  | `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. |
558
- | 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. Give it a template, or name its own file with `path=` or `LITEGRIP_CALIB`. |
634
+ | 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). |
559
635
  | 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. |
560
636
  | `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. |
561
637
 
@@ -14,10 +14,10 @@ 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.1.2"
17
+ version = "1.2.0"
18
18
  description = "Python SDK for the LiteGrip lightweight robotic gripper series"
19
19
  readme = "README.md"
20
- requires-python = ">=3.8"
20
+ requires-python = ">=3.10"
21
21
  license = "Apache-2.0"
22
22
  license-files = ["LICENSE"]
23
23
  authors = [{ name = "NEXFORM ROBOTICS" }]
@@ -37,11 +37,11 @@ classifiers = [
37
37
  "Operating System :: POSIX :: Linux",
38
38
  "Programming Language :: Python :: 3",
39
39
  "Programming Language :: Python :: 3 :: Only",
40
- "Programming Language :: Python :: 3.8",
41
- "Programming Language :: Python :: 3.9",
42
40
  "Programming Language :: Python :: 3.10",
43
41
  "Programming Language :: Python :: 3.11",
44
42
  "Programming Language :: Python :: 3.12",
43
+ "Programming Language :: Python :: 3.13",
44
+ "Programming Language :: Python :: 3.14",
45
45
  "Topic :: Scientific/Engineering",
46
46
  "Typing :: Typed",
47
47
  ]
@@ -66,5 +66,5 @@ where = ["src"]
66
66
  [tool.setuptools.package-data]
67
67
  # py.typed tells type checkers the annotations are real. The JSON files are the
68
68
  # read-only fallback used when a unit has never been calibrated on site: the
69
- # factory one, plus the normal/reverse direction templates.
69
+ # factory one, plus the legacy direction templates kept for compatibility.
70
70
  litegrip = ["py.typed", "*.json"]
@@ -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",