# esp32-WS2812B-8x8-matrix

> ESP32 firmware that creates an open Wi-Fi Access Point with a captive portal and a web UI to control an 8×8 WS2812B LED matrix (power, brightness, color hue, and simple animations) using FastLED.

- Author: Mikrobot.pl
- Platform: ESP32
- Board: ESP32 Dev Module (`esp32:esp32:esp32`)
- SDK version: 3.3.6
- Tags: #esp32, #captive-portal, #fastled, #led-matrix, #ws2812b
- Created: 2026-03-05
- Updated: 2026-10-23
- Favorites: 1, forks: 0
- Project page (view, flash from the browser, fork): https://flashesp.com/explore/oc6qoqqV4K0N3mqQLkgcT
- Download all sources (zip): https://flashesp.com/api/public-projects/oc6qoqqV4K0N3mqQLkgcT/download-sources/

## Source files

- [libraries_lock.json (87 B)](https://flashesp.com/explore/oc6qoqqV4K0N3mqQLkgcT/files/nQFNhdLN6AfIcXKj4y2j6.md)
- [main.ino (8.9 KB)](https://flashesp.com/explore/oc6qoqqV4K0N3mqQLkgcT/files/0sZgEILKbcV5Y1mRHOa8T.md)
- readme.md (2.9 KB)

## README

# 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
