154 lines
5.0 KiB
Markdown
154 lines
5.0 KiB
Markdown
# Backend Task: Subscribe to Vesper MQTT Alert Topics
|
|
|
|
> Use this document as a prompt / task brief for implementing the backend side
|
|
> of the Vesper MQTT alert system. The firmware changes are complete.
|
|
> Full topic spec: `docs/reference/mqtt-events.md`
|
|
|
|
---
|
|
|
|
## What the firmware now publishes
|
|
|
|
The Vesper firmware (v155+) publishes on three status topics:
|
|
|
|
### 1. `vesper/{device_id}/status/heartbeat` (unchanged)
|
|
- Every 30 seconds, retained, QoS 1
|
|
- You already handle this — **no change needed** except: suppress any log entry / display update triggered by heartbeat arrival. Update `last_seen` silently. Only surface an event when the device goes *silent* (no heartbeat for 90s).
|
|
|
|
### 2. `vesper/{device_id}/status/alerts` (NEW)
|
|
- Published only when a subsystem state changes (HEALTHY → WARNING, WARNING → CRITICAL, etc.)
|
|
- QoS 1, not retained
|
|
- One message per state transition — not repeated until state changes again
|
|
|
|
**Alert payload:**
|
|
```json
|
|
{ "subsystem": "FileManager", "state": "WARNING", "msg": "ConfigManager health check failed" }
|
|
```
|
|
**Cleared payload (recovery):**
|
|
```json
|
|
{ "subsystem": "FileManager", "state": "CLEARED" }
|
|
```
|
|
|
|
### 3. `vesper/{device_id}/status/info` (NEW)
|
|
- Published on significant device state changes (playback start/stop, etc.)
|
|
- QoS 0, not retained
|
|
|
|
```json
|
|
{ "type": "playback_started", "payload": { "melody_uid": "ABC123" } }
|
|
```
|
|
|
|
---
|
|
|
|
## What to implement in the backend (FastAPI + MQTT)
|
|
|
|
### Subscribe to new topics
|
|
|
|
Add to your MQTT subscription list:
|
|
```python
|
|
client.subscribe("vesper/+/status/alerts", qos=1)
|
|
client.subscribe("vesper/+/status/info", qos=0)
|
|
```
|
|
|
|
### Database model — active alerts per device
|
|
|
|
Create a table (or document) to store the current alert state per device:
|
|
|
|
```sql
|
|
CREATE TABLE device_alerts (
|
|
device_id TEXT NOT NULL,
|
|
subsystem TEXT NOT NULL,
|
|
state TEXT NOT NULL, -- WARNING | CRITICAL | FAILED
|
|
message TEXT,
|
|
updated_at TIMESTAMP NOT NULL,
|
|
PRIMARY KEY (device_id, subsystem)
|
|
);
|
|
```
|
|
|
|
Or equivalent in your ORM / MongoDB / Redis structure.
|
|
|
|
### MQTT message handler — alerts topic
|
|
|
|
```python
|
|
def on_alerts_message(device_id: str, payload: dict):
|
|
subsystem = payload["subsystem"]
|
|
state = payload["state"]
|
|
message = payload.get("msg", "")
|
|
|
|
if state == "CLEARED":
|
|
# Remove alert from active set
|
|
db.device_alerts.delete(device_id=device_id, subsystem=subsystem)
|
|
else:
|
|
# Upsert — create or update
|
|
db.device_alerts.upsert(
|
|
device_id = device_id,
|
|
subsystem = subsystem,
|
|
state = state,
|
|
message = message,
|
|
updated_at = now()
|
|
)
|
|
|
|
# Optionally push a WebSocket event to the console UI
|
|
ws_broadcast(device_id, {"event": "alert_update", "subsystem": subsystem, "state": state})
|
|
```
|
|
|
|
### MQTT message handler — info topic
|
|
|
|
```python
|
|
def on_info_message(device_id: str, payload: dict):
|
|
event_type = payload["type"]
|
|
data = payload.get("payload", {})
|
|
|
|
# Store or forward as needed — e.g. update device playback state
|
|
if event_type == "playback_started":
|
|
db.devices.update(device_id, playback_active=True, melody_uid=data.get("melody_uid"))
|
|
elif event_type == "playback_stopped":
|
|
db.devices.update(device_id, playback_active=False, melody_uid=None)
|
|
```
|
|
|
|
### API endpoint — get active alerts for a device
|
|
|
|
```
|
|
GET /api/devices/{device_id}/alerts
|
|
```
|
|
|
|
Returns the current active alert set (the upserted rows from the table above):
|
|
|
|
```json
|
|
[
|
|
{ "subsystem": "FileManager", "state": "WARNING", "message": "SD mount failed", "updated_at": "..." },
|
|
{ "subsystem": "TimeKeeper", "state": "WARNING", "message": "NTP sync failed", "updated_at": "..." }
|
|
]
|
|
```
|
|
|
|
An empty array means the device is fully healthy (no active alerts).
|
|
|
|
### Console UI guidance
|
|
|
|
- Device list: show a coloured dot next to each device (green = no alerts, yellow = warnings, red = critical/failed). Update via WebSocket push.
|
|
- Device detail page: show an "Active Alerts" section that renders the alert set statically. Do not render a scrolling alert log — just the current state.
|
|
- When a `CLEARED` event arrives, remove the entry from the UI immediately.
|
|
|
|
---
|
|
|
|
## What NOT to do
|
|
|
|
- **Do not log every heartbeat** as a visible event. Heartbeats are internal housekeeping.
|
|
- **Do not poll the device** for health status — the device pushes on change.
|
|
- **Do not store alerts as an append-only log** — upsert by `(device_id, subsystem)`. The server holds the current state, not a history.
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
1. Flash a device with firmware v155+
|
|
2. Subscribe manually:
|
|
```bash
|
|
mosquitto_sub -h <broker> -t "vesper/+/status/alerts" -v
|
|
mosquitto_sub -h <broker> -t "vesper/+/status/info" -v
|
|
```
|
|
3. Remove the SD card from the device — expect a `FileManager` `WARNING` alert within 5 minutes (next health check cycle), or trigger it immediately via:
|
|
```json
|
|
{ "v": 2, "cmd": "system.health" }
|
|
```
|
|
sent to `vesper/{device_id}/control`
|
|
4. Reinsert the SD card — expect a `FileManager` `CLEARED` alert on the next health check
|