# abcdaaa1111/picomp3 architecture

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

- Interactive diagram: https://gitdiagram.com/abcdaaa1111/picomp3
- Repository: https://github.com/abcdaaa1111/picomp3

## Overview

This repository is firmware for an RP2040 Hi-Fi MP3 player. The main workflow is button-driven playback: the application reads music from SD storage through FatFs, decodes MP3 audio with libmad, and sends PCM to the audio output. Separate branches cover the OLED interface, battery and input handling, status LEDs, and the documented second-core spectrum analysis. Some connections rely on README descriptions because the relevant implementation excerpts were not provided.

Main entry points: [`main.c`](https://github.com/abcdaaa1111/picomp3/blob/main/main.c) (Player Application), [`Astra/graphic/2d/src/Astra_GUI.c`](https://github.com/abcdaaa1111/picomp3/blob/main/Astra/graphic/2d/src/Astra_GUI.c) (Graphics and GUI), [`devices/sound/sound.c`](https://github.com/abcdaaa1111/picomp3/blob/main/devices/sound/sound.c) (PCM Output), [`FatFs/ff.c`](https://github.com/abcdaaa1111/picomp3/blob/main/FatFs/ff.c) (FatFs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_playback["Playback"]
  node_application["Player Application<br/>[main.c]"]
  node_filesystem["FatFs<br/>[ff.c]"]
  node_decoder["MP3 Decoder<br/>[layer3.c]"]
end

subgraph group_hardware["Device I/O"]
  node_sdcard["SD Card Driver<br/>[sdcard.c]"]
  node_audio["PCM Output<br/>[sound.c]"]
  node_pcmchannel["PCM Channel<br/>[PCMchannel.c]"]
end

subgraph group_interface["Interface"]
  node_buttons["Button Input<br/>[buttons.c]"]
  node_gui["Graphics and GUI<br/>[Astra_GUI.c]"]
  node_bitmap["Bitmap Drawing<br/>[Astra_Bitmap.c]"]
  node_display["OLED Display<br/>[display.c]"]
  node_ssd1306["SSD1306 Driver<br/>[ssd1306_spi.c]"]
  node_battery["Battery Sensing<br/>[battery.c]"]
  node_adc["ADC Scan<br/>[adc_scan.c]"]
  node_led["WS2812 Driver<br/>[ws2812.c]"]
end

subgraph group_analysis["Audio Analysis"]
  node_core1["Core 1 Analysis<br/>[core1_main.c]"]
  node_pid["PID Algorithm<br/>[pid.c]"]
end

node_listener(("Listener"))
node_card[("SD Card")]
node_dac["PCM5102A DAC"]

node_listener -->|"presses"| node_buttons
node_buttons -.->|"provides input"| node_application
node_application -->|"reads tracks"| node_filesystem
node_filesystem -->|"accesses storage"| node_sdcard
node_sdcard -->|"reads blocks"| node_card
node_application -->|"decodes frames"| node_decoder
node_decoder -->|"outputs PCM"| node_audio
node_audio -->|"uses channels"| node_pcmchannel
node_audio -->|"sends I2S"| node_dac
node_application -->|"updates interface"| node_gui
node_gui -.->|"draws graphics"| node_bitmap
node_gui -->|"renders screen"| node_display
node_display -->|"uses driver"| node_ssd1306
node_application -.->|"samples battery"| node_adc
node_battery -.->|"reads voltage"| node_adc
node_application -.->|"controls indicator"| node_led
node_application -->|"starts second core"| node_core1
node_core1 -->|"sends spectrum"| node_gui

click node_application "https://github.com/abcdaaa1111/picomp3/blob/main/main.c"
click node_filesystem "https://github.com/abcdaaa1111/picomp3/blob/main/FatFs/ff.c"
click node_sdcard "https://github.com/abcdaaa1111/picomp3/blob/main/devices/sdcard/sdcard.c"
click node_decoder "https://github.com/abcdaaa1111/picomp3/blob/main/libmad/layer3.c"
click node_audio "https://github.com/abcdaaa1111/picomp3/blob/main/devices/sound/sound.c"
click node_pcmchannel "https://github.com/abcdaaa1111/picomp3/blob/main/devices/sound/PCMchannel.c"
click node_buttons "https://github.com/abcdaaa1111/picomp3/blob/main/devices/buttons/buttons.c"
click node_gui "https://github.com/abcdaaa1111/picomp3/blob/main/Astra/graphic/2d/src/Astra_GUI.c"
click node_bitmap "https://github.com/abcdaaa1111/picomp3/blob/main/Astra/graphic/2d/src/Astra_Bitmap.c"
click node_display "https://github.com/abcdaaa1111/picomp3/blob/main/devices/display/display.c"
click node_ssd1306 "https://github.com/abcdaaa1111/picomp3/blob/main/devices/display/ssd1306/ssd1306_spi.c"
click node_battery "https://github.com/abcdaaa1111/picomp3/blob/main/devices/battery/battery.c"
click node_adc "https://github.com/abcdaaa1111/picomp3/blob/main/services/adc_scan.c"
click node_led "https://github.com/abcdaaa1111/picomp3/blob/main/devices/led/ws2812/ws2812.c"
click node_core1 "https://github.com/abcdaaa1111/picomp3/blob/main/core1_main.c"
click node_pid "https://github.com/abcdaaa1111/picomp3/blob/main/algorithms/pid/pid.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_application,node_filesystem,node_decoder toneBlue
class node_sdcard,node_audio,node_pcmchannel,node_card toneAmber
class node_buttons,node_gui,node_bitmap,node_display,node_ssd1306,node_battery,node_adc,node_led toneMint
class node_core1,node_pid toneRose
class node_listener,node_dac toneIndigo
```

## Components

### Playback

- [Player Application](https://github.com/abcdaaa1111/picomp3/blob/main/main.c): `main.c`
- [FatFs](https://github.com/abcdaaa1111/picomp3/blob/main/FatFs/ff.c): `FatFs/ff.c`
- [MP3 Decoder](https://github.com/abcdaaa1111/picomp3/blob/main/libmad/layer3.c): `libmad/layer3.c`

### Device I/O

- [SD Card Driver](https://github.com/abcdaaa1111/picomp3/blob/main/devices/sdcard/sdcard.c): `devices/sdcard/sdcard.c`
- [PCM Output](https://github.com/abcdaaa1111/picomp3/blob/main/devices/sound/sound.c): `devices/sound/sound.c`
- [PCM Channel](https://github.com/abcdaaa1111/picomp3/blob/main/devices/sound/PCMchannel.c): `devices/sound/PCMchannel.c`

### Interface

- [Button Input](https://github.com/abcdaaa1111/picomp3/blob/main/devices/buttons/buttons.c): `devices/buttons/buttons.c`
- [Graphics and GUI](https://github.com/abcdaaa1111/picomp3/blob/main/Astra/graphic/2d/src/Astra_GUI.c): `Astra/graphic/2d/src/Astra_GUI.c`
- [Bitmap Drawing](https://github.com/abcdaaa1111/picomp3/blob/main/Astra/graphic/2d/src/Astra_Bitmap.c): `Astra/graphic/2d/src/Astra_Bitmap.c`
- [OLED Display](https://github.com/abcdaaa1111/picomp3/blob/main/devices/display/display.c): `devices/display/display.c`
- [SSD1306 Driver](https://github.com/abcdaaa1111/picomp3/blob/main/devices/display/ssd1306/ssd1306_spi.c): `devices/display/ssd1306/ssd1306_spi.c`
- [Battery Sensing](https://github.com/abcdaaa1111/picomp3/blob/main/devices/battery/battery.c): `devices/battery/battery.c`
- [ADC Scan](https://github.com/abcdaaa1111/picomp3/blob/main/services/adc_scan.c): `services/adc_scan.c`
- [WS2812 Driver](https://github.com/abcdaaa1111/picomp3/blob/main/devices/led/ws2812/ws2812.c): `devices/led/ws2812/ws2812.c`

### Audio Analysis

- [Core 1 Analysis](https://github.com/abcdaaa1111/picomp3/blob/main/core1_main.c): `core1_main.c`
- [PID Algorithm](https://github.com/abcdaaa1111/picomp3/blob/main/algorithms/pid/pid.c): `algorithms/pid/pid.c`

### Other components

- **Listener**
- **SD Card**
- **PCM5102A DAC**

## Connections

- Listener → Button Input: presses
- Button Input → Player Application: provides input
- Player Application → FatFs: reads tracks (evidence: `main.c`)
- FatFs → SD Card Driver: accesses storage
- SD Card Driver → SD Card: reads blocks (evidence: `devices/sdcard/sdcard.c`)
- Player Application → MP3 Decoder: decodes frames (evidence: `main.c`)
- MP3 Decoder → PCM Output: outputs PCM
- PCM Output → PCM Channel: uses channels (evidence: `devices/sound/sound.c`)
- PCM Output → PCM5102A DAC: sends I2S
- Player Application → Graphics and GUI: updates interface
- Graphics and GUI → Bitmap Drawing: draws graphics
- Graphics and GUI → OLED Display: renders screen
- OLED Display → SSD1306 Driver: uses driver (evidence: `devices/display/display.c`)
- Player Application → ADC Scan: samples battery
- Battery Sensing → ADC Scan: reads voltage
- Player Application → WS2812 Driver: controls indicator
- Player Application → Core 1 Analysis: starts second core
- Core 1 Analysis → Graphics and GUI: sends spectrum