dm10

一台 10 自由度双足人形下肢 —— 从零到走起来。 训练 → 部署 → 上机的完整流程，以及过程中的实测记录与教训。

---

这是什么

一台双足机器人的完整工程记录。本体是 3D 打印的达妙下肢 + RDK X5 主控， 用强化学习（UniLab + MuJoCo + PPO）训练行走策略，部署到 roboparty 框架上跑。

已跑通：电机通信、零点标定、方向校准、IMU 集成、PD 站立保底、安全降级链、 观测录制与回放。待完成：用实测质量 + 真实执行器模型训出一版能跑的 checkpoint。

硬件

本体    10 DoF：两腿各 5 关节（髋P / 髋R / 髋Y / 膝 / 踝）
电机    10× 达妙 DM-J4340-2EC（24V，减速比 40）
质量    6.12 kg（12 个 body 全部实测）
主控    RDK X5（aarch64，Ubuntu 22.04）
总线    2× CAN FD（can0 左腿 / can1 右腿），USB2FDCAN Dual 适配器
IMU     DM-IMU-L1，串口 921600

结构

dm10/
├── dm10.contract.yaml   ⭐ 契约 —— 跨仓库共享的数字，唯一来源
├── docs/                    硬件清单 / 流程 / 实测记录
├── scripts/                 校验与入口脚本
└── modules/                 ← 三个模块，各自独立仓库
    ├── UniLab               训练（fork of Motphys/UniLab）
    ├── roboparty_deploy     部署框架（fork of Roboparty/roboparty_deploy）
    └── robot-deploy-toolkit 流程与工具链

为什么是 submodule 而不是拷贝

modules/ 下的三个仓各自独立，本仓只用指针钉住版本。

拷贝（vendor）会让同一份代码存在两处 ⇒ 必然漂移 —— 这个项目已经因此踩过坑 （参考系在两个仓里不一致、rsync 覆盖事故）。submodule 只能"指向"不能"改写"， 结构上就不可能漂。

⇒ git submodule status 就是本项目的版本锁。

流程

① 训练      cd modules/UniLab && ./train_safe.sh --algo ppo --task dm10_joystick_flat --sim mujoco
② 契约预检   scripts/preflight.sh          ← 训前 15 秒，防止训完才发现真机给不出某个观测
③ 导出      policy.onnx → modules/roboparty_deploy/src/inference/robots/dm10/models/
④ 上板      modules/roboparty_deploy 走 git pull，不用 rsync
⑤ 上机      吊架 → 手扶 → 半速 → 全速
⑥ 记录      结果回流到 modules/robot-deploy-toolkit/results/

⚠️ 上机前必读

1. 任何悬空标零或步态推理，必须在承重吊架下进行
2. 物理急停开关要够得着 —— 软件失控时拍它
3. scripts/preflight.sh 必须通过（它会查契约一致性）

契约 —— 本项目的核心

dm10.contract.yaml 里放的是跨仓库、单边改不报错的那些数字：

组	为什么危险
frame.joint_default_angle	必须等于 sim 的 home keyframe。单边改 ⇒ 策略整体平移 ⇒ 发散，启动时不报错
observation.layout	部署侧只校验总维度不校验顺序。39 维对 39 维照样通过，但语义全错
action.alpha	策略在 α=1.0 下训的，部署用 0.8 —— 已知的行为偏离
hardware.motor_id	按策略关节顺序索引。写反 ⇒ 髋角当踝角用，不报错

scripts/ 下的校验器读这个文件，去各仓库比对实际的副本。不一致就报错。

相关仓库

仓库	内容
Tszoom/dm10	本仓 —— 契约 / 文档 / 校验脚本
Tensor-0/UniLab	训练框架 + dm10 资产（dm10 分支）
Tensor-0/roboparty_deploy	部署框架（dm10 分支，含 3 个 submodule fork）
Tensor-0/robot-deploy-toolkit	流程文档 + 实测工具
Tensor-0/rdk-x5-config	板子的 CAN/udev 系统配置

许可

本仓内容为原创整理。modules/ 下的各仓遵循其各自许可（UniLab 为 Apache-2.0， roboparty 系列为 GPL-3.0）。