Skip to content

fix(errors): 对齐 1.12.3 item 集合 + 补 0x2F/0x51 清队 (2.4.1) - #51

Open
luomaofu wants to merge 7 commits into
mainfrom
feat/zero-g-v10-params
Open

luomaofu wants to merge 7 commits into
mainfrom
feat/zero-g-v10-params

Conversation

@luomaofu

Copy link
Copy Markdown
Contributor

变更

  • 0x26/0x28/0x2B/0x2C 的合法 item 集合与固件 1.11/1.12 对齐(1.11.0 删 12..14;1.12.0 加 0x26 item16、删 0x28 item10)
  • 0x06 错误文案补 drop_hold 门禁
  • RSP_OF_CMD 补 0x2F / 0x51:查询前清掉迟到的专属应答,避免被下一次查询误用
  • state.py 注释同步 1.12.3:故障原因不在状态帧里,走 get_fault_detail()
  • 交付文档补 §5.17(故障详情 + 错误描述),中英文同步
  • 版本 2.4.0 -> 2.4.1

判据

  • 新增 test_err_text_item_set_matches_firmware(4 条):从固件 params.c / usb_cmd.c 现解合法 item 集合,再要求错误文案与之一致
  • 新增 test_dedicated_replies_are_cleared_before_reuse / test_drain_for_clears_fault_and_license_queues:盯 RSP_OF_CMD 完整性与实际清队
  • 反向验证:把 0x2B 文案改回“须 1..15”、从 RSP_OF_CMD 删掉 0x51,两条新判据都会红

验证

  • python -m pytest -q:789 passed, 2 skipped
  • 未上真机:本次只改错误文案、状态注释、查询清队与文档;协议与动作语义未变

说明

本分支同时包含 1.12.x SDK 的既有提交(2.2.0 逐关节 drag_gain、2.3.0 错误描述、2.4.0 故障详情查询)。

固件 1.11.0 把零重力改成无状态力矩律,删除了 5 组参数:
  0x26 item 12/13/14 = zg_kp / zg_kd / zg_damping
  0x28 item 13..16   = zg_vel_thr / zg_engage_sec / zg_engage_kp / zg_engage_kd

SDK 侧同步:
- FF_VEC_ITEMS 由 1..15 收窄为 1..11 + 15(12..14 本地即拒);
- FF_SCALAR_ITEMS 去掉 13..16(保留 17 wall_fw_kd / 18 hold_kp_gain);
- 错误文案与 _protocol.py 的 item 注释同步。

编号不做复用:固件对已删 item 回 ERR{cmd,0x02},SDK 本地拒是一致的。
判据:tests/test_ff_io.py 的 item 全集用例;753 passed / 2 skipped。
- FF_VEC_ITEMS 增加 16=drag_gain; FF_SCALAR_ITEMS 删除 item10
- 新增 set_drag_gain / get_drag_gain
- 版本 2.2.0; 文档与离线测试同步
- decode_status 支持 1.12.2 布局 (6+21N+8): fault_reason[N] + drop_hold_reason
- RobotState.fault_reasons -> [(轴号, 原因号)]; 旧固件为空列表
- 错误码直接用固件二元组 (2B-02 / FF-01), 不编号、不建反向表
- describe/describe_fault/describe_exc: 命令名 + 通用档模板, zh-CN/en-US
- 异常类绑定 E-01..E-16; 未知码也能渲染, 不空白
- 全量 773 passed, 2 skipped
- decode_status 读 flags bit11 -> RobotState.fault_detail_available
- Arm.get_fault_detail() -> FaultDetail (tick/cause/reason[N]/drop)
- 状态帧布局冻结在 153B, 新能力只走请求-应答
- 全量 778 passed, 2 skipped
- 固件 payload = tick u32 + cause + reason[N] + drop (13B), 不含响应码
- 原按 RSP_FF_VEC 的自带 id 惯例解析, 真机立刻暴露 1 字节错位
- 测试载荷改为与固件逐字节一致; 真机 0x51 返回全 0 通过
- 新增 ZeroGActiveError(E-17) / CartInFlightError(E-18), 不再折成 E-05 参数非法
- 修正 local_text: (标题, 动作) 不再把动作放进 cause 字段
- 现场点复位被零重力守卫拒绝时, 码与处置可直接定位
- 778 passed, 2 skipped
- 0x26/0x28/0x2B/0x2C 的合法 item 集合与固件 1.11/1.12 对齐
- 0x06 错误文案补 drop_hold 门禁
- RSP_OF_CMD 补 0x2F/0x51,避免迟到的专属应答被下一次查询误用
- state.py 注释同步 1.12.3 的 0x51 查询路径
- 新增 item 集合漂移哨兵与清队判据
- 交付文档补 §5.17

@X-F-R X-F-R left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

合并 + 全面测试复核(2.4.1 @ 0e43a2f)

在本地把本 PR 合入当前 main(33dc2c6,已含 #46/#47/#48),完成冲突处理、离线回归与双臂真机测试,结果如下。

合并冲突与处理

位置 冲突 处理
pyproject.toml / src/litearm/__init__.py 版本 2.2.0 vs 2.4.1 取 2.4.1
tests/test_error_codes.py 等 5 个文件 #35 已在 main 删除旧测试套件,本 PR 仍修改它们 保留删除(遵循 #35 决议)
src/litearm/_protocol.py 注释引用了已删测试 保留 PR 的“假成功方向”说明,去掉测试路径引用
src/litearm/errors.py 0x28 文案旧口径 vs 新合法集 取 PR 的 1..8、11、17、18 文案
tests/test_smoke.py::test_version 仍钉 "2.2.0" 同步为 "2.4.1"(合并时必须一起改,否则 main 的冒烟直接红)

合并后 #48 的 CollisionModel / LocalKinematicsError 等公开面保持完整。

测试结果

离线(PR 分支,LITEARM_FW_DIR 指向固件 1.12.3 源码)

789 passed, 2 skipped

PR 点名的 6 条判据显式跑通:

  • test_err_text_item_set_matches_firmware[38/40/43/44]
  • test_dedicated_replies_are_cleared_before_reuse
  • test_drain_for_clears_fault_and_license_queues

反向验证(复现 PR 描述)

  • 把 0x2B 文案改回“须 1..15” → [43] 变红 ✅
  • 从 RSP_OF_CMD 删掉 0x51 → test_dedicated_replies_are_cleared_before_reuse 变红 ✅

离线(合并后的 main)

49 passed, 15 skipped(跳过全部是可选依赖 pinocchio/scipy 缺失)

真机双臂并发(ACM0/ACM1 均为 Litearm1.12.3-7J,7J,独立线程同时驱动)

/dev/ttyACM0: 39/39 PASS
/dev/ttyACM1: 39/39 PASS

覆盖:0x28 合法集 1..8/11/17/18;0x26 与 0x2B 合法集 1..11/15/16(item 16=drag_gain 可直接读回);0x2C 合法集 1..9/11/17/18;删项均回对应 ERR{cmd,0x02} 且文案与固件一致;0x2F/0x51 交替 20 轮无迟到应答串用;get_fault_detail() 偏移解析正确。全程未使能/失能、未运动,写入均为预期被拒。

合并前建议

  1. rebase 到当前 main(或采纳上述冲突处理),当前 mergeable=false。
  2. 把 4 条 test_err_text_item_set_matches_firmware 移植到新套件:它们现在随 test_error_codes.py 一起被 #35 的删除吃掉,合并后 main 上就没有这条核心判据了(反向验证已证明它有效)。
  3. 版本断言同步 2.4.1(见上表)。
  4. 真机结论:本 PR 的协议/文案改动在两条 1.12.3-7J 臂上行为一致,并发下无跨臂串扰。

🤖 Generated with Claude Code

@cao-xiao-hao cao-xiao-hao left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additional review at 0e43a2f

Reviewed the PR head in an isolated worktree against main (33dc2c6). This adds to the earlier merge/test report and focuses on what changed for this branch since then.

Test evidence

With LITEARM_FW_DIR unset (no firmware source tree):

765 passed, 26 skipped in 65.48s

The PR body reports 789 passed, 2 skipped. Both runs total 791 tests, so the 24-test difference is exactly the firmware-sentinel group that skips without a source tree. The reported result is consistent.

Blocking

1. Rebasing drops more coverage than the earlier review noted

main deleted the old test suite in #35, then added the minimal suite in #47. Five test files modified by this branch no longer exist on main, so their changes disappear when the branch is rebased:

  • tests/test_error_codes.py — the four test_err_text_item_set_matches_firmware cases
  • tests/test_ff_io.py — item pass-through and drag_gain cases
  • tests/test_full_coverage.py — 0x51 coverage
  • tests/test_protocol_sync.py — status-frame layout allowance
  • tests/test_status_layout.py — 161B/29B decode cases

Only tests/test_error_describe.py and tests/test_fault_detail.py are new files and survive unchanged. The core feature of this PR (item-set alignment) therefore ships with no test in the merged tree unless those judgments are ported into the new suite. Please move them into a new file rather than restoring the deleted suite.

2. Version edits conflict with the release process

main has .releaserc.json and release.yml. The latest tag is v1.4.0, and the release jobs rewrite pyproject.toml's version and __init__.py's __version__ from the tag before building. The hand-written 2.4.1 is never published, and the squashed commit subject fix(errors): ... produces a patch (v1.4.1), not 2.4.1.

Please drop the version changes in pyproject.toml and src/litearm/__init__.py. If the version stays at the value already on main (2.2.0), tests/test_smoke.py does not need to change either. If the intent is a minor release, the PR title must be feat(...), because a multi-commit PR takes its title as the squash subject.

3. 1J status-frame length is unverified

decode_status accepts exactly 2 + N + 1 trailing bytes after the joint records: 161B for 7J, 29B for 1J. The firmware buffer is declared as 6 + LITEARM_NUM_JOINTS * 21 + 8, which is 35B for 1J. The older 1.10.1 firmware sends the actual written length rather than the buffer size, so 29B may well be correct, but:

  • hardware validation in this PR covers 7J only;
  • the docstring says the layout is 6+21N+8 and also that 1J is 29B, which cannot both be true.

Please confirm the actual 1.12.x 1J frame length (firmware source or a 1J arm) before merging. A 35B 1J frame would be rejected by decode_status and break status reporting on 1J hardware.

Smaller items

  • errors.CMD_NAMES has no entry for 0x51, so a rejection of GET_FAULT on older firmware renders as CMD 0x51 instead of GET_FAULT.
  • ZeroGActiveError and CartInFlightError are defined in errors.py but are not exported from litearm/__init__.py, unlike every other error class with an E-xx id.
  • docs/DEVELOPER_GUIDE.md says "0x2B / 0x2C read paths use the same sets as their write counterparts". That is inaccurate for 0x2C: item 9 is readable (ff_mask) but not writable through 0x28.
  • Removing the client-side item whitelist changes observable behavior: an item outside the old whitelist used to raise a local InvalidCommandError; it now sends the frame and the firmware answers ERR, which surfaces as CommandRejectedError. That class is not a subclass of InvalidCommandError, so callers catching the latter will stop catching this case. This belongs in the PR Summary as a consumer-visible change.

Positive notes

  • Adding 0x2F to RSP_OF_CMD is a real fix; main is missing it, so a late license reply can be consumed by the next query.
  • Passing unknown items through to the firmware is the right call for supporting both 1.10.x and 1.12.x with one SDK.

Requested next step

Rebase onto main (33dc2c6), drop the version edits, and port the lost judgments into the new test suite. The rebase also brings in .github/workflows/ci.yml, so CI will run for the first time on this PR. I would not merge before that run is green.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants