ioBroker-Skripte/AWTRIX Now Playing Sonos/Readme.md aktualisiert

ioBroker-Skripte/AWTRIX Now Playing Sonos/Readme.md

@@ -1,201 +1,82 @@
-# 🎵 AWTRIX NowPlaying – Sonos → AWTRIX Custom App (ioBroker)
+# AWTRIX 3 – Sonos NowPlaying (ioBroker Script)
 
-Zeigt den aktuell laufenden Song von **Sonos** als eigene **AWTRIX Custom-App** an:  
+Zeigt den aktuell abgespielten Sonos-Titel als **AWTRIX 3 Custom App** via **MQTT** an:
-`🎵 Künstler — Titel (Album)` – hält sich per Keep-Alive in der Rotation, solange ein Titel läuft.
 
-> Getestet mit ioBroker (Javascript Adapter) + MQTT Adapter und einer AWTRIX mit MQTT-Support für Custom-Apps.
+> 🎵 Künstler — Titel (Album)
 
----
+Das Script nutzt einen **Keep-Alive Refresh**, damit die App in der Rotation bleibt, solange Sonos spielt. Sobald Playback stoppt/pausiert oder kein Titel mehr vorhanden ist, wird die App automatisch entfernt.
 
-## 🚀 Features
+## Features
 
-- Liest **Titel / Artist / Album** aus Sonos-Datenpunkten  
+- ✅ Anzeige: `🎵 Künstler — Titel (Album)`
-- Baut automatisch die Anzeige: `🎵 Künstler — Titel (Album)`  
+- ✅ Keep-Alive Refresh (damit die App nicht „rausfällt“)
-- **Keep-Alive**: hält die App aktiv, solange ein Titel vorhanden ist  
+- ✅ Entfernt die App automatisch bei Stop/Pause/kein Titel
-- Automatisches **Entfernen** der App, sobald keine Titelinfos mehr da sind  
+- ✅ Debounce gegen Event-Spam vom Sonos-Adapter
-- Optionales **FORCE_SWITCH**: bei jedem Refresh auf die App umschalten  
+- ✅ Alles in **einer Datei** (ioBroker-friendly)
-- **Debounce-Logik** (200 ms) gegen Flattern bei Trackwechseln  
 
----
+## Voraussetzungen
 
-## 🧩 Voraussetzungen
+- ioBroker **JavaScript-Adapter**
+- ioBroker **Sonos-Adapter**
+- ioBroker **MQTT-Adapter** (als Client/Publisher nutzbar über `sendMessage2Client`)
+- AWTRIX 3 mit aktivierter MQTT-Anbindung (Prefix bekannt, i.d.R. `awtrix`)
 
-- **ioBroker** mit:
+## Installation (Quick Start)
-  - Javascript Adapter (zum Ausführen des Skripts)
-  - MQTT Adapter (als Client zum MQTT-Broker; verwendet `sendMessage2Client`)
-  - Sonos Adapter (liefert `current_title`, `current_artist`, `current_album`)
-- **AWTRIX** (mit MQTT-Support für Custom-Apps)
-- Ein erreichbarer **MQTT-Broker** (falls nicht in ioBroker integriert)
 
----
+1. Datei `nowplaying.js` öffnen und den Block **USER CONFIG** anpassen:
+   - `AWTRIX_PREFIX` (meist `awtrix`)
+   - `DP.*` (deine Sonos-Datenpunkte)
+2. In ioBroker → **JavaScript** → neues Script anlegen → Inhalt von `nowplaying.js` einfügen
+3. Script starten
+4. Sonos abspielen → nach spätestens wenigen Sekunden sollte es auf der AWTRIX erscheinen
 
-## ⚙️ Installation
+## Sonos-Datenpunkte finden
 
-1. In ioBroker den **Javascript-Adapter** öffnen → neues Script `NowPlaying Sonos → AWTRIX` anlegen  
+In ioBroker unter **Objekte**:
-2. Den Code aus `nowplaying_sonos_awtrix.js` einfügen  
-3. Folgende Werte anpassen:
-   - `MQTT_INSTANCE`, `AWTRIX_PREFIX`
-   - Sonos-Datenpunkte unter `DP.title / artist / album`
-4. Skript starten  
-   → Beim ersten laufenden Titel sollte auf der AWTRIX die App **NowPlaying** erscheinen.
 
----
+`sonos.0` → `root` → `<dein Gerät>` →  
+- `current_title`
+- `current_artist`
+- `current_album`
+- `state_simple`
 
-## 🔧 Konfiguration
+Kopiere die Objekt-IDs in `CFG.DP`.
 
-| Variable           | Typ     | Standardwert | Beschreibung |
+## AWTRIX MQTT Topics (was das Script sendet)
-|--------------------|---------|---------------|--------------|
-| `MQTT_INSTANCE`    | String  | `"mqtt.0"`    | ioBroker-Instanzname des MQTT-Adapters |
-| `AWTRIX_PREFIX`    | String  | `"awtrix"`    | MQTT-Prefix der AWTRIX (z. B. `awtrix/custom/NowPlaying`) |
-| `APP_NAME`         | String  | `"NowPlaying"`| Name der Custom-App |
-| `LIFETIME_SEC`     | Number  | `600`         | Lebensdauer der App in Sekunden (wenn kein Refresh kommt) |
-| `KEEPALIVE_SEC`    | Number  | `10`          | Intervall für den Refresh in Sekunden |
-| `FORCE_SWITCH`     | Boolean | `false`       | Bei jedem Refresh auf die App umschalten |
-| `ICON_MUSIC`       | Number  | `29944`       | AWTRIX-Icon-ID |
-| `COLOR_RGB`        | Array   | `[255,255,255]` | RGB-Farbe für Text |
-| `TEXT_CASE`        | Number  | `2`           | Textdarstellung (0 = normal, 1 = upper, 2 = smart) |
-| `DP.title`         | String  | Beispiel      | Sonos-Datenpunkt `current_title` |
-| `DP.artist`        | String  | Beispiel      | Sonos-Datenpunkt `current_artist` |
-| `DP.album`         | String  | Beispiel      | Sonos-Datenpunkt `current_album` |
 
-> ⚠️ **Hinweis:** Passe die Sonos-Datenpunkte an dein Gerät an – IP und Struktur können variieren.
+- Custom App:
+  - `<prefix>/custom/<APP_NAME>`
+  - Beispiel: `awtrix/custom/NowPlaying`
+- Optionaler Switch:
+  - `<prefix>/switch`
+  - Wird nur genutzt, wenn `FORCE_SWITCH=true`
 
----
+## Konfiguration (wichtigste Optionen)
 
-## 🧠 Funktionsweise
+Im `CFG` Block:
 
-1. **Trigger:**  
+- `LIFETIME_SEC`: Wie lange ein Eintrag ohne Refresh überlebt
-   ```js
+- `KEEPALIVE_SEC`: Alle wieviel Sekunden refreshed wird
-   on({ id: [DP.title, DP.artist, DP.album], change: "ne" }, scheduleUpdate);
+- `FORCE_SWITCH`: Wenn `true`, schaltet AWTRIX bei jedem Refresh aktiv auf die App (meist **false** lassen)
-   ```
+- `ICON_MUSIC`, `COLOR_RGB`, `TEXT_CASE`: Darstellung
-   Bei Änderung wird `updateAwtrix()` mit Debounce (200 ms) aufgerufen.
+- `DEBUG`: Zusätzliche Logs
 
-2. **Logik:**
+## Troubleshooting
-   - Kein Titel → App entfernen, Keep-Alive stoppen  
-   - Neuer Track → Text bauen, sofort publishen, Keep-Alive starten  
-   - Gleicher Track → Keep-Alive aktualisiert regelmäßig selbst  
 
-3. **Keep-Alive:**  
+### Es wird nichts angezeigt
-   Alle `KEEPALIVE_SEC` Sekunden wird `publishCustom()` aufgerufen.  
+- Stimmt `AWTRIX_PREFIX`?
-   Sobald kein Titel mehr vorhanden ist → App wird automatisch entfernt.
+- Ist MQTT auf der AWTRIX aktiv?
+- Funktioniert dein MQTT Adapter (und kann publishen)?
+- Stimmen die Sonos-Datenpunkte?
 
----
+### App verschwindet nach kurzer Zeit
+- `KEEPALIVE_SEC` ggf. kleiner setzen (z.B. 5–10)
+- `LIFETIME_SEC` größer setzen (z.B. 600–1200)
+- Prüfen ob `state_simple` wirklich `true` während Playback ist
 
-## 📡 MQTT-Themen & Payloads
+### Die Uhr springt ständig auf die App
+- `FORCE_SWITCH` auf `false` setzen
 
-### Custom-App veröffentlichen
+## Lizenz
-**Topic:**  
-```
-<AWTRIX_PREFIX>/custom/<APP_NAME>
-```
 
-**Payload:**
+MIT – siehe `LICENSE`.
-```json
-{
-  "name": "NowPlaying",
-  "text": "🎵 Artist — Title (Album)",
-  "icon": 29944,
-  "color": [255, 255, 255],
-  "textCase": 2,
-  "lifetime": 600
-}
-```
-
----
-
-### Auf App umschalten (optional)
-**Topic:**  
-```
-<AWTRIX_PREFIX>/switch
-```
-
-**Payload:**
-```json
-{ "name": "NowPlaying" }
-```
-
----
-
-### App entfernen
-**Topic:**  
-```
-<AWTRIX_PREFIX>/custom/<APP_NAME>
-```
-
-**Payload:**
-```json
-{ "name": "NowPlaying", "lifetime": 1 }
-```
-
----
-
-> Das Skript sendet über:
-> ```js
-> sendTo("mqtt.X", "sendMessage2Client", { topic, message, retain: false, qos: 0 });
-> ```
-
----
-
-## 🛠️ Anpassungen & Tipps
-
-### Mehrere Sonos-Player
-- Skript **duplizieren**
-- `APP_NAME` (z. B. `NowPlaying_Kueche`) und `DP.*` anpassen
-
-### Anzeige-Dauer / Refresh
-- Anzeige-Frequenz → `KEEPALIVE_SEC`
-- Ablaufzeit ohne Refresh → `LIFETIME_SEC`
-
-### Direkter Wechsel auf NowPlaying
-- `FORCE_SWITCH = true` setzen, um bei jedem Refresh direkt zu wechseln
-
----
-
-## 🧰 Troubleshooting
-
-| Problem | Mögliche Ursache / Lösung |
-|----------|----------------------------|
-| Keine Anzeige | MQTT-Broker nicht erreichbar, falsches Prefix oder kein Song aktiv |
-| App verschwindet zu schnell | `LIFETIME_SEC` erhöhen |
-| Zu häufige Refreshs | `KEEPALIVE_SEC` erhöhen |
-| Falsches Icon oder Textformat | `ICON_MUSIC` oder `TEXT_CASE` anpassen |
-| App spammt Rotation | `FORCE_SWITCH = false` lassen |
-| Keine Daten von Sonos | Sonos-Adapter prüfen (korrekte Player-IDs?) |
-
----
-
-## 💾 Code
-
-Die vollständige Version liegt in:  
-`nowplaying_sonos_awtrix.js`
-
----
-
-## 🔒 Sicherheit
-
-- MQTT-Zugangsdaten werden im ioBroker-MQTT-Adapter verwaltet  
-- Kein Retain (`retain:false`), QoS = 0 → kein Risiko veralteter Nachrichten  
-
----
-
-## 📜 Lizenz
-
-**MIT License** – siehe `LICENSE`
-
----
-
-## 👏 Credits
-
-- **Autor:** Mike  
-- **AWTRIX-Projekt:** Community & Entwickler  
-- **ioBroker Adapter:** Sonos, MQTT & Javascript  
-
----
-
-## 🧾 Changelog
-
-| Version | Datum | Änderungen |
-|----------|--------|------------|
-| v0.0.1 | 2025-10-27 | Erste Veröffentlichung |
-
----