readme.md

Markdown · 181 lines

# ESP32-S3 RGB LED Captive Portal
![Web Portal](https://i.imgur.com/QhLLEGO_d.webp?maxwidth=500&fidelity=grand "Web 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.