WLEDAura

Change colors on WLED strand based on system load.

WLEDAura is a lightweight, zero-dependency Python daemon designed to run in the background on macOS. It continuously monitors system load average and mirrors the thermal state of your Mac onto a WLED addressable LED strip over the network using WLED's high-speed UDP Realtime / Sync interface (port 21324).

As the workload changes, the lighting smoothly shifts across a classic color temperature palette—from serene cool tones to warm amber and hot crimson—while sparse, breathing fairy twinkles gently shimmer throughout the strip.

---

Features

• macOS System Load Monitoring:
  • Samples macOS load average (1m, 5m, or 15m) using os.getloadavg().
  • Automatically scales load relative to total CPU core count (os.cpu_count()), or custom threshold.
  • Applies Exponential Moving Average (EMA) smoothing to prevent jarring color jumps during short spikes.
• Color Temperature Gradient:
  • Cool (Idle / Low Load): Deep ice blue & cyan (#0046ff, #00bef5).
  • Temperate (Normal Load): Emerald green / lime (#1ed75a).
  • Warm (Moderate Load): Amber gold & radiant orange (#ffc30f, #ff5f00).
  • Hot (High Load / Stress): Vivid crimson red (#ff0f0f).
  • Multiple built-in schemes available: temperature, thermal, aurora, and traffic.
• Sparse Fairy Twinkle Effect:
  • Organically spawns gentle breathing sparkles across a sparse subset of LEDs (~5–10% active at any time).
  • Uses a smooth sinusoidal envelope (\sin^2(\pi \cdot t)) for organic fade-in, peak sparkle, and fade-out.
  • Additively highlights the underlying temperature color without overpowering it.
• WLED UDP Realtime / Sync Protocol:
  • Direct RGB streaming (DRGB protocol ID 2, or DNRGB protocol ID 4) to UDP port 21324.
  • Configurable timeout byte so WLED automatically reverts to its normal preset if the Mac sleeps or daemon exits.
• Native macOS Background Integration:
  • Integrated with macOS launchd via ~/Library/LaunchAgents/com.wledaura.monitor.plist.
  • Starts on login, automatically restarts if interrupted, and writes logs to ~/Library/Logs/wledaura.log.
• Zero External Dependencies:
  • Built purely with the Python standard library. Runs out of the box on macOS with Python 3.9+.
• Interactive Terminal Preview:
  • 24-bit ANSI truecolor simulation mode to see the live color aura and twinkles directly in your terminal.

---

Quick Start

1. Requirements & WLED Configuration

• macOS with Python 3.9+
• A WLED device on your local Wi-Fi or LAN
• In your WLED web UI:
  • Navigate to Config > Sync Interfaces.
  • Ensure Receive Realtime is enabled (UDP Port: 21324).

2. Test Connection to WLED

Verify your Mac can send UDP packets to your WLED controller:

./bin/wledaura test-wled --host 192.168.50.94 --leds 30

(Replace 192.168.50.94 with your WLED device IP address or mDNS name like wled.local)

3. Live Terminal Preview

Preview the color gradient and fairy twinkles in your terminal based on your Mac's current load:

./bin/wledaura preview --leds 30

4. Run in Foreground

./bin/wledaura run --host 192.168.50.94 --leds 30

---

Running in the Background (macOS launchd)

WLEDAura includes native launchd service management to run seamlessly as a macOS background daemon.

1. Initialize Configuration

Generate the configuration file at ~/.config/wledaura/config.json:

./bin/wledaura config --init

Edit ~/.config/wledaura/config.json with your WLED host and LED count:

{
  "wled_host": "192.168.50.94",
  "wled_port": 21324,
  "led_count": 30,
  "brightness": 0.85,
  "color_scheme": "temperature",
  "twinkle_enabled": true,
  "twinkle_density": 0.08,
  "twinkle_speed": 1.0,
  "fps": 25
}

2. Install and Start Background Service

# Install and register the LaunchAgent
./bin/wledaura service install

# Check status
./bin/wledaura service status

3. Managing the Service

• Status: ./bin/wledaura service status
• View Recent Logs: ./bin/wledaura service logs (or tail -f ~/Library/Logs/wledaura.log)
• Stop: ./bin/wledaura service stop
• Start: ./bin/wledaura service start
• Restart: ./bin/wledaura service restart
• Uninstall: ./bin/wledaura service uninstall

---

CLI Options

usage: wledaura [-h] {run,preview,test-wled,service,config} ...

Subcommands:
  run          Run the aura daemon in foreground
  preview      Interactive terminal preview of LED aura and sparkles
  test-wled    Send color test sequence to WLED device
  service      Manage macOS launchd background service
  config       View or create default configuration

run flags:

Flag	Description	Default
--host	WLED IP or hostname	wled.local
--port	UDP port	21324
--leds	Number of LEDs on strip	30
--scheme	Color scheme (temperature, thermal, aurora, traffic)	temperature
--brightness	Brightness multiplier (0.0 - 1.0)	0.85
--fps	Animation frames per second	25
--max-load	Explicit max load value (default: CPU core count)	Auto
--no-twinkle	Disable the fairy twinkle sparkle effect	False
--twinkle-density	Fraction of LEDs twinkling simultaneously (0.01 - 0.5)	0.08
--config	Custom path to config.json	~/.config/wledaura/config.json

---

Architecture

• wledaura/monitor.py: Queries macOS os.getloadavg(), scales against os.cpu_count(), and applies smoothing.
• wledaura/color.py: Maps normalized load ratio to color temperature gradients with subtle organic spatial waves.
• wledaura/effects.py: Fairy twinkle engine managing lifecycles and additive highlight blending.
• wledaura/udp_client.py: Constructs and transmits WLED Realtime UDP packets (DRGB/DNRGB/WARLS).
• wledaura/daemon.py: Main coordination loop and graceful signal handling (SIGINT, SIGTERM).
• wledaura/service.py: macOS launchd plist manager for background execution.

---

Running Unit Tests

python3 -m unittest discover tests