169 lines
5.4 KiB
Markdown
169 lines
5.4 KiB
Markdown
# 真机部署与验证指南
|
||
|
||
本文档面向仓库中的 `05_software/real/sim2real_v2`（`v0.9.0`），用于减少上机排错时间。默认不修改该快照中已验证的电机映射、方向、零位和策略观测。
|
||
|
||
## 1. 前期环境
|
||
|
||
推荐在 Orin / Linux 上运行：
|
||
|
||
```bash
|
||
cd 05_software/real/sim2real_v2
|
||
python -m pip install -r requirements-orin.txt
|
||
```
|
||
|
||
确认设备：
|
||
|
||
```bash
|
||
ip link show can0
|
||
ip link show can1
|
||
ls -l /dev/ttyACM0
|
||
```
|
||
|
||
确认 `config.yaml`：
|
||
|
||
- `can1_port` 和 `can2_port` 对应实际 SocketCAN 设备。
|
||
- `control_freq` 默认保持 `50`。
|
||
- `remote.port` 默认 `/dev/ttyACM0`。
|
||
- `policy.action_scale` 必须是 16 维。
|
||
- 默认策略文件优先使用 `policies/model_rough.onnx`；如果只有 `.pt`，先用 `tools/export_onnx.py` 导出。
|
||
- `controller.kp_leg/kd_leg/kd_wheel` 不要在未记录实验的情况下大改。
|
||
|
||
## 2. 无硬件/低风险检查
|
||
|
||
先做文件和模型契约检查：
|
||
|
||
```bash
|
||
python tools/export_onnx.py --pt policies/model_rough.pt --onnx policies/model_rough.onnx
|
||
python tools/alignment_check.py --policy policies/model_rough.onnx --manifest deployment_manifest.yaml
|
||
python tools/standalone_check.py
|
||
python -m py_compile tools/logger.py interface/motor_driver.py interface/imu_client.py interface/real_io.py web/session.py
|
||
```
|
||
|
||
`alignment_check.py` 会同时检查：
|
||
|
||
- 策略 obs/action 维度。
|
||
- action scale。
|
||
- default pose。
|
||
- joint order。
|
||
- wheel indices。
|
||
- `config.yaml` 与 `deployment_manifest.yaml` 的控制频率和 command filter 是否一致。
|
||
- ONNX 策略的 obs/action 维度是否仍为 `53D/16D`。
|
||
|
||
如果有 Node 环境，可检查前端语法：
|
||
|
||
```bash
|
||
node --check web/static/app.js
|
||
```
|
||
|
||
## 3. 上电前检查
|
||
|
||
上电前确认：
|
||
|
||
- 机器人架空或有可靠支撑。
|
||
- 16 个电机 CAN 线和电源线固定。
|
||
- Odin1 连接稳定，启动时机器人尽量静止，利于重力对齐。
|
||
- Web 急停可见，遥控软急停通道可用。
|
||
- CAN 设备名和遥控串口名与 `config.yaml` 一致。
|
||
|
||
## 4. Web 启动
|
||
|
||
```bash
|
||
python web/server.py --host 0.0.0.0 --port 8080
|
||
```
|
||
|
||
浏览器打开：
|
||
|
||
```text
|
||
http://<orin-ip>:8080
|
||
```
|
||
|
||
推荐先只看状态，不急着释放遥控。
|
||
|
||
## 5. 标准上机流程
|
||
|
||
1. 点击 `Connect`，确认 IMU/Odin 和 CAN 初始化正常。
|
||
2. 点击 `Enable Motors`，确认 16 个电机都有反馈。
|
||
3. 点击 `Startup`，从当前实测姿态过渡到站立。
|
||
4. 进入 `STAND_HOLD` 后观察 IMU age、Motor Fresh、Loop Profile。
|
||
5. 点击 `Start Runtime`，进入 50Hz 策略循环。
|
||
6. 策略 release 后再点击遥控接管。
|
||
7. 小幅给命令，先测试前后、转向，再测试组合动作。
|
||
|
||
## 6. 本轮新增诊断如何看
|
||
|
||
`Loop Profile`：
|
||
|
||
- `read_state_ms` 高：优先查电机接收、CAN 队列、Odin 获取是否阻塞。
|
||
- `policy_ms` 高：优先查策略推理和 CPU 负载。
|
||
- `send_actions_ms` 高：优先查 CAN 发送和 USB-CAN 适配器。
|
||
- `log_ms` 高：说明日志队列或磁盘仍可能有压力。
|
||
|
||
`Motor Fresh`：
|
||
|
||
- 理想状态是 `16/16 (cnt 16, val 0)` 或接近。
|
||
- `cnt` 高说明 `update_count` 正常增长，这是最可靠的电机反馈证据。
|
||
- 如果机器人静止时 `val` 为 0 是正常现象，不应据此判断丢电机。
|
||
|
||
`Odin Odom`：
|
||
|
||
- 显示 `STANDARD/HIGHFREQ/TF`、age、local x/y/yaw。
|
||
- 当前只用于诊断和全局坐标显示，不参与策略输入。
|
||
- odom 不可用时，当前 locomotion 仍应可以运行。
|
||
- 如果显示 `JUMP`，说明 odom 局部位置或 yaw 出现突变，先不要把它用于闭环导航。
|
||
|
||
`Latest Target`：
|
||
|
||
- 显示当前电机目标来源，例如 `runtime_policy`、`runtime_zero_hold`、`runtime_release_hold`。
|
||
- `age` 应随 runtime 正常刷新；如果明显超过控制周期很多，说明目标更新链路卡住。
|
||
- `d` 是相邻目标最大变化量，可用于观察停车/起步是否有目标突变。
|
||
|
||
`Obs / Action`：
|
||
|
||
- `obs` 接近 `100` 时，说明观测可能接近 clip 边界。
|
||
- `raw` 接近 `10` 时，说明策略输出可能接近 raw action 裁剪边界。
|
||
- `scaled` 长期很大时，检查 action scale、目标限幅和 safety clip。
|
||
|
||
`cmd/raw cmd`：
|
||
|
||
- `raw cmd` 是 Web/遥控原始输入。
|
||
- `cmd` 是经过 `command_filter` 限加速度后的策略命令。
|
||
- 如果机器人响应慢，先看两者差值是否由命令滤波造成。
|
||
|
||
## 7. 如果出现前后晃动
|
||
|
||
先不要直接改控制频率。按顺序排查：
|
||
|
||
1. 看 `Loop Overruns` 是否增长。
|
||
2. 看 `Loop Profile` 最慢阶段。
|
||
3. 看 `imu_age` 是否超过 30-60ms。
|
||
4. 看 `Motor Fresh` 是否掉到 16 以下。
|
||
5. 看停止时 `cmd` 是否真的回到 0。
|
||
6. 看 `runtime_released`、`release_alpha` 和 `track_err` 是否异常。
|
||
|
||
只有确认 50Hz 长期跑不稳时，才把 `control_freq: 40` 作为诊断实验，而不是默认方案。训练/部署频率不一致可能引入新的 sim2real gap。
|
||
|
||
## 8. 日志
|
||
|
||
每次运行会生成：
|
||
|
||
- `state.csv`：高频状态流，后台线程写入。
|
||
- `events.jsonl`：事件流，关键事件会即时 flush。
|
||
|
||
重点搜索：
|
||
|
||
```bash
|
||
grep LOOP_OVERRUN web/logs/*/events.jsonl
|
||
grep SAFETY web/logs/*/events.jsonl
|
||
grep GUARD web/logs/*/events.jsonl
|
||
```
|
||
|
||
## 9. 当前不建议改动的内容
|
||
|
||
- 16 个电机映射、方向、零位。
|
||
- 策略 53D 观测顺序和缩放。
|
||
- 16D 动作顺序和 action scale。
|
||
- 默认 `50Hz` 控制频率。
|
||
- 已经真机跑通过的遥控方向配置。
|
||
|
||
这些内容只有在有新日志和明确现象时再改，避免把已验证链路打散。
|