Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 24 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ young. Ask both when the difference matters.
| `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. |
| `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. |
| `home()` → `MoveResult` | Ramps to the calibrated closed position. |
| `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). |
| `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). |
| `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. |
| `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). |
| `goto(position_mm, kp=None, kd=None, duration=0.5)` → `MoveResult` | Ramp to a position in millimetres. |
Expand Down Expand Up @@ -359,8 +359,8 @@ What it *means*, and what to check, is per action:

| Type | Fields | `bool()` is |
| --- | --- | --- |
| `MoveResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `limit_rad`, `final_cmd_rad`, `steps`, `protected`, `released` | `ok` |
| `GraspResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `force_n`, `cycles`, `travel_guard`, `released` | `ok` |
| `MoveResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `limit_rad`, `final_cmd_rad`, `steps`, `protected`, `released`, `no_bite` | `ok` |
| `GraspResult` | `ok`, `reached`, `stalled`, `state`, `target_rad`, `force_n`, `cycles`, `travel_guard`, `released`, `no_bite` | `ok` |
| `ReleaseResult` | `ok`, `state`, `opened_mm`, `target_rad`, `aborted` | `ok` |
| `EnableResult` | `ok`, `state`, `tries` | `ok` |

Expand All @@ -386,6 +386,25 @@ A fourth combination is a failure, and new in this version:
`cycles=0`. Nothing was gripped. If you see this, the closing leg is being starved — a stale
state read, or friction the mechanism's own budget cannot overcome.

A fifth is a refusal:

- **`grasp()` with `ok=False, no_bite=True`** means the approach carried its force but never moved
the jaws: it stopped within `MotionConfig.no_bite_mm` (0.5 mm) of where it started *and* its
budget (`force_n × 0.1 × press_safety`) was below `MotionConfig.breakaway_nm` (0.2 N·m on this
unit, so setpoints up to 2.2 N). That is not contact — it is a budget that cannot break static
friction — and it is exactly the case where handing over the hold would send a jaw with a free
stroke ahead of it into the torque-only frames and let it accelerate. So the hold is never
entered, the call releases in place, and `cycles` is 0. `stalled` and `reached` are both `False`
on this path. The remedy is a setpoint above the breakaway (~2.5 N here), not a longer hold.
Above the breakaway a zero-displacement stop *is* contact and is held normally: a part already
against the open jaw, or a re-grasp in place after `release(abort=True)`, still grips.

Two edges worth knowing. An approach that starts within `reach_tol` (0.9 mm) of the closed stop
gets no stall verdict at all — it reports `reached` instead, and the hold has nothing to run
because the jaws are already on the end stop. And the refusal is about the budget, not the part:
if a grippy part sits at the start pose *and* the setpoint is below the breakaway, the grasp is
refused rather than risked.

- **`grasp()` ended by a release** returns `released=True`: `ok=True` when the opening completed,
`ok=False` when it was an E-stop (`release(abort=True)`), which sends no opening move. `reached`
and `stalled` still describe the closing leg; `state` is the pose after the release.
Expand Down Expand Up @@ -447,6 +466,8 @@ with LiteGrip("can0") as gripper:
| `max_lead_mm` | `4.0` | cap on how far the command may lead the measured position, on moves that carry no force setpoint |
| `stop_lead_mm` | `0.7` | the same cap on the approach to a stop, so the pressing torque stays bounded |
| `press_safety` | `0.9` | fraction of the setpoint a force-carrying approach may spend |
| `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) |
| `breakaway_nm` | `0.2` | measured static-friction breakaway; only a budget below it makes a zero-displacement stop a refusal rather than contact |
| `reach_tol` | `0.02` | position tolerance for `reached`, radians |
| `stop_tol` | `0.03` | how close to the calibrated stop the jaw must park to count as pressed home |
| `settle_s` | `0.3` | time spent holding the target after the ramp |
Expand Down
24 changes: 21 additions & 3 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,7 @@ print(state.position_mm, state.force_n, state.timestamp)
| `open(speed_mm_s=None, *, progress=None)` → `MoveResult` | 爬坡走向标定的张开侧限位。若 `GripperConfig.work_stroke_mm` 有值,则停在那段行程处 —— 出厂标定设的是 `80.0`,对着这台机器 85 mm 的行程,所以裸调 `open()` 会在距张开端 5 mm 处停下。 |
| `close(speed_mm_s=None, *, progress=None)` → `MoveResult` | 一样,方向朝闭合侧。`work_stroke_mm` 是张开侧的数字,不改变 `close()` 的落点。 |
| `home()` → `MoveResult` | 爬坡回到标定的闭合位置。 |
| `grasp(force_n=None, hold_s=0.0, *, progress=None)` → `GraspResult` | 闭到工件上(中间没东西就闭到闭合侧标定限位),再爬到 `force_n` N 并保持。闭合段就把 `force_n` 当力矩预算,所以顶到工件时压得不会比设定值更狠。保力只在爪子**停下来**之后接手:`stalled=True`(爪子间夹着东西)或 `reached=True`(空爪闭到底)。`hold_s=0` 表示保持到故障、失控监视触发或 Ctrl+C。`force_n=None` 用 `MotionConfig.force_n`(20 N)。 |
| `grasp(force_n=None, hold_s=0.0, *, progress=None)` → `GraspResult` | 闭到工件上(中间没东西就闭到闭合侧标定限位),再爬到 `force_n` N 并保持。闭合段就把 `force_n` 当力矩预算,所以顶到工件时压得不会比设定值更狠。保力只在爪子**停下来**之后接手:`stalled=True`(爪子间夹着东西)或 `reached=True`(空爪闭到底)。但**从起点就没动过**就停下、且预算低于 `MotionConfig.breakaway_nm` 时不算接触 —— 那是预算压不出静摩擦 —— 这种情形调用原地撤力、返回 `no_bite=True`,不进保力段。`hold_s=0` 表示保持到故障、失控监视触发或 Ctrl+C。`force_n=None` 用 `MotionConfig.force_n`(20 N)。 |
| `goto(position_mm, kp=None, kd=None, duration=0.5)` → `MoveResult` | 爬坡走到毫米目标。 |
| `goto_rad(position_rad, kp=None, kd=None, dq_target=0.0, tau_feedforward=0.0, duration=0.5)` → `MoveResult` | 一样的,单位 rad。`dq_target` 与 `tau_feedforward` 必须是 0:速度前馈由斜坡按自己的排程给出,所以这两个值一律拒绝并抛 `CommandError`,不是静默忽略。 |
| `move_to(target_rad, kp=None, kd=None, tau_feedforward=0.0, duration=1.0)` → `MoveResult` | 和 `goto_rad` 一样,只是 `duration` 的默认值更长。 |
Expand Down Expand Up @@ -309,8 +309,8 @@ print(abs(cfg.pos_open_rad - cfg.pos_closed_rad) * cfg.rad_to_mm) # 行程,m

| 类型 | 字段 | `bool()` 是 |
| --- | --- | --- |
| `MoveResult` | `ok`、`reached`、`stalled`、`state`、`target_rad`、`limit_rad`、`final_cmd_rad`、`steps`、`protected`、`released` | `ok` |
| `GraspResult` | `ok`、`reached`、`stalled`、`state`、`target_rad`、`force_n`、`cycles`、`travel_guard` | `ok` |
| `MoveResult` | `ok`、`reached`、`stalled`、`state`、`target_rad`、`limit_rad`、`final_cmd_rad`、`steps`、`protected`、`released`、`no_bite` | `ok` |
| `GraspResult` | `ok`、`reached`、`stalled`、`state`、`target_rad`、`force_n`、`cycles`、`travel_guard`、`released`、`no_bite` | `ok` |
| `EnableResult` | `ok`、`state`、`tries` | `ok` |

**看 `ok`。** 下面三种组合看着吓人,其实都是对的:
Expand All @@ -332,6 +332,22 @@ print(abs(cfg.pos_open_rad - cfg.pos_closed_rad) * cfg.rad_to_mm) # 行程,m
撤力。此时调用改为原地撤力,报 `cycles=0`。什么也没夹住。见到它就说明闭合段被饿着了 ——
读数过期,或者机构自身预算吃不掉的摩擦。

第五种组合是拒夹:

- **`grasp()` 返回 `ok=False, no_bite=True`**,意思是接近段带着力,却**从起点就没推动过**
爪子:停住时离起始位置还不到 `MotionConfig.no_bite_mm`(0.5 mm),**而且**这一段的预算
(`force_n × 0.1 × press_safety`)低于 `MotionConfig.breakaway_nm`(这台机器 0.2 Nm,
也就是设定值 2.2 N 及以下)。这不是接触 —— 是力矩预算压不出脱离静摩擦需要的力 —— 而这
恰好就是交接会让爪子带着一整段自由行程冲进纯力矩帧、一路加速的情形。所以保力段一帧都不
发,调用原地撤力,`cycles` 为 0,`stalled` 与 `reached` 在这条路上都是 `False`。要救它得
把设定值抬到脱离力之上(这台机器约 2.5 N),不是把保力拉长。预算在脱离力之上时,零位移
**就是**顶到了东西,照常交接:工件已经贴在张开侧、或者 `release(abort=True)` 之后原地
重夹,都还能夹住。

两个边界值得知道。起点落在闭合端 `reach_tol`(0.9 mm)以内时整段不判堵转 —— 它报
`reached`,保力段前面本来也没有自由行程。另外判的是预算、不是工件:粘手的工件正好摆在起点、
而设定值又低于脱离力时,这一次夹取会被拒。

在离限位很远的地方堵转,才会给 `ok=False`:有东西挡住了行程。为假时该记的,就是那几个诊断
字段 —— `final_cmd_rad`、`steps`、`state`。

Expand Down Expand Up @@ -386,6 +402,8 @@ with LiteGrip("can0") as gripper:
| `max_lead_mm` | `4.0` | 不带力设定值的运动里,指令允许领先实测位置的上限 |
| `stop_lead_mm` | `0.7` | 接近限位时的同一上限,用来压住压紧力矩 |
| `press_safety` | `0.9` | 带力的接近段最多能花掉设定值的多少 |
| `no_bite_mm` | `0.5` | 带力接近段离起点这么近就停住时,判为没咬住、不交接(见上文 `grasp()`) |
| `breakaway_nm` | `0.2` | 实测静摩擦脱离力矩;只有预算低于它时,零位移停住才算拒夹而不是接触 |
| `reach_tol` | `0.02` | 判定 `reached` 的位置容差,rad |
| `stop_tol` | `0.03` | 要算「压到位」,爪子得停到离标定限位多近 |
| `settle_s` | `0.3` | 爬坡结束后在目标上停留的时间 |
Expand Down
38 changes: 36 additions & 2 deletions examples/grasp_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -274,7 +274,8 @@ def _report(result, trace: Trace, cfg, motion, label: str, grasped: bool) -> str
st = result.state
lines = [
f" ok={result.ok} reached={result.reached} stalled={result.stalled} "
f"runaway_watch={result.travel_guard} err={st.error_code}",
f"no_bite={result.no_bite} runaway_watch={result.travel_guard} "
f"err={st.error_code}",
f" stopped at {st.position_mm:+.1f} mm ({st.position_rad:+.6f} rad), "
f"empty target was {to_mm(cfg, result.target_rad):+.1f} mm, "
f"off by {abs(st.position_rad - result.target_rad) * cfg.rad_to_mm:.2f} mm",
Expand Down Expand Up @@ -329,14 +330,45 @@ def _hold_problem(result) -> str | None:
"the closed stop by more than MotionConfig.hold_runaway_rad, so "
"the torque was dropped — either nothing is stopping the closing "
"direction, or the calibration no longer describes the travel")
if result.no_bite:
# Not a hold problem at all: grasp() refused the hand-over, so no hold
# ran and there was no fault. The judges name this
# (_no_bite_problem); here it must not be mistaken for "err=0".
return None
if not result.ok:
return f"the hold phase ended abnormally (err={result.state.error_code})"
return None


def _judge_empty(result, trace: Trace, cfg, _motion) -> list[str]:
def _no_bite_problem(result, motion) -> str:
"""The one ending that is a refusal rather than a motion, said plainly.

``grasp()`` dropped the torque because the approach never moved the jaws
and its budget was below the breakaway (``MotionConfig.breakaway_nm``).
Reporting that as "the closing leg ran out of frames while still
travelling" — the message the other endings get — points the operator the
opposite way, and "err=0" reads like a fault that did not happen.
"""
floor_n = motion.breakaway_nm / (N_TO_NM * motion.press_safety)
return (f"refused, not held (no_bite=True): the closing leg never moved the "
f"jaws. Its budget ({result.force_n:g} N = "
f"{result.force_n * N_TO_NM:g} Nm, of which the approach may spend "
f"{motion.press_safety:g}) is below the breakaway "
f"({motion.breakaway_nm:g} Nm), so grasp() dropped the torque "
f"instead of handing the jaws to the torque-only hold — that would "
f"have powered them across the free stroke. The jaws stopped at "
f"{result.state.position_mm:+.1f} mm. Raise --force above "
f"{floor_n + 0.1:.1f} N (or check whether something is already "
f"against the jaws before closing)")


def _judge_empty(result, trace: Trace, cfg, motion) -> list[str]:
"""Clear jaws: it should reach the closed stop and not report a stall."""
problems = []
if result.no_bite:
# A refusal, not a movement. Everything below judges the closing leg
# and the hold that followed — neither ran.
return [_no_bite_problem(result, motion)]
if not result.reached:
short_mm = (abs(result.state.position_rad - result.target_rad)
* cfg.rad_to_mm)
Expand Down Expand Up @@ -372,6 +404,8 @@ def _judge_empty(result, trace: Trace, cfg, _motion) -> list[str]:
def _judge_loaded(result, trace: Trace, cfg, motion) -> list[str]:
"""An object between the jaws: it should stall early and then hold."""
problems = []
if result.no_bite:
return [_no_bite_problem(result, motion)]
short = _stall_ramp_mm(result, trace, cfg, motion)
if short is not None:
# stalled could not have become True here, so saying it did not fire is
Expand Down
Loading
Loading