# fanhao375/microduck-replica architecture

> Architecture diagram of the GitHub repository fanhao375/microduck-replica, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fanhao375/microduck-replica
- Repository: https://github.com/fanhao375/microduck-replica

## Overview

Microduck 复刻是一个围绕双足机器鸭的复刻与实验仓库：从仿真模型辅助机械分析，到强化学习训练，再到舵机、IMU 的台架调试。图中保留了 README 重点介绍的训练、网页调试、IMU 固件和机械分析分支。未采样的模块只按 README 与文件树描述；箭头仅表示文档明确的调用或数据交互。

Main entry points: [`software/training/src/mjlab_microduck/train_cli.py`](https://github.com/fanhao375/microduck-replica/blob/master/software/training/src/mjlab_microduck/train_cli.py) (训练入口), [`tools/servo-web/server.py`](https://github.com/fanhao375/microduck-replica/blob/master/tools/servo-web/server.py) (调试台服务), [`hardware/imu_to_dxl/firmware/Core/Src/main.c`](https://github.com/fanhao375/microduck-replica/blob/master/hardware/imu_to_dxl/firmware/Core/Src/main.c) (固件主循环), [`software/training/src/mjlab_microduck/tasks`](https://github.com/fanhao375/microduck-replica/tree/master/software/training/src/mjlab_microduck/tasks) (训练任务配置)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["策略训练"]
  node_task_configs["训练任务配置"]
  node_mdp["MDP 函数<br/>[mdp.py]"]
  node_actuators["执行器模型"]
  node_train_cli["训练入口<br/>[train_cli.py]"]
  node_hf_jobs["远程训练提交<br/>[hf_jobs.py]"]
  node_training_scripts["策略工作流工具"]
end

subgraph group_console["网页调试"]
  node_web_server["调试台服务<br/>[server.py]"]
  node_servo_protocol["飞特协议驱动<br/>[feetech.py]"]
  node_sim_bus["舵机总线模拟器<br/>[sim_bus.py]"]
  node_imu_bridge["IMU 观测桥<br/>[imu_bridge.py]"]
end

subgraph group_imu["IMU 固件"]
  node_imu_main["固件主循环<br/>[main.c]"]
  node_board["板级接口<br/>[board.c]"]
  node_protocol["总线协议解析<br/>[protocol.c]"]
  node_control_table["寄存器映射<br/>[control_table.c]"]
  node_imu_sensor["IMU 传感器处理<br/>[imu.c]"]
  node_lsm_driver["LSM6DSV16X 驱动<br/>[lsm6dsv16x_reg.c]"]
end

subgraph group_bench["舵机台架"]
  node_servo_cli["HD1910 测试 CLI<br/>[main.rs]"]
  node_servo_lib["HD1910 驱动库<br/>[lib.rs]"]
  node_sts_cli["STS3215 测试工具<br/>[main.rs]"]
  node_sts_driver["STS 总线驱动<br/>[sts.rs]"]
end

subgraph group_mechanical["机械分析"]
  node_model_analysis["装配接触分析<br/>[fold_contact.py]"]
  node_assembly_tools["装配模型工具"]
end

node_engineer(("工程师"))
node_mjlab["mjlab 仿真框架"]
node_browser(("浏览器操作员"))
node_servo_bus["舵机总线"]
node_imu_device["LSM6DSV16X"]
node_mjcf["MJCF 模型输入"]

node_engineer -->|"启动训练"| node_train_cli
node_train_cli -->|"选择任务"| node_task_configs
node_train_cli -->|"运行训练"| node_mjlab
node_task_configs -->|"配置函数"| node_mdp
node_task_configs -->|"配置执行器"| node_actuators
node_train_cli -.->|"提交远程任务"| node_hf_jobs
node_engineer -->|"运行策略工具"| node_training_scripts
node_training_scripts -->|"仿真推理"| node_mjlab
node_browser -->|"发送操作"| node_web_server
node_web_server -->|"读写舵机"| node_servo_protocol
node_servo_protocol -->|"收发数据"| node_servo_bus
node_web_server -.->|"模拟总线"| node_sim_bus
node_web_server -.->|"读取姿态"| node_imu_bridge
node_imu_bridge -.->|"观测固件状态"| node_imu_main
node_imu_main -->|"收发总线与日志"| node_board
node_imu_main -->|"解析与应答"| node_protocol
node_imu_main -->|"轮询传感器"| node_imu_sensor
node_protocol -->|"读取寄存器"| node_control_table
node_control_table -->|"读取快照"| node_imu_sensor
node_imu_sensor -->|"驱动传感器"| node_lsm_driver
node_lsm_driver -->|"读取传感数据"| node_imu_device
node_engineer -->|"执行台架测试"| node_servo_cli
node_servo_cli -->|"调用驱动"| node_servo_lib
node_servo_lib -->|"收发数据"| node_servo_bus
node_engineer -->|"执行台架测试"| node_sts_cli
node_sts_cli -->|"调用总线操作"| node_sts_driver
node_sts_driver -->|"收发数据"| node_servo_bus
node_engineer -->|"分析装配接触"| node_model_analysis
node_model_analysis -->|"读取模型"| node_mjcf
node_engineer -->|"处理装配模型"| node_assembly_tools

click node_task_configs "https://github.com/fanhao375/microduck-replica/tree/master/software/training/src/mjlab_microduck/tasks"
click node_mdp "https://github.com/fanhao375/microduck-replica/blob/master/software/training/src/mjlab_microduck/tasks/mdp.py"
click node_actuators "https://github.com/fanhao375/microduck-replica/tree/master/software/training/src/mjlab_microduck/actuator"
click node_train_cli "https://github.com/fanhao375/microduck-replica/blob/master/software/training/src/mjlab_microduck/train_cli.py"
click node_hf_jobs "https://github.com/fanhao375/microduck-replica/blob/master/software/training/src/mjlab_microduck/hf_jobs.py"
click node_training_scripts "https://github.com/fanhao375/microduck-replica/tree/master/software/training/scripts"
click node_web_server "https://github.com/fanhao375/microduck-replica/blob/master/tools/servo-web/server.py"
click node_servo_protocol "https://github.com/fanhao375/microduck-replica/blob/master/tools/servo-web/feetech.py"
click node_sim_bus "https://github.com/fanhao375/microduck-replica/blob/master/tools/servo-web/sim_bus.py"
click node_imu_bridge "https://github.com/fanhao375/microduck-replica/blob/master/tools/servo-web/imu_bridge.py"
click node_imu_main "https://github.com/fanhao375/microduck-replica/blob/master/hardware/imu_to_dxl/firmware/Core/Src/main.c"
click node_board "https://github.com/fanhao375/microduck-replica/blob/master/hardware/imu_to_dxl/firmware/Core/Src/board.c"
click node_protocol "https://github.com/fanhao375/microduck-replica/blob/master/hardware/imu_to_dxl/firmware/Core/Src/protocol.c"
click node_control_table "https://github.com/fanhao375/microduck-replica/blob/master/hardware/imu_to_dxl/firmware/Core/Src/control_table.c"
click node_imu_sensor "https://github.com/fanhao375/microduck-replica/blob/master/hardware/imu_to_dxl/firmware/Core/Src/imu.c"
click node_lsm_driver "https://github.com/fanhao375/microduck-replica/blob/master/hardware/imu_to_dxl/firmware/Drivers/LSM6DSV16X/lsm6dsv16x_reg.c"
click node_servo_cli "https://github.com/fanhao375/microduck-replica/blob/master/tools/FeeTech_HD1910M_Servo/src/main.rs"
click node_servo_lib "https://github.com/fanhao375/microduck-replica/blob/master/tools/FeeTech_HD1910M_Servo/src/lib.rs"
click node_sts_cli "https://github.com/fanhao375/microduck-replica/blob/master/tools/sts3215Servo_testtool/src/main.rs"
click node_sts_driver "https://github.com/fanhao375/microduck-replica/blob/master/tools/sts3215Servo_testtool/src/sts.rs"
click node_model_analysis "https://github.com/fanhao375/microduck-replica/blob/master/tools/fold_contact/fold_contact.py"
click node_assembly_tools "https://github.com/fanhao375/microduck-replica/tree/master/scripts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_task_configs,node_mdp,node_actuators,node_train_cli,node_hf_jobs,node_training_scripts toneBlue
class node_web_server,node_servo_protocol,node_sim_bus,node_imu_bridge toneAmber
class node_imu_main,node_board,node_protocol,node_control_table,node_imu_sensor,node_lsm_driver toneMint
class node_servo_cli,node_servo_lib,node_sts_cli,node_sts_driver toneRose
class node_model_analysis,node_assembly_tools,node_engineer,node_mjlab,node_browser,node_servo_bus,node_imu_device,node_mjcf toneIndigo
```

## Components

### 策略训练

- [训练任务配置](https://github.com/fanhao375/microduck-replica/tree/master/software/training/src/mjlab_microduck/tasks): `software/training/src/mjlab_microduck/tasks`
- [MDP 函数](https://github.com/fanhao375/microduck-replica/blob/master/software/training/src/mjlab_microduck/tasks/mdp.py): `software/training/src/mjlab_microduck/tasks/mdp.py`
- [执行器模型](https://github.com/fanhao375/microduck-replica/tree/master/software/training/src/mjlab_microduck/actuator): `software/training/src/mjlab_microduck/actuator`
- [训练入口](https://github.com/fanhao375/microduck-replica/blob/master/software/training/src/mjlab_microduck/train_cli.py): `software/training/src/mjlab_microduck/train_cli.py`
- [远程训练提交](https://github.com/fanhao375/microduck-replica/blob/master/software/training/src/mjlab_microduck/hf_jobs.py): `software/training/src/mjlab_microduck/hf_jobs.py`
- [策略工作流工具](https://github.com/fanhao375/microduck-replica/tree/master/software/training/scripts): `software/training/scripts`

### 网页调试

- [调试台服务](https://github.com/fanhao375/microduck-replica/blob/master/tools/servo-web/server.py): `tools/servo-web/server.py`
- [飞特协议驱动](https://github.com/fanhao375/microduck-replica/blob/master/tools/servo-web/feetech.py): `tools/servo-web/feetech.py`
- [舵机总线模拟器](https://github.com/fanhao375/microduck-replica/blob/master/tools/servo-web/sim_bus.py): `tools/servo-web/sim_bus.py`
- [IMU 观测桥](https://github.com/fanhao375/microduck-replica/blob/master/tools/servo-web/imu_bridge.py): `tools/servo-web/imu_bridge.py`

### IMU 固件

- [固件主循环](https://github.com/fanhao375/microduck-replica/blob/master/hardware/imu_to_dxl/firmware/Core/Src/main.c): `hardware/imu_to_dxl/firmware/Core/Src/main.c`
- [板级接口](https://github.com/fanhao375/microduck-replica/blob/master/hardware/imu_to_dxl/firmware/Core/Src/board.c): `hardware/imu_to_dxl/firmware/Core/Src/board.c`
- [总线协议解析](https://github.com/fanhao375/microduck-replica/blob/master/hardware/imu_to_dxl/firmware/Core/Src/protocol.c): `hardware/imu_to_dxl/firmware/Core/Src/protocol.c`
- [寄存器映射](https://github.com/fanhao375/microduck-replica/blob/master/hardware/imu_to_dxl/firmware/Core/Src/control_table.c): `hardware/imu_to_dxl/firmware/Core/Src/control_table.c`
- [IMU 传感器处理](https://github.com/fanhao375/microduck-replica/blob/master/hardware/imu_to_dxl/firmware/Core/Src/imu.c): `hardware/imu_to_dxl/firmware/Core/Src/imu.c`
- [LSM6DSV16X 驱动](https://github.com/fanhao375/microduck-replica/blob/master/hardware/imu_to_dxl/firmware/Drivers/LSM6DSV16X/lsm6dsv16x_reg.c): `hardware/imu_to_dxl/firmware/Drivers/LSM6DSV16X/lsm6dsv16x_reg.c`

### 舵机台架

- [HD1910 测试 CLI](https://github.com/fanhao375/microduck-replica/blob/master/tools/FeeTech_HD1910M_Servo/src/main.rs): `tools/FeeTech_HD1910M_Servo/src/main.rs`
- [HD1910 驱动库](https://github.com/fanhao375/microduck-replica/blob/master/tools/FeeTech_HD1910M_Servo/src/lib.rs): `tools/FeeTech_HD1910M_Servo/src/lib.rs`
- [STS3215 测试工具](https://github.com/fanhao375/microduck-replica/blob/master/tools/sts3215Servo_testtool/src/main.rs): `tools/sts3215Servo_testtool/src/main.rs`
- [STS 总线驱动](https://github.com/fanhao375/microduck-replica/blob/master/tools/sts3215Servo_testtool/src/sts.rs): `tools/sts3215Servo_testtool/src/sts.rs`

### 机械分析

- [装配接触分析](https://github.com/fanhao375/microduck-replica/blob/master/tools/fold_contact/fold_contact.py): `tools/fold_contact/fold_contact.py`
- [装配模型工具](https://github.com/fanhao375/microduck-replica/tree/master/scripts): `scripts`

### Other components

- **工程师**
- **mjlab 仿真框架**
- **浏览器操作员**
- **舵机总线**
- **LSM6DSV16X**
- **MJCF 模型输入**

## Connections

- 工程师 → 训练入口: 启动训练
- 训练入口 → 训练任务配置: 选择任务
- 训练入口 → mjlab 仿真框架: 运行训练
- 训练任务配置 → MDP 函数: 配置函数
- 训练任务配置 → 执行器模型: 配置执行器
- 训练入口 → 远程训练提交: 提交远程任务
- 工程师 → 策略工作流工具: 运行策略工具
- 策略工作流工具 → mjlab 仿真框架: 仿真推理
- 浏览器操作员 → 调试台服务: 发送操作
- 调试台服务 → 飞特协议驱动: 读写舵机
- 飞特协议驱动 → 舵机总线: 收发数据
- 调试台服务 → 舵机总线模拟器: 模拟总线
- 调试台服务 → IMU 观测桥: 读取姿态
- IMU 观测桥 → 固件主循环: 观测固件状态
- 固件主循环 → 板级接口: 收发总线与日志
- 固件主循环 → 总线协议解析: 解析与应答
- 固件主循环 → IMU 传感器处理: 轮询传感器
- 总线协议解析 → 寄存器映射: 读取寄存器
- 寄存器映射 → IMU 传感器处理: 读取快照
- IMU 传感器处理 → LSM6DSV16X 驱动: 驱动传感器
- LSM6DSV16X 驱动 → LSM6DSV16X: 读取传感数据
- 工程师 → HD1910 测试 CLI: 执行台架测试
- HD1910 测试 CLI → HD1910 驱动库: 调用驱动
- HD1910 驱动库 → 舵机总线: 收发数据
- 工程师 → STS3215 测试工具: 执行台架测试
- STS3215 测试工具 → STS 总线驱动: 调用总线操作
- STS 总线驱动 → 舵机总线: 收发数据
- 工程师 → 装配接触分析: 分析装配接触
- 装配接触分析 → MJCF 模型输入: 读取模型
- 工程师 → 装配模型工具: 处理装配模型