WLED_Billboard/README.md

WLED 48x32 Modular LED Matrix & DDP Control Daemon

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 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.
• 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.
  • Native HTML5 color wheel selectors.
  • 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 (e.g., Aurelia or hypervisor guest):

python3 matrix_billboard.py --daemon --listen-ip 0.0.0.0 --listen-port 8080 --ip 192.168.195.216

### 2. restfulAPI example

bash curl -X POST "http://localhost:8080/"

 -H "Content-Type: application/json" \
 -d '{
   "mode": "scroll",
   "text": "WOMAN CAVE",
   "effect": "gradient-h",
   "color": "#ff00ff",
   "color2": "#00ffff",
   "bg_effect": "solid",
   "bg_color": "#000000",
   "speed": 0.04,
   "sweep_pause": 2.0,
   "brightness": 255
 }'