Microduck：从一只 399 美元的小型双足，到机器人系统软件的真实边界

0. 简介

Microduck 是 Pollen Robotics 与 Hugging Face 推出的 25 cm 小型双足机器人 。官方产品页将它描述为可由用户训练强化学习行为的开源软件栈设备，预售起价为 399 美元（不含税费和运费） ；其公开仓库则给出了更具体的工程轮廓：Rockchip RK3566 上运行多个 Rust daemon，robotd 以 50 Hz 驱动 15 个舵机，并加载经 MuJoCo/PPO 训练、导出为 ONNX 的策略。本篇不把它写成"可爱的机器鸭新闻"，而是沿着设备运行时、策略控制、升级恢复、ROS 2/Isaac 仿真集成和真机安全五条线拆解：这套架构究竟解决了哪些问题，社区教程能带人走到哪里，以及哪些环节仍必须由真实硬件验证。

围绕 Microduck 的讨论很容易把三个层次搅在一起。第一层是 Pollen Robotics 的官方产品与 pollen-robotics/microduck 软件仓库；第二层是官方的 microduck_rl 策略训练仓库，负责 MuJoCo、PPO、随机化与 ONNX 导出；第三层是 osrbot/microduck-ros2-isaac 社区集成项目，它提供 ROS 2 Jazzy、RViz 和 Isaac Sim 的中文学习路径。它们可以互相参考，却不是同一份发布物。 后文中所有关于电机控制权、更新机制和设备命令的描述以官方仓库为准；所有 ROS 2/Isaac 命令则标注为社区仿真与集成路线。

如果读者只关心系统架构，可以先看第 3 至第 7 节；如果想在电脑上跑通模型、关节和策略，应直接看第 9 至第 11 节；如果目标是自行装配类似双足设备，第 12 节的安全边界比任何安装命令都更重要。这里要厘清的是，官方仓库当前明确公开的是软件栈，不能据此推导"官方已完整开源机械和电子设计文件"。社区 DIY 或改装方案的 BOM、3D 打印件和接线图，必须以其各自仓库的许可证、版本和文档为准，不能被包装成官方 Microduck 的标准硬件方案。

1. 从价格标签回到工程对象

1.1 小机器人不等于小问题

一台约 800 g、15 个舵机的小型双足，外观上远离工业机器人，但它仍有真实的执行器、惯性传感器、电池、无线连接和跌倒风险。体积缩小不会自动降低系统软件的责任。 手机应用偶发崩溃通常意味着界面失去响应；双足控制程序在错误时刻把一个关节推向错误位置，则可能造成电机堵转、机械干涉或设备跌落。Microduck 的价值不在于它首次发现了这些风险，而在于其公开设计把"谁可写电机、谁能恢复系统、谁负责策略切换"写成了代码和服务边界，而不只是宣传语。

1.2 硬件规格意味着什么

公开 README 和产品页给出的关键信息包括 RK3566、15 个舵机、摄像头、头部深度传感器、IMU、无线连接和 50 Hz 控制循环。对于控制软件而言，最有分量的不是某一个营销参数，而是资源约束：1 块 ARM 板既要运行 Linux 服务，又要处理传感器、策略推理、通信和升级。 因此，项目没有把"在机训练一个大模型"当作前提，而是把训练更多地放到工作站或云端，将部署端收敛为轻量观测、ONNX 推理和安全执行。这是一条适合小型机器人、但并不适合所有机器人形态的工程路线。

1.3 控制频率的量纲

50 Hz 的含义是每轮控制周期的理论预算为 20 ms，而不是"Linux 变成了硬实时系统"。若第 k k k 轮起点为 t k t_k tk，理想周期可以写成。这个表达式只描述调度目标，不描述总线读写、推理、日志和其他 Linux 任务是否刚好都能在窗口内结束；因此它是后续测量与告警的刻度，而不是一张自动生效的实时证书：

T = 1 f = 1 50 s = 20 m s , t k + 1 = t k + T . T = \frac{1}{f} = \frac{1}{50}\ \mathrm{s} = 20\ \mathrm{ms}, \qquad t_{k+1} = t_k + T. T=f1=501 s=20 ms,tk+1=tk+T.

其中 f f f 是控制频率， T T T 是周期。循环要在这段窗口内完成读取总线、整理观测、推理策略、施加限幅并下发目标。进一步看，50 Hz 和 1 kHz 的难度并不在一个数量级：前者允许把准实时工作限制在一个精简进程内，后者通常会把电流环、FOC 或硬安全下沉到 MCU、专用控制器或 RTOS。Microduck 的选择是约束问题，而不是宣称通用替代实时控制。

直觉理解：把 20 ms 想成每秒 50 次的节拍器。某一次来不及完成时，合理的做法不是连补几次过期动作，而是丢弃已经失去时效的节拍并回到当前时间。这和驾驶时错过一个转向提示后不能立刻连续猛打几次方向盘是同一个道理。

2. 官方软件栈的基本形状

2.1 一块板上的七个 daemon

官方架构文档把第一版目标写成"一块板、七个 daemon、Unix socket 通信"。robotd 负责电机、传感器、策略与安全；configd 管 Wi-Fi、身份、配对与电源相关配置；updaterd 管验证、安装、切换、健康检查和回滚；btd、padd、mediad 分别承担蓝牙、手柄和媒体/远程传输；tofd 发布 8×8 ToF 深度数据。这里的关键是，这并不是把消费机器人硬套成云端微服务，而是用 Linux 原有的进程隔离、systemd 生命周期和文件权限，把会一起故障的事情尽量拆开。

2.2 本地 IPC 并非"没有接口"

文档明确采用 JSON-RPC 2.0 over Unix Domain Socket ，每行一个 NDJSON 对象。与在本机开一个 TCP 端口相比，Unix socket 的路径权限可以直接限制哪些进程能连接，SO_PEERCRED 还能帮助服务识别调用者的 uid、gid 与 pid。这样做并不排斥远程控制：蓝牙和 WebRTC 只是把外部输入转译为同一套调用，最终仍由拥有服务 socket 的进程处理。换句话说，Microduck 没有选择一个笨重的全局消息总线，不等于没有 API；它是在单板、少量服务的约束下，优先选择更小的故障面和更清晰的本地授权边界。

2.3 systemd 的角色

在这套设计中，systemd 不是机器人算法框架，却承担了相当实际的职责：服务启动顺序、异常重启、watchdog、运行目录与权限。官方文档特意强调 configd、updaterd 和 btd 不依赖 robotd，因为控制循环已经死亡时，用户仍需要配置网络、连接设备并恢复旧版本。恢复路径不能依赖待恢复的组件。 这是嵌入式产品经常被忽略的一条原则：把所有能力塞进控制进程，开发期看起来简单，现场故障时却会把诊断、更新和网络配置一起锁死。

3. 单一所有权：谁能让机器人动起来

3.1 Intent 与电机写入之间的闸门

官方架构将 robotd 定义为唯一接触机器人本体的服务：15 个舵机与 IMU 共享一条串行总线，50 Hz 控制循环独占该总线。手柄、手机、远程 WebRTC 客户端或命令行工具发出的不是原始电机寄存器写入，而是"前进多快""看向哪里""站起来"等 Intent（意图） 。robotd 根据当前姿态、跌倒状态、关节与热限制决定哪些请求可执行。这使得控制链有一个不可绕过的安全决策点，也让不同输入设备不必各自实现一份不一致的限幅逻辑。

3.2 一个状态只有一个 owner

"单一写入者"不只针对电机。configd 拥有配网和设备身份，updaterd 拥有版本状态，tofd 拥有深度传感器发布，padd 读取手柄并把意图送往 robotd。服务之间可以订阅或调用，但不应各自保留一份可以修改的影子状态。核心问题在于，机器人故障往往不是某个算法完全失效，而是两个模块对"当前模式""当前版本"或"当前目标姿态"持有不同答案。单一 owner 让状态转移有来源可查，也让后续审计能回答"是谁在什么条件下改变了什么"。

3.3 真实代码如何落实入口收敛

padd 的源码注释直接写明它读取手柄后将 intents 发往 robotd socket。下面片段不是伪代码，它展示了客户端连接 robotd 的真实入口；手柄程序本身不持有电机总线，也不保存运动控制会话状态。工程上的收益是新增输入设备时不会自然获得执行器权限，代价是每条控制路径都要遵守稳定的 IPC 合约与超时语义。

// pollen-robotics/microduck/padd/src/main.rs
let mut stream = match UnixStream::connect(&args.socket) {
    Ok(stream) => stream,
    Err(e) => {
        tracing::error!(error = %e, socket = %args.socket.display(), "cannot reach robotd");
        return ExitCode::FAILURE;
    }
};

工程价值：这像楼宇门禁系统。门外的卡、手机和前台都可以提出"开门"请求，但真正控制门锁的是同一台门禁控制器。权限集中并不消除接口设计工作，却能避免每个入口都悄悄带着一把能直通电机的钥匙。

4. 50 Hz：Linux 上的准实时孤岛

4.1 不追赶过期节拍

官方 robotd 主循环使用 Tokio interval，并显式选择 MissedTickBehavior::Skip。注释给出的理由很具体：Burst 会把积压的电机命令连续补发，Delay 会把每次调度延迟累加到下一周期，只有 Skip 保留原有时间轴并丢掉来不及执行的旧 tick。这说明项目把"控制时序"当作行为正确性的一部分，而不是普通业务程序中的吞吐量问题。过期控制命令的价值接近于零，连续补发反而可能放大风险。

// pollen-robotics/microduck/robotd/src/main.rs
let mut ticker = tokio::time::interval(period);
ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);

while !state.shutdown.load(Ordering::Relaxed) {
    ticker.tick().await;
    let tick_start = Instant::now();
    let fresh = match safety.read() {
        Ok(sensors) => Some(sensors),
        Err(e) => {
            tracing::warn!(error = %e, "bus read failed");
            None
        }
    };
}

4.2 缓存而非同步等待

架构文档给出一条关键不变量：robotd 的控制循环永远不应同步等待另一个 service。跨服务读取使用 last-value-wins 缓存，而不是让每轮控制等待网络、摄像头或深度传感器回复。直观理解是，保持平衡的人不会每迈一步都停下来等手机地图刷新；地图可以慢一点，脚下的平衡不能等。这个设计并不保证所有数据总是最新，却把必须按时完成的链条缩短为总线读写、局部状态、安全逻辑与策略推理，从而把 Linux 调度抖动的影响限制在可观测的范围内。

4.3 监测比口号重要

讨论 Linux 与 RTOS 时，最容易丢掉的是观测指标。官方 robotctl monitor 与 robotctl health 设计会报告循环频率、IMU 数据、关节目标与实测、跌倒判定、电池和温度等状态；文档还将"控制循环只有 43.9 Hz"直接作为不健康示例。这里值得强调的是，项目提到过某次 bring-up 的 tick 统计，并不构成所有负载、温度和外设组合下的实时性承诺。实时性不是贴在内核名上的属性，而是 deadline、负载、总线、调度策略和实机测量共同给出的结果。

难点提示：把控制频率看成航班时刻表会更容易理解。只看平均飞行速度没有意义，关键是某一趟航班能否在登机口关闭前到达。50 Hz 下偶尔缺一班需要被记录和处理；若任务变成 1 kHz 电流控制，允许迟到的窗口缩到 1 ms，系统分层就必须改变。

5. 策略进入控制环

5.1 61 维观测与 14 维动作

用户提供的资料与官方实现都指向同一条链：当前 locomotion policy 的接口是 o b s 1 , 61 → a c t i o n s 1 , 14 \mathrm{obs}1,61 \rightarrow \mathrm{actions}1,14 obs1,61→actions1,14。观测包含 IMU、关节位置与速度、默认姿态、上一轮 action 和速度命令等状态，输出用于生成关节偏移。整机有 15 个电机而 locomotion action 只有 14 维，并不矛盾：嘴部舵机不属于行走策略动作空间。模型输出不是"直接操纵全部硬件"的同义词，它只是控制合约中的一组受约束变量。

o t = ω t , g t , q t − q 0 , q ˙ t , a t − 1 , c t ∈ R 61 , a t = π θ ( o t ) ∈ R 14 . o_t = \\omega_t,\\ g_t,\\ q_t-q_0,\\ \\dot q_t,\\ a_{t-1},\\ c_t \in \mathbb{R}^{61}, \qquad a_t = \pi_\theta(o_t) \in \mathbb{R}^{14}. ot=ωt, gt, qt−q0, q˙t, at−1, ct∈R61,at=πθ(ot)∈R14.

其中 ω t \omega_t ωt 是角速度， g t g_t gt 是重力方向投影， q t q_t qt 与 q ˙ t \dot q_t q˙t 是关节位置和速度， q 0 q_0 q0 是默认姿态， a t − 1 a_{t-1} at−1 是上一轮动作， c t c_t ct 是来自意图层的命令。将上一轮动作写入观测，能让策略了解自己刚刚发出的控制趋势，而不是把连续系统误看成每一轮都从零开始。

5.2 ONNX 推理之后仍有控制学

源码中 Observation::build 先构造观测，self.policy.infer 运行网络，随后代码依据默认姿态、action scale 与过滤参数生成目标关节位置。这里的关键是，神经网络没有跳过控制层。它给出的是相对偏移，最终目标还要经模式选择、站立/行走调参、比例缩放、头部与腿部低通滤波后才进入电机执行链。把所有保护寄托在训练奖励中，会让部署期缺少可解释、可调的防线；将策略嵌入已有控制管线，则保留了运行时的限幅与诊断位置。

// pollen-robotics/microduck/robotd/src/control.rs
let observation = Observation::build(
    &sensors.imu, &sensors.positions, &sensors.velocities,
    &DEFAULT_POSITION, &self.last_action, &effective,
);
let action = self.policy.infer(&observation, net)?;
self.last_action = action;

let offsets = Observation::scatter_action(&action);
let mut targets = [0.0; NUM_JOINTS];
for joint in 0..NUM_JOINTS {
    targets[joint] = DEFAULT_POSITION[joint] + scale * offsets[joint];
}

5.3 从动作到目标角的边界

可以把这段关系写成下面的式子。它把"神经网络输出"和"要写入舵机的目标"清楚分为两层：网络提供相对动作，部署层再将动作放回机器人的默认姿态坐标系，并按照当前模式施加缩放与可选的时间滤波。这个中间映射还固定了动作向量每一个位置对应哪个关节；只要顺序或正负方向发生偏差，形式完全正确的模型也会在真机上给出错误动作：

q t ⋆ = q 0 + s t   S ( a t ) , q ~ t ⋆ = α q t ⋆ + ( 1 − α ) q ~ t − 1 ⋆ . q_t^{\star} = q_0 + s_t\,\mathcal{S}(a_t), \qquad \tilde q_t^{\star} = \alpha q_t^{\star} + (1-\alpha)\tilde q_{t-1}^{\star}. qt⋆=q0+stS(at),q~t⋆=αqt⋆+(1−α)q~t−1⋆.

其中 S \mathcal{S} S 将 14 维动作散射到实际关节索引， s t s_t st 是随模式和电压等条件变化的缩放系数， α \alpha α 是可选低通滤波系数。公式说明了一个常被省略的事实：策略动作的单位和真实电机目标的单位不必相同。训练时改变动作范围、部署时改变 scale 或滤波，都可能让同一 ONNX 文件展现完全不同的运动品质。因此，导入自训模型前必须同时核对观测顺序、动作顺序、默认姿态、关节方向、缩放和安全参数。

难点提示：把 policy 看作舞蹈编导，而不是直接拉动四肢的绳子。编导给出"这一拍左腿抬多少"的建议，控制层还要检查地面、平衡、可活动范围与身体状态，最后才把建议翻译成关节目标。训练得再好的编导，也不能替代舞台安全员。

6. 训练、导出与策略版本

6.1 PPO 在这里解决什么

官方 README 指向 microduck_rl，并注明策略通过 MuJoCo 与 PPO 训练后导出 ONNX。PPO 的重点不是让机器人"自动拥有智能"，而是在连续控制任务中限制每次策略更新过大，使奖励优化不会因一次激进梯度步骤突然破坏既有步态。若 r t ( θ ) r_t(\theta) rt(θ) 表示新旧策略概率比，典型裁剪目标可写为：

L C L I P ( θ ) = E t min ⁡ ( r t ( θ ) A \^ t , clip ⁡ ( r t ( θ ) , 1 − ϵ , 1 + ϵ ) A \^ t ) . \mathcal{L}^{\mathrm{CLIP}}(\theta)=\mathbb{E}_t\left\\min\\left(r_t(\\theta)\\hat A_t,\\ \\operatorname{clip}(r_t(\\theta),1-\\epsilon,1+\\epsilon)\\hat A_t\\right)\\right. LCLIP(θ)=Etmin(rt(θ)A\^t, clip(rt(θ),1−ϵ,1+ϵ)A\^t).

其中 A ^ t \hat A_t A^t 是优势估计， ϵ \epsilon ϵ 控制策略单次更新可偏离旧策略的程度。训练层还会叠加跟踪速度、保持姿态、能耗、足端接触和碰撞等奖励或惩罚；具体权重不是一个可脱离机器人结构照抄的配方，而是需要结合模型、随机化与实机差异反复校正。特别是步态任务里，单独提高速度奖励常会诱发脚步冲击、姿态抖动或落脚不稳，因此奖励函数只能作为待验证的设计假设，不能脱离跌倒率、能耗和恢复能力单独阅读。

6.2 策略是可更新工件

官方命令文档已把策略管理从 daemon 整包更新中区分出来：robotctl policy list 查看 slot 与 skill，robotctl policy check 检查更新，sudo robotctl policy update 更新官方策略，sudo robotctl policy load walk /home/radxa/my_walking.onnx 可尝试本地 ONNX。文档还说明替换行走策略前机器人回到 home pose，并在加载失败时不把系统留在无步态状态。这比"把模型文件复制到目录里"多了一层产品化语义：模型也有来源、版本、兼容性、回退和正在运行的状态。

6.3 Policy Store 仍是路线图，不是既成生态

把策略称为"机器人软件包"很有解释力，但必须保留技术边界。可分发的模型需要稳定的 observation/action contract、模型 API 版本、签名或可信来源、已知坏版本记录与安全验证；缺任何一项，所谓社区策略市场都会退化为随机文件交换。官方架构文档已经讨论 policy channel、独立更新与回滚相关问题，这说明团队正在把模型生命周期当作系统问题处理；它不等于已经形成成熟的、可任意安装第三方步态的应用商店。这里要的是可证据化的版本管理，而不是替未来生态提前下结论。

7. OTA：能升级，也能回到昨天

7.1 updaterd 为什么要独立

对于可售设备，升级失败的代价远高于实验室里重新刷一次系统。官方文档中，release 落在 /opt/robot/daemon/releases/<version>/，current 符号链接指向正在使用的版本；updaterd 验签后切换链接、重启相关服务，再询问 robotd 的健康状态。如果新版本不健康，旧 release 会自动恢复。这里的关键是 updaterd 不依赖 robotd 的正常存活，原因很直白：控制进程起不来时，更新和回滚恰恰必须可达。

7.2 哈希、签名和健康门

源码把完整性和真实性分开处理：先核对 SHA-256，再用可信密钥验证签名，随后才解压到 staging 目录。这个顺序既避免损坏文件进入 live path，也避免只凭哈希却不知道发布者身份。之后的 health gate 回答的是另一类问题：文件未被篡改不代表机器人在这块板上能正常起步。若记 H ( v ) H(v) H(v) 为版本 v v v 的健康检查结果，则安装决策可简化为：

activate ⁡ ( v ) = { v , sig ⁡ ( v ) = 1 ∧ hash ⁡ ( v ) = 1 ∧ H ( v ) = 1 , v p r e v i o u s , otherwise . \operatorname{activate}(v)= \begin{cases} v, & \operatorname{sig}(v)=1\ \land\ \operatorname{hash}(v)=1\ \land\ H(v)=1,\\ v_{\mathrm{previous}}, & \text{otherwise}. \end{cases} activate(v)={v,vprevious,sig(v)=1 ∧ hash(v)=1 ∧ H(v)=1,otherwise.

这不是数学上充分的安全证明，却是面对断电、错误工件、进程启动失败和依赖不匹配时很实用的恢复框架。它的实际含义是将失败切成可定位的阶段：下载与签名失败不触碰 live release，启动或健康检查失败则回到先前版本；维护者还必须借助日志、硬件状态和健康报告，判断异常是否真由软件版本引起。

// pollen-robotics/microduck/updater/src/engine.rs
rec.phase(Phase::Verifying, None);
let artifact = fetched.artifact.clone();
let expected = manifest.sha256.clone();
blocking(move || verify::verify_sha256(&artifact, &expected)).await?;

let signature = std::fs::read(&fetched.signature)?;
let keys = std::sync::Arc::clone(&self.keys);
let artifact = fetched.artifact.clone();
let signed_by = blocking(move || {
    keys.verify_file(&artifact, &signature).map(|key| key.id.clone())
}).await?;

工程价值：升级流程像登机前的三道检查。哈希确认行李没有在运输中损坏，签名确认行李来自可信航空公司，健康门确认飞机发动机真的启动。只做其中任意一道，都不足以替代另两道。

7.3 版本回退不是倒退

很多设备把 OTA 理解为"永远向前升级"，但机器人需要保留一个更重要的动作：确认新版本让运动、总线或传感器异常后，能回到此前已验证的状态。官方文档还讨论了 boot counter，用于捕获一次健康门之外的启动崩溃循环。进一步看，回退并不保证修复所有问题，例如电池失效、舵机未上电或硬件接触不良都不是软件回滚能解决的原因。好设计的价值在于把"版本造成的故障"和"版本无法修复的故障"分开，让维护者不会对每次异常都盲目反复更新。

8. 不把"不以 ROS 2 为中心"误读成"反对 ROS 2"

8.1 两套架构回答不同问题

Microduck 官方运行时以 Linux service、Unix socket 和 JSON-RPC 为中心；ROS 2 则以 Node、Topic、Service、Action 与可替换的 RMW 中间件为中心。ROS 2 在多机、多进程、多传感器和需要标准化工具链的系统里极具优势，尤其是可视化、消息录制、导航、机械臂规划与跨团队集成。对于"单板、七个本地服务、少量固定硬件配置"的目标，官方项目选择不引入完整 ROS 2 运行时，也有合理性。差异是复杂度预算和系统边界，不是先进与落后的排名。

8.2 一个对照表

维度	官方 Microduck 设备运行时	ROS 2 生态常见做法
核心程序模型	Rust daemon + systemd	ROS 2 Node + launch
本地控制通信	Unix socket + JSON-RPC/NDJSON	Topic、Service、Action
执行器权限	robotd 独占电机总线	由节点与系统集成策略决定
重点能力	固定设备、恢复、更新、安全边界	组件协同、工具链、分布式扩展
OTA	updaterd 是一等服务	通常由产品层另行实现
适合场景	单板、资源受限、软硬件边界稳定	多计算单元、模块多、快速研究集成

表格不表示 ROS 2 不适合 Microduck。社区项目已经证明，ROS 2 可以成为理解 URDF、关节状态、传感器可视化和 Isaac 协同的极好入口。真正需要避免的是把 ROS 2 的开发机工作空间误当成官方设备上的唯一控制根；一旦把两者混为一谈，就会模糊 robotd 的安全权威和社区仿真的目的。

8.3 社区项目的位置

osrbot/microduck-ros2-isaac 的中文站点明确把 ROS 2 与 Isaac 分为两条独立路线：ROS 2 路线要求 Ubuntu 24.04 与 ROS 2 Jazzy，不要求 NVIDIA GPU；Isaac 路线需要 Ubuntu 24.04、可用 Vulkan 的 NVIDIA GPU，并说明其完整测试组合为 Isaac Sim 6.0.1 standalone 与 Isaac Lab 3.0.0 beta 2。这是一份很适合初学者的仿真集成教程，而不是官方真机固件安装说明。 它的价值在于先让读者看见模型、动关节、验证策略，再决定是否进入高风险的实机阶段。

9. 实用教程第一部分：先在电脑上建立可验证环境

9.1 选择路线，而不是全都安装

第一次接触时，应先选一条路线。若目标是阅读模型、查看 TF/关节状态、在 RViz 中理解机械结构，选 ROS 2 Jazzy；若目标是跑 ONNX 策略、观察物理交互或研究训练，才进入 Isaac Sim/Isaac Lab。社区安装页给出的最小前提是 Ubuntu 24.04；ROS 2 路线可在无 NVIDIA GPU 的电脑上开始，Isaac 路线则必须先确认显卡驱动、nvidia-smi 与 Isaac Lab launcher 正常。这样拆分的好处是把"工具没装好"和"策略表现异常"分开，避免一上来在庞大依赖中迷失。

9.2 克隆并检查仓库结构

下面命令来自社区安装页。执行前请确认当前目录是自己允许保存源码的位置；它只下载社区集成项目，不会向官方真机写入任何内容。第二条检查同时确认 README、ROS 2 工作空间和 Isaac 资产目录存在。若输出不是 MicroDuck repository: OK，先处理仓库下载或目录错误，不要跳到后面的 RViz、Isaac 或策略脚本步骤。

# osrbot.github.io/microduck-ros2-isaac/zh/guide/installation
git clone https://github.com/osrbot/microduck-ros2-isaac.git
cd microduck-ros2-isaac

test -f README.md && test -d ros2_ws && test -d assets/isaac \
  && echo "MicroDuck repository: OK"

9.3 安装 ROS 2 Jazzy 的最小集

社区文档将以下命令定位为 ROS 2 路线的环境准备，并假设 Ubuntu 24.04 已按 ROS 官方方式配置 apt 源。安装完成后，source /opt/ros/jazzy/setup.bash 只影响当前终端，因此新开窗口时还要重新执行。这里的关键是把 ROS_DISTRO、ros2 与 colcon 当作三个独立检查点：它们任何一个缺失，都说明后续失败更可能是环境问题而不是 Microduck 模型或代码问题。

# osrbot.github.io/microduck-ros2-isaac/zh/guide/installation
sudo apt update
sudo apt install \
  ros-jazzy-desktop \
  ros-jazzy-joint-state-publisher-gui \
  ros-jazzy-xacro \
  python3-colcon-common-extensions

source /opt/ros/jazzy/setup.bash
echo "ROS_DISTRO=$ROS_DISTRO"
command -v ros2
command -v colcon

9.4 只构建 description 包，先把模型带进 ROS 2

ROS 2 主页面没有要求初学者一开始构建整个工作空间，而是先选择 microduck_description。这一步只为 URDF、网格、关节限制、robot state publisher 与 RViz 建立最小可用基础，适合将"编译问题"和"物理仿真或策略问题"分离。下面命令必须在仓库根目录执行；source install/setup.bash 不可省略，它让当前终端优先发现刚才构建进 install/ 的包。输出应以 Summary: 1 package finished 收束，随后 ros2 pkg prefix 应返回当前工作空间下的安装路径。

# osrbot.github.io/microduck-ros2-isaac/zh/ros2/
cd ros2_ws
source /opt/ros/jazzy/setup.bash
colcon build --symlink-install --packages-select microduck_description
source install/setup.bash
ros2 pkg prefix microduck_description

9.5 版本差异要在启动前消化

社区页面以 ROS 2 Jazzy 为主，并明确说明 rviz_fullscreen:=true 是该项目面向 Jazzy 的 launch 参数；在 Humble 中把它传给 RViz 可能造成程序因不支持的 --fullscreen 选项退出。这里的关键是，"ROS 2 能运行"不是各发行版命令行参数完全一致的承诺。 若环境是 Humble，应只替换系统 setup 脚本并去掉该全屏参数；若教程目标是社区文档所验证的完整路径，则应优先使用 Ubuntu 24.04 与 Jazzy。先确定发行版与启动参数，能减少许多被误判为模型或显卡故障的问题。

一句话理解：ROS 2 路线先像搭一个透明的解剖台。读者可以看到模型与关节如何组织，却还没有碰真机电源和电机总线。先把"看见"和"控制"分开，是降低学习成本的最好办法。

10. 实用教程第二部分：从可视化到策略回放

10.1 RViz 的目标是校验语义

进入 ROS 2 工作空间后，首先应该验证的是模型语义，而不是追求界面效果：根坐标系方向是否正确，关节名称是否和 URDF/控制配置一致，正向关节运动是否符合直觉，传感器 frame 是否落在合理位置。对于任何以后想接实机的人，这一步都很关键，因为关节反向、零位错位和 IMU 轴定义错误，在仿真可视化中通常比在真实舵机上便宜得多。社区站点将"把鸭子请进 RViz""转镜头、动关节"和"跑 ROS 2 例程"分为连续章节，正说明这些检查应由浅入深完成。

10.2 RViz 与 14 个关节的最小验证

description 包构建后，先使用默认姿态打开 RViz，再加 use_gui:=true 启动 Joint State Publisher GUI。社区文档将完成条件定义为：RobotModel 没有红色网格错误，头部、身体、双腿与双脚齐全，Fixed Frame 使用 base_link 且模型稳定；随后用滑块轻微移动 head_yaw 和一个膝关节，确认 RViz 中只有正确的关节链发生变化。滑块会遵守 URDF 范围，但它不模拟重力、接触或电机扭矩，因此任何夸张姿态只能说明坐标与关节限制可视，绝不能用来证明真机步态稳定。

# osrbot.github.io/microduck-ros2-isaac/zh/ros2/
ros2 launch microduck_description view_microduck.launch.py use_gui:=true

# 在另一个已 source 的终端读取一次实际发布的关节消息
ros2 topic echo /joint_states --once

/joint_states 的 name 与 position 是这条验证链中的数据证据。社区教程期望 name 列表包含 14 个关节；拖动滑块后重新执行一次 ros2 topic echo /joint_states --once，相应 position 数值应改变。直观理解是，RViz 画面回答"模型是否按预期显示"，topic 回答"状态是否真的在 ROS 图中流动"。两项都成立，才说明可视化链路已经打通；只看到一个静态模型还不足以确认 publisher、TF 与关节状态能够协同工作。

10.3 先查 Visual mesh，再查 Collision mesh 与相机

RViz 排障页给出的顺序很值得保留：当模型看起来缺少零件时，先旋转镜头并重置视图，确认不是被遮挡；随后检查 RobotModel 的 Visual Enabled 与 Alpha，展开 Links 找有错误标记的网格，再查看 launch 终端中是否出现 package://microduck_description/meshes/... 路径失败。不要用 collision mesh 补 visual mesh，因为碰撞几何本来就是为了计算而简化的结构，不是外观资产。若模型只是走出 Orbit 相机焦点，则应调整视角或 reset，而不是立即修改 URDF。这种排障顺序把视图问题、资产路径问题和数据问题拆开，能避免重启碰运气。

10.4 Isaac 路线的环境闸门

Isaac 路线不是 ROS 2 安装的一个勾选项，而是另一套 GPU 物理仿真环境。社区文档先要求确认 nvidia-smi，再检查 Isaac Lab 的 isaaclab.sh，并允许用 ISAACLAB_DIR 指向非默认安装目录。只有这两个基本条件都成立，才值得下载公开上游资产并建立项目本地 ONNX Runtime 环境。这样做的原因是图形驱动、Isaac 版本、Python ABI 与模型运行时任何一项不匹配，都可能伪装成"策略无法走路"。

# osrbot.github.io/microduck-ros2-isaac/zh/guide/installation
export ISAACLAB_DIR=/path/to/IsaacLab
nvidia-smi
test -x "${ISAACLAB_DIR:-$HOME/rlgpu_ws/IsaacLab}/isaaclab.sh" \
  && echo "Isaac Lab launcher: OK"

./scripts/fetch_upstream.sh
./scripts/setup_isaac_python_env.sh

10.5 从仿真到真机不能省略中间层

仿真走通的最小闭环是：载入结构模型，获得状态，运行策略，观察动作与奖励或目标，再保存可追踪的工件；真机部署则额外引入供电、电机编号、总线、零位、IMU 安装方向、机械装配公差和散热问题。两者之间不是简单复制一个 ONNX 文件。部署前应将策略接口、参数文件和机器人模型固定为同一版本，并记录每次变化。仿真为错误提供低成本暴露机会，真机测试负责回答仿真无法证明的问题。

10.6 纯 RViz 例程适合查关节顺序，不适合判定动力学

社区例程页要求在 ROS 2 工作空间中额外构建 microduck_control_bridge 与 microduck_examples，随后可以启动 rviz_motion_demo.launch.py。其默认 showcase 会播放看向左右、点头、交替抬腿和鞠躬等动作；routine:=hello、routine:=walk 与 repeat:=false 可用于缩小测试范围。这一层的意义是把 14 关节命名、URDF 限位和 TF 关系放到可重复的动态序列中，而不是只检查某一个滑块。文档也明确说明它发布的是给 RViz 的 JointState 动画，不包含重力、接触、控制器或强化学习策略，因而不能据此推断真实物理世界的平衡能力。

# osrbot.github.io/microduck-ros2-isaac/zh/ros2/examples
cd ros2_ws
source /opt/ros/jazzy/setup.bash
colcon build --symlink-install --packages-select \
  microduck_description microduck_control_bridge microduck_examples
source install/setup.bash
ros2 launch microduck_examples rviz_motion_demo.launch.py routine:=walk speed:=1.5

10.7 ROS 到 Isaac 的闭环以 telemetry 为完成标志

...详情请参照古月居