# motion_math_learn_project

**Repository Path**: caixiaoliang/motion_math_learn_project

## Basic Information

- **Project Name**: motion_math_learn_project
- **Description**: 算法训练，嵌入式，运控算法，
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-08
- **Last Updated**: 2026-03-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 人形机器人训练到 RK3588 IGH 部署骨架工程

本仓库用于整理一条从强化学习训练、策略导出，到 RK3588 + IGH EtherCAT 主站部署的人形机器人控制链路。

当前状态更准确地说是“工程骨架 + 接口规范 + 部分部署代码”，而不是已经完全打通的单仓闭环。仓库内已有训练入口、导出脚本、部署线程模型、配置规范和安全文档，但训练 runner、真实策略导出绑定、RK3588 端 ONNX Runtime 推理仍有占位实现。

## 当前完成度

| 模块 | 当前状态 | 说明 |
| --- | --- | --- |
| 配置规范 | 可用 | `config/` 中已有 12 轴、31 轴配置与 joint order 说明 |
| 训练入口 | 骨架 | `training/train.py` 当前只做配置读取、维度推导和目录准备 |
| Play / Export 入口 | 骨架 | `training/play_export.py` 目前以说明和占位逻辑为主 |
| ONNX 导出 | 原型 | `export/export_onnx.py` 可导出占位 MLP，不保证与真实训练 actor 完全一致 |
| ONNX 校验 | 基础检查 | `export/sim2sim_verify.py` 当前主要做 shape smoke test |
| RK3588 部署线程 | 已有骨架 | `rk3588_deploy/` 已包含 50 Hz 推理线程 + 1 kHz EtherCAT 线程 |
| RK3588 真实推理 | 未完成 | `policy_inference_run.c` 的 `USE_ONNXRUNTIME` 分支仍是 TODO |
| 安全文档 | 已有说明 | `docs/safety_rt_31axis.md` 提供实机 bring-up 安全约束 |

## 仓库结构

```text
motion_math_learn_project/
|-- README.md
|-- requirements.txt
|-- config/
|   |-- humanoid_12dof.yaml
|   |-- humanoid_31dof.yaml
|   `-- pdo_obs_action_spec.md
|-- training/
|   |-- envs/
|   |-- train.py
|   `-- play_export.py
|-- export/
|   |-- export_onnx.py
|   `-- sim2sim_verify.py
|-- rk3588_deploy/
|   |-- README.md
|   |-- CMakeLists.txt
|   |-- main.c
|   |-- policy_inference_50hz.c
|   |-- policy_inference_run.c
|   `-- ethercat_1khz_thread.c
`-- docs/
    |-- reproducibility_quickstart.md
    |-- bringup_checklist.md
    `-- safety_rt_31axis.md
```

## 先看什么

如果你是第一次接手这个仓库，建议按下面顺序阅读和验证：

1. 阅读 `README.md`，判断当前仓库的能力边界和外部依赖。
2. 阅读 `docs/reproducibility_quickstart.md`，先搭最小环境，再决定是走训练链路还是部署链路。
3. 阅读 `config/pdo_obs_action_spec.md`，确认 joint order、obs/action 维度、PDO 布局。
4. 如果要接实机部署，再看 `rk3588_deploy/README.md` 与 `docs/bringup_checklist.md`。
5. 实机前必须阅读 `docs/safety_rt_31axis.md`。

## 本仓库包含什么

- 12 轴和 31 轴的人形配置样例。
- 训练、导出、验证、RK3588 部署的脚本和代码骨架。
- EtherCAT 1 kHz 控制线程与 50 Hz 策略线程的基本拆分。
- 安全 bring-up 文档与 PDO / 观测 / 动作规范说明。

## 本仓库不包含什么

以下内容当前不保证在仓内直接提供或直接可跑通：

- 完整的 `rsl_rl` 训练 runner 与环境实现。
- 仓内可直接使用的 URDF、ESI、虚拟从站工程和 RK3588 交叉编译工具链文件。
- 已完成的 RK3588 端 ONNX Runtime 推理实现。
- 经过数值一致性校验的真实训练 actor 导出链路。

## 外部依赖

当前文档和代码会引用到一些仓外资源。首次使用前，请先确认这些资源是否已准备：

| 依赖项 | 是否在本仓库内 | 用途 |
| --- | --- | --- |
| Python 运行环境 | 否 | 训练脚本、导出脚本、验证脚本 |
| `rsl_rl` | 否 | 真实 PPO 训练 |
| `motion_ethercat_sim` 或等价虚拟从站工程 | 否 | Sim2Sim / 主站联调 |
| IGH EtherCAT 安装产物 | 否 | RK3588 主站编译与运行 |
| `toolchain_rk3588.cmake` | 否 | 交叉编译 RK3588 |
| URDF / ESI / 实机映射文件 | 否 | 对齐 joint order、PDO、从站地址 |

安装与依赖分层见 `docs/reproducibility_quickstart.md`。

## 推荐验证路径

### 1. 最小文档核对

先不运行任何代码，只核对以下三件事：

- 你要使用 12 轴还是 31 轴配置。
- 你的 PDO 字节布局是 `20/12` 还是 `23/17`。
- 你是否具备外部 URDF、ESI、IGH 和工具链文件。

### 2. Python 环境准备

```bash
pip install -r requirements.txt
pip install git+https://github.com/leggedrobotics/rsl_rl.git
```

注意：`rsl_rl` 不是 `requirements.txt` 中的硬依赖，而是训练闭环所需的额外安装项。

### 3. 训练骨架验证

```bash
python training/train.py --config config/humanoid_12dof.yaml
python training/train.py --config config/humanoid_31dof.yaml
```

当前预期结果：

- 成功读取 YAML 配置。
- 打印 `obs_dim`、`action_dim`、`policy_freq`。
- 在日志目录下写出 `config.yaml`。

当前不应期待：

- 直接开始 PPO 训练。
- 直接产出真实策略 checkpoint。

### 4. 导出和基础校验

```bash
python export/export_onnx.py --checkpoint runs/xxx/policy.pt --config config/humanoid_31dof.yaml --output policy.onnx
python export/sim2sim_verify.py --onnx policy.onnx --config config/humanoid_31dof.yaml
```

当前预期结果：

- 生成 ONNX 文件或 stub 说明文件。
- 使用随机观测检查 ONNX 输入输出形状与配置是否匹配。

当前不应期待：

- 自动证明导出的 ONNX 与真实训练 actor 数值一致。
- 自动完成 MuJoCo 闭环 Sim2Sim。

### 5. RK3588 编译准备

在进入板端部署前，先确认：

- 已安装 IGH 并能提供 `ethercat` 库。
- 已准备 `toolchain_rk3588.cmake`。
- 明确当前 `policy_inference_run.c` 默认是零输出 stub。

部署细节见 `rk3588_deploy/README.md` 和 `docs/bringup_checklist.md`。

## 已知限制

- `training/envs/` 目前没有完整环境实现，训练链路仍是骨架。
- `training/play_export.py` 目前主要是入口说明，不会自动完成 rollout 和真实导出。
- `export/export_onnx.py` 当前构建的是占位 `ActorMLP`，而不是和训练阶段严格绑定的真实 actor 结构。
- `export/sim2sim_verify.py` 当前更接近 ONNX smoke test，而不是完整 Sim2Sim。
- `rk3588_deploy/policy_inference_run.c` 的 ONNX Runtime 推理尚未实现，未启用时默认输出全零动作。
- `config/humanoid_31dof.yaml` 与 `rk3588_deploy/pdo_types.h` 当前存在 `23/17` 和 `20/12` 两种 PDO 版本并存的风险，部署前必须和 ESI / 从站实现核对。

## 相关文档

- `docs/reproducibility_quickstart.md`：环境准备、外部依赖、最小可复现路径。
- `docs/bringup_checklist.md`：导出验证和 RK3588 bring-up 前检查表。
- `config/pdo_obs_action_spec.md`：joint order、obs/action 维度、PDO 布局规范。
- `rk3588_deploy/README.md`：RK3588 构建、运行、ONNX Runtime 接入说明。
- `docs/safety_rt_31axis.md`：实机 bring-up 与安全注意事项。