readme.md
Markdown · 181 lines
# ESP32-S3 RGB LED Captive Portal

### Control the on-board WS2812B RGB LED via WiFi — no app, no internet required
This project turns an **ESP32-S3-N16R8 Dev Board** into a WiFi-controlled RGB light module.
When powered, the board creates an **open WiFi Access Point** and a **captive portal**.
Connecting a phone or laptop to the network opens a control page automatically — no URL to type.
---
## ⭐ Features
- **Open WiFi Access Point** — no password
- SSID: `ESP32-S3-RGB`
- **Automatic captive portal**
- Works with Android / iOS / macOS / Windows / Linux
- **Real-time RGB control (no page reload)**
- Canvas-based HSV colour wheel — tap or drag to pick any colour
- Master brightness slider
- ON / OFF toggle with live glow preview
- **JSON REST API** — easy to extend or integrate
- Fully self-contained — no router, no cloud, no app
---
## 📦 Hardware Requirements
| Item | Notes |
|------|-------|
| **ESP32-S3-N16R8 Dev Board** | 16 MB Flash, 8 MB OPI PSRAM, dual USB-C |
| USB-C cable | For power and flashing |
| No other components | The on-board WS2812B RGB LED is used |
### On-board WS2812B LED
Most ESP32-S3 development boards with a built-in RGB LED connect it to **GPIO 48**.
Some boards (or alternative firmware builds) use **GPIO 38** instead.
```cpp
#define RGB_PIN 48 // ← change to 38 if your LED does not respond
```
> **How to find the correct pin:** Check your board's silkscreen or schematic.
> If `48` doesn't work, try `38`. The LED is the small component labeled **RGB** on the PCB.
### Dual USB-C ports
| Port | Purpose |
|------|---------|
| Upper port (UART / CH340) | Firmware upload and Serial Monitor |
| Lower port (Native USB) | Power only, or USB-CDC when enabled in firmware |
When using the **native USB port** for the Serial Monitor, make sure
**"USB CDC On Boot: Enabled"** is set in Arduino IDE (see board settings below).
---
## 🚀 Usage
1. **Power the board** via USB-C.
2. On your phone or laptop, open WiFi settings and connect to **`ESP32-S3-RGB`** (open, no password).
3. A browser tab opens automatically — if not, navigate to **`http://192.168.4.1`**.
4. Use the controls:
| Control | Function |
|---------|---------|
| Colour wheel | Tap or drag anywhere on the circle — angle = hue, distance from centre = saturation |
| Brightness slider | Dim or intensify without changing the hue |
| Turn ON / Turn OFF | Toggle LED on or off; glowing preview reflects the current colour and brightness |
---
## 🔌 REST API
The web page communicates with the board via two lightweight JSON endpoints.
You can also call them directly from any HTTP client (browser, curl, etc.).
### `GET /api/status`
Returns the current LED state.
**Example response:**
```json
{
"on": true,
"r": 255,
"g": 80,
"b": 0,
"brightness": 200
}
```
### `GET /api/set`
Updates any combination of parameters. Missing parameters keep their current value.
**Query parameters:**
| Parameter | Range | Description |
|-----------|-------|-------------|
| `on` | `0` / `1` | Turn LED off / on |
| `r` | `0–255` | Red channel |
| `g` | `0–255` | Green channel |
| `b` | `0–255` | Blue channel |
| `bri` | `0–255` | Master brightness |
**Examples:**
```
# Turn on with orange at 50% brightness
http://192.168.4.1/api/set?on=1&r=255&g=100&b=0&bri=128
# Just change brightness
http://192.168.4.1/api/set?bri=64
# Turn off
http://192.168.4.1/api/set?on=0
```
---
## 🖥️ Serial Monitor Output
Open the Serial Monitor at **115 200 baud** to see startup diagnostics:
```
=== ESP32-S3 RGB Captive Portal ===
WS2812B: GPIO 48
AP: ESP32-S3-RGB | IP: 192.168.4.1
HTTP server + DNS captive portal started.
===================================
```
---
## 📡 Captive Portal OS Compatibility
| Platform | Detection endpoint served |
|----------|--------------------------|
| Android | `/generate_204` |
| iOS / macOS | `/hotspot-detect.html` |
| Windows | `/ncsi.txt` |
| Linux / Firefox | `/connectivity-check` |
| Any other URL | `302 redirect → /` |
---
## ⚙️ Configuration Reference
All user-adjustable constants are at the top of the `.ino` file:
```cpp
#define RGB_PIN 48 // GPIO for WS2812B; try 38 if needed
#define RGB_COUNT 1 // Number of chained LEDs
const char* AP_SSID = "ESP32-S3-RGB"; // WiFi network name
IPAddress apIP(192, 168, 4, 1); // AP / portal IP address
```
To chain **multiple LEDs**, increase `RGB_COUNT`. `applyLed()` currently drives only pixel 0 — update it to loop over all pixels if needed.
---
## 📁 File Structure
```
esp32s3_rgb_captive_portal/
├── esp32s3_rgb_captive_portal.ino # Main sketch (firmware + embedded HTML)
└── README.md # This file
```
---
## 🔢 ESP32-S3 Module Variant — N16R8
| Field | Value | Meaning |
|-------|-------|---------|
| N16 | 16 MB | NOR Flash size |
| R8 | 8 MB | OPI PSRAM size |
This is why **OPI PSRAM** must be selected in the board settings —
selecting `Quad PSRAM` or `Disabled` will cause a boot panic on this variant.