From bbd877fb025a0eb028cafef62896b16230f1233f Mon Sep 17 00:00:00 2001 From: thetooler Date: Mon, 26 Oct 2026 11:43:43 +0800 Subject: [PATCH 1/4] test: remove the test suite and its CI gate The owner removed tests/ from the repository. Drop the pytest config, replace the CI test step with an install and import smoke check, and update README, the developer guide and AGENTS.md so they no longer promise a test suite. --- .github/workflows/ci.yml | 25 +- README.md | 29 +- README.zh-CN.md | 26 +- docs/DEVELOPER_GUIDE.md | 37 +- docs/DEVELOPER_GUIDE.zh-CN.md | 35 +- pyproject.toml | 3 - src/litearm/__init__.py | 4 +- tests/conftest.py | 177 ---- tests/fake_serial.py | 19 - tests/test_ack_echo.py | 110 --- tests/test_arm_offline.py | 190 ---- tests/test_banner.py | 109 -- tests/test_capability.py | 62 -- tests/test_cart_errors.py | 110 --- tests/test_cart_protocol.py | 1477 --------------------------- tests/test_cart_queue.py | 1480 ---------------------------- tests/test_cart_wait.py | 594 ----------- tests/test_cli.py | 73 -- tests/test_dfu.py | 322 ------ tests/test_diagnostics.py | 122 --- tests/test_doc_examples.py | 358 ------- tests/test_error_codes.py | 945 ------------------ tests/test_error_hierarchy.py | 24 - tests/test_ff_io.py | 126 --- tests/test_fork_guard.py | 246 ----- tests/test_frame_ownership.py | 264 ----- tests/test_full_coverage.py | 363 ------- tests/test_home.py | 65 -- tests/test_ik_bench.py | 73 -- tests/test_license.py | 223 ----- tests/test_lifecycle.py | 179 ---- tests/test_live.py | 41 - tests/test_log.py | 161 --- tests/test_model.py | 237 ----- tests/test_msg.py | 388 -------- tests/test_offline.py | 95 -- tests/test_package_metadata.py | 46 - tests/test_params.py | 101 -- tests/test_payload.py | 400 -------- tests/test_protocol_crc.py | 125 --- tests/test_protocol_sync.py | 367 ------- tests/test_public_api.py | 131 --- tests/test_request_and_get.py | 173 ---- tests/test_silent_noops.py | 140 --- tests/test_status_layout.py | 99 -- tests/test_teardown.py | 403 -------- tests/test_tool_offset.py | 212 ---- tests/test_transport.py | 835 ---------------- tests/test_transport_injection.py | 25 - tests/test_transport_threadsafe.py | 146 --- tests/test_zero_g.py | 111 --- tests/test_zero_g_cart_guard.py | 194 ---- 52 files changed, 51 insertions(+), 12249 deletions(-) delete mode 100644 tests/conftest.py delete mode 100644 tests/fake_serial.py delete mode 100644 tests/test_ack_echo.py delete mode 100644 tests/test_arm_offline.py delete mode 100644 tests/test_banner.py delete mode 100644 tests/test_capability.py delete mode 100644 tests/test_cart_errors.py delete mode 100644 tests/test_cart_protocol.py delete mode 100644 tests/test_cart_queue.py delete mode 100644 tests/test_cart_wait.py delete mode 100644 tests/test_cli.py delete mode 100644 tests/test_dfu.py delete mode 100644 tests/test_diagnostics.py delete mode 100644 tests/test_doc_examples.py delete mode 100644 tests/test_error_codes.py delete mode 100644 tests/test_error_hierarchy.py delete mode 100644 tests/test_ff_io.py delete mode 100644 tests/test_fork_guard.py delete mode 100644 tests/test_frame_ownership.py delete mode 100644 tests/test_full_coverage.py delete mode 100644 tests/test_home.py delete mode 100644 tests/test_ik_bench.py delete mode 100644 tests/test_license.py delete mode 100644 tests/test_lifecycle.py delete mode 100644 tests/test_live.py delete mode 100644 tests/test_log.py delete mode 100644 tests/test_model.py delete mode 100644 tests/test_msg.py delete mode 100644 tests/test_offline.py delete mode 100644 tests/test_package_metadata.py delete mode 100644 tests/test_params.py delete mode 100644 tests/test_payload.py delete mode 100644 tests/test_protocol_crc.py delete mode 100644 tests/test_protocol_sync.py delete mode 100644 tests/test_public_api.py delete mode 100644 tests/test_request_and_get.py delete mode 100644 tests/test_silent_noops.py delete mode 100644 tests/test_status_layout.py delete mode 100644 tests/test_teardown.py delete mode 100644 tests/test_tool_offset.py delete mode 100644 tests/test_transport.py delete mode 100644 tests/test_transport_injection.py delete mode 100644 tests/test_transport_threadsafe.py delete mode 100644 tests/test_zero_g.py delete mode 100644 tests/test_zero_g_cart_guard.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a07b3bb..1bb18cd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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 @@ -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 @@ -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 # 都已经生成 —— 构建到那一步才炸, 等于白烧一个版本号。在这里先构建一次, diff --git a/README.md b/README.md index d705ab6..d01579e 100644 --- a/README.md +++ b/README.md @@ -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`. diff --git a/README.zh-CN.md b/README.zh-CN.md index c283dfd..b69128b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -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`。 diff --git a/docs/DEVELOPER_GUIDE.md b/docs/DEVELOPER_GUIDE.md index 6af1091..a16ee37 100644 --- a/docs/DEVELOPER_GUIDE.md +++ b/docs/DEVELOPER_GUIDE.md @@ -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`. @@ -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. --- @@ -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. diff --git a/docs/DEVELOPER_GUIDE.zh-CN.md b/docs/DEVELOPER_GUIDE.zh-CN.md index 89806b0..c58cc7c 100644 --- a/docs/DEVELOPER_GUIDE.zh-CN.md +++ b/docs/DEVELOPER_GUIDE.zh-CN.md @@ -29,7 +29,6 @@ LiteArm 机械臂的 Python SDK,USB 串口直连固件。 ```bash pip install -e . # 安装 -pip install -e ".[dev]" # 开发(含 pytest) ``` `pip` 与 `python` 指向不同解释器时用 `python -m pip`。 @@ -758,8 +757,8 @@ src/litearm/ testing.py 离线桩(FakeTransport) ``` -固件里每条已实现的下行命令都有对应入口,契约落在 `_protocol.COMMAND_COVERAGE`, -由 `tests/test_protocol_sync.py` 直接解析固件头文件双向强制。 +固件里每条已实现的下行命令都有对应入口,契约落在 `_protocol.COMMAND_COVERAGE`。 +本仓库不再随包提供协议漂移校验测试。 --- @@ -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()`。 diff --git a/pyproject.toml b/pyproject.toml index 635a973..46721e0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -39,9 +39,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"] diff --git a/src/litearm/__init__.py b/src/litearm/__init__.py index e954ce6..b4b0f65 100644 --- a/src/litearm/__init__.py +++ b/src/litearm/__init__.py @@ -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()` —— 返回上下文管理器, 保活由后台线程自动维持。 """ diff --git a/tests/conftest.py b/tests/conftest.py deleted file mode 100644 index 20b342b..0000000 --- a/tests/conftest.py +++ /dev/null @@ -1,177 +0,0 @@ -"""pytest fixtures —— 桩 transport 连接 (离线) / 真机 live 开关。 - -用法: - pytest # 只跑离线 (桩 transport), 不碰真机 - LITEARM_LIVE=1 pytest # 额外跑真机 live (需接 Litearm1.5.0+ 整臂/台架) -""" -from __future__ import annotations - -import os -import sys -import weakref - -import pytest - -_HERE = os.path.dirname(os.path.abspath(__file__)) -sys.path.insert(0, _HERE) # tests/ (fake_serial) -sys.path.insert(0, os.path.join(_HERE, "..", "src")) # litearm (免安装) - -from fake_serial import FakeTransport # noqa: E402 - -LIVE = bool(os.environ.get("LITEARM_LIVE")) - - -@pytest.fixture(autouse=True) -def _no_leaked_port_registration(): - """**本用例**收尾时不许留下 open 着的 `SerialTransport` (登记表里那条要还在)。 - - 为什么需要这道守卫: 端口登记表按**端口字符串**比 (`transport._PORT_OWNERS`)。一个用例 - 把传输 open 着留在册上, 下一个用**同一端口名**的用例就会在 `_claim_port` 上炸 —— 而 - "它还留着吗"取决于该传输**何时被回收**: 无环的传输随引用计数当场消失 (没事), 被引用环 - 或回溯钉住的传输要等一次全量 gc (于是失败**按用例顺序传染**, 且 gc 何时跑看不出来)。 - `tests/test_transport.py` 的"端点独占"一节靠**各用例独享端口名**绕开这条耦合; 本守卫把它 - 变成**泄漏当场、就地报出来**的失败, 与跑的顺序、gc 开不开都无关。 - - ⚠ **按增量判**: 只认"本用例新登记进来、且收尾时还开着"的那几条 —— 否则一个没修的泄漏 - 会让**后面每一个**用例都报错 (归因就指错了人)。判据比的是 `(端口, 持有者 id)`, 所以 - 前一个用例留下的那条不会被算到本用例头上。 - - ⚠ 判据只取"**在册 且 `is_open`**": 在册但**已 `close()`** 的传输不占端口 (fd 已释放), - 不算泄漏 —— 那正是 `close()` 该有的收尾 (登记随 `_release_port` 当场消失)。本守卫因此 - 不要求"对象被回收", 只要求"口被关上"。 - """ - from litearm.transport import _PORT_OWNERS - - def _snapshot(): - out = {} - for port, ref in list(_PORT_OWNERS.items()): - owner = ref() - if owner is not None: - out[(port, id(owner))] = owner - return out - - before = set(_snapshot()) - - yield - - leaked = sorted({ - port for (port, _oid), owner in _snapshot().items() - if (port, _oid) not in before and owner.is_open - }) - assert not leaked, ( - f"本用例结束时留下了 open 着的传输, 占着端口 {leaked!r} —— 它会挡住后面任何一个用" - f"同一端口名的用例, 而挡不挡得住还取决于 gc 何时跑 (引用环/回溯钉住的对象要等全量" - f" gc)。请在用例里 close() 它, 或改用本用例独享的端口名。") - - -def _live_reader_threads() -> set: - """当前活着的读线程(按名字)—— `Arm` 的读线程固定叫 `litearm-reader`。""" - import threading - return {t for t in threading.enumerate() - if t.is_alive() and t.name == "litearm-reader"} - - -@pytest.fixture(autouse=True) -def _no_leaked_reader_threads(): - """⚠ 每条用例结束后**不许**留下读线程 —— 离线侧的**唯一**泄漏哨兵。 - - **为什么需要它**:`Arm` 现在带一条读线程,而线程的 target 是绑定方法 ⇒ 线程强引用 - `_Ack`→`Arm`。**忘了 `close()` 的 `Arm` 会带着它的线程一起活着**,而 - `tests/conftest.py` 另一条"端口泄漏"哨兵对离线用例**是空转的** —— - `FakeTransport` 不登记 `_PORT_OWNERS`,它什么都抓不住(实测)。 - - **两条职责分开**(别把第一条读成"哨兵在放水"): - - 1. **自动收尾**:本用例里构造过、又没 `close()` 的 `Arm`,由这里统一收掉 —— - 跑一次测试不该给下一条用例留几十条活线程(那会把整套拖垮)。 - ⚠ 这是**兜底**,不是"可以不 close":生产代码里 `close()` 仍然必须显式调。 - 2. **断言**:收完之后**仍须一条不剩** —— 它验的是「**`close()` 真的停得掉读线程**」 - 这个性质。`close()` 少了 `stop_reader()`、或 join 超时不够,这里就会红。 - """ - from litearm import arm as _arm_mod - - #: ⚠ **弱引用**,不是强引用 —— 强引用会把这些 `Arm` 钉到用例结束,于是 - #: `test_teardown.py` 那几条"松开 `Arm` 就该回收 + 跑兜底收尾"的用例全部失效 - #: (它们靠 `del arm` + `gc.collect()` 让 `Arm.__del__` 触发)。**实测踩过**。 - made: list = [] - _orig_init = _arm_mod.Arm.__init__ - - def _init(self, *args, **kwargs): - _orig_init(self, *args, **kwargs) - made.append(weakref.ref(self)) - - _arm_mod.Arm.__init__ = _init - before = _live_reader_threads() - try: - yield - finally: - _arm_mod.Arm.__init__ = _orig_init - for _ref in made: # ① 兜底收尾 - arm = _ref() - if arm is None: - continue # 已被回收(兜底收尾已跑过) - try: - arm.close() - except Exception: # noqa: BLE001 - 收尾失败不该掩盖断言 - pass - leaked = _live_reader_threads() - before # ② 断言 - assert not leaked, ( - f"本用例留下了 {len(leaked)} 条读线程 —— **连 `close()` 都停不掉它**。" - f"检查 `_Ack.stop_reader()` 是否被 `Arm.close()` 调到、join 超时够不够。") - - -@pytest.fixture -def fake_transport_factory(monkeypatch): - """把 arm.SerialTransport 换成 FakeTransport, 返回工厂 (fw=..., port=...)。""" - import litearm.arm as arm_mod - - def _factory(fw: str = "Litearm1.7.0-7J", **kw): - def make(port="fake", timeout=0.2, **_ignored): - return FakeTransport(port=port, timeout=timeout, fw=fw, **kw) - monkeypatch.setattr(arm_mod, "SerialTransport", make) - return make - return _factory - - -@pytest.fixture -def offline_arm(fake_transport_factory): - """连上桩固件的 Arm (默认 Litearm1.7.0-7J)。 - - ⚠⚠ **必须 `yield` + `close()`** (2026-09-22 起): `Arm` 现在带一条**读线程**, - 而线程的 target 是绑定方法 ⇒ 线程强引用 `_Ack`→`Arm`, 活线程又被 `threading._active` - 强引用 ⇒ **不 `close()` 就回收不掉 `Arm`**, 且线程会一直活着。 - ⚠ 离线侧**没有哨兵兜底**: `FakeTransport` 不登记 `_PORT_OWNERS`, 那条"端口泄漏" - 哨兵对离线用例是空转的 —— 漏了这里就是一堆静默的活线程。 - """ - fake_transport_factory() # 应用桩 (monkeypatch) - from litearm import Arm - arm = Arm(port="fake").connect() - try: - yield arm - finally: - arm.close() - - -@pytest.fixture -def offline_arm_1j(fake_transport_factory): - """连上**台架单电机**桩固件 (Litearm1.7.0-1J, N=1)。 - - 固件侧台架版: `LITEARM_NUM_JOINTS=1` 且 `LITEARM_BENCH_MODEL_AXIS=5` - (joint_cfg.h), 即台架那台电机对应整臂运动学模型的第 6 轴。 - - ⚠ 同 `offline_arm`: **必须 `yield` + `close()`** (读线程的生命周期)。 - """ - fake_transport_factory(fw="Litearm1.7.0-1J", n=1) - from litearm import Arm - arm = Arm(port="fake").connect() - try: - yield arm - finally: - arm.close() - - -@pytest.fixture -def live_only(): - """真机用例: 未设 LITEARM_LIVE=1 时跳过。""" - if not LIVE: - pytest.skip("真机用例需 LITEARM_LIVE=1 (并接好 Litearm1.5.0+ 固件)") diff --git a/tests/fake_serial.py b/tests/fake_serial.py deleted file mode 100644 index de1b094..0000000 --- a/tests/fake_serial.py +++ /dev/null @@ -1,19 +0,0 @@ -"""向后兼容薄壳 —— 实物已提升为公开的 `litearm.testing`。 - -本文件**只做 re-export,不要在这里加逻辑**:两份假件必然漂移,而漂移的假件会让 -离线全绿、真机全挂。见本仓 `kin-bench-two-frame-contract` 那条教训 —— -"桩把多帧合成一帧 = 把契约测掉"。 - -⚠ 保留本文件是**必须**的:`tests/` 下 5 个文件在 `from fake_serial import ...` -(`conftest.py` 把 `tests/` 插进了 `sys.path`)。 -""" -from litearm.testing import * # noqa: F401,F403 -from litearm.testing import ( # noqa: F401 下划线名显式转出 - _N, - _CART_MIN_LEN, - _CART_PLANNING_CMDS, - _ack, - _mk_log, - _split_kin_bench, - _status, -) diff --git a/tests/test_ack_echo.py b/tests/test_ack_echo.py deleted file mode 100644 index ba98aec..0000000 --- a/tests/test_ack_echo.py +++ /dev/null @@ -1,110 +0,0 @@ -"""ACK 必须回显原命令 —— 迟到的旧 ACK 不能被当成新命令的成功。 - -固件侧 ERR 载荷是 [回显cmd, code], ACK 载荷首字节同样是原命令 -(litearm-stm32/User/litearm/hal/usb_cmd.c)。若上位机不比对, 上一条命令超时后 -迟到的 ACK 会让下一条命令"假成功"(对 disable/emergency_stop 这类安全命令尤其危险)。 -""" -from __future__ import annotations - -import struct - -import pytest - -from litearm import _protocol as P -from litearm.errors import MotionTimeoutError - - -def _status_frame(n=7): - body = bytearray(struct.pack(" 必须超时失败, 不能算成功。""" - arm = _make_arm(monkeypatch, {P.CMD_DISABLE: [P.pack_frame(P.RSP_ACK, bytes([P.CMD_MOVE_J]))]}) - with pytest.raises(MotionTimeoutError): - arm.disable() - - -def test_matching_ack_accepted_after_foreign(monkeypatch): - """先来一个别的命令的 ACK, 再来正确的 -> 必须成功 (不能过度严格)。""" - arm = _make_arm(monkeypatch, {P.CMD_DISABLE: [ - P.pack_frame(P.RSP_ACK, bytes([P.CMD_MOVE_J])), - P.pack_frame(P.RSP_ACK, bytes([P.CMD_DISABLE])), - ]}) - arm.disable() # 不抛即成功 - - -def test_emergency_stop_requires_own_echo(monkeypatch): - """急停同样不能被别的命令的 ACK 顶替。""" - arm = _make_arm(monkeypatch, {P.CMD_EMERGENCY_STOP: [ - P.pack_frame(P.RSP_ACK, bytes([P.CMD_ENABLE])), - ]}) - with pytest.raises(MotionTimeoutError): - arm.emergency_stop() - - -def test_foreign_err_does_not_fail_current_command(monkeypatch): - """迟到的**别的命令**的 ERR 不能算到当前命令头上 (ACK 已过滤, ERR 也要过滤)。 - - 否则 enable() 会对无关 ERR 触发无意义重试, 连续伺服会打断一条本来有效的命令。 - """ - arm = _make_arm(monkeypatch, {P.CMD_DISABLE: [ - P.pack_frame(P.RSP_ERR, bytes([P.CMD_MOVE_J, 0x05])), # 别人的 ERR - P.pack_frame(P.RSP_ACK, bytes([P.CMD_DISABLE])), - ]}) - arm.disable() # 不应被别人的 ERR 打断 - - -def test_own_err_still_raises(monkeypatch): - from litearm.errors import CommandRejectedError - arm = _make_arm(monkeypatch, {P.CMD_DISABLE: [ - P.pack_frame(P.RSP_ERR, bytes([P.CMD_DISABLE, 0x03])), - ]}) - with pytest.raises(CommandRejectedError): - arm.disable() diff --git a/tests/test_arm_offline.py b/tests/test_arm_offline.py deleted file mode 100644 index 5c5c03a..0000000 --- a/tests/test_arm_offline.py +++ /dev/null @@ -1,190 +0,0 @@ -"""离线全流程 (桩 transport): 连接/版本门禁/enable/movej 到位/move_p/ik/get_tcp/ -状态解析/FF 命令/伺服编码 —— 镜像 pylitearm tests (test_arm_embedded_dryrun 风格)。""" -from __future__ import annotations - -import pytest - -from litearm import _protocol as P -from litearm import Arm -from litearm.errors import ( - FirmwareMismatchError, - InvalidCommandError, - MotionTimeoutError, -) - - -def test_connect_fw_ok(offline_arm): - assert offline_arm.firmware == "Litearm1.7.0-7J" - assert offline_arm.fw_version == (1, 7, 0) - assert offline_arm.n == 7 - assert not offline_arm.get_state().value.faulted - - -def test_version_gate_old_naming(fake_transport_factory): - fake_transport_factory(fw="A1.3.0-7J-USB") - with pytest.raises(FirmwareMismatchError): - Arm(port="fake").connect() - - -def test_version_gate_too_old(fake_transport_factory): - fake_transport_factory(fw="Litearm1.3.0-7J") - with pytest.raises(FirmwareMismatchError): - Arm(port="fake").connect() - - -def test_enable_disable(offline_arm): - offline_arm.enable() - offline_arm.disable() - - -def test_movej_arrives(offline_arm): - target = [0.0, 0.3, 0.0, 0.0, 0.0, 0.0, 0.0] - offline_arm.movej(target, speed=0.5) # 桩会先给 3 拍"运动中"再到位 - st = offline_arm.get_state().value - assert all(abs(st.q[i] - target[i]) < 1e-6 for i in range(7)) - - -def test_movej_bad_count(offline_arm): - with pytest.raises(InvalidCommandError): - offline_arm.movej([0.0] * 6) # N=7 缺一 - - -def test_move_p_tcp_arrives(offline_arm): - pose = [0.30, 0.02, 0.35, 0.0, 0.0, 0.0] - offline_arm.move_p(pose, speed=0.2, pos_tol=0.006, rpy_tol=0.03) - tcp = offline_arm.get_tcp().value - assert abs(tcp[0] - pose[0]) < 1e-4 and abs(tcp[1] - pose[1]) < 1e-4 - - -def test_move_p_rejects_a_pose_sequence_and_points_at_move_path(offline_arm): - """位姿序列必须给出一条**指名 `move_path`** 的错。 - - ⚠ 为什么非要指名: 从前 `move_p` (旧名 `movep`) 收序列就走 PC 侧规划。序列重载移除 - 后, 若只让它落到 `_rot.as_pose` 的形状判据, 用户拿到的是那句 - "pose 形状无法识别: len=3" —— **完全看不出"这个 API 变了"**, 只会以为自己的位姿 - 写错了。 - - ⚠ 文案里还得带语义差异, 不能只说"改名了": 旧序列形态是**关节空间**多路点 (PC 侧 - 规划, 已退役), `move_path` 是**笛卡尔**多路点 (固件规划), 两者不是同一个东西。 - """ - with pytest.raises(InvalidCommandError) as ei: - offline_arm.move_p([[0.31, 0.0, 0.35, 0.0, 0.0, 0.0], - [0.31, 0.01, 0.35, 0.0, 0.0, 0.0], - [0.31, 0.02, 0.35, 0.0, 0.0, 0.0]]) - msg = str(ei.value) - assert "move_path" in msg - assert "关节空间" in msg and "笛卡尔" in msg # 语义差异必须在文案里 - assert P.CMD_MOVE_P not in [c for c, _ in offline_arm._tr.tx_log] # 一帧没发 - - -#: 单位旋转 —— `move_p` 的 `(pos[3], R[3x3])` 输入形态要用。 -ID_R = [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]] - - -def test_move_p_single_pose_uses_firmware_move_p(offline_arm): - """单点 `move_p` 走固件 `CMD_MOVE_P` —— **不是**走 PC 侧规划 (`move_js` 流式)。 - - ⚠ **改靶说明**: 本条从已删的 `tests/test_cartesian_motion.py` 摘出保留 (原 - `test_move_p_single_pose_uses_firmware_move_p`)。它测的从来不是被删的子包, 而是 - `Arm.move_p` 的**管道契约** —— 固件后台 IK + S 曲线 (一条 `0x02` 就够), 与 PC 侧 - 规划那条流 (`move_js` 100Hz 逐拍 + `movej` 收尾) 是两回事。子包退役后这条契约 - **更**要守住: 现在它是"`move_p` 没有偷偷退回 PC 规划"的唯一哨兵。 - - 返回类型也钉住: `RobotState` (有 `mode_name`), 不是那条流返回的 `CartPlan`。 - (原 docstring 写的是"不是 CartPlan/MotionResult" —— `MotionResult` 随子包没了, - 改写成现在真实存在的两个类型。) - """ - st = offline_arm.move_p([0.32, 0.0, 0.35, 0.0, 0.0, 0.0]) - sent = [c for c, _ in offline_arm._tr.tx_log] - assert P.CMD_MOVE_P in sent - assert P.CMD_MOVE_JS not in sent # 没走 PC 规划 - assert hasattr(st, "mode_name") # RobotState - - -def test_move_p_accepts_a_pose_pair(offline_arm): - """`(pos[3], R[3x3])` 是合法**单点**输入 —— 它形状像"两个位姿的序列", 不能判成序列。 - - ⚠ **改靶说明**: 从已删的 `test_cartesian_motion.py` 摘出保留, 是**唯一**一条 - 测 `move_p` 收位姿对形态的用例 (其余 `move_p` 用例传的都是 6 标量或序列)。 - `Arm.move_p` 里那条 `else` 分支 (`_rot.as_pose` + `mat_to_rpy`) 今天仍是活代码, - 删掉本条就等于让"位姿对静默失效"回归无人看守 —— 同形态在三条笛卡尔入口上**各有一条** - 用例, 但**都不覆盖 `move_p`**: `tests/test_cart_protocol.py` 的 - `test_a_pose_pair_produces_the_same_frame_as_the_six_scalars`(…`:1289`, `move_l`)、 - `test_a_homogeneous_4x4_pose_is_accepted_too`(`:1313`, `move_l` 的 4×4)、 - `test_move_c_pose_start_also_accepts_a_pose_pair`(`:1324`, `move_c`)、 - `test_move_path_waypoints_also_accept_a_pose_pair`(`:1341`, `move_path`)。 - (此处原写"`…:902` 守的是 `move_l`/`move_c`/`move_path`" —— **引错位置**: `:902` 落在 - `test_a_pose_pair_*` 中间, 而且当时**全仓没有**任何 `move_path` 位姿对用例; 行号与 - 覆盖缺口两处一并订正。) - """ - offline_arm.move_p(([0.32, 0.0, 0.35], ID_R)) - assert P.CMD_MOVE_P in [c for c, _ in offline_arm._tr.tx_log] - - -def test_ik_returns(offline_arm): - qs = offline_arm.ik([0.30, 0.0, 0.35, 0.0, 0.0, 0.0]) - assert len(qs) == 7 - - -def test_get_tcp(offline_arm): - tcp = offline_arm.get_tcp().value - assert tcp is not None and len(tcp) == 6 - - -def test_ff_commands(offline_arm): - offline_arm.ff_preset(1) - offline_arm.set_ff_mask(P.FF_MASTER | P.FF_G) - offline_arm.set_gravity_scale([2.7, 2.1, 1.75, 1.85, 2.9, 3.1, 1.2]) - offline_arm.set_inertia_scale([2.84, 8.62, 9.5, 2.56, 5.27, 4.02, 3.56]) - offline_arm.set_payload(0.4, (0.0, 0.0, 0.02)) - offline_arm.set_gravity_vector([0.0, 0.0, -9.81]) - offline_arm.save_params() - - -def test_move_js_send_mit_encoding(offline_arm): - q = [0.0] * 7 - offline_arm.move_js(q, dq=[0.0] * 7) - offline_arm.send_mit(0, q[0], 0.0, 50.0, 2.0, 0.0) - offline_arm.send_mit_all(q, [0.0] * 7, [50.0] * 7, [2.0] * 7, [0.0] * 7) - with pytest.raises(InvalidCommandError): - offline_arm.send_mit(9, 0.0, 0.0, 0.0, 0.0, 0.0) - - -def test_state_decode_shape(offline_arm): - st = offline_arm.get_state(refresh=True).value - assert len(st.joints) == 7 - assert len(st.q) == 7 and len(st.dq) == 7 - - -def test_ik_without_state_raises_litearm_error(offline_arm): - """拿不到状态帧时 ik() 应抛本包错误, 不能漏 AttributeError (用户 except LiteArmError 抓不住)。""" - from litearm.errors import LiteArmError - - offline_arm._a.state = None - offline_arm._read_status = lambda timeout=0.5: None # 模拟状态帧缺失 - with pytest.raises(LiteArmError): - offline_arm.ik([0.30, 0.0, 0.35, 0.0, 0.0, 0.0]) - - -def test_state_faulted_true_when_axis_latched(offline_arm): - """固件 G7 单轴断轴不一定置全局 FAULT 位 —— 状态视图必须把 joint_fault 算作故障, - 否则 movej 不会早失败, 只会耗满 15s 超时才报'未到位'(M7 要消除的"断轴装活")。""" - from litearm import state as ST - st = ST.RobotState(mode=1, joint_fault=0b100) # 只有 J3 断轴, 无全局 FAULT - assert st.faulted is True - assert st.fault_axes == [2] - - -def test_move_p_raises_litearm_error_without_state(offline_arm): - """与 ik() 同款: 取不到状态帧时不能漏 AttributeError (要耗超时也不能崩类型)。 - - 注意目标位姿要**不同于桩位姿**, 否则会走"tcp 到位但无状态帧"的等待循环而不触发异常。 - """ - from litearm.errors import LiteArmError, MotionTimeoutError - - offline_arm.move_timeout = 0.4 - offline_arm._a.state = None - offline_arm._read_status = lambda timeout=0.5: None - with pytest.raises(MotionTimeoutError) as ei: - offline_arm.move_p([0.9, 0.9, 0.9, 0.0, 0.0, 0.0]) - assert isinstance(ei.value, LiteArmError) diff --git a/tests/test_banner.py b/tests/test_banner.py deleted file mode 100644 index bd9e823..0000000 --- a/tests/test_banner.py +++ /dev/null @@ -1,109 +0,0 @@ -"""开机签名 (banner) —— 固件在 USB 枚举完成后发一次, 是**唯一能区分 IWDG 复位**的信息。 - -固件 `usb_cmd_report` (枚举后单发, `usb_cmd.c:1297-1303`): - sig_ok = "\\r\\n[litearm-usbcdc] ready (" LITEARM_FW_VERSION ")\\r\\n" - sig_iwdg = "\\r\\n[litearm-usbcdc] ready (" LITEARM_FW_VERSION ", iwdg-rst)\\r\\n" -即独立看门狗复位过的那次启动会带 `, iwdg-rst` 标注 (原实现在 init 里三连发, 未枚举时 -必丢, 该标注从来到不了上位机; L9 fix 移到枚举后单发)。 - -这段文本不是帧 (不以 SOF 0xA5 开头), 旧实现把它当噪声逐字节丢弃。现改为在丢弃路径 -上留痕, 供上层解析。 -""" -from __future__ import annotations - -import struct -import sys -import time -import types - -from litearm import _protocol as P -from litearm.transport import SerialTransport - -BANNER_OK = "\r\n[litearm-usbcdc] ready (Litearm1.7.0-7J)\r\n" -BANNER_IWDG = "\r\n[litearm-usbcdc] ready (Litearm1.7.0-7J, iwdg-rst)\r\n" - - -# ---------------------------------------------------------------- 纯解析 -def test_parse_banner_normal_boot(): - assert P.parse_boot_banner(BANNER_OK) == "normal" - - -def test_parse_banner_iwdg_reset(): - assert P.parse_boot_banner(BANNER_IWDG) == "iwdg-rst" - - -def test_parse_banner_absent_or_noise(): - assert P.parse_boot_banner("") is None - assert P.parse_boot_banner("\x11\x22random noise\x00") is None - - -def test_parse_banner_picks_latest_when_repeated(): - """重连/多次枚举会重复出现; 取最后一次。""" - assert P.parse_boot_banner(BANNER_IWDG + "junk" + BANNER_OK) == "normal" - - -# ---------------------------------------------------------------- 传输层留痕 -def mk_status(seq): - body = bytearray(struct.pack(" 必须抛 UnsupportedByFirmwareError 并带上 cmd。""" - arm = offline_arm - arm._tr.unknown_cmds.add(P.CMD_PARAM_SAVE) - with pytest.raises(UnsupportedByFirmwareError) as ei: - arm.save_params() - assert ei.value.cmd == P.CMD_PARAM_SAVE - assert ei.value.code == 0x00 - - -def test_unsupported_is_a_command_rejected_subclass(offline_arm): - """既有捕获 CommandRejectedError 的调用方不得被这次细分破坏。""" - arm = offline_arm - arm._tr.unknown_cmds.add(P.CMD_PARAM_SAVE) - with pytest.raises(CommandRejectedError): - arm.save_params() - assert issubclass(UnsupportedByFirmwareError, CommandRejectedError) - - -def test_other_error_codes_are_not_unsupported(offline_arm): - """ERR{cmd,0x03}(未使能) 一类是**真拒绝**, 不能误判成「固件不支持」。""" - arm = offline_arm - arm._tr.err_override[P.CMD_PARAM_SAVE] = 0x03 - with pytest.raises(CommandRejectedError) as ei: - arm.save_params() - assert not isinstance(ei.value, UnsupportedByFirmwareError) - assert ei.value.code == 0x03 - - -def test_unsupported_during_motion_wait(offline_arm): - """运动等待路径 (pump/_arrive) 里的 ERR 也要走同一套映射。""" - arm = offline_arm - arm._tr.unknown_cmds.add(P.CMD_MOVE_J) - with pytest.raises(UnsupportedByFirmwareError): - arm.movej([0.1] * 7) - - -def test_unsupported_during_status_read(offline_arm): - """状态读取路径 (_read_status) 里的 ERR 同样要走映射。""" - arm = offline_arm - arm._tr.unknown_cmds.add(P.CMD_GET_STATUS) - arm._tr.err_override.pop(P.CMD_GET_STATUS, None) - with pytest.raises(UnsupportedByFirmwareError): - arm.get_status_now(timeout=0.2) diff --git a/tests/test_cart_errors.py b/tests/test_cart_errors.py deleted file mode 100644 index 5136340..0000000 --- a/tests/test_cart_errors.py +++ /dev/null @@ -1,110 +0,0 @@ -"""笛卡尔固件规划的三种结局 —— 必须与「固件拒绝了这条命令」可区分。 - -固件原生笛卡尔 (`0x3A/0x3B/0x3C-0x3E` + `RSP_CART_PLAN 0x4E`) 会回三种 -**语义完全不同**的结果, 上位机若把它们混进一个通用异常, 调用方就分不清: - -- `CartesianPlanError` —— 真失败 (IK 无解 / 三点共线 / 超容量 / 越限位); -- `MotionSupersededError` —— **预期内的接管**, 我这条请求被新请求取代了, 不是故障; - 把它当失败处理会让正常的抢占流程报错, 甚至触发不该有的故障恢复; -- `CartReplyLostError` —— **未知结局**: 固件单槽 pending 在突发下会吞掉中段应答, - 臂可能动了也可能没动, 只能靠回读状态判定。 - -三者都**不是** `CommandRejectedError`: 后者是「固件显式 ERR{cmd, code}」, -带 `cmd`/`code` 字段。这三条没有固件错误码, 硬套进去会污染 `code` 的语义 -(例如 `code=0x00` 在既有约定里意为「固件无此命令」—— 见 `UnsupportedByFirmwareError`)。 -""" -from __future__ import annotations - -import importlib.util - -import litearm as pa -from litearm.errors import (CartReplyLostError, CartesianPlanError, - CommandRejectedError, LiteArmError, - MotionSupersededError) - -NEW_ERRORS = (CartesianPlanError, MotionSupersededError, CartReplyLostError) - - -def test_three_errors_exist_and_subclass_lite_arm_error(): - for exc in NEW_ERRORS: - assert issubclass(exc, LiteArmError), f"{exc.__name__} 未继承 LiteArmError" - assert issubclass(exc, Exception) - - -def test_none_of_them_is_a_command_rejected_error(): - """它们不是「固件拒绝了这条命令」—— 不得继承 `CommandRejectedError`。 - - 继承会带来两个实伤: (1) `except CommandRejectedError` 的既有调用方会被 - 接管/应答丢失误触发; (2) 凭空多出 `cmd`/`code` 字段而语义是错的。 - """ - for exc in NEW_ERRORS: - assert not issubclass(exc, CommandRejectedError), ( - f"{exc.__name__} 继承了 CommandRejectedError —— 它不是固件显式拒绝") - - -def test_superseded_is_distinguishable_from_failure(): - """**接管不是失败**: 捕获失败的代码不得误吞接管, 反之亦然。""" - assert not issubclass(MotionSupersededError, CartesianPlanError) - assert not issubclass(CartesianPlanError, MotionSupersededError) - # 应答丢失是「未知结局」, 既不是失败也不是接管 - assert not issubclass(CartReplyLostError, CartesianPlanError) - assert not issubclass(CartReplyLostError, MotionSupersededError) - - -def test_each_error_has_a_docstring_and_carries_a_message(): - for exc in NEW_ERRORS: - assert exc.__doc__, f"{exc.__name__} 缺 docstring (本仓库风格: 中文 docstring)" - assert str(exc("具体原因")) == "具体原因" - - -def test_errors_are_reachable_from_the_catch_all_raise(): - """`raise` / `except` 端到端可用, 且带上原始信息。""" - try: - raise MotionSupersededError("被 0x4E 新请求取代") - except CartesianPlanError: # pragma: no cover - raise AssertionError("接管被误判为规划失败") - except MotionSupersededError as e: - assert "取代" in str(e) - - -def test_new_errors_are_reachable_from_the_package_top_level(): - """SDK 对外只有 `import litearm as pa` 一个入口, 没进 `__all__` 等于没交付。 - - 这里必须比**对象身份**, 不能只比名字: 重名冲突下 `hasattr(pa, name)` 会 - 指着**另一个类**照样绿 —— 那正是本仓最忌讳的假绿。 - """ - for name, exc in (("MotionSupersededError", MotionSupersededError), - ("CartReplyLostError", CartReplyLostError)): - assert name in pa.__all__, f"{name} 未进 __all__" - assert getattr(pa, name) is exc, \ - f"pa.{name} 不是 litearm.errors 里那个类" - - -def test_cartesian_plan_error_now_comes_from_errors_and_is_no_longer_the_legacy_class(): - """✅ **绊线已兑现** —— 场景二 Task 8 删掉 `cartesian/` 时公开名已翻转到新类。 - - 这条的前身是 Task 1 立下的现场绊线: 那时 `pa.CartesianPlanError` 指向**旧**规划器类 - (`cartesian/planner.py`, 基类 `InvalidCommandError`), 新类 `errors.CartesianPlanError` - 从包顶层取不到。绊线的存在意义就是提醒「删包这一刻必须把导入改到 `errors`」—— - 那一刻它确实变红了, 本函数就是翻转后的形态。 - - ⚠ **为什么不留着"旧类已删"这条事实的空断言**: 旧类随包一起没了, 于是 - "`pa.CartesianPlanError` 不是旧类"这条**换个判据**来钉 —— 旧类**唯一**可观察的 - 区别是它继承 `InvalidCommandError` (新类直挂 `LiteArmError`)。用基类关系而非 - 模块路径来判, 使本条在旧包已不存在时仍能证伪 (写 `assert not hasattr(...)` 之类 - 是永真断言, 证不了任何东西)。 - - ⚠ 这里比的是**对象身份**而非名字: 重名冲突下 `hasattr(pa, name)` 指着另一个类 - 照样绿 —— 本仓最忌讳的假绿 (见上面 `test_new_errors_are_reachable_from_the_package_top_level`)。 - """ - from litearm import errors as err_mod - assert pa.CartesianPlanError is err_mod.CartesianPlanError, \ - "pa.CartesianPlanError 不指向 litearm.errors 里那个类" - #: 旧类的判别式: 删掉的那个类继承 `InvalidCommandError`, 新类**刻意不继承** - assert not issubclass(pa.CartesianPlanError, pa.InvalidCommandError), \ - "pa.CartesianPlanError 仍继承 InvalidCommandError —— 公开名还指着旧规划器类" - #: `__all__` 里只许出现一次 (重名冲突的另一个残留形态) - assert pa.__all__.count("CartesianPlanError") == 1 - #: 旧类真的随包走了 —— 不留"其实还能 import 到"的夹层 - assert importlib.util.find_spec("litearm.cartesian") is None, \ - "litearm.cartesian 仍可导入 —— 子包没删干净" diff --git a/tests/test_cart_protocol.py b/tests/test_cart_protocol.py deleted file mode 100644 index 4d875e5..0000000 --- a/tests/test_cart_protocol.py +++ /dev/null @@ -1,1477 +0,0 @@ -"""笛卡尔固件原生路径 (`0x3A`/`0x3B`/`0x3C-0x3E` + `RSP_CART_PLAN 0x4E`) 的离线判据。 - -**为什么单独一个文件**: `test_protocol_sync.py` 管"常量/登记/入口可达"的**静态**契约, -`test_full_coverage.py` 管"每条命令真的被发出去过", `test_cart_queue.py` 管 FIFO 配对。 -本文件管**结果语义与守卫顺序** —— 也就是"发出去之后, 这条命令的结局怎么落到调用方身上": - -* **守卫顺序** (⚠ 承重): `_CartPending.request()` 只在 `TransportError` 上摘 token, - 其余异常一律 re-raise 且**不动队列** —— 所以"写之前就会抛、却不是 `TransportError`" - 的那两类异常 (`NotConnectedError` / 零重力守卫的 `InvalidCommandError`) **必须**在 - 登记 token **之前**跑完, 否则 token 会留在队里, 下一条合法应答就会被配错。 -* **能力探测**: 固件受 `#if LITEARM_CART_PLAN` 约束, 且 `0x3A~0x3E` 里**没有只读命令** - —— 探测只能是"发空载荷撞长度校验", 绝不能发合法载荷 (那等于"connect 之后臂自己动一下")。 -* **`err` 映射**: `0x4E` 的 `err` 字节是 `cart_err_t`; 被取代 (CANCELED) 是**正常结果** - 而不是失败, 必须能与"规划失败"分开。 -* **`CartPlan` 的四个"未等待"字段**: `wait=False` 时入口只等到**规划结果**, 不到位; - `wait=True` (默认) 的到位判据在 `tests/test_cart_wait.py`。 -""" -from __future__ import annotations - -import math -import struct -import sys -import threading -import time -import types - -import pytest - -from fake_serial import FakeTransport, _status # tests/ 在 conftest 里进了 sys.path -from litearm import Arm, _protocol as P -from litearm.arm import _orient_angle -from litearm.cart import (CART_START_POS_TOL, CART_START_RPY_TOL, CartPlan, - raise_for_plan) -from litearm.errors import (CartesianPlanError, CommandRejectedError, - IKError, InvalidCommandError, - MotionSupersededError, NotConnectedError, - TransportError, UnsupportedByFirmwareError) - -#: 桩的初始 TCP (`fake_serial` 的 `self.pose`), `move_c` 的 pose_start 必须与它一致。 -TCP0 = (0.30, 0.0, 0.35, 0.0, 0.0, 0.0) - - -@pytest.fixture -def make_arm(monkeypatch): - """可配置的桩工厂 —— 在 `connect()` **之前**装配桩 (探测就发生在 connect 里)。""" - import litearm.arm as arm_mod - from fake_serial import FakeTransport - - def _make(cfg=None, cls=FakeTransport): - def factory(port="fake", timeout=0.2, **_ignored): - t = cls(port=port, timeout=timeout) - if cfg is not None: - cfg(t) - return t - monkeypatch.setattr(arm_mod, "SerialTransport", factory) - from litearm import Arm - return Arm(port="fake") - return _make - - -class _SilentProbe: - """混入: 让桩对 `0x3A` **一片安静** (其余照常) —— 模拟探测应答丢失。""" - - def write_frame(self, cmd, payload=b""): - if cmd == P.CMD_MOVE_L: - with self._tx_lock: - self.tx_log.append((cmd, bytes(payload))) - self.tx_stamps.append(time.monotonic()) - return - super().write_frame(cmd, payload) - - -class _ShortTcpPayload(FakeTransport): - """`0x43` (GET_TCP) 回一条**短**载荷 (< 24B)。 - - `Arm.get_tcp` 对它的契约是**返回 `None`** (`if len(p) >= 24 … return None`) —— 不是抛。 - 于是两条守卫同时拿到"取不到 TCP": `move_c` 的起点校验 (发帧**之前**) 与 - `_tcp_reached` (收尾回读)。两条各自都有保守处置, 都要有判据。 - """ - - def write_frame(self, cmd, payload=b""): - if cmd == P.CMD_GET_TCP: - with self._tx_lock: - self.tx_log.append((cmd, bytes(payload))) - self.tx_stamps.append(time.monotonic()) - self._push(P.pack_frame(P.RSP_TCP, b"\x00" * 8)) - return - super().write_frame(cmd, payload) - - -def _silent_probe_transport(): - from fake_serial import FakeTransport - - class _T(_SilentProbe, FakeTransport): - pass - return _T - - -def _sent(arm): - return [c for c, _ in arm._tr.tx_log] - - -def _payloads(arm, cmd): - return [p for c, p in arm._tr.tx_log if c == cmd] - - -def _is_f32(got, want) -> bool: - """按 f32 精度比较 (载荷是 `struct.pack(" None: - """等读线程把已推入桩的帧投递出去 —— 旧"`poll_cart()` 自己读一帧"的等价物。 - - ⚠ `poll_cart()` 现在**不碰链路**(读线程是唯一读者),它只是"看一眼收集器的待认领 - 队列"。所以用例必须先让帧**被投递**,再调它。 - """ - import time as _t - end = _t.monotonic() + timeout - while _t.monotonic() < end and arm._tr._resp: - _t.sleep(0.002) - _t.sleep(0.01) - - -def test_probe_sends_an_empty_move_l_payload(offline_arm): - """探测帧**必须是空载荷**: 合法载荷的 `0x3A` 会让臂真的动 (那是运动命令, 不是查询)。""" - arm = offline_arm - assert arm._cart_supported is True, "普通桩 (有笛卡尔) 的探测结果应为 True" - assert _payloads(arm, P.CMD_MOVE_L) == [b""], ( - "探测发的 0x3A 不是空载荷 —— 合法载荷就是 connect 之后臂自己动一下") - assert arm._cart.pending == 0, "探测帧登记了 token (会造出一个永远等不到 0x4E 的悬挂态)" - - -def test_probe_goes_through_the_query_port_not_the_action_port(offline_arm): - """探测走 `_write_query` (查询口), **不是** `_write_cmd` (动作口) —— 见 `probe` 的实现。 - - ⚠ 两个口在"没在拖动示教"时行为逐字节相同, 所以只有**零重力保活期**这一种形状能把它们 - 分开: `_write_cmd` 带零重力守卫, 会把这条**空载荷的探测**当成动作命令拒掉 - (`InvalidCommandError`); 而 `_write_query` 那条路的 docstring 明写"拖动示教期间仍应能 - 读状态"。 - ⚠ 探测确实是**查询语义**: 载荷是空的, 固件在**长度校验**那一关就回 - `ERR{cmd,0x01}` —— 排在一切副作用之前, 臂不会动 (见 `probe` 的 docstring 与 - `test_probe_sends_an_empty_move_l_payload`)。故它不该被动作口那道守卫拦。 - """ - from litearm import cart as cart_mod - - arm = offline_arm - arm._zg_active = True # 拖动示教保活期 - try: - assert cart_mod.probe(arm) is True, "零重力保活期探测被拒了 (走了动作口)" - finally: - arm._zg_active = False - assert (P.CMD_MOVE_L, b"") in arm._tr.tx_log, "探测帧根本没发出去" - - -def test_probe_is_done_once_in_connect_not_lazily(offline_arm): - """探测在 `connect()` 里做一次; 之后每次入口调用不再重探。""" - arm = offline_arm - n0 = _sent(arm).count(P.CMD_MOVE_L) - assert n0 == 1, f"connect() 应恰好探测一次, 实测 {n0} 次" - arm.move_l(TCP0, speed=0.3) - arm.move_l(TCP0, speed=0.3) - assert _sent(arm).count(P.CMD_MOVE_L) == 3, "入口调用又探了一次" - - -def test_no_cart_firmware_is_detected_offline(offline_arm): - """桩关掉 `cart_supported` = 固件没编进 `LITEARM_CART_PLAN` -> 落 default -> 不支持。""" - from litearm import cart as cart_mod - - arm = offline_arm - arm._tr.cart_supported = False - assert cart_mod.probe(arm) is False - assert arm._cart.pending == 0, "探测帧进了队列" - - -def test_unsupported_firmware_raises_and_sends_nothing(make_arm): - """不支持时三个入口**直接抛 `UnsupportedByFirmwareError` 且一帧都不发**。""" - arm = make_arm(lambda t: setattr(t, "cart_supported", False)).connect() - assert arm._cart_supported is False - for fn in (lambda: arm.move_l(TCP0, speed=0.3), - lambda: arm.move_c(TCP0, TCP0, TCP0, speed=0.3), - lambda: arm.move_path([TCP0], speed=0.3)): - before = list(arm._tr.tx_log) - with pytest.raises(UnsupportedByFirmwareError): - fn() - assert arm._tr.tx_log == before, "不支持时仍然发了帧" - assert arm._cart.pending == 0 - - -def test_silent_probe_is_treated_as_unsupported_not_as_a_crash(make_arm): - """探测帧没被回答时**不抛** —— 判成"不支持"。 - - 依据: 固件的 `default` 分支保证任何固件都会回一条 ERR, 所以"一片安静"只可能是应答 - 丢了; 而在固件声明自己实现之前绝不发一条能起规划的命令, 与"这一帧为什么没回来" - 无关。判成"不支持"的代价是归因含糊 (报错里两种可能都写了); 判成"崩溃"的代价是 - 整个会话连关节空间都用不了 —— 后者更糟。 - """ - arm = make_arm(cls=_silent_probe_transport()).connect() - assert arm._cart_supported is False - with pytest.raises(UnsupportedByFirmwareError): - arm.move_l(TCP0, speed=0.3) - - -def _flaky_probe_transport(drop_first: int = 1): - """桩混入: 把 `0x3A` 的**前 `drop_first` 帧应答丢掉** (其余照常) —— 模拟上行丢帧。 - - ⚠ 丢的必须是**应答**而不是下行帧: 下行帧照记 `tx_log` —— "重试有没有真的重发" - 正是靠它判的。 - """ - from fake_serial import FakeTransport - - class _T(FakeTransport): - _dropped = 0 - - def write_frame(self, cmd, payload=b""): - if cmd == P.CMD_MOVE_L and _T._dropped < drop_first: - _T._dropped += 1 - with self._tx_lock: - self.tx_log.append((cmd, bytes(payload))) - self.tx_stamps.append(time.monotonic()) - return - super().write_frame(cmd, payload) - - return _T - - -def test_a_lost_probe_reply_is_retried_not_read_as_unsupported(make_arm): - """⚠ 本组是"安静 ≠ 不支持"的判据: 丢一帧应答**不得**把整个会话判成不支持。 - - 固件的 `default` 分支保证**任何**固件都会对 `0x3A` 回一条 `ERR{cmd,0x00}`, 所以读超时 - 只可能是**这一帧丢了** (本硬件 USB CDC 上行有已知丢帧); 而探测结果在 `connect()` - 里缓存**整个会话**, 一次丢帧就把笛卡尔能力误判成"固件没编进去"。 - """ - arm = make_arm(cls=_flaky_probe_transport(drop_first=1)).connect() - assert arm._cart_supported is True, "丢了一帧应答就把整个会话的笛卡尔判成不支持" - assert _payloads(arm, P.CMD_MOVE_L) == [b"", b""], "重试时没有再发一帧探测" - - -def test_all_silent_probes_leave_the_reason_as_unconfirmed(make_arm): - """3 次都安静 ⇒ 判"不支持"(fail-closed), 且**报错要能与"固件确报不支持"区分**。 - - 没有这条区分, 现场只能看到一个笼统的"固件不支持笛卡尔", 无法判断该换固件还是 - 该查链路 —— 两种可能的原因完全不同。 - """ - arm = make_arm(cls=_silent_probe_transport()).connect() - assert arm._cart_supported is False - assert _payloads(arm, P.CMD_MOVE_L) == [b""] * 3, "安静时的重试次数不是 3" - with pytest.raises(UnsupportedByFirmwareError) as ei: - arm.move_l(TCP0, speed=0.3) - assert "探测未获确认" in str(ei.value), "报错没有写明是「没等到应答」这一支" - - -def test_a_probe_answered_with_err_00_is_not_retried(make_arm): - """`ERR{0x3A,0x00}` 是**确定结论** (固件确实没有这条命令) ⇒ 立刻返回, **不重试**。""" - arm = make_arm(lambda t: setattr(t, "cart_supported", False)).connect() - assert arm._cart_supported is False - assert _payloads(arm, P.CMD_MOVE_L) == [b""], "固件已确报不支持却仍在重试" - with pytest.raises(UnsupportedByFirmwareError) as ei: - arm.move_l(TCP0, speed=0.3) - msg = str(ei.value) - assert "固件确报不支持" in msg, "报错没有写明是「固件确报不支持」这一支" - assert "探测未获确认" not in msg, "把已确认的结论报成了「未获确认」" - - -# --------------------------------------------------------------------------- -# 2. 守卫顺序 —— 全部排在 request() (登记 token) 之前 -# --------------------------------------------------------------------------- - -def test_zero_g_guard_fires_before_the_token_is_registered(offline_arm): - """⚠ 本组是关键判据: `_zg_active=True` 时抛 `InvalidCommandError` **且 `pending == 0`**。 - - `pending == 0` 的意思是"**根本没登记**", 不是"登记之后又摘掉" —— 若守卫被放进 - `request()` 里面, 异常会在写的位置抛出, 而 `_CartPending.request` 只对 - `TransportError` 摘 token, 于是这条 token 留在队里, 下一次 `0x4E` 就配错对象。 - """ - arm = offline_arm - arm._zg_active = True # 只置标志, 不起保活线程 - for label, fn in (("move_l", lambda: arm.move_l(TCP0, speed=0.3)), - ("move_c", lambda: arm.move_c(TCP0, TCP0, TCP0, speed=0.3)), - ("move_path", lambda: arm.move_path([TCP0], speed=0.3))): - before = list(arm._tr.tx_log) - with pytest.raises(InvalidCommandError): - fn() - assert arm._cart.pending == 0, f"{label}: 守卫在登记之后才拦 —— token 滞留了" - assert arm._tr.tx_log == before, f"{label}: 零重力保活期间仍然发了帧" - - -def test_not_connected_raises_before_the_token_is_registered(): - """未连接 (`NotConnectedError`) 同样必须早于登记 —— 它是另一个"写之前就抛"的异常。""" - from litearm import Arm - - arm = Arm() - with pytest.raises(NotConnectedError): - arm.move_l(TCP0, speed=0.3) - assert arm._cart.pending == 0 - - -def test_bad_arguments_are_validated_before_the_frame_is_written(offline_arm): - arm = offline_arm - for fn in (lambda: arm.move_l(TCP0, speed=1.5), - lambda: arm.move_l((0.3, 0.0), speed=0.3), - lambda: arm.move_path([], speed=0.3), - lambda: arm.move_path([TCP0] * 33, speed=0.3)): - before = list(arm._tr.tx_log) - with pytest.raises(InvalidCommandError): - fn() - assert arm._tr.tx_log == before, "参数校验失败却已经发了帧" - assert arm._cart.pending == 0 - - -# --------------------------------------------------------------------------- -# 3. 帧布局 (逐字节, 照固件 `usb_cmd.h`) -# --------------------------------------------------------------------------- - -def test_move_l_payload_is_pose6_plus_speed(offline_arm): - arm = offline_arm - plan = arm.move_l((0.31, 0.0, 0.36, 0.0, 0.0, 0.0), speed=0.3) - ps = _payloads(arm, P.CMD_MOVE_L)[-1] - assert len(ps) == 28, "0x3A 载荷应 28B (pose[6]f32 + sp f32)" - assert _is_f32(P.unpack_f32s(ps, 0, 6), [0.31, 0.0, 0.36, 0.0, 0.0, 0.0]) - assert P.unpack_f32s(ps, 24, 1)[0] == pytest.approx(0.3, abs=1e-6) - assert plan.ok and plan.n_wp == arm._tr.cart_n_wp - assert plan.plan_us == arm._tr.cart_plan_us - - -def test_move_l_invalid_speed_rejected(offline_arm): - """`speed` 越界必须在**发帧之前**被拒 —— `0x3A` 一出门, 臂就真的动。 - - ⚠ **改靶说明**: 本条从已删的 `tests/test_cartesian_motion.py` 摘出保留 (原名 - `test_movel_invalid_speed_rejected`)。原靶 `Arm.movel` 随 PC 侧规划子包删除, 而 - 它测的**从来不是**被删的规划器 —— 是 `speed` 的取值校验本身。新载体是 - `cart._as_speed` (三个固件侧入口 `move_l`/`move_c`/`move_path` 共用同一把尺子), - 这里以 `move_l` 为代表钉住"越界抛 `InvalidCommandError`"。 - - ⚠ **判据集不能照搬原用例**: 原用例喂的是 `(0.0, -1.0, 1.5)`, 而 `0.0` 在 - **旧 PC 规划器**那里才是非法的 (它要 `0 < speed` 保证剖面可解)。新载体与新域的 - 是 `[0, 1]` **闭区间** —— 与同文件的 `Arm.movej` / `Arm.movej_sync` 逐字一致 - (`arm.py` 两处都写 `0.0 <= float(speed) <= 1.0`)。`0.0` 在这里**合法且安全**: - 固件 `cart_plan.c` 把乘过 speed 的限幅做了下限 clamp (`p->v_lim = fmaxf(v_lim * - speed, 1e-4f)`), 且那份源码在 clamp 处自带注释"若将来有人想删, 先补一条 speed→0 - 的用例" —— 即"speed 极小"是固件显式覆盖过的输入, 不是漏网。照搬 `0.0` 会让本条 - 变成常在的假红。 - """ - arm = offline_arm - for bad in (-1.0, 1.5, 2.0): - n_before = len(_sent(arm)) - with pytest.raises(InvalidCommandError, match="speed"): - arm.move_l((0.31, 0.0, 0.36, 0.0, 0.0, 0.0), speed=bad) - assert _sent(arm)[n_before:] == [], f"speed={bad} 被拒前已经发帧" - - -def test_move_c_payload_is_via_end_speed(offline_arm): - arm = offline_arm - via = (0.30, 0.0, 0.40, 0.0, 0.0, 0.0) - goal = (0.32, 0.0, 0.40, 0.0, 0.0, 0.0) - arm.move_c(TCP0, via, goal, speed=0.3) - ps = _payloads(arm, P.CMD_MOVE_C)[-1] - assert len(ps) == 52, "0x3B 载荷应 52B (via[6] + end[6] + sp)" - assert _is_f32(P.unpack_f32s(ps, 0, 6), via) - assert _is_f32(P.unpack_f32s(ps, 24, 6), goal) - assert P.unpack_f32s(ps, 48, 1)[0] == pytest.approx(0.3, abs=1e-6) - - -def test_move_path_is_begin_then_add_then_run(offline_arm): - """`0x3C`(n+sp) -> `0x3D`×n (idx+pose) -> `0x3E`(空); **token 只登记在 RUN 上**。""" - arm = offline_arm - pts = [TCP0, (0.30, 0.0, 0.40, 0.0, 0.0, 0.0), (0.32, 0.0, 0.40, 0.0, 0.0, 0.0)] - plan = arm.move_path(pts, speed=0.3) - sent = _sent(arm) - # ⚠ 切到 **RUN 为止**: `wait=True` 的收尾还会回读一次 `get_tcp` (0x43) 与目标比对, - # 那一条排在 RUN **之后** —— 用 `sent[-5:]` 会把 0x43 当成第五帧。 - end = sent.index(P.CMD_CART_RUN) + 1 - ids = sent[end - 5:end] - assert ids == [P.CMD_CART_BEGIN, P.CMD_CART_ADD, P.CMD_CART_ADD, P.CMD_CART_ADD, - P.CMD_CART_RUN], ids - begin = _payloads(arm, P.CMD_CART_BEGIN)[-1] - assert len(begin) == 5 and begin[0] == 3, "0x3C 载荷应 5B (n u8 + sp f32)" - adds = _payloads(arm, P.CMD_CART_ADD) - assert len(adds) == 3 - for i, (a, p) in enumerate(zip(adds, pts)): - assert len(a) == 25, "0x3D 载荷应 25B (idx u8 + pose[6])" - assert a[0] == i and _is_f32(P.unpack_f32s(a, 1, 6), p) - assert _payloads(arm, P.CMD_CART_RUN)[-1] == b"", "0x3E 是空载荷" - assert plan.ok - assert arm._cart.pending == 0, "RUN 的 token 没有被 wait 取走" - - -class _WatermarkSpy(FakeTransport): - """记下**每次下行之前**的 `status_seq` 与 `tx_log` 长度 —— 给"水位线取在哪"那条用例。 - - ⚠ `BEGIN` 的应答前**先交一帧状态**: 真固件的 100Hz 状态流不会因为主机在发 BEGIN 就 - 停下来。没有这一帧, "水位线取在 BEGIN 之前"与"取在 BEGIN 之后"在桩上**看不出差别** - (`status_seq` 只数**交付给 SDK 的**帧, 而 BEGIN 的 ACK 交换本身不交付状态帧), - 那条用例就白写了。 - """ - - def __init__(self, *a, **kw) -> None: - super().__init__(*a, **kw) - #: (命令, 该次下行**之前**的 status_seq, 该次下行**之前**的 tx_log 长度) - self.downlink_marks: list = [] - - def write_frame(self, cmd, payload=b""): - self.downlink_marks.append((cmd, self.status_seq, len(self.tx_log))) - if cmd == P.CMD_CART_BEGIN: - self._push(_status(self.q, mode=1, n=self.n)) - return super().write_frame(cmd, payload) - - -def test_move_path_takes_the_watermark_before_begin(monkeypatch): - """⚠ 水位线 (`seq0`) 必须取在 **BEGIN 之前** —— "命令"是 BEGIN+ADD×n+RUN 这**一整段**。 - - 取在段中间 (BEGIN 之后) 就把这一段最早的那几帧挪出了"命令之后"的窗口。 - 这条事实此前**没有测试**: 把 `seq0 = _seq_now(arm)` 挪进 `with` 里 (BEGIN 之后), - 全量 398 条照旧全绿 —— 而注释是把"取在 BEGIN 之前"当**承重**写的。 - - 判据 (两条, 同时断言, 各守一头): - ① **位置**: `_seq_now()` 被调用时 `tx_log` 里**还没有**这一段的第一条帧 (BEGIN —— - 在本桩上它是会话的**第三条**帧: 前两条是 `connect()` 的版本握手与空载荷能力探测)。 - 这条就是"取在 BEGIN 之后"的判别式 (那段代码只要挪进 `with` 就必然落在 BEGIN 的帧写 - 之后 ⇒ ① 红); - ② **取值来源**: 它拿到的必须是 BEGIN **下行之前那一刻**的 `status_seq` (桩在 BEGIN - 应答前交了一帧状态, 所以"取在 BEGIN 之后"会拿到一个**更大**的数)。① 过了而 ② 红 - 只有一种走法 —— `_seq_now` 被换成读某处**陈旧**水位线 (那时位置对、值不对), - 所以两条都要在。 - """ - import litearm.arm as arm_mod - import litearm.cart as cart_mod - - def factory(port="fake", timeout=0.2, **_ignored): - return _WatermarkSpy(port=port, timeout=timeout) - - monkeypatch.setattr(arm_mod, "SerialTransport", factory) - arm = Arm(port="fake").connect() - tr = arm._tr - - seen = [] - real_seq_now = cart_mod._seq_now - - def spy(a): - v = real_seq_now(a) - seen.append((v, len(a._tr.tx_log))) - return v - - monkeypatch.setattr(cart_mod, "_seq_now", spy) - arm.move_path([TCP0, (0.30, 0.0, 0.40, 0.0, 0.0, 0.0)], speed=0.3) - - assert len(seen) == 1, f"水位线取了 {len(seen)} 次 —— 用例自身失效" - got, n_tx = seen[0] - marks = [m for m in tr.downlink_marks - if m[0] in (P.CMD_CART_BEGIN, P.CMD_CART_ADD, P.CMD_CART_RUN)] - assert marks and marks[0][0] == P.CMD_CART_BEGIN, "这一段的第一条帧不是 BEGIN" - _, begin_seq, begin_tx = marks[0] - assert n_tx <= begin_tx, ( - f"水位线是在这一段的帧**写出去之后**取的: 取的时候 `tx_log` 已经有 {n_tx} 条帧, " - f"而 BEGIN (这一段的第一条) 在下标 {begin_tx} —— 段内最早的几帧被挪出了窗口") - assert got == begin_seq, ( - f"水位线不是 BEGIN 下行**之前**那一刻的值 (取到 {got}, 应为 {begin_seq})") - - -def test_move_path_failure_midway_is_raised_and_not_papered_over(offline_arm): - """BEGIN/ADD 中途失败 -> 抛错, 且**不发任何**"清状态"的补偿命令 (固件 RECV 2s 自愈)。""" - arm = offline_arm - arm._tr.err_override[P.CMD_CART_ADD] = 0x04 - with pytest.raises(CommandRejectedError): - arm.move_path([TCP0, TCP0], speed=0.3) - assert P.CMD_CART_RUN not in _sent(arm), "ADD 失败后仍然发了 RUN" - assert arm._cart.pending == 0 - - -# --------------------------------------------------------------------------- -# 4. move_c 的起点校验 —— 复用 `_pose_near` 的**两条**判据 -# --------------------------------------------------------------------------- - -def test_move_c_rejects_a_start_far_from_the_actual_tcp(offline_arm): - arm = offline_arm - before = list(arm._tr.tx_log) - with pytest.raises(InvalidCommandError) as ei: - arm.move_c((0.50, 0.0, 0.35, 0.0, 0.0, 0.0), TCP0, TCP0, speed=0.3) - assert "0.5" in str(ei.value), "报错要给出**实际起点**" - # ⚠ 只断言"没发 0x3B": 校验要用 `get_tcp` (0x43) 读实测起点, 那一条**该**发。 - assert P.CMD_MOVE_C not in _sent(arm), "校验失败却已经发了帧 (0x3B 受理即起跑)" - assert len(arm._tr.tx_log) > len(before) - assert arm._cart.pending == 0 - - -#: 固件/本包两侧**锁带宽度不同**的那条带里的一点 (`_rot.mat_to_rpy` 的 docstring 实测): -#: 本包 `|pitch|` 距 `π/2` 小于 `1e-6` 才走锁分支, 固件是 `|cos(pitch)| <= 1e-4` -#: (`kin.c:362`/`:376`)。取 `5e-5` —— 离两侧边界各约 50 倍, 两条分支各自稳稳成立。 -_LOCK_BAND_PITCH = math.pi / 2 - 5e-5 - - -def test_move_c_start_check_reuses_the_rotation_equivalence_branch(offline_arm): - """⚠ 万向锁附近: **同一个旋转**可以给出差很远的 rpy 分量 ⇒ 只抄逐分量判据会判失败。 - - ⚠⚠ **这条判据在 `move_c` 上可达的形状只有一种**, 别按"给一个非规范形的 start"去写 - —— 那种写法**碰不到**这条分支 (实测: 用它时, 把被测实现换成忠实的逐分量版, - 全量套件照**绿**; 也就是"声称守了、实际抓不到"): - - `move_c` 的 `start` 一定过 `cart._as_pose6` ⇒ 一定被 `_rot.mat_to_rpy(rpy_to_mat(…))` - **归一化** (给出 6 标量或 `(pos, R)` 都一样, 那条路径结尾恒是 `mat_to_rpy`)。所以 - 非规范形**只能出在固件回读那一侧** (`get_tcp` 的 `rpy` 走固件的 `kin_rot_to_rpy`)。 - 两侧的**锁带宽度不同** (见 `_LOCK_BAND_PITCH`), 于是存在一条带: 固件已经走锁分支 - (强制 `yaw=0`) 而本包还没走 —— 带内对**同一个旋转**给出的分量可以差 O(1) rad。 - - 本用例就取带内一点: `pitch = π/2 − 5e-5`, `roll = yaw = 0.5`。 - * 固件那条 (`rpy_override`) 是它锁分支的输出 —— `(roll−yaw, pitch, 0)` = `(0, pitch, 0)`; - * 给 `move_c` 的 `start` 是本包归一化后的 `(0.5, pitch, 0.5)`。 - 两者只差测地夹角 ~2.5e-5 (远小于 `CART_START_RPY_TOL`), 逐分量却差 **0.5** rad。 - """ - arm = offline_arm - pitch = _LOCK_BAND_PITCH - arm._tr.pos_override = [0.30, 0.0, 0.35] - arm._tr.rpy_override = [0.0, pitch, 0.0] # 固件锁分支的输出 (yaw 被强制 0) - start = (0.30, 0.0, 0.35, 0.5, pitch, 0.5) - - # 用例自身的两道前置判据 (不成立就说明它验的是别的东西, 不是"旋转等价"那一支) - tcp_rpy = [0.0, pitch, 0.0] - assert max(abs(start[3 + i] - tcp_rpy[i]) for i in range(3)) >= CART_START_RPY_TOL, ( - "用例没有构造出分量差足够大的姿态 —— 逐分量判据本来就会过, 验不到这一支") - assert _orient_angle(tcp_rpy, start[3:6]) < CART_START_RPY_TOL, ( - "用例的两个姿态其实**不是**同一个旋转 —— 那它验的是反例那一侧") - - arm.move_c(start, (0.30, 0.0, 0.40, 0.0, 0.0, 0.0), - (0.32, 0.0, 0.40, 0.0, 0.0, 0.0), speed=0.3) # 不应抛 (起点校验必须过) - - # 反例: 姿态**真的**不同 (同一个 pitch 下摆 yaw, 相差 0.5 rad) -> 必须拒 - with pytest.raises(InvalidCommandError): - arm.move_c((0.30, 0.0, 0.35, 0.0, pitch, 0.5), - (0.30, 0.0, 0.40, 0.0, 0.0, 0.0), - (0.32, 0.0, 0.40, 0.0, 0.0, 0.0), speed=0.3) - - -# --------------------------------------------------------------------------- -# 5. `0x4E` 的 err -> 异常 (⚠ 与 `RSP_ERR` 的门禁原因码是两套码) -# --------------------------------------------------------------------------- - -def test_move_c_refuses_to_send_when_the_current_tcp_cannot_be_read(make_arm): - """⚠ `move_c` 的起点校验是**发帧之前**的最后一道门 —— 取不到 TCP 就**一帧不发**。 - - 固件圆弧的起点恒为**实测 TCP** (载荷里没有 start)。发出去就等于让臂从"此刻真实位置" - 起跑, 而我们连"此刻在哪"都没读到 —— 无从校验起点。故这一支必须当场抛 - `TransportError`: `0x3B` **受理即起跑**, 没有"发出去再判"的安全顺序。 - """ - arm = make_arm(cls=_ShortTcpPayload).connect() - before = len(arm._tr.tx_log) - with pytest.raises(TransportError) as ei: - arm.move_c(TCP0, (0.30, 0.0, 0.40, 0.0, 0.0, 0.0), - (0.32, 0.0, 0.40, 0.0, 0.0, 0.0), speed=0.3) - - assert "TCP" in str(ei.value), "报的错没说是取不到 TCP" - assert arm._tr.tx_log[before:] == [(P.CMD_GET_TCP, b"")], ( - "取不到 TCP 却把 0x3B 发出去了 (受理即起跑, 起点无从校验)") - assert arm._cart.pending == 0, "没发帧却登记了 token" - - -def test_settled_stays_false_when_the_tcp_cannot_be_read(make_arm): - """⚠ 「停稳」≠「停在了目标上」: 收尾回读 TCP **取不到**时 `settled` 必须**保持 False**。 - - `_tcp_reached` 的保守方向是写死的: 取不到就报"没到位" (超时 / 断连 / 被别的 `ERR` - 串台), 与"宁可报未知"同向。放行成"停在目标上了"就在**假成功**那一侧 —— 而这条正是 - "停稳 ≠ 停在目标上"唯一的一道防线 (轨迹被别的运动作废时收尾同样是 `bit10=0` + `q` 静止)。 - """ - arm = make_arm(cls=_ShortTcpPayload).connect() - arm.move_timeout = 1.0 - plan = arm.move_l(TCP0, speed=0.3) # wait=True 默认: 等到停稳 + 回读 TCP - - assert plan.ok, "用例自身失效: 规划没成功" - assert plan.settled is False, ( - "取不到 TCP 却把这条报成'停在目标上' —— 假成功方向, 且这是唯一一道防线") - - -@pytest.mark.parametrize("err,exc", [ - (1, IKError), - (2, CartesianPlanError), # COLLINEAR (⚠ 固件头文件注释写 0x03, 真值是 2) - (3, CartesianPlanError), # TOO_LONG - (4, CartesianPlanError), # LIMIT - (5, MotionSupersededError), # CANCELED = 预期内的接管 - (6, InvalidCommandError), # BADARG - (9, CartesianPlanError), # 未登记的档: 不得静默吞掉 -]) -def test_plan_err_maps_to_the_right_exception(offline_arm, err, exc): - arm = offline_arm - arm._tr.cart_err_override = err - with pytest.raises(exc) as ei: - arm.move_l(TCP0, speed=0.3) - assert f"err={err}" in str(ei.value), "异常消息里要带原始 err" - if err == 5: - assert not isinstance(ei.value, CartesianPlanError), ( - "接管 (CANCELED) 被并进了『规划失败』 —— 调用方会把正常抢占走成故障恢复") - assert arm._cart.pending == 0 - - -def test_plan_failure_is_not_a_command_rejection(offline_arm): - """接管/规划失败都不是"固件拒绝执行这条命令" (`RSP_ERR`) —— 不得混进那个类型。""" - arm = offline_arm - arm._tr.cart_err_override = 5 - with pytest.raises(MotionSupersededError): - arm.move_l(TCP0, speed=0.3) - arm._tr.cart_err_override = 3 - with pytest.raises(CartesianPlanError) as ei: - arm.move_l(TCP0, speed=0.3) - assert not isinstance(ei.value, CommandRejectedError) - - -def test_gate_style_rejection_drops_the_token(offline_arm): - """固件**显式拒绝** (门禁/长度校验回 `RSP_ERR`) 时那条 token 必须摘掉。 - - 受理前的每一道校验都在 `cart_req_*` 之前 `break`, 所以"回 ERR ⟹ 永远不会有 0x4E"。 - 留着它会占住 FIFO 队首, **下一条**合法命令的应答被配给它 —— 下一条报"结局未知", - 死 token 却被"报成功", 正是本模块最防的那一侧。 - """ - arm = offline_arm - arm._tr.err_override[P.CMD_MOVE_L] = 0x03 # 固件门禁: 未使能 - with pytest.raises(CommandRejectedError): - arm.move_l(TCP0, speed=0.3) - assert arm._cart.pending == 0, "被显式拒绝的 token 留在队里了" - arm._tr.err_override.pop(P.CMD_MOVE_L) - plan = arm.move_l(TCP0, speed=0.3) # 配对没有错位 - assert plan.ok - - -# --------------------------------------------------------------------------- -# 6. `CartPlan` 的字段语义 (本版只等到"规划结果") -# --------------------------------------------------------------------------- - -def test_unwaited_fields_are_the_documented_defaults(offline_arm): - """⚠ `wait=False` 时到位相关的四个字段恒为"未等待"默认值 (`CartPlan` docstring 的表)。 - - 这条是给后人的护栏: 谁把 `started_busy` 填成真值, 必须连带把到位判据一起接上, - 不能只改一半 (调用方会以为拿到的是到位结论)。判据落在 **`wait=False` 这一支**上 - —— 不是"入口恒不等待" (`wait=True` 的默认语义见 `tests/test_cart_wait.py`)。 - """ - plan = offline_arm.move_l(TCP0, speed=0.3, wait=False) - assert (plan.started_busy, plan.settled, plan.q_final, - plan.settle_err_rad) == (False, False, [], 0.0) - assert isinstance(plan, CartPlan) - - -def _plan_payload(ok: int, err: int, n_wp: int = 12, plan_us: int = 4700) -> bytes: - """`0x4E` 的 8B 载荷: `ok u8 + err u8 + n_wp u16 LE + plan_us u32 LE`。""" - return (bytes([ok, err]) + struct.pack(" bytes: - return bytes([ok, err]) + n_wp.to_bytes(2, "little") + plan_us.to_bytes(4, "little") - - -def test_poll_cart_claims_a_result_that_nobody_waited_for(offline_arm): - arm = offline_arm - arm._cart.register() # 手工登记一条在途请求 - arm._tr._resp.clear() # 让下一次取帧**一定**拿到下面这一条 - arm._tr.push_frame(P.RSP_CART_PLAN, _plan_frame(1, 0, n_wp=arm._tr.cart_n_wp, - plan_us=arm._tr.cart_plan_us)) - _await_collector(arm) - plan = arm.poll_cart() - assert plan is not None and plan.ok and plan.n_wp == arm._tr.cart_n_wp - assert arm.poll_cart() is None, "同一条结果被认领了两次" - assert arm._cart.pending == 0 - - -def test_poll_cart_returns_none_when_there_is_nothing_to_claim(offline_arm): - assert offline_arm._cart.pending == 0 - assert offline_arm.poll_cart() is None - - -def test_poll_cart_does_not_steal_a_frame_from_a_running_entry(offline_arm): - """⚠ `poll_cart()` 会读一帧 ⇒ 它**是**个抢帧者, 必须与在跑的入口互斥。 - - 实测 (改前): 往内核缓冲里塞一条**在飞那条命令**的 `ACK{0x3A}`, 再调 `poll_cart()` —— - 那条 ACK **被它吃掉** (`_resp` 剩 0 字节), 而它的主人随后耗满窗口报 - `MotionTimeoutError("无应答")`, **命令其实已被固件受理**。这与 F4 修的是**同一类** - (读帧动作在别处并发发生), 只是 F4 那条是 `move_c` 的 `get_tcp()`, 这条是 `poll_cart`。 - - 修法是让它也走 `Arm._cart_serial` 的**非阻塞** `acquire`: 拿不到 (有笛卡尔入口在用 - 这条链路, 它自己会取帧) 就返回 `None` —— "此刻没有可取的结果"本来就是本方法的 `None` - 语义, 而"别人正在用"比"抢他一帧"好。 - - 判据: `None` **且**那条 ACK 还在库里 (改前只满足前一半 —— 帧没了却什么都不报)。 - """ - arm = offline_arm - arm._tr._resp.clear() - arm._tr.push_frame(P.RSP_ACK, bytes([P.CMD_MOVE_L])) # 在飞那条命令的 ACK - assert len(arm._tr._resp) == 1, "用例自身失效: 帧没进库" - - held, release = threading.Event(), threading.Event() - - def _hold(): - arm._cart_serial.acquire() # 模拟"有笛卡尔入口正持锁在跑" - held.set() - release.wait(5.0) - arm._cart_serial.release() - - t = threading.Thread(target=_hold, daemon=True) - t.start() - try: - assert held.wait(5.0), "用例自身失效: 没拿到锁" - assert arm.poll_cart() is None, ( - "锁被占时 poll_cart 本该返回 None ('此刻没有可取的结果')") - assert len(arm._tr._resp) == 1, ( - "poll_cart 把在跑那条命令的 ACK 抢走了 —— 它的主人随后会报'无应答', " - "而命令其实已被受理 (与 F4 同一类)") - finally: - release.set() - t.join(5.0) - - -class _KernelBufferSerial: - """`serial.Serial` 的**保真**替身 —— `read(n)` 从"内核 RX 缓冲"取字节。 - - ⚠ 与 `fake_serial.FakeTransport` 的关键差别: 这里"数据在不在库里"与"SDK 有没有去取" - 是**两件分得开**的事 (桩把 `timeout` 参数整个忽略掉, 于是"SDK 一个字节都没读"在桩上 - 看不出来)。`timeout=0` 的真实语义 (非阻塞: 有就返回、没有就 `b""`) 由 `read` 体现; - 本用例只走"数据早已在库里"那一支, 所以**不**模拟阻塞等待 (不引入睡眠)。 - """ - - def __init__(self, *a, **kw): - self.timeout = kw.get("timeout", 0.2) - self.kbuf = bytearray() - self.is_open = True - self.written = bytearray() - - def read(self, n=1): - if not self.kbuf: - return b"" - out = bytes(self.kbuf[:n]) - del self.kbuf[:n] - return out - - def write(self, d): - self.written += d - return len(d) - - def flush(self): - pass - - def close(self): - self.is_open = False - - -def test_poll_cart_claims_a_result_from_a_real_transport(monkeypatch): - """⚠ `poll_cart()` 必须在**真** `SerialTransport` 上认领得到结果 —— 桩会骗人。 - - `fake_serial.FakeTransport.read_frame` **忽略 `timeout` 参数**, 于是 - `test_poll_cart_claims_a_result_that_nobody_waited_for` 在**桩**上通过 —— 而它断言的 - 正是"非阻塞取帧能拿到**已到达**的帧", 真机上不成立 (旧实现 `read_frame(0.0)` 一个字节 - 都不读 ⇒ `poll_cart()` 恒 `None`)。本用例把这一层换成"内核 RX 缓冲"模型, 走的仍是 - 真正的 `litearm.transport.SerialTransport`。 - - ⚠ 与桩用例的**分工**: 桩用例管"认领语义" (claim_resolved / 不重复交付), 本用例只管 - "真读路径确实取得到" —— 前者改桩、后者才咬得住这个缺陷。 - ⚠ 2026-09-22 读路径重构后,"真读路径"从 `poll_cart` 挪到了**读线程**(见下面那行 - `start_reader`);判据(认领得到、且内核缓冲真的被取空)逐字不变。 - """ - monkeypatch.setitem(sys.modules, "serial", - types.SimpleNamespace(Serial=_KernelBufferSerial)) - from litearm.arm import _Ack - from litearm.transport import SerialTransport - - tr = SerialTransport("faketty") - kern = tr._ser - kern.kbuf += P.pack_frame( # 固件早就发来了, 只是**没人读过** - P.RSP_CART_PLAN, _plan_frame(1, 0, n_wp=12, plan_us=4700)) - - arm = Arm(port="faketty") # 只测**读路径**: 手工接线, 不做握手/探测 - arm._tr = tr - arm._a = _Ack(arm) - arm._cart.register() # 一条"登记了、但没人 wait"的在途请求 - # ⚠ **[2026-09-22] 主体改了**:`poll_cart()` 不再自己读链路(读线程是唯一读者), - # 所以"真 transport 上取得到已到达的帧"这件事现在由**读线程**来负责验 —— 不启动 - # reader 的话,帧就永远躺在内核缓冲里。判据里那个"内核缓冲真的被取空"的检查不变。 - arm._a.start_reader(tr) - import time as _t - plan = None - for _ in range(500): - plan = arm.poll_cart() - if plan is not None: - break - _t.sleep(0.002) - assert plan is not None and (plan.ok, plan.n_wp) == (True, 12), ( - "真 transport 上认领不到**已到达**的结果 —— 非阻塞取帧没有真的去读 " - f"(拿到 {plan!r})") - assert kern.kbuf == bytearray(), "帧还留在'内核缓冲'里 —— 一个字节都没取走" - assert arm._cart.pending == 0 and arm.poll_cart() is None - - #: ⚠ 收尾**必须显式 close()**: `tr` 挂在一个 `Arm` 上, 而 `Arm` **有引用环** - #: (`_CartPending(arm=self)`) ⇒ 用例返回后它不会被引用计数回收, 要等一次全量 gc; - #: 在那之前端口名 `"faketty"` 一直被登记表认作占用。靠"对象迟早被回收"来释放端口 - #: 就是把释放时机交给 gc —— `close()` 落在那句 `_release_port` 上, 与 gc 何时跑无关。 - tr.close() - - -def test_poll_cart_maps_failures_like_the_entries(offline_arm): - arm = offline_arm - arm._cart.register() - arm._tr._resp.clear() - arm._tr.push_frame(P.RSP_CART_PLAN, _plan_frame(0, 5)) # CANCELED - _await_collector(arm) - with pytest.raises(MotionSupersededError): - arm.poll_cart() - assert arm._cart.pending == 0, "结局已取走的 token 必须摘掉 (否则会错配下一条)" - - -# --------------------------------------------------------------------------- -# 8. 状态帧的 `CART_BUSY` (bit10) -# --------------------------------------------------------------------------- - -def test_cart_busy_reads_bit10_and_is_not_a_fault_flag(): - from litearm.state import RobotState - - st = RobotState(flags=(1 << 10)) - assert st.cart_busy is True and st.flag_names == [] and st.fault_detail == "无故障位" - assert RobotState(flags=0).cart_busy is False - - -def test_cart_busy_must_not_enter_flag_names(): - """⚠ `FLAG_NAMES` 只放**安全故障位** (bit0..bit5) —— `CART_BUSY`(10) 不属此列。 - - 真正的护栏是 `decode_status` 里那个**隐式的 `range(6)`** (`flag_names` 只看 bit0..5), - **不是**"并进去会被打印成故障位" (实测: 往 `FLAG_NAMES` 加 `10: "CART_BUSY"` 什么都不会 - 发生, 加了照样全绿)。但"现在无事发生"= 这条防线写在**别人的隐式常量**里: 谁把 - `range(6)` 改成"遍历整张表", bit6..bit8 (mode) / bit9 (enabled) / bit10 (cart_busy) - 会**一起**变成"故障位" (故障消息里冒出 `flags=CART_BUSY`)。 - - 故这里把**意图**钉在表面上 (键集合恰是 bit0..bit5) —— 判据能失败: 加一条 - `FLAG_NAMES[10] = "CART_BUSY"` 即红。 - """ - assert set(P.FLAG_NAMES) == set(range(6)), ( - f"`FLAG_NAMES` 的键集合变了: {sorted(P.FLAG_NAMES)} —— 它只装安全故障位 " - f"(bit0..bit5); mode(6..8)/enabled(9)/CART_BUSY(10) 都不是故障, 不属此列") - assert 10 not in P.FLAG_NAMES, "CART_BUSY 被当成故障位了" - - -class _StalledCartWrite(FakeTransport): - """`0x3A` 的**合法载荷**写会**卡住** (等 `release`) 且**永不回**应答。 - - 给"持锁者长时间不放手"那条用例用 —— 那条请求会一直握着 `_cart_serial`。 - ⚠ 其它命令照常应答 (急停/失能/取 TCP 都要能在这期间走过去)。 - """ - - def __init__(self, *a, **kw) -> None: - super().__init__(*a, **kw) - self.write_entered = threading.Event() - self.release = threading.Event() - - def write_frame(self, cmd, payload=b""): - if cmd == P.CMD_MOVE_L and payload: - with self._tx_lock: - self.tx_log.append((cmd, bytes(payload))) - self.tx_stamps.append(time.monotonic()) - self.write_entered.set() - self.release.wait(5.0) # 卡住: 持锁者不放手的写照 - return None - super().write_frame(cmd, payload) - - -def test_lower_energy_commands_stay_reachable_while_the_cart_lock_is_held(monkeypatch): - """⚠ 串行锁**不许**把"降能量方向"的动作与只读查询挡在外面。 - - 持锁者可能阻塞到 `move_timeout` (默认 15s), 而急停/失能 (`guarded=False`) 与取状态 - 必须**永远可达** —— 把它们拉进 `_cart_serial` 就等于"一条卡住的笛卡尔命令能把急停 - 关在门外"。本条的桩把那条 `0x3A` 的写卡住 (于是它持锁不放), 然后断言 - `get_tcp()`/`disable()`/`emergency_stop()` 仍能在 **1s** 内跑完。 - - 判据能失败: 让 `emergency_stop` (或它经过的 `_write_cmd`) 去拿这把锁 —— - 这里会等到超时并报"被挡在门外"。 - """ - import litearm.arm as arm_mod - - def factory(port="fake", timeout=0.2, **_ignored): - return _StalledCartWrite(port=port, timeout=timeout) - - monkeypatch.setattr(arm_mod, "SerialTransport", factory) - arm = Arm(port="fake").connect() - tr = arm._tr - - def run_cart() -> None: - try: - arm.move_l(TCP0, speed=0.3) - except BaseException: # noqa: BLE001 - 这条请求的结局不是被测对象 - pass - - holder = threading.Thread(target=run_cart, name="cart-holder", daemon=True) - holder.start() - assert tr.write_entered.wait(2.0), "那条 0x3A 没进到写里 (用例自身失效)" - try: - done = threading.Event() - - def low_energy() -> None: - arm.get_tcp() # 只读 - arm.disable() # 降能量 - arm.emergency_stop() # 降能量 - done.set() - - threading.Thread(target=low_energy, name="estop", daemon=True).start() - assert done.wait(1.0), ( - "急停/失能/取 TCP 被 `_cart_serial` 挡在门外 —— 持锁者可能阻塞到 " - "move_timeout(15s), 这条路径必须永远可达") - finally: - tr.release.set() # 放手, 别让卡住的写拖住收尾 - tr.push_frame(P.RSP_ACK, bytes([P.CMD_MOVE_L])) - holder.join(2.0) - - -def test_stub_emits_the_written_busy_frame_order(offline_arm): - """桩的 bit10 帧序**写死**: 收到 `0x4E` 后第 2 帧置 1、第 8 帧落 0。 - - 这条把桩的契约钉住 —— "先见 1 再见 0"的到位判据正是靠它才有主判据可测。 - - ⚠ **[2026-09-22] 观测方式换了**:从前是"自己取 8 帧、逐帧看 bit10" —— 读线程一开, - 帧由读线程消费,调用方**取不到帧**了。现在看 `_Ack.state` 单槽的 `cart_busy` **轨迹** - (每次 `seq` 变化采一个点),判据是"出现一段**恰好 6 个连续 True**,且它前后都是 False"。 - ⚠ 不钉"第 2..7 帧"这个索引(采样点由读线程的节奏决定,索引不再可观察)。 - """ - import time as _t - arm = offline_arm - arm.move_l(TCP0, speed=0.3, wait=False) - - frames = [] - last_seq = None - deadline = _t.monotonic() + 2.0 - while len(frames) < 12 and _t.monotonic() < deadline: - st = arm._a.state - if st is not None and st.seq != last_seq: - last_seq = st.seq - frames.append(bool(st.cart_busy)) - _t.sleep(0.0005) - - assert True in frames and False in frames, f"没观察到 bit10 的跳变: {frames}" - best = cur = 0 - for b in frames: # 最长的一段连续 True = CART_BUSY 窗口 - cur = cur + 1 if b else 0 - best = max(best, cur) - assert best == 6, f"CART_BUSY 窗口不是 6 帧宽: {frames} (最长连续 True={best})" - assert frames[-1] is False, ( - f"观察窗结束时 bit10 还亮着 —— 窗口没有落回 0: {frames}") - - -# --------------------------------------------------------------------------- -# 8b. 串行是强制的 —— ≥2 条在途会**交叉交付** (假成功) -# --------------------------------------------------------------------------- - -#: 桩等"第二个写者"的窗口 (秒)。串行用法下那个写者**不会**来 (它在 `Arm._cart_serial` -#: 上排队), 于是每条用例白等这么久 —— 取 0.4s: 足够让一个已在跑的线程把自己的帧写进来。 -_OVERLAP_WINDOW = 0.4 - -#: 线程名 -> 用例里的短标签 (桩记的是 `threading.current_thread().name`)。 -_THREAD_LABELS = {"cart-A": "A", "cart-B": "B"} - - -class _CrossDeliverTransport(FakeTransport): - """把"第一条"的应答推迟到"第二条"的 `ERR` **之后**的桩 —— 复现真机的帧顺序。 - - 真机顺序: 后受理那条被门禁拒 ⇒ `ERR` **立刻**回; 先受理那条要**等规划**才回 `0x4E` - (10ms~1s) ⇒ `ERR` 排在先受理者的 `ACK`/`0x4E` **之前**。 - - ⚠ 只对**合法载荷**的 `0x3A` 生效 (空载荷是 connect 里的能力探测, 照常走长度校验)。 - ⚠ 第二条的写要**等到那条 `ERR` 被读走**才返回 —— 否则"谁先读"变成抢跑, 用例就不是 - 确定性的 (也就测不出加锁前后的差别)。 - """ - - def __init__(self, *a, **kw) -> None: - super().__init__(*a, **kw) - self._gate = threading.Lock() - #: 谁的 `0x3A` 真被固件受理了 —— 只有它该拿到 `CartPlan`。 - self.accepted_thread = None - self._first_in_write = False - self.second_write_entered = threading.Event() - self.err_pushed = threading.Event() - self.err_consumed = threading.Event() - - def read_frame(self, timeout=None): - fr = super().read_frame(timeout) - if fr is not None and fr[0] == P.RSP_ERR: - self.err_consumed.set() - return fr - - def write_frame(self, cmd, payload=b""): - if cmd != P.CMD_MOVE_L or len(payload) != 28: - return super().write_frame(cmd, payload) - with self._gate: - first = self.accepted_thread is None - if first: - self.accepted_thread = threading.current_thread().name - self._first_in_write = True - if first: - try: - if self.second_write_entered.wait(_OVERLAP_WINDOW): - self.err_pushed.wait(_OVERLAP_WINDOW) # 等它的 ERR 落进队列 - return super().write_frame(cmd, payload) # 现在才推 ACK + 0x4E - finally: - self._first_in_write = False - self.second_write_entered.set() - self._push(P.pack_frame(P.RSP_ERR, bytes([cmd, 0x03]))) # 固件门禁: 未使能 - overlapped = self._first_in_write - self.err_pushed.set() - if overlapped: - self.err_consumed.wait(_OVERLAP_WINDOW) - return None - - -def test_two_concurrent_requests_cannot_cross_deliver(monkeypatch): - """⚠ **两条在途 = 报告与物理事实相反** —— 串行锁 (`Arm._cart_serial`) 必须把两条排开。 - - 复现场景 (真机形状): A、B 同时发 `0x3A`, B 被固件门禁拒 ⇒ `ERR{0x3A,0x03}`, - 而 A 那条**已受理**的 `0x4E` 因为要等规划排在 `ERR` **之后**。无锁时两条线程的 - `expect` 会**互相吃掉对方的帧** (回显只有命令码, `0x3A/0x3B/0x3E` 共用码空间, - 分辨不出来) ⇒ **被拒那条报的不是它自己那条 `ERR`**。 - - 判据必须**逐线程** ("结局集合里有一个成功、一个失败"在错配下**也成立** —— 它恰好 - 就是无锁时的观测): 被受理那条 (由桩记下是哪个线程) 必须拿到 `CartPlan`; 另一条 - **绝不许**是 `CartPlan`, 必须是它自己那条 `CommandRejectedError`。 - - ⚠ **咬住这条用例的是最后那条"逐线程归因"** —— 实测去掉锁之后, 前两条 (被受理者拿到 - `CartPlan` / 另一条不是 `CartPlan`) **照样通过**, 只有归因那条会红 (被拒那条报的是 - `MotionTimeoutError`)。原因: `_Ack.expect(..., err_waits_for_ack=True)` 让一条按命令码 - 匹配的 `ERR` 不再当场作数 (见 `_request_and_wait`), 于是"错拿别人的 ERR ⇒ 摘掉自己的 - token ⇒ 下一条假成功"这条**旧**形态不再发生。锁仍然不可省, 但理由换成了**顺序**: - `_request_and_wait` 先登记后写, 无锁时登记顺序与固件受理顺序可以倒置, 而 `0x4E` 里 - 没有命令 id ⇒ 应答配错 token (失败那条被报成成功)。 - """ - import litearm.arm as arm_mod - - def factory(port="fake", timeout=0.2, **_ignored): - return _CrossDeliverTransport(port=port, timeout=timeout) - - monkeypatch.setattr(arm_mod, "SerialTransport", factory) - arm = Arm(port="fake").connect() - tr = arm._tr - # ⚠ `connect()` 里的能力探测**已经读过一条** `ERR` (空载荷撞长度校验那条), 于是 - # `err_consumed` 在起跑前就是置位的 —— 不清掉的话"第二条写"会直接冲进自己的 `expect`, - # 抢先把 `ERR` 读走, 这条用例就**测不出**加锁前后的差别 (跑出一个"碰巧正确"的结局)。 - tr.err_consumed.clear() - out = {} - start = threading.Barrier(2) - - def run(name: str) -> None: - start.wait() - try: - out[name] = arm.move_l(TCP0, speed=0.3) - except BaseException as e: # noqa: BLE001 - 结局本身就是被测的东西 - out[name] = e - - ta = threading.Thread(target=run, args=("A",), name="cart-A") - tb = threading.Thread(target=run, args=("B",), name="cart-B") - ta.start() - tb.start() - # ⚠ `join` 的上限取 **5s** (不是 30s): 它只在"判据失效"那一支上花时间 —— - # `RLock`→`Lock` 的变异会让同线程二次获取**自己锁死**, 那时两条线程都回不来, - # 两个 `join` 的下限就是这一支的**实测时长** (30s 会把整轮拖住 60s)。 - # 合法路径的时长由 `_OVERLAP_WINDOW` (0.4s) 决定, 5s 有 10 倍余量。 - ta.join(5) - tb.join(5) - - assert set(out) == {"A", "B"}, f"线程没回来: {sorted(out)}" - accepted = _THREAD_LABELS.get(tr.accepted_thread) - assert accepted in ("A", "B"), ( - f"桩没记下哪条被受理 (拿到 {tr.accepted_thread!r}) —— 用例自身失效") - other = "B" if accepted == "A" else "A" - - assert isinstance(out[accepted], CartPlan), ( - f"{accepted} 那条**被固件受理**了, 却报 {out[accepted]!r} —— " - f"它的 expect 认下了另一条命令的 ERR (按命令码判, 0x3A 共用码空间)") - assert not isinstance(out[other], CartPlan), ( - f"{other} 那条**被固件拒绝**了, 却拿到一个 CartPlan ({out[other]}) —— " - f"假成功: 它把被受理那条的 0x4E 配给了自己") - assert isinstance(out[other], CommandRejectedError), ( - f"{other} 的结局是 {out[other]!r}, 应为固件那条 ERR 对应的 CommandRejectedError") - - -def _safe(fn): - """跑一下, 把异常当结局返回 (逐线程判据用)。""" - try: - return fn() - except BaseException as e: # noqa: BLE001 - return e - - -class _GatedPlanTransport(FakeTransport): - """第一条**合法载荷**的 `0x3A` 受理后**扣住** `0x4E`, 直到 `release` 被置位。 - - 给"持锁者还在跑"造一个确定的窗口 (它靠 `wait=True` 一直持着 `Arm._cart_serial`), - 于是"别人能不能在这期间**读帧**"变成可判的。判据落在**下行时序**上 (不依赖"谁先读到" - 这种抢跑): `GET_TCP (0x43)` 是 `move_c` 起点校验那次读, 它若在 `release` 之前就写出去, - 就是在**锁外**读的。 - """ - - def __init__(self, *a, **kw) -> None: - super().__init__(*a, **kw) - self.release = threading.Event() - self.gate_open = False - #: 下行时序 (只看这两条): "plan" = 在飞那条的 `0x4E` 被推出; "tcp" = GET_TCP 被写 - self.order: list = [] - self.early_tcp_read = False - - def _cart_cmd(self, cmd: int, payload: bytes) -> None: - if cmd == P.CMD_MOVE_L and payload and not self.gate_open: - self.gate_open = True - self._push(P.pack_frame(P.RSP_ACK, bytes([cmd]))) - if not self.release.wait(5.0): # 扣住 0x4E - raise AssertionError("用例自身失效: release 一直没来") - self.order.append("plan") - # ⚠ `_push` 收的是**整帧**, `push_frame` 收的是 (id, 载荷) —— 别把载荷喂给 - # `_push` (它会当成帧塞进队列, 再被 `unpack_frame` 判成坏帧**静默丢掉**)。 - self.push_frame(P.RSP_CART_PLAN, - _plan_frame(1, 0, n_wp=self.cart_n_wp, - plan_us=self.cart_plan_us)) - return - super()._cart_cmd(cmd, payload) - - def write_frame(self, cmd: int, payload: bytes = b"") -> None: - if cmd == P.CMD_GET_TCP: - self.order.append("tcp") - if self.gate_open and not self.release.is_set(): - self.early_tcp_read = True # ← 在跑那条还没收尾就写了 = 锁外读 - super().write_frame(cmd, payload) - - -def test_move_c_reads_the_tcp_inside_the_cart_lock(monkeypatch): - """⚠ `move_c` 起点校验那次 `get_tcp()` 必须在 `Arm._cart_serial` **之内** —— 它读的是 - "此刻 TCP", 与正在跑的那条运动本来就是同一个临界区。 - - 锁外读的代价 (E4b 实测 8/8): 那条 `get_tcp` 在**别的线程**正跑着一条笛卡尔轨迹时把 - 它的 `ACK{0x3A}` 抢走 —— `expect` 只认自己读到的那条, 被抢走就**再也找不回来** ⇒ - **受害者报 `MotionTimeoutError`"无应答", 而它的命令早已写进固件并被受理**: 报告与 - 物理事实相反。 - - 判据 (**下行时序**, 与"谁先读到帧"无关): A 那条 `0x4E` 被推出**之前**, `GET_TCP` - **一个都不许**写出去。⚠ 造窗口靠 `release` (0.3s 垫底), 所以本用例**不会**误报失败, - 极端负载下可能误报**通过** —— 判据仍能咬住实现 (去掉锁会立刻变成 `early_tcp_read`)。 - - ⚠ `move_timeout` 取小值 (0.5) 只为让**修复前**那支快点收场: 那里 A 会先耗满 1.0s 的 - ACK 窗口, 而它留在队里的那条陈旧 token 又会吃掉 B 的 `0x4E` ⇒ B 白等一个 - `move_timeout`。修复后两条都按正常路径走完 (实测 ~0.4s)。 - """ - def factory(port="fake", timeout=0.2, **_ignored): - return _GatedPlanTransport(port=port, timeout=timeout) - - import litearm.arm as _arm_mod - - monkeypatch.setattr(_arm_mod, "SerialTransport", factory) - arm = Arm(port="fake", move_timeout=0.5).connect() - tr = arm._tr - out = {} - - def run_l(): - try: - out["l"] = arm.move_l(TCP0, speed=0.3) # wait=True: 持锁到停稳 - except BaseException as e: # noqa: BLE001 - out["l"] = e - - ta = threading.Thread(target=run_l, name="cart-A") - ta.start() - deadline = time.monotonic() + 2.0 - while not tr.gate_open and time.monotonic() < deadline: - time.sleep(0.005) - assert tr.gate_open, "用例自身失效: 第一条 0x3A 没被受理 (拿不到'在跑'这个窗口)" - - tb = threading.Thread(target=lambda: out.update( - c=_safe(lambda: arm.move_c(TCP0, (0.35, 0.0, 0.32, 0.0, 0.0, 0.0), TCP0, - speed=0.3, wait=False))), name="cart-B") - tb.start() - time.sleep(0.3) # 给 B 充足的时间去"抢读" (修复后它只能排队) - tr.release.set() - ta.join(5) - tb.join(5) - - assert isinstance(out.get("l"), CartPlan), f"A 那条没跑通: {out.get('l')!r}" - assert isinstance(out.get("c"), CartPlan), f"B 那条没跑通: {out.get('c')!r}" - assert not tr.early_tcp_read, ( - "`move_c` 在**锁外**读了 TCP —— 它是在飞那条还没收尾时把 GET_TCP 写出去的, " - "那一次读会抢走在跑那条的 ACK = 受害者报 '无应答' 而命令其实已生效") - assert tr.order[:1] == ["plan"], ( - f"下行时序是 {tr.order} —— 那条在飞请求的 0x4E 必须先出; 它后面的 'tcp' 里既有 " - f"A 自己的到位回读 (`_tcp_reached`), 也有 B 那次起点校验") - - -class _BeginRendezvousTransport(FakeTransport): - """给"`move_path` 的 BEGIN/ADD 也在不在串行锁里"造窗口的桩。 - - 第一条 `0x3C` (BEGIN) **先落进 `tx_log`, 再卡住** `_OVERLAP_WINDOW` 等第二个写者 —— - 于是无锁时第二个线程能在它卡住期间把自己的 BEGIN/ADD/RUN **整段**写完 (两条请求的 - 帧在 `tx_log` 里交错); 有锁时第二个线程进不来 (它在 `Arm._cart_serial` 上排队), - 那个写者永远不来 ⇒ 每条用例白等 `_OVERLAP_WINDOW` (与 `_CrossDeliverTransport` 同款, - 是知情的代价)。 - - ⚠ "先落 log 再卡住"是**承重**的: 反过来 (卡住后再落 log) 会把第一条的整段帧推迟到 - 第二条之后, 于是**无锁时也看着是连续的** —— 那条用例就测不出加锁前后的差别。 - - ⚠ **建模缺口**: 本桩对**第二条** `0x3C` 也回 `RSP_ACK`, 而真固件会拒 - (`cart_req_begin` 只在 `IDLE` 受理, `cart_exec.c:304` ⇒ `ERR{0x3C,0x04}`)。 - 故本桩只建模"锁把并发变成排队"这一面, 不建模"真固件下第二条根本发不出 ADD"。 - """ - - def __init__(self, *a, **kw) -> None: - super().__init__(*a, **kw) - self._begin_writers = 0 - self.first_begin_logged = threading.Event() - self.second_writer_entered = threading.Event() - self._begin_lock = threading.Lock() - - def write_frame(self, cmd, payload=b""): - if cmd != P.CMD_CART_BEGIN: - return super().write_frame(cmd, payload) - with self._begin_lock: - first = self._begin_writers == 0 - self._begin_writers += 1 - with self._tx_lock: # 与 FakeTransport 同款记账 (先落 log) - self.tx_log.append((cmd, bytes(payload))) - self.tx_stamps.append(time.monotonic()) - if first: - self.first_begin_logged.set() - self.second_writer_entered.wait(_OVERLAP_WINDOW) - else: - self.second_writer_entered.set() - self._push(P.pack_frame(P.RSP_ACK, bytes([cmd]))) - - -#: `move_path` 一次调用在 `tx_log` 里留下的**笛卡尔帧序** (过滤掉其它命令后): -#: BEGIN + ADD(0) + ADD(1) + RUN —— 两条请求各一份, **两次调用不许交错**。 -_MOVE_PATH_FRAME_ORDER = [(P.CMD_CART_BEGIN, None), (P.CMD_CART_ADD, 0), - (P.CMD_CART_ADD, 1), (P.CMD_CART_RUN, None)] - - -def test_move_path_begin_and_add_are_inside_the_serial_lock(monkeypatch): - """⚠ `move_path` 的 **BEGIN + ADD×n + RUN 整段**必须在 `Arm._cart_serial` 里。 - - 只圈 RUN (经 `_request_and_wait`) 是不够的: 固件的 `RECV` 收集态**只从 `IDLE` 开** - (`cart_exec.c:304`: `state != CART_ST_IDLE` ⇒ `CART_REQ_STATE`), 两条并发 `move_path` - 里**后到的那条会在 BEGIN 就被拒** (`ERR{0x3C,0x04}`), 于是它连自己的 ADD 都发不出去 - —— 那是**响亮失败**, 不是静默串路。持锁把它**变成排队** (两条都跑完整段), 并把 - `BEGIN→RUN` 整段与其它笛卡尔入口互斥。 - - ⚠ **桩的建模缺口 —— 别按错模型去改这个用例**: 本桩 - (`_BeginRendezvousTransport`) 对**第二条** BEGIN 也回 `RSP_ACK`, 所以**不持锁时** - 第二条会照常把 ADD/RUN 写完、`tx_log` 里真的交错 (用例**红**)。真固件不会这样: 它的 - 第二条 BEGIN 会被 `0x04` 拒。⇒ 本用例绿的原因是"**锁让它们排队**", **不是**"不锁就会 - 拼出同一条路径"。 - ⚠ 本段原写"固件的 `RECV` 缓冲按**到达顺序**收路点 ⇒ 两条请求的路点会拼进**同一条** - 收集态" —— **归因错**: 缓冲按帧里的 `idx` 索引而非到达顺序 (`cart_exec.c:321`), 且 - 重复 idx 被去重 (`cart_exec.c:320`), 而同一时刻只可能存在**一条**收集会话 (上面那条 - `IDLE` 判据)。 - - 判据: `tx_log` 里过滤出 `0x3C/0x3D/0x3E` 后的帧序必须**恰好**是两份连续的路点块。 - 红时的实测帧序是 `3C, 3C, 3D(0), 3D(1), 3E, 3D(0), 3D(1), 3E` - —— 第二条的 BEGIN 插在第一条的 BEGIN 与它的 ADD 之间。 - """ - import litearm.arm as arm_mod - - def factory(port="fake", timeout=0.2, **_ignored): - return _BeginRendezvousTransport(port=port, timeout=timeout) - - monkeypatch.setattr(arm_mod, "SerialTransport", factory) - arm = Arm(port="fake").connect() - tr = arm._tr - out = {} - - def run(name, poses): - try: - out[name] = arm.move_path(poses, speed=0.3) - except BaseException as e: # noqa: BLE001 - 结局不是本条的被测对象 - out[name] = e - - pa = [(0.30, 0.0, 0.35, 0.0, 0.0, 0.0), (0.31, 0.0, 0.35, 0.0, 0.0, 0.0)] - pb = [(0.32, 0.0, 0.35, 0.0, 0.0, 0.0), (0.33, 0.0, 0.35, 0.0, 0.0, 0.0)] - ta = threading.Thread(target=run, args=("A", pa), name="cart-A", daemon=True) - ta.start() - assert tr.first_begin_logged.wait(2.0), "第一条 BEGIN 没写进来 (用例自身失效)" - tb = threading.Thread(target=run, args=("B", pb), name="cart-B", daemon=True) - tb.start() - ta.join(5) # 上限同前: 只给"判据失效"那一支用 (0.4s 的余量) - tb.join(5) - assert set(out) == {"A", "B"}, f"线程没回来: {sorted(out)}" - - got = [(c, p[0] if c == P.CMD_CART_ADD else None) - for c, p in tr.tx_log if c in (P.CMD_CART_BEGIN, P.CMD_CART_ADD, P.CMD_CART_RUN)] - assert got == _MOVE_PATH_FRAME_ORDER * 2, ( - f"两条 `move_path` 的 BEGIN/ADD 交错了下行帧: {got} —— " - f"锁没能把第二条拦在 BEGIN 之前 (真固件会在它的 BEGIN 回 0x3C/0x04, " - f"见用例 docstring 的'桩的建模缺口')") - - -# --------------------------------------------------------------------------- -# 9. 位姿入参的形态 —— 三条入口要收下 `movel/movec` 收过的**全部**写法 -# --------------------------------------------------------------------------- - -def _R_from_rpy(r: float, p: float, y: float): - """照固件 `kin_rpy_to_rot` 的定义**重写一遍** (ZYX 内旋)。 - - 刻意不用被测代码 (`rpy_to_mat`) 造输入: 拿被测函数构造期望值, 两边一起错也测不出来。 - """ - cr, sr = math.cos(r), math.sin(r) - cp, sp = math.cos(p), math.sin(p) - cy, sy = math.cos(y), math.sin(y) - return [[cy * cp, cy * sp * sr - sy * cr, cy * sp * cr + sy * sr], - [sy * cp, sy * sp * sr + cy * cr, sy * sp * cr - cy * sr], - [-sp, cp * sr, cp * cr]] - - -def test_a_pose_pair_produces_the_same_frame_as_the_six_scalars(offline_arm): - """⚠ `(pos[3], R[3x3])` 与等价的 6 标量必须产生**逐字节相同**的下行载荷。 - - 这三条入口替代的 `movel/movec` 收两种写法 ("固件的 `[x,y,z,r,p,y]` **或** - pylitearm 的 `(position[3], rotation[3x3])`"), 只收 6 标量就是**公开 API 的能力 - 倒退**。判据取"逐字节相同"而不是"都能跑": 两条路径必须殊途同归到**同一帧**。 - - ⚠ **它守的是"两条路径互相一致", 不是绝对值**: 两边**一起错** (例如 rpy 约定整体 - 反了、`mat_to_rpy` 与固件的 `kin_rot_to_rpy` 一起偏) 时它照样绿 —— 因为输入里的 - `R` 正是用同一套约定造出来的。真正钉住绝对值的是同文件里**用独立重写的 - `_R_from_rpy` 造输入、再断言载荷逐字节等于原 rpy** 的那几条 - (`test_a_homogeneous_4x4_pose_is_accepted_too` / - `test_move_c_pose_start_also_accepts_a_pose_pair`) 以及上面那两条直接断言 - 6 标量载荷的用例。别以为本条守住了绝对值。 - """ - arm = offline_arm - pos, rpy = (0.31, 0.0, 0.36), (0.2, 0.3, 0.4) - arm.move_l(list(pos) + list(rpy), speed=0.3) - from_scalars = _payloads(arm, P.CMD_MOVE_L)[-1] - arm.move_l((pos, _R_from_rpy(*rpy)), speed=0.3) - from_pair = _payloads(arm, P.CMD_MOVE_L)[-1] - assert from_scalars == from_pair, "两种写法下发的载荷不同" - - -def test_a_homogeneous_4x4_pose_is_accepted_too(offline_arm): - """4x4 齐次矩阵也收 (`as_pose` 的第三种形态)。""" - arm = offline_arm - pos, rpy = (0.31, 0.0, 0.36), (0.2, 0.3, 0.4) - R = _R_from_rpy(*rpy) - M = [R[0] + [pos[0]], R[1] + [pos[1]], R[2] + [pos[2]], [0.0, 0.0, 0.0, 1.0]] - arm.move_l(M, speed=0.3) - ps = _payloads(arm, P.CMD_MOVE_L)[-1] - assert _is_f32(P.unpack_f32s(ps, 0, 6), list(pos) + list(rpy)) - - -def test_move_c_pose_start_also_accepts_a_pose_pair(offline_arm): - """`pose_start` (要发 `get_tcp` 比对的起点) 同样收两种形态 —— 旧 `movec` 也收。 - - ⚠ 三个位姿都必须是**完整位姿** (6 标量或位姿对): `[x,y,z]` 这种 3 元素写法 - 从来就不被收 (`as_pose` 与旧的 `_as_pose6` 一致) —— `pose_via` 的**姿态被固件忽略** - 是固件侧的事, 载荷里那一格仍然存在。 - """ - arm = offline_arm - arm.move_c(((TCP0[0], TCP0[1], TCP0[2]), _R_from_rpy(0.0, 0.0, 0.0)), - ((0.30, 0.0, 0.40), _R_from_rpy(0.0, 0.0, 0.0)), - (0.32, 0.0, 0.40, 0.0, 0.0, 0.0), speed=0.3) - assert P.CMD_MOVE_C in _sent(arm), "位姿对形态的位姿被拒了" - ps = _payloads(arm, P.CMD_MOVE_C)[-1] - assert _is_f32(P.unpack_f32s(ps, 0, 6), [0.30, 0.0, 0.40, 0.0, 0.0, 0.0]) - assert _is_f32(P.unpack_f32s(ps, 24, 6), [0.32, 0.0, 0.40, 0.0, 0.0, 0.0]) - - -def test_move_path_waypoints_also_accept_a_pose_pair(offline_arm): - """`move_path` 的**每一个**路点同样收两种形态 —— 逐点 `_as_pose6`, 不是只认 6 标量。 - - 与上面两条同族 (同一形态在三条入口上各有一条用例)。⚠ 判据必须**逐点**比、且**混着传**: - `move_path` 的实现是 `pts = [_as_pose6(p, "move_path") for p in poses]` —— 一个路点一个 - 路点各转各的, 所以"第一个点收了"证明不了第二个点也收 (整段只转一次的实现照样过)。 - - ⚠ 它守的**不是**"位姿对语法转得对" (那由 `test_a_pose_pair_produces_the_same_frame_as_ - the_six_scalars` 的**逐字节**比对守): 这里只钉"`move_path` 的路点走的是同一条转换", - 防的是将来有人把这条入口改成只收 6 标量。 - """ - arm = offline_arm - pair = ((0.30, 0.0, 0.40), _R_from_rpy(0.0, 0.0, 0.0)) - arm.move_path([TCP0, pair], speed=0.3) - adds = _payloads(arm, P.CMD_CART_ADD) - assert len(adds) == 2, "路点没全发出去 (位姿对形态的路点被拒了)" - assert adds[0][0] == 0 and adds[1][0] == 1, "idx 不连续" - assert _is_f32(P.unpack_f32s(adds[0], 1, 6), TCP0) - assert _is_f32(P.unpack_f32s(adds[1], 1, 6), [0.30, 0.0, 0.40, 0.0, 0.0, 0.0]), ( - "位姿对形态的路点没有走 `_as_pose6` 那条转换") - - -@pytest.mark.parametrize("bad,shape", [ - ([0.1] * 9, "len=9"), # 扁平 9 元素旋转矩阵 (位置不可省) - ((0.1, 0.2), "len=2"), - (3.14, "float"), - ("0.3,0,0.35,0,0,0", "str"), -]) -def test_an_illegal_pose_reports_the_shape_that_was_actually_received( - offline_arm, bad, shape): - """非法形态抛 `InvalidCommandError`, 且**消息里含实际收到的形状**。 - - 只说 "pose 非法" 会让调用方在 6 向量与位姿对之间反复猜 —— 这正是 `as_pose` 那条 - 文案存在的理由, 别在外面包一层把它盖掉。 - """ - arm = offline_arm - before = list(arm._tr.tx_log) - with pytest.raises(InvalidCommandError) as ei: - arm.move_l(bad, speed=0.3) - assert shape in str(ei.value), f"报错没有给出实际形状 ({shape})" - assert arm._tr.tx_log == before, "形态非法却已经发了帧" - assert arm._cart.pending == 0 - - -@pytest.mark.parametrize("bad,reason", [ - ([0.1, 0.2, 0.3, 0.4, 0.5, "x"], "float"), # 6 标量里混了字符串 - (((0.1, 0.2, 0.3), [1, 2, 3]), "not iterable"), # 位姿对的 R 不是"行的序列" -]) -def test_malformed_pose_values_stay_inside_the_lite_arm_error_family( - offline_arm, bad, reason): - """⚠ 畸形**数值** (`ValueError`/`TypeError`) 也必须收进 `LiteArmError` 体系。 - - 这两类发生在 `as_pose` 的**数值转换**里 (`float(v)` / `list(row)`), 与上面那条 - "形态不合法" 是**同一种处境**、同一种归因 —— 而且对老版本**正是** `InvalidCommandError`: - `7e8c2f4` 的 `_as_pose6` 写着 `except (TypeError, ValueError): raise InvalidCommandError`。 - 把形态判定整个委托给 `_rot.as_pose` 之后漏了这一步 ⇒ **回归**: 调用方按 `LiteArmError` - 做分支 (重连/改参数/放弃) 的代码对这几种输入会全部失效 (帧未发出, 方向安全, - 但异常类型契约破了)。 - - 判据: 类型是 `InvalidCommandError` (**不是** `builtins.ValueError`/`TypeError`), - 文案里带上**哪条入口**, 且**原文不丢** (它含实际收到的值/形状), 帧也没发出去。 - """ - arm = offline_arm - before = list(arm._tr.tx_log) - with pytest.raises(InvalidCommandError) as ei: - arm.move_l(bad, speed=0.3) - assert "move_l" in str(ei.value), "报错没说是哪条入口的位姿" - assert reason in str(ei.value), "`as_pose` 那句原文被盖掉了" - assert arm._tr.tx_log == before, "入参畸形却已经发了帧" - assert arm._cart.pending == 0 - - -def test_cart_start_tolerances_track_move_p_defaults(): - """⚠ `move_c` 的起点容差必须**跟随** `Arm.move_p` 的默认值 (同源的, 不是巧合)。 - - `move_c` 判的就是"实际 TCP 是否在 `pose_start` 附近", 与 `move_p` 的到位判据必须是 - **同一把尺子** —— 否则 `move_p` 刚判定"到位"的位置会被 `move_c` 判成"起点不一致"。 - 这两个常量是从 `move_p` 的默认值**复制**来的, 没有任何机制保证它们跟随; 判据能失败: - 把 `Arm.move_p` 的 `pos_tol`/`rpy_tol` 默认值改一个数, 这条即红。 - """ - import inspect - - params = inspect.signature(Arm.move_p).parameters - assert CART_START_POS_TOL == params["pos_tol"].default, ( - f"move_c 的起点位置容差 {CART_START_POS_TOL} 与 move_p 的默认 " - f"{params['pos_tol'].default} 不一致 —— 两把尺子分叉了") - assert CART_START_RPY_TOL == params["rpy_tol"].default, ( - f"move_c 的起点姿态容差 {CART_START_RPY_TOL} 与 move_p 的默认 " - f"{params['rpy_tol'].default} 不一致 —— 两把尺子分叉了") diff --git a/tests/test_cart_queue.py b/tests/test_cart_queue.py deleted file mode 100644 index a46d65a..0000000 --- a/tests/test_cart_queue.py +++ /dev/null @@ -1,1480 +0,0 @@ -"""Task 3: `_CartPending` 队列 + `0x4E` 收集器 + 清队钩子。 - -**为什么**: 固件原生笛卡尔 (`0x3A/0x3B/0x3E` + `RSP_CART_PLAN 0x4E`) 的应答载荷里 -**没有命令 id**, 只能按**受理顺序** FIFO 配对。而"作废在途规划"在固件侧有两条 -**语义完全相反**的路径: - -* 走 `cart_invalidate_before_motion()` 的 opcode → **静默作废** (一条 `0x4E` 都不发) - → 主机必须**在发出前**把队清掉, 否则陈旧 token 会被下一个 `0x4E` 错配; -* `0x3A/0x3B/0x3E` → **绝不清队** (被取代的那条必有 CANCELED), 清队会让 - "报告"与"物理事实"相反。 - -**本 Task 钉死的三条**: - -1. 清队集合 = **12** 个 opcode (固件 `cart_invalidate_before_motion()` 的调用点归约), - `0x3A/0x3B/0x3E` **不在**里面; -2. 清队**只挂在最底层写口** `Arm._raw_write` 上 —— 零重力保活线程刻意绕过 - `_write_cmd` (避开零重力守卫), 但它**不该**绕过清队: 它发的 `0x06` 正是会静默 - 作废在途规划的那一类; -3. `0x4E` 一律由 `Arm._read_one` 交给收集器 (**不返回给调用方**、也不计入未识别帧); - 队列空却收到应答 = "多了一条" → **计数 + 报错**, 不静默丢弃。 - -⚠ 清队**销毁在途记账**, 于是后来那条 `0x4E` 归属不明 (载荷里没有命令 id): 它可能是 -"清队后固件根本没发" 那支 (无应答), 也可能是 "清队那一刻固件**已经跑完**、应答早躺在 -主机 RX 缓冲里" 那支。后者属于刚被清掉的那条请求 —— 按"多了一条"无条件报错会让 -`LiteArmError` 从毫不相干的读路径里炸出来, 并把一条**已经成功**的运动报成"结局未知"。 -故清队**记吸收额度**, 见本文件第 5 节 (Task 3.5)。 - -⚠ 本 Task (历史坐标) **只**做队列/收集器/清队 —— 当时把 `CartPlan`、入口方法、能力探测 -**留给后续 Task**; 三者今天**都已交付并有测试** (别把这句读成"今天还没有"): -`CartPlan.from_reply` 见 `cart.py` / 用例 `test_cart_protocol.py::test_from_reply_reads_ok_and_err_from_their_own_bytes`; -入口方法与探测在同文件 (`test_probe_*` / `test_move_l_*` / `test_move_c_*` / `test_move_path_*`) -与 `tests/test_cart_wait.py`。 -""" -from __future__ import annotations - -import pathlib -import sys -import threading -import time -import types - -import pytest - -import litearm.arm as arm_mod -import litearm.cart as cart_mod -from fake_serial import FakeTransport -from litearm import _protocol as P -from litearm.arm import _ZG_THREAD_NAME -from litearm.cart import _CART_CLEARS_UPON, _UNCLAIMED_MAX, _CartPending -from litearm.errors import (CartReplyLostError, CommandRejectedError, - LiteArmError, MotionTimeoutError, - TransportError) - -#: 固件 `cart_invalidate_before_motion()` 的调用点归约出的 opcode —— **12 个** -#: (实测 `control_loop.c` 11 处 + `kin_runner.c:176` 1 处; 其中 `0x2A` home 复用 -#: `ctrl_accept_move_j` 那一处, 故"调用点数"= "opcode 数" = 12)。 -#: -#: ⚠ 提示语里写的"13 个 opcode"与规格表 (12 行) 和固件实测都不符 —— 以表/固件为准。 -EXPECTED_CLEARS = frozenset({ - 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, # move_j/P/js/mit/mit_all/zero_g/j_sync - 0x11, 0x12, 0x13, 0x14, 0x2A, # disable/estop/clear_faults/reset/home -}) - - -def _push(arm, fid: int, payload: bytes = b"") -> None: - """往桩的响应队列里塞一帧 (`FakeTransport._push(frame)`)。""" - arm._tr._push(P.pack_frame(fid, payload)) - - -def _plan_payload(ok: int = 1, err: int = 0, n_wp: int = 12, - plan_us: int = 4700) -> bytes: - """`RSP_CART_PLAN (0x4E)` 载荷 (8B): `ok u8 + err u8 + n_wp u16 LE + plan_us u32 LE`。""" - return bytes([ok, err]) + n_wp.to_bytes(2, "little") + plan_us.to_bytes(4, "little") - - -# --------------------------------------------------------------------------- -# 1. 清队集合 —— 边界的两侧各钉一遍 -# --------------------------------------------------------------------------- - -def _settle(arm, timeout: float = 1.0) -> None: - """等读线程把**已经推入桩的**帧投递完 —— 旧 `arm._read_one(0.2)` 的等价物。 - - ⚠ 旧写法是"调用方驱动取一帧"(那时 SDK 没有读线程);现在是"**等**那一帧被读线程 - 取走并投递"。判据 = 桩的接收队列排空 + 一小段静默(投递异步,见 `_Ack._reader_loop`)。 - ⚠ 它**不做任何归属判定** —— 那正是重构要消灭的动作。 - """ - import time as _t - end = _t.monotonic() + timeout - while _t.monotonic() < end and arm._tr._resp: - _t.sleep(0.002) - _t.sleep(0.01) - - -def test_clear_set_is_exactly_the_twelve_firmware_opcodes(): - """集合**恰好**是固件那 12 个 (多一个=误伤笛卡尔应答, 少一个=泄漏 token)。 - - 逐 opcode 的固件依据: - `0x01` ctrl_accept_move_j / `0x02` kin_runner_request_move_p / - `0x03` ctrl_accept_move_js / `0x04` ctrl_accept_move_mit / - `0x05` ctrl_accept_move_mit_all / `0x06` ctrl_accept_zero_g / - `0x07` ctrl_accept_move_j_sync / `0x11` ctrl_disable / - `0x12` ctrl_emergency_stop / `0x13` ctrl_clear_faults / - `0x14` ctrl_reset / `0x2A` home (复用 ctrl_accept_move_j)。 - """ - assert _CART_CLEARS_UPON == EXPECTED_CLEARS, ( - f"清队集合与固件对不上: 多={sorted(_CART_CLEARS_UPON - EXPECTED_CLEARS)} " - f"少={sorted(EXPECTED_CLEARS - _CART_CLEARS_UPON)}") - - -def test_clear_set_never_includes_the_cart_commands(): - """⚠ 0x3A/0x3B/0x3E 绝不清队 —— 它们欠的是**两条已知应答** (A 的 CANCELED + B 的结果)。 - - 危害由 `test_the_clear_set_must_not_swallow_the_two_known_replies` 实地摆出来; - 一句话: 清队把**已知**的结局 (接管 / 成功) 报成**未知**, 并把 B 的结果丢掉。 - ⚠ 别写成"B 会收到 `MotionSupersededError`、于是不去纠正" —— 那是后果链说反 - (`MotionSupersededError` 只在**读到** `err=5` 时产生, 而这里两条应答都被吸收了)。 - """ - for cmd in (0x3A, 0x3B, 0x3E): - assert cmd not in _CART_CLEARS_UPON, f"0x{cmd:02X} 欠两条 0x4E, 清队会错配" - - -#: 手工走 `_CartPending` 那几步的用例用的**定值** TTL —— 见 -#: `test_the_clear_set_must_not_swallow_the_two_known_replies` 的 docstring: -#: 这几条验的是**配对/吸收语义**, 不是"额度能活多久", 故不许跟 `_ABSORB_TTL_FLOOR` 耦合 -#: (耦合之后把那个常量改成 0.0 会让它们红在错的地方 —— 判据一句都没验到)。 -_FIXED_TTL = 15.0 - - -def test_the_clear_set_must_not_swallow_the_two_known_replies(): - """⚠ "清队集合为什么**恰好**是那 12 个"的另一半: 把假设摆出来, 看清代价落在谁头上。 - - 不改清队集合, 只手工走一遍 `_CartPending` 上那几步 —— 顺序按真实代码: - `request()` 是**先登记、后写**, 清队钩子挂在**写口** (`_raw_write`) 上。 - - 1. A 已在飞 (PLANNING); - 2. B 登记 —— 它的 token **此刻已在队里**, 而那一次写会触发清队; - 3. 清队之后, 固件那两条应答才到: A 的 CANCELED (取代它的正是 B) 与 B 自己的结果。 - - 判据 (每一条都是"报告与物理事实相反"的一种): - ① 清队摘掉的是 **2** 条 (A 与 B 自己的) ⇒ 两位调用方**都**被判"结局未知", - 而真相是"A 被**预期内**地接管 + B 马上就要跑"; - ② 那两条应答**全数被吸收** (`absorbed_replies == 2`) —— B 那条本该交付的规划结果 - 被**丢掉**, 谁也没拿到; - ③ 谁也没读到 `err=5` (所以**不**是 `MotionSupersededError`) —— "接管"与"结局未知" - 在报告上分不开, 而前者按约定是**不该纠正**的。 - - ⚠ **TTL 刻意用一个与常量解耦的定值** (`_FIXED_TTL`), 不用 `_ABSORB_TTL_FLOOR`: - 后者被改成 `0.0` 时, 这里现构造的 `_CartPending` 的额度当场过期 ⇒ `on_reply` 走 - "队列空 + 无额度"那条路抛 `LiteArmError`, 用例红在 `on_reply` **内部**, - 上面三条判据**一个字都没验到** (归因错)。"下限本身够不够"由 - `test_the_absorb_ttl_floor_is_the_firmware_planning_bound_plus_margin` 单独守。 - """ - q = _CartPending(absorb_ttl=_FIXED_TTL) - a = q.register() # A 已在飞 (PLANNING) - b = q.register() # B: 登记**先于**写 (见 `_CartPending.request`) - assert q.clear_pending("假设 0x3A 在清队集合里") == 2, ( - "清队只摘掉了在飞那条 —— 而 `request()` 是先登记后写, B 那条此时已经在队里了") - - assert "结局未知" in (a.lost or "") and "结局未知" in (b.lost or ""), ( - "清队没把两条都判成结局未知 —— 与上面那句 `== 2` 不符") - q.on_reply(_plan_payload(ok=0, err=5)) # 固件为 A 发的 CANCELED - q.on_reply(_plan_payload(ok=1, err=0, n_wp=12)) # B 自己的结果 - assert (q.absorbed_replies, q.extra_replies) == (2, 0), ( - "两条已知应答应当**双双被吸收** (2 格额度正对 2 条应答): 既没被交付, " - "也没被当成脱同步报出来") - assert a.reply is None and b.reply is None, ( - "有谁拿到了应答 —— 与'两条都被吸收'不符 (如果 B 拿到了, 那才是假成功)") - - -def test_clear_set_excludes_the_other_cartesian_and_readonly_opcodes(): - """另外几个**看着像**却不清队的: BEGIN/ADD 与 GET_IK。 - - * `0x3C` BEGIN / `0x3D` ADD: 受理态不同 (`IDLE` 与 `RECV`), 但**都不涉及** - 丢弃在途规划 —— 不满足受理条件一律回 `0x04`。 - * `0x42` GET_IK: 固件走 `kin_runner_request_ik`, 与唯一带 `cart_invalidate` 的 - `kin_runner_request_move_p` 是**两个函数** (纯读, 不会间接走到 ctrl_accept_move_j)。 - * `0x40` GET_STATUS / `0x43` GET_TCP / `0x2B`~`0x2E` 读回: 纯查询。 - """ - for cmd in (0x3C, 0x3D, 0x42, 0x40, 0x43, 0x2B, 0x2C, 0x2D, 0x2E): - assert cmd not in _CART_CLEARS_UPON, f"0x{cmd:02X} 不作废在途规划, 不该清队" - - -def test_clear_set_includes_home_and_stop_commands(): - """0x2A home 经 ctrl_accept_move_j 静默丢弃; 0x06/0x11/0x12/0x13/0x14 同理。""" - assert P.CMD_HOME == 0x2A # 钉住码值, 防语义漂移 - assert 0x2A in _CART_CLEARS_UPON, "0x2A home 最易漏 —— 它复用 ctrl_accept_move_j" - for cmd in (P.CMD_ZERO_G, P.CMD_DISABLE, P.CMD_EMERGENCY_STOP, - P.CMD_CLEAR_FAULTS, P.CMD_RESET): - assert cmd in _CART_CLEARS_UPON, f"0x{cmd:02X} 会静默作废在途规划" - - -# --------------------------------------------------------------------------- -# 2. 清队挂在**最底层写口**上 —— 三处 `write_frame` 逐处验 -# --------------------------------------------------------------------------- - -def test_write_frame_has_single_call_site(): - """结构断言: `arm.py` 里只剩 `_raw_write` 一处 `write_frame`。 - - 没有这条, "三处改走 `_raw_write`"只能靠人肉数 —— 漏掉保活线程那一处时 - (它是唯一绕过 `_write_cmd` 的写者) 离线用例全绿, 真机上它每 40ms 静默作废 - 一次在途规划而 SDK 毫无察觉。 - """ - import litearm.arm as arm_mod - - src = pathlib.Path(arm_mod.__file__).read_text(encoding="utf-8") - - assert src.count(".write_frame(") == 1, ( - "还有直接写 `_tr.write_frame` 的地方 —— 清队钩子拦不到它") - - -def test_connect_handshake_goes_through_raw_write(monkeypatch, fake_transport_factory): - """写口 ①: `connect()` 握手 (`CMD_GET_FIRMWARE`)。""" - import litearm.arm as arm_mod - - seen = [] - orig = arm_mod.Arm._raw_write - - def spy(self, cmd, payload=b""): - seen.append(cmd) - return orig(self, cmd, payload) - - monkeypatch.setattr(arm_mod.Arm, "_raw_write", spy) - fake_transport_factory() - - arm_mod.Arm(port="fake").connect() - - assert P.CMD_GET_FIRMWARE in seen, "握手没走 _raw_write" - - -def test_write_query_goes_through_raw_write(monkeypatch, offline_arm): - """写口 ②: `_write_query` —— **所有**命令的出口。""" - arm = offline_arm - seen = [] - orig = type(arm)._raw_write - - def spy(self, cmd, payload=b""): - seen.append(cmd) - return orig(self, cmd, payload) - - monkeypatch.setattr(type(arm), "_raw_write", spy) - arm._write_query(P.CMD_CLEAR_FAULTS) - - assert seen == [P.CMD_CLEAR_FAULTS] - - -def test_keepalive_thread_also_clears(offline_arm, monkeypatch): - """写口 ③: **零重力保活线程** —— 保活线程走 `_raw_write`, 所以它的 0x06 也会清队。 - - 这一条必须单独钉: 保活线程**刻意**绕过 `_write_cmd` (避开零重力守卫), 清队钩子 - 若挂在 `_write_cmd`/`_write_query` 上就拦不到它 —— 而 `0x06` 恰恰是清队集合成员。 - - 判据用"**清队发生在哪个线程**"来钉 (线程名), 不用时序推断: 时序推断在 - "注册后马上断言队列非空"那一步就有竞态 (线程可能恰好抢先清掉)。 - """ - arm = offline_arm - threads = [] - orig_clear = _CartPending.clear_pending - - def spy(self, reason=""): - threads.append(threading.current_thread().name) - return orig_clear(self, reason) - - monkeypatch.setattr(_CartPending, "clear_pending", spy) - - arm.zero_g_start(period=0.01) - try: - threads.clear() # 丢掉 zero_g_start 自己在主线程发的那条 - arm._cart.register() - assert arm._cart.pending == 1 - - deadline = time.monotonic() + 2.0 - while not threads and time.monotonic() < deadline: - time.sleep(0.005) - - assert threads, "保活线程一拍都没发 —— 用例没测到要测的东西" - assert threads[0] == _ZG_THREAD_NAME, ( - f"清队发生在 '{threads[0]}' 线程 —— 保活线程的 0x06 绕过了清队") - assert arm._cart.pending == 0, "保活线程写的 0x06 没清队" - finally: - arm.zero_g_stop() - - -def test_clearing_happens_before_the_write(offline_arm, monkeypatch): - """**发出前清, 不看应答** —— 写这一瞬间队列必须已经空了。 - - 固件的 `cart_invalidate_before_motion()` 是 `ctrl_accept_move_j` 的**第一条语句**, - 位于**全部门禁之前**: 被 `ERR 0x03/0x04/0x06` 拒掉的命令**同样已经**作废了在途 - 规划。写成"收到 ACK 才清队"就会在这条被拒路径上留下陈旧 token。 - """ - arm = offline_arm - at_write = [] - tr = arm._tr - orig = tr.write_frame - - def spy(cmd, payload=b""): - at_write.append(arm._cart.pending) - return orig(cmd, payload) - - monkeypatch.setattr(tr, "write_frame", spy) - arm._cart.register() - - arm._raw_write(P.CMD_EMERGENCY_STOP, b"") - - assert at_write == [0], "清队必须发生在发出**之前**" - - -def test_rejected_command_still_clears(offline_arm): - """被固件 ERR 拒掉的清队命令**照样**已经作废在途规划 —— 判据不是应答。""" - arm = offline_arm - arm._tr.err_override[P.CMD_CLEAR_FAULTS] = 0x04 - tok = arm._cart.register() - - with pytest.raises(CommandRejectedError): - arm._cmd(P.CMD_CLEAR_FAULTS, b"", "clear_faults") - - assert arm._cart.pending == 0 - assert tok.lost is not None, "token 必须被标成『结局未知』, 不能被静默留着" - - -def test_non_clearing_command_leaves_the_queue_alone(offline_arm): - """不在表里的命令**一条都不许清** —— 否则正常的查询也会作废在途规划。""" - arm = offline_arm - tok = arm._cart.register() - - arm._raw_write(0x3A, b"\x00" * 7) # move_l: 固件侧欠一条 0x4E - arm._raw_write(P.CMD_GET_STATUS) - - assert arm._cart.pending == 1 - assert tok.lost is None - - -# --------------------------------------------------------------------------- -# 3. 队列 + 收集器 (登记 / FIFO 配对 / 两条守卫) -# --------------------------------------------------------------------------- - -def test_request_registers_before_the_write(offline_arm, monkeypatch): - """登记与写在**同一个 try 内**, 且登记在前 —— 否则应答会落在空队列上。""" - arm = offline_arm - at_write = [] - tr = arm._tr - orig = tr.write_frame - - def spy(cmd, payload=b""): - at_write.append(arm._cart.pending) - return orig(cmd, payload) - - monkeypatch.setattr(tr, "write_frame", spy) - - tok = arm._cart.request(lambda: arm._raw_write(0x3A, b"\x00" * 7)) - - assert at_write == [1], "写的时候 token 必须已经在队里" - assert arm._cart.pending == 1 - assert tok.lost is None - - -def test_write_failure_drops_its_own_token(offline_arm, monkeypatch): - """写失败 (**仅** `TransportError`) **立即摘除自己那个 token** 并原样抛出。 - - ⚠ 口径**只在 `TransportError` 上**: 其余异常证明不了帧没送达, 摘了就是假成功 —— - 见 `test_interrupt_after_the_frame_is_written_leaves_its_token_in_the_queue`。 - - ⚠ 这一步的正当性来自**载重不变量"抛 ⟹ 整帧未送达"**(见 - `test_flush_failure_is_not_reported_as_a_write_failure` 与 - `_CartPending.request` 的 docstring): 固件从没收到这条请求 ⟹ 永远不欠它应答 ⟹ - 摘掉它才恰好让在途条数与应答条数相等。 - **不是**"滞留比报错更危险" —— 正相反: 滞留只会让末尾那条活 token 报"结局未知", - 而**丢弃一条其实已送达的** token 才会把固件的应答错配给下一条 = 假成功。 - """ - arm = offline_arm - - def boom(cmd, payload=b""): - raise TransportError("桩: 写失败") - - monkeypatch.setattr(arm._tr, "write_frame", boom) - - with pytest.raises(TransportError): - arm._cart.request(lambda: arm._raw_write(0x3A, b"\x00" * 7)) - - assert arm._cart.pending == 0 - - -def _stub_serial(monkeypatch): - """注入只服务 `write_frame` 的桩串口; 返回 `holder["ser"]` = 建出来的那一个。""" - holder = {} - - class _WStubSerial: - """`write` / `flush` 各自可注入异常 —— 这两半的**失败语义完全不同**。""" - - def __init__(self, port, baudrate=0, timeout=0.2, **kw): - self.is_open = True - self.written = bytearray() - self.write_exc = None - self.flush_exc = None - holder["ser"] = self - - def write(self, d): - if self.write_exc is not None: - raise self.write_exc - self.written += d - return len(d) - - def flush(self): - if self.flush_exc is not None: - raise self.flush_exc - - def close(self): - self.is_open = False - - monkeypatch.setitem(sys.modules, "serial", types.SimpleNamespace(Serial=_WStubSerial)) - return holder - - -def test_flush_failure_is_not_reported_as_a_write_failure(monkeypatch): - """⚠ 配对器的**载重不变量**: "抛 `TransportError` ⟹ 整帧未送达"。 - - `_CartPending.request()` 靠"写失败 (**仅** `TransportError`) 就摘掉自己那个 token" - 成立, 而这条**只在 "抛错 ⟹ 帧没出去" 成立时才对**: 帧其实送到了却把 token 摘掉, - 固件那条 `0x4E` 就会配给队列里**后面那条活 token** —— 报的是"成功"而实际没跑, - 即**假成功** (本项目最忌讳的方向)。 - - 两半的物理事实不同, 故**必须拆开**: - - * `write()` 抛 → 帧没送达 (残缺帧被固件按 CRC 丢) ⇒ 照旧 `TransportError`; - * `flush()` (tcdrain) 抛 → **整帧已经在驱动里, 会被送达**, 失败也收不回来 - ⇒ **不报成发送失败**, 只把这次失败记进可观测计数 `flush_failures` - (静默是另一条底线)。真链路故障会在**下一次写**上暴露。 - """ - holder = _stub_serial(monkeypatch) - from litearm.transport import SerialTransport - - tr = SerialTransport("/dev/null") - ser = holder["ser"] - - ser.flush_exc = OSError("桩: tcdrain 失败 (帧已在驱动缓冲里)") - tr.write_frame(0x3A, b"\x00" * 7) # ← 不许抛 - - assert tr.flush_failures == 1, "flush 失败必须留下可观测计数, 不能静默" - assert P.unpack_frame(bytes(ser.written)) == (0x3A, b"\x00" * 7), ( - "这一半的前提是'整帧已交给驱动' —— 帧没出去的话另一支才成立") - - ser.write_exc = OSError("桩: 写失败") - with pytest.raises(TransportError): - tr.write_frame(0x3A, b"\x00" * 7) # ← 这半不能退化 - assert tr.flush_failures == 1, "write 失败不该计进 flush_failures" - - #: ⚠ 收尾**必须显式 close()**, 不能指望"函数返回就释放了": 上面那条 `pytest.raises` - #: 造出 `帧 -> traceback -> 帧` 的环, 把 `tr` 钉到一次全量 gc 之后 (与 `test_transport.py` - #: "端点独占"一节的注释同源)。而 `tr` 到此**从没关过** ⇒ 端口 `/dev/null` 会**按 gc 时机** - #: 继续被登记表认作占用 —— 本文件下一条用例正好也用 `/dev/null`, 于是"红不红"成了看时机的事。 - #: `close()` 落在那句 `_release_port` 上, 释放与 gc 何时跑无关 (判据见 `transport._claim_port`)。 - tr.close() - - -def test_interrupt_after_the_frame_is_written_leaves_its_token_in_the_queue(monkeypatch): - """⚠ **摘 token 只能发生在 `TransportError` 上** —— 其余异常**证明不了**帧没送达。 - - 最现实的那一支 (本用例复现的): `KeyboardInterrupt` 落在 `flush()` 里 —— 那一刻 - `write()` **已经返回**, 整帧**已交进驱动、会被送达** (与"`write()` 抛"那支的物理 - 事实**相反**, 见上面两条用例)。固件于是真会受理并回一条 `0x4E`; 此时若按"没送达" - 把自己那个 token 摘掉, 那条应答就配给队列里**后面那条活 token** ⇒ 报"成功"而实际 - 没跑 = **假成功** (本项目最忌讳的方向)。 - - 故除 `TransportError` 外一律 re-raise 且**不动队列**。代价是可能滞留一条其实没送达 - 的 token, 而那只会让队列**末尾**那条活 token 报"结局未知" (`CartReplyLostError`) - —— **安全方向**, 这才是两个方向里该选的那一个。 - """ - holder = _stub_serial(monkeypatch) - from litearm.transport import SerialTransport - - tr = SerialTransport("/dev/null") - ser = holder["ser"] - ser.flush_exc = KeyboardInterrupt() # ← 落在 write() 返回之后 - q = _CartPending(absorb_ttl=1.0) - - with pytest.raises(KeyboardInterrupt): # ← 异常照常传播 - q.request(lambda: tr.write_frame(0x3A, b"\x00" * 7)) - - assert P.unpack_frame(bytes(ser.written)) == (0x3A, b"\x00" * 7), ( - "这一支的前提正是'整帧已交给驱动' —— 帧没出去的话摘 token 才成立") - assert q.pending == 1, ( - "其余异常下**不许动队列**: 摘掉它会让固件随后的 0x4E 配给后面的活 token = 假成功") - - #: 同 `test_flush_failure_is_not_reported_as_a_write_failure` 的收尾: 本用例也用 - #: `/dev/null`, 开着就走会把端口名留给下一条同端口的用例 (释放时机取决于 gc)。 - tr.close() - - -def test_drop_removes_its_own_token_not_the_tail(offline_arm): - """摘除必须按**对象身份**, 不能 pop 末位 —— 并发下末位是别人的 token。 - - 行为证明: 三条 token 里摘掉中间那条, 两条应答必须归 a 与 c (b 一条都不吃)。 - """ - arm = offline_arm - a = arm._cart.register() - b = arm._cart.register() - c = arm._cart.register() - - arm._cart.drop(b) - _push(arm, 0x4E, b"first") - _push(arm, 0x4E, b"second") - - _settle(arm) - _settle(arm) - - assert a.reply == b"first" - assert c.reply == b"second" - assert b.reply is None, "被摘掉的 token 不该吃到任何一条应答" - assert arm._cart.pending == 0 - assert arm._cart.extra_replies == 0 - - -def test_0x4e_reply_is_claimed_by_the_collector(offline_arm): - """`0x4E` 由读线程交给收集器: **不返回给调用方**、也不进队列(更不会被计成丢弃)。""" - arm = offline_arm - tok = arm._cart.register() - _push(arm, 0x4E, b"\x01\x00\x00\x00") - - _settle(arm) - assert tok.reply == b"\x01\x00\x00\x00" - assert arm._cart.pending == 0 - assert arm._a.dropped == 0, "收集器认领的帧不该被计成丢弃" - - -def test_wait_returns_the_reply(offline_arm): - """配对成功: `wait()` 交回原始载荷, 队列复原。""" - arm = offline_arm - tok = arm._cart.register() - _push(arm, 0x4E, b"ok") - - _settle(arm) - - assert arm._cart.wait(tok, 0.05) == b"ok" - assert arm._cart.pending == 0 - - -def test_wait_can_drive_the_reads_itself(offline_arm): - """`pump` 给出时由 `wait()` 自己驱动取帧 (本包**没有读线程**, 决策 12)。""" - arm = offline_arm - tok = arm._cart.request(lambda: arm._raw_write(0x3A, b"\x00" * 7)) - _push(arm, 0x4E, b"driven") - - assert arm._cart.wait(tok, 0.5) == b"driven" - - -def test_a_result_delivered_by_wait_is_not_delivered_again_by_poll_cart(offline_arm): - """`wait` 成功交付之后, 那条结果**不许**再被 `poll_cart` 认领一次。 - - 两条路都指向同一句 "结果已被取走": `wait` 结尾的 `self._unclaim(token)` 与 - `poll_cart` 的 `claim_resolved`。少了前者, 同一条结果被交付两次 —— 调用方会把它 - 当成**两条不同的规划** (而它其实只有一条)。 - - 判据能失败: 删掉 `wait` 末尾那句 `self._unclaim(token)`, 下面 `poll_cart` 会返回 - 一个 `CartPlan` (而不是 `None`)。 - """ - arm = offline_arm - tok = arm._cart.register() - arm._tr._resp.clear() # 让 pump 一定拿到下面这条 0x4E - arm._tr.push_frame(P.RSP_CART_PLAN, _plan_payload()) - - assert arm._cart.wait(tok, 0.5) == _plan_payload() - assert arm._cart.pending == 0 - assert arm.poll_cart() is None, ( - "同一条结果先被 wait 交付、又被 poll_cart 认领了一次 (重复交付)") - - -def test_the_unclaimed_column_is_filled_before_the_waiter_is_woken(offline_arm, - monkeypatch): - """⚠ 钉住 `on_reply` 里"**先 append 再 resolve**"这个顺序 (反序必须变红)。 - - 反序不是风格问题: `resolve()` 一置位, 另一个线程里正 `wait` 的等待者就会醒来, 而它 - 醒来后做的第一件事就是 `_unclaim` —— 反序时那次摘除**扑空**, 随后 append 才发生, - 于是同一条结果永久留在那一列, `poll_cart` 会**重复交付**它 (`wait` 的 `_unclaim` 是 - 在 `resolve` **之后**跑的, 补不了这个洞)。 - - 判据 (确定性, 不靠抢跑): 把"等待者醒来后做的第一件事" (`_unclaim`) 与"那一刻 token - 在不在列里"一起挂在 `resolve` 上 —— 这正是坏交错里等待者所处的位置与时机。 - 先 append 的实现: 交付那一刻它在列里, 摘得掉 (列空) ⇒ 两条断言都绿; - 反序的实现: 摘除扑空、随后 append 把它留下 ⇒ **第一条断言即红**。 - """ - arm = offline_arm - tok = arm._cart.register() - seen = [] - real_resolve = cart_mod._CartToken.resolve - - def resolve_and_let_the_waiter_wake(self, payload): - if self is tok: - # 置位**之前**: 等待者被唤醒后要摘的正是这一列 - seen.append(any(t is tok for t in arm._cart._unclaimed)) - real_resolve(self, payload) - if self is tok: - arm._cart._unclaim(self) # 等待者醒来后的第一件事 (= 那边 `wait` 做的) - - monkeypatch.setattr(cart_mod._CartToken, "resolve", - resolve_and_let_the_waiter_wake) - _push(arm, 0x4E, _plan_payload()) - _settle(arm) - - assert seen == [True], ( - "resolve 置位的那一刻 token **还不在** `_unclaimed` 里 —— 等待者醒来后那次摘除会" - "扑空, 随后 append 把它留成一条永远不会被取走的结果 (poll_cart 会重复交付)") - assert arm.poll_cart() is None, ( - "结果已被等待者取走, poll_cart 却又认领到一次 (同上, 顺序反了)") - assert arm._cart.wait(tok, 0.05) == _plan_payload() # wait 自身仍能交付 - - -def test_claim_resolved_ignores_a_token_that_has_not_settled_yet(): - """⚠ `claim_resolved` 的判据必须含 `_done.is_set()`, 不能只看"那一列非空"。 - - `on_reply` 是**先登记进那一列、后 `resolve`** (顺序承重, 见 - `test_the_unclaimed_column_is_filled_before_the_waiter_is_woken`), 两条语句之间有一条 - 缝 —— 并发读者恰好落进去, 拿到的是一个**还没收尾**的 token, 于是 - `CartPlan.from_reply(None)` 当场 `TypeError` (单线程不可达, 故此前没暴露)。 - 缝里返回 `None` 才是对的语义 ("此刻没有可取的结果"), `poll_cart` 本来就以 `None` - 表示它。 - - 判据: 手工造出"已登记、未收尾"那一态 (就是缝里的观测面), 断言认领不到; `resolve` - 之后才认得动。 - """ - cp = _CartPending(absorb_ttl=15.0) - tok = cp.register() - with cp._lock: - cp._unclaimed.append(tok) # 缝: `on_reply` 已登记, 尚未 resolve - - assert cp.claim_resolved() is None, ( - "认领到了一个还没 resolve 的 token —— `CartPlan.from_reply(None)` 会 TypeError") - - tok.resolve(_plan_payload()) - assert cp.claim_resolved() is tok, "收尾之后反而认领不到了" - - -def test_drop_removes_the_token_from_both_columns(): - """`drop` 要摘**两列** (`_q` 与 `_unclaimed`) —— 见它的 docstring: - "一条被判死的请求不该还能被 `poll_cart` 认领出结果"。 - - ⚠ 既有用例**一次都没走到 `_unclaimed` 那一半**: 唯一的调用点 - (`_request_and_wait` 的 ACK 超时支) 一定发生在应答到达**之前**, 那时 token 只在 `_q` - 里。把 `_unclaim_locked` 里 `self._unclaimed.remove(token)` 换成 `pass` 全量套件照绿。 - 这里直接把"应答已到、还没人认领"那一态造出来再摘。 - """ - cp = _CartPending(absorb_ttl=_FIXED_TTL) - tok = cp.register() - cp.on_reply(_plan_payload()) # 应答到了 ⇒ token 进 `_unclaimed` 并 resolve - - assert tok in cp._unclaimed, "用例自身失效: token 没进 `_unclaimed`" - cp.drop(tok) - - assert tok not in cp._unclaimed, ( - "`drop` 只摘了 `_q` 那一列 —— 被判死的请求还能被 `poll_cart` 认领出结果 (重复交付)") - assert cp.claim_resolved() is None, "被判死的 token 仍被 `claim_resolved` 交付了" - - -def test_token_timeout_raises_reply_lost_and_drops_token(offline_arm): - """**少了一条** —— 超时 (用 `Arm.move_timeout`, 不新造字段) → 摘除 token 并抛 - `CartReplyLostError`。缺了这条, 后续的 `0x4E` 会被错配给一条早已被吞掉的请求 - (固件单槽 pending: 同一 main 排空窗口内登记 ≥3 条时中段应答会被吞掉, N≥3 只存活 2 条)。""" - arm = offline_arm - tok = arm._cart.register() - - with pytest.raises(CartReplyLostError) as ei: - arm._cart.wait(tok, 0.05) - - assert arm._cart.pending == 0, "超时的 token 必须摘除, 否则下一个 0x4E 会错配" - assert "超时" in str(ei.value) - - -def test_queue_empty_reply_is_counted_and_raises(offline_arm): - """**多了一条** —— 队列空却收到 `0x4E`: 计数 + 报错, **不静默丢弃**。 - - 内部一致性错误 (应答比请求多 ⟹ 固件与主机已经错位), 故**不是** - `CartReplyLostError` (那是"少了一条"的未知结局)。 - - ⚠ 判据: "**少一条**"是调用方面对的**处境** (结局未知, 要能与失败/接管区分) - ⇒ 独立类型、可被 `except`; "**多一条**"是 SDK 配对模型与固件**脱同步**的 - 内部不变量破坏 ⇒ 抛基类 `LiteArmError`, **不该**被专门 catch。本条钉住这一点 - (断言不是 `CartReplyLostError`) —— 别顺手给它补一个专用子类。 - """ - arm = offline_arm - _push(arm, 0x4E, b"\x01\x00\x00\x00") - _settle(arm) # 读线程先把它交给收集器 (收集器在这一刻抛) - - # ⚠ 读线程**不当场抛、也不死**(`_Ack._reader_loop`):它把异常存进 `_errors`, - # 由**下一个等待者**抛出。所以这里要真的等一次(用驱动型读者,它现在也看 `_errors`)。 - with pytest.raises(LiteArmError) as ei: - arm.get_status_now(timeout=0.5) - - assert not isinstance(ei.value, CartReplyLostError) - assert "0x4E" in str(ei.value) - assert arm._cart.extra_replies == 1 - - -def test_clear_pending_fails_tokens_as_unknown_outcome(offline_arm): - """清队 = 那几条请求**永远等不到应答**了, 必须标成"未知结局"并唤醒等待者 —— - 否则调用方会白等到超时, 而臂可能已经朝着旧目标动了。""" - arm = offline_arm - tok = arm._cart.register() - - assert arm._cart.clear_pending("测试清队") == 1 - assert arm._cart.pending == 0 - assert tok.lost is not None - - with pytest.raises(CartReplyLostError) as ei: - arm._cart.wait(tok, 0.05) - - assert "测试清队" in str(ei.value) - - -def test_clear_pending_on_empty_queue_is_a_noop(offline_arm): - """空队清队不该报错也不该计数 (保活线程每 40ms 清一次, 大多数时候队是空的)。""" - arm = offline_arm - - assert arm._cart.clear_pending() == 0 - assert arm._cart.extra_replies == 0 - - -def test_extra_replies_counter_is_independent_from_the_dropped_counter(offline_arm): - """两个计数**各记各的**: `0x4E` 由收集器认领 (不计丢弃), 没人认领的 id 只进队列。 - - ⚠ 重构后 `unexpected_frames` / `foreign_frames` 合并成 `_Ack.dropped`(只在**队列封顶** - 时递增);一条没人认领的未知帧**进队列等着**,并不立刻计丢弃 —— 那是设计("不丢")。 - """ - arm = offline_arm - _push(arm, 0x7F) # 没人认领的上行 id - - arm.get_status_now(timeout=0.5) - - assert arm._a._queues.get((0x7F, None)), "未知 id 应当进队列等着, 而不是被丢掉" - assert arm._a.dropped == 0 - assert arm._cart.extra_replies == 0 - - -# --------------------------------------------------------------------------- -# 4. 生命周期 —— 重连 = 新会话 = 新配对状态 -# --------------------------------------------------------------------------- - -def test_reconnect_drops_stale_tokens(offline_arm): - """`close()` → `connect()` 后**陈旧 token 必须消失** —— 否则 off-by-one 传递。 - - 配对状态与链路同寿: 陈旧 token 留着, 下一条**合法** `0x4E` 会配给那条早就没人 - 认领的死 token, 于是活 token 一条应答都收不到、一路走到超时 - —— 这正是 FIFO 配对存在的意义被反噬的形态。 - - ⚠ 判据必须能真的失败: 只断言"队列空"的话, 实现若改成"重连时把旧 token 一个个 - `drop` 掉"也会绿, 而那并不能证明陈旧者不再吃应答。故这里**同时**断言"陈旧 token - 一条都吃不到"。 - - ⚠⚠ **重连时会继承一格吸收额度** (见 - `test_reconnect_inherits_the_in_flight_count_as_absorb_credit`), 于是**第一条**到 - 的 `0x4E` 是"旧会话那条"还是"新 token 自己那条"**在原理上无法区分** (载荷里没有 - 命令 id) —— 本用例把两只都摆出来: 第一条被**吸收**, 第二条 (新会话自己那条) 才 - 配上 `fresh`。取舍是知情的: 反过来 (不继承额度) 会让旧会话那条迟到应答配给 - **新** token = **假成功**, 而本模块的方向一贯是"宁可报结局未知"。 - """ - arm = offline_arm - stale = arm._cart.register() - - arm.close() - arm.connect() # 新会话 - - assert arm._cart.pending == 0, "重连后陈旧 token 还留在队里" - - fresh = arm._cart.register() - _push(arm, 0x4E, b"stale") # 旧会话那条迟到应答 - - _settle(arm) - assert arm._cart.absorbed_replies == 1, ( - "旧会话那条迟到应答既没被吸收、也没配对 —— 它去哪了?") - assert fresh.reply is None and stale.reply is None, ( - "陈旧 token 吃到了应答 (off-by-one 错配)") - - _push(arm, 0x4E, b"fresh") # 新会话**自己**那条 - _settle(arm) - assert fresh.reply == b"fresh", "新 token 没配到它自己那条应答" - assert stale.reply is None, "陈旧 token 吃到了新会话的应答 (off-by-one 错配)" - assert arm._cart.extra_replies == 0 - - -# --------------------------------------------------------------------------- -# 5. 清队吸收额度 (Task 3.5) —— 清队销毁了归属信息, 只能按"判错得安全"那一支收场 -# --------------------------------------------------------------------------- - -class _FakeClock: - """确定性时间源 —— 由用例 `monkeypatch.setattr(cart_mod, "time", clock)` 装上去。 - - `cart.py` 只从 `time` 用 `monotonic()` 一个方法, 所以这个假对象就够。 - ⚠ **不用真实 `sleep` 卡过期边界**: 那种断言在负载下必假 (边界附近的 flaky - 用例比没有更坏), 而把 `time.monotonic` 打补丁会连带影响 `threading`。 - """ - - def __init__(self, t: float = 1000.0) -> None: - self.t = t - - def monotonic(self) -> float: - return self.t - - -def test_late_reply_for_a_cleared_request_is_absorbed_not_raised(offline_arm): - """清队后迟到的那条 `0x4E` (固件**已经跑完**、应答早躺在 RX 缓冲里): 进 - `absorbed_replies`, **不报错**, `extra_replies` 仍为 0。 - - 按"多了一条"无条件报错的话, `LiteArmError` 会从毫不相干的读路径里炸出来, 并把一条 - **已经成功**的运动报成"结局未知" —— 触发条件只是"清队 opcode 紧跟在笛卡尔命令之后、 - 中间没有读帧", 而 abort / 急停 / 收尾路径天生就是这个形状。 - """ - arm = offline_arm - tok = arm._cart.register() - arm._cart.clear_pending("测试清队") - - assert tok.lost is not None - assert arm._cart.absorbed_replies == 0 - - _push(arm, 0x4E, b"\x01\x00\x00\x00") # 迟到的、不可归属的那条应答 - - _settle(arm) # "不返回给调用方" 现在是**结构事实**: 没有调用方取帧这一说了 - assert arm._cart.absorbed_replies == 1 - assert arm._cart.extra_replies == 0, ( - "清队后的不可归属应答被算成了真·脱同步 —— 正常收尾被炸成硬异常") - assert arm._cart.pending == 0 - - -def test_an_absorb_during_the_wait_window_suppresses_the_fresh_credit(): - """⚠ `drop_and_absorb` 的**例外**: 本条请求的窗口里吸收过一条 ⇒ **不补**额度。 - - 理据 (见那个函数的 docstring): 吸收**先于**配对 ⇒ 一条在途 token 的应答到了、而额度 - 还有存量时, 被吃掉的就是**它自己那条** —— 固件不再欠它什么。此时若照旧补一格, 补出来 - 的那格会去吃**下一条**命令的应答, 那条又超时、又补一格 … **自持** - (入口: `connect()` 继承来的那一格; 端到端用例见 - `test_an_inherited_credit_cannot_perpetuate_itself_across_a_reconnect`)。 - - 判据分两半, **缺一不可** (只验前半会让"干脆永远不补"也绿 —— 那会退化 E3 的守卫): - · 窗口里吸收过 ⇒ `_absorb` 仍是 0; - · 没吸收过 ⇒ 照旧 1 (既有行为**不变**)。 - - ⚠ 两条 `drop_and_absorb` 都传 `timed_out=True` (= **超时支**) —— 例外**只**对这一支 - 生效; pump (读链路炸) 支走例外会翻成**假成功**, 由 - `test_a_pump_failure_must_not_suppress_the_credit` 单独钉住。 - """ - cp = _CartPending(absorb_ttl=15.0) - - absorbed = cp.register() - assert cp.clear_pending("清队") == 1 # 时长队: 那份额度是**挣来的**(与继承同形) - cp.on_reply(b"late") # 窗口里被消费掉 ⇒ "已经交出来了" - assert cp.absorbed_replies == 1 - cp.drop_and_absorb(absorbed, timed_out=True) - assert cp._absorb == 0, ( - "窗口里已经吸收过还补一格 —— 它就是自持入口: 下一条命令的应答会被这格吞掉") - - plain = cp.register() - cp.drop_and_absorb(plain, timed_out=True) - assert cp._absorb == 1, ( - "没吸收过也不补额度 —— 固件真欠的那条应答会撞空队列, E3 守卫退化") - - -def test_a_dead_reader_must_not_suppress_the_credit(offline_arm): - """⚠⚠ **"读线程死"那一支照旧补额度** —— 例外只许挂在**超时**那一支上。 - - (`pump` 参数已随读路径重构删除;旧"pump 支"= 调用方驱动取帧时炸,它的等价物是 - **读线程退出** `_Ack._reader_error` —— 两者都是"链路没了、这条请求没人再来收"。) - - `drop_and_absorb` 有**两条**调用点 (都在 `wait()` 里): 链路没那条与超时那条。 - 例外段那个判据 ("窗口里吸收过 ⇒ 不补") 的理据**只对超时那一支成立** —— 它靠的是 - "窗口够长 ⟹ 固件早该把该发的都发了"; 而 pump 那一支是**读链路炸了**, 根本没等过窗口, - 于是"被吸收的那条是本 token 自己的"这个推断在那一支上**没有依据**。 - - ⚠ 判错的方向是**假成功**, 不是"宁可让一条报结局未知": 被放弃的那条请求**固件真还欠 - 它一条应答**, 而例外把该补的那格吞了 ⇒ 那条应答到达时队列非空 ⇒ `on_reply` 直接配给 - **下一条** token ⇒ 调用方拿到**别人那条**的规划结果并**报成功** (`0x4E` 载荷里没有 - 命令 id, 它无从分辨)。 - - 场景 (照 `test_an_absorb_during_the_wait_window_suppresses_the_fresh_credit` 摆, - 只把"放弃"那一步换成 pump 支): - 清队(额度 1) → 登记本 token(**先于**那条旧应答到达) → 旧应答被吸收 → pump 炸 ⇒ - 本 token 被放弃 → 它的**自己那条**应答到达。 - - 判据: 放弃之后 `_absorb == 1`, 且那条应答**不许**配给下一个 token。 - """ - # ⚠ 必须带 `arm`:旧 `pump` 支的等价物是"读线程死掉",而那一支要读 `arm._a._reader_error`。 - cp = _CartPending(absorb_ttl=15.0, arm=offline_arm) - - stale = cp.register() # 清队前的那条在途记账 - assert cp.clear_pending("清队") == 1 # ⇒ 额度 1 (固件可能还欠 `stale` 一条) - assert stale.lost is not None - - tok = cp.register() # 本 token: `absorbed_at` 快照 = 0 - cp.on_reply(b"stale") # **旧的**那条先到 ⇒ 被吸收 (不配给 `tok`) - assert cp.absorbed_replies == 1 - - # ⚠ `pump` 参数已删。旧"pump 支"(调用方驱动取帧时炸)的等价物是**读线程死掉** - # —— 两者都是"链路没了、这条请求没人再来收",`wait` 必须同样放弃并**原样抛出病因**。 - cp._arm._a._reader_error = TransportError("桩: 读链路炸了 (读线程支)") - - with pytest.raises(TransportError): - cp.wait(tok, 5.0) # 这一支放弃 —— **没等过窗口** - - credit = cp._absorb # ⚠ 必须在下面那条 `on_reply` **之前**读: - # 应答一到就会把这格额度消费掉 - - nxt = cp.register() - cp.on_reply(b"tok-own") # `tok` **自己**那条 (固件确实会发) - mismatched = nxt.reply is not None - - assert not mismatched, ( - "`tok` 自己那条应答配给了下一个 token = **报成功而实际没跑完** (假成功) —— " - "pump 失败支错走了例外, 该补的那格额度没补") - assert credit == 1, ( - "pump 失败支也没补额度 —— 例外只许挂在超时那一支上 (那一支才有" - "'窗口够长'的理据); 补不上就没有东西替这条迟到的应答兜底") - - -def test_absorb_happens_before_pairing_even_with_a_live_token_queued(offline_arm): - """⚠ 本组最关键的一条 —— 防**假成功**。 - - 清队(T1) → 立刻登记(T2, 队列**非空**) → T1 的迟到应答到达。吸收若只挂在"队列空" - 那个分支上, 这条应答会被配给 **T2** —— 即**报成功而实际没跑完**。 - - 判据: `absorbed_replies == 1` **且 T2 仍未收尾** (还留在队里等它自己那条)。 - """ - arm = offline_arm - t1 = arm._cart.register() - arm._cart.clear_pending("T1 清队") - t2 = arm._cart.register() # 清队后立刻登记 → 队列非空 - - assert arm._cart.pending == 1 - assert t1.lost is not None - - _push(arm, 0x4E, b"late-T1") - _settle(arm) - - assert arm._cart.absorbed_replies == 1, "队列非空时吸收没生效" - assert t2.reply is None, ( - "T2 配到了 T1 的迟到应答 = 假成功 (T2 实际还没跑完)") - assert t2.lost is None, "T2 既没配对也没被作废 —— 它应当还在等自己的应答" - assert arm._cart.pending == 1 - assert arm._cart.extra_replies == 0 - - -def test_absorbance_expires_after_move_timeout(monkeypatch): - """额度过期后, 队列空再收应答仍**计数并报错** —— 真·脱同步不能被吞。 - - "多了一条"这条守卫的语义没有变, 只是被吸收额度**让路**了一段有限的时间。 - """ - clock = _FakeClock() - monkeypatch.setattr(cart_mod, "time", clock) - - fresh = _CartPending(absorb_ttl=15.0) - fresh.register() - assert fresh.clear_pending("测试清队") == 1 # 额度 1, 截止 = 清队时刻(1000) + 15 - clock.t = 1014.5 - fresh.on_reply(b"within-ttl") - assert fresh.absorbed_replies == 1, "没过期的额度居然不吸收" - - stale = _CartPending(absorb_ttl=15.0) - stale.register() - assert stale.clear_pending("测试清队") == 1 # 额度 1, 截止 = 清队时刻(1014.5) + 15 - clock.t = 1029.501 # 越过截止 (`now > 截止` 才过期) - with pytest.raises(LiteArmError): - stale.on_reply(b"after-ttl") - assert stale.extra_replies == 1, "过期的额度还在吞应答 —— 硬错误降级成静默" - assert stale.absorbed_replies == 0 - - # ⚠ 边界: "now **恰好** == 截止"算**未**过期 (实现取 `now > 截止`) —— 规格没写这 - # 一侧, 是实现的刻意选择, 故在这里钉住: 改成 `>=` 本断言必须变红。 - edge = _CartPending(absorb_ttl=15.0) - clock.t = 2000.0 - edge.register() - assert edge.clear_pending("边界清队") == 1 # 额度 1, 截止 = 2000 + 15 = 2015 - clock.t = 2015.0 # **恰好**落在截止上 - edge.on_reply(b"exactly-at-deadline") - assert edge.absorbed_replies == 1, ( - "\"now == 截止\"被判成了过期 —— 实现取 `now > 截止` (相等仍未过期)") - assert edge.extra_replies == 0 - - -def test_allowance_accumulates_across_clears(): - """清两次 (各清掉一条) ⇒ 能吸收**两条**。 - - 写成"重置为本次条数"的话, 前一次那条待吸收的迟到应答会退化成硬错误 —— 而清队与 - 迟到应答的到达顺序本来就无法保证 (两条清队之间那条应答可能还没被读到)。 - """ - cp = _CartPending(absorb_ttl=15.0) - cp.register() - assert cp.clear_pending("第一次") == 1 - cp.register() - assert cp.clear_pending("第二次") == 1 # 累加, 不是重置 - - cp.on_reply(b"late-first") - cp.on_reply(b"late-second") - - assert cp.absorbed_replies == 2 - assert cp.extra_replies == 0 - - -def test_clear_of_an_empty_queue_does_not_refresh_the_deadline(monkeypatch): - """⚠ 空清队**不许**刷新截止时间 —— 否则额度永不过期。 - - 零重力保活线程每 40ms 发一条 `0x06` (它在 `_CART_CLEARS_UPON` 里), 那几乎永远是 - "空清队"。若 `n == 0` 也把截止推到 `now + ttl`, 额度就永远活着 —— 此后一条**真** - 脱同步的应答会被永久静默吞掉, 硬错误降级成静默。 - """ - clock = _FakeClock() - monkeypatch.setattr(cart_mod, "time", clock) - - cp = _CartPending(absorb_ttl=15.0) - cp.register() - assert cp.clear_pending("T1 清队") == 1 # 额度 1, 截止 = 1000 + 15 = 1015 - - clock.t = 1010.0 - for _ in range(5): # 保活线程式的空清队 (队里没有 token) - assert cp.clear_pending("保活 0x06") == 0 - clock.t += 1.0 # 1010 → 1015 - - clock.t = 1016.0 # 越过最初那条截止 (1015) - with pytest.raises(LiteArmError): - cp.on_reply(b"desync") - assert cp.extra_replies == 1 - assert cp.absorbed_replies == 0, ( - "空清队刷新了截止 → 额度永不过期, 真脱同步被永久静默") - - -def test_both_cart_pending_construction_sites_take_move_timeout(monkeypatch, - fake_transport_factory): - """两个构造点 (`__init__` 与 `connect()`) **都**得按 `move_timeout` 现算 TTL, - 且**都不许低于** `_ABSORB_TTL_FLOOR`。 - - ⚠ 只验一个点会漏掉另一个: `connect()` 会**重建** `_CartPending`, 那一处若写死默认 - 值, 真机 (总是先 `connect()`) 走的就是**没接线**的那个 —— 于是要么 `move_timeout` - 调小不生效, 要么额度永不过期。 - - ⚠ 期望值是 `max(move_timeout, _ABSORB_TTL_FLOOR)` **不是** `move_timeout`: - 额度过期而那条应答还在路上时, 它会被 `on_reply` 配给**新登记**的那条 token ⇒ - 调用方拿到**别人那条**的规划结果并**报成功** (见 - `test_a_reply_that_outlives_move_timeout_is_not_paired_to_the_next_request`)。 - 故 TTL 有一个**固件依据的下限** (三段推导见 `_ABSORB_TTL_FLOOR` 的定义 —— 别在这里 - 复述那个算式: 复述出来的第二份就是会漂移的那一份); - 这半条判据由"取一个**远小于**下限的 `move_timeout`, 断言 TTL **没有**跟着变小" - 钉住 —— 只断言"等于 `max(...)"的话, 实现若把下限整个删掉、改成恒等于 `move_timeout` - 照样绿。 - - ⚠ 两半的边界都要**相对清队时刻**取: 写成"绝对时刻 + 硬编码边界"的话, 把 TTL 改成 - 0.5 也照样绿 —— 只验得出"太大"、验不出"太小" (那正是漏接线的形态)。 - """ - clock = _FakeClock() - monkeypatch.setattr(cart_mod, "time", clock) - fake_transport_factory() - from litearm import Arm - - MV_TIMEOUT = 2.0 # < 下限 ⇒ 走"下限兜底"那一支 - MV_TIMEOUT_BIG = 20.0 # > 下限 ⇒ 必须整段跟随 `move_timeout` - FLOOR = cart_mod._ABSORB_TTL_FLOOR - - def _probe(cart, expected: float) -> None: - """以当前时刻清队, 再验"TTL 内吸收 / 越过 TTL 报错" —— 两半都相对清队时刻取边界。""" - ttl = cart._absorb_ttl # 接线成果本身, 不是期望值 - assert ttl == expected, ( - f"TTL 拿到 {ttl}, 应为 {expected} " - f"(写死/漏传/漏掉下限都会在这里露出来)") - - base = clock.t - cart.register() - assert cart.clear_pending("清队") == 1 # 截止 = base + ttl - - clock.t = base + ttl - 1e-3 # 差一点才到截止 —— 必须吸收 - cart.on_reply(b"within-ttl") - assert cart.absorbed_replies == 1, "没接上额度 (额度根本没生效)" - - base = clock.t - cart.register() - assert cart.clear_pending("清队") == 1 # 截止 = base + ttl - clock.t = base + ttl + 1e-3 # 刚过截止 - with pytest.raises(LiteArmError): - cart.on_reply(b"over-ttl") - assert cart.extra_replies == 1, "TTL 太长 (真脱同步被吞)" - - arm = Arm(port="fake", move_timeout=MV_TIMEOUT) # 构造点 ①: `__init__` - _probe(arm._cart, max(MV_TIMEOUT, FLOOR)) - assert arm._cart._absorb_ttl > MV_TIMEOUT, ( - "TTL 跟着小 move_timeout 一起变小了 —— 额度过期早于固件那条应答的到达时刻 " - "= 陈旧 0x4E 会配给新 token (假成功)") - - cart_before = arm._cart - # ⚠ 走 `reconnect()` 而不是 `connect()`: `connect()` 现在是**幂等**的 (已连着同一 - # 目标时是 no-op, 不重建会话), 而本行要的正是"会话重建"这个动作本身。 - arm.reconnect() # 构造点 ②: `connect()` 重建 - assert arm._cart is not cart_before, ( - "会话重建没有重建 `_CartPending` —— 旧对象的累积计数会被下半个 probe 继承, " - "于是失败会表现成'额度没生效'(断言 `absorbed_replies == 1` 上) 而非本行; " - "先钉住对象身份, 失败消息才指向真实死因") - _probe(arm._cart, max(MV_TIMEOUT, FLOOR)) - - # ⚠ `max` 的另一半: 大 `move_timeout` 那支**不许**被下限砍短 (方向是"只增不减") - arm.move_timeout = MV_TIMEOUT_BIG - arm.reconnect() - _probe(arm._cart, MV_TIMEOUT_BIG) - - -def test_the_absorb_ttl_floor_is_the_firmware_planning_bound_plus_margin(): - """吸收额度的存活下限**不是拍脑袋的常数** —— 它有固件依据, 写在常量的定义里。 - - ⚠ 判据要覆盖的是**到达**时刻, 三段相加 (逐段的 `文件:行号` 见 `_ABSORB_TTL_FLOOR`): - - ① **生成** ≤ 写帧 + **3 s**: `RSP_CART_PLAN` 的唯一发射点是 `cart_report_if_done()` - (`usb_cmd.c:1246`, `usb_cmd_reply(RSP_CART_PLAN,…)` 在 **`:1261`**), 由 main 循环 - 每圈调 (`Core/Src/main.c:187`) —— **不在** `cart_publish()` 里。规划期硬上界 - `CART_PLAN_MAX_TICKS` = `LITEARM_CTRL_HZ * 3u` = 3 s (`cart_exec.h:42`), 到点 - `cart_tick_timeout` 会 `cart_abort()` (`.c:890`) 并补发终态应答 (`.c:917`)。 - ② **发射时延** ≤ **~8 s**: main 循环里排在 `cart_report_if_done` **前面**的 - `usb_cmd_report()` (`main.c:179`) 可能卡在参数保存的阻塞擦写上 —— 固件自述 - "擦写 ~1s CPU 全停" (`usb_cmd.c:1272`), 另两处按 ~1.86s 记 (`usb_cmd.c:690` / - `usb_cmd.h:94`)。⚠ **这两个只是典型值**, 唯一的上界是同一个现象在**看门狗**那个 - 量纲上的自述: `hw_watchdog.h:28` "擦除期间 CPU 取指停顿 … 擦写前放宽到 ~8 s" - (实现在 `hw_watchdog.c:63-66`, 由 `flash_store.c:332/:351` 夹住整次擦写)。取它。 - ③ **链路 + 主机侧取帧余量** ~1 s。 - - ⇒ 下限 ≈ 3 + 8 + 1 = **12 s**。⚠ 只按 ① 取 (旧写法: 3s + 1s = 4s) **短一截** —— - 那只覆盖了"结果被生成", 没覆盖"它还要等 main 循环把它送出去"。 - ⚠⚠ 下限**两个方向都错**, 别只记一侧: 取大 ⇒ 真脱同步被**静默**吸收; 取小 ⇒ 迟到的 - 陈旧应答配给新 token ⇒ **假成功**。故宁可取大 (这是一条**正确性条件**, 不是余量)。 - """ - assert cart_mod._ABSORB_TTL_FLOOR >= 12.0, ( - "下限没有覆盖'生成 3s + 发射时延 ~8s (IWDG park 窗口, hw_watchdog.h:28)' —— " - "额度会先过期, 陈旧应答就会配给新 token ⇒ 假成功") - assert cart_mod._ABSORB_TTL_FLOOR <= 15.0, ( - "余量过大: 它只让'真脱同步被静默吸收'的时间窗变长, 对正确性没有贡献") - assert cart_mod.cart_absorb_ttl(0.1) == cart_mod._ABSORB_TTL_FLOOR - assert cart_mod.cart_absorb_ttl(20.0) == 20.0 - - -class _SwallowPlanOnce(FakeTransport): - """第一条**合法载荷**的 `0x3A` 只回 ACK、**不推** `0x4E` —— 模拟"应答比 - `move_timeout` 还慢" (规划慢了 / 上行挤满了 / 我们读得太迟)。 - - ⚠ 空载荷 (`probe` 的探测帧) 不走这一支: 它照常撞长度校验回 `ERR{0x3A,0x01}`。 - """ - - swallow = True - - def _cart_cmd(self, cmd: int, payload: bytes) -> None: - if cmd == P.CMD_MOVE_L and payload and self.swallow: - self.swallow = False - self._push(P.pack_frame(P.RSP_ACK, bytes([cmd]))) - return - super()._cart_cmd(cmd, payload) - - -def test_a_reply_that_outlives_move_timeout_is_not_paired_to_the_next_request(monkeypatch): - """⚠⚠ 额度过期 + 队列非空 ⇒ 清队前的**陈旧** `0x4E` 被悄悄配给**新** token: - 调用方**报成功**, 却拿到**别人那条**的规划结果 (本项目最忌讳的方向, E3 实测)。 - - 场景 (真机形状): 固件那条应答比 `move_timeout` 还慢 ⇒ 主机先超时放弃 - (`drop_and_absorb` 留一格额度), 而应答随后才到。**额度还活着**时它被吸收, 下一条 - 命令拿到**自己**那条; **额度已经过期**时 `on_reply` 就直接把它配给队列里**新登记** - 的那条 token —— `0x4E` 载荷里**没有命令 id**, 它无从分辨。 - - ⇒ 额度的存活时间必须覆盖"固件还可能发出那条应答"的**最长时间** —— 那是一个三段 - 推导的**到达**上界 (见 `_ABSORB_TTL_FLOOR`: 生成 3s + 发射时延 ~8s + 链路余量)。 - 光在 docstring 里写"过期后不可归属"**不改可达性** —— 本用例就是那条可达性。 - - 判据: 第二条拿到的必须是**它自己**那条的 `n_wp`/`plan_us`。 - """ - from litearm.arm import Arm - - def factory(port="fake", timeout=0.2, **_ignored): - return _SwallowPlanOnce(port=port, timeout=timeout) - - monkeypatch.setattr(arm_mod, "SerialTransport", factory) - arm = Arm(port="fake", move_timeout=0.15).connect() - tr = arm._tr - tr.swallow = True - - with pytest.raises(CartReplyLostError): - arm.move_l(_L_POSE, speed=0.3, wait=False) # 固件**其实已受理** - - time.sleep(0.20) # ← 比 `move_timeout` (0.15) 还慢 —— 额度若只有那么长就已过期 - tr.push_frame(P.RSP_CART_PLAN, _plan_payload(n_wp=99, plan_us=1111)) # 第一条那条 - - plan = arm.move_l(_L_POSE, speed=0.3, wait=False) - assert (plan.n_wp, plan.plan_us) == (tr.cart_n_wp, tr.cart_plan_us), ( - f"第二条拿到了 (n_wp={plan.n_wp}, plan_us={plan.plan_us}) —— 那是**第一条**那条" - f"陈旧应答的结果 (自己那条是 n_wp={tr.cart_n_wp}, plan_us={tr.cart_plan_us}) " - f"= 假成功; 额度到期得太早 (`move_timeout`=0.15 不足以覆盖它)") - assert arm._cart.absorbed_replies == 1, "那条陈旧应答不是被吸收的 —— 那就是被错配了" - - -# --------------------------------------------------------------------------- -# 6. 放弃路径: `wait` 超时后的迟到应答 + "待认领"列的界 (Task 4.6) -# --------------------------------------------------------------------------- - -class _SilentCartAck: - """混入: **合法载荷**的 `0x3A` 只记不发 (应答不回) —— 模拟"ACK 丢在链路上"。 - - 这正是 `_request_and_wait` 那条决定的现场: 命令**已送达** (固件会受理并回 `0x4E`), - 但主机读不到 ACK ⇒ 超时放弃。空载荷的探测帧不参与 (照常走 `default`/长度校验)。 - """ - - def write_frame(self, cmd, payload=b""): - if cmd == P.CMD_MOVE_L and payload: - with self._tx_lock: - self.tx_log.append((cmd, bytes(payload))) - self.tx_stamps.append(time.monotonic()) - return - super().write_frame(cmd, payload) - - -class _TickingClock: - """**每次读时都前进**的假时钟 —— 让 `_Ack.expect` 的 1.0s 窗口几乎立刻到期。 - - ⚠ 与 `_FakeClock` 的区别: 那个是**冻结**的 (给"额度过期边界"用)。冻结的时钟在这里 - 不行 —— `expect` 的循环形如 `while monotonic() < end`, 时钟不动就是**死循环** - (每次读到的状态帧都不满足 `want`, 继续等)。 - 本类不动 `threading` (只换 `arm` 模块里的 `time` 引用), 故不影响别的线程。 - """ - - def __init__(self, t: float = 1000.0, step: float = 0.25) -> None: - self.t = t - self.step = step - - def monotonic(self) -> float: - self.t += self.step - return self.t - - -def test_a_late_reply_after_a_token_timeout_is_absorbed_not_raised(offline_arm): - """⚠ `wait` 超时摘 token 之后, 固件**真欠**的那条 `0x4E` 会炸**无关读路径** —— - 摘 token 时必须**同时**留一格吸收额度 (`drop_and_absorb`, 与 `clear_pending` 同构)。 - - 场景: 固件已受理这条命令 (应答在路上), 而主机等不到就先超时放弃了 —— `wait` 摘掉 - token 并抛 `CartReplyLostError` (**结局未知**, 这个判断是对的)。随后那条应答到达, - 若不留额度, 它撞上"队列空"判据 ⇒ `LiteArmError` 从 `get_state()` 里炸出来, 实测形状 - 与一次**真**脱同步**一模一样** ("收到 0x4E ... 队列为空"), 现场无法归因。 - - 判据: `get_state()` 不抛, 且 `extra_replies == 0` —— 那一条被**吸收** - (`absorbed_replies == 1`), 不是被当成脱同步。方向与"多了一条"守卫一致: - 宁可多吸收一条, 绝不把"我们自己放弃了一条"报成"固件与主机已错配"。 - """ - arm = offline_arm - tok = arm._cart.register() - - with pytest.raises(CartReplyLostError): - arm._cart.wait(tok, 0.05) - assert arm._cart.absorbed_replies == 0, "还没给额度就先吸收了一条?" - - arm._tr._resp.clear() - _push(arm, 0x4E, _plan_payload()) # 固件那条迟到/在路上的应答 - - st = arm.get_state(refresh=True, timeout=0.2).value # ⚠ 无关读路径: 不许抛 - assert st is not None - assert arm._cart.absorbed_replies == 1 - assert arm._cart.extra_replies == 0, ( - "超时放弃后那条应答被算成了真·脱同步 —— `LiteArmError` 从读路径里炸出来了") - - -def test_the_unclaimed_column_is_bounded_when_the_caller_gives_up(monkeypatch, - fake_transport_factory): - """⚠ "待认领"列 (`_unclaimed`) 在**调用方放弃 token** 的路径上会无界增长 —— 必须封顶。 - - 漏点只有一个: `_request_and_wait` 的 ACK 超时 (`MotionTimeoutError`) **刻意不摘** - token (摘了会让"固件其实已受理"那条应答配给后面的活 token = 假成功 —— 那个决定是 - 对的)。于是那条请求的 `0x4E` 一到就落进 `_unclaimed`, 而它的调用方**早已带着异常 - 返回**、再也不会来 `wait`; 只有 `poll_cart` 能摘 ⇒ 无界就是内存增长。 - - 判据 (与轮数无关的"有界"): 跑 `_UNCLAIMED_MAX + 5` 轮 (每轮 = 一次 ACK 超时 + 那条 - 迟到的 `0x4E`), 断言列长**恰好**等于上界 (不再随轮数增长), 且越界的被**记进** - `evicted_unclaimed` —— 丢弃不报错 (报错会从无关读路径炸出来), 但不能是静默的。 - - ⚠ 耗时: `expect` 的 1.0s 窗口由 `_TickingClock` 假时钟**快速**推到期, 而 ACK 由 - `_SilentCartAck` 桩**不回** (两个都是这条用例的必要条件: 一个真等 1s × N 轮太慢, - 另一个若不静默则 `expect` 会读到 ACK 而根本不超时)。时钟只在 `connect()` **之后** - 打补丁 —— 握手/探测那几步要用真时钟驱动读循环。 - """ - from fake_serial import FakeTransport - - class _T(_SilentCartAck, FakeTransport): - pass - - def factory(port="fake", timeout=0.2, **_ignored): - return _T(port=port, timeout=timeout) - - monkeypatch.setattr(arm_mod, "SerialTransport", factory) - from litearm import Arm - - arm = Arm(port="fake").connect() - clock = _TickingClock() # 每次读时间戳都前进 -> 窗口几乎立刻到期 - monkeypatch.setattr(arm_mod, "time", clock) - - rounds = _UNCLAIMED_MAX + 5 - for i in range(rounds): - with pytest.raises(MotionTimeoutError): - arm.move_l((0.30, 0.0, 0.35, 0.0, 0.0, 0.0), speed=0.3) - # 调用方带着异常走了, 而固件**其实已受理** —— 那条 0x4E 现在才到 - # (`n_wp` 当序号, 便于分辨留下的是哪几条) - _push(arm, 0x4E, _plan_payload(n_wp=i)) - _settle(arm) - - assert arm._cart.pending == 0 - assert len(arm._cart._unclaimed) == _UNCLAIMED_MAX, ( - f"放弃路径让'待认领'列涨到 {len(arm._cart._unclaimed)} 条 (上界 {_UNCLAIMED_MAX})" - f" —— 无界增长") - assert arm._cart.evicted_unclaimed == rounds - _UNCLAIMED_MAX, ( - "越界丢弃是静默的 (没有计数) —— 本模块其余丢弃点都留了可观测面") - - # ⚠ 界必须保住 `poll_cart` 的语义: 剩下的仍是**可交付的结果**, 且丢的是**最旧**的 - # (丢最新会让调用方先拿到早已过期的那些 —— 同一句 "丢最旧" 必须真的落在 pop(0) 上)。 - assert [arm.poll_cart().n_wp for _ in range(_UNCLAIMED_MAX)] == \ - list(range(rounds - _UNCLAIMED_MAX, rounds)), ( - "留下的不是**最新**那 8 条 (丢错了一端), 或 `poll_cart` 已经交付不出结果") - assert arm.poll_cart() is None - assert len(arm._cart._unclaimed) == 0 - - -# --------------------------------------------------------------------------- -# 7. 一条**外来**的 `ERR{cmd}` 不许把本命令判成"被拒" (假成功的高发点) -# --------------------------------------------------------------------------- - -#: 随便一条合法 `move_l` 位姿 (这条命令不做起点校验, 只要长度够 28B)。 -_L_POSE = (0.30, 0.0, 0.35, 0.0, 0.0, 0.0) - - -class _ForeignCartErrOnce(FakeTransport): - """在**受理之前**先塞一条**不属于本次请求**的 `ERR{0x3A,0x01}`, 然后照常受理。 - - 这条外来帧的来源是真实可达的 (不是编出来的): `cart.probe()` 的 docstring 自己写明 - "迟到的探测 ERR 会从无关读路径里冒出来", 而 `probe` 会**重试** (第一次超时、第二次 - 读到第一次那条) ⇒ `connect()` 返回时, 下游还欠着一条 `ERR{0x3A}` 没人读。它一到, - 就会被**下一条** `move_l` 的 ACK 等待撞上。 - - 之后走 `super()._cart_cmd` —— 也就是**固件其实受理了**这条命令 (ACK + `0x4E` 都会发)。 - """ - - stray_pending = True - reject_next = False - - def _cart_cmd(self, cmd: int, payload: bytes) -> None: - # `payload` 非空 = 真的是一条命令; 空载荷是 `probe()` 的探测帧, 不掺和 - if cmd == P.CMD_MOVE_L and payload and self.stray_pending: - self.stray_pending = False - self._push(P.pack_frame(P.RSP_ERR, bytes([cmd, 0x01]))) # 外来 ERR - if cmd == P.CMD_MOVE_L and payload and self.reject_next: - self.reject_next = False - self._push(P.pack_frame(P.RSP_ERR, bytes([cmd, 0x03]))) # 本条被门禁拒 - return - super()._cart_cmd(cmd, payload) - - -def test_a_foreign_err_cannot_be_taken_for_this_commands_own_rejection(monkeypatch): - """⚠ `expect(echo_cmd=...)` **只按命令码**比对, 而 `0x3A/0x3B/0x3E` **共用码空间** - ⇒ 流里一条**别人的** `ERR{0x3A}` 会被本命令认成"我被拒了"。认错的代价是**双向**的: - - * 报错的那条命令**其实已被受理** ⇒ 调用方拿到了一个假的失败 (臂真的会动); - * 由此摘掉的那条活 token 让"在途 ⟹ 应答"少一格 ⇒ 固件为它发的那条 `0x4E` 配给 - **下一条**命令 ⇒ **下一条报成功, 而它的命令被固件拒了、一步没跑** (假成功 —— - 本项目最忌讳的方向)。 - - 判据 (逐条命令, 不能只看"一成功一失败" —— 那恰好是无修复时的观测): - ① 被受理那条必须拿到 `CartPlan` (它真的跑了); - ② 被拒那条必须是它自己那条 `CommandRejectedError`, **绝不许**是 `CartPlan`; - ③ 被拒之后账必须重新平 (`pending == 0` 且没有多出来的吸收额度) —— 否则下一条命令 - 的应答会被这笔无主的额度吞掉, 变成此后**每一条**都报"结局未知"。 - - ⚠ 判据 ② 的 `ERR` 是**门禁**那条 (`0x03`); 于是"这两个 ERR 是不是同一条命令的" - 在**码**上不可分辨 —— 唯一可分辨的信号是固件**受理必回 `ACK{cmd}`、拒绝绝不回**。 - """ - from litearm.cart import CartPlan - - def factory(port="fake", timeout=0.2, **_ignored): - return _ForeignCartErrOnce(port=port, timeout=timeout) - - monkeypatch.setattr(arm_mod, "SerialTransport", factory) - from litearm import Arm - - arm = Arm(port="fake", move_timeout=0.3).connect() - tr = arm._tr - assert tr.stray_pending, "用例自身失效: 外来 ERR 在 connect() 期间就被用掉了" - - plan = arm.move_l(_L_POSE, speed=0.3, wait=False) # ← 固件其实**受理了**这条 - assert isinstance(plan, CartPlan), ( - f"第①条被固件受理了, 却报 {plan!r} —— 它认下了 probe 遗留的那条**外来** ERR") - assert plan.ok - - tr.reject_next = True - with pytest.raises(CommandRejectedError): - arm.move_l((0.40, 0.0, 0.40, 0.0, 0.0, 0.0), speed=0.3, wait=False) - - assert arm._cart.pending == 0 - assert arm._cart.absorbed_replies == 0, ( - "留下了一笔无主的吸收额度 —— 下一条命令的应答会被它吞掉 (那条报'结局未知')") - tr.reject_next = False - plan = arm.move_l(_L_POSE, speed=0.3, wait=False) # 配对没有错位 - assert plan.ok and arm._cart.absorbed_replies == 0 - - -# --------------------------------------------------------------------------- -# 8. 会话重建 = 第二处"销毁记账" (`Arm.connect()` 重建 `_CartPending`) -# --------------------------------------------------------------------------- - -def test_reconnect_wakes_the_old_sessions_waiters(fake_transport_factory): - """⚠ `connect()` 重建 `_CartPending` 时, **旧对象**里在途的 token 必须被**唤醒**。 - - 不唤醒的后果是"两个窗口分叉": 旧会话那条请求的调用方(可能正阻塞在 `wait` 上)会一直 - 挂到 `move_timeout`, 而新会话早已开始 —— 它等的那条应答**永远不会**再配上它 - (新对象是另一份配对状态)。 - """ - fake_transport_factory() - from litearm import Arm - - arm = Arm(port="fake").connect() - stale = arm._cart.register() # 旧会话里在途的一条 - - # ⚠ `reconnect()` 而不是 `connect()`: 后者幂等 (已连着即 no-op, 不再重建会话)。 - arm.reconnect() # 新会话 = 新 `_CartPending` - - assert stale.lost is not None, ( - "旧会话那条在途 token 没被唤醒 —— 等它的线程会一直挂到 move_timeout, " - "而重连之后它已经不可能再收到应答了") - - -def test_reconnect_inherits_the_in_flight_count_as_absorb_credit(fake_transport_factory): - """⚠ 会话重建是**第二处"销毁记账"**: 旧的账被销毁了, 但那份"可能还欠应答"的额度 - **必须跟着搬过去** —— 否则旧会话那条迟到 `0x4E` 会撞上新对象的"队列为空"判据, - 从一个**毫不相干的读路径** (`get_state()`) 炸出 `LiteArmError`, 归因指向 - "固件与主机已错配", 而真相是"我们自己重建了会话"。 - - (`clear_pending`/超时那两处都留了额度; `connect()` 这处从前一格都不给。) - """ - fake_transport_factory() - from litearm import Arm - - arm = Arm(port="fake").connect() - arm._cart.register() # 旧会话留下一条在途记账 - arm.reconnect() # ⚠ 不是 connect(): 后者幂等, 不重建会话 - - _push(arm, 0x4E, _plan_payload(n_wp=7)) # 旧会话那条应答现在才到 - - st = arm.get_state(refresh=True, timeout=0.2).value # 无关读路径: 不许抛 - assert st is not None - assert arm._cart.extra_replies == 0, ( - "旧会话的迟到应答被算成'真·脱同步' —— `LiteArmError` 从无关读路径里炸出来了") - assert arm._cart.absorbed_replies == 1, "那条应答既没被吸收、也没报错?" - - -def test_an_inherited_credit_cannot_perpetuate_itself_across_a_reconnect( - fake_transport_factory): - """⚠⚠ 继承额度**不许被超时路径续成永动机** —— 那是 F5 修出来的**新入口** (实测)。 - - 继承来的那一格额度与"挣来的"额度在 `on_reply` 里**先于配对**被消费 (顺序是载重的, - 见 `on_reply`), 所以它吃掉的是**新会话自己那条**应答: 那条命令报"结局未知" - (`CartReplyLostError`) —— 这是 F5 的**知情取舍** (两只在原理上无法区分: 载荷里没有 - 命令 id, 旧会话那条迟到应答与新 token 自己那条形状完全一样)。 - - ⚠ **回不来的那一支才是缺陷**: 那条命令随后超时放弃, 而**超时路径**的 - `drop_and_absorb` 会按"固件还欠它一条"补一格额度 —— 若那格的截止又被顺手续上, 额度 - 就**永远 ≥ 1**: 此后**每一条**命令的应答都被吞, 每条都报"结局未知", 且每轮再补一格, - **自持**。实测 (改前): `#1..#6` 全红, `absorb=1 absorbed=1..6`。 - - 判据: 第 #1 条照旧报结局未知 (取舍, 必须留着 —— 去掉它就是允许旧会话那条迟到应答 - 配给新 token = **假成功**), 但 **#2 起必须恢复正常**。机理不是"少补一格"而是 - "**不许为一条已经被吸收过的请求再记一笔额度**" (见 `drop_and_absorb`: 吸收额度在 - 这条 token 的窗口里被消费过 ⟹ 那条被吃掉的应答**就是它的** ⟹ 固件不再欠)。 - """ - fake_transport_factory() - from litearm import Arm - - arm = Arm(port="fake", move_timeout=0.15).connect() - arm._cart.register() # 旧会话留下一条在途记账 ⇒ 新会话继承额度 1 - arm.reconnect() # ⚠ 不是 connect(): 后者幂等, 不重建会话 - assert arm._cart._absorb == 1, "用例自身失效: 额度没被继承 (那测的就不是这条路径)" - - got = [] - for _ in range(6): - try: - arm.move_l(_L_POSE, speed=0.3, wait=False) - got.append("ok") - except CartReplyLostError: - got.append("lost") - - assert got[0] == "lost", ( - "第 #1 条不该正常 —— 继承那一格**应当**吃掉它的应答 (那是 F5 的取舍; 两只无法区分)") - assert got[1:] == ["ok"] * 5, ( - f"继承额度自持了: #2 起仍报结局未知 ({got}) —— 超时路径每轮给它续一格, " - f"此后**每一条**都会报'结局未知'。恢复只该发生在额度过期/被消费光/重连") - assert arm._cart.absorbed_replies == 1, ( - "吸收计数与'只吃掉一条'不符 —— 自持的痕迹") diff --git a/tests/test_cart_wait.py b/tests/test_cart_wait.py deleted file mode 100644 index 5344215..0000000 --- a/tests/test_cart_wait.py +++ /dev/null @@ -1,594 +0,0 @@ -"""Task 5: 笛卡尔到位等待 (`CART_BUSY` bit10) + `wait=True`。 - -**为什么**: 三条入口从前只等到**规划结果** (`0x4E`) 就返回 —— 而 `0x4E` 只说明"固件收了 -这条路点、规划出来了", 不说明**臂动没动、动完没有**。调用方拿到 `CartPlan` 时臂可能正 -在半路。本 Task 让入口默认等到**停稳**再返回, 并把收尾事实填进 `CartPlan` 的四个字段。 - -**本文件钉死的判据**: - -1. **主判据**: 可信帧上看到 `bit10` **1→0**, **且** `q` 静止判据成立; -2. **降级分支**: 可信帧上**始终**没见过 `bit10=1` 但 `q` 静止 ⇒ 同样 "停稳" (`settled` 还要过下一关), - `started_busy=False`, **不抛异常** ("不能判失败"); -3. **`q` 静止判据是双判据**: 相邻两帧 Δq < `q_tol` 连续 `arrive_frames` 帧 **且** - `dq` 的 max-norm < `dq_tol` —— 只抄一半会宽松得多 (`bit10` 落 0 那一刻臂可能还在爬); -4. **故障立刻抛** (`MotorFaultError`) —— 与 `_arrive` 同款, 不能悄悄返回 `settled=False`; -5. **上限是 `move_timeout`** (`MotionTimeoutError`) —— EMERGENCY / 未使能期间固件的 cart - FSM 完全冻结、`CART_BUSY` **常亮**, 只等 `bit10` 落 0 会耗满超时, 所以上限存在; - ⚠ **"常亮"只对"安全锁存 + `RUNNING`/`READY`"成立** (见 `cart._wait_settled`): - `PLANNING` ≤3s 自解, 而**命令**引起的失能/急停反而**会**清掉它 —— 别读成三条路径都亮; -6. **新鲜度闸**: 只信"命令发出之后生成"的状态帧 (见下), 陈旧帧**既不判到位也不判故障**; -7. **`wait=False`** 时四个字段回到"未等待"默认值, 且**一帧都不多读**; -8. **断连唤醒**: `close()` 期间在等的线程必须**带失败原因**立刻退出, 不能挂到 `move_timeout`; -9. ⚠⚠ **"停稳" ≠ "停在了目标上"**: `settled=True` 还要求停稳后回读的实际 TCP 与本次 - 请求的目标位姿对得上 —— 否则一条**被别的运动作废**的轨迹 (收尾同样是 `bit10=0` + - `q` 静止) 会被报成成功 (**假成功**方向); -10. ⚠ **并发读者不许把到位等待饿死**: 判据认的是**帧**, 不是"谁读的帧" —— 只认自己读到的 - 帧的实现会被 `get_state()`/`get_tcp()` 抢帧抢到超时 (**假失败**方向)。 - -⚠ **关于新鲜度闸的一条实测结论 (写在这里免得后人再推一遍)**: 计划给的判据是 -"`seq0` = 发命令**之前**已知的最高状态帧序号, 只信 `(seq - seq0) & 0xFFFF ∈ (0, 32768)`"。 -在**当前**取帧结构下 **FIFO 链路交付不出**这个形状的帧 —— 命令之前生成的状态帧在流里 -一律排在**那条命令的 ACK 之前**, 而 `_request_and_wait` 必读的一条就是 ACK -(`expect(RSP_ACK)` 会一路读到它), 于是它们**不可能**留到到位等待里。换句话说: -"不会被陈旧帧判成到位"这条性质在本结构下**由 ACK 排水顺带保证**, 那道闸平时**不会响**; -它是**不变量守卫** (重放/换取帧口/将来有人把水线取错时才响), 而不是现场可复现的故障形状。 -`test_stale_frames_*` 两条因此用**伪造**的陈旧帧 (桩里直接注入 seq 落后于水线的一帧) 来 -钉住这个不变量 —— 别把它读成"真链路上会这样"。 -""" -from __future__ import annotations - -import struct -import threading -import time -from typing import Optional - -import pytest - -from fake_serial import FakeTransport, _status -from litearm import Arm, _protocol as P -from litearm import state as ST -from litearm.cart import CartPlan, _wait_settled -from litearm.errors import (MotionTimeoutError, MotorFaultError, - NotConnectedError) - -#: 桩的初始 TCP (`fake_serial` 的 `self.pose`), `move_c` 的 `pose_start` 必须与它一致。 -TCP0 = (0.30, 0.0, 0.35, 0.0, 0.0, 0.0) - -#: 桩的 `CART_BUSY` 帧序 (见 `FakeTransport._stamp_status`): 收到 `0x4E` 后**第 2..7 帧** -#: 置位、**第 8 帧**落 0 ⇒ 一条"先见 1 再见 0"的到位等待恰好吃掉 **8** 帧状态。 -_BUSY_WINDOW_FRAMES = 8 - - -@pytest.fixture -def cart_arm(monkeypatch): - """可配置的桩工厂 —— 与 `test_cart_protocol.make_arm` 同款 (在 `connect()` 前装桩)。""" - import litearm.arm as arm_mod - - def _make(cls=FakeTransport, move_timeout: float = 15.0, **cfg): - def factory(port="fake", timeout=0.2, **_ignored): - t = cls(port=port, timeout=timeout) - for k, v in cfg.items(): - setattr(t, k, v) - return t - monkeypatch.setattr(arm_mod, "SerialTransport", factory) - from litearm import Arm as _Arm - return _Arm(port="fake", move_timeout=move_timeout).connect() - return _make - - -class _ScriptedStatus(FakeTransport): - """把**交付给 SDK 的**状态帧换成脚本形状的桩 —— 每条判据各配一份脚本。 - - * `q_script` —— 逐帧取用的关节角: 列表形式用完后停在最后一组, **可调用**形式 - (`f(i) -> q`) 则每帧现算 (给"永远不停"的形状用); 缺省 = 桩自己的 `q`; - * `dq_value` —— 每帧的 dq (缺省 0.0); - * `flags` —— 每帧的基础 flags (缺省 0; 置 1 = FAULT 位); - * `no_busy` —— True 时父类那股 `CART_BUSY` 帧序被压掉 (模拟"`bit10` 没上报"); - * `silent` —— True 时干脆不交帧 (给"只能等到超时"/"断连唤醒"两条用例)。 - - ⚠ 仍然走父类的 `_stamp_status`: `seq` 递增与 `CART_BUSY` 帧序与真桩完全一致 —— - 换了盖章口就等于把被测的取帧语义一起换掉了。 - """ - - def __init__(self, *a, **kw) -> None: - super().__init__(*a, **kw) - self.q_script: list = [] - self.dq_value = 0.0 - self.extra_flags = 0 - self.no_busy = False - self.silent = False - self.frames_served = 0 - - def _scripted_q(self): - i = self.frames_served - self.frames_served += 1 - if callable(self.q_script): - return list(self.q_script(i)) - if not self.q_script: - return list(self.q) - return list(self.q_script[min(i, len(self.q_script) - 1)]) - - def read_frame(self, timeout=None): - if self._resp: # ACK / 0x4E 照旧先走父类 - return super().read_frame(timeout) - if self.silent: - time.sleep(0.02) - return None - # ⚠⚠ **[2026-09-22] 脚本按「节拍」推进, 不再"读一次推进一格"**。 - # 从前 SDK 的读是**调用方驱动**的 ⇒ "谁读谁推进"成立; 现在 SDK 有**读线程** - # (`_Ack._reader_loop`), 它会把脚本在微秒内读完, 而被测的到位等待**一帧都看不到** - # ⇒ 判据全乱 (`started_busy=False` 这种"假到位"就是这么来的)。 - # 真机上一个状态帧**按时间产生、与谁在读无关** —— 桩必须建模这一点: - # 一个节拍 (`auto_status_period`) 才推进一格, 节拍内重复读返回 `None` - # (读线程据此退避, 也不空转)。 - now = time.monotonic() - if now - self._auto_status_last < self.auto_status_period: - return None - self._auto_status_last = now - if self.no_busy: - self.cart_busy_seq = None - q = self._scripted_q() - body = P.unpack_frame(_status(q, dq=[self.dq_value] * self.n, - flags=self.extra_flags, n=self.n))[1] - return self._stamp_status((P.RSP_STATUS, body)) - - -class _StaleFrames(FakeTransport): - """在 `0x4E` **之后**先交付几帧"命令之前生成"的状态帧 (伪造 `seq` 落后于水线)。 - - ⚠ **伪造是刻意的** (见模块 docstring 最后一段): 本结构下 ACK 排水已经把这形状挡在 - 到位等待之外, 所以只能注入。注入点选在 `_resp` **排空之后** —— 否则它们会排在 ACK - 前面被 `expect` 吃掉, 那就什么都没测到。绕过 `_stamp_status` 是必需的: 盖章口会给 - 每一帧换新的 `seq`, 一换就不再陈旧。 - - `stale_fault` 为真时注入的那几帧带 FAULT 位 (给"陈旧帧**也不判故障**"用)。 - """ - - def __init__(self, *a, **kw) -> None: - super().__init__(*a, **kw) - self.stale_count = 0 - self.stale_fault = False - self.stale_pending: list = [] - self._planned = False - - def _push(self, frame: bytes) -> None: - super()._push(frame) - # ⚠ 帧头第 0 字节是 SOF, 命令码在第 1 字节 (`_protocol.pack_frame` 的布局) - if len(frame) > 1 and frame[1] == P.RSP_CART_PLAN: - self._planned = True - - def read_frame(self, timeout=None): - if self.stale_pending and not self._resp: - return self.stale_pending.pop(0) # "缓冲里躺着的陈旧帧"先出来 - fr = super().read_frame(timeout) - if self._planned and not self._resp and not self.stale_pending: - # 规划帧刚被取走 -> 把"缓冲里躺着的陈旧帧"补上 (seq 落后于当前水线) - self._planned = False - k = self.status_seq - 5 - for i in range(self.stale_count): - self.stale_pending.append(self._stale_frame((k + i) & 0xFFFF)) - return fr - - def _stale_frame(self, seq: int): - flags = (1 if self.stale_fault else 0) - body = struct.pack(" None: - super().__init__(*a, **kw) - self.waiter_name: Optional[str] = None - self.greedy_name: Optional[str] = None - self.greedy_reads = 0 - - def _idle_status(self): - """一帧空闲状态 —— **必须**走 `_stamp_status`: `seq` 与 `CART_BUSY` 的盖章口只有 - 一个, 绕开它就等于把被测的取帧语义一起换掉了。""" - return self._stamp_status((P.RSP_STATUS, P.unpack_frame( - _status(self.q, mode=1, n=self.n))[1])) - - def read_frame(self, timeout=None): - cur = threading.current_thread().name - head = P.unpack_frame(self._resp[0])[0] if self._resp else None - if cur == self.greedy_name: - self.greedy_reads += 1 - if head is not None and head != P.RSP_STATUS: - return self._idle_status() # 别人的应答: 不吃, 改交一帧空闲状态 - return super().read_frame(timeout) - if cur == self.waiter_name and (head is None or head == P.RSP_STATUS): - return None # 抢走了: 等待者一帧状态都拿不到 - return super().read_frame(timeout) - - -def test_a_concurrent_status_poller_does_not_disturb_the_arrival_wait(cart_arm): - """**并发状态读者不再有受害面** —— 判据是"到位等待照常成功"。 - - ⚠ 本用例从前叫 `test_a_greedy_concurrent_reader_cannot_starve_the_arrival_wait`, - 靠 `_GreedyReader`(一个按**调用线程名**决定交不交帧的桩)模拟"另一个读者把状态帧 - 全抢走"。读线程一开,那个模型**整体作废**: - · 读 `transport` 的只有读线程一条,桩根本看不到第二个线程来读帧; - · 状态帧走**单槽 + `status_seq`**(不是队列),所有消费者看的是**同一份事实**, - "谁读到了"不再影响"谁看到了"。 - 故本用例改成测**它现在真正该保证的事**:一边死命轮询 `get_state(refresh=True)`, - 一边 `move_l` 到位 —— 两者都必须正常收场。 - """ - arm = cart_arm() - tr = arm._tr - out = {} - polls = {"n": 0} - - def run(): - try: - out["plan"] = arm.move_l(TCP0, speed=0.3) - except BaseException as e: # noqa: BLE001 - 结局就是被测的东西 - out["exc"] = e - - th = threading.Thread(target=run, name="cart-waiter", daemon=True) - th.start() - while th.is_alive(): - arm.get_state(refresh=True) # 并发读者:死命取状态 - polls["n"] += 1 - th.join(5.0) - - assert polls["n"] > 0, "并发读者一次都没跑 (用例自身失效)" - assert "exc" not in out, f"到位等待被并发读者搅了: {out['exc']!r}" - assert out["plan"].settled is True, "并发读者与等待者看到的必须是同一份事实" - - -# --------------------------------------------------------------------------- -# 11. `_wait_settled` 里两条**从来没被走到**的分支 (变异存活 = 无覆盖) -# --------------------------------------------------------------------------- - -def test_the_first_frame_only_establishes_the_watermark(cart_arm): - """⚠ `_wait_settled` 的"还没有水线"那一支: `seq0 is None` 时**第一帧只当起算点**。 - - `seq0` 由 `cart._seq_now(arm)` 取 (`arm._a.state.seq`, 见 `_seq_now` 的 docstring); - **还没见过任何状态帧**时它是 `None` —— 握手那一帧丢了就是这个形状。 - - ⚠ **本条之前没有任何用例走到这里**: `_request_and_wait` 总是拿得到水线 (连 `connect()` - 都见过状态帧)。所以把这一支整段拿掉 (`if seq0 is None:` → `if False:`) 时**加本条之前** - 的全量套件照绿 —— 因为它只在**真进过这一支**之后才会炸 (下一循环就会拿 `None` 去算 - `(st.seq - seq0) & 0xFFFF`)。 - """ - arm = cart_arm() - arm.move_timeout = 2.0 - arm._a.state = None # "还没见过任何状态帧" (见 `cart._seq_now`) - - plan = arm.move_l(TCP0, speed=0.3) # 不应抛 - - assert plan.ok, "用例自身失效: 规划没成功" - assert plan.started_busy is True, "`CART_BUSY` 那一支没被走到 —— 用例自身失效" - - -def test_the_same_frame_is_not_counted_twice(cart_arm): - """⚠ **假停稳方向**: 同一帧在两次采样里被数成两帧 ⇒ 静止窗少判一帧。 - - `_wait_settled` 的取帧是"自己读不到就采 `arm._require().state` 留下的成果" - (判据认的是**帧**, 不是"谁读的帧" —— 见 `_GreedyReader` 那条)。并发读者把帧读走之后, - `arm.state` 在两次采样里可以是**同一帧**; 不去重就等于每拍都往里塞一个采样点, - `arrive_frames` 拍"静止"可以全由**一帧**凑出来。 - - ⚠ 既有用例同样一次都没走到: 桩的每帧都换新的 `seq`。 - 形状: 取帧口 (`_read_status`) 恒回 `None` (帧被并发读者抢走), 而 `arm.state` **停在** - 一帧上 ⇒ 去重生效时窗口永远只有 1 帧 ⇒ 必须**超时**; 不去重则 3 拍就凑满窗 ⇒ 假停稳。 - """ - # ⚠ 冻结的**方式**换了:`_Ack.state` 现在归**读线程**所有(它一直在填), - # 所以"把 state 设成一帧然后不改"做不到 —— 必须让**桩不再产帧**(`silent`)。 - # ⚠ 也删掉了 `monkeypatch.setattr(arm, "_read_status", ...)`:那个方法已经不存在, - # 而它当年模拟的"帧被并发读者抢走"在本设计下**不可能发生**。 - arm = cart_arm(cls=_ScriptedStatus, silent=True) - arm.move_timeout = 0.3 - seq0 = 100 - body = P.unpack_frame(_status([0.0] * arm.n, dq=[0.0] * arm.n, - mode=1, seq=seq0 + 1))[1] - arm._a.state = ST.decode_state(body) # 水线之后、静止的一帧 (恒为同一帧) - - with pytest.raises(MotionTimeoutError): - _wait_settled(arm, "去重用例", seq0) diff --git a/tests/test_cli.py b/tests/test_cli.py deleted file mode 100644 index 716fec3..0000000 --- a/tests/test_cli.py +++ /dev/null @@ -1,73 +0,0 @@ -"""CLI (`litearm-python` / `python -m litearm`) —— 破坏性变更后必须仍可用。 - -`home()` 去掉 speed 参数后, CLI 的 home 分支若还传 `args.speed` 会直接 TypeError; -这类"改了一处忘了另一处"的死角只有真的把 CLI 跑一遍才会暴露。 -""" -from __future__ import annotations - -import pytest - -from litearm import arm as arm_mod - - -@pytest.fixture -def cli_arm(fake_transport_factory): - fake_transport_factory() - return None - - -def _run(argv): - return arm_mod.main(argv) - - -def test_cli_home_runs_without_speed(cli_arm, capsys): - """`home` 动作不得再依赖 --speed 参数。""" - assert _run(["--port", "fake", "home"]) == 0 - assert "home done" in capsys.readouterr().out - - -def test_cli_home_still_accepts_speed_flag_but_ignores_it(cli_arm): - """--speed 是 CLI 全局参数 (movej 也用); home 上误传不应崩。""" - assert _run(["--port", "fake", "home", "--speed", "0.5"]) == 0 - - -def test_cli_enable_disable_cycle(cli_arm, capsys): - assert _run(["--port", "fake", "enable"]) == 0 - assert "enabled" in capsys.readouterr().out - assert _run(["--port", "fake", "disable"]) == 0 - - -def test_cli_status_and_fw(cli_arm, capsys): - assert _run(["--port", "fake", "status"]) == 0 - assert _run(["--port", "fake", "fw"]) == 0 - assert "Litearm" in capsys.readouterr().out - - -# --------------------------------------------------------------------------- -# Task 8 (返回信封 `Msg`): CLI 的两条读分支 -# -# `status` 分支直接读 `st.mode_name/st.seq/st.flag_names/st.joints` —— `get_state` 一旦回 -# `Msg`, 那一行立刻 `AttributeError` (本文件在此前就会红); 而 `tcp` 分支**更静默**: -# 它从前直接 `print("tcp:", arm.get_tcp())`, 包了信封之后会**把 `Msg` 的 repr 打给用户** -# 而没有任何断言看得见 —— 所以下面那条是**新加**的 (此前零覆盖)。 -# --------------------------------------------------------------------------- - -def test_cli_status_prints_the_state_and_the_envelope(cli_arm, capsys): - assert _run(["--port", "fake", "status"]) == 0 - out = capsys.readouterr().out - assert "mode=" in out and "seq=" in out, "状态正文没打出来 (读 .value 之前就用了?)" - assert "hz=" in out, "信封里的 hz 没打出来 —— CLI 是唯一的人眼出口" - assert "J1:" in out, "逐关节那几行没打出来" - - -def test_cli_tcp_prints_the_value_not_the_msg_repr(cli_arm, capsys): - assert _run(["--port", "fake", "tcp"]) == 0 - out = capsys.readouterr().out - assert "Msg(" not in out, "把信封的 repr 打给用户了 —— 要的是那一帧的值" - assert out.startswith("tcp: (0.3"), f"没打出 TCP 值: {out!r}" - assert "hz=" in out - - -def test_cli_movej_requires_right_arity(cli_arm, capsys): - assert _run(["--port", "fake", "movej", "0.1", "0", "0", "0", "0", "0", "0"]) == 0 - assert "movej done" in capsys.readouterr().out diff --git a/tests/test_dfu.py b/tests/test_dfu.py deleted file mode 100644 index a85f0b7..0000000 --- a/tests/test_dfu.py +++ /dev/null @@ -1,322 +0,0 @@ -"""DFU `0x15` —— SDK 里**唯一**的终端态操作 (spec §6.1)。 - -固件契约 (逐条对着固件源码核过; 本文件每条判据的依据都写在注释里, 固件只读): - -* **受理**: `usb_cmd.c:543-555` 的 `case CMD_ENTER_DFU` —— 载荷非空 ⇒ - `ERR{0x15,0x01}`; 否则 `ctrl_request_enter_dfu()` 返回 0 ⇒ `ACK{0x15}`, 非 0 ⇒ - `ERR{0x15, r}`。 -* **门禁与登记**: `control_loop.c:1087-1099` —— `g_arm.enabled || enable_pending` - ⇒ `0x03`; ROM 向量表无效 ⇒ `0x02`; 否则 `dfu_pending = true` (**只登记**)。 -* ⚠ **`ACK{0x15}` 只表示"已登记"**: 不表示"会跳"、更不表示"已经跳"。登记可被**三个** - 点**静默撤销** (都 `dfu_pending = false; return;` 且**不回报** —— 而 ACK 是成功的): - `control_loop.c:1106` (并发 ENABLE: 同一个 USB 批里 `0x15` 紧接 `0x10` 即命中)、 - `:1142` (交棒前向量表**复读**失败) 与 `:1112` (1s 总超时兜底)。 - ⚠ 第三条 (`:1112`) **实际不可达**: 10ms/100ms/100ms 三道门控 (`:1118`/`:1131`/`:1137`) - 都在 `age ≤ 100ms` 处放行, 到点必然先在 `:1142`/`:1156` 落定, 走不到 1s 判据 - (`:1111` 要 `age > 300` 拍)。理由与算术同 `arm.py` 模块顶部 `DFU_REVOKED_MESSAGE` 那段。 -* **真跳转在 main 线程** (`Core/Src/main.c:189` 的 `ctrl_dfu_poll_main()`), 上界 - **100ms** —— 三道门控共用同一个 `age` (`control_loop.c:1110/1118/1131/1137`), - **不是** 10+100+100=210ms。 - -⇒ 所以 `enter_dfu()` 必须**两段式**: ACK 之后**等设备真的消失**才置终端态; 超时未消失 -就抛"登记被撤销/未执行"并**让 `Arm` 保持可用** (静默撤销路径的**唯一**出口)。 - -"设备已消失"的判据只有一条: **读路径抛 `TransportError`** —— pyserial 在设备被摘掉时 -`select` 报就绪而 `read()` 返回空 ⇒ `serialposix.py:591-597` 抛 `SerialException` -(注释原话: Linux 上断开的设备就是这样), 被 `transport._read_chunk` 包成 -`TransportError` (`transport.py:318-336` —— 函数从 `:318` 起, `raise` 在 `:336`)。 -⚠ 两条**不可用**的判据 (spec §8 V1): `is_open` 拔线后仍为真 (它是 pyserial **自己维护的 -实例属性**, 开置 True / 关置 False, 而拔线不经过 `close()`); "读到 0 字节"是**读超时**的正常 -返回 (`serialposix.py:573-574` → `b''`) —— 拿它当判据会把**真跳转**读成"什么都没发生", -结论正好反了。 -""" -from __future__ import annotations - -import pytest - -import litearm as pa -from litearm import _protocol as P - - -def _sent(tr) -> set: - return {c for c, _p in tr.tx_log} - - -def _dfu_payloads(tr) -> list: - """发出去的 `0x15` 的载荷 (逐条) —— "我们恒发空载荷"这条由它钉住。 - - ⚠ 取的是**桩 transport 对象**, 不是 `arm._tr`: 真跳转那条路径上 `enter_dfu()` - 会关链路 (`arm._tr` 置 `None`), 之后再想读 `tx_log` 就没得读了 —— 测试必须在调用 - 之前抓住 transport 引用。 - """ - return [p for c, p in tr.tx_log if c == P.CMD_ENTER_DFU] - - -# ---------------------------------------------------------------- 预检 -def test_enabled_precheck_refuses_readably_and_sends_nothing(offline_arm): - """使能中 ⇒ **不发帧**、给可读错 (spec §6.1 的门禁 1)。 - - ⚠ 这**不是**洁癖: 跳转停 TIM3 ⇒ 不再发 MIT 帧 ⇒ 电机侧 `RID_TIMEOUT`(100ms) - 松开 ⇒ 使能中跳会让臂**下垂** (`control_loop.c:1088-1090` 的原注释)。 - ⚠ 本地预检的口径**只有** `st.enabled` (状态帧 bit9) —— 固件那道门禁是 - `ctrl_is_armed() = enabled || enable_pending` (定义在 `control_loop.c:1334-1336`; - `:1091` 是 `ctrl_request_enter_dfu` 里把同一谓词**内联**写的那一行), 所以 - **使能在途**时预检会放行、由固件回 `ERR{0x15,0x03}` (那一条的判据见下面 - `test_err_0x03_*`)。 - """ - arm = offline_arm - arm.enable() - tr = arm._tr - before = len(tr.tx_log) - - with pytest.raises(pa.InvalidCommandError) as ei: - arm.enter_dfu() - - assert "disable()" in str(ei.value), f"错误消息没给出路: {ei.value}" - assert len(tr.tx_log) == before, "预检拒了却还是把帧发出去了" - assert P.CMD_ENTER_DFU not in _sent(tr) - - -def test_state_unreadable_does_not_block_the_command(offline_arm): - """读不到状态帧时**不拦** —— 本地预检只为可读性, 门禁的权威在固件。 - - 理由: 固件对 `enabled || enable_pending` 一律回 `ERR{0x15,0x03}`, 所以"没确认 - 失能就发"**不会**让使能中的臂被跳掉; 反过来, 拿"读不到状态"当拒绝理由会把一次 - 合法升级卡死在一个与它无关的故障上。 - """ - arm = offline_arm - arm._tr.auto_status = False # 桩不再补空闲状态帧 ⇒ 读不到状态 - arm._tr._resp.clear() - tr = arm._tr - - arm.enter_dfu() # 桩默认"真跳转" ⇒ 正常返回 - - assert _dfu_payloads(tr) == [b""], "预检取不到状态时 0x15 没发出去" - - -# ---------------------------------------------------------------- 静默撤销 -def test_silent_revocation_times_out_and_leaves_the_arm_usable(offline_arm): - """桩只回 ACK、设备**不消失** ⇒ 抛"登记被撤销/未执行", 且 `Arm` 仍可用。 - - 这就是那三个静默撤销点 (`control_loop.c:1106` / `:1142` / `:1112`, 最后一条不可达) - 的**唯一出口**: - ACK 是成功的、而设备还在 CDC 上, 缺了这条出口就是"ACK 成功了却什么都没发生"。 - "仍可用"必须**行为化**验证 (读一帧 + 写一条), 因为终态的对象**所有走到取帧/写帧 - 收口的**入口都抛 `ArmIsInDfuError` (⚠ 射程的准话见 `_reject_if_in_dfu`) —— - 只看"没抛异常"证明不了它没进终态。 - """ - arm = offline_arm - arm._tr.dfu_vanishes = False # 登记成功但设备不跳 (静默撤销那一支) - tr = arm._tr - - with pytest.raises(pa.LiteArmError) as ei: - arm.enter_dfu() - - assert "撤销" in str(ei.value) or "未执行" in str(ei.value), ( - f"超时未消失的归因不对 (要指明'登记被撤销/未执行'): {ei.value}") - assert _dfu_payloads(tr) == [b""], "0x15 没发出去 —— 那测的不是这条路径" - - st = arm.get_state(refresh=True).value # 读路径仍可用 (且没被置成终态) - assert st is not None - arm.enable() # 写路径仍可用 - assert P.CMD_ENABLE in _sent(tr) - - -# ---------------------------------------------------------------- 真消失 ⇒ 终态 -def test_a_real_jump_sets_the_terminal_state(offline_arm): - """桩在 ACK 之后让读路径抛 `TransportError` (= 真跳转) ⇒ 置**终端态**。 - - 终态的两条性质都钉在这里: - · 关 transport (`Arm._tr` 置 `None`, 与 `close()` 同一套收尾); - · 此后**所有走到取帧/写帧收口的**入口都抛 `ArmIsInDfuError` —— 而不是 - `NotConnectedError` - (后者会被读成"一次可以重连恢复的掉线")、也不是 `MotionTimeoutError` - ("固件不理我")。 - ⚠ `close()` **必须仍然可用**: teardown 在任何状态下都不能抛 (否则 `with Arm(...)` - 的退出路径会把一次成功升级报成异常)。 - """ - arm = offline_arm - - assert arm.enter_dfu() is None # 桩默认: ACK 后设备消失 ⇒ 正常返回 - - assert arm._tr is None, "终端态必须把 transport 关掉 (与 close() 同一套收尾)" - assert isinstance(pa.ArmIsInDfuError("x"), pa.LiteArmError) - assert not issubclass(pa.ArmIsInDfuError, pa.NotConnectedError), ( - "终态刻意**不**继承 NotConnectedError —— 它不是一次可重连恢复的掉线") - - entries = { - "get_state": lambda: arm.get_state(), - "get_state(refresh)": lambda: arm.get_state(refresh=True), - "enable": lambda: arm.enable(), - "disable": lambda: arm.disable(), - "movej": lambda: arm.movej([0.0] * 7), - # ⚠ 这三条是**带本地 arity/idx 预检**的入口: 它们把 `self.n` 检查排在 `_cmd()` - # 之前, 而终态下 `self.n` 已被 `close()` 清成 0 ⇒ 少了各自最前那句守卫就会 - # 抛 `InvalidCommandError("q 需 N 个")` (N=0)、把人引向一个**不存在**的 arity - # bug, 并让文档给的"捕获 `ArmIsInDfuError` → 新建 `Arm`"迁移姿势漏掉它们。 - # 放进本表 = 与其余入口**同判据** (见 `_reject_if_in_dfu` 的 docstring)。 - "move_js": lambda: arm.move_js([0.0] * 7), - "send_mit": lambda: arm.send_mit(0, 0.0, 0.0, 50.0, 2.0, 0.0), - "send_mit_all": lambda: arm.send_mit_all([0.0] * 7, [0.0] * 7, [50.0] * 7, - [2.0] * 7, [0.0] * 7), - "get_tcp": lambda: arm.get_tcp(), - "save_params": lambda: arm.save_params(), - "params.get_joint_param": lambda: arm.params.get_joint_param(0), - "log.start": lambda: arm.log.start(4), - "diag.kin_bench": lambda: arm.diag.kin_bench(), - "poll_cart": lambda: arm.poll_cart(), - "zero_g_start": lambda: arm.zero_g_start(), - "enter_dfu (again)": lambda: arm.enter_dfu(), - "connect": lambda: arm.connect(), - "reconnect": lambda: arm.reconnect(), - # 私有写口也要拦 —— 终态下"不会再有任何帧发出去"必须是**结构性**的事实 - # (`_raw_write` 是唯一写口, 保活线程当年就是绕过 `_write_cmd` 走它的), - # 而不是靠逐入口枚举 (`_require()` 之外还有它这条旁路)。 - "_raw_write (私有写口)": lambda: arm._raw_write(P.CMD_GET_FIRMWARE), - } - wrong = [] - for name, fn in entries.items(): - try: - fn() - wrong.append(f"{name}: 没报错") - except pa.ArmIsInDfuError: - pass - except Exception as e: # noqa: BLE001 - wrong.append(f"{name}: {type(e).__name__} (应为 ArmIsInDfuError)") - assert not wrong, "终端态下这些入口的行为不对: " + "; ".join(wrong) - - arm.close() # teardown 永远可用 (且不抛) - - -def test_a_held_ack_reference_also_reports_the_terminal_state(offline_arm): - """直接持 `_Ack` 引用那条路 (不经 `_require()`) 也必须报终态。 - - 终态下 `_tr`/`_a` 都已置 `None`, 所以等待口 (`_Ack._wait`) 顶部那两句守卫 - **必须把终态排在"链路已关"之前** —— 否则报出来的是 `NotConnectedError` - ("一次可重连恢复的掉线"), 把"我们主动把设备交出去了"说成"没连上"。 - 判据与 `tests/test_frame_ownership.py` 里 - `test_a_held_ack_reference_after_close_reports_not_connected` **同形** - (那条钉的是 close 之后的归因方向, 这条钉的是终态优先于它)。 - """ - arm = offline_arm - a = arm._a # 先抓住引用 —— enter_dfu() 会把 arm._a 一并置 None - arm.enter_dfu() - - with pytest.raises(pa.ArmIsInDfuError): - a.expect(P.RSP_FIRMWARE, 0.2, "test", echo_cmd=P.CMD_GET_FIRMWARE) - with pytest.raises(pa.ArmIsInDfuError): - a.expect(P.RSP_ACK, 0.2, "test", echo_cmd=P.CMD_ENABLE) - - -def test_the_vanish_window_does_not_consume_frames(offline_arm): - """⚠ 消失观察窗口**一帧都不碰链路** —— 窗口里到的帧原样留在自己队列里。 - - ⚠ 本用例改过三次名,每次都在追同一件事:**别人的帧不许被这个窗口吃掉**。 - · `..._counts_the_frames_it_drops`(断言 `foreign_frames == 1`)—— 描述的是缺陷本身; - · `..._preserves_the_frames_it_does_not_use`(断言帧进了暂存盒)—— 暂存盒已随读路径 - 重构删除; - · 现在 —— `Arm._wait_until_link_lost` **根本不读链路**了:它只等 - `_Ack._reader_error` 被置(读线程发现设备消失时写的那一格)。于是"窗口吃掉别人的帧" - 这条**路径不存在**:帧由读线程投进各自的队列,谁也拿不走。 - - ⚠ 判据钉的是**更强**的那件事:那条 ACK **原样躺在它自己的队列里**(不是"被存起来了", - 而是"根本没被碰过"),且 `dropped` 没涨。 - """ - arm = offline_arm - arm._tr.dfu_vanishes = False - # 桩: 登记 ACK 之后、设备离开之前还会投递的帧 (这里塞一条别人的 ACK) - arm._tr.dfu_post_ack_frames = [(P.RSP_ACK, bytes([0x11]))] - - with pytest.raises(pa.LiteArmError): - arm.enter_dfu() - - # 等读线程把它投递掉(消失窗口本身不驱动读,读线程一直在读) - import time as _t - for _ in range(200): - if arm._a._queues.get((P.RSP_ACK, 0x11)): - break - _t.sleep(0.002) - - assert arm._a._queues.get((P.RSP_ACK, 0x11)) == [(P.RSP_ACK, bytes([0x11]), arm._a._queues[(P.RSP_ACK, 0x11)][0][2])], ( - f"窗口里那条 ACK 没原样留在自己的队列里: {arm._a._queues}") - assert arm._a.dropped == 0, "它不该被计成丢弃(没人丢它)" - - -# ---------------------------------------------------------------- 固件三种回码 -def test_enter_dfu_always_sends_an_empty_payload(offline_arm): - """我们恒发**空载荷** ⇒ 固件的 `{0x15,0x01}` 那一档够不到 (`usb_cmd.c:547`)。 - - ⚠ 这句话的**依据**是紧邻的 `test_the_stub_models_the_length_gate_verbatim` —— - 它拿**裸帧**证明桩真的会对非空载荷回 `ERR{0x15,0x01}`; 少了那一条, 这里的 - "够不到"就只是一句没有观测面的断言 (桩把那一档删掉, 本用例照样绿)。 - """ - arm = offline_arm - tr = arm._tr - arm.enter_dfu() - assert _dfu_payloads(tr) == [b""] - - -def test_the_stub_models_the_length_gate_verbatim(offline_arm): - """⚠ **桩保真度检查** (钉的是 `tests/fake_serial.py` 的 `0x15` 分支, 不是 SDK 行为)。 - - 固件 `usb_cmd.c:543-555` 的 `case CMD_ENTER_DFU` 是**长度优先**: 载荷非空 ⇒ - `ERR{0x15,0x01}`, 连门禁都不看。桩必须照抄这一档 —— 它是 - `test_enter_dfu_always_sends_an_empty_payload` 那句"我们恒发空载荷 ⇒ 那一档够不到" - 的**唯一**依据。 - - 判据只能走**裸帧**: SDK 入口 `enter_dfu()` **恒发空载荷** (上一条用例), 所以经 SDK - 永远够不到这一档 —— 实测把桩里 `if payload:` 改成 `if False:` (等价于删掉这一档), - **全量 531 passed 全绿**, 没有任何用例报错。 - """ - tr = offline_arm._tr - tr.write_frame(P.CMD_ENTER_DFU, b"\x00") # 非空载荷 ⇒ 固件那一档 - got = tr.read_frame(0.2) - assert got is not None, "桩对非空载荷一个字节都没回" - assert (got[0], bytes(got[1])) == (P.RSP_ERR, bytes([P.CMD_ENTER_DFU, 0x01])), ( - f"桩没有照固件 `usb_cmd.c:547` 回 ERR{{0x15,0x01}} (实测回的是 {got!r}) —— " - f"少这一档, 「SDK 恒发空载荷」后面的那句『那一档够不到』就没有依据了" - ) - - -def test_err_0x02_is_surfaced_verbatim(offline_arm): - """`ERR{0x15,0x02}` (ROM 向量表无效) ⇒ **照实透出** —— 它是**硬件故障**, 不是用法 - 错误, 更不是"登记被撤销" (`control_loop.c:1092-1095`: 当场拒, 不等安全点)。""" - arm = offline_arm - arm._tr.dfu_rom_table_invalid = True - - with pytest.raises(pa.CommandRejectedError) as ei: - arm.enter_dfu() - - assert (ei.value.cmd, ei.value.code) == (P.CMD_ENTER_DFU, 0x02) - assert "向量表" in str(ei.value), f"没照实透出固件的归因: {ei.value}" - assert "撤销" not in str(ei.value), ( - "把'向量表坏了'吞成了'登记被撤销' —— 两者一个是硬件故障、一个是时序竞态") - assert arm.get_state(refresh=True).value is not None, ( - "请求根本没被受理 ⇒ 不该置终态") - - -def test_err_0x03_from_enable_pending_is_surfaced_and_is_not_a_revocation(offline_arm): - """`ERR{0x15,0x03}` —— **预检够不到的那一半**: `enable_pending` 在途。 - - 桩只置 `dfu_armed_pending` (固件侧那个"已武装但 `enabled` 还没落地"的窗口, - `control_loop.c:1091` **内联**的那条 `|| enable_pending` —— 与 `:1334-1336` 的 - `ctrl_is_armed()` 同义), 于是 `st.enabled` 仍为 False ⇒ - 预检**放行**、由固件回 `0x03`。 - - **处置 (写死)**: 它是**用法错误**的照实透出 —— `CommandRejectedError` 带 - `.code == 0x03`, 文本取 `errors.ERR_TEXT[(0x15,0x03)]` (已写明"使能中, 或使能在途; - 跳转会停 TIM3...下垂"); **不算**"登记被撤销" —— 那一刻固件**还没登记** - (`ctrl_request_enter_dfu` 在 `dfu_pending = true` 之前就返回了), 所以既没有 - "ACK 成功了却什么都没发生"这回事, 也**不该**置终态。 - """ - arm = offline_arm - arm._tr.dfu_armed_pending = True # 固件侧 enable_pending 在途 (enabled 仍 False) - - with pytest.raises(pa.CommandRejectedError) as ei: - arm.enter_dfu() - - assert (ei.value.cmd, ei.value.code) == (P.CMD_ENTER_DFU, 0x03) - assert "撤销" not in str(ei.value), ( - "把'使能在途, 请求未被受理'读成了'登记被撤销' —— 后者意味着 ACK 过了") - assert arm.get_state(refresh=True).value is not None, "这条拒绝不该置终态" - arm.enable() # 照旧可用 (用户该做的就是等使能落地/失能后重来) diff --git a/tests/test_diagnostics.py b/tests/test_diagnostics.py deleted file mode 100644 index c9f3896..0000000 --- a/tests/test_diagnostics.py +++ /dev/null @@ -1,122 +0,0 @@ -"""KIN_BENCH 运动学开销自测 (固件 0x49 -> RSP_KIN_BENCH 0x4A) —— 此前 SDK 无入口。 - -固件侧 (`kin_runner.c` 的 `kin_bench_run`, `:335-564`; LINK 行在 `:514`): 后台 DWT-cycle -测 FK/JAC/IK/S 曲线/重力/RNEA/M/控制律 -单拍开销, 最终文本经 `RSP_KIN_BENCH(0x4A)` 可靠通道回。**最后一行 LINK 是拿到 -`usb_cmd_crc_err_count` (CRC 坏帧) / `usb_cmd_reply_dropped` (应答 FIFO 丢) / -`fdcanx_tx_fail_count` (CAN TX 失败) 等诊断计数的唯一通道** —— 这些计数在固件里 -原本全部静默 (L3/M1 fix)。 - -文本格式 (逐行): - FK / JAC / IK / LOOP1 / SC / G / RNEA / M / LAW - LINK crc=.. ovf=.. rfd=.. txf=.. tfe=.. tfd=.. tfc=.. tfs=.. tfm=.. loop_k=.. ovr=.. flt=/st=<0|1> -""" -from __future__ import annotations - -import pytest - -from litearm import _protocol as P -from litearm.errors import TransportError, UnsupportedByFirmwareError - - -def test_kin_bench_returns_raw_text(offline_arm): - r = offline_arm.diag.kin_bench().value - assert "FK200" in r.raw - assert r.raw.splitlines()[0] == "FK200 108 240 " - assert str(r) == r.raw - - -def test_kin_bench_parses_per_block_timings(offline_arm): - """⚠ 固件把块名与计数**相连** (`FK200 108 240 `), `LOOP1` 行是 `LOOP14000 ` —— - 名字里本身带数字, 故按固件已知块名集合切分, 不能用通用正则。""" - r = offline_arm.diag.kin_bench().value - assert r.timings["FK"] == (200, 108, 240) - assert r.timings["RNEA"] == (200, 800, 1500) - assert r.timings["IK"] == (100, 2600, 5200) - assert r.timings["LOOP1"] == (4000,) - - -def test_kin_bench_parses_link_diagnostics(offline_arm): - """链路诊断是 KIN_BENCH 最实用的产出 —— 必须逐个解析出来。""" - link = offline_arm.diag.kin_bench().value.link - assert link["crc"] == 3 # CRC 坏帧累计 - assert link["rfd"] == 1 # 应答 FIFO 队满丢弃 - assert link["txf"] == 7 # CAN TX 失败 - assert link["tfc"] == 3 # TX 失败分类桶 c - assert link["loop_k"] == 2 # 控制拍峰值 (千 cycle) - assert link["ovr"] == 4 # 超预算拍数 - assert link["fault_tick"] == 12345 - assert link["fault_cause"] == 6 - assert link["store_from_flash"] is True - - -def test_kin_bench_parses_link_keys_that_contain_digits(offline_arm): - """⚠ `rxl0` / `rxl1` **名字里带数字** —— 解析器必须吃得下。 - - 它们不是可有可无的边角: 固件 `kin_runner.c:520-522` 明写 - "`[N-12 fix]` RX FIFO 溢出 (原为零遥测): **溢出 = 静默丢反馈 = 可能整臂 EMERGENCY**"。 - 即**最该看见的那两个计数器**。 - - 而 `_KV_RE` 从前是 `[a-z_]+` —— 匹配不到带数字的键, 于是那两个**静默丢失**, - 三个出口恒返回 0, 与"没丢过"长得一模一样。 - - ⚠ 这是**同一个文件里第二次**栽在"名字里带数字"上: `_TIMING_RE` 段落早就写过 - `LOOP1` 行是 `LOOP14000`, "名字里本身带数字…不能用通用正则"。 - """ - link = offline_arm.diag.kin_bench().value.link - assert "rxl0" in link, "`rxl0` 没解析出来 —— 字符类又写窄了" - assert "rxl1" in link, "`rxl1` 没解析出来 —— 字符类又写窄了" - assert link["rxl0"] == 13 - assert link["rxl1"] == 17 - - r = offline_arm.diag.kin_bench().value - assert r.rx_fifo_lost_motor == 13 - assert r.rx_fifo_lost_bridge == 17 - assert r.gsusb_ring_drops == 19 - - -def test_kin_bench_reads_the_second_link_frame(offline_arm): - """⚠ 固件的回执是**连续两帧** (第 1 帧各项耗时 / 第 2 帧 LINK 诊断行)。 - - 只收第 1 帧会**静默**丢掉全部链路计数 —— 那五个便捷出口是 `link.get(k, 0)`, - 拿不到就是 **0**, 与"没有出错"分不开 (真机上实测踩过: 回执里没有 LINK 行, - `link == {}`, 五个出口全报 0)。 - - 桩已按真机拆帧。**本用例的判别力正来自这个桩**: 若桩仍把全文塞一帧, - 它会在"只收一帧"的实现上照样通过。 - """ - r = offline_arm.diag.kin_bench().value - assert r.link, "第 2 帧 (LINK 行) 没被收下 —— 五个链路计数会静默全 0" - assert r.crc_errors == 3 - assert r.reply_dropped == 1 - assert r.can_tx_fail == 7 - assert r.loop_max_kcycle == 2 - assert r.loop_overruns == 4 - - -def test_kin_bench_tolerates_old_firmware_with_only_one_frame(offline_arm): - """旧固件只发一帧 (无 LINK 行): 第 2 帧等超时**不是错误**。 - - 兼容分支要**静默降级** —— 前一半 (各项耗时) 仍必须可用, 不能因此抛异常。 - """ - arm = offline_arm - arm._tr.kin_bench_one_frame = True - r = arm.diag.kin_bench().value - assert r.timings["FK"] == (200, 108, 240) - assert r.link == {} # 拿不到就是拿不到 —— 但降级不许抛 - assert r.crc_errors == 0 # 静默 0 是这一刻的诚实结果, 不是"没出错" - - -def test_kin_bench_empty_reply_raises(offline_arm): - """空文本 = 非正常回执, 不能当成"全 0"静默返回。""" - arm = offline_arm - arm._tr.kin_bench_text = "" - with pytest.raises(TransportError): - arm.diag.kin_bench() - - -def test_kin_bench_unsupported_on_old_firmware(offline_arm): - arm = offline_arm - arm._tr.unknown_cmds.add(P.CMD_KIN_BENCH) - with pytest.raises(UnsupportedByFirmwareError): - arm.diag.kin_bench() diff --git a/tests/test_doc_examples.py b/tests/test_doc_examples.py deleted file mode 100644 index 284fe53..0000000 --- a/tests/test_doc_examples.py +++ /dev/null @@ -1,358 +0,0 @@ -"""文档里的代码必须是对的 —— 逐块校验 `*.md` 的 python 代码块。 - -文档示例写错是**静默**故障: 不跑就发现不了。本用例把 8 份文档里所有 ```python 块 -抽出来, 按**内容**分三类处理 (不按块序号 —— 序号会随文档编辑错位): - -* **可执行示例** —— 接到离线桩 `Arm` 上真跑一遍, 所以不会碰真机。 - 块里出现任何没交代的名字 (例如留了 `p1` / `tcp` / `via_pose` 这种占位符) 都会 - `NameError` 而失败。 -* **签名清单** —— `foo(a, b=1) -> T` 这种不执行, 改为**逐条比对 `inspect.signature`**: - 参数名、位置顺序、关键字专用性 (`*`)、默认值全都要对得上。 - 只读属性名单 (`n` / `q_tol` / …) 也走这条, 逐个确认成员真的存在。 -* **说明性片段** —— 会 fork、会阻塞、或本身就是类型定义示意, 见 `ILLUSTRATIVE`, - 只做语法检查。 - -**新增示例若跑不起来, 本用例直接失败。** 别把只是写错的块塞进 `ILLUSTRATIVE` 蒙混过去 —— -那条正则只匹配"本来就不是可执行代码"的块。 -""" -from __future__ import annotations - -import ast -import inspect -import os -import re - -import pytest - -_HERE = os.path.dirname(os.path.abspath(__file__)) -_ROOT = os.path.dirname(_HERE) - -from litearm.arm import Arm # noqa: E402 - conftest 已在更早处设好 sys.path - -#: ⚠ `conftest.py` 那条 autouse 的读线程哨兵会把 `Arm.__init__` 换成 -#: `(self, *args, **kwargs)` 的包装, 于是**测试期里 `inspect.signature(Arm.__init__)` -#: 再也读不到真实签名**。这里在补丁生效前先把原始函数抓住。 -_ARM_INIT_PRISTINE = Arm.__init__ - -DOCS = [ - "README.md", - "README.zh-CN.md", - "TROUBLESHOOTING.md", - "TROUBLESHOOTING.zh-CN.md", - "docs/DEVELOPER_GUIDE.md", - "docs/DEVELOPER_GUIDE.zh-CN.md", - "examples/README.md", - "examples/README.zh-CN.md", -] - -#: 只做语法检查的块 —— 按内容判, 不按序号。 -#: ⚠ 别加 `re.X` / 行尾 `#` 注释: `re.X` 下第一个 `#` 会把**后面所有分支**注释掉。 -ILLUSTRATIVE = re.compile( - r"\bmultiprocessing\b" # fork 示例, 会真的开子进程 - r"|\binput\s*\(" # 交互示例, 会阻塞 - r"|^\s*@\w+", # 类型定义示意 (Msg 的 dataclass) - re.M, -) - -#: `foo(...)` / `group.foo(...)`, 允许尾随的 `-> 返回类型` -_SIG = re.compile(r"^(?:([A-Za-z_]\w*)\.)?([A-Za-z_]\w*)\((.*)\)\s*(?:->\s*.+)?$", re.S) - -#: 裸属性引用 —— `r.total_bytes` / `n` -_ATTR = re.compile(r"^(?:([A-Za-z_]\w*)\.)?([A-Za-z_]\w*)$") - -#: 一个"像参数"的形参: 裸标识符 / `*` 或 `/` 分隔符 / `**name` / `name=任何字面量` -_PARAM_OK = re.compile(r"^(\*$|/$|\*{0,2}[A-Za-z_]\w*(=.*)?)$", re.S) - -_EVAL_NS: dict = {} - - -def _blocks(): - for rel in DOCS: - path = os.path.join(_ROOT, rel) - if not os.path.exists(path): - continue - text = open(path, encoding="utf-8").read() - for i, body in enumerate(re.findall(r"```python\n(.*?)```", text, re.S), 1): - yield rel, i, body - - -ALL_BLOCKS = list(_blocks()) -IDS = [f"{r}#{i}" for r, i, _ in ALL_BLOCKS] - - -# ---------------------------------------------------------------- 文本切分 - -def _strip_comment(line: str) -> str: - """去掉行尾注释 —— 文档里的 `# 需 10 个值` 之类不算代码。""" - out, quote = [], None - for ch in line: - if quote: - out.append(ch) - if ch == quote: - quote = None - continue - if ch in "\"'": - quote = ch - out.append(ch) - continue - if ch == "#": - break - out.append(ch) - return "".join(out).rstrip() - - -def _entries(body: str): - """把块切成逻辑条目: 括号未闭合的续行并进上一条。""" - buf, depth = "", 0 - for raw in body.splitlines(): - line = _strip_comment(raw) - if not line and not buf: - continue - buf = f"{buf} {line}".strip() if buf else line - depth += line.count("(") - line.count(")") - if depth <= 0: - yield buf - buf, depth = "", 0 - if buf: - yield buf - - -def _split_params(text: str): - """按顶层逗号切参数, 保住嵌套结构。""" - parts, buf, depth = [], "", 0 - for ch in text: - if ch in "([{": - depth += 1 - elif ch in ")]}": - depth -= 1 - if ch == "," and depth == 0: - parts.append(buf.strip()) - buf = "" - else: - buf += ch - if buf.strip(): - parts.append(buf.strip()) - return [p for p in parts if p] - - -# ---------------------------------------------------------------- 名字解析 - -def _sub_objects(): - from litearm.diagnostics import Diagnostics - from litearm.log import ArmLog, LogReader - from litearm.model import ModelParams - from litearm.params import JointParams - - return (JointParams, ModelParams, ArmLog, LogReader, Diagnostics) - - -def _group_of(selector: str | None): - """`params.` / `model.` / `log.` / `diag.` / `r.` / `payload.` 前缀 → 对应的对象。 - - 大多数是 `Arm` 的子对象类; `payload` 是**模块**(`litearm.payload` 里的函数拿 `arm` - 当第一个参数, 不是 `Arm` 的方法)—— 但签名核对要的东西一样: 对象上有这个成员、 - 签名对得上。它能进来, 文档里的 `payload.identify(arm, baseline, …)` 才有人管。 - """ - from litearm import payload as payload_mod - from litearm.diagnostics import Diagnostics - from litearm.log import ArmLog, LogReader - from litearm.model import ModelParams - from litearm.params import JointParams - - return { - "params": JointParams, "model": ModelParams, - "log": ArmLog, "diag": Diagnostics, - "r": LogReader, "reader": LogReader, - "payload": payload_mod, - }.get(selector or "") - - -def _has_member(cls, name: str) -> bool: - """类上有这个成员吗 —— **含 `__init__` 里赋的实例属性** (`total_bytes` 就是这种)。 - - `hasattr(cls, ...)` 看不见实例属性, 所以要再扫一遍类源码里的 `self.`。 - """ - if hasattr(cls, name): - return True - try: - src = inspect.getsource(cls) - except (OSError, TypeError): # pragma: no cover - return False - return re.search(rf"self\.{re.escape(name)}\s*[:=]", src) is not None - - -def _owner_of(name: str, selector: str | None): - """这个成员属于哪个类。带前缀就认前缀; 裸名字先找 `Arm`, 再在各子对象里唯一命中。""" - if selector: - return _group_of(selector) or Arm - if _has_member(Arm, name): - return Arm - hits = [c for c in _sub_objects() if _has_member(c, name)] - return hits[0] if len(hits) == 1 else None - - -def _verify_member(name: str, selector: str | None, rel: str, idx: int): - owner = _owner_of(name, selector) - assert owner is not None and _has_member(owner, name), ( - f"{rel}#{idx}: 文档写了 {name},但真实 API 里没有") - - -def _resolve_call(name: str, selector: str | None, rel: str, idx: int): - if name == "Arm": - return _ARM_INIT_PRISTINE - _verify_member(name, selector, rel, idx) - owner = _owner_of(name, selector) - return getattr(owner, name) - - -# ---------------------------------------------------------------- 签名核对 - -def _check_signature_entry(entry: str, rel: str, idx: int) -> bool: - """核对一条签名/属性条目。返回 True 表示这一条确实是签名条目。""" - # 只读属性名单可以一行写几个: `n` / `q_tol` / `dq_tol` … 用 ` / ` 分隔 - if "/" in entry and not _SIG.match(entry): - for piece in entry.split("/"): - piece = piece.strip() - m = _ATTR.match(piece) - assert m, f"{rel}#{idx}: 认不出的条目 {entry!r}" - _verify_member(m.group(2), m.group(1), rel, idx) - return True - - attr = _ATTR.match(entry) - if attr: - _verify_member(attr.group(2), attr.group(1), rel, idx) - return True - - m = _SIG.match(entry) - if not m: - return False - selector, name, raw_params = m.group(1), m.group(2), m.group(3) - real = inspect.signature(_resolve_call(name, selector, rel, idx)) - real_params = [p for p in real.parameters.values() if p.name != "self"] - real_by_name = {p.name: p for p in real_params} - - kw_only_from, doc_names = None, [] - for pos, item in enumerate(_split_params(raw_params)): - if item == "*": - kw_only_from = len(doc_names) - continue - pname = item.split("=", 1)[0].strip().lstrip("*") - doc_names.append(pname) - - assert pname in real_by_name, ( - f"{rel}#{idx}: 文档写了 {name}({pname}=…),但真实签名没有这个参数" - f"(真实参数:{list(real_by_name)})") - - real_p = real_by_name[pname] - if kw_only_from is not None and pos >= kw_only_from: - assert real_p.kind is inspect.Parameter.KEYWORD_ONLY, ( - f"{rel}#{idx}: 文档把 {pname} 写成关键字专用(`*` 之后)," - f"但真实签名里它是 {real_p.kind.name}") - elif real_p.kind is inspect.Parameter.KEYWORD_ONLY: - # 反方向: 真实是关键字专用, 文档却没写 `*` ⇒ 读者会以为能按位置传 - assert item.startswith("*"), ( - f"{rel}#{idx}: {name}() 的 {pname!r} 是**关键字专用**," - f"文档的签名清单漏了 `*`,读者会以为能按位置传") - - if "=" in item: - doc_default = item.split("=", 1)[1].strip() - try: - expected = eval(doc_default, dict(_EVAL_NS)) # noqa: S307 - 文档字面量 - except Exception: # noqa: BLE001 - 求不出来就只查名字 - continue - assert real_p.default == expected, ( - f"{rel}#{idx}: {name}(… {pname}={doc_default}) 文档写的默认值是 " - f"{expected!r},真实是 {real_p.default!r}") - - for p in real_params: - if p.name in doc_names: - continue - assert p.default is not inspect.Parameter.empty or p.kind in ( - inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD), ( - f"{rel}#{idx}: {name}() 有个必填参数 {p.name!r},文档的签名清单里没写出来") - return True - - -def _looks_like_signature(entry: str) -> bool: - """一条条目是不是"签名"而非"代码"。 - - ⚠ 判据的关键在**形参必须是标识符**: `movej(q, speed=1.0)` 是签名, 而 - `movej([0.1, 0, ...], speed=0.3)` 是**真调用** —— 后者要拿去执行。 - """ - if _ATTR.match(entry): - return True - if "/" in entry and not _SIG.match(entry): - return all(_ATTR.match(p.strip()) for p in entry.split("/")) - m = _SIG.match(entry) - return bool(m) and all(_PARAM_OK.match(p) for p in _split_params(m.group(3))) - - -def _is_signature_block(body: str) -> bool: - """块里**每条**逻辑条目都是签名/属性 → 当成签名清单。""" - entries = list(_entries(body)) - return bool(entries) and all(_looks_like_signature(e) for e in entries) - - -# ---------------------------------------------------------------- 可执行示例 - -def _make_arm(): - """连上离线桩固件 —— 与 conftest 的 offline_arm 同构。""" - from fake_serial import FakeTransport - - return Arm(port="fake", transport_factory=lambda port="fake", timeout=0.2, **k: - FakeTransport(port=port, timeout=timeout, fw="Litearm1.7.0-7J", **k)).connect() - - -@pytest.fixture -def _stub_port_discovery(monkeypatch): - """让 `pa.Arm().connect()`(不带 port)在**没接真机**的机器上也能跑。 - - ⚠ 必须打这个补丁: `connect()` 里 `find_cdc_port()` 排在传输工厂**之前** - (`arm.py:919`), 它只枚举 USB 不开设备 —— 但机器上没接臂时它回 `None`, - 紧跟的 `raise TransportError` 会让"最小完整程序"那类示例在 CI 上假失败。 - """ - import litearm.arm as arm_mod - - monkeypatch.setattr(arm_mod, "find_cdc_port", lambda: "fake") - - -@pytest.fixture(scope="module", autouse=True) -def _eval_ns(): - import litearm - from litearm.arm import FIRMWARE_PREFIX, MIN_FW - - _EVAL_NS.update({"MIN_FW": MIN_FW, "FIRMWARE_PREFIX": FIRMWARE_PREFIX, - "litearm": litearm}) - - -@pytest.mark.parametrize("rel,idx,body", ALL_BLOCKS, ids=IDS) -def test_doc_block(rel, idx, body, fake_transport_factory, _stub_port_discovery): - fake_transport_factory() # 把 SerialTransport 换成桩(monkeypatch,自动还原) - - # ⚠ 签名清单要**先**判, 不能放在语法检查后面: 签名清单本来就不是合法 Python - # (`f(a, *, b=1)` 当语句写是语法错误), 放在后面会被 SyntaxError 直接 return 掉, - # 于是核对整个被跳过 —— 实测踩过, 变异测试立刻显形。 - if _is_signature_block(body): - for e in _entries(body): - _check_signature_entry(e, rel, idx) - return - - try: - ast.parse(body) - except SyntaxError as e: - pytest.fail(f"{rel}#{idx} 语法错误: {e}") - - if ILLUSTRATIVE.search(body): - return - - # 真跑。只注入 `arm` 与 `pa` —— 别的名字未定义就会 NameError, - # 这正是要抓的"示例里留了没交代的占位符"。 - import litearm as pa - - arm = _make_arm() - try: - exec(compile(body, f"{rel}#{idx}", "exec"), {"pa": pa, "arm": arm}) - except Exception as e: # noqa: BLE001 - 示例跑不起来就是失败 - pytest.fail(f"{rel}#{idx} 执行失败:\n{body}\n→ {type(e).__name__}: {e}") - finally: - arm.close() diff --git a/tests/test_error_codes.py b/tests/test_error_codes.py deleted file mode 100644 index ac143f2..0000000 --- a/tests/test_error_codes.py +++ /dev/null @@ -1,945 +0,0 @@ -"""`(cmd, code)` 语义表 + `enable()` 重试策略 + 解析固件的防漂移哨兵 (spec §6.3)。 - -三块内容分开看: - -1. **表本身** (`errors.ERR_TEXT` / `ERR_CODE_TEXT` / `err_reason`) —— 语义文本、 - 未登记的码不静默、异常层级不变; -2. **`enable()` 的重试白名单** (`errors.ENABLE_RETRYABLE_CODES`) —— 锁存故障 - **只发一次**, 不白耗 3.3 秒 (12 次尝试只有 11 次 `sleep(0.3)`); 可重试码照旧重试; -3. **哨兵**: 直接解析固件源码, 断言 SDK 的表**没有漏掉固件任何一档错误码**。 - -## ⚠⚠ 第 3 块的口径必须先定 (否则这条哨兵写不出来/写成假绿) - -固件 `usb_cmd.c` 的 94 处 `usb_cmd_reply(RSP_ERR, …)` 里, **27 处载荷不是纯十六进制 -字面量** (一条只抓 `{0x.., 0x..}` 的正则会得到 67 处, 漏 27 处): - -* **14 处** 的**命令码是符号名** (`{CMD_MOVE_L, 0x01}` … `{CMD_CART_ADD, 0x04}`) —— - 这 14 处**会被本文件自动解析**: 符号名从固件 `usb_cmd.h` 的 `#define CMD_*` 取值 - (与 `test_protocol_sync.py` 同一套解析)。⚠ 这正是"笛卡尔那 5 条对纯字面量正则 - 得到空集"那个坑的解法 —— 不靠白名单, 靠**真的去解析符号**。 -* **13 处** 的载荷**无法字面解析** (`{cmd, rc}` / `{0x10, e}` …) —— 其中 **9 处** - 的**错码**是变量, 另 **4 处**的**命令码**是变量 (这 4 处的错码是字面量; 有 1 处 - 两者都是变量, 归入前 9 处)。它们的取值集合由固件的收口函数决定, 字面上无从解析。 - -⚠ `SYMBOLIC_ERR_SITES` 里那 9 处变量错码的**码集合是手工转录**的 —— 逐条对着固件 -`control_loop.c` / `cart_exec.c` 的收口函数**函数体**抄下来的, 不是解析出来的。 -⇒ 收口函数**新增一个返回码**而**没有新增发射点**时 (例: `ctrl_accept_move_js` -将来多回一个 `0x05`), 本哨兵**不会红** —— 得靠人跟着改清单。这是本口径已知的 -精度上限, 不是漏写。 - -⇒ 本文件采用的**口径 = 计划里的 (B) 「单向 + 显式清单」**, 并做了一处**加强**: -`CMD_*` 符号名自动解析 (于是清单只需覆盖那 13 处**无法字面解析**的位点, 而不是 27 处)。 -写死在此处, 免得下一个人以为可以随手改成别的口径: - - · **正向 (自动, 无清单)**: 固件里所有能解析成 `(cmd, code)` 的发射点 - (76 个不同的 `(cmd, code)`, 覆盖 **83 处** = 96 − 13) **必须**在 - `errors.ERR_TEXT` 里 - (唯一例外: `code == 0x00`, 那是 `default` 分支, 见 `test_protocol_sync.py` - 的 `test_err_code_zero_only_comes_from_default_branch`)。 - · **变量码 (清单, 15 条)**: `SYMBOLIC_ERR_SITES` 逐条列举, 每条声明它的 - `(命令集合 × 码集合)`; **清单条数被断言钉死** (见 - `test_symbolic_site_manifest_matches_firmware`), 清单自己漂了也红。 - ⚠ 组成 = `usb_cmd.c` 13 条 + `kin_runner.c` 1 条 + `default` 哨兵 1 条。 - (2026-10-10 之前只有 14 条 —— 下面那条 `usb_cmd.c` 的分解是**单文件**口径, - 而 `_firmware_err_sites` 走的是**整棵固件树**, 于是 `kin_runner.c` 那条 - 一直没被清单看见; 是 SDK 对着固件跑 `test_protocol_sync`/本文件时抓出来的。) - · **反向闭合 (这是"双向差集"唯一写得出来的形态)**: `ERR_TEXT` 里**不在**上两类 - 覆盖范围内的条目 = 必须是**显式列举且计数**的 `ERR_TEXT_OUT_OF_TREE` - (当前 2 条, 出处是另一条固件分支)。于是"表里凭空多一条固件发不出的码" - 也会红 —— 单靠正向是抓不到的。 - -⚠ 本哨兵的价值是"**固件新增一档错误码时 SDK 不会静默**"。**别为了让它绿而降级** -(拆掉反向闭合、把清单改成白名单、或对不上就 `pytest.skip`) —— 那是本仓最忌讳的假绿, -`_read()` 里那句"找不到时 skip, 不是 pass"就是同一条纪律。 -""" -from __future__ import annotations - -import glob -import os -import re -from collections import Counter - -import pytest - -from litearm import _protocol as P -from litearm import arm as arm_mod -from litearm import errors as E -from litearm import state as ST - -FW_DIR = os.environ.get("LITEARM_FW_DIR") or os.path.expanduser("~/litearm-stm32") -_FW_SUBDIR = os.path.join("User", "litearm") -USB_CMD_H = os.path.join(FW_DIR, _FW_SUBDIR, "hal", "usb_cmd.h") - - -def _read(path: str) -> str: - if not os.path.isfile(path): - pytest.skip(f"固件源码不在 {path} —— 设 LITEARM_FW_DIR 指向 litearm-stm32 仓库") - with open(path, encoding="utf-8", errors="replace") as f: - return f.read() - - -# =========================================================================== -# 1. 表本身 -# =========================================================================== - -def test_table_is_not_empty_and_covers_the_cartesian_range(): - """笛卡尔 `0x3A~0x3E` 的码必须在表里 —— 旧固件工具的那张表**没有**它们, - 正是本次重新穷举的理由 (spec §6.3 的起点)。 - - ⚠ `0x3E` (CART_RUN) **没有** `0x01` 档: 它的载荷是**空的**, dispatch 里根本 - 没有长度校验 (`usb_cmd.c` 的 `case CMD_CART_RUN` 直接进门禁)。四条有 `0x01` - 的是 `0x3A/0x3B/0x3C/0x3D`。别按"笛卡尔五条同形"去推 —— 它们的载荷形状不同。 - """ - assert len(E.ERR_TEXT) > 90 - for cmd in (0x3A, 0x3B, 0x3C, 0x3D): - assert (cmd, 0x01) in E.ERR_TEXT, f"笛卡尔 0x{cmd:02X} 的载荷长度档未登记" - assert (0x3E, 0x01) not in E.ERR_TEXT, "CART_RUN 载荷为空, 不存在长度不足档" - - -#: 会因 drop_hold 而回 `0x06` 的命令。 -#: -#: ⚠ **`0x02` MOVE_P 走的是另一条路, 但同样会回 `0x06`** —— 它的 **dispatch** -#: (`usb_cmd.c` 的 `case CMD_MOVE_P` → `kin_runner_request_move_p`) 确实**没有** -#: drop_hold 门禁 (三档只有 `!enabled`(0x03) / 零重力(0x04) / 忙(0x05)); -#: 但**受理之后**后台 IK 出解时走 `kin_runner_flush_move` → `ctrl_accept_move_j`, -#: 那里面**有** `if (g_arm.drop_hold) return 0x06`, 并以 `{0x02, rc}` 补一条 -#: **迟到终态应答** (固件 `kin_runner.c` 的 [2026-09-24 fix]; 其注释点名 -#: "0x06 掉线锁存")。⇒ **登记 IK 与 flush 之间**发生锁存, 就会看到 `{0x02,0x06}`。 -#: -#: ⚠ [2026-10-10 修正] 本条原先写"`0x02` 不在其中 … 它是运动类命令里唯一的例外", -#: 并据此断言 `(0x02, 0x06)` **不得**在表里。那只覆盖了 **dispatch** 一路, 漏了 -#: 迟到终态应答一路 —— 是 SDK 对着固件跑 `test_protocol_sync`/本文件时抓出来的 -#: (同一批里清单新增了 `kin_runner.c` 那个变量码位点)。**别按"dispatch 没有"去推 -#: 整条命令没有** —— 收口函数与 dispatch 不是同一层。 -DROP_HOLD_CMD_CODES = (0x01, 0x02, 0x03, 0x04, 0x05, 0x07, 0x2A, - 0x3A, 0x3B, 0x3C, 0x3D, 0x3E) - - -def test_the_two_previously_untabulated_entries_are_present(): - """S4 fix 的两条"今天不在任何表里"的码 (计划 Step 5 点名)。 - - ⚠ `(0x02, 0x06)` 的**负向**断言已于 2026-10-10 撤掉并改为由上面的循环**正向** - 断言 —— 见 `DROP_HOLD_CMD_CODES` 那段: MOVE_P 的 0x06 走的是迟到终态应答, - 不是 dispatch。撤负向不是放宽, 是**改对了方向**。 - """ - assert (0x25, 0x03) in E.ERR_TEXT, "异步保存失败码 {0x25,0x03} 未登记" - for cmd in DROP_HOLD_CMD_CODES: - assert (cmd, 0x06) in E.ERR_TEXT, f"{{0x{cmd:02X},0x06}} (drop_hold 门禁) 未登记" - - -@pytest.mark.parametrize("cmd", DROP_HOLD_CMD_CODES) -def test_code_0x06_on_motion_commands_means_drop_hold(cmd): - """`0x06` 在**运动类**命令上恒等于 drop_hold 锁存 (`g_arm.drop_hold`) —— - 这是 SDK 唯一能**确证**该锁存的信号 (见 `state.drop_hold_inferred` 的文档)。 - - ⚠ 但 `0x10` ENABLE 的 `0x06` **不含** drop_hold 判据 (它判 EMERGENCY / - `joint_fault`, 出处 `control_loop.c` 的 `ctrl_enable`), 所以下面单独断言它 - **不得**在文本里提 drop_hold —— 混了会把"该去 reset"引向错的排查方向。 - """ - assert "drop_hold" in E.ERR_TEXT[(cmd, 0x06)] - - -def test_enable_code_0x06_does_not_claim_drop_hold(): - assert "drop_hold" not in E.ERR_TEXT[(0x10, 0x06)] - - -def test_no_code_zero_entry_anywhere(): - """`code == 0x00` 恒为"固件没有这条命令" (唯一真源是 `default` 分支) —— - 登记进具体档会让它变成"某条命令的一个普通错误码", 破坏能力探测的判定。""" - assert not [k for k in E.ERR_TEXT if k[1] == 0x00] - - -def test_unregistered_code_is_not_silent(): - """未登记的码必须带上**原始 cmd/code** —— 这是固件新增一档时唯一会让上位机 - 看见"我没见过这个码"的地方。""" - txt = E.err_reason(0x3A, 0x55) - assert "0x3A" in txt and "0x55" in txt - assert "未登记" in txt - - -def test_generic_fallback_still_carries_the_raw_code(): - """通用档命中时同样要带原始码 (计划: "未登记的码不许静默")。""" - txt = E.err_reason(0x3C, 0x05) # 0x05 有通用档, 但 (0x3C,0x05) 没登记 - assert "忙" in txt and "0x3C" in txt and "0x05" in txt - - -def test_every_entry_has_nonempty_text_and_int_keys(): - for (cmd, code), txt in E.ERR_TEXT.items(): - assert isinstance(cmd, int) and isinstance(code, int) - assert isinstance(txt, str) and txt.strip(), f"({cmd:#04x},{code:#04x}) 文本为空" - - -def test_enable_retryable_codes_are_registered(): - for code in E.ENABLE_RETRYABLE_CODES: - assert (0x10, code) in E.ERR_TEXT, f"重试白名单里的 0x{code:02X} 未登记" - - -def test_exception_hierarchy_is_unchanged(): - """计划: **不新增异常类型**, `CommandRejectedError` 仍是基类 (spec §6.3)。""" - assert issubclass(E.UnsupportedByFirmwareError, E.CommandRejectedError) - assert issubclass(E.CommandRejectedError, E.LiteArmError) - # 两条"刻意不继承"的既有约定, 一并钉住 (它们上面都写了很长的理由) - assert not issubclass(E.CartesianPlanError, E.CommandRejectedError) - assert not issubclass(E.MotionSupersededError, E.CartesianPlanError) - - -def test_err_from_carries_code_and_readable_text(): - """`_err_from` 是 `CommandRejectedError` 的唯一生产者 —— 它必须同时给出 - 可编程判定的 `.code` 与可读文本。""" - e = arm_mod._err_from(bytes([0x10, 0x06]), "enable(1) 被固件拒绝: ") - assert isinstance(e, E.CommandRejectedError) - assert (e.cmd, e.code) == (0x10, 0x06) - assert "[10,6]" in str(e) # 原始码 (固件 ERR 回显的两位十六进制) - assert "锁存" in str(e) and "RESET" in str(e) - - -def test_err_from_keeps_the_unsupported_by_firmware_subclass(): - """`code == 0x00` 走的仍是子类 (能力探测依赖它), 且**不进**具体档。""" - e = arm_mod._err_from(bytes([0x15, 0x00]), "") - assert isinstance(e, E.UnsupportedByFirmwareError) - assert (e.cmd, e.code) == (0x15, 0x00) - - -# =========================================================================== -# 2. enable() 区分"可重试"与"锁存" -# =========================================================================== - -def _enable_sends(arm) -> int: - return len(arm._tr.stamps_of(P.CMD_ENABLE)) - - -def test_enable_latched_code_sends_once_and_does_not_burn_the_retry_budget( - offline_arm, monkeypatch): - """`(0x10, 0x06)` = 锁存, 须先 RESET ⇒ **立刻抛, 别重试**。 - - 判据两条 (第二条是"不耗满预算"的直接观测): 只发**一次**; - 且**一次 `sleep(0.3)` 都没有发生** —— 12 次预算 = 11 × 0.3 = 3.3 秒, 全是白耗。 - """ - arm = offline_arm - arm._tr.err_override[P.CMD_ENABLE] = 0x06 - sleeps = [] - monkeypatch.setattr("time.sleep", lambda s: sleeps.append(s)) - - before = _enable_sends(arm) - with pytest.raises(E.CommandRejectedError) as ei: - arm.enable() # 默认 attempts=12, 一次都不该用满 - assert (ei.value.cmd, ei.value.code) == (P.CMD_ENABLE, 0x06) - assert _enable_sends(arm) - before == 1 - assert sleeps == [], f"锁存码之后还发生了 {len(sleeps)} 次重试等待" - assert isinstance(ei.value, E.CommandRejectedError) # 层级不变 - - -@pytest.mark.parametrize("code", [0x07]) -def test_enable_other_non_retryable_codes_also_send_once(offline_arm, monkeypatch, code): - """`0x07` (CMODE 补写预算耗尽, 固件原注释: "重发无用, 须现场排查") 与 `0x06` - 是同一类 —— 白名单口径 (`ENABLE_RETRYABLE_CODES`) 让它们都 fail-fast。""" - arm = offline_arm - arm._tr.err_override[P.CMD_ENABLE] = code - monkeypatch.setattr("time.sleep", lambda s: None) - before = _enable_sends(arm) - with pytest.raises(E.CommandRejectedError) as ei: - arm.enable() - assert ei.value.code == code - assert _enable_sends(arm) - before == 1 - - -def test_enable_retryable_code_still_retries(offline_arm, monkeypatch): - """`(0x10, 0x03)` = 可重试 (反馈未齐 / CMODE 首写) ⇒ **照旧重试**。""" - arm = offline_arm - arm._tr.err_override[P.CMD_ENABLE] = 0x03 - sleeps = [] - monkeypatch.setattr("time.sleep", lambda s: sleeps.append(s)) - - before = _enable_sends(arm) - with pytest.raises(E.CommandRejectedError) as ei: - arm.enable(attempts=3) - assert ei.value.code == 0x03 - assert _enable_sends(arm) - before == 3 - assert sleeps == [0.3, 0.3] - - -def test_enable_retries_then_succeeds(offline_arm, monkeypatch): - """0x03 之后放行 -> 重试确实能走到 ACK (证明白名单没把正常首使能路径堵死)。 - - 固件真机时序就是 "ENABLE#1 -> 0x03(首写 CMODE), ENABLE#2 -> ACK"。 - """ - arm = offline_arm - tr = arm._tr - tr.err_override[P.CMD_ENABLE] = 0x03 - orig = tr.write_frame - - def wf(cmd, payload=b""): - orig(cmd, payload) - if cmd == P.CMD_ENABLE: - tr.err_override.pop(P.CMD_ENABLE, None) # 只拒第一次 - - monkeypatch.setattr(tr, "write_frame", wf) - monkeypatch.setattr("time.sleep", lambda s: None) - - before = _enable_sends(arm) - arm.enable(attempts=3) # 不抛 - assert _enable_sends(arm) - before == 2 - - -def test_enable_missing_command_fails_fast_as_unsupported(offline_arm, monkeypatch): - """固件没有 `0x10` 时 (`ERR{0x10,0x00}`) 必须**立刻**抛 - `UnsupportedByFirmwareError` —— 重试 12 次只会把"固件太旧"这个结论推迟 3.3 秒。""" - arm = offline_arm - arm._tr.unknown_cmds.add(P.CMD_ENABLE) - monkeypatch.setattr("time.sleep", lambda s: None) - before = _enable_sends(arm) - with pytest.raises(E.UnsupportedByFirmwareError): - arm.enable() - assert _enable_sends(arm) - before == 1 - - -# =========================================================================== -# 3. drop_hold 的具名暴露 (⚠ 固件不上报它, 只能是推断) -# =========================================================================== - -def test_drop_hold_inferred_tracks_joint_fault(): - assert ST.RobotState(joint_fault=0).drop_hold_inferred is False - assert ST.RobotState(joint_fault=1 << 3).drop_hold_inferred is True - assert ST.RobotState(joint_fault=0x0008).drop_hold_inferred is True - - -def test_drop_hold_is_not_exposed_as_a_directly_read_bit(): - """⚠ "不许假装能直接读到" (spec §6.3) —— 状态帧里**没有** drop_hold 的位。 - - 具名的那个属性必须带 `_inferred` 后缀, 免得调用方以为它来自状态帧。 - """ - assert not hasattr(ST.RobotState, "drop_hold") - assert hasattr(ST.RobotState, "drop_hold_inferred") - - -def test_doc_warns_that_inference_is_one_sided(): - """**文档存在性守卫, 不计入判据强度** —— 它只查 `drop_hold_inferred` 的 docstring - 里还在不在那三个词 (`单向` / `joint_fault` / `不上报`), 不查行为。 - - ⚠ 它**两侧都能骗人**, 这是刻意的取舍, 别把它当成"方向正确"的证明: - - * **能误报**: 把同一句话**等价改写** (例如"该推断不可逆"), 词面一去掉就红 —— - 文档没变坏, 但用例红了; - * **能漏报**: 把这句话写成**反向的错话** (例如"`joint_fault != 0` ⇒ - `drop_hold` 必为真"), 只要还没删掉那三个词, 这里照样绿。 - - ⇒ **方向本身由行为用例覆盖**, 不靠这一条: 真值表在同文件的 - `test_drop_hold_inferred_tracks_joint_fault` (`joint_fault == 0 -> False`、 - `0x0008 -> True`, 属性实现就是 `bool(self.joint_fault)`, `state.py:125`)。 - 本用例的唯一职责是"那段警告没被顺手删掉", 所以它 - 用**最松**的判据 (三个子串) 避免自己变成维护负担 —— 也正因如此, 它的绿 - 不构成任何方向性结论。 - """ - txt = ST.RobotState.drop_hold_inferred.__doc__ - assert "单向" in txt and "joint_fault" in txt and "不上报" in txt - - -# =========================================================================== -# 4. 哨兵 —— 解析固件, 防 (cmd, code) 表漂移 -# =========================================================================== - -#: 固件 `ERR` 发射点: `usb_cmd_reply(RSP_ERR, (const uint8_t[]){, }, 2)`。 -#: 用 `[^}]*` 取花括号里的载荷 (载荷里不含 `}`)。 -#: ⚠ 函数名到 `,` 之间用 `\s*` 容错 —— 好让下面那条"裸调用头 vs 本正则"的核对 -#: 只对**载荷形态**敏感, 不对**换行缩进**敏感 (否则有人把参数折行就会假红)。 -_ERR_SITE = re.compile( - r"usb_cmd_reply\s*\(\s*RSP_ERR\s*,\s*\(const uint8_t\[\]\)\{([^}]*)\}") - -#: 同一个发射**函数名**的"裸调用头"—— 只看调用, 不看载荷形态。用途见 -#: `_firmware_err_sites` 里的逐文件核对: 把"`usb_cmd_reply(RSP_ERR` 出现过几次"与 -#: "`_ERR_SITE` 命中几次"钉成相等, 于是**换一种载荷发射形态**时哨兵不会静默。 -#: 实测今天这棵树上两者是 94 + 2, 一个不多一个不少。 -_ERR_CALL_HEAD = re.compile(r"usb_cmd_reply\s*\(\s*RSP_ERR") -_HEX = re.compile(r"^0x[0-9A-Fa-f]+$") - -#: 15 条**变量码**符号位点 (清单, 见模块 docstring 的口径说明)。 -#: key = `(相对固件仓的路径, cmd 表达式, code 表达式)`; -#: value = `(可达的 (cmd, code) 对集合, 说明)` —— 命令位写 `None` 表示"任意命令" -#: (只有 `default` 分支的 `{cmd, 0x00}` 是这样)。 -#: -#: ⚠ 声明的是**对集合**而不是"命令集合 × 码集合"的笛卡尔积: `cart_reply` 的五个 -#: 调用点可达的码**不同** (`cart_req_run` 只会回 `0x04`, 从不回 `0x02`), 笛卡尔积 -#: 会凭空多声明 `(0x3E, 0x02)` —— 那会让 -#: `test_manifest_declared_codes_are_registered` 报一条假缺陷。这正是 -#: "口径不定就写不出来"的实例: 精度只能做到**发射点**这一层, 再细化就得解析 -#: `cart_exec.c` 的函数体了。 -#: ⚠ 上面那句"再细化就得解析函数体"的另一面, 就是本清单的**精度上限**: -#: 这几个 `pairs` 是**手工转录**函数体里的返回码得到的 (不是算出来的) ⇒ -#: 收口函数**新增一个码而不新增发射点**时 (例: `ctrl_accept_move_js` 将来多回一个 -#: `0x05`), 固件树里的发射点一行没变 ⇒ `symbolic` 多重集不变 ⇒ **哨兵不红**。 -#: 只有**多一个调用点/多一处载荷**才会红。加码请人工跟这张清单。 -#: ⚠ 这份清单**必须与固件逐条对齐**: 条数与内容都被 -#: `test_symbolic_site_manifest_matches_firmware` 钉住。 -_USB_CMD_C = os.path.join(_FW_SUBDIR, "hal", "usb_cmd.c") -_KIN_RUNNER_C = os.path.join(_FW_SUBDIR, "kinematics", "kin_runner.c") -SYMBOLIC_ERR_SITES = { - (_USB_CMD_C, "cmd", "0x03"): - (frozenset({(0x3A, 0x03), (0x3B, 0x03), (0x3E, 0x03)}), - "cart_gate_ok: 未使能 —— 三个门禁调用点 (MOVE_L/MOVE_C/CART_RUN)"), - (_USB_CMD_C, "cmd", "0x06"): - (frozenset({(0x3A, 0x06), (0x3B, 0x06), (0x3E, 0x06)}), - "cart_gate_ok: 掉线刚性持位锁存 (drop_hold) —— [S4 fix]"), - (_USB_CMD_C, "cmd", "0x04"): - (frozenset({(0x3A, 0x04), (0x3B, 0x04), (0x3E, 0x04)}), - "cart_gate_ok: 零重力(拖动示教)中"), - (_USB_CMD_C, "cmd", "rc"): - (frozenset({(0x3A, 0x04), (0x3B, 0x04), # movel/movec: 只有 STATE - (0x3C, 0x02), (0x3C, 0x04), # begin: BADARG(n 越界) / STATE - (0x3D, 0x02), (0x3D, 0x04), # add: BADARG(idx 越界) / STATE - (0x3E, 0x04)}), # run: 只有 STATE (点名不满) - "cart_reply: 透传 cart_req_* 的 rc (cart_exec.h: CART_REQ_BADARG=0x02 / " - "CART_REQ_STATE=0x04) —— 五个调用点, 可达码各不相同"), - (_USB_CMD_C, "0x01", "mj"): - (frozenset({(0x01, 0x03), (0x01, 0x04), (0x01, 0x06)}), - "ctrl_accept_move_j 的返回码"), - (_USB_CMD_C, "0x07", "ms"): - (frozenset({(0x07, 0x03), (0x07, 0x04), (0x07, 0x06)}), - "ctrl_accept_move_j_sync 的返回码 (与 0x01 同表)"), - (_USB_CMD_C, "0x2A", "hr"): - (frozenset({(0x2A, 0x03), (0x2A, 0x04), (0x2A, 0x06)}), - "home 复用 ctrl_accept_move_j 的返回码 ([Z0 fix]: 原恒回 ACK)"), - (_USB_CMD_C, "0x03", "rjs"): - (frozenset({(0x03, 0x03), (0x03, 0x04), (0x03, 0x06)}), - "ctrl_accept_move_js 的返回码"), - (_USB_CMD_C, "0x04", "rmit"): - (frozenset({(0x04, 0x03), (0x04, 0x04), (0x04, 0x06)}), - "ctrl_accept_move_mit 的返回码"), - (_USB_CMD_C, "0x05", "rma"): - (frozenset({(0x05, 0x03), (0x05, 0x04), (0x05, 0x06)}), - "ctrl_accept_move_mit_all 的返回码"), - (_USB_CMD_C, "0x08", "rjf"): - (frozenset({(0x08, 0x03), (0x08, 0x04), (0x08, 0x06)}), - "ctrl_accept_joint_follow 的返回码 (与 0x05 同表: 0x03 未使能/急停锁存 / " - "0x04 零重力中 / 0x06 掉线刚性持位锁存)"), - (_USB_CMD_C, "0x10", "e"): - (frozenset({(0x10, 0x03), (0x10, 0x06), (0x10, 0x07), (0x10, 0x08)}), - "ctrl_enable 的返回码 (control_api.h: 0x03 可重试 / 0x06 锁存须 reset / " - "0x07 CMODE 补写预算耗尽 / 0x08 未激活 —— 固件 1.8.0 起 `ctrl_enable()` 的" - "**第一条**判据 (`control_loop.c:944`) 就是 `!license_is_activated()`)"), - (_USB_CMD_C, "0x15", "r"): - (frozenset({(0x15, 0x02), (0x15, 0x03)}), - "ctrl_request_enter_dfu 的返回码 (0x02 ROM 向量表无效 / 0x03 使能中)"), - (_KIN_RUNNER_C, "0x02", "rc"): - (frozenset({(0x02, 0x03), (0x02, 0x04), (0x02, 0x06)}), - "kin_runner_flush_move: 受理过的 move_p 的**迟到终态应答** —— IK 结果登记之后" - "才发生失能/掉线锁存/进零重力时补发, rc = ctrl_accept_move_j 的返回码直接透传" - " (固件注释点名: 0x03 未使能 / 0x04 零重力中 / 0x06 掉线锁存, **不新增码**)。" - "⚠ 本仓 2026-10-10 才发现: 上面那 14 条全部按 `usb_cmd.c` 计数, 而 " - "`_firmware_err_sites` 走的是**整棵固件树**, 故这一条在 `kin_runner.c` 里" - "一直没进清单 —— 哨兵此前对它是瞎的"), - (_USB_CMD_C, "cmd", "0x00"): - (frozenset({(None, 0x00)}), - "default 分支: 固件没有这条命令 (唯一一处 0x00, 能力探测的哨兵)"), -} - -#: 清单自身的**条数** —— 断言它, 免得清单被"顺手"改小而不自知。 -SYMBOLIC_ERR_SITES_COUNT = 15 - -#: `ERR_TEXT` 里**不在本固件树产出范围内**、但刻意保留的条目 (spec R5): -#: 出处是 `origin/feat/hyy-model-import` (1.5.3 `cdb744a` 不是 master 祖先), -#: 那里 `0x26 item7` / `0x28 item6` 在武装态回 `0x04`。留着是为了产线若烧那条 -#: 分支时 SDK 的解读不落回通用档。**显式列举 + 计数**, 不是一张可以顺手塞东西的 -#: 白名单 —— 加条目就要一起改下面的计数。 -ERR_TEXT_OUT_OF_TREE = frozenset({(0x26, 0x04), (0x28, 0x04)}) -ERR_TEXT_OUT_OF_TREE_COUNT = 2 - - -def _cmd_defines(hdr_src: str): - """`#define CMD_NAME 0xNN` -> {名字: 值} (与 test_protocol_sync.py 同一套)。""" - pat = r"^#define[ \t]+(CMD_\w+)[ \t]+(0x[0-9A-Fa-f]+)[ \t]*(.*)$" - return {m.group(1): int(m.group(2), 16) for m in re.finditer(pat, hdr_src, re.M)} - - -def _firmware_err_sites(): - """扫描固件 `User/litearm` 树 (不只 `usb_cmd.c`) 的**全部** `RSP_ERR` 发射点。 - - ⚠ 必须整树扫: `kin_runner.c` 里也有 2 处 (`0x02, 0x03` 的后台 IK 失败) —— - 只扫 `usb_cmd.c` 会漏掉它们。返回 `[(相对路径, cmd 表达式, code 表达式), …]`。 - - ⚠ **逐文件核对: 裸调用头数 == `_ERR_SITE` 命中数**。 - `_ERR_SITE` 只认**花括号字面量**这一种发射形态; 换成"先声明数组再传指针" - (`uint8_t eb[2]={…}; usb_cmd_reply(RSP_ERR, eb, 2);`) 就整棵树扫不到。 - 这棵固件树今天 96 处**恰好全是**花括号形态 ⇒ 是"未来形态变化"的洞, 不是现存缺陷。 - ⚠ 而且这种漏**不一定**会被既有的正/反向判据接住 —— 实测: 在 `kin_runner.c` - 把一处 `(const uint8_t[])` 的 `const` 去掉 (语义等价的形态变化), 因为 - `(0x02, 0x03)` 另有两处在发, 正向与反向闭合**都照样绿**, - **旧代码 36 passed 全静默**。下面这行是唯一的兜底: 让"换形态"当场变红。 - - ⚠ 它的口径上限是"只认 `usb_cmd_reply` 这**一个函数名**": 固件若新增另一个发射 - 函数 (或把发射收进 helper), 裸调用头与 `_ERR_SITE` **两侧都看不见**。 - ⚠ 这个洞**已封**, 但**不是**靠放宽本函数的正则 (放宽成"任意函数名 + `RSP_ERR`" - 会大量误伤: 注释、`==` 比较、`#define` 行都会命中) —— 而是由下面**另一条窄判据** - `test_only_usb_cmd_reply_receives_rsp_err` 回答"还有没有别人在收这个常量"。 - 两条的分工: **本函数管载荷形态漂移, 那条管发射面漂移**。 - """ - sites = [] - root = os.path.join(FW_DIR, _FW_SUBDIR) - if not os.path.isdir(root): - pytest.skip(f"固件源码树不在 {root} —— 设 LITEARM_FW_DIR") - for path in sorted(glob.glob(os.path.join(root, "**", "*.c"), recursive=True)): - src = open(path, encoding="utf-8", errors="replace").read() - rel = os.path.relpath(path, FW_DIR) - hits = _ERR_SITE.findall(src) - n_head = len(_ERR_CALL_HEAD.findall(src)) - assert n_head == len(hits), ( - f"{rel}: 看到 {n_head} 处 `usb_cmd_reply(RSP_ERR` 调用, 而 `_ERR_SITE` " - f"只解析出 {len(hits)} 处 —— 有 {n_head - len(hits)} 处换了发射形态 " - f"(不是 `(const uint8_t[]{{…}})` 花括号载荷), 哨兵看不见它们。" - f" 要么把 `_ERR_SITE` 改成能认这种形态, 要么把该处写回花括号形态;" - f" **别把本断言删掉** —— 少了它, 换形态的位点会静默少算" - f" (实测: 旧代码对 `kin_runner.c` 的同型变异 36 passed 全静默)。") - for m in _ERR_SITE.finditer(src): - parts = [x.strip() for x in m.group(1).split(",")] - assert len(parts) == 2, f"{rel}: 载荷不是 [cmd, code] 两段: {m.group(1)!r}" - sites.append((rel, parts[0], parts[1])) - return sites - - -#: C 里会引导一个**括号**、但**不是**"接收 `RSP_ERR` 的函数"的关键字。 -#: 例: `if (rsp == RSP_ERR)` —— 那个 `(` 同样是"最内层未闭合的括号", 不排掉就会把 -#: 接收者读成 `if` (一条假红, 而且名字看着莫名其妙)。 -#: ⚠ 今天的固件树里 **0 命中** —— 这条是给**未来写法**留的 (今天全部 96 处都是直接 -#: 调用 `usb_cmd_reply(...)`), 不是现存缺陷的补丁。 -_NOT_A_CALLER = frozenset({ - "if", "while", "for", "switch", "return", "sizeof", "do", "else", "case", -}) - - -def _strip_noncode(src: str) -> str: - """把 C 注释与字符串/字符字面量换成**等长空白** —— 只留代码, 且下标与原文对齐。 - - 为什么必须去: 本判据问的是"谁在**代码里**接收 `RSP_ERR`", 而固件树里 `RSP_ERR` - 还出现在**注释**中 (`usb_cmd.c` 里那句 0x00 约定说明、`kin_runner.c` 的 include - 注释) —— 不去注释就得逐处判"这段是不是注释", 那比去注释本身更容易写错。 - 等长替换 (**不是删除**) 的两个理由: 报错能指回原文行号; 不会把相邻 token 粘成 - 一个 (`a/*x*/b` 不能变成 `ab`)。 - """ - out, i, n = [], 0, len(src) - while i < n: - c = src[i] - if c == "/" and i + 1 < n and src[i + 1] == "*": - j = src.find("*/", i + 2) - j = n if j < 0 else j + 2 - elif c == "/" and i + 1 < n and src[i + 1] == "/": - j = src.find("\n", i) - j = n if j < 0 else j - elif c in "\"'": - j = i + 1 - while j < n and src[j] != c and src[j] != "\n": - j += 2 if src[j] == "\\" else 1 - j = min(j + 1, n) - else: - out.append(c) - i += 1 - continue - out.append(re.sub(r"[^\n]", " ", src[i:j])) - i = j - return "".join(out) - - -def _err_receiver_owners(code_src: str): - """`RSP_ERR` 的**接收者** → 计数; 外加"没有接收者"的下标表 (裸引用)。 - - 接收者 = **最内层未闭合的那个 `(`** 前面的标识符, 即"谁在调它、把这个常量传进去"。 - 向后扫 (遇到 `)` 记一层, `(` 且深度为 0 即本层) 是为了正确处理 - `usb_cmd_reply(RSP_ERR, (const uint8_t[]){cmd, code})` 这种**载荷里还有括号**的形态。 - 解析不出接收者的 (`rsp == RSP_ERR` 这类裸引用、关键字引导的括号) 进第二个返回值 - —— 它们**不构成发射面**, 但要在失败信息里列出来, 免得读的人以为"扫到了却没人收"。 - """ - owners, bare = Counter(), [] - for m in re.finditer(r"\bRSP_ERR\b", code_src): - depth, i = 0, m.start() - 1 - while i >= 0: - if code_src[i] == ")": - depth += 1 - elif code_src[i] == "(": - if depth == 0: - break - depth -= 1 - i -= 1 - if i < 0: - bare.append(m.start()) - continue - j = i - 1 - while j >= 0 and code_src[j] in " \t\r\n": - j -= 1 - k = j - while k >= 0 and (code_src[k].isalnum() or code_src[k] == "_"): - k -= 1 - name = code_src[k + 1:j + 1] - if not name or name in _NOT_A_CALLER: - bare.append(m.start()) - else: - owners[name] += 1 - return owners, bare - - -def test_only_usb_cmd_reply_receives_rsp_err(fw_err_sites): - """⚠ **发射面**哨兵: 固件 `.c` 里接收 `RSP_ERR` 的函数名集合**恰好** `{usb_cmd_reply}`。 - - 为什么另设一条, 而不是把 `_ERR_SITE` 的正则放宽: 放宽成"任意函数名 + `RSP_ERR`" - 会大量误伤 (注释 / `==` 比较 / `#define` 行都会命中), 而**窄判据**只回答一个问题: - **还有没有别人在收这个常量** —— 这正是 `_ERR_CALL_HEAD` 那条兜底**封不住**的洞 - (固件新增第二个发射函数、或把发射收进 helper 时, 裸调用头与 `_ERR_SITE` 两侧都 - 看不见, 见 `_firmware_err_sites` 的 docstring)。 - - **口径** (实测于 2026-09-19, 与 `_firmware_err_sites` **同一个根** `User/litearm`): - - * 扫 `User/litearm` 整棵树的 `.c` (**不扫全仓**, 两个理由: 全仓会连带扫到 `tools/` - —— 那是**宿主编译**的检查工具, 把 `RSP_ERR` 当**值**比较是它的正常用法 - (`tools/s4_drop_hold_gate_check_host.c:218`); 以及 `.claude/worktrees/` - —— 那是**另一条分支的检出**, 不是本树); - * 只算**调用点**: 先 `_strip_noncode` 去注释/字面量, 再取"最内层括号前面的标识符"; - 裸引用与注释里的提及**都不算**"接收" (故 `usb_cmd.c` 里那句 - `RSP_ERR{*,0x00}` 的约定说明不会命中); - * 今天: **96 处**接收点 (94 处在 `usb_cmd.c` + 2 处在 `kin_runner.c`), **全部**属主是 - `usb_cmd_reply`, 裸引用 **0** 处 —— 集合恰好单元素。 - - ⚠ **已知边界** (留底, 别读成"全仓都封了"): 只在 `User/litearm` **之外**的 `.c` 里 - 新增发射函数 (例: `Core/Src/main.c`) 时本判据看不见。截至今天全仓 - `grep -rln RSP_ERR --include=*.c` 只有 3 个文件, 树外那个是**比较**不是发射。 - - ⚠ 判据能失败: 在 `/tmp` 的固件副本里给任一 `.c` 加一句 - `usb_cmd_reply2(RSP_ERR, …)` 就红 (实测过); 集合变了就红, 不看条数。 - """ - root = os.path.join(FW_DIR, _FW_SUBDIR) - if not os.path.isdir(root): - pytest.skip(f"固件源码树不在 {root} —— 设 LITEARM_FW_DIR") - owners, bare, n_files = Counter(), 0, 0 - for path in sorted(glob.glob(os.path.join(root, "**", "*.c"), recursive=True)): - n_files += 1 - o, b = _err_receiver_owners(_strip_noncode(_read(path))) - owners.update(o) - bare += len(b) - assert n_files, f"{root} 下一个 .c 都没有 —— 路径坏了" - # ⚠ 空转防护与上一条**同源但会分流归因**: 解析器坏掉时读数是 0, 那时"集合 != {…}" - # 也能红, 但红的原因会被读成"固件里多了个发射函数"; 这条把两者分开。 - # ⚠⚠ 判据是"**与本判据自己的 `_ERR_SITE` 命中数相等**", **不是**"≥ 一个硬编码下界": - # 实测把扫描面退回 `usb_cmd.c` (94 处) 时 `94 >= 90` **照样通过** ⇒ 口径漂了而守卫 - # 不响。两个解析器是**相互独立**的 (`_err_receiver_owners` 去注释/字面量后取最内层 - # 括号前的标识符; `_ERR_SITE` 只认花括号字面量那一形态), 各自覆盖**同一棵树** - # ⇒ 数不相等就说明至少有一侧的口径漂了, 该当场红。 - assert sum(owners.values()) == len(fw_err_sites[1]), ( - f"本判据解析出 {sum(owners.values())} 个 `RSP_ERR` 接收点, 而 `_ERR_SITE` 在同一棵" - f"树上命中 {len(fw_err_sites[1])} 处 —— 两侧口径已经不一致 (扫描面/解析器漂了), " - f"别让本判据空转成假绿") - offenders = sorted(n for n in owners if n != "usb_cmd_reply") - assert not offenders, ( - f"固件里有 `usb_cmd_reply` 之外的函数在接收 `RSP_ERR`: {offenders} " - f"(逐处: {dict(owners)}; 另有 {bare} 处裸引用/非调用形态, 不计入接收面) —— " - f"若它是**新的发射面**, 那么 `_ERR_SITE`/`_ERR_CALL_HEAD` 那套**看不见它** " - f"(它们只认 `usb_cmd_reply` 一个名字), 本判据正是为它设的; 别直接删本用例。") - - -def _split_sites(sites, defines): - """发射点 -> (字面量 `(cmd,code)` 集合, 变量位点 Counter)。 - - 命令码优先按固件 `usb_cmd.h` 的 `CMD_*` 符号名解析 (那 14 处笛卡尔/收口点), - 故"字面量"的定义是**可解析**, 不是"纯十六进制"。解析不出的进第二桶。 - """ - literal, symbolic = set(), Counter() - for rel, cmd_expr, code_expr in sites: - if cmd_expr in defines: - cmd = defines[cmd_expr] - elif _HEX.match(cmd_expr): - cmd = int(cmd_expr, 16) - else: - symbolic[(rel, cmd_expr, code_expr)] += 1 - continue - if not _HEX.match(code_expr): - symbolic[(rel, cmd_expr, code_expr)] += 1 - continue - literal.add((cmd, int(code_expr, 16))) - return literal, symbolic - - -@pytest.fixture(scope="module") -def fw_err_sites(): - defines = _cmd_defines(_read(USB_CMD_H)) - return defines, _firmware_err_sites() - - -def test_every_firmware_literal_err_code_is_registered(fw_err_sites): - """**正向**: 固件每一个可解析的 `(cmd, code)` 都要在 `errors.ERR_TEXT` 里。 - - 固件**新增一个字面量错误码**而 SDK 没跟 -> 这里红 (这正是"不会静默"的下半句)。 - `code == 0x00` 例外: 它是 `default` 分支的"固件无此命令", 不进具体档。 - """ - defines, sites = fw_err_sites - literal, _ = _split_sites(sites, defines) - assert len(literal) > 60, "解析到的字面量码太少 —— 解析器大概坏了 (别让哨兵空转)" - missing = sorted((c, k) for (c, k) in literal if k != 0x00 and (c, k) not in E.ERR_TEXT) - assert not missing, ( - "固件里有、SDK 的 (cmd,code) 表里没有的码: " - + ", ".join(f"0x{c:02X}/0x{k:02X}" for c, k in missing)) - - -def test_symbolic_site_manifest_matches_firmware(fw_err_sites): - """**清单**: 13 条变量码位点必须与固件**逐条**一致 (多重集比对, 不是子集)。 - - ⚠ 用 `Counter` 而不是 `set`: 同一段载荷文本若在**新的**位置再出现一份 - (例如又加一个 `{cmd, 0x03}`), 集合比对会看不见, 多重集比对会红。 - """ - defines, sites = fw_err_sites - _, symbolic = _split_sites(sites, defines) - assert len(SYMBOLIC_ERR_SITES) == SYMBOLIC_ERR_SITES_COUNT, ( - f"清单条数被改成 {len(SYMBOLIC_ERR_SITES)}, 而钉死的是 {SYMBOLIC_ERR_SITES_COUNT}" - f" —— 改条数要连这个常量一起改 (它是故意的摩擦, 不是笔误)") - assert set(symbolic) == set(SYMBOLIC_ERR_SITES), ( - "变量码位点清单与固件对不上:\n 固件有而清单没有: " - f"{sorted(set(symbolic) - set(SYMBOLIC_ERR_SITES))}\n 清单有而固件没有: " - f"{sorted(set(SYMBOLIC_ERR_SITES) - set(symbolic))}") - assert symbolic == Counter({k: 1 for k in SYMBOLIC_ERR_SITES}), ( - f"某个变量码位点在固件里出现次数变了: {sorted(symbolic.items())}") - - -def test_manifest_declared_codes_are_registered(fw_err_sites): - """清单里声明的每个 `(cmd, code)` 对都必须在 `ERR_TEXT` 里 —— - 清单说"某收口函数会回这个码", 表就必须认识它。""" - problems = [] - for (rel, cmd_expr, code_expr), (pairs, why) in SYMBOLIC_ERR_SITES.items(): - assert pairs, f"{rel}:{cmd_expr}/{code_expr} 声明了空码集" - for cmd, code in pairs: - if cmd is not None and code != 0x00 and (cmd, code) not in E.ERR_TEXT: - problems.append(f"0x{cmd:02X}/0x{code:02X} ({why})") - assert not problems, f"清单声明了表里没有的码: {problems}" - - -def test_err_text_has_no_entry_the_firmware_cannot_produce(fw_err_sites): - """**反向闭合** —— 这条是"双向差集"里 SDK→固件 的那一半, 且它是写得出来的。 - - `ERR_TEXT` 的每一条都必须能被下面三者之一解释: - ① 固件里作为一个**字面量**出现 (`{0x23, 0x03}`); - ② 由**清单**里某条变量位点产出 (`cmds × codes`); - ③ 显式列举的树外条目 `ERR_TEXT_OUT_OF_TREE` (另一条固件分支)。 - - 否则 = **表里凭空多了一条固件发不出的码** (典型成因: 照着旧分支的表抄、 - 或固件删了某个码而 SDK 没跟) —— 纯正向判据**抓不到**这一类。 - """ - defines, sites = fw_err_sites - literal, _ = _split_sites(sites, defines) - covered = set() - for (rel, cmd_expr, code_expr), (pairs, _why) in SYMBOLIC_ERR_SITES.items(): - for cmd, code in pairs: - if cmd is None: # default 分支: 任意命令 - covered.update((c, code) for c in range(0x100)) - else: - covered.add((cmd, code)) - unexplained = sorted(set(E.ERR_TEXT) - literal - covered - ERR_TEXT_OUT_OF_TREE) - assert not unexplained, ( - "ERR_TEXT 里有固件产不出的条目 (表里凭空多出来的码): " - + ", ".join(f"0x{c:02X}/0x{k:02X}" for c, k in unexplained) - + " —— 若它属于另一条固件分支, 请显式加进 ERR_TEXT_OUT_OF_TREE 并改计数") - - -def test_out_of_tree_exemption_is_explicit_and_counted(): - """③ 那张树外清单本身也要守 —— 它不是白名单, 是**计数过的例外**。""" - assert len(ERR_TEXT_OUT_OF_TREE) == ERR_TEXT_OUT_OF_TREE_COUNT, ( - f"树外条目被改成 {len(ERR_TEXT_OUT_OF_TREE)}, 钉死的是 " - f"{ERR_TEXT_OUT_OF_TREE_COUNT}") - for pair in ERR_TEXT_OUT_OF_TREE: - assert pair in E.ERR_TEXT, f"树外条目 {pair} 不在 ERR_TEXT 里 (过期登记)" - - -def test_err_site_scan_is_not_silently_empty(fw_err_sites): - """哨兵自身的空转防护: 固件树必须真的扫到东西。 - - ⚠ 没有这条, "路径写错/正则失效"会让上面四条**全部恒真** —— 那是最隐蔽的假绿。 - """ - defines, sites = fw_err_sites - assert len(sites) >= 90, f"只扫到 {len(sites)} 处 ERR 发射点 (期望 90+, 实测 96)" - assert len(defines) > 30, f"只解析到 {len(defines)} 个 CMD_* 定义" - - -# =========================================================================== -# 6. `{0x28,0x02}` 的**拒绝条件** —— 文本曾错报一条固件没有的判据 (回归闸) -# =========================================================================== - -def test_0x28_02_text_does_not_claim_a_mass_rejection_that_firmware_lacks(): - """**文档存在性守卫, 不计入判据强度** —— 它查的是 `ERR_TEXT[(0x28,0x02)]` 那段散文里 - 几个字面量在不在 (`NaN` / `sub>2` / `item 9`+`保留` / `default` / `静默钳制` / `0,20`), - 不查任何行为; 唯一的**取反**断言是 ① 那条被撤回的子串不许回来。⚠ 两侧都能骗人: - - * **能误报**: 同一句话**等价改写** (例如把 "只有三类" 写成 "仅有三种情形") 就可能红; - * **能漏报**: 反过来说成**错话**只要还带着那几个字面量就照样绿 —— 例如把 "只有三类" - 改成 "只有四类" (`NaN`/`sub>2`/`item 9`/`default` 全都还在) ⇒ 本用例绿。 - - ⇒ **内容对不对**由行为与固件地面真值那几条覆盖 (`test_symbolic_site_manifest_matches_firmware` - / 下面 `test_0x28_02_text_scopes_the_clamp_claim_to_items_that_actually_clamp` 的 - `_ff_scalar_cases()` 现解), 不靠本条。 - - ⚠ **回归闸**: `ERR_TEXT[(0x28,0x02)]` 曾写 "值非法 (… / payload_mass<=0)"。 - - 固件 `params_ff_scalar()` 里**没有**这条路径 —— item 4 走 - `ff_clamp(v, 0.0f, 20.0f)` **静默钳制**后 `return true` 回 ACK - (`params.c:184` 钳、`:232` 返回真)。留着那条鬼判据的代价是双向的: - · 现场看到 `ERR{0x28,0x02}` 会去查一个**不存在**的质量校验; - · 反过来运维会以为 `set_payload(-5)` **失败了** —— 实际它 ACK, 且把质量 - 静默钳成 0 (重力前馈已经变了)。 - 会回本码的**只有四类** (逐条对着 `params.c:170-232` 抄): - NaN (`:172`) / item 5·6 的 `sub>2` (`:188`/`:193`) / - item 7 的 `v∉{0,1,2}` (`:199`) / 其余 item 落 `default` (`:219-220`, 含保留的 item 9)。 - """ - text = E.ERR_TEXT[(0x28, 0x02)] - # ① 那条已被撤回的判据不许回来 (直接钉那个子串) - assert "payload_mass<=0" not in text, "那条固件不存在的质量判据又回来了" - # ② 四类真拒绝理由逐条在册 - assert "NaN" in text, "少了 NaN 这一类" - assert "sub>2" in text.replace(" ", ""), "少了 item 5/6 的 sub>2 这一类" - assert "item 9" in text and "保留" in text, ( - "少了「item 9 保留、写它走 default 也回本码」这句 —— 合法区间是 1..8 与 10..18, " - "写成 1..18 会让人以为 item 9 可写") - assert "default" in text, "少了「其余 item 落 default」这一类" - # ③ "幅值静默钳制" 必须在 —— 它才是 `set_payload(-5)` 的真实命运 - assert "静默钳制" in text, "少了「幅值一律静默钳制」这句 (0x28 最容易被误读的地方)" - assert "0,20" in text, "少了 payload_mass 的钳幅 [0,20]" - - -# --------------------------------------------------------------------------- -# 6b. 「幅值一律静默钳制」的**射程** —— 上一句曾被读成"每个 item 都钳"(回归闸) -# --------------------------------------------------------------------------- - -_FF_SCALAR_BODY = re.compile(r"bool\s+params_ff_scalar\s*\([^)]*\)\s*\{(.*?)\n\}", re.DOTALL) - - -def _ff_scalar_cases(): - """从固件 `params_ff_scalar()` 抽 `item -> 该 case 的正文` —— 本判据的**地面真值**。 - - 只切 `case N:` 段 (到下一个 `case`/`default` 为止), 不解析语义 —— 判据只用 - "`return false` 出现在任何 `ff_clamp(` **之前**"这一个形态特征来判"值域拒绝"。 - - ⚠ **射程上限 (已声明, 只记账)**: 正因为只判**形态特征**, 它**挡得住"删掉"、挡不住 - "语义关掉"** —— 把那一行写成 `if (0) return false;` 形态仍在, 本判据照样绿。⇒ 它覆盖 - 的只是"拒绝位点漂到 `ff_clamp(` 之后"这一类改动, **语义正确性不由它保证**。 - """ - src = _read(os.path.join(FW_DIR, _FW_SUBDIR, "params", "params.c")) - m = _FF_SCALAR_BODY.search(src) - assert m, "params.c 里找不到 params_ff_scalar() 的函数体 —— 形态变了, 本判据要跟着改" - body = m.group(1) - cases = {} - for cm in re.finditer( - r"case\s+(\d+)\s*:(.*?)(?=\n\s*case\s+\d+\s*:|\n\s*default\s*:|\Z)", body, - re.DOTALL): - cases[int(cm.group(1))] = cm.group(2) - return cases - - -def _rejects_before_any_clamp(case_body: str) -> bool: - """该 case 是不是"**在任何 `ff_clamp()` 之前**就 `return false`" —— 值域拒绝。""" - i_false = case_body.find("return false") - i_clamp = case_body.find("ff_clamp(") - return i_false != -1 and (i_clamp == -1 or i_false < i_clamp) - - -def test_0x28_02_text_scopes_the_clamp_claim_to_items_that_actually_clamp(): - """**文档存在性守卫, 不计入判据强度** —— 加上面 `_ff_scalar_cases()` 的**地面真值**那 - 几行: 前者查的是那段散文里的字面量, 后者查的才是固件 `params.c` **今天真的是什么形状** - (它只判"`return false` 出现在任何 `ff_clamp(` 之前"这一个**形态特征**, **不解析语义** - —— 把 `return false` 写成 `if (0) return false;` 之类的**语义关掉**, 它照样绿; 那是 - 已声明的射程上限)。两侧都能骗人: - - * **能误报**: 同一句话**等价改写**就红 (下面那段"已知误红"有实测); - * **能漏报**: 反过来说成**错话**只要还带着那几个字面量就照样绿 —— 这正是下面那条 - **取反**断言存在的理由 (实测: 把历史错话**原文追加回去**, 原来那三条"子串在场" - 的断言**全部仍在场** ⇒ 旧判据绿)。 - - ⚠ **回归闸**: `ERR_TEXT[(0x28,0x02)]` 曾写"⚠ **幅值一律静默钳制**: 每个 item 过 - `ff_clamp()` 后照样 `return true` 回 ACK, 固件**没有**「幅值越界 ⇒ ERR」这条路径"。 - - 那句话**自己打自己**: 同一条文本前一句刚把 item 7 的 `v∉{0,1,2}` 列为回本码的三类 - 之一, 而 item 7 **根本不过 `ff_clamp()`** —— 它的 case 正文是 - `if (v != 0.0f && v != 1.0f && v != 2.0f) return false;` 后直接赋值 - (`params.c:197-200`), 固件自查头也写着"其余拒绝" (`usb_cmd.h:83`)。 - 同理 item 5/6 的 `sub > 2` (`:188` / `:193`) 也在**任何 clamp 之前** `return false`。 - - 危害是**双向**的 (与上面那条"质量判据"同型): 现场面对 - `set_ff_scalar(7, 0, 3.0)` 的 `ERR{0x28,0x02}` 会去查一个**不存在**的钳幅边界, - 而真正的判据是"值域只有 {0,1,2}"。 - - ⇒ 判据 = ① 钳制那句必须**被限定**在"有 clamp 的 item"上; ② item 7 与 item 5/6 的 - `sub` 必须被点名成**值域拒绝**。地面真值从固件源码现解, 不写死在这里。 - - ⚠ **已知误红 —— 刻意留着, 口径同本文件的 - `test_doc_warns_that_inference_is_one_sided`**: 那三条断言查的是**字面量**, 所以把 - 同一句话**等价改写**就会红。实测 (2026-09-19, `/tmp` 副本): 把 - "只对**有 `clamp` 的那些 item**" 改成 "只对**会走 `ff_clamp()` 的 item**" - (语义等价) ⇒ `assert "有clamp" in flat` 立刻失败, 文档本身**没变坏**。 - **为什么不放宽**: 这句钳制文案是**给现场读的错误文本**(它的危害是双向的, 见上), - 改写它**就等于重写判据的表述** ⇒ 本来就该连带把地面真值重核一遍 (本用例的地面真值 - 正是从 `params.c` **现解**的), 让它红是**提醒**, 不是维护负担。 - ⚠ **尤其别**放宽成"含 `clamp` 或 `ff_clamp`" —— 实测那句**历史错话** - ("幅值一律静默钳制: 每个 item 过 `ff_clamp()` 后照样 `return true` 回 ACK") - **同样含 `ff_clamp`** ⇒ 这种放宽**放过了它自己的回归对象**, 等于把闸拆了。 - (能同时接住"现文本 / 等价改写"又挡住历史错话的写法是"`只对`/`仅对` **且** `clamp`"; - 但那是**另一条**任意线 —— 它会放过"只对 item 7 钳制"这类**真错话**, 故不取。) - - ⚠ **补的那条取反断言 (③) 才是真正的回归闸**: 上面 ①② 与 `item7` 只查"正确的话在场", - 接不住"错话**并存**" —— 实测 (2026-09-19) 把历史错话原文**追加回** - `ERR_TEXT[(0x28,0x02)]`, 那三条子串断言**全部仍在场** ⇒ 旧判据 **GREEN**。③ 因此 - **取反**钉住那句的**普遍量化**形状 ("每个 item 都过 `ff_clamp()`")。⚠ 它自己的射程: - 只钉 `每个item` / `所有item` 两个扁平化词面, **换个说法的同义错话** (例: "任何 item - 均过 `ff_clamp()`") **不在此列** —— 那种改写要连带重核地面真值, 由上面那段"已知误红" - 的口径兜底。 - """ - cases = _ff_scalar_cases() - for item in (5, 6, 7): - assert item in cases, f"params.c 里没有 case {item} —— 地面真值变了" - assert _rejects_before_any_clamp(cases[item]), ( - f"params.c 的 case {item} 不再是「clamp 之前就 return false」了 —— " - f"本判据的地面真值变了, 先核对固件再改这里 (别为了让用例变绿而放宽断言)") - assert "ff_clamp(" in cases[4], ( - "case 4 不再是走 ff_clamp 的钳幅那一路 —— 地面真值变了 ('有 clamp 的 item' " - "这句话的正面样本就是它)") - - text = E.ERR_TEXT[(0x28, 0x02)] - flat = text.replace(" ", "").replace("*", "").replace("`", "") - # ① 钳制那句必须被限定 —— 少了限定就会被读成"每个 item 都钳", 而同一条文本自己 - # 列的 item 7 就是**不钳**的直接反例 - assert "有clamp" in flat, ( - "缺少「只对**有 clamp 的那些 item** 成立」这个限定 —— 强断言会把 item 7 / " - "item 5·6 的 sub 一起说成'被钳', 与同一条文本自己列的拒绝条件矛盾") - # ② 那两处必须被点名成**值域拒绝**, 而不是幅值越界 - assert "值域拒绝" in flat, ( - "缺少「item 7 与 item 5/6 的 sub 是**值域拒绝**」这句 —— 它们是 rejection, " - "不是幅值越界; 少了它, 现场会去查一个不存在的钳幅边界") - assert "item7" in flat, "「值域拒绝」那句没有点名 item 7 (最容易被误读的就是它)" - # ③ (**取反题**) 历史错话的**普遍量化**形状不许并存 —— ①② 只查"正确的话在场", - # 追加回历史错话时它们全部仍在场 ⇒ 只靠 ①② 的旧判据接不住那个回归对象 (实测) - for universal in ("每个item", "所有item"): - assert universal not in flat, ( - f"「幅值一律静默钳制」又被写成了**普遍量化** ({universal}) —— 历史错话 " - f"(docstring 里那一段) 正是这个形状: \"每个 item 过 `ff_clamp()` 后照样 " - f"`return true` 回 ACK\"; 而同一条文本自己列的 item 7 / item 5·6 的 sub " - f"就是**不钳**的直接反例") - - -def test_set_payload_accepts_negative_mass_without_a_local_rejection(offline_arm): - """`set_payload(-5)` **不抛** —— SDK 侧刻意**不**加 "质量须 >0" 的本地预检。 - - ⚠ 本用例**压着两件事, 判据强度不同**, 别把它们读成同一档: - - * **最后那条查 docstring 的断言**是 **文档存在性守卫, 不计入判据强度** —— 它只查 - `set_payload` 的 docstring 里还有没有 `钳` 与 `负` 两个字, 不查行为 (把整段说明 - 换成任何**别的话**、只要这两个字还在, 它照样绿; 而等价改写缺了字就红); - * 前面两条查的是**行为**: "不抛" + "`0x28` 帧照发出去"。⚠ 那两条也**只管到 - '发出去了'为止** —— **不校验载荷值**, 所以"SDK 先钳了再发"对它**没有观测面** - (实测: 给 `set_payload` 加本地钳制, 全量 531 passed 全绿)。载荷值由 - `tests/test_ff_io.py::test_set_payload_sends_the_raw_value_and_leaves_clamping_to_the_firmware` - 钉住。 - - 固件对负质量是**钳成 0 后回 ACK** (`params.c:184`), **不是**拒绝。SDK 若自作主张 - 抛 `InvalidCommandError`, 调用方拿到的"被拒"就是**假的** (参数其实写进去了, 只是 - 被钳过), 而且与 `set_ff_scalar` 的"固件权威 + 幅值钳制"口径分叉。 - - ⚠ 桩 (`fake_serial.py:297-299`) **不建模钳幅**, 只存原值 —— 所以本用例钉的是 - "**SDK 不拦、帧照发**", **不是** "钳到 0" (后者只能真机验)。别把断言写成 - `读回 == 0.0`, 那会去断言一个桩压根没实现的语义。 - """ - arm = offline_arm - arm.set_payload(-5.0) # 不抛即通过 (无本地预检) - assert P.CMD_SET_FF_SCALAR in {c for c, _p in arm._tr.tx_log}, ( - "负质量被本地吞掉了, 一个字节都没发 —— 固件那侧根本没机会钳制它") - doc = arm_mod.Arm.set_payload.__doc__ or "" - assert "钳" in doc and "负" in doc, ( - "`set_payload` 的 docstring 必须写明负值会被钳成 0 —— 否则调用方无从知道" - "传负值不是「被拒」而是「质量变成 0、重力前馈跟着变」") diff --git a/tests/test_error_hierarchy.py b/tests/test_error_hierarchy.py deleted file mode 100644 index 664d960..0000000 --- a/tests/test_error_hierarchy.py +++ /dev/null @@ -1,24 +0,0 @@ -"""跨线异常必须落在 `LiteArmError` 家族内, 且从包根可导出。 - -为什么单独钉这两条: -* 「是 LiteArmError 子类」—— 这 4 个原先各自定义在 server 侧且直接继承 - `Exception`, 客户端写 `except LiteArmError` **抓不到**"已被遥操占用"这条 - 最常撞的拒绝; -* 「在包根 `__all__` 里」—— SDK 既有的 `test_public_api.py::test_all_listed_names_are_actually_present` - 是**单向**的 (只查"列了的得存在"), 漏加 `__all__` 它**不会红**, 故必须在此显式断言。 -""" -from litearm import errors as E - -CROSSABLE = ("NotRemoteable", "NotSupportedOnThisBackend", - "TeleopLockedError", "TeleopBusyError") - - -def test_crossable_errors_are_litearm_errors(): - for name in CROSSABLE: - assert issubclass(getattr(E, name), E.LiteArmError), f"{name} 不是 LiteArmError 子类" - - -def test_exported_from_package_root(): - import litearm as pa - for name in CROSSABLE: - assert name in pa.__all__ and hasattr(pa, name) diff --git a/tests/test_ff_io.py b/tests/test_ff_io.py deleted file mode 100644 index dba6ed6..0000000 --- a/tests/test_ff_io.py +++ /dev/null @@ -1,126 +0,0 @@ -"""参数读写口与固件对齐 —— item 全集 + 读回闭环 (0x2B/0x2C -> 0x4B/0x4C)。 - -固件权威 (litearm-stm32/User/litearm/params/params.c + hal/usb_cmd.c): - 0x26 SET_FF_VEC item 1..15 (1-6 关节 / 7,8 gs,is / 9-11 摩擦 v2 / 12-14 零重力 / 15 kd_extra) - 0x28 SET_FF_SCALAR item 1..8 + 10..18 (item 9 保留: 写口拒绝, 只给 0x2C 读 ff_mask) - 0x2B -> RSP_FF_VEC 0x4B: payload = [0x4B, item, 7×f32 LE] (30B) - 0x2C -> RSP_FF_SCALAR 0x4C: payload = [0x4C, item, sub, f32 LE] (7B) -""" -from __future__ import annotations - -import struct - -import pytest - -from litearm import _protocol as P -from litearm.errors import InvalidCommandError - -VEC_ITEMS = list(range(1, 16)) # 1..15 全部有效 -SCALAR_ITEMS = list(range(1, 9)) + list(range(10, 19)) # 1..8 + 10..18 - - -def test_protocol_ids_match_firmware(): - assert (P.CMD_GET_FF_VEC, P.CMD_GET_FF_SCALAR) == (0x2B, 0x2C) - assert (P.RSP_FF_VEC, P.RSP_FF_SCALAR) == (0x4B, 0x4C) - - -#: 按固件 params.c 的**符号/值域契约**给每个 item 取合法样例值。 -#: ⚠ 桩 (tests/fake_serial.py) 只存值、不建模 params.c 的钳幅与符号守卫 —— -#: 样例值若违反契约, 离线仍会"绿"而真机必被拒 (item 11 fc1 必须 ≤0 就是这么踩的)。 -_VEC_SAMPLE = { - 11: [-0.1] * 7, # friction_fc1 ≤ 0 -} - - -@pytest.mark.parametrize("item", VEC_ITEMS) -def test_set_ff_vec_accepts_all_firmware_items(offline_arm, item): - """白名单必须覆盖固件支持的 1..15 (旧实现 >8 直接拒, 摩擦 v2/零重力/kd_extra 全不可调)。""" - offline_arm.set_ff_vec(item, _VEC_SAMPLE.get(item, [0.1] * 7)) - - -def test_vec_sample_values_respect_firmware_sign_contract(): - """守住上面的样例值本身: fc1 必须 ≤0, 其余非负, 否则测试会掩盖真机拒绝。""" - assert all(v <= 0 for v in _VEC_SAMPLE[11]) - for item, vals in _VEC_SAMPLE.items(): - if item == 11: - continue - assert all(v >= 0 for v in vals) - - -@pytest.mark.parametrize("item", [0, 16, 200]) -def test_set_ff_vec_rejects_out_of_range(offline_arm, item): - with pytest.raises(InvalidCommandError): - offline_arm.set_ff_vec(item, [0.0] * 7) - - -@pytest.mark.parametrize("item", SCALAR_ITEMS) -def test_set_ff_scalar_accepts_all_firmware_items(offline_arm, item): - offline_arm.set_ff_scalar(item, 0, 1.0) - - -@pytest.mark.parametrize("item", [0, 9, 19]) # item 9 = 保留给读 ff_mask -def test_set_ff_scalar_rejects_reserved(offline_arm, item): - with pytest.raises(InvalidCommandError): - offline_arm.set_ff_scalar(item, 0, 1.0) - - -def test_set_ff_scalar_sub_out_of_range(offline_arm): - with pytest.raises(InvalidCommandError): - offline_arm.set_ff_scalar(5, 3, 0.0) - - -# ------------------------------------------------------- 读回 (写→读闭环) -def test_get_ff_vec_roundtrip(offline_arm): - vals = [1.0, 2.0, 3.0, 4.0, 0.5, 0.25, 0.125] - offline_arm.set_ff_vec(7, vals) # gravity_scale - got = offline_arm.get_ff_vec(7).value - assert len(got) == 7 - assert all(abs(a - b) < 1e-6 for a, b in zip(got, vals)) - - -def test_get_ff_vec_item_echoed(offline_arm): - """应答载荷首字节是 RSP id, 第二字节是 item —— 解析必须跳过这两字节。""" - offline_arm.set_ff_vec(9, [0.5] * 7) # 摩擦 v2 fv - assert offline_arm.get_ff_vec(9).value == [0.5] * 7 - - -def test_get_ff_scalar_roundtrip(offline_arm): - offline_arm.set_payload(0.75, (0.01, 0.02, 0.03)) - assert abs(offline_arm.get_ff_scalar(4, 0).value - 0.75) < 1e-6 # payload_mass - assert abs(offline_arm.get_ff_scalar(5, 1).value - 0.02) < 1e-6 # payload_com[1] - - -def test_set_payload_sends_the_raw_value_and_leaves_clamping_to_the_firmware(offline_arm): - """⚠ **SDK 不替固件钳制**: `set_payload(-5)` 那一帧的 f32 载荷**就是 `-5.0`**。 - - 钳制发生在固件 (`params.c:184` 的 `ff_clamp(v, 0.0f, 20.0f)`, `:189` 对 com 逐轴 - `[-1,1]`) —— 主机侧的**原值**是固件唯一的输入。判据必须**解载荷**: - 只断言"帧发出去了"对"SDK 先把值钳了再发"**完全没有观测面** (实测: 把 `set_payload` - 改成先 `min(max(mass,0),20)` / `min(max(v,-1),1)` 再发, 全量 531 passed 全绿), 而那 - 与整条 `(0x28,0x02)` 口径的"**固件权威**"主张**直接冲突** —— 读回值 - (`get_ff_scalar`) 与发出值会分叉, 现场按发出值推断重力前馈就会错。 - - ⚠ **别写成"读回 == 0"**: 桩 (`fake_serial.py:297-299`) **不建模 `ff_clamp`**, 只存 - 原值 —— "钳到 0" 是真机的行为, 在离线用例里那样断言是**假判据**。 - """ - arm = offline_arm - arm.set_payload(-5.0, (2.0, -3.0, 0.0)) - - ps = [p for c, p in arm._tr.tx_log if c == P.CMD_SET_FF_SCALAR] - assert [(p[0], p[1]) for p in ps] == [(4, 0), (5, 0), (5, 1), (5, 2)], ( - f"`set_payload` 发出的 (item, sub) 序列变了: {[(p[0], p[1]) for p in ps]}") - sent = [struct.unpack_from(" 推进链路的任一帧,要么被某个队列的等待者取走,要么在**队列封顶**时被计数。 -> **不存在"静默销毁"这条路。** - -它靠一个机制成立:**SDK 只有一条读线程**(`_Ack._reader_loop`,唯一碰 -`transport.read_frame` 的地方),它把每帧按 `(上行 id, 回显码)` 投进队列, -等待者只从自己的队列里取。于是"谁读到归谁"这个问题**不存在**了。 - -⚠ 旧实现在这里放的是 11 条 `xfail`(那时断言的是 `_take_pending`)。那套机制 -(暂存盒 + `want` + `since` + `unexpected_frames` / `foreign_frames` 八处计数) -已整体删除,本文件随之改写 —— **契约不变,断言的机制换了**。 -""" -from __future__ import annotations - -import ast -import pathlib -import threading - -import pytest - -from litearm import _protocol as P -from litearm.arm import _QUEUE_MAX, _wait_keys -from litearm.errors import InvalidCommandError, MotionTimeoutError, NotConnectedError - -_ARM_PY = pathlib.Path(__file__).resolve().parents[1] / "src" / "litearm" / "arm.py" - - -def _push(arm, fid: int, payload: bytes = b"") -> None: - """往桩的响应队列里塞一帧(桩上没有 `feed`,实测写法是 `_push(pack_frame(...))`)。""" - arm._tr._push(P.pack_frame(fid, payload)) - - -# --------------------------------------------------------------------------- -# 1. 结构性判据 —— 这两条一红,整套机制的地基就没了 -# --------------------------------------------------------------------------- - -def test_read_frame_has_a_single_call_site_and_it_is_the_reader_loop(): - """全包只有**一处** `transport.read_frame` 调用点,且它在读线程里。 - - ⚠ 这是本设计的**承重结构**:只要还有第二处,那份代码就又在"自己决定帧归谁"。 - 判据走 AST(不是 grep):散文里提到 `read_frame` 不算,注释掉的也不算。 - """ - tree = ast.parse(_ARM_PY.read_text(encoding="utf-8")) - sites = [] - for fn in ast.walk(tree): - if not isinstance(fn, ast.FunctionDef): - continue - for node in ast.walk(fn): - if (isinstance(node, ast.Call) - and getattr(node.func, "attr", None) == "read_frame"): - sites.append((fn.name, node.lineno)) - assert len(sites) == 1, f"`read_frame` 调用点应当恰好一处, 实际: {sites}" - assert sites[0][0] == "_reader_loop", ( - f"`read_frame` 的唯一调用点必须是 `_reader_loop`, 实际在 `{sites[0][0]}`") - - -def test_no_wildcard_fetch_point_remains(): - """`src/` 里不存在"什么都不要、但读到什么就吃掉什么"的取帧点。 - - 旧实现里 `want=None` 的通配取帧会让整条归属机制失效(`poll_cart` 就走过那条路)。 - """ - src = _ARM_PY.parent - offenders = [] - for p in src.rglob("*.py"): - for node in ast.walk(ast.parse(p.read_text(encoding="utf-8"))): - if (isinstance(node, ast.Call) - and getattr(node.func, "attr", None) in ("_read_one", "_read_frames")): - offenders.append(f"{p.name}:{node.lineno}") - assert offenders == [], f"仍存在取帧口 (应为队列等待): {offenders}" - - -# --------------------------------------------------------------------------- -# 2. 归属判据 —— 同 id 不同命令**永不互通** -# --------------------------------------------------------------------------- - -def test_an_ack_waiter_must_declare_which_command_it_waits_for(): - """等 `RSP_ACK`/`RSP_ERR` 时 `echo_cmd` **必填** —— 它就是归属判据。 - - 不给就等于"随便哪条 ACK 都算我的",而那正是并发下两条命令互吃应答的成因 - (实测:到达序与等待序不一致时 **60/60 轮必有一方丢**)。 - ⚠ 库内 11 处调用点**全都给了**(`ast` 实测)⇒ 这里直接拒绝而不是退化成通配。 - """ - with pytest.raises(InvalidCommandError) as ei: - _wait_keys(P.RSP_ACK, None) - assert "echo_cmd" in str(ei.value) - - -def test_a_reply_goes_to_the_waiter_that_owns_it_not_the_first_to_read(offline_arm): - """`ACK{0x11}` 落在 `(0x11)` 那条队列里,等 `ACK{0x10}` 的人**碰不到它**。 - - 形状:先塞一条别人命令的 ACK,再让"别人的读者"来取 —— 它取不到,而主人取得到。 - """ - arm = offline_arm - _push(arm, P.RSP_ACK, bytes([P.CMD_DISABLE])) - # 等 `enable` 的一方来取("别人的读者")—— 它不该拿到这条 - assert arm._a._wait(((P.RSP_ACK, P.CMD_ENABLE),), 0.05) is None - # 主人拿得到(队列里那条还在) - arm._a.expect(P.RSP_ACK, 0.3, "disable", echo_cmd=P.CMD_DISABLE) - - -def test_two_concurrent_commands_do_not_eat_each_others_replies(offline_arm): - """**真两线程**:到达序与等待序相反时,两个等待者**都必须成功**。 - - ⚠ 这是旧实现最要命的一条(实测 100% 有一方丢应答)。判据是"两条命令都被受理过、 - 两条 ACK 也都到达过 ⇒ 两个等待者都该成功" —— 与谁先取无关。 - """ - arm = offline_arm - _push(arm, P.RSP_ACK, bytes([P.CMD_DISABLE])) # 到达序与等待序**相反** - _push(arm, P.RSP_ACK, bytes([P.CMD_ENABLE])) - - got: dict = {} - - def waiter(echo: int, label: str) -> None: - try: - arm._a.expect(P.RSP_ACK, 0.5, label, echo_cmd=echo) - got[label] = True - except MotionTimeoutError: - got[label] = False - - t1 = threading.Thread(target=waiter, args=(P.CMD_ENABLE, "enable")) - t2 = threading.Thread(target=waiter, args=(P.CMD_DISABLE, "disable")) - t1.start(); t2.start(); t1.join(); t2.join() - assert got == {"enable": True, "disable": True}, f"有人丢了应答: {got}" - - -#: 一个**不存在**的命令码 —— 用它当"别人的读者",保证与任何被测命令都不是同一条队列。 -_OTHER_CMD = 0x7F - - -@pytest.mark.parametrize("cmd", [P.CMD_ENABLE, P.CMD_DISABLE, P.CMD_EMERGENCY_STOP, - P.CMD_RESET, P.CMD_CLEAR_FAULTS]) -def test_safety_command_replies_are_never_stolen(offline_arm, cmd): - """安全命令(使能/失能/急停/复位/清故障)的应答是**最不能丢**的一族 —— 各钉一条。""" - arm = offline_arm - _push(arm, P.RSP_ACK, bytes([cmd])) - # 一个"别人的"读者先来取(⚠ 键必须与被测命令不同,否则它就是在取自己那条) - assert arm._a._wait(((P.RSP_ACK, _OTHER_CMD),), 0.05) is None - arm._a.expect(P.RSP_ACK, 0.3, f"cmd {cmd:#x}", echo_cmd=cmd) - - -def test_a_rejection_is_still_visible_to_a_non_ack_waiter(offline_arm): - """非 `ACK` 型等待(`want` 是某条 `RSP_*`)也必须看到**本命令的 ERR**。 - - ⚠ 实测过的回归:不给这类等待带上 `(RSP_ERR, echo_cmd)`,一次**被拒**会退化成 - "无应答"超时(`model.probe()` 撞的就是这条)。判据用 `model.get_body` 的真路径。 - """ - arm = offline_arm - arm._tr.err_override[P.CMD_GET_MODEL_PARAM] = 0x01 - with pytest.raises(Exception) as ei: - arm.model.get_body(0) - assert "被固件拒绝" in str(ei.value), ( - f"被拒必须报'被拒', 不能退化成超时: {ei.value!r}") - - -# --------------------------------------------------------------------------- -# 3. 陈旧帧 —— 不许冒充新应答("假成功"是本包最忌讳的方向) -# --------------------------------------------------------------------------- - -def _await_queued(arm, key, timeout: float = 1.0) -> bool: - """等读线程把某条队列填上(用例要控制"帧已经躺在队列里"这个前提)。""" - import time as _t - end = _t.monotonic() + timeout - while _t.monotonic() < end: - if arm._a._queues.get(key): - return True - _t.sleep(0.002) - return bool(arm._a._queues.get(key)) - - -def test_a_stale_reply_already_in_the_queue_is_dropped_before_the_next_command(offline_arm): - """发帧**之前**清本命令的应答队列(`_Ack.drain_for`,由 `_raw_write` 调)。 - - 形状:上一条 `reset` 已放弃,它的 ACK 已经**躺在队列里**;此时再发一条 `reset` - —— 那条陈旧 ACK **必须被清掉**,本条只能报超时,**绝不能凭它报成功**。 - ⚠ 方向是承重的:清晚了会吃掉自己的应答(假超时,安全侧);不清就是**假成功**(危险侧)。 - - ⚠⚠ **残余窗口(知情的、不可再约)**:清队只清**队列**。一条还在**传输缓冲/线上**的 - 陈旧应答,会在我们写完之后才被读线程取到 ⇒ 它躲过清队、被当成本次的应答。 - 根因是线上**没有请求 id**(松灵也一样)。⇒ 用例必须先把帧**送进队列**再发命令, - 否则测的是那个残余窗口,不是清队本身。 - """ - arm = offline_arm - _push(arm, P.RSP_ACK, bytes([P.CMD_RESET])) # 陈旧 ACK 先到 - assert _await_queued(arm, (P.RSP_ACK, P.CMD_RESET)), "用例自身失效: 帧没进队列" - # ⚠ 必须让桩**不再回答** `0x14`:否则这次成功可能来自固件那条**真** ACK, - # 用例就证明不了"清掉了陈旧的那条"(判据失去判别力)。 - _orig = arm._tr.write_frame - arm._tr.write_frame = lambda cmd, payload=b"": ( - None if cmd == P.CMD_RESET else _orig(cmd, payload)) - with pytest.raises(MotionTimeoutError): - arm.reset() # 不许凭陈旧帧"成功" - - -def test_the_drain_does_not_swallow_the_commands_own_reply(offline_arm): - """清队排在**写之前** ⇒ 不可能吃掉自己的应答(写之前它还不存在)。 - - ⚠ 这条是被实测逼出来的:早先的写法(在 `expect` 入口清队)会 **100%** 吃掉自己的 - 应答 —— 桩上直接让 `connect()` 的固件握手超时。 - """ - arm = offline_arm - arm.emergency_stop() # 活着回来即证明没有吃掉自己的 ACK - - -# --------------------------------------------------------------------------- -# 4. 有界与计数 —— 丢必须看得见 -# --------------------------------------------------------------------------- - -def test_the_queue_is_bounded_and_counts_what_it_evicts(offline_arm): - """每条队列封顶 `_QUEUE_MAX`;挤掉的帧必须计进 `_a.dropped`(**不静默**)。""" - arm = offline_arm - assert arm._a.dropped == 0 - for _ in range(_QUEUE_MAX + 5): - _push(arm, P.RSP_TCP, b"\x00" * 8) # 没人等 `(RSP_TCP, None)` - arm._a._wait(((P.RSP_ACK, P.CMD_ENABLE),), 0.002) # 驱动读线程把它投递掉 - assert arm._a.dropped >= 5, f"封顶丢帧没有计数 (dropped={arm._a.dropped})" - assert len(arm._a._queues.get((P.RSP_TCP, None), [])) <= _QUEUE_MAX - - -def test_the_queues_are_cleared_with_the_session(offline_arm): - """队列与 `_Ack` 同寿:`connect()` 重建 ⇒ 新会话看不到旧会话的残留。""" - arm = offline_arm - _push(arm, P.RSP_ACK, bytes([P.CMD_DISABLE])) - arm._a._wait(((P.RSP_ACK, P.CMD_ENABLE),), 0.002) - assert arm._a._queues.get((P.RSP_ACK, P.CMD_DISABLE)) - arm.reconnect() - assert arm._a._queues.get((P.RSP_ACK, P.CMD_DISABLE)) is None, "旧会话的帧漏进新会话" - - -# --------------------------------------------------------------------------- -# 5. 守卫 —— 从前挂在 `_read_one`/`_request_and_get` 上,必须跟着搬家 -# --------------------------------------------------------------------------- - -def test_negative_timeout_is_rejected_not_treated_as_wait_forever(offline_arm): - """`timeout < 0` 抛 `InvalidCommandError`。 - - ⚠ 这是守卫搬家清单里最危险的一条:漏了它,**负 timeout 会变成"等到永远"**。 - """ - arm = offline_arm - with pytest.raises(InvalidCommandError): - arm._a._wait(((P.RSP_ACK, P.CMD_ENABLE),), -1.0) - - -def test_a_held_ack_reference_after_close_reports_not_connected(offline_arm): - """`close()` 之后经**持有的 `_Ack` 引用**调 `expect` ⇒ `NotConnectedError`。 - - ⚠ 不能退化成"等满超时":那会把"链路已关"报成"固件不理我"。 - """ - arm = offline_arm - a = arm._a - arm.close() - with pytest.raises(NotConnectedError): - a.expect(P.RSP_ACK, 0.1, "after close", echo_cmd=P.CMD_ENABLE) - - -@pytest.mark.parametrize("entry", ["get_state", "get_status_now", "get_tcp"]) -def test_arm_entries_still_raise_not_connected_after_close(offline_arm, entry): - """`Arm` 级入口照旧**立刻**抛 `NotConnectedError`(它们先过 `_require()`)。""" - arm = offline_arm - arm.close() - with pytest.raises(NotConnectedError): - getattr(arm, entry)() diff --git a/tests/test_full_coverage.py b/tests/test_full_coverage.py deleted file mode 100644 index 33a95c9..0000000 --- a/tests/test_full_coverage.py +++ /dev/null @@ -1,363 +0,0 @@ -"""「覆盖所有功能」的可执行断言 —— 固件每条命令都要被某个 SDK 入口**真的发出去过**。 - -`test_protocol_sync.py` 只保证「入口能解析到」(属性存在且可调用), 那是**静态**的。 -这里做**动态**验证: 在桩固件上把每个入口真跑一遍, 断言固件会收到对应的命令 id。 -两者缺一不可 —— 属性存在但一调用就炸, 静态检查是看不出来的。 - -[2026-09-14] **无豁免** —— `0x30`/`0x33` 已由「动力学模型在线导入」实现, -`P.UNIMPLEMENTED_CMDS` 现为空表。 -""" -from __future__ import annotations - -import struct - -import pytest - -from litearm import _protocol as P -from litearm.errors import ArmIsInDfuError, CommandRejectedError - - -def _sent_ids_of(tr): - return {c for c, _ in list(tr.tx_log)} - - -def _sent_ids(arm): - return _sent_ids_of(arm._tr) - - -def test_every_implemented_command_is_exercised_through_its_entry(offline_arm): - """逐个入口跑一遍, 断言固件确实收到了那条命令。""" - arm = offline_arm - arm.connect() # 0x41 固件版本 - arm.get_status_now() # 0x40 主动取状态 - - arm.enable() # 0x10 - arm.movej([0.05] * 7, speed=0.3) # 0x01 - arm.movej_sync([0.05] * 7, speed=0.3) # 0x07 [SYNC] 同步 PTP - arm.move_p((0.30, 0.0, 0.35, 0.0, 0.0, 0.0), speed=0.3) # 0x02 - arm.move_js([0.0] * 7, dq=[0.0] * 7) # 0x03 - arm.move_js([0.0] * 7, dq=[0.0] * 7, tau_ff=[0.0] * 7) - arm.send_mit(0, 0.0, 0.0, 50.0, 2.0, 0.0) # 0x04 - arm.send_mit_all([0.0] * 7, [0.0] * 7, [50.0] * 7, [2.0] * 7, [0.0] * 7) # 0x05 - arm.joint_follow([0.0] * 7, [0.0] * 7, [50.0] * 7, [2.0] * 7) # 0x08 - arm.set_motion_mode(0) # 0x20 - arm.set_speed(50) # 0x21 - arm.ik((0.30, 0.0, 0.35, 0.0, 0.0, 0.0)) # 0x42 - arm.get_tcp() # 0x43 - arm.set_ff_vec(1, [0.0] * 7) # 0x26 - arm.set_ff_scalar(1, 0, 0.0) # 0x28 - arm.set_ff_mask(P.FF_ALL) # 0x27 - arm.ff_preset(1) # 0x31 - arm.get_ff_vec(1) # 0x2B - arm.get_ff_scalar(1, 0) # 0x2C - arm.home() # 0x2A - arm.params.set_joint_param(0, 50.0, 2.0, 10.0) # 0x22 - arm.params.set_joint_limits(0, -3.0, 3.0) # 0x23 - arm.params.get_joint_param(0) # 0x24 - arm.log.start(4) # 0x2D - arm.log.reader().read_all() # 0x2E - arm.log.stop() # 0x2D (0) - arm.diag.kin_bench() # 0x49 - with arm.zero_g(): # 0x06 - pass - # ---- [笛卡尔] 固件原生规划 (0x3A/0x3B/0x3C/0x3D/0x3E) ---- - # ⚠ **必须留在这段使能窗口内**: 下面 `arm.disable()` 之后固件侧三道门禁会回 - # `ERR{cmd,0x03}` (未使能) —— 那是**固件的**行为, 与桩无关, 但真机上放在下面 - # 就是一次 `CommandRejectedError`。 - # `move_c` 的 pose_start 必须与**实测 TCP** 一致 (上面 move_p 已把桩的 pose 设成它)。 - arm.move_l((0.30, 0.0, 0.35, 0.0, 0.0, 0.0), speed=0.3) # 0x3A - arm.move_c((0.30, 0.0, 0.35, 0.0, 0.0, 0.0), - (0.30, 0.0, 0.40, 0.0, 0.0, 0.0), - (0.32, 0.0, 0.40, 0.0, 0.0, 0.0), speed=0.3) # 0x3B - arm.move_path([(0.30, 0.0, 0.35, 0.0, 0.0, 0.0), - (0.30, 0.0, 0.40, 0.0, 0.0, 0.0), - (0.32, 0.0, 0.40, 0.0, 0.0, 0.0)], speed=0.3) # 0x3C/0x3D/0x3E - - # ---- [工具点 TCP 偏移] 宿主侧换算, 不发任何固件命令 (判据在 test_tool_offset.py) ---- - # ⚠ 这两行**必须清回零偏移**: 下面还有 `move_c` 之外的入口, 留着偏移会让它们的 - # 位姿被悄悄换算 (本用例只该验"命令真发出去了")。 - arm.set_tcp_offset((0.0, 0.0, 0.18)) # 只改内存, 不发帧 - arm.get_tool_tcp() # 0x43 + 换算 - arm.tcp_offset # 只读属性 - arm.tool_config_path() # 只读 (默认路径) - arm.clear_tcp_offset() - - arm.clear_faults() # 0x13 - arm.reset() # 0x14 - arm.enable() - arm.disable() # 0x11 - # ⚠ `0x25` **必须留在这段失能窗口内** (固件 `ctrl_is_armed()` ⇒ `ERR{0x25,0x04}`)。 - # 它从前排在 0x24 之后、即**上面那段使能窗口里** —— 桩那时不建模该门禁, 离线全绿, - # 真机上却是一次货真价实的 `CommandRejectedError`。 - # ⚠ **别改成"在使能窗口里插一句 `disable()`"**: 那会把 0x3A~0x3E 的笛卡尔块顶出 - # 使能窗口 (见上面那段注释), 而离线仍绿 (桩不建模笛卡尔的使能门禁) ⇒ 那句注释 - # 变成假话、真机上 5 条笛卡尔命令全被拒。这就是本文件要消灭的那类"会说谎的测试"。 - arm.save_params() # 0x25 (须失能 — 上面已 disable) - arm.emergency_stop() # 0x12 - arm.params.reset_factory() # 0x36 (须失能 — 上面已 disable) - - # 其余公开入口也真跑一遍 (只登记不调用 = 死接口) - arm.get_state(refresh=True) - arm.get_ff_mask() # 0x2C item 9 只读 - arm.set_gravity_scale([1.0] * 7) # 0x26 item 7 - arm.set_inertia_scale([1.0] * 7) # 0x26 item 8 - arm.set_payload(0.5, (0.0, 0.0, 0.0)) # 0x28 item 4/5 - arm.set_gravity_vector((0.0, 0.0, -9.81)) # 0x28 item 6 - arm.park() # 0x20 mode 0 - arm.zero_g_start() # 0x06 显式配对 - arm.zero_g_stop() - - # ---- [2026-09-14] 动力学模型在线导入 (0x30/0x32/0x33/0x34/0x35/0x37/0x38/0x39) ---- - # commit / revert 要求失能 (固件判据 ctrl_is_armed = enabled || enable_pending) - arm.disable() - arm.model.probe() # 0x34 (能力探测) - arm.model.get_body(0) # 0x34 - for i in range(1, 8): # 0x30 ×7 (body1..7) - arm.model.set_body(i, [1.0, 0.0, 0.0, 0.0] + [0.0] * 6) - arm.model.set_jm([0.0] * 7) # 0x33 - arm.model.get_jm() # 0x35 - from litearm.model import MODEL_MASK_WRITTEN - arm.model.commit(MODEL_MASK_WRITTEN) # 0x32 (掩码必须逐位相符) - arm.model.status() # 0x38 - arm.model.get_gravity([0.0] * 7) # 0x39 - arm.model.revert() # 0x37 - - # ---- [授权] 0x2F 查询 / 0x3F 提交 (见 tests/test_license.py) ---- - # ⚠ `0x3F` 同样**必须留在这段失能窗口内** —— 固件对已武装的臂回 `ERR{0x3F,0x04}` - # (与 `0x25` 同语义), 而桩照同一判据建模。 - # ⚠ 桩默认 `activated=True` ⇒ 这一发会得到聚合档 `0x02`(已存在), 再由 SDK 回读 - # `0x2F` 定性后**正常返回** —— 那正是本包要跑的路径 (0x02 的处理在 test_license.py - # 另有正反两条判据)。本用例只负责"入口可达、命令真发出去了"。 - arm.license() # 0x2F - arm.activate(cust_id=1, issued=20260922, mac=bytes(16)) # 0x3F - - # ---- [DFU] 0x15 `Arm.enter_dfu()` —— **必须留在这段失能窗口内** ---- - # 固件侧它是**两段式**: ACK 只表示"已登记", 还要等设备真的消失才置终态 (见 - # tests/test_dfu.py)。桩默认模拟"真跳转" (ACK 之后读路径抛 TransportError), - # 于是本行正常返回、而 `arm` 从此进**终端态** ⇒ 它只能是本测试的**最后**一条命令, - # 上面的 `sent` 快照与下面的 close 都还在终态之前/之中完成。 - # ⚠ 放在**使能中**会怎样: 固件回 `ERR{0x15,0x03}` (`ctrl_is_armed`), 而桩照同一 - # 判据守 —— 故这里必须是失能态 (上面那几处 `disable()` 之后一路失能; ⚠ 别按行号找, - # 行号会漂)。 - tr = arm._tr # 终态会把 `arm._tr` 置 None ⇒ 先抓住 transport 引用 - arm.enter_dfu() # 0x15 (终端态: 此后本对象不可用) - - sent = _sent_ids_of(tr) # 关链前取快照 (reconnect 会换成新的 transport) - arm.close() # 终态下仍必须可用 (幂等空操作, 不抛) - with pytest.raises(ArmIsInDfuError): - # 终态**不因 reconnect 复活** —— 要接着用臂请新建一个 `Arm`。 - # (这条钉在这里而不是只写在 test_dfu.py: 它是"终端态"最容易被顺手放宽的一处) - arm.reconnect() - - want = set(P.COMMAND_COVERAGE) - set(P.UNIMPLEMENTED_CMDS) - missing = sorted(want - sent) - assert not missing, ( - "以下固件命令从未被任何 SDK 入口真正发出: " - + ", ".join(f"0x{m:02X}({P.COMMAND_COVERAGE[m]})" for m in missing)) - - -def test_no_extra_command_ids_are_sent(offline_arm): - """反向: 发出去的 id 必须都在覆盖表里 (防止发了未登记/越界的命令)。""" - arm = offline_arm - arm.connect() - arm.enable() - arm.movej([0.0] * 7) - arm.get_tcp() - arm.disable() - sent = _sent_ids(arm) - unknown = sorted(sent - set(P.COMMAND_COVERAGE) - set(P.UNIMPLEMENTED_CMDS)) - assert not unknown, f"发出了未登记的命令 id: {[hex(x) for x in unknown]}" - - -def test_public_api_surface_is_all_exercised(offline_arm): - """`Arm` 的公开方法/属性 —— **名单守卫**: 不许出现没登记进 `exercised` 的公开成员。 - - ⚠ **措辞要说准** (本条从前写成"不许有**从没被调用过**的死接口" —— 与实现不符): - 实现只做**集合比较** `public - exercised - allowed_extra`, 它**不真的验证**这些成员 - 被调用过。哪个成员由哪条用例、在什么形状下被练习到, 是**那些用例自己**的事, - 不在这条判据的射程内 —— 别把"名单里有"读成"已经验过了"。 - """ - arm = offline_arm - exercised = { - "connect", "close", "get_state", "get_status_now", "get_tcp", "ik", "home", - "enable", "disable", "emergency_stop", "reset", "clear_faults", - "set_motion_mode", "park", "set_speed", "zero_g", "zero_g_start", "zero_g_stop", - "movej", "movej_sync", "move_p", "move_js", "send_mit", "send_mit_all", - "joint_follow", "reconnect", - # 收尾的两个名字 (同一个操作): 判据在 tests/test_teardown.py - "disconnect", - "set_ff_mask", "ff_preset", "set_ff_vec", "set_ff_scalar", "get_ff_vec", - "get_ff_scalar", "get_ff_mask", "set_gravity_scale", "set_inertia_scale", - "set_payload", "set_gravity_vector", "save_params", - "params", "log", "diag", "zero_g_active", "zero_g_error", "last_reset_reason", - # DFU (唯一会置**终端态**的入口; 判据在 tests/test_dfu.py, 本文件只跑一次真下发) - "enter_dfu", - # 笛卡尔 —— 只有固件原生路径一条 (PC 侧规划的 cartesian/movel/movec 已退役) - "move_l", "move_c", "move_path", "poll_cart", - # [2026-09-14] 动力学模型在线导入 (见 tests/test_model.py) - "model", - # [授权] 开机即锁 + 激活/查询 (见 tests/test_license.py) - "license", "activate", - # [工具点 TCP 偏移] 宿主侧换算 + 本地配置 (见 tests/test_tool_offset.py) - "set_tcp_offset", "clear_tcp_offset", "tcp_offset", "get_tool_tcp", - "save_tool", "load_tool", "tool_config_path", - } - public = {n for n in dir(arm) if not n.startswith("_")} - # 允许的少量内部/兼容名 - allowed_extra = { - # 只读状态 - "min_firmware", "firmware", "fw_version", "n", "q_tol", "dq_tol", - "arrive_frames", "move_timeout", "bench_model_axis", - # 类级数据表 (不是方法) - "FF_VEC_ITEMS", "FF_SCALAR_ITEMS", "FF_SCALAR_RO_ITEMS", - } - unlisted = public - exercised - allowed_extra - assert not unlisted, ( - f"Arm 上有未纳入清单的公开成员: {sorted(unlisted)} —— " - f"要么补进 exercised(并加测试), 要么确认它是内部状态") - - -# =========================== 门禁 (0x23 / 0x25) =========================== -# -# 上面那条覆盖用例只证明"命令真的发出去了" —— 它读的是**下行** `tx_log`。若桩对 -# `0x23`/`0x25` 一律回 ACK, 那么"SDK 在固件拒绝时会给调用方一个可判定的失败"这件事 -# 在离线用例里**完全没有观测面**: 桩的绿灯就变成"桩不建模门禁"的同义语。 -# -# 固件出处 (两条都是 `usb_cmd.c` 的 case 内第一道判据, 排在一切副作用之前): -# `CMD_PARAM_SAVE(0x25)` -> `ctrl_is_armed()` ⇒ `ERR{0x25,0x04}` -# `CMD_SET_JOINT_LIMITS(0x23)` -> `ctrl_is_armed() && ctrl_axis_outside(idx,lo,hi)` -# ⇒ `ERR{0x23,0x03}` -# ⚠ 0x23 的**顺序**是关键: 门禁在 idx/区间校验**之前** ⇒ "武装 + idx 越界" 固件回 -# `0x03`, 而不是值校验那条 `0x02`。桩若把门禁排在后面就会在这格上与固件相反。 -# ⚠ 门禁判据是 `ctrl_is_armed() = enabled || enable_pending`。`enable_pending` 在状态 -# 帧里没有位 (主机预检看不见), 桩用 `dfu_armed_pending` 造那个形状, 并由 `FakeTransport -# .armed` **一个判据供五处共用** (0x25/0x36/0x32/0x37 + 0x23 的第一层, 逐条对得上固件 -# 那五处 case) —— 所以下面既有"武装 (enable) 中"的用例, 也有"仅使能在途"的那条。 -# -# 桩的 `self.q[idx]` 是固件 `g_arm.cmd[idx].q_ref` 的**代理** (桩不建模运动过程) —— -# ⚠ 只在 `0x01`/`0x2A` 上精确, 其余命令后 `self.q` 停在旧值 (潜伏, 现无用例能踩到); -# 精确的例外清单见 `fake_serial.py` 的 `_axis_outside` 文档串。 - - -def test_set_joint_limits_refused_while_armed_when_new_range_cannot_hold_the_ref(offline_arm): - """armed **且**新限位关不住当前参考 ⇒ `ERR{0x23,0x03}` (固件 B1 fix)。 - - 载荷本身完全合法 (`0 < 0.10 < 0.20`), 被拒**只**因为 q_ref=0.05 落在新限位之外 - —— 固件那条注释的原话: ACK 了会出现在途轨迹仍奔向收窄前的旧目标、轴被开出新限位 - ⇒ 位置包络锁存 (该轴失力)。 - """ - arm = offline_arm - arm.enable() - arm.movej([0.05] * 7) # 桩: 此后 q_ref = 0.05 - with pytest.raises(CommandRejectedError) as ei: - arm.params.set_joint_limits(0, q_min=0.10, q_max=0.20) - assert (ei.value.cmd, ei.value.code) == (P.CMD_SET_JOINT_LIMITS, 0x03) - - -def test_set_joint_limits_allowed_while_armed_when_new_range_holds_the_ref(offline_arm): - """⚠ "武装中"本身**不是**拒绝理由 —— 判据是"武装 **且** 关不住"。 - - 专防把门禁写成"armed 一律拒": 那样上面那条覆盖用例里的一次 - `set_joint_limits(0, -3.0, 3.0)` (`q[0]=0.05 ∈ [-3,3]`) 会立刻变红, 真机上 - 任何"武装中收窄一个无关轴"的合法用法也都会变成 ERR。 - """ - arm = offline_arm - arm.enable() - arm.movej([0.05] * 7) - arm.params.set_joint_limits(0, q_min=-3.0, q_max=3.0) # 0.05 ∈ [-3,3] ⇒ 放行 - # 不只是"没抛": 读回确认这一笔真的落到了参数表 (ACK 与生效是两件事) - assert arm.params.get_joint_param(0).value.q_min == -3.0 - - -def test_set_joint_limits_gate_precedes_the_value_checks(offline_arm): - """⚠ 桩级 (裸帧): 门禁在 idx / 区间校验**之前** —— 判据只有"门禁"命中的那两格。 - - 固件 `ctrl_axis_outside` 的六条里有**两条只看入参** (① `idx` 越界、② 空区间), - 它们**只在武装态**才成为拒绝理由 (门禁是 `ctrl_is_armed() && ...`): - (a) armed + idx 越界 ⇒ `0x03` (不是值校验那条 `0x02`) - (b) armed + 空区间 ⇒ `0x03` (同上) - - `Arm.params.set_joint_limits` 在本地 (`_check_idx` / `q_min < q_max`) 就把这两格拦掉 - 了, 所以只有直接发裸帧才到得了桩 —— 它钉的是**分支顺序**: 桩原有分支是 - len → idx(0x02) → lo 明确报「固件不支持」而不是含糊的超时。""" - arm = offline_arm - arm.enable() - arm._tr.unknown_cmds.add(P.CMD_HOME) - with pytest.raises(UnsupportedByFirmwareError) as ei: - arm.home() - assert ei.value.cmd == P.CMD_HOME - - -def test_home_no_longer_takes_speed(offline_arm): - """破坏性变更: 速度由固件写死 0.10, speed 参数已移除 (误用须立刻炸)。""" - arm = offline_arm - arm.enable() - with pytest.raises(TypeError): - arm.home(speed=0.3) diff --git a/tests/test_ik_bench.py b/tests/test_ik_bench.py deleted file mode 100644 index f265e6b..0000000 --- a/tests/test_ik_bench.py +++ /dev/null @@ -1,73 +0,0 @@ -"""台架 1J 上的 `ik()` —— 固件 IK 的 seed 恒为 7 轴, 与 `LITEARM_NUM_JOINTS` 解耦。 - -固件 `usb_cmd_dispatch` 的 `case CMD_GET_IK` (`usb_cmd.c:574-575`): - /* pose[6] + q_seed[7] = 52B ... seed 恒为模型 7 轴 (KIN_N), 与 - * LITEARM_NUM_JOINTS 解耦 */ - -而旧 SDK 在 `q_seed=None` 时直接拿 `st.q` 当种子 —— 台架上 `st.q` 只有 1 个元素, -随即在长度校验处抛 `InvalidCommandError("q_seed 需 7 个")`, **台架 IK 完全不可用**。 - -台架那台电机对应模型第 `LITEARM_BENCH_MODEL_AXIS` 轴 (joint_cfg.h: 台架=5, 整臂=0), -故种子应构造为: 7 个 0, 其中台架轴填当前实测值。 -""" -from __future__ import annotations - -import pytest - -from litearm import _protocol as P -from litearm.errors import InvalidCommandError - - -def _ik_payload(arm): - ps = [p for c, p in list(arm._tr.tx_log) if c == P.CMD_GET_IK] - assert ps, "未发出 GET_IK" - return ps[-1] - - -def test_ik_on_bench_sends_seven_axis_seed(offline_arm_1j): - """台架上 ik() 必须能发出 52B 载荷 (pose[6] + seed[7]), 而不是本地就炸。""" - arm = offline_arm_1j - assert arm.n == 1 - q = arm.ik((0.30, 0.0, 0.35, 0.0, 0.0, 0.0)) - assert len(q) == 7 - - p = _ik_payload(arm) - assert len(p) == 52, f"GET_IK 载荷应为 52B, 实为 {len(p)}B" - seed = P.unpack_f32s(p, 24, 7) - assert len(seed) == 7 - - -def test_ik_on_bench_seeds_the_bench_axis_from_feedback(offline_arm_1j): - """台架轴 (LITEARM_BENCH_MODEL_AXIS=5) 的种子应来自实测, 其余轴为 0。""" - arm = offline_arm_1j - arm._tr.q = [0.42] # 台架电机当前位形 - arm.get_state(refresh=True) # 让 SDK 拿到该反馈 - arm.ik((0.30, 0.0, 0.35, 0.0, 0.0, 0.0)) - - seed = P.unpack_f32s(_ik_payload(arm), 24, 7) - assert seed[P.BENCH_MODEL_AXIS] == pytest.approx(0.42, abs=1e-6), \ - "台架轴种子未取自实测反馈" - assert [v for i, v in enumerate(seed) if i != P.BENCH_MODEL_AXIS] == [0.0] * 6 - - -def test_ik_on_full_arm_still_seeds_from_current_q(offline_arm): - """整臂行为不变: 7 关节直接用当前 q 当种子。""" - arm = offline_arm - arm._tr.q = [0.1 * (i + 1) for i in range(7)] - arm.get_state(refresh=True) - arm.ik((0.30, 0.0, 0.35, 0.0, 0.0, 0.0)) - seed = P.unpack_f32s(_ik_payload(arm), 24, 7) - assert seed == pytest.approx([0.1 * (i + 1) for i in range(7)], abs=1e-6) - - -def test_explicit_seed_still_honoured(offline_arm_1j): - arm = offline_arm_1j - my_seed = [0.0, 0.0, 0.0, 0.0, 0.0, 0.9, 0.0] - arm.ik((0.30, 0.0, 0.35, 0.0, 0.0, 0.0), q_seed=my_seed) - assert P.unpack_f32s(_ik_payload(arm), 24, 7) == pytest.approx(my_seed) - - -def test_explicit_seed_must_be_seven(offline_arm_1j): - arm = offline_arm_1j - with pytest.raises(InvalidCommandError): - arm.ik((0.30, 0.0, 0.35, 0.0, 0.0, 0.0), q_seed=[0.1]) diff --git a/tests/test_license.py b/tests/test_license.py deleted file mode 100644 index 17996d9..0000000 --- a/tests/test_license.py +++ /dev/null @@ -1,223 +0,0 @@ -"""授权/激活 (`0x2F` 查询 / `0x3F` 提交) —— 固件 1.8.0 起的开机即锁。 - -固件侧事实 (逐条对着 `litearm-stm32` 源码抄的, 不是转述): - · `ctrl_enable()` 的**第一条**判据是 `!license_is_activated()` -> `0x08` - (`control/control_loop.c:938-946`) ⇒ 未激活时 `ENABLE` 恒被拒, **重发无用、无旁路**; - · `0x2F` 的应答 `RSP_LICENSE(0x4F)` 是 **26B**, 首字节是 `state` 而**不是**冗余帧 id - (`hal/usb_cmd.c:1016-1030`); - · `0x3F` 的失败码除长度 `0x01` 外**一律折成 `0x02`**, 于是"已经激活过"与"真失败" - **同码** (`hal/usb_cmd.c:1067-1079`); - · 激活成功回的是 `ACK{0x3F}`, 不是 `RSP_ACTIVATE(0x50)` —— 后者**本版无生产者**。 - -桩 (`litearm.testing.FakeTransport`) 按同一套顺序建模, 但有一处**结构性**做不到: -它**不验 MAC** —— 桩没有也不该有密钥 (规格: 客户侧不许有能算 MAC 的代码)。 -故"签名不对"只能靠 `license_fail_next` 注入, 而本文件要测的也只是上游那一段判据。 -""" -from __future__ import annotations - -import struct - -import pytest - -import litearm as pa -from litearm import _protocol as P -from litearm.errors import CommandRejectedError, InvalidCommandError, err_reason - -MAC = bytes(range(16)) # 16B; 桩不验内容, 只验长度 - - -def _frames(arm): - return arm._tr.tx_log - - -# --------------------------------------------------------------------------- -# 1. 查询 (`0x2F`) -# --------------------------------------------------------------------------- - -def test_license_reads_the_full_record(offline_arm): - """已激活: 五个字段 + UID 都要读出来。""" - tr = offline_arm._tr - tr.license_cust_id, tr.license_issued, tr.license_flags = 1042, 20260917, 0 - lic = offline_arm.license() - assert isinstance(lic, pa.LicenseInfo) - assert lic.state == 1 and lic.activated is True - assert lic.ver == 1 - assert lic.uid == tr.license_uid - # 签发器要的就是这个形态 —— 逐字节等于设备给的那 12 字节 - assert lic.uid_hex == tr.license_uid.hex() and len(lic.uid_hex) == 24 - assert (lic.cust_id, lic.issued, lic.flags) == (1042, 20260917, 0) - assert lic.factory_mode is False and lic.state_name == "activated" - - -def test_unactivated_is_a_state_not_an_error(offline_arm): - """**未激活不抛异常** —— 它是状态。且**UID 照回**, 其余字段恒 0。 - - 这两条都直接对应固件行为: 未激活时"除 ENABLE 外一切照常"(售后/产线要能诊断), - 且签发器**必须**能从本应答拿到 UID (否则没法给这台机器签)。 - """ - tr = offline_arm._tr - tr.activated = False - tr.license_cust_id, tr.license_issued, tr.license_flags = 999, 20260101, 1 - lic = offline_arm.license() - assert lic.state == 0 and lic.activated is False - assert lic.state_name == "not_activated" - assert lic.uid == tr.license_uid, "未激活也必须回 UID (签发器的唯一来源)" - assert (lic.cust_id, lic.issued, lic.flags) == (0, 0, 0), ( - "未激活时这三格必须是 0 —— 固件靠'调用方预置零'保证, 桩照抄") - - -def test_license_is_deliberately_not_wrapped_in_msg(offline_arm): - """刻意**不**返回 `Msg`(`Msg` 的"刻意不包"清单里有它)—— 别顺手全包。 - - 理由: `RSP_LICENSE` 没有固件发起的流量, 它的 `hz`/`timestamp` 只会度量 - "调用方自己轮询的频率"。 - """ - assert not isinstance(offline_arm.license(), pa.Msg) - - -def test_factory_mode_is_the_flags_bit_not_the_state(offline_arm): - """产线码是 `flags` bit0 ⇒ `state` 报 2; 但它**不**是"激活与否"的判据。""" - offline_arm._tr.license_flags = 0x1 - lic = offline_arm.license() - assert lic.state == 2 and lic.state_name == "activated_factory" - assert lic.activated is True and lic.factory_mode is True - # 反向: 有产线码但未激活 -> state 仍是 0 (桩与固件同口径) - offline_arm._tr.activated = False - lic = offline_arm.license() - assert lic.state == 0 and lic.activated is False - - -def test_unknown_state_carries_the_raw_value(offline_arm): - """认不出的 `state` 码要**带上原值**回, 不许静默折叠。""" - offline_arm._tr.license_ver = 9 - assert offline_arm.license().state_name == "activated" # ver 不参与 state - assert pa.LicenseInfo(state=7, ver=1, uid=b"\x00" * 12, cust_id=0, - issued=0, flags=0).state_name == "unknown_state_7" - - -# --------------------------------------------------------------------------- -# 2. 开机即锁 (`ERR{0x10,0x08}`) -# --------------------------------------------------------------------------- - -def test_unactivated_enable_is_rejected_with_the_license_code(offline_arm): - """未激活时 `enable()` 抛 `ERR{0x10,0x08}`, 且**只发一条**(重发无用)。""" - offline_arm._tr.activated = False - with pytest.raises(CommandRejectedError) as ei: - offline_arm.enable() - e = ei.value - assert (e.cmd, e.code) == (0x10, 0x08) - # 0x08 **不在**重试白名单 (`ENABLE_RETRYABLE_CODES`) ⇒ 不该有第二次尝试 - assert len([f for f in _frames(offline_arm) if f[0] == P.CMD_ENABLE]) == 1, ( - "0x08 被重试了 —— 它是'这台臂没被授权', 重发无用") - assert "未激活" in str(e) and "activate" in str(e), ( - "报错没把补救路径说清楚 (用户看到的应当是'未激活', 不是'未登记错误码')") - - -def test_activation_unlocks_enable(offline_arm): - """对照组: 激活之后同一条 `enable()` 就通了 —— 锁确实挂在 license 上。""" - tr = offline_arm._tr - tr.activated = False - with pytest.raises(CommandRejectedError): - offline_arm.enable() - offline_arm.activate(cust_id=7, issued=20260922, mac=MAC) - offline_arm.enable() - assert tr.enabled is True - - -# --------------------------------------------------------------------------- -# 3. 提交 (`0x3F`) -# --------------------------------------------------------------------------- - -def test_activate_sends_the_28_byte_payload_and_lands(offline_arm): - """载荷 = `cust_id LE + issued LE + flags LE + mac[16]`, 且**设备侧真的落位**。""" - tr = offline_arm._tr - tr.activated = False - offline_arm.activate(cust_id=1042, issued=20260917, mac=MAC) - at = [f for f in _frames(offline_arm) if f[0] == P.CMD_ACTIVATE] - assert len(at) == 1 - payload = at[0][1] - assert len(payload) == 28 - assert struct.unpack_from(" `ERR{0x3F,0x04}`(与 `save_params` 同语义)。 - - ⚠ 这个场景**只能是"已激活"的机器**: 未激活的机器根本使能不了(`ERR{0x10,0x08}`) - ⇒ 现实里撞上本码的正是"拿同一份凭据再提交一次、而臂正被使能着"。 - 门禁顺序也照固件: **武装判据排在"已经激活过"之前**(`usb_cmd.c:1035` 早于 - `license_activate()` 里的 EXISTS 判据)—— 故这台机器回的是 0x04, 不是 0x02。 - """ - tr = offline_arm._tr - assert tr.activated is True - offline_arm.enable() - assert tr.enabled is True - with pytest.raises(CommandRejectedError) as ei: - offline_arm.activate(cust_id=1, issued=20260922, mac=MAC) - assert (ei.value.cmd, ei.value.code) == (0x3F, 0x04) - - -def test_local_prechecks_reject_before_any_frame_goes_out(offline_arm): - """两条本地预检 —— 关键是**帧没发**(否则会撞上聚合档 0x02, 归因变模糊)。""" - for kwargs, needle in ( - (dict(cust_id=1, issued=20260922, flags=0x2, mac=MAC), "flags"), - (dict(cust_id=1, issued=20260922, mac=MAC[:-1]), "16 字节"), - ): - before = len(_frames(offline_arm)) - with pytest.raises(InvalidCommandError) as ei: - offline_arm.activate(**kwargs) - assert needle in str(ei.value) - assert len(_frames(offline_arm)) == before, "本地预检失败却把帧发出去了" - - -def test_activate_0x02_on_an_already_activated_device_is_not_a_failure(offline_arm): - """⚠⚠ **本文件最重要的一条**: `0x02` 是聚合档, 不能光看码判失败。 - - 形态: 上一条 ACK 被丢掉后重发 —— 设备**已经激活**, 故回 `0x02`, 而它其实成功了。 - 若照着码号抛异常, 产线会把一台**已经解锁**的机器当成激活失败去返工。 - 正确动作 (厂商侧工具同款): 回读 `0x2F`, 看 `state != 0`。 - """ - tr = offline_arm._tr - assert tr.activated is True # 已经是激活态 - offline_arm.activate(cust_id=1042, issued=20260917, mac=MAC) - # 没抛 => 认出了"其实已经激活" - at = [f for f in _frames(offline_arm) if f[0] == P.CMD_ACTIVATE] - lic_queries = [f for f in _frames(offline_arm) if f[0] == P.CMD_GET_LICENSE] - assert len(at) == 1 and len(lic_queries) >= 1, ( - "0x02 之后没有回读 —— 那就不可能区分'已激活'与'真失败'") - - -def test_activate_0x02_on_a_genuine_failure_still_raises(offline_arm): - """**同一档码的对照**: 设备确实没激活时, `0x02` 必须抛 —— 否则就是静默失败。""" - tr = offline_arm._tr - tr.activated = False - tr.license_fail_next = True # 模拟 MAC 不符 / 密钥非法 / 写失败 - with pytest.raises(CommandRejectedError) as ei: - offline_arm.activate(cust_id=1, issued=20260922, mac=MAC) - assert (ei.value.cmd, ei.value.code) == (0x3F, 0x02) - assert tr.activated is False - assert [f for f in _frames(offline_arm) if f[0] == P.CMD_GET_LICENSE], ( - "判'真失败'之前也必须先回读过 —— 两条路径的回读是同一个动作") - - -# --------------------------------------------------------------------------- -# 4. 错误码文本 (用户真正读到的那句话) -# --------------------------------------------------------------------------- - -def test_err_text_names_the_remedy_for_the_two_license_codes(): - """`0x10/0x08` 与 `0x3F/0x02` 的文本必须**可执行**, 而不是"未登记"。 - - 这两条是用户可见性最强的一对: 前者是"每台未激活的机器一开机就撞"的码, - 后者是最容易被误判成失败的那个聚合档。 - """ - blocked = err_reason(0x10, 0x08) - assert "未激活" in blocked and "activate" in blocked - assert "旁路" in blocked, "没写清'不得加旁路'这条规格硬要求" - agg = err_reason(0x3F, 0x02) - assert "回查" in agg and "0x2F" in agg - assert "已经激活" in agg, "没提醒'可能其实已经解锁'这个陷阱" diff --git a/tests/test_lifecycle.py b/tests/test_lifecycle.py deleted file mode 100644 index 96cf326..0000000 --- a/tests/test_lifecycle.py +++ /dev/null @@ -1,179 +0,0 @@ -"""生命周期与关链时序 —— 保活线程引入的并发面。 - -零重力保活是本 SDK 唯一的后台线程, 它的启停必须能经受"另一个线程恰好在错误时刻 -插进来"以及"串口写卡住"这两种真实情况 —— 否则后果不是报错, 而是**静默失效**: -`zero_g_active` 说谎、所有动作命令被守卫永久拒绝、或者迟到的保活帧把臂重新拉回 -零重力却无人维持 (0.1s 后被看门狗掐掉)。 -""" -from __future__ import annotations - -import threading -import time - -import pytest - -from litearm import _protocol as P -from litearm.errors import TransportError - - -def _zg_payloads(arm): - return [p for c, p in list(arm._tr.tx_log) if c == P.CMD_ZERO_G] - - -def _zg_stamps(arm): - return arm._tr.stamps_of(P.CMD_ZERO_G) - - -# --------------------------------------------------------- P1-1 启停竞态 -def test_stop_never_joins_an_unstarted_thread(offline_arm): - """`zero_g_stop` 只能 join **真正跑起来**的线程。 - - 对未启动的 Thread 调 `join()` 会抛 `RuntimeError: cannot join thread before it - is started`; 旧实现把 join 放在置 `_zg_active=False` **之前**, 异常一抛 - `_zg_active` 就永久停在 True —— 保活一帧不发, 而所有动作命令被守卫永久拒绝。 - 这个状态可以由 `zero_g_start` 的「发布句柄 → start()」窗口被 `zero_g_stop` - 插进来触发, 也可能是任何异常路径的残留。 - """ - arm = offline_arm - arm._zg_thread = threading.Thread(target=lambda: None) # 故意不 start - arm._zg_active = True - arm.zero_g_stop() - assert arm.zero_g_active is False, "zero_g_active 卡在 True -> 守卫会永久拒绝动作命令" - assert arm._zg_thread is None - - -def test_concurrent_start_stop_storm_never_wedges(offline_arm): - """反复并发 start/stop: 任意交错顺序下都不得抛异常、不得把状态卡住、不得漏线程。""" - arm = offline_arm - errors = [] - - for _ in range(15): - def starter(): - try: - arm.zero_g_start() - except Exception as e: # noqa: BLE001 - errors.append(("start", e)) - - def stopper(): - try: - arm.zero_g_stop() - except Exception as e: # noqa: BLE001 - errors.append(("stop", e)) - - t1 = threading.Thread(target=starter) - t2 = threading.Thread(target=stopper) - t1.start() - t2.start() - t1.join(5.0) - t2.join(5.0) - arm.zero_g_stop() # 收尾: 归一化终态 - assert arm.zero_g_active is False, f"第 {_} 轮后状态卡住" - - assert not errors, f"并发启停抛了异常: {errors}" - assert not [t for t in threading.enumerate() if t.name.startswith("litearm-zero_g")], \ - "并发启停泄漏了保活线程" - payloads = _zg_payloads(arm) - assert not payloads or payloads[-1] == b"\x00", f"0x06 序列以 on 结尾: {payloads}" - - -# ------------------------------------------------- P1-2 join 超时的迟到帧 -def test_stop_refuses_to_send_off_when_keepalive_thread_wont_die(offline_arm): - """保活线程卡在写里 (CDC 阻塞) 停不下来时, **绝不能发 off 帧**。 - - 否则迟到的 `0x06(on=1)` 会排在 off 之后抵达固件 —— 臂被重新拉进零重力模式 - 却已无人维持 (0.1s 后 fail-soft), 而 SDK 认为"已退出", 紧接着发的 movej - 会与它互相打架。正确做法是报错并把问题暴露出来。 - """ - arm = offline_arm - arm._zg_join_s = 0.10 - arm._tr.zg_slow_write_s = 0.6 # 每次保活写都卡 0.6s - arm.zero_g_start(period=0.01) - time.sleep(0.15) - with pytest.raises(TransportError): - arm.zero_g_stop() - assert _zg_payloads(arm)[-1] == b"\x01", "卡死的保活线程未被等停, 却仍发了 off 帧" - assert arm.zero_g_active is False - - -def test_close_after_stuck_keepalive_still_returns(offline_arm): - """即便保活线程卡住, close() 也必须能返回并把链路关掉 (teardown 不能挂死)。""" - arm = offline_arm - arm._zg_join_s = 0.10 - arm._tr.zg_slow_write_s = 0.4 - arm.zero_g_start(period=0.01) - time.sleep(0.1) - t0 = time.monotonic() - arm.close() - assert time.monotonic() - t0 < 3.0 - assert arm.zero_g_active is False - - -# --------------------------------------------------------- 保活间隔不变量 -def test_keepalive_gap_stays_under_watchdog(offline_arm): - """真正该守的不变量是**相邻保活帧间隔** < 固件看门狗 0.10s, 不是"发了几次"。 - - 只数帧数的话, 一旦某次写卡了 0.12s, 固件看门狗已经跳闸, 而计数断言照样通过。 - """ - arm = offline_arm - with arm.zero_g(): - time.sleep(0.45) - ts = _zg_stamps(arm) - ons = [t for (c, p), t in zip(arm._tr.tx_log, arm._tr.tx_stamps) - if c == P.CMD_ZERO_G and p == b"\x01"] - assert len(ons) >= 4, f"保活帧太少: {len(ons)}" - gaps = [b - a for a, b in zip(ons, ons[1:])] - assert max(gaps) < 0.08, ( - f"相邻保活帧最大间隔 {max(gaps) * 1000:.0f}ms —— 固件看门狗 100ms, 会跳闸") - assert ts == sorted(ts) - - -# ------------------------------------------------- zero_g_error 文档一致性 -def test_zero_g_error_is_cleared_by_stop(offline_arm): - """`zero_g_error` 的文档说 stop 会消费清空它 —— 实现必须一致。""" - arm = offline_arm - arm._tr.zg_fail_after = 1 - with pytest.raises(TransportError): - with arm.zero_g(): - time.sleep(0.20) - assert arm.zero_g_error is None - - -# ------------------------------------------------- 传输层共享态 -def test_text_log_is_read_under_lock(monkeypatch): - """`text_log` 读的是读者线程正在改的 `_text` —— 必须与其它共享态同口径加锁。""" - import sys - import types - from litearm.transport import SerialTransport - - class FakeSerial: - def __init__(self, port, baudrate=0, timeout=0.2, **kw): - self.is_open = True - self.timeout = timeout - - def read(self, size=1): - return b"" - - def write(self, d): - return len(d) - - def flush(self): - pass - - def close(self): - self.is_open = False - - monkeypatch.setitem(sys.modules, "serial", types.SimpleNamespace(Serial=FakeSerial)) - tr = SerialTransport("/dev/null") - seen = [] - - def reader(): - for _ in range(300): - tr.read_frame(0.001) - seen.append(tr.text_log) - - th = threading.Thread(target=reader) - th.start() - for i in range(300): - tr._note_text(0x41) - th.join() - assert seen, "未取到 text_log" diff --git a/tests/test_live.py b/tests/test_live.py deleted file mode 100644 index b41a283..0000000 --- a/tests/test_live.py +++ /dev/null @@ -1,41 +0,0 @@ -"""真机 live 用例 —— 需 LITEARM_LIVE=1 + 接好 Litearm1.5.0+ 整臂(或台架)。 - -风险自担: 会 enable 并小幅 move_j (当前姿态 +小量, 不影响他人/障碍时跑)。 -""" -from __future__ import annotations - -import pytest - -from litearm import Arm - - -def test_live_connect_read(live_only): - arm = Arm().connect() - try: - assert arm.firmware.startswith("Litearm") - assert arm.n in (1, 7) - assert arm.get_state().value is not None - assert arm.get_tcp().value is not None - finally: - arm.close() - - -def test_live_movej_tcp_ik(live_only): - arm = Arm().connect() - try: - arm.enable() - st = arm.get_state().value - tgt = list(st.q) - idx = 5 if arm.n == 7 else 0 - tgt[idx] += 0.04 if idx == 5 else 0.10 - arm.movej(tgt, speed=0.2) - st2 = arm.get_state().value - assert all(abs(st2.q[i] - tgt[i]) < 0.06 for i in range(arm.n)) - tcp = arm.get_tcp().value - assert tcp is not None - arm.disable() - finally: - try: - arm.disable() - finally: - arm.close() diff --git a/tests/test_log.py b/tests/test_log.py deleted file mode 100644 index 4fc76f9..0000000 --- a/tests/test_log.py +++ /dev/null @@ -1,161 +0,0 @@ -"""300Hz 控制拍采集 (固件 0x2D/0x2E + RSP_LOG_DATA 0x4D) —— 此前 SDK 无任何入口。 - -固件侧 (`hal/log_capture.h` + `usb_cmd_dispatch` 的 `case CMD_LOG_CTRL`/`CMD_LOG_READ`, -`usb_cmd.c:960-984`): - 0x2D LOG_CTRL : u32 n_ticks(f32? 否 —— u32 LE); 0=停/清; n>LOG_MAX_SAMPLES(2400) -> ERR{0x2D,0x02} - 0x2E LOG_READ : u32 offset_byte LE -> RSP_LOG_DATA(0x4D) - data = [u32 total_bytes][u32 next_byte][u8 n][bytes n], n<=245; - **next_byte == 0 表示读完** (掉帧时按 next_byte 续读) - 样本布局 : u32 tick + q_ref[N]f32 + dq[N]f32 + tau[N]f32 = 4 + 12N B (7J = 88B) -""" -from __future__ import annotations - -import struct - -import pytest - -from litearm import _protocol as P -from litearm.errors import ( - CommandRejectedError, - MotionTimeoutError, - TransportError, - UnsupportedByFirmwareError, -) - - -def _payloads(arm, cmd): - return [p for c, p in list(arm._tr.tx_log) if c == cmd] - - -def test_start_sends_n_ticks_as_u32_le(offline_arm): - arm = offline_arm - arm.log.start(600) - ps = _payloads(arm, P.CMD_LOG_CTRL) - assert len(ps) == 1 and len(ps[0]) == 4 - assert struct.unpack_from(" 必须按游标重试, 而不是丢一段数据。""" - arm = offline_arm - arm.log.start(600) - arm._tr.log_read_fail_once = True - r = arm.log.reader(timeout=0.05, retries=3) - assert r.read_all() == arm._tr.log_bytes - - -def test_reader_on_empty_log_returns_nothing(offline_arm): - arm = offline_arm - arm.log.stop() # n=0: 停/清 - assert arm.log.reader().read_all() == b"" - - -def test_truncated_blob_is_rejected(offline_arm): - """字节数不是样本整数倍 -> 明确报错, 不能悄悄解析出半截样本。""" - arm = offline_arm - arm.log.start(10) - arm._tr.log_bytes = arm._tr.log_bytes[:-3] # 截断到非整数倍 - with pytest.raises(TransportError): - arm.log.reader().samples() - - -def test_dump_writes_raw_bytes(offline_arm, tmp_path): - arm = offline_arm - arm.log.start(20) - out = tmp_path / "cap.bin" - arm.log.dump(str(out)) - assert out.read_bytes() == arm._tr.log_bytes - - -def test_capture_waits_until_recording_completes(offline_arm): - """固件是**逐拍**记录的 (300Hz, `log_capture_tick` 一拍一条): - - log_capture_start(600) 之后缓冲里是空的, 要 2 秒才录满。 - - `capture(n)` 若 start() 后立刻读回, 只能拿到 0 或一个前缀 —— 必须等到录满。 - """ - arm = offline_arm - arm._tr.log_hz = 2000.0 # 2000 拍/秒 -> 600 拍约 0.3s 录满 - samples = arm.log.capture(600, record_timeout=5.0) - assert len(samples) == 600, ( - f"只拿到 {len(samples)}/600 拍 —— capture() 没等固件录满就读回了") - assert [s.tick for s in samples] == list(range(600)) - - -def test_dump_waits_for_the_started_capture(offline_arm, tmp_path): - """`start(200)` 后立刻 dump -> 不能落盘一个空/半截文件 (同一类逐拍记录陷阱)。""" - arm = offline_arm - arm._tr.log_hz = 2000.0 # 200 拍约 0.1s 录满 - arm.log.start(200) - out = tmp_path / "c.bin" - arm.log.dump(str(out)) - assert len(out.read_bytes()) == 200 * (4 + 12 * arm.n) - - -def test_dump_can_skip_waiting_explicitly(offline_arm, tmp_path): - """要读"此刻已录到多少"时, 显式关掉等待。""" - arm = offline_arm - arm._tr.log_hz = 20.0 # 200 拍要 10s; 不等 -> 立刻读只能拿到前缀 - arm.log.start(200) - out = tmp_path / "c.bin" - arm.log.dump(str(out), wait=False) - assert len(out.read_bytes()) < 200 * (4 + 12 * arm.n), "不该已经录满""" - - -def test_capture_raises_when_recording_never_finishes(offline_arm): - """录不满必须报错, 不能返回半截数据冒充成功。""" - arm = offline_arm - arm._tr.log_hz = 5.0 # 5 拍/秒 -> 600 拍要 120s, 必然等不满 - with pytest.raises(MotionTimeoutError) as ei: - arm.log.capture(600, record_timeout=0.3) - assert "600" in str(ei.value) - - -def test_reader_rejects_non_advancing_cursor(offline_arm): - """固件回 `next_byte == offset` (无进展) 时必须报错 —— 否则读者死循环。""" - arm = offline_arm - arm.log.start(10) - arm._tr.log_cursor_stuck = True - with pytest.raises(TransportError): - arm.log.reader().read_all() - - -def test_log_unsupported_on_old_firmware(offline_arm): - arm = offline_arm - arm._tr.unknown_cmds.add(P.CMD_LOG_CTRL) - with pytest.raises(UnsupportedByFirmwareError): - arm.log.start(10) diff --git a/tests/test_model.py b/tests/test_model.py deleted file mode 100644 index 6b59e9a..0000000 --- a/tests/test_model.py +++ /dev/null @@ -1,237 +0,0 @@ -"""动力学模型在线导入 (固件 0x30/0x32/0x33/0x34/0x35/0x37/0x38/0x39) 的 SDK 侧用例。 - -分层: - - 帧格式/载荷长度/错误码映射 —— 与 `fake_serial.FakeTransport` 对拍 - - `probe()` 的能力判定 —— **必须用 0x34**, 不能用 0x30/0x33 (旧固件对后者有显式 case, - 回 `0x02` 而非 `0x00`, 无法区分「无此命令」与「参数非法」) - - `commit` 的掩码语义 (掩码不符 -> 0x07; 已武装 -> 0x04) - - `MODEL_MASK_WRITTEN == 0x2FE` 的跨仓契约 -""" -from __future__ import annotations - -import struct - -import pytest - -from litearm import _protocol as P -from litearm.errors import (CommandRejectedError, InvalidCommandError, - UnsupportedByFirmwareError) -from litearm.model import (MODEL_BODY_PARAMS, MODEL_MASK_WRITTEN, MODEL_NBODY, - ModelParams, ModelStatus) - -BODY1 = [1.0, 0.01, 0.02, 0.03, -1.1, 0.02, -0.03, -0.01, 0.01, -1.2] -JM = [0.0, 0.0, -0.0188174839, -0.0236409545, -0.00612815024, -0.0196070617, -0.0142279878] - - -def test_mask_contract(): - """跨仓契约: 写 body1..7 + jm = 0x2FE (固件 `T_DIRTY_ALL & ~(1|1<<8)` 同值)。""" - assert MODEL_MASK_WRITTEN == 0x2FE - assert MODEL_NBODY == 9 - assert MODEL_BODY_PARAMS == 10 - - -def test_get_body_frame_roundtrip(offline_arm): - arm = offline_arm - arm.connect() - v = arm.model.get_body(1).value - assert len(v) == MODEL_BODY_PARAMS - # fake 固件的初始 body1 = [1,0,...,0] - assert v[0] == pytest.approx(1.0) - assert all(x == pytest.approx(0.0) for x in v[1:]) - - -def test_set_get_body_roundtrip_and_staging(offline_arm): - """写 staging 不生效; commit 后才读得到 —— 与固件的 bank/staging 分层一致。""" - arm = offline_arm - arm.connect() - arm.model.set_body(1, BODY1) - assert arm.model.get_body(1).value[0] == pytest.approx(1.0), "commit 前 bank 不应变" - arm.model.commit(1 << 1) - got = arm.model.get_body(1).value - for a, b in zip(got, BODY1): - assert a == pytest.approx(b), "commit 后 bank 应等于写入值" - - -def test_set_body_rejects_bad_arity(offline_arm): - arm = offline_arm - arm.connect() - with pytest.raises(InvalidCommandError): - arm.model.set_body(1, [1.0, 0.0]) # 少于 10 个 - with pytest.raises(InvalidCommandError): - arm.model.set_body(9, BODY1) # 索引越界 (恒 9 刚体, 与 arm.n 无关) - with pytest.raises(InvalidCommandError): - arm.model.get_body(9) - - -def test_body_idx_bound_is_model_nbody_not_arm_n(offline_arm_1j): - """**台架 1J 上模型仍是 9 刚体** —— 判据不能掺 `arm.n`。 - - 若照抄 `JointParams._check_idx` (用 `arm.n` 做上界), 台架上 `set_body(1)` 会被 - SDK 自己拦掉, 于是台架完全无法验证模型 (而固件在台架上确实支持 9 刚体)。 - """ - arm = offline_arm_1j - arm.connect() - assert arm.n == 1 - arm.model.set_body(8, [0.0] * MODEL_BODY_PARAMS) # body8 合法 (ee 固定体) - assert arm.model.get_body(8).value is not None - - -def test_jm_roundtrip(offline_arm): - arm = offline_arm - arm.connect() - assert arm.model.get_jm().value == pytest.approx([0.0] * 7) - arm.model.set_jm(JM) - arm.model.commit(1 << 9) - assert arm.model.get_jm().value == pytest.approx(JM) - with pytest.raises(InvalidCommandError): - arm.model.set_jm([0.0] * 6) - - -def test_commit_mask_mismatch_is_0x07(offline_arm): - """掩码不符 -> 独立码 0x07 (不是与"数值非法"混用的 0x02)。""" - arm = offline_arm - arm.connect() - for i in range(1, 8): - arm.model.set_body(i, BODY1) - arm.model.set_jm(JM) - with pytest.raises(CommandRejectedError) as ei: - arm.model.commit(0x002) # 只声明了 body1, 实际写了 0x2FE - assert ei.value.code == 0x07 - - -def test_commit_requires_disabled(offline_arm): - """commit 要求失能 (固件判据 ctrl_is_armed) -> 0x04。""" - arm = offline_arm - arm.connect() - arm.enable() - arm.model.set_body(1, BODY1) - with pytest.raises(CommandRejectedError) as ei: - arm.model.commit(1 << 1) - assert ei.value.code == 0x04 - - -def test_revert_requires_disabled_and_clears_override(offline_arm): - arm = offline_arm - arm.connect() - arm.model.set_body(1, BODY1) - arm.model.commit(1 << 1) - assert arm.model.status().value.override == 1 - - arm.enable() - with pytest.raises(CommandRejectedError) as ei: - arm.model.revert() - assert ei.value.code == 0x04 - - arm.disable() - arm.model.revert() - st = arm.model.status().value - assert st.override == 0 - assert st.staged_mask == 0 - - -def test_status_fields(offline_arm): - arm = offline_arm - arm.connect() - arm.model.set_body(3, BODY1) # staging 置位, 未 commit - st = arm.model.status().value - assert isinstance(st, ModelStatus) - assert st.override == 0 - assert st.staged_mask == (1 << 3) - assert st.dirty == 1 - - -def test_get_gravity_frame(offline_arm): - arm = offline_arm - arm.connect() - g = arm.model.get_gravity([0.0] * 7).value - assert len(g) == 7 - with pytest.raises(InvalidCommandError): - arm.model.get_gravity([0.0] * 6) - - -def test_probe_true_on_modern_firmware(offline_arm): - arm = offline_arm - arm.connect() - assert arm.model.probe() is True - - -def test_probe_false_on_old_firmware(offline_arm): - """旧固件: 0x34 没有 case -> 落 default -> ERR{0x34,0x00} -> probe() 回 False。 - - ⚠ 这条正是「不能用 0x30/0x33 探测」的理由: 旧固件对它们有**显式 case** 回 0x02, - SDK 无法据此判定"无此命令"。用 0x34 才有稳定的 0x00 哨兵。 - """ - arm = offline_arm - arm.connect() - arm._tr.unknown_cmds.add(P.CMD_GET_MODEL_PARAM) # 模拟旧固件的 default 分支 - assert arm.model.probe() is False - with pytest.raises(UnsupportedByFirmwareError): - arm.model.get_body(0) - - -def test_commit_encodes_u16_le(offline_arm): - """`expected_mask` 必须是 2 字节小端 —— 写成 `bytes([mask])` 会截断成 1B。""" - arm = offline_arm - arm.connect() - arm.model.set_body(1, BODY1) # 只写 1 个 body + jm ⇒ 声明匹配的掩码 - arm.model.set_jm(JM) - arm.model.commit((1 << 1) | (1 << 9)) - frames = [p for c, p in arm._tr.tx_log if c == P.CMD_MODEL_COMMIT] - assert frames, "未发出 0x32" - assert len(frames[-1]) == 2, f"0x32 载荷应 2B, 实得 {len(frames[-1])}B" - assert struct.unpack_from("=` 而不是 `>`: `get_state()` 的缓存分支**不取帧** ⇒ 两次回的是同一帧的时刻。 - """ - a = call(offline_arm) - time.sleep(0.002) - b = call(offline_arm) - - assert b.timestamp >= a.timestamp, f"{name}: timestamp 回退了" - assert b.timestamp > 0.0, f"{name}: timestamp 没被填 (哨兵 0.0 只表示'从没收到过')" - - -def test_timestamp_is_a_local_monotonic_reading(offline_arm): - arm = offline_arm - before = time.monotonic() - m = arm.get_state(refresh=True) - after = time.monotonic() - assert before <= m.timestamp <= after, ( - "timestamp 必须是本机 time.monotonic() (段一到三全库用的都是它)") - - -# --------------------------------------------------------------------------- -# 3. hz —— 分母是"实际到达的间隔" -# --------------------------------------------------------------------------- - -def test_recv_stats_formula_is_exact_on_a_synthetic_clock(offline_arm): - """**公式的**判据 (确定性, 不靠真实时钟): `(count-1)/(last-first)`。 - - 直接喂 `_note_recv` —— 这是唯一能把"分母是什么"钉死的测法: 真实时钟下只能断言一个 - 带宽度的区间。 - """ - a = offline_arm._a - for t in (10.0, 10.5, 11.0, 11.5): # 4 帧, 间隔 0.5s - a._note_recv(P.RSP_FF_VEC, t) - - hz, ts = a.recv_stats(P.RSP_FF_VEC) - assert hz == pytest.approx(3 / 1.5), "分母不是 (last-first) —— 公式变了" - assert ts == 11.5, "timestamp 不是**最近一帧**的时刻" - - -def test_recv_stats_is_zero_below_two_samples_and_for_unseen_ids(offline_arm): - a = offline_arm._a - - assert a.recv_stats(P.RSP_TCP) == (0.0, 0.0), "没收到过该类帧时该是 (0.0, 0.0) 哨兵" - a._note_recv(P.RSP_TCP, 5.0) - hz, ts = a.recv_stats(P.RSP_TCP) - assert (hz, ts) == (0.0, 5.0), "一个样本定不出频率 ⇒ hz 写死 0.0, 但 timestamp 照给" - - -def test_hz_of_a_single_frame_getter_needs_a_second_call(offline_arm): - """单发请求/应答式那几个: 第一次 `hz == 0.0`, 第二次起非 0。 - - 它们的"到达率"**就是调用方自己的轮询频率** (一次调用只到一个帧) —— 所以判据只能 - 这么写, `hz > 0` 那条通不过第一次调用。 - - ⚠ **`diag.kin_bench` 从前在名单里, 现在不在** —— 它的回执是**连续两帧** - (耗时帧 + LINK 帧, 见 `diagnostics._KIN_BENCH_FRAMES`), 一次调用到达 2 帧。 - 于是 `hz` 第一次就非 0, 且那个数**没有意义**: 分子被拆帧放大 (2 而不是 1), - 分母仍是调用间隔。**它对 `kin_bench` 从来就不是"到达率"** —— 收窄成单帧那会儿 - 它恰好等于轮询频率, 那是巧合, 不是语义。 - """ - arm = offline_arm - for name, call in [ - ("params.get_joint_param", lambda: arm.params.get_joint_param(0)), - ("model.get_body", lambda: arm.model.get_body(0)), - ("model.get_jm", lambda: arm.model.get_jm()), - ("model.get_gravity", lambda: arm.model.get_gravity([0.0] * 7)), - ]: - assert call().hz == 0.0, f"{name}: 第一次调用 (只有一个样本) 的 hz 该是 0.0" - time.sleep(0.002) - assert call().hz > 0.0, f"{name}: 第二次调用之后 hz 仍是 0 —— 接收表没在记" - - -def test_hz_of_the_passive_status_stream_tracks_the_arrival_cadence(offline_arm): - """被动连续流那一支: **到达节奏 20ms** ⇒ `hz` ≈ 50。 - - ⚠ **[2026-09-22] 节奏的**来源**变了**:从前"20ms 一帧"靠**调用方**每 20ms 读一次 - 造出来(那正是"读驱动时间");现在帧由**读线程**按桩的节拍收进来 ⇒ 节奏由 - `FakeTransport.auto_status_period` 决定。所以这里显式把它设成 20ms,判据(hz≈50) - 与区间含义都不变,变的是**谁决定节奏**。 - ⚠ 判据仍是**区间**而不是定值 (真实时钟下做不到确定): 上界 100 排除"写死一个 100Hz" - 那种假实现, 下界 10 容忍宿主机卡顿。 - """ - arm = offline_arm - arm._tr.auto_status_period = 0.02 # ⇒ 50Hz 的被动流 - time.sleep(0.12) # 攒够样本 - - hz = arm.get_state(refresh=True).hz - assert 10.0 < hz < 100.0, f"状态帧的 hz={hz} 不在按 20ms 采样应有的区间里" - - -def test_hz_uses_only_arrivals_of_that_type(offline_arm): - """`hz` 是 **per-type** 的: 别的帧到得再多, 也不该改这一类帧的统计。 - - ⚠ 判据用 `recv_stats` 而不是"再调一次 getter 看 hz": 后者会把**自己**那一类的样本 - 从 1 条加到 2 条, 于是无论 per-type 有没有失效都变成"hz > 0" —— 那是条假绿。 - """ - arm = offline_arm - for _ in range(3): # 灌一堆 RSP_TCP 与状态帧 - arm.get_tcp() - arm.get_status_now() - - assert arm._a.recv_stats(P.RSP_MODEL_JM) == (0.0, 0.0), ( - "别的帧类型污染了本类帧的统计 (per-type 失效)") - assert arm._a.recv_stats(P.RSP_TCP)[0] > 0.0, "RSP_TCP 自己反倒没统计上" - - arm.model.get_jm() # 真调一次: 现在只有**这一类**动了 - time.sleep(0.002) - assert arm.model.get_jm().hz > 0.0 - - -# --------------------------------------------------------------------------- -# 4. hz 的载体**不是** `unexpected_frames` (§6.6 第 6 轮订正) -# --------------------------------------------------------------------------- - -def test_status_frames_produce_hz_while_the_dropped_counter_stays_zero(offline_arm): - """状态帧给出 `hz`, 却**永远不会**让 `dropped` +1 —— 它走单槽、不进队列。""" - arm = offline_arm - arm.get_state(refresh=True) - time.sleep(0.002) - m = arm.get_state(refresh=True) - - assert m.hz > 0.0, "状态帧的 hz 是 0 ⇒ 统计没发生" - # ⚠ 状态帧走**单槽**(不进队列)⇒ 它永远不会被封顶挤掉。 - assert arm._a.dropped == 0, "状态帧被计成了丢弃" - - -def test_unrecognized_frames_are_queued_not_dropped_and_get_their_own_hz(offline_arm): - """未识别帧进**它自己那条队列**等着(不丢), 在接收表里也只记在**它自己**那个 id 下。 - - ⚠ 重构把 `unexpected_frames` / `foreign_frames` 合并成 `dropped`,且**只在队列封顶时** - 递增 —— 一条没人认领的未知帧**进队列等着**,不计丢弃。「不丢」才是设计。 - """ - arm = offline_arm - for _ in range(3): - arm._tr._push(P.pack_frame(UNKNOWN_ID)) - - for _ in range(200): # 等读线程把它们收进来 - if len(arm._a._queues.get((UNKNOWN_ID, None), [])) >= 3: - break - time.sleep(0.002) - - assert len(arm._a._queues.get((UNKNOWN_ID, None), [])) == 3, "未识别帧没进队列" - assert arm._a.dropped == 0, "没人认领 ≠ 丢弃 (队列远没到封顶)" - assert arm._a.recv_stats(UNKNOWN_ID)[1] > 0.0, "接收表没记它 (两份统计应当各记各的)" - assert arm._a.recv_stats(P.RSP_MODEL_JM) == (0.0, 0.0), ( - "未识别帧漏进了某一类真帧的 hz") - - -def test_normal_replies_of_ids_outside_known_rsp_ids_are_not_counted(offline_arm): - """`RSP_GRAVITY(0x57)` 的**正常应答**进它自己那条队列、被主人取走 —— - 既不计丢弃, 也照记进接收表 (`hz` 非 0)。""" - arm = offline_arm - arm.model.get_gravity([0.0] * 7) - time.sleep(0.002) - m = arm.model.get_gravity([0.0] * 7) - - assert m.hz > 0.0, "RSP_GRAVITY 没进接收表" - assert arm._a.dropped == 0, "正常应答被计成了丢弃" - - -def test_the_reception_table_records_every_arriving_frame_including_0x4e(offline_arm): - """`0x4E` 被收集器认领**之前**就已经进接收表 —— 统计的是"到达", 与归谁认领无关。""" - arm = offline_arm - assert P.RSP_CART_PLAN not in arm._a._recv - arm._cart.register() - arm._tr._resp.clear() - arm._tr.push_frame(P.RSP_CART_PLAN, bytes([1, 0]) + (12).to_bytes(2, "little") - + (4700).to_bytes(4, "little")) - - # ⚠ `poll_cart()` 不再驱动取帧(读线程是唯一读者)⇒ 必须先等读线程把它投递出去, - # 再让 `poll_cart` 去收集器认领。少了这一步,测的是"谁先跑"而不是接收表。 - for _ in range(200): - if P.RSP_CART_PLAN in arm._a._recv: - break - time.sleep(0.002) - - assert arm.poll_cart() is not None, "桩这条规划应答没被认领 (用例前提不成立)" - assert P.RSP_CART_PLAN in arm._a._recv, ( - "被收集器吃掉的帧没进接收表 —— 说明记录排在收集器分支之后了") - - -def test_the_reception_table_resets_with_the_session(offline_arm): - """接收表与 `_Ack` 同寿 ⇒ `reconnect()` 之后统计从零开始 (不是跨会话累计)。 - - ⚠ 判据不能写成"重连后第一次读的 `hz == 0.0`": `connect()` 的握手**自己就会**读进 - 一帧状态, 而两帧挨得极近时 `hz` 是个几千的数 (公式没错, 是样本太少) —— 那种写法 - 会把一个正常行为判成缺陷。 - """ - arm = offline_arm - for _ in range(4): - arm.get_state(refresh=True) - time.sleep(0.002) - assert arm._a.recv_stats(P.RSP_STATUS)[0] > 0.0, "前提: 旧会话攒到了样本" - old_table = arm._a._recv - - arm.reconnect() - - assert arm._a._recv is not old_table, "接收表跨会话复用了 (统计没跟着会话走)" - # ⚠ 判据从「`hz == 0.0`」改成「**计数从 1 重新起**」:读线程在 `connect()` 里就起来了, - # 它会在我们检查之前就投进若干状态帧 ⇒ `hz == 0.0` 与读线程**竞态**(实测红)。 - # "统计从零开始"的确定性表述是:新表的 count **小于**旧表攒到的数。 - assert arm._a._recv[P.RSP_STATUS][0] < old_table[P.RSP_STATUS][0], ( - "换了一条会话, 计数该从 1 重新起 (不是跨会话累计)") - - -# --------------------------------------------------------------------------- -# 5. 两个派生 getter 仍是裸值 (`get_ff_mask` / `all_joint_params`) -# --------------------------------------------------------------------------- - -def test_get_ff_mask_stays_a_bare_int(offline_arm): - """`get_ff_mask` 是 `get_ff_scalar(9, 0)` 的**标量投影** —— 包两层会把同一帧的同一 - 份统计说两遍, 而且它的定义 `int(round(...))` 本身就只能消费裸值。""" - got = offline_arm.get_ff_mask() - assert isinstance(got, int) and not isinstance(got, pa.Msg) - - -def test_all_joint_params_stays_a_list_of_jointparam(offline_arm): - """N 次往返的**聚合** —— 一个 `hz`/`timestamp` 描述不了它 (N 帧 N 个时刻), - 且逐项读字段的既有契约 (`for jp in ...: jp.q_min`) 不许破。""" - arm = offline_arm - got = arm.params.all_joint_params() - assert len(got) == arm.n - assert all(isinstance(jp, JointParam) for jp in got), f"returned list[Msg]? {got!r}" - - -def test_the_scalar_projection_still_shares_the_underlying_frame_stats(offline_arm): - """要那一帧的信封就直接调 `get_ff_scalar(9, 0)` —— 两条路的**值**必须一致。""" - arm = offline_arm - assert arm.get_ff_mask() == int(round(arm.get_ff_scalar(9, 0).value)) diff --git a/tests/test_offline.py b/tests/test_offline.py deleted file mode 100644 index 89e7445..0000000 --- a/tests/test_offline.py +++ /dev/null @@ -1,95 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -"""离线单测(无硬件): 帧编解码/G8 状态解析/版本约定/到位判定。""" -import os -import sys - -sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src")) - -import struct - -from litearm import _protocol as P -from litearm import state as ST -from litearm.arm import Arm -from litearm.errors import FirmwareMismatchError - -fails = [] - - -def check(name, cond): - if not cond: - fails.append(name) - print(f" FAIL: {name}") - else: - print(f" ok: {name}") - - -def test_frame_roundtrip(): - for cmd, payload in ((0x01, b""), (0x45, b"\x10"), (0x02, bytes(28))): - fr = P.pack_frame(cmd, payload) - assert len(fr) == 3 + len(payload) + 2 - got = P.unpack_frame(fr) - check(f"frame rt cmd={cmd:02x}", got == (cmd, payload)) - bad = P.unpack_frame(bytes([0xA5, 0x45, 0x01, 0x99, 0, 0])) - check("frame crc bad -> None", bad is None) - check("frame nan/short -> None", P.unpack_frame(b"\x01\x02") is None) - - -def synth_status(n=7, mode=1, flags=0): - body = bytearray() - body += struct.pack(" raise", _raises(ValueError, lambda: ST.decode_state(b"\x01"))) - - -def _raises(exc, fn): - try: - fn() - except exc: - return True - return False - - -def test_fw_version(): - v = P.parse_firmware_version("Litearm1.4.0-7J") - check("fw parse Litearm", v == (1, 4, 0, "7J")) - v = P.parse_firmware_version("Litearm1.4.0-1J") - check("fw parse 1J", v == (1, 4, 0, "1J")) - check("fw old A -> None", P.parse_firmware_version("A1.3.0-7J-USB") is None) - check("fw junk -> None", P.parse_firmware_version("hello") is None) - - -def test_pose_near(): - a = object.__new__(Arm) - tcp = (0.3002, 0.001, 0.35, 3.1416, 0.0, 0.001) - goal = (0.30, 0.0, 0.35, 3.1416, 0.0, 0.0) - check("pose near ok", Arm._pose_near(tcp, goal, 0.006, 0.03)) - tcp2 = (0.35, 0.0, 0.35, 3.14, 0.0, 0.0) - check("pose far", not Arm._pose_near(tcp2, goal, 0.006, 0.03)) - - -def test_ff_mask_bits(): - check("ff bits", P.FF_ALL == 0x1FF and P.FF_MASTER == 1) - - -if __name__ == "__main__": - test_frame_roundtrip() - test_state_decode() - test_fw_version() - test_pose_near() - test_ff_mask_bits() - print("offline:", "PASS" if not fails else f"FAIL {len(fails)}: {fails}") - sys.exit(1 if fails else 0) diff --git a/tests/test_package_metadata.py b/tests/test_package_metadata.py deleted file mode 100644 index f3ecc3d..0000000 --- a/tests/test_package_metadata.py +++ /dev/null @@ -1,46 +0,0 @@ -"""Packaging metadata —— PyPI 的副标题和许可证都取自 `pyproject.toml`。 - -副标题 (`[project].description`) 会直接出现在 PyPI 项目页和搜索结果里, 所以它 -必须是英文。许可证 (`[project].license`) 则必须与仓库根目录的 `LICENSE` 一致: -GitHub 只扫 `LICENSE` 文件, PyPI 只读包元数据, 两处不一致时两个平台会显示不同 -的许可证。这两条用例把上述约束变成可检查的门禁。 -""" -from __future__ import annotations - -import re -from pathlib import Path - -PYPROJECT = Path(__file__).resolve().parents[1] / "pyproject.toml" - - -def _project_description() -> str: - text = PYPROJECT.read_text(encoding="utf-8") - match = re.search(r'^description\s*=\s*"([^"]*)"\s*$', text, re.MULTILINE) - assert match is not None, "pyproject.toml has no [project].description" - return match.group(1) - - -def _project_license() -> str: - text = PYPROJECT.read_text(encoding="utf-8") - match = re.search(r'^license\s*=\s*"([^"]+)"\s*$', text, re.MULTILINE) - assert match is not None, "pyproject.toml has no [project].license" - return match.group(1) - - -def test_pypi_subtitle_is_english(): - """PyPI 副标题 (Summary) 必须是英文, 不能是中文。""" - description = _project_description() - assert description, "[project].description must not be empty" - assert description.isascii(), ( - "PyPI shows [project].description as the project subtitle; " - f"write it in English: {description!r}" - ) - - -def test_license_metadata_matches_the_license_file(): - """PyPI 读 pyproject 的 license 字段, GitHub 扫 LICENSE 文件, 两边必须一致。""" - declared = _project_license() - license_file = (PYPROJECT.parent / "LICENSE").read_text(encoding="utf-8") - assert declared == "Apache-2.0" - assert "Apache License" in license_file - assert "Version 2.0" in license_file diff --git a/tests/test_params.py b/tests/test_params.py deleted file mode 100644 index 889538d..0000000 --- a/tests/test_params.py +++ /dev/null @@ -1,101 +0,0 @@ -"""关节级运行时参数 (固件 0x22/0x23/0x24/0x36) —— 此前 SDK 有常量、零 API。 - -固件载荷约定 (`usb_cmd_dispatch` 的 `case CMD_SET_JOINT_PARAM`(0x22) / -`CMD_SET_JOINT_LIMITS`(0x23) / `CMD_GET_JOINT_PARAM`(0x24) / `CMD_PARAM_RESET`(0x36), -`usb_cmd.c:611-664` 及 `:677-712`): - 0x22 SET_JOINT_PARAM : idx(1B) + kp,kd,tau_max(f32×3) = 13B; ERR 0x01=长度 / 0x02=idx越界或值非法 - 0x23 SET_JOINT_LIMITS : idx(1B) + q_min,q_max(f32×2) = 9B; ERR 同上 - 0x24 GET_JOINT_PARAM : idx(1B) -> RSP_JOINT_PARAM(0x49) = idx + kp,kd,tau_max,q_min,q_max (21B) - 0x36 PARAM_RESET : 空载荷, 恢复出厂 + 失效 flash; **须失能** 否则 ERR{0x36,0x04} -""" -from __future__ import annotations - -import struct - -import pytest - -from litearm import _protocol as P -from litearm.errors import CommandRejectedError, InvalidCommandError - - -def _payloads(arm, cmd): - return [p for c, p in list(arm._tr.tx_log) if c == cmd] - - -def test_set_joint_param_payload_and_ack(offline_arm): - arm = offline_arm - arm.params.set_joint_param(2, kp=60.0, kd=3.0, tau_max=12.0) - ps = _payloads(arm, P.CMD_SET_JOINT_PARAM) - assert len(ps) == 1 and len(ps[0]) == 13 - idx = ps[0][0] - kp, kd, tm = struct.unpack_from(" int: - """**独立的参考实现** —— 逐位算,与被测实现无共享代码。 - - ⚠ 这是**参照物**:改动 `_protocol` 时**不要动它**。把参照物也改成新算法, - 这条判据就废了(两边的错会互相抵消)。 - """ - crc = 0xFFFF - for byte in data: - crc ^= byte << 8 - for _ in range(8): - crc = ((crc << 1) ^ 0x1021) & 0xFFFF if crc & 0x8000 else (crc << 1) & 0xFFFF - return crc - - -def test_the_standard_check_value_from_the_crc_catalogue(): - """CRC-16/CCITT-FALSE 的**标准检查值**:`"123456789"` → `0x29B1`。 - - 这条**不来自本仓任何代码** —— 它来自 CRC 参数目录(`poly=0x1021, init=0xFFFF, - refin=false, refout=false, xorout=0x0000`)。抽查值一错,说明算法参数被改过。 - """ - assert P.crc16_ccitt_false(b"123456789") == 0x29B1 - - -def test_matches_the_independent_reference_on_every_length_0_to_259(): - """长度 **0..259 全覆盖**(帧载荷上限 255 + 头 3 + CRC 2 = 260 ⇒ 259 是上限-1)。 - - 每个长度都用**确定性的**内容(不靠随机,失败可复现)。 - """ - for n in range(0, 260): - data = bytes((i * 7 + n) & 0xFF for i in range(n)) - assert P.crc16_ccitt_false(data) == _crc_ref_bitwise(data), ( - f"长度 {n} 上与被测实现不一致") - - -def test_matches_the_independent_reference_on_random_payloads(): - """随机载荷铺一层(覆盖全覆盖用例碰不到的字节组合)。""" - rng = random.Random(20260922) - for _ in range(2000): - data = bytes(rng.randrange(256) for _ in range(rng.randrange(0, 256))) - assert P.crc16_ccitt_false(data) == _crc_ref_bitwise(data) - - -def test_empty_input_is_the_init_value(): - """空输入必须回 init(`0xFFFF`)—— 钉住"没有末异或"这一格。""" - assert P.crc16_ccitt_false(b"") == 0xFFFF - assert P.crc16_ccitt_false(b"") == _crc_ref_bitwise(b"") - - -def test_a_single_flipped_bit_changes_the_crc(): - """**负控**:改一个 bit 必须换一个 CRC。 - - ⚠ 没有这条,一个"恒返回常数"的实现也能过上面所有长度/随机用例 —— - 因为参考实现会跟着一起算,只有恒等比较才能发现。所以这里直接问 - "它对输入敏感吗"。 - """ - a = _crc_ref_bitwise(b"\x01\x02\x03") - b = _crc_ref_bitwise(b"\x01\x02\x02") # 翻最低位 - assert a != b, "参考实现自己对输入不敏感 —— 上面那些用例的判据不成立" - assert P.crc16_ccitt_false(b"\x01\x02\x03") != P.crc16_ccitt_false(b"\x01\x02\x02") - - -# --------------------------------------------------------------------------- -# 线级契约 —— CRC 在帧里的**位置与字节序** -# --------------------------------------------------------------------------- - -def test_the_frame_carries_the_crc_low_byte_first(): - """`SOF CMD LEN PAYLOAD crc_LO crc_HI` —— **低字节在前**。 - - ⚠ 这是与固件的线契约里最容易改错的一格(换个字节序,本机全绿、真机全哑)。 - """ - payload = bytes(range(20)) - frame = P.pack_frame(0x34, payload) - body = frame[:-2] - want = P.crc16_ccitt_false(body) - assert frame[-2] == (want & 0xFF), "CRC 低字节不在倒数第二位" - assert frame[-1] == (want >> 8), "CRC 高字节不在最后一位" - assert P.unpack_frame(frame) == (0x34, payload) - - -def test_a_bad_crc_is_rejected(): - """坏 CRC 必须被拒(返回 `None`)—— 否则坏帧会被当成好帧收下。""" - frame = bytearray(P.pack_frame(P.RSP_STATUS, b"\x01\x02\x03")) - frame[-1] ^= 0x01 # 翻 CRC 高字节 - assert P.unpack_frame(bytes(frame)) is None - - -@pytest.mark.parametrize("bad", [ - b"", # 空 - bytes([P.SOF, 0x34, 0x05, 1, 2]), # 长度说 5 但只有 2 个载荷字节 -]) -def test_truncated_or_short_input_is_rejected(bad): - """长度不足 / 声明长度超过实际 ⇒ 拒绝,不许越界读或猜。""" - assert P.unpack_frame(bad) is None diff --git a/tests/test_protocol_sync.py b/tests/test_protocol_sync.py deleted file mode 100644 index 902e793..0000000 --- a/tests/test_protocol_sync.py +++ /dev/null @@ -1,367 +0,0 @@ -"""协议漂移防护 —— SDK 与固件头文件的**双向强制比对**。 - -为什么必须有这个文件: 上一次栽的跟头就是「命令/帧布局改了, SDK 没跟上」—— -1.5.x 把状态帧从 `4+21N` 改成 `6+21N` 时漏同步本 SDK, 而桩测试整替换 transport、 -自造旧布局, 结果**离线 293 绿、真机必挂**。人工核对挡不住这种事, 只有把固件头文件 -当输入喂给测试才挡得住。 - -做法: 直接解析固件仓库的头文件源码 (不依赖固件编译), 断言: - 1. 固件每条 `CMD_*` 在 SDK `_protocol` 里都有同名同值常量 (反向亦然); - **两类例外, 语义不同**: ① `_protocol.FIRMWARE_ONLY_CMDS` / - `FIRMWARE_ONLY_RSPS` 里的条目豁免 —— 这两张表**历史上**装的是"用户裁决 SDK - **有意不暴露**"的命令/应答 (笛卡尔 0x3A~0x3E / 0x4E 曾是这里的例子), ⚠ **现在两张 - 都是空的**: 段二已给笛卡尔补上常量与入口, 于是"豁免"不再成立 - (空表本身就是"当前没有任何固件单边命令"的断言载体); - ② **既有的**固件/SDK 不同步 (目前 1 条, 见 `_protocol.PREEXISTING_GAPS`) —— - 只豁免不修复。 - 两类豁免的有效性都由 `test_firmware_only_exemption_is_still_valid` 单独守 - (不是永久白名单); - 2. 固件每条**已实现**命令在 `COMMAND_COVERAGE` 里都有 SDK 入口, 且该入口 - `getattr` 得到 (覆盖"无死角"这件事本身); - 3. 固件标注「未实现」的命令仍然标注着 (固件一旦实现, 这里立刻红, 提醒补入口); - 4. 状态帧布局表达式未被改动; - 5. `joint_cfg.h` 的台架常量与 SDK `BENCH_MODEL_AXIS` 一致 —— 固件 2026-09-28 移除 - 台架模式后, 该条**退化为**"防再打开的 `#error` 守卫仍在 + SDK 的 legacy 常量仍在" - (见用例内注释; SDK 仍要服务 1J 老固件, 故常量不能删); - 6. `ERR{cmd,0x00}` 在固件里仍**只**由 `default` 分支产生 —— 这条守的是 - 「用 ERR 码判定固件能力」这个核心假设 (见 test_capability.py); - 7. 固件自报版本不低于 SDK 要求的 `MIN_FW`。 - -固件仓库位置: 环境变量 `LITEARM_FW_DIR`, 默认 `~/litearm-stm32`。 -**找不到时 skip, 不是 pass** —— 假绿比没测更糟。 -""" -from __future__ import annotations - -import os -import re -import struct - -import pytest - -from litearm import _protocol as P -from litearm import arm as arm_mod - -FW_DIR = os.environ.get("LITEARM_FW_DIR") or os.path.expanduser("~/litearm-stm32") -USB_CMD_H = os.path.join(FW_DIR, "User/litearm/hal/usb_cmd.h") -USB_CMD_C = os.path.join(FW_DIR, "User/litearm/hal/usb_cmd.c") -LITEARM_H = os.path.join(FW_DIR, "User/litearm/litearm.h") -JOINT_CFG_H = os.path.join(FW_DIR, "User/litearm/params/joint_cfg.h") - - -def _read(path: str) -> str: - if not os.path.isfile(path): - pytest.skip(f"固件源码不在 {path} —— 设 LITEARM_FW_DIR 指向 litearm-stm32 仓库") - with open(path, encoding="utf-8", errors="replace") as f: - return f.read() - - -@pytest.fixture(scope="module") -def hdr(): - return _read(USB_CMD_H) - - -def _fw_defines(hdr_src: str, prefix: str): - """`#define NAME 0xNN` -> {名字: (值, 该行其余内容)}。 - - ⚠ 空白一律用 `[ \\t]` 而非 `\\s` —— `\\s` 会跨越换行, 于是 `(.*)$` 会把**下一行** - 整行吞掉, 使相邻的 #define 交替漏匹配 (本文件 34 条只命中 26 条)。 - """ - out = {} - pat = (r"^#define[ \t]+(" + prefix + r"\w+)[ \t]+(0x[0-9A-Fa-f]+)[ \t]*(.*)$") - for m in re.finditer(pat, hdr_src, re.M): - out[m.group(1)] = (int(m.group(2), 16), m.group(3)) - return out - - -def _fn_body(src: str, name: str): - """取出 `static void (void) { ... }` 的函数体 (用于把解析限定在单个函数内)。""" - m = re.search(r"static void[ \t]+" + re.escape(name) + r"\(void\)[ \t]*\{(.*?)\n\}", - src, re.S) - return m.group(1) if m else None - - -# ---------------------------------------------------------------- 1. 常量双向 -def test_every_firmware_cmd_has_sdk_constant(hdr): - """固件每条已实现命令都要在 SDK 里有同名同值常量 (未实现的那两条按豁免跳过, - 其豁免有效性由 test_unimplemented_exemption_is_still_true 单独守)。 - - ⚠ 这张表按**名字**豁免 (下面的 `if name in exempt`) —— 与 - `test_every_implemented_cmd_has_reachable_api` 的**码值**口径不同, 改一处必须改两处; - 这里并进去的必须是 FIRMWARE_ONLY_CMDS / PREEXISTING_GAPS 的 **values()(名字)**, - 键是码值。 - """ - fw = _fw_defines(hdr, "CMD_") - exempt = (set(P.UNIMPLEMENTED_CMDS.values()) - | set(P.FIRMWARE_ONLY_CMDS.values()) - | set(P.PREEXISTING_GAPS.values())) - missing = [] - for name, (val, _) in fw.items(): - if name in exempt: - continue - got = getattr(P, name, None) - if got != val: - missing.append(f"{name}=0x{val:02X} (SDK: {got!r})") - assert not missing, "SDK _protocol 缺少/值不符的固件命令: " + ", ".join(sorted(missing)) - - -def test_sdk_has_no_command_the_firmware_lacks(hdr): - fw_names = set(_fw_defines(hdr, "CMD_")) - sdk_names = {n for n in dir(P) if n.startswith("CMD_")} - extra = sdk_names - fw_names - assert not extra, f"SDK 声明了固件没有的命令 (漂移): {sorted(extra)}" - - -def test_every_firmware_rsp_has_sdk_constant(hdr): - """⚠ 本条原本**没有豁免路径**, 笛卡尔那次新增了一条 —— 与上面第一条同口径 - (按**名字**判, 故并进去的是 FIRMWARE_ONLY_RSPS.values())。""" - fw = _fw_defines(hdr, "RSP_") - exempt = set(P.FIRMWARE_ONLY_RSPS.values()) - missing = [f"{n}=0x{v:02X}" for n, (v, _) in fw.items() - if n not in exempt and getattr(P, n, None) != v] - assert not missing, "SDK _protocol 缺少/值不符的固件应答: " + ", ".join(sorted(missing)) - - -# ---------------------------------------------------------------- 2. 入口可达 -def _resolve(instance, dotted: str): - """解析 `Arm.params.set_joint_param` 形式的入口路径 (首段 `Arm` 从实例起算)。""" - parts = dotted.split(".") - if parts and parts[0] == "Arm": - parts = parts[1:] - obj = instance - for part in parts: - obj = getattr(obj, part) - return obj - - -def test_every_implemented_cmd_has_reachable_api(hdr): - """「无死角」: 固件每条已实现命令都要能在 Arm 上摸到入口。 - - ⚠ 本条按**码值**判 (`val in ...`, 因为它拿不到名字那条路径的豁免集合) —— - 与 `test_every_firmware_cmd_has_sdk_constant` 的**名字**口径不同, 两者都要改。 - """ - fw = _fw_defines(hdr, "CMD_") - arm = arm_mod.Arm() # 不连接: 只解析属性/方法是否存在 - problems = [] - for name, (val, _) in sorted(fw.items(), key=lambda kv: kv[1][0]): - if (val in P.UNIMPLEMENTED_CMDS or val in P.FIRMWARE_ONLY_CMDS - or val in P.PREEXISTING_GAPS): - continue - entry = P.COMMAND_COVERAGE.get(val) - if entry is None: - problems.append(f"0x{val:02X} {name}: 未登记 SDK 入口") - continue - try: - target = _resolve(arm, entry) - except AttributeError as e: - problems.append(f"0x{val:02X} {name}: 入口 {entry} 不存在 ({e})") - continue - if not callable(target): - problems.append(f"0x{val:02X} {name}: 入口 {entry} 不可调用") - assert not problems, "覆盖缺口: " + "; ".join(problems) - - -def test_coverage_map_has_no_stale_entries(hdr): - """反向: 覆盖表里不许有固件已不存在的命令 id (否则是过期登记)。""" - fw_ids = {v for v, _ in _fw_defines(hdr, "CMD_").values()} - stale = [f"0x{k:02X}" for k in P.COMMAND_COVERAGE if k not in fw_ids] - assert not stale, f"COMMAND_COVERAGE 有过期登记: {sorted(stale)}" - - -def test_unimplemented_exemption_is_still_true(hdr): - """豁免不是永久白名单: 固件一旦实现, 头文件里的「未实现」标注会消失 -> 这里红。""" - fw = _fw_defines(hdr, "CMD_") - still_exempt = [] - for val, name in P.UNIMPLEMENTED_CMDS.items(): - assert name in fw, f"{name} 已从固件头文件消失, 应从豁免表移除" - assert fw[name][0] == val, f"{name} 的 id 变了: 0x{fw[name][0]:02X} != 0x{val:02X}" - if "未实现" in fw[name][1]: - still_exempt.append(name) - assert len(still_exempt) == len(P.UNIMPLEMENTED_CMDS), ( - "固件已经实现了原来豁免的命令: " + - ", ".join(sorted(set(P.UNIMPLEMENTED_CMDS.values()) - set(still_exempt))) + - " —— 请补 SDK 入口并从 UNIMPLEMENTED_CMDS 移除") - - -def test_firmware_only_exemption_is_still_valid(hdr): - """三张豁免表都不是永久白名单: 固件侧若删掉/改名/换号, 这条必须红。 - - 守 `_protocol` 的 `FIRMWARE_ONLY_CMDS` / `FIRMWARE_ONLY_RSPS` / `PREEXISTING_GAPS`。 - ⚠ 三张表的**语义不同**, 别以为一条判据就是一个意思: - · 前两张 (`FIRMWARE_ONLY_CMDS`/`FIRMWARE_ONLY_RSPS`) **现在都是空表** —— 它们的 - **历史**语义是"用户裁决 SDK **有意不暴露**"("不做", 不是"还没做"; 笛卡尔 - 0x3A~0x3E/0x4E 曾是例子, 段二已暴露并补上入口)。表空 ⇒ 下面两个循环一条都不跑, - 本判据对它们只是"**表里若有东西**, 固件侧必须仍存在且 SDK 还没实现"; - · `PREEXISTING_GAPS` = **既有的固件/SDK 不同步**(DFU), 本应同步而未同步。 - 判据相同(固件里必须仍有这几条)不等于理由相同。 - - ⚠ 与 `test_unimplemented_exemption_is_still_true` 同一意图, 但判据**相反**: - 那条要求固件注释里**仍**写着"未实现", 这条要求固件里**确实有**这些命令。 - - ⚠ 它同时守反向: 一旦 SDK 补上了同名常量(= 真的实现了入口), 豁免就该撤掉, - 否则豁免表会变成"谁都看不见的过期登记"。 - - ⚠ 本守卫读的是**磁盘上的固件树**(`LITEARM_FW_DIR`), 所以对着**没有这些命令的 - 固件分支**(如 master)跑会红 —— **这是预期**: 它抓的正是"固件有、SDK 无"。 - 刻意不做"区分换分支与真删了"(那是推测性复杂度)。 - """ - fw = _fw_defines(hdr, "CMD_") - for code, name in P.FIRMWARE_ONLY_CMDS.items(): - assert name in fw, ( - f"豁免表里的 {name}(0x{code:02X}) 在固件头文件里已不存在 —— " - f"请从 _protocol.FIRMWARE_ONLY_CMDS 移除") - assert fw[name][0] == code, ( - f"{name} 在固件里是 0x{fw[name][0]:02X}, 豁免表写的是 0x{code:02X} —— 请同步") - assert not hasattr(P, name), f"{name} 已被 SDK 实现, 请从豁免表移除" - - fwr = _fw_defines(hdr, "RSP_") - for code, name in P.FIRMWARE_ONLY_RSPS.items(): - assert name in fwr, ( - f"豁免表里的 {name}(0x{code:02X}) 在固件头文件里已不存在 —— " - f"请从 _protocol.FIRMWARE_ONLY_RSPS 移除") - assert fwr[name][0] == code, ( - f"{name} 在固件里是 0x{fwr[name][0]:02X}, 豁免表写的是 0x{code:02X} —— 请同步") - assert not hasattr(P, name), f"{name} 已被 SDK 实现, 请从豁免表移除" - - # PREEXISTING_GAPS 同样要守: 它记的是"**本应同步而未同步**"的既有缺口, - # 一旦固件侧消失或 SDK 补上了入口, 豁免就该撤 —— 否则它会变成没人看得见的过期登记。 - for code, name in P.PREEXISTING_GAPS.items(): - assert name in fw, ( - f"PREEXISTING_GAPS 里的 {name}(0x{code:02X}) 在固件头文件里已不存在 —— " - f"请从 _protocol.PREEXISTING_GAPS 移除") - assert fw[name][0] == code, ( - f"{name} 在固件里是 0x{fw[name][0]:02X}, PREEXISTING_GAPS 写的是 0x{code:02X} —— 请同步") - assert not hasattr(P, name), ( - f"{name} 已被 SDK 实现, 请从 PREEXISTING_GAPS 移除(缺口已补上)") - - -# ---------------------------------------------------------------- 3. 状态帧布局 -def test_status_frame_layout_unchanged(): - """状态帧载荷长度表达式必须仍是 `6 + N*21` (SDK 解析器按此硬编码)。""" - body = _fn_body(_read(USB_CMD_C), "usb_cmd_report_status") - assert body, "在 usb_cmd.c 里找不到 usb_cmd_report_status 函数体" - m = re.search(r"uint8_t[ \t]+payload[ \t]*\[[ \t]*([^\]]+)\]", body) - assert m, "找不到状态帧 payload 声明" - expr = re.sub(r"\s+", " ", m.group(1)).strip() - assert expr == "6 + LITEARM_NUM_JOINTS * 21", ( - f"固件状态帧布局变了: `{expr}` —— SDK decode_status 的 6+21N 假设需同步; " - f"历史上正是这类改动漏同步导致离线全绿真机必挂") - - -def test_status_frame_joint_stride_matches_sdk_constant(): - """每关节字节数 (5×f32 + 1×err = 21) 必须与 SDK 的步长一致。""" - body = _fn_body(_read(USB_CMD_C), "usb_cmd_report_status") - assert body, "找不到 usb_cmd_report_status 函数体" - m = re.search(r"for[ \t]*\(int i = 0; i < LITEARM_NUM_JOINTS; i\+\+\)[ \t]*\{(.*?)\n \}", - body, re.S) - assert m, "找不到状态帧的逐关节打包循环" - seg = m.group(1) - n_floats = len(re.findall(r"f32_to_le\(", seg)) - n_u8 = len(re.findall(r"\*pp\+\+[ \t]*=", seg)) - assert n_floats * 4 + n_u8 == 21, ( - f"每关节 {n_floats} 个 f32 + {n_u8} 个 u8 = {n_floats * 4 + n_u8}B, " - f"与 SDK 的 21B 步长不符") - - -# ---------------------------------------------------------------- 4. 台架常量 -def test_bench_model_axis_matches_sdk_constant(): - """`BENCH_MODEL_AXIS` 与固件 `joint_cfg.h` 的台架映射一致。 - - ⚠ [2026-10-10] 固件 **2026-09-28 已移除** `LITEARM_BENCH_1J` 台架单电机模式 - (joint_cfg.h 顶部三条理由, 其中 ② 是**静默丢 flash 标定**), 并留了防"再打开"的 - `#error` 硬守卫。故本用例分两支: - - · 固件**仍**定义 `LITEARM_BENCH_MODEL_AXIS` ⇒ 逐值比对 (旧固件树); - · 固件**已移除** ⇒ 断言守卫仍在, 且 SDK 常量仍在 —— SDK 仍要服务 1J 老固件 - (`Litearm1.7.0-1J`, 见 `test_ik_bench.py` / `conftest.offline_arm_1j`), - 故这里 assert 的是"**这条 legacy 通路没被人当死代码删掉**", 不是放行。 - - ⚠ 判据**只认 `#define` 行**, 不走 `#if\\s+LITEARM_BENCH_1J(.*?)#else`: - 旧写法带 `re.S`, 而 joint_cfg.h 的**注释里**同时出现 `#if LITEARM_BENCH_1J` - 与 `#else` 字样 (逐字讨论 litearm.h 的两支结构) ⇒ 正则**从注释匹配到注释**, - 于是这条断言被一个**假匹配**触发、报"找不到台架分支", 归因指向错误的地方 - (实测 2026-10-10)。 - """ - src = _read(JOINT_CFG_H) - m = re.search(r"^[ \t]*#define[ \t]+LITEARM_BENCH_MODEL_AXIS[ \t]+(\d+)[ \t]*$", - src, re.M) - if m: - assert int(m.group(1)) == P.BENCH_MODEL_AXIS, ( - f"固件台架模型轴 = {m.group(1)}, SDK BENCH_MODEL_AXIS = {P.BENCH_MODEL_AXIS} " - f"—— IK 种子会填错轴") - return - assert "#error" in src and "LITEARM_BENCH_1J" in src, ( - "joint_cfg.h 既没有 LITEARM_BENCH_MODEL_AXIS, 也没有防再打开的 `#error` 守卫 " - "—— 台架模式是被**移除**了还是被**改坏**了? 先弄清再改本用例, 别顺手删断言") - assert P.BENCH_MODEL_AXIS == 5, ( - f"固件已移除台架模式, SDK 的 BENCH_MODEL_AXIS 现在只服务 1J 老固件 " - f"(Litearm1.7.0-1J); 当前值 = {P.BENCH_MODEL_AXIS}。真要改它, 请同时更新" - f"本断言与 _protocol.py 上那条 legacy 标注") - - -# ---------------------------------------------------------------- 5. 能力判定假设 -def test_err_code_zero_only_comes_from_default_branch(): - """`ERR{cmd,0x00}` 必须**只**由未实现命令的 default 分支产生 —— - SDK 的 UnsupportedByFirmwareError 判定完全建立在这个假设上。""" - src = _read(USB_CMD_C) - codes = re.findall(r"RSP_ERR,\s*\(const uint8_t\[\]\)\{([^}]*)\}", src) - zeros = [c for c in codes if c.strip().endswith("0x00")] - assert len(zeros) == 1, ( - f"固件里有 {len(zeros)} 处回 ERR 码 0x00 (期望恰好 1 处, 即 default 分支): " - f"{zeros} —— SDK 会把它误判成「固件不支持该命令」") - assert re.search(r"default:\s*\n\s*usb_cmd_reply\(RSP_ERR,\s*\(const uint8_t\[\]\)\{cmd, 0x00\}", - src), "那唯一一处 0x00 不在 default 分支里" - - -# ---------------------------------------------------------------- 6. 版本门 -def test_firmware_version_not_below_sdk_minimum(): - src = _read(LITEARM_H) - vers = re.findall(r'#define\s+LITEARM_FW_VERSION\s+"([^"]+)"', src) - assert vers, "找不到 LITEARM_FW_VERSION" - parsed = [P.parse_firmware_version(v) for v in vers] - assert all(p is not None for p in parsed), f"版本串不符合约定: {vers}" - for v, p in zip(vers, parsed): - assert p[:3] >= arm_mod.MIN_FW, ( - f"固件自报 {v} 低于 SDK 要求的 " - f"{'.'.join(map(str, arm_mod.MIN_FW))}") - - -# ------------------------------------------------- 7. 0x08 的载荷布局(跨仓) -def test_joint_follow_payload_layout_matches_firmware(hdr, offline_arm): - """⛔ `0x08` 的载荷:固件**声明的分段顺序**必须等于 SDK **实际发出的字节**。 - - 契约两端是 SDK `arm.joint_follow()` 的打包与固件 `usb_cmd.c` 的 - `case CMD_JOINT_FOLLOW` 解析。**只改一边**是这里最容易出的错,而别的用例 - 都发现不了它:`test_full_coverage` 只断言"这条命令发出去过",不看载荷内容。 - - ⚠ 判据取**真实发出的字节**逐段核对,而**不是**复述 `arm.py` 里的那个 - `pack_f32s(list(q)+list(dq)+list(kp)+list(kd))` —— 期望值与实现同源的话, - 判据会随实现一起错(本仓栽过:ACK/ERR 常量写错而测试自洽地全绿)。 - """ - # ① 固件头文件里声明的分段顺序 + 总长(顺序或长度改了这里先红) - m = re.search( - r"payload\s*=\s*q_target\[N\]\s*f32\s*\+\s*dq_ref\[N\]\s*f32\s*\+" - r"\s*K\[N\]\s*f32\s*\+\s*B\[N\]\s*f32\s*=\s*16N\s*字节", hdr) - assert m, ( - "固件 usb_cmd.h 里 CMD_JOINT_FOLLOW 的载荷声明变了或没了 —— " - "两端(SDK 打包 / 固件解析)必须一起改;本条判据就是防「只改一边」") - - # ② SDK 实发字节:四段用互不相同的哨兵值,好钉住每一段的位置 - n = 7 - q = [0.1 * (i + 1) for i in range(n)] # 0.1 … 0.7 - dq = [10.0 + i for i in range(n)] # 10 … 16 - kp = [100.0 + i for i in range(n)] # 100 … 106 - kd = [1000.0 + i for i in range(n)] # 1000 … 1006 - offline_arm.connect() - offline_arm.joint_follow(q, dq, kp, kd) - - payloads = [p for c, p in offline_arm._tr.tx_log if c == P.CMD_JOINT_FOLLOW] - assert payloads, "0x08 一帧都没发出去" - pl = payloads[-1] - - assert len(pl) == 16 * n, f"载荷应为 16N={16 * n} 字节,实为 {len(pl)}" - got = list(struct.unpack("<" + "f" * (4 * n), pl)) # 小端,与 pack_f32s 同 - seg = ("q_target", "dq_ref", "K", "B") - want = (q, dq, kp, kd) - for i in range(4): - assert got[i * n:(i + 1) * n] == pytest.approx(want[i], rel=1e-5), ( - f"第 {i + 1} 段不是 {seg[i]}(固件按 {seg} 的顺序解析)") diff --git a/tests/test_public_api.py b/tests/test_public_api.py deleted file mode 100644 index d8481c9..0000000 --- a/tests/test_public_api.py +++ /dev/null @@ -1,131 +0,0 @@ -"""公开 API 面 —— 新能力与错误类型必须能从包顶层直接取到。 - -SDK 对外只有 `import litearm as pa` 一个入口, 新加的东西若没进 `__all__`, -使用者就得去摸私有模块 —— 那等于没交付。 -""" -from __future__ import annotations - -import pytest - -import litearm as pa - - -def test_error_types_are_exported(): - assert issubclass(pa.UnsupportedByFirmwareError, pa.CommandRejectedError) - assert pa.CommandRejectedError("x", cmd=0x2A, code=0x00).cmd == 0x2A - - -def test_result_types_are_exported(): - assert pa.JointParam is not None - assert pa.LogSample is not None - assert pa.KinBenchResult is not None - - -def test_all_listed_names_are_actually_present(): - missing = [n for n in pa.__all__ if not hasattr(pa, n)] - assert not missing, f"__all__ 里列了不存在的名字: {missing}" - - -def test_new_names_are_in_all(): - for name in ("UnsupportedByFirmwareError", "JointParam", "LogSample", - "KinBenchResult", "LogReader", "parse_samples", - "Baseline", "HoldSample", "PayloadResult"): - assert name in pa.__all__, f"{name} 未进 __all__" - assert hasattr(pa, name) - - -def _baseline(): - """最小合法基线 (两个姿态) —— 只为把 `identify()` 送进"取状态"那一步。""" - return pa.Baseline( - poses=((0.0, 0.6, 0.0, -1.0, 0.0, 0.5, 0.0), - (0.0, 1.2, 0.0, -0.9, 0.0, 0.4, 0.0)), - q=((0.0, 0.6, 0.0, -1.0, 0.0, 0.5, 0.0), - (0.0, 1.2, 0.0, -0.9, 0.0, 0.4, 0.0)), - tau=((0.0,) * 7, (0.0,) * 7)) - - -def _result(): - return pa.PayloadResult(mass=0.3, com=(0.0, 0.0, 0.05), sigma_mass=0.01, - sigma_com=(0.01, 0.01, 0.01), rank=4, cond=4.0, - residual_rms=0.1, n_rows=14, poses=2, - quality=(0.0, 0.0)) - - -def test_every_api_raises_not_connected_when_offline(): - """未连接时**所有**对外 API 都必须抛 NotConnectedError。 - - 漏掉 _require() 的先写后检路径会静默变成 `AttributeError: 'NoneType' object has - no attribute 'write_frame'` —— 调用方按错误类型做分支 (重连/重试) 的代码全失效。 - """ - arm = pa.Arm() # 故意不 connect() - cases = { - "get_status_now": lambda: arm.get_status_now(), - "get_tcp": lambda: arm.get_tcp(), - "ik": lambda: arm.ik((0.3, 0, 0.35, 0, 0, 0)), - "get_ff_vec": lambda: arm.get_ff_vec(1), - "get_ff_scalar": lambda: arm.get_ff_scalar(1), - "save_params": lambda: arm.save_params(), - "zero_g": lambda: arm.zero_g(), - "enable": lambda: arm.enable(), - # DFU 也是"先判连接": 未连接时第一因是断开, 不是"本对象已进 DFU 终态" - # (`enter_dfu` 的 `_require()` 排在预检读取之前)。 - "enter_dfu": lambda: arm.enter_dfu(), - "movej": lambda: arm.movej([0.0] * 7), - "params.get_joint_param": lambda: arm.params.get_joint_param(0), - "params.set_joint_param": lambda: arm.params.set_joint_param(0, 1.0, 1.0, 1.0), - "params.set_joint_limits": lambda: arm.params.set_joint_limits(0, -1.0, 1.0), - "params.reset_factory": lambda: arm.params.reset_factory(), - "log.start": lambda: arm.log.start(10), - "log.stop": lambda: arm.log.stop(), - "log.reader().read_all": lambda: arm.log.reader().read_all(), - "diag.kin_bench": lambda: arm.diag.kin_bench(), - # 负载辨识是模块级函数 (拿 arm 当第一个参数), 守卫顺序同样要"先判连接" - "payload.identify": lambda: pa.payload.identify(arm, _baseline()), - "payload.apply": lambda: pa.payload.apply(arm, _result()), - "payload.sample_hold": lambda: pa.payload.sample_hold(arm), - "payload.regressor": lambda: pa.payload.regressor(arm, [0.0] * 7), - "payload.gravity": lambda: pa.payload.gravity(arm, [0.0] * 7), - } - wrong = [] - for name, fn in cases.items(): - try: - fn() - wrong.append(f"{name}: 未报错") - except pa.NotConnectedError: - pass - except Exception as e: # noqa: BLE001 - wrong.append(f"{name}: {type(e).__name__} (应为 NotConnectedError)") - assert not wrong, "未连接时的错误类型不一致: " + "; ".join(wrong) - - -@pytest.mark.parametrize("call", [ - lambda a: a.move_l([0.32, 0.0, 0.35, 0.0, 0.0, 0.0]), - lambda a: a.move_c([0.32, 0.0, 0.35, 0.0, 0.0, 0.0], - [0.30, 0.02, 0.35, 0.0, 0.0, 0.0], - [0.31, 0.01, 0.35, 0.0, 0.0, 0.0]), - lambda a: a.move_path([[0.31, 0.0, 0.35, 0.0, 0.0, 0.0]]), - lambda a: a.move_p([[0.31, 0.0, 0.35, 0.0, 0.0, 0.0]]), - lambda a: a.poll_cart(), -]) -def test_cartesian_api_offline_raises_not_connected(call): - """笛卡尔入口在未连接时也抛 `NotConnectedError` —— 不因入参形状抢先报错。 - - ⚠ **改靶说明**: 本条从已删的 `tests/test_cartesian_motion.py` 摘出保留。原靶是 - `movel` / `movec` / **`arm.cartesian` 属性** —— 三者都随 PC 侧规划子包一起没了, - 照原样搬就是一条调已删方法的死用例。现靶是**仍在**的公开入口 - (`move_l` / `move_c` / `move_path` / `move_p` / `poll_cart`)。 - - ⚠ 其中 `move_p` 那条刻意传**位姿序列** (它本身要报"请用 `move_path`", 见 - `tests/test_arm_offline.py`): 这条钉的是**守卫顺序** —— 链路没开时第一因是断开, - 不该被入参形状的报错抢先。也就是说它测的不是"序列被拒", 而是"**先判连接**"。 - `cart.py` 三个入口都是 `arm._require()` 排在能力探测/零重力守卫/参数校验之前 - (①~④ 的顺序), 这条用例就是那个顺序的公开面哨兵。 - """ - with pytest.raises(pa.NotConnectedError): - call(pa.Arm()) - - -def test_version_bumped_for_breaking_change(): - """home()/zero_g() 是破坏性变更 —— 版本必须已越过 1.5.x。""" - major, minor, *_ = (int(x) for x in pa.__version__.split(".")) - assert (major, minor) >= (1, 6), f"破坏性变更后版本仍为 {pa.__version__}" diff --git a/tests/test_request_and_get.py b/tests/test_request_and_get.py deleted file mode 100644 index 2f35d94..0000000 --- a/tests/test_request_and_get.py +++ /dev/null @@ -1,173 +0,0 @@ -"""同一帧节流 (`Arm._tx_allowed`) —— **取帧模板已随读路径重构删除**。 - -⚠ 本文件原先叫「Task 5: 取帧收口 —— `_request_and_get` 模板 + 同帧节流」。2026-09-22 的 -读路径重构把 `_request_and_get` / `_read_frames` / `_read_one` 整条取帧链**删掉**了 -(SDK 现在只有一条读线程 `_Ack._reader_loop`,调用方只等队列),于是: - -* timeout 三态 / 每一拍夹紧 / `_MIN_FETCH_S` 那几节 —— **机制不存在了**,删; - 其中仍然成立的契约(`timeout < 0` 抛 `InvalidCommandError`、单帧非阻塞探、 - 取帧口只有一个)已搬到 `tests/test_frame_ownership.py`; -* **同帧节流那两节原地保留** —— `_tx_allowed` 挂在唯一的写口 `Arm._raw_write` 上, - 与读路径无关,本次未动。删掉整个文件会连它们一起丢掉。 -""" -from __future__ import annotations - -import time - -import pytest - -from litearm import _protocol as P -from litearm.errors import ArmIsInDfuError, InvalidCommandError - - -# --------------------------------------------------------------------------- -# 3. 同帧节流 (`min_interval`) —— 机制本身 -# --------------------------------------------------------------------------- - -def test_identical_frames_are_throttled_within_the_interval(offline_arm): - """同 cmd + **逐字节相同**的载荷在 `min_interval` 内重复 ⇒ 不发, 且**计数**。""" - arm = offline_arm - payload = P.pack_f32s([0.0] * arm.n) + b"\x00\x00\x00\x00" - arm._set_tx_repeat_min_interval(P.CMD_MOVE_JS, 0.5) - - arm._raw_write(P.CMD_MOVE_JS, payload) - n_after_first = len(arm._tr.stamps_of(P.CMD_MOVE_JS)) - - arm._raw_write(P.CMD_MOVE_JS, payload) # 窗口内重复 ⇒ 丢 - arm._raw_write(P.CMD_MOVE_JS, payload) - - assert len(arm._tr.stamps_of(P.CMD_MOVE_JS)) == n_after_first, "重复帧没被节流" - assert arm._tx_throttled_frames == 2, ( - "节流丢帧**不静默**: 每丢一帧必须计一次 (否则'指令没出去'完全不可观测)") - - -def test_a_changed_payload_is_never_throttled(offline_arm): - """载荷变了就**照发** —— 伺服换目标必须能出去 (节流只吃逐字节相同的重复)。""" - arm = offline_arm - arm._set_tx_repeat_min_interval(P.CMD_MOVE_JS, 5.0) - - arm._raw_write(P.CMD_MOVE_JS, P.pack_f32s([0.1] * arm.n) + b"\x00\x00\x00\x00") - arm._raw_write(P.CMD_MOVE_JS, P.pack_f32s([0.2] * arm.n) + b"\x00\x00\x00\x00") - - assert len(arm._tr.stamps_of(P.CMD_MOVE_JS)) == 2, ( - "换了载荷的新目标被节流丢掉了 —— 伺服会停在旧目标上") - assert arm._tx_throttled_frames == 0 - - -def test_the_throttle_lets_a_repeat_through_after_the_interval(offline_arm): - """过了间隔, 同样的帧**照发** (节流是"短时间内不重发", 不是"永不重发")。""" - arm = offline_arm - payload = b"\x00" * 8 - arm._set_tx_repeat_min_interval(P.CMD_MOVE_MIT, 0.05) - - arm._raw_write(P.CMD_MOVE_MIT, payload) - time.sleep(0.06) - arm._raw_write(P.CMD_MOVE_MIT, payload) - - assert len(arm._tr.stamps_of(P.CMD_MOVE_MIT)) == 2 - assert arm._tx_throttled_frames == 0 - - -def test_the_terminal_state_guard_is_not_short_circuited_by_the_throttle(offline_arm): - """⚠ 终态守卫 (`_reject_if_in_dfu`) **排在节流之前** —— 终态必须**响亮**, 不许静默。 - - `_raw_write` 里两道口的顺序是有射程的: 帧被节流丢掉时返回 `None` (什么都不发生), - 而终态下**任何**写都必须抛 `ArmIsInDfuError` (那是"结构性"的: 终态对象不会再发出 - 帧, 而且这件事必须可判定)。若节流排在前面, "终态 + 一条重复载荷"就会静默无声 —— - 调用方看不出自己已经在一个废掉的会话上。故顺序是守卫在前。 - """ - arm = offline_arm - arm._set_tx_repeat_min_interval(P.CMD_ZERO_G, 5.0) - arm._raw_write(P.CMD_ZERO_G, b"\x01") # 先发一条, 让表里有"上一帧" - arm.enter_dfu() # 终端态 (此后本对象不可用) - - with pytest.raises(ArmIsInDfuError): - arm._raw_write(P.CMD_ZERO_G, b"\x01") # 逐字节相同 ⇒ 节流会想丢它 - assert arm._tx_throttled_frames == 0, ( - "终态那条被节流**静默**丢掉了 —— 终态守卫必须排在节流之前") - - -def test_a_dropped_frame_does_not_clear_the_cart_queue(offline_arm): - """⚠ 被节流丢掉的帧**不算发出去过** ⇒ 清队钩子**不许**跑。 - - `_raw_write` 里那道清队钩子 (`_CART_CLEARS_UPON`) 的理据是"固件**收到**这个命令就会 - `cart_invalidate_before_motion()`" —— 帧压根没上 USB 时固件的状态一点没变, 此时清队 - 反而把一条**还有效**的在途请求作废掉。故节流判断必须排在清队**之前**。 - """ - arm = offline_arm - arm._set_tx_repeat_min_interval(P.CMD_ZERO_G, 5.0) - - arm._raw_write(P.CMD_ZERO_G, b"\x01") # 第一条: 真发出去 (顺带清队) - tok = arm._cart.register() - - arm._raw_write(P.CMD_ZERO_G, b"\x01") # 第二条: 被节流 ⇒ 固件侧什么都没发生 - - assert arm._tx_throttled_frames == 1 - assert arm._cart.pending == 1, ( - "被节流丢掉的帧触发了清队 —— 固件那边这条在途请求其实还有效") - assert tok.lost is None - - -# --------------------------------------------------------------------------- -# 4. ⚠⚠ 安全 —— 伺服/保活路径**默认不被节流** (本轮最要紧的一格) -# --------------------------------------------------------------------------- - -def test_moving_paths_are_not_throttled_by_default(offline_arm): - """⚠⚠ `move_js` / `send_mit` 这类 ≥10Hz 重发的路径**默认必须不被节流**。 - - 它们靠**重发**维持固件 0.1s 命令看门狗 (`fail-soft` = 丢重力前馈); 节流会把重发 - 丢掉 ⇒ 伺服断流 / 保活断流。判据取**行为** (真发出去的帧数), 不取配置 - (配置可以改对而行为照错): 3 次逐字节相同的 `move_js` / `send_mit` ⇒ 线上必须 - **3** 条。 - - ⚠ 本用例在改动前后**都是绿的** (它钉的是"默认关闭"这个**不变量**, 不是新功能) —— - 它的牙由变异证明: 把 `_tx_repeat_min_interval` 改成对 0x03/0x04 预置一个间隔, - 它立刻红在下面那两句计数上。 - """ - arm = offline_arm - q, dq = [0.1] * arm.n, [0.0] * arm.n - - for _ in range(3): - arm.move_js(q, dq=dq) # 0x03: 伺服 - for _ in range(3): - arm.send_mit(0, 0.1, 0.0, 50.0, 2.0, 0.0) # 0x04: 透传 - - assert len(arm._tr.stamps_of(P.CMD_MOVE_JS)) == 3, ( - "伺服重发被节流掉了 —— 固件 0.1s 看门狗会 fail-soft") - assert len(arm._tr.stamps_of(P.CMD_MOVE_MIT)) == 3, ( - "透传重发被节流掉了 —— 同上") - assert arm._tx_repeat_min_interval == {}, ( - "节流间隔表默认非空 —— 任何一条命令都可能被静默节流") - - -def test_enabling_the_throttle_on_the_keepalive_drops_it(offline_arm): - """⚠⚠ 反侧: **一旦**对保活 `0x06` 打开节流, 重发真的会被丢掉。 - - 这条与上一条合起来才说明"默认关闭"为什么是**安全相关**的开关 (而不是一个 - 无害的省流旋钮) —— 同时它也把上一条的牙交代清楚: 机制真的会吃帧。 - """ - arm = offline_arm - arm._set_tx_repeat_min_interval(P.CMD_ZERO_G, 5.0) - - for _ in range(3): - arm._raw_write(P.CMD_ZERO_G, b"\x01") - - assert len(arm._tr.stamps_of(P.CMD_ZERO_G)) == 1, ( - "对 0x06 打开节流之后重发没被丢 —— 这条用例失去了意义 (机制没生效)") - assert arm._tx_throttled_frames == 2 - - -def test_the_throttle_setter_validates_its_arguments(offline_arm): - """旋钮自己守门: 负间隔 / 越界 cmd 直接拒 (不然它会变成"静默打开"的入口)。""" - arm = offline_arm - with pytest.raises(InvalidCommandError): - arm._set_tx_repeat_min_interval(P.CMD_MOVE_JS, -1.0) - with pytest.raises(InvalidCommandError): - arm._set_tx_repeat_min_interval(P.CMD_MOVE_JS, float("nan")) - - arm._set_tx_repeat_min_interval(P.CMD_MOVE_JS, 0.5) - assert arm._tx_repeat_min_interval == {P.CMD_MOVE_JS: 0.5} - arm._set_tx_repeat_min_interval(P.CMD_MOVE_JS, 0.0) # 0 = 关 - assert arm._tx_repeat_min_interval == {} - - diff --git a/tests/test_silent_noops.py b/tests/test_silent_noops.py deleted file mode 100644 index 3cee533..0000000 --- a/tests/test_silent_noops.py +++ /dev/null @@ -1,140 +0,0 @@ -"""静默失效 —— 命令回了 ACK,但**实际效果不是调用方以为的那个**。 - -这类缺陷比崩溃危险: 调用方拿到成功返回,臂却处于另一种状态。三条来自固件对照审阅, -每一条都已在固件源码里核实过: - -* `set_ff_mask(0x1000)` —— 固件 `params/params.c:237` 是 `ff_mask = mask & FF_ALL_MASK`, - SDK 也这么掩。于是误用高位 → 掩成 **0 = 前馈全关** → **重力补偿被静默关掉, 臂会垂下来**。 -* `set_motion_mode(4)` —— 固件 `control_loop.c:1338-1342` 的 `ctrl_set_motion_mode()` 只有 - 一行 `park_requested = (mode == 0u);`,**mode 从不写进 `g_arm.mode`**。除 0 以外任何值 - 都只是"清除 park 声明",回 ACK 但模式不变。**从前这里只 `warnings.warn` 一下就照发 - 命令** —— 告警被日志淹没时调用方拿到的仍是"成功";现在直接抛 `InvalidCommandError`。 -* `set_speed(0.3)` —— `bytes([0.3])` 抛裸 `TypeError`(不是本包的错误类型)。 -""" -from __future__ import annotations - -import math - -import pytest - -from litearm import _protocol as P -from litearm.errors import InvalidCommandError - - -# --------------------------------------------------------------- ff_mask -def test_set_ff_mask_rejects_bits_outside_the_mask(offline_arm): - """误用高位不得被静默折成 0 (那等于把前馈全关, 臂会垂)。""" - arm = offline_arm - with pytest.raises(InvalidCommandError) as ei: - arm.set_ff_mask(0x1000) - assert "0x1FF" in str(ei.value) or "FF_ALL" in str(ei.value) or "范围" in str(ei.value) - - -def test_set_ff_mask_rejects_negative(offline_arm): - """`-1 & 0x1FF == 0x1FF` —— 会被静默变成"全开", 同样必须拒绝。""" - with pytest.raises(InvalidCommandError): - offline_arm.set_ff_mask(-1) - - -def test_set_ff_mask_accepts_all_defined_bits(offline_arm): - arm = offline_arm - arm.set_ff_mask(P.FF_ALL) - assert arm.get_ff_mask() == P.FF_ALL - arm.set_ff_mask(0) - assert arm.get_ff_mask() == 0 - - -# --------------------------------------------------------- motion mode -def test_set_motion_mode_rejects_out_of_range(offline_arm): - with pytest.raises(InvalidCommandError): - offline_arm.set_motion_mode(256) - with pytest.raises(InvalidCommandError): - offline_arm.set_motion_mode(-1) - - -def test_set_motion_mode_rejects_values_other_than_zero(offline_arm): - """非 0 模式在本固件无效果 (阶段 A 未内建) —— 必须**响亮失败**, 不能回 ACK 当成功。 - - ⚠ 这里从前只发一条 `RuntimeWarning` 就照发命令: 告警会被日志淹没, 而调用方 - 拿到的是一个"成功"的返回, 臂其实还在旧模式。非 0 值固件**只**改 - `park_requested`(即"清除 park 声明"), 不写 `g_arm.mode`。 - """ - arm = offline_arm - before = list(arm._tr.tx_log) - with pytest.raises(InvalidCommandError) as ei: - arm.set_motion_mode(4) - msg = str(ei.value) - assert "只识别 0" in msg, f"报错没有写清本固件只认 0: {msg}" - assert "park" in msg, f"报错没有给出替代动作 (arm.park()): {msg}" - assert arm._tr.tx_log == before, "拒绝之后仍然把 0x20 发了出去" - - -def test_set_motion_mode_zero_is_quiet(offline_arm): - """mode=0 是 park 声明, 有真实语义, 不该有告警。""" - import warnings - with warnings.catch_warnings(): - warnings.simplefilter("error") - offline_arm.set_motion_mode(0) - - -def test_park_is_recommended_path(offline_arm): - import warnings - with warnings.catch_warnings(): - warnings.simplefilter("error") - offline_arm.park() - - -# --------------------------------------------------------------- speed -def test_set_speed_rejects_non_integer(offline_arm): - """`set_speed(0.3)` 不得抛裸 TypeError —— 按 0..1 思维调用是高发误用。""" - with pytest.raises(InvalidCommandError): - offline_arm.set_speed(0.3) - - -def test_set_speed_rejects_out_of_range(offline_arm): - with pytest.raises(InvalidCommandError): - offline_arm.set_speed(101) - with pytest.raises(InvalidCommandError): - offline_arm.set_speed(-1) - - -def test_set_speed_boundaries_are_accepted(offline_arm): - offline_arm.set_speed(0) - offline_arm.set_speed(100) - - -# ------------------------------------------------- move_p 万向锁到位判定 -def test_move_p_arrives_when_firmware_canonicalises_rpy_at_gimbal_lock(offline_arm): - """固件 `kin_rot_to_rpy` 在 |pitch|≈π/2 时**强制 yaw=0** (锁分支 `kin.c:380-384`)。 - - 目标 (roll=0.5, pitch=π/2, yaw=0.2) 与固件回读的 (roll=0.3, π/2, 0.0) 其实是 - **同一个旋转** (只依赖 roll-yaw), 但逐分量比较会差 0.2rad > rpy_tol -> - 旧实现每次都耗满 move_timeout 才报"未到位"。 - """ - arm = offline_arm - arm.move_timeout = 0.5 - arm._tr.pos_override = [0.30, 0.0, 0.35] - arm._tr.rpy_override = [0.3, math.pi / 2, 0.0] # 固件规范化后的等价表示 - st = arm.move_p((0.30, 0.0, 0.35, 0.5, math.pi / 2, 0.2)) - assert st is not None - - -def test_move_p_still_rejects_a_genuinely_different_orientation(offline_arm): - """别把判定放松成"永远到位": 真的差 90° 必须仍判未到位。""" - arm = offline_arm - arm.move_timeout = 0.4 - arm._tr.pos_override = [0.30, 0.0, 0.35] - arm._tr.rpy_override = [0.0, 0.0, math.pi / 2] # yaw 差 90° - with pytest.raises(Exception) as ei: - arm.move_p((0.30, 0.0, 0.35, 0.0, 0.0, 0.0)) - assert "未到" in str(ei.value) or "到位" in str(ei.value) - - -def test_pose_near_keeps_componentwise_behaviour(offline_arm): - """新增的旋转等价判定必须是**超集**: 逐分量已判到的, 不能反而判丢。""" - from litearm.arm import Arm - tcp = (0.3002, 0.001, 0.35, 3.1416, 0.0, 0.001) - goal = (0.30, 0.0, 0.35, 3.1416, 0.0, 0.0) - assert Arm._pose_near(tcp, goal, 0.006, 0.03) - far = (0.60, 0.0, 0.35, 3.1416, 0.0, 0.0) - assert not Arm._pose_near(far, goal, 0.006, 0.03) diff --git a/tests/test_status_layout.py b/tests/test_status_layout.py deleted file mode 100644 index c574dcb..0000000 --- a/tests/test_status_layout.py +++ /dev/null @@ -1,99 +0,0 @@ -"""状态帧布局兼容性 —— 固件 1.5.x 的 `6+21N` 与旧版 `4+21N` 都必须能解。 - -固件侧权威定义: litearm-stm32/User/litearm/hal/usb_cmd.c 的 usb_cmd_report_status() - 0x40 = flags(u16) + seq(u16) + 每轴 [q,dq,tau,t_mos,t_coil f32×5 + err u8] + joint_fault(u16, 仅 1.5.x) - 7J: 6+21*7 = 153B (1.5.x) / 4+21*7 = 151B (<=1.4.x); 1J: 27B / 25B -flags bit9 = enabled (1.5.0 起) -""" -from __future__ import annotations - -import struct - -import pytest - -from litearm import _protocol as P -from litearm import state as ST - - -def synth_status(n=7, mode=1, flags=0, joint_fault=0, err=0, layout=6): - """按指定布局造一帧状态 payload (layout=6 → 1.5.x, layout=4 → 旧版)。""" - body = bytearray(struct.pack(" 视为 0, 不抛错。""" - p = synth_status(7, mode=1, flags=(1 << 9), layout=4) - assert len(p) == 151 - st = ST.decode_state(p) - assert st.n == 7 - assert st.joint_fault == 0 - assert st.enabled is True - - -def test_decode_1j_both_layouts(): - for layout, ln in ((6, 27), (4, 25)): - p = synth_status(1, mode=6, flags=1, layout=layout) - assert len(p) == ln - st = ST.decode_state(p) - assert st.n == 1 and st.faulted - - -def test_decode_enabled_bit_is_not_flag(): - """bit9=enabled 不能被当成安全 flag 名报出来 (flags 低 6 位才是)。""" - p = synth_status(7, mode=1, flags=(1 << 9), layout=6) - st = ST.decode_state(p) - assert st.flag_names == [] - assert st.enabled is True - assert not st.faulted - - -def test_decode_rejects_junk(): - for bad in (b"", b"\x01\x02", synth_status(7, layout=6) + b"\x00"): - with pytest.raises(ValueError): - ST.decode_state(bad) - - -def test_decode_status_tuple_shape(): - """decode_status 返回含 joint_fault (旧调用方按位置解包的形状保持不变)。""" - flags, seq, mode, names, joints, jf = P.decode_status(synth_status(7, layout=6)) - assert mode == 1 and len(joints) == 7 and jf == 0 - - -def test_err_byte_decoded(): - st = ST.decode_state(synth_status(7, mode=1, err=13, layout=6)) - assert st.joints[0].err == 13 - - -# ---------------------------------------------------------------- 版本门 -def test_min_firmware_requires_1_5(): - from litearm.arm import MIN_FW - - assert MIN_FW == (1, 5, 0) - - -def test_version_gate_rejects_1_4(fake_transport_factory): - """1.4.0 是旧布局 (4+21N), 本包最低要求 1.5.0。""" - from litearm import Arm - from litearm.errors import FirmwareMismatchError - - fake_transport_factory(fw="Litearm1.4.0-7J") - with pytest.raises(FirmwareMismatchError): - Arm(port="fake").connect() diff --git a/tests/test_teardown.py b/tests/test_teardown.py deleted file mode 100644 index 27ebb94..0000000 --- a/tests/test_teardown.py +++ /dev/null @@ -1,403 +0,0 @@ -"""会话收尾 (teardown) —— 幂等 `connect()`/`disconnect()`/`close()` + 上下文管理器 + 兜底收尾。 - -分层: - - **幂等**: 重复调用是 no-op (不抛、也不重建会话); - - **收口**: `disconnect()` 与 `close()` 是同一个操作; 收尾 = 收保活线程 → 关链路 → 清状态; - - **兜底**: 用户**没**显式 `close()` 时也必须收干净 —— 且兜底**只能**是 `close()` 自己 - (第二套清理逻辑会漂), 且不许挂死/漏异常。 - -⚠ 兜底的**机制**与规格 §6.6 写的不一样 (规格写 `weakref.finalize`), 依据是实测: - - `weakref.finalize(obj, func, *args)` 的 `func` 与 `args` **一个都不许引用 obj** - (CPython 文档原话: 否则 obj 永远不会被回收 ⇒ 兜底永不触发); 而回调真正跑起来时, - obj **已经**被回收 —— 连 `weakref.ref(obj)` 放进 args 也拿不到东西: - - weakref.finalize(self, _cb, weakref.ref(self)) - # _cb 里 ref() 返回 **None** (实测: CPython 3.13.5) - - ⇒ "兜底 ⟹ 委托给 `Arm.close()`" 这条要求在 `weakref.finalize` 下**物理上做不到**, - 除非把整个会话状态搬进一个独立对象 (那是重写, 不属于本 Task)。故用 `Arm.__del__` - —— 它拿到的 `self` 是**活的**, 于是能原样委托给 `close()`。 - ⚠ 代价 (如实记, 不是缺陷掩盖): 保活线程的 target 是 `self._zg_keepalive` (绑定方法), - 线程活着就**钉住** Arm ⇒ **保活进行中**被丢弃的 Arm 收不到兜底 (见下面 - `test_a_running_keepalive_thread_pins_the_arm` —— 它把这条限制钉住, 免得被误读成保证)。 -""" -from __future__ import annotations - -import gc -import sys -import threading -import time - -import pytest - -import litearm as pa -from litearm import _protocol as P -from litearm.errors import TransportError - - -def _no_unraisable(monkeypatch): - """捕获 `sys.unraisablehook` 的报告 —— 兜底里的异常绝不该从这里漏出去。 - - 为什么用这个口而不是 `pytest.raises`: 兜底跑在 **gc 时刻**, 异常不会被任何 - `try` 接住 —— 它要么被我们自己吞掉, 要么以 "Exception ignored in ..." 的形式 - 走 `sys.unraisablehook` (实测: 不吞的 `__del__` 会走这里, 吞掉的不会)。 - """ - seen = [] - monkeypatch.setattr(sys, "unraisablehook", lambda a: seen.append(str(a.exc_value))) - return seen - - -# =========================== 幂等: connect =========================== - -def test_connect_three_times_does_not_rebuild_the_session(offline_arm): - """重复 `connect()` **不抛**, 而且必须是 **no-op** —— 不是"关掉再连一遍"。 - - 只断言"不抛"是不够的: 旧实现每次 `connect()` 都 `close()` 后重建 (桩上照样不抛), - 于是**在途的笛卡尔记账被清空、保活被中断、串口被关掉又打开** —— 一个"重复调用" - 白白打断正在跑的会话。判据取 **transport 身份不变** (no-op 的硬证据)。 - """ - arm = offline_arm - tr = arm._tr - for _ in range(3): - assert arm.connect() is arm - assert arm._tr is tr, "重复 connect() 重建了会话 —— 它是 no-op, 不是重连" - - -def test_connect_with_a_different_port_does_retarget(offline_arm): - """⚠ **幂等不是"永远不做事"**: 显式给了**另一个端口**时必须真的改靶。 - - 否则 `connect("/dev/ttyACM2")` 会被静默吞掉, 用户以为连的是 ACM2 而实际还在 ACM1 - —— 本模块一贯不接受这种"静默无效"。要"强制重建同一个目标"用 `reconnect()`。 - """ - arm = offline_arm - tr = arm._tr - arm.connect("/dev/other") - assert arm._tr is not tr, "换端口被静默吞掉了" - assert arm._tr.port == "/dev/other" - - -def test_retargeting_closes_the_old_transport_before_opening_the_new_one(offline_arm): - """⚠ 改靶必须**先收干净旧会话**再开新的 —— "换个引用"不是收尾。 - - 旧链路不关 = 串口句柄还开着 (fd/驱动侧资源泄漏), 而且旧传输**仍在册** - (`transport._PORT_OWNERS`) ⇒ 同一个口想再连回来会被自己的僵尸挡住。既有那条改靶 - 用例只断言"换了新 `_tr` 且 `.port` 对", 对"旧链路关没关"**恒不敏感** - (实测: 把那一处 `self.close()` 换成 `pass`, 全量 531 passed 全绿)。 - """ - arm = offline_arm - old = arm._tr - arm.connect("/dev/other") - - assert arm._tr is not old, "换端口被静默吞掉了" - assert arm._tr.port == "/dev/other" - assert not old.is_open, ( - "改靶没有关掉旧链路 —— 旧串口还开着 (既漏句柄, 又让旧端口名在册占位)") - - -def test_reconnect_forces_a_fresh_session(offline_arm): - """`reconnect()` 与 `connect()` 的分工: 前者**无条件**重建, 后者已连就 no-op。 - - (这条是为了让 `reconnect()` 名副其实 —— 旧实现它是 `return self.connect(port)`, - 一旦 `connect()` 变成 no-op, 它就会跟着变成一个什么都不做的别名。) - """ - arm = offline_arm - tr = arm._tr - assert arm.reconnect() is arm - assert arm._tr is not tr, "reconnect() 没重建会话" - - -# =========================== 幂等: transport.close =========================== - -def test_serial_transport_close_is_idempotent(monkeypatch): - """`SerialTransport.close()` 幂等 —— 判据不止"不抛", 还有"**第二次不再碰串口**"。 - - 上层有**三条**收尾路径 (`close()` / `disconnect()` / `__del__` 的兜底) 全落在这一个 - 方法上, 幂等是它们能互相叠加的前提。⚠ 只断言"不抛"是不够的: pyserial 的 `close()` - 自己带 `if self.is_open:` 守卫, 于是"靠它兜"的实现也能不抛 —— 但那是**别人的** - 实现细节 (它 `os.close()` 中途失败时 `is_open` 会停在 True, 下一次就重试一串已经 - 关掉的 fd), 契约得由我们这一层说了算。判据取**实际调用次数**。 - """ - import types - - from litearm.transport import SerialTransport - - calls = [] - - class FakeSerial: - def __init__(self, port, baudrate=0, timeout=0.2, **kw): - self.is_open = True - self.timeout = timeout - - def read(self, size=1): - return b"" - - def write(self, d): - return len(d) - - def flush(self): - pass - - def close(self): - calls.append(1) - self.is_open = False - - monkeypatch.setitem(sys.modules, "serial", types.SimpleNamespace(Serial=FakeSerial)) - tr = SerialTransport("/dev/null") - assert tr.is_open is True - tr.close() - tr.close() - tr.close() - assert len(calls) == 1, f"重复 close() 又去关串口了 (实际调了 {len(calls)} 次)" - assert tr.is_open is False - - -# =========================== 幂等: disconnect / close =========================== - -def test_disconnect_three_times_does_not_raise(offline_arm): - """`disconnect()` 是幂等的 —— 连续 3 次是 no-op, 不是错误。""" - arm = offline_arm - tr = arm._tr - arm.disconnect() - assert tr.closed is True, "disconnect() 没关链路" - for _ in range(3): - arm.disconnect() - - -def test_disconnect_on_a_never_connected_arm_is_silent(): - """从未 `connect()` 过的对象上 `disconnect()` 也必须不抛 (teardown 永远可达)。""" - pa.Arm(port="/dev/never").disconnect() - - -def test_close_three_times_does_not_raise(offline_arm): - """`close()` 幂等 —— 它是所有收尾路径的**唯一**实现, 不许因为"已经关过"就抛。""" - arm = offline_arm - arm.close() - for _ in range(3): - arm.close() - - -def test_disconnect_and_close_are_the_same_operation(fake_transport_factory): - """两个名字**一个操作** —— `disconnect()` 只是松灵 API 的肌肉记忆名。 - - 判据取"可观测结局逐条相同": 链路关、`_tr`/`_a` 置空、保活停、会话状态清零。 - """ - fake_transport_factory() - a, b = pa.Arm(port="fake").connect(), pa.Arm(port="fake").connect() - a._zg_active = True # 让"收保活"这一步有活干 - b._zg_active = True - a.close() - b.disconnect() - for arm in (a, b): - assert arm._tr is None and arm._a is None - assert arm._zg_active is False - assert (arm.firmware, arm.fw_version, arm.n) == ("", None, 0) - - -def test_close_clears_the_session_state(offline_arm): - """收尾的第三件事是**清状态** —— 关掉之后不许再报上一个会话的事实。 - - `firmware`/`n`/`_cart_supported` 都是**握手与探测**的产物: 链路一关, 它们说的就是 - 一个已经不存在的会话 (下一个对象可能是另一台臂、另一个固件版本)。留着它们必然 - 导致"读到一个没人再维护的旧值"。 - """ - arm = offline_arm - assert arm.firmware.startswith("Litearm") and arm.n > 0, "前置: 握手已完成" - assert arm._cart_supported is not None, "前置: 笛卡尔能力已探过" - arm.close() - assert arm.firmware == "", "close() 后仍在报旧会话的固件版本串" - assert arm.fw_version is None - assert arm.n == 0, "close() 后仍在报旧会话的关节数" - assert arm._cart_supported is None, "close() 后仍缓存着旧会话的能力探测结果" - - -def test_close_does_not_clear_what_is_not_session_state(offline_arm): - """⚠ 反向判据: **别把旋钮和累计计数一起清掉**。 - - - `_tx_repeat_min_interval` 是**用户配置**, 清掉 = 静默关掉同帧节流; - - `_tx_throttled_frames` 是**累计可观测计数** (与 `flush_failures` 同类), 它记的是 - "这个进程一共丢过几帧", 不随会话归零; - - `_dfu_entered` 是会话**终态** (见 `ArmIsInDfuError`) —— 关闭**不**能给它解锁; - - `_cart` 的在途记账**刻意**不在这里清 (见 `Arm.connect()` 里那段: 断连那一刻在途 - token 的结局属 `wait()` 的决定)。 - """ - arm = offline_arm - arm._set_tx_repeat_min_interval(P.CMD_GET_FIRMWARE, 0.05) - arm._tx_throttled_frames = 7 - cart = arm._cart - arm._dfu_entered = True # 直接置位: 只验 close() 不动它 - arm.close() - assert P.CMD_GET_FIRMWARE in arm._tx_repeat_min_interval, "用户配置被 close() 清掉了" - assert arm._tx_throttled_frames == 7, "累计计数被 close() 归零了" - assert arm._dfu_entered is True, "close() 给终态解锁了" - assert arm._cart is cart, "close() 重建/清空了在途记账 (那是 connect()/wait() 的事)" - - -# =========================== 上下文管理器 =========================== - -def test_context_manager_closes_the_link_on_exit(fake_transport_factory): - """`with Arm(...) as arm:` 退出即关 —— 不管块里有没有异常。""" - fake_transport_factory() - with pa.Arm(port="fake") as arm: - tr = arm._tr - assert tr is not None and arm.firmware.startswith("Litearm") - assert tr.closed is True, "with 块退出后链路还开着" - assert arm._tr is None - - -def test_context_manager_closes_even_on_exception(fake_transport_factory): - """块里抛异常也要关 (且不吞掉那个异常 —— `__exit__` 返回 False)。""" - fake_transport_factory() - arm = pa.Arm(port="fake") - with pytest.raises(RuntimeError, match="块内故障"): - with arm: - tr = arm._tr - raise RuntimeError("块内故障") - assert tr.closed is True, "with 块异常退出后链路没关" - assert arm._tr is None - - -def test_context_manager_reuses_an_already_connected_arm(offline_arm): - """已经连上的对象进 `with` 不该重连, 但**退出时必须关**。""" - arm = offline_arm - tr = arm._tr - with arm as got: - assert got is arm - assert arm._tr is tr, "进 with 时重连了" - assert tr.closed is True, "退出 with 时没关" - - -# =========================== 兜底收尾 (没有显式 close) =========================== - -def test_dropping_the_arm_closes_the_link(fake_transport_factory): - """**核心判据**: 构造 → 丢弃引用 → 触发 GC ⇒ 链路已关 (句柄不泄漏)。 - - 必须 `gc.collect()`: `Arm` 与 `_Ack`/`_CartPending` 之间是**引用环** - (`_CartPending(arm=self)`), 光靠引用计数收不掉。 - """ - fake_transport_factory() - arm = pa.Arm(port="fake").connect() - tr = arm._tr - assert tr.closed is False - del arm - gc.collect() - assert tr.closed is True, "丢弃 Arm 后串口句柄仍开着 (兜底没生效)" - - -def test_the_backstop_is_close_itself(fake_transport_factory): - """⚠⚠ 兜底**不许**是第二套清理逻辑 —— 判据: 它走的**就是** `Arm.close()`。 - - 用一个把 `close()` 记账 (并 `super().close()`) 的子类: 若兜底自己另外实现一套, - 这里的计数就是 0。两套清理逻辑必然漂 (改了一处忘了另一处)。 - """ - calls = [] - - class Spy(pa.Arm): - def close(self): - calls.append(1) - super().close() - - fake_transport_factory() - arm = Spy(port="fake").connect() - tr = arm._tr - del arm - gc.collect() - assert calls == [1], "兜底没走 close() —— 那就是第二套清理逻辑" - assert tr.closed is True, "兜底走了 close(), 但链路没关" - - -def test_backstop_still_armed_after_close_then_connect(fake_transport_factory): - """⚠ `close()` **不许**把兜底拆掉 (detach): 关掉之后又连上的会话, 照样要有人收尾。 - - 否则 `arm.close(); arm.connect()` 之后丢弃对象 ⇒ **新**会话的句柄泄漏 —— 而这条 - 路径恰恰是"重连"最常见的写法。 - """ - fake_transport_factory() - arm = pa.Arm(port="fake").connect() - arm.close() - arm.connect() - tr2 = arm._tr - del arm - gc.collect() - assert tr2.closed is True, "close() 之后重连的会话没被兜底收掉" - - -def test_backstop_closes_the_link_even_when_teardown_raises(fake_transport_factory, monkeypatch): - """兜底里收保活失败 (抛) 时: **吞掉异常后照常关链路**, 且不许漏成 unraisable。 - - 这就是段二 `close()` 上那条注释记的坑的另一半 —— 解释器退出/GC 时刻把异常抛出去, - 轻则 "Exception ignored in" 刷屏, 重则退出流程挂死。 - """ - seen = _no_unraisable(monkeypatch) - fake_transport_factory() - arm = pa.Arm(port="fake").connect() - tr = arm._tr - - def boom(): - raise TransportError("模拟收保活失败 (串口写卡住)") - - arm.zero_g_stop = boom - arm._zg_active = True # 让 close() 真的走"收保活"这一步 - del arm - gc.collect() - assert tr.closed is True, "收尾抛异常后链路没关 —— teardown 必须照常走完" - assert not seen, f"兜底把异常漏成了 unraisable: {seen}" - - -def test_backstop_does_not_hang_on_a_slow_teardown_write(fake_transport_factory): - """兜底期间那次退出帧 (0x06 off) 写得很慢时: 仍然**返回**并把链路关掉。 - - "不能打哑 CDC" 的可测形态就是这条 —— 收尾路径不许变成一个不返回的调用。 - """ - fake_transport_factory() - arm = pa.Arm(port="fake").connect() - tr = arm._tr - real_write = tr.write_frame - - def slow_write(cmd, payload=b""): - if cmd == P.CMD_ZERO_G: - time.sleep(0.4) - return real_write(cmd, payload) - - tr.write_frame = slow_write - arm._zg_active = True - del arm - t0 = time.monotonic() - gc.collect() - elapsed = time.monotonic() - t0 - assert tr.closed is True, "慢写之后链路没关" - assert elapsed < 5.0, f"兜底花了 {elapsed:.2f}s —— 收尾不许无界等待" - - -def test_a_running_keepalive_thread_pins_the_arm(fake_transport_factory): - """⚠ **如实钉住一条限制** (不是保证): 保活线程活着时, 丢弃 Arm 收不到兜底。 - - 机制: 线程的 target 是 `self._zg_keepalive` (绑定方法) ⇒ 线程持有一个对 Arm 的 - **强引用**, 且运行中的线程本身被 `threading._active` 强引用 ⇒ Arm 根本不可回收, - 兜底自然没机会跑。**这不是本 Task 引入的**, 而是"保活线程"这个设计的固有性质; - 写在这里是为了不让 `__del__` 被读成"忘了关也一定没事" —— 保活期该走 - `with arm.zero_g():` (它退出时会停保活), 而不是指望兜底。 - - ⚠ 本条**不能**用 `offline_arm` 夹具: pytest 会把夹具结果缓存到用例结束, 那时候 - `del arm` 掉的只是本帧的引用, 对象照样活着 (那样这条判据会变成永真的假绿)。 - """ - fake_transport_factory() - arm = pa.Arm(port="fake").connect() - tr = arm._tr - arm._zg_active = True - arm._zg_stop.clear() - # 真的保活线程 (period 5s: 用例结束前不会真写帧), target 是绑定方法 - th = threading.Thread(target=arm._zg_keepalive, args=(5.0,), daemon=True) - th.start() - arm._zg_thread = th - stop_ev = arm._zg_stop - del arm - gc.collect() - assert tr.closed is False, ( - "这条钉的是**限制**: 线程持引用时兜底跑不了 —— 如果这里变成 True, 说明线程的" - "持引用方式变了, 请同步更新本模块 docstring 与 `Arm.__del__` 的说明") - stop_ev.set() - th.join(2.0) - assert not th.is_alive() - gc.collect() - assert tr.closed is True, "线程退出后兜底应当补上" diff --git a/tests/test_tool_offset.py b/tests/test_tool_offset.py deleted file mode 100644 index 78bbb89..0000000 --- a/tests/test_tool_offset.py +++ /dev/null @@ -1,212 +0,0 @@ -"""工具点 (TCP 偏移) —— 换算、入参校验、各入口的落地位置、以及持久化。 - -判据分三层, 缺一层就会出现"注了偏移但没生效"或"注了偏移把别的入口搞坏": - -1. **换算本身** (`litearm.tool` 的纯数学, 不连臂); -2. **落到线上** —— 从 `tx_log` 里把那条帧的载荷解出来, 断言它是**法兰**位姿 - (固件只认法兰), 而不是"函数返回了个东西"; -3. **零偏移时逐字节不变** —— 这条是回归闸: 默认全零 ⇒ 各入口必须与没有这层时完全相同, - 连"多算一遍再四舍五入回来"都不许。 -""" -from __future__ import annotations - -import math - -import pytest - -from litearm import _protocol as P -from litearm import tool -from litearm.errors import InvalidCommandError, MotionTimeoutError - - -def _payload(arm, cmd: int) -> bytes: - """最后一条 `cmd` 的载荷 (没有就是测试写错了, 直接失败)。""" - for c, p in reversed(arm._tr.tx_log): - if c == cmd: - return p - raise AssertionError(f"0x{cmd:02X} 从未被发出") - - -def _pose_of(payload: bytes, off: int = 0) -> list: - """载荷里的位姿 (6 个 f32) —— `off` 用来跳过 `0x3D` 前面的 idx 字节。""" - return [round(v, 6) for v in P.unpack_f32s(payload, off, 6)] - - -# ---------------------------------------------------------------- 换算本身 - -def test_offset_round_trip_keeps_pose(): - """法兰 → 工具 → 法兰必须回到原值 (含 rpy 偏移)。""" - off, R = tool.as_offset((0.05, -0.02, 0.1), (0.0, 0.0, math.pi / 2)) - pose = [0.30, 0.10, 0.40, 0.20, -0.30, 0.50] - back = tool.to_flange(tool.to_tool(pose, off, R), off, R) - assert max(abs(pose[i] - back[i]) for i in range(3)) < 1e-12 - assert max(abs(math.remainder(pose[i] - back[i], 2 * math.pi)) - for i in range(3, 6)) < 1e-12 - - -def test_offset_uses_flange_frame(): - """偏移方向随法兰姿态走 —— pitch=90° 时法兰的 +z 在世界系是 +x。""" - off, R = tool.as_offset((0.0, 0.0, 0.18)) - tool_pose = tool.to_tool([0.30, 0.0, 0.35, 0.0, math.pi / 2, 0.0], off, R) - assert [round(v, 6) for v in tool_pose[:3]] == [0.48, 0.0, 0.35] - - -def test_zero_offset_is_identity(): - assert tool.ZERO.is_identity - assert not tool.as_offset((0.0, 0.0, 1e-9))[0].is_identity - - -@pytest.mark.parametrize("xyz,rpy", [ - ((0.0, 0.0, float("nan")), None), - ((0.0, float("inf"), 0.0), None), - ((0.0, 0.0), None), # 两个数 - ((0.0, 0.0, 0.0, 0.0), None), # 四个数 - (None, (90.0, 0.0, 0.0)), # 度数当弧度填 (超过 10π) - ((0.0, 0.0, 180.0), None), # 毫米当米填 -]) -def test_offset_rejects_bad_input(xyz, rpy): - with pytest.raises(InvalidCommandError): - tool.as_offset(xyz, rpy) - - -# ---------------------------------------------------------------- 落到线上 - -def test_move_p_sends_flange_pose(offline_arm): - """入参是工具位姿, 线上必须是法兰位姿。""" - arm = offline_arm - arm.set_tcp_offset((0.0, 0.0, 0.18)) - arm.move_p((0.48, 0.0, 0.35, 0.0, math.pi / 2, 0.0), speed=0.3) - - sent = _pose_of(_payload(arm, P.CMD_MOVE_P)) - assert sent[:3] == [0.30, 0.0, 0.35] # 法兰退回 0.18 - assert sent[4] == pytest.approx(math.pi / 2, abs=1e-6) - - -def test_move_p_arrival_is_judged_on_the_tool(offline_arm, monkeypatch): - """臂没走到位时仍然要抛超时 —— 偏移不改变"到位"这件事的判据强度。""" - arm = offline_arm - arm.set_tcp_offset((0.0, 0.0, 0.18)) - arm.move_timeout = 0.1 - arm._tr.pos_override = [0.90, 0.90, 0.90] # 桩永远回这个位姿 - with pytest.raises(MotionTimeoutError): - arm.move_p((0.48, 0.0, 0.35, 0.0, math.pi / 2, 0.0), speed=0.3) - - -def test_move_l_move_path_convert_every_pose(offline_arm): - arm = offline_arm - arm.set_tcp_offset((0.0, 0.0, 0.1)) - arm.move_l((0.30, 0.0, 0.45, 0.0, 0.0, 0.0), speed=0.3) - assert _pose_of(_payload(arm, P.CMD_MOVE_L))[:3] == [0.30, 0.0, 0.35] - - arm.move_path([(0.30, 0.0, 0.45, 0.0, 0.0, 0.0), - (0.32, 0.0, 0.45, 0.0, 0.0, 0.0)], speed=0.3) - added = [p for c, p in arm._tr.tx_log if c == P.CMD_CART_ADD] - # `0x3D` 的载荷 = idx u8 + pose[6] ⇒ 位姿从第 1 个字节起 - assert [_pose_of(p, 1)[2] for p in added] == [0.35, 0.35] - assert [_pose_of(p, 1)[0] for p in added] == [0.30, 0.32] - - -def test_move_c_accepts_a_tool_space_start(offline_arm): - """`start` 与实测 TCP 的本地校验两端都换算 ⇒ 传**工具**起点必须能过。 - - 不换算的写法会在这里直接 `InvalidCommandError` (实测 TCP 是法兰, 差 0.18 m)。 - """ - arm = offline_arm - arm.set_tcp_offset((0.0, 0.0, 0.18)) - arm._tr.pose = [0.30, 0.0, 0.35, 0.0, 0.0, 0.0] # 固件实测 (法兰) - tool_start = [0.30, 0.0, 0.53, 0.0, 0.0, 0.0] # 同一构型的工具点 - - arm.move_c(tool_start, - (0.30, 0.0, 0.55, 0.0, 0.0, 0.0), - (0.32, 0.0, 0.55, 0.0, 0.0, 0.0), speed=0.3) - # `0x3B` 的载荷 = via[6] + goal[6] + sp —— 起点不在帧里 (固件取实测 TCP), - # 它只参与上面那道**本地**校验, 而那道校验两端都做了换算才会放行。 - raw = _payload(arm, P.CMD_MOVE_C) - assert _pose_of(raw, 0)[:3] == [0.30, 0.0, 0.37] # via 换算法兰 - assert _pose_of(raw, 24)[:3] == [0.32, 0.0, 0.37] # goal 换算法兰 - - -def test_ik_converts_pose(offline_arm): - arm = offline_arm - arm.set_tcp_offset((0.0, 0.0, 0.18)) - arm.ik((0.48, 0.0, 0.35, 0.0, math.pi / 2, 0.0), q_seed=[0.0] * 7) - sent = _pose_of(_payload(arm, P.CMD_GET_IK)) - assert sent[:3] == [0.30, 0.0, 0.35] - assert sent[4] == pytest.approx(math.pi / 2, abs=1e-6) - - -def test_get_tcp_stays_flange_and_tool_readback_is_offset(offline_arm): - arm = offline_arm - assert arm.get_tcp().value == pytest.approx((0.30, 0.0, 0.35, 0.0, 0.0, 0.0)) - assert arm.get_tool_tcp().value == pytest.approx((0.30, 0.0, 0.35, 0.0, 0.0, 0.0)) - - arm.set_tcp_offset((0.0, 0.0, 0.10)) - assert arm.get_tcp().value == pytest.approx((0.30, 0.0, 0.35, 0.0, 0.0, 0.0)) - assert arm.get_tool_tcp().value == pytest.approx((0.30, 0.0, 0.45, 0.0, 0.0, 0.0)) - - -# ---------------------------------------------------------------- 零偏移 = 行为不变 - -def test_zero_offset_sends_the_pose_untouched(offline_arm): - """默认零偏移时载荷必须与入参逐字节一致 (回归闸)。""" - arm = offline_arm - pose = (0.31, -0.02, 0.36, 0.1, -0.2, 0.3) - arm.move_p(pose, speed=0.3) - assert _pose_of(_payload(arm, P.CMD_MOVE_P)) == [round(v, 6) for v in pose] - - -def test_offset_survives_reconnect(offline_arm): - """偏移是"这把工具"的属性, 不是会话状态 —— `connect()` 不许清它。""" - arm = offline_arm - arm.set_tcp_offset((0.0, 0.0, 0.18), (0.0, 0.0, 0.5)) - arm.reconnect() - assert arm.tcp_offset.xyz == (0.0, 0.0, 0.18) - assert arm.tcp_offset.rpy == (0.0, 0.0, 0.5) - - -def test_clear_offset_restores_flange_control(offline_arm): - arm = offline_arm - arm.set_tcp_offset((0.0, 0.0, 0.18)) - arm.clear_tcp_offset() - assert arm.tcp_offset.is_identity - pose = (0.31, 0.0, 0.36, 0.0, 0.0, 0.0) - arm.move_p(pose, speed=0.3) - assert _pose_of(_payload(arm, P.CMD_MOVE_P)) == [round(v, 6) for v in pose] - - -# ---------------------------------------------------------------- 负载耦合 + 持久化 - -def test_payload_is_set_together_with_the_offset(offline_arm): - """"换工具"两半: 同时给 `payload_mass` 时顺带下发 0x28 item4。""" - arm = offline_arm - arm.set_tcp_offset((0.0, 0.0, 0.18), payload_mass=0.58, - payload_com=(0.0, 0.0, 0.05)) - item4 = [(c, p) for c, p in arm._tr.tx_log - if c == P.CMD_SET_FF_SCALAR and p[0] == 4] - assert item4, "0x28 item4 (payload_mass) 没有下发" - assert arm.get_ff_scalar(4).value == pytest.approx(0.58) - - -def test_save_and_load_round_trip(offline_arm, tmp_path): - arm = offline_arm - path = str(tmp_path / "sub" / "tool.json") - assert arm.load_tool(path) is False # 文件不存在 ⇒ False, 不抛 - - arm.set_tcp_offset((0.01, -0.02, 0.18), (0.0, 0.0, math.pi / 2)) - written = arm.save_tool(path) - assert written.endswith("tool.json") - - arm.clear_tcp_offset() - assert arm.tcp_offset.is_identity - assert arm.load_tool(path) is True - assert arm.tcp_offset.xyz == pytest.approx((0.01, -0.02, 0.18)) - assert arm.tcp_offset.rpy[2] == pytest.approx(math.pi / 2) - - -def test_malformed_config_is_reported_not_swallowed(offline_arm, tmp_path): - arm = offline_arm - path = tmp_path / "tool.json" - path.write_text("不是 json", encoding="utf-8") - with pytest.raises(Exception) as exc: - arm.load_tool(str(path)) - assert "JSON" in str(exc.value) diff --git a/tests/test_transport.py b/tests/test_transport.py deleted file mode 100644 index 625e2fe..0000000 --- a/tests/test_transport.py +++ /dev/null @@ -1,835 +0,0 @@ -"""真实 SerialTransport 的字节流解析 —— 此前零覆盖 (桩测试整替换掉了 transport)。 - -覆盖: 连续多帧、逐字节到达、噪声字节、CRC 坏帧、**半帧读超时不丢帧**。 -用 fake `serial.Serial` 注入 (read(1) 每次最多 1 字节, 与真实用法一致)。 -""" -from __future__ import annotations - -import os -import struct -import sys -import time -import types -import weakref - -import pytest - -from litearm import _protocol as P -from litearm.errors import TransportError -from litearm.transport import SerialTransport - - -def mk_status(seq, n=7): - body = bytearray(struct.pack(" 该帧必须能续读出来, 不能被丢掉。 - - 旧实现在超时时把已消费的 SOF 丢掉、把余下字节当新流扫描, 导致整帧丢失 - (注入 5 帧只收到 seq [1,3,4,5])。 - """ - frames = [mk_status(s) for s in range(1, 6)] - _install(monkeypatch, b"".join(frames), delay_at=len(frames[0]) // 2) - tr = SerialTransport("/dev/null") - got = _drain(tr) - assert [struct.unpack_from(" 后续补上 LEN/PAYLOAD 仍能解出。""" - fr = mk_status(42) - _install(monkeypatch, fr, delay_at=2, delay_s=0.06) - tr = SerialTransport("/dev/null") - got = _drain(tr) - assert [struct.unpack_from("= end` 就 `return None` —— 一个字节都不读, 于是 - "数据早已躺在驱动缓冲里"这一支**永远取不到**。真机上 `Arm.poll_cart()` 因此在**任何** - 情况下都返回 `None` (它走的就是 `read_frame(0.0)`), 而离线用例全绿 —— 因为桩 - (`fake_serial.FakeTransport.read_frame`) 把 `timeout` 参数整个**忽略**掉了 - (它只管 `if self._resp: pop(0)`)。 - """ - st = _install(monkeypatch, P.pack_frame(P.RSP_STATUS, b"\x01\x02")) - tr = SerialTransport("/dev/null") - - fr = tr.read_frame(0.0) - assert fr is not None and fr[0] == P.RSP_STATUS, ( - "库里就有一条完整帧, 非阻塞读却返回 None —— 它没有真的去取") - assert st["buf"] == bytearray(), "帧还留在'内核缓冲'里 —— 一个字节都没取走" - - -def test_a_zero_timeout_read_does_not_wait_for_a_partial_frame(monkeypatch): - """非阻塞读**不许**为了凑齐半帧而等 —— 库里只有半帧时立刻返回 `None` 并**保留**它。 - - (这条与上一条是一对: 上一条钉"要真的读", 这一条钉"别读起来没完"。) - """ - full = P.pack_frame(P.RSP_STATUS, b"\x01\x02") - st = _install(monkeypatch, full[:6]) - tr = SerialTransport("/dev/null") - - t0 = time.monotonic() - assert tr.read_frame(0.0) is None - assert time.monotonic() - t0 < 0.05, "非阻塞读睡下去了" - - assert st["buf"] == bytearray() and len(tr._buf) == 6, "半帧没被保留下来" - st["buf"] += full[6:] - assert tr.read_frame(0.05) is not None, "半帧之后的续读没能凑齐" - - -def _install_endless_noise(monkeypatch, cut_after_s: float = 3.0): - """注入 fake Serial: `read()` **永远**返回噪声字节, **永不**返回 `b""`。 - - ⚠ 这是 `_NONBLOCK_EXTRA_S` 存在理由所对应的**唯一**形状: 数据**持续**到达时, 超时后 - 那段"非阻塞补读"只能靠**时间**收口 —— 既有用例的桩缓冲要么空 (`b""`)、要么有限, 循环 - 都必然自己结束, 于是**没有任何用例**碰到那条时间上限 (把 `_NONBLOCK_EXTRA_S` 改成 - `float('inf')`, 全量套件照绿)。 - - `cut_after_s` 是**测试自保**: 到点抛异常, 把"没有时间上限"的实现掐断。挂死会拖垮整个 - 套件, 而"抛出来"同样是一条红。 - """ - st = {"reads": 0, "t0": None} - - class EndlessNoise: - def __init__(self, port, baudrate=0, timeout=0.2, **kw): - self.is_open = True - self.timeout = timeout - - def read(self, size=1): - st["reads"] += 1 - if st["t0"] is None: - st["t0"] = time.monotonic() - elif time.monotonic() - st["t0"] > cut_after_s: - raise RuntimeError( - "测试自保: 噪声已灌满 cut_after_s, 被测实现没有时间上限") - return b"\x00" * size # 永远有数据 - - def write(self, d): - return len(d) - - def flush(self): - pass - - def close(self): - self.is_open = False - - monkeypatch.setitem(sys.modules, "serial", - types.SimpleNamespace(Serial=EndlessNoise)) - return st - - -def test_a_zero_timeout_read_is_bounded_even_when_data_keeps_arriving(monkeypatch): - """⚠ `_NONBLOCK_EXTRA_S` 说的是"**已经到达**的字节最多花多久读完" —— 必须**有上限**。 - - 那一支 (`_read_frame_locked` 里 `now >= end` 之后) **没有** `end` 兜底: 只要数据持续 - 到达, 光靠"读到凑出一帧"就没有界。噪声灌满的线上不能把 `read_frame` 变成不返回的循环 - —— 它正是 `Arm.poll_cart()` 走的那条非阻塞口 (`_read_one(0.0)`)。 - - 判据: `read()` 永不返回 `b""` 时, `read_frame(0.0)` 仍必须在 `_NONBLOCK_EXTRA_S` - 量级内返回 `None`。 - (改前实测: 上限取 `inf` ⇒ 这里不返回, 由 `cut_after_s` 抛出 `TransportError` 掐断 ⇒ 红。) - """ - _install_endless_noise(monkeypatch) - tr = SerialTransport("/dev/null") - - t0 = time.monotonic() - fr = tr.read_frame(0.0) - dt = time.monotonic() - t0 - - assert fr is None, "噪声里不该凑出一帧" - assert dt < 0.5, ( - f"read_frame(0.0) 花了 {dt:.3f}s —— `_NONBLOCK_EXTRA_S` 的时间上限没生效 " - f"(数据持续到达时本调用必须有界; 它是 `poll_cart` 的口)") - - - -# ========================== 端点独占 (§6.6 ① ② ③) ========================== -# 背景实测 (E5): **Linux 下 CDC 口不独占** —— 第二个进程 `open` **成功**且分吃同一字节 -# 流 (双方拿残帧、**静默失败**); Windows 反而由 OS 强制独占 ⇒ 独占性因平台而异, 不能 -# 当常量依赖。三处收口都在 `transport.py`, 本节**逐层**咬: -# · 跨进程那层 —— 真 pyserial + 真 flock (`test_an_externally_locked_port_...`); -# · 构造处翻译 —— `exclusive` 抛的就是 `SerialException`; -# · 进程内那层 —— 端口登记表 (用 fake `serial` 把 flock 那层**摘掉**, 只剩登记表)。 -# -# ⚠ 本节的用例**各用一个独享的端口名**: 登记表按端口字符串比, 若都挤在 "/dev/null" 上, -# 前一个用例里那个"还活着"的传输就会挡到后一个 —— 而"它还活着"取决于**帧有没有被引用环 -# 钉住** (pytest 的 `raises(...) as ei` 会造出 `帧 -> ei -> traceback -> 帧` 这个环 ⇒ 该帧 -# 与其中的传输要等 gc 才消失), 于是失败会**按用例顺序传染**。独享端口名把这条耦合去掉。 -# (这不是实现缺陷: 被环钉住的传输**真的**还开着那个 fd —— 登记表报"占用"是真话。) - -def _install_serial(monkeypatch, ser_cls, exc_cls=None): - """注入 fake `serial` 模块 (可带 `SerialException`)。""" - ns = {"Serial": ser_cls} - if exc_cls is not None: - ns["SerialException"] = exc_cls - monkeypatch.setitem(sys.modules, "serial", types.SimpleNamespace(**ns)) - - -_ORIGINAL_TEXT = "桩: 原文保留判据" - - -def _broken_serial(exc_cls, at: str): - """造一个"在 `at` 处抛 `exc_cls(原文)`"的 fake `serial.Serial`。 - - `at="open"` = 构造处抛 (`exclusive` 被拒就是这一支); `"read"`/`"write"` = 开成功, - 句柄在这两处抛。 - """ - def _boom(): - raise exc_cls(_ORIGINAL_TEXT) - - class BrokenSerial: - def __init__(self, port, baudrate=0, timeout=0.2, **kw): - if at == "open": - _boom() - self.is_open = True - self.timeout = timeout - - def read(self, size=1): - if at == "read": - _boom() - return b"" - - def write(self, d): - if at == "write": - _boom() - return len(d) - - def flush(self): - pass - - def close(self): - self.is_open = False - - return BrokenSerial - - -@pytest.fixture -def pty_port(): - """一对**真** pty 的从端路径 —— 走真 pyserial (本文件的 `_install*` 只在本用例内 - 注入 fake `serial`)。pty 的两个 fd 全程开着, 用完关掉。""" - master, slave = os.openpty() - try: - yield os.ttyname(slave) - finally: - for fd in (slave, master): - try: - os.close(fd) - except OSError: - pass - - -def test_an_externally_locked_port_cannot_be_opened(pty_port): - """① **载重判据**: 该口已被另一条 `open file description` 独占时, `SerialTransport` - 必须**开不起来**。 - - 那条句柄走的是**真的** pyserial (`exclusive=True`), 与"另一个进程打开"是同一条内核 - 判据 —— 测试里起不了第二个进程, 真机的跨进程那半见 Task 9 V5。 - - 变异 (删掉 `exclusive=True`) ⇒ 本用例红: 没有 flock 时第二次 `open` 成功, 那正是 - Linux 上"两个进程静默分吃同一字节流"的形状 (实测本机: 不带 `exclusive` 的第二次 - `open` 确实成功)。 - """ - import serial as real_serial - - holder = real_serial.Serial(pty_port, 921600, timeout=0.2, exclusive=True) - try: - with pytest.raises(TransportError) as ei: - SerialTransport(pty_port) - assert pty_port in str(ei.value), ( - "翻译后的错必须点名是哪个口 —— 只留 pyserial 那句 'Resource temporarily " - f"unavailable' 无从照做 (实际 {str(ei.value)!r})") - finally: - holder.close() - - # 让开之后同一个口必须能开 —— 否则上面那条红可能只是"这个口本身坏了" - tr = SerialTransport(pty_port) - assert tr.is_open - tr.close() - - -def test_arm_connect_on_a_taken_port_raises_a_lite_arm_error(pty_port): - """② 的用户面: 口被占时 `Arm.connect()` 抛的必须是**本包的错误**。 - - 裸 `serial.SerialException` 从 `connect()` 逃出去的话, 上游 `except LiteArmError` - 那类分支全接不住 (它连本包的基类都不是)。 - """ - import serial as real_serial - - from litearm import Arm - - holder = real_serial.Serial(pty_port, 921600, timeout=0.2, exclusive=True) - try: - with pytest.raises(TransportError): - Arm(port=pty_port).connect() - finally: - holder.close() - - -def test_a_second_transport_on_the_same_port_fails_loudly(monkeypatch): - """③ 同进程内两个传输指同一个口 ⇒ 第二个**响亮失败**, 不是静默分吃。 - - 用 fake `serial` (每次构造给一个独立句柄) 把 flock 那层**摘掉** —— 于是本用例咬的 - **只有**登记表: 抽掉登记表, 第二个构造会成功, 那正是"静默分吃"的形状。 - """ - port = "/dev/fake-excl-second" - _install(monkeypatch, b"") - tr1 = SerialTransport(port) - - with pytest.raises(TransportError) as ei: - SerialTransport(port) - - assert port in str(ei.value), f"错里没点名端口: {str(ei.value)!r}" - assert tr1.is_open, "第一个传输不该被这一下动到" - tr1.close() - - -def test_closing_releases_the_port_registration(monkeypatch): - """③ 释放登记 —— 否则**重连会被自己挡住**。 - - `close()`/`disconnect()` 之后同一个口必须能再开: `Arm.reconnect()` 走的就是 - "先关再连"这条路, 而 `disconnect()` 是 `close()` 的别名 ⇒ 两条都落在这一格上。 - """ - port = "/dev/fake-excl-close" - _install(monkeypatch, b"") - tr1 = SerialTransport(port) - tr1.close() - - tr2 = SerialTransport(port) # ← 不许被自己上一个传输挡住 - assert tr2.is_open - tr2.close() - - -def test_dropping_a_transport_releases_the_port_registration(monkeypatch): - """③ 登记判的是"持有者**还活着**", 不是"登记过"。 - - 对象一被回收, 它那个 pyserial 句柄也被一并回收 (pyserial 在 `__del__` 里关 fd) ⇒ - 口**真的**空了。若登记表持**强**引用, 一个忘了 `close()` 的旧对象会永久占住端口名, - 把此后每一次连接都挡掉 (而且没有解开的入口)。 - - 前提 (`weakref` 立刻为 `None`) 是本用例的一部分: 登记表依赖"传输对象**无环**"。 - """ - port = "/dev/fake-excl-drop" - _install(monkeypatch, b"") - tr1 = SerialTransport(port) - ref = weakref.ref(tr1) - del tr1 - - assert ref() is None, ( - "前提破了: `SerialTransport` 变得需要 gc 才回收 —— 登记表的弱引用会滞留, " - "于是'死掉的'传输还会挡住重连") - - tr2 = SerialTransport(port) # ← 不许被一个已死的对象挡住 - assert tr2.is_open - tr2.close() - - -class _Pinned: - """一个**自环**持有者 —— 与 `Arm` 的 `_CartPending(arm=self)` 同型。 - - `self.self = self` 造出引用环: 外层引用一丢, 引用计数收不掉它, 只有全量 gc 能收。 - 真实事故的形状就是这样 —— 用例函数返回、局部名消失之后传输**还活着**, 端口登记里那条 - 弱引用**不会被自动清掉** (要等一次全量 gc), 于是"释放"变成了看时机的事。 - - ⚠ 用例里仍把它放在**局部名**里。那是为了让"持有者此刻一定还活着"成为**确定**的前置 - (不必去赌 gc 跑没跑), 判据才确定; 环本身不参与任何断言。 - """ - - def __init__(self): - self.self = self - self.tr = None - - -def test_a_closed_transport_does_not_block_the_port_even_when_it_is_pinned(monkeypatch): - """③ `close()` 之后同一个口**立刻**能再开 —— 释放**不能**取决于 gc 何时跑。 - - ⚠ 与上一条 (`test_dropping_a_transport_releases_the_port_registration`) 的**分工**: - 上一条咬的是"对象被回收 ⇒ 登记自动消失"那条路 (弱引用), 那一条**本来就**看 gc 何时跑; - 本用例咬的是**另一条路** —— `close()` 里那句 `_release_port`, 它必须**当场**撤登记。 - 两条路都要在, 因为"重连会不会被自己上一个传输挡住"这件事不许由 gc 的调度决定。 - - 持有者用**自环** (`_Pinned`, 与 `Arm` 的 `_CartPending(arm=self)` 同型) 并留在局部名里: - 它此刻**一定**还活着, 所以下面那次构造成功就**只**能来自 `_release_port`, 排除了"其实 - 是弱引用刚好断了"这种解释 —— 断言因此可以下在登记表本身 (**立刻**消失) 上, 而不是 - "迟早会消失"。 - """ - from litearm.transport import _PORT_OWNERS - - port = "/dev/fake-excl-pinned-closed" - _install(monkeypatch, b"") - pinned = _Pinned() - tr1 = SerialTransport(port) - pinned.tr = tr1 # ← 挂在环上 (函数返回后它也还在) - tr1.close() # ← fd 已释放 - - assert port not in _PORT_OWNERS, ( - "close() 之后登记必须**立刻**消失 —— 要靠 gc 才消失的话, 重连会不会被自己上一个" - "传输挡住就成了看时机的事") - - tr2 = SerialTransport(port) # ← 已 close 的口不许被挡住 - assert tr2.is_open, "close() 之后的传输仍然占着端口名 —— 后来者被一个僵尸挡住了" - tr2.close() - - -def test_an_open_transport_blocks_the_port_even_when_it_is_pinned(monkeypatch): - """③ **反向**: 被环钉住**且还开着**的传输, 同一个口的第二者必须响亮失败。 - - 与上一条**只差一个 `close()`** —— 两条合起来把"拦住的是**口还开着**这件事"钉死: - 既不是"登记过", 也不是"对象还在"。少了本用例, 上一条的断言只看"能再开", 无法区分 - "因为 `close()` 撤了登记"与"因为压根没人拦" —— 真·静默分吃会从那个缺口回来。 - """ - port = "/dev/fake-excl-pinned-open" - _install(monkeypatch, b"") - pinned = _Pinned() - pinned.tr = SerialTransport(port) - - assert pinned.tr.is_open - with pytest.raises(TransportError) as ei: - SerialTransport(port) - - assert port in str(ei.value), f"错里没点名端口: {str(ei.value)!r}" - pinned.tr.close() - - -def test_open_failure_is_a_transport_error_that_keeps_the_original_text(monkeypatch): - """② **构造处** —— `exclusive` 被拒时抛的**就是** `SerialException`, 而 `__init__` - 里那句 `serial.Serial(...)` 此前**没有**任何包装 ⇒ 裸异常会从 `Arm.connect()` 逃出去。 - """ - class SerialException(OSError): - pass - - _install_serial(monkeypatch, _broken_serial(SerialException, "open"), SerialException) - - with pytest.raises(TransportError) as ei: - SerialTransport("/dev/fake-excl-open") - - assert _ORIGINAL_TEXT in str(ei.value), ( - f"翻成 TransportError 时把原文丢了: {str(ei.value)!r}") - - -def test_a_failed_open_does_not_leave_the_port_claimed(monkeypatch): - """② 的收尾: 开失败那次**不能**把端口占死 —— 否则修好原因之后重连会被自己挡住 - (那个半成品对象连 `close()` 都不会被调到, 登记没别的释放点)。 - - ⚠ `as ei` 是**载重**的, 不是顺手写的: 它复现的是"异常被上层接住并留着"的真实形状 - (记日志/包一层再抛), 而那一刻 `帧 -> ei -> traceback -> 帧` 成环 ⇒ `__init__` 的帧 - (连其中的 `self`) 要等 gc 才消失。只靠弱引用自动释放的话, 这段时间里端口是**被占着** - 的 —— 显式撤登记才让它与 gc 何时跑无关。 - (变异实测: 把 `__init__` except 里那句 `_release_port` 删掉 ⇒ 本用例红。) - """ - class SerialException(OSError): - pass - - port = "/dev/fake-excl-open2" - _install_serial(monkeypatch, _broken_serial(SerialException, "open"), SerialException) - - with pytest.raises(TransportError) as ei: - SerialTransport(port) - assert _ORIGINAL_TEXT in str(ei.value) # ← `ei` 被留到用例结束 (见 docstring) - - _install(monkeypatch, b"") # 换成能开成功的桩 - tr = SerialTransport(port) - assert tr.is_open, "开失败那次把端口占死了 —— 修好原因之后重连会被自己挡住" - tr.close() - - -def test_arm_close_and_disconnect_release_the_port_registration(monkeypatch): - """③ 的**用户面**收尾: `Arm.close()` / `Arm.disconnect()` 之后同一个口必须能重连 - (那是 `Arm.reconnect()` 走的"先关再连"那条路)。 - - 手工接线 (只测收尾那一格, 不做握手/探测 —— 与本仓既有的手工接线用法同形)。 - `disconnect()` 是 `close()` 的别名, 两条**都咬**: 将来谁把它改成第二套实现 (于是 - 少放一次登记) 就得红。两个名字各用**自己的**端口, 免得第一个 `Arm` 的引用环还没被 - gc 收掉就干扰第二个。 - """ - from litearm.arm import Arm - - _install(monkeypatch, b"") - for closer in ("close", "disconnect"): - port = f"/dev/fake-excl-arm-{closer}" - tr = SerialTransport(port) - arm = Arm(port=port) - arm._tr = tr - - getattr(arm, closer)() - - assert not tr.is_open, f"Arm.{closer}() 没把链路关掉" - tr2 = SerialTransport(port) # ← 登记必须已经放开 - assert tr2.is_open, f"Arm.{closer}() 之后同一个口连不回来 (被自己的登记挡住)" - tr2.close() - - -def test_read_failure_is_a_transport_error_that_keeps_the_original_text(monkeypatch): - """② **读处**: `serial.SerialException` 不许从 `read_frame` 逃出去。""" - class SerialException(OSError): - pass - - _install_serial(monkeypatch, _broken_serial(SerialException, "read"), SerialException) - tr = SerialTransport("/dev/fake-excl-read") - try: - with pytest.raises(TransportError) as ei: - tr.read_frame(0.05) - assert _ORIGINAL_TEXT in str(ei.value) - finally: - tr.close() - - -def test_write_failure_is_a_transport_error_that_keeps_the_original_text(monkeypatch): - """② **写处**: 同上 (⚠ 这一处是**载重**的 —— `_CartPending.request()` 靠 - "`TransportError` ⟹ 整帧未送达" 摘 token, 类型不对会静默变成假成功)。""" - class SerialException(OSError): - pass - - _install_serial(monkeypatch, _broken_serial(SerialException, "write"), SerialException) - tr = SerialTransport("/dev/fake-excl-write") - try: - with pytest.raises(TransportError) as ei: - tr.write_frame(P.CMD_GET_STATUS) - assert _ORIGINAL_TEXT in str(ei.value) - finally: - tr.close() - - -# --------------------------------------------------------------------------- -# 一次读多少字节 —— `_want_bytes` / `_READ_CHUNK_MAX`(2026-09-22 的 33× 修复) -# --------------------------------------------------------------------------- -# -# ⚠ 上面那批用例用的 `_install` fake **没有** `in_waiting` ⇒ 它们跑的是**逐字节**那条 -# 路(语义与改动前逐字相同,所以一条都不用改)。**整块读那条路必须有它自己的用例** —— -# 否则"新路径从没被跑过"就是本仓最忌讳的那种绿。 - -def _close_quietly(*trs): - """用例失败时也要放掉端口注册。 - - ⚠ 不是洁癖:`SerialTransport` 打开时会把端口名**注册**进全局表(同文件后面 - `test_an_open_transport_blocks_the_port_*` 钉的就是它)。一条**该红**的用例若在 - `close()` 之前就断言失败,会把这个注册留在全局 —— 于是它自己多报一条与病因无关的 - `ERROR`,还可能连累后面的用例(本文件某条注释专门讲过这个坑)。 - """ - for t in trs: - try: - t.close() - except Exception: # noqa: BLE001 - 收尾不许掩盖原异常 - pass - - -def _install_with_in_waiting(monkeypatch, data): - """带 `in_waiting` 的 fake Serial —— **真串口就是这样**(有数据就报数量)。 - - 与 `_install` 的差别只有两点:多一个 `in_waiting`、`read` 记下**被要了几个字节**。 - """ - st = {"buf": bytearray(data), "read_sizes": []} - - class FakeSerial: - def __init__(self, port, baudrate=0, timeout=0.2, **kw): - self.is_open = True - self.timeout = timeout - - @property - def in_waiting(self): - return len(st["buf"]) - - def read(self, size=1): - st["read_sizes"].append(size) - if not st["buf"]: - return b"" - out = bytes(st["buf"][:size]) - del st["buf"][:size] - return out - - def write(self, d): - return len(d) - - def flush(self): - pass - - def close(self): - self.is_open = False - - monkeypatch.setitem(sys.modules, "serial", - types.SimpleNamespace(Serial=FakeSerial)) - return st - - -def test_a_port_reporting_in_waiting_is_drained_in_chunks_not_byte_by_byte(monkeypatch): - """⭐ 本修复的**判别力所在**:报得出到达量时,一次多取,不许退回逐字节。 - - 真机实测:这块板子**空闲**时状态流就 ~14 kB/s ⇒ 逐字节读 = 每字节一次 - `select()`+`os.read()` ⇒ 在 2 核机上烧满**一整核**(server 无客户端时也 100.0%)。 - 判据取"一帧只该花常数次读":旧行为对这一帧是 **158 次**。 - """ - frame = mk_status(1) - st = _install_with_in_waiting(monkeypatch, frame) - tr = SerialTransport("/dev/null-chunked") - - try: - fr = tr.read_frame(0.05) - assert fr is not None and fr[0] == P.RSP_STATUS, "整块读那条路没解出帧" - assert len(st["read_sizes"]) <= 3, ( - f"一帧读了 {len(st['read_sizes'])} 次 —— 退回逐字节了: {st['read_sizes']}") - assert max(st["read_sizes"]) > 1, ( - f"从没按到达量取过(一直要 1): {st['read_sizes']}") - finally: - _close_quietly(tr) - - -def test_the_same_stream_parses_identically_byte_by_byte_and_all_at_once(monkeypatch): - """⚠ **粒度不许改变解析结果** —— 这条是"整块读"敢上真机的依据。 - - 同一串字节,分别用【逐字节】与【一次到齐】两种到达方式喂进去, - 解出来的帧序列必须**逐帧相同**(含跨帧的半帧保留、噪声字节跳过)。 - """ - stream = mk_status(1) + mk_status(2) + P.pack_frame(0x34, b"abc") + mk_status(3) - - _install(monkeypatch, stream) # 无 in_waiting ⇒ 逐字节 - tr_a = SerialTransport("/dev/null-gran-a") - byte_by_byte = _drain(tr_a) - - _install_with_in_waiting(monkeypatch, stream) # 有 ⇒ 一次到齐 - tr_b = SerialTransport("/dev/null-gran-b") - all_at_once = _drain(tr_b) - trs = (tr_a, tr_b) - - try: - assert len(byte_by_byte) == 4, f"逐字节那条没解出 4 帧: {byte_by_byte}" - assert byte_by_byte == all_at_once, ( - "到达粒度改变了解析结果 —— 整块读不能上真机") - finally: - _close_quietly(*trs) - - -def test_a_port_without_in_waiting_degrades_to_one_byte_reads(monkeypatch): - """拿不到 `in_waiting` ⇒ **退化成 1**(桩 / 平台不支持时不许抛)。 - - 这条把"既有桩跑的就是旧的逐字节语义"从**巧合**变成**契约**: - 上面那批老用例全绿,靠的就是这条退化路径。 - """ - _install(monkeypatch, b"") - tr = SerialTransport("/dev/null-no-inwaiting") - try: - assert tr._want_bytes() == 1, "没有 `in_waiting` 时没有退化成 1" - finally: - _close_quietly(tr) - - -def test_a_port_reporting_zero_in_waiting_still_reads(monkeypatch): - """`in_waiting == 0` 是"**还没到**",要 **1**(阻塞等),**不是"不读"**。 - - ⚠ 方向是承重的:把 0 读成"没数据 ⇒ 直接返回 b''"会让**每一帧的起始字节都得等 - 下一次调用**,而 `read_frame(0)` 会因此恒返回 None —— 那正是旧实现踩过的坑 - (`poll_cart()` 在真机上恒 None,而离线全绿)。 - """ - frame = mk_status(1) - st = {"buf": bytearray(frame), "read_sizes": []} - - class LyingSerial: - """`in_waiting` **恒报 0**(谎报),但 `read` 照给数据。""" - - def __init__(self, port, baudrate=0, timeout=0.2, **kw): - self.is_open = True - self.timeout = timeout - - @property - def in_waiting(self): - return 0 - - def read(self, size=1): - st["read_sizes"].append(size) - if not st["buf"]: - return b"" - out = bytes(st["buf"][:size]) - del st["buf"][:size] - return out - - def write(self, d): - return len(d) - - def close(self): - self.is_open = False - - monkeypatch.setitem(sys.modules, "serial", - types.SimpleNamespace(Serial=LyingSerial)) - tr = SerialTransport("/dev/null-lying") - - try: - assert tr.read_frame(0.2) is not None, ( - "报 0 时一个字节都不读 —— 帧永远取不到") - assert set(st["read_sizes"]) == {1}, ( - f"报 0 时不该要多个: {sorted(set(st['read_sizes']))}") - finally: - _close_quietly(tr) - - -def test_the_chunk_size_is_capped_and_odd_reports_are_safe(monkeypatch): - """封顶 `_READ_CHUNK_MAX`;负数/异常报告一律当 1。""" - from litearm.transport import _READ_CHUNK_MAX - - st = _install_with_in_waiting(monkeypatch, b"") - tr = SerialTransport("/dev/null-cap") - - try: - st["buf"] = bytearray(100_000) - assert tr._want_bytes() == _READ_CHUNK_MAX, "没有封顶" - st["buf"] = bytearray(2) - assert tr._want_bytes() == 2, "到达量 >1 时没有按到达量要" - st["buf"] = bytearray(1) - assert tr._want_bytes() == 1, "到达量为 1 时应与从前一致(要 1)" - finally: - _close_quietly(tr) diff --git a/tests/test_transport_injection.py b/tests/test_transport_injection.py deleted file mode 100644 index ad67dda..0000000 --- a/tests/test_transport_injection.py +++ /dev/null @@ -1,25 +0,0 @@ -"""可注入传输口 —— 让 Arm 能接一个假传输(离线运行 / litearm-server --dry-run 用)。""" -from litearm import Arm -from litearm.testing import FakeTransport - - -def test_transport_factory_is_used(): - """给了 transport_factory ⇒ connect() 用它,而不是 SerialTransport。""" - made = [] - - def factory(port): - made.append(port) - return FakeTransport() - - arm = Arm(port="fake", transport_factory=factory).connect() - try: - assert made == ["fake"], "工厂没被调用 / 拿到的 port 不对" - assert arm.n == 7, "假件的状态帧应定出 7 轴" - assert arm.firmware.startswith("Litearm") - finally: - arm.close() - - -def test_no_factory_is_none_by_default(): - """不给工厂 ⇒ 保持 None(connect() 里回落到 SerialTransport)。""" - assert Arm(port="fake")._transport_factory is None diff --git a/tests/test_transport_threadsafe.py b/tests/test_transport_threadsafe.py deleted file mode 100644 index 5fd9d6b..0000000 --- a/tests/test_transport_threadsafe.py +++ /dev/null @@ -1,146 +0,0 @@ -"""SerialTransport 的并发安全 —— 加保活线程之前必须先钉住的两个契约。 - -背景: `Arm.zero_g()` 的保活线程会是本 SDK **第一个并发写入者**。原 transport -类 docstring 写着「读写同一锁」, 但文件里没有任何 Lock 对象。并发上线后会出现: - - 保活线程的写与主线程的写交错 -> 帧体互相插入 -> 上位机侧 CRC 全坏; - - 若用「单一 RLock 罩住读写」图省事 -> 主线程一次最长 80ms 的阻塞读会把 - 50ms 周期的保活写拖过期 -> 零重力被看门狗掐掉。 -故设计取**读写各一把锁**: 读者之间互斥 (保护 _buf/_partial_since/_ser.timeout), -写者之间互斥 (保护帧完整性), 读写之间**不互斥** (pyserial 的 os.read/os.write -并发本就安全, 且 _ser.timeout 只被读者改)。 -""" -from __future__ import annotations - -import struct -import sys -import threading -import time -import types - -from litearm import _protocol as P -from litearm.transport import SerialTransport - - -class _RaceSerial: - """模拟真实串口: write 非原子 (分两段 + 中间释放 GIL), read 可被拖慢。""" - - def __init__(self, port, baudrate=0, timeout=0.2, **kw): - self.is_open = True - self.timeout = timeout - self.sink = bytearray() # 上位机"发出去"的字节 - self.rx = bytearray() # 待上位机读的字节 - self.read_delay = 0.0 - - def write(self, d): - h = len(d) // 2 - self.sink += d[:h] - time.sleep(0.0005) # 抢占点: 无锁时另一线程的字节会插进来 - self.sink += d[h:] - return len(d) - - def read(self, size=1): - if self.read_delay: - time.sleep(self.read_delay) - if not self.rx: - return b"" - out = bytes(self.rx[:size]) - del self.rx[:size] - return out - - def flush(self): - pass - - def close(self): - self.is_open = False - - -def _install(monkeypatch, read_delay=0.0): - holder = {} - - class _F(_RaceSerial): - def __init__(self, *a, **kw): - super().__init__(*a, **kw) - self.read_delay = read_delay - holder["ser"] = self - - monkeypatch.setitem(sys.modules, "serial", types.SimpleNamespace(Serial=_F)) - return holder - - -def _scan(buf: bytes): - """按 SOF 扫描出全部**完整且 CRC 正确**的帧; 坏帧被丢弃后继续重扫。""" - out, i = [], 0 - while i + 5 <= len(buf): - if buf[i] != P.SOF: - i += 1 - continue - ln = buf[i + 2] - total = 3 + ln + 2 - if i + total > len(buf): - break - got = P.unpack_frame(buf[i:i + total]) - if got is not None: - out.append(got) - i += 1 - return out - - -def test_concurrent_writers_never_interleave_a_frame(monkeypatch): - """四个线程各写 40 帧 -> 静置区必须恰好 160 个完整帧, 无一帧被拆散。 - - 无锁时 write 的抢占点会让两帧字节交错, 扫描出的完整帧数远少于 160 - (交错帧 CRC 全坏, 只能被丢弃)。 - """ - holder = _install(monkeypatch) - tr = SerialTransport("/dev/null") - n_threads, n_each = 4, 40 - - def worker(tid: int): - for i in range(n_each): - tr.write_frame(P.CMD_MOVE_MIT, struct.pack(" 0.1s 后模式被掐回 fail-soft, 而调用方只看到 ACK (静默失败)。 -""" -from __future__ import annotations - -import threading -import time - -import pytest - -from litearm import _protocol as P -from litearm.errors import InvalidCommandError, TransportError - -#: 固件看门狗 0.10s; SDK 默认保活周期须留 ≥2 倍余量 -_KEEPALIVE_PERIOD = 0.04 - - -def _zg_payloads(arm): - """桩收到的全部 0x06 载荷序列 (含保活线程的并发写)。""" - return [p for c, p in list(arm._tr.tx_log) if c == P.CMD_ZERO_G] - - -def test_zero_g_starts_and_resends_within_keepalive_window(offline_arm): - """进入后必须周期重发 0x06(on=1), 间隔远小于固件 0.10s 超时。""" - arm = offline_arm - with arm.zero_g(): - assert arm.zero_g_active is True - time.sleep(0.30) - ons = [p for p in _zg_payloads(arm) if p == b"\x01"] - assert len(ons) >= 5, ( - f"0.30s 内只发了 {len(ons)} 次 0x06(on=1) —— 保活未生效, " - f"固件 0.10s 后会把模式掐回 fail-soft") - - -def test_zero_g_exit_sends_off_once_then_stops(offline_arm): - """退出: 最后一条 0x06 必须是 on=0, 且之后不再有保活帧、线程已回收。""" - arm = offline_arm - with arm.zero_g(): - time.sleep(0.15) - assert arm.zero_g_active is False - payloads = _zg_payloads(arm) - assert payloads[-1] == b"\x00", "退出未发 0x06(on=0)" - - n = len(payloads) - time.sleep(0.20) - assert len(_zg_payloads(arm)) == n, "退出后仍在发保活帧" - assert not [t for t in threading.enumerate() if t.name.startswith("litearm-zero_g")], \ - "保活线程未回收" - - -def test_other_write_commands_rejected_while_zero_g_active(offline_arm): - """保活期间拒绝其它**动作类**命令 —— 它们会改写模式/看门狗, 与保活互相打架。""" - arm = offline_arm - with arm.zero_g(): - with pytest.raises(InvalidCommandError): - arm.movej([0.1] * 7) - with pytest.raises(InvalidCommandError): - arm.set_speed(50) # 会改写全局调速器 - with pytest.raises(InvalidCommandError): - arm.enable() - arm.set_speed(50) # 退出后恢复可用 - - -def test_safety_actions_bypass_zero_g_guard(offline_arm): - """急停/失能是「降能量」方向的安全动作 —— 保活期间也必须永远可达, 不得被守卫挡住。""" - arm = offline_arm - with arm.zero_g(): - arm.emergency_stop() # 必须发出, 不得抛 InvalidCommandError - arm.disable() - - -def test_state_reads_still_work_while_zero_g_active(offline_arm): - """查询类命令不走守卫 —— 拖动示教期间仍要能读状态。""" - arm = offline_arm - with arm.zero_g(): - st = arm.get_state(refresh=True).value - assert st is not None and st.n == arm.n - assert arm.get_tcp().value is not None - - -def test_close_stops_keepalive_and_releases_thread(offline_arm): - """close() 必须先收干净保活线程 —— 残留线程会在解释器退出时打哑 CDC。""" - arm = offline_arm - arm.zero_g() - time.sleep(0.10) - arm.close() - assert arm.zero_g_active is False - assert not [t for t in threading.enumerate() if t.name.startswith("litearm-zero_g")], \ - "close() 后保活线程仍在运行" - - -def test_stop_without_start_sends_nothing(offline_arm): - """幂等退出 ≠ 无中生有: 从未进入过就不该发任何 0x06。""" - arm = offline_arm - arm.zero_g_stop() - arm.zero_g_stop() - assert _zg_payloads(arm) == [], "未进入零重力却发出了 0x06" - - -def test_keepalive_write_failure_is_raised_not_silent(offline_arm): - """保活写失败 (CDC 掉线) 不能在退出时静默吞掉 —— 臂已脱离零重力。""" - arm = offline_arm - arm._tr.zg_fail_after = 3 - with pytest.raises(TransportError): - with arm.zero_g(): - time.sleep(0.40) - assert arm.zero_g_active is False diff --git a/tests/test_zero_g_cart_guard.py b/tests/test_zero_g_cart_guard.py deleted file mode 100644 index 77a80df..0000000 --- a/tests/test_zero_g_cart_guard.py +++ /dev/null @@ -1,194 +0,0 @@ -"""反向守卫: **笛卡尔在途时拒绝进入零重力** (`zero_g()` / `zero_g_start()`)。 - -规格 §5.2(4) 的两条理由 (缺一不可): - -1. 固件 `0x06` 丢掉位置环、只剩重力前馈 —— 轨迹中途进场会让臂**靠摩擦滑停 - (coast)**, 比 `movej()` 的受控接管 / `emergency_stop()` 差得多。拦下来并把 - 替代动作写进消息 = 把操作员推向**更好的停机动作**。 -2. 它堵掉吸收额度的残余: 保活线程每 40ms 一条 `0x06` 在清队集合里, "笛卡尔在途 + - 零重力保活"会让清队拿到 `n=1` 的额度并存活 `move_timeout`, 那条额度可能吞掉 - 下一条**合法**应答。拦住这个交错 ⇒ 该残余在生产路径上不再可达。 - -⚠ **方向相反的另一侧不拦**: `movej`/`movej_sync` 是**受控接管** (新 S 曲线从当前 -状态收口), 拦它等于把人推去用更重的 `emergency_stop`。只做 `zero_g` 这一侧。 -⚠ **`zero_g_stop()` 不拦** (退出动作, 降能量方向必须永远可达), 同理 -`emergency_stop()` / `disable()` / `get_tcp()`。 - -判据用**两条信号** (见 `Arm._reject_if_cart_in_flight`): ① `_cart_serial` 被持有; -② **现取**的状态帧 bit10。只用①漏 `wait=False`, 只用②漏"刚登记还没起规划"。 -""" -from __future__ import annotations - -import struct -import threading - -import pytest - -from litearm import _protocol as P -from litearm.errors import InvalidCommandError, LiteArmError, MotionTimeoutError - -#: 与 `test_cart_protocol.py` 同款的目标位姿 (桩的初始 TCP 就是它) -TCP0 = (0.30, 0.0, 0.35, 0.0, 0.0, 0.0) - - -def _zg_writes(arm): - """桩收到的 0x06 载荷序列 (守卫失败时必须是空集 —— 一帧都不该发)。""" - return [p for c, p in list(arm._tr.tx_log) if c == P.CMD_ZERO_G] - - -def _enter_busy_window(arm): - """把桩摆到「0x4E 已回、规划仍在跑」那一刻。 - - 桩的 `CART_BUSY` 窗口写死为 `0x4E` 之后的**第 2..7 帧** (`fake_serial._stamp_status`), - 而 `cart_busy_seq` 每次受理时归 0 —— 于是紧接着的第一帧恰好不带 bit10。 - 置 1 即"下一帧就落在窗口内", 也就是 `wait=False` 返回之后臂仍在跑的真实时刻。 - """ - arm._tr.cart_busy_seq = 1 - - -# --------------------------------------------------------------- 判据 ① -def test_zero_g_rejected_while_a_cartesian_call_holds_the_serial_lock(offline_arm): - """① 串行锁被持有 ⇒ 有一次笛卡尔调用正在途 (三条入口全程持它)。""" - arm = offline_arm - holding = threading.Event() - release = threading.Event() - - def holder(): - with arm._cart_serial: # 模拟一条正在途的 move_l/move_c/move_path - holding.set() - release.wait(5.0) - - th = threading.Thread(target=holder, name="cart-in-flight", daemon=True) - th.start() - try: - assert holding.wait(5.0), "辅助线程没拿到锁 —— 用例没测到要测的东西" - before = list(arm._tr.tx_log) - with pytest.raises(InvalidCommandError) as ei: - arm.zero_g() - msg = str(ei.value) - assert "零重力" in msg - assert "movej" in msg or "emergency_stop" in msg, \ - f"只拒绝而不给出路会把操作员卡住: {msg}" - assert arm._tr.tx_log == before, "守卫拦下之前就写了帧 (0x06 必须在写之前拦)" - assert arm.zero_g_active is False, "被拒的 zero_g 不该留下 active 状态" - finally: - release.set() - th.join(5.0) - - -# --------------------------------------------------------------- 判据 ② -def test_zero_g_rejected_after_wait_false_returned_with_the_arm_still_running(offline_arm): - """② `wait=False` 已返回 (锁已释放) 但臂仍在跑 ⇒ 只看锁会放行, 必须靠现取的 bit10。 - - 这正是计划点名的那条坑, 也是真机 V3 唯一走得通的形状 (`wait=True` 时调用方 - 阻塞在到位等待里, 根本调不到 `zero_g()`)。 - """ - arm = offline_arm - arm.move_l(TCP0, speed=0.3, wait=False) - _enter_busy_window(arm) - - # 锁**确实**空闲 —— 否则本用例就退化成判据 ①, 测不到 bit10 这一条 - assert arm._cart_serial.acquire(blocking=False) is True, "锁被持有, 用例没测到 bit10" - arm._cart_serial.release() - # ⚠ 此刻 `_a.state` 还是**旧**帧 (bit10=0): 拿它当判据就会假放行 —— 守卫必须现取。 - # 这一行同时是"新鲜采样"那一条的判据 (用陈旧帧的实现会在这里放行)。 - assert arm._a.state is not None and arm._a.state.cart_busy is False, \ - "用例前提不成立: 陈旧帧没有停在 bit10=0, 分辨不出'现取'与'用旧帧'" - - with pytest.raises(InvalidCommandError) as ei: - arm.zero_g() - assert "零重力" in str(ei.value) - # ⚠ 判据只钉 `0x06`: 守卫自己会发一条 `0x40` (现取状态帧), 那是它的手段不是副作用 - assert _zg_writes(arm) == [], "守卫拦下之前就把 0x06 发了出去" - # 事后复核: 那一刻固件确实报忙 (否则本用例是空跑) - assert arm.get_status_now().value.cart_busy is True, "桩此刻没报忙, 用例没测到 bit10" - - # 反向对照: 桩报停稳时同一条调用必须放行 (否则守卫会把正常示教拦死) - arm._tr.cart_busy_seq = None - with arm.zero_g(): - assert arm.zero_g_active is True - - -# --------------------------------------------------------------- 判据 ③ -def test_exit_and_energy_down_actions_are_never_blocked(offline_arm): - """③ 退出/降能量/只读动作在**同样条件下**一律不被拦。 - - 守卫若被挂到 `_write_cmd`/`_raw_write` 上 (而不是 `zero_g_start` 里), 这四条会 - 一起被挡 —— 那是把安全动作变成不可达, 方向错得比漏拦更严重。 - """ - arm = offline_arm - arm.move_l(TCP0, speed=0.3, wait=False) - _enter_busy_window(arm) - holding = threading.Event() - release = threading.Event() - - def holder(): - with arm._cart_serial: - holding.set() - release.wait(5.0) - - th = threading.Thread(target=holder, name="cart-in-flight", daemon=True) - th.start() - try: - assert holding.wait(5.0) - arm.zero_g_stop() # 退出动作 (且幂等) - arm.zero_g_stop() - arm.emergency_stop() # 降能量方向 - arm.disable() - assert arm.get_tcp().value is not None # 只读查询 - assert _zg_writes(arm) == [], "从未进入零重力却发出了 0x06" - finally: - release.set() - th.join(5.0) - - -# ------------------------------------------------- 取不到状态 ⇒ 保守拒绝 -def test_status_that_cannot_be_confirmed_is_a_conservative_refusal(offline_arm, monkeypatch): - """取不到状态帧 ⇒ **保守拒绝** —— "未确认就不拦"漏过去的正是 coast 那一侧。""" - arm = offline_arm - # (a) 等状态帧时**读到一条 ERR** —— 用桩的 `unknown_cmds` 造出来 (它照 `fake_serial.py` - # 建模固件 `usb_cmd.c` 的 `default` 分支: 回 `ERR{cmd,0x00}`)。 - # ⚠ 别把这句读成"固件对 0x40 回 ERR": 真固件的 `CMD_GET_STATUS` - # (`usb_cmd.c:566-568`) 只把 RAM 里的 `g_arm` 打包 (`usb_cmd_report_status()`), - # **没有失败路径、没有门禁/长度校验** —— 它**永远回 `RSP_STATUS`、永不回 `ERR`**。 - # 真能产生 `ERR{0x40,·}` 的只有一根: 固件的 `default` 分支 (那版固件里根本没有这条 - # 命令) —— 也就是上面桩建模的那一支。另一支能走到这里的是**别的命令的迟到 `ERR` - # 串台**, 但那种 ERR 带的是**别的**命令码, 不是 0x40。两支在这儿殊途同归: - # `get_status_now` 对**任意** `RSP_ERR` 都抛 (它自己那一句 `raise _err_from(...)`, - # `arm.py:655`; `_err_from` 的**定义**在 `arm.py:134` —— 别引成 `_read_status` 里 - # 那处 `:627`。这条路径**没有** `expect` 那层 `echo_cmd` 过滤), 于是同样落到 - # "保守拒绝"。 - # 本用例测的是**那条拒绝路径**, 不是固件真会这么回。 - arm._tr.unknown_cmds.add(P.CMD_GET_STATUS) - with pytest.raises(InvalidCommandError) as ei: - arm.zero_g() - assert "保守拒绝" in str(ei.value), str(ei.value) - assert _zg_writes(arm) == [], "状态未确认却仍然进了零重力" - arm._tr.unknown_cmds.discard(P.CMD_GET_STATUS) - - # (b) 超时: 连状态帧都收不到 - def _timeout(self, timeout: float = 0.5): - raise MotionTimeoutError("桩: 故意超时") - - monkeypatch.setattr(type(arm), "get_status_now", _timeout) - with pytest.raises(InvalidCommandError) as ei2: - arm.zero_g() - assert "保守拒绝" in str(ei2.value), str(ei2.value) - assert _zg_writes(arm) == [], "状态未确认却仍然进了零重力" - - -def test_extra_0x4e_desync_is_not_masked_as_unconfirmed(offline_arm): - """⚠ 例外里**不能**兜整个 `LiteArmError` —— "多了一条 `0x4E`" 抛的是基类。 - - 那条的含义是"固件与主机**已经**错配", `cart.py` 刻意让它响亮 (连专用异常类型都 - 刻意不给, 免得后人 `except` 掉)。守卫把它改写成"取不到状态、保守拒绝"就等于 - 把协议失步藏进一句常规拒绝里 —— 方向与那处刻意相反。 - """ - arm = offline_arm - arm._tr.push_frame(P.RSP_CART_PLAN, bytes([1, 0]) + struct.pack(" Date: Mon, 26 Oct 2026 17:38:28 +0800 Subject: [PATCH 2/4] docs: drop stale test references and warn on save_params The test suite is gone, so comments pointing at tests/... no longer resolve. Replace them with the behavior they described, or state that the check is now manual. AGENTS.md now points at the smoke check instead of a test suite. Arm.save_params() carries an explicit warning: irreversible whole-sector flash write, requires the disabled state, and the erase window must not be interrupted. params.py, payload.py and load_tool() cross-reference it. --- src/litearm/_protocol.py | 59 +++++++++++++++---------------- src/litearm/arm.py | 76 +++++++++++++++++++++++----------------- src/litearm/cart.py | 40 +++++++++------------ src/litearm/errors.py | 7 ++-- src/litearm/params.py | 3 +- src/litearm/payload.py | 7 ++-- src/litearm/state.py | 7 ++-- src/litearm/testing.py | 26 ++++++-------- src/litearm/transport.py | 8 ++--- 9 files changed, 117 insertions(+), 116 deletions(-) diff --git a/src/litearm/_protocol.py b/src/litearm/_protocol.py index 4785c3d..45bcc29 100644 --- a/src/litearm/_protocol.py +++ b/src/litearm/_protocol.py @@ -156,9 +156,9 @@ # ② 与下行 `CMD_GET_FIRMWARE 0x41` **撞号** —— 同 `0x49` (CMD_KIN_BENCH / RSP_JOINT_PARAM) # 那类"双 ID": 收发方向不同, 靠方向区分, 不可用单张 ID 表查。 # -# ⚠ **为什么保留而不删**: `test_protocol_sync.py::test_every_firmware_rsp_has_sdk_constant` -# 按**名字**遍历固件头的 `RSP_*`, 固件头里那一行还在 ⇒ **删 SDK 常量会让段三验收立刻红**; -# 而且 0x41 属**固件仓**的决定, 本轮是纯 SDK/文档侧 (spec §8)。 +# ⚠ **为什么保留而不删**: 当年按**名字**遍历固件头的 `RSP_*` 做双向比对, 固件头里那一行 +# 还在 ⇒ 删 SDK 常量会让那条检查失败; 而且 0x41 属**固件仓**的决定, 本轮是纯 +# SDK/文档侧 (spec §8)。仓库已无测试套件, 但常量本身仍应与固件头对齐。 # ⚠ **别说成"没有别的豁免路径"**: 机制上当然可以再往 `FIRMWARE_ONLY_RSPS` 添一项来豁免它; # **不这么做是设计选择** —— 那张表的语义是"用户裁决 SDK **有意不暴露**" ("不做", 不是 # "还没做"), 把一条**没人发**的应答塞进去语义不符 (同理见 `PREEXISTING_GAPS` 的注释)。 @@ -188,7 +188,7 @@ RSP_LICENSE = 0x4F #: [授权] **本版无生产者** —— 激活成功回的是 `ACK{0x3F}`(见 `CMD_ACTIVATE`), #: 故固件里**没有任何代码会发出** 0x50; 该号只被占住。 -#: ⚠ 保留定义是为了让 `test_protocol_sync` 的按名比对自然通过 —— **不要**给它造生产者, +#: ⚠ 保留定义是为了让按名比对固件头时自然通过 —— **不要**给它造生产者, #: 也不要塞进 `FIRMWARE_ONLY_RSPS` (那张表的语义是"SDK 有意不暴露", 与"固件没有生产者"不同)。 RSP_ACTIVATE = 0x50 @@ -200,7 +200,7 @@ # ---- [2026-09-14] 动力学模型在线导入 (0x30/0x32/0x33/0x34/0x35/0x37/0x38/0x39) ---- # 固件侧三层语义 (bank/staging/生效层) 与完整注释见 litearm-stm32 的 # User/litearm/hal/usb_cmd.h; SDK 封装见 litearm/model.py。 -# ⚠ 常量名必须与固件头**逐字相同** —— test_protocol_sync 按名字双向比对。 +# ⚠ 常量名必须与固件头**逐字相同** —— 协议同步靠人工按名字双向比对。 # ff_mask 位 (固件 litearm.h) FF_MASTER = 0x0001 @@ -224,10 +224,10 @@ #: (joint_cfg.h 顶部三条理由, 其中 ② 是 flash 布局随开关变却不 bump #: `FLASH_STORE_VERSION` ⇒ **静默丢现场标定**; 另有防"再打开"的 `#error` 硬守卫)。 #: ⇒ 当前固件**不再定义**这个宏, 本常量只服务**仍要支持的 1J 老固件** -#: (`Litearm1.7.0-1J`, 见 `tests/test_ik_bench.py` / `conftest.offline_arm_1j`)。 +#: (`Litearm1.7.0-1J`; 离线可用 `FakeTransport(n=1)` 复现)。 #: **不要当成死代码删掉** —— 删了 1J 会话的 IK 种子就会填错轴。 -#: 跨仓一致性由 tests/test_protocol_sync.py::test_bench_model_axis_matches_sdk_constant -#: 守: 固件仍有该宏则逐值比对, 固件已移除则断言守卫在 + 本常量仍在。 +#: 跨仓一致性需**人工**核对: 固件仍有该宏时逐值比对; 固件已移除时本常量仍须保留 +#: (仓库已无测试套件来守这条)。 BENCH_MODEL_AXIS = 5 #: 固件**状态帧频率** (Hz)。`RSP_STATUS` 是被动连续流, 固定 100 Hz (10 ms) —— @@ -266,19 +266,16 @@ def parse_boot_banner(text: str) -> Optional[str]: return "iwdg-rst" if "iwdg-rst" in hits[-1] else "normal" -#: 「协议无死角」契约: 固件每条**已实现**的下行命令 -> SDK 上的一等方法入口。 -#: 由 `tests/test_protocol_sync.py` 强制: 直接解析固件 `hal/usb_cmd.h`, 双向比对 -#: 命令集合与 ID, 并逐条断言这里的入口在 `Arm` 上真的可解析到。少一条命令就红。 #: **请求 → 它的那条 `RSP_*` 应答**(只列"应答不是 `ACK`/`ERR`"的命令)。 -#: ⚠ **名字刻意不叫 `CMD_*`**:`tests/test_protocol_sync.py` 把所有 `CMD_` 前缀的 -#: 模块级名字当成**命令码常量**去和固件头对表,叫 `CMD_TO_RSP` 会被判成 -#: "SDK 声明了固件没有的命令"(实测踩过)。 +#: ⚠ **名字刻意不叫 `CMD_*`**:历史测试曾把所有 `CMD_` 前缀的模块级名字当成 +#: **命令码常量**去和固件头对表, 叫 `CMD_TO_RSP` 会被判成"SDK 声明了固件没有的命令" +#: (实测踩过);这个命名禁忌仍值得保留, 免得以后重新加检查时再踩。 #: #: 唯一的用途是 `Arm._raw_write` 在**发出前**清掉本命令的应答队列(见那里)—— #: `ACK`/`ERR` 两条由命令码自己就能推出来,故**不在这张表里**。 #: ⚠ `0x40` (`GET_STATUS`) 也不在:它的应答是 `RSP_STATUS`,走的是**单槽**不是队列。 -#: ⚠ 与固件的对应关系逐条抄自本文件上面各 `CMD_*` 的注释;改固件时这里要跟着改 -#: (`tests/test_protocol_sync.py` 会盯 `CMD_*`/`RSP_*` 常量本身,这张表**没有**自动判据)。 +#: ⚠ 与固件的对应关系逐条抄自本文件上面各 `CMD_*` 的注释;改固件时这里要跟着改, +#: 且这张表**没有**自动判据 (仓库已无测试套件)。 RSP_OF_CMD = { 0x24: 0x49, # GET_JOINT_PARAM -> RSP_JOINT_PARAM 0x2B: 0x4B, # GET_FF_VEC -> RSP_FF_VEC @@ -295,6 +292,9 @@ def parse_boot_banner(text: str) -> Optional[str]: } +#: 「协议无死角」契约: 固件每条**已实现**的下行命令 -> SDK 上的一等方法入口。 +#: 仓库已无测试套件, 这张表靠**人工**对照固件 `hal/usb_cmd.h` 维护: 双向核对命令 +#: 集合与 ID, 并确认这里的入口在 `Arm` 上真的可解析到。少一条命令不会有人报红。 COMMAND_COVERAGE = { 0x01: "Arm.movej", 0x07: "Arm.movej_sync", @@ -364,16 +364,16 @@ def parse_boot_banner(text: str) -> Optional[str]: # # 历史: 用户 2026-09-13 一度裁决 SDK **不暴露**笛卡尔运控入口(spec §7.1 选项 A), # 故 `0x3A~0x3E` / `0x4E` 这 6 条曾是"固件有、SDK 无",在这里显式豁免, -# 免得 test_protocol_sync.py 因双向比对而长期红着(哨兵红久了就失去意义)。 +# 免得此后按名比对时被当成"固件有、SDK 无"的缺口。 # # [段二] 该裁决已被"固件原生笛卡尔"取代: 5 条命令与那条应答现在都有 SDK 入口与常量 # (`COMMAND_COVERAGE` 的 0x3A/0x3B/0x3C/0x3D/0x3E / 本节上方的 `RSP_CART_PLAN`), # 于是两张豁免表**同时清空**。留空是有意的 —— 与 `UNIMPLEMENTED_CMDS` 同一个用法: # 它现在是"当前没有任何固件单边命令"这句话的断言载体, 而不是可以顺手塞东西的地方。 # -# ⚠ 与 `test_protocol_sync.py` 的耦合: `test_firmware_only_exemption_is_still_valid` -# 逐个断言"豁免表里的名字在固件头文件里仍然存在、且 SDK **还没有**同名常量"。 -# 往这里加条目等于宣布"SDK 有意不做这条命令", 加之前先想清楚是不是真的不做。 +# ⚠ 往这里加条目等于宣布"SDK 有意不做这条命令", 加之前先想清楚是不是真的不做。 +# 仓库已无测试套件; 当年那条逐项断言"豁免表里的名字在固件头文件里仍然存在、且 +# SDK **还没有**同名常量"的检查已移除, 改表时需人工对照固件头。 # ⚠ **不要**把"已知缺口"塞进来: 那是 `PREEXISTING_GAPS` 的语义(本应同步而未同步), # 两者的理由不同, 混在一起会让读的人以为缺口是有意为之。 # --------------------------------------------------------------------------- @@ -388,18 +388,17 @@ def parse_boot_banner(text: str) -> Optional[str]: # 【既有的固件/SDK 不同步 —— **只豁免, 不修复**】(**现已清空**) # # 历史: 固件自 `b6cbc33`(DFU 免探针烧录)起有 `CMD_ENTER_DFU = 0x15`, 而 SDK 侧 -# `grep -ri dfu src/ tests/` **命中 0**。当时**豁免而非修复**的理由三条: +# `grep -ri dfu src/` **命中 0**(当时也扫过 tests/)。当时**豁免而非修复**的理由三条: # ① 它不是那一笔的产物(修它等于把另一个特性的决定塞进去); # ② 长期红着会让**真正的**回归看不见(哨兵失效, 与 `UNIMPLEMENTED_CMDS` 同一个理由); # ③ DFU 是固件**维护**命令(进 ROM bootloader), 不是运动 API, 豁免语义成立。 # # [段三] 该缺口已被**补上**: `0x15` 现在有常量、有入口 (`Arm.enter_dfu`, 两段式: # ACK 之后还要**等设备真的消失**), 并登记进 `COMMAND_COVERAGE` —— 于是本表**清空**, -# 覆盖契约 = **47/47**。留空是有意的, 与 `UNIMPLEMENTED_CMDS` / `FIRMWARE_ONLY_CMDS` -# 同一个用法: 它现在是"**当前没有任何既有的固件/SDK 不同步**"这句话的断言载体, -# 而不是可以顺手塞东西的地方(哨兵 `test_firmware_only_exemption_is_still_valid` -# 对它逐条断言"固件里仍有这条命令、且 SDK **还没有**同名常量" ⇒ 往空表里塞东西前, -# 先确认那件事真的没做)。 +# 当时的覆盖契约 = **47/47** (仓库现已无测试套件, 这条契约需人工维持)。留空是有意的, +# 与 `UNIMPLEMENTED_CMDS` / `FIRMWARE_ONLY_CMDS` 同一个用法: 它现在是"**当前没有 +# 任何既有的固件/SDK 不同步**"这句话的断言载体, 而不是可以顺手塞东西的地方 +# (往空表里塞东西前, 先确认固件里仍有这条命令、且 SDK **还没有**同名常量)。 # ⚠ **两张表的语义不要混**: `FIRMWARE_ONLY_CMDS`/`FIRMWARE_ONLY_RSPS` 的语义是 # "用户裁决 SDK **有意不暴露**"("不做", 不是"还没做"; 笛卡尔 0x3A~0x3E / 0x4E 曾是 # 那里的例子, 段二已暴露并补上入口, 见本节上方那段历史说明 —— ⚠ 别按行号找, 它会漂); @@ -427,10 +426,10 @@ def crc16_ccitt_false(data: bytes) -> int: * `crc_hqx` 实测 **232×** 快(68.1 µs → 0.29 µs,同一台机器同一载荷)。 ⚠ **等价性不是"看算法像"认定的,是测出来的**:3260 个载荷(长度 0..259 全覆盖 + - 随机)与真帧逐一比对 **0 不一致**;并由 `tests/test_protocol_crc.py` **长期钉住** —— - 那里有一份**独立的纯 Python 参考实现当判据**,另有 CRC 目录的**标准检查值** - (`"123456789"` → `0x29B1`)。**别把那条用例改成拿本函数跟 `crc_hqx` 对拍** —— - 那是自己验自己,判据会失去判别力。 + 随机)与真帧逐一比对 **0 不一致**;当时用一份**独立的纯 Python 参考实现当判据**, + 另有 CRC 目录的**标准检查值**(`"123456789"` → `0x29B1`)。**别为了"验证"拿本函数 + 跟 `crc_hqx` 对拍** —— 那是自己验自己,判据会失去判别力;仓库已无测试套件,需要 + 复核时请保留独立参考实现。 """ return binascii.crc_hqx(data, 0xFFFF) diff --git a/src/litearm/arm.py b/src/litearm/arm.py index 65be883..40d3b2b 100644 --- a/src/litearm/arm.py +++ b/src/litearm/arm.py @@ -183,7 +183,7 @@ def _err_from(payload: bytes, prefix: str) -> CommandRejectedError: """把固件 ERR 应答映射成异常 (可读文本查 `errors.ERR_TEXT`, 见 spec §6.3)。 `code == 0x00` ⟺ 固件 `usb_cmd.c` 的 `default` 分支 —— 即**未实现该命令**, - 且固件侧无任何副作用 (唯一真源, 由 `tests/test_protocol_sync.py` 钉住)。 + 且固件侧无任何副作用 (唯一真源是固件 `default` 分支; 仓库已无测试套件来守它)。 已实现命令的错误码一律落在 `0x01..0x07`。 ⚠ 消息里的语义文本**不在这里写死**: 走 :func:`litearm.errors.err_reason`, @@ -403,15 +403,15 @@ class _Ack: `_arrive` 恰好是没做的那一个 (实测: 逐处各塞一条外来 `ACK`, 只有那两处涨计数); `cart` 那处是后来补齐的一处 (而它偏偏是持锁最长的一段), `poll_cart` 是紧随其后的 一处 (它从前在本 docstring 里被**单列**成"已知缺口", 现已补上), `_wait_until_link_lost` - 是**段三最后**补的一处 (见 `tests/test_read_one.py` 里那几条同形用例, 以及 - `tests/test_dfu.py` 里专给它的一条)。 + 是**段三最后**补的一处 (当时的用例覆盖了 `_read_one` 与 DFU 入口的同形路径; + 仓库已无测试套件)。 """ def __init__(self, arm: "Arm"): #: ⚠ **弱引用**:读线程不能钉住 `Arm`。线程的 target 是绑定方法 ⇒ 线程持有一个 #: 对 `_Ack` 的强引用,若 `_Ack` 再强引 `Arm`,那么**忘了 `close()` 的 `Arm` 再也 - #: 不会被回收** ⇒ `Arm.__del__` 的兜底收尾永不触发 ⇒ 端口不释放(实测: - #: `test_teardown.py` 的六条兜底用例全红)。弱引用把这条边断掉,兜底就能回来。 + #: 不会被回收** ⇒ `Arm.__del__` 的兜底收尾永不触发 ⇒ 端口不释放(实测确认过)。 + #: 弱引用把这条边断掉,兜底就能回来。 self._arm = weakref.ref(arm) # ---- 读线程 (起停见 `Arm.connect()` / `Arm.close()`) ---- self._reader: Optional[threading.Thread] = None @@ -752,9 +752,8 @@ def __init__(self, port: Optional[str] = None, *, #: ⚠ **注入点排在 `connect()` 的 `find_cdc_port()` 空值检查之后**(见那里), #: 所以调用方**必须同时给一个占位 port**(如 `"fake"`):否则无硬件时会在走到 #: 本工厂**之前**就抛 `TransportError("未找到 STM32 CDC")`。 - #: ⚠ 带前导下划线是**刻意**的 —— `tests/test_full_coverage.py` 的公开成员哨兵 - #: (`{n for n in dir(arm) if not n.startswith("_")}`) 看不见它,因此新增本参数 - #: **不需要**放宽那条哨兵(白放宽一条哨兵是本仓文化里的危险动作)。 + #: ⚠ 带前导下划线是**刻意**的 —— 它只给离线假传输用, 不属于公开 API + #: (`dir(arm)` 的公开成员检查看不见它)。不要为了图方便把它改成公开参数。 self._transport_factory = transport_factory self._tr: Optional[SerialTransport] = None self._a: Optional[_Ack] = None @@ -837,9 +836,8 @@ def __init__(self, port: Optional[str] = None, *, #: 锁不是会话状态, 重建会让"旧会话的持锁者"与"新会话的持锁者"同时进临界区。 self._cart_serial = threading.RLock() #: 固件是否支持笛卡尔 (受 `#if LITEARM_CART_PLAN` 约束) —— `connect()` 里探一次。 - #: ⚠ 名字**必须**带前导下划线: `test_full_coverage.py` 的 - #: `test_public_api_surface_is_all_exercised` 要求每个公开成员都被练习过, - #: 公开一个没人读的探测缓存会让那条哨兵变红。 + #: ⚠ 名字**必须**带前导下划线: 它只是探测缓存, 不是公开 API。 + #: 公开一个没人读的探测缓存会无谓扩大公开面。 self._cart_supported: Optional[bool] = None #: 探测**没获确认** (3 次全安静 = 上行丢帧) 而不是"固件确报不支持" —— 只用来给 #: `_require_cart_support` 分两支措辞 (归因用), 不参与任何判据。 @@ -1042,8 +1040,8 @@ def close(self) -> None: 持有的那个**继承来的 fd 留给进程退出时由内核关闭** —— 它既不读也不写 (守卫把 命令全拒了), 父进程也另有自己的 fd, 故留着是无害的; 比"为了体面地关一个 fd 而 挂死"划算得多。 - ⚠ 判据: `tests/test_fork_guard.py` 里那条"`close()` 不碰传输"的用例 —— 它在 - 修复前**必红** (修复前会走到 `self._tr.close()`)。 + ⚠ 判据: fork 出来的子进程里 `close()` **一个字节都不许碰传输** (上面那几行就是 + 执行点); 修复前会走到 `self._tr.close()` 并永久挂死。 """ if self._pid is not None and os.getpid() != self._pid: # fork 守卫: 见 docstring —— 绝不能走到下面取传输层锁的那几行。 @@ -1135,7 +1133,7 @@ def __del__(self) -> None: 也拿不到东西 —— 实测 (CPython 3.13.5) 那里 `ref()` 返回 `None`。 `__del__` 拿到的 `self` 是**活的**, 于是能原样委托 (对**引用环**也成立: Arm 与 `_CartPending(arm=self)` 之间就是环, 靠 gc 收 —— 所以兜底的判据必须 - `gc.collect()`, 见 tests/test_teardown.py)。 + `gc.collect()` 才能验证兜底是否触发)。 ⚠ 异常必须**吞掉**: 这一刻 (GC 或解释器退出) 抛出去没人接, 会以 "Exception ignored in ..." 走 `sys.unraisablehook`; 解释器退出时更可能挂死。 @@ -1144,7 +1142,7 @@ def __del__(self) -> None: `self._zg_keepalive` (绑定方法) ⇒ 线程持有一个对 Arm 的强引用, 而运行中的线程 自己又被 `threading._active` 强引用 ⇒ Arm 根本不可回收。这是"保活线程"这个设计的 固有性质 (不是本兜底引入的): 保活期该走 `with arm.zero_g():` (退出时会停保活), - 而不是指望兜底。tests/test_teardown.py 有一条用例**钉住**这个限制。 + 而不是指望兜底。这是该设计的固有性质, 不是能靠兜底绕开的。 """ try: self.close() @@ -1177,8 +1175,8 @@ def _reject_if_in_dfu(self) -> None: arity/idx 预检排在 `_cmd()` **之前**, 而终态下 `self.n` 是 `0` (`close()` 清的) ⇒ 预检先炸, 报的是 "q 需 N 个" 这种**误导性**消息 (指针指向一个不存在的 arity bug)、且文档给的"捕获 `ArmIsInDfuError` 再新建 `Arm`"那个迁移姿势会**漏掉**它们。 - 故这三条各自在**最前**补一句本守卫 —— 判据在 `tests/test_dfu.py` 的入口清单里 - (那三条与其余入口**同表断言** `ArmIsInDfuError`)。 + 故这三条各自在**最前**补一句本守卫 —— 它们与其余入口一样, 终态下必须抛 + `ArmIsInDfuError`。 ⚠ 补这一句**不动非终态**: `_dfu_entered` 为假时它只是个布尔读; 那三条的 arity/idx 预检与"预检先于连接"的既有归因**逐字未动** (那是别处刻意定的, 见 `movej` 顶部那句注释的另一取向 —— 刻意**不**在本轮统一)。 @@ -1342,8 +1340,8 @@ def _done(a) -> bool: # (真固件的 `GET_STATUS` 没有失败路径,这一支只可能来自"那版固件里没有 # 这条命令"的 `default` 分支 —— 但契约必须成立)。 # ⚠ 只看**回显本命令码**的那条:别人的 ERR 落在**别的**队列里,不是我们的 - # 结论(这正是重构要买的东西 —— 从前"对任意 ERR 都抛"会把别人的拒绝记到 - # 自己头上,见 `tests/test_zero_g_cart_guard.py`)。 + # 结论(这正是这次重构要买的东西 —— 从前"对任意 ERR 都抛"会把别人的拒绝 + # 记到自己头上)。 return bool(a._queues.get(err_key)) or a.status_seq != seq0 self._pump_until(timeout, _done, "get_status_now") @@ -1384,8 +1382,7 @@ def _raw_write(self, cmd: int, payload: bytes = b"") -> None: self._reject_if_wrong_process() # fork 守卫: 唯一写口, 结构性地保证"子进程零下发" # ⚠ 同帧节流**必须**排在下面那道清队钩子**之前**: 钩子的理据是"固件**收到**这条 # 命令就会 `cart_invalidate_before_motion()`", 而帧压根没上 USB 时固件的状态一点 - # 没变 —— 此时清队会把一条**还有效**的在途请求作废掉 (见 - # `test_a_dropped_frame_does_not_clear_the_cart_queue`)。 + # 没变 —— 此时清队会把一条**还有效**的在途请求作废掉。 if not self._tx_allowed(cmd, payload): return if cmd in _CART_CLEARS_UPON: @@ -1406,8 +1403,7 @@ def _tx_allowed(self, cmd: int, payload: bytes) -> bool: * 该 `cmd` 在 `_tx_repeat_min_interval` 里有一个 >0 的间隔 (**表默认空 ⇒ 全关**); * 上一次**真发出去**的那一帧与本帧 `cmd` 相同、载荷**逐字节相同**, 且距今 < 间隔。 - ⚠ 载荷一变就照发 (伺服换目标必须能出去; 见 - `test_a_changed_payload_is_never_throttled`)。 + ⚠ 载荷一变就照发 (伺服换目标必须能出去)。 ⚠ 被丢的帧**不更新**时间戳 ⇒ 持续重发同一条帧是"每 `min_interval` 出去一帧", 不是"每帧都延期"。 ⚠ 丢帧**不静默**: `_tx_throttled_frames` +1。 @@ -1430,16 +1426,14 @@ def _tx_allowed(self, cmd: int, payload: bytes) -> bool: def _set_tx_repeat_min_interval(self, cmd: int, interval: float) -> None: """同帧节流旋钮: `cmd` 的最短重发间隔 (秒), `0` = 关闭该命令的节流。 - ⚠ 是**私有**的: `test_full_coverage.py::test_public_api_surface_is_all_exercised` - 要求每个公开成员都进它的名单 ⇒ 公开它就要改那条既有用例 (本轮的判据是"既有用例 - 一行不改")。要把它做成产品面, 那是另一步 —— §6.6 只要求这条约定**存在且默认关闭**。 + ⚠ 是**私有**的: 它只是调参旋钮, 不是公开 API。要把它做成产品面, 那是另一步 —— + §6.6 只要求这条约定**存在且默认关闭**。 - ⚠⚠ 打开之前必须知道**两条**后果 (两条都有用例钉住): + ⚠⚠ 打开之前必须知道**两条**后果 (均经实测确认): * **伺服/保活会断流**: `move_js`/`send_mit` 靠 ≥10Hz 重发维持固件 0.1s 命令看门狗 (`fail-soft` = 丢重力前馈), 保活 `0x06` 靠重发维持零重力 —— 重发被节流掉就是 - 断流 (`test_moving_paths_are_not_throttled_by_default` / - `test_enabling_the_throttle_on_the_keepalive_drops_it`); + 断流; * **被丢的请求不会有应答**: 一条被节流的请求, 它的调用方会**等到窗口耗尽**再报 "无应答" (命令其实**没发**) —— 这是与上游那个"请求被节流仍能从解析缓存取值"的 设计的**根本差别**。⚠ [2026-09-21] 论据换了一个, 结论没变: 从前写的是"本包 @@ -1937,7 +1931,7 @@ def _arrive(self, target: Sequence[float], `arrive_frames` 拍永远凑不齐 ⇒ **臂明明停在目标上 (偏差 0.0026 rad, 远在 `q_tol=0.03` 内) 却报 `未到位, 超时 15.0s`**。 同一段采样里**位置数据是干净的**, 所以改用它 —— 它直接回答"有没有动", - 与电机内部的速度估计无关。两次复现的位形见 `tests/` 与审计记录。 + 与电机内部的速度估计无关。两次复现的位形见审计记录。 ⚠ 需要**相邻两帧**才能判静止: 第一帧只登记 `prev`, 不参与判定 (故实际比 旧实现多用一帧, 约 10 ms)。 @@ -2189,7 +2183,8 @@ def load_tool(self, path: Optional[str] = None) -> bool: """从本地 json 恢复偏移 (**只改本进程**, 不动固件)。文件不存在返回 `False`。 ⚠ 文件里的负载值**不**自动下发: 那是会给臂上力的动作, 不该由"读文件"触发 —— - 要恢复负载请显式 `set_payload(...)` 后 `save_params()`。 + 要恢复负载请显式 `set_payload(...)`。若要持久化到 flash, 先读 + `save_params()` 的警告 (不可逆, 且须先失能)。 """ full = path or tool_mod.default_path() try: @@ -2512,7 +2507,24 @@ def set_gravity_vector(self, g) -> None: self.set_ff_scalar(6, k, float(v)) def save_params(self) -> None: - """持久化当前运行时参数到 Flash (固件异步, ~0.5-1s)。""" + """持久化当前运行时参数到 Flash (固件异步, ~0.5-1s)。 + + ⚠⚠ **不可逆的 Flash 写。** 它把当前 RAM 参数整组写进 flash, 并**覆盖**该臂此前 + 保存的记录 —— 包括逐台辨识的动力学模型 (整扇区擦除, 旧记录不可恢复)。没有 undo: + 参数写错只能重新辨识/标定, 或 `params.reset_factory()` 回到出厂 (那会丢掉该臂的 + 全部标定)。**只应在明确知道这台臂可以重新标定/固化的场合调用**; 标定过的整臂上 + 不要顺手保存。 + + ⚠ **须先失能** (`disable()`): 已使能或 `enable` 在途时固件回 `ERR{0x25,0x04}`。 + 本方法**不代劳 `disable()`** —— 失能瞬间位置环不再托住臂, 有负载/侧装时臂会因 + 自重下垂; 请先托住臂或走到低位再调用。 + + ⚠ 固件在擦写期间 CPU 会阻塞约 1s (看门狗为此放宽到 ~8s)。这 ~0.5-1s 内**不要 + 掉电/拔线/进 DFU**, 否则可能留下半写的参数区。调用返回只表示固件已受理; 真要确认 + 写进去了, 重新上电后回读参数, 不要只看 ACK。 + """ + # ⚠ 0x25 是整扇区擦写: 不可逆, 且固件要求失能。不要为了"省事"在本方法里 + # 自动 disable() —— 那会替调用方做一次可能让臂下垂的安全决策。 self._cmd(P.CMD_PARAM_SAVE, b"", "save_params", timeout=2.5) # ---------- DFU (SDK 里唯一的终端态操作) ---------- diff --git a/src/litearm/cart.py b/src/litearm/cart.py index 28c2d26..cdb9451 100644 --- a/src/litearm/cart.py +++ b/src/litearm/cart.py @@ -31,9 +31,8 @@ (`expect(echo_cmd=...)` 只能按码比), 而 `0x3A/0x3B/0x3E` **共用码空间** ⇒ 后受理那条 被门禁拒的 `ERR` 可能被**先受理那条**的 `expect` 读走, 而先受理者的 `ACK` 也被后受理者 读走 ⇒ **被拒那条报的不是它自己那条 `ERR`**, 而是耗满窗口的 `MotionTimeoutError` / - `CartReplyLostError` (报告与物理事实相反; 实测见 - `test_cart_protocol.py::test_two_concurrent_requests_cannot_cross_deliver`, 那条用例 - 现在**靠"逐线程归因"那一条判据咬住** —— 前两条在 `err_waits_for_ack` 之后已不再区分)。 + `CartReplyLostError` (报告与物理事实相反; 实测确认过, 逐线程归因是唯一还能咬住它的 + 判据 —— 前两条在 `err_waits_for_ack` 之后已不再区分)。 ⚠ 这一支的**旧**形态 ("先受理者摘掉自己的 token ⇒ 后受理者拿到它那条 `0x4E` 而报成功") 被 `err_waits_for_ack` 消掉了, 别再照旧文档复述。 @@ -84,9 +83,7 @@ #: #: ⚠ `0x3A/0x3B/0x3E` **不在**此列 —— 它们欠应答, 而且**欠两条**: 被取代的那条在 #: PLANNING 期由 `cart_begin_request` 补一条 CANCELED, 新受理那条随后还有自己的结果。 -#: 清队会让报告与物理事实**相反**, 且**两个方向都反** (机制由 -#: `tests/test_cart_queue.py::test_the_clear_set_must_not_swallow_the_two_known_replies` -#: 实地摆出来): +#: 清队会让报告与物理事实**相反**, 且**两个方向都反** (下面①②是当时实地验证过的机制): #: #: ① **被摘掉的不止在飞那条**: `_request_and_wait` 是**先登记、后写**, 而清队钩子挂在 #: 写口 (`_raw_write`) 上 ⇒ 新受理那条的 token 刚登记、还没写出去就被**一起摘掉** @@ -147,7 +144,7 @@ #: **为什么必须有下限**: 额度是"清队/放弃那一刻, 那条请求**可能**还欠一条应答"的通行证。 #: 额度**过期**而那条应答**还在路上**时, 它一到就撞上 `on_reply`: 队列若**非空** (清队后 #: 又登记了新请求), 它被**配给那条新 token** ⇒ 调用方拿到**别人那条**的规划结果并**报 -#: 成功** (E3 实测, 见 `test_a_reply_that_outlives_move_timeout_is_not_paired_to_the_next_request`); +#: 成功** (E3 实测确认过); #: 队列若空, 报的是 `LiteArmError` "固件与主机已错配" (**归因误导** —— 真相只是"我们自己 #: 放弃了一条请求, 而额度先过期了")。故额度的存活时间必须覆盖 #: "**固件还可能发出那条应答**"的最长时间。 @@ -193,8 +190,7 @@ #: · **取大** ⇒ "真·脱同步"的那条应答被静默吸收掉, 硬错误被降级成**静默** (只是窗口 #: 被拉长, 见 `_CartPending.__init__` 里那段"额度有效期偏长的后果"); #: · **取小 / 过期** ⇒ 一条**还在路上**的应答撞上"队列**非空**"而被配给**新登记**的 -#: token ⇒ 调用方拿到**别人那条**的规划结果并**报成功** = **假成功** (E3 实测, 见 -#: `test_a_reply_that_outlives_move_timeout_is_not_paired_to_the_next_request`); +#: token ⇒ 调用方拿到**别人那条**的规划结果并**报成功** = **假成功** (E3 实测确认过); #: 撞上"队列空"则报 `LiteArmError` (归因误导)。这半写在上面"为什么必须有下限"那段。 #: ⇒ 两害相权**必须偏向取大**: "静默"是少报一次错, "假成功"是报了个**错的结果**。 #: (G1 实测的另一半仍成立: 额度本身不会把"被拒"变成"成功"。) @@ -323,8 +319,8 @@ def __init__(self, *, absorb_ttl: float, absorb: int = 0, #: ⚠ 只搬**条数**: 旧对象里那几条的调用方由 `clear_pending` 唤醒, 不在这里管。 #: ⚠⚠ 继承来的额度**至多影响新会话的一条命令, 且不被超时路径续期**: 它若先于配对 #: 吃掉新会话**自己那条**应答 (两只在原理上无法区分), 那条命令报"结局未知", 而 - #: 它的超时路径**不再补额度** ⇒ 下一条起恢复正常 (见 `drop_and_absorb` 的例外段与 - #: `test_an_inherited_credit_cannot_perpetuate_itself_across_a_reconnect`)。 + #: 它的超时路径**不再补额度** ⇒ 下一条起恢复正常 (见 `drop_and_absorb` 的例外段; + #: 该"额度不跨重连续期"的性质经实测确认)。 self._absorb = absorb #: 额度截止 (monotonic 秒); `_absorb == 0` 时无意义。 #: 带进来的额度**从建对象这一刻起算** `absorb_ttl` (与 `clear_pending`/ @@ -454,7 +450,7 @@ def drop_and_absorb(self, token: _CartToken, *, timed_out: bool) -> None: 配给**下一条** token ⇒ 调用方拿到**别人那条**的规划结果并**报成功**; 撞上队列空则 炸 `LiteArmError` (归因仍是错的)。`0x4E` 载荷里没有命令 id, 它无从分辨。 ⚠ pump 支走例外时正是这一侧: 被吸收的可能是**清队前遗留的**那条, 而本 token 自己 - 那条还在路上 —— `test_a_pump_failure_must_not_suppress_the_credit` 钉的就是它。 + 那条还在路上 —— 这正是本条例外要覆盖的情形。 (超时支若同样判错, 代价也是假成功; 但那一支至少还有"窗口够长"可依, 且**没有它 自持就回不来** —— 实测 `#1..#6` 全红, 那是本例外唯一的立论。) @@ -703,9 +699,9 @@ def pending(self) -> int: #: move_c 的起点校验容差 —— 与 `Arm.move_p` 的默认值同源 (6mm / 0.03rad), 不是**抄**来的 #: 巧合: `move_c` 校验的就是"实际 TCP 是否在 `pose_start` 附近", 判据必须与 `move_p` 的 #: 到位判据一致 (同一把尺子), 否则 move_p 收工的位置会被 move_c 判成"起点不一致"。 -#: ⚠ 同源关系由 `test_cart_protocol.py::test_cart_start_tolerances_track_move_p_defaults` -#: 钉住 —— 只靠这两个数字与 `Arm.move_p` 的默认值**字形相同**是守不住的: 改了 move_p 默认 -#: 而忘了这里, `move_c` 的起点判据会**静默不跟随**。 +#: ⚠ 这两个数必须与 `Arm.move_p` 的默认到位容差**同源** —— 只靠字形相同是守不住的: +#: 改了 move_p 默认而忘了这里, `move_c` 的起点判据会**静默不跟随** (仓库已无测试套件, +#: 改任一处时请人工同步另一处)。 CART_START_POS_TOL = 0.006 CART_START_RPY_TOL = 0.03 @@ -882,8 +878,8 @@ def probe(arm) -> bool: except MotionTimeoutError: continue # 安静 = 这一帧丢了, 再试一次 # 判据就是能力判定那一条: **0x00 恒等于固件的 `default` 分支** (未实现该命令), - # 其余任何非 0 的错误码都说明这条命令在固件里存在 (`test_capability.py` 与 - # `test_protocol_sync.py::test_err_code_zero_only_comes_from_default_branch` 守它)。 + # 其余任何非 0 的错误码都说明这条命令在固件里存在 (这一点靠人工对照 + # `usb_cmd.c` 的 `default` 分支确认)。 return (payload[1] if len(payload) > 1 else 0) != 0x00 arm._cart_probe_silent = True # 3 次均无应答 —— 探测未获确认 (不是"确报不支持") return False @@ -896,9 +892,8 @@ def probe(arm) -> bool: def _require_cart_support(arm) -> None: """② 能力检查 —— 排在 `_require()` 之后、零重力守卫之前。 - ⚠ 缓存在 `Arm._cart_supported` (私有名)。写成公开的 `arm.cart_supported` 或加一层 - `arm.cart` 门面会让 `tests/test_full_coverage.py::test_public_api_surface_is_all_exercised` - 变红 —— 它会要求每个公开成员都被练习过。 + ⚠ 缓存在 `Arm._cart_supported` (私有名)。不要写成公开的 `arm.cart_supported` 或加一层 + `arm.cart` 门面 —— 那会扩大公开 API 面, 而本仓约定新公开成员必须有入口/文档/覆盖。 ⚠ 报错**分两支措辞** —— 探测那一步把两种"不支持"分开了 (`arm._cart_probe_silent`), 在这里混成一句话会让现场无法归因: 一支该换固件, 另一支该查链路。 @@ -1003,8 +998,7 @@ def _tcp_reached(arm, goal) -> bool: —— 两根方向相反的判断, 别抄成一条 (见 §5.3)。 容差复用 `CART_START_POS_TOL`/`CART_START_RPY_TOL`: 与 `Arm.move_p` 的到位判据、 - `move_c` 的起点校验是**同一把尺子** (这三处的同源关系由 - `test_cart_protocol.py::test_cart_start_tolerances_track_move_p_defaults` 钉住)。 + `move_c` 的起点校验是**同一把尺子** (改任一处的默认值时请人工同步另外两处)。 ⚠ **取不到就报"没到位"** (超时 / 断连 / 被别的 `ERR` 串台): 保守方向, 与"宁可报未知" 同向。故障不归这里管 —— 它由到位等待里的 `st.faulted` 立刻抛 `MotorFaultError`。 @@ -1241,7 +1235,7 @@ def _request_and_wait(arm, cmd: int, payload: bytes, label: str, goal, 缓冲再调它, 那条 ACK **被它吃掉** —— 而它的主人随后报"无应答", 与 F4 修的同类)。 它**已经**改成与笛卡尔入口互斥 (非阻塞 `acquire(blocking=False)`, 拿不到就返回 `None`), 所以抢不走**入口**的帧; 但清单里其余那些读者都不持那把锁 ⇒ `poll_cart` 仍可能把 - **它们**的帧吃掉。这一条是**实现里检查过的**: `test_poll_cart_does_not_steal_a_frame_from_a_running_entry`。 + **它们**的帧吃掉。这一条是**实现里检查过的** (当时有专门的抢帧用例; 仓库已无测试套件)。 ⚠ 故**别**把这里读成"串行是强制的"这种无条件说法: 强制只覆盖"**入口与入口**之间"。 ⚠ 段三又添了一个抢帧者: `Arm.enter_dfu()` 的**消失观察窗口** (`Arm._wait_until_link_lost`, 在 ACK 之后读满 0.3s 等设备离开) —— 它同样不持本锁, diff --git a/src/litearm/errors.py b/src/litearm/errors.py index 905dfe2..b3a0793 100644 --- a/src/litearm/errors.py +++ b/src/litearm/errors.py @@ -178,8 +178,8 @@ class ArmIsInDfuError(LiteArmError): #: 具体档: `(cmd, code) -> 语义`。**逐条取自固件原注释, 不自行起名。** #: ⚠ `code == 0x00` 一律不在此表 —— 它**恒**等于"固件没有这条命令"(唯一真源是 -#: `usb_cmd.c` 的 `default` 分支, 由 `tests/test_protocol_sync.py` 的 -#: `test_err_code_zero_only_comes_from_default_branch` 钉住), 由通用档承担。 +#: `usb_cmd.c` 的 `default` 分支; 仓库已无测试套件, 改固件时需人工核对这一点), +#: 由通用档承担。 ERR_TEXT = { # ---- 0x01 MOVE_J(每轴一条独立 S 曲线; 0x07 是同步版, 同码同语义)---- (0x01, 0x01): "载荷长度不足 (需 4×N+4 字节)", @@ -372,8 +372,7 @@ class ArmIsInDfuError(LiteArmError): # item 7 的 `v ∉ {0,1,2}` (`:199`) / 其余 item 落 `default` (`:219-220`) # ⚠ "幅值静默钳制"那句的**射程**只覆盖"**有 clamp 的** item" —— item 7 与 item 5/6 # 的 `sub` 是**值域拒绝** (在**任何** `ff_clamp()` 之前就 `return false`), 不是 - # 幅值越界。判据 (地面真值现解 `params.c`): - # `test_error_codes.py::test_0x28_02_text_scopes_the_clamp_claim_to_items_that_actually_clamp` + # 幅值越界。判据 (地面真值现解 `params.c`; 下表的措辞与之一致): (0x28, 0x02): "item 越界 (合法区间是 1..8 与 10..18; **item 9 已保留**给 0x2C 读 " "ff_mask, 写它走 `default` 同样回本码), 或值非法 —— 只有三类: **NaN**、" "item 5/6 的 `sub>2`、item 7 的 `v∉{0,1,2}`。" diff --git a/src/litearm/params.py b/src/litearm/params.py index 460a2d2..6eeea06 100644 --- a/src/litearm/params.py +++ b/src/litearm/params.py @@ -3,7 +3,8 @@ 与 FF/动力学调参族 (留在 `Arm` 上) 的分工: 那一族是**前馈/控制律**参数 (0x26/0x27/0x28/0x31 + 读回 0x2B/0x2C); 本模块是**关节级** MIT 刚度/阻尼/力矩钳幅与 -软限位。两者都是 RAM 生效, 持久化统一走 `Arm.save_params()` (0x25)。 +软限位。两者都是 RAM 生效, 持久化统一走 `Arm.save_params()` (0x25) —— +⚠ 那是**不可逆的 flash 写**且须先失能, 调用前先读 `Arm.save_params()` 的警告。 固件侧载荷与错误码见 `litearm-stm32/User/litearm/hal/usb_cmd.c` 的 `CMD_SET_JOINT_PARAM`/`CMD_SET_JOINT_LIMITS`/`CMD_GET_JOINT_PARAM`/`CMD_PARAM_RESET` 分支。 diff --git a/src/litearm/payload.py b/src/litearm/payload.py index cf2b988..51fda5d 100644 --- a/src/litearm/payload.py +++ b/src/litearm/payload.py @@ -600,7 +600,7 @@ def identify(arm: "Arm", baseline: Baseline, *, speed: float = 0.3, raise InvalidCommandError( f"baseline 需 Baseline (读 JSON 用 Baseline.load), 收到 {type(baseline).__name__}") # ⚠ 取状态**排在**轴数/速度校验之前: 链路没开时第一因是断开, 不该被入参形状抢先 - # (与 `cart.py` 三个入口的同一条顺序理由, 判据见 test_public_api 的离线用例)。 + # (与 `cart.py` 三个入口的同一条顺序理由)。 st = arm.get_state().value if st is None: raise TransportError("辨识开始前取不到状态帧") @@ -697,7 +697,10 @@ def identify(arm: "Arm", baseline: Baseline, *, speed: float = 0.3, def apply(arm: "Arm", result: PayloadResult, *, com: bool = True) -> None: - """把辨识结果写进固件(`set_payload`,RAM 生效;要持久化再 `save_params()`)。 + """把辨识结果写进固件(`set_payload`,RAM 生效)。 + + ⚠ 要持久化再 `save_params()` —— 那是**不可逆的 flash 写**, 且须先 `disable()`; + 先读一遍 `Arm.save_params()` 的警告, 再决定要不要在这台臂上做。 `com=False` 只写质量(质心按 0 处理)—— 这在质心解不可信、但有外部先验时有用。 值越界在这里就拒:固件对 `payload_mass` / `payload_com` 是**静默钳制**的 diff --git a/src/litearm/state.py b/src/litearm/state.py index 6efcc95..3e004da 100644 --- a/src/litearm/state.py +++ b/src/litearm/state.py @@ -46,14 +46,13 @@ def cart_busy(self) -> bool: names = [FLAG_NAMES[k] for k in range(6) if flags & (1 << k)] —— `flag_names` 只会去看 bit0..bit5, 于是"往 `FLAG_NAMES` 加 `10: "CART_BUSY"` - 什么都不会发生" (加了也读不到)。**这不是"会被打印成故障位"** (实测: 加了照样全绿 - —— 当时套件 **374** 条, 那是**当时的规模**、不是现值, 别拿它核现在的全量输出), + 什么都不会发生" (加了也读不到)。**这不是"会被打印成故障位"** (实测: 加了当时 + 全套用例照样全绿; 那些用例现已移除, 别依赖"测试会红"来防这件事), 别照着那句假后果去推理: `fault_detail()` 只拼 `flag_names` 这个**列表**, 而列表本身由 `range(6)` 决定。 ⚠ 但"现在无事发生"= 一条防线写在**别人的隐式常量**里 —— 一旦有人把 `range(6)` 改成 `range(11)` (或改成遍历整张表), bit6..bit10 (mode 三位 + enabled + cart_busy) - 会**一起**变成"故障位"。`test_cart_protocol.py::test_cart_busy_must_not_enter_flag_names` - 就是为这条可能的改动守的。 + 会**一起**变成"故障位"。改 `range(6)` 或 `FLAG_NAMES` 前先检查这一点。 """ return bool(self.flags & (1 << 10)) diff --git a/src/litearm/testing.py b/src/litearm/testing.py index 6fc22f4..e072b02 100644 --- a/src/litearm/testing.py +++ b/src/litearm/testing.py @@ -1,7 +1,7 @@ """脚本化应答的假传输 —— 让 Arm 全流程可离线测试 (镜像 pylitearm 桩硬件风格)。 按收到的下行命令推送预设帧 (ACK/状态/RSP_TCP/RSP_IK), 维持 Arm 接口 -(write_frame/read_frame/close/is_open), 供 pytest monkeypatch SerialTransport 用。 +(write_frame/read_frame/close/is_open), 供离线测试 monkeypatch SerialTransport 用。 """ from __future__ import annotations @@ -183,7 +183,7 @@ def _ack(cmd: int) -> bytes: # ⚠ LINK 行的键**按固件 `kin_runner.c:513-560` 的实际发射顺序与命名**抄全 —— # 桩比真机短是这一类缺陷反复漏网的原因 (`rxl0`/`rxl1`/`rbd`/`cmode`… 从前就没有, # 于是"解析器漏掉它们"在离线永远测不出来)。 - # ⚠ `rxl0`/`rxl1` **名字里带数字** —— 解析器必须吃得下 (见 `test_..._digit_keys`)。 + # ⚠ `rxl0`/`rxl1` **名字里带数字** —— 解析器必须吃得下。 "LINK crc=3 ovf=11 rfd=1 txf=7 rxlen=5 rxl0=13 rxl1=17 rbd=19 " "cmode=127 cmb=23 tfe=1 tfd=2 tfc=3 tfs=0 tfm=1 tec=29 rec=31 psr=8 " "ebo=0 eep=0 eew=0 epa=0 epd=0 " @@ -286,10 +286,10 @@ def __init__(self, port: str = "fake", timeout: float = 0.2, self.model_dirty = False #: 关节级参数表 (0x22/0x23 写, 0x24 读, 0x36 回出厂默认) self.enabled = False - # ---- [授权] 见 `_protocol` 的 license 段; 判据在 tests/test_license.py ---- - #: 是否已激活。**默认 True** —— 否则每一条既有用例的 `enable()` 都会撞 - #: `ERR{0x10,0x08}`(固件 `ctrl_enable()` 的第一条判据), 而那些用例与授权无关。 - #: 授权用例把它置 False 来复现"开机即锁"。 + # ---- [授权] 见 `_protocol` 的 license 段 ---- + #: 是否已激活。**默认 True** —— 否则离线桩上的 `enable()` 会撞 + #: `ERR{0x10,0x08}`(固件 `ctrl_enable()` 的第一条判据), 而多数离线调试 + #: 与授权无关。把它置 False 可复现"开机即锁"。 self.activated = True #: 激活记录 —— `0x2F` 回报的就是这几格 (未激活时后三格按固件约定**恒 0**)。 self.license_ver = 1 @@ -389,8 +389,7 @@ def armed(self) -> bool: **没有位** (SDK 只看得到 `self.enabled` / bit9) ⇒ 桩里由 `dfu_armed_pending` 造那个形状。**五处门禁 (0x25/0x36/0x32/0x37/0x23) 与 0x15 共用这一个判据** —— 逐条对得上固件这六处 `usb_cmd.c` 的用法 (`:670` / `:684` / `:877` / `:923` - / `:633` / `:543-555`)。判据只有这一份, 别在任何一处退回 `self.enabled` - (`test_full_coverage.py::test_all_gates_share_the_one_armed_predicate` 逐处钉住)。 + / `:633` / `:543-555`)。判据只有这一份, 别在任何一处退回 `self.enabled`。 """ return self.enabled or self.dfu_armed_pending @@ -425,11 +424,9 @@ def _axis_outside(self, idx: int, qmin: float, qmax: float) -> bool: 落到 `else: _ack`)。 ⚠ 于是上面五种情况里代理**失真** (固件 `q_ref` 已到新目标, 桩 `self.q` 还在旧值)。 - 这属**潜伏**, 目前无任何用例能踩到: `0x07` 是最像的同族, 而 `Arm.movej_sync` 到 - 不了位就抛 `MotionTimeoutError` (异目标实测), 控制回不到用例体; 唯一调用它的 - 用例 (`test_full_coverage.py:36`) 给的目标与当前 `q` 相同, 于是立刻判到位、代理 - 仍然准确。其余四条之后现有用例发的 `0x23` 要么根本不在武装态 (门禁整条跳过), - 要么区间容得下旧值 (`test_full_coverage.py:54` 的 `±3.0`)。 + 这属**潜伏**: `0x07` 是最像的同族, 而 `Arm.movej_sync` 到不了位就抛 + `MotionTimeoutError` (异目标实测), 控制回不到调用方。若以后在桩上测 `0x23`, + 注意这一代理关系在运动命令之后可能失真。 """ if not 0 <= idx < self.n: return True # ① (固件收 uint8_t, 只有上界那一半会命中) @@ -533,8 +530,7 @@ def write_frame(self, cmd: int, payload: bytes = b"") -> None: if len(payload) < 28: self._push(P.pack_frame(P.RSP_ERR, bytes([cmd, 0x01]))) elif self.armed: - # ⚠ 用统一的 `armed` 判据 (固件 `ctrl_is_armed()`), 不是裸 `self.enabled` - # —— 由 `test_full_coverage.py::test_all_gates_share_the_one_armed_predicate` 钉住。 + # ⚠ 用统一的 `armed` 判据 (固件 `ctrl_is_armed()`), 不是裸 `self.enabled`。 self._push(P.pack_frame(P.RSP_ERR, bytes([cmd, 0x04]))) elif self.license_fail_next or self.activated: # 0x02 是**聚合档** —— "已经激活过"与"MAC 不符/写失败"混在一起。 diff --git a/src/litearm/transport.py b/src/litearm/transport.py index 95cda24..46ad140 100644 --- a/src/litearm/transport.py +++ b/src/litearm/transport.py @@ -122,11 +122,9 @@ def _release_port(port: str, owner: object) -> None: ⚠ `is owner` 这个判据今天是**防御性**的, 到不了"该登记已经属于别人"那一步: 登记只在 持有者**死后**才被别人替换, 而死者不会再来撤登记 (活着的持有者撤完自己那条之后, - `close()` 的幂等早退也排在前面)。变异实测: 把它改成无条件 `del`, 全套 **483** 条 - **照样全绿** ⇒ 别把它当成在挡某个今天跑得出来的场景。⚠ "483" 是**当时的规模**、 - 不是现值 (现值看 `pytest --collect-only`), 别拿它核现在的全量输出 —— 与 - `state.py:50` 的 "374" 同一种标注口径。留着是因为**本函数的契约应当是自明 - 的** ("只撤自己的"), 而不是靠上面那句推理**永远**成立。 + `close()` 的幂等早退也排在前面)。当时把它改成无条件 `del`, 全套用例**照样全绿** + ⇒ 别把它当成在挡某个今天跑得出来的场景。这里没有回归测试来守它 —— 留着是因为 + **本函数的契约应当是自明的** ("只撤自己的"), 而不是靠上面那句推理**永远**成立。 """ with _PORT_OWNERS_LOCK: cur = _PORT_OWNERS.get(port) From ffdd8ebdf2be5d3b93affd0f572430e9f16ff8dc Mon Sep 17 00:00:00 2001 From: thetooler Date: Mon, 2 Nov 2026 12:24:32 +0800 Subject: [PATCH 3/4] test: remove tests added after the branch point #33 and #43 landed on main after this branch was opened: they added tests/test_env_sh.py and tests/test_transport_tcp.py, and two new references to tests/conftest.py. Delete the remaining tests so the repository really has no suite, and point the two comments at litearm.testing.FakeTransport instead. Co-Authored-By: Claude Code --- src/litearm/arm.py | 2 +- src/litearm/transport.py | 2 +- tests/test_env_sh.py | 55 --------- tests/test_transport_tcp.py | 217 ------------------------------------ 4 files changed, 2 insertions(+), 274 deletions(-) delete mode 100644 tests/test_env_sh.py delete mode 100644 tests/test_transport_tcp.py diff --git a/src/litearm/arm.py b/src/litearm/arm.py index 40d3b2b..d90348e 100644 --- a/src/litearm/arm.py +++ b/src/litearm/arm.py @@ -934,7 +934,7 @@ def connect(self, port: Optional[str] = None) -> "Arm": elif is_tcp_target(p): # 远端/仿真: 帧与串口完全相同, 只是载体是 socket (见 transport_tcp)。 # ⚠ 刻意**不**把串口分支也塞进一个总工厂: 那会挡掉 - # `tests/conftest.py` 替换 `SerialTransport` 的注入点。 + # 替换 `SerialTransport` 的注入点 (`litearm.testing.FakeTransport`)。 from litearm.transport_tcp import TcpTransport self._tr = TcpTransport(p) else: diff --git a/src/litearm/transport.py b/src/litearm/transport.py index 46ad140..ba5fbb5 100644 --- a/src/litearm/transport.py +++ b/src/litearm/transport.py @@ -377,7 +377,7 @@ def is_tcp_target(port: object) -> bool: 为什么本模块需要知道这件事、而不是干脆提供一个 `make_transport()` 总工厂: `Arm.connect()` 的串口分支必须**仍然直接引用 `SerialTransport` 这个名字** —— 离线测试与 `litearm-server --dry-run` 都靠替换那个属性来注入假传输 - (`tests/conftest.py` 的 `fake_transport_factory`)。总工厂会把那个注入点挡掉。 + (`litearm.testing.FakeTransport`)。总工厂会把那个注入点挡掉。 所以分流的形状是"TCP 例外走新路, 其余原路不动", 而不是"所有传输过一道工厂"。 """ from litearm.transport_tcp import is_tcp_url diff --git a/tests/test_env_sh.py b/tests/test_env_sh.py deleted file mode 100644 index 4cdd73b..0000000 --- a/tests/test_env_sh.py +++ /dev/null @@ -1,55 +0,0 @@ -"""env.sh 的严格模式只能作用于自己 —— `source env.sh` 不能改变调用者的 shell。 - -`source` 在调用者的 shell 里执行,所以文件里一句 `set -e` 会留在调用者的交互 -shell 里:之后任何一条命令返回非零,终端就直接退出。这几条用例在子 shell 里 -source 一次,确认调用者的选项没被改动、失败命令不再中断 shell。 -""" -from __future__ import annotations - -import os -import subprocess -from pathlib import Path - -REPO = Path(__file__).resolve().parents[1] -ENV_SH = REPO / "env.sh" - - -def _bash(script: str, **kwargs) -> subprocess.CompletedProcess: - return subprocess.run( - ["bash", "--norc", "--noprofile", "-c", script], - capture_output=True, - text=True, - timeout=30, - **kwargs, - ) - - -def test_sourcing_env_sh_leaves_errexit_off(): - """source 之后 `false` 不能把 shell 干掉。""" - proc = _bash(f'source "{ENV_SH}" >/dev/null 2>&1; false; echo survived') - assert proc.returncode == 0, proc.stderr - assert "survived" in proc.stdout - - -def test_sourcing_env_sh_keeps_caller_shell_options(): - """source 前后 `set +o` 的输出必须逐字相同。""" - proc = _bash( - f'before=$(set +o); source "{ENV_SH}" >/dev/null 2>&1; after=$(set +o); ' - '[ "$before" = "$after" ] && echo unchanged' - ) - assert proc.returncode == 0, proc.stderr - assert "unchanged" in proc.stdout - - -def test_executing_env_sh_enables_strict_mode_cleanly(): - """直接执行时仍然开严格模式,并且在最小环境里也不因未定义变量而失败。""" - env = {"PATH": os.environ["PATH"], "HOME": os.environ.get("HOME", "")} - proc = subprocess.run( - ["bash", str(ENV_SH)], - capture_output=True, - text=True, - timeout=30, - env=env, - ) - assert proc.returncode == 0, proc.stderr - assert f"repo={REPO}" in proc.stdout diff --git a/tests/test_transport_tcp.py b/tests/test_transport_tcp.py deleted file mode 100644 index 7be581f..0000000 --- a/tests/test_transport_tcp.py +++ /dev/null @@ -1,217 +0,0 @@ -"""TCP 传输 —— 契约与串口逐条对齐 (见 `litearm/transport_tcp.py` 模块 docstring)。 - -这些用例**不依赖**任何仿真后端: 一个本地 socket 假装成固件, 只验传输层本身。 -""" -from __future__ import annotations - -import contextlib -import socket -import threading -import time - -import pytest - -from litearm import _protocol as P -from litearm import transport as tr_mod -from litearm.errors import TransportError -from litearm.transport import is_tcp_target -from litearm.transport_tcp import TcpTransport, is_tcp_url, parse_tcp_url - - -@contextlib.contextmanager -def fake_firmware(): - """起一个只监听 127.0.0.1 的"固件", 返回 (url, 服务端 socket)。""" - srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM) - srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) - srv.bind(("127.0.0.1", 0)) - srv.listen(1) - port = srv.getsockname()[1] - accepted = {} - - def _accept(): - conn, _ = srv.accept() - accepted["conn"] = conn - - th = threading.Thread(target=_accept, daemon=True) - th.start() - try: - yield f"tcp://127.0.0.1:{port}", accepted - finally: - th.join(timeout=2.0) - for s in (accepted.get("conn"), srv): - if s is not None: - try: - s.close() - except OSError: - pass - - -def _conn(box, timeout=2.0): - """等服务端 accept 落地, 返回那条连接 (构造 TcpTransport 是异步完成的)。""" - end = time.time() + timeout - while "conn" not in box and time.time() < end: - time.sleep(0.005) - assert "conn" in box, "服务端没接受连接" - return box["conn"] - - -# --------------------------------------------------------------------------- # -# 端口字符串的判定 -# --------------------------------------------------------------------------- # -@pytest.mark.parametrize("port", ["tcp://127.0.0.1:5601", "sim://localhost:9000", - "127.0.0.1:5601", "host:1"]) -def test_tcp_urls_are_recognized(port): - assert is_tcp_url(port) is True - - -@pytest.mark.parametrize("port", ["/dev/ttyACM0", "COM3", "fake", "", None, 42, - "C:\\Users\\x", "host:abc", "host:70000", ":5601"]) -def test_non_tcp_ports_are_not_misdetected(port): - assert is_tcp_url(port) is False, f"{port!r} 不应被判成 TCP" - - -def test_parse_rejects_bad_urls(): - for bad in ("tcp://noport", "tcp://:123", "tcp://h:notanumber", "tcp://h:99999"): - with pytest.raises(ValueError): - parse_tcp_url(bad) - - -def test_parse_accepts_scheme_less_form(): - assert parse_tcp_url("127.0.0.1:5601") == ("127.0.0.1", 5601) - assert parse_tcp_url("sim://localhost:7") == ("localhost", 7) - - -# --------------------------------------------------------------------------- # -# 收发契约 -# --------------------------------------------------------------------------- # -def test_roundtrip_write_then_read(): - with fake_firmware() as (url, accepted): - tr = TcpTransport(url, timeout=0.5) - try: - tr.write_frame(P.CMD_GET_STATUS) - _conn(accepted).settimeout(2.0) - data = _conn(accepted).recv(64) - assert P.unpack_frame(data) == (P.CMD_GET_STATUS, b"") - _conn(accepted).sendall(P.pack_frame(P.RSP_FIRMWARE, b"Litearm1.10.0-7J")) - got = tr.read_frame(timeout=2.0) - assert got == (P.RSP_FIRMWARE, b"Litearm1.10.0-7J") - finally: - tr.close() - - -def test_port_is_kept_verbatim_for_connect_idempotency(): - """`Arm.connect()` 的幂等判据读的是 `transport.port`, 必须是原样的 URL。""" - with fake_firmware() as (url, accepted): - tr = TcpTransport(url) - try: - assert tr.port == url - assert isinstance(tr.port, str) - finally: - tr.close() - - -def test_half_frame_survives_a_timeout(): - """半帧超时**不丢**: 下一次读要能接着把它装配出来 (串口的同名契约)。""" - with fake_firmware() as (url, accepted): - tr = TcpTransport(url, timeout=0.05) - try: - frame = P.pack_frame(P.RSP_TCP, P.pack_f32s([0.1, 0.2, 0.3, 0.0, 0.0, 0.0])) - conn = _conn(accepted) - conn.sendall(frame[:6]) - assert tr.read_frame(timeout=0.15) is None, "半帧不该装配成功" - conn.sendall(frame[6:]) - got = tr.read_frame(timeout=1.0) - assert got is not None and got[0] == P.RSP_TCP - finally: - tr.close() - - -def test_timeout_zero_returns_what_already_arrived(): - """`timeout=0` 是"有就给我" —— `Arm.poll_cart()` 靠它。""" - with fake_firmware() as (url, accepted): - tr = TcpTransport(url, timeout=0.2) - try: - _conn(accepted).sendall(P.pack_frame(P.RSP_ACK, bytes([P.CMD_ENABLE]))) - time.sleep(0.05) # 让字节真的到达内核缓冲 - got = tr.read_frame(0) - assert got == (P.RSP_ACK, bytes([P.CMD_ENABLE])) - finally: - tr.close() - - -def test_noise_bytes_go_to_text_log(): - with fake_firmware() as (url, accepted): - tr = TcpTransport(url, timeout=0.2) - try: - _conn(accepted).sendall(b"[litearm-usbcdc] ready (normal)") - assert tr.read_frame(timeout=0.2) is None - assert "ready" in tr.text_log - finally: - tr.close() - - -def test_peer_close_raises_instead_of_silently_timing_out(): - """对端关闭必须**报链路断**: 静默超时会把归因指向"固件不理我"。""" - with fake_firmware() as (url, accepted): - tr = TcpTransport(url, timeout=0.5) - try: - _conn(accepted).close() - with pytest.raises(TransportError): - for _ in range(50): - tr.read_frame(timeout=0.05) - finally: - tr.close() - - -def test_write_after_close_raises_transport_error(): - with fake_firmware() as (url, accepted): - tr = TcpTransport(url) - tr.close() - with pytest.raises(TransportError): - tr.write_frame(P.CMD_GET_STATUS) - assert tr.is_open is False - tr.close() # 幂等 - - -def test_connect_failure_is_a_transport_error(): - """端口没人监听时, 必须是本包的 TransportError (调用方按它做分支)。""" - with pytest.raises(TransportError): - TcpTransport("tcp://127.0.0.1:1", connect_timeout=0.5) - - -# --------------------------------------------------------------------------- # -# 分发 (Arm.connect 的分支) -# --------------------------------------------------------------------------- # -def test_is_tcp_target_delegates_to_the_same_rules(): - assert is_tcp_target("tcp://127.0.0.1:5601") is True - assert is_tcp_target("127.0.0.1:5601") is True - assert is_tcp_target("/dev/ttyACM0") is False - assert is_tcp_target("fake") is False - - -def test_arm_keeps_using_serial_transport_for_non_tcp_ports(monkeypatch): - """串口分支必须**仍然直接引用 `arm.SerialTransport`** —— 那是离线测试与 - `litearm-server --dry-run` 的注入点 (tests/conftest.py 靠替换它注桩)。 - """ - from litearm import arm as arm_mod - from litearm.testing import FakeTransport - - made = [] - - def factory(port): - made.append(port) - return FakeTransport() - - monkeypatch.setattr(arm_mod, "SerialTransport", factory) - arm_mod.Arm(port="fake").connect().close() - assert made == ["fake"], "非 TCP 端口没有走 SerialTransport 注入点" - - -def test_arm_routes_a_tcp_url_to_the_tcp_transport(monkeypatch): - from litearm import arm as arm_mod - - monkeypatch.setattr(arm_mod, "SerialTransport", - lambda *a, **k: pytest.fail("TCP 目标不该去开串口")) - with pytest.raises(TransportError): - # 端口没人监听 -> 传输层报 TransportError, 但**不是**串口路径 - arm_mod.Arm(port="tcp://127.0.0.1:1").connect() From c6e0af7a79402e94fb422142452c08f912fbb06d Mon Sep 17 00:00:00 2001 From: thetooler Date: Mon, 2 Nov 2026 14:37:58 +0800 Subject: [PATCH 4/4] chore: drop the unused pytest dev extra The repository no longer has a test suite, so `.[dev]` only pulled in pytest for nothing. Remove the optional-dependencies block. Co-Authored-By: Claude Code --- pyproject.toml | 3 --- 1 file changed, 3 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 46721e0..5d63d4d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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"