Plugin ‚yamahayxc‘ Konfiguration

plugin type logo

Im folgenden sind etwaige Anforderungen und unterstützte Hardware beschrieben. Danach folgt die Beschreibung, wie das Plugin yamahayxc konfiguriert wird. Außerdem ist im folgenden beschrieben, wie das Plugin in den Item Definitionen genutzt werden kann. [1]

Es handelt sich bei diesem Plugin um ein interface Plugin.

Beschreibung

Dieses Plugin ermöglicht, Yamaha MusicCast-Geräte in SmartHomeNG einzubinden.

Dabei ist es möglich, verschiedene Geräte aus SmartHomeNG aus anzusprechen und zu steuern, als auch über SmartHomeNG auszulesen.

Die Steuerungsmöglichkeiten umfassen unter Anderem:

  • Gerät ein-/ausschalten, Standby, Sleep-Timer

  • Wiedergabequelle auswählen (geräteabhängig, z.B. NetRadio, Radio, NetUSB, Streamingdienste)

  • Wiedergabesteuerung (Play/Pause/Stop/nächster,vorheriger Titel/Vor-,Zurückspulen)

  • Lautstärkesteuerung

  • Anwahl von Favoriten und Presets (geräteabhängig)

  • Stellen und De-/Aktivieren des Weckers (geräteabhängig)

  • Tuner-Steuerung (AM/FM): Band, Frequenz, Sendersuchlauf, Presets

  • Klangfeld/DSP (geräteabhängig): Sound Program, 3D Surround, Direct/Pure Direct, Enhancer, Klangregelung, Equalizer, Balance

  • Multiroom (MusicCast Link, geräteabhängig, Grundfunktionen an echter Mehrgeräte-Hardware getestet): Gruppen erstellen/beitreten/verlassen, Clients hinzufügen/entfernen

Die Möglichkeiten, Statusinformationen abzurufen, umfassen u.a.

  • Gerätestatus (an/aus/Standby),

  • Lautstärke, Stummschaltung,

  • aktuelle Wiedergabequelle,

  • aktueller Wiedergabestatus (Play/Pause/…),

  • aktueller Titel (quellenabhängig),

  • aktuelle Wiedergabeposition (quellenabhängig),

  • Coverbild des aktuellen Titels (quellenabhängig)

Für noch nicht implementierte Steuerungsbefehle ist ein genereller „Pass-Thru“-Befehl vorhanden, so dass beliebige Befehlssequenzen an das Gerät gesendet werden können.

Anforderungen

  • Minimum SmartHomeNG Version: 1.12

Konfiguration

Im folgenden ist beschrieben, wie das Plugin yamahayxc konfiguriert wird. Außerdem ist im folgenden beschrieben, wie das Plugin in den Item Definitionen genutzt werden kann.

Parameter

Das Plugin verfügt über folgende Parameter, die in der Datei ../etc/plugin.yaml konfiguriert werden:

cycle

Intervall in Sekunden für die periodische Erreichbarkeitsprüfung der konfigurierten Geräte (siehe Item-Attribut reachable).

  • Datentyp: int

  • Standardwert: 60

Item Attribute

Das Plugin unterstützt folgende Item Attribute, die in den Dateien im Verzeichnis ../items verwendet werden:

yamahayxc_cmd

Kommando, das dem aktuellen Item zugeordnet ist

  • Datentyp: str

yamahayxc_host

Hostname oder IP-Adresse für das Yamaha-Gerät. Gilt für alle untergeordneten Items.

  • Datentyp: str

yamahayxc_zone

Ausgewählte Zone. Gilt für alle untergeordneten Items.

  • Datentyp: str

  • Standardwert: main

Item-Structs

Das Plugin stellt die folgenden Item-Structs zur Verfügung. Diese Informationen sind aus der plugin.yaml entnommen und möglicherweise nicht vollständig.

alarm

  • alarm (foo, —)

    • alarm_on (bool, Wecker aktivieren)

    • alarm_time (str, Weckzeit als vierstelliger String, bspw. „0630“)

    • alarm_beep (bool, Wecker-Piepen aktivieren (nur, wenn Wecker aktiv))

amp

  • amp (foo, —)

basic

  • basic (foo, —)

    • wakeup (bool, —)

    • power (bool, Ein-/Ausschalter für die aktuelle Zone)

    • volume (num, Lautstärke der aktuellen Zone in Gerätewerten)

    • mute (bool, Stummschaltung)

    • input (str, Tonquelle)

    • track (str, Aktuell gespielter Track. Nur-Lese-Zugriff.)

    • albumart (str, URL zum Bild des aktuellen Albums. Nur-Lese-Zugriff.)

    • albumarturl (str, HTML-Snippet zum Bild des aktuellen Albums. Nur-Lese-Zugriff.)

    • update (bool, Alle Werte für aktuelles Gerät neu lesen.)

    • preset (num, Auswahl voreingestellter Wiedergabelisten.)

    • sleep (num, Ausschalttimer, gültige Werte 0, 30, 60, 90, 120)

    • artist (str, Interpret des aktuell gespielten Tracks. Nur-Lese-Zugriff.)

    • curtime (num, Aktuelle Spielzeit des gespielten Tracks. Nur-Lese-Zugriff.)

    • totaltime (num, Länge des aktuell gespielten Tracks. Nur-Lese-Zugriff.)

    • playback (str, Wiedergabestatus als Textausgabe.)

    • passthru (str, Item, um fertig formatierte Befehlssequenzen an das Gerät zu senden.)

    • playing (bool, Bool-Indikator, ob die Wiedergabe läuft. Nur-Lese-Zugriff.)

    • standby (bool, Bool-Indikator, ob das Gerät im Leerlauf ist. Nur-Lese-Zugriff.)

debug

Diagnose-Items, kein Teil des YXC-Protokolls.

  • debug (foo, Diagnose-Items, kein Teil des YXC-Protokolls.)

    • refresh (bool, Debug-Items neu befüllen.)

    • features (dict, Erkannte getFeatures-Fähigkeiten dieser Zone. Nur-Lese-Zugriff.)

    • dev_zone (dict, Registrierte Item-Pfade je Kommando für diese Zone. Nur-Lese-Zugriff.)

    • tuner_features (dict, Erkannte Tuner-Fähigkeiten dieses Geräts. Nur-Lese-Zugriff.)

    • dev_global (dict, Registrierte Item-Pfade je Kommando, geräteweit/netusb/Wecker. Nur-Lese-Zugriff.)

    • dev_tuner (dict, Registrierte Item-Pfade je Kommando, Tuner. Nur-Lese-Zugriff.)

    • dev_link (dict, Registrierte Item-Pfade je Kommando, Link. Nur-Lese-Zugriff.)

dsp

  • dsp (foo, —)
    • dsp (foo, —)

      • available (bool, Bool-Indikator, ob DSP-Funktionen für diese Zone verfügbar sind. Nur-Lese-Zugriff.)

dsp_content

Klangfeld/DSP-Steuerung der aktuellen Zone (geräteabhängig).

  • dsp_content (foo, Klangfeld/DSP-Steuerung der aktuellen Zone (geräteabhängig).)
    • sound_program (str, Soundprogramm, gültige Werte in .values)

      • values (list, Gültige Werte für Soundprogramm. Nur-Lese-Zugriff.)

    • surround_3d (bool, 3D-Surround-Modus aktivieren)

    • direct (bool, Direkt-Modus aktivieren)

    • pure_direct (bool, Pure-Direct-Modus aktivieren)

    • enhancer (bool, Enhancer aktivieren)

    • tone_control_mode (str, Klangregelungs-Modus, gültige Werte in .values)

      • values (list, Gültige Werte für Klangregelungs-Modus. Nur-Lese-Zugriff.)

    • tone (foo, Bass-/Höhen-/Balance-Einstellungen.)
      • bass (num, Bass-Anhebung/-Absenkung)

        • min (num, Minimaler Wert für tone.bass. Nur-Lese-Zugriff.)

        • max (num, Maximaler Wert für tone.bass. Nur-Lese-Zugriff.)

        • step (num, Schrittweite für tone.bass. Nur-Lese-Zugriff.)

      • treble (num, Höhen-Anhebung/-Absenkung)

        • min (num, Minimaler Wert für tone.treble. Nur-Lese-Zugriff.)

        • max (num, Maximaler Wert für tone.treble. Nur-Lese-Zugriff.)

        • step (num, Schrittweite für tone.treble. Nur-Lese-Zugriff.)

      • balance (num, Balance zwischen linkem/rechtem Kanal)

        • min (num, Minimaler Wert für tone.balance. Nur-Lese-Zugriff.)

        • max (num, Maximaler Wert für tone.balance. Nur-Lese-Zugriff.)

        • step (num, Schrittweite für tone.balance. Nur-Lese-Zugriff.)

    • equalizer_mode (str, Equalizer-Modus, gültige Werte in .values)

      • values (list, Gültige Werte für Equalizer-Modus. Nur-Lese-Zugriff.)

    • equalizer (foo, Equalizer-Einstellungen (tief/mittel/hoch).)
      • low (num, Equalizer tiefe Frequenzen)

        • min (num, Minimaler Wert für equalizer.low. Nur-Lese-Zugriff.)

        • max (num, Maximaler Wert für equalizer.low. Nur-Lese-Zugriff.)

        • step (num, Schrittweite für equalizer.low. Nur-Lese-Zugriff.)

      • mid (num, Equalizer mittlere Frequenzen)

        • min (num, Minimaler Wert für equalizer.mid. Nur-Lese-Zugriff.)

        • max (num, Maximaler Wert für equalizer.mid. Nur-Lese-Zugriff.)

        • step (num, Schrittweite für equalizer.mid. Nur-Lese-Zugriff.)

      • high (num, Equalizer hohe Frequenzen)

        • min (num, Minimaler Wert für equalizer.high. Nur-Lese-Zugriff.)

        • max (num, Maximaler Wert für equalizer.high. Nur-Lese-Zugriff.)

        • step (num, Schrittweite für equalizer.high. Nur-Lese-Zugriff.)

    • update (bool, Aktuelle DSP-Werte neu lesen.)

isx-18

  • isx-18 (foo, —)

legacy_alarm

  • legacy_alarm (foo, —)

media

  • media (foo, —)
    • netusb (foo, UPNP-AV, USB, Bluetooth-Status und -Steuerung)

      • track (str, Aktuell gespielter Track. Nur-Lese-Zugriff.)

      • artist (str, Interpret des aktuell gespielten Tracks. Nur-Lese-Zugriff.)

      • curtime (num, Aktuelle Spielzeit des gespielten Tracks. Nur-Lese-Zugriff.)

      • totaltime (num, Länge des aktuell gespielten Tracks. Nur-Lese-Zugriff.)

      • playback (str, Wiedergabestatus als Textausgabe.)

      • repeat (str, Wiederholmodus, gültige Werte in .available.)

      • repeat_available (list, Gültige Werte für repeat. Nur-Lese-Zugriff.)

      • shuffle (str, Zufallswiedergabe, gültige Werte in .available.)

      • shuffle_available (list, Gültige Werte für shuffle. Nur-Lese-Zugriff.)

      • queue_type (str, Art der aktuellen Wiedergabe-Warteschlange (beobachteter Wert z.B. „user“).

Laut Spezifikation als „Reserved“ markiert, wird vom Gerät aber tatsächlich befüllt. Nur-Lese-Zugriff.)

  • playing (bool, Bool-Indikator, ob die Wiedergabe läuft. Nur-Lese-Zugriff.)

  • albumart (str, URL zum Bild des aktuellen Albums. Nur-Lese-Zugriff.)

  • albumarturl (str, HTML-Snippet zum Bild des aktuellen Albums. Nur-Lese-Zugriff.)

  • preset (num, Auswahl voreingestellter Wiedergabelisten.)

  • standby (bool, Bool-Indikator, ob das Gerät im Leerlauf ist. Nur-Lese-Zugriff.)

  • update (bool, Aktuelle Werte für netusb neu lesen.)

  • browse (foo, UPnP/USB/DLNA-Inhalte durchsuchen (getListInfo/setListControl). Geräteweit

geteilte Navigationsposition - nicht pro Client/Zone getrennt, kann sich also mit der offiziellen MusicCast App oder einer zweiten Visu-Sitzung überschneiden. Zielzone für .play ist vorerst immer „main“. play_now/play_next/queue_add/ playlist_bank/playlist_add (manageList) sind nicht Teil der offiziellen YXC-Spezifikation - deren type-Werte wurden per Netzwerkmitschnitt der echten MusicCast-iOS-App aus dem „…“-Kontextmenü rekonstruiert, nicht aus dem Dokument.)

  • list (list, Aktuelle Seite der Liste (bis zu 8 Einträge). Nur-Lese-Zugriff.)

  • menu_name (str, Name der aktuellen Ebene/des aktuellen Ordners. Nur-Lese-Zugriff.)

  • menu_layer (num, Tiefe der aktuellen Ebene (0 = Wurzel). Nur-Lese-Zugriff.)

  • max_line (num, Gesamtanzahl der Einträge auf dieser Ebene. Nur-Lese-Zugriff.)

  • index (num, Offset der aktuell angezeigten Seite (Vielfaches von 8). Nur-Lese-Zugriff.)

  • playing_index (num, Index des aktuell wiedergegebenen Eintrags in dieser Liste, -1 falls keiner. Nur-Lese-Zugriff.)

  • busy (bool, True während ein getListInfo-Abruf läuft (bis zu 30s laut Spezifikation). Nur-Lese-Zugriff.)

  • page (num, Schreiben fordert die Seite ab diesem Offset an (wird intern auf ein

Vielfaches von 8 abgerundet).)

  • select (num, Schreiben des absoluten Index (browse.index + Position in browse.list)

eines Eintrags steigt eine Ebene tiefer in diesen Eintrag ein, sofern per .attribute als auswählbar markiert.)

  • play (num, Schreiben des absoluten Index eines Eintrags spielt ihn ab (Zone „main“),

sofern per .attribute als abspielbar markiert.)

  • return (bool, True schreiben, um eine Ebene nach oben zu wechseln.)

  • play_now (num, Schreiben des absoluten Index eines Eintrags spielt ihn sofort ab (unterbricht

die aktuelle Wiedergabe), unabhängig vom Layer/Auswahlstatus. Nicht Teil der offiziellen YXC-Spezifikation, per Mitschnitt der echten MusicCast-App aus dem „…“-Kontextmenü rekonstruiert (siehe Hinweis oben im Beschreibungstext).)

  • play_next (num, Schreiben des absoluten Index eines Eintrags reiht ihn direkt nach dem

aktuellen Titel ein. Siehe play_now.)

  • queue_add (num, Schreiben des absoluten Index eines Eintrags hängt ihn ans Ende der

Wiedergabe-Warteschlange an. Siehe play_now.)

  • playlist_bank (num, Auswahl einer der (bis zu 5) benannten MusicCast-Playlisten für playlist_add

(1-5, gerätespezifisch). Muss vor playlist_add mindestens einmal gesetzt werden - rein lokal gemerkt, löst selbst keine Geräteanfrage aus.)

  • playlist_add (num, Schreiben des absoluten Index eines Eintrags fügt ihn der über playlist_bank

gewählten Playliste hinzu. Siehe play_now.)

  • playlist_names (list, Namen der bis zu 5 benannten MusicCast-Playlisten (Index 0 = Bank 1, …).

Wird nicht automatisch aktualisiert (ändert sich selten) - Aktualisierung nach playlist_rename sowie über media.netusb.update. Nur-Lese-Zugriff.)

  • playlist_rename (str, Schreiben eines Textes benennt die über playlist_bank gewählte Playliste um.)

  • playlist_clear (bool, True schreiben, um die über playlist_bank gewählte Playliste zu leeren

(Name bleibt erhalten).)

  • queue (foo, Wiedergabe-Warteschlange (getPlayQueue/managePlayQueue/copyPlayQueue/

clearPlayQueue). Eigener, von browse getrennter Index-Raum - queue.play/ queue.delete beziehen sich auf die Position in queue.list, nicht in browse.list. Nicht Teil der offiziellen YXC-Spezifikation, nicht einmal als „Reserved“ erwähnt - per Netzwerkmitschnitt der echten MusicCast-iOS-App rekonstruiert.)

  • list (list, Aktuelle Warteschlange (alle Einträge, keine Seitenweise-Abfrage wie bei

browse.list beobachtet). Nur-Lese-Zugriff.)

  • max_line (num, Gesamtanzahl der Einträge in der Warteschlange. Nur-Lese-Zugriff.)

  • playing_index (num, Index des aktuell wiedergegebenen Eintrags in der Warteschlange. Nur-Lese-Zugriff.)

  • play (num, Schreiben des absoluten Index eines Warteschlangen-Eintrags springt dorthin

und spielt ihn ab (Zone „main“).)

  • delete (num, Schreiben des absoluten Index eines Warteschlangen-Eintrags entfernt ihn

aus der Warteschlange. Heißt „delete“ statt „remove“, da „remove“ mit Item.remove() kollidiert (siehe check_item_name_collision).)

  • save_playlist (bool, True schreiben, um die gesamte aktuelle Warteschlange als über

browse.playlist_bank gewählte MusicCast-Playliste zu speichern (dieselbe Bank-Auswahl wie browse.playlist_add, aber ganze Warteschlange statt einzelnem Eintrag).)

  • clear (bool, True schreiben, um die Warteschlange zu leeren.)

  • update (bool, True schreiben, um die Warteschlange neu abzufragen.)

  • tuner (foo, Tuner-Steuerung (AM/FM))
    • band (str, AM/FM/DAB, je nach Gerät. RDS ist kein eigenes Band, sondern Zusatzinfo im FM-Betrieb.)

      • values (list, Gültige Werte für Band. Nur-Lese-Zugriff.)

    • freq (num, Sendefrequenz für das aktuell gewählte Band, Grenzen in .min/.max/.step)

      • min (num, Minimaler Frequenzwert für das aktuell gewählte Band. Nur-Lese-Zugriff.)

      • max (num, Maximaler Frequenzwert für das aktuell gewählte Band. Nur-Lese-Zugriff.)

      • step (num, Schrittweite für Frequenzwert für das aktuell gewählte Band. Nur-Lese-Zugriff.)

    • seek (str, Sendersuchlauf, gültige Werte „up“/“down“/“cancel“/“auto_up“/“auto_down“/“tp_up“/“tp_down“ (RDS))

    • tuned (bool, Bool-Indikator, ob ein Sender empfangen wird. Nur-Lese-Zugriff.)

    • station (str, Empfangener Sendername (RDS Program Service). Nur-Lese-Zugriff.)

    • preset (num, Anwahl gespeicherter Tuner-Presets.)

    • preset_store (num, Aktuellen Sender auf Preset-Nummer speichern.)

    • preset_clear (num, Preset-Nummer löschen.)

    • preset_switch (str, Zum nächsten/vorherigen Preset wechseln, gültige Werte „next“/“previous“)

    • update (bool, Aktuelle Werte für Tuner neu lesen.)

  • link (foo, Multiroom (MusicCast Link) Gruppen-Status und -Steuerung.)

    • linked (bool, Bool-Indikator, ob das Gerät aktuell in einer Link-Gruppe ist. Nur-Lese-Zugriff.)

    • role (str, Rolle in der Link-Gruppe („server“/“client“/“none“). Nur-Lese-Zugriff.)

    • available_devices (list, Für Link konfigurierte Hosts, als Auswahl für client.join/server.add_device. Nur-Lese-Zugriff.)

    • server (foo, Aktionen/Status in der Rolle als Gruppen-Server.)

      • linked_devices (list, IP-Adressen der Gruppen-Clients (nur als Server verfügbar). Nur-Lese-Zugriff.)

      • add_device (str, Host/IP als Client zur Gruppe hinzufügen.)

      • remove_device (str, Host/IP aus der Gruppe entfernen.)

      • disband (bool, Gruppe auflösen (Serverrolle beenden).)

    • client (foo, Aktionen in der Rolle als Gruppen-Client.)

      • join (str, Als Client dem Server mit dem/der angegebenen Host/IP beitreten.)

      • leave (bool, Gruppe als Client verlassen.)

    • options (foo, Selten benötigte Optionen/Informationen zum Link.)

      • group_id (str, Link-Gruppen-ID des Geräts. Nur-Lese-Zugriff.)

      • group_name (str, Name der Link-Gruppe. Nur-Lese-Zugriff.)

      • server_zone (str, Zone des Gruppen-Servers. Nur-Lese-Zugriff.)

      • audio_dropout (bool, Bool-Indikator für Audio-Aussetzer in der Link-Gruppe. Nur-Lese-Zugriff.)

    • update (bool, Aktuelle Werte für Link neu lesen.)

netusb

  • netusb (foo, —)

    • netusb (foo, —)

rx-v483

  • rx-v483 (foo, —)

    • dsp (foo, —)

tuner

  • tuner (foo, —)

    • tuner (foo, —)

wx-010

  • wx-010 (foo, —)

zone2

  • zone2 (foo, —)

    • available (bool, Bool-Indikator, ob Zone 2 an diesem Gerät verfügbar ist. Nur-Lese-Zugriff.)

zone3

  • zone3 (foo, —)

    • available (bool, Bool-Indikator, ob Zone 3 an diesem Gerät verfügbar ist. Nur-Lese-Zugriff.)

zone4

  • zone4 (foo, —)

    • available (bool, Bool-Indikator, ob Zone 4 an diesem Gerät verfügbar ist. Nur-Lese-Zugriff.)

zone_amp

  • zone_amp (foo, —)

    • power (bool, Ein-/Ausschalter für die aktuelle Zone)

    • reachable (bool, Bool-Indikator, ob das Gerät aktuell erreichbar ist (geräteweit, nicht zonenspezifisch,

siehe Plugin-Parameter „cycle“). Bei Nichterreichbarkeit behalten alle anderen Items ihren letzten bekannten Wert (kein automatisches Zurücksetzen). Nur-Lese-Zugriff.)

  • last_seen (num, Zeitpunkt des letzten erfolgreichen Kontakts zum Gerät (Unix-Timestamp, geräteweit).

Nur-Lese-Zugriff.)
  • volume (num, Lautstärke der aktuellen Zone in Prozent)

    • min (num, Minimaler Lautstärkewert für volume.raw. Nur-Lese-Zugriff.)

    • max (num, Maximaler Lautstärkewert für volume.raw. Nur-Lese-Zugriff.)

    • step (num, Schrittweite für Lautstärkewert für volume.raw. Nur-Lese-Zugriff.)

    • raw (num, Lautstärke der aktuellen Zone in Gerätewerten)

  • mute (bool, Stummschaltung)

  • sleep (num, Ausschalttimer, gültige Werte 0, 30, 60, 90, 120)

  • input (str, Tonquelle, gültige Werte in .values)

    • values (list, Gültige Werte für Tonquelle. Nur-Lese-Zugriff.)

  • update (bool, Alle Werte für aktuelles Gerät neu lesen.)

  • passthru (str, Item, um fertig formatierte Befehlssequenzen an das Gerät zu senden.)

zones

  • zones (foo, —)

    • zone2 (foo, Zone 2)

    • zone3 (foo, Zone 3)

    • zone4 (foo, Zone 4)

Logik Parameter

Das Plugin verfügt über folgende Parameter, die in der Datei ../etc/logic.yaml konfiguriert werden:

Keine Logik Parameter in den Metadaten beschrieben - Bitte in der README nachsehen (siehe Fußnote)

Plugin Functions

Das Plugin verfügt über folgende öffentliche Funktionen, die z.B. in Logiken aufgerufen werden können.

Keine