MorayGlow

MorayGlow is an ESP32-S3 firmware that turns a 12V 5050 RGB LED strip into a smart home device. Three IRLML6344TR N-channel MOSFETs are driven by 1 kHz LEDC PWM on GPIO1, GPIO2 and GPIO6, allowing full 8-bit colour control of each channel. A MP1584 buck converter provides regulated 5V from the same 12V rail that powers the strip, keeping the BOM simple.

The device runs an ESPAsyncWebServer serving a LittleFS-hosted single-page UI, a WebSocket endpoint for real-time state push, and a JSON REST API. It simultaneously connects to an MQTT broker and publishes Home Assistant auto-discovery payloads, making it zero-configuration in a standard HA setup. State changes from any source — REST, WebSocket command, or MQTT — funnel through applyLedState() → broadcastState() → mqttPublishState(), keeping all clients in sync.

On first boot (or after a button-hold factory reset) the device starts an access point and serves a captive portal that scans for nearby networks and saves credentials to EEPROM. The mDNS-based device discovery endpoint allows the devices.html UI page to list all MorayGlow units on the local network automatically.

Control Flow

Boot & State Change Sequence

Web UI served from LittleFS on the device and mirrored by the Node.js mock server. All three pages share the same dark theme and minimalist layout.

Two build variants share the same circuit topology. The SMD build is designed for the custom PCB; the through-hole build suits breadboard or perfboard prototyping.

The schematic shows the XIAO ESP32-S3 GPIO connections. The three PWM outputs (D0, D1, D5) connect to MOSFET gates and are not shown here for clarity — see the KiCad project in docs/KiCad/ for the full schematic including the MOSFET drive and 12V strip wiring. The optional status LED circuit on D3 is shown below.

Full KiCad Schematic

The firmware is a PlatformIO project targeting the seeed_xiao_esp32s3 board using the Arduino framework. Three build environments are defined: USB flash (xiao_esp32s3), OTA Wi-Fi flash (xiao_esp32s3_ota), and native unit tests (native).

The state.h header is intentionally inline-only with #ifndef ARDUINO guards so it compiles on the native host. This lets unit tests exercise JSON serialisation and MQTT command parsing without any ESP32 hardware. Tests are written with the Unity framework and run via pio test -e native.

First-Time Setup

#define MQTT_HOST     "192.168.1.10"   // your broker IP
#define MQTT_PORT     1883
#define MQTT_USER     ""               // leave blank if unauthenticated
#define MQTT_PASSWORD ""

# Build only
& "$env:USERPROFILE\.platformio\penv\Scripts\pio.exe" run -e xiao_esp32s3

# Build + flash firmware
& "$env:USERPROFILE\.platformio\penv\Scripts\pio.exe" run -e xiao_esp32s3 -t upload

& "$env:USERPROFILE\.platformio\penv\Scripts\pio.exe" run -e xiao_esp32s3 -t uploadfs

# Firmware OTA (replace with your device hostname or IP)
& "$env:USERPROFILE\.platformio\penv\Scripts\pio.exe" run -e xiao_esp32s3_ota -t upload --upload-port morayglow-2cb120.local

# LittleFS OTA
& "$env:USERPROFILE\.platformio\penv\Scripts\pio.exe" run -e xiao_esp32s3_ota -t uploadfs --upload-port morayglow-2cb120.local

& "$env:USERPROFILE\.platformio\penv\Scripts\pio.exe" test -e native

Dev Mock Server (Client-only development)

A Node.js mock server mirrors the firmware REST and WebSocket API so the web UI can be developed without flashing hardware.

cd MorayClient/test-server
npm install        # first time only
npm start          # → http://localhost:3000

# Run Jest tests
cd MorayClient
npm test           # tests moray.js + app.js

cd MorayClient/test-server
npm test           # tests logic.js + server.js

REST Endpoints

All endpoints return Content-Type: application/json. POST bodies must be JSON. State-modifying endpoints return the new full state object.

WebSocket

MQTT Topics

Topics are prefixed with the runtime device ID (e.g. morayglow-2cb120). The MQTT command schema follows the Home Assistant JSON light schema — note it differs from the REST API format.

LWT (Last Will & Testament)

On MQTT connect the device registers {"on":false} as the LWT on its state topic. If the device disconnects unexpectedly, the broker immediately publishes this payload, allowing Home Assistant to mark the light as unavailable.