Add notification-board folder with detailed README for the Notification Board script

2026-08-14 17:57:06 +00:00
parent 686fb1b937
commit 3089573e51
2 changed files with 356 additions and 0 deletions
@@ -10,6 +10,7 @@ README.
 | Ordner | Beschreibung |
 |---|---|
 | [`verbraucher-rangliste/`](./verbraucher-rangliste) | Custom Lovelace-Karte „Power Ranking Card“: zeigt alle Verbraucher (Watt/kW-Entities) absteigend nach aktueller Leistung als animierte Rangliste an. Aktuell im Einsatz auf dem Dashboard `lovelace` → View „Energie“. |
+| [`notification-board/`](./notification-board) | Home-Assistant-Script `script.notification_board`: zentrales Skript zum Versenden von Benachrichtigungen über mehrere Kanäle gleichzeitig (Mobile App, Alexa, TV, Pushover, Telegram, ntfy, persistente Benachrichtigung). |

 ## Konventionen

@@ -0,0 +1,355 @@
+# Notification Board
+
+Zentrales Home-Assistant-**Script** (`script.notification_board`), das eine
+Nachricht wahlweise über eine ganze Reihe von Kanälen gleichzeitig verschickt:
+Mobile App (iOS), Alexa-Sprachausgabe, TV, Pushover, Telegram, ntfy und
+persistente Benachrichtigung in Home Assistant. Statt in jeder Automation
+einzelne `notify.*`-Actions zu pflegen, ruft man dieses eine Script mit den
+gewünschten Feldern (`notify_oliver: true`, `pushover_lisa: true`, …) auf und
+das Script kümmert sich um Routing, Formatierung und Sonderfälle (kritische
+iOS-Alerts, Kamera-Foto als Anhang, Alexa Durchsage vs. Sprechen, …).
+
+## Voraussetzungen
+
+Damit alle Funktionen des Scripts nutzbar sind, werden folgende Integrationen
+benötigt (jedes Feld ist aber einzeln optional/deaktivierbar – man braucht nur
+die Integrationen, deren Felder man tatsächlich verwendet):
+
+| Integration | Wofür |
+|---|---|
+| **Mobile App** (iOS/Android) | `notify.mobile_app_*` – Push-Benachrichtigungen auf dem Handy, inkl. kritischer Alerts |
+| **Alexa Devices** (`alexa_devices`) | `notify.*_durchsagen` / `notify.*_sprechen` – Sprachausgabe über Echo-Geräte |
+| **Pushover** | `notify.pushover_*` – Push über Pushover-App |
+| **Telegram Bot** (`telegram_bot`) | `telegram_bot.send_message` / `send_photo` – Nachrichten/Fotos über einen Telegram-Bot |
+| **ntfy** | `notify.*` (Domain `ntfy`) – Push über selbstgehostete/öffentliche ntfy-Topics |
+| **LG webOS TV** (oder anderer Media Player mit `notify`-Unterstützung) | Einblendung auf dem Fernseher |
+| **Kamera-Integration** (optional) | `camera.snapshot` – Foto einer Kamera an ntfy/Telegram anhängen |
+
+Kern-Services (`system_log.write`, `notify.persistent_notification`) sind in
+jeder Home-Assistant-Instanz bereits vorhanden.
+
+## Funktionsweise (Kurzüberblick)
+
+1. **Notify-Targets sammeln:** Das Script baut sich zu Beginn dynamisch eine
+   Liste aller Ziel-`notify`-Entities/Services (`notify_targets`) zusammen –
+   abhängig davon, welche Boolean-Felder (`notify_oliver`, `pushover_lisa`,
+   `notify_alexa_durchsagen`, …) beim Aufruf `true` sind. Bei den Alexa-Feldern
+   wird per Template automatisch nach allen `notify.*_durchsagen` bzw.
+   `notify.*_sprechen`-Entities gesucht; alternativ können über
+   `notify_alexa_durchsagen_geraete` / `notify_alexa_sprechen_geraete` gezielt
+   einzelne Geräte ausgewählt werden.
+2. **Kamera-Snapshot (optional):** Ist `ntfy_camera` gesetzt, wird vorab ein
+   Snapshot der Kamera nach `/config/www/notification_board_snapshot.jpg`
+   geschrieben und je nach Kanal als Anhang mitgeschickt (ntfy, Telegram,
+   Pushover).
+3. **Versand-Schleife:** Für jedes Ziel in `notify_targets` wird per
+   `repeat.for_each` der passende Service mit dem passenden Datenformat
+   aufgerufen (z. B. Pushover mit `priority: 2, sound: siren` bei
+   `critical: true`, Mobile App mit `push.sound.critical: 1`, Alexa über
+   `notify.send_message`, Telegram über `telegram_bot.send_message` /
+   `send_photo` inkl. optionalem Inline-Keyboard).
+4. **ntfy separat:** ntfy-Topics werden am Ende nochmal separat behandelt
+   (eigenes Feld `ntfy_topics`, nicht Teil der generischen `notify_targets`),
+   inkl. Priorität, Action-Buttons und Kamera-Anhang.
+
+Mode: `queued`, `max: 10` – mehrere gleichzeitige Aufrufe werden nacheinander
+abgearbeitet statt sich gegenseitig abzubrechen.
+
+## Felder (Inputs)
+
+| Feld | Typ | Beschreibung |
+|---|---|---|
+| `message` | Text (mehrzeilig) | Nachrichtentext |
+| `title` | Text | Titel der Benachrichtigung |
+| `critical` | Boolean | iOS "Kritische Benachrichtigung" bzw. Pushover-Priorität 2 + Sirene |
+| `notify_persistent` | Boolean | Dauerhafte Benachrichtigung in der HA-Oberfläche |
+| `notify_oliver` / `notify_lisa` | Boolean | Push über Mobile App für die jeweilige Person |
+| `notify_familie` | Boolean | Push an beide Mobile Apps gleichzeitig |
+| `notify_tv` | Boolean | Einblendung auf dem TV (nur wenn TV eingeschaltet ist) |
+| `notify_alexa_durchsagen` | Boolean | Durchsage auf **allen** Alexa-Geräten mit `_durchsagen` |
+| `notify_alexa_durchsagen_geraete` | Entity (mehrfach) | Durchsage nur auf ausgewählten Geräten (wirkt nur wenn obiges Feld `false`) |
+| `notify_alexa_sprechen` | Boolean | Ansage im "Sprechen"-Modus auf **allen** Alexa-Geräten mit `_sprechen` |
+| `notify_alexa_sprechen_geraete` | Entity (mehrfach) | Nur ausgewählte Geräte (wirkt nur wenn obiges Feld `false`) |
+| `notify_alexa_multiroom_durchsagen` | Boolean | Durchsage über Multiroom-Gruppe(n) |
+| `pushover_oliver` / `pushover_lisa` | Boolean | Push über Pushover |
+| `telegram_oliver` | Boolean | Nachricht über Telegram senden |
+| `telegram_bot_config_entry` | Config Entry (`telegram_bot`) | Welcher Telegram-Bot verwendet wird |
+| `telegram_parse_mode` | Auswahl (`html` / `markdown` / keiner) | Formatierung der Telegram-Nachricht, Default `html` |
+| `telegram_inline_keyboard` | Text (JSON) | Optionale Buttons unter der Telegram-Nachricht |
+| `telegram_chat_id_oliver` | Text | Optionale explizite Chat-ID |
+| `ntfy_topics` | Entity (mehrfach, Domain `notify`, Integration `ntfy`) | Ziel-Topics für ntfy |
+| `ntfy_priority` | Auswahl `1`–`5` | ntfy-Priorität, Default `3` |
+| `ntfy_actions` | Text (JSON) | Bis zu 3 Action-Buttons unter der ntfy-Benachrichtigung |
+| `ntfy_camera` | Entity (Domain `camera`) | Kamera, deren aktuelles Bild an ntfy/Telegram angehängt wird |
+
+## Installation / Neu anlegen
+
+### Variante A – über die UI (empfohlen)
+
+1. **Einstellungen → Automatisierungen & Szenen → Skripte → Skript
+   hinzufügen**
+2. Oben rechts auf die drei Punkte → **"In YAML bearbeiten"** wechseln.
+3. Den YAML-Block unten (Felder-Definition) einfügen bzw. als Basis nehmen
+   und um die Sequenz-Logik ergänzen (siehe Hinweis unten).
+4. Speichern, Skript in `script.notification_board` umbenennen (Entity-ID
+   wird beim ersten Speichern aus dem Alias `Notification Board` erzeugt).
+
+### Variante B – direkt in `scripts.yaml`
+
+Falls Skripte per YAML statt Storage verwaltet werden, den Skript-Schlüssel
+`notification_board:` mit `alias`, `mode`, `max`, `fields` und `sequence`
+unter `scripts.yaml` anlegen und danach **Entwicklerwerkzeuge → YAML neu
+laden → Skripte** ausführen (oder `ha_reload_core(target="scripts")`).
+
+### Felder-Definition (YAML)
+
+```yaml
+alias: Notification Board
+mode: queued
+max: 10
+description: ''
+fields:
+  message:
+    name: Message
+    description: Nachricht
+    selector:
+      text:
+        multiline: true
+  title:
+    name: Title
+    description: Titel
+    selector:
+      text: null
+  critical:
+    name: Critical
+    description: iPhone Kritische Hinweise
+    selector:
+      boolean: {}
+    required: true
+  notify_alexa_multiroom_durchsagen:
+    name: Notify Alexa Multiroom (Durchsagen)
+    description: Sprachausgabe über alle Amazon-Geräte mit "_durchsagen"
+    selector:
+      boolean: {}
+    required: true
+  notify_alexa_durchsagen:
+    name: Notify Alexa (Durchsagen)
+    description: Sprachausgabe über Amazon-Geräte mit "_durchsagen"
+    selector:
+      boolean: {}
+    required: true
+  notify_alexa_sprechen:
+    name: Notify Alexa (Sprechen)
+    description: Sprachausgabe über Amazon-Geräte mit "_sprechen"
+    selector:
+      boolean: {}
+    required: true
+  notify_alexa_durchsagen_geraete:
+    name: Bestimmte Alexas (Durchsagen)
+    description: >-
+      Nur diese Geräte per Durchsage benachrichtigen (wirkt nur, wenn
+      "Notify Alexa (Durchsagen)" aus ist). Mehrfachauswahl möglich.
+    selector:
+      entity:
+        multiple: true
+        filter:
+          integration: alexa_devices
+          domain: notify
+  notify_alexa_sprechen_geraete:
+    name: Bestimmte Alexas (Sprechen)
+    description: >-
+      Nur diese Geräte im Sprechen-Modus benachrichtigen (wirkt nur, wenn
+      "Notify Alexa (Sprechen)" aus ist). Mehrfachauswahl möglich.
+    selector:
+      entity:
+        multiple: true
+        filter:
+          integration: alexa_devices
+          domain: notify
+  notify_tv:
+    name: Notify TV
+    description: Benachrichtigung auf TV Geräten
+    selector:
+      boolean: {}
+    required: true
+  telegram_oliver:
+    name: Telegram Oliver
+    description: Benachrichtigung über Telegram (Oliver)
+    selector:
+      boolean: {}
+    required: true
+  telegram_bot_config_entry:
+    name: Telegram Bot
+    description: Wähle den Telegram Bot aus
+    selector:
+      config_entry:
+        integration: telegram_bot
+  telegram_parse_mode:
+    name: Telegram Parse Mode
+    description: Parse Mode für Telegram
+    selector:
+      select:
+        options:
+          - label: HTML
+            value: html
+          - label: Markdown
+            value: markdown
+          - label: Kein
+            value: ''
+    default: html
+  telegram_inline_keyboard:
+    name: Telegram Inline Keyboard
+    description: >-
+      Inline Keyboard im Home Assistant Format (JSON).
+      Format 1 (einfach): ["/button1, /button2", "/button3"]
+      Format 2 (strukturiert): [[["Text btn1", "/button1"],["Text btn2", "/button2"]], [["Google link", "https://google.com"]]]
+      Beispiel: [["Strom-Bezug:/power_out", "Strom-Einspeisung:/power_in"], ["Planzenprobleme:/plant_problems"]]
+    selector:
+      text:
+        multiline: true
+  telegram_chat_id_oliver:
+    name: Telegram Chat ID (Oliver)
+    description: Chat ID für Oliver (optional, falls target benötigt wird)
+    selector:
+      text: null
+  pushover_oliver:
+    name: Pushover Oliver
+    description: Benachrichtigung über Pushover (Oliver)
+    selector:
+      boolean: {}
+    required: true
+  pushover_lisa:
+    name: Pushover Lisa
+    description: Benachrichtigung über Pushover (Lisa)
+    selector:
+      boolean: {}
+    required: true
+  notify_persistent:
+    name: Notify Persistent (Nur App)
+    description: Dauerhafte Benachrichtigung in Home Assistant
+    selector:
+      boolean: {}
+    required: true
+  notify_oliver:
+    name: Notify Oliver
+    description: Benachrichtigung über Mobile App (Oliver)
+    selector:
+      boolean: {}
+    required: true
+  notify_lisa:
+    name: Notify Lisa
+    description: Benachrichtigung über Mobile App (Lisa)
+    selector:
+      boolean: {}
+    required: true
+  notify_familie:
+    name: Notify Familie
+    description: Benachrichtigung über beide Mobile Apps
+    selector:
+      boolean: {}
+    required: true
+  ntfy_topics:
+    name: Ziel (ntfy Themen)
+    description: ntfy-Themen (Topics), an die gesendet werden soll
+    selector:
+      entity:
+        multiple: true
+        filter:
+          integration: ntfy
+          domain: notify
+  ntfy_priority:
+    name: Nachrichtenpriorität (ntfy)
+    description: Priorität der ntfy-Benachrichtigung (1 = minimal, 5 = maximal)
+    selector:
+      select:
+        options:
+          - label: 1 - Minimum
+            value: '1'
+          - label: 2 - Niedrig
+            value: '2'
+          - label: 3 - Standard
+            value: '3'
+          - label: 4 - Hoch
+            value: '4'
+          - label: 5 - Maximal
+            value: '5'
+        mode: dropdown
+    default: '3'
+  ntfy_actions:
+    name: Aktionsknöpfe (ntfy)
+    description: >-
+      Bis zu 3 Buttons unter der Benachrichtigung, als JSON-Liste. Das Feld
+      heisst "action" (nicht "type")!
+      Website/App oeffnen: {"action": "view", "label": "Text", "url": "https://...", "clear": true}
+      HTTP-Request senden: {"action": "http", "label": "Text", "url": "https://...", "method": "POST", "headers": {}, "body": "...", "clear": true}
+      Android-Broadcast senden: {"action": "broadcast", "label": "Text", "intent": "...", "extras": {}, "clear": true}
+      In Zwischenablage kopieren: {"action": "copy", "label": "Text", "value": "...", "clear": true}
+      Beispiel: [{"action": "view", "label": "Dashboard oeffnen", "url": "http://homeassistant.local:8123", "clear": true}]
+    selector:
+      text:
+        multiline: true
+  ntfy_camera:
+    name: Kamera-Foto
+    description: >-
+      Optional: Kamera, deren aktuelles Bild an ntfy- und
+      Telegram-Benachrichtigungen angehängt wird
+    selector:
+      entity:
+        filter:
+          domain: camera
+```
+
+> Die vollständige `sequence:` (Ablauflogik mit allen Templates) ist bewusst
+> nicht 1:1 in dieser README abgedruckt, da sie stark auf die konkreten
+> Entity-IDs dieser Instanz zugeschnitten ist (siehe nächster Abschnitt). Der
+> einfachste Weg, das Script 1:1 zu übernehmen, ist ein Export/Import über
+> **Einstellungen → Automatisierungen & Szenen → Skripte → Notification Board
+   → ⋮ → Herunterladen** auf der Quell-Instanz und Import auf der Ziel-Instanz,
+> oder das Kopieren der Sequenz aus dem YAML-Editor der Quell-Instanz.
+
+## Anpassungen bei Neuaufbau auf einer anderen Instanz
+
+Folgende Stellen in der `sequence:` sind **hart auf diese Instanz** codiert
+und müssen bei einer Neuinstallation angepasst werden:
+
+| Stelle | Aktueller Wert | Anpassen auf |
+|---|---|---|
+| TV-Zustand prüfen | `media_player.lg_webos_tv_75nano769qa` | eigene TV-`media_player`-Entity |
+| TV-Benachrichtigung senden | `notify.lg_webos_tv_75nano769qa` | eigene TV-`notify`-Entity |
+| Pushover Ziel Oliver | `notify.pushover_oliver` | eigene Pushover-`notify`-Entity |
+| Pushover Ziel Lisa | `notify.pushover_lisa` | eigene Pushover-`notify`-Entity |
+| Mobile App Oliver | `notify.mobile_app_iphone14pro_oliver` | eigene Mobile-App-`notify`-Entity |
+| Mobile App Lisa | `notify.mobile_app_meins` | eigene Mobile-App-`notify`-Entity |
+| Telegram Bot Fallback-ID | `telegram_config_entry_id` fällt, wenn `telegram_bot_config_entry` leer ist, auf die feste Config-Entry-ID `01KG2WFXSK97RRBGS7XF9990DV` zurück | eigene Telegram-Bot Config-Entry-ID (oder Fallback entfernen und das Feld verpflichtend machen) |
+| Kamera-Snapshot Pfad | `/config/www/notification_board_snapshot.jpg` | kann so bleiben, muss aber im `www`-Ordner beschreibbar sein |
+
+Die Alexa-Erkennung (`notify.*_durchsagen`, `notify.*_sprechen`,
+`notify.*multiroom_durchsagen`) ist **nicht** hart codiert, sondern läuft
+per Namens-Pattern über alle vorhandenen `notify`-Entities – hier ist nur
+wichtig, dass die eigenen Alexa-`notify`-Entities entsprechend benannt sind
+(bzw. die passenden Felder für Geräteauswahl genutzt werden).
+
+## Beispielaufruf
+
+Als Service-Call (z. B. aus einer Automation):
+
+```yaml
+action: script.notification_board
+data:
+  title: "Waschmaschine fertig"
+  message: "Die Waschmaschine ist seit 5 Minuten fertig."
+  critical: false
+  notify_familie: true
+  notify_persistent: true
+  pushover_oliver: false
+  pushover_lisa: false
+  notify_tv: false
+  telegram_oliver: false
+  notify_alexa_durchsagen: false
+  notify_alexa_sprechen: false
+  notify_alexa_multiroom_durchsagen: false
+```
+
+Alle Boolean-Felder sind `required: true`, müssen beim Aufruf also explizit
+mitgegeben werden (auch mit `false`), sofern man sie nicht über die
+UI-Skriptmaske ausfüllt, die die Defaults automatisch setzt.