litegrip-python 1.1.3__tar.gz → 1.2.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/PKG-INFO +111 -18
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/README.md +110 -17
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/pyproject.toml +2 -2
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/__init__.py +2 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/actions.py +548 -41
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/gripper.py +128 -51
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/models.py +11 -9
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/teleop.py +1 -1
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip_python.egg-info/PKG-INFO +111 -18
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_actions.py +353 -3
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/LICENSE +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/setup.cfg +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/calibration_normal.json +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/calibration_reverse.json +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/can/__init__.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/can/controller.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/can/motor.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/can/protocol.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/can/transport.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/constants.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/exceptions.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/factory_calibration.json +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/protocols/__init__.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/protocols/can_bus.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/py.typed +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/trajectory.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip/zenoh_link.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip_python.egg-info/SOURCES.txt +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip_python.egg-info/dependency_links.txt +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip_python.egg-info/requires.txt +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/src/litegrip_python.egg-info/top_level.txt +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_bus_limits.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_calibration.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_can_stream_silence.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_enable.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_example_hold_force.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_example_teleop.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_examples_bootstrap.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_iface_mtu.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_protocol.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_send_failure_reports_its_cause.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_state_staleness.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_teleop.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_trajectory.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_transport_send.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_version.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/tests/test_write_zero.py +0 -0
- {litegrip_python-1.1.3 → litegrip_python-1.2.1}/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
|
|
3
|
+
Version: 1.2.1
|
|
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). A stop that came **without the jaw ever moving from where the approach began**, with a budget below `MotionConfig.breakaway_nm`, is not treated as contact — the budget simply cannot break static friction — so the call releases in place and returns `no_bite=True` instead of handing over the hold. `hold_s=0` holds until a fault, the runaway watch, Ctrl+C, or a `release()` / `request_release()` from another thread — which ends the grasp with `released=True`. `force_n=None` uses `MotionConfig.force_n` (20 N). |
|
|
206
|
+
| `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
|
|
|
@@ -320,8 +387,9 @@ What it *means*, and what to check, is per action:
|
|
|
320
387
|
|
|
321
388
|
| Type | Fields | `bool()` is |
|
|
322
389
|
| --- | --- | --- |
|
|
323
|
-
| `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` |
|
|
390
|
+
| `MoveResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `limit_rad`, `final_cmd_rad`, `steps`, `protected`, `released`, `no_bite` | `ok` |
|
|
391
|
+
| `GraspResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `force_n`, `cycles`, `travel_guard`, `released`, `no_bite` | `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,29 @@ 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
|
+
A fifth is a refusal:
|
|
418
|
+
|
|
419
|
+
- **`grasp()` with `ok=False, no_bite=True`** means the approach carried its force but never moved
|
|
420
|
+
the jaws: it stopped within `MotionConfig.no_bite_mm` (0.5 mm) of where it started *and* its
|
|
421
|
+
budget (`force_n × 0.1 × press_safety`) was below `MotionConfig.breakaway_nm` (0.2 N·m on this
|
|
422
|
+
unit, so setpoints up to 2.2 N). That is not contact — it is a budget that cannot break static
|
|
423
|
+
friction — and it is exactly the case where handing over the hold would send a jaw with a free
|
|
424
|
+
stroke ahead of it into the torque-only frames and let it accelerate. So the hold is never
|
|
425
|
+
entered, the call releases in place, and `cycles` is 0. `stalled` and `reached` are both `False`
|
|
426
|
+
on this path. The remedy is a setpoint above the breakaway (~2.5 N here), not a longer hold.
|
|
427
|
+
Above the breakaway a zero-displacement stop *is* contact and is held normally: a part already
|
|
428
|
+
against the open jaw, or a re-grasp in place after `release(abort=True)`, still grips.
|
|
429
|
+
|
|
430
|
+
Two edges worth knowing. An approach that starts within `reach_tol` (0.9 mm) of the closed stop
|
|
431
|
+
gets no stall verdict at all — it reports `reached` instead, and the hold has nothing to run
|
|
432
|
+
because the jaws are already on the end stop. And the refusal is about the budget, not the part:
|
|
433
|
+
if a grippy part sits at the start pose *and* the setpoint is below the breakaway, the grasp is
|
|
434
|
+
refused rather than risked.
|
|
435
|
+
|
|
436
|
+
- **`grasp()` ended by a release** returns `released=True`: `ok=True` when the opening completed,
|
|
437
|
+
`ok=False` when it was an E-stop (`release(abort=True)`), which sends no opening move. `reached`
|
|
438
|
+
and `stalled` still describe the closing leg; `state` is the pose after the release.
|
|
439
|
+
|
|
349
440
|
Stalling far from the limit gives `ok=False`: something blocked the travel. The diagnostic fields
|
|
350
441
|
— `final_cmd_rad`, `steps`, `state` — are what you log when it is false.
|
|
351
442
|
|
|
@@ -397,11 +488,14 @@ with LiteGrip("can0") as gripper:
|
|
|
397
488
|
| `force_n` | `20.0` | default `grasp` force |
|
|
398
489
|
| `force_ramp_n_s` | `20.0` | rate the held force climbs to its setpoint, N/s |
|
|
399
490
|
| `hold_interval` | `0.2` | force-hold slice length, seconds |
|
|
491
|
+
| `release_wait_s` | `10.0` | how long `release()` waits for the grasp thread when `timeout_s` is not given |
|
|
400
492
|
| `hold_runaway_rad` | `0.05` | past the closed stop by this much, the force hold drops the torque and stops |
|
|
401
493
|
| `margin` | `0.05` | fraction of travel kept in reserve from the stop by the `limit_target` helper; no shipped call reaches it |
|
|
402
494
|
| `max_lead_mm` | `4.0` | cap on how far the command may lead the measured position, on moves that carry no force setpoint |
|
|
403
495
|
| `stop_lead_mm` | `0.7` | the same cap on the approach to a stop, so the pressing torque stays bounded |
|
|
404
496
|
| `press_safety` | `0.9` | fraction of the setpoint a force-carrying approach may spend |
|
|
497
|
+
| `no_bite_mm` | `0.5` | a force-carrying approach that stops this close to its start pose is refused, not read as contact (see `grasp()` above) |
|
|
498
|
+
| `breakaway_nm` | `0.2` | measured static-friction breakaway; only a budget below it makes a zero-displacement stop a refusal rather than contact |
|
|
405
499
|
| `reach_tol` | `0.02` | position tolerance for `reached`, radians |
|
|
406
500
|
| `stop_tol` | `0.03` | how close to the calibrated stop the jaw must park to count as pressed home |
|
|
407
501
|
| `settle_s` | `0.3` | time spent holding the target after the ramp |
|
|
@@ -528,8 +622,8 @@ python3 examples/trajectory.py --play pick --repeat 3
|
|
|
528
622
|
- **A capture that did not fill raises** rather than returning a short recording as if it were
|
|
529
623
|
whole.
|
|
530
624
|
- **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.
|
|
625
|
+
only *reads* state, so the caller may run a `grasp()` (ended with `release()`) or a move sequence
|
|
626
|
+
from another thread and capture it.
|
|
533
627
|
- `LITEGRIP_TRAJ_DIR` moves the trajectory directory. Recording, replay and teleop are mutually
|
|
534
628
|
exclusive and raise `TrajectoryBusyError` / `TeleopBusyError`; `disconnect()` stops whichever is
|
|
535
629
|
running.
|
|
@@ -584,10 +678,9 @@ the config as their first argument rather than being called on the gripper.
|
|
|
584
678
|
| `CommandError` naming a calibration | No calibration loaded for this channel. Call `load_calibration()`. |
|
|
585
679
|
| `ConnectError`, or no status frame ever | `can0` is down, or the bitrate is not 1 Mbit/s. See step 2. |
|
|
586
680
|
| `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
681
|
| `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
682
|
| `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.
|
|
683
|
+
| 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
684
|
| 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
685
|
| `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
686
|
|
|
@@ -71,8 +71,8 @@ with LiteGrip("can0") as gripper: # connect() on entry, disconnect()
|
|
|
71
71
|
Two things to know before going further:
|
|
72
72
|
|
|
73
73
|
- **The factory calibration is the default.** A no-argument `load_calibration()` reads the
|
|
74
|
-
calibration file shipped inside the SDK, which describes the shipped units
|
|
75
|
-
|
|
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).
|
|
76
76
|
- **Nothing moves before a calibration is loaded.** Every motion method raises `CommandError` on
|
|
77
77
|
an uncalibrated config, because the placeholder limits describe no real travel.
|
|
78
78
|
|
|
@@ -91,9 +91,9 @@ LiteGrip(channel="can0", can_id=0x08, mst_id=None, canfd_mode=None,
|
|
|
91
91
|
|
|
92
92
|
- `channel` — CAN interface name. Every LiteGrip shares CAN ID `0x08`, so the channel is the only
|
|
93
93
|
identity key when two sit on one machine.
|
|
94
|
-
- `mount` —
|
|
95
|
-
|
|
96
|
-
|
|
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()`.
|
|
97
97
|
- `mst_id` — master ID; `None` auto-detects it.
|
|
98
98
|
- `config` / `motion_config` — replace the two dataclasses up front instead of editing them after
|
|
99
99
|
construction.
|
|
@@ -106,7 +106,7 @@ LiteGrip(channel="can0", can_id=0x08, mst_id=None, canfd_mode=None,
|
|
|
106
106
|
| `config` | `GripperConfig` — limits, scale, gains |
|
|
107
107
|
| `motion_config` | `MotionConfig` — every tunable; settable as a whole or field by field |
|
|
108
108
|
| `actions` | `GripperActions` — the engine the high-level methods forward to |
|
|
109
|
-
| `mount` | `"normal"
|
|
109
|
+
| `mount` | **Deprecated**, kept for compatibility; always `"normal"` on a calibrated shipped unit, `None` until calibrated |
|
|
110
110
|
| `is_connected`, `is_enabled` | Session state |
|
|
111
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. |
|
|
112
112
|
| `session` | The CAN session, for advanced use |
|
|
@@ -174,7 +174,9 @@ young. Ask both when the difference matters.
|
|
|
174
174
|
| `open(speed_mm_s=None, *, progress=None)` → `MoveResult` | Ramps toward the calibrated open-side stop. With `GripperConfig.work_stroke_mm` set it stops at that opening instead — the shipped calibration sets `80.0` against the unit's 85 mm of travel, so a plain `open()` ends 5 mm short of the open end. |
|
|
175
175
|
| `close(speed_mm_s=None, *, progress=None)` → `MoveResult` | The same, toward the closed side. `work_stroke_mm` is an open-side number and does not change where a close ends. |
|
|
176
176
|
| `home()` → `MoveResult` | Ramps to the calibrated closed position. |
|
|
177
|
-
| `grasp(force_n=None, hold_s=0.0, *, progress=None)` → `GraspResult` | Closes onto the object — or onto the closed-side calibrated stop if there is nothing there — then ramps to and holds `force_n` N. The closing leg carries `force_n` as its torque budget, so meeting the object presses no harder than the setpoint. The hold takes over only once the jaw is stopped: it is `stalled=True` (something is between the jaws) or `reached=True` (the jaws closed empty). `hold_s=0` holds until a fault, the runaway watch,
|
|
177
|
+
| `grasp(force_n=None, hold_s=0.0, *, progress=None)` → `GraspResult` | Closes onto the object — or onto the closed-side calibrated stop if there is nothing there — then ramps to and holds `force_n` N. The closing leg carries `force_n` as its torque budget, so meeting the object presses no harder than the setpoint. The hold takes over only once the jaw is stopped: it is `stalled=True` (something is between the jaws) or `reached=True` (the jaws closed empty). A stop that came **without the jaw ever moving from where the approach began**, with a budget below `MotionConfig.breakaway_nm`, is not treated as contact — the budget simply cannot break static friction — so the call releases in place and returns `no_bite=True` instead of handing over the hold. `hold_s=0` holds until a fault, the runaway watch, Ctrl+C, or a `release()` / `request_release()` from another thread — which ends the grasp with `released=True`. `force_n=None` uses `MotionConfig.force_n` (20 N). |
|
|
178
|
+
| `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). |
|
|
178
180
|
| `goto(position_mm, kp=None, kd=None, duration=0.5)` → `MoveResult` | Ramp to a position in millimetres. |
|
|
179
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. |
|
|
180
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`. |
|
|
@@ -204,6 +206,18 @@ and the hold frames carry `kp = kd = 0`, so the drive's output *is* the feed-for
|
|
|
204
206
|
`force_n × 0.1 Nm`. That is what makes the force independent of the workpiece: as a soft object
|
|
205
207
|
yields, the jaws follow it and the grip stays at the setpoint.
|
|
206
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
|
+
|
|
207
221
|
**A force is only meaningful against something.** There is no call that applies a force at the
|
|
208
222
|
current position, and that is deliberate. Such a call cannot tell whether anything is between the
|
|
209
223
|
jaws, and the hold frames give the drive no position or velocity error to work against — with
|
|
@@ -250,7 +264,7 @@ it and nothing else:
|
|
|
250
264
|
from litegrip import LiteGrip
|
|
251
265
|
|
|
252
266
|
with LiteGrip("can0") as gripper:
|
|
253
|
-
gripper.load_calibration() # the shipped file, describing
|
|
267
|
+
gripper.load_calibration() # the shipped file, describing the shipped unit
|
|
254
268
|
gripper.enable()
|
|
255
269
|
```
|
|
256
270
|
|
|
@@ -258,8 +272,8 @@ with LiteGrip("can0") as gripper:
|
|
|
258
272
|
| --- | --- |
|
|
259
273
|
| `load_calibration()` → `bool` | The shipped factory calibration, plus `LITEGRIP_CALIB` when that is set (the env var wins). |
|
|
260
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. |
|
|
261
|
-
| `load_calibration(template="normal")` / `load_template(name)` → `bool` |
|
|
262
|
-
| `list_templates()` → `List[str]` | `['normal', 'reverse']
|
|
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']`. |
|
|
263
277
|
| `default_calib_path(channel="can0")` → `str` | Where a calibration is saved: `~/.litegrip/<channel>_calibration.json`, or `$LITEGRIP_CALIB` when set. |
|
|
264
278
|
| `save_calibration(path=None)` → `str` | Writes the current config to that path. |
|
|
265
279
|
| `zero()` → `CalibrationData` | Probes both mechanical stops, derives the scale, saves the result. |
|
|
@@ -283,7 +297,60 @@ What follows from that:
|
|
|
283
297
|
the one per-unit measurement no calibration file carries, and it matters only when you re-probe.
|
|
284
298
|
- The factory file declares `channel: can0`, so a `can1` unit has no implicit source and fails
|
|
285
299
|
loudly — `load_calibration()` returns `False` — rather than silently adopting `can0`'s
|
|
286
|
-
|
|
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.
|
|
287
354
|
|
|
288
355
|
### Reading the results
|
|
289
356
|
|
|
@@ -292,8 +359,9 @@ What it *means*, and what to check, is per action:
|
|
|
292
359
|
|
|
293
360
|
| Type | Fields | `bool()` is |
|
|
294
361
|
| --- | --- | --- |
|
|
295
|
-
| `MoveResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `limit_rad`, `final_cmd_rad`, `steps`, `protected`, `released` | `ok` |
|
|
296
|
-
| `GraspResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `force_n`, `cycles`, `travel_guard` | `ok` |
|
|
362
|
+
| `MoveResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `limit_rad`, `final_cmd_rad`, `steps`, `protected`, `released`, `no_bite` | `ok` |
|
|
363
|
+
| `GraspResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `force_n`, `cycles`, `travel_guard`, `released`, `no_bite` | `ok` |
|
|
364
|
+
| `ReleaseResult` | `ok`, `state`, `opened_mm`, `target_rad`, `aborted` | `ok` |
|
|
297
365
|
| `EnableResult` | `ok`, `state`, `tries` | `ok` |
|
|
298
366
|
|
|
299
367
|
**Read `ok`.** Three combinations look alarming and are correct:
|
|
@@ -318,6 +386,29 @@ A fourth combination is a failure, and new in this version:
|
|
|
318
386
|
`cycles=0`. Nothing was gripped. If you see this, the closing leg is being starved — a stale
|
|
319
387
|
state read, or friction the mechanism's own budget cannot overcome.
|
|
320
388
|
|
|
389
|
+
A fifth is a refusal:
|
|
390
|
+
|
|
391
|
+
- **`grasp()` with `ok=False, no_bite=True`** means the approach carried its force but never moved
|
|
392
|
+
the jaws: it stopped within `MotionConfig.no_bite_mm` (0.5 mm) of where it started *and* its
|
|
393
|
+
budget (`force_n × 0.1 × press_safety`) was below `MotionConfig.breakaway_nm` (0.2 N·m on this
|
|
394
|
+
unit, so setpoints up to 2.2 N). That is not contact — it is a budget that cannot break static
|
|
395
|
+
friction — and it is exactly the case where handing over the hold would send a jaw with a free
|
|
396
|
+
stroke ahead of it into the torque-only frames and let it accelerate. So the hold is never
|
|
397
|
+
entered, the call releases in place, and `cycles` is 0. `stalled` and `reached` are both `False`
|
|
398
|
+
on this path. The remedy is a setpoint above the breakaway (~2.5 N here), not a longer hold.
|
|
399
|
+
Above the breakaway a zero-displacement stop *is* contact and is held normally: a part already
|
|
400
|
+
against the open jaw, or a re-grasp in place after `release(abort=True)`, still grips.
|
|
401
|
+
|
|
402
|
+
Two edges worth knowing. An approach that starts within `reach_tol` (0.9 mm) of the closed stop
|
|
403
|
+
gets no stall verdict at all — it reports `reached` instead, and the hold has nothing to run
|
|
404
|
+
because the jaws are already on the end stop. And the refusal is about the budget, not the part:
|
|
405
|
+
if a grippy part sits at the start pose *and* the setpoint is below the breakaway, the grasp is
|
|
406
|
+
refused rather than risked.
|
|
407
|
+
|
|
408
|
+
- **`grasp()` ended by a release** returns `released=True`: `ok=True` when the opening completed,
|
|
409
|
+
`ok=False` when it was an E-stop (`release(abort=True)`), which sends no opening move. `reached`
|
|
410
|
+
and `stalled` still describe the closing leg; `state` is the pose after the release.
|
|
411
|
+
|
|
321
412
|
Stalling far from the limit gives `ok=False`: something blocked the travel. The diagnostic fields
|
|
322
413
|
— `final_cmd_rad`, `steps`, `state` — are what you log when it is false.
|
|
323
414
|
|
|
@@ -369,11 +460,14 @@ with LiteGrip("can0") as gripper:
|
|
|
369
460
|
| `force_n` | `20.0` | default `grasp` force |
|
|
370
461
|
| `force_ramp_n_s` | `20.0` | rate the held force climbs to its setpoint, N/s |
|
|
371
462
|
| `hold_interval` | `0.2` | force-hold slice length, seconds |
|
|
463
|
+
| `release_wait_s` | `10.0` | how long `release()` waits for the grasp thread when `timeout_s` is not given |
|
|
372
464
|
| `hold_runaway_rad` | `0.05` | past the closed stop by this much, the force hold drops the torque and stops |
|
|
373
465
|
| `margin` | `0.05` | fraction of travel kept in reserve from the stop by the `limit_target` helper; no shipped call reaches it |
|
|
374
466
|
| `max_lead_mm` | `4.0` | cap on how far the command may lead the measured position, on moves that carry no force setpoint |
|
|
375
467
|
| `stop_lead_mm` | `0.7` | the same cap on the approach to a stop, so the pressing torque stays bounded |
|
|
376
468
|
| `press_safety` | `0.9` | fraction of the setpoint a force-carrying approach may spend |
|
|
469
|
+
| `no_bite_mm` | `0.5` | a force-carrying approach that stops this close to its start pose is refused, not read as contact (see `grasp()` above) |
|
|
470
|
+
| `breakaway_nm` | `0.2` | measured static-friction breakaway; only a budget below it makes a zero-displacement stop a refusal rather than contact |
|
|
377
471
|
| `reach_tol` | `0.02` | position tolerance for `reached`, radians |
|
|
378
472
|
| `stop_tol` | `0.03` | how close to the calibrated stop the jaw must park to count as pressed home |
|
|
379
473
|
| `settle_s` | `0.3` | time spent holding the target after the ramp |
|
|
@@ -500,8 +594,8 @@ python3 examples/trajectory.py --play pick --repeat 3
|
|
|
500
594
|
- **A capture that did not fill raises** rather than returning a short recording as if it were
|
|
501
595
|
whole.
|
|
502
596
|
- **Record without zero-gravity when something else drives.** `record_start(zero_gravity=False)`
|
|
503
|
-
only *reads* state, so the caller may run a `grasp()` or a move sequence
|
|
504
|
-
capture it.
|
|
597
|
+
only *reads* state, so the caller may run a `grasp()` (ended with `release()`) or a move sequence
|
|
598
|
+
from another thread and capture it.
|
|
505
599
|
- `LITEGRIP_TRAJ_DIR` moves the trajectory directory. Recording, replay and teleop are mutually
|
|
506
600
|
exclusive and raise `TrajectoryBusyError` / `TeleopBusyError`; `disconnect()` stops whichever is
|
|
507
601
|
running.
|
|
@@ -556,10 +650,9 @@ the config as their first argument rather than being called on the gripper.
|
|
|
556
650
|
| `CommandError` naming a calibration | No calibration loaded for this channel. Call `load_calibration()`. |
|
|
557
651
|
| `ConnectError`, or no status frame ever | `can0` is down, or the bitrate is not 1 Mbit/s. See step 2. |
|
|
558
652
|
| `HardwareError` from `enable()` | The motor never reported `err == 1`. Check power, then `clear_fault()`. |
|
|
559
|
-
| The jaws move the wrong way | The unit is reverse-mounted, not normal. Construct with `mount="reverse"`. |
|
|
560
653
|
| `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. |
|
|
561
654
|
| `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. |
|
|
562
|
-
| 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.
|
|
655
|
+
| 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). |
|
|
563
656
|
| 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. |
|
|
564
657
|
| `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. |
|
|
565
658
|
|
|
@@ -14,7 +14,7 @@ name = "litegrip-python"
|
|
|
14
14
|
# Python repositories the placeholder has to be plain `0.0.0`. The nearby
|
|
15
15
|
# `0.0.0+semantic-release` spelling is valid PEP 440 but PyPI rejects local version
|
|
16
16
|
# labels, so it would only move the failure to upload time.
|
|
17
|
-
version = "1.1
|
|
17
|
+
version = "1.2.1"
|
|
18
18
|
description = "Python SDK for the LiteGrip lightweight robotic gripper series"
|
|
19
19
|
readme = "README.md"
|
|
20
20
|
requires-python = ">=3.10"
|
|
@@ -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
|
|
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",
|