首页/新闻资讯/正文详情

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

发布时间:2026/11/19 15:20:18 来源:云帆数科 栏目:资讯中心
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也能跑但移动性就差很多。我实测下来树莓派 4B4GB 版本跑 Microduck 上位机程序CPU 占用率在 15% 到 25% 之间完全够用。树莓派 5 当然更快但如果你只是做基础步态调试4B 的性价比更高。2. 环境准备从系统烧录到依赖装齐2.1 树莓派系统选择与基础配置树莓派官方系统Raspberry Pi OS是首选别去折腾什么 Windows on ARM 或者非官方镜像。我见过有人想在树莓派上装 Windows XP 来跑老软件这在 Microduck 场景下完全是自找麻烦——驱动不全、GPIO 支持差、串口权限混乱。烧录系统后用raspi-config做几件事开启串口Interface Options - Serial Port - 登录 shell 选 No硬件串口选 Yes。开启 I2C如果你用的 IMU 是 I2C 接口比如 MPU6050这一步必须做。修改源国内网络环境下把 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 update2.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 numpy1.24.0 pyserial3.5 matplotlib3.7.02.3 串口权限最容易忽略的一步树莓派默认情况下普通用户没有串口读写权限。你直接跑程序会报Permission denied: /dev/ttyUSB0。解决办法是把用户加入dialout组sudo usermod -a -G dialout $USER # 然后注销重新登录或者重启注意这一步不做后面所有串口通信都会失败而且报错信息不一定直接指向权限问题有时候会显示设备不存在让你误以为是硬件没接好。3. 代码拉取与 Makefile 目标解析3.1 仓库结构速览Microduck 的仓库通常包含这几个目录目录内容firmware/主控固件源码含 Makefilehost/上位机 Python 程序docs/硬件接线图、舵机角度表tools/校准脚本、串口调试工具拿到代码后先别急着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怎么处理这个报错在热词里出现频率很高说明很多人踩过。原因通常有三个当前目录不对你不在firmware/目录下执行make。解决办法是cd firmware再执行。Makefile 文件名不对有些仓库里叫Makefile有些叫makefileLinux 区分大小写。用ls确认一下。仓库没拉全如果你是用git clone但没加--recursive子模块可能是空的Makefile 在子模块里。# 确认当前目录 pwd # 确认 Makefile 存在 ls -la | grep -i makefile # 如果是子模块问题 git submodule update --init --recursive4. 首次运行让小鸭站起来并回中位4.1 上电前的硬件检查清单软件部署再完美硬件接错一样站不起来。上电前逐项确认舵机电源和主控电源是否共地不共地会导致信号电平漂移舵机抖动。舵机电源电压是否在额定范围内常见的大扭矩舵机是 6V 到 7.4V用 5V 供电会扭矩不足。IMU 是否固定牢靠IMU 松动会导致姿态解算完全错误。串口线是否接对TX 接 RXRX 接 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正常情况下你会看到所有舵机缓慢转到中位小鸭从趴着变成站着。如果某个舵机不动或者抖动检查三件事该舵机的 ID 是否和配置文件一致。该舵机的电源线是否接触良好。该舵机的偏移量是否超出合理范围一般不超过 ±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/ttyUSB0USB 转串口或/dev/ttyAMA0GPIO 串口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 的规格能省掉很多莫名其妙的故障排查时间。

相关推荐

PDF签名在线预览实战:pdf.js渲染、坐标换算与pdf-lib写入
PDF签名在线预览实战:pdf.js渲染、坐标换算与pdf-lib写入

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/11/8 12:50:26

C#串口助手实战:实时接收数据并写入Excel的WinForms方案
C#串口助手实战:实时接收数据并写入Excel的WinForms方案

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/11/20 8:29:41

SCMA稀疏码多址ML检测工程实战:从码本到球形译码
SCMA稀疏码多址ML检测工程实战:从码本到球形译码

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/11/15 17:08:55

之前考的证在外省能不能转过来 过期状态的电工证值不值得考
之前考的证在外省能不能转过来 过期状态的电工证值不值得考

之前考的证在外省能不能转过来 过期状态的电工证值不值得考 之前考的证在外省能不能转过来?这个问题在咱们这个圈子里可太常见了,很多人拿着外省的电工证,心里打鼓,怕过期、怕无效、怕用不上。特别是那些在河南本地打工、跑项目、做工程的,更担心证书是… · 2026/11/20 11:53:20

承德哪里考电工证多久拿证 工地太忙根本没时间复习考试
承德哪里考电工证多久拿证 工地太忙根本没时间复习考试

承德哪里考电工证多久拿证 工地太忙根本没时间复习考试 工地太忙根本没时间复习考试,这几乎是每个在工地干电工的朋友的共识。尤其是一线施工人员,每天面对高强度的工作节奏,根本没时间去复习备考。但如果你正在考虑报考电工证,又担心“… · 2026/11/20 11:53:20

初次报考电工证p上别人考前押题攻略,学历不高也能顺利拿下
初次报考电工证p上别人考前押题攻略,学历不高也能顺利拿下

初次报考电工证p上别人考前押题攻略,学历不高也能顺利拿下 你是不是也觉得学历不高,报考电工证会很麻烦?其实不然,现在国家对电工证的报考门槛已经越来越合理,只要你满足基本条件,学历不是障碍。尤其是像你这样的初次报考者,更需要掌握【考前押题】的… · 2026/11/20 11:53:20

中泰特种工工厂招工考不过白交钱?值不值得考这几点必须搞清楚
中泰特种工工厂招工考不过白交钱?值不值得考这几点必须搞清楚

中泰特种工工厂招工考不过白交钱?值不值得考这几点必须搞清楚 怕考不过白交培训费?别让几万块打水漂!中泰特种工工厂招工门槛越来越高,很多求职者担心考不过,花了钱也找不到工作,这确实是个现实问题。但问题是, 值不值得考… · 2026/11/20 11:53:20

电工证p上别人与郑州报考避坑指南:学历不高也能拿下高薪电工证
电工证p上别人与郑州报考避坑指南:学历不高也能拿下高薪电工证

电工证p上别人与郑州报考避坑指南:学历不高也能拿下高薪电工证 你是不是也担心自己学历不高,报不了电工证?别急,很多人跟你想的一样,但照样考下来了,甚至通过“电工证p上别人”的方式顺利拿到证书,进而在郑州甚至全省的水利工程、建筑施工等行业拿到… · 2026/11/20 11:53:20

低压电工证培训政策全国通用怎么考?实操考试心里没底怕挂科
低压电工证培训政策全国通用怎么考?实操考试心里没底怕挂科

低压电工证培训政策全国通用怎么考?实操考试心里没底怕挂科 实操考试心里没底怕挂科,这是大多数准备考低压电工证的朋友最真实的写照。尤其是刚入行的新人,面对复杂的设备操作和严格的评分标准,往往容易手忙脚乱。但好消息是,低压电工证 全国通用… · 2026/11/20 11:52:20

长春初级电工证怎么考?通过率揭秘全在这里
长春初级电工证怎么考?通过率揭秘全在这里

长春初级电工证怎么考?通过率揭秘全在这里 之前考的证在外省能不能转过来?这几乎是每个想从事电工工作的人都会问的问题。特别是那些在外地打拼多年、手里握着一张“外地电工证”的人,到了长春想继续干这一行,第一反应就是“我的证能用吗?”。今天我们就… · 2026/11/19 16:06:02

国内电工证报考条件与考试时间
国内电工证报考条件与考试时间

低压电工证怎么考?学历不高也能报名,官方报名入口全在这 你是不是经常听说“电工证是入行门槛”,但又担心自己学历不够、经验不足,根本报不了名?别急,今天就带你从零了解【国内电工证】的报考流程、考试内容,还有怎么在 官方报名入口… · 2026/11/19 17:40:37

电工作业时如何断电?电子证书到底能不能全国通用?
电工作业时如何断电?电子证书到底能不能全国通用?

电工作业时如何断电?电子证书到底能不能全国通用? 实操考试心里没底怕挂科,特别是电工作业时如何断电这一操作,不仅关系到你能不能拿到证书,更关系到以后能不能顺利上岗。很多人觉得这不过就是“断个电”,但其实这里面的门道可不少,稍有不慎就可能出错… · 2026/11/19 17:50:07

建设厅特种工周三报名怎么弄?上岗必备别被中介坑
建设厅特种工周三报名怎么弄?上岗必备别被中介坑

建设厅特种工周三报名怎么弄?上岗必备别被中介坑 不知道去哪报名怕被中介坑?作为商丘某高校工程类应届毕业生,小李最近就遇到了这样的困扰。他刚毕业,正在找实习岗位,发现很多工地都要求持有特种作业操作证,尤其是【建设厅特种工周三报名】这个时间点,… · 2026/11/20 0:00:54

中专考的中级电工证内部消息全攻略
中专考的中级电工证内部消息全攻略

中专考的中级电工证内部消息全攻略 你中专毕业,手头有中级电工证,但不知道从哪开始报名,怕被中介坑?别急,这篇文章就是为你量身定制的“内部消息”,帮你避开报名陷阱,稳稳拿到证书。… · 2026/11/20 0:00:54

外省电工证能转过来吗?电子证书怎么查电工作业教学效果评价
外省电工证能转过来吗?电子证书怎么查电工作业教学效果评价

外省电工证能转过来吗?电子证书怎么查电工作业教学效果评价 之前考的证在外省能不能转过来?这几乎是所有在外地打拼的电工从业者最关心的问题。特别是像洛阳这样的工业城市,很多电工证是在外地考的,现在想在当地用,流程是不是很复杂?其实,只要搞清楚… · 2026/11/20 0:00:54

双极步进电机控制实战:DRV8818PWPR与PIC18F86K22驱动调试
双极步进电机控制实战:DRV8818PWPR与PIC18F86K22驱动调试

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/11/20 10:25:45

STM32F207ZG + DRV8818PWPR 步进电机驱动实战解析
STM32F207ZG + DRV8818PWPR 步进电机驱动实战解析

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/11/20 10:25:54

DRV8818PWPR+dsPIC30F4013工业级双极步进电机控制方案
DRV8818PWPR+dsPIC30F4013工业级双极步进电机控制方案

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/11/20 10:26:03

了解更多?预约专属演示

我们的顾问将为您一对一讲解产品与方案

企业微信二维码