readme.md
Markdown · 183 lines
---
# ESP32 Internet Radio – WiFi Captive Portal Setup
### Configure WiFi credentials via captive portal and stream internet radio 🎶
This project turns an **ESP32** into a **standalone internet radio receiver** with a built-in **WiFi captive portal**.
On first boot (or when no WiFi credentials are stored), the ESP32 creates its own **WiFi Access Point** and displays a **captive portal** that allows the user to:
* scan for nearby WiFi networks
* select a network
* enter the WiFi password
The credentials are saved in flash memory, the device **automatically reboots**, connects to the selected network, and starts **streaming internet radio** via **I2S audio output**.
---
## ⭐ Features
* 📡 **WiFi captive portal for first-time setup**
* Automatic WiFi network scan
* SSID + password entry via browser
* 🌐 **Auto redirect captive portal**
* Works on Android / iOS / Windows / Linux
* 💾 **WiFi credentials stored in flash (NVS)**
* No need to reconfigure after power loss
* 🔁 **Automatic reboot after configuration**
* 🎶 **Internet radio streaming (MP3)**
* 🔊 **I2S audio output**
* Compatible with PCM5102MK, PCM5102A, etc.
* 🔌 Fully standalone – no serial input required after flashing
---
## 📦 Hardware Requirements
* **ESP32** (ESP32-WROOM / Dev Module / DevKitC)
* **I2S DAC or amplifier**
* PCM5102MK (recommended)
* PCM5102A
* Speaker or external audio system
* WiFi network with internet access
### Default I2S pin configuration
```cpp
// GPIO26 -> BCLK
// GPIO25 -> LRC (WS / LCK)
// GPIO22 -> DIN / DATA
```
> ℹ️ Pins can be changed in the code if needed.
---
## 🔧 Software Requirements
* **Arduino IDE**
* **ESP32 Board Package**
```
Boards Manager → esp32 by Espressif Systems
```
### Required Libraries
Install via **Arduino Library Manager**:
* `WiFiManager` by tzapu
* `ESP32 Audio I2S` (ESP8266Audio)
Used core libraries:
* `WiFi`
* `WebServer`
* `DNSServer`
---
## 🚀 Getting Started
1. Open the project in **Arduino IDE**
2. Select the board, for example:
```
ESP32 Dev Module
```
3. Select the correct **COM port**
4. Upload the sketch to the ESP32
5. Open **Serial Monitor** (115200 baud) for logs (optional)
---
## 📶 First Boot – WiFi Configuration
1. Power the ESP32
2. A new WiFi network appears:
```
ESP32-Radio-Setup
```
3. Connect to it using your phone or computer
4. The **captive portal opens automatically**
* If not, open:
```
http://192.168.4.1
```
5. Select your WiFi network
6. Enter the password
7. Click **Save**
➡️ The ESP32 will reboot automatically and connect to WiFi.
---
## 🎧 Normal Operation
After WiFi credentials are stored:
1. ESP32 boots
2. Connects to saved WiFi automatically
3. Starts streaming internet radio
4. Audio is played via the I2S DAC
No user interaction required 🎵
---
## 🌍 Captive Portal Behavior
The captive portal responds to common OS connectivity checks:
* **Android** → `/generate_204`
* **iOS / macOS** → `/hotspot-detect.html`
* **Windows** → `/ncsi.txt`
Any URL entered in the browser is redirected to the WiFi configuration page.
---
## 🔁 Reset WiFi Settings
To force WiFi reconfiguration, you can:
* call `wm.resetSettings()` in code (temporary)
* or add a **physical reset button** (recommended)
This will erase stored credentials and re-enable the captive portal.
---
## 🛠 Customization Ideas
You can easily extend this project with:
* 🎛 Web interface for:
* volume control
* station selection
* 📻 Multiple radio stations
* 💾 Station list stored in flash
* 🔘 Hardware buttons
* 📡 OTA firmware updates
* 🎨 Custom captive portal UI (HTML/CSS)
* 💤 Deep sleep support
---
## 📄 License
This project is released under the **MIT License**.
You are free to use, modify, and share it in personal and commercial projects.
---