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, 107 insertions, 1 deletions

diff --git a/main/http_api.c b/main/http_api.c
index 7e97407..8bf5f81 100644
--- a/main/http_api.c
+++ b/main/http_api.c
@@ -12,6 +12,7 @@
 #include "esp_timer.h"
 
 #include "display.h"
+#include "jpeg_decoder.h"
 #include "mdns_service.h"
 #include "net_eth.h"
 #include "nvs_config.h"
@@ -273,6 +274,105 @@ static esp_err_t config_post_handler(httpd_req_t *req)
 }
 
 // ============================================================================
+// POST /frame
+// ============================================================================
+static esp_err_t respond_status(httpd_req_t *req, const char *status, const char *body)
+{
+    httpd_resp_set_status(req, status);
+    httpd_resp_set_type(req, "text/plain");
+    return httpd_resp_send(req, body, body ? HTTPD_RESP_USE_STRLEN : 0);
+}
+
+static void expected_dims(uint16_t *w, uint16_t *h)
+{
+    viewport_state_lock();
+    bool portrait = (viewport_state_get()->orientation == VIEWPORT_ORIENTATION_PORTRAIT);
+    viewport_state_unlock();
+    if (portrait) { *w = 480; *h = 800; }
+    else          { *w = 800; *h = 480; }
+}
+
+static esp_err_t frame_post_handler(httpd_req_t *req)
+{
+    // Content-Type must be image/jpeg.
+    char ct[40] = {0};
+    if (httpd_req_get_hdr_value_str(req, "Content-Type", ct, sizeof(ct)) != ESP_OK ||
+        strncasecmp(ct, "image/jpeg", 10) != 0) {
+        return respond_status(req, "400 Bad Request", "Content-Type must be image/jpeg");
+    }
+
+    if (req->content_len == 0) {
+        return respond_status(req, "400 Bad Request", "empty body");
+    }
+    if (req->content_len > JPEG_DECODER_MAX_INPUT_BYTES) {
+        return respond_status(req, "413 Payload Too Large", "JPEG > 1 MB");
+    }
+
+    if (!display_is_up()) {
+        return respond_status(req, "500 Internal Server Error", "display not initialized");
+    }
+
+    // Single in-flight frame. Concurrent posts get 503 (spec).
+    if (!jpeg_decoder_try_lock(0)) {
+        return respond_status(req, "503 Service Unavailable", "frame in flight");
+    }
+
+    esp_err_t result = ESP_OK;
+    uint8_t *in = jpeg_decoder_input_buffer();
+    size_t got = 0;
+    while (got < req->content_len) {
+        int n = httpd_req_recv(req, (char *)(in + got), req->content_len - got);
+        if (n <= 0) { result = ESP_FAIL; break; }
+        got += n;
+    }
+
+    if (result != ESP_OK) {
+        jpeg_decoder_unlock();
+        return respond_status(req, "400 Bad Request", "body read failed");
+    }
+
+    void   *rgb = NULL;
+    uint16_t w = 0, h = 0;
+    esp_err_t dec_err = jpeg_decoder_decode(got, &rgb, &w, &h);
+    if (dec_err != ESP_OK) {
+        viewport_state_lock();
+        viewport_state_get()->decode_errors++;
+        viewport_state_unlock();
+        jpeg_decoder_unlock();
+        return respond_status(req, "400 Bad Request", "JPEG decode failed");
+    }
+
+    uint16_t want_w, want_h;
+    expected_dims(&want_w, &want_h);
+    if (w != want_w || h != want_h) {
+        viewport_state_lock();
+        viewport_state_get()->decode_errors++;
+        viewport_state_unlock();
+        jpeg_decoder_unlock();
+        char msg[80];
+        snprintf(msg, sizeof(msg), "expected %ux%u, got %ux%u", want_w, want_h, w, h);
+        return respond_status(req, "400 Bad Request", msg);
+    }
+
+    esp_err_t paint_err = display_present_rgb565((const uint16_t *)rgb, w, h);
+    if (paint_err != ESP_OK) {
+        jpeg_decoder_unlock();
+        return respond_status(req, "500 Internal Server Error", "display paint failed");
+    }
+
+    viewport_state_lock();
+    viewport_state_t *st = viewport_state_get();
+    st->frames_received++;
+    st->last_frame_us = esp_timer_get_time();
+    viewport_state_unlock();
+
+    jpeg_decoder_unlock();
+
+    httpd_resp_set_status(req, "204 No Content");
+    return httpd_resp_send(req, NULL, 0);
+}
+
+// ============================================================================
 // Route table + start
 // ============================================================================
 static const httpd_uri_t s_state_get = {
@@ -284,6 +384,9 @@ static const httpd_uri_t s_config_get = {
 static const httpd_uri_t s_config_post = {
     .uri = "/config", .method = HTTP_POST, .handler = config_post_handler,
 };
+static const httpd_uri_t s_frame_post = {
+    .uri = "/frame",  .method = HTTP_POST, .handler = frame_post_handler,
+};
 
 esp_err_t http_api_start(void)
 {
@@ -300,7 +403,10 @@ esp_err_t http_api_start(void)
                        TAG, "register GET /config");
     ESP_RETURN_ON_ERROR(httpd_register_uri_handler(server, &s_config_post),
                        TAG, "register POST /config");
+    ESP_RETURN_ON_ERROR(httpd_register_uri_handler(server, &s_frame_post),
+                       TAG, "register POST /frame");
 
-    ESP_LOGI(TAG, "http server listening on :80 (GET /state, GET/POST /config)");
+    ESP_LOGI(TAG, "http server listening on :80 "
+                  "(GET /state, GET/POST /config, POST /frame)");
     return ESP_OK;
 }