Microduck-build-tutorial 是一个面向小型双足机器人 Microduck 的完整开源装机与运行教程，覆盖硬件 BOM、3D 打印结构件、Raspberry Pi Zero 2 W 部署代码、Dynamixel XL330 舵机控制、BNO08x IMU 读取、ONNX 强化学习行走策略加载，以及基于 MuJoCo/MjLab 的训练环境。仓库更偏“可复现机器人项目”而不是单纯 Python 库，适合希望从零组装并运行 RL 双足机器人的开发者、机器人爱好者和教学团队。
适用领域
机器人 / 双足机器人 / 强化学习 / 嵌入式 Linux / 树莓派 / 舵机控制 / 仿真到现实 Sim2Real / MuJoCo 仿真 / ONNX 模型部署 / 3D 打印硬件
配置难度
高。对于熟悉 Linux、Python、树莓派、3D 打印和基础电路的开发者，按教程复现具有可操作性；但对于纯软件开发者，需要同时掌握硬件采购、机械装配、舵机参数配置、电源接线、IMU 姿态、SSH 调试和机器人安全测试。若进一步训练自己的行走模型，还需要强化学习和 MuJoCo/MjLab 经验。
商业价值
该项目的商业价值主要体现在教育、科研原型和机器人开发验证平台。它可作为双足机器人、强化学习控制、Sim2Real、嵌入式部署和舵机总线控制的教学套件或实验平台，也适合作为小型机器人产品概念验证的开源基础。由于 MIT 许可证较宽松，企业或团队可以在其基础上做课程、套件、演示机器人或二次开发。但作为商业产品仍需解决硬件供应链、装配一致性、稳定性、安全认证、售后维护和模型鲁棒性问题。
01
技术亮点
- README 提供中英文双语教程，中文开发者上手成本较低。
- 覆盖从 BOM、接线、刷镜像、Wi-Fi、SSH、运行模型、手柄控制到故障排查的完整流程。
- 提供预构建 microduck.img.xz，降低 Raspberry Pi 环境配置和依赖安装难度。
- 项目不仅有实机部署代码，还包含基于 MuJoCo/MjLab 的强化学习训练环境，可形成训练到部署的闭环。
- 使用 ONNX 格式部署行走策略，便于替换模型和做推理优化。
- 支持键盘控制和蓝牙手柄无头模式，适合没有显示器的机器人实机运行。
- 硬件选型相对明确，舵机 ID、接线、电源和 IMU 配置说明详细。
- 提供常用 Makefile 命令，如 sync、setup、run、stop、shutdown、imu、voltage，方便日常开发迭代。
- MIT 许可证，便于学习、修改和二次开发。
- 仓库已有 517 stars 和 134 forks，说明有一定社区关注度。
02
目标用户
- 希望自制小型双足机器人的开发者和创客
- 学习机器人控制、舵机总线、IMU 姿态读取的嵌入式开发者
- 研究强化学习行走策略部署的学生和研究人员
- 想做机器人教学、演示或课程项目的高校/实验室/创客空间
- 熟悉 Raspberry Pi、Python、Linux、3D 打印和基础电路的硬件爱好者
03
配置要求
- 硬件需要 Raspberry Pi Zero 2 W，且 Wi-Fi 只能使用 2.4GHz 网络。
- 需要 ROBOTIS OpenRB-150 作为 Dynamixel 舵机控制板，通常通过 USB 被识别为 /dev/serial/by-id/usb-ROBOTIS_OpenRB-150_*。
- 舵机需要使用 Dynamixel XL330-M288-T，当前行走代码依赖 14 个舵机，ID 1 到 14 必须与 README 中的关节映射一致。
- Dynamixel 推荐配置为 Protocol 2.0、Baud Rate 1Mbps、Return Delay Time 0、PWM Slope 255，并注意 Shutdown 选项避免电压波动误停。
- IMU 需要 BNO080/BNO085/BNO086 模块，通过 I2C bus 1 连接，安装方向需与 IMU_MOUNT_QUAT 配置和当前 walk.onnx 模型匹配。
- 电源侧需要 6V 可充电电池给舵机/OpenRB-150 供电，Raspberry Pi 需要稳定 5V 供电，两侧需要共地。
- 软件镜像内置 Raspberry Pi OS Lite 64-bit、用户 user、部署目录 ~/microduck、虚拟环境 .venv、walk.onnx 和 microduck-gamepad.service。
- 如重新训练模型，需要将导出的 ONNX 文件放到 microduck/src/agents/walk.onnx 并同步到 Pi。
- 开发机使用 Makefile 命令时，需要能通过网络 SSH 到 microduck.local 或目标 IP。
04
适用场景
- 按教程采购硬件并组装一台 Microduck 小型双足机器人
- 在 Raspberry Pi Zero 2 W 上部署预构建镜像并直接运行 walk.onnx 行走模型
- 通过 SSH、键盘或蓝牙手柄控制机器人行走、转向和停止
- 基于 mjlab_microduck 在 MuJoCo/MjLab 中训练新的强化学习行走策略并导出 ONNX
- 作为机器人控制、强化学习、Sim2Real 和嵌入式部署课程的实验平台
- 研究 Dynamixel XL330 舵机总线、多关节机器人 ID 映射、IMU 安装方向和实时控制循环
05
部署与配置
- 准备硬件：Raspberry Pi Zero 2 W、ROBOTIS OpenRB-150、14 个 Dynamixel XL330-M288-T 舵机、BNO080/BNO085/BNO086 IMU、6V 可充电电池、microSD 卡、3D 打印件和线材。
- 打印并组装 microduck/cad/ 中的结构件，按 README 中的舵机 ID 表为每个 Dynamixel 舵机设置 ID、Protocol 2.0、1Mbps 波特率等参数。
- 按电源、舵机总线和 IMU 接线图连接：Pi 通过 USB 连接 OpenRB-150，舵机使用 6V 电源，Pi 使用稳定 5V 供电，IMU 通过 I2C 连接 GPIO2/GPIO3。
- 从 GitHub Release 下载 microduck.img.xz，并建议使用 sha256sum 校验镜像完整性。
- 使用 Raspberry Pi Imager 选择 Raspberry Pi Zero 2 W 和自定义镜像 microduck.img.xz，将镜像刷写到 16GB 或更大的 microSD 卡。
- 配置 Wi-Fi：可在 bootfs/network-config 中填写 2.4GHz Wi-Fi 的 SSID、密码和国家代码，或首次接 HDMI/键盘后用 nmcli 配置。
- 插入 SD 卡并首次启动，等待 1 到 3 分钟完成分区扩展、SSH host key 生成、Wi-Fi 连接和后台手柄服务启动。
- 通过 ssh user@microduck.local 登录，默认密码为 password，首次登录后建议立即执行 passwd 修改密码。
- 进入 ~/microduck，执行 PYTHONPATH=src .venv/bin/python src/main.py 启动控制程序。
- 首次运行务必扶住机器人，通过键盘 v 开关行走、方向键控制移动、q 停止，或配对蓝牙手柄后使用无头手柄模式控制。
06
风险与注意事项
- 这是硬件项目，成功复现依赖采购、3D 打印精度、装配质量、接线、电源稳定性和舵机参数，难度明显高于纯软件项目。
- 机器人首次运行存在摔倒、舵机过载、夹手、短路或电池问题等安全风险，必须扶持测试并远离桌边。
- 默认镜像用户为 user、密码为 password，如果不及时修改，连接网络后存在安全隐患。
- 手柄连接后服务会关闭 Wi-Fi 以改善蓝牙稳定性，可能导致 SSH 中断，对调试流程有影响。
- 行走策略 walk.onnx 与当前硬件结构、IMU 安装方向、舵机 offset 强相关，装配偏差可能导致机器人无法稳定行走。
- Raspberry Pi Zero 2 W 算力、内存和无线稳定性有限，复杂模型或高频调试可能受限。
- BOM 成本不低，14 个 Dynamixel XL330 舵机加 OpenRB-150、Pi、IMU 和结构件会形成较高入门成本。
- README 中提到应校验 SHA256，但实际校验值需要在 Release 或说明中确认，若发布信息不完整会影响镜像可信度。
- 强化学习训练部分可能需要额外理解 MuJoCo/MjLab、仿真环境、奖励函数和 ONNX 导出流程，对初学者不友好。
- 硬件电源和共地处理不当可能损坏 Raspberry Pi、OpenRB-150 或舵机。
2026-09-10
第19名
新收录 · github_search
