---
name: MQTT Home Assistant Integration Plan
description: Detailed plan for adding MQTT discovery-based Home Assistant integration to the split-flap display Flask app
type: project
---

Plan to add MQTT integration to the split-flap display so Home Assistant can control it natively.

**Why:** The display is currently only controllable via the Flask web UI. MQTT lets HA send text, switch apps/animations, and see current state via auto-discovered entities.

**How to apply:** When implementing, all changes go in `SplitFlap-RPI-FRONTEND/frontend_code_apr24/app.py`. The full plan is saved at `.claude/plans/cached-beaming-twilight.md`.

**Summary of approach:**
- Add `paho-mqtt` dependency
- MQTT settings added to `load_settings()` defaults: broker (homeassistant.local), port (1883), user, password, enabled flag
- 3 HA entities via MQTT Discovery: `text` (send display text), `select` (switch app/animation mode), `sensor` (current display string)
- All entities grouped under one device, shared LWT availability on `splitflap/availability`
- Command handlers reuse existing patterns: `send_to_display()`, `active_app`, `stop_event.set()`, `loop_delay` logic
- State published with `retain=True` from `send_to_display()` and route handlers so HA stays in sync
- Graceful fallback if MQTT unavailable (same pattern as serial fallback)
- Firmware and serial protocol unchanged
- Broker: Mosquitto add-on on Home Assistant