M5: POST /frame — hardware JPEG decode + orientation-aware paint

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.

1 files changed, 97 insertions, 0 deletions

diff --git a/main/jpeg_decoder.c b/main/jpeg_decoder.c
new file mode 100644
index 0000000..b34612d
--- /dev/null
+++ b/main/jpeg_decoder.c
@@ -0,0 +1,97 @@
+#include "jpeg_decoder.h"
+
+#include <string.h>
+
+#include "driver/jpeg_decode.h"
+#include "esp_check.h"
+#include "esp_log.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/semphr.h"
+
+static const char *TAG = "jpeg";
+
+static jpeg_decoder_handle_t s_engine;
+static SemaphoreHandle_t     s_mutex;
+static void   *s_in_buf;
+static size_t  s_in_cap;
+static void   *s_out_buf;
+static size_t  s_out_cap;
+
+esp_err_t jpeg_decoder_init(void)
+{
+    s_mutex = xSemaphoreCreateMutex();
+    if (!s_mutex) return ESP_ERR_NO_MEM;
+
+    jpeg_decode_engine_cfg_t cfg = {
+        .intr_priority = 0,
+        .timeout_ms    = 200,
+    };
+    ESP_RETURN_ON_ERROR(jpeg_new_decoder_engine(&cfg, &s_engine),
+                       TAG, "jpeg_new_decoder_engine");
+
+    // DMA-aligned PSRAM scratch buffers. Allocate once, reuse.
+    jpeg_decode_memory_alloc_cfg_t in_cfg  = { .buffer_direction = JPEG_DEC_ALLOC_INPUT_BUFFER };
+    jpeg_decode_memory_alloc_cfg_t out_cfg = { .buffer_direction = JPEG_DEC_ALLOC_OUTPUT_BUFFER };
+
+    s_in_buf = jpeg_alloc_decoder_mem(JPEG_DECODER_MAX_INPUT_BYTES,  &in_cfg,  &s_in_cap);
+    if (!s_in_buf) {
+        ESP_LOGE(TAG, "jpeg input buf alloc failed");
+        return ESP_ERR_NO_MEM;
+    }
+    s_out_buf = jpeg_alloc_decoder_mem(JPEG_DECODER_MAX_OUTPUT_BYTES, &out_cfg, &s_out_cap);
+    if (!s_out_buf) {
+        ESP_LOGE(TAG, "jpeg output buf alloc failed");
+        return ESP_ERR_NO_MEM;
+    }
+
+    ESP_LOGI(TAG, "decoder ready (in=%u bytes, out=%u bytes)",
+             (unsigned)s_in_cap, (unsigned)s_out_cap);
+    return ESP_OK;
+}
+
+bool jpeg_decoder_try_lock(uint32_t timeout_ms)
+{
+    return xSemaphoreTake(s_mutex, pdMS_TO_TICKS(timeout_ms)) == pdTRUE;
+}
+
+void jpeg_decoder_unlock(void)
+{
+    xSemaphoreGive(s_mutex);
+}
+
+void *jpeg_decoder_input_buffer(void) { return s_in_buf; }
+
+esp_err_t jpeg_decoder_decode(size_t   jpeg_len,
+                              void   **out_rgb565,
+                              uint16_t *out_width,
+                              uint16_t *out_height)
+{
+    if (jpeg_len == 0 || jpeg_len > s_in_cap) return ESP_ERR_INVALID_SIZE;
+
+    jpeg_decode_cfg_t dec_cfg = {
+        .output_format = JPEG_DECODE_OUT_FORMAT_RGB565,
+        .rgb_order     = JPEG_DEC_RGB_ELEMENT_ORDER_RGB,
+        .conv_std      = JPEG_YUV_RGB_CONV_STD_BT601,
+    };
+
+    jpeg_decode_picture_info_t info = {0};
+    esp_err_t err = jpeg_decoder_get_info(s_in_buf, jpeg_len, &info);
+    if (err != ESP_OK) {
+        ESP_LOGW(TAG, "jpeg_decoder_get_info: %s", esp_err_to_name(err));
+        return err;
+    }
+
+    uint32_t out_size = 0;
+    err = jpeg_decoder_process(s_engine, &dec_cfg,
+                               s_in_buf,  jpeg_len,
+                               s_out_buf, s_out_cap, &out_size);
+    if (err != ESP_OK) {
+        ESP_LOGW(TAG, "jpeg_decoder_process: %s", esp_err_to_name(err));
+        return err;
+    }
+
+    *out_rgb565 = s_out_buf;
+    *out_width  = info.width;
+    *out_height = info.height;
+    return ESP_OK;
+}