# joegould1878/spectrum_visualiser_lab architecture

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

- Interactive diagram: https://gitdiagram.com/joegould1878/spectrum_visualiser_lab
- Repository: https://github.com/joegould1878/spectrum_visualiser_lab

## Overview

Spectrum Visualiser is ESP32-S3 firmware that turns microphone samples into a 32×8 LED spectrum, with LOG/LINEAR modes, tone and signal-quality reporting, persistent settings, and button controls. Its principal workflow starts in `main/main.c`: audio frames are sampled and analysed, passed to the display task, and rendered on the MAX7219 matrix; a separate input task handles controls. Python tools parse firmware and bring-up logs for inspection. The README documents the signal-processing stages; sampled task code and the SOURCE INDEX support the specific task/component links shown. Unsampled internals are represented only where the README documents their role.

Main entry points: [`main/audio_task.c`](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/audio_task.c) (Audio Task), [`main/display_task.c`](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/display_task.c) (Display Task), [`main/input_task.c`](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/input_task.c) (Button Input), [`main/main.c`](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/main.c) (Firmware Startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application Tasks"]
  node_startup["Firmware Startup<br/>[main.c]"]
  node_settings["Settings<br/>[settings.c]"]
  node_input["Button Input<br/>[input_task.c]"]
  node_audio["Audio Task<br/>[audio_task.c]"]
  node_debug["Serial Debug<br/>[debug_stream.c]"]
  node_buttons["Debounced Buttons<br/>[button.c]"]
end

subgraph group_signal["Audio Analysis"]
  node_adc["DMA ADC Sampling<br/>[adc_sampler.c]"]
  node_fft["FFT Processing<br/>[spectrum.c]"]
  node_bands["Band Mapping<br/>[band_map.c]"]
  node_tone["Tone Finding<br/>[tone_finder.c]"]
end

subgraph group_display["Display Output"]
  node_display_task["Display Task<br/>[display_task.c]"]
  node_bars["Bar Model<br/>[bar_model.c]"]
  node_graphics["Frame Graphics<br/>[frame_gfx.c]"]
  node_matrix["MAX7219 Driver<br/>[max7219.c]"]
end

subgraph group_analysis["Log Analysis"]
  node_logparse["Log Parser<br/>[logparse.py]"]
  node_rawplots["Raw Log Plots<br/>[plot_raw.py]"]
  node_frames["Frame Visualisation<br/>[frames.py]"]
  node_accuracy["Accuracy Plots<br/>[plot_accuracy.py]"]
  node_tone_stats["Tone Statistics<br/>[tone_stats.py]"]
  node_rate_table["Rate Tables<br/>[rate_table.py]"]
end

node_user(("Operator"))

node_user -->|"presses buttons"| node_input
node_startup -->|"loads settings"| node_settings
node_startup -->|"starts display"| node_display_task
node_startup -->|"starts audio"| node_audio
node_startup -->|"starts input"| node_input
node_input -->|"reads presses"| node_buttons
node_input -->|"controls listening"| node_audio
node_input -->|"sets brightness"| node_display_task
node_audio -->|"reads samples"| node_adc
node_audio -->|"processes samples"| node_fft
node_audio -->|"maps bins"| node_bands
node_audio -->|"finds tone"| node_tone
node_audio -->|"emits telemetry"| node_debug
node_audio -->|"queues frames"| node_display_task
node_display_task -->|"models levels"| node_bars
node_display_task -->|"draws frame"| node_graphics
node_display_task -->|"writes rows"| node_matrix
node_display_task -->|"emits display stats"| node_debug
node_rawplots -->|"parses logs"| node_logparse
node_frames -->|"parses logs"| node_logparse
node_tone_stats -->|"parses logs"| node_logparse
node_rate_table -->|"parses logs"| node_logparse

click node_startup "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/main.c"
click node_settings "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/settings.c"
click node_input "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/input_task.c"
click node_audio "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/audio_task.c"
click node_debug "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/debug_stream.c"
click node_adc "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/adc_sampler/adc_sampler.c"
click node_fft "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/spectrum/spectrum.c"
click node_bands "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/band_map/band_map.c"
click node_tone "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/tone_finder/tone_finder.c"
click node_display_task "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/display_task.c"
click node_bars "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/bar_model/bar_model.c"
click node_graphics "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/frame_gfx/frame_gfx.c"
click node_matrix "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/max7219/max7219.c"
click node_buttons "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/button/button.c"
click node_logparse "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/tools/logparse.py"
click node_rawplots "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/tools/plot_raw.py"
click node_frames "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/tools/frames.py"
click node_accuracy "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/tools/plot_accuracy.py"
click node_tone_stats "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/tools/tone_stats.py"
click node_rate_table "https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/tools/rate_table.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_startup,node_settings,node_input,node_audio,node_debug,node_buttons toneBlue
class node_adc,node_fft,node_bands,node_tone toneAmber
class node_display_task,node_bars,node_graphics,node_matrix toneMint
class node_logparse,node_rawplots,node_frames,node_accuracy,node_tone_stats,node_rate_table toneRose
class node_user toneIndigo
```

## Components

### Application Tasks

- [Firmware Startup](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/main.c): `main/main.c`
- [Settings](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/settings.c): `main/settings.c`
- [Button Input](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/input_task.c): `main/input_task.c`
- [Audio Task](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/audio_task.c): `main/audio_task.c`
- [Serial Debug](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/debug_stream.c): `main/debug_stream.c`
- [Debounced Buttons](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/button/button.c): `components/button/button.c`

### Audio Analysis

- [DMA ADC Sampling](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/adc_sampler/adc_sampler.c): `components/adc_sampler/adc_sampler.c`
- [FFT Processing](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/spectrum/spectrum.c): `components/spectrum/spectrum.c`
- [Band Mapping](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/band_map/band_map.c): `components/band_map/band_map.c`
- [Tone Finding](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/tone_finder/tone_finder.c): `components/tone_finder/tone_finder.c`

### Display Output

- [Display Task](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/main/display_task.c): `main/display_task.c`
- [Bar Model](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/bar_model/bar_model.c): `components/bar_model/bar_model.c`
- [Frame Graphics](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/frame_gfx/frame_gfx.c): `components/frame_gfx/frame_gfx.c`
- [MAX7219 Driver](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/components/max7219/max7219.c): `components/max7219/max7219.c`

### Log Analysis

- [Log Parser](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/tools/logparse.py): `tools/logparse.py`
- [Raw Log Plots](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/tools/plot_raw.py): `tools/plot_raw.py`
- [Frame Visualisation](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/tools/frames.py): `tools/frames.py`
- [Accuracy Plots](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/tools/plot_accuracy.py): `tools/plot_accuracy.py`
- [Tone Statistics](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/tools/tone_stats.py): `tools/tone_stats.py`
- [Rate Tables](https://github.com/joegould1878/spectrum_visualiser_lab/blob/main/tools/rate_table.py): `tools/rate_table.py`

### Other components

- **Operator**

## Connections

- Operator → Button Input: presses buttons
- Firmware Startup → Settings: loads settings (evidence: `main/main.c`)
- Firmware Startup → Display Task: starts display (evidence: `main/main.c`)
- Firmware Startup → Audio Task: starts audio (evidence: `main/main.c`)
- Firmware Startup → Button Input: starts input (evidence: `main/main.c`)
- Button Input → Debounced Buttons: reads presses (evidence: `main/input_task.c`)
- Button Input → Audio Task: controls listening (evidence: `main/input_task.c`)
- Button Input → Display Task: sets brightness (evidence: `main/input_task.c`)
- Audio Task → DMA ADC Sampling: reads samples (evidence: `main/audio_task.c`)
- Audio Task → FFT Processing: processes samples (evidence: `main/audio_task.c`)
- Audio Task → Band Mapping: maps bins (evidence: `main/audio_task.c`)
- Audio Task → Tone Finding: finds tone (evidence: `main/audio_task.c`)
- Audio Task → Serial Debug: emits telemetry (evidence: `main/audio_task.c`)
- Audio Task → Display Task: queues frames
- Display Task → Bar Model: models levels (evidence: `main/display_task.c`)
- Display Task → Frame Graphics: draws frame (evidence: `main/display_task.c`)
- Display Task → MAX7219 Driver: writes rows (evidence: `main/display_task.c`)
- Display Task → Serial Debug: emits display stats (evidence: `main/display_task.c`)
- Raw Log Plots → Log Parser: parses logs (evidence: `tools/plot_raw.py`)
- Frame Visualisation → Log Parser: parses logs (evidence: `tools/frames.py`)
- Tone Statistics → Log Parser: parses logs (evidence: `tools/tone_stats.py`)
- Rate Tables → Log Parser: parses logs (evidence: `tools/rate_table.py`)
