readme.md

Markdown · 84 lines

# ESP32 LED Matrix Captive Portal (8x8 WS2812B)

![Example usage](https://i.imgur.com/1usIPo8.png "Example usage")

This project turns an ESP32 into an **open Wi-Fi Access Point** with a **captive portal** (no login page) and a simple web UI to control an **8×8 addressable LED matrix** (WS2812B / NeoPixel).

When a phone/laptop connects to the AP, it is redirected to the portal automatically (DNS wildcard). From the web page you can control:
- Power ON/OFF
- Brightness (0–255, with a safety cap in firmware)
- Hue (for Solid and Chase modes)
- Animation mode (Solid, Rainbow, Plasma, Chase)

## Features
- Open Wi-Fi AP (no password) for quick access
- Captive portal using DNS wildcard (redirects any domain to ESP32)
- Web dashboard (`/`) + JSON endpoints (`/state`, `/set`)
- Smooth, non-blocking animations (~40 FPS)
- LED matrix XY mapping with optional serpentine (zigzag) layout
- Power-friendly brightness cap to reduce current draw

## Hardware
- ESP32 (any common dev board)
- 8×8 WS2812B / NeoPixel LED matrix (64 LEDs total)
- Recommended: external 5V power supply (2–3A or more depending on brightness)

## Wiring
> Use a common ground between ESP32 and the LED power supply.

| Matrix Pin | Connect To |
|-----------:|:-----------|
| +5V        | +5V power supply |
| GND        | GND power supply |
| DIN        | ESP32 GPIO5 (configurable in code) |
| ESP32 GND  | GND power supply (shared ground) |

### Recommended extras (best practice)
- 330–470Ω resistor in series on the DIN line
- 1000µF capacitor across 5V and GND near the matrix
- Optional level shifter (3.3V → 5V) if your LEDs are picky about data level

## Software Requirements
- ESP32 board support: **“ESP32 by Espressif Systems”**

### Libraries
Install via Arduino Library Manager:
- **FastLED**

Built-in (ESP32 Arduino core):
- `WiFi.h`
- `WebServer.h`
- `DNSServer.h`

## How to Use
1. Flash the firmware to your ESP32.
2. Power the ESP32 and the LED matrix.
3. Connect your phone/PC to the Wi-Fi network:
   - **SSID:** `LED-Matrix-Portal`
4. The captive portal should open automatically.
   - If it doesn’t, open a browser and go to: `http://192.168.4.1/`
5. Use the web UI to control the matrix.

## Configuration
Edit these constants in the sketch:
- `AP_SSID` / `AP_PASS` (leave empty for open AP)
- `LED_PIN` (default: GPIO5)
- `MATRIX_W`, `MATRIX_H` (default: 8×8)
- `SERPENTINE_LAYOUT` (true for zigzag wiring, false for linear rows)
- `BRIGHTNESS_CAP` (hard brightness safety limit)

## Captive Portal Endpoints
- `GET /` – web UI
- `GET /state` – JSON state:
  - `power` (bool)
  - `mode` (number)
  - `brightness` (number)
  - `hue` (number)
- `GET /set?power=1&mode=0&bri=80&hue=120` – update state

## Notes
- A full-white frame at high brightness can draw a lot of current. Use an external 5V supply and keep brightness limited.
- If the portal does not pop up, manually open `http://192.168.4.1/`.

## License
MIT