Hex Hive

A local web tool for controlling a hexagonal WLED LED-strip installation.

Arrange hexagons in a layout, map physical LEDs to each hex, then drive the strip with curated patterns, per-hex painting, static scenes, and animated waves. The browser never contacts WLED directly — a server-side proxy handles HTTP and a WebSocket subscriber mirrors live device state back to the UI.

Features

• Layout designer — arrange hex tiles, drag-and-snap, save layouts to disk.
• LED mapper — map each hex tile to one or more LED ranges on the strip, with a mini-preview.
• Per-hex painting — pick a color, click hexes, push the result to WLED.
• Patterns / scenes / waves — curated catalog plus a server-side render loop for animated waves.
• Live state mirroring — what you see in the browser is what the strip is doing, via WLED's WebSocket.
• No database, no cloud — JSON files in data/, logs in logs/hex-hive.log, that's it.

Requirements

• Node.js 18+ and npm.
• A WLED device on your local network (tested against an ESP8266; ESP32 should work).
  • Reachable at wled.local or a static IP — you configure the host in the UI.
  • WLED auth must be off (not currently supported by this app).
  • For WS281x strips: set color order to GRB in WLED's own settings.

Install

git clone https://github.com/joeltelling/HexHive.git
cd HexHive
npm install
cp .env.example .env     # optional — only LOG_LEVEL lives here

Run

npm run dev              # http://localhost:3000  (auto-bumps to 3001+ if taken)
npm run logs             # second terminal: pretty-printed log tail

Then open the app, enter your WLED host (wled.local or 192.168.x.y) in the top bar, and start designing.

For a production build:

npm run build
npm run start

Scripts

Script	Does
npm run dev	Next.js dev server
npm run build	Production build
npm run start	Production server
npm run logs	Tail logs/hex-hive.log through pino-pretty
npm run typecheck	tsc --noEmit

Environment

Var	Default	Purpose
LOG_LEVEL	debug	Pino log level (trace/debug/info/warn/error)
NODE_ENV	—	production disables the stdout log stream

The WLED host is not an env var — it's set in the UI and persisted to data/config.json.

Stack

Next.js 14 (App Router) · React 18 · TypeScript (strict) · Tailwind CSS · Pino · ws · zod. File-based persistence in data/.

Documentation

Full design docs live in docs/:

• architecture.md — system design, data flow, source layout
• api.md — REST + SSE endpoint reference
• wled.md — WLED HTTP client, payload encoder, WebSocket subscriber
• wave-streamer.md — server-side wave render loop
• frontend.md — React components and state context
• storage.md — file-based JSON persistence
• catalogs.md — pattern / scene / wave catalogs and hex math
• development.md — workflow, env vars, and the known pitfalls (read this before debugging anything that "should work")
• CHANGELOG.md — dated log of changes

License

GPL-3.0. If you fork or build on this, your derivative work must also be GPL-3.0.

Acknowledgements

Built on WLED by Aircoookie and contributors.