RadioJKK32 is an advanced internet radio project based on the ESP32-A1S (ESP32-A1S Audio Kit), built using ESP-ADF libraries and designed to provide seamless music playback with a wide range of features and control options.
- Automatic MQTT discovery – entities appear in Home Assistant without manual YAML configuration
- Full control – station, equalizer, volume, play/stop, recording, LCD on/off
- Real-time state sync – all changes (from buttons, web, or HA) are instantly reflected everywhere
- Easy setup – broker found automatically via mDNS or set manually in the web interface
- Remote control via a web browser: volume, station selection, equalizer adjustment
- Dedicated LCD on/off button in the web interface for manual display control (visible only if display is present)
- Edit the radio station list – modify, add, delete, and reorder entries
- Automatic network discovery using mDNS/Bonjour/NetBIOS
- Responsive interface that works on all devices
- Local access without the need for an Internet connection
- Automatic SD card save of the current station list
- Supports many audio formats: MP3, AAC, OGG, WAV, FLAC, OPUS, M4A, AMR
- High-quality decoding and playback
- Automatic reconnect on connection issues
- 10-band equalizer with predefined presets
- Real-time audio level indicator (display required)
- Option to enable/disable audio processing (equalizer)
- Recording to SD card in AAC format
- Automatic folder structure by date
- Info files with recording metadata
- Support for high-capacity SD cards
- Local web server – main control interface
- OLED I2C (SSD1306/SH1107) with LVGL graphical interface
- GPIO keypad with long press support
- QR codes (if display is present) for easy WiFi setup
- Station, equalizer, and volume are saved and restored after restart
- Flash memory safety – data is saved only after 10 seconds of change to avoid frequent writes
- Flash durability – with intense use (hundreds of changes/day) minimum 15 years lifespan
- Save station list to SD card in format compatible with RadioJKK
- WiFi with automatic provisioning via ESP SoftAP Prov app
- MQTT for Home Assistant integration (auto-discovery via mDNS or manual broker address)
- mDNS/Bonjour, NetBIOS for easy network discovery
- SNTP for time synchronization
- Configuration support via ESP SoftAP app
- Configuration via SD card (stations, equalizer, WiFi)
- NVS storage for persistent settings
- Automatic configuration loading on startup
- ESP32-A1S Audio Kit
- MicroSD card (optional)
- OLED I2C display (optional)
Example offer: App: AI Thinker ESP32-A1S, Web: AI Thinker ESP32-A1S
OLED SSD1306 128x64 with I2C interface. Ideally with 4 built-in buttons, or connect separate buttons for convenience, e.g. OLED SSD1306 128x64 with 4 buttons
- SDA: GPIO18
- SCL: GPIO5
- KEY4 [Up] GPIO23
- KEY3 [Down] GPIO19
- KEY2 [Eq/Rec] GPIO13/MTCK (note: change DIP switch settings)
- KEY1 [Stations] GPIO22
-
Clone the repository:
git clone --recurse-submodules https://github.com/MacWyznawca/RadioJKK.git cd radioJKK32 -
Configure ESP-IDF and ESP-ADF: Installation guide: ESP-ADF. Repository: ESP-ADF on GitHub.
Note: for ESP-IDF 5.4.x and 5.5.x use:
cd $IDF_PATH git apply $ADF_PATH/idf_patches/idf_v5.4_freertos.patch
-
Build and flash:
idf.py build idf.py -p [your/COM port] flash monitor
Exit monitor: Ctrl + ]
-
Use precompiled file: Flash selected file from the
binfolder to address 0x0 using any ESP32 flashing tool:esptool.py -p /dev/cu.usbserial-0001 write_flash 0x0 bin/RadioJKK_v1.bin
Provisioning app is disabled by default in release binaries. Use the built‑in SoftAP to set Wi‑Fi (works for both LCD and no‑LCD builds):
- On boot, the device starts SoftAP: SSID:
RadioJKK-Setup, password:radiopass - Connect to the AP, open the web UI at http://192.168.4.1 (or http://RadioJKK.local)
- Enter your Wi‑Fi SSID/password, click Save & reboot; device restarts and connects as STA
- Next access: use http://radiojkk32.local or the obtained STA IP
Fallback: if STA fails (wrong creds or default menuconfig creds), the device auto-starts the same SoftAP to let you re-enter Wi‑Fi.
Create settings.txt file with SSID and password separated by a semicolon (single line):
mySSID;myPassword
If you don’t want to start the web server, add wwwoff after the semicolon:
mySSID;myPassword;wwwoff
Via web interface or SD card
Create stations.txt file on SD card in the format:
http://stream.url;ShortName;Long station name;0;1;audio_description
Example:
http://mp3.polskieradio.pl:8904/;PR3;Polskie Radio Program Trzeci;0;1;
http://stream2.nadaje.com:9248/prw.aac;RW;Radio Wrocław;0;5;
Create eq.txt file on the SD card:
flat;0;0;0;0;0;0;0;0;0;0
music;2;3;1;0;-1;-2;0;1;2;0
rock;4;5;3;1;-1;-3;-1;3;4;0
Always 10 EQ values in dB.
Note: all config files must be saved in the root of the SD card.
- Auto discovery:
http://radiojkk32.local(via mDNS/Bonjour). NetBIOS:RadioJKK - Direct IP:
http://[device-ip-address] - Port: 80 (default)
- 📻 Playback control (play/pause/stop)
- 🔊 Real-time volume control
- 📋 Station selection with full list
- 📋 Edit station list without physical access
RadioJKK supports automatic integration with Home Assistant via MQTT discovery. All entities are created automatically — no manual YAML configuration needed.
| Entity | Type | Description |
|---|---|---|
| Station | Select | Choose from the configured station list |
| Equalizer | Select | Choose equalizer preset |
| Volume | Number | Volume level 0–100% |
| Playback | Switch | Play / Stop with state indicator |
| Recording | Switch | Start / Stop recording to SD card |
| LCD | Switch | Display on / off |
RadioJKK discovers the MQTT broker automatically via mDNS (service _mqtt._tcp). If your broker advertises this service (e.g. Mosquitto with Avahi), no manual configuration is needed.
To set the broker address manually:
- Open the web interface:
http://radiojkk32.local - Enter the MQTT broker address (e.g.
mqtt://192.168.1.100:1883) - Optionally enter Username and Password if your broker requires authentication
- Save — the device will reconnect immediately with the new settings (no restart needed)
- MQTT broker (e.g. Mosquitto) accessible on the local network
- Home Assistant with MQTT integration enabled and connected to the same broker
| Button | Short Press | Long Press |
|---|---|---|
| PLAY KEY3 | Previous station | Favorite station |
| SET KEY4 | Next station | First station |
| MODE KEY2 | Next equalizer | Reset equalizer |
| REC KEY1 | Start recording | Stop recording |
| VOL+ KEY6 | Volume up | - |
| VOL- KEY5 | Volume down | Mute |
| Button | Short Press | Long Press |
|---|---|---|
| MODE KEY1 | Station list/Confirm | Close [ESC] |
| SET KEY2 | Equalizer list | Recording start/stop |
| VOL+/- KEY4/KEY3 | Menu navigation / Volume | Mute / Favorite |
The project offers rich configuration via menuconfig:
idf.py menuconfig- Display type: SSD1306/SH1107
- Resolution: 128x64
- Button type: GPIO
- Board variant: ESP32-A1S
- SD card: enable/disable
- External keys: optional
The project supports Polish diacritics with automatic UTF-8 to ASCII conversion for monochrome displays.
You're welcome to contribute to the project!
- Fork the repository
- Create a branch for your feature
- Add changes with descriptive commits
- Submit a Pull Request
This project is licensed under the MIT License – see the LICENSE file for details.
- Espressif Systems for ESP-IDF and ESP-ADF
- LVGL for the graphics library
- Open-source community for support and inspiration
- Author: Jaromir K. Kopp (JKK)
- GitHub: MacWyznawca
RadioJKK32 – Internet radio with web control 🎵