# WLED 48x32 Modular LED Matrix & DDP Control Daemon

![WLED 48x32 Matrix Demo](demo.jpg)

A high-density 1,536-pixel (48x32) modular LED matrix built across 6 panels in a 3x2 landscape layout. Features custom 3D-printed prismatic diffuser lenses and a thread-safe Python HTTP daemon streaming real-time DDP (Distributed Display Protocol) frame buffers directly to WLED.

3D CAD files, OpenSCAD scripts, and assembly specs are published on Thingiverse:  
**https://www.thingiverse.com/thing:7391918**

---

## Hardware Architecture

- **Resolution:** 48 × 32 pixels (1,536 WS2812B LEDs)
- **Panel Grid:** 6 modular tiles arranged in a 3×2 landscape grid (16×16 pixels per tile)
- **Pitch:** 10mm center-to-center
- **Diffuser System:** Modular 0.4mm transparent PLA sandwich film with integrated 1.5mm square pegs, topped with 0.8mm micro-pyramid prismatic refractors to eliminate light bleed and LED hotspots.
- **Protocol:** DDP over UDP (Port 4048)

---

## Software & Daemon Features

- **Multithreaded Engine:** Non-blocking Python daemon handling HTTP requests and real-time animation loops concurrently.
- **Active DDP Keep-Alive:** Streams dynamic background frames during scroll sweep pauses to prevent WLED timeout drops.
- **Display Modes:**
  - **Scroll Text:** Variable scroll speed, adjustable sweep pauses, and custom text payloads.
  - **Digital Clock:** Toggleable date, seconds, and blinking colon. Automatically restricts font selection to monospaced typefaces when active to eliminate horizontal layout jitter.
  - **Analog Clock:** Procedural analog clock face rendering.
- **Transient Alerts & State Restoration:** Passing a `duration` > 0 temporarily interrupts the continuous ambient display to show an alert, automatically reverting to the previous state once the timer expires.
- **Inline PNG Asset Engine:** Drop $32\times32$ or $16\times16$ transparent PNGs into the `icons/` directory and inject them inline using `{icon:filename}`. The engine preserves raw image colors while applying effects to the surrounding text.
- **Dual-Layer FX Pipeline:**
  - Independent foreground (text/clock) and background canvas effect engines.
  - Supported effects: `solid`, `rainbow`, `gradient-h` (horizontal), `gradient-v` (vertical), and `pulse`.
- **Interactive Web Control Panel:**
  - Integrated live WYSIWYG preview box with marquee scrolling animations and HTML token rendering.
  - Clickable status icon grid auto-populated from the local filesystem.
  - Real-time cURL command generator for API automation.
  - Automatic system TTF font detection and web preview font-loader.

---

## Quickstart

### 1. Run as Daemon
Start the HTTP controller on your host machine or hypervisor guest:
```bash
python3 matrix_billboard.py --daemon --listen-ip 0.0.0.0 --listen-port 8080 --ip 192.168.1.100