# emuqi/esp-mosaico-fluidbox architecture

> Architecture diagram of the GitHub repository emuqi/esp-mosaico-fluidbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/emuqi/esp-mosaico-fluidbox
- Repository: https://github.com/emuqi/esp-mosaico-fluidbox

## Overview

Mosaico FluidBox is ESP32 firmware that turns device motion into animated particle-fluid visuals. The principal loop reads the BMI270 and button state, advances the particle simulation, renders a selected visual mode, and presents banded frames on the CO5300 display. The README also documents five modes, revision detection, brightness control, and host previews. The graph focuses on firmware runtime; preview tooling is omitted. Some edges rely on header or README contracts because implementation excerpts are partial.

Main entry points: [`main/main.c`](https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/main.c) (Firmware tasks), [`main/render.c`](https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/render.c) (Mode rendering), [`main/config.h`](https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/config.h) (Fluid configuration), [`main/display.c`](https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/display.c) (Band scheduling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Runtime orchestration"]
  node_app["Firmware tasks<br/>[main.c]"]
  node_config["Fluid configuration<br/>[config.h]"]
end

subgraph group_inputs["Motion and controls"]
  node_board["Board controls<br/>[board.c]"]
  node_imu["Motion sensing<br/>[imu.c]"]
end

subgraph group_visuals["Simulation and rendering"]
  node_simulation["Particle solver<br/>[sim.c]"]
  node_renderer["Mode rendering<br/>[render.c]"]
end

subgraph group_hardware["Device output"]
  node_display["Band scheduling<br/>[display.c]"]
end

node_user(("Device user"))
node_bmi270["BMI270 sensor"]
node_co5300["CO5300 panel"]

node_user -->|"presses controls"| node_app
node_app -->|"reads controls"| node_board
node_app -->|"reads motion"| node_imu
node_bmi270 -->|"provides samples"| node_imu
node_app -->|"steps and resets"| node_simulation
node_app -->|"selects mode"| node_renderer
node_app -->|"sets gravity"| node_renderer
node_app -->|"renders frames"| node_renderer
node_renderer -->|"reads snapshots"| node_simulation
node_renderer -->|"stages and presents"| node_display
node_display -->|"transfers bands"| node_co5300
node_app -->|"initializes and monitors"| node_display
node_app -->|"uses settings"| node_config
node_simulation -->|"uses physics settings"| node_config
node_renderer -->|"uses visual settings"| node_config
node_display -->|"uses panel settings"| node_config
node_imu -->|"uses sensor mapping"| node_config

click node_app "https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/main.c"
click node_config "https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/config.h"
click node_board "https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/board.c"
click node_imu "https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/imu.c"
click node_simulation "https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/sim.c"
click node_renderer "https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/render.c"
click node_display "https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/display.c"

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_app,node_config,node_user toneBlue
class node_board,node_imu toneAmber
class node_simulation,node_renderer toneMint
class node_display toneRose
class node_bmi270,node_co5300 toneIndigo
```

## Components

### Runtime orchestration

- [Firmware tasks](https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/main.c): `main/main.c`
- [Fluid configuration](https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/config.h): `main/config.h`

### Motion and controls

- [Board controls](https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/board.c): `main/board.c`
- [Motion sensing](https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/imu.c): `main/imu.c`

### Simulation and rendering

- [Particle solver](https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/sim.c): `main/sim.c`
- [Mode rendering](https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/render.c): `main/render.c`

### Device output

- [Band scheduling](https://github.com/emuqi/esp-mosaico-fluidbox/blob/main/main/display.c): `main/display.c`

### Other components

- **Device user**
- **BMI270 sensor**
- **CO5300 panel**

## Connections

- Device user → Firmware tasks: presses controls (evidence: `README.md`)
- Firmware tasks → Board controls: reads controls (evidence: `main/main.c`)
- Firmware tasks → Motion sensing: reads motion (evidence: `main/main.c`)
- BMI270 sensor → Motion sensing: provides samples
- Firmware tasks → Particle solver: steps and resets (evidence: `main/main.c`)
- Firmware tasks → Mode rendering: selects mode (evidence: `main/main.c`)
- Firmware tasks → Mode rendering: sets gravity (evidence: `main/main.c`)
- Firmware tasks → Mode rendering: renders frames (evidence: `main/main.c`)
- Mode rendering → Particle solver: reads snapshots
- Mode rendering → Band scheduling: stages and presents (evidence: `README.md`)
- Band scheduling → CO5300 panel: transfers bands (evidence: `main/display.c`)
- Firmware tasks → Band scheduling: initializes and monitors (evidence: `main/main.c`)
- Firmware tasks → Fluid configuration: uses settings (evidence: `main/main.c`)
- Particle solver → Fluid configuration: uses physics settings (evidence: `main/sim.c`)
- Mode rendering → Fluid configuration: uses visual settings (evidence: `main/render.c`)
- Band scheduling → Fluid configuration: uses panel settings (evidence: `main/display.c`)
- Motion sensing → Fluid configuration: uses sensor mapping (evidence: `main/imu.c`)
