TLED - Matter-over-Thread LED Controller

A Matter-compatible LED strip controller for ESP32-C6 that works over Thread networking. Control addressable LED strips (WS2812B, SK6812, etc.) from Home Assistant, Apple Home, Google Home, or any Matter-compatible smart home platform.

Disclaimer: This entire firmware was written by AI (Claude by Anthropic). I (@maui1911) have not read or written a single line of code — I only provided direction, tested on real hardware, and deployed. Use at your own risk.

Features

Matter over Thread - Native Matter protocol, no cloud or WiFi required
Full RGB + RGBW control - Color picker, brightness, on/off from your smart home app
Smooth transitions - 300ms fades on all changes
Thread mesh networking - Self-healing network, device acts as a router
Web-based installer - Flash firmware directly from your browser
USB configuration - Change settings via serial without recompiling
NVS persistence - Settings survive reboots
Temperature monitoring - Chip temperature exposed to Home Assistant
Health monitoring - Watchdog timer, heap tracking, auto-reboot on hang
Power-on behavior - Configurable: restore last state, always on, or always off
Built-in effects - Rainbow, breathing, candle, chase (implemented but not yet user-accessible, untested)

Hardware

This project was developed for the DFRobot Beetle ESP32-C6 - a tiny 25mm × 20.5mm board that's perfect for embedding in LED strip projects. Any ESP32-C6 board should work, but the Beetle's small size makes it ideal.

Requirements

ESP32-C6 board - DFRobot Beetle ESP32-C6 recommended (or any ESP32-C6)
Addressable LED strip - WS2812B, WS2811, or SK6812 (RGBW)
5V power supply - Size for your LED count (~60mA per LED at full white)
Thread border router - HomePod Mini, Apple TV 4K, Google Nest Hub, or dedicated like SLZB-06/SMLight

3D Printable Enclosure

A parametric OpenSCAD enclosure design is included in the enclosure/ folder, sized specifically for the DFRobot Beetle ESP32-C6.

Features:

Friction-fit lid - No screws needed, snaps securely in place
USB-C port cutout - Easy access for flashing and power
Wire slit - Solder your wires first, then slide them into the enclosure
Super compact - Just slightly larger than the Beetle board itself

Ready-to-print STL files (tled_base.stl, tled_lid.stl) are included in the enclosure/ folder. If you want to tweak dimensions, open tled_enclosure.scad in OpenSCAD - it's fully parametric so you can adjust wall thickness, tolerances, and ventilation hole sizes.

Printing tips:

Print the base upside-down (opening facing up)
0.2mm layer height works well
No supports needed
PLA or PETG recommended

Quick Start

1. Flash the Firmware

Visit the Web Installer and click "Install TLED Firmware".

Note: Requires Chrome or Edge browser. If prompted, hold the BOOT button on your ESP32-C6 while clicking Install.

2. Configure Your LED Strip

Go to the Configure tab in the web installer
Click Connect to Device
Set your LED count, GPIO pin, and LED type
Click Save & Reboot

3. Commission to Your Smart Home

After reboot, a QR code will appear in the web installer. Scan it with:

Home Assistant - Settings → Devices & Services → Add Integration → Matter
Apple Home - Add Accessory → Scan QR Code
Google Home - Add Device → Matter-enabled device

Configuration Options

| Setting | Default | Description | |---------|---------|-------------| | LED Count | 10 | Number of LEDs in your strip (1-1000) | | GPIO Pin | 5 | Data pin connected to LED strip | | LED Type | WS2812B | Chipset: WS2812B, WS2811, or SK6812 (RGBW) | | RGB Order | GRB | Color byte order (try others if colors are wrong) | | Max Brightness | 255 | Limits maximum brightness (saves power) | | Device Name | TLED | Name shown in your smart home app | | Power-on | restore | Behavior on power up: restore last state, on, or off |

Wiring

ESP32-C6          LED Strip
─────────         ─────────
GPIO 5    ────────  DIN (Data In)
GND       ────────  GND
                    5V  ──── External 5V Power Supply

Important: Power your LED strip from an external 5V supply, not from the ESP32's 5V pin (except for very short strips).

Serial Commands

Connect via USB and use the serial console in the web installer, or any serial terminal at 115200 baud:

help                    Show available commands
config                  Show current configuration
set leds <n>            Set number of LEDs (1-1000)
set gpio <n>            Set data GPIO pin
set type <type>         Set LED type (ws2812b/ws2811/sk6812)
set order <order>       Set RGB order (grb/rgb/brg/rbg/bgr/gbr)
set brightness <1-255>  Set max brightness
set name <name>         Set device name
set poweron <mode>      Power-on behavior (restore/on/off)
save                    Save configuration and reboot
reboot                  Restart device
factory                 Factory reset (erases settings & commissioning)

Building from Source

Prerequisites

Build & Flash

# Source the environments
source ~/esp/esp-idf/export.sh
source ~/esp/esp-matter/export.sh

# Build
idf.py build

# Flash (keeps commissioning data)
idf.py -p /dev/ttyACM0 flash

# Flash with erase (clears commissioning - need to re-pair)
idf.py -p /dev/ttyACM0 erase-flash flash

# Monitor serial output
idf.py -p /dev/ttyACM0 monitor

Configuration via menuconfig

idf.py menuconfig
# Navigate to "TLED Configuration" for build-time defaults

Troubleshooting

Can't flash the device

Use Chrome or Edge (Firefox doesn't support Web Serial)
Hold the BOOT button while clicking Install
Try a different USB cable (some are charge-only)

"No bootable app partitions" / Boot loop

Flash was interrupted. Try flashing again.

Can't find device during commissioning

Commission within 30 seconds of boot (BLE advertising slows down)
Run factory command if device was previously commissioned
Move closer to your Thread border router

Wrong colors

Try different RGB Order settings (GRB → RGB → BGR → RBG)

LEDs don't light up

Check 5V power supply connection
Verify GPIO pin matches your wiring
Confirm LED count is correct

Project Structure

TLED/
├── main/
│   ├── app_main.cpp            # Matter setup, endpoint creation
│   ├── app_driver.cpp          # LED strip driver, transitions, effects
│   ├── app_nvs_config.cpp      # Runtime configuration storage
│   ├── app_serial_config.cpp   # USB serial command interface
│   ├── app_monitoring.cpp      # Health monitoring, watchdog, temperature
│   ├── app_device_info.cpp     # Matter device branding
│   ├── app_ble_config.cpp      # BLE commissioning configuration
│   └── Kconfig.projbuild       # Build-time configuration options
├── web-installer/
│   ├── index.html              # Web installer & configurator
│   └── manifest.json           # ESP Web Tools manifest
├── enclosure/
│   ├── tled_enclosure.scad     # OpenSCAD parametric enclosure design
│   ├── tled_base.stl           # Pre-exported base STL
│   └── tled_lid.stl            # Pre-exported lid STL
├── partitions.csv              # Flash partition layout
└── sdkconfig.defaults          # Default SDK configuration

License

MIT License - see LICENSE for details.

Acknowledgments

ESP-Matter - Espressif's Matter SDK
ESP Web Tools - Browser-based flashing
ConnectedHomeIP - Matter protocol implementation

TLED

Install / Use

README