SignalRGB → Magic Home Bridge

pip install signalrgb-magichome-bridge → run one command → your Magic Home LEDs show up in SignalRGB.

Use SignalRGB to control Magic Home WiFi SPI LED controllers in real-time — rainbow waves, audio-reactive effects, game integrations, and every other SignalRGB effect on your Magic Home LED strips and panels.

Magic Home's addressable WiFi controllers (model 0xA3) are cheap and widely available, but SignalRGB doesn't support them natively. This bridge fixes that by emulating a WLED device on your LAN. SignalRGB discovers it automatically, streams pixel data over UDP, and the bridge forwards every frame to the controller via flux_led — no flashing, no custom firmware, fully reversible.

Quick Start

Install the bridge, find your controller, run it. Three steps, two minutes.

1. Install

pip install signalrgb-magichome-bridge

2. Find your controller

signalrgb-bridge --discover

Searching for Magic Home controllers on the network...

Found 1 device(s):

  IP Address           MAC Address          Model
  ------------------   -----------------    --------------------
  192.168.10.22        AABBCCDDEEFF         HF-LPB100-ZJ200

Use: signalrgb-bridge --ip <IP> --leds <COUNT>

3. Start the bridge

signalrgb-bridge --ip 192.168.10.22 --leds 300

============================================================
SignalRGB-to-MagicHome Bridge
============================================================
  Magic Home : 192.168.10.22:5577
  LEDs       : 300
  Max FPS    : 5
  Color Order: auto
  WLED HTTP  : http://192.168.1.50:80
  DDP Port   : 4048
============================================================
Bridge is READY. Waiting for SignalRGB to connect...

Now open SignalRGB → Devices. The bridge appears as a WLED device named "MagicHome Bridge". Click on it, map it to your canvas, apply any effect — pixels stream to your LEDs in real-time.

Run at Startup (Windows)

Want the bridge running every time you log in — silently, in the system tray, no console window?

signalrgb-bridge-install --ip 192.168.10.22 --leds 300

Run this as Administrator. It registers a Windows scheduled task.

That's it. On every logon:

• A hexagon tray icon appears in your system tray
• The bridge starts automatically in the background
• If it crashes, Windows restarts it (up to 3 times)
• Right-click the tray icon for status, restart, log file, or quit

To start the task right now (without rebooting):

signalrgb-bridge-install --start

To remove it:

signalrgb-bridge-install --uninstall

How It Works

                      Your PC                              WiFi Network
            ┌─────────────────────────┐              ┌─────────────────────┐
            │                         │   mDNS       │                     │
            │  SignalRGB  ────────────────────────►   │  Bridge             │
            │             ◄────────────────────────   │  (this app)         │
            │                         │   WLED HTTP   │                     │
            │                         │              │         │            │
            │  SignalRGB  ─── UDP ────────────────►   │  Pixel Receiver     │
            │             (DNRGB/DDP) │   :4048      │         │            │
            │                         │              │    Frame Buffer      │
            │                         │              │    (latest wins)     │
            │                         │              │         │            │
            └─────────────────────────┘              │  Magic Home Client   │
                                                     │  (via flux_led)     │
                                                     │         │ TCP :5577  │
                                                     └─────────┼───────────┘
                                                               │
                                                     ┌─────────▼───────────┐
                                                     │  Magic Home 0xA3    │
                                                     │  WiFi Controller    │
                                                     │         │ SPI       │
                                                     │    LED Strip /      │
                                                     │    Hex Panels       │
                                                     └─────────────────────┘

1. Discovery — The bridge advertises itself via mDNS as a WLED device (_wled._tcp and _http._tcp). SignalRGB finds it automatically, just like a real WLED controller. Initial burst announcements ensure fast discovery on startup.

2. Pixel Streaming — SignalRGB streams RGB pixel data over UDP using WLED's DNRGB protocol (also supports DDP, DRGB, and WARLS). The bridge reassembles multi-packet frames into a contiguous pixel buffer.

3. Protocol Translation — Complete frames are translated into Magic Home's 0xA3 addressable protocol via flux_led and sent over a persistent TCP connection. flux_led handles protocol detection, checksums, counters, and auto-reconnect.

4. Controller Protection — The ESP8266-based controllers have very limited TCP stacks. The bridge protects them with multiple layers:

   • Proactive throttle — First 8 frames at max FPS for instant response, then auto-decelerate to 2 FPS during sustained animation
   • Fuzzy dedup — Skip frames where no channel differs by more than 50 from the last sent frame. Static colors generate zero TCP traffic.
   • Breathing pauses — 3-second silence every 15 frames (TCP stays open) gives the controller's lwIP stack time to drain buffers

5. Zone Mapping — If the controller has fewer addressable points than input pixels (e.g., 10 hex panels driven by 300 pixels), the bridge auto-detects the controller's zone count and downsamples by sampling the center pixel of each zone. Color byte order (RGB/GRB) is auto-detected from the IC type.

Features

• Zero-config discovery — mDNS advertisement with burst announcements, SignalRGB finds the bridge automatically
• Full WLED protocol support — DNRGB, DDP, DRGB, WARLS auto-detected from packet headers
• flux_led transport — Protocol-correct communication via flux_led (checksums, counters, 0xA3 wrapping, auto-reconnect)
• Auto zone detection — Queries the controller for its pixels_per_segment and downsamples accordingly. Results cached for fast restarts.
• Color order auto-detection — Reads IC type from the controller (WS2812B → GRB, etc.) and reorders bytes automatically
• Controller stability — Proactive throttle, fuzzy dedup, and breathing pauses prevent the ESP8266 from freezing
• Persistent TCP with SO_LINGER(0) — Immediate RST on close prevents ghost connections from crashing the controller on rapid restarts
• Frame throttling — Configurable max FPS with latest-frame-wins strategy
• Power control passthrough — SignalRGB on/off commands forwarded to the controller
• System tray mode — Runs as a Windows tray icon with status, restart, and log file access
• File logging — Always logs to ~/signalrgb-bridge.log (essential for tray mode debugging)
• One-command auto-start — signalrgb-bridge-install sets up a Windows scheduled task
• Controller discovery — Find Magic Home controllers on your network via UDP broadcast

Requirements

• Python 3.10+
• Magic Home WiFi SPI controller — Addressable v3 / model 0xA3 (the ones with HF-LPB100 or similar WiFi modules)
• SignalRGB — installed on the same LAN

Note: This bridge works with Magic Home controllers that use the 0xA3 addressable protocol. These are typically the WiFi SPI controllers for addressable LED strips (WS2812B, WS2811, etc.) sold under brands like Magic Home, MagicLight, or Zengge. If your controller shows up in the Magic Home app with individually addressable LEDs, it's likely compatible.

Example: Hexagonal LED Panels

This bridge was originally built to control hexagonal LED wall panels (like Nanoleaf-style hex lights) powered by a Magic Home WiFi SPI controller. Here's how that setup works:

The Setup

Magic Home 0xA3 Controller ──[SPI]──► 10 Hexagonal LED Panels (daisy-chained)
         ▲                             Each panel = ~30 LEDs wired in series
         │ TCP :5577                   Total: 300 physical LEDs
         │
    WiFi Network
         │
    This Bridge (on your PC)
         ▲
         │ UDP :4048
         │
    SignalRGB

Each hexagonal panel contains ~30 individually wired LEDs, but the Magic Home controller treats each panel as one addressable zone. The controller has 10 zones (pixels_per_segment=10), one per panel — this is a firmware limitation, not a bridge limitation.

What This Means in Practice

• 10 zones = 10 independent colors — Each hexagonal panel lights up as a single solid color
• Rainbow effects work — A rainbow spread across your 10 panels shows 10 distinct colors, shifting smoothly over time
• Audio-reactive effects work — Panels react to music with per-panel color changes
• You won't get per-LED gradients within a single panel — All 30 LEDs inside one hexagon show the same color

How to Set It Up

1. Start the bridge with your total physical LED count:

   signalrgb-bridge --ip 192.168.10.22 --leds 300
   

2. The bridge auto-detects that the controller only has 10 addressable zones and logs it at startup:

   Controller config: 10 points, 10 segments, IC=WS2812B, color_order=GRB
   

3. In SignalRGB, add the device and set it to 300 LEDs (matching --leds). Map it on the canvas to cover your wall layout.

4. SignalRGB sends 300 pixels of color data. The bridge downsamples this to 10 zone colors by sampling the center pixel of each 30-pixel group. This gives the truest color match to what SignalRGB previews on screen.

Tips for Hex Panel Users

• Layout matters — In SignalRGB's canvas editor, arrange the device strip to roughly match how your hex panels are physically mounted. This way the rainbow direction and effect flow match your wall.
• Use wide effects — Effects with broad color gradients (Rainbow Wave, Color Cycle, Gradient) look best. Fine-grained effects (Matrix rain, detailed patterns) will be simplified to 10 colors.
• Lower FPS is fine — With only 10 zones, the default --fps 5 is plenty. The color transitions are smooth since each zone is a solid color anyway.

Configuration

All options can be set via CLI flags, a config.json file, or both (CLI overrides JSON).

Using a config file

Copy the example and edit it:

cp config.example.json config.json

{
    "magic_home_ip": "192.168.10.22",
    "num_leds": 300,
    "max_fps": 5,
    "wled_name": "My Hex Panels",
    "wled_http_port": 80,
    "log_level": "INFO"
}

Then just:

signalrgb-bridge

Troubleshooting

Architecture

Running Tests

pip install -e ".[dev]"
python -m pytest tests/ -v

Known Limitations

• ESP8266 stability — The controller's cheap WiFi chip (ESP8266/ESP32) has a limited TCP stack (~4 sockets, small buffers). The bridge works around this with breathing pauses, throttling, and fuzzy dedup, but sustained animation at high FPS can still eventually overwhelm it. The default settings are tuned for long-term stability.
• Latency — Expect 30-100ms end-to-end (WiFi + TCP). Not suitable for rhythm games.
• Addressable zones — Some controllers only support a limited number of independently addressable zones (e.g., 10 zones for hex panel setups). The bridge auto-detects this and downsamples. Each zone displays one color.
• Model support — Only 0xA3 (Addressable v3) controllers. Legacy models use different protocols.
• Single controller — One bridge instance controls one controller. Run multiple instances on different --http-port values for multiple controllers.

Protocol References

• flux_led — Magic Home protocol library (used as the transport layer)
• WLED UDP Realtime — DNRGB/DDP/DRGB protocol documentation
• WLED JSON API — HTTP API that SignalRGB uses for discovery
• DDP Protocol — Distributed Display Protocol specification

Contributing

Contributions are welcome! Some ideas:

• More controller models — Add support for non-0xA3 Magic Home controllers
• Linux/macOS tray — Port the system tray to work cross-platform
• Multi-controller — Single bridge instance managing multiple controllers
• Brightness mapping — Pass SignalRGB brightness changes through to controller brightness
• Web dashboard — Status page showing FPS, latency, connection health

License

MIT