LeKiwi 底盘有界能力 + 配件知识数据化 (ADR-017/018, AT-032/033/038) #2

Open
jiaqi02.sun wants to merge 14 commits from codex/lekiwi-chassis into codex/sim-rebuild
Owner

堆叠在 #1 之上(本分支 = codex/sim-rebuild + 底盘/配件切片),#1 合入后此 PR 差异即底盘部分。

内容

ADR-017 — LeKiwi 底盘有界能力(真机验收通过 16/16)

  • 工装声明(人工面、观察事实门控)+ 有界模板:探查自动(零写自证)、运动逐次审批单次消费
  • 三层包络(宿主计划前/程序内/验证器)+ 安全终态收敛回读
  • 真机证据:7/8/9 舵机应答(型号 777、11.4V)、vx=0.05 m/s 微动 1s 自停、运动中取消;断电演练 not_run
  • 真机揪出并修复:Feetech 状态帧 LEN 语义、STS 裸 ACK、停止采样收敛等 6 项(均有回归)

ADR-018 — 配件知识数据化(机制是代码,配件是数据)

  • AccessoryPack 注册表:内置审核层(数据文件)+ 本机用户层,同模型同绝对上限、出处必填、能力族受控
  • 通用能力族:base.scan / base.velocity.bounded;模板 base-scan/base-move;轮角等运动学由宿主注入
  • 记住:配件账册(VID:PID/串口事实,拔了也记得);推荐:注册表×设备事实 → active/ready/missing_facts
  • 协议面:agent 面 accessory.registry/history,人工面 accessory.pack.create/remove;Pi 工具、rdkctl、AT-038 覆盖数据边界

门禁

pytest 全绿、ruff/format/mypy clean、pi 24 / surface 62 / desktop 7(0 fail)

未决

  • ADR-018 重构后的真机复跑(验证数据驱动链路复现 16/16)——验收时板子链路中断,留待下次
  • 断电演练(用户决定下次做)
  • GUI:设备卡 peripherals 渲染、模板参数表单(后续切片)
**堆叠在 #1 之上**(本分支 = codex/sim-rebuild + 底盘/配件切片),#1 合入后此 PR 差异即底盘部分。 ## 内容 **ADR-017 — LeKiwi 底盘有界能力(真机验收通过 16/16)** - 工装声明(人工面、观察事实门控)+ 有界模板:探查自动(零写自证)、运动逐次审批单次消费 - 三层包络(宿主计划前/程序内/验证器)+ 安全终态收敛回读 - 真机证据:7/8/9 舵机应答(型号 777、11.4V)、vx=0.05 m/s 微动 1s 自停、运动中取消;断电演练 not_run - 真机揪出并修复:Feetech 状态帧 LEN 语义、STS 裸 ACK、停止采样收敛等 6 项(均有回归) **ADR-018 — 配件知识数据化(机制是代码,配件是数据)** - AccessoryPack 注册表:内置审核层(数据文件)+ 本机用户层,同模型同绝对上限、出处必填、能力族受控 - 通用能力族:base.scan / base.velocity.bounded;模板 base-scan/base-move;轮角等运动学由宿主注入 - 记住:配件账册(VID:PID/串口事实,拔了也记得);推荐:注册表×设备事实 → active/ready/missing_facts - 协议面:agent 面 accessory.registry/history,人工面 accessory.pack.create/remove;Pi 工具、rdkctl、AT-038 覆盖数据边界 ## 门禁 pytest 全绿、ruff/format/mypy clean、pi 24 / surface 62 / desktop 7(0 fail) ## 未决 - ADR-018 重构后的真机复跑(验证数据驱动链路复现 16/16)——验收时板子链路中断,留待下次 - 断电演练(用户决定下次做) - GUI:设备卡 peripherals 渲染、模板参数表单(后续切片)
jiaqi02.sun added 14 commits 2026-08-27 14:41:49 +08:00
Open the first physical-output capability per ADR-012 §5: a human-declared,
reviewed fixture pack (lekiwi-base) overlays chassis capabilities onto device
snapshots when the serial node is an observed fact. Discovery (base.scan.lekiwi,
R0, zero bus writes) runs automatically once available; motion
(base.velocity.lekiwi, R2) only runs as a reviewed template with envelope
parameters and a per-run human approval (single-use). Probes keep zero
interaction with actuator buses (AT-002 unchanged); VID:PID never infers
product naming.

- core: fixtures.py (FixtureDeclaration, REVIEWED_PACKS, overlay), schema
- host: FileFixtureStore, overlay on inventory/inspect, parameterized
  two-phase templates, fixture/template protocol methods, json.range verifier
- cli: rdkctl fixture declare/list/remove, template list/run/start
- pi: rdk_template_list/run/start + rdk_fixture_list tools, SKILL.md guidance
- docs: ADR-017, docs/05 §3/§9/§13, docs/03 §2.2.2/§2.3, CFR-026, baseline
  v0.7, HIL spec §5A, AT-031/032, traceability, CLAUDE.md note
- gates: pytest 721 pass, ruff/format/mypy clean, pi 24/5skip, surface 62/6skip,
  desktop 7/0; also fixes an approval-misuse lease leak (failed start left a
  non-terminal record holding the device write lease) and the surface barrel
  tripwire drift (listSkills/readSkill)
Real-device acceptance (AT-031/032) exposed two sharp edges:

1. _execute_start consumed the single-use human approval BEFORE the
   exclusive write-lease check; a lease conflict (e.g. a scan still
   running) burned the approval. Lease now rejects first.
2. A host process that dies after starting a run leaves a non-terminal
   record holding the write lease. The drive script reconciles zombie
   runs via run_status (device truth) before starting; product-level
   auto-reconcile for template runs noted as follow-up.

Also: HIL wait window 10s -> 60s (bus scans spend seconds in servo
timeouts), clean-slate fixture handling for reruns, and the lease-order
regression test.
The sim session committed AT-031 (embodiment follows detected device) while
this branch was in flight; rebase onto b548dab and take the next free
numbers. Also drop the stale empty runtime artifacts from the first HIL
attempt — they regenerate on the next drive run.
Real-device finding: LeKiwi servos powered (red LEDs), signal line seated,
yet the bus stayed completely silent. USB-CDC bus-servo adapters commonly
gate the TTL transceiver on modem lines; pyserial (LeRobot's driver) asserts
DTR/RTS on open, the bare termios open did not.
No servo answers at the pack baud (1 Mbaud) despite powered servos (red
LEDs), seated signal line and DTR/RTS asserted. Sweep 500k/250k/115200
and record raw wire bytes per rate so an RX-path fault is distinguishable
from a baud mismatch. Still zero write commands.
Board-side termios module crashed at import (AttributeError), scan never
reached the bus. Verified against the board's Python; sweep tiers are now
500000/230400/115200/57600.
54 raw bytes arrived at 1 Mbaud with no parseable frame — need per-ping
evidence to tell adapter TX echo apart from corrupted servo replies.
Real-bus evidence proved the parser wrong: ID 7 answered every ping with a
valid ACK (07 02 00 f6, checksum ~(7+2+0)=0xf6), rejected as 'checksum
mismatch' because the parser expected CHK outside the LEN range. STS-series
ping ACKs carry no model payload, so ping now returns 0 for a bare ACK and
the scan reads REG_MODEL for the real number. Read/write/stop all shared
this misframing — every real-bus transaction was affected.
Protocol (decisive real-bus evidence):
- Feetech status framing: LEN includes ERR and CHK bytes. Servos answered
  every ping with a valid ACK (07 02 00 f6, checksum ~(7+2+0)=0xf6) that
  the old parser rejected as 'checksum mismatch' — the earlier 'bus silent'
  was our bug, not the hardware.
- STS ping ACK carries no model payload; ping returns 0 for a bare ACK and
  the scan reads REG_MODEL (777 = STS3215).
- Assert DTR/RTS on open (pyserial parity) and keep the baud sweep +
  per-ping RX accounting as diagnostic evidence.

Stop confirmation:
- At-rest Present_Velocity reads exactly 0 (twos complement). The -30k
  values right after the stop write were half-duplex parse artifacts; the
  envelope bounds real wheel speed to ~1400 raw, so >4096 read-backs are
  re-sampled as glitches and stop is confirmed by two consecutive
  in-tolerance samples of every wheel.

Facts:
- This LeKiwi assembly has NO 12V switch; the kill method is unplugging
  the battery connector. Corrected in fixtures, ADR-017, AT-033, HIL §5A
  and the hardware baseline.
- Evidence: LEKIWI-CHASSIS.md + artifacts; mechanism 16/16, scan and
  bounded motion passed on hardware; power-cut drill deferred (not_run).
The agent's accessory capabilities are now DATA, not product code:

- AccessoryPack model (core): servo ids, motion envelope with ABSOLUTE
  product ceilings, kinematics (incl. wheel mounting angles), bus
  protocol, requirements, mandatory provenance. Shipped packs are JSON
  validated by the model; user packs use the SAME model with the same
  ceilings (FileAccessoryPackStore, state dir).
- Capability ids generalized: base.scan (R0) / base.velocity.bounded
  (R2, aligns with sim naming); packs reference the modeled capability
  set and can never mint new ones. Templates renamed base-scan/base-move;
  Template.fixture_pack -> fixture_capability, resolved against the
  device's declared pack at run time; pack envelope gated host-side
  before planning (three-layer enforcement kept).
- Mechanism unchanged: human fixture declaration over observed facts,
  default-deny policy, R2 per-run approval, zero bus interaction from
  probes, VID:PID never infers product identity.

Docs: ADR-018; docs/03 §2.2.2, docs/05 §3/§9, baseline, traceability;
AT-032/033 generalized (LeKiwi stays the instance), AT-034 added.
- Accessory ledger: inventory records raw accessory facts (VID:PID /
  serial nodes, first/last seen) per device; facts only, never product
  naming (AT-002). Fake engine now emits peripherals like the real one.
- Recommendation: registry x snapshot facts -> active / ready /
  missing_facts per pack (CFR-014 style); advice only, capabilities still
  need a human fixture declaration.
- User packs: accessory.pack.create/remove on the human plane; same
  AccessoryPack model with the same absolute ceilings, provenance
  required, shipped ids cannot be shadowed; in-use packs cannot be
  removed. rdkctl gains 'accessory recommend|history|pack create|remove'.
- Agent plane: accessory.registry + accessory.history (R0 facts) with Pi
  tools rdk_accessory_registry / rdk_accessory_history; AT-021 tripwire
  updated; pack create/remove stay human-only.
- rdk-develop skill: accessory guidance generalized (recommend from the
  registry, never infer from VID:PID).
fix(rebase): sim-export dispatch tail + AT-038 renumber after sim-rebuild integration
Some checks failed
ci / python (pull_request) Has been cancelled
ci / typescript (pull_request) Has been cancelled
137edebadb
The sim session reserved AT-034..037 (ADR-019); the accessory-registry
acceptance becomes AT-038. Also repair the sim export dispatch statement
truncated during conflict resolution.
Some checks failed
ci / python (pull_request) Has been cancelled
ci / typescript (pull_request) Has been cancelled
This pull request can be merged automatically.
You are not authorized to merge this pull request.

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin codex/lekiwi-chassis:codex/lekiwi-chassis
git checkout codex/lekiwi-chassis
Sign in to join this conversation.
No Reviewers
No Label
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: jiaqi02.sun/rdkagentsun#2
No description provided.