# maujabur/midi-usb-esp32s3 architecture

> Architecture diagram of the GitHub repository maujabur/midi-usb-esp32s3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maujabur/midi-usb-esp32s3
- Repository: https://github.com/maujabur/midi-usb-esp32s3

## Overview

This ESP32-S3 firmware provides three distinct profiles: the primary USB-host MIDI controller, a USB-MIDI device, and a USB-to-UART serial bridge. In the primary workflow, the BOOT button is debounced, press/release events advance a note sequence, and MIDI output is queued and sent to an enumerated MIDI device such as the FM1. The device profile exposes MIDI to a USB host; the bridge relays serial data for log monitoring. The host source excerpt is partial, so its internal task and transfer details are represented only where shown.

Main entry points: [`src/device/main.cpp`](https://github.com/maujabur/midi-usb-esp32s3/blob/main/src/device/main.cpp) (Device application), [`src/host/main.cpp`](https://github.com/maujabur/midi-usb-esp32s3/blob/main/src/host/main.cpp) (Host application), [`lib/core/button_fsm.h`](https://github.com/maujabur/midi-usb-esp32s3/blob/main/lib/core/button_fsm.h) (Button debounce), [`lib/core/note_sequence.h`](https://github.com/maujabur/midi-usb-esp32s3/blob/main/lib/core/note_sequence.h) (Note sequencer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared MIDI logic"]
  node_fsm["Button debounce<br/>[button_fsm.h]"]
  node_sequence["Note sequencer<br/>[note_sequence.h]"]
  node_midiapi["MIDI output interface<br/>[midi_out.h]"]
end

subgraph group_host["USB host controller"]
  node_hostapp["Host application<br/>[main.cpp]"]
  node_hostmidi["USB host MIDI<br/>[usb_host_midi.cpp]"]
end

subgraph group_device["USB MIDI device"]
  node_deviceapp["Device application<br/>[main.cpp]"]
end

subgraph group_bridge["Serial bridge"]
  node_bridgeapp["Serial bridge<br/>[main.cpp]"]
end

node_button(("BOOT button"))
node_fm1["FM1 MIDI device"]
node_pc(("USB MIDI host"))
node_hostuart["Host UART log"]
node_monitor(("USB serial monitor"))

node_button -->|"pressed at"| node_hostapp
node_hostapp -->|"updates"| node_fsm
node_fsm -->|"returns events"| node_hostapp
node_hostapp -->|"dispatches events"| node_sequence
node_sequence -->|"sends notes"| node_midiapi
node_hostapp -->|"starts host"| node_hostmidi
node_hostmidi -->|"sends USB-MIDI"| node_fm1
node_button -->|"pressed at"| node_deviceapp
node_deviceapp -->|"updates"| node_fsm
node_fsm -->|"returns events"| node_deviceapp
node_deviceapp -->|"dispatches events"| node_sequence
node_deviceapp -->|"implements output"| node_midiapi
node_sequence -->|"sends notes"| node_deviceapp
node_deviceapp -->|"exposes USB MIDI"| node_pc
node_hostapp -->|"writes logs"| node_hostuart
node_hostuart -->|"relays UART"| node_bridgeapp
node_bridgeapp -->|"forwards serial"| node_monitor

click node_hostapp "https://github.com/maujabur/midi-usb-esp32s3/blob/main/src/host/main.cpp"
click node_fsm "https://github.com/maujabur/midi-usb-esp32s3/blob/main/lib/core/button_fsm.h"
click node_sequence "https://github.com/maujabur/midi-usb-esp32s3/blob/main/lib/core/note_sequence.h"
click node_midiapi "https://github.com/maujabur/midi-usb-esp32s3/blob/main/lib/core/midi_out.h"
click node_hostmidi "https://github.com/maujabur/midi-usb-esp32s3/blob/main/src/host/usb_host_midi.cpp"
click node_deviceapp "https://github.com/maujabur/midi-usb-esp32s3/blob/main/src/device/main.cpp"
click node_bridgeapp "https://github.com/maujabur/midi-usb-esp32s3/blob/main/src/bridge/main.cpp"

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_fsm,node_sequence,node_midiapi toneBlue
class node_hostapp,node_hostmidi toneAmber
class node_deviceapp toneMint
class node_bridgeapp toneRose
class node_button,node_fm1,node_pc,node_hostuart,node_monitor toneIndigo
```

## Components

### Shared MIDI logic

- [Button debounce](https://github.com/maujabur/midi-usb-esp32s3/blob/main/lib/core/button_fsm.h): `lib/core/button_fsm.h`
- [Note sequencer](https://github.com/maujabur/midi-usb-esp32s3/blob/main/lib/core/note_sequence.h): `lib/core/note_sequence.h`
- [MIDI output interface](https://github.com/maujabur/midi-usb-esp32s3/blob/main/lib/core/midi_out.h): `lib/core/midi_out.h`

### USB host controller

- [Host application](https://github.com/maujabur/midi-usb-esp32s3/blob/main/src/host/main.cpp): `src/host/main.cpp`
- [USB host MIDI](https://github.com/maujabur/midi-usb-esp32s3/blob/main/src/host/usb_host_midi.cpp): `src/host/usb_host_midi.cpp`

### USB MIDI device

- [Device application](https://github.com/maujabur/midi-usb-esp32s3/blob/main/src/device/main.cpp): `src/device/main.cpp`

### Serial bridge

- [Serial bridge](https://github.com/maujabur/midi-usb-esp32s3/blob/main/src/bridge/main.cpp): `src/bridge/main.cpp`

### Other components

- **BOOT button**
- **FM1 MIDI device**
- **USB MIDI host**
- **Host UART log**
- **USB serial monitor**

## Connections

- BOOT button → Host application: pressed at (evidence: `src/host/main.cpp`)
- Host application → Button debounce: updates (evidence: `src/host/main.cpp`)
- Button debounce → Host application: returns events (evidence: `src/host/main.cpp`)
- Host application → Note sequencer: dispatches events (evidence: `src/host/main.cpp`)
- Note sequencer → MIDI output interface: sends notes (evidence: `lib/core/note_sequence.h`)
- Host application → USB host MIDI: starts host (evidence: `src/host/main.cpp`)
- USB host MIDI → FM1 MIDI device: sends USB-MIDI
- BOOT button → Device application: pressed at (evidence: `src/device/main.cpp`)
- Device application → Button debounce: updates (evidence: `src/device/main.cpp`)
- Button debounce → Device application: returns events (evidence: `src/device/main.cpp`)
- Device application → Note sequencer: dispatches events (evidence: `src/device/main.cpp`)
- Device application → MIDI output interface: implements output (evidence: `src/device/main.cpp`)
- Note sequencer → Device application: sends notes (evidence: `lib/core/note_sequence.h`)
- Device application → USB MIDI host: exposes USB MIDI (evidence: `README.md`)
- Host application → Host UART log: writes logs (evidence: `src/host/main.cpp`)
- Host UART log → Serial bridge: relays UART (evidence: `README.md`)
- Serial bridge → USB serial monitor: forwards serial (evidence: `src/bridge/main.cpp`)
