PlaiiinLightOS

Make any LED lamp think. PlaiiinLightOS is open firmware for ESP32 microcontrollers driving addressable LED strips and matrices — AI-aware, scriptable, OTA-updatable, with HTTP, WebSocket, BLE, and MQTT control surfaces. Describe a pattern in plain words, let an AI write the effect, and watch it light up.

Runs the whole PlaiiinLight lamp family — towers, cubes, wall displays, rockets, wormholes, and plain strips — and any WS2812 / SK6812 / SK9822-class LED hardware you wire up yourself.

Getting started

The fastest way to a running lamp — no toolchain needed — is a prebuilt binary: grab your form's flash.bin from the latest release (<form>-flash.bin for classic ESP32 boards, <form>-esp32c3-flash.bin for the ESP32-C3, <form>-esp32c6-flash.bin for the ESP32-C6, <form>-esp32c5-flash.bin for the ESP32-C5), or flash straight from the browser (Chrome/Edge) using the release's ESP Web Tools manifest.

Building from source is three commands:

git clone https://github.com/nebeleben/plaiiin-light.git
cd plaiiin-light
./scripts/setup.sh                    # installs ESP-IDF v5.3.2 + tools
./scripts/build.sh --form display     # tower | display | cube | rocket | wormhole | strip
                                      # add --chip esp32c3 / esp32c6 / esp32s3 for those boards;
                                      # --chip esp32c5 needs ESP-IDF v5.5 at ~/esp/esp-idf-v5.5

That drops two artifacts into build/dist/: a merged …-flash.bin for USB first-flash and an …-app.bin OTA payload for wireless updates.

Burn it to the device over USB — profile-burn erases the chip, writes the firmware, burns the device's hardware identity (LED count, GPIO, lamp type, form) from profiles/, and installs its per-form effects in one shot:

./scripts/profile-burn.sh --full /dev/cu.usbserial-0001 display/<device>

First boot: the lamp opens a WiFi access point PlaiiinLight-XXXX — connect, enter your home WiFi at http://192.168.4.1/network, and after the reboot the lamp is on your network. Everything else happens in the built-in web portal at http://<device-ip>/ — and every update from then on is wireless via /ota.

Features

All the features you ever wanted from a lamp OS — and a few you didn't know you did:

• AI Compose — describe an effect in natural language on /compose; the AI writes it, the browser previews it, one click saves it to the lamp. Bring your own key (Claude, GPT, or a local LLM) — it never touches the device.
• Scriptable effects — effects are tiny JavaScript shade() shaders, compiled to PLBC bytecode and played on-device by a purpose-built VM at your chosen FPS.
• Script library & tunes — list, edit, save, and play scripts on the lamp; every script exposes parameter knobs and switches you can tweak live.
• Full web portal — control, compose, stream, draw, scripts, config, network, MQTT, and OTA pages served straight from the lamp. Day/night theme included.
• GIF & image streaming — drag a GIF onto /stream and it plays on the matrix, serpentine mapping and rotation handled for you.
• WebSocket pixel streaming — a compact binary protocol for real-time frames from any client you write.
• Draw / frame mode — paint pixel art on a grid (or drop an image) in the app or the on-device /draw editor, push it once, and the lamp holds the still frame reboot-safe until you change it — no client needs to stay connected to keep it lit.
• Saved images & carousel — keep up to 30 drawings in the lamp's own image library (/api/images), browse them as thumbnails in the apps or /draw, and play them as a slideshow with the built-in carousel effect — dwell, crossfade, and shuffle are live-tunable knobs.
• HTTP API — power, color, brightness, modes, scripts, limits, OTA: everything the portal does, a curl away.
• MQTT — power, color, brightness, mode, and effect next/prev topics for Home Assistant, Node-RED, and friends.
• Swarm mode — group nearby lamps into a masterless ESP-NOW mesh: change one lamp's color, brightness, or effect and the whole group follows. HMAC-authenticated, de-duplicated multi-hop flood, and it works with no router at all — AP-less lamps included.
• BLE onboarding & control — claim a fresh lamp and hand it WiFi credentials over an encrypted Bluetooth link, no captive-portal hopping.
• Ownership & sharing — lamps are open until claimed; claiming mints a bearer token, and owners can share role-scoped keys (user / creator / admin) — revocable any time.
• OTA updates — dual-slot, form-checked (a tower binary can't brick a ), with config and scripts preserved.

Supported Devices

Microcontrollers

Any ESP32 development board with at least 4 MB flash works. Five SoC targets are supported by the build system (./scripts/build.sh --chip …):

Chip	Boards (examples)	Notes
ESP32 (classic)	ESP32 Mini / D1 Mini ESP32, ESP32 DevKit	Dual-core Xtensa @ 240 MHz — the fleet default; prebuilt <form>-*.bin release binaries
ESP32-C3	C3 SuperMini, C3 DevKit	Single-core RISC-V @ 160 MHz — prebuilt <form>-esp32c3-*.bin release binaries, or build with --chip esp32c3
ESP32-C6	C6 Super Mini (C6FH4), C6 DevKit	Single-core RISC-V @ 160 MHz, Wi-Fi 6 (2.4 GHz), BLE 5 — prebuilt <form>-esp32c6-*.bin release binaries, or build with --chip esp32c6; builds -Os (see sdkconfig.esp32c6.defaults, ~88% of the OTA slot)
ESP32-C5	C5 DevKitC-1	Single-core RISC-V @ 240 MHz, Wi-Fi 6 dual-band, BLE 5 — experimental: prebuilt <form>-esp32c5-*.bin release binaries (may be absent from a release), or build with --chip esp32c5
ESP32-S3	S3 Super Mini (S3FH4R2), S3 DevKit	Dual-core Xtensa @ 240 MHz — prebuilt <form>-esp32s3-*.bin release binaries, or build with --chip esp32s3 (verified on a Super Mini; profiles/strip/s3mini drives its onboard WS2812 on GPIO 48)

Every lamp form builds for every chip; the C3, C5, C6 and S3 differ only in bootloader offset and (C3/C6) CPU clock, which the build script handles. The C5 is the one exception on toolchain: it only exists as a target from ESP-IDF v5.5, so --chip esp32c5 builds against a second IDF checkout (~/esp/esp-idf-v5.5, or IDF_DIR=…) while everything else stays on the pinned v5.3.2 — and it builds -Os (see sdkconfig.esp32c5.defaults) because the 5.5 radio stack doesn't fit the shared OTA slots at -Og. Even so a 4 MB C5 sits at ~97% of an OTA slot (Espressif's Wi-Fi 6 + BLE 5 blobs are ~250 KB larger than the 5.3.2 ones and can't be trimmed), so treat it as a bring-up target: a C5-based lamp wants the 8 MB module and its own partition table. The lamp still uses 2.4 GHz only; 5 GHz isn't wired up.

Boards that expose only the SoC's native USB-Serial/JTAG port (S3 Super Mini, C5 DevKit) can wedge esptool on macOS after a few monitor/flash sessions ("download mode detected, but no sync reply") — unplug/replug the board; ESPTOOL_OPTS on profile-burn.sh passes extra esptool flags if a board needs them.

LEDs

All common addressable strip and matrix chipsets, one- and two-wire:

Chipset	Wiring	Notes
WS2812 / WS2812B (NeoPixel)	1 wire (data)	The default; unknown types fall back to it
SK6812	1 wire (data)	RGB variant
SK6812W / SK6812 RGBW	1 wire (data)	4-channel RGBW, dedicated white LEDs driven natively
SK9822 / APA102 (DotStar)	2 wire (data + clock)	SPI+DMA driver — flicker-free even with WiFi busy

The chipset, data/clock GPIOs, and LED count are per-device hardware identity (burned via profile-burn, editable on /config) — no firmware rebuild needed to switch strips.

Powering the LEDs — don't run a panel off USB

The LEDs are the load, not the MCU. A WS2812 pulls up to ~60 mA at full white, so a 256-pixel matrix can draw ~15 A (≈7 A at mid-brightness). Give the LEDs their own 5 V supply sized for that, tie its ground to the board's ground, and run only the data line to the LED GPIO. Powering a sizable strip or matrix from the board's USB / 5 V pin is out of spec.

If you do, the inrush on a power-on, mode switch, or bright frame sags the 3.3 V rail and the SoC's brownout detector resets the chip — so the lamp appears to "restart on every change". This is a power problem, not a firmware fault; the serial console shows Brownout detector was triggered. Boards with only a native USB-Serial/JTAG port and a lean 5 V path are the most exposed — the ESP32-C5 DevKit notably, which already runs its brownout detector at the most tolerant threshold it offers (2.51 V; a classic ESP32 bottoms out lower, at 2.43 V), so there is no config headroom left to relax. A stiffer board like an ESP32 Mini may ride through the same undervoltage silently rather than resetting — it is not immune, just quieter.

Two ways out: a proper external 5 V supply (plus a ~1000 µF cap across 5 V/GND at the panel to absorb inrush); or, to bench-test without one, cap the draw in firmware with POST /api/limits {"maxCurrentMa":…} (and/or maxBrightness), which scales brightness so the current never spikes. Those limits persist in NVS — no reflash.

Specs

Want the deep end? SPECS.md is the full technical reference: build system and per-form binaries, the complete HTTP API and WebSocket protocol, the shade() script contract, MQTT topics, the security and pairing model, persistence, partition table, and error indicators. Client authors should start with the canonical wire contract in docs/protocol.md — third-party clients are explicitly welcome.

Latest release

Current firmware: v2.6.0 — grab it from the releases page. Every release ships, per form and per chip (classic ESP32, ESP32-C3, ESP32-C6 and ESP32-C5, the RISC-V ones with an -esp32c3 / -esp32c6 / -esp32c5 infix): a flash.bin (USB first-flash), an app.bin (OTA payload), an effects.bin (per-form effects image), an ESP Web Tools manifest for browser flashing, and SHA256SUMS.

What's new in the 2.x line:

• v2.6.0 — scenes. A scene is a named, saved snapshot of the lamp's state (on, mode, effect and its params or a saved image, colour, brightness), stored on the lamp and recalled in one call: POST /api/scenes/<name>/capture saves what the lamp is doing right now, POST /api/scenes/<name>/activate brings it back in the right order with the normal fades, and GET /api/scenes lists them. Every field is optional, so a partial "mood" scene that only sets a colour works too. Up to 32 per lamp; they mirror to the swarm like manual control. API version 2.5.0 (additive).
• v2.5.0 — agent-ready API. The whole HTTP contract is served machine-readably at GET /api/openapi.json (OpenAPI 3, unauthenticated, gzipped), so an AI agent or any tool-binding client can discover every operation from the lamp itself. GET /api/js gains an additive effects array with a description, tags and source per effect, so a client can pick an effect by intent ("something cozy") instead of by name; every shipped effect is annotated, and your own scripts self-describe from a // @description / // @tags header or their leading comment. POST /api/color accepts {"color":[r,g,b]} to paint every LED without knowing the LED count. API version 2.4.0 (additive; existing clients unaffected).
• v2.4.0 — brown-out-safe boot. Lighting the panel is a lamp's biggest current surge, so boot no longer does it early: the lamp comes up dark but reachable (Wi-Fi + HTTP first), then restores and soft-starts the panel over ~0.8 s, so its inrush never coincides with the Wi-Fi bring-up. A boot-loop breaker counts consecutive boots that fail to stay up (a brown-out is a non-power-on reset); after three it enters safe boot — panel held off, lamp dark but reachable (safeBoot in GET /api/health) — so an under-powered lamp never loops forever. An explicit POST /api/power resumes. See the Powering the LEDs and Brown-out-safe boot sections of SPECS.md. API version unchanged at 2.3.0.
• v2.3.0 — model identity. Every lamp now reports modelName + modelVersion (GET /api, BLE device-info), which the apps show as the model (tower8 + v2 = tower8v2); a profile's filename is that model. The lamp name is separate: a freshly burned lamp boots as <name>-<MAC suffix> (tower8-3FA8, the same suffix as its provisioning AP) so several lamps of one model stay distinguishable, and a full factory reset restores that factory name. Lamps that OTA onto 2.3.0 keep their existing name and derive the model from it. API version 2.3.0 (additive; older clients ignore the fields).

Earlier — the 1.9 line:

• v1.9.14 — smoother onboarding: the WiFi network scan works before the lamp has a connection, slow WiFi at boot no longer costs you mDNS/MQTT or the portal, and the panel and /api/state stay in agreement after setup.
• v1.9.13 — prebuilt ESP32-C3 binaries for every lamp form now ship with each release, alongside the classic ESP32 set.
• v1.9.12 — ESP32-C3 support lands: build any form with --chip esp32c3; /api/ota/info now reports the chip target so updaters can't cross-flash; new shrumLight (24-LED strip) profile.
• v1.9.11 — web server no longer wedges when clients leave connections half-open: stale sockets are purged (LRU) so the portal and API stay reachable.
• v1.9.10 — the factory-reset recovery key is now durable: it survives reset and unpair, so a lost lamp can always be recovered.
• v1.9.9 — release-pipeline rebuild; no firmware changes.
• v1.9.8 — recovery-key endpoints (/api/reset-key); effect next/prev no longer stalls on an uncompilable script; fire effect fixed on pixel-grouped displays.
• v1.9.7 — MQTT learned mode switching (color/js) and effect next/prev topics; portal root now redirects to /control; knob and switch tunes on the Scripts and Compose pages.

License

Everything in this repository is Apache License, Version 2.0 — see LICENSE. Audit it, fork it, run it on your own hardware, ship products that include it; the only requirement is the standard Apache 2.0 attribution + notice retention.