DDP protocol enables real-time LED animations over WiFi using OpenBeken and xLights.
It sends 24-bit RGB or 32-bit RGBW data over connectionless UDP, with one packet covering multiple LEDs or WS2812 strips.
OpenBeken starts DDP with `startDriver DDP`, and strip setups can also use `SM16703P_Init 50` or `GRB`.
xLights groups independent LEDs, arranges them in 2D or 3D, and sends test animations to a device by IP address.
UDP brings no retransmission, so a lost packet can be missed; fixed IP or reservation helps keep controllers aligned.
Generated by the language model.
DDP is a connectionless LED light control protocol based on UDP. DDP supports various color formats, but usually 24-bit RGB or 32-bit RGBW is used. One packet can contain multiple colors, so DDP can also be used to control LED strips such as WS2812. By using connectionless UDP (as opposed to TCP), DDP is suitable for real-time applications and allows you to create fast and responsive animations. The disadvantage of this solution is the lack of retransmission of the packet if it does not reach its destination, but when this protocol is used for animation, it should not be noticeable because new data is constantly being sent and nothing will happen if one packet is lost.
Detailed DDP documentation can be found on the 3waylabs website:
http://www.3waylabs.com/ddp/ But its popular implementations are much more stripped down.
For example Tasmota only loads RGB data from a given offset in the package:
Code: C / C++
Log in, to see the code
IN OpenBeken it works similarly, but there, pixel groups for LED strips are also supported:
Code: C / C++
Log in, to see the code
This is really enough to animate any groups of our LEDs and "smart" strips via the WiFi network.
How to send DDP data? There are many tools that support DDP, and it`s just as easy to send DDP packets from your own program, but one of the more popular ways to create and manage animations is xLights : :
xLights allows you to combine independent LEDs into groups, create advanced effects, arrange them freely in 2D and 3D space and configure them on the timeline.
To send data to a device, you only need to know it IP address . In this case, it is worth using a fixed IP or IP reservation, otherwise after restarting the router our LEDs may get mixed up...
As for the device itself, I will use an LED lamp from OpenBeken:
On the side OBK turn on the driver DDP : :
It is best to enter this in the startup command so that the controller starts every time you reboot. After that, we restart the device:
Then, on the xLights side, we open the Test options from Tools:
We mark the channels of our lamp and make sure on the OBK side whether the lamp is turned on.
As a result, the LED plays a test animation:
Of course, the video only shows a test animation, we can send any combinations we want from xLights, but more about that in the xLights topic.
Summary DDP is an extremely easy-to-use and useful protocol for creating LED animations. It allows you to control both individual lamps and LED strips. Combined with systems such as xLights, it allows you to create complex LED animations for an entire room or even a house, which I will try to discuss in the next part.
DDP is so simple that we can basically send such packets from our own program or receive them in our own program, which I will present soon.
Basically, the only downside to DDP that I see is what also makes it very light and fast - its connectionlessness. DDP is based on UDP, which does not offer retransmission in the event of a lost packet, so if our target use of DDP assumes that we will send one packet that will set the color and forget about the light, we may be quite surprised if this packet does not arrive.
The solution in such a case is to use MQTT or at least HTTP, both of these protocols operate on TCP, which ensures greater transmission reliability than TCP.
The entire organization of DDP-based effects is so cool that we don`t have to worry about cables and can freely change the configuration many times in the software itself. On the hardware side, all you need is that the lamp/LED has power and access to WiFi, and you can control it.
Has anyone reading created LED effects based on DDP? The possibilities are really great. Feel free to comment.
About Author
p.kaczmarek2 wrote 14580 posts with
rating 12604 , helped 654 times.
Been with us since 2014 year.
Hi guys,
I'm testing DDP protocol on RGBCCT GU10 bulbs with OpenBK firmware:
- when it finishes receiving DDP packets the bulb stays off (black) and does not return to the previous state, while in... [Read more]
p.kaczmarek2
05 Dec 2024 11:57
Sure, I can implement RGBW DDP for you. Can you specify how do you send RGBW DDP packets and how OBK should respond to them? What is your current device config?
What do you mean by "return to previous... [Read more]
tech1977
05 Dec 2024 12:27
I would like to send DDP packets from Xlight or WLED controller, I don't know what OBK should answer, I'm not an expert in programming;
yes, when the DDP animation stops the light bulb remains black... [Read more]
p.kaczmarek2
05 Dec 2024 12:33
Can you tell me how to send RGBW packets from XLights, so I can recreate the problem on my side?
Currently I can clearly see, that both Tasmota and OBK parses only RGB values, no W, so I need to find... [Read more]
tech1977
05 Dec 2024 18:50
ok, as soon as I can I'll flash via OTA;
Athom WLED bulb already works with DDP RGBW and WLED DDP controller for example ESP32:
https://obrazki.elektroda.pl/9723086500_1733410444_thumb.jpg
but... [Read more]
p.kaczmarek2
05 Dec 2024 18:55
I see, that can be very useful indeed. For the clarity, can you also attach dump of RGB only packets? Just make 100% sure to use RGB only mode, and not RGB color in RGBW mode...
This is because I need... [Read more]
tech1977
06 Dec 2024 02:12
I configured the bulb in Xlights with only 3 channels RGB here is the log:
Info:DDP:Packet: 41030001000000000003FFFFFF, Length: 13 [Read more]
p.kaczmarek2
06 Dec 2024 09:05
Now we can do comparison. So, there is one more byte and length is one more higher.
410F0001000000000004000000FF
41030001000000000003FFFFFF
So, what is your OBK JSON template currently? Do you want... [Read more]
tech1977
06 Dec 2024 09:31
I would like it to go white around 4000k so half between WW and CW [Read more]
p.kaczmarek2
06 Dec 2024 10:26
Ahhh, so the fourth byte should set BOTH Cool White and Warm White channels? Is this some kind of standard, or should it configurable?
Another question. If I set OBK brightness to 50%, and then send:
...... [Read more]
tech1977
06 Dec 2024 14:55
It should be a standard where there are cold white LEDs and warm white LEDs
DDP should set the brightness based on the configuration inside Xlights, so it overrides the brightness setting [Read more]
p.kaczmarek2
06 Dec 2024 21:21
I see, I've added experimental parsing, either RGB if len is 3 or RGBW when len is 4 (then Cool is 50% and Warm is 50%), can you update to 1.17.795 and check how it behaves? I wasn't been able to test... [Read more]
Hi,
sorry for the delay, as soon as I can I'll test it and let you know [Read more]
tech1977
11 Dec 2024 12:45
21337805[/pHiostid]
Hi,
I tried version 1.17.795 with Xlights and enable DDP driver,
now channel 4 (W) works !!! on the standard test of the individual channels of Xlights,
but if I do the test... [Read more]
p.kaczmarek2
11 Dec 2024 13:04
It should be very easy to check this.
Flash the "DDP dump again:
https://github.com/openshwprojects/OpenBK7231T_App/pull/1457
And then do A-B-C-ALL cycle and copy packets data to forum.
Then it will... [Read more]
tech1977
11 Dec 2024 14:37
when I do the RGB Cycle test by selecting A-B-C-ALL A (Red) is activated together with channel 4 which is White, so maybe this test is only for 3 RGB channels:
https://obrazki.elektroda.pl/4625245700_1733923884_thumb.jpg... [Read more]
p.kaczmarek2
11 Dec 2024 23:28
Well, if that's the content of sent packets, then there is no suprise that OBK behaves in such a way. I would rather expect the RGB test to send packet with 3, not 4 colors. You can see 04 (hex 4) in the... [Read more]
tech1977
12 Dec 2024 09:00
yes, I still have to study Xlights, now I just have to figure out which GU10 with DDP is best for me to buy, I would prefer something with a fairly narrow light beam [Read more]
FAQ
TL;DR: DDP sends 24-bit RGB or 32-bit RGBW LED data over WiFi using UDP, and one expert calls it "extremely easy-to-use." This FAQ helps OpenBeken and xLights users configure single lamps, strips, RGBW bulbs, packet debugging, and MQTT-visible DDP status without extra wiring. [#20989597]
Why it matters: If you want fast WiFi LED effects on OBK devices, DDP gives simple setup and low-latency animation, but you must plan for packet loss, RGBW quirks, and driver-state handling.
Option
Transport
Best use
Main advantage
Main limitation
DDP
UDP
Continuous LED animation
Fast, lightweight, multi-pixel packets
No retransmission if a packet is lost
MQTT
TCP
Reliable state changes
Better delivery reliability
Less suited to rapid frame-by-frame effects
HTTP
TCP
Simple command-based control
Reliable single actions
Not ideal for real-time animation
Key insight: DDP works best when software keeps sending fresh frames. If you need a bulb to remember or restore a stable state after animation stops, use extra OBK logic or switch to a TCP-based control path. [#20989597]
Quick Facts
DDP packets in the thread use UDP port 4048, and both Tasmota and OpenBeken examples read color bytes starting at payload offset 10. [#20989597]
The thread compares xLights packet sizes directly: an RGB test packet was 13 bytes, while an RGBW test packet was 14 bytes. [#21335096]
For OBK LED strips, the example startup uses startDriver DDP, startDriver SM16703P, and SM16703P_Init 50, which configures a strip with 50 pixels. [#20989597]
Experimental RGBW support in OBK 1.17.795 mapped the fourth DDP byte to 50% cool white + 50% warm white, targeting about 4000K on an RGBCCT bulb. [#21336347]
One LN882H test bulb that needed a custom DDP-enabled build was described as a 5W, 500 lm, GU10 smart lamp. [#21358155]
What is the DDP protocol, and why is it useful for real-time LED animations over WiFi?
DDP is a connectionless UDP protocol for LED lighting that sends color data fast enough for real-time animation over WiFi. "DDP" is a lighting-control protocol that transports pixel color data in UDP packets, avoids connection setup, and can carry multiple LED values in one frame for responsive effects. In the thread, it commonly uses 24-bit RGB or 32-bit RGBW, and one packet can control whole LED strips, not just one lamp. [#20989597]
What does xLights do, and how is it used to send DDP effects to OpenBeken devices?
xLights creates, groups, and transmits LED effects to OBK devices over DDP by targeting the device IP address. The thread shows xLights arranging LEDs in 2D or 3D, assigning channels, and sending test effects from the Tools menu. A fixed IP or DHCP reservation matters, because a router reboot can otherwise change addresses and break the mapping between xLights outputs and OBK lamps. [#20989597]
How do I configure OpenBeken to receive DDP packets for a single RGB lamp?
You enable the DDP driver and then send xLights output to the lamp’s IP address. 1. Add startDriver DDP to OBK startup commands. 2. Reboot the device so the driver starts automatically. 3. In xLights Tools, test the lamp’s channels and verify the lamp is powered on in OBK. The thread’s OBK example then accepts RGB bytes from the DDP payload and plays the test animation. [#20989597]
What steps are needed to control a WS2812B or SM16703P LED strip over DDP with OBK and xLights?
You must enable both DDP reception and the strip driver, then set the pixel count and matching xLights channels. 1. In OBK, run startDriver DDP. 2. Start the strip driver with startDriver SM16703P. 3. Initialize the strip, for example SM16703P_Init 50, or SM16703P_Init 50 GRB if color order is wrong. The thread shows this working for a 50-pixel strip and notes that xLights channel counts must match the configured pixels. [#20989597]
Why does DDP use UDP instead of TCP, and what are the trade-offs for LED animation reliability?
DDP uses UDP because animation needs low overhead and constant updates more than guaranteed delivery. UDP lets OBK receive frames quickly without connection management, which keeps effects responsive. The trade-off is clear: if one packet is lost, DDP does not retransmit it. That is usually acceptable for continuous animation, but it becomes a problem if you send one color-setting packet and expect the light to hold that state reliably. [#20989597]
How does DDP compare with MQTT or HTTP for controlling LEDs when I need reliable state changes instead of continuous animation?
MQTT or HTTP fit reliable state changes better than DDP. The thread explicitly recommends TCP-based MQTT or HTTP when you need a bulb to keep a commanded state, because TCP offers better transmission reliability than UDP. DDP is better for rapid, repeated frame updates. If your use case is one command, one result, and no continuous stream, MQTT or HTTP is the safer control path. [#20989597]
Why does an OpenBK RGBCCT GU10 bulb stay black after DDP packets stop instead of returning to its previous color like WLED?
It stays black because OBK, as discussed in the thread, did not automatically restore the pre-DDP state after the stream ended. A user reported that when DDP reception finished, the GU10 bulb remained black instead of returning to the previous color or white mode. The discussion framed the desired behavior as restoring the earlier state after about a minute of animation, but no completed restore-state mechanism was shown in the thread. [#21333950]
How can RGBW DDP packets from xLights be parsed in OpenBeken, and how is the white channel mapped on RGBCCT bulbs?
OBK can parse RGBW by treating a 4-byte color payload as RGB plus one white byte. In the thread, experimental support added RGB parsing when color length is 3 and RGBW parsing when length is 4. For an RGBCCT bulb, the fourth byte was mapped to both cool and warm white at 50% each, aiming for roughly 4000K. That was released for testing in OBK version 1.17.795. [#21336347]
Why does channel 4 white work in xLights single-channel testing but behave strangely during the A-B-C-All RGB cycle on an RGBW bulb?
xLights appears to send a 4-color packet during that RGB cycle, so OBK correctly lights white when the packet says four channels exist. The thread showed channel 4 working in single-channel tests, but during A-B-C-All, red also lit white. The follow-up conclusion was that this was driven by packet content, not random bulb behavior: the packet still contained 04 where a 3-channel RGB cycle would have been expected to use 03. [#21344435]
How can I capture and analyze raw DDP packet hex dumps in OpenBeken to troubleshoot RGB vs RGBW behavior?
Use the DDP debug build that logs raw packet bytes in the OBK Web App console. 1. Flash the special build from the DDP dump pull request by OTA. 2. Enable the DDP driver and send a single RGB packet, then a single RGBW packet. 3. Copy the hex dumps from the log and compare payload length and byte count. The thread used this method to isolate RGB versus RGBW packet structure from xLights. [#21333957]
What do DDP packet length and payload differences mean when comparing RGB packets with RGBW packets in xLights?
They show how many color bytes xLights is actually sending per pixel. In the thread, the RGBW example 410F0001000000000004000000FF had length 14, while the RGB example 41030001000000000003FFFFFF had length 13. The practical meaning is simple: one extra payload byte indicates a fourth channel. That gives OBK a concrete way to distinguish 3-byte RGB from 4-byte RGBW traffic. [#21335220]
How should DDP brightness interact with the existing OBK light brightness setting when xLights sends animation data?
DDP should override the existing OBK brightness when xLights sends animation data. The user explicitly requested that behavior, and stated that brightness should follow the xLights configuration rather than stay at a prior OBK setting such as 50%. That makes DDP act like the active frame source, not a tint layered on top of manual brightness. The thread presents that as the expected control model for animation playback. [#21335708]
Why won’t the DDP driver start on an LN882H OpenBeken build, and how do I enable it in a custom firmware build?
The DDP driver will not start if the LN882H firmware build does not include that driver. In the thread, entering startDriver DDP at runtime showed that the driver was missing from the build. The fix was to enable DDP in obk_config.h and build custom firmware, or use a prepared DDP-enabled build. After flashing that custom compilation, the LN882H GU10 bulb started working as expected. [#21358147]
What can I do in OpenBeken so a bulb switches cleanly from WLED/DDP control back to normal cool-white manual control without needing to move the temperature slider first?
You currently need extra OBK logic, because the thread reports no finished automatic handoff for that case. A user described losing normal cool-white behavior after stopping DDP, then having to move the temperature slider before the bulb lit again. The stated goal was a script or flag that restores manual control cleanly and prevents DDP and manual white mode from being active together. The maintainer replied that DDP improvements were under active review, but no final solution was posted there. [#21647952]
How can I publish the OpenBeken DDP driver running state over MQTT so Home Assistant can track whether light show mode is enabled?
You can expose a binary DDP-running state over MQTT, and the maintainer indicated this was easy to add. The Home Assistant use case in the thread toggled startDriver and stopDriver to enter light-show mode, then needed MQTT state tracking because DDP resets after reboot. A proposed workaround used OBK uptime to detect restarts, and a proposed solution showed publishing driver state after waitFor MQTTState 1 in autoexec so Home Assistant can mirror the switch state. [#21693022]
Comments
Hi guys, I'm testing DDP protocol on RGBCCT GU10 bulbs with OpenBK firmware: - when it finishes receiving DDP packets the bulb stays off (black) and does not return to the previous state, while in... [Read more]
Sure, I can implement RGBW DDP for you. Can you specify how do you send RGBW DDP packets and how OBK should respond to them? What is your current device config? What do you mean by "return to previous... [Read more]
I would like to send DDP packets from Xlight or WLED controller, I don't know what OBK should answer, I'm not an expert in programming; yes, when the DDP animation stops the light bulb remains black... [Read more]
Can you tell me how to send RGBW packets from XLights, so I can recreate the problem on my side? Currently I can clearly see, that both Tasmota and OBK parses only RGB values, no W, so I need to find... [Read more]
ok, as soon as I can I'll flash via OTA; Athom WLED bulb already works with DDP RGBW and WLED DDP controller for example ESP32: https://obrazki.elektroda.pl/9723086500_1733410444_thumb.jpg but... [Read more]
I see, that can be very useful indeed. For the clarity, can you also attach dump of RGB only packets? Just make 100% sure to use RGB only mode, and not RGB color in RGBW mode... This is because I need... [Read more]
I configured the bulb in Xlights with only 3 channels RGB here is the log: Info:DDP:Packet: 41030001000000000003FFFFFF, Length: 13 [Read more]
Now we can do comparison. So, there is one more byte and length is one more higher. 410F0001000000000004000000FF 41030001000000000003FFFFFF So, what is your OBK JSON template currently? Do you want... [Read more]
I would like it to go white around 4000k so half between WW and CW [Read more]
Ahhh, so the fourth byte should set BOTH Cool White and Warm White channels? Is this some kind of standard, or should it configurable? Another question. If I set OBK brightness to 50%, and then send: ...... [Read more]
It should be a standard where there are cold white LEDs and warm white LEDs DDP should set the brightness based on the configuration inside Xlights, so it overrides the brightness setting [Read more]
I see, I've added experimental parsing, either RGB if len is 3 or RGBW when len is 4 (then Cool is 50% and Warm is 50%), can you update to 1.17.795 and check how it behaves? I wasn't been able to test... [Read more]
@tech1977 any news on testing? [Read more]
Hi, sorry for the delay, as soon as I can I'll test it and let you know [Read more]
21337805[/pHiostid] Hi, I tried version 1.17.795 with Xlights and enable DDP driver, now channel 4 (W) works !!! on the standard test of the individual channels of Xlights, but if I do the test... [Read more]
It should be very easy to check this. Flash the "DDP dump again: https://github.com/openshwprojects/OpenBK7231T_App/pull/1457 And then do A-B-C-ALL cycle and copy packets data to forum. Then it will... [Read more]
when I do the RGB Cycle test by selecting A-B-C-ALL A (Red) is activated together with channel 4 which is White, so maybe this test is only for 3 RGB channels: https://obrazki.elektroda.pl/4625245700_1733923884_thumb.jpg... [Read more]
Well, if that's the content of sent packets, then there is no suprise that OBK behaves in such a way. I would rather expect the RGB test to send packet with 3, not 4 colors. You can see 04 (hex 4) in the... [Read more]
yes, I still have to study Xlights, now I just have to figure out which GU10 with DDP is best for me to buy, I would prefer something with a fairly narrow light beam [Read more]