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
77 changes: 71 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,30 +1,33 @@
# litearm-python

Python SDK for the LiteArm robotic arm: drive the arm from a PC over one USB serial cable,
straight to its firmware — no server or middleware in between. Trajectory planning, kinematics
and dynamics are all carried by the firmware.
straight to its firmware — no server or middleware in between. The firmware owns real-time
control and S-curves; the optional SDK model computes local FK/IK/Jacobians and guarded PTPs.

> Full interface reference: [docs/DEVELOPER_GUIDE.md](https://github.com/nexform-tech/litearm-python/blob/main/docs/DEVELOPER_GUIDE.md).

## Features

- **Pure Python**: Python 3.9+, poses are plain lists / tuples, no numpy needed
- **A single dependency**: `pyserial`, nothing else
- **Lightweight by default**: the normal serial install depends only on `pyserial`
- **Direct over USB**: one cable to the firmware, no server in between
- **The firmware does the planning**: kinematics and dynamics live there; the PC sends points and decides arrival
- **Optional local kinematics**: Pinocchio uses the packaged URDF for FK/IK/Jacobians
- **Execution stays in firmware**: STM32 enforces velocity, acceleration, jerk and synchronized S-curves
- **Full motion API**: joint moves, Cartesian lines / arcs / waypoints, hand-guiding
- **Tool point (TCP) offset**: a host-side xyz + rpy layer, so `move_*` and `ik()` take tool
poses while `get_tcp()` keeps returning the flange
- **Payload identification**: measure the mass and centre of mass of the end-of-arm load from
the arm's own torque, then hand the result to `set_payload()`
- **Optional self-collision checks**: Pinocchio/hpp-fcl checks the packaged URDF meshes before
a predictable joint path is sent; the normal serial SDK stays dependency-light
- **Safety built in**: fail-closed in child processes, a dedicated emergency stop, and every irreversible command flagged

## Install

| Item | Requirement |
| --- | --- |
| Python | 3.9 or later |
| Dependencies | `pyserial >= 3.4` (the only one) |
| Default dependency | `pyserial >= 3.4` (`robotics` extras are optional) |
| Firmware | `Litearm1.5.0` or later |
| Connection | USB CDC serial, VID:PID `1d50:606f` |

Expand All @@ -35,6 +38,47 @@ pip install litearm-python
python3 -c "import litearm; print(litearm.__version__)" # verify
```

Local kinematics and self-collision checking are an optional, heavier install:

```bash
pip install "litearm-python[robotics]"
```

If the shell has sourced ROS, its `PYTHONPATH` and `LD_LIBRARY_PATH` can inject
a Pinocchio build for another Python ABI. On `pinocchio_pywrap_default` or
`undefined symbol` errors, run with
`env -u PYTHONPATH -u LD_LIBRARY_PATH .venv/bin/python your_script.py`.

`CollisionModel()` automatically loads the wheel's URDF and nine collision meshes. Its
`in_collision(q)` method returns a boolean; `colliding_pairs(q)` returns all colliding geometry
name pairs; `minimum_distance(q)` returns the nearest non-adjacent-link clearance. All require
exactly seven finite joint angles. Each checker owns its mutable
Pinocchio data and serializes calls on that instance, so it can be shared across threads.

Use it for planning/preflight work, not a real-time loop. For path checking, sample every
configuration along the path. In particular, `movej_sync` follows the joint-space line and can
be checked that way; ordinary `movej` drives independent per-axis S-curves, so checking only its
endpoints does not prove the unknown intermediate path collision-free.

```text
collision = pa.CollisionModel()
collision.in_collision([0.0] * 7)
collision.colliding_pairs(q)
```

For VR/servo control, the exact differential-IK backend from `lite-vr` is also
available without changing the firmware pose solver `Arm.ik()`:

```bash
pip install "litearm-python[ik]"
```

Call `litearm.exact_ik.exact_task_velocity(J, twist, lower, upper)` with a
Jacobian and velocity/range box. It either delivers the complete twist or
returns zero velocity with a structured failure reason. Use
`bounded_task_velocity(...)` when partial, damped motion is preferable to
holding position. The Jacobian and twist must use the same reference frame.

Or install from a checkout:

```bash
Expand Down Expand Up @@ -219,9 +263,29 @@ state = arm.get_state().value
print(state.q, state.dq, state.tau) # joint angles / velocity / torque
print(state.enabled, state.faulted) # enabled? faulted?
print(arm.get_tcp().value) # flange pose (firmware forward kinematics)
print(arm.ik((0.30, 0.0, 0.35, 3.1416, 0.0, 0.0))) # pose → joint angles
print(arm.ik((0.30, 0.0, 0.35, 3.1416, 0.0, 0.0))) # firmware remote IK

q = state.q
print(arm.kinematics.fk(q, frame="flange")) # SDK-local FK, no command sent
print(arm.kinematics.jacobian(q).sigma_min) # SDK-local Jacobian
q_seed = [0.0, -0.5, 0.0, -1.0, 0.0, 0.5, 0.0]
target_pose = arm.kinematics.fk(q_seed, frame="flange")
solution = arm.kinematics.ik(target_pose, q_seed=q_seed, frame="flange")
# arm.kinematics.move_pose(target_pose, speed=0.2) # preflight, then one 0x07
```

`arm.kinematics.move_pose()` seeds from fresh state, reads the STM32 runtime soft limits, and
samples the joint line at no more than 0.02 rad to check limit margin, self-collision/5 mm
clearance and `sigma_min >= 0.05`. If the start moves during preflight it replans once, then
fails closed on a second drift. A passing move sends exactly one `movej_sync`; STM32 still owns
velocity, acceleration and jerk limits. This checks **self-collision only**—not benches, people,
or external obstacles.

The IK residual is numerical convergence, not guaranteed physical TCP accuracy. `move_pose()`
waits with the existing joint-space `q_tol` / `dq_tol` criteria, so tracking, encoder and calibration
errors still apply. Evaluate `arm.kinematics.fk(returned_state.q)` when the measured endpoint matters;
hardware review saw about 0.7-1.1 mm error on 2-10 mm test moves (informative, not a specification).

### Tool point (TCP) offset

The firmware's TCP *is* the flange. To control a tool point instead, declare the offset once —
Expand Down Expand Up @@ -488,6 +552,7 @@ See [examples/README.md](https://github.com/nexform-tech/litearm-python/blob/mai
- `02_movej.py` — joint motion
- `03_move_p.py` — Cartesian point to point
- `04_ik_tcp.py` — inverse kinematics and the current pose
- `10_local_kinematics.py` — SDK-local FK/IK/Jacobian and guarded pose PTP
- `06_cartesian.py` — Cartesian lines / arcs / waypoints
- `07_vel_jitter_trace.py` — 300 Hz per-tick capture

Expand Down
72 changes: 67 additions & 5 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,30 @@
# litearm-python

LiteArm 机械臂的 Python SDK:从 PC 经一根 USB 串口线直连固件驱动机械臂 ——
不需要服务端或中间件。轨迹规划、运动学、动力学全部由固件承担。
不需要服务端或中间件。固件负责实时控制和 S 曲线;SDK 可选在本地计算
FK/IK/Jacobian,并在安全预检后下发同步关节 PTP。

> 完整接口说明见 [docs/DEVELOPER_GUIDE.zh-CN.md](docs/DEVELOPER_GUIDE.zh-CN.md)。

## 特性

- **纯 Python**:Python 3.9+,位姿就是普通的 list / tuple,不需要 numpy
- **单一依赖**:只有 `pyserial`
- **默认轻依赖**:普通串口安装只有 `pyserial`
- **USB 直连**:一根线接到固件,不经过任何服务端
- **规划在固件里**:运动学、动力学都在固件里,PC 侧只发点、判到位
- **本地运动学可选**:Pinocchio 使用随包 URDF 算 FK/IK/Jacobian;默认串口安装不变
- **执行仍在固件里**:速度、加速度、jerk 限幅和同步 S 曲线由 STM32 完成
- **完整运动接口**:关节运动、笛卡尔直线 / 圆弧 / 多路点、拖动示教
- **负载辨识**:从臂自身的力矩里量出末端负载的质量与质心,结果直接交给 `set_payload()`
- **可选自碰检测**:Pinocchio/hpp-fcl 用随包 URDF 网格做规划前检查;默认串口 SDK
仍保持轻依赖
- **安全兜底**:子进程 fail-closed,急停独立入口,不可逆命令逐个标注

## 安装

| 项目 | 要求 |
| --- | --- |
| Python | 3.9 及以上 |
| 依赖 | `pyserial >= 3.4`(唯一依赖) |
| 默认依赖 | `pyserial >= 3.4`(`robotics` 为可选重依赖) |
| 固件 | `Litearm1.5.0` 及以上 |
| 连接 | USB CDC 串口,VID:PID `1d50:606f` |

Expand All @@ -31,6 +35,44 @@ pip install -e .
python3 -c "import litearm; print(litearm.__version__)" # 验证
```

本地运动学与碰撞检测是可选的重依赖能力,按需安装:

```bash
pip install -e ".[robotics]"
```

若当前终端 source 过 ROS,ROS 的 `PYTHONPATH` / `LD_LIBRARY_PATH` 可能把另一 Python
版本的 Pinocchio 动态库注入虚拟环境。遇到 `pinocchio_pywrap_default` 缺失或
`undefined symbol` 时,用
`env -u PYTHONPATH -u LD_LIBRARY_PATH .venv/bin/python your_script.py` 运行。

`CollisionModel()` 会自动加载 wheel 内的 URDF 与 9 个碰撞网格。`in_collision(q)` 返回
是否自碰,`colliding_pairs(q)` 返回全部碰撞几何名称对,`minimum_distance(q)` 返回非相邻
连杆的最小间隙;三者都严格要求 7 个有限关节角。
每个 checker 独占 Pinocchio 的可变模型数据,同一实例的查询会串行化,因此可跨线程共享。

它只用于规划/下发前检查,不应进入实时控制环。路径检测必须沿路径采样每个构型:
`movej_sync` 的中间轨迹是关节空间直线,可以据此检查;普通 `movej` 各轴使用独立 S 曲线,
中间路径不可预测,只检查起终点不能证明整段无碰撞。

```text
collision = pa.CollisionModel()
collision.in_collision([0.0] * 7)
collision.colliding_pairs(q)
```

VR/伺服控制所需的 `lite-vr` 精确微分逆解也已独立提供,不会覆盖固件位姿逆解
`Arm.ik()`:

```bash
pip install -e ".[ik]"
```

向 `litearm.exact_ik.exact_task_velocity(J, twist, lower, upper)` 传雅可比、任务速度和
关节速度/行程盒;它要么完整交付 twist,要么返回零速度及结构化失败原因。不可完整交付时
若希望继续做阻尼降级跟随,可调用 `bounded_task_velocity(...)`。雅可比与 twist 必须采用
同一参考坐标系。

Linux 需要串口权限 —— 先看设备节点本身怎么说:

```bash
Expand Down Expand Up @@ -195,9 +237,28 @@ state = arm.get_state().value
print(state.q, state.dq, state.tau) # 关节角 / 速度 / 力矩
print(state.enabled, state.faulted) # 使能中?有故障?
print(arm.get_tcp().value) # 法兰位姿(固件正运动学)
print(arm.ik((0.30, 0.0, 0.35, 3.1416, 0.0, 0.0))) # 位姿 → 关节角
print(arm.ik((0.30, 0.0, 0.35, 3.1416, 0.0, 0.0))) # 固件远程 IK

q = state.q
print(arm.kinematics.fk(q, frame="flange")) # SDK 本地 FK,不发命令
print(arm.kinematics.jacobian(q).sigma_min) # SDK 本地 Jacobian
q_seed = [0.0, -0.5, 0.0, -1.0, 0.0, 0.5, 0.0]
target_pose = arm.kinematics.fk(q_seed, frame="flange")
solution = arm.kinematics.ik(target_pose, q_seed=q_seed, frame="flange")
# arm.kinematics.move_pose(target_pose, speed=0.2) # 预检后仅发一条 0x07
```

`arm.kinematics.move_pose()` 使用当前状态为种子、读取 STM32 运行时软限位,并对实际将执行的
关节直线按不大于 0.02 rad 的步长检查限位余量、自碰/5 mm 间隙和
`sigma_min >= 0.05`。预检期间起点变化会重算一次,再变化则拒绝。通过后只调用一次
`movej_sync`;STM32 继续负责速度、加速度和 jerk 限制。该检查只覆盖机械臂自碰,**不检测
工作台、人员和外部障碍物**。

IK 残差表示数值求解收敛,不等于真机 TCP 到位精度。`move_pose()` 仍按现有的关节空间
`q_tol` / `dq_tol` 判据等待,最终误差还包含跟踪、编码器和标定误差;对精度敏感时请对返回的
`RobotState.q` 再调用 `arm.kinematics.fk()`。本次真机 review 的 2–10 mm 小步运动误差约
0.7–1.1 mm,该数据仅供参考,不是规格承诺。

### 工具点(TCP)偏移

固件的 TCP 就是法兰。想控工具尖就声明一次偏移 —— 之后 `move_p` / `move_l` / `move_c` /
Expand Down Expand Up @@ -444,6 +505,7 @@ p.start()
- `02_movej.py` — 关节运动
- `03_move_p.py` — 笛卡尔点到点
- `04_ik_tcp.py` — 逆解与当前位姿
- `10_local_kinematics.py` — SDK 本地 FK/IK/Jacobian 与安全位姿 PTP
- `06_cartesian.py` — 笛卡尔直线 / 圆弧 / 多路点
- `07_vel_jitter_trace.py` — 300 Hz 逐拍采集

Expand Down
31 changes: 26 additions & 5 deletions docs/DEVELOPER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

Python SDK for the LiteArm robotic arm, talking straight to the firmware over USB serial.

Planning, kinematics and dynamics live in the firmware; the PC side only encodes frames, sends
commands and decides arrival. A pose is 6 numbers (list or tuple), and `pyserial` is the only
dependency.
Real-time control, S-curves and dynamics live in firmware. The optional SDK model adds local
FK/IK/Jacobians and guarded joint PTP using the packaged URDF. A pose is 6 numbers (list or
tuple), and the default install still depends only on `pyserial`.

## Contents

Expand All @@ -30,6 +30,7 @@ dependency.

```bash
pip install -e . # install
pip install -e ".[robotics]" # local kinematics, self-collision and clearance checks
```

When `pip` and `python` point at different interpreters, use `python -m pip`.
Expand Down Expand Up @@ -299,6 +300,10 @@ Failures raise `CartesianPlanError` and reject the whole move — the arm does n
get_tcp(timeout=0.6) -> Msg[Optional[tuple]]
get_tool_tcp(timeout=0.6) -> Msg[Optional[tuple]]
ik(pose, q_seed=None, timeout=3.0) -> list[float]
kinematics.fk(q, frame="tool") -> tuple[6]
kinematics.jacobian(q, frame="tool") -> JacobianResult
kinematics.ik(pose, q_seed=None, frame="tool") -> IKSolution
kinematics.move_pose(pose, speed=0.2, frame="tool") -> RobotState
set_tcp_offset(xyz=(0.0, 0.0, 0.0), rpy=(0.0, 0.0, 0.0), *, payload_mass=None, payload_com=None)
clear_tcp_offset()
tcp_offset
Expand All @@ -312,10 +317,26 @@ load_tool(path=None) -> bool
| `get_tcp()` | The **flange** (`ee_link`) pose from firmware forward kinematics, 6 numbers. Never affected by `set_tcp_offset()` |
| `get_tool_tcp()` | The same pose with the tool offset applied — where the tool point actually is |
| `ik(pose, q_seed=None)` | Inverse kinematics. It may return another equally valid branch, so a result far from `q_seed` is not necessarily an error |
| `kinematics.fk/ik/jacobian` | SDK-local calculations using the packaged URDF; no firmware IK/FK command is sent. `frame="tool"` applies the current TCP offset |
| `kinematics.move_pose()` | Local continuation IK plus full joint-line preflight, then exactly one `CMD_MOVE_J_SYNC 0x07` |
| `set_tcp_offset(xyz, rpy)` | Declares where the tool point sits. See below: this is a host-side layer, not a firmware feature |

There is no `fk(q)`. The PC side carries no kinematic model, so forward kinematics is only
`get_tcp()`.
`Arm.ik()` and `get_tcp()` remain firmware-remote APIs. `arm.kinematics.*` explicitly selects
the SDK-local model, while `litearm.exact_ik.exact_task_velocity()` is differential velocity IK.

`move_pose()` requires an enabled, fault-free arm outside zero-gravity and Cartesian planning.
It reads the STM32 runtime soft limits and samples the actual joint line at at most 0.02 rad,
checking a 0.01 rad limit margin, self-collision/non-adjacent-link 5 mm clearance, and
`sigma_min >= 0.05`. It replans once if the start drifts over 0.03 rad and rejects a second
drift. Non-finite values, model errors, and unavailable distances all fail before a motion frame
is sent. This protects against **self-collision only**, not benches, people, or external obstacles.

The IK position/orientation residuals report numerical solver convergence; they are not a promise
of physical arrival accuracy. `move_pose()` ultimately waits with the same joint-space criteria as
`movej_sync` (`q_tol`, `dq_tol`, and `arrive_frames`), so encoder, tracking, calibration, and firmware
arrival tolerance remain in the final TCP error. Use `kinematics.fk(returned_state.q)` to evaluate
the measured final pose when accuracy matters. Hardware review observed roughly 0.7-1.1 mm TCP
error for 2-10 mm test moves; that measurement is informative, not a universal specification.

#### Tool point (TCP) offset

Expand Down
29 changes: 25 additions & 4 deletions docs/DEVELOPER_GUIDE.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,9 @@

LiteArm 机械臂的 Python SDK,USB 串口直连固件。

规划、运动学、动力学都在固件里,PC 侧只编解码帧、下发命令、判到位。
位姿是 6 个数(list 或 tuple),只依赖 `pyserial`。
实时控制、S 曲线和动力学在固件里;SDK 还可选提供基于随包 URDF 的本地
FK/IK/Jacobian 与安全关节 PTP。位姿是 6 个数(list 或 tuple),默认安装只依赖
`pyserial`。

## 目录

Expand All @@ -23,12 +24,13 @@ LiteArm 机械臂的 Python SDK,USB 串口直连固件。
## 1. 环境要求与安装

- Python **3.9 及以上**
- `pyserial >= 3.4`(唯一依赖)
- `pyserial >= 3.4`(默认安装唯一依赖)
- 固件 **`Litearm1.5.0` 及以上**,版本串为 `Litearm<主.次.修>-{7J|1J}`
- Linux 需串口权限:`sudo usermod -aG dialout $USER`(重新登录生效)

```bash
pip install -e . # 安装
pip install -e ".[robotics]" # 本地运动学、自碰与间隙检查
```

`pip` 与 `python` 指向不同解释器时用 `python -m pip`。
Expand Down Expand Up @@ -290,6 +292,10 @@ set_speed(percent)
get_tcp(timeout=0.6) -> Msg[Optional[tuple]]
get_tool_tcp(timeout=0.6) -> Msg[Optional[tuple]]
ik(pose, q_seed=None, timeout=3.0) -> list[float]
kinematics.fk(q, frame="tool") -> tuple[6]
kinematics.jacobian(q, frame="tool") -> JacobianResult
kinematics.ik(pose, q_seed=None, frame="tool") -> IKSolution
kinematics.move_pose(pose, speed=0.2, frame="tool") -> RobotState
set_tcp_offset(xyz=(0.0, 0.0, 0.0), rpy=(0.0, 0.0, 0.0), *, payload_mass=None, payload_com=None)
clear_tcp_offset()
tcp_offset
Expand All @@ -303,9 +309,24 @@ load_tool(path=None) -> bool
| `get_tcp()` | **法兰**(`ee_link`)位姿,来自固件正运动学,6 个数。**不受 `set_tcp_offset()` 影响** |
| `get_tool_tcp()` | 同一姿态套上工具偏移 —— 工具点此刻在哪 |
| `ik(pose, q_seed=None)` | 反解。可能返回另一个同样有效的分支,与 `q_seed` 差得远未必是错误 |
| `kinematics.fk/ik/jacobian` | 使用随包 URDF 在 SDK 本地计算,不发送固件 IK/FK 命令;`frame="tool"` 应用当前 TCP offset |
| `kinematics.move_pose()` | 本地连续 IK + 完整关节直线预检,通过后只发一次 `CMD_MOVE_J_SYNC 0x07` |
| `set_tcp_offset(xyz, rpy)` | 声明工具点位置。这是**宿主侧**一层换算,不是固件能力 —— 见下 |

没有 `fk(q)`。PC 侧不带运动学模型,正运动学只有 `get_tcp()` 这一条路。
`Arm.ik()` 与 `get_tcp()` 保持为固件远程接口;`arm.kinematics.*` 明确表示 SDK 本地模型,
`litearm.exact_ik.exact_task_velocity()` 则是速度级微分 IK,三者不要混用。

`move_pose()` 要求设备已使能、无故障、非零重力且没有外部笛卡尔规划在途。它每次读取
STM32 运行时软限位,沿实际执行的 `q(s)=q0+s(q1-q0)` 以最多 0.02 rad 步长检查 0.01 rad
限位余量、非相邻连杆 5 mm 间隙、自碰和 `sigma_min >= 0.05`。预检后起点漂移超过
0.03 rad 会重算一次,再漂移即拒绝。任何非有限值、模型异常或距离不可得都在发运动帧前
失败。这里只能保证自碰安全,**不能检测工作台、人员或外部障碍物**。

IK 返回的位置/姿态残差表示数值求解是否收敛,**不是机械臂物理到位精度承诺**。
`move_pose()` 最终仍按 `movej_sync` 的关节空间判据(`q_tol`、`dq_tol`、`arrive_frames`)
等待,因此最终 TCP 误差还包含编码器、跟踪、标定和固件到位容差。对精度敏感时,应对返回的
`RobotState.q` 再调用 `kinematics.fk()` 评估实测终点。本次真机 review 的 2–10 mm 小步运动
测得约 0.7–1.1 mm TCP 误差;该结果仅供参考,不是所有机械臂的统一规格。

#### 工具点(TCP)偏移

Expand Down
Loading
Loading