feat(starlark,on-demand): the third-party fixes worth taking, plus a Home Assistant MQTT bridge

docs/REST_API_REFERENCE.md

@@ -33,7 +33,7 @@ All endpoints return JSON responses with a standard format:
 
 > The API blueprint is mounted at `/api/v3` (`web_interface/app.py:199`).
 > SSE stream endpoints (`/api/v3/stream/*`) are defined directly on the
-> Flask app at `app.py:799-809`. There are 94 routes total — see
+> Flask app at `app.py:799-809`. There are 111 routes total — see
 > `web_interface/blueprints/api_v3.py` for the canonical list.
 
 ---
@@ -223,6 +223,56 @@ Get the current display state and preview image.
 }
 ```
 
+### List Display Modes
+
+**GET** `/api/v3/display/modes`
+
+Every display mode that can be requested on-demand, with the plugin that owns
+it. This is the list the force-display dialog offers.
+
+Send the reported `plugin_id` alongside `mode` when starting an on-demand
+display: `/display/on-demand/start` falls back to `find_plugin_for_mode` when
+`plugin_id` is omitted, and that lookup only sees modes declared in a static
+manifest — a plugin whose modes are generated (each installed Starlark app is
+one) returns 404 there.
+
+Triggers plugin discovery, which is otherwise lazy — so a caller that never
+opens the dashboard still gets the full list.
+
+**Query Parameters**:
+- `include_disabled` (optional): `1` to include modes belonging to disabled
+ plugins. They are still valid on-demand targets — the controller enables the
+ plugin for the duration of the request — and are reported with
+ `"enabled": false`.
+
+**Response**:
+```json
+{
+ "status": "success",
+ "data": {
+ "modes": [
+ {
+ "mode": "nfl_live",
+ "plugin_id": "football-scoreboard",
+ "plugin_name": "Football Scoreboard",
+ "name": "nfl_live",
+ "enabled": true
+ },
+ {
+ "mode": "clock-simple",
+ "plugin_id": "clock-simple",
+ "plugin_name": "Simple Clock",
+ "name": "Simple Clock",
+ "enabled": true
+ }
+ ]
+ }
+}
+```
+
+`name` is a label for a dropdown: a single-mode plugin's own name, or the raw
+mode string for a multi-mode plugin, since there is no per-mode name anywhere.
+
 ### On-Demand Display Status
 
 **GET** `/api/v3/display/on-demand/status`

integrations/mqtt_bridge/.gitignore

@@ -0,0 +1 @@
+bridge_config.json

integrations/mqtt_bridge/README.md

@@ -0,0 +1,118 @@
+# Home Assistant MQTT Bridge
+
+Control the matrix from Home Assistant: force any plugin or mode on demand,
+turn the display on and off, and set brightness — as real HA entities, not
+hand-written `mqtt.publish` calls.
+
+The bridge owns no display logic. It subscribes to one command topic and
+turns each message into a call against the same `api_v3` routes the web UI
+uses, so behaviour lives in one place. It talks to the API over HTTP only —
+no filesystem access — so it can run on the Pi or anywhere that can reach
+the web interface.
+
+## What appears in Home Assistant
+
+On connect the bridge publishes [MQTT Discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery)
+config, so the matrix shows up under **Settings → Devices & Services → MQTT**
+with no YAML:
+
+| Entity | Does |
+|---|---|
+| `select.ledmatrix_display_mode` | Every mode across enabled plugins. Choosing one force-displays it. |
+| `button.ledmatrix_stop_display` | Back to normal rotation. |
+| `switch.ledmatrix_power` | Starts/stops the display service. |
+| `number.ledmatrix_brightness` | 0–100. |
+
+State is read back from the API every 30 seconds, so the entities also track
+changes made from the web UI or an on-demand window expiring on its own.
+All four share an availability topic that is the bridge's MQTT last will:
+if the bridge dies, HA greys the controls out rather than leaving them
+looking live but inert.
+
+## Raw commands
+
+For anything the entities do not cover, publish JSON to the command topic
+(`ledmatrix/command` by default):
+
+```jsonc
+// Force a mode. plugin_id is optional — the bridge fills it in from
+// /api/v3/display/modes.
+{"action": "display", "mode": "nfl_live"}
+
+// duration is seconds; pinned holds this one mode instead of rotating
+// through every mode the plugin owns. Pin Starlark apps, where each mode
+// is an unrelated widget; leave a sports plugin unpinned so live/recent/
+// upcoming still cycle.
+{"action": "display", "plugin_id": "starlark-apps", "mode": "aquarium",
+ "duration": 300, "pinned": true}
+
+{"action": "stop_display"}
+{"action": "power", "state": "on"}
+{"action": "brightness", "value": 75}
+
+// Re-read the mode list and re-publish discovery, after installing a plugin
+{"action": "refresh"}
+```
+
+Every command publishes its outcome to `<command_topic>/status`, and current
+state to `<command_topic>/state`.
+
+## Requirements
+
+- A LEDMatrix install with its web interface reachable (default `http://localhost:5000`)
+- An MQTT broker that Home Assistant is also connected to
+- Python 3 with `paho-mqtt` 2.x and `requests`
+
+## Install
+
+```bash
+sudo ./scripts/install/install_mqtt_bridge.sh
+```
+
+That copies `bridge_config.example.json` to `bridge_config.json` on first
+run, installs the dependencies, and enables `ledmatrix-mqtt-bridge.service`.
+Edit the config with your broker details and re-run it.
+
+```json
+{
+ "mqtt_host": "192.168.1.10",
+ "mqtt_port": 8883,
+ "mqtt_username": "ledmatrix",
+ "mqtt_password": null,
+ "mqtt_topic": "ledmatrix/command",
+ "mqtt_tls": true,
+ "ledmatrix_api_base": "http://localhost:5000"
+}
+```
+
+**TLS is on by default.** Without it the broker password and every display
+command cross the network in cleartext. If your broker only listens on plain
+1883 — which the Mosquitto add-on does out of the box — set `"mqtt_tls": false`
+and `"mqtt_port": 1883`. The bridge logs a warning at startup when a password
+is configured without TLS.
+
+`bridge_config.json` is gitignored. Any key can also be supplied through the
+environment as `LEDMATRIX_MQTT_<KEY>` (`LEDMATRIX_MQTT_MQTT_PASSWORD`, say),
+which keeps a broker password out of a file on disk — put it in a systemd
+drop-in with `Environment=` or `EnvironmentFile=` instead.
+
+Set `mqtt_tls: true` for a broker with TLS. `mqtt_tls_insecure` skips
+certificate verification and exists only for a self-signed broker on a
+trusted LAN; it logs a warning when used.
+
+To run it in the foreground while setting things up:
+
+```bash
+python3 integrations/mqtt_bridge/ledmatrix_mqtt_bridge.py --config integrations/mqtt_bridge/bridge_config.json
+```
+
+## Notes
+
+- Only one thing can be on-demand at a time — the same constraint the web UI has.
+- Forcing a mode restarts the display service, so the panel blanks for a moment.
+- The mode list comes from `/api/v3/display/modes`, which triggers plugin
+ discovery itself. Discovery is lazy and normally happens because somebody
+ opened the dashboard; without that endpoint a bridge that never does would
+ see an empty list.
+- Brightness writes `display.hardware.brightness` through `/api/v3/config/main`.
+ The display service picks it up on its next restart, not instantly.

integrations/mqtt_bridge/bridge_config.example.json

@@ -0,0 +1,13 @@
+{
+ "mqtt_host": "192.168.1.10",
+ "mqtt_port": 8883,
+ "mqtt_username": "ledmatrix",
+ "mqtt_password": null,
+ "mqtt_client_id": "ledmatrix-mqtt-bridge",
+ "mqtt_topic": "ledmatrix/command",
+ "mqtt_tls": true,
+ "ledmatrix_api_base": "http://localhost:5000",
+ "request_timeout": 15,
+ "on_demand_duration": null,
+ "log_level": "INFO"
+}