# yunyu-x/yunyu-esp32 architecture

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

- Interactive diagram: https://gitdiagram.com/yunyu-x/yunyu-esp32
- Repository: https://github.com/yunyu-x/yunyu-esp32

## Overview

yunyu-esp32 is the LingCube modular robot ecosystem’s firmware, StickS3 companion/HIL terminal, and open hardware design. The user workflow runs through the StickS3 network interfaces for control and bidirectional audio, while the robot firmware manages attitude, motion, and optical mesh communication; hardware design and simulation form a separate engineering branch. README capabilities are included, but many subsystem links are documented rather than visible in sampled implementation, so those edges cite the README; unsampled internal wiring is omitted.

Main entry points: [`firmware/m5sticks3_buddy/src/main.cpp`](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/src/main.cpp) (Buddy Runtime), [`firmware/esp32_msrr_firmware/src/main.cpp`](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/main.cpp) (Robot Runtime), [`firmware/m5sticks3_buddy/include/sticks3_wifi.h`](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_wifi.h) (Wi-Fi Console), [`firmware/esp32_msrr_firmware/src/controllers/roll_fsm.cpp`](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/controllers/roll_fsm.cpp) (Roll Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_buddy["StickS3 Companion"]
  node_stick_main["Buddy Runtime<br/>[main.cpp]"]
  node_wifi["Wi-Fi Console<br/>[sticks3_wifi.h]"]
  node_audio["Audio Subsystem<br/>[sticks3_audio.h]"]
  node_bailian["Bailian Client"]
  node_buddy_protocol["Buddy Protocol<br/>[buddy_protocol.cpp]"]
  node_gbk["GBK Unicode<br/>[gbk_to_utf8.h]"]
  node_memory[("Conversation Memory")]
  node_wakeword["Wakeword Engine<br/>[sticks3_wakeword.h]"]
  node_wifi_config["Wi-Fi Configuration"]
  node_i2c["I²C Lock"]
  node_metrics["System Metrics"]
end

subgraph group_robot["Robot Firmware"]
  node_robot_main["Robot Runtime<br/>[main.cpp]"]
  node_roll["Roll Controller<br/>[roll_fsm.cpp]"]
  node_ekf["Attitude EKF<br/>[attitude_ekf.cpp]"]
  node_motor["Motor Driver<br/>[motor_mcpwm.cpp]"]
  node_epm["EPM Driver<br/>[epm_driver.cpp]"]
  node_driver_api["Driver Interface<br/>[driver_interface.h]"]
  node_hal_api["Hardware Abstraction<br/>[hal_interface.h]"]
  node_optical["Optical Mesh"]
  node_neuromorphic["Neuromorphic Reflex"]
  node_multi_fsm["Multi-Unit FSM<br/>[multi_unit_fsm.cpp]"]
end

subgraph group_hardware["Hardware Design"]
  node_cad["3D CAD Models"]
  node_pcb["PCB Design"]
  node_manufacturing["Manufacturing Package"]
  node_circuit_sim["Circuit Simulation"]
  node_environment_sim["Fault Simulation"]
  node_netlist["Netlist Verification"]
end

subgraph group_adapters["Robot Adapters"]
  node_actuator_adapter["Actuator Bus"]
  node_planner["Behavior Planner"]
  node_brain_protocol["Brain Protocol"]
  node_observation["Observation Adapter"]
end

node_mobile(("Mobile Clients"))
node_desktop(("PC Clients"))
node_wechat(("WeChat Clients"))

node_mobile -->|"uses HTTP"| node_wifi
node_desktop -->|"connects BLE"| node_stick_main
node_wechat -->|"uses TCP/UDP"| node_wifi
node_wifi -->|"controls audio"| node_audio
node_stick_main -->|"initializes"| node_wifi
node_stick_main -->|"dispatches queries"| node_bailian
node_stick_main -->|"uses protocol"| node_buddy_protocol
node_stick_main -->|"converts text"| node_gbk
node_stick_main -->|"loads config"| node_wifi_config
node_stick_main -->|"uses lock"| node_i2c
node_stick_main -->|"reads metrics"| node_metrics
node_stick_main -->|"uses memory"| node_memory
node_stick_main -->|"uses detection"| node_wakeword
node_bailian -->|"streams audio"| node_audio
node_bailian -->|"stores turns"| node_memory
node_wifi -->|"controls client"| node_bailian
node_wifi -->|"serves recordings"| node_audio
node_wifi -->|"clears memory"| node_memory
node_robot_main -->|"updates"| node_roll
node_robot_main -->|"updates"| node_motor
node_robot_main -->|"updates"| node_epm
node_robot_main -->|"initializes"| node_ekf
node_robot_main -->|"broadcasts heartbeat"| node_optical
node_roll -->|"uses driver"| node_motor
node_roll -->|"uses driver"| node_epm
node_roll -->|"uses estimate"| node_ekf
node_motor -.->|"implements"| node_driver_api
node_epm -.->|"implements"| node_driver_api
node_driver_api -.->|"uses abstraction"| node_hal_api
node_robot_main -.->|"runs reflex"| node_neuromorphic
node_robot_main -.->|"runs coordination"| node_multi_fsm
node_pcb -.->|"produces outputs"| node_manufacturing
node_pcb -->|"checked by"| node_netlist
node_planner -->|"uses protocol"| node_brain_protocol

click node_stick_main "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/src/main.cpp"
click node_wifi "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_wifi.h"
click node_audio "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_audio.h"
click node_bailian "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_bailian_client.h"
click node_buddy_protocol "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/src/buddy_protocol.cpp"
click node_gbk "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/gbk_to_utf8.h"
click node_memory "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_memory_store.h"
click node_wakeword "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_wakeword.h"
click node_wifi_config "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_wifi_config.h"
click node_i2c "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_i2c_mutex.h"
click node_metrics "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_system_metrics.h"
click node_robot_main "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/main.cpp"
click node_roll "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/controllers/roll_fsm.cpp"
click node_ekf "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/filters/attitude_ekf.cpp"
click node_motor "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/drivers/motor_mcpwm.cpp"
click node_epm "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/drivers/epm_driver.cpp"
click node_driver_api "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/include/drivers/driver_interface.h"
click node_hal_api "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/include/hal/hal_interface.h"
click node_optical "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/comm/optical_mesh_protocol.cpp"
click node_neuromorphic "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/controllers/neuromorphic_reflex.cpp"
click node_multi_fsm "https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/controllers/multi_unit_fsm.cpp"
click node_cad "https://github.com/yunyu-x/yunyu-esp32/blob/main/hardware/cad/generate_cad_models.py"
click node_pcb "https://github.com/yunyu-x/yunyu-esp32/blob/main/hardware/kicad/generate_kicad_pcb.py"
click node_manufacturing "https://github.com/yunyu-x/yunyu-esp32/blob/main/hardware/scripts/export_manufacturing_package.py"
click node_circuit_sim "https://github.com/yunyu-x/yunyu-esp32/blob/main/hardware/simulate_circuit_spice.py"
click node_environment_sim "https://github.com/yunyu-x/yunyu-esp32/blob/main/hardware/simulate_harsh_environment_and_faults.py"
click node_netlist "https://github.com/yunyu-x/yunyu-esp32/blob/main/hardware/verify_circuit_netlist.py"
click node_actuator_adapter "https://github.com/yunyu-x/yunyu-esp32/blob/main/microduck/adapters/actuator_bus_manager.py"
click node_planner "https://github.com/yunyu-x/yunyu-esp32/blob/main/microduck/adapters/behavior_tree_planner.py"
click node_brain_protocol "https://github.com/yunyu-x/yunyu-esp32/blob/main/microduck/adapters/brain_cerebellum_protocol.py"
click node_observation "https://github.com/yunyu-x/yunyu-esp32/blob/main/microduck/adapters/microduck_observation_adapter.py"

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_stick_main,node_wifi,node_audio,node_bailian,node_buddy_protocol,node_gbk,node_memory,node_wakeword,node_wifi_config,node_i2c,node_metrics,node_mobile,node_desktop,node_wechat toneBlue
class node_robot_main,node_roll,node_ekf,node_motor,node_epm,node_driver_api,node_hal_api,node_optical,node_neuromorphic,node_multi_fsm toneAmber
class node_cad,node_pcb,node_manufacturing,node_circuit_sim,node_environment_sim,node_netlist toneMint
class node_actuator_adapter,node_planner,node_brain_protocol,node_observation toneRose
```

## Components

### StickS3 Companion

- [Buddy Runtime](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/src/main.cpp): `firmware/m5sticks3_buddy/src/main.cpp`
- [Wi-Fi Console](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_wifi.h): `firmware/m5sticks3_buddy/include/sticks3_wifi.h`
- [Audio Subsystem](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_audio.h): `firmware/m5sticks3_buddy/include/sticks3_audio.h`
- [Bailian Client](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_bailian_client.h): `firmware/m5sticks3_buddy/include/sticks3_bailian_client.h`
- [Buddy Protocol](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/src/buddy_protocol.cpp): `firmware/m5sticks3_buddy/src/buddy_protocol.cpp`
- [GBK Unicode](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/gbk_to_utf8.h): `firmware/m5sticks3_buddy/include/gbk_to_utf8.h`
- [Conversation Memory](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_memory_store.h): `firmware/m5sticks3_buddy/include/sticks3_memory_store.h`
- [Wakeword Engine](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_wakeword.h): `firmware/m5sticks3_buddy/include/sticks3_wakeword.h`
- [Wi-Fi Configuration](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_wifi_config.h): `firmware/m5sticks3_buddy/include/sticks3_wifi_config.h`
- [I²C Lock](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_i2c_mutex.h): `firmware/m5sticks3_buddy/include/sticks3_i2c_mutex.h`
- [System Metrics](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/m5sticks3_buddy/include/sticks3_system_metrics.h): `firmware/m5sticks3_buddy/include/sticks3_system_metrics.h`

### Robot Firmware

- [Robot Runtime](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/main.cpp): `firmware/esp32_msrr_firmware/src/main.cpp`
- [Roll Controller](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/controllers/roll_fsm.cpp): `firmware/esp32_msrr_firmware/src/controllers/roll_fsm.cpp`
- [Attitude EKF](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/filters/attitude_ekf.cpp): `firmware/esp32_msrr_firmware/src/filters/attitude_ekf.cpp`
- [Motor Driver](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/drivers/motor_mcpwm.cpp): `firmware/esp32_msrr_firmware/src/drivers/motor_mcpwm.cpp`
- [EPM Driver](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/drivers/epm_driver.cpp): `firmware/esp32_msrr_firmware/src/drivers/epm_driver.cpp`
- [Driver Interface](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/include/drivers/driver_interface.h): `firmware/esp32_msrr_firmware/include/drivers/driver_interface.h`
- [Hardware Abstraction](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/include/hal/hal_interface.h): `firmware/esp32_msrr_firmware/include/hal/hal_interface.h`
- [Optical Mesh](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/comm/optical_mesh_protocol.cpp): `firmware/esp32_msrr_firmware/src/comm/optical_mesh_protocol.cpp`
- [Neuromorphic Reflex](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/controllers/neuromorphic_reflex.cpp): `firmware/esp32_msrr_firmware/src/controllers/neuromorphic_reflex.cpp`
- [Multi-Unit FSM](https://github.com/yunyu-x/yunyu-esp32/blob/main/firmware/esp32_msrr_firmware/src/controllers/multi_unit_fsm.cpp): `firmware/esp32_msrr_firmware/src/controllers/multi_unit_fsm.cpp`

### Hardware Design

- [3D CAD Models](https://github.com/yunyu-x/yunyu-esp32/blob/main/hardware/cad/generate_cad_models.py): `hardware/cad/generate_cad_models.py`
- [PCB Design](https://github.com/yunyu-x/yunyu-esp32/blob/main/hardware/kicad/generate_kicad_pcb.py): `hardware/kicad/generate_kicad_pcb.py`
- [Manufacturing Package](https://github.com/yunyu-x/yunyu-esp32/blob/main/hardware/scripts/export_manufacturing_package.py): `hardware/scripts/export_manufacturing_package.py`
- [Circuit Simulation](https://github.com/yunyu-x/yunyu-esp32/blob/main/hardware/simulate_circuit_spice.py): `hardware/simulate_circuit_spice.py`
- [Fault Simulation](https://github.com/yunyu-x/yunyu-esp32/blob/main/hardware/simulate_harsh_environment_and_faults.py): `hardware/simulate_harsh_environment_and_faults.py`
- [Netlist Verification](https://github.com/yunyu-x/yunyu-esp32/blob/main/hardware/verify_circuit_netlist.py): `hardware/verify_circuit_netlist.py`

### Robot Adapters

- [Actuator Bus](https://github.com/yunyu-x/yunyu-esp32/blob/main/microduck/adapters/actuator_bus_manager.py): `microduck/adapters/actuator_bus_manager.py`
- [Behavior Planner](https://github.com/yunyu-x/yunyu-esp32/blob/main/microduck/adapters/behavior_tree_planner.py): `microduck/adapters/behavior_tree_planner.py`
- [Brain Protocol](https://github.com/yunyu-x/yunyu-esp32/blob/main/microduck/adapters/brain_cerebellum_protocol.py): `microduck/adapters/brain_cerebellum_protocol.py`
- [Observation Adapter](https://github.com/yunyu-x/yunyu-esp32/blob/main/microduck/adapters/microduck_observation_adapter.py): `microduck/adapters/microduck_observation_adapter.py`

### Other components

- **Mobile Clients**
- **PC Clients**
- **WeChat Clients**

## Connections

- Mobile Clients → Wi-Fi Console: uses HTTP (evidence: `README.md`)
- PC Clients → Buddy Runtime: connects BLE (evidence: `README.md`)
- WeChat Clients → Wi-Fi Console: uses TCP/UDP (evidence: `README.md`)
- Wi-Fi Console → Audio Subsystem: controls audio (evidence: `README.md`)
- Buddy Runtime → Wi-Fi Console: initializes (evidence: `firmware/m5sticks3_buddy/src/main.cpp`)
- Buddy Runtime → Bailian Client: dispatches queries (evidence: `firmware/m5sticks3_buddy/src/main.cpp`)
- Buddy Runtime → Buddy Protocol: uses protocol (evidence: `firmware/m5sticks3_buddy/src/main.cpp`)
- Buddy Runtime → GBK Unicode: converts text (evidence: `firmware/m5sticks3_buddy/src/main.cpp`)
- Buddy Runtime → Wi-Fi Configuration: loads config (evidence: `firmware/m5sticks3_buddy/src/main.cpp`)
- Buddy Runtime → I²C Lock: uses lock (evidence: `firmware/m5sticks3_buddy/src/main.cpp`)
- Buddy Runtime → System Metrics: reads metrics (evidence: `firmware/m5sticks3_buddy/src/main.cpp`)
- Buddy Runtime → Conversation Memory: uses memory (evidence: `firmware/m5sticks3_buddy/src/main.cpp`)
- Buddy Runtime → Wakeword Engine: uses detection (evidence: `firmware/m5sticks3_buddy/src/main.cpp`)
- Bailian Client → Audio Subsystem: streams audio (evidence: `firmware/m5sticks3_buddy/include/sticks3_bailian_client.h`)
- Bailian Client → Conversation Memory: stores turns (evidence: `firmware/m5sticks3_buddy/include/sticks3_bailian_client.h`)
- Wi-Fi Console → Bailian Client: controls client (evidence: `firmware/m5sticks3_buddy/include/sticks3_wifi.h`)
- Wi-Fi Console → Audio Subsystem: serves recordings (evidence: `firmware/m5sticks3_buddy/include/sticks3_wifi.h`)
- Wi-Fi Console → Conversation Memory: clears memory (evidence: `firmware/m5sticks3_buddy/include/sticks3_wifi.h`)
- Robot Runtime → Roll Controller: updates (evidence: `firmware/esp32_msrr_firmware/src/main.cpp`)
- Robot Runtime → Motor Driver: updates (evidence: `firmware/esp32_msrr_firmware/src/main.cpp`)
- Robot Runtime → EPM Driver: updates (evidence: `firmware/esp32_msrr_firmware/src/main.cpp`)
- Robot Runtime → Attitude EKF: initializes (evidence: `firmware/esp32_msrr_firmware/src/main.cpp`)
- Robot Runtime → Optical Mesh: broadcasts heartbeat (evidence: `firmware/esp32_msrr_firmware/src/main.cpp`)
- Roll Controller → Motor Driver: uses driver
- Roll Controller → EPM Driver: uses driver
- Roll Controller → Attitude EKF: uses estimate
- Motor Driver → Driver Interface: implements
- EPM Driver → Driver Interface: implements
- Driver Interface → Hardware Abstraction: uses abstraction
- Robot Runtime → Neuromorphic Reflex: runs reflex
- Robot Runtime → Multi-Unit FSM: runs coordination
- PCB Design → Manufacturing Package: produces outputs
- PCB Design → Netlist Verification: checked by (evidence: `hardware/verify_circuit_netlist.py`)
- Behavior Planner → Brain Protocol: uses protocol (evidence: `microduck/adapters/behavior_tree_planner.py`)