184 lines
10 KiB
Markdown
184 lines
10 KiB
Markdown
# 🎛️ MIDI Breadboard Instrument — Desk Rave & 16-Track Symphony Controller
|
||
|
||
[](https://docs.espressif.com/projects/esp-idf/en/v5.2.2/esp32/)
|
||
[](https://www.espressif.com/en/products/socs/esp32)
|
||
[](main/mmcontroller.c)
|
||
[](LICENSE)
|
||
|
||
A standalone, dual-core **ESP32 MIDI Synthesizer, Drum Sequencer, and 30 FPS OLED Visualizer** built from scratch in **ESP-IDF v5.2.2 (C99 / FreeRTOS)**, paired with a custom **Run-Length Encoding (RLE) Python MIDI-to-C compiler** (`scripts/midi_to_c.py`).
|
||
|
||
---
|
||
|
||
## 📸 Breadboard Hardware Gallery
|
||
|
||
| Full Breadboard Overview | Active OLED Visualizer & Controls | Multi-Buzzer & Rotary Wiring |
|
||
| :---: | :---: | :---: |
|
||
|  |  |  |
|
||
| *Dual-breadboard layout featuring ESP32, 1.3" SPI OLED, rotary encoder, tactile buttons, passive melody piezo, and dual active drum buzzers.* | *Live 30 FPS OLED HUD showing track title (`WHISP`), playback state, `SPD`/`VOL` multiplier, kick/hi-hat drum boxes, and frequency bars.* | *Close-up of the KY-040 rotary encoder, tactile control buttons, kick/hi-hat LED indicators, and triple-buzzer acoustic stage.* |
|
||
|
||
---
|
||
|
||
## 📖 1. Engineering Origin & Technical Challenges Solved
|
||
|
||
This project began as a bare-metal hardware exploration to push an ESP32 and simple piezo/magnetic transducers to their physical limits—evolving from a single-tone passive buzzer test into a 16-track polyphonic-illusion "Desk Rave" synthesizer.
|
||
|
||
Key embedded engineering challenges solved during development:
|
||
|
||
1. **The "Strobe-Light" MIDI Fragmentation Bug:** Raw MIDI files frequently split sustained notes into microscopic delta-time slices, causing the LEDs and OLED visualizer to strobe at 30+ Hz and exhausting flash memory.
|
||
2. **Custom RLE Python Compiler (`scripts/midi_to_c.py`):** We engineered a custom `mido`-based Python parser with a **Run-Length Encoding (RLE)** state machine that coalesces contiguous identical frequency/drum states into solid `SequenceStep` blocks and routes MIDI Channel 10 (plus low bass notes `< MIDI 50`) to hardware percussion triggers.
|
||
3. **Piezo Acoustic Resonance Limits:** Passive piezo buzzers physically struggle to resonate at low fundamental bass frequencies. Tracks with deep basslines—such as *Seven Nation Army*—were transposed **+2 full octaves** so the piezo disc resonates clearly while retaining rhythmic punch via the dedicated Kick/Hi-Hat active buzzers.
|
||
4. **Dual-Core FreeRTOS Lockless IPC:** To prevent SPI display transfers from introducing timing jitter into microsecond-sensitive audio generation, the firmware partitions tasks across both Tensilica Xtensa LX6 CPU cores:
|
||
- **Core 0 (UI & Human Interface):** Runs `oled_visualizer_task` (30 FPS framebuffer renderer using a zero-dependency custom 5×7 font byte array) and `button_task` (50 ms debounced input polling).
|
||
- **Core 1 (Real-Time Music Engine):** Runs `buzzer_sequence_task`, reading `SequenceStep` arrays from flash, polling the hardware **PCNT (Pulse Counter)** quadrature rotary encoder for real-time tempo (`0.2x`–`3.0x`) and PWM duty-cycle volume (`0%`–`100%`) scaling, and driving the 13-bit hardware **LEDC PWM** timer.
|
||
|
||
---
|
||
|
||
## 🧠 2. System Architecture
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph Host["Host PC Tooling (Python 3)"]
|
||
MIDI["Standard .mid Files"] --> PARSER["scripts/midi_to_c.py (RLE Compressor + Drum Router)"]
|
||
end
|
||
|
||
subgraph ESP32["ESP32 Dual-Core Firmware (ESP-IDF v5.2.2)"]
|
||
PARSER -->|Generates C Struct Arrays| FLASH["Flash Playlist (16 Tracks / SequenceStep[])"]
|
||
|
||
subgraph Core1["Core 1: Real-Time Audio Engine"]
|
||
FLASH --> ENGINE["buzzer_sequence_task"]
|
||
PCNT["Hardware PCNT Unit (Rotary CLK GPIO 32 / DT GPIO 33)"] --> ENGINE
|
||
end
|
||
|
||
subgraph Core0["Core 0: UI & Input Polling"]
|
||
BTN["button_task (Pause GPIO 13 / Next GPIO 14 / Mode SW GPIO 16)"]
|
||
OLED_TASK["oled_visualizer_task (30 FPS Framebuffer)"]
|
||
end
|
||
|
||
BTN <-->|Volatile IPC Flags| ENGINE
|
||
ENGINE -->|Volatile Pitch & Drum State| OLED_TASK
|
||
end
|
||
|
||
subgraph Hardware["Breadboard Peripherals"]
|
||
ENGINE -->|LEDC 13-Bit PWM GPIO 25| P_BUZ["Passive Buzzer (Main Melody)"]
|
||
ENGINE -->|GPIO 26 + GPIO 21| KICK["Active Buzzer 1 + Kick LED"]
|
||
ENGINE -->|GPIO 27 + GPIO 22| HAT["Active Buzzer 2 + Hi-Hat LED"]
|
||
OLED_TASK -->|10 MHz SPI2 DMA| OLED["1.3-inch SPI OLED (SH1106 / SSD1306)"]
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 🎵 3. The 16-Track Flash Symphony (`SequenceStep`)
|
||
|
||
All 16 tracks are compiled directly into ESP32 flash memory inside [`main/mmcontroller.c`](main/mmcontroller.c) using a compact 4-field C struct:
|
||
|
||
```c
|
||
typedef struct {
|
||
uint16_t frequency; // Melody pitch in Hz (0 = REST)
|
||
uint16_t duration; // Step duration in ms (scaled live by current_speed)
|
||
bool kick_drum; // Triggers Active Buzzer 1 (GPIO 26) + Kick LED (GPIO 21)
|
||
bool hi_hat; // Triggers Active Buzzer 2 (GPIO 27) + Hat LED (GPIO 22)
|
||
} SequenceStep;
|
||
```
|
||
|
||
| Index | OLED Tag | Track Title | Arrangement / Engineering Notes |
|
||
| :---: | :---: | :--- | :--- |
|
||
| `0` | `WHISP` | **Careless Whisper** | Extended Club Edit with synthesized four-on-the-floor kick/hat groove |
|
||
| `1` | `TAKE ` | **Take On Me** | High-tempo EDM build-up arrangement |
|
||
| `2` | `RICK ` | **Never Gonna Give You Up (Rickroll)** | Double chorus arrangement with syncopated percussion |
|
||
| `3` | `ELVIS` | **Can't Help Falling In Love** | Arpeggiated ballad / wedding mix |
|
||
| `4` | `GIMME` | **Gimme! Gimme! Gimme!** | ABBA midnight rave synth lead |
|
||
| `5` | `ELISE` | **Für Elise** | Beethoven trance remix |
|
||
| `6` | `MOZRT` | **Symphony No. 40** | Mozart intense strings arrangement |
|
||
| `7` | `MARIO` | **Super Mario Bros. Theme** | RLE-compressed MIDI conversion with percussion routing |
|
||
| `8` | `PIRT1` | **Pirates of the Caribbean 1** | *He's a Pirate* — RLE MIDI conversion |
|
||
| `9` | `PIRT2` | **Pirates of the Caribbean 2** | *The Black Pearl* — RLE MIDI conversion |
|
||
| `10` | `ALLA ` | **Rondo Alla Turca** | Mozart Turkish March (`scripts/midillis/Alla_Turca/Alla_Turca.mid`) |
|
||
| `11` | `TETRS` | **Tetris (Korobeiniki)** | Classic Type-A theme |
|
||
| `12` | `SONIC` | **Sonic the Hedgehog** | *Green Hill Zone* |
|
||
| `13` | `CAST ` | **Castlevania** | *Vampire Killer* |
|
||
| `14` | `SEVEN` | **Seven Nation Army** | Transposed **+2 octaves** to overcome passive piezo bass roll-off |
|
||
| `15` | `MEGA ` | **Mega Man 2** | *Dr. Wily Stage 1* |
|
||
|
||
---
|
||
|
||
## 🧱 4. Hardware Pinout & Peripherals
|
||
|
||
**Target Microcontroller:** ESP32 Development Board (Dual-Core Tensilica Xtensa LX6 @ 160 MHz)
|
||
|
||
### 🎛️ Inputs (Hardware PCNT & Active-Low Buttons)
|
||
| Component | ESP32 GPIO | Peripheral / Mode | Function |
|
||
| :--- | :---: | :--- | :--- |
|
||
| **Rotary Encoder CLK** | `GPIO 32` | Hardware `PCNT` Edge/Level | Quadrature rotation tracking (1000 ns hardware glitch filter) |
|
||
| **Rotary Encoder DT** | `GPIO 33` | Hardware `PCNT` Edge/Level | Quadrature rotation direction |
|
||
| **Rotary Encoder SW** | `GPIO 16` | Input (`GPIO_PULLUP_ONLY`) | Toggles rotary knob mode between **Speed (`SPD`)** and **Volume (`VOL`)** |
|
||
| **Pause Button** | `GPIO 13` | Input (`GPIO_PULLUP_ONLY`) | Play / Pause toggle (immediately silences outputs when paused) |
|
||
| **Next Track Button** | `GPIO 14` | Input (`GPIO_PULLUP_ONLY`) | Cycles through the 16-track playlist (`0` → `15`) |
|
||
|
||
### 🔊 Audio & LED Outputs
|
||
| Component | ESP32 GPIO | Peripheral / Mode | Function |
|
||
| :--- | :---: | :--- | :--- |
|
||
| **Passive Buzzer** | `GPIO 25` | `LEDC_CHANNEL_0` (13-bit PWM) | Plays main melody pitch (`step.frequency`) & duty-cycle volume |
|
||
| **Active Buzzer 1** | `GPIO 26` | Digital Output | **Kick Drum** acoustic transient (`45 ms` scaled pulse) |
|
||
| **Active Buzzer 2** | `GPIO 27` | Digital Output | **Hi-Hat** acoustic transient (`45 ms` scaled pulse) |
|
||
| **LED 1 (Kick)** | `GPIO 21` | Digital Output | Flashes in sync with Kick Drum hits |
|
||
| **LED 2 (Hi-Hat)** | `GPIO 22` | Digital Output | Flashes in sync with Hi-Hat hits |
|
||
|
||
### 📺 1.3" 7-Pin SPI OLED Display (SH1106 / SSD1306, 128×64)
|
||
| OLED Pin | ESP32 GPIO | SPI2 Function |
|
||
| :--- | :---: | :--- |
|
||
| **CS** | `GPIO 5` | SPI Chip Select (`10 MHz` clock) |
|
||
| **DC** | `GPIO 2` | Data / Command control line |
|
||
| **RES** | `GPIO 4` | Hardware Reset line |
|
||
| **SDA (MOSI)** | `GPIO 23` | SPI2 Master Out Slave In |
|
||
| **SCL (SCK)** | `GPIO 18` | SPI2 Serial Clock |
|
||
|
||
---
|
||
|
||
## 🛠️ 5. Building & Flashing (ESP-IDF v5.2.2)
|
||
|
||
### Prerequisites
|
||
- **ESP-IDF v5.2.2** installed and exported (`source ~/esp/esp-idf/export.sh`)
|
||
- **Python 3** with `mido` (`pip install mido`) if converting custom `.mid` files
|
||
|
||
### Build & Flash Commands
|
||
```bash
|
||
# 1. Source the ESP-IDF environment
|
||
source ~/esp/esp-idf/export.sh
|
||
|
||
# 2. Build the firmware image
|
||
idf.py build
|
||
|
||
# 3. Flash to the ESP32 and open the serial monitor
|
||
idf.py -p /dev/ttyUSB0 flash monitor
|
||
```
|
||
|
||
### Converting Custom MIDI Files (`scripts/midi_to_c.py`)
|
||
```bash
|
||
python3 scripts/midi_to_c.py scripts/midillis/Alla_Turca/Alla_Turca.mid > my_track.h
|
||
```
|
||
|
||
---
|
||
|
||
## 📂 Repository Structure
|
||
|
||
```text
|
||
├── CMakeLists.txt # Top-level ESP-IDF project build configuration
|
||
├── sdkconfig # ESP32 target configuration (Dual-Core @ 160 MHz)
|
||
├── main/
|
||
│ ├── CMakeLists.txt # Component registration
|
||
│ └── mmcontroller.c # Complete 16-track synth, OLED driver, PCNT & FreeRTOS tasks
|
||
├── scripts/
|
||
│ ├── midi_to_c.py # Custom Python RLE MIDI-to-C struct converter
|
||
│ └── midillis/ # Sample MIDI source tracks (Alla Turca, etc.)
|
||
└── images/
|
||
├── MIDI_FIRST.jpg # Full breadboard hardware build photo
|
||
├── MIDI_SECOND.jpg # Active OLED visualizer & control interface photo
|
||
└── MIDI_THIRD.jpg # Buzzer & rotary encoder wiring close-up
|
||
```
|
||
|
||
---
|
||
|
||
## 🗺️ Roadmap & Future Iterations
|
||
- **Perfboard / Custom PCB Migration:** Consolidating the dual-breadboard layout onto a soldered perfboard or custom KiCad PCB.
|
||
- **Optional WS2812B Addressable RGB Strip Expansion:** Re-introducing RMT-driven RGB lighting effects synchronized to `kick_drum` and `hi_hat` triggers.
|