Repository navigation
Conversation
固件 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
left a comment
There was a problem hiding this comment.
合并 + 全面测试复核(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_reusetest_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() 偏移解析正确。全程未使能/失能、未运动,写入均为预期被拒。
合并前建议
- rebase 到当前 main(或采纳上述冲突处理),当前
mergeable=false。 - 把 4 条
test_err_text_item_set_matches_firmware移植到新套件:它们现在随test_error_codes.py一起被 #35 的删除吃掉,合并后 main 上就没有这条核心判据了(反向验证已证明它有效)。 - 版本断言同步 2.4.1(见上表)。
- 真机结论:本 PR 的协议/文案改动在两条 1.12.3-7J 臂上行为一致,并发下无跨臂串扰。
🤖 Generated with Claude Code
cao-xiao-hao
left a comment
There was a problem hiding this comment.
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 fourtest_err_text_item_set_matches_firmwarecasestests/test_ff_io.py— item pass-through anddrag_gaincasestests/test_full_coverage.py— 0x51 coveragetests/test_protocol_sync.py— status-frame layout allowancetests/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+8and 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_NAMEShas no entry for0x51, so a rejection ofGET_FAULTon older firmware renders asCMD 0x51instead ofGET_FAULT.ZeroGActiveErrorandCartInFlightErrorare defined inerrors.pybut are not exported fromlitearm/__init__.py, unlike every other error class with anE-xxid.docs/DEVELOPER_GUIDE.mdsays "0x2B/0x2Cread paths use the same sets as their write counterparts". That is inaccurate for0x2C: item 9 is readable (ff_mask) but not writable through0x28.- 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 answersERR, which surfaces asCommandRejectedError. That class is not a subclass ofInvalidCommandError, so callers catching the latter will stop catching this case. This belongs in the PR Summary as a consumer-visible change.
Positive notes
- Adding
0x2FtoRSP_OF_CMDis a real fix;mainis 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.
变更
RSP_OF_CMD补0x2F/0x51:查询前清掉迟到的专属应答,避免被下一次查询误用state.py注释同步 1.12.3:故障原因不在状态帧里,走get_fault_detail()判据
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完整性与实际清队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 故障详情查询)。