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
25 changes: 13 additions & 12 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
# 测试门禁。
# 构建门禁。
#
# 跑在 PR 与默认分支的 push 上。⚠ CI 里**绝不**设 LITEARM_LIVE ——
# 那会去开 /dev/ttyACM0 连真机。
# 测试单独成 workflow: 它跑在 PR 上, 而 release workflow 跑在默认分支的 push 上。
# 跑在 PR 与默认分支的 push 上。仓库不包含测试套件:这里只验证包能安装、能 import、
# 能构建,挡住坏掉的安装与 pyproject.toml。
# ⚠ CI 里**绝不**设 LITEARM_LIVE —— 那会去开 /dev/ttyACM0 连真机。
# 构建单独成 workflow: 它跑在 PR 上, 而 release workflow 跑在默认分支的 push 上。
# 两者混在一起会让「发布坏了」和「PR 坏了」互相挡住。
name: CI

Expand All @@ -21,13 +22,13 @@ concurrency:
cancel-in-progress: true # 被取代的 PR 运行没有意义

jobs:
# job id 沿用 `test`: 分支保护可能按 `test (3.x)` 这个 check 名要求合并。
test:
runs-on: ubuntu-22.04
strategy:
fail-fast: false
matrix:
# pyproject 声明 requires-python >= 3.9; 3.10/3.13 两端本地已实测通过
# (569 passed, 2 skipped)。3.9 本机没有解释器, 故未纳入矩阵。
# pyproject 声明 requires-python >= 3.9; 取 3.10/3.13 两端。
python-version: ["3.10", "3.13"]
steps:
- name: Checkout Code
Expand All @@ -38,12 +39,12 @@ jobs:
with:
python-version: ${{ matrix.python-version }}

# tests/conftest.py 只在 LITEARM_LIVE=1 时才连真机; 不设这个变量即纯离线桩。
# CI 里**绝不**设它 —— 那会去开 /dev/ttyACM0。
- name: Test
run: |
pip install -e ".[dev]"
pytest
# 没有测试套件: 装得上、import 得进来, 就说明包结构与依赖没坏。
- name: Install
run: pip install -e .

- name: Import smoke
run: python -c "import litearm; print(litearm.__version__)"

# release workflow 只在合进默认分支之后才打包, 那时 tag 和 GitHub Release
# 都已经生成 —— 构建到那一步才炸, 等于白烧一个版本号。在这里先构建一次,
Expand Down
29 changes: 6 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -502,33 +502,16 @@ python3 examples/01_hello.py

## Development

```bash
pip install -e ".[dev]"
pytest # full offline run, never touches hardware
LITEARM_LIVE=1 pytest # plus hardware tests, moves a little
```

Running the tests does not require installing the package; `tests/conftest.py` sets `sys.path`
itself. Do not set `LITEARM_LIVE` with nobody present, and never call `enter_dfu()` /
`reset_factory()`.

**On a machine with ROS 2 installed, `pytest` dies during collection and none of this repository
is involved**: pytest auto-loads the plugins under `/opt/ros/...` by entry point, and `launch`
needs `lark`, which is not installed:

```
ModuleNotFoundError: No module named 'lark'
```

A virtualenv does not stop it — `PYTHONPATH` takes priority over the venv's `site-packages`.
Either of these works:
This repository does not ship a test suite. Verify a change with a minimal smoke check:

```bash
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest
env -u PYTHONPATH pytest
pip install -e .
python3 -c "import litearm; print(litearm.__version__)"
python3 -m build # after pip install build
```

`-p no:launch_testing` is **not** enough: the `launch_ros` entry point gets loaded anyway.
`litearm.testing.FakeTransport` is still shipped. To write your own offline tests, replace
`SerialTransport` with it; no hardware is needed.

On Windows use `env.ps1` / `env.cmd` and `run_example.ps1` / `run_example.cmd`.

Expand Down
26 changes: 6 additions & 20 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -457,30 +457,16 @@ python3 examples/01_hello.py

## 开发

```bash
pip install -e ".[dev]"
pytest # 离线全流程,不碰真机
LITEARM_LIVE=1 pytest # 额外跑真机用例,会小幅运动
```

跑测试不需要装包,`tests/conftest.py` 会自己设好 `sys.path`。
无人在场时不要设 `LITEARM_LIVE`,也不要调用 `enter_dfu()` / `reset_factory()`。

**本机装了 ROS 2 时 `pytest` 会在收集阶段崩掉,与本仓库无关**:pytest 按 entry point
自动加载 `/opt/ros/...` 里的插件,其中 `launch` 需要未安装的 `lark`:

```
ModuleNotFoundError: No module named 'lark'
```

venv 拦不住它 —— `PYTHONPATH` 的优先级高于 venv 的 `site-packages`。加下面任一个即可:
仓库当前不包含测试套件。改动后用最小冒烟验证:

```bash
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest
env -u PYTHONPATH pytest
pip install -e .
python3 -c "import litearm; print(litearm.__version__)"
python3 -m build # 先 pip install build
```

`-p no:launch_testing` **不够**:`launch_ros` 那个入口照样会被加载。
`litearm.testing.FakeTransport` 仍随包发布。要写自己的离线测试,用它替换
`SerialTransport` 即可,不需要真机。

Windows 用 `env.ps1` / `env.cmd` 与 `run_example.ps1` / `run_example.cmd`。

Expand Down
37 changes: 12 additions & 25 deletions docs/DEVELOPER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,6 @@ dependency.

```bash
pip install -e . # install
pip install -e ".[dev]" # development (includes pytest)
```

When `pip` and `python` point at different interpreters, use `python -m pip`.
Expand Down Expand Up @@ -826,8 +825,7 @@ src/litearm/
```

Every implemented downstream command in the firmware has an entry point. The contract lives in
`_protocol.COMMAND_COVERAGE` and is enforced in both directions by `tests/test_protocol_sync.py`,
which parses the firmware headers directly.
`_protocol.COMMAND_COVERAGE`. This repository no longer ships the protocol-drift test.

---

Expand Down Expand Up @@ -855,27 +853,16 @@ hard-codes 0.10).

## 10. Testing

```bash
pytest # full offline run, never touches hardware
LITEARM_LIVE=1 pytest # plus hardware tests
python tests/test_offline.py # runs without pytest too
```
This repository does not ship a test suite. To write your own offline tests, use the shipped
`litearm.testing.FakeTransport` in place of `SerialTransport`:

```python
import litearm.arm as arm_mod
from litearm.testing import FakeTransport

Running the tests does not require installing the package; `tests/conftest.py` puts `src/` and
`tests/` on `sys.path`. Do not set `LITEARM_LIVE` with nobody present, and never call
`enter_dfu()` / `reset_factory()`.
arm_mod.SerialTransport = lambda port, timeout=0.2: FakeTransport(port="fake", timeout=timeout)
```

| Test | What it guards |
| --- | --- |
| `test_protocol_sync.py` | Protocol drift protection: parses the firmware headers and compares command sets and IDs. The firmware repo location comes from the `LITEARM_FW_DIR` environment variable (default `~/litearm-stm32`); when it cannot be found the test **skips rather than passes** |
| `test_protocol_crc.py` | CRC16 against an external authoritative value plus an independent reference implementation |
| `test_frame_ownership.py` | A frame is not silently destroyed, and its owner receives it |
| `test_transport.py` | Real byte-stream parsing (back-to-back frames / noise / bad frames / partial frames) |
| `test_ack_echo.py` | Replies must echo the original command, so a late old ACK cannot make a new command succeed falsely |
| `test_capability.py` | "The firmware does not have this command" → `UnsupportedByFirmwareError` |
| `test_fork_guard.py` | The fork guard: a child sends nothing |
| `test_zero_g.py` | Hand-guiding keep-alive period / exit cleanup / thread reclamation / command gating |
| `test_live.py` | Hardware smoke test, only with `LITEARM_LIVE=1` |

The stub in `tests/fake_serial.py` must match the real firmware layout, or the offline run gives
a false green and fails on hardware.
Use it only in tests; never replace `SerialTransport` in production code. Hardware verification
requires a connected arm and is the operator's responsibility; never call `enter_dfu()` /
`reset_factory()` with nobody present.
35 changes: 12 additions & 23 deletions docs/DEVELOPER_GUIDE.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@ LiteArm 机械臂的 Python SDK,USB 串口直连固件。

```bash
pip install -e . # 安装
pip install -e ".[dev]" # 开发(含 pytest)
```

`pip` 与 `python` 指向不同解释器时用 `python -m pip`。
Expand Down Expand Up @@ -758,8 +757,8 @@ src/litearm/
testing.py 离线桩(FakeTransport)
```

固件里每条已实现的下行命令都有对应入口,契约落在 `_protocol.COMMAND_COVERAGE`,
由 `tests/test_protocol_sync.py` 直接解析固件头文件双向强制。
固件里每条已实现的下行命令都有对应入口,契约落在 `_protocol.COMMAND_COVERAGE`。
本仓库不再随包提供协议漂移校验测试。

---

Expand All @@ -786,25 +785,15 @@ litearm-python movej -0.1 0 0 0 0 0 0 --speed 0.3

## 10. 测试

```bash
pytest # 离线全流程,不碰真机
LITEARM_LIVE=1 pytest # 额外跑真机用例
python tests/test_offline.py # 不装 pytest 也能跑
```
仓库当前不包含测试套件。要写自己的离线测试,用随包发布的 `litearm.testing.FakeTransport`
替换 `SerialTransport`:

```python
import litearm.arm as arm_mod
from litearm.testing import FakeTransport

跑测试不需要装包,`tests/conftest.py` 会把 `src/` 与 `tests/` 塞进 `sys.path`。
无人在场时不要设 `LITEARM_LIVE`,也绝不调用 `enter_dfu()` / `reset_factory()`。
arm_mod.SerialTransport = lambda port, timeout=0.2: FakeTransport(port="fake", timeout=timeout)
```

| 测试 | 守什么 |
| --- | --- |
| `test_protocol_sync.py` | 协议漂移防护,直接解析固件头文件比对命令集合与 ID。固件仓库位置由环境变量 `LITEARM_FW_DIR` 指定(默认 `~/litearm-stm32`),**找不到时 skip 而不是 pass** |
| `test_protocol_crc.py` | CRC16,用外部权威检查值 + 独立参考实现 |
| `test_frame_ownership.py` | 帧没被静默销毁,它的主人拿到了它 |
| `test_transport.py` | 真实字节流解析(连续帧 / 噪声 / 坏帧 / 半帧) |
| `test_ack_echo.py` | 应答必须回显原命令,迟到的旧应答不得让新命令假成功 |
| `test_capability.py` | 固件没有这条命令 → `UnsupportedByFirmwareError` |
| `test_fork_guard.py` | fork 守卫:子进程零下发 |
| `test_zero_g.py` | 拖动示教保活周期 / 退出收尾 / 线程回收 / 命令门禁 |
| `test_live.py` | 真机冒烟,`LITEARM_LIVE=1` 才跑 |

`tests/fake_serial.py` 的桩必须与固件真实布局一致,否则离线假绿而真机必挂。
这只用于测试,不要在生产代码里改 `SerialTransport`。真机验证需要接臂并自行控制风险;
无人在场时绝不调用 `enter_dfu()` / `reset_factory()`。
6 changes: 0 additions & 6 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,6 @@ classifiers = [
]
dependencies = ["pyserial>=3.4"]

[project.optional-dependencies]
dev = ["pytest>=7"]

[project.urls]
Repository = "https://github.com/nexform-tech/litearm-python"
Issues = "https://github.com/nexform-tech/litearm-python/issues"
Expand All @@ -39,9 +36,6 @@ Documentation = "https://github.com/nexform-tech/litearm-python/blob/main/docs/D
[project.scripts]
litearm-python = "litearm.arm:main"

[tool.pytest.ini_options]
testpaths = ["tests"]

[tool.setuptools.packages.find]
where = ["src"]

Expand Down
4 changes: 2 additions & 2 deletions src/litearm/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,8 @@

协议覆盖: 固件 `hal/usb_cmd.h` 里每条**已实现**的下行命令都有对应入口
(`arm.params.*` 关节级参数 / `arm.log.*` 300Hz 采集 / `arm.diag.kin_bench` 自检);
覆盖契约见 `_protocol.COMMAND_COVERAGE`, 由 `tests/test_protocol_sync.py` 直接解析
固件头文件强制。命令不被本机固件支持时抛 `UnsupportedByFirmwareError`。
覆盖契约见 `_protocol.COMMAND_COVERAGE`。命令不被本机固件支持时抛
`UnsupportedByFirmwareError`。

零重力拖动示教见 `Arm.zero_g()` —— 返回上下文管理器, 保活由后台线程自动维持。
"""
Expand Down
Loading
Loading