From cbbb4b7914e54e330ba534e34a26c1e065e3fd0b Mon Sep 17 00:00:00 2001 From: mike Date: Mon, 27 Oct 2025 12:32:45 +0100 Subject: [PATCH] Update README.md --- README.md | 201 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 200 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3025048..5dd602d 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,201 @@ -# public-scripts +# 🎵 AWTRIX NowPlaying – Sonos → AWTRIX Custom App (ioBroker) +Zeigt den aktuell laufenden Song von **Sonos** als eigene **AWTRIX Custom-App** 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. + +--- + +## 🚀 Features + +- Liest **Titel / Artist / Album** aus Sonos-Datenpunkten +- Baut automatisch die Anzeige: `🎵 Künstler — Titel (Album)` +- **Keep-Alive**: hält die App aktiv, solange ein Titel vorhanden ist +- Automatisches **Entfernen** der App, sobald keine Titelinfos mehr da sind +- Optionales **FORCE_SWITCH**: bei jedem Refresh auf die App umschalten +- **Debounce-Logik** (200 ms) gegen Flattern bei Trackwechseln + +--- + +## 🧩 Voraussetzungen + +- **ioBroker** mit: + - 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) + +--- + +## ⚙️ Installation + +1. In ioBroker den **Javascript-Adapter** öffnen → neues Script `NowPlaying Sonos → AWTRIX` anlegen +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. + +--- + +## 🔧 Konfiguration + +| Variable | Typ | Standardwert | Beschreibung | +|--------------------|---------|---------------|--------------| +| `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. + +--- + +## 🧠 Funktionsweise + +1. **Trigger:** + ```js + on({ id: [DP.title, DP.artist, DP.album], change: "ne" }, scheduleUpdate); + ``` + Bei Änderung wird `updateAwtrix()` mit Debounce (200 ms) aufgerufen. + +2. **Logik:** + - 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:** + Alle `KEEPALIVE_SEC` Sekunden wird `publishCustom()` aufgerufen. + Sobald kein Titel mehr vorhanden ist → App wird automatisch entfernt. + +--- + +## 📡 MQTT-Themen & Payloads + +### Custom-App veröffentlichen +**Topic:** +``` +/custom/ +``` + +**Payload:** +```json +{ + "name": "NowPlaying", + "text": "🎵 Artist — Title (Album)", + "icon": 29944, + "color": [255, 255, 255], + "textCase": 2, + "lifetime": 600 +} +``` + +--- + +### Auf App umschalten (optional) +**Topic:** +``` +/switch +``` + +**Payload:** +```json +{ "name": "NowPlaying" } +``` + +--- + +### App entfernen +**Topic:** +``` +/custom/ +``` + +**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 | +|----------|--------|------------| +| v1.0.0 | 2025-10-27 | Erste Veröffentlichung | + +---