Microduck power hub

MicroDuck Observer

面向 MicroDuck 实机的观测、标定与控制平台。将网页调试、Android 蓝牙遥控、传感器采集、舵机执行和 ONNX 策略运行统一接入 Rust 控制后端，让界面显示的状态、模型使用的反馈和机器人执行的命令来自同一条控制链路。

本仓库维护机器人端服务、Web 工作台、模型运行合同及实测证据。Android App 在独立项目 DuckLink 中维护。

手柄自定义控制

侧栏「手柄设置」支持8个动作键自定义、取消绑定及恢复默认，网页与板端实体手柄共用持久化配置；固定急停/停止及起身长按保留。当前为本地实现，未部署实机，见 手柄映射说明。

模型管理

侧栏独立「模型管理」页面支持显式模型选择、默认执行模板、完整metadata和部分官方manifest导入、上一版本回退，姿态工作台保持原布局。同合同的新权重无需重编后端；停止控制后校验与预热，导入不自动启用。当前为本地实现，尚未部署实机。操作、接口及验证方法见 模型管理说明。

功能规划

• 自主行动功能规划：2026-10-19确认，第一版模式切换、人工接管、6秒限时起身及后续感知路线；尚未实现。

硬件设计资料

硬件工程、BOM、加工文件、效果图与设计检查统一存放在 hardware/，后续硬件模块也从该目录继续。当前电源Hub为 Rev N / ECO1无开关＋C1版本，内含立创EDA、KiCad源文件、Gerber及采购清单；源检查通过，立创客户端与实物验证状态见版本说明。实测主记录继续维护在 docs/实测记录/。

界面预览

Observer 主控工作台

将 3D 姿态、IMU 曲线、网页虚拟手柄与 15 个舵机反馈放在同一工作台。中央保留 3D 视图和可读的手柄控制区；高度不足时控制区滚动，窄屏按列重排，手柄改用分区布局，避免文字和按钮被强行缩小。

截图来自 2026-10-14 最新 Web 源码本地页面，浏览器视口 1920×1080 CSS px、100% 缩放、DPR 1，图片也是1920×1080。处于未连接状态，3D 是参考模型，曲线和关节数值等待设备反馈，动作按钮禁用。另已检查 1280×720、1366×768 和 390px 窄屏；窄屏截图为完整滚动页面。

网页手柄支持鼠标和多指触控：左摇杆行走 / 转向、右摇杆控制头部，松开归零。当前按键如下：

翻滚入口保留在“按键说明与诊断”中。网页完整身体与头部控制需要配套 Rust 后端；当前手柄改动仅完成本地开发，未部署主板或通过实机验收。物理手柄配置与按键差异见 手柄使用说明。

DuckLink 控制 App

横屏操作页采用左侧行走轮盘、中间动作技能、右侧头部轮盘；顶部显示连接状态、电量与急停，底部提供速度和身体姿态。倒地起身是技能就绪入口，“嘎一下”独立提供嘴部与叫声控制。设备页支持多设备连接与切换、Observer 版本查看和 OTA 更新。

截图为已发布的 App 0.9.61 在 Android 模拟器中的未连接界面，屏幕 2160×1240 px、440 dpi（约785×451 dp）；图中含安卓导航区域。以上截图用于展示各自注明版本的界面，不代表整机动作验收结果。

重构重点

系统架构

flowchart TB
    Web["Web 工作台<br/>Vue 3 · TypeScript · Three.js · ECharts"]
    App[DuckLink Android App]
    Gamepad["T4 Nova Lite 手柄<br/>本地开发 · 待实测"]
    Gamepad -->|BlueZ HID / Linux evdev| API
    Web <-->|HTTP / WebSocket| API
    App <-->|认证加密 BLE · BlueZ| API

    subgraph Board[机器人主板 · Linux ARM64]
        API["Rust 主服务<br/>Axum / Tokio · 控制会话与动作入口"]
        Telemetry["遥测缓存<br/>最新样本 · 时间戳 · 有效性 · 日志"]
        Bus["舵机总线唯一拥有者<br/>反馈读取 · 目标写入 · 校准 · 卸力"]
        Policy["模型运行器<br/>ONNX Runtime CPU · 模型合同 · 技能切换"]
        IMU[IMU 独立采集线程]
        State["持久状态<br/>共享标定 · 模型增益 · BLE 身份"]
        Helpers["受限 Rust 辅助服务<br/>Wi-Fi 管理 · 系统电源"]
        API <-->|状态订阅| Telemetry
        API -->|显式控制命令| Bus
        Bus <-->|观测与目标| Policy
        Bus -->|关节反馈| Telemetry
        IMU --> Telemetry
        IMU -->|姿态与角速度| Policy
        API <--> State
        Policy -->|读取执行配置| State

控制链路。 网页、App 和已配置的物理手柄发出意图，服务检查当前任务与控制会话，再由总线拥有者执行。停止保持与卸力是不同操作；方向控制携带会话和递增序号，过期方向命令归零。动作、使能与模型推理由明确的用户操作启动，打开页面或恢复连接不会自动启动运动。

模型链路。 当前模型常用 61 维观测、14 维动作，嘴部为独立舵机控制。原生技能运行路径在控制循环中完成反馈、观测、推理与目标写入；兼容路径使用独立推理线程和最新结果槽。两条路径按各自合同执行，不将所有模型强行套用同一种滤波、增益或切换方式。机械范围、编码转换及故障处理集中在机器人端，客户端不重复实现策略。

观测链路。 IMU 独立采集，关节反馈与模型控制共用串口拥有者，服务对外发布主题化遥测。WebSocket 按展示需要订阅最新数据，HTTP 提供元信息、快照、标定和控制接口。硬件采集频率、模型执行频率与浏览器展示频率分别管理；慢客户端不会要求服务积压全部传感器历史帧。

运行与工具。 机器人主服务、Wi-Fi 和电源辅助程序均为 Rust；推理使用原生 ONNX Runtime 动态库。Python 仅用于打包、部署、只读分析及部分测试工具，不作为机器人控制服务运行。音频调用系统 ALSA 播放器；可选摄像头由 Rust Observer 管理 V4L2/FFmpeg 子进程，与主服务共用 systemd 单元及 HTTP 端口，不运行 Python 摄像头服务。摄像头开关默认关闭，选择保存在主板；当前部署状态见实测记录。

主要功能

• 观测工作台： 3D 身体姿态与 15 关节反馈、Roll/Pitch/Yaw、IMU 曲线、舵机电压/温度/电流/状态、CPU/内存/温度与部署版本。
• 标定： 关节显示零位与方向、IMU 安装方向和参考姿态、Roll/Pitch 归零、显式硬件中位校准。显示标定与 EEPROM 写入分别处理。
• 实机控制： 坐下预备、站立接行走、双摇杆网页手柄、速度设置、倒地起身、拾取、翻滚、左右脚踢球、零位，以及主板扬声器配合张闭嘴的“嘎一下”。
• 主板直连手柄（开发版）： Linux evdev 输入复用控制后端；App BLE 与手柄连接可共存，显式动作获取控制权。物理手柄以双摇杆回中后的 LB+A 站立、LB+Y 倒地起身，Back 全局卸力。默认关闭，蓝牙配对、设备映射和双连接稳定性待实测，详见 配置与验收要求。
• 诊断： 控制状态与技能进度、反馈暂停、故障帧和会话记录、串口收发证据、日志筛选及 JSONL 导出。
• 连接与管理： Web 自动重连及断线原因、BLE 绑定与认证、Wi-Fi 管理、Web 地址获取、确认后的主板关机/重启。

功能已接入服务不等于对应动作已在每种装配和姿态下通过验收；目前倒地起身和部分运动效果仍有用户反馈问题。

硬件 BOM 与接入概况

下表为当前实物配置摘要，不是完整机械采购表。针脚、电平、供电和改焊细节以对应实测页为准。

实测摘要

实测、软件回归和仿真分别记录，完整证据见 实测索引。以下摘录截至 2026-10-12 的结果：

最近相关证据：网络与网页核查 · 后端部署。历史采集基准保留在实测文档中，不用于描述当前所有路径的实时性能。

本地开发

需要 Linux / WSL、Rust 工具链，以及 Node.js 22.12+。生产 BLE 使用 Linux BlueZ。ONNX 推理需安装匹配的原生 ONNX Runtime，并设置 ORT_DYLIB_PATH。

启动隔离模拟服务：

cd backend-rust
MICRODUCK_SOURCE=simulation \
MICRODUCK_BLE_ENABLED=0 \
MICRODUCK_BIND=127.0.0.1:8877 \
cargo run --locked --bin microduck-observer

另一个终端启动网页：

cd frontend
npm ci
npm run dev

打开 http://127.0.0.1:5173，连接 API http://127.0.0.1:8877。模拟数据有明确来源标识，不连接实物总线。生产构建的 frontend/dist/ 由主服务直接提供，默认部署 Web 端口为 8877。

常用检查：

cd frontend
npm test
npm run build

cd backend-rust
cargo test --locked --bins
cargo build --release --locked --bins

外部模型 fixture、原生推理库和实机测试有独立环境要求；详细配置见 Rust 后端、协议 和 当前工具。

部署与目录

发布流程见 Rust 部署。后端更新使用 tools/deploy-runtime.py；网页独立发布使用 tools/deploy-frontend.py；Wi-Fi / 电源辅助迁移使用 tools/deploy-service-rust.py。构建与候选验证完成后，确认机器人空闲、15 个舵机卸力再部署；安装器保留现有配置并验证回滚来源。

许可与资源来源

平台代码采用 Apache-2.0。机器人外形与部分策略资源来自公开项目，平台重构与资源来源分别记录：

• 3D 网格与模型描述的来源和转换说明见 模型 NOTICE，保留随附许可证。
• 当前部分策略权重来自 kissqy/Microduck-kissqy，具体提交、权重哈希、观测合同和执行配置以 models/*.metadata.json 为准；自行训练的权重也在对应 metadata 中区分。

接入资源不代表本项目训练或原创全部模型；具体模型文件名兼容历史接口，不用于判断当前权重版本。上游资源的许可和署名随资源保留。