From 6cbdd4ed7466da28e524c9e0804722428a4b9698 Mon Sep 17 00:00:00 2001
From: Luke Hoersten <luke@hoersten.org>
Date: Sat, 13 Jun 2026 22:48:48 -0500
Subject: M5: POST /frame — hardware JPEG decode + orientation-aware paint
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

jpeg_decoder.{h,c} wraps esp_driver_jpeg (ESP32-P4 hardware decoder).
- One-time engine + DMA-aligned PSRAM scratch buffer setup (1 MB input,
  768 KB output @ panel native 800x480 RGB565).
- try_lock + unlock so concurrent /frame POSTs get 503 instead of
  queueing, per spec.
- jpeg_decoder_get_info() reports the dimensions; the http handler
  validates them against the effective resolution before painting.

display.h adds display_present_rgb565(src, w, h):
- Landscape: src is 800x480, memcpy 1:1 into the panel framebuffer.
- Portrait: src is 480x800, software rotate 90° CW into the 800x480
  panel framebuffer. (PPA / 2D-DMA hardware rotation is a later
  optimization if portrait latency matters.)

http_api.c adds POST /frame:
- Content-Type must be image/jpeg → else 400.
- Empty body → 400. > 1 MB → 413. Display not initialized → 500.
- jpeg_decoder_try_lock(0) for concurrency: second post returns 503.
- Body streamed into the decoder's input buffer in chunks.
- Decode failure or dimension mismatch → 400 + decode_errors++.
- Paint failure → 500.
- Success → frames_received++, last_frame_us = esp_timer_get_time(),
  204 No Content.

app_main initializes the JPEG decoder after display_init(). Both are
best-effort: failures log a warning and leave the rest of the firmware
running.

CMakeLists.txt: add esp_driver_jpeg to REQUIRES.

Known gap (M6 closes it): /frame currently paints regardless of
wake/sleep state. The 409-when-asleep rule lands with POST /state
in M6.

Build clean against ESP-IDF 5.4 (binary ~640 KB).

TESTING.md M5 expanded with portrait/landscape test commands,
ImageMagick test-image recipes, the full negative matrix (wrong
Content-Type, oversize, wrong dims, concurrent, garbage), and the
M6 dependency note.
---
 main/jpeg_decoder.h | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 main/jpeg_decoder.h

(limited to 'main/jpeg_decoder.h')

diff --git a/main/jpeg_decoder.h b/main/jpeg_decoder.h
new file mode 100644
index 0000000..9c5bf89
--- /dev/null
+++ b/main/jpeg_decoder.h
@@ -0,0 +1,33 @@
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "esp_err.h"
+
+#define JPEG_DECODER_MAX_INPUT_BYTES   (1024 * 1024)        // 1 MB
+#define JPEG_DECODER_MAX_OUTPUT_BYTES  (800 * 480 * 2)      // RGB565 panel native
+
+// One-time setup of the ESP32-P4 hardware JPEG decoder. Allocates reusable
+// DMA-aligned input + output buffers in PSRAM.
+esp_err_t jpeg_decoder_init(void);
+
+// The decoder owns shared scratch buffers. Caller must serialize access.
+// http_api uses a try-lock so concurrent /frame POSTs get 503 instead of
+// queueing.
+bool jpeg_decoder_try_lock(uint32_t timeout_ms);
+void jpeg_decoder_unlock(void);
+
+// Pointer to the input scratch buffer (PSRAM, DMA-aligned). Capacity =
+// JPEG_DECODER_MAX_INPUT_BYTES. Caller fills before calling decode.
+void *jpeg_decoder_input_buffer(void);
+
+// Decode the JPEG sitting in the input buffer. Fills out_rgb565 with a
+// pointer to the decoded RGB565 image and reports its width/height in
+// pixels.  The output buffer is owned by the decoder — valid only until
+// the next jpeg_decoder_unlock().
+esp_err_t jpeg_decoder_decode(size_t   jpeg_len,
+                              void   **out_rgb565,
+                              uint16_t *out_width,
+                              uint16_t *out_height);
-- 
cgit v1.2.3