10个让复刻机器鸭的人深夜抓狂的坑：Microduck复刻踩坑清单——现象、原因、怎么办，三条一坑

• 机器人
• 硬件开发
• 嵌入式
• 强化学习
• 人工智能
• 逆向工程

microduck-replica 项目从官方 Microduck 的 MJCF 仿真模型与开源 Rust 源码中，反推出装配图、CAD 装配体与完整电控方案。本文从它的 踩坑记录 里挑出 10 个最真实的Microduck 复刻踩坑，横跨买件、舵机校准、主板刷机和模型上机四个阶段——每坑固定三条：现象、原因、怎么办，动手前先扫一遍，能帮你省下不少深夜。

一、买东西阶段：件还没到手，就已经买错了

坑 1：STL 文件名叫 NP-F970，要买的电池却是 NP-F550

• 现象：官方网格文件叫np_f970.stl，照着名字买 NP-F970 电池，装进电池仓——塞不进去。
• 原因：量出舱位是 39 × 21 × 71 mm，这是 F550 的尺寸；真 F970 厚约 60 mm，而且 300 g 重量会吃掉整机预算的三分之一。
• 怎么办：买NP-F550（2S，6.6–8.4 V），详见 BOM.md。⚠️ 额外注意：F550 满电 8.4 V 正好顶在 HD-1910 的电压上限上，零余量——刚充满别直接堵转测试，开机前把舵机过压保护打开。

坑 2：ToF 模块连买两次，两次都装不上

• 现象：先买 VL53L8CX，国内常见那块板 33.4 × 10.2 mm，脸壳（face_part）装不下；改买更短的 L7CX（26 mm），结果固件启动就报错退出。两块白买。
• 原因：官方tof固件只认 L5CX 和 L8CX 两颗芯片的 revision ID，L7CX 对不上，直接报neither a VL53L5CX nor a VL53L8CX然后退出——固件里只编了这两个驱动，改 ID 绕不过去。
• 怎么办：选型顺序是先看芯片固件认不认，再看板子塞不塞得进，反过来先挑尺寸就是这次的下场。买VL53L5CX：固件认、孔距 20 mm 正好对上打印件、板体还最小。三种板型尺寸对比见 docs/电控采购清单.md。

二、舵机阶段：15 颗 HD-1910 一上总线，全体「反」了

坑 3：HD-1910 位置方向 15 颗全反，不是个别装错

• 现象：网页调试台拖滑块，3D 模型跟实际反着动；按官方站姿发角度，腿往反方向弯。
• 原因：HD-1910 读数增大的方向跟官方 XL330 相反，而机械装法是照搬官方的，所以每个关节整体反了一次——是全体反，不是几颗装反了。
• 怎么办：15 颗方向全取 −1，表在 tools/servo-web/directions.json，网页调试台每颗舵机旁有 ± 按钮，逐颗对着实物核对。

坑 4：中位校准「写 128」回成功，偏移寄存器却没动

• 现象：内存表手册明写「写 128：任意当前位置较正为 2048」，照着做舵机回「成功」，但偏移寄存器（31）一个都没变。代码接着把目标位置写成 2048，关节反而被拉回旧零位。
• 原因：这台舵机固件 3.46 不支持该指令。协议手册 4.9 的支持表写着：SMS ≤2.54 和 STS ≥3.10 才支持写 128，HLS ≥3.43不支持、只支持 0x0B 位置校准——HD-1910 的表现与 HLS 一致。
• 怎么办：用0x0B 位置校准指令，校完必须回读位置和偏移确认——飞特很多不支持的操作照样回「成功」，别信应答。另外校准时别关着扭矩干等：关扭矩后等几十毫秒再读位置，颈部会被重力压掉 80 步（7°），零位就校歪了。

坑 5：先给舵机上电、后插 USB，整条总线「半死」

• 现象：15 颗舵机全不应答，广播 ping 也只收到几个全 0 字节；万用表量总线 S–G 空闲只有 2.1 V（正常 4.5 V 上下）。这个项目的人在这上面耗了一小时，先怀疑 S/G 插反、再怀疑板子坏。
• 原因：URT-2 调试板的逻辑电只来自 USB。舵机那边先把总线拉到 5 V 时板子还没电，电流从 S 脚倒灌进 5 V 轨，等 USB 再插上，电平转换部分已经卡在半死状态。
• 怎么办：先插 USB，再给舵机上电。顺序反了就把两边都断开重来，别急着怀疑接线或硬件。完整总线拓扑见下图，踩坑原文在 踩坑记录.md。

三、主板阶段：镜像起不来、串口「消失」

坑 6：Armbian 官方镜像在 V1.12 Radxa Zero 3W 上起不来

• 现象：Armbian vendor 镜像烧上去，灯有心跳双闪（内核起来了），但系统盘一个字节都没被碰过，局域网里永远找不到这块板。瑞莎官方镜像同一张卡、同一块板一次就起。
• 原因：2024 年底后出厂的 Zero 3W 是 V1.12，WiFi 换成 AIC8800。Armbian 配的是主线 U-Boot + 较老的内存初始化固件，自带的设备树还不认这批板子——差异最后只剩引导程序和设备树。
• 怎么办：引导和 DTB 都从瑞莎 B1 镜像里拿（写到卡的扇区 64 / 16384，extlinux 的fdt指向拷来的那份），内核和根文件系统保留 Armbian 的。一键做卡脚本在 tools/radxa/，逐步说明见 tools/radxa/镜像使用说明.md。

坑 7：舵机怎么都不通——ttyS2 被拿去打系统日志了

• 现象：板子正常启动，但没有/dev/ttyS2；或者节点在、舵机却完全不应答，线确认接对了。
• 原因：这个串口上蹲着三个「小偷」。① Armbian 出厂overlay_prefix=rk35xx，而 RK3566 的 overlay 叫rk3568-*，加载器静默失败，uart2 节点根本没建；② 内核 console 默认就挂在 ttyS2 上，等于往舵机总线上打日志；③ Armbian 还在 UART2 上跑agetty登录控制台，占着端口不放。
• 怎么办：三件事各做一遍：/boot/armbianEnv.txt改overlay_prefix=rk3568并加overlays=uart2-m0；extraargs里去掉console=ttyS2,1500000；systemctl mask serial-getty@ttyS2。不走官方 HAT、用飞线直连主板的完整接法见 docs/不打HAT.md。

四、散热阶段：主板一热，鸭子全身都「慢半拍」

坑 8：主板 89°C 锁死 408 MHz，网页摇杆点一下没反应

• 现象：跑策略时控制周期从 20 ms 拉长到 25 ms；中控各项数据都正常，点网页摇杆的 Start 却没反应，robotd 根本没收到启用请求；top里一个服务占满整核，CPU 84–87°C，scaling_max_freq被压到最低档 408 MHz。
• 原因：两层叠加。一是没接摄像头和 ToF 时，官方mediad、tofd服务不停崩溃重启，其中一个 99.5% 占满一个核，把主板烧热；二是主板装在机身里没有散热片、没有进出风的风道，RK3566 到 85°C 就降频，408 MHz 下连网页虚拟手柄光启动就要 1.7 秒，等不到确认，按键直接作废。
• 怎么办：没接这两样就先sudo systemctl disable --now mediad tofd；在头壳或机身开孔做出风道（有进风、有出风，风扇不一定要贴主板）；跑模型前看一眼/sys/class/thermal/thermal_zone0/temp和当前频率——频率停在 408000 就是在降频。

五、模型上机阶段：仿真里会走，真机上「不走」「塌了」

坑 9：手托着机身测行走模型——只换姿势，不走

• 现象：kissqy 的 walk 模型上机：手托着机身时给 0 / 0.05 / 0.15 m/s 都只换一下姿势，然后几秒不动；放到地上不扶，0.4 秒内两腿就开始交替屈伸。
• 原因：这类行走模型的输入里没有「节拍」，迈步靠身体晃动、重心转移，再经 IMU 和关节反馈带出来。机身被托住，身体不晃，输出很快停在一个静止姿势上。
• 怎么办：放地上，两手在两侧虚护 2–3 cm，倒了再接。速度 0 本来就是「站着不动」，不能拿来判断模型会不会走。每个运行参数的作用见 docs/HD1910-20261011-kissqy-walk上机实测.md。

坑 10：一走就全身卸力——保护误触发，起步没软启动

• 现象：鸭子刚迈腿就停，接着 15 颗舵机一起卸力，整只塌下去；或者一起步 0.3 秒内 14 颗电压掉到 4.6–5.2 V，保护停机。
• 原因：运行器的两道保护是按台架小动作定的——任一舵机电压低于 6.6 V 就停（走起来电流大，7.4 V 供电在舵机端就掉到 6.5 V 触发）；停下后要求位置偏差 ≤ 1° 才保持（正在动或下沉的鸭子做不到，于是走到「全部卸力」）。再加第一帧姿态直接跳变，十几颗舵机同时猛发力，起步瞬间电流尖峰最大。
• 怎么办：保持判定放宽到 5°（回站到位仍按 1°）；加软起步——开头 1 秒动作幅度从 0 线性升到 100%；电源调到约 8.0 V 留余量（HD-1910 上限 8.4 V）。要做大动作，直接用瞬间能出十几安的 2S 锂电池。

动手前的三件事

1. 先把 踩坑记录.md 通读一遍——每坑三条，按「买东西 → 画板 → 飞线 → 舵机 → 主板 → 软件 → 工具」排好，有新坑也会持续往里加。配套的过程文档：机械看 构建日志.md，电气与软件看 调试记录.md。
2. 先选路线再下单：原版 XL330 与飞特 HD-1910 两条线的打印件、电压、软件适配都不一样，舵盘配合件不能混用。选型论证在 docs/执行器选型.md，飞特总线协议差异见 software/飞特适配架构.md。
3. 运行端优先在现成的上面改：策略对控制周期、动作滤波、采样时序很敏感，自己另写一套运行器，每个细节都是看不见的变量。

• 机器人
• 硬件开发
• 嵌入式
• 强化学习
• 人工智能
• 逆向工程