DocsUSB LEDs

WLED bridge

Drive ESP32 / ESP8266 boards running WLED firmware over Wi-Fi via the DDP protocol. Pairing by IP address, IP guard, and led_count validation.

From v1.5.0, LumaSync drives ESP32 / ESP8266 boards running WLED firmware over Wi-Fi as a first-class output target alongside USB strips and Philips Hue. The wire protocol is DDP (Distributed Display Protocol) over UDP — a thin per-frame format that WLED understands natively, no firmware modifications needed.

When to use WLED instead of (or alongside) USB

  • The strip is too far from the host machine to wire over USB — typical for ceiling coves, hallway runs, or strips behind a TV in a room without a desktop.
  • You already own ESP-based controllers from the WLED ecosystem and don’t want to buy CH340 / FTDI USB-serial adapters.
  • You want LumaSync’s screen-driven ambilight without committing the host machine to a permanent USB tether.

You can drive WLED and USB simultaneously — the chip-type selector and per-LED sampling apply to each sink independently. Running WLED and Hue zones from the same screen capture is also fully supported.

Hardware requirements

  • An ESP32 (preferred), ESP8266, ESP32-S2, or ESP32-C3 board flashed with current WLED firmware. WLED’s board list covers what works.
  • The board joined to the same LAN as the host machine. Wi-Fi 5 GHz or wired uplinks reduce jitter on busier networks; 2.4 GHz works but you’ll see occasional frame drops on a congested band.
  • WLED’s own configuration done first: strip type, LED count, GPIO pin, power budget — all live in the WLED web UI, not in LumaSync. LumaSync only streams DDP frames in.

Setup

1 · Enter the board’s IP

Open Settings → Device → WLED.

Paste the board’s IPv4 address into the WLED IP field. LumaSync does not browse the network for boards — you tell it where the board is, and it asks that one address for /json/info. If the board answers, its name and the LED count it reports appear, ready to connect.

The board’s IP is on the WLED web UI’s WiFi page, and your router’s client list will have it too. Give the board a DHCP reservation or a static lease if you would rather not re-enter it after a router restart.

Only IPv4 is accepted — hostnames and IPv6 addresses are not.

2 · IP validation

Before any connect attempt, the IP is validated host-side. Inputs that resolve to any of the following are rejected with WLED_INVALID_IP:

  • Loopback (127.0.0.0/8) — wouldn’t drive a real strip anyway.
  • Unspecified (0.0.0.0) — placeholder for “any interface”, invalid as a destination.
  • Multicast (224.0.0.0/4) — would deliver frames to every subscriber on the segment.
  • Broadcast (255.255.255.255) — same problem at the link layer.

This sits on top of the v1.5.1 parser-level SSRF guard that rejected unparseable inputs. The combined effect is that frames are only ever sent to a single, routable LAN address.

3 · Connect

Click Connect. LumaSync queries the WLED /json/info endpoint to confirm the board is responsive and reads back the strip layout (LED count, segment configuration). Boards that reply with led_count == 0 are rejected with WLED_INVALID_LED_COUNT — there’s nothing to drive on a zero-length strip, and proceeding silently would leave the pipeline in an inconsistent state.

4 · Test

Click Test. LumaSync pushes a brief solid-colour pattern over DDP and reports the round-trip in milliseconds (WledTestResponse) in the picker. If you see a real number, the path is open and ready for Ambilight mode. If you see a timeout, check the network reachability section below.

How DDP frames are sent

The encoder emits DDP packets over UDP to the board’s port (4048 by default in WLED). Each packet carries a chunk of the LED buffer; large strips are split across multiple packets per frame. The host-side encoder applies the same gamma + Kelvin + saturation chain as the USB and Hue paths so all three sinks stay visually consistent — there’s no separate WLED-only colour pipeline.

UDP is intentionally connectionless: dropped packets aren’t retransmitted. On a healthy LAN this is invisible; on a congested 2.4 GHz radio you may see occasional brief hitches.

Network reachability checklist

If connect / test fail:

  1. Right IP — a board that took a new address from DHCP is the usual cause. Check the WLED web UI’s WiFi page, or your router’s client list.
  2. Routable — host and board need a route between them. VLANs and guest-network isolation are the common blockers; unlike a discovery browser, a direct probe does not need them on the same L2 segment, only reachable.
  3. Firewall — host firewalls (macOS Firewall, Windows Defender, Linux ufw) sometimes block outbound UDP to the WLED port. Add a rule for the DDP port if necessary.
  4. Board answering HTTP — pairing reads /json/info over HTTP with a 2 s timeout. Open http://<board-ip>/json/info in a browser: if that does not load, LumaSync cannot pair either.

Why DDP and not WLED’s other protocols

WLED supports several real-time protocols (DDP, E1.31, Art-Net, TPM2). LumaSync uses DDP for three reasons:

  • Lowest framing overhead of the four — fewer bytes per frame means less Wi-Fi airtime.
  • No DMX universe accounting — Art-Net and E1.31 inherit a 512-channel-per-universe model that doesn’t compose well with arbitrary LED counts.
  • WLED’s own preferred path — DDP is the protocol the WLED maintainers point at first for high-FPS streaming use cases.

Type to search. Up and down arrows to navigate, Enter to open.