185 lines
5.3 KiB
Markdown
185 lines
5.3 KiB
Markdown
# Design: Display-Steuerung Schritt 1 — Command-Pipeline
|
|
|
|
**Datum:** 2026-03-26
|
|
**Scope:** Command-Pipeline (MQTT + Agent + Backend-API + Ansible-DPMS-Fix)
|
|
**Nicht in Scope:** Zeitplan (Schritt 2), UI-Schalter (Schritt 3)
|
|
|
|
## Ziel
|
|
|
|
Das Backend kann ein einzelnes Display per API-Aufruf ein- oder ausschalten. Der Befehl wird per MQTT an den Agent auf dem Pi übermittelt. Der Agent führt `xset dpms force on/off` aus und meldet den Ist-Zustand zurück.
|
|
|
|
## Gesamtarchitektur
|
|
|
|
```
|
|
Aufrufer (manuell / später: Zeitplan oder UI)
|
|
│
|
|
▼
|
|
POST /api/v1/screens/{screenSlug}/display
|
|
│
|
|
├─► MQTT publish (retained, QoS 1)
|
|
│ Topic: signage/screen/{slug}/command
|
|
│ Payload: {"action": "display_on"}
|
|
│
|
|
▼
|
|
Agent (auf dem Pi)
|
|
│
|
|
├─► xset dpms force on/off
|
|
│
|
|
├─► MQTT publish (QoS 0, nicht retained)
|
|
│ Topic: signage/screen/{slug}/display-state
|
|
│ Payload: {"display_state": "on", "ts": "..."}
|
|
│
|
|
└─► nächster HTTP-Status-Report (POST /api/v1/player/status)
|
|
+ display_state: "on"|"off"|"unknown"
|
|
│
|
|
▼
|
|
Backend: speichert in screen_status-Tabelle
|
|
```
|
|
|
|
## MQTT-Vertrag
|
|
|
|
### Command-Topic (Backend → Agent)
|
|
|
|
- **Topic:** `signage/screen/{screenSlug}/command`
|
|
- **QoS:** 1
|
|
- **Retained:** true
|
|
- **Payload:**
|
|
```json
|
|
{"action": "display_on"}
|
|
```
|
|
oder
|
|
```json
|
|
{"action": "display_off"}
|
|
```
|
|
|
|
Retained sorgt dafür, dass der Agent nach einem Neustart automatisch den letzten Sollzustand empfängt und wiederherstellt.
|
|
|
|
### Display-State-Topic (Agent → Welt)
|
|
|
|
- **Topic:** `signage/screen/{screenSlug}/display-state`
|
|
- **QoS:** 0
|
|
- **Retained:** false
|
|
- **Payload:**
|
|
```json
|
|
{"display_state": "on", "ts": "2026-03-26T10:00:00Z"}
|
|
```
|
|
|
|
`display_state`: `"on"` | `"off"` | `"unknown"`
|
|
|
|
## Backend-Änderungen
|
|
|
|
### 1. Neuer API-Endpunkt
|
|
|
|
`POST /api/v1/screens/{screenSlug}/display`
|
|
|
|
- Auth: `authScreen` (bestehende Middleware, Tenant-Isolation)
|
|
- Request-Body: `{"state": "on"}` oder `{"state": "off"}`
|
|
- Aktion: publiziert MQTT-Command (retained, QoS 1)
|
|
- Response: `204 No Content`
|
|
- Fehler: `400` bei ungültigem `state`, `404` bei unbekanntem Screen
|
|
|
|
### 2. Erweiterung `mqttnotifier`
|
|
|
|
Neue Methode:
|
|
```go
|
|
func (n *Notifier) SendDisplayCommand(screenSlug, action string) error
|
|
```
|
|
Publiziert auf `signage/screen/{screenSlug}/command` mit QoS 1 und `retained=true`.
|
|
|
|
Das bestehende `publish()`-Helper nutzt QoS 0 und `retain=false` — `SendDisplayCommand` ruft den MQTT-Client direkt auf, um QoS 1 und `retain=true` zu setzen. Gibt Fehler zurück wenn der Publish fehlschlägt; der HTTP-Handler antwortet dann mit `502`.
|
|
|
|
### 3. Neue DB-Tabelle `screen_status`
|
|
|
|
Migration:
|
|
```sql
|
|
create table if not exists screen_status (
|
|
screen_id text primary key references screens(id) on delete cascade,
|
|
display_state text, -- 'on' | 'off' | 'unknown'
|
|
reported_at timestamptz not null default now()
|
|
);
|
|
```
|
|
|
|
### 4. Erweiterung `POST /api/v1/player/status`
|
|
|
|
Request-Payload bekommt optionales Feld:
|
|
```json
|
|
{"display_state": "on"}
|
|
```
|
|
|
|
Backend schreibt/aktualisiert `screen_status` per UPSERT.
|
|
|
|
### 5. Neuer Store-Methode
|
|
|
|
```go
|
|
func (s *ScreenStore) UpsertDisplayState(ctx context.Context, screenID, displayState string) error
|
|
```
|
|
|
|
## Agent-Änderungen
|
|
|
|
### 1. Neues Package `displaycontroller`
|
|
|
|
Pfad: `player/agent/internal/displaycontroller/controller.go`
|
|
|
|
```go
|
|
type Controller struct {
|
|
display string // DISPLAY-Env, z.B. ":0"
|
|
currentState string // "on" | "off" | "unknown"
|
|
mu sync.Mutex
|
|
}
|
|
|
|
func New(display string) *Controller
|
|
func (c *Controller) TurnOn() error // xset -display :0 dpms force on
|
|
func (c *Controller) TurnOff() error // xset -display :0 dpms force off
|
|
func (c *Controller) State() string // aktueller Zustand (thread-safe)
|
|
```
|
|
|
|
Nach `TurnOn`/`TurnOff` publiziert der Controller den neuen Zustand per MQTT auf `display-state`-Topic.
|
|
|
|
`DISPLAY` wird aus Env-Var gelesen (Default: `:0`).
|
|
|
|
### 2. Erweiterung `mqttsubscriber`
|
|
|
|
Drittes Topic: `signage/screen/{slug}/command`
|
|
|
|
Bei eingehender Nachricht:
|
|
- JSON parsen
|
|
- `action` auslesen (`display_on` oder `display_off`)
|
|
- `DisplayController.TurnOn()` bzw. `TurnOff()` aufrufen
|
|
- Unbekannte Actions: loggen, ignorieren
|
|
|
|
### 3. Erweiterung `statusreporter`
|
|
|
|
Request-Payload bekommt Feld `display_state string` — aus `DisplayController.State()` befüllt.
|
|
|
|
## Ansible-Änderungen
|
|
|
|
Datei: `ansible/roles/signage_display/templates/morz-kiosk.j2`
|
|
|
|
```bash
|
|
# Vorher:
|
|
xset -dpms
|
|
|
|
# Nachher:
|
|
xset +dpms
|
|
xset dpms 0 0 0 # Timeouts deaktivieren — Steuerung nur über Backend
|
|
```
|
|
|
|
Optional (falls Agent nicht im X-Kontext läuft):
|
|
`ansible/roles/signage_display/templates/morz-kiosk.service.j2`:
|
|
```ini
|
|
Environment=XAUTHORITY=/home/{{ signage_user }}/.Xauthority
|
|
```
|
|
Wird beim Testen geprüft.
|
|
|
|
## Nicht in Scope (Schritt 1)
|
|
|
|
- Zeitplan (`power_on_time`, `power_off_time`, `schedule_enabled`)
|
|
- UI-Schalter in der Playlist-Verwaltung
|
|
- Sammelschalter für mehrere Displays
|
|
- `device_commands`-Tabelle (Audit-Log)
|
|
- Backend-MQTT-Subscriber (Backend empfängt keine MQTT-Messages)
|
|
|
|
## Offen / beim Testen zu klären
|
|
|
|
- Braucht der Agent explizit `XAUTHORITY` im Systemd-Unit, oder reicht `DISPLAY=:0`?
|
|
- Funktioniert `xset` aus dem Agent-Prozess heraus, oder muss es im X-Session-Kontext laufen?
|