# pfkellogg/fm1-bonus-box architecture

> Architecture diagram of the GitHub repository pfkellogg/fm1-bonus-box, 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/pfkellogg/fm1-bonus-box
- Repository: https://github.com/pfkellogg/fm1-bonus-box

## Overview

FM-1 Bonus Box combines an ESP32-S3 controller, browser-based soundbank management, and sing-on-key practice; a separate CLI manages banks over USB MIDI. The main workflow is to browse or arrange presets, save a bank, and send it to the FM-1. The current control-box sketch, USB bridge sketch, and several runtime details were not excerpted, so their links below rely on README statements where available; unsampled implementation relationships are omitted.

Main entry points: [`fm1_control_box/fm1_control_box.ino`](https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/fm1_control_box.ino) (Control firmware), [`fm1_control_box/usb_midi_host.cpp`](https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/usb_midi_host.cpp) (USB MIDI host), [`fm1_control_box/web_page.h`](https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/web_page.h) (Bank web page), [`fm1_usb_bridge/usb_midi_bridge.cpp`](https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_usb_bridge/usb_midi_bridge.cpp) (USB MIDI bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control box"]
  node_controlbox["Control firmware"]
  node_display["Preset display"]
end

subgraph group_bank["Soundbank management"]
  node_webpage["Bank web page<br/>[web_page.h]"]
  node_flashbank[("Stored bank")]
end

subgraph group_sing["Sing practice"]
  node_pitch["Pitch detector<br/>[pitch_detector.cpp]"]
  node_singvoice["DOO voice data<br/>[doo_voice.py]"]
end

subgraph group_midi["MIDI connections"]
  node_usbhost["USB MIDI host<br/>[usb_midi_host.cpp]"]
  node_bridge["USB MIDI bridge"]
  node_bridgefirmware["Bridge firmware<br/>[fm1_usb_bridge.ino]"]
end

subgraph group_legacy["Standalone tools"]
  node_cli["Soundbank CLI<br/>[fm1_soundbank.py]"]
  node_footswitch["Sustain footswitch firmware"]
end

node_musician(("Musician"))
node_fm1["FM-1 synthesizer"]
node_browser(("Phone or laptop"))
node_microphone(("Microphone"))
node_usbkeyboard(("USB MIDI keyboard"))

node_musician -->|"operates"| node_controlbox
node_controlbox -->|"updates"| node_display
node_controlbox -->|"sends MIDI"| node_fm1
node_controlbox -->|"polls pitch"| node_pitch
node_microphone -->|"provides audio"| node_pitch
node_controlbox -->|"selects voice"| node_singvoice
node_browser -->|"uses"| node_webpage
node_webpage -->|"saves bank"| node_flashbank
node_controlbox -->|"reads bank"| node_flashbank
node_controlbox -->|"sends banks"| node_fm1
node_usbkeyboard -->|"sends events"| node_usbhost
node_controlbox -->|"reads packets"| node_usbhost
node_usbhost -->|"forwards MIDI"| node_fm1
node_bridgefirmware -.->|"starts"| node_bridge
node_bridge -->|"bridges USB MIDI"| node_fm1
node_musician -->|"runs commands"| node_cli
node_cli -->|"sends banks"| node_fm1
node_musician -.->|"presses pedal"| node_footswitch
node_footswitch -.->|"sends sustain"| node_fm1

click node_controlbox "https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/fm1_control_box.ino"
click node_display "https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/fm1_control_box.ino"
click node_pitch "https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/pitch_detector.cpp"
click node_webpage "https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/web_page.h"
click node_flashbank "https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/fm1_control_box.ino"
click node_usbhost "https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/usb_midi_host.cpp"
click node_bridge "https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_usb_bridge/usb_midi_bridge.cpp"
click node_bridgefirmware "https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_usb_bridge/fm1_usb_bridge.ino"
click node_singvoice "https://github.com/pfkellogg/fm1-bonus-box/blob/main/tools/doo_voice.py"
click node_cli "https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_soundbank_app/fm1_soundbank.py"
click node_footswitch "https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_sustain_footswitch.ino"

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_controlbox,node_display toneBlue
class node_webpage,node_flashbank toneAmber
class node_pitch,node_singvoice toneMint
class node_usbhost,node_bridge,node_bridgefirmware toneRose
class node_cli,node_footswitch,node_musician,node_fm1,node_browser,node_microphone,node_usbkeyboard toneIndigo
```

## Components

### Control box

- [Control firmware](https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/fm1_control_box.ino): `fm1_control_box/fm1_control_box.ino`
- [Preset display](https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/fm1_control_box.ino): `fm1_control_box/fm1_control_box.ino`

### Soundbank management

- [Bank web page](https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/web_page.h): `fm1_control_box/web_page.h`
- [Stored bank](https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/fm1_control_box.ino): `fm1_control_box/fm1_control_box.ino`

### Sing practice

- [Pitch detector](https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/pitch_detector.cpp): `fm1_control_box/pitch_detector.cpp`
- [DOO voice data](https://github.com/pfkellogg/fm1-bonus-box/blob/main/tools/doo_voice.py): `tools/doo_voice.py`

### MIDI connections

- [USB MIDI host](https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_control_box/usb_midi_host.cpp): `fm1_control_box/usb_midi_host.cpp`
- [USB MIDI bridge](https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_usb_bridge/usb_midi_bridge.cpp): `fm1_usb_bridge/usb_midi_bridge.cpp`
- [Bridge firmware](https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_usb_bridge/fm1_usb_bridge.ino): `fm1_usb_bridge/fm1_usb_bridge.ino`

### Standalone tools

- [Soundbank CLI](https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_soundbank_app/fm1_soundbank.py): `fm1_soundbank_app/fm1_soundbank.py`
- [Sustain footswitch firmware](https://github.com/pfkellogg/fm1-bonus-box/blob/main/fm1_sustain_footswitch.ino): `fm1_sustain_footswitch.ino`

### Other components

- **Musician**
- **FM-1 synthesizer**
- **Phone or laptop**
- **Microphone**
- **USB MIDI keyboard**

## Connections

- Musician → Control firmware: operates (evidence: `README.md`)
- Control firmware → Preset display: updates (evidence: `README.md`)
- Control firmware → FM-1 synthesizer: sends MIDI (evidence: `README.md`)
- Control firmware → Pitch detector: polls pitch
- Microphone → Pitch detector: provides audio
- Control firmware → DOO voice data: selects voice
- Phone or laptop → Bank web page: uses (evidence: `README.md`)
- Bank web page → Stored bank: saves bank (evidence: `fm1_control_box/web_page.h`)
- Control firmware → Stored bank: reads bank (evidence: `README.md`)
- Control firmware → FM-1 synthesizer: sends banks (evidence: `README.md`)
- USB MIDI keyboard → USB MIDI host: sends events
- Control firmware → USB MIDI host: reads packets
- USB MIDI host → FM-1 synthesizer: forwards MIDI (evidence: `README.md`)
- Bridge firmware → USB MIDI bridge: starts
- USB MIDI bridge → FM-1 synthesizer: bridges USB MIDI
- Musician → Soundbank CLI: runs commands (evidence: `fm1_soundbank_app/fm1_soundbank.py`)
- Soundbank CLI → FM-1 synthesizer: sends banks (evidence: `fm1_soundbank_app/fm1_soundbank.py`)
- Musician → Sustain footswitch firmware: presses pedal
- Sustain footswitch firmware → FM-1 synthesizer: sends sustain
