Upkie 开源轮式双足机器人 复刻全流程
Upkie 开源轮式双足机器人 从采购、打印、组装到装软件、标定和训练的 175 个步骤,附物料表、购买链接与官方出处。
作者在 FOSDEM 2026 讲座摘要中称用现成零件约 3,000 美元即可造一台;为作者估算,BOM 页不列单价,3D 打印机、工具与运费是否计入未说明。无官方套件出售
物料 · Bill of materials {#bill-of-materials}
| 零件 | 数量 |
|---|---|
| 3D printer · FDM 3D printer such as a Prusa i3 MK3S+ · your preference | 1 |
| Battery · RYOBI 18V compatible battery · online retail [1] | 1 |
| Battery spring · Battery contact spring · Digi-Key | 2 |
| DC fan · DC FAN 24V 1.8W 60x60x15mm · online retail [1] | 1 |
| Heat shrink · Heat shrink tubing, 3:1 ratio, standard sizes · online retail | 2 m |
| Heat shrink large · Heat shrink tubing, 2:1 ratio, 19 mm diameter · online retail | 1 m |
| Hex spacer · M2x12 + 3 male hex spacer · comes with pi3hat | 4 |
| Hex wrench · 17 mm RC Hex Wrench · 3D print | 1 |
| JST connector · JST PH-3 2.0 mm 3 pin connector, see cables · come with mjbots products | 14 |
| Leg power cable · Female-female power cable, length 400 mm · see cables | 4 |
| M2.5 inserts · M2.5x4x4 heat set inserts, M2.5, OD 4 mm, length 4 mm · online retail | 8 |
| M2.5 screws · M2x8 socket head screws, M2.5, length 8 mm · online retail | 10 |
| M2.5x4 screws · M2.5x4 screws, M2.5, length 4 mm · comes with pi3hat | 4 |
| M2.5x6 screws · M2.5 screws, M2.5, length 6 mm · online retail | 4 |
| M2.5x8 screws · M2.5x8 screws, M2.5, length 8 mm · online retail | 10 |
| M3 inserts · M3x5x4 heat set inserts, M3, OD 5mm, length 4 mm · online retail | 100 |
| M3x10 screws · M3x10 socket head screws, M3, length 10 mm · online retail | 12 |
| M3x12 screws · M3x12 socket head screws, M3, length 12 mm · online retail | 22 |
| M3x8 screws · M3x8 socket head screws, M3, length 8 mm · online retail | 50 |
| Micro HDMI cable · Any micro HDMI cable that works with your monitor · online retail [1] | 1 |
| MicroSD card · microSDXC card, U3, V30, A2 · online retail | 1 |
| Pi3hat · mjbots pi3hat, r4.4b+ · mjbots | 1 |
| Power dist · mjbots power dist, r4.3b+ · mjbots | 1 |
| Qdd100 · mjbots qdd100 servo, beta 2+ · mjbots | 4 |
| Raspi · Raspberry Pi 4 Model B · see raspberrypi.com | 1 |
| Raspi heat sink · Aluminum Heatsink, for rpi 4b+ · online retail | 1 |
| Terminator · Resistor, 120 Ω, see this note · online retail | 2 |
| Torso power cable · Male-female power cable, length: 30 cm · see cables | 3 |
| USB gamepad · USB gaming controller (or Bluetooth: instructions) · online retail [1] | 1 |
| Wheel · RC 1:8 rubber tyre, see RC wheels · online retail | 2 |
| Wheel actuator · moteus developer kit, r4.11+ · mjbots | 2 |
| Wheel hex coupler · 17 mm Wheel Hex Coupler · online retail [1] | 2 |
| XT-30 connector · XT30 connector, see cables · come with mjbots products | 20 |
| XT-90S connector · XT90-S connector · online retail [1] | 1 |
物料 · Optional components {#optional-components}
| 零件 | 数量 |
|---|---|
| RTC module · DS3231 Chip · online retail | 1 |
采购
- 获取 3D 打印机
从链接的物料清单中获取 3D 打印机。
- 获取电源线
从链接的线缆页面获取电源线。
- 获取螺丝刀
从链接的物料清单中获取螺丝刀。
- 按指定尺寸选择 RC 车轮
选择外径 112 mm、内径 80 mm、轮驱动六角尺寸 17 mm、轴孔直径 12 mm 的 RC 车轮。外径是软件默认值。
- 购买匹配的六角联轴器
如果选择不同的轮驱动六角尺寸或轴孔直径,请购买匹配的六角联轴器。
- 选择符合尺寸的 RC 车轮
车轮外径为 112 mm、内径为 80 mm、轮驱动六角孔为 17 mm、轴孔直径为 12 mm。
- 购买匹配的六角联轴器
如果选择了不同的轮驱动六角孔或轴孔直径,请购买匹配的六角联轴器。
- 订购物料清单中的零件
先订购物料清单中列出的零件,因为配送需要一些时间。
打印与加工
- 获取每个零件的 3MF 文件
使用 upkie_parts 仓库中为每个零件提供的 3MF 文件。这些文件包含速度、填充率、层高等打印配置。
- 在其他打印机上导入 STL 文件
如果使用 Prusa i3 MK3S+ 以外的 3D 打印机,请从 upkie_parts 导入 STL 网格文件并应用文中给出的打印设置。
- 使用适当设置切片所有零件
使用适当的设置对每个零件进行切片。零件设计为使用 PETG、0.2 mm 层高和 15% 至 30% 的填充率;轮毂在六角联轴器连接器处有明确的填充修改器。
- 打印后盖
打印前一步切片的 1× 后盖。
- 打印背板
打印前一步切片的 1× 背板。
- 打印电池插头
打印前一步切片的 1× 电池插头。
- 打印电池螺柱
打印前一步切片的 1× 电池螺柱。
- 打印底板
打印前一步切片的 1× 底板。
- 打印面板
打印前一步切片的 1× 面板。
- 打印头板
打印前一步切片的 1× 头板。
- 打印侧板
打印前一步切片的 2× 侧板。
- 打印底部加强件
打印前一步切片的 1× 底部加强件。
- 打印顶部加强件
打印前一步切片的 1× 顶部加强件。
- 打印踝关节
打印前一步切片的 2× 踝关节。
- 打印大腿
打印前一步切片的 2× 大腿。
- 打印horn零件
打印前一步切片的 4× horn 零件。
- 打印膝关节
打印前一步切片的 2× 膝关节。
- 打印小腿
打印前一步切片的 2× 小腿。
- 打印轮毂
打印前一步切片的 2× 轮毂。轮毂在六角联轴器连接器处有明确的填充修改器。
- 可选打印把手
可选从指定链接3D打印把手;这一步也可在之后的任何阶段完成。
- 打印并调整轮毂配合
打印更新后的轮毂并装入车轮测试,使其紧密配合。这通常需要几次迭代才能完成。
- 打印并安装提手
可选择 3D 打印提手,并使用四个 M3x8 螺钉将其固定到头部板;此操作可稍后完成。
- 更新并打印轮毂
若更改内径、轮驱动六角孔或轴孔直径,需要相应更新3D打印的轮毂。轮毂通常需要经过几次迭代才能与车轮紧密配合。
组装
- 安装 Raspberry Pi
使用四个 M2 间隔柱将 Raspberry Pi 安装到板子上,USB 端口应朝向印有“USB”文字的一侧。
- 安装 pi3hat
使用 pi3hat 随附的四个 M2 螺钉,将其安装在 Pi 顶部。
- 安装头部组件
将头部安装到左右两块板上,使 USB 一侧朝向机器人右侧;眼睛朝前,电池朝后。
- 安装电源分配板
使用四个 M2.5x6 螺钉,将电源分配板固定到臀部板上。
- 安装电池连接器
使用六个 M3x8 螺钉,将电池连接器固定到面板上。
- 定位电池连接器
电池连接器的尖端应指向机器人左侧,因此连接器相对面板略向左偏置。
- 以面板确定方向
以面板为基准辨认机器人的左、右、前、后方向。
- 连接面板与臀板
使用 M3x8 螺钉将面板拧接到臀板上。
- 设置电源分配板方向
确认电源分配板的 XT90 一侧位于机器人左侧。
- 安装左右侧板
使用 M3x8 螺钉将左板和右板分别固定到面板与臀板上。
- 安装头部面板
将头部面板拧接到面板、左板和右板上。
- 设置头部面板 USB 侧
确认头部面板的 USB 一侧位于机器人左侧。
- 设置头部面板 XT30 侧
确认头部面板的 XT30 一侧位于机器人右侧。
- 保持头部面板正确朝向
该朝向适配电缆长度,IMU 也安装在头部面板上。
- 安装两个加强件
使用 M3x8 螺钉将两个加强件固定到前板上。
- 暂不安装内部盖板
此时先不安装内部盖板。
- 安装两个内部盖板
使用十枚 M2.5 螺钉安装两个内部盖板。
- 连接电池
将电池插入连接器,连接时应发出清晰的咔嗒声。
- 保持电机与支架组装
组装每只脚踝时,不要从支架上拆下 mj5208 或 moteus。
- 选择三个外部螺孔
使用呈三角形排列的三个外部螺孔,不要使用中心对面的两个内部螺孔。
- 使用 M3x8 螺钉
脚踝组装使用 M3x8 螺钉。
- 确保 PCB 位于内部
确认 PCB 能够安装在支架内部。
- 必要时切削螺纹
如果 3D 打印塑料阻挡螺孔,可能需要切削出螺纹。
- 清除孔内多余塑料
如果孔内有太多 3D 打印塑料,使用较小的螺丝刀清除阻塞塑料。
- 用螺钉切削螺纹
随后用螺钉切削螺纹,可能需要施加一定力量。
- 对齐电机与轮毂
必要时反复拧下和拧紧螺钉,使电机与轮毂间隙最小,并对齐每颗螺钉。
- 插入锁定销
将销钉插入小孔,锁定电机和轮毂。
- 对齐六角联轴器
小心对齐联轴器的六角形与轮辋内部的六角孔。
- 确认轮毂完全进入轮胎
两者对齐后会发出咔嗒声,轮毂会完全进入轮胎。
- 锁定轮胎六角联轴器
使用 17 mm 内六角扳手拧紧轮胎六角联轴器的最后部分,将轮胎锁定到轮毂。
- 准备线缆热缩管
每套线缆准备两段约3–4厘米的热缩管,放在线缆末端、连接器前数厘米处并加热。不要加热线缆护套,以免其熔化。
- 固定每套线缆的一端
在每套线缆的一端贴上可移除胶带。
- 将胫骨固定到踝部
用中间的孔将胫骨螺接到踝部。
- 制作线缆尖鼻端
用可移除胶带将连接器与热缩管部分绑在一起,形成便于插入线缆的尖鼻状。
- 连接胫骨与轮电机
将胫骨上的连接器接到轮子的电机上,并使用七枚M3x12或M3x10螺钉;不要使用M3x8。
- 将股骨装入T形部件
将股骨及其线缆插入T形部件内部。
- 连接股骨与电机
将股骨上的连接器接到电机,并留出一些余量,使电机能够转动。使用电机上的三个小孔,不要使用三个较大的孔。
- 安装圆角轮毂
将圆角轮毂安装到电机另一侧,再把两个部件螺接在一起。
- 连接电机数据与电源线
先连接数据线,再连接电源线到电机。
- 标记通信线缆
在一根通信线缆上添加“JC1”标签,在另一根通信线缆上添加“JC3”标签。
软件与固件
- 安装 Upkie Python 库
通过 pip 从 PyPI 安装 `upkie` Python 库。
- 创建 PyBullet 摆锤环境
使用 `Upkie-PyBullet-Pendulum` 环境并将频率设为 `200.0`。
- 将环境切换到真实机器人
在环境名称中将 `"PyBullet"` 替换为 `"Spine"`,即可切换到真实机器人。
- 启动并登录树莓派
打开系统电源,并通过 SSH 登录树莓派。
- 配置每个舵机 ID
对每个舵机 ID X 运行 moteus_tool,将总线 1 配置为舵机 1、2、3,总线 2 配置为舵机 4、5、6。
- 更新代理配置中的车轮外径
更换外径时,只需更新代理的配置。大多数代理可以适应厘米级的外径变化。
- 克隆主代码仓库
在计算机上克隆主要的 `upkie` 仓库并进入该目录;安装软件时,将从该目录运行所有内容。
- 登录树莓派
通过SSH登录树莓派。
- 在代理配置中更新车轮外径
若更改外径,只需更新代理的配置。大多数代理可以承受车轮外径在厘米范围内的变化。
标定与测试
- 准备测试工作台
按照图示在工作台上布置并测试电子组件。
- 检查电源分配板 LED
如果连接正确,电源分配板上的红色 LED 应点亮。
- 检查 pi3hat 和电源板 LED
如果连接正确,pi3hat 和电源分配板上的红色 LED 都应点亮。
- 通过 USB 连接舵机
通过 USB 将待配置的舵机连接到电脑。
- 打开配置选项卡
在 tview 中进入配置选项卡。
- 设置舵机标识符
将 id.id 设置为所需值;这会在控制台中写入 conf set 命令。
- 用新 ID 重启 tview
关闭 tview,然后使用新的 ID 重启,例如执行 tview -t X。
- 检查配置参数列表
确认控制台显示配置参数列表;如果列表为空,则存在通信问题。
- 永久保存舵机 ID
在控制台执行 conf write,永久保存新的 ID。
- 配置指定的执行器
按照文档中的六行表配置 qdd100 和 mj25208 执行器。
- 测试舵机通信
使用 conf enumerate 命令测试与各舵机的通信。
- 测试舵机运动
依次使用 d stop 和 d pos 命令测试舵机。
- 摆正机器人底座
尽可能将机器人底座竖直,并左右晃动双腿,使其尽可能垂直。髋关节和膝关节存在一些摩擦。
- 执行硬归零
执行rezero脚本,运行硬校准程序,为所有执行器设置绝对零位。Upkie的零位配置是双腿伸直。硬归零只需执行一次,不必每次开机都运行。
- 执行软归零
后续通过upkie_tool rezero执行软归零。软归零只要求机器人大致直立,即髋关节和膝关节与真实零位的偏差不超过60度。
- 运行 PyBullet 平衡控制循环
重置环境,使用增益 `[10.0, 1.0, 0.0, 0.1]` 计算动作并循环最多 `1_000_000` 步。
- 在回合结束时重置环境
当步骤返回 `terminated` 或 `truncated` 时,重置环境。
用起来
- 运行卧姿屈膝示例
运行独立示例,让机器人在水平地面上保持卧姿并进行屈膝动作。
- 运行模型预测控制示例
运行独立示例,使用自包含的 MPC 平衡器。
- 运行 PD 平衡器示例
运行独立示例,通过对轮速进行比例-微分反馈来保持平衡。
常见问题
物料
- mjbots qdd100 执行器 ×4(beta 2 以上)驱动髋与膝,峰值力矩 16 N·m
- moteus r4.11 开发套件 ×2 驱动轮子(mj5208 电机,软件限速约 111 rad/s,力矩 1.7 N·m)
- 树莓派 4B 与散热片、mjbots pi3hat r4.4b+(板载 IMU)、mjbots power dist r4.3b+ 配电板
- RYOBI 18V 兼容电池、XT90‑S 与 XT30 接头、JST PH‑3 通信线、120 Ω 终端电阻 ×2、24V 60×60×15 mm 风扇
- 1:8 RC 橡胶轮胎 ×2(默认外径 112 mm、17 mm 六角驱动)与 17 mm 轮毂联轴器
- PETG 打印件(0.2 mm 层高,每件的 3MF 项目文件含全部切片设置)、约 100 个 M3 热熔螺母与 M2.5/M3 螺丝
- USB 手柄、microSD 卡、Micro HDMI 线;可选 DS3231 实时时钟模块
工具
- FDM 3D 打印机(作者用 Prusa i3 MK3S+)
- JST PH 压线钳(推荐 PA‑09)
- M2.5 与 M3 公制内六角螺丝刀(推荐球头)
- 焊 XT 接头的烙铁、剥线钳
技能
- 压接 JST 通信线、焊接 XT 电源线
- 树莓派系统配置与电子测试
- Python 智能体(Gymnasium API)与 C++ spine 底层控制
- 进阶:模型预测控制(ProxQP)与强化学习(Stable‑Baselines3、mjlab_upkie 需 NVIDIA GPU)
软件
- upkie Python 库 v13.1.0(PyPI、conda‑forge):Gymnasium 环境、C++ spine、状态估计与控制
- 示例:PD 平衡、MPC 平衡、躺地屈膝;PyBullet 仿真
- 强化学习:rl_zoo3_balancer(Codeberg,CPU)与 mjlab_upkie(MuJoCo Warp,需 NVIDIA GPU)
- upkie_description:URDF/Xacro 模型,可载入 Pinocchio 等框架