DevelopmentGuidelinesAV

Aus FHEMWiki

Einleitung

Auf dieser Seite sollen Richtlinien für AV-Module gesammelt werden damit es einfacher wird diese zusammen mit anderen Modulen wie remotecontroll oder LightScene zu verwenden. Auch Benachrichtigungen wie Sprachdurchsagen oder Einblendungen lassen sich universeller verwenden wenn sie bei allen Geräten die dies unterstützen gleich angesprochen werden.

Der Text aus dem ursprünglichen Forumsthread war folgender:


gerade ist ja mit den tv und verstärker modulen sowie dem remotecontrol modul ziemlich schwung in den bereich audio und video geräte gekommen. zusätzlich gibt es noch eine ganze reihe älterer module wie sonor und xbmc und zwei arten itunes anzusprechen und neue module wie für die web radios oder das raspberry multiroom stehen vor der tür.
wie wäre es sich rechtzeitig auf ein möglichst einheitiches kommando set zu verständigen damit grundlegende dinge wie play/pause/volume/next bei allen geräten einheitlich, in gleicher schreibweise und mit möglichst ähnlichen parametern funktionieren?
das würde module wie die remotecontrol aber auch structure und lightscene deutlich einfacher und nützlicher machen und auch alternative frontends erleichtern wenn bestimmte features wie audio,video oder cover über ein einheitliches schema markiert würden.
mein vorschlag wäre sich an das sonos modul anzulehnen weil es mir in dieser hinsicht am fortgeschrittensten erscheint und auch weitergehende features wie cover oder durchsagen anbietet.
zu vereinheitlichen wäre dann u.a.:
- welche kommandos zu welchem zweck
- kommandos sollten einheitlich geschrieben werden. also z.b. immer klein oder immer mixed case.
- parameter sollten so weit möglich den gleichen wertebereich haben. also z.b. volume immer von 0-100.
- wenn es aus irgendeinem grund noch ein gerätespezifischer wertebereich nötig ist sollte der zusätzlich vorhanden sein.
- cover sollten immer auf die gleiche art gelesen werden können
- ...


Der Thread ist hier zu finden.

Bezeichner

siehe Bezeichnungen allgmein

Kommandos

Diese Tabelle soll eine einheitliche Definition von set-Befehlen aufzeigen. Dazu zählen auch ggf. Parameter und deren Bedeutung.

Name Parameter Bedeutung
on Schaltet das Gerät ein, so dass es benutzt werden kann.
off Schaltet das Gerät aus.
play Startet das Abspielen von Medien (Video, mp3, Radio stream etc.)
pause Pausiert das Abspielen von Medien, stoppt es aber nicht.
stop Stoppt (beendet) das Abspielen von Medien.
volume 0 - 100 Setzt die Lautstärke auf einen prozentualen Wert.
volumeStraight X-Y Setzt die Lautstärke auf den absoluten Wert, so wie er vom Gerät tatsächlich verwendet wird (z.B. dB)

Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.
volumeUp [0 - 100] Erhöht die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Inkrement als optionaler Parameter mit angegeben werden.
volumeDown [0 - 100] Verringert die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Dekrement als optionaler Parameter mit angegeben werden.
mute on | off | toggle Aktiviert, deaktiviert oder schaltet die Mutefunktion = Lautstärke der aktuellen Ausgabe wird verringert bzw. abgschaltet (Gerätespezifisch)
repeat one | all | off Aktivieren der Repeatfunktion = wiederholen des aktuellen Titels/Albums
shuffle on | off Aktiviert oder deaktiviert die Shufflefunktion = zufällige Wiedergabe.
channel 0 - 9999 Schaltet auf einen absoluten Sender- oder Programmspeicherplatz (Nicht zu verwechseln mit input)
channelUp Springt zum nächsten Sender- oder Programmspeicherplatz.
channelDown Springt zum vorherigen Sender- oder Programmspeicherplatz.
remoteControl # Parameter ist Hersteller- und Gerätespezifisch. Funktion bei Geräten, die es erlauben die mitgelieferte Hardware Fernbedienung zu simulieren. Parameter in lowerCamelCaps (ggf. muss im Modul selber auf die Herstellerspezifische Schreibweise umcodiert werden; Alles groß- oder klein geschrieben)
input z.B. hdmi[1-n] | av[1-n] | usb | airplay | server [1-n] Auswahl von Hardwarekanälen (HDMI, DVB-S, PAL, DVI) oder Softwarekanälen (Airplay, IPTV, IP-Radiostream) die das zu steuernde Gerät aktiv schalten soll (zur Darstellung auf TV, Kanalwahl bei AV-Receivern etc.). Da diese Kanäle je nach Gerät und Modellreihen unterschiedliche Bezeichnungen besitzen, sollten alle möglichen Bezeichnungen in Form von lowerCamelCaps angeboten werden.
output z.B. Airtunes1,Airtunes2,Intern Auswahl des/der Ausgabegerätes.
statusRequest Den aktuellen Status des Gerätes abfragen
...

Readings

Diese Tabelle soll eine einheitliche Wertedefinition von Readings. Dazu zählen auch die verwendeten Werte und deren Bedeutung.

Wenn es zwischen reading und zugehörigen set eine 1:1 Beziehung gibt sollte sich der Inhalt des readings als Argument des set verwenden lassen um genau diesen dargestellten Zustand zu erreichen.

Name mögliche Werte Bedeutung
power on|off Ist das Gerät an oder aus?
presence present|absent Ist das Gerät aktuell ansprechbar? Sollte das Gerät aufgrund abgeschalteten Stromzufuhr, o.ä. aktuell nicht steuerbar sein, so sollte dies mit dem Wert "absent" verdeutlicht werden. In solch einem Fall sollte ein set-Befehl eine entsprechende Fehlermeldung bringen. Evtl. StatusUpdate-Timer sollten ensprechende Fehlermeldungen nur einmal im Log, etc. festhalten und Fehlermeldungen beim nächsten Status-Update entsprechend unterdrücken um so die Logfiles nicht unnötig vollzuschreiben. Auch das presence reading sollte nur dann aktualisiert werden wenn sich der Status geändert hat um am timestamp sehen zu können wann das war. event-on-change-reading ist hierzu nicht ausreichend weil nur das Event unterdrückt wird der Timestamp sich aber trotzdem ändert.
volume 0-100 Der prozentuale Lautstärkepegel gemessen der maximal möglichen tatsächlichen Werte.
volumeStraight X-Y Der tatsächliche Lautstärkepegel des Gerätes, so wie er am Gerät angezeigt/verwendet wird.

Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.
mute on | off Ist das Gerät aktuell stumm geschaltet?
repeat one | all | off Ist das Gerät im repeat modus?
shuffle on | off Ist das Gerät im shuffle modus?
input aktuell gewählter Eingangskanal
output aktuell gewählte(s) Ausgabegerät(e)
channel aktuell gewählter Eingangskanal entsprechend dem Gerät
currentArtist aktueller Interpret
currentAlbum aktuelles Album
currentTitle aktueller Titelname
currentMedia "Name" der Wiedergabe"datei" kann alles sein: Datei vom Filesystem, Stream aus dem Internet, m3u-URL oder was auch immer
playStatus playing | paused | stopped
state on | off | absent Sofern das Gerät empfangsbereit ist, soll der Schaltzustand des Gerätes (Reading: power, sofern anwendbar) zurückgegeben werden. Ansonsten ist die Abwesenheit des Gerätes durch den Wert "absent" anzuzeigen.
stateAV <presence> | <power> | <mute> | <playStatus> Kombiniert den Status von bestehenden Readings zu einer logisch abhängigen Einheit nach folgendem Format: Wenn presence=absent=>absent, sonst power=off=>off, sonst mute=on=>muted, sonst playStatus!=stopped=>playStatus, sonst =>power
...

Implementation in Modulen

yes = Implementiert yes2 = device spezifisch build = Implementation geplant/in Arbeit no = Nicht implementiert/Keine Implementation geplant

set-Befehl LGTV LISTENLIVE STV VIERA YAMAHA_AVR iTunes ENIGMA2 ONKYO_AVR Squeezebox PHTV PIONEER harmony plex
on
no
yes
no
yes
yes
yes
yes
yes
yes2
off
yes
yes
no
yes
yes
yes
yes
yes
yes2
play
no
yes
yes
yes
yes
yes
yes
yes
yes2
yes
pause
no
yes
yes
yes
yes
yes
yes
yes
yes2
yes
stop
no
yes
no
yes
yes
yes
yes
yes
yes2
yes
volume
yes
yes
yes
yes
yes
yes
yes
yes
yes
no
yes
volumeStraight
no
yes
no
no
build
yes
yes
yes
no
no
volumeUp
yes
yes
build
yes
yes
yes
yes
yes
yes2
no
volumeDown
yes
yes
build
yes
yes
yes
yes
yes
yes2
no
mute
yes
yes
yes
yes
yes
yes
yes
yes
yes
yes2
no
repeat
no
yes
yes
no
yes2
yes
no
yes2
yes2
yes
shuffle
no
yes
yes
no
yes2
yes
no
yes2
yes2
yes
channel
yes
no
no
yes
yes
no
yes
yes
yes2
no
channelUp
yes
no
no
yes
yes
yes
yes
yes
yes2
no
channelDown
yes
no
no
yes
yes
yes
yes
yes
yes2
no
remoteControl
yes
yes
yes
yes
yes
no
yes
yes2
yes2
no
input
yes
no
yes
no
yes
yes
no
yes
yes
yes2
no
output
no
no
yes
no
no
no
no
no
yes2
no
statusRequest
yes
yes
yes
build
yes
yes
yes
yes
yes
no
no
Reading LGTV LISTENLIVE STV VIERA YAMAHA_AVR iTunes ENIGMA2 ONKYO_AVR Squeezebox PHTV PIONEER harmony
power
yes
yes
build
yes
yes
yes
yes
yes
yes
presence
yes
yes
build
yes
yes
yes
yes
yes
no
yes
volume
yes
yes
yes
yes
yes
yes
yes
yes
no
yes
volumeStraight
no
yes
no
no
build
yes
yes
yes
no
no
mute
yes
yes
yes
yes
yes
yes
yes
yes
no
build
repeat
no
no
yes
no
yes2
yes
no
no
no
build
shuffle
no
no
yes
no
yes2
yes
no
no
no
build
input
no
yes
no
yes
yes
no
yes
yes
no
no
output
no
no
yes
no
no
no
no
no
no
no
channel
yes
no
no
yes
yes
yes
yes
yes
no
no
currentArtist
no
yes
yes
no
yes
yes
no
yes
no
yes
currentAlbum
no
yes
yes
no
yes
yes
no
yes
no
yes
currentTitle
no
yes
yes
yes
yes
yes
no
yes
no
yes
currentMedia
no
no
build
yes
build
yes
yes
no
no
playStatus
no
yes
yes
build
yes2
yes
no
no
no
state
yes
yes
yes
yes
yes2
yes
yes
yes
no
yes
stateAV
no
no
no
yes
yes
no
yes
no
no
no

Sonstiges

Wie funktioniert Cover Art?

Reading mit URL-Link oder als Gerätestatus???

Wie funktionieren Sprachdurchsagen oder Text Einblendungen?

Obwohl dies sehr stark davon abhängt, ob das jeweilige Gerät eine solche Funktion unterstützt, oder ob sie anderweitig (z.B. durch Google Service) umgesetzt werden können, so sollen dennoch solche Features über die folgenden Set-Kommandos angeboten werden.

Kommando Beispiel Beschreibung
sayText 
set ''<device>'' sayText "Anruf in Abwesenheit"
 Dieses Kommando soll den übergebenen Text auf dem jeweiligen Device in Audio-Form wieder ausgeben. Hierbei kann auf einen Synthese-Anbieter im Internet zurückgegriffen werden, der ein solches Audiosample erzeugt, oder geräteinterne Kommandos verwendet werden, je nach dem was vorhanden und unterstützt wird.
showText 
set ''<device>'' showText "Anruf in Abwesenheit"
 Dieses Kommando soll einen Text z.B. auf dem Display des Gerätes (oder Fernseher) in geeigneter Form anzeigen, sofern das Gerät eine solche Funktion unterstützt.
Alternativvorschlag
message 
set ''<device>'' message "Anruf in Abwesenheit" [audio|video]
 Dieses Kommando soll eine Nachricht mit dem Gerät anzeigen (video) oder abspielen (audio), sofern das Gerät eine solche Funktion unterstützt. Ohne die optionale Wiedergabe-Art oder wenn die angegebene nicht unterstützt ist über die von diesem Gerät bevorzugte Methode.

Wie funktionieren Playlisten?

Sofern anwendbar, sollten diese mit dem Kommando set <device> playlist XY aufrufbar sein. Dabei sollten die zur Verfügung stehenden Playlists bereits bekannt sein und als möglicher Kommando-Parameter angeboten werden.

Wie funktionieren Zonen?

Jede einzelne Zone eines Gerätes wird durch ein eigenes FHEM-Device repräsentiert. Die gewünschte Zone ist als optionaler Parameter in den Definitions-Argumenten zu übergeben.

Wenn keine bestimmte Zone explizit in der Definition übergeben wird, ist die Hauptzone (Main-Zone) zu verwenden. Die zur Verfügung stehenden Zonen sollten in den Internals aufgelistet sein, mindestens jedoch in der commandref des entsprechenden Moduls.

Jede Definition sollte nur die tatsächlich möglichen Befehle, Eingänge, etc. der entsprechenden Zone anbieten.

Abgerufen von „http://wiki.fhem.de/w/index.php?title=DevelopmentGuidelinesAV&oldid=16224“