Philips Hue Tap Dial Switch (RDM002) — Blueprint für Home Assistant

Blueprint für den Philips Hue Tap Dial Switch (RDM002) über ZHA. Der Drehregler steuert wahlweise Licht-Helligkeit, Speaker-Lautstärke oder beides gleichzeitig. Die vier Tasten sind frei mit eigenen Aktionen belegbar.

---

Varianten

Datei	Blueprint-Name in HA	Zweck
blueprints/automation/philips_tap_dial/philips_tap_dial_switch.yaml	Philips Tap Dial Switch (Licht & Speaker)	Aktuelle Variante — Dial für Licht und/oder Media-Player
blueprints/automation/philips_tap_dial/legacy/philips_tap_dial_switch_light_only.yaml	Philips Tap Dial Switch (nur Licht, Original)	Unveränderter Ursprungs-Blueprint, damit bestehende Automationen weiterlaufen

Beide haben unterschiedliche Namen und erscheinen in HA getrennt in der Blueprint-Liste.

---

Installation

1. Repo klonen oder ZIP entpacken.
2. Die YAML-Datei(en) nach <config>/blueprints/automation/philips_tap_dial/ kopieren (Ordner ggf. anlegen).
3. Entwicklerwerkzeuge → YAML → Automationen neu laden (oder HA neu starten).
4. Einstellungen → Automationen & Szenen → Blueprints → Blueprint auswählen → Automation erstellen.

Alternativ per Import-URL (nach dem Push auf GitHub, GITHUB_USER ersetzen):

https://github.com/GITHUB_USER/ha-philips-tap-dial/blob/main/blueprints/automation/philips_tap_dial/philips_tap_dial_switch.yaml

---

Konfiguration

Drehregler (Dial)

Eingabe	Beschreibung
Ziel des Drehreglers	Nur Licht · Nur Speaker · Licht und Speaker gleichzeitig
Dimmbare Lampe(n)	Target-Selector (Entity / Gerät / Bereich / Label)
Speaker / Media-Player	Target-Selector (Entity / Gerät / Bereich / Label) — wird zur Laufzeit auf media_player.* aufgelöst

Feinabstimmung

Eingabe	Default	Beschreibung
Übergangszeit Licht	1 s	Weiche Helligkeitsänderung
Lautstärke-Faktor	0.5	Multiplikator auf die Dial-Schrittweite
Minimale Lautstärke	0 %	Untergrenze
Maximale Lautstärke	80 %	Obergrenze (Gehörschutz)

Tasten

Taste 1–4: beliebige Aktionsblöcke (Szene, Skript, media_player.media_play_pause, media_player.media_next_track, …).

---

Wie die Lautstärke berechnet wird

Der Dial sendet je nach Drehgeschwindigkeit eine variable Schrittweite (step_size, typisch 10–70). Im Original wird dieser Wert 1:1 als brightness_step_pct verwendet — für Lautstärke wäre das viel zu grob (ein schneller Dreh würde von 20 % auf 90 % springen).

Deshalb:

neue_lautstärke = clamp(
    aktuelle_lautstärke + (step_size × Lautstärke-Faktor / 100),
    Minimale Lautstärke,
    Maximale Lautstärke
)

Beispiel: step_size = 20, Faktor 0.5 → +10 % Lautstärke. Langsam drehen → kleine step_size → feine Schritte. Schnell drehen → große step_size → grobe Schritte.

Null-Guard: Media-Player im Zustand unavailable/unknown werden übersprungen — es wird nie ein float() auf einen ungültigen Zustand angewendet (sonst würde die Lautstärke stillschweigend auf 0 fallen und beim nächsten Dreh von 0 aus hochlaufen).

Fähigkeits-Guard über supported_features:

Fähigkeit	Bit	Verhalten
VOLUME_SET	4	media_player.volume_set mit exaktem, begrenztem Wert
nur VOLUME_STEP	1024	Fallback auf media_player.volume_up / volume_down (TV, AVR)
keins von beiden	—	Player wird übersprungen

---

Ziel-Auswahl der Speaker (Target-Selector)

Die Speaker werden genau wie die Lampen ausgewählt: Entity, Gerät, Bereich oder Label.

Unterschied unter der Haube: Das Licht-Target kann direkt an light.turn_on durchgereicht werden. Bei Speakern brauche ich die konkreten Entity-IDs, weil pro Player der aktuelle volume_level gelesen und daraus der neue Wert berechnet wird. Der Blueprint löst das Target deshalb zur Laufzeit auf:

• entity_id → direkt (Selector liefert je nach Auswahl String oder Liste → wird normalisiert)
• device_id → device_entities()
• area_id → area_entities()
• label_id → label_entities() + label_devices() + label_areas()
• danach Filter auf Domain media_player und unique (keine Dubletten bei Überschneidungen)

Praktisch daran: Ein Label „Speaker" vergeben → neue Player werden automatisch mitgesteuert, ohne den Blueprint anzufassen. Ein Bereich zieht sinnvollerweise nur die media_player aus dem Raum, Lichter/Sensoren werden herausgefiltert. Ein TV im selben Bereich landet aber ebenfalls mit drin — falls das nicht gewollt ist, lieber Label oder Entities direkt wählen.

Der Aufbau nutzt das namespace()-Pattern, da list.append() in der HA-Jinja-Sandbox gesperrt ist.

---

Event-Mapping (ZHA, RDM002)

Aktion	command	Relevante Daten
Dial rechts	step_with_on_off	params.step_mode = StepMode.Up, params.step_size
Dial links	step_with_on_off	params.step_mode = StepMode.Down, params.step_size
Taste 1	recall	scene_id = 1
Taste 2	recall	scene_id = 0
Taste 3	recall	scene_id = 5
Taste 4	recall	scene_id = 4

Der Blueprint liest die Scene primär aus params.scene_id und fällt auf args[1] zurück (ältere ZHA-Versionen).

Eigene Events prüfen: Entwicklerwerkzeuge → Ereignisse → auf zha_event lauschen und am Gerät drehen/drücken.

---

Ausführungsmodus

mode: queued (max. 25) statt restart. Beim Drehen feuert das Gerät mehrere Events schnell hintereinander. Mit restart würde ein laufender Lauf abgebrochen, bevor die Lautstärke gesetzt ist — Schritte gingen verloren. queued arbeitet jeden Dial-Schritt sauber ab; jeder Lauf liest den aktuellen volume_level direkt vor dem Setzen.

---

Beispiele

Siehe examples/example_automation.yaml.

---

Troubleshooting

Symptom	Ursache / Lösung
Blueprint erscheint nicht	Falscher Pfad, oder Automationen nicht neu geladen
Gerät nicht im Selector wählbar	Nur ZHA-Geräte mit Hersteller Signify Netherlands B.V. / Modell RDM002 werden angeboten
Dial tut nichts	zha_event in Entwicklerwerkzeuge → Ereignisse prüfen; device_id muss zum gewählten Gerät passen
Lautstärke springt zu stark	Lautstärke-Faktor verkleinern (z. B. 0.2)
Lautstärke ändert sich gar nicht	Player liefert kein volume_level → Fallback volume_up/volume_down greift nur bei verfügbarem Player
Tasten lösen nichts aus	Scene-IDs prüfen (1/0/5/4) — Firmware-abhängig

---

Credits

Basiert auf dem Blueprint von nnmalex/ha-blueprints, erweitert um Media-Player-Steuerung, Grenzwerte, Null-Guards und Queued-Mode.

Lizenz

MIT — siehe LICENSE.