luke/esp32-poe-scrypted-viewport/main, branch v1.3.1

release: v1.3.1

2026-07-16T00:04:56+00:00

Stream throughput tuning, measured on hardware (kitchen panel): wire 53 -> 74 Mbps, per-frame recv 30.5 -> 21.4 ms, painted fps 19.8 -> 23.6, g2g 73 -> 62 ms, sender backpressure 61% -> 47%. - lwip: TCP_WND 5760 -> 23040 (16 x MSS), RECVMBOX 6 -> 32 - eth: EMAC RX DMA pool sized above the TCP window (1600B x 24); below-window pool caused silent burst tail-drop + ~200-400ms sender RTO stalls - stream: TCP-window decomposition instrumentation (wire kbps, hdr_gap, pend_age) in the window log and /state; connect log stamps TCP_WND/MSS/RECVMBOX Set VIEWPORT_VERSION and scrypted/package.json to 1.3.1.

stream: instrument TCP-window decomposition (wire kbps, hdr_gap, pend_age)

2026-07-15T23:04:31+00:00

Before touching CONFIG_LWIP_TCP_WND_DEFAULT, make the window question decidable from the logs. New per-window metrics in the stream log, /state, and stats struct: - wire min/avg/max kbps: instantaneous throughput while each body drained (jpeg_len/recv_us). Ceiling ~= TCP_WND/RTT, so it scales with the window iff the window is the limiter. - hdr_gap min/avg/max us: time blocked waiting for the next header after finishing a body. Large = sender-paced; ~0 = receive path is the bottleneck. - pend_age min/avg/max us: publish->claim latency of painted frames. Growing across windows = queue backlog building, the failure mode that killed the previous WND=65535 attempt. Together with recv/dec/paint the frame interval is now fully decomposable: interval ~= hdr_gap + recv + pend_age + dec + paint. Also stamp TCP_WND/TCP_MSS/RECVMBOX into the client-connect log line so every capture is self-labeled with the config it ran under.

release: v1.3.0

2026-07-01T19:23:49+00:00

Unify firmware and plugin versions for the production release. Highlights since v1.1.0/1.2.0: - event wake fixed (self-healing camera-listener re-attach after the reload/ add storage race); doorbell/motion/person confirmed on hardware - stop() fully tears down (stop+start == fresh load); stale childId pruning; live-stream events ignored (no queue/relaunch) - triggers default to person+doorbell; doorbell hidden for non-doorbell cams - cold-start (wake -> live video) ~6s -> ~0.7s: prebuffered substream by id + request >= GOP + burst-friendly ffmpeg flags; snapshot removed - firmware: Loading screen on new stream connection (no stale-frame flash) - logging trimmed for chatty cameras - README/protocol docs rewritten for the TCP-socket streaming model Set VIEWPORT_VERSION and scrypted/package.json to 1.3.0.

firmware: clear panel to Loading screen on new stream connection

2026-07-01T01:50:34+00:00

The panel used to hold its last framebuffer during the connect→first-frame gap, flashing a stale old frame before video appeared — more visible now that the Scrypted side no longer sends a bridging snapshot. The wake path already paints the Loading screen, but state_machine_set(AWAKE) is a no-op when the device is already awake (e.g. a stream restart), so the clear didn't happen there. Tie the clear to the stream connection instead: recv-task paints local_screens_show_loading() once per new conn_id, guarded by the decoder lock so the RGB565 present can't race a trailing decode-task paint, and gated on AWAKE so it never draws on a sleeping panel.

firmware: split stream recv into its own task with 3-buffer ping-pong

2026-06-21T01:50:43+00:00

handle_client previously ran recv → decode → paint serially on one FreeRTOS task. The kernel TCP buffer filled during decode+paint (~6ms), and against the IDF-default 5760-byte window the sender naturally stop-go-rate-limited to ~consumption. Raising the window to 65535 (previous experiment) regressed g2g from ~100ms to 17s growing unbounded — the sender pumped 45+ segments per round into a kernel buffer the app couldn't drain in time, and there was no way to skip-oldest on the kernel queue. This commit decouples recv from decode+paint: recv-task: owns the socket. Reads header + body into one of three preallocated PSRAM body buffers. On body complete, swaps the just-filled buffer into a 1-deep pending slot and picks a free buffer for the next recv. If the slot already held a frame (decode is slow), drops oldest in place — mirror of the Scrypted-side skip-oldest from e5acf93. decode-task: waits on a binary semaphore. On signal, claims pending, then decodes + paints without holding any shared lock. Frees its prior buffer implicitly by overwriting s_decode_idx on the next claim. 3 PSRAM body buffers (~3MB of 28MB free) ensure the invariant {recv_idx, pending_idx, decode_idx} are pairwise distinct without ever blocking recv. jpeg_decoder.c grew an alloc_input_buffer helper + jpeg_decoder_decode now takes an explicit input pointer so the stream and http_api snapshot paths don't share scratch. New stats: - recv_dropped_oldest: per-window count of pending-slot overwrites - decode_idle_min/avg/max_us: time decode-task spent waiting on signal Measurement at IDF-default 5760 window, Unifi medium substream: before split: recv_avg=32ms recv_max~44ms fps=22-26 (recv blocked during 6ms decode+paint; chunk_max capped at 5760) after split: recv_avg=17ms recv_max=18-37ms fps=21-29 steady, decode_idle_avg=27-40ms (decode mostly waiting), drop_oldest=0, painted at source rate The bottleneck moved from 'decode+paint serializes recv' to the wire's own send rate. Bigger windows are now safe (recv-task drains continuously, can't bury us), but won't add fps until source rate goes up — that's a separate conversation.

firmware: recv-throughput instrumentation (FIONREAD pre-body, recv() call/chunk stats, SO_RCVBUF probe)

2026-06-21T01:16:01+00:00

Per-frame samples aggregated over the existing 30-frame window: - queued_at_body_start (FIONREAD just before body recv loop): how much of the frame the kernel already absorbed during the previous decode+paint. Close to jpeg_len → wire delivered the full frame while we were busy (we're decode/paint-bound). Much smaller → wire is throttled (window or buffer too small to absorb a frame in our paint window). - recv_calls: number of recv() syscalls the body read needed per frame. High → small chunks → window-throttled sender. - recv_chunk min/avg/max: bytes returned per recv() return in the window. Avg = window body bytes / total syscalls. - SO_RCVBUF: one-shot getsockopt at accept, logged and stashed in stats. Confirms whether sdkconfig values reached the build — TCP_WND_DEFAULT discrepancies are otherwise invisible. All surfaced in the windowed log and in /state JSON alongside the existing recv/dec/paint/idle stats. No behavior change yet.

firmware: OTA firmware updates via POST /firmware + rollback

2026-06-20T18:03:23+00:00

Streams the raw .bin to the inactive ota_0/ota_1 slot via esp_ota_*, flips otadata, replies 200, reboots after 500 ms. Single-shot guarded by atomic_flag (409 on concurrent). CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE armed: new images boot pending-verify and ota_arm_healthy_timer marks them valid after 30 s of healthy uptime; otherwise the bootloader reverts on next reset. /state gains ota_state.

firmware: live-update last_paint_event_us_low so /state g2g reflects real frame age

2026-06-20T16:50:25+00:00

Previous Phase 4 implementation only published last_paint_event_us_low into the windowed-stats snapshot at every 30-frame roll (~1.5s at 20fps). Combined with the script's 5s /state poll cadence, the "freshest frame age" we could compute was up to ~6.5s stale before any actual lag — meaningless as a perf signal. Update s_stats.last_paint_event_us_low under portMUX on every painted v1 frame. The other window stats (recv/dec/paint/idle min/avg/max + fps/MBps) keep their roll cadence because they genuinely need a full window to compute; this single u32 just gets overwritten with the most recent value each paint. portENTER_CRITICAL on the ESP32-P4 is ~half a microsecond per side — at 20fps that's 20µs/s of overhead, immeasurable next to the 30-40ms recv per frame. Expected: g2g during a saturated stream drops from the previous 2-6s reading to single-digit hundreds of ms or lower, reflecting the actual emit→display lag.

phase 6: performance review playbook in TESTING.md + UDP-vs-TCP rationale in stream_server

2026-06-20T16:40:26+00:00

Two pieces of documentation, neither changes behavior: 1. TESTING.md gains a "Performance review playbook" section: per- session capture commands for firmware serial + /state poll + Scrypted console, an annotated walkthrough of what each log shape means, an investigation-threshold table mapping user-facing symptoms to likely causes and the first thing to check, and a one-line tools list. Replaces the implicit "ask the maintainer how to debug" loop with a reproducible workflow. 2. stream_server.c gains a "Why TCP and not UDP" header comment documenting the analysis from the design phase. JPEGs are ~123 IP datagrams at 1500 MTU; on hardwired Gigabit LAN switch-fabric loss is < 1e-9/packet → per-frame corruption ≈ 1.2e-7. UDP's theoretical wins (no Nagle, latest-wins semantics) don't apply because TCP_NODELAY is on, socket.write p50 < 1ms, and the FIONREAD trick already implements latest-wins on the receive side. UDP's costs (200-400 LOC of app-layer fragmentation, loss of nc/curl debug, FIONREAD trick stops working under fragmentation) are real. Documented as reference so a future contributor doesn't re-derive the analysis from scratch.

phase 4: glass-to-glass via 16-byte stream header + /state stream stats

2026-06-20T16:38:14+00:00

Wire format change: stream frames now carry a 4-byte "VPRT" magic + 4-byte jpeg_len + 4-byte seq + 4-byte event_us_low. Total 16 bytes (was 8). The firmware sniffs the first 4 bytes per frame: if they spell VPRT it reads the remaining 12 bytes of v1 header; otherwise it interprets bytes 0-3 as jpeg_len for the old v0 8-byte format and reads 4 more for seq. Lets a v1 firmware accept a v0 (legacy) Scrypted script during the rollout window. v0 will be removed once all field deployments roll forward. event_us_low is the low 32 bits of the Scrypted host's monotonic µs at camera-event arrival. The firmware does NOT interpret it (the clocks aren't sync'd); it just stamps it on every painted frame and exposes the most recent value via /state. The script polls /state every 5s during an active stream, reads last_paint_event_us_low, and computes glass-to-glass = (now_us_low - last_paint_event_us_low) with 32-bit wrap. 30s sanity ceiling on the wrap to discard event timestamps from before the stream started. Also expose the firmware's just-closed 30-frame window stats via /state under the "stream" key — frames, bytes, window_us, plus min/avg/max for recv/dec/paint/idle. Lets external tools (a curl loop, the Scrypted plugin, etc) poll the firmware's view without parsing serial logs. Firmware: - stream_server.h: 16-byte v1 wire spec, stream_server_stats_t struct, stream_server_snapshot_stats(out) getter. - stream_server.c: magic-detect header read path, last_event_us_low capture into per-connection state, portMUX-protected window-stats snapshot at every 30-frame roll. - http_api.c: GET /state JSON gains a "stream" sub-object with the full snapshot. - viewport_state.h: VIEWPORT_VERSION 1.0.0 → 1.1.0 (new /state shape). Scrypted: - startStream captures eventUsLow = (tEvent * 1000) >>> 0. - TCP demux loop writes the 16-byte v1 header with the VPRT magic. - New fwPoller setInterval (5s) fetches /state, parses .stream, computes g2g, emits one summary line per poll cycle.