Add battery level reporting (Kconfig-gated) and display orientation

Battery (firmware + server, disabled by default): new battery.c reads
a 2x200k voltage divider via ADC oneshot with curve-fitting calibration
(the ESP32-C6's scheme), maps through a piecewise LiPo discharge curve,
and restores the pin to button duty after each read -- the settled
XIAO ESP32-C6 design shares the back button's GPIO0/A0, time-shared per
wake. Skipped entirely when on mains (a 2x100k VBUS divider into a
spare digital pin -- the 5V pin is dead on battery power, so presence =
mains, where the charging voltage would read misleadingly full) or when
the reading is implausible. The manage overlay gains a battery region
(static outline glyph + "NN%", below the manage QR, all menu levels),
and the device POSTs to the new /frame/battery endpoint after a
successful fetch; the server stores percent + as-of timestamp, exposed
via /api/queue and shown in the web UI. FRAME_BATTERY_ADC_GPIO /
FRAME_VBUS_SENSE_GPIO default to -1 (fully inert on the dev board);
compile-verified both disabled and enabled, hardware bring-up deferred
until the ordered XIAO + batteries arrive.

Orientation (server-side only): new config setting + web UI dropdown
(landscape / portrait / landscape_flipped / portrait_flipped). Photos
are composed/cropped at the logical hanging shape (portrait crops at
480x800, so face-aware crops match how the frame actually hangs), then
rotated losslessly into the panel's native 800x480 byte layout after
dithering -- the device never knows. Face-label anchors are transformed
through the same rotation (logical_to_native()) so they stay attached
to faces on rotated frames. Known documented limitation: the on-device
manage overlay still renders in native orientation, so it appears
sideways on a portrait-hung frame (QRs scan at any rotation; text reads
sideways).

firmware/main/frame_client.c

@@ -588,7 +588,8 @@ static bool wait_for_button_press(uint32_t timeout_ms)
  * had that data); level 2 adds named-face labels on top. action only
  * applies at level 1 -- escalating to level 2 redisplays the same
  * photo, so it never re-advances/-backs. */
-static esp_err_t show_menu_level(const frame_config_t *cfg, fetch_action_t action, int level)
+static esp_err_t show_menu_level(const frame_config_t *cfg, fetch_action_t action, int level,
+                                  int battery_percent)
 {
     char management_url[256];
     build_url(management_url, sizeof(management_url), cfg, "");
@@ -621,6 +622,7 @@ static esp_err_t show_menu_level(const frame_config_t *cfg, fetch_action_t actio
         .share_url = share_url[0] != '\0' ? share_url : NULL,
         .face_labels = face_labels,
         .face_label_count = face_label_count,
+        .battery_percent = battery_percent,
     };
 
     manage_overlay_set_t overlay;
@@ -645,10 +647,10 @@ static esp_err_t show_menu_level(const frame_config_t *cfg, fetch_action_t actio
  * that (escalating, or the final revert) are logged but don't count as
  * an overall failure -- something was already shown successfully, which
  * was the point of the button. */
-static esp_err_t run_management_menu(const frame_config_t *cfg, fetch_action_t action)
+static esp_err_t run_management_menu(const frame_config_t *cfg, fetch_action_t action, int battery_percent)
 {
     int level = 1;
-    esp_err_t err = show_menu_level(cfg, action, level);
+    esp_err_t err = show_menu_level(cfg, action, level, battery_percent);
     if (err != ESP_OK) {
         ESP_LOGW(TAG, "Could not render management overlay (%s), showing photo normally", esp_err_to_name(err));
         return fetch_and_display(cfg, action, NULL);
@@ -661,7 +663,7 @@ static esp_err_t run_management_menu(const frame_config_t *cfg, fetch_action_t a
             break; /* timeout at any level, or a press while already maxed out -- exit */
         }
         level++;
-        esp_err_t level_err = show_menu_level(cfg, FETCH_NORMAL, level);
+        esp_err_t level_err = show_menu_level(cfg, FETCH_NORMAL, level, battery_percent);
         if (level_err != ESP_OK) {
             ESP_LOGW(TAG, "Could not render menu level %d (%s), reverting", level, esp_err_to_name(level_err));
             break;
@@ -678,15 +680,58 @@ static esp_err_t run_management_menu(const frame_config_t *cfg, fetch_action_t a
 /* Runs the appropriate fetch for this cycle: a plain fetch, or -- if
  * show_management_qr -- the escalating manage menu (see
  * run_management_menu()). */
-static esp_err_t run_fetch_cycle(const frame_config_t *cfg, fetch_action_t action, bool show_management_qr)
+static esp_err_t run_fetch_cycle(const frame_config_t *cfg, fetch_action_t action, bool show_management_qr,
+                                  int battery_percent)
 {
     if (!show_management_qr) {
         return fetch_and_display(cfg, action, NULL);
     }
-    return run_management_menu(cfg, action);
+    return run_management_menu(cfg, action, battery_percent);
 }
 
-void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool show_management_qr)
+/* Reports the battery percent to the server (POST /frame/battery).
+ * Best-effort only: a battery report must never fail a photo cycle, so
+ * every failure here is just a warning. No-op for percent < 0. */
+static void report_battery(const frame_config_t *cfg, int percent)
+{
+    if (percent < 0) {
+        return;
+    }
+
+    char url[256];
+    build_url(url, sizeof(url), cfg, "frame/battery");
+
+    char body[48];
+    int body_len = snprintf(body, sizeof(body), "{\"percent\": %d}", percent);
+
+    esp_http_client_config_t config = {
+        .url = url,
+        .method = HTTP_METHOD_POST,
+        .timeout_ms = CONFIG_FRAME_SERVER_CHECK_TIMEOUT_MS,
+        .crt_bundle_attach = esp_crt_bundle_attach,
+    };
+    esp_http_client_handle_t client = esp_http_client_init(&config);
+    esp_http_client_set_header(client, "Content-Type", "application/json");
+
+    esp_err_t err = esp_http_client_open(client, body_len);
+    if (err != ESP_OK) {
+        ESP_LOGW(TAG, "Battery report failed to connect: %s", esp_err_to_name(err));
+        esp_http_client_cleanup(client);
+        return;
+    }
+    esp_http_client_write(client, body, body_len);
+    int status = esp_http_client_fetch_headers(client) >= 0 ? esp_http_client_get_status_code(client) : -1;
+    if (status != 200) {
+        ESP_LOGW(TAG, "Battery report returned HTTP %d", status);
+    } else {
+        ESP_LOGI(TAG, "Reported battery %d%% to server", percent);
+    }
+    esp_http_client_close(client);
+    esp_http_client_cleanup(client);
+}
+
+void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool show_management_qr,
+                       int battery_percent)
 {
     esp_err_t epd_err = epd_init();
     bool have_display = (epd_err == ESP_OK);
@@ -720,7 +765,7 @@ void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool sho
      * worth it to stop false-failing on the common case. */
     bool image_ok = true;
     if (have_display) {
-        esp_err_t fetch_err = run_fetch_cycle(cfg, action, show_management_qr);
+        esp_err_t fetch_err = run_fetch_cycle(cfg, action, show_management_qr, battery_percent);
         image_ok = (fetch_err == ESP_OK);
         if (!image_ok) {
             /* epd_display_stream() never triggers a physical refresh on a
@@ -741,6 +786,7 @@ void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool sho
      * just be discarded. */
     uint32_t sleep_seconds = CONFIG_FRAME_RETRY_INTERVAL_S;
     if (image_ok) {
+        report_battery(cfg, battery_percent);
         frame_server_config_t server_cfg = fetch_frame_config(cfg);
         sleep_seconds = server_cfg.reachable ? server_cfg.refresh_interval_s : CONFIG_FRAME_RETRY_INTERVAL_S;
     }