Microduck开源双足机器人软件部署与首次运行实战指南

双足机器人这个领域，很多人第一反应是波士顿动力那种液压怪兽，或者实验室里动辄几十万的科研平台。但真正上手过的人都知道，从零把一台双足机器人从"散件"弄到"能站起来"这一步，中间隔着的不只是钱，还有一堆让人抓狂的软件配置问题。Microduck 这个开源双足机器鸭项目，恰好卡在一个很舒服的位置——它足够小、足够便宜，但该有的东西一样不少：舵机驱动、姿态反馈、步态控制、上位机通信。我最近花了两周时间把它的软件部分从头跑通，踩了不少坑，也积累了一些文档里不会写的经验。这篇文章就围绕"软件部署与首次运行"这个环节，把从拿到代码到让小鸭站起来并回中位的完整过程拆开讲清楚。

1. 先搞清楚 Microduck 的软件架构长什么样

1.1 三层结构：上位机、主控、执行器

Microduck 的软件架构并不复杂，但如果你把它当成一个"单片机点灯"项目来对待，后面一定会出问题。它本质上是三层结构：

• 上位机层：跑在 PC 或树莓派上的控制程序，负责步态解算、逆运动学计算、以及给主控发送目标角度序列。
• 主控层：一块微控制器（常见的是 ESP32 或 STM32 系列），负责接收上位机指令、驱动舵机、读取 IMU 数据。
• 执行器层：若干个大扭矩舵机，直接决定小鸭能不能站起来。

这三层之间的通信方式决定了你部署时的复杂度。Microduck 官方仓库里通常提供两种通信方案：串口直连和无线模块。串口直连最稳，调试阶段强烈建议先用串口，别一上来就折腾无线。

1.2 为什么 Makefile 是这个项目的核心入口

很多人看到 Makefile 就头疼，觉得这是"老派 C 项目"才用的东西。但 Microduck 用 Makefile 是有道理的：它的主控固件需要针对不同硬件平台编译，Makefile 能让你用一条命令切换目标板、切换通信方式、切换调试等级。相比之下，如果你用 CMake，配置文件的层级会多一层，对于这种中小规模嵌入式项目反而累赘。

提示：Makefile 和 CMake 的区别在这里体现得很明显——Makefile 是"直接告诉编译器怎么做"，CMake 是"先生成 Makefile 再告诉编译器怎么做"。Microduck 这种项目规模，直接用 Makefile 更透明，改起来也更快。

1.3 树莓派在整套系统里扮演什么角色

热词里反复出现树莓派，这不是偶然。Microduck 的上位机程序对算力要求不高，但对"能随身携带、能接屏幕、能接摄像头"有需求。树莓派 4B 或树莓派 5 刚好满足：性能足够跑逆运动学解算，GPIO 能直接接串口，USB 口能接调试器。如果你手头只有 PC，也能跑，但移动性就差很多。

我实测下来，树莓派 4B（4GB 版本）跑 Microduck 上位机程序，CPU 占用率在 15% 到 25% 之间，完全够用。树莓派 5 当然更快，但如果你只是做基础步态调试，4B 的性价比更高。

2. 环境准备：从系统烧录到依赖装齐

2.1 树莓派系统选择与基础配置

树莓派官方系统（Raspberry Pi OS）是首选，别去折腾什么 Windows on ARM 或者非官方镜像。我见过有人想在树莓派上装 Windows XP 来跑老软件，这在 Microduck 场景下完全是自找麻烦——驱动不全、GPIO 支持差、串口权限混乱。

烧录系统后用raspi-config做几件事：

1. 开启串口：Interface Options -> Serial Port -> 登录 shell 选 No，硬件串口选 Yes。
2. 开启 I2C：如果你用的 IMU 是 I2C 接口（比如 MPU6050），这一步必须做。
3. 修改源：国内网络环境下，把 apt 源换成清华或中科大镜像，否则apt update能等到你怀疑人生。

# 备份原源列表 sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak # 替换为清华源（以 bookworm 为例） sudo sed -i 's|deb.debian.org|mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list sudo apt update

2.2 编译工具链与依赖库

Microduck 主控固件编译需要gcc-arm-none-eabi（如果是 STM32）或者 ESP-IDF（如果是 ESP32）。上位机程序需要 Python 3.9 以上，以及numpy、pyserial、matplotlib（用于可视化调试）。

# 安装基础编译工具 sudo apt install build-essential git make cmake -y # 安装 ARM 工具链（STM32 方案） sudo apt install gcc-arm-none-eabi binutils-arm-none-eabi -y # 安装 Python 依赖 pip3 install numpy pyserial matplotlib

这里有个坑：树莓派自带的 Python 版本可能和 Microduck 要求的版本不一致。我遇到过numpy版本过高导致上位机程序报AttributeError的情况。解决办法是用virtualenv建一个独立环境，锁定版本。

python3 -m venv microduck_env source microduck_env/bin/activate pip install numpy==1.24.0 pyserial==3.5 matplotlib==3.7.0

2.3 串口权限：最容易忽略的一步

树莓派默认情况下，普通用户没有串口读写权限。你直接跑程序会报Permission denied: '/dev/ttyUSB0'。解决办法是把用户加入dialout组：

sudo usermod -a -G dialout $USER # 然后注销重新登录，或者重启

注意：这一步不做，后面所有串口通信都会失败，而且报错信息不一定直接指向权限问题，有时候会显示"设备不存在"，让你误以为是硬件没接好。

3. 代码拉取与 Makefile 目标解析

3.1 仓库结构速览

Microduck 的仓库通常包含这几个目录：

拿到代码后先别急着make，花五分钟把firmware/Makefile从头到尾读一遍。重点看这几个变量：

• TARGET：目标板型号，决定编译器和链接脚本。
• SERIAL_PORT：默认串口设备名，可能需要改成/dev/ttyUSB0或/dev/ttyACM0。
• DEBUG_LEVEL：调试输出等级，首次运行建议设为1或2。

3.2 常用 Makefile 目标与用途

# 编译固件 make all # 清理编译产物 make clean # 烧录到主控 make flash # 打开串口监视器 make monitor # 校准舵机中位 make calibrate

这几个目标里，make calibrate是首次运行的关键。它会引导你把所有舵机逐个转到中位，并记录偏移量。没有这一步，小鸭站起来的时候会歪向一边，甚至直接摔倒。

3.3 编译报错"没有指明目标并且找不到 makefile"怎么处理

这个报错在热词里出现频率很高，说明很多人踩过。原因通常有三个：

1. 当前目录不对：你不在firmware/目录下执行make。解决办法是cd firmware再执行。
2. Makefile 文件名不对：有些仓库里叫Makefile，有些叫makefile，Linux 区分大小写。用ls确认一下。
3. 仓库没拉全：如果你是用git clone但没加--recursive，子模块可能是空的，Makefile 在子模块里。

# 确认当前目录 pwd # 确认 Makefile 存在 ls -la | grep -i makefile # 如果是子模块问题 git submodule update --init --recursive

4. 首次运行：让小鸭站起来并回中位

4.1 上电前的硬件检查清单

软件部署再完美，硬件接错一样站不起来。上电前逐项确认：

• 舵机电源和主控电源是否共地？不共地会导致信号电平漂移，舵机抖动。
• 舵机电源电压是否在额定范围内？常见的大扭矩舵机是 6V 到 7.4V，用 5V 供电会扭矩不足。
• IMU 是否固定牢靠？IMU 松动会导致姿态解算完全错误。
• 串口线是否接对？TX 接 RX，RX 接 TX，这个不用多说，但每年都有人接反。

4.2 舵机中位校准的完整流程

中位校准是让小鸭"站直"的前提。Microduck 的校准逻辑是：给每个舵机发送 1500us 脉宽信号（标准中位），然后观察机械结构是否处于设计的中立位置。如果不是，通过调整舵机臂的安装角度或者软件偏移量来修正。

# 进入校准模式 make calibrate # 程序会逐个提示：请将舵机 X 调整到中位，按回车确认 # 全部确认后，偏移量会写入 firmware/config/servo_offset.h

我踩过的坑：第一次校准的时候，我直接把舵机臂按到"看起来正"的位置，结果跑起来发现左腿比右腿短了一截。后来才明白，校准不是靠眼睛看，而是要靠机械限位或者水平仪。最稳的办法是先把机身放在水平桌面上，用水平仪确认机身水平，再逐个调整舵机臂。

4.3 回中位指令的发送与验证

校准完成后，运行上位机程序，发送回中位指令：

cd host python3 main.py --port /dev/ttyUSB0 --command home

正常情况下，你会看到所有舵机缓慢转到中位，小鸭从"趴着"变成"站着"。如果某个舵机不动或者抖动，检查三件事：

1. 该舵机的 ID 是否和配置文件一致。
2. 该舵机的电源线是否接触良好。
3. 该舵机的偏移量是否超出合理范围（一般不超过 ±200us）。

4.4 站起来之后的稳定性微调

小鸭站起来不等于站得稳。如果它站起来后前后晃动，说明重心偏了。Microduck 的上位机程序里通常有balance_gain参数，调大这个值会让姿态修正更激进，但太大会导致震荡。我的经验是从0.5开始，每次加0.1，直到晃动明显减小但不震荡为止。

5. 调试过程中最容易卡住的几个点

5.1 串口能打开但收不到数据

这种情况通常是波特率不匹配。Microduck 固件默认波特率一般是115200，但有些分支改成了921600。用stty命令确认当前串口配置：

stty -F /dev/ttyUSB0 # 输出里看 speed 字段

如果波特率不对，要么改固件重新编译，要么在上位机程序里指定正确波特率。

5.2 舵机嗡嗡响但不转

这是舵机堵转的典型表现。原因可能是：

• 目标角度超出了机械限位，舵机拼命想转但被结构卡住。
• 舵机扭矩不够，带不动负载。
• 电源电流不足，舵机处于"半死不活"状态。

解决办法：先用make calibrate确认中位，然后手动发送一个小角度指令（比如从 1500us 到 1550us），看舵机是否能平滑转动。如果小角度能转、大角度不转，基本就是电源问题，换一个电流更大的电源。

5.3 树莓派上运行上位机程序卡顿

树莓派 4B 跑 Microduck 上位机程序一般不会卡，但如果你同时开了桌面环境、浏览器、还有一堆后台服务，CPU 会被抢。建议用raspi-config把启动模式改成命令行，能省不少资源。

sudo raspi-config # System Options -> Boot / Auto Login -> Console Autologin

另外，如果你用的是树莓派 5，注意它的串口默认设备名可能和 4B 不同。4B 通常是/dev/ttyUSB0（USB 转串口）或/dev/ttyAMA0（GPIO 串口），5 的 GPIO 串口设备名变成了/dev/ttyAMA0但引脚定义有变化，接线前务必查树莓派 5 引脚图。

5.4 IMU 数据跳变导致姿态解算失败

IMU 数据跳变通常有两个原因：一是 I2C 总线干扰，二是 IMU 本身没校准。Microduck 的固件里一般有 IMU 校准模式，进入后把机器人静置几秒，让程序采集零偏。

make imu_calibrate # 静置 5 秒，不要碰机器人

如果校准后数据还是跳，检查 I2C 线是否过长。I2C 线超过 20cm 就容易受干扰，尽量缩短，或者加屏蔽。

6. 一些让部署更顺手的个人经验

6.1 用脚本封装重复操作

每次调试都要敲一长串命令很烦。我写了一个deploy.sh，把编译、烧录、启动上位机串起来：

#!/bin/bash set -e cd firmware make clean make all make flash cd ../host python3 main.py --port /dev/ttyUSB0 --command home

这样每次改完代码，只需要跑./deploy.sh，省去来回切换目录的时间。

6.2 保留一份"已知能跑"的配置备份

调试过程中你会改很多参数：舵机偏移、平衡增益、波特率。改到后面很容易忘记哪个版本是能跑的。我的做法是每调通一个阶段，就把firmware/config/和host/config/打包备份，命名带上日期和状态，比如config_20240115_stand_ok.tar.gz。后面出问题了直接回滚，比一点点排查快得多。

6.3 串口调试工具常备

除了 Microduck 自带的上位机程序，我建议再装一个minicom或者picocom，用来直接看串口原始数据。有时候上位机程序报错信息不明确，但串口里能看到主控实际返回了什么。

sudo apt install picocom -y picocom -b 115200 /dev/ttyUSB0

提示：用picocom的时候记得先关掉上位机程序，否则两个程序抢同一个串口，谁都收不到数据。

6.4 关于树莓派供电的一个细节

树莓派 4B 和 5 对电源要求比较高，官方推荐 5V 3A。如果你用树莓派给主控板供电，同时还要驱动舵机，电源很容易不够。我的方案是舵机单独供电，树莓派和主控共用另一个电源，两边共地但不共电源。这样舵机动作时不会把树莓派的电压拉低导致重启。

6.5 首次运行不要急着装外壳

很多人喜欢先把机械结构装得漂漂亮亮再调软件，结果发现要改舵机臂角度的时候得拆半天。我的建议是首次运行阶段保持"裸机"状态，所有舵机臂都露在外面，方便随时调整。等中位校准完成、能稳定站立了，再装外壳。

7. 从"站起来"到"走起来"之间还差什么

让小鸭站起来并回中位，只是 Microduck 的第一步。站起来之后，下一步通常是原地踏步，再下一步才是行走。这两步对软件的要求完全不同：站立只需要位置控制，行走需要轨迹规划和零力矩点（ZMP）稳定性判断。

如果你已经跑通了本文的所有步骤，接下来可以关注这几个方向：

• 步态参数文件：Microduck 的host/gait/目录下通常有步态配置文件，里面定义了步长、步频、抬腿高度。先从最小的步长开始试。
• IMU 反馈闭环：站立阶段 IMU 只用来显示姿态，行走阶段 IMU 要参与平衡修正。确保 IMU 数据稳定后再开闭环。
• 舵机温度监控：行走时舵机负载比站立大得多，连续跑几分钟后摸一下舵机外壳，烫手就说明需要降低步频或者换更大扭矩的舵机。

我在实际调试中发现，从站立到行走的过渡阶段，最容易出问题的地方不是算法，而是电源。站立时电流可能只有 1A 到 2A，行走时瞬间电流能到 5A 以上。如果你的电源没留够余量，行走指令一发，主控直接复位。所以如果你打算继续往下走，先把电源升级到至少 5V 10A 的规格，能省掉很多莫名其妙的故障排查时间。