DDP-over-ws: handle fragmented (multi-part) messages

[softhack007]

WLED/wled00/data/common.js

Line 218 in a8ae8af

let maxDDPpx = 472; // must fit into one WebSocket frame of 1428 bytes, DDP header is 10+1 bytes -> 472 RGB pixels

WLED/wled00/ws.cpp

Lines 99 to 105 in a8ae8af

	} else {
	DEBUG_PRINTF_P(PSTR("WS multipart message: final %u index %u len %u total %u\n"), info->final, info->index, len, (uint32_t)info->len);
	//message is comprised of multiple frames or the frame is split into multiple packets
	//if(info->index == 0){
	//if (!wsFrameBuffer && len < 4096) wsFrameBuffer = new uint8_t[4096];
	//}

When trying videolab on a setup with 128x64 pxels (wled 16.0 HUB75), I still have a very laggy/jumpy playback at low FPS. In debug mode, there are tons of WS multipart messages that arrive from the frontend. Multi-part messages are not reduced when lowering the maxDDPpx parameter in common.js. My conclusion is that the esp32 side is splitting some ws messages into multi-part, especially when the receiver is under heavy load.

I think we should implement multi-part binary message handling, to improve performance on fixtures that are larger than 48x64 pixels.

[DedeHai]

videolab should split the messages into correctly sized chunks but maybe the browser/OS puts them into larger messages?
anyway - no objections in adding multi-part support.

[softhack007]

@coderabbitai please suggest how to extend the code in ws.cpp to properly handle multipart WS receiving of binary messages that contain a DDP pixel stream.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '=== Issue `#5755` ==='
gh issue view 5755 --repo wled/WLED --comments

echo '=== Locate candidate files ==='
fd -HI -t f '^(ws|ddp)\.(cpp|h)$' . || true
fd -HI -t f . | rg '(^|/)(ws|ddp)\.(cpp|h)$|AsyncWebSocket|DDP'

echo '=== WebSocket source outline ==='
ws_file="$(fd -HI -t f '^ws\.cpp$' . | head -n1)"
printf 'ws_file=%s\n' "$ws_file"
if [ -n "$ws_file" ]; then
  ast-grep outline "$ws_file" --items all || true
  echo '=== WebSocket callback/frame metadata and DDP references ==='
  rg -n -C 12 'AwsFrameInfo|WS_EVT_DATA|opcode|final|index|len|DDP|ddp|binary' "$ws_file" || true
fi

echo '=== DDP definitions and WebSocket/DDP call sites ==='
rg -n -C 6 --glob '*.{cpp,h}' '\b(handleDDP|parseDDP|DDP\w*|ddp\w*)\s*\(' . || true

Length of output: 9755

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '=== Complete wsEvent context ==='
sed -n '1,132p' wled00/ws.cpp

echo '=== Protocol handler definition and DDP parsing branches ==='
rg -n -C 18 --glob '*.{cpp,h}' '\bhandleE131Packet\s*\(' .
rg -n -C 12 --glob '*.{cpp,h}' 'P_DDP|DDP' wled00

echo '=== AsyncWebSocket client state APIs available in checked-out sources/dependencies ==='
rg -n -C 3 --hidden \
  'class AsyncWebSocketClient|setUserData\s*\(|getUserData\s*\(|userData\s*\(' \
  . \
  -g '*AsyncWebSocket*' -g '*WebSockets*' -g '*.{h,hpp,cpp}' \
  || true

echo '=== Configuration limits that could bound an inbound DDP WebSocket message ==='
rg -n -C 4 --glob '*.{cpp,h}' \
  'MAX_.*(DDP|PACKET|PAYLOAD|WS)|(?:DDP|E131).*(?:MAX|SIZE|LEN)|MAX_LEDS|ledCount' \
  wled00 || true

Length of output: 72871

---

@softhack007, I’d reassemble the WebSocket message first, then invoke the existing DDP path once with a contiguous buffer. Do not pass individual fragments to handleE131Packet(): the first fragment may not contain the complete 10-byte DDP header, and a later fragment has no wrapper protocol byte.

The key details are:

• Use info->message_opcode == WS_BINARY for multipart messages. info->opcode describes an individual WebSocket frame and may be a continuation opcode.
• Use info->index as the required offset into the message and info->len as its advertised total size.
• Keep assembly state per client->id(), since callbacks from clients can interleave.
• Bound the accepted total before allocation. For the existing WLED DDP sender, 1 + DDP_HEADER_LEN + DDP_CHANNELS_PER_PACKET is 1451 bytes: one WS protocol selector byte, a 10-byte DDP header, and up to 1440 DDP data bytes.
• Discard state on disconnect, malformed sequencing, oversize input, and allocation failure.

A compact implementation shape for wled00/ws.cpp would be:

#include <map>
#include <vector>

constexpr size_t WS_DDP_MAX_MESSAGE =
  1U + DDP_HEADER_LEN + DDP_CHANNELS_PER_PACKET;

struct WsBinaryAssembly {
  size_t expected = 0;
  size_t received = 0;
  std::vector<uint8_t> bytes;
};

static std::map<uint32_t, WsBinaryAssembly> wsBinaryAssemblies;

static void clearWsBinaryAssembly(const AsyncWebSocketClient* client) {
  wsBinaryAssemblies.erase(client->id());
}

static void handleWsBinaryMessage(AsyncWebSocketClient* client,
                                  const uint8_t* data, size_t len) {
  constexpr size_t protocolOffset = 1;

  if (!data || len < protocolOffset + DDP_HEADER_LEN) return;

  if (data[0] == BINARY_PROTOCOL_DDP) {
    handleE131Packet(
      (e131_packet_t*)&data[protocolOffset],
      client->remoteIP(),
      P_DDP,
      len - protocolOffset
    );
  }

  // Keep the existing E1.31/Art-Net branches here if multipart support for
  // those wrapper protocols is desired too.
}

Then, in wsEvent(), handle binary traffic before the current single-frame-only branch:

} else if (type == WS_EVT_DISCONNECT) {
  clearWsBinaryAssembly(client);
  if (client->id() == wsLiveClientId) wsLiveClientId = 0;
  DEBUG_PRINTLN(F("WS client disconnected."));

} else if (type == WS_EVT_DATA) {
  AwsFrameInfo* info = (AwsFrameInfo*)arg;

  const bool isBinaryMessage =
    info->opcode == WS_BINARY || info->message_opcode == WS_BINARY;

  if (isBinaryMessage) {
    // Retain the efficient zero-copy path for a complete callback.
    if (info->final && info->index == 0 && info->len == len) {
      handleWsBinaryMessage(client, data, len);
      return;
    }

    const uint32_t clientId = client->id();

    if (info->index == 0) {
      // A new message supersedes any incomplete previous message from this client.
      clearWsBinaryAssembly(client);

      if (info->message_opcode != WS_BINARY ||
          info->len < 1U + DDP_HEADER_LEN ||
          info->len > WS_DDP_MAX_MESSAGE) {
        return;
      }

      WsBinaryAssembly& assembly = wsBinaryAssemblies[clientId];
      assembly.expected = info->len;
      assembly.received = 0;

      // Reserve once; do not repeatedly grow the buffer as data arrives.
      assembly.bytes.resize(assembly.expected);
    }

    auto it = wsBinaryAssemblies.find(clientId);
    if (it == wsBinaryAssemblies.end()) return;

    WsBinaryAssembly& assembly = it->second;

    // Require contiguous, in-order delivery and a consistent total length.
    if (!data ||
        info->len != assembly.expected ||
        info->index != assembly.received ||
        len > assembly.expected - assembly.received) {
      clearWsBinaryAssembly(client);
      return;
    }

    memcpy(assembly.bytes.data() + assembly.received, data, len);
    assembly.received += len;

    if (assembly.received == assembly.expected) {
      if (!info->final) {
        // All advertised bytes arrived, but the WS message was not finalized.
        clearWsBinaryAssembly(client);
        return;
      }

      handleWsBinaryMessage(client, assembly.bytes.data(), assembly.bytes.size());
      clearWsBinaryAssembly(client);
    }

    return;
  }

  // Existing complete-text JSON handling follows here.
  if (info->final && info->index == 0 && info->len == len) {
    // existing WS_TEXT code
  }

I would also add an explicit maximum number of active assemblies if the WebSocket library’s client count is not already tightly bounded; otherwise many connected peers could each reserve a buffer. For this issue, a small fixed slot table keyed by client ID may be preferable to std::map on constrained targets.

The existing DDP parser already rejects packets shorter than DDP_HEADER_LEN and rejects an advertised dataLen that exceeds the reassembled buffer (wled00/e131.cpp, Line 24 and Line 66). Therefore, reassembly only needs to enforce WebSocket sequencing and memory limits before handing the result to that parser.

Useful test cases:

1. A normal unfragmented 0x02 + DDP message still reaches handleE131Packet() without allocation.
2. Split at byte 1 (protocol selector separated from the DDP header).
3. Split within the DDP header and within pixel data.
4. Interleaved fragmented messages from two clients.
5. A fragment with a non-contiguous index, changed info->len, or index + len > info->len.
6. An advertised length above WS_DDP_MAX_MESSAGE.
7. Disconnect while an assembly is incomplete.

[softhack007]

videolab should split the messages into correctly sized chunks but maybe the browser/OS puts them into larger messages?

@DedeHai That might be - actually I only observed these very low framerates with 64x64 or more pixels. At 128x64, it went down to 1 fps, no matter how I modified maxDDPpx. Observed on win11, MSEdge or Chrome; chrome usually has slightly better FPS but still lots of multipart messages.

[DedeHai]

@softhack007 when I wrote the FX to gif recorder tool I had issues with windows: it would drop to 10FPS recording the live preview but it would work flawlessly at 25FPS on my macbook. I can not recall the exact resolution but I wrote it down in the tool as "If you get only 10FPS on Windows, check NetworkThrottlingIndex and TCP Delayed ACK"
https://github.com/DedeHai/WLED-Tools/blob/main/FX%20to%20GIF/FX-to-gif-recorder.html