qing
58725c8a12
pybot --loop HEF 后端异步闭环（执行上一步动作与 NPU 推理并行）与 actpred predict_async 流水线落地后未同步文档，本次补齐： - pybot/README：--loop 补异步推理路径说明（滞后一拍，~16ms→~12ms） - actpred/README：Hailo 节新增 predict_async 小节（缓冲语义/2.6× 实测） - 根 README、MODULES.md、ARCHITECTURE.md：pybot 行与机器人数据链同步 - MODULES.md：docs md 计数 70→76；ARCHITECTURE §9 挂 panel 设计稿规划项
104 lines
4.9 KiB
Markdown
104 lines
4.9 KiB
Markdown
# pybot
|
||
|
||
机器人 `.mt` 动作脚本解析器 —— [bot4cj](../bot4cj/)（仓颉版）的 Python 迁移版。
|
||
|
||
驱动大顺（Dashun）蜘蛛机器人（树莓派 aarch64，10 舵机 + 2 云台，
|
||
PCA9685 PWM 控制器 + MPU6050 姿态传感器）。
|
||
|
||
迁移方案与审计修复映射见
|
||
[docs/reports/bot4cj_python_migration_dev_doc.md](../docs/reports/bot4cj_python_migration_dev_doc.md)。
|
||
|
||
## 特性
|
||
|
||
- **零第三方依赖**：纯标准库（fcntl / struct / threading / wave / argparse），
|
||
树莓派上 `git pull` 即部署，无构建步骤。
|
||
（picamera2 为可选依赖，仅 `@Camera` 摄像头块需要，树莓派 OS 预装，勿 pip 安装）
|
||
- **与仓颉版逐语义对齐**：FSM 解析器、占位符递归、Servo 校准算法、
|
||
PCA9685 寄存器序列均与 bot4cj 一致（Mock 总线 journal 可逐字节 diff）。
|
||
- **Python 插件替代 Lua**：`modules/<块名>.py` 定义
|
||
`build(ctx) / call(ctx) / destroy(ctx)`，消除 JSON 深拷贝 + 五层 FFI 桥接。
|
||
- **审计修复**：bot4cj 审计 15 项发现（S01~S08 / Q01~Q07）全部修复，
|
||
详见迁移文档 §5。
|
||
|
||
## 用法
|
||
|
||
```bash
|
||
cat scripts/std.mt | ./_run.sh # 与 bot4cj 相同的管道用法
|
||
./_run.sh scripts/std.mt # 位置参数（增强）
|
||
./_run.sh --dry-run scripts/std.mt # Mock 总线，动作序列到 stdout
|
||
./_run.sh --test roundtrip in.mt out.mt # 解析↔序列化往返自检
|
||
./_run.sh --verbose scripts/std.mt # DEBUG 日志（stderr）
|
||
./_run.sh --record data/ep scripts/std.mt # 录制 actpred 格式 episode
|
||
```
|
||
|
||
`--record` 时若脚本含 `@MPU6050_BIND` 块，逐帧同步落盘 `imu.npy`
|
||
（每传感器 8 槽 roll,pitch,ax,ay,az,gx,gy,gz；多个传感器（≤4）按块行顺序
|
||
拼接，shape (T, 8×N)，与图像/动作按帧时刻天然对齐）；
|
||
无 IMU 硬件则保持旧格式（仅 images + actions.npy）。
|
||
|
||
`-i` / `-o` 参数位保留（reserved），未来对接跨进程 FIFO。
|
||
|
||
### 实时预测闭环（`--loop`）
|
||
|
||
`--loop CKPT` 进入进程内闭环：采样 → actpred 推理 → 执行 → 回写历史。
|
||
脚本提供硬件配置与 `@Action` 表头（动作向量索引映射），不执行脚本动作行。
|
||
|
||
```bash
|
||
./_run.sh --loop ../actpred/checkpoints/best_inference.pt --hz 10 scripts/std.mt
|
||
./_run.sh --loop actpred_pretrain.hef --hz 20 --loop-steps 100 scripts/std.mt # NPU 后端
|
||
```
|
||
|
||
- checkpoint 后缀 `.hef` → Hailo NPU 后端，否则 → PyTorch 后端
|
||
- `hz` 须 ≥ 推理 + 执行耗时（ONNX ~11ms / Hailo ~12ms，hz ≤ 50 安全）
|
||
- **异步推理路径**：predictor 提供 `predict_async`（Hailo NPU 后端，见
|
||
actpred `hailo_infer.py`）时自动启用——提交推理后**并行执行上一步动作**
|
||
（滞后一拍执行，动作与状态错位一拍，10Hz 下 = 100ms，对微动作步态影响
|
||
可忽略），隐藏真实 I2C 执行耗时（实测 HEF 步耗时 ~16ms → ~12ms）；
|
||
PyTorch/ONNX 同步路径不变
|
||
- `@Action` 表头列数须 ≤ `action_dim`（默认 18），闭环中跳过 `spk.delay` 阻塞
|
||
- **帧源**：闭环从 camera 守护线程队列取最近 F 帧（无阻塞），`@Camera` 的
|
||
`framerate` 建议 ≥ 2×`hz` 以保证帧新鲜度；`capacity` 应 ≥ F（帧窗长度）。
|
||
部署时若日志出现 `loop overrun` 告警，说明 `hz` 超过推理+执行能力，应降低 `hz`
|
||
- **姿态回流（R2）**：脚本含 `@MPU6050_BIND` 且模型带 imu 输入
|
||
（`predictor.imu_dim` 非 None）时，每步读取 MPU6050 最新姿态随帧/历史
|
||
一同传给推理器（原始量纲，归一化在推理端完成）；多个传感器（≤4）按
|
||
块行顺序拼接为 8×N 向量，再 pad/truncate 到 `predictor.imu_dim`；
|
||
模型无 imu 输入时不接入推理（若带 `--record` 仍会读取落盘 imu.npy）
|
||
|
||
## 目录
|
||
|
||
```
|
||
pybot/ # 包：parser / robot / hardvars / plugin / main
|
||
pybot/hd/ # 硬件层：i2c / spi / servo / kalman / mpu6050 / speaker / camera
|
||
modules/ # 硬件驱动插件：PCA9685 / SPI / ADS1115 / ADS1256
|
||
scripts -> ../bot4cj/scripts # .mt 脚本与仓颉版共享
|
||
tests/ # pytest 单元测试（Mock 总线，无需硬件）
|
||
```
|
||
|
||
插件查找顺序：`$PYBOT_MODULES_PATH`（`os.pathsep` 分隔：Linux `:` / Windows `;`）→ 包内置 `modules/` → `./modules/`。
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
./_set.sh # venv + pytest 全量测试
|
||
venv/bin/python -m pytest tests/ -v
|
||
```
|
||
|
||
## .mt 脚本格式
|
||
|
||
见 [bot4cj/README.md](../bot4cj/README.md) 与 `scripts/std.mt`。
|
||
格式要点：`@块名` 开块、行 0 为表头、`;` 结行、`#` 注释、
|
||
`-` 占位符（非首行取上一行同列值；首行数值列解析为 0）、`@` 收块。
|
||
|
||
新增块（无仓颉版对应）：
|
||
|
||
```
|
||
@Camera
|
||
name width height framerate capacity;
|
||
cam0 1920 1080 30 4;
|
||
@
|
||
```
|
||
|
||
`build` 启动后台抓帧线程，维护容量为 `capacity` 的有界帧队列（满丢最旧帧）；
|
||
`play` 返回最新帧 `(时间戳, frame)`。
|