From 2aa887a0377a04f18bc8238551ad7cd8854b0477 Mon Sep 17 00:00:00 2001 From: Patrick Balsiger Date: Sun, 28 Sep 2025 22:10:18 +0200 Subject: [PATCH] docs(streaming): add 'Things to consider' on high-frequency WS usage and throttling Notes on heap fragmentation, UDP saturation, throttling/coalescing, buffer reuse, yielding, and payload sizing for reliable streaming/broadcast. --- docs/StreamingAPI.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/StreamingAPI.md b/docs/StreamingAPI.md index 0ab22ba..8acc5a6 100644 --- a/docs/StreamingAPI.md +++ b/docs/StreamingAPI.md @@ -78,3 +78,21 @@ Notes: Related docs: - [`ClusterBroadcast.md`](./ClusterBroadcast.md) — centralized UDP broadcasting and CLUSTER_EVENT format +### Things to consider + +- High-frequency updates can overwhelm ESP8266: + - Frequent JSON parse/serialize and `String` allocations fragment heap and may cause resets (e.g., Exception(3)). + - UDP broadcast on every message amplifies load; WiFi/UDP buffers can back up. + - Prefer ≥50–100 ms intervals; microbursts at 10 ms are risky. +- Throttle and coalesce: + - Add a minimum interval in the core `cluster/broadcast` handler. + - Optionally drop redundant updates (e.g., same color as previous). +- Reduce allocations: + - Reuse `StaticJsonDocument`/preallocated buffers in hot paths. + - Avoid re-serializing when possible; pass-through payload strings. + - Reserve `String` capacity when reuse is needed. +- Yielding: + - Call `yield()` in long-running or bursty paths to avoid WDT. +- Packet size: + - Keep payloads small to fit `ClusterProtocol::UDP_BUF_SIZE` and reduce airtime. +