Add battery widget (device's own last-reported level, no live upstream)

Shows Frame.battery_percent/battery_as_of, already set by every device
wake-on-battery report, plus routers/common.py's existing
battery_estimate_s time-remaining estimate -- nothing new to fetch or
cache. Compact (icon + percent) or detailed (+ estimate, last report
age) display mode. No button actions.

server/tests/test_migrations.py

@@ -82,6 +82,9 @@ def test_expected_columns_exist_on_current_schema():
     assert "weather_widget_configs" in inspector.get_table_names()  # migration 24
     weather_widget_columns = {c["name"] for c in inspector.get_columns("weather_widget_configs")}
     assert {"mode", "provider", "city_latitude", "cities"} <= weather_widget_columns
+    assert "battery_widget_configs" in inspector.get_table_names()  # migration 25
+    battery_widget_columns = {c["name"] for c in inspector.get_columns("battery_widget_configs")}
+    assert "mode" in battery_widget_columns
 
 
 # --- widget system backfill (migration 16 + _ensure_widgets_backfilled) ---
@@ -192,22 +195,24 @@ def test_migration_16_raw_sql_path_applies_to_an_existing_pre_widget_database(db
     with db_module.engine.begin() as conn:
         # static_widget_configs/text_widget_configs are migration 20/21
         # tables, saved_layouts/saved_layout_widgets/saved_layout_
-        # sources/saved_layout_button_actions are migration 23's, and
-        # weather_widget_configs is migration 24's (all post-16, like the
+        # sources/saved_layout_button_actions are migration 23's,
+        # weather_widget_configs is migration 24's, and
+        # battery_widget_configs is migration 25's (all post-16, like the
         # rest of this list) -- dropped here too so a real version-15
         # database is what's actually being simulated, not "version 15
         # plus tables that wouldn't exist yet". Harmless to omit as long
         # as no migration after the one that creates a table also ALTERs
         # or re-CREATEs it (that's what let a create_all-based migration
         # go unlisted safely so far), but static_widget_configs/
-        # text_widget_configs/weather_widget_configs all use a raw
-        # CREATE TABLE (not create_all -- see migration 20's own
-        # docstring on why), so an already-present one is a real "table
-        # already exists" collision, not a silent no-op.
+        # text_widget_configs/weather_widget_configs/battery_widget_
+        # configs all use a raw CREATE TABLE (not create_all -- see
+        # migration 20's own docstring on why), so an already-present one
+        # is a real "table already exists" collision, not a silent no-op.
         for table in ("frame_button_actions", "whiteboard_widget_configs", "task_widget_configs", "frame_task_lists",
                       "calendar_widget_configs", "photo_widget_configs", "static_widget_configs",
                       "text_widget_configs", "saved_layout_button_actions", "saved_layout_sources",
-                      "saved_layout_widgets", "saved_layouts", "weather_widget_configs", "widgets"):
+                      "saved_layout_widgets", "saved_layouts", "weather_widget_configs",
+                      "battery_widget_configs", "widgets"):
             conn.execute(text(f"DROP TABLE {table}"))
         conn.execute(text("DROP TABLE frame_calendars"))
         conn.execute(text(
@@ -275,11 +280,11 @@ def test_migration_17_and_18_extract_tasks_into_a_standalone_multi_list_widget(d
     calendar_key columns either."""
     with db_module.engine.begin() as conn:
         # static_widget_configs/text_widget_configs/saved_layout_*/
-        # weather_widget_configs dropped too -- see the comment on the
-        # identical setup in
+        # weather_widget_configs/battery_widget_configs dropped too --
+        # see the comment on the identical setup in
         # test_migration_16_raw_sql_path_applies_to_an_existing_pre_widget_database above (migrations
-        # 20/21/23/24's raw CREATE TABLE collides with an already-present table
-        # otherwise, since this test replays 17 through 24 and none of
+        # 20/21/23/24/25's raw CREATE TABLE collides with an already-present table
+        # otherwise, since this test replays 17 through 25 and none of
         # these tables would really exist yet at a genuine pre-migration-17
         # schema_version).
         conn.execute(text("DROP TABLE task_widget_configs"))
@@ -292,6 +297,7 @@ def test_migration_17_and_18_extract_tasks_into_a_standalone_multi_list_widget(d
         conn.execute(text("DROP TABLE saved_layout_widgets"))
         conn.execute(text("DROP TABLE saved_layouts"))
         conn.execute(text("DROP TABLE weather_widget_configs"))
+        conn.execute(text("DROP TABLE battery_widget_configs"))
         conn.execute(text(
             "CREATE TABLE calendar_widget_configs ("
             "widget_id INTEGER PRIMARY KEY REFERENCES widgets(id) ON DELETE CASCADE, "
@@ -393,7 +399,8 @@ def test_frame_calendars_rekey_attaches_existing_rows_to_their_calendar_widget(d
         for table in ("frame_button_actions", "whiteboard_widget_configs", "task_widget_configs", "frame_task_lists",
                       "calendar_widget_configs", "photo_widget_configs", "static_widget_configs",
                       "text_widget_configs", "saved_layout_button_actions", "saved_layout_sources",
-                      "saved_layout_widgets", "saved_layouts", "weather_widget_configs", "widgets"):
+                      "saved_layout_widgets", "saved_layouts", "weather_widget_configs",
+                      "battery_widget_configs", "widgets"):
             conn.execute(text(f"DROP TABLE {table}"))
         conn.execute(text("DROP TABLE frame_calendars"))
         conn.execute(text(

server/tests/test_widget_config_and_queue_endpoints.py

@@ -14,6 +14,7 @@ import io
 from PIL import Image
 
 from app.models import (
+    BatteryWidgetConfig,
     CalendarWidgetConfig,
     Frame,
     PhotoWidgetConfig,
@@ -93,6 +94,18 @@ def _add_weather_widget(db_session, **cfg_kwargs) -> Widget:
     return widget
 
 
+def _add_battery_widget(db_session, **cfg_kwargs) -> Widget:
+    import time
+
+    widget = Widget(frame_id=1, widget_type="battery", x=0, y=0, w=1, h=1,
+                    sort_order=1, created_at=time.time())
+    db_session.add(widget)
+    db_session.flush()
+    db_session.add(BatteryWidgetConfig(widget_id=widget.id, **cfg_kwargs))
+    db_session.commit()
+    return widget
+
+
 def _png_bytes(size=(20, 10), color=(10, 20, 30)) -> bytes:
     buf = io.BytesIO()
     Image.new("RGB", size, color).save(buf, format="PNG")
@@ -277,6 +290,38 @@ def test_config_save_rejects_an_unrecognized_static_display_mode(client, db_sess
     assert cfg.display_mode == "crop_fill"
 
 
+def test_config_save_updates_a_battery_widget(client, db_session):
+    client.post("/setup", data={"username": "alice", "password": "hunter22"})
+    widget = _add_battery_widget(db_session)
+
+    resp = client.post(
+        f"/api/frames/1/widgets/{widget.id}/config",
+        data={"battery_mode": "compact"},
+        headers=csrf_headers(client),
+    )
+    assert resp.status_code == 200, resp.text
+
+    cfg = db_session.get(BatteryWidgetConfig, widget.id)
+    assert cfg.mode == "compact"
+
+
+def test_config_save_rejects_an_unrecognized_battery_mode(client, db_session):
+    """Falls back to the default rather than erroring -- same "clamp,
+    don't reject" posture as the other config-save fields."""
+    client.post("/setup", data={"username": "alice", "password": "hunter22"})
+    widget = _add_battery_widget(db_session)
+
+    resp = client.post(
+        f"/api/frames/1/widgets/{widget.id}/config",
+        data={"battery_mode": "graph"},
+        headers=csrf_headers(client),
+    )
+    assert resp.status_code == 200, resp.text
+
+    cfg = db_session.get(BatteryWidgetConfig, widget.id)
+    assert cfg.mode == "detailed"
+
+
 def test_config_save_updates_a_text_widget(client, db_session):
     client.post("/setup", data={"username": "alice", "password": "hunter22"})
     widget = _add_text_widget(db_session)
@@ -502,6 +547,38 @@ def test_preview_text_400s_for_a_widget_that_is_not_text(client, db_session):
     assert resp.status_code == 400
 
 
+# --- battery: preview ---------------------------------------------------
+
+def test_preview_battery_renders_even_before_any_report(client, db_session):
+    """Unlike every other widget type's preview endpoint, there's no
+    "not configured yet" 400 -- render() always has something to show
+    (a placeholder, here, since the frame's never reported)."""
+    client.post("/setup", data={"username": "alice", "password": "hunter22"})
+    widget = _add_battery_widget(db_session)
+    resp = client.get(f"/api/frames/1/widgets/{widget.id}/preview/battery")
+    assert resp.status_code == 200, resp.text
+    assert resp.headers["content-type"] == "image/png"
+
+
+def test_preview_battery_renders_after_a_report(client, db_session):
+    client.post("/setup", data={"username": "alice", "password": "hunter22"})
+    widget = _add_battery_widget(db_session)
+    frame = db_session.get(Frame, 1)
+    frame.battery_percent = 77
+    db_session.commit()
+
+    resp = client.get(f"/api/frames/1/widgets/{widget.id}/preview/battery")
+    assert resp.status_code == 200, resp.text
+    assert resp.headers["content-type"] == "image/png"
+
+
+def test_preview_battery_400s_for_a_widget_that_is_not_battery(client, db_session):
+    client.post("/setup", data={"username": "alice", "password": "hunter22"})
+    widget = _add_static_widget(db_session)
+    resp = client.get(f"/api/frames/1/widgets/{widget.id}/preview/battery")
+    assert resp.status_code == 400
+
+
 # --- weather: location/cities/preview ---------------------------------
 
 def _mock_geocode(monkeypatch, label="Portland, Oregon, United States", latitude=45.5, longitude=-122.6):

server/tests/test_widgets_battery.py

@@ -0,0 +1,83 @@
+"""app.widgets.battery -- unit-level, no HTTP: constructs Widget/
+BatteryWidgetConfig rows directly and sets Frame.battery_percent/
+battery_as_of straight on the Frame row, same as routers/device.py's
+frame_battery would."""
+
+from __future__ import annotations
+
+import time
+
+from app import widgets
+from app.models import BatteryWidgetConfig, Frame, Widget
+
+
+def _make_widget(db_session, mode="detailed") -> tuple[Frame, Widget]:
+    frame = db_session.get(Frame, 1)
+    widget = Widget(frame_id=frame.id, widget_type="battery", x=0, y=0, w=1, h=1,
+                    sort_order=0, created_at=time.time())
+    db_session.add(widget)
+    db_session.flush()
+    db_session.add(BatteryWidgetConfig(widget_id=widget.id, mode=mode))
+    db_session.commit()
+    return frame, widget
+
+
+def test_render_shows_a_placeholder_when_frame_has_never_reported(db_session):
+    frame, widget = _make_widget(db_session)
+    assert frame.battery_percent == -1
+    img = widgets.battery.render(db_session, frame, widget, 300, 200)
+    assert img.size == (300, 200)
+    assert img.mode == "RGB"
+
+
+def test_render_shows_the_reported_percent(db_session):
+    frame, widget = _make_widget(db_session)
+    frame.battery_percent = 42
+    frame.battery_as_of = time.time()
+    db_session.commit()
+    img = widgets.battery.render(db_session, frame, widget, 300, 200)
+    assert img.size == (300, 200)
+    assert img.mode == "RGB"
+
+
+def test_render_compact_mode_omits_the_estimate_lines(db_session):
+    frame, widget = _make_widget(db_session, mode="compact")
+    frame.battery_percent = 80
+    frame.battery_as_of = time.time()
+    db_session.commit()
+    img = widgets.battery.render(db_session, frame, widget, 300, 200)
+    assert img.size == (300, 200)
+
+
+def test_render_at_minimum_grid_footprint(db_session):
+    """grid.MIN_FOOTPRINT["battery"] is (1, 1) cells -- on an 8x5 grid
+    against a full 800x480 panel that's a 100x96 box, the smallest a
+    battery widget can actually be placed at."""
+    frame, widget = _make_widget(db_session)
+    frame.battery_percent = 15
+    db_session.commit()
+    img = widgets.battery.render(db_session, frame, widget, 100, 96)
+    assert img.size == (100, 96)
+
+
+def test_render_falls_back_to_detailed_mode_with_no_config_row(db_session):
+    """widget_id has no BatteryWidgetConfig row at all -- render() must
+    not raise, matching every other widget type's "never raises for a
+    foreseeable failure" contract."""
+    frame = db_session.get(Frame, 1)
+    widget = Widget(frame_id=frame.id, widget_type="battery", x=0, y=0, w=1, h=1,
+                    sort_order=0, created_at=time.time())
+    db_session.add(widget)
+    db_session.flush()
+    db_session.commit()
+    frame.battery_percent = 60
+    db_session.commit()
+    img = widgets.battery.render(db_session, frame, widget, 100, 96)
+    assert img.size == (100, 96)
+
+
+def test_no_button_actions():
+    """A number the device itself pushes on every wake -- nothing to
+    advance/back/check."""
+    assert widgets.battery.ACTIONS == {}
+    assert widgets.battery.ACTION_LABELS == {}