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..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" @@ -39,9 +36,6 @@ Documentation = "https://github.com/nexform-tech/litearm-python/blob/main/docs/D [project.scripts] litearm-python = "litearm.arm:main" -[tool.pytest.ini_options] -testpaths = ["tests"] - [tool.setuptools.packages.find] where = ["src"] 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/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..d90348e 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` 分两支措辞 (归因用), 不参与任何判据。 @@ -936,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: @@ -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..ba5fbb5 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) @@ -379,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/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_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_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_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() 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("