# luwudynamics/rig_omni architecture

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

- Interactive diagram: https://gitdiagram.com/luwudynamics/rig_omni
- Repository: https://github.com/luwudynamics/rig_omni

## Overview

RIG-Omni is ESP32-S3 robot firmware sharing an application core across multiple robot forms. The main interaction runs from user input through application state and voice services to cloud protocols and back to display/audio output; MCP tools and board-specific control provide a parallel remote-command path to robot hardware. The README documents several capabilities whose implementations were not sampled, so those are represented at supported directory or module paths without speculative call wiring.

Main entry points: [`main/application.cc`](https://github.com/luwudynamics/rig_omni/blob/main/main/application.cc) (Application), [`main/boards`](https://github.com/luwudynamics/rig_omni/tree/main/main/boards) (Board implementations), [`main/protocols/protocol.cc`](https://github.com/luwudynamics/rig_omni/blob/main/main/protocols/protocol.cc) (Cloud protocols), [`main/audio/audio_service.cc`](https://github.com/luwudynamics/rig_omni/blob/main/main/audio/audio_service.cc) (Audio service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application Core"]
  node_application["Application<br/>[application.cc]"]
  node_state["Device state"]
  node_settings[("Settings<br/>[settings.cc]")]
  node_assets["Runtime assets<br/>[assets.cc]"]
end

subgraph group_voice["Voice Interaction"]
  node_audio_service["Audio service<br/>[audio_service.cc]"]
  node_codec["Audio codecs"]
  node_wake["Wake-word detection"]
  node_processor["Audio processing"]
end

subgraph group_robot["Robot Hardware"]
  node_board["Board implementations"]
  node_motion["Motion control<br/>[xgo.cc]"]
  node_common_hw["Shared hardware"]
  node_camera["Camera<br/>[esp32_camera.cc]"]
end

subgraph group_io["User Interfaces"]
  node_mcp["MCP tools<br/>[mcp_server.cc]"]
  node_display["Emotion display<br/>[emote_display.cc]"]
  node_lcd["LCD / LVGL<br/>[lcd_display.cc]"]
  node_ble["BLE remote control"]
  node_hover_debug["Hover debug server"]
end

subgraph group_connect["Connectivity"]
  node_protocol["Cloud protocols<br/>[protocol.cc]"]
  node_mqtt["MQTT transport<br/>[mqtt_protocol.cc]"]
  node_websocket["WebSocket transport"]
  node_ota["Firmware updates<br/>[ota.cc]"]
  node_provisioning["WiFi provisioning<br/>[blufi.cpp]"]
end

node_user(("Robot user"))
node_cloud(("Voice services"))

node_user -->|"interacts with"| node_application
node_application -->|"updates state"| node_state
node_application -->|"gets board"| node_board
node_application -->|"updates UI"| node_display
node_application -->|"controls audio"| node_audio_service
node_application -->|"initializes protocol"| node_protocol
node_application -->|"checks updates"| node_ota
node_application -->|"loads assets"| node_assets
node_audio_service -->|"reads / plays audio"| node_codec
node_audio_service -->|"detects wake word"| node_wake
node_audio_service -->|"processes audio"| node_processor
node_protocol -->|"selects transport"| node_mqtt
node_protocol -->|"selects transport"| node_websocket
node_protocol -->|"exchanges voice data"| node_cloud
node_cloud -->|"returns responses"| node_protocol
node_board -->|"uses shared drivers"| node_common_hw
node_board -->|"controls robot"| node_motion
node_board -->|"registers tools"| node_mcp
node_board -->|"initializes camera"| node_camera
node_board -->|"provides remote control"| node_ble
node_board -->|"supports provisioning"| node_provisioning
node_board -.->|"exposes tuning"| node_hover_debug
node_mcp -->|"dispatches commands"| node_board
node_mcp -.->|"receives remote requests"| node_cloud
node_display -->|"renders animations"| node_lcd
node_user -.->|"controls robot"| node_ble
node_user -.->|"tunes motors"| node_hover_debug
node_application -->|"reads configuration"| node_settings
node_settings -->|"persists preferences"| node_user

click node_application "https://github.com/luwudynamics/rig_omni/blob/main/main/application.cc"
click node_state "https://github.com/luwudynamics/rig_omni/blob/main/main/device_state_machine.cc"
click node_settings "https://github.com/luwudynamics/rig_omni/blob/main/main/settings.cc"
click node_audio_service "https://github.com/luwudynamics/rig_omni/blob/main/main/audio/audio_service.cc"
click node_codec "https://github.com/luwudynamics/rig_omni/tree/main/main/audio/codecs"
click node_wake "https://github.com/luwudynamics/rig_omni/tree/main/main/audio/wake_words"
click node_processor "https://github.com/luwudynamics/rig_omni/tree/main/main/audio/processors"
click node_protocol "https://github.com/luwudynamics/rig_omni/blob/main/main/protocols/protocol.cc"
click node_mqtt "https://github.com/luwudynamics/rig_omni/blob/main/main/protocols/mqtt_protocol.cc"
click node_websocket "https://github.com/luwudynamics/rig_omni/blob/main/main/protocols/websocket_protocol.cc"
click node_ota "https://github.com/luwudynamics/rig_omni/blob/main/main/ota.cc"
click node_provisioning "https://github.com/luwudynamics/rig_omni/blob/main/main/boards/common/blufi.cpp"
click node_mcp "https://github.com/luwudynamics/rig_omni/blob/main/main/mcp_server.cc"
click node_display "https://github.com/luwudynamics/rig_omni/blob/main/main/display/emote_display.cc"
click node_lcd "https://github.com/luwudynamics/rig_omni/blob/main/main/display/lcd_display.cc"
click node_board "https://github.com/luwudynamics/rig_omni/tree/main/main/boards"
click node_motion "https://github.com/luwudynamics/rig_omni/blob/main/main/boards/puppy/xgo.cc"
click node_common_hw "https://github.com/luwudynamics/rig_omni/tree/main/main/boards/common"
click node_camera "https://github.com/luwudynamics/rig_omni/blob/main/main/boards/common/esp32_camera.cc"
click node_ble "https://github.com/luwudynamics/rig_omni/blob/main/main/boards/puppy/ble_remote_control.cc"
click node_hover_debug "https://github.com/luwudynamics/rig_omni/blob/main/main/boards/hover/hover_debug_server.cc"
click node_assets "https://github.com/luwudynamics/rig_omni/blob/main/main/assets.cc"

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_application,node_state,node_settings,node_assets,node_user toneBlue
class node_audio_service,node_codec,node_wake,node_processor toneAmber
class node_board,node_motion,node_common_hw,node_camera toneMint
class node_mcp,node_display,node_lcd,node_ble,node_hover_debug toneRose
class node_protocol,node_mqtt,node_websocket,node_ota,node_provisioning,node_cloud toneIndigo
```

## Components

### Application Core

- [Application](https://github.com/luwudynamics/rig_omni/blob/main/main/application.cc): `main/application.cc`
- [Device state](https://github.com/luwudynamics/rig_omni/blob/main/main/device_state_machine.cc): `main/device_state_machine.cc`
- [Settings](https://github.com/luwudynamics/rig_omni/blob/main/main/settings.cc): `main/settings.cc`
- [Runtime assets](https://github.com/luwudynamics/rig_omni/blob/main/main/assets.cc): `main/assets.cc`

### Voice Interaction

- [Audio service](https://github.com/luwudynamics/rig_omni/blob/main/main/audio/audio_service.cc): `main/audio/audio_service.cc`
- [Audio codecs](https://github.com/luwudynamics/rig_omni/tree/main/main/audio/codecs): `main/audio/codecs`
- [Wake-word detection](https://github.com/luwudynamics/rig_omni/tree/main/main/audio/wake_words): `main/audio/wake_words`
- [Audio processing](https://github.com/luwudynamics/rig_omni/tree/main/main/audio/processors): `main/audio/processors`

### Robot Hardware

- [Board implementations](https://github.com/luwudynamics/rig_omni/tree/main/main/boards): `main/boards`
- [Motion control](https://github.com/luwudynamics/rig_omni/blob/main/main/boards/puppy/xgo.cc): `main/boards/puppy/xgo.cc`
- [Shared hardware](https://github.com/luwudynamics/rig_omni/tree/main/main/boards/common): `main/boards/common`
- [Camera](https://github.com/luwudynamics/rig_omni/blob/main/main/boards/common/esp32_camera.cc): `main/boards/common/esp32_camera.cc`

### User Interfaces

- [MCP tools](https://github.com/luwudynamics/rig_omni/blob/main/main/mcp_server.cc): `main/mcp_server.cc`
- [Emotion display](https://github.com/luwudynamics/rig_omni/blob/main/main/display/emote_display.cc): `main/display/emote_display.cc`
- [LCD / LVGL](https://github.com/luwudynamics/rig_omni/blob/main/main/display/lcd_display.cc): `main/display/lcd_display.cc`
- [BLE remote control](https://github.com/luwudynamics/rig_omni/blob/main/main/boards/puppy/ble_remote_control.cc): `main/boards/puppy/ble_remote_control.cc`
- [Hover debug server](https://github.com/luwudynamics/rig_omni/blob/main/main/boards/hover/hover_debug_server.cc): `main/boards/hover/hover_debug_server.cc`

### Connectivity

- [Cloud protocols](https://github.com/luwudynamics/rig_omni/blob/main/main/protocols/protocol.cc): `main/protocols/protocol.cc`
- [MQTT transport](https://github.com/luwudynamics/rig_omni/blob/main/main/protocols/mqtt_protocol.cc): `main/protocols/mqtt_protocol.cc`
- [WebSocket transport](https://github.com/luwudynamics/rig_omni/blob/main/main/protocols/websocket_protocol.cc): `main/protocols/websocket_protocol.cc`
- [Firmware updates](https://github.com/luwudynamics/rig_omni/blob/main/main/ota.cc): `main/ota.cc`
- [WiFi provisioning](https://github.com/luwudynamics/rig_omni/blob/main/main/boards/common/blufi.cpp): `main/boards/common/blufi.cpp`

### Other components

- **Robot user**
- **Voice services**

## Connections

- Robot user → Application: interacts with
- Application → Device state: updates state
- Application → Board implementations: gets board
- Application → Emotion display: updates UI
- Application → Audio service: controls audio
- Application → Cloud protocols: initializes protocol
- Application → Firmware updates: checks updates
- Application → Runtime assets: loads assets
- Audio service → Audio codecs: reads / plays audio
- Audio service → Wake-word detection: detects wake word
- Audio service → Audio processing: processes audio
- Cloud protocols → MQTT transport: selects transport
- Cloud protocols → WebSocket transport: selects transport
- Cloud protocols → Voice services: exchanges voice data
- Voice services → Cloud protocols: returns responses
- Board implementations → Shared hardware: uses shared drivers
- Board implementations → Motion control: controls robot
- Board implementations → MCP tools: registers tools
- Board implementations → Camera: initializes camera
- Board implementations → BLE remote control: provides remote control
- Board implementations → WiFi provisioning: supports provisioning
- Board implementations → Hover debug server: exposes tuning
- MCP tools → Board implementations: dispatches commands
- MCP tools → Voice services: receives remote requests
- Emotion display → LCD / LVGL: renders animations
- Robot user → BLE remote control: controls robot
- Robot user → Hover debug server: tunes motors
- Application → Settings: reads configuration
- Settings → Robot user: persists preferences