# microduck_rust
**Repository Path**: offerexe/microduck_rust
## Basic Information
- **Project Name**: microduck_rust
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-16
- **Last Updated**: 2026-11-22
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Microduck · HD1910 + BNO085
master 已集成独立视觉功能,支持 ArUco 注视与停走跟随;部署与操作见[视觉模块部署与操作测试](docs/视觉功能_全新WSL与板端部署.md)。
**基于强化学习的小型双足机器人运行时,适配飞特 HD1910 舵机与 I²C BNO085 IMU。**
**简体中文** | [English](README.en.md)
[硬件与接口](#2-硬件与接口) · [模型与训练](#3-模型与训练) · [编译与部署](#4-编译与部署) · [使用说明](#5-使用说明) · [文档导航](#6-仓库结构与文档) · [致谢](#7-项目来源与致谢)
重新安装或更新软件:[重新部署软件](重新部署软件.md) → [校准](校准.md)。断连或刷机恢复见 [断开连接处理](断开连接处理.md)。
## 1. 项目简介
本工程 fork 自 [Pollen Robotics / microduck](https://github.com/pollen-robotics/microduck),在其 Rust 运行时基础上适配 **飞特 HD1910 电机**,并将 IMU 改为通过 **I²C(IIC)连接的 BNO085**。
本工程使用 **Radxa ZERO 3W(2 GB 内存、无 eMMC,硬件版本 v1.1.2)**,通过 TF 卡运行 **Armbian 26.8.1 精简版**。机器人通过 ONNX 运动策略控制关节,默认控制频率为 50 Hz。仓库包含运动控制、硬件驱动、手柄输入、命令行工具、网页舵机调试工具和部署脚本。
| 项目 | 本分支内容 |
| --- | --- |
| 舵机 | 15 路飞特 HD1910,使用飞特总线驱动 |
| IMU | BNO085,通过独立 I²C 总线读取姿态与角速度 |
| 运动控制 | Rust 控制循环与 ONNX 策略推理 |
| 操作方式 | 蓝牙手柄、板端命令行、SSH 交互式键盘控制 |
| 调试工具 | 舵机网页调试台、状态监控、电流记录 |
| 训练流程 | 在独立训练仓库中训练并导出 ONNX,再部署到本运行时 |
本仓库主要负责实机运行与部署;配套训练仓库为 [MHDuck/microduck_rl](https://github.com/MHDuck/microduck_rl)。可执行的动作取决于已部署模型和配置。
## 2. 硬件与接口
以下为本工程使用的硬件与系统,接口配置见 [deploy/robotd.toml](deploy/robotd.toml)。接线与设备路径需要和实际硬件对应。
| 硬件 / 参数 | 当前设置 |
| --- | --- |
| 主控 | Radxa ZERO 3W / RK3566 |
| 内存 | 2 GB |
| 板卡硬件版本 | v1.1.2 |
| 存储与启动 | 无 eMMC,使用 TF(microSD)卡 |
| 板端系统 | Armbian 26.8.1 精简版 / ARM64 Linux |
| 平台选择 | `platform.variant = "open_microduck"` |
| 舵机型号与数量 | 飞特 HD1910 × 15 |
| 舵机驱动 | `bus.driver = "hd1910"` |
| 舵机串口 | `/dev/ttyS4`,1 Mbps |
| IMU 驱动 | `imu.driver = "bno085"` |
| IMU 总线 | `/dev/i2c-3` |
| IMU 地址 | `0x4B`;驱动接受 `0x4A` 或 `0x4B` |
| 控制频率 | 50 Hz |
> [!IMPORTANT]
> [fanhao375/microduck-replica](https://github.com/fanhao375/microduck-replica) 中提到的 **B1 引导 + B1 DTB + Armbian 6.1.115 内核**方案不适用于本工程上述硬件与系统组合。本工程按 Armbian 26.8.1 精简版的流程部署,无需套用该 B1 引导和设备树替换方案。
BNO085 驱动当前按传感器 **+X 朝上、+Y 朝左、+Z 朝后**处理安装方向。更改安装方向时,需要同步调整 [坐标变换](robotd/src/bno085.rs),并检查机器人直立时的重力方向。
### 舵机编号
编号以 [关节映射](duck-control/src/model.rs) 为准:
| ID | 关节,按 ID 顺序 |
| --- | --- |
| 10 / 11 / 12 / 13 / 14 | 右髋偏航 / 右髋侧倾 / 右髋俯仰 / 右膝 / 右踝 |
| 20 / 21 / 22 / 23 / 24 | 左髋偏航 / 左髋侧倾 / 左髋俯仰 / 左膝 / 左踝 |
| 30 / 31 / 32 / 33 | 颈部俯仰 / 头部俯仰 / 头部偏航 / 头部侧倾 |
| 34 | 嘴部 |
ONNX 输出控制其中 14 个关节,嘴部单独控制。模型数组顺序不等于舵机 ID 顺序;部署前应核对 ID、零位、正方向以及训练使用的默认姿态。
## 3. 模型与训练
本工程的配套训练仓库为 **[MHDuck/microduck_rl](https://github.com/MHDuck/microduck_rl)**,训练环境配置、模型训练与 ONNX 导出方法请查阅该仓库。
训练工程上游来源为 [pollen-robotics/microduck_rl](https://github.com/pollen-robotics/microduck_rl),训练适配参考 [LuwuDynamics/xgoduck_rl](https://github.com/LuwuDynamics/xgoduck_rl)。
本运行时使用的模型接口为:
```text
obs [1, 61] → ONNX policy → actions [1, 14]
```
除输入输出维度外,观测顺序、关节顺序、默认姿态、动作缩放和电机参数也需要与训练一致。其他硬件平台的模型不能仅凭维度相同就视为兼容。
当前 [策略配置](deploy/robotd.toml) 引用:
| 配置项 | 模型 / 设置 | 用途 |
| --- | --- | --- |
| `walk` | `walk_hd1910_flat_v5.onnx` | 行走 |
| `sitstand` | `sitstand_hd1910.onnx` | 坐下 / 站起 |
| `stand` | `"none"` | 未启用独立站立策略 |
| `ground_pick`、`kick_left`、`kick_right`、`roulade` | `"none"` | 未启用对应动作策略 |
> [!IMPORTANT]
> 当前源码中的默认模型路径与随附文件尚未完全对齐:上述行走、坐站文件缺失,打包脚本还引用了缺失的 `policies/kp30.onnx`。部署前需要补齐对应文件,或同步调整策略路径与打包清单。仓库内其他 ONNX 文件不会自动替换这些模型。
模型放在 [policies/](policies/),板端路径通过 `/etc/robot/robotd.toml` 的 `[policy]` 配置。文件来源说明见 [policies/README.md](policies/README.md);打包清单见 [scripts/dev-push.sh](scripts/dev-push.sh)。修改策略路径后需重启 `robotd`。
## 4. 编译与部署
**重新部署顺序:安装 PC 依赖 → 配置 Rust / Zig → 部署 RK3566 环境 → 推送模型和配置 → 网页校准。** 以下命令同时适用于 PC 原生 Ubuntu 和 WSL Ubuntu;详细依赖用途、板端软件清单及排错见 [重新部署软件](重新部署软件.md)。
### 4.1 板端首次上电
将 **Armbian 26.8.1 精简版**写入 TF 卡,插入主板并上电。按首次启动提示设置**用户名、密码和 Wi-Fi 信息**,确认电脑可以通过 SSH 登录主板,且该账号具有 sudo 权限。
下文以 `radxa@192.168.2.90` 为例;请替换为首次启动时设置的用户名和主板实际 IP。
### 4.2 PC 端准备
在新的 **Ubuntu / WSL Ubuntu** 中拿到完整仓库,进入仓库根目录即可运行下一节的一条命令。电脑和板子需要联网,板端须已安装本项目支持的 Radxa 系统、开启 SSH,并有可执行 `sudo` 的账号。
脚本自动安装缺少的 APT 工具、Rust(至少 1.89)、ARM64 目标、Zig 构建环境及依赖,配置 SSH 公钥登录,并准备语音模型。Ubuntu 22.04 的 Python 3.10 或较新系统的 Python 3.14 会使用独立的 Python 3.12 语音环境,不替换系统 Python。无需提前执行 `setup-build.sh`、`ssh-copy-id` 或手动创建虚拟环境。
使用普通用户运行,按提示输入本机 sudo、板端登录和板端 sudo 密码;重启后的新 SSH 会话可能再次要求板端 sudo 密码。首次下载和编译耗时较长,失败后修复报错并重跑同一命令。默认使用国内 Rust / PyPI 镜像;已有镜像环境变量会保留。
### 4.3 一条命令部署
确认仓库中的 [deploy/robotd.toml](deploy/robotd.toml) 与机器人的串口、IMU、舵机和模型匹配,托稳机器人并退出旧键盘控制程序。在 **PC 的 Ubuntu / WSL 终端**中执行:
```bash
bash scripts/provision-board.sh \
--pause-btd-on-pair \
--name Ducky \
radxa@radxa.local
```
若 `.local` 无法解析,直接把最后一项换为实际地址,例如 `radxa@192.168.1.198`。电脑端会安装 mDNS 支持,但 WSL / 路由器是否允许组播仍取决于网络。
脚本完成本地构建、签名打包、板端环境初始化及重启等待、`servo-web` 安装、当前 `robotd` / `mediad` / `padd` / `configd` / ONNX / 控制脚本 / 配置同步与校验,以及板端语音依赖、音频库和模型检查。已有安装会先备份二进制、模型、脚本和配置到板端 `~/microduck-deploy-backups/before-provision.*/runtime.tar.gz`,再更新;不再需要补跑下一节的命令。`--pause-btd-on-pair` 在手柄配对期间暂停 `btd`;`--name Ducky` 设置机器人名称。
首次安装同时准备 NPU 环境、视觉模块的独立 OpenCV 环境和相机追加 180° 修正(保留零拷贝)。`vision-follow.service` 随系统启动,部署完成后打开 `http://板子IP:8091/`,即可使用 ArUco 识别、注视和前后跟随;网页也可切换 MicroDuck 模型检测,新安装的配置默认开启鸭子检测,NPU 不可用时尝试 CPU 模型。机器人动作仍需人工起身、设置基准并启动,具体操作见[视觉部署与操作测试](docs/视觉功能_全新WSL与板端部署.md)。重跑部署会保留已有相机方向配置和视觉内参。
视觉依赖按板端 Python 版本在电脑端下载、自动重试并缓存,随部署包上传后离线安装。中断后重新运行同一条部署命令即可,无需登录板子手动补装。
**会覆盖板端 `/etc/robot/robotd.toml` 并重启 robotd**,板端调好的参数应先同步回仓库。部署使用当前检出的源码与 `policies/` 模型,不自动拉取 Git 或训练新模型。语音安装验证成功后才切换 `~/microduck-speech/current`,默认仍为 `--speech off`;部署不会录音或发起运动测试。语音使用见 [speech/README.md](speech/README.md)。
### 4.4 后续仅更新模型和程序(可选)
完整部署已包含此步骤。以后只需更新程序和模型时,可以在 **PC 的 Linux / WSL 终端、仓库根目录**执行:
```bash
bash build.sh
sh xh_push.sh radxa@192.168.2.90
```
上传入口为仓库根目录的 [xh_push.sh](xh_push.sh)。`bash build.sh` 默认编译 `robotd`、`mediad`、`padd`、`configd`,输出到 `target/native/aarch64-unknown-linux-gnu/release/`,并自动准备 ARM64 GStreamer / udev sysroot。已有这四个程序的最新编译产物时,可直接上传。
上传脚本下发四个程序、`configd.service`、`policies/*.onnx`、控制 / 诊断脚本与 `deploy/robotd.toml`,校验四个二进制、`configd.service`、键盘脚本和配置的 SHA-256。更新时先停止 `robotd` / `mediad` / `padd`,替换文件并重新加载 systemd,再重启 `configd`、启动 `robotd`,最后恢复原本运行中的 `mediad` / `padd`;原本停止的客户端保持停止。不带 `--build` 时不会自动编译;也可用 `sh xh_push.sh --build <用户@地址>` 一次编译并上传(Cargo 缓存需齐全)。此入口用于已有运行环境的板子,其他系统服务定义和运行库由完整部署入口安装。
若 8080 网页的“初始化”提示“不支持 `system.restartRobot`”,旧版上传脚本曾遗漏 `configd` 及其服务配置,导致新网页仍连接旧版配置服务。使用当前仓库重跑 `./xh_push.sh --build <用户@地址>`,脚本会一起更新它们,授权 `mediad` 调用重启接口并重启 `configd`。完成后强制刷新网页,再重新 connect。
**上传会覆盖板端 `/etc/robot/robotd.toml`。** 板端调试后的参数应先同步回本地配置。后续更新程序或模型也使用上述命令。
上传前先托住机器人并退出旧 keycontrol;上传后重新运行键盘脚本。重启 robotd 不会让已经运行的 Python 进程加载新版界面。
兼容 Direct Update 的文件写保护:`xh_push.sh` 用 `lsattr` 检查本次覆盖的四个程序、`configd.service`、音频目录配置、`policies/*.onnx`、控制/诊断脚本及 `/etc/robot/robotd.toml`,对已有 `i` 属性的文件先执行 `sudo chattr -i`,远程安装结束后恢复 `sudo chattr +i`。部署失败或收到 HUP/INT/TERM 时也会尝试恢复;解锁失败会阻止安装,恢复失败会报错退出。原本未保护或新增的文件保持可写,未参与本次上传的文件及引导配置保持原状。原有 `robotd.toml` 和 `configd.service` 会分别保留一份 `.xh-backup`。
上传时也会安装 `mediad` 的 `60-duck-audio.conf` 并执行 `systemctl daemon-reload`。服务启动后由 systemd 创建并授权 `/var/lib/duck-audio`,使开启 `ProtectSystem=strict` 的媒体服务可以保存手机上传的音频。已有音频文件会保留;原本停止的 mediad 仍保持停止,下次启动时配置生效。
### 4.5 保护 TF 卡上的引导配置
本工程使用 TF 卡时曾遇到断电后 `/boot/armbianEnv.txt` 损坏、系统无法启动的情况。**部署完系统服务并确认主板正常启动后**,在板端执行:
```bash
sudo chattr +i /boot/armbianEnv.txt
lsattr /boot/armbianEnv.txt
```
确认属性中出现 `i`。它将文件设为不可变(immutable),阻止改写或删除,详见 [chattr 手册](https://man7.org/linux/man-pages/man1/chattr.1.html)。这能防止误写,但不能保证 TF 卡在异常断电后不损坏;使用完毕请先执行 `sudo poweroff`,待主板关机后再断电。
`provision-board.sh` 把 `i` 属性作为“已手工配置”的标记:有 `i` 时保留 `/boot/armbianEnv.txt` 和现有设备树文件,不解除保护;没有 `i` 时按新板流程配置设备树。两种情况都会继续安装设备别名、系统服务、程序、模型和语音环境。
后续确实需要重新配置引导参数或设备树时,先在板端解除保护,再运行部署或手工维护:
```bash
sudo chattr -i /boot/armbianEnv.txt
```
维护完成后,再执行 `sudo chattr +i /boot/armbianEnv.txt` 恢复保护。首次部署需要写入引导配置,请在部署完成后设置该属性。
### 4.6 检查运行状态
安装或更新后,在板端检查:
```bash
robotctl health
robotctl monitor
journalctl -u robotd -b -n 80 --no-pager
```
### 4.7 部署完成后进行网页校准
先托稳机器人,在 **RK3566 的 SSH 终端**运行:
```bash
sudo systemctl restart servo-web
```
启动调试台会停止 `robotd`、`padd`、`mediad` 和 `tofd`。在 **PC 浏览器**打开 [校准网页](http://192.168.2.90:8081/),确认设备已连接、位置持续刷新,标准整机应有 15 颗舵机在线。IP 按实机替换。
把真机摆成下图的零位:**双腿伸直、不外撇,脚底与小腿成直角,脖子竖直,头部平视朝前,嘴闭合**。手动摆动前先支撑并关闭相应舵机扭矩,不硬掰有力的关节。难以保持姿态时,可使用我们的校准工装辅助固定。

在网页“一键校准”区域选择 **“零位 2048(鸭子摆直)”**,核对校准列表,然后点击 **“一键校准”**,检查弹出的逐颗预览并确认。**工装实际固定的姿态必须与基准一致;若固定为折叠姿态,不能套用摆直零位,需按 [校准说明](校准.md#fixture) 选择匹配基准。** “全部回零位(2048)”是运动按钮,不是校准按钮。

上图是按钮位置示例,截图中的“断开”和保留姿态不是可执行校准的状态。校准完成后查看成功 / 失败列表,再按 [校准文档](校准.md) 验证和恢复控制;图中姿态、工装、完整界面及操作细节均在该文档中。
**校准保存与换板:** 实际零点写在每颗舵机的 EEPROM 中;板端默认的 `~/microduck/tools/servo-web/calib/eeprom-*.json` 是校准前的偏移备份,用于撤销。同一只 duck 只换 RK3566,校准随原舵机保留;另一只 duck 使用另一套舵机时,应重新校准,不能套用旧备份。实际目录、结果日志和迁移说明见 [校准文件与 RK3566 迁移](校准.md#calibration-migration)。
## 5. 使用说明
首次使能前应支撑好机器人,确认关节零位、IMU 姿态和模型配置正确。
### 蓝牙手柄
让手柄进入配对模式,在板端执行:
```bash
sudo robotctl pad pair
robotctl pad status
```
配对后由 `padd` 读取手柄输入,`robotd` 执行运动控制。常用操作如下,按键名称以 Xbox 手柄为例:
| 按键 | 功能 |
| --- | --- |
| Start | 启用 / 停用运动策略;停用策略不等于关闭舵机力矩 |
| 左摇杆 | 前进、后退、左右横移 |
| 右摇杆左右 | 转向 |
| Y | 切换头部控制模式 |
| B | 切换身体姿态模式 |
| 方向键下 | 坐下 / 站起,需要 `sitstand` 模型 |
| RT / LT | 嘴部与声音控制 |
动作按键存在并不表示相应模型已经配置。完整配对与排障说明见 [手柄文档](docs/robot/pair-a-gamepad.md)。
### SSH 键盘控制
在板端的交互式终端运行:
```bash
sudo systemctl stop padd
sudo python3 /opt/robot/daemon/current/scripts/keyboard-control.py
```
Enter 每次都会执行 `systemctl restart robotd`,重连并等待模型、IMU 就绪,再调用
`policy.stand` 指定的 StandUp 模型从倒地姿态起身;当前为 `standup_hd1910_v6.onnx`。
服务未启动、行走摔倒无法恢复,或倾倒 / 过流保护导致舵机失能时,排除故障并准备好起身空间后,均可按 Enter 重新走这套流程;已经站稳时也会重启。
起身直接运行 StandUp,不经过 HOME 或 SitStand。起身期间速度归零,暂缓倾倒锁定和
预测降力,过流保护仍按配置执行。完成判定为 IMU 就绪、读取成功且样本更新,重力 `z < -0.9`、角速度模长 `< 1 rad/s` 的有效样本累计达到 500 ms。
重复样本暂停计时,新的不稳定样本或 IMU 未就绪会清零;不要求学习到的站姿与 HOME 关节角一致。键盘端收到 `standup` 转为 `stand` 后提示“起身完成,可继续行走”。
12 秒未完成则锁定卸力,界面提示“起身失败,摆好姿势后按 Enter 重试”。服务未启动时也可先运行脚本,再按 Enter 恢复。
首次从旧版本升级到 Enter 起身和实时保护状态功能时,需同时部署配套 `robotd` 二进制与键盘脚本;后续仅调整界面文字时更新脚本即可。
自定义 `--socket` 只请求 StandUp,不操作默认 systemd 服务。
主界面每 0.2 秒刷新 VX、VY(m/s)和 VTHETA(rad/s)三轴指令速度,以及当前动作或故障。
故障自动另行打印完整原始消息,无需打开 C/L:ONNX 加载失败保留文件路径,舵机通信错误保留 ID、关节名(如有)和底层原因。
HD1910 批量读取失败时,每个失败周期额外只读诊断一颗舵机,轮询定位异常 ID;正常读取不增加查询。
尚未定位到异常舵机时明确提示正在诊断,不把批量通信失败猜成某颗舵机掉线。此功能需同时更新 robotd 二进制和脚本。
故障优先显示,Enter 恢复成功后清除;通信断开时停止发送运动指令,保留界面等待 Enter 重试。
上传后须退出旧键盘进程并重新运行,已有 Python 进程不会自动加载新脚本;`xh_push.sh` 会核验板端脚本的 SHA-256。
另外始终通过独立只读连接以 10 Hz 订阅 `robot.state`,每秒读取 `robot.health`,不依赖日志或 C。
按 C 打开详细日志,显示速度、实际策略、IMU 就绪/新鲜度、重力 z、倾倒配置及计时、电流和原始错误;
同时回放最近缓存的诊断消息,连接正常时开始电流 CSV 记录。再次按 C 关闭详情和记录;L 也关闭时返回简洁界面。
CSV 默认保存到当前工作目录的 `logs/`,可用 `--log-dir` 修改;CSV 保存电流、策略与指令速度等采样数据,不包含终端的原始错误日志。C 不改变运动指令,停车仍需按空格。
Enter 重启会结束当前 CSV 记录;恢复后如果 C 详情仍开启,先按 C 关闭,再按 C 开启新记录。
robotd 未连接时也能按 C 查看错误;状态流断开或超过 1 秒未更新会显示简短提示,重启后自动重连。
行走模式下按 **L** 单独开关运行日志,不开始电流 CSV:显示当前策略对应的 ONNX 文件名、策略/模型切换、每秒的指令与应用速度、IMU/保护状态,以及 robotd 已输出的运行日志。打开时回放最近 100 条消息;可直接检查 `walk → stand`、`rise → stand` 或 Enter 的 `standup → stand`,其中 `stand` 和 `standup` 都对应 `policy.stand` 的 StandUp 文件。服务尚未连接、等待 IMU 或 Enter 起身期间也可按 L。
C 与 L 分别开关;只看运行日志时关闭 C,关闭两者后恢复简洁界面。L 在头部/身体姿态模式仍用于侧倾调整,返回行走模式后再按 L 开关日志。原始日志以 robotd 当前日志级别实际输出的内容为准,不会因按 L 自动提高日志级别。
日志跟随进程随键盘脚本退出;自定义 socket 同样订阅实时状态,但不读取默认服务日志。
倾倒配置、超限计时、倒地确认、倾角恢复和预测降力过程的原始详情在 C/L 日志中显示。
`fall_debounce_ms = 200` 表示超限累计达到 200 ms 才确认倒地;恢复到角度阈值内会清零计时。行走模式正常站立/行走或 SitStand 的 rising 过程中确认倒地后,自动调用 StandUp,最多尝试 5 秒;成功回到站立,失败锁定卸力。rising 倒地时直接中断坐站起立,不必等满 1.5 秒。L 可查看 `rise → standup`、剩余时间和结果。
“确认倒地”与“保护锁定”分别提示,只有锁定触发才代表已请求全身卸力。
左右踢腿(Z/V)与前翻滚(X)执行期间暂停倾倒判定、清空倾倒计时,动作结束后恢复;预测降力不打断这些动作。
过流仍按配置处理,已经锁定的保护也不会被这些动作解除;修改此行为需要更新 robotd 二进制。
| 键盘 | 对应手柄 | 功能 |
| --- | --- | --- |
| Enter | — | 重启 robotd 并调用 StandUp 起身,成功后允许行走 |
| W / S、A / D | 左摇杆 | 行走模式下增减前后 / 横移速度,每次 0.10 m/s,范围 ±0.40 m/s;松开保持 |
| Q / E | 右摇杆左右 | 增减 VTHETA,每次 0.10 rad/s,范围 ±0.30 rad/s;松开保持转向,空格三轴归零 |
| T | 方向键下 | 启用后的坐下 / 站起切换;先归零速度,不打印关节位置日志 |
| Y / B | Y / B | 切换头部 / 身体姿态模式,再按同键返回行走;切换时速度归零 |
| G | A | 地面拾取(A 保留给方向控制) |
| Z / V | LB / RB | 左 / 右踢腿 |
| X | X | 前滚翻,长按连续翻滚 |
| R / F | RT / LT | 张嘴;R 触发叫声,F 按住播放 wheee;松开后关闭 |
| M 长按 3 秒 | 方向键上长按 | 切换步行 / 轮滑(rollers);键盘等待加载完成并显示 ONNX |
| P 长按 2 秒 | Select 长按 | 请求坐下并关机;无法执行坐下时直接卸力,请先托住机器人 |
| 空格 | — | 速度归零、姿态目标归零,并释放嘴部、声音和连续翻滚输入 |
| C | — | 打开 / 关闭详细日志,同时开始 / 停止电流 CSV 记录 |
| L(行走模式) | — | 独立开关运行日志,显示 ONNX、策略切换、起身/保护和原始日志;不开始电流 CSV |
| H | — | 开启 / 关闭行走发声;R/F 手动发声期间暂停自动语音 |
| Esc / Ctrl-C | — | 退出并卸力;默认连接下还会停止 `robotd`,退出前应托住机器人 |
头部模式:W/S 控制头部俯仰,A/D 控制头部偏航,I/K 控制颈部俯仰,J/L 控制头部侧倾。
每次调整 0.10 rad,范围 ±2.5 rad。身体姿态模式:W/S 调整高度(每次 0.001 m,范围
−0.025~+0.010 m),I/K 调整俯仰,J/L 调整侧倾(每次 0.02 rad,范围 ±0.2618 rad)。
姿态按键松开后保持目标,空格归零;这两个模式下机器人不接收行走速度。
终端没有按键松开事件,脚本通过按键重复估算长按;R/F/X 松开约 0.3 秒释放,
Enter、Y/B、T、G、Z/V、C、L(日志开关)、H 两次点按需间隔 1 秒以上,以免长按被当成反复切换。
M/P 单次长按只触发一次。动作缺少模型时显示拒绝原因,保留键盘会话。
轮滑使用独立的 `policy.roller`,当前为 `rollerswalk_v1.0.onnx`;切回步行使用原来的
`policy.walk`(`walk_v2.9.onnx`)。网页与 APP 也提供步行 / 轮滑按钮,使用同一个
`robot.setMode` 接口。部署与测试步骤见 [轮滑模式测试](docs/robot/web-control.md#轮滑模式测试)。
T 使用 `policy.sitstand`(当前为 `sitstand_v3.onnx`),不重启 robotd,也不代替 Enter 的倒地自主起身。
策略自动切换:普通 walk 的平滑速度指令幅值进入零速阈值(≤0.05)后,延时 1.5 秒切到 `policy.stand` 的 StandUp;期间重新移动会重置计时。sitstand 的 rising 运行 1.5 秒后结束,零速时直接切到 StandUp,不额外等待。坐下时继续由 sitstand 保持坐姿。常规站立/行走中发起的踢腿、翻滚结束后也交回自动策略选择;零速接 StandUp,有移动指令则接 walk。拾取结束后先接 walk,再按同样的 1.5 秒零速规则切到 StandUp。StandUp 持续推理控制姿态,不冻结最后一帧;Enter 的 12 秒恢复超时与这些切换计时是独立的。
先停 `padd` 是为了避免手柄与键盘争抢指令;恢复手柄控制时执行 `sudo systemctl start robotd padd`。
`--walk-voice` 可在启动时开启行走发声,`--voice-sound-only` 关闭自动语音的嘴部动画,
手动 R/F 仍控制嘴部。独立语音、视觉诊断和 StandUp 测试见
[本地部署增量](docs/LOCAL_CUSTOMIZATIONS.md)。
### 网页调试与保护设置
[servo-web](tools/servo-web/README.md) 用于舵机调试。启动该服务会停止 `robotd`、`padd`、`mediad` 和 `tofd`。调试结束后,支撑好机器人再恢复手柄控制:
```bash
sudo systemctl stop servo-web
sudo systemctl start robotd padd
```
当前仓库的 [deploy/robotd.toml](deploy/robotd.toml) 中,`fall_protection = true`、`fall_gravity_z = -0.5`、`fall_debounce_ms = 200`;`overcurrent_protection = false`。板端以 `/etc/robot/robotd.toml` 为准,实际生效的倾倒开关与计时可在 C/L 日志中查看。
| 机制 | 判定和动作 |
| --- | --- |
| 倾倒起身与锁定 | 开启 `fall_protection` 后,IMU 就绪且有新样本时,机身重力 `z > fall_gravity_z` 累计达到 `fall_debounce_ms`,确认倒地。行走模式正常站立/行走或 SitStand 的 rising 过程中,自动归零速度并运行 StandUp,最多 5 秒;失败后锁定并请求全身卸力。缺少起身模型或不在可自动恢复的状态时直接锁定。扶正不会自动解除锁定 |
| 预测倾倒降力 | 仅在 `fall_protection = false` 且 `limp_fall = true`、策略处于可触发状态时运行。使用 IMU 重力和角速度预测继续倾倒,先降低增益;落地稳定或降力超时后回 HOME,再交回策略,不是锁定卸力 |
| 过流锁定 | 开启 `overcurrent_protection` 后,使用舵机供电电流估算和连续拍数确认,触发后锁定并请求卸力;当前阈值配置为 18 A、连续 2 拍,但开关关闭,不执行这项锁定 |
倒地确认的 200 ms 按有效样本累计;新的正常角度样本或 IMU 未就绪会清零,重复样本暂停累计。确认倒地后,自动起身的 5 秒按实际经过时间计算,IMU 重复、读取失败或新的速度指令都不会延长它。完成判定与 Enter 相同:有效样本累计直立(`z < -0.9`)且角速度模长 `< 1 rad/s` 达到 500 ms。主界面依次显示“倾倒中”“起身中”,成功显示“站立中”,失败持续显示“起身失败,摆好姿势后按 Enter 重试”。
配置中的这项只控制倒地确认消抖,不是起身超时:
```toml
fall_debounce_ms = 200 # 200 ms 有效样本后确认倒地,随后开始 5 秒起身尝试
```
自动起身时长由 `robotd/src/main.rs` 的 `AUTO_STAND_UP_TIMEOUT` 控制,当前 5 秒;keycontrol 还有独立的 `AUTO_STANDUP_TIMEOUT_S = 5.0`,持续处于 `standup` 超时会主动请求卸力。调整时长需要同步这两个值,重新编译并更新脚本。Enter 手动重启起身仍为最多 12 秒。
一次倒地只自动尝试一次:即使短暂满足完成判定,随后再次倒地,也会锁定卸力,不会自动重开 5 秒。成功后重新发出行走指令并在直立状态实际运行 walk,或重新操作 T 坐站,才允许下一次自动恢复。失败状态通过实时订阅上报,不依赖日志;失败后键盘停止发送运动指令,W/T 不会重新上力,摆好姿势后按 Enter 重启重试。起身期间过流保护仍按配置执行。
本次升级需同步 robotd 二进制、键盘脚本和配置,再重启服务;仅更新脚本不会启用自动起身。使用 `xh_push.sh` 更新时,应先修改本地 `deploy/robotd.toml`,避免上传覆盖板端调整。
预测降力使用另外一组参数:默认已倾斜到 `z > -0.90`,且继续倾倒、预测 300 ms 后 `z > -0.5`,累计满足 60 ms 后触发。`limp_fall_debounce_ms` 是预测触发确认时间,`limp_fall_max_ms` 是降力最长时间(默认 1500 ms),都不等于 `fall_debounce_ms`。当前开启倾倒锁定,所以这条预测降力流程不运行。
过流阈值需结合实际电源和负载标定。独立舵机调试工具不经过 robotd 的这套保护。
## 6. 仓库结构与文档
| 路径 | 内容 |
| --- | --- |
| [robotd/](robotd/) | 运动控制服务、动作调度与 BNO085 接入 |
| [duck-control/](duck-control/) | 舵机总线、观测构建、ONNX 推理与保护逻辑 |
| [robotd-params/](robotd-params/) | 运行参数与配置解析 |
| [padd/](padd/)、[robotctl/](robotctl/)、[duckctl/](duckctl/) | 手柄服务、板端 CLI、电脑端客户端 |
| [configd/](configd/)、[btd/](btd/)、[mediad/](mediad/)、[tof/](tof/) | 网络与配对、BLE、音视频、ToF 服务 |
| [policies/](policies/) | ONNX 策略与来源说明 |
| [deploy/](deploy/)、[scripts/](scripts/) | 板端配置、安装与部署脚本 |
| [tools/servo-web/](tools/servo-web/) | 舵机网页调试工具 |
| [docs/](docs/) | 操作、架构与开发文档 |
常用文档:[重新部署软件](重新部署软件.md) · [校准](校准.md) · [中文入门指南](Microduck入门指南.md) · [故障排除](故障排除.md) · [断开连接处理](断开连接处理.md) · [命令速查](docs/robot/cheatsheet.md) · [系统架构](docs/design/architecture.md) · [开发指南](CONTRIBUTING.md) · [文档索引](docs/README.md)。
部分文档沿用上游平台和示例参数;本分支的硬件配置以当前源码及 `deploy/robotd.toml` 为准,已部署设备以 `/etc/robot/robotd.toml` 为准。
## 7. 项目来源与致谢
感谢以下项目作者与贡献者。本工程的来源与参考关系如下:
| 项目 | 关系 |
| --- | --- |
| [pollen-robotics/microduck](https://github.com/pollen-robotics/microduck) | 本工程的上游仓库,提供 Microduck 运行时基础 |
| [fanhao375/microduck](https://github.com/fanhao375/microduck) | 硬件与运行时适配参考 |
| [LuwuDynamics/xgoduck_runtime_arduino](https://github.com/LuwuDynamics/xgoduck_runtime_arduino) | 运行时适配参考 |
| [pollen-robotics/microduck_rl](https://github.com/pollen-robotics/microduck_rl) | 训练工程来源 |
| [LuwuDynamics/xgoduck_rl](https://github.com/LuwuDynamics/xgoduck_rl) | 训练适配参考 |
## 8. 参与贡献与许可
欢迎通过 GitHub Issues 反馈问题,或通过 Pull Request 提交改进。反馈实机问题时,请附上主板与系统版本、舵机和 IMU 型号、相关配置、模型文件名以及复现步骤。开发约定见 [CONTRIBUTING.md](CONTRIBUTING.md)。
根目录保留上游的 [Apache License 2.0](LICENSE)。部分文件另有许可声明:[BNO085 驱动](robotd/src/bno085.rs) 和 [网页调试传感器模块](tools/servo-web/board_sensors.py) 标注为 **GPL-3.0-or-later**,相关来源和许可副本见 [NOTICE-board.md](tools/servo-web/NOTICE-board.md)。
请同时查阅各文件、第三方组件及模型的许可说明;不能将根目录 LICENSE 视为所有内容的统一许可。本 README 不变更现有版权或授权声明。