DDP

showstack / protocols / ddp

Also called Distributed Display Protocol.

3waylabs' minimal UDP protocol for pushing pixel data at LED controllers, using a ten byte header with an offset and a length so a display larger than one packet can be written in pieces. It is the usual choice when DMX universe boundaries get in the way of a high pixel count.

Lighting controlOpen3waylabsReported

Control Small, urgent, must arrive

Small messages that either repeat constantly or fire once. Bandwidth is almost never the problem.

What kills it. Latency and loss on the messages that fire once. A repeating level survives a dropped packet; a GO does not.

The four flows, and why the model is worth having →

Ports

udp/4048 DDP data and control
WLED and other receivers listen here per the protocol's recommendation. The protocol itself is agnostic about UDP versus TCP, but senders in the field use UDP almost exclusively.

Addressing

No universes. A display is a flat byte array addressed by an offset and a length in the header, so a strip of any size is written directly without splitting into 512-slot blocks.

What goes wrong

The offset is a byte offset, not a pixel index. Feed a pixel number straight into it and your data lands a third of the way along the strip in RGB, a quarter of the way in RGBW.

A frame usually spans several packets and only the final one carries the push flag. A receiver that renders on every packet tears; a sender that never sets push leaves the display frozen on the last frame it did push.

WLED ignores the optional timecode fields in the header, so do not design synchronised multi-controller playback around them. Check per receiver before assuming anyone reads them.

It is UDP with no retransmission and no sequence recovery. On a congested or wireless link you get dropped frames that look exactly like a failing power supply or a bad data injector.

The protocol permits TCP but effectively every device only listens on UDP 4048. If you need a reliable path, prove the receiver actually accepts TCP before designing around it.

Open source implementations

ddp-rs — Rust, MIT
WLED — C++, EUPL-1.2

Typical use

Driving WLED and similar addressable LED controllers from a pixel mapper
High pixel-count LED walls and strips where universe boundaries are a nuisance
Software-to-software pixel streaming between mapping and effects tools
Retrofitting a media server output onto cheap LED hardware

Sources

DDP Protocol specification — 3waylabs primary
DDP protocol — WLED documentation (UDP 4048, timecode fields ignored) — WLED Project
ddp-rs — Distributed Display Protocol in Rust (10 byte header, port 4048, transport agnostic) — Jonas Bengtson

Understand the mechanism

DMX on the wire Show networks

Something wrong, or missing?

Known gaps on this entry: first_published. If you can source one of them, that is a ten minute pull request.

Edit this entry on GitHub — one file, editable in your browser, and your handle goes on it permanently.

Work at 3waylabs? Confirm or correct this entry — it is free, it stays free, and nothing about it is for sale.