AI-FanGe / Microduck-build-tutorial

# Microduck
Microduck 是一个小型双足机器人项目，包含两部分：
- `microduck/`: Raspberry Pi Zero 2 W 上运行的部署代码，负责读取 IMU、读取手柄/键盘输入、驱动 Dynamixel 舵机，并加载 ONNX 行走策略。
- `mjlab_microduck/`: 基于 MuJoCo/MjLab 的强化学习训练环境，用来训练并导出 `walk.onnx`。
本 README 面向装机和第一次运行：准备硬件、接线、刷写 `microduck.img.xz`、初始化 Wi-Fi、SSH 登录、运行模型，以及后续更新代码。3D打印的文件在项目中。
视频教程：https://www.youtube.com/watch?v=Vep8AjoCnEM
## 致谢
感谢开源项目 microban 和 microduck。本项目的机械结构、部署思路、仿真训练和实机行走流程都受益于这些开源工作。
## 项目状态
当前发布镜像已经内置：
- Raspberry Pi OS Lite 64-bit。
- 主机名 `microduck`。
- 默认用户 `user`。
- 部署目录 `~/microduck`。
- Python 虚拟环境 `~/microduck/.venv`。
- 行走模型 `~/microduck/src/agents/walk.onnx`。
- 无头手柄服务 `microduck-gamepad.service`，可开机后用手柄启动模型。
当前预构建镜像：
- microduck.img.xz
## BOM
下面是组装一台 Microduck 的主要物料。价格会随地区、采购渠道和批量变化，仅用于估算。
| 类别 | 物料 | 数量 | 说明 |
| :--- | :--- | :---: | :--- |
| 控制板 | Raspberry Pi Zero 2 W | 1 | 运行控制程序、蓝牙手柄、Wi-Fi 和 SSH。 |
| 舵机控制板 | ROBOTIS OpenRB-150 | 1 | 通过 USB 连接 Raspberry Pi，负责和 XL330 舵机总线通信。代码会优先自动查找 `/dev/serial/by-id/usb-ROBOTIS_OpenRB-150_*`。 |
| 舵机 | Dynamixel XL330-M288-T | 14 | 当前行走代码使用 14 个舵机：双腿 10 个，头/颈 4 个。若安装嘴部舵机，可使用 ID 15，但当前行走模型不依赖它。 |
| 电池 | 成品 6V 可充电电池 | 1 | 当前硬件直接使用成品 6V 电池包供电，不使用两节 18650 自制电池组。请确认电池能提供足够瞬时电流。 |
| 开关 | 电源开关 | 1 | 控制机器人主电源。 |
| 存储 | 16GB 或更大 microSD 卡 | 1 | 推荐使用质量稳定的新卡。镜像刷写后首次启动会自动扩展分区。 |
| IMU | BNO080/BNO085/BNO086 模块 | 1 | 通过 I2C 读取姿态，代码会自动探测常见地址。 |
| 结构件 | 3D 打印件 | 1 套 | 使用 `microduck/cad/` 中的模型打印。推荐 PLA。 |
| 螺丝 | M2/M2.5 自攻螺丝 | 若干 | 舵机固定、舵盘固定、结构件连接。建议多备。 |
| 线材 | Dynamixel 3-pin 线| 若干 | 舵机串联、电源连接、分线。 |
## 舵机 ID
控制代码期望的 ID 映射如下。烧录镜像之前或第一次运行之前，应先用 Dynamixel Wizard 设置好每个舵机。
| ID | 名称 | 位置 |
| :---: | :--- | :--- |
| 1 | `right_ankle` | 右踝 |
| 2 | `right_knee` | 右膝 |
| 3 | `right_hip_pitch` | 右髋俯仰 |
| 4 | `right_hip_roll` | 右髋横滚 |
| 5 | `right_hip_yaw` | 右髋偏航 |
| 6 | `left_ankle` | 左踝 |
| 7 | `left_knee` | 左膝 |
| 8 | `left_hip_pitch` | 左髋俯仰 |
| 9 | `left_hip_roll` | 左髋横滚 |
| 10 | `left_hip_yaw` | 左髋偏航 |
| 11 | `head_pitch` | 头部俯仰 |
| 12 | `neck_pitch` | 颈部俯仰 |
| 13 | `head_yaw` | 头部偏航 |
| 14 | `head_roll` | 头部横滚 |
| 15 | `mouth` | 可选嘴部舵机，当前行走策略不使用 |
Dynamixel Wizard 推荐参数：
- Protocol: `2.0`
- Baud Rate: `1Mbps`
- Return Delay Time: `0`
- PWM Slope: `255`
- Shutdown: 去掉输入电压错误触发项，避免电池电压波动时误停
## 接线图
### 电源接线
电源链路如下：
 [code] 
检查要点：
- 上电前用万用表确认正负极。
- 当前硬件使用成品 6V 可充电电池，不需要自制 2S 电池组、BMS 和 2S 充电板。
- OpenRB-150 负责 XL330 舵机通信，Raspberry Pi 通过 USB 连接 OpenRB-150。
- Raspberry Pi 需要稳定 5V 供电；舵机/OpenRB-150 使用 6V 电池侧供电。两侧必须共地，具体以你的电源模块和 OpenRB-150 接法为准。
- 焊点需要热缩管或热熔胶绝缘，避免短路。
### 舵机总线
XL330 使用 3-pin 串联总线。OpenRB-150 接出后可通过分线分到左右腿和头部。
 [code] 
注意：
- 舵机顺序可以按结构方便布线，但 ID 必须和上表一致。
- 如果总线上有通信错误，优先检查 OpenRB-150 是否枚举成功、电池电压、GND、线序和舵机 ID。
- 正常情况下代码会自动选择 OpenRB-150 的 USB 串口；如果没有找到，会回退到 `/dev/ttyACM0`、`/dev/serial0`、`/dev/ttyAMA0` 或 `/dev/ttyS0`。
### IMU 接线
BNO08x 模块走 I2C：
| IMU 引脚 | Raspberry Pi / Hat |
| :--- | :--- |
| `VIN` / `3V3` | 3.3V，按模块标识选择 |
| `GND` | GND |
| `SDA` | GPIO2 / I2C SDA |
| `SCL` | GPIO3 / I2C SCL |
软件默认使用 I2C bus `1`，会自动寻找 BNO08x 常见地址。安装方向由 `IMU_MOUNT_QUAT` 配置，已经和当前行走模型匹配。
## 使用 `microduck.img.x