FHEMWiki - Benutzerbeiträge [de]

DevelopmentGuidelinesAV

2014-02-11T09:07:09Z

Fhemrocks: /* Implementation in Modulen */

== 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 [http://forum.fhem.de/index.php?t=msg&th=13784&start=0&rid=430 hier] zu finden.

== Bezeichner ==
siehe [[DevelopmentGuidelines#Bezeichnungen|Bezeichnungen allgmein]]

== Kommandos ==

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

{| class="wikitable"
|-
! 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''' || <nowiki>on | off | toggle</nowiki> || Aktiviert, deaktiviert oder schaltet die Mutefunktion = Lautstärke der aktuellen Ausgabe wird verringert bzw. abgschaltet (Gerätespezifisch)
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Aktivieren der Repeatfunktion = wiederholen des aktuellen Titels/Albums
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || 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''' || <nowiki>z.B. hdmi[1-n] | av[1-n] | usb | airplay | server [1-n]</nowiki> || 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''' || <nowiki>z.B. Airtunes1,Airtunes2,Intern</nowiki> || Auswahl des/der Ausgabegerätes.
|-
| '''statusRequest''' || || Den aktuellen Status des Gerätes abfragen
|-
|colspan="3"| ...
|}

== 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.

{| class="wikitable"
|-
! Name !! mögliche Werte !! Bedeutung
|-
| '''power''' || <nowiki>on|off</nowiki> || Ist das Gerät an oder aus?
|-
| '''presence''' || <nowiki>present|absent</nowiki> || 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''' || <nowiki>on | off</nowiki> || Ist das Gerät aktuell stumm geschaltet?
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Ist das Gerät im repeat modus?
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || 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''' || <nowiki>playing | paused | stopped</nowiki> ||
|-
| '''state''' || <nowiki>on | off | absent</nowiki> || 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.
|-
|colspan="3"| ...
|}

== Implementation in Modulen ==
{{yes}} = Implementiert {{planed}} = Implementation geplant/in Arbeit {{no}} = Nicht implementiert/Keine Implementation geplant

{| class="wikitable"
! set-Befehl !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox
|-
| '''on''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''off''' || || || || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''play''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''pause''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''stop''' || || || || {{no-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''volume''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{yes-c}}
|-
| '''volumeUp''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''volumeDown''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''mute''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{no-c}}
|-
| '''channelUp''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''channelDown''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''remoteControl''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}}
|-
| '''input''' || {{yes-c}} || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}}|| {{no-c}}
|-
| '''output''' || || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''statusRequest''' || || {{yes-c}} || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
! Reading !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox
|-
| '''power''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''presence''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''volume''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{yes-c}}
|-
| '''mute''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}}
|-
| '''input''' || || || || || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}}
|-
| '''output''' || || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''channel''' || || || || {{no-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''currentArtist''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}} || {{yes-c}}
|-
| '''currentAlbum''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}} || {{yes-c}}
|-
| '''currentTitle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''currentMedia''' || || || || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''playStatus''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{planed-c}} || {{yes-c}}
|-
| '''state''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|}

== 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.
{| class="wikitable"
|-
! Kommando !! Beispiel !! Beschreibung
|-
| '''sayText'''|| <pre>set ''<device>'' sayText "Anruf in Abwesenheit"</pre>
|| 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''' || <pre>set ''<device>'' showText "Anruf in Abwesenheit"</pre>|| 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.
|-
! colspan="3"| Alternativvorschlag
|-
| '''message''' || <pre>set ''<device>'' message "Anruf in Abwesenheit" [audio|video]</pre>|| 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 <code>set <device> playlist XY</code> aufrufbar sein. Dabei sollten die zur Verfügung stehenden Playlists bereits bekannt sein und als möglicher Kommando-Parameter angeboten werden.

...

[[Kategorie:Development]]

DevelopmentGuidelinesAV

2014-01-23T13:16:51Z

Fhemrocks: /* Implementation in Modulen */

== 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 [http://forum.fhem.de/index.php?t=msg&th=13784&start=0&rid=430 hier] zu finden.

== Bezeichner ==
siehe [[DevelopmentGuidelines#Bezeichnungen|Bezeichnungen allgmein]]

== Kommandos ==

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

{| class="wikitable"
|-
! Name !! Parameter !! Bedeutung
|-
| '''on''' || || Schaltet das Gerät ein, so dass es benutzt werden kann.
|-
| '''off''' || || Schaltet das Gerät aus, so dass es nicht mehr benutzt werden kann.
|-
| '''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''' || <nowiki>on | off | toggle</nowiki> || Aktiviert, deaktiviert oder schaltet die Mutefunktion = Lautstärke der aktuellen Ausgabe wird verringert bzw. abgschaltet (Gerätespezifisch)
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Aktivieren der Repeatfunktion = wiederholen des aktuellen Titels/Albums
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Aktiviert oder deaktiviert die Shufflefunktion = zufällige Wiedergabe.
|-
| '''channel''' || 0 - 9999 || ??? Schaltet auf einen absoluten Fernsehkanal (Nicht zu verwechseln mit input)
|-
| '''channelUp''' || || Erhöht den Fernsehkanal.
|-
| '''channelDown''' || || Verringert den Fernsehkanal.
|-
| '''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''' || <nowiki>z.B. hdmi[1-n] | av[1-n] | usb | airplay | server [1-n]</nowiki> || 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''' || <nowiki>z.B. Airtunes1,Airtunes2,Intern</nowiki> || Auswahl des/der Ausgabegerätes.
|-
| '''statusRequest''' || || Den aktuellen Status des Gerätes abfragen
|-
|colspan="3"| ...
|}

== 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.

{| class="wikitable"
|-
! Name !! mögliche Werte !! Bedeutung
|-
| '''power''' || <nowiki>on|off</nowiki> || Ist das Gerät an oder aus?
|-
| '''presence''' || <nowiki>present|absent</nowiki> || 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''' || <nowiki>on | off</nowiki> || Ist das Gerät aktuell stumm geschaltet?
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Ist das Gerät im repeat modus?
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || 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''' || <nowiki>playing | paused | stopped</nowiki> ||
|-
| '''state''' || <nowiki>on | off | absent</nowiki> || 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.
|-
|colspan="3"| ...
|}

== Implementation in Modulen ==
{{yes}} = Implementiert {{planed}} = Implementation geplant/in Arbeit {{no}} = Nicht implementiert/Keine Implementation geplant

{| class="wikitable"
! set-Befehl !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox
|-
| '''on''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''off''' || || || || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''play''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''pause''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''stop''' || || || || {{no-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''volume''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{planed-c}}
|-
| '''volumeUp''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''volumeDown''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''mute''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{no-c}}
|-
| '''channelUp''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''channelDown''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''remoteControl''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}}
|-
| '''input''' || {{yes-c}} || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}}|| {{no-c}}
|-
| '''output''' || || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''statusRequest''' || || {{yes-c}} || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}}
|-
! Reading !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox
|-
| '''power''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}}
|-
| '''presence''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}}
|-
| '''volume''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{planed-c}}
|-
| '''mute''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''input''' || || || || || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}}
|-
| '''output''' || || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''channel''' || || || || {{no-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{planed-c}}
|-
| '''currentArtist''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}} || {{yes-c}}
|-
| '''currentAlbum''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}} || {{yes-c}}
|-
| '''currentTitle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''currentMedia''' || || || || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{planed-c}} || {{planed-c}}
|-
| '''playStatus''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{planed-c}} || {{yes-c}}
|-
| '''state''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|}

== 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.
{| class="wikitable"
|-
! Kommando !! Beispiel !! Beschreibung
|-
| '''sayText'''|| <pre>set ''<device>'' sayText "Anruf in Abwesenheit"</pre>
|| 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''' || <pre>set ''<device>'' showText "Anruf in Abwesenheit"</pre>|| 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.
|-
! colspan="3"| Alternativvorschlag
|-
| '''message''' || <pre>set ''<device>'' message "Anruf in Abwesenheit" [audio|video]</pre>|| 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 <code>set <device> playlist XY</code> aufrufbar sein. Dabei sollten die zur Verfügung stehenden Playlists bereits bekannt sein und als möglicher Kommando-Parameter angeboten werden.

...

[[Kategorie:Development]]

DevelopmentGuidelinesAV

2014-01-20T16:18:11Z

Fhemrocks:

== 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 [http://forum.fhem.de/index.php?t=msg&th=13784&start=0&rid=430 hier] zu finden.

== Bezeichner ==
siehe [[DevelopmentGuidelines#Bezeichnungen|Bezeichnungen allgmein]]

== Kommandos ==

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

{| class="wikitable"
|-
! Name !! Parameter !! Bedeutung
|-
| '''on''' || || Schaltet das Gerät ein, so dass es benutzt werden kann.
|-
| '''off''' || || Schaltet das Gerät aus, so dass es nicht mehr benutzt werden kann.
|-
| '''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''' || <nowiki>on | off | toggle</nowiki> || Aktiviert, deaktiviert oder schaltet die Mutefunktion = Lautstärke der aktuellen Ausgabe wird verringert bzw. abgschaltet (Gerätespezifisch)
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Aktivieren der Repeatfunktion = wiederholen des aktuellen Titels/Albums
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Aktiviert oder deaktiviert die Shufflefunktion = zufällige Wiedergabe.
|-
| '''channel''' || 0 - 9999 || ??? Schaltet auf einen absoluten Fernsehkanal (Nicht zu verwechseln mit input)
|-
| '''channelUp''' || || Erhöht den Fernsehkanal.
|-
| '''channelDown''' || || Verringert den Fernsehkanal.
|-
| '''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''' || <nowiki>z.B. hdmi[1-n] | av[1-n] | usb | airplay | server [1-n]</nowiki> || 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''' || <nowiki>z.B. Airtunes1,Airtunes2,Intern</nowiki> || Auswahl des/der Ausgabegerätes.
|-
| '''statusRequest''' || || Den aktuellen Status des Gerätes abfragen
|-
|colspan="3"| ...
|}

== 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.

{| class="wikitable"
|-
! Name !! mögliche Werte !! Bedeutung
|-
| '''power''' || <nowiki>on|off</nowiki> || Ist das Gerät an oder aus?
|-
| '''presence''' || <nowiki>present|absent</nowiki> || 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''' || <nowiki>on | off</nowiki> || Ist das Gerät aktuell stumm geschaltet?
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Ist das Gerät im repeat modus?
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || 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''' || <nowiki>playing | paused | stopped</nowiki> ||
|-
| '''state''' || <nowiki>on | off | absent</nowiki> || 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.
|-
|colspan="3"| ...
|}

== Implementation in Modulen ==
{{yes}} = Implementiert {{planed}} = Implementation geplant/in Arbeit {{no}} = Nicht implementiert/Keine Implementation geplant

{| class="wikitable"
! set-Befehl !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox
|-
| '''on''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''off''' || || || || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''play''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''pause''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''stop''' || || || || {{no-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''volume''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{no-c}}
|-
| '''volumeUp''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''volumeDown''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''mute''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{no-c}}
|-
| '''channelUp''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''channelDown''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''remoteControl''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}}
|-
| '''input''' || {{yes-c}} || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}}|| {{no-c}}
|-
| '''output''' || || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''statusRequest''' || || {{yes-c}} || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}}
|-
! Reading !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox
|-
| '''power''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}}
|-
| '''presence''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}}
|-
| '''volume''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{planed-c}}
|-
| '''mute''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''input''' || || || || || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}}
|-
| '''output''' || || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''channel''' || || || || {{no-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{planed-c}}
|-
| '''currentArtist''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}} || {{yes-c}}
|-
| '''currentAlbum''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}} || {{yes-c}}
|-
| '''currentTitle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}}
|-
| '''currentMedia''' || || || || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{planed-c}} || {{no-c}}
|-
| '''playStatus''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{planed-c}} || {{yes-c}}
|-
| '''state''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}}
|}

== 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.
{| class="wikitable"
|-
! Kommando !! Beispiel !! Beschreibung
|-
| '''sayText'''|| <pre>set ''<device>'' sayText "Anruf in Abwesenheit"</pre>
|| 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''' || <pre>set ''<device>'' showText "Anruf in Abwesenheit"</pre>|| 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.
|-
! colspan="3"| Alternativvorschlag
|-
| '''message''' || <pre>set ''<device>'' message "Anruf in Abwesenheit" [audio|video]</pre>|| 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 <code>set <device> playlist XY</code> aufrufbar sein. Dabei sollten die zur Verfügung stehenden Playlists bereits bekannt sein und als möglicher Kommando-Parameter angeboten werden.

...

[[Kategorie:Development]]

DevelopmentModuleIntro

2014-01-14T13:20:33Z

Fhemrocks: /* Noch zu beschreiben */

== Einleitung ==
Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden.
Insbesondere beschreibt der Text derzeit nur einstufige Module. Die Abgrenzung zu zweistufigen Modulen und deren Eigenschaften sollte noch ergänzt werden.

Um neue Geräte in FHEM verfügbar zu machen, kann man ein eigenes Modul in Perl schreiben, das automatisch von FHEM geladen wird, wenn ein passendes Gerät in FHEM definiert wird. Das Modul definiert dann wie mit dem Gerät kommuniziert wird, stellt Werte ("Readings") innerhalb von FHEM zur Verfügung oder erlaubt es das Gerät mit "Set"-Befehlen zu beeinflussen. Dieser Text soll den Einstieg in die Entwicklung eigener Module erleichtern.

Mit dem FHEM-Befehl "define", der typischerweise in die zentrale Konfigurationsdatei fhem.cfg eingetragen wird, werden Geräte in FHEM definiert. Der Befehl sorgt dafür dass ein neues Modul bei Bedarf geladen wird und die Initialisierungsfunktion des Moduls aufgerufen wird.

Damit das funktioniert müssen der Name des Geräts, der Name des Moduls und der Name der Initialisierungsfunktion zueinander passen. Das folgende Beispiel soll dies verdeutlichen:

Ein Jeelink USB-Stick in einer Fritz-Box könnte beispielsweise mit dem Befehl <code>define JeeLink1 JeeLink /dev/ttyUSB0@57600</code> definiert werden.

In der fhem.pl wird der define-Befehl verarbeitet, geprüft, ob ein Modul mit Namen JeeLink schon geladen ist und falls nicht ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (bei einer FritzBox z.B. /var/media/ftp/fhem/FHEM) gesucht und dann geladen.
Danach wird die Funktion JeeLink_Initialize aufgerufen.
Die Moduldatei muss also nach dem Namen des Geräts benannt werden und eine Funktion mit dem Namen des Geräts und einer _initialize Funktion enthalten.
In der Initialisierungsfunktion des Moduls werden dann die Namen der aller weiteren Funktionen des Moduls, die von fhem.pl aus aufgerufen werden, bekannt gemacht. Dazu wird der Hash - das ist die zentrale Datenstruktur für jede Instanz eines Gerätes - mit entsprechenden Werten gefüllt.

== Der Hash einer Geräteinstanz ==
Der zentrale Speicherort für Informationen einer Geräteinstanz ist ein Hash, der seinerseits in fhem.pl von einem globalen Hash referenziert wird.

<code>$defs{$d}</code> in fhem.pl verweist auf den Hash der Geräteinstanz mit Namen <code>$d</code>. Diesen Hash bekommen die Funktionen eines Moduls oft von fhem.pl übergeben. In ihm stehen beispielsweise die internen Werte des Geräts, die im GUI als "Internals" angezeigt werden oder die Readings des Geräts.

<code>$hash{NAME}</code> enthält beispielsweise den Namen der Geräteinstanz, <code>$hash{TYPE}</code> enthält den Namen des Typs des Geräts, der ja auch für den Namen des Moduls verwendet wird.

Ein Abfrageintervall, das beim define eines Geräts an die define-Funktion im Modul übergeben wird, würde typischerweise als "Internal" in <code>$hash->{INTERVAL}</code> abgelegt.

Die Readings sind hier als weitere Unterstruktur gespeichert, beispielsweise <code>$hash{READINGS}{$ReadingName}{VAL}</code> und <code>$hash{READINGS}{$ReadingName}{TIME}</code>. Innerhalb von fhem.pl könnten die selben Readings beispielsweise über <code>$defs{$d}{READINGS}{$ReadingName}{VAL}</code> adressiert werden, da <code>$defs{$d}</code> ja auf den gleichen Hash verweist, der dann den Modul-Funktionen übergeben wird und innerhalb der Funktionen typischerweise als <code>$hash</code> verwendet wird.

== Readings ==
Werte, die von einem Gerät gelesen werden und in FHEM zur Verfügung stehen werden Readings genannt. Sie werden wie oben beschrieben als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise <code>$hash{READINGS}{$Temp}{VAL}</code> für die Temperatur eines Fühlers, die als Reading gespeichert wurde.
Zum Setzen von Readings (siehe auch unten) ist es empfehlenswert die Funktionen <code>readingsBeginUpdate</code>, <code>readingsBulkUpdate</code>, <code>readingsEndUpdate</code> oder <code>readingsSingleUpdate</code> aufzurufen. Dabei kann man auch angeben, ob dabei ein Event ausgelöst werden soll oder nicht. Events erzeugen spürbare Last auf dem System (siehe NotifyFn), das Ändern von Readings ohne dass dabei Events erzeugt werden jedoch nicht.

für den lesenden Zugriff auf Readings steht die Funktion ReadingsVal($$$) zur Verfügung.

Readings werden im statefile von FHEM automatisch zwischengespeichert, damit sie nach einem Neustart sofort wieder zur Verfügung stehen, auch bevor sie vom Modul neu gesetzt oder aktualisiert werden.

== Internals ==
Werte, die das Modul intern als Teil des Hashes speichert, die aber keine Readings sind, nennt man Internals. Sie werden abenfalls als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielswiese <code>$hash->{INTERVAL}</code> für ein Abfrageintervall, das beim Define-Befehl übergeben wurde und als Internal gespeichert wird. Internals werden jedoch im Gegensatz zu Readings nicht im statefile zwischengespeichert.

== Attribute ==
Parameter eines Moduls können als so genannte Attribute gesetzt und damit dem Modul zur Verfügung gestellt werden. Attribute werden zusammen mit der Definition der Geräte beim Speichern der aktuellen Konfiguration von FHEM in die Konfigurationsdate geschrieben. Zur Laufzeit werden sie in der globalen Datenstruktur <code>$attr{$name}</code> gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielswiese mit <code>$attr{$name}{header}</code> adressiert (<code>$attr{$name}->{'header'}</code> wäre eine alternative aber unübliche Schreibweise für die selber Variable).

Zum Auslesen solcher Attribute sollte die Funktion <code>AttrVal($$$)</code> verwendet werden.

Welche Attribute ein Modul unterstützt sollte in der Funktion <code>X_Initialize</code> durch Setzen der Variable <code>$hash->{AttrList}</code> bekannt gemacht werden (siehe unten). Wenn beim Setzen von Attributen die Werte geprüft werden sollen oder zusätzliche Funktionalität implementiert werden muss, dann kann dies in der Funktion <code>X_Attr</code> (siehe unten) implementiert werden.

== Die wichtigsten Funktionen in einem Modul ==
Eine typische Grundfunktion eines einfachen Moduls ist das Auslesen von Werten von einem physischen Gerät und Bereitstellen dieser Werte innerhalb von FHEM als Readings. Das Geräte könnte beispielsweise an einem USB-Port angeschlossen sein. Folgende Funktionen könnte man beispielsweise in einem Modul mit Namen X implementieren:
* X_Initialize (initialisiert das Modul und gibt de Namen der zusätzlichen Funktionen bekannt)
* X_Define (wird beim <code>define</code> aufgerufen
* X_Undef (wird beim Löschen einer Geräteinstanz aufgerufen - Gegenteil zu <code>define</code>)
* X_Set (wird beim Befehl <code>set</code> aufgerufen um Daten an das Gerät zu senden)
* X_Get (wird beim Befehl <code>get</code> aufgerufen um Daten vom Gerät abzufragen)
* X_Attr (wird beim Befehl <code>attr</code> aufgerufen um beispielsweise Werte zu prüfen)
* X_Read (wird vom globalen select aufgerufen, falls Daten zur Verfuegung stehen)
* X_Parse (wird bei zweistufigen Modulen vom Dispatch aufgerufen und muss hier noch beschrieben werden)
* X_Ready (wird unter windows als ReadFn-Erstatz benoetigt bzw. um zu pruefen, ob ein Geraet wieder eingesteckt ist)
* X_Notify (falls man benachrichtigt werden will)
* X_Rename (falls ein Gerät umbenannt wird)

Die Funktionen werden im folgenden beschrieben (soweit diese Seite inzwischen vollständig ist):

=== X_Initialize ===

<pre>
sub X_Initialize($)
{
my ($hash) = @_;
...
</pre>

Das <code>X</code> im Namen muss dabei auf den Namen des Moduls bzw. des definierten Gerätetyps geändert werden. Im Modul mit der Datei <code>36_JeeLink.pm</code> beispielsweise ist der Name der Funktion <code>JeeLink_Initialize</code>. Die Funktion wird von Fhem.pl nach dem Laden des Moduls aufgerufen und bekommt einen Hash für das Modul als zentrale Datenstruktur übergeben.
Die Initialize-Funktion setzt dann weitere Funktionsnamen, die im Modul implementiert sind, in diesen Hash:

<pre>
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
</pre>

<code>X</code> ist wieder durch den Modulnamen ohne die vorangestellte Zahl zu ersetzen.
Entsprechend können auch die Funktionen <code>X_Read</code>, <code>X_Parse</code> etc. durch Zuweisung an <code>$hash->{ReadFn}</code> etc. bekannt gemacht werden.

Darüber hinaus sollten die vom Modul unterstützen Attribute definiert werden:

<pre>
$hash->{AttrList} =
"do_not_notify:1,0 " .
"header " .
$readingFnAttributes;
</pre>

In Fhem.pl werden dann die entsprechenden Werte beim Aufruf eines <code>attr</code>-Befehls in die globale Datenstruktur <code>$attr{$name}</code>, z.B. <code>$attr{$name}{header}</code> für das Attribut <code>header</code> gespeichert. Falls im Modul weitere Aktionen oder Prüfungen beim Setzen eines Attributs nötig sind, dann kann wie im Beispiel oben die Funktion <code>X_Attr</code> implementiert und in der Initialize-Funktion bekannt gemacht werden.

Die Variable <code>$readingFnAttributes</code>, die im obigen Beispiel an die Liste der unterstützten Attribute angefügt wird, definiert Attributnamen, die dann verfügbar werden wenn das Modul zum Setzen von Readings die Funktionen readingsBeginUpdate, readingsBulkUpdate, readingsEndUpdate oder readingsSingleUpdate verwendet. In diesen Funktionen werden Attribute wie <code>event-min-interval</code> oder auch <code>event-on-change-reading</code> ausgewertet. Für Details hierzu siehe commandref.

=== X_Define ===
Die Define-Funktion eines Moduls wird von Fhem aufgerufen wenn der Define-Befehl für ein Geräte ausgeführt wird und das Modul bereits geladen und mit der Initialize-Fubktion initialisiert ist. Sie ist typischerweise dazu da, die übergebenen Parameter zu prüfen und an geeigneter Stelle zu speichern sowie einen Kommunikationsweg zum Gerät zu öffnen (z.B. TCP-Verbindung, USB-Schnittstelle o.ä.)
Sie beginnt typischerweise mit:

<pre>
sub HTTPMOD_Define($$)
{
my ( $hash, $def ) = @_;
my @a = split( "[ \t][ \t]*", $def );
...
</pre>

Als Übergabeparameter bekommt die Define-Funktion den Hash der Geräteinstanz sowie den Rest der Parameter, die im Befehl angegeben wurden. Welche und wie viele Parameter
akzeptiert werden ist Sache dieser Funktion. Im obigen Beispiel wird alles nach dem übergebenen Hash in ein Array aufgeteilt und so können die vom Modul bzw. der Define-Funktion erwarteten Werte über das Array der Reihe nach verarbeitet werden:

<pre>
my $name = $a[0];
my $url = $a[2];
my $inter = 300;
if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5, default is 300";
}
}
</pre>

Damit die übergebenen Werte auch anderen Funktionen zur Verfügung stehen und an die jeweilige Geräteinstanz gebunden sind, werden die Werte typischerwiese als Internals im Hash der Geräteinstanz gespeichert:

<pre>
$hash->{url} = $url;
$hash->{Interval} = $inter;
</pre>

Wenn eine physische Schnittstelle geöffnet werden soll und dann bei verfügbaren Eingabedaten eine Lese-Funktion von Fhem aufgerufen werden soll, dann kann man in der Define-Funktion die Funktion DevIo_OpenDev aufrufen, die sich um alles weitere kümmert. Sie öffnet die Schnittstelle und fügt den Filedeskriptor an die globale Liste offener Verbindungen (selectlist / readyfnlist) an. Damit kann Fhem in seiner Hauptschleife erkennen, von welchem Gerät Daten bereit stehen und die zuständigen Funktionen aufrufen:

<pre>
my $ret = DevIo_OpenDev( $hash, 0, "X_DevInit" );
</pre>

Die optionale Funktion <code>X_DevIni</code>t wird zur weiteren Initialisierung der Verbindung von <code>DevIo_OpenDev</code> aufgerufen. Der zweite Übergabeparameter an <code>DevIo_OpenDev</code> (hier <code>0</code>) steht für reopen und wird benötigt, da die Funktion auch aufgerufen wird, wenn ein USB-Geräte beispielsweise im Betrieb aus- und wieder eingesteckt wird. In diesem Fall wird die Funktion mit <code>1</code> aufgerufen.

=== X_Undef ===

Die <code>Undef</code>-Funktion ist das Gegenstück zur <code>Define</code>-Funktion und wird aufgerufen wenn ein Gerät mit <code>delete</code> gelöscht wird. Entsprechend müssen in der Funktion typische Aufräumarbeiten durchgeführt werden wie das saubere Schließen von Verbindungen oder das entfernen von internen Timern sofern diese im Modul zum Pollen verwendet wurden (siehe später).

Beispiel:
<pre>
sub WKRCD4_Undef($$)
{
my ( $hash, $arg ) = @_;
DevIo_CloseDev($hash);
RemoveInternalTimer($hash);
return undef;
}
</pre>

=== X_Get ===
Die Get-Funktion wird aufgerufen wenn der Fhem-Befehl <code>get</code> mit einem Gerät dieses Moduls ausgeführt wird. Mit <code>get</code> werden typischerweise Werte von einem Gerät abgefragt. Einige Module verwenden für diese Funktion einen Hash im Modul, der die möglichen <code>get</code>-Optionen mit zusätzlichen Werten definiert:

<pre>
my X_gets = (
"TempSoll" => "XY",
"Steilheit" => "Z"
);
</pre>
In der Get-Funktion selbst werden dann die übergebenen Parameter gegen diesen Hash geprüft.

Beispiel:

<pre>
sub X_Get($@)
{
my ( $hash, @a ) = @_;
return "\"get X\" needs at least one argument" if ( @a < 2 );
my $name = shift @a;
my $opt = shift @a;
if(!$X_gets{$opt}) {
my @cList = keys %X_gets;
return "Unknown argument $attr, choose one of " . join(" ", @cList);
}
...
</pre>

Die Ausgabe der Meldung mit <code>... choose one of ...</code> ist dabei wichtig, da sie im GUI-Modul verwendet wird um die möglichen <code>get</code>-Optionen zu ermitteln und als Auswahl anzubieten. Im weiteren Verlauf der Get-Funktion könnte man dann mit dem physischen Gerät kommunizieren und den gefragten Wert abfragen und diesen als Return-Wert der Get-Funktion zurückgeben.

=== X_Set ===
Die Set-Funktion ist das Gegenteil zur Get-Funktion. Sie ist dafür gedacht, Werte zum physischen Gerät zu schicken. Falls nur interne Werte im Modul gesetzt werden sollen, so sollte statt Set die Attr-Funktion verwendet werden. Attribute werden bei Save-Config auch in der Fhem.cfg gesichert. Set-Befehle nicht.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch nach dem Namen der Option auch den zu setzenden Wert übergeben.

Beispiel:
<pre>
sub X_Set($@)
{
my ( $hash, @a ) = @_;
return "\"set X\" needs at least an argument" if ( @a < 2 );
my $name = shift @a;
my $opt = shift @a;
my $arg = join("", @a);

if(!defined($X_sets{$attr})) {
my @cList = keys %X_sets;
return "Unknown argument $attr, choose one of " . join(" ", @cList);
}
</pre>

Den einzelnen Befehlen, die das Modul versteht und die via set <name> <cmd> <arg1> übergeben werden kann man bei der Rückgabe auch zulässige Auswahlwerte für Kommando Argumente mitgeben. Aus diesen Auswahlwerten erzeugt FHEM-Web dann z.B. Drop-Down Boxen in der Detailansicht, mit denen der Anwender die jeweiligen Argumente auswählen kann. Dabei ist jeweils vor dem Doppelpunkt der Name des Kommandoes anzugeben und nach dem Doppelpunkt der jeweilige Auswahlwert.
Es gibt dabei folgende Möglichkeiten:

'''noArg'''

es werden keine weiteren Argumente mehr benötigt
<pre>on:noArg</pre>

'''slider'''

es wird ein Schieberegler für den Wert angezeigt. Dabei Minimum, Schrittweite und Maximum angeben
<pre>dim:slider,0,1,100</pre>

'''RGB'''

es wird ein Colorpicker angezeigt, der dem Anwender die Auswahl einer Farbe ermöglicht. Bitte dazu auch den Wiki Artikel zum Colorpicker lesen, da im Modul noch weiterer Code eingefügt werden muß.
<pre>rgb:colorpicker,RGB</pre>

'''Liste'''

Mit Kommata getrennte Werte ergeben eine Drop-Down Liste, mit der der User die Werte auswählen kann
<pre>loglevel:1,2,3,4,5
timer:30,120,300
mode:verbose,ultra,relaxed</pre>

'''Leer'''

Wird kein Doppelpunkt zum Kommando angegeben, so wird eine Eingabezeile angezeigt, die die freie Eingabe eines Wertes erlaubt

Damit die jeweiligen Auswahllisten bereits mit dem korrekten Wert, der aktuell im Modul gesetzt ist, befüllt wird, muß dass Get Kommando im Modul implementiert sein und den jeweiligen Wert zurück liefern.
Am Beispiel des Sliders oben:
der Wert heisst dim und soll per Slider dargestellt sein. Damit der aktuelle Wert des dim im Slider in der Oberfläche bereits richtig voreingestellt ist, sollte die Get Funktion auf Anfrage nach dim auch den aktuellen Wert von dim zurück liefern.

'''Hinweise'''

- bei den üblichen Kommandos wie on off sollte man auf noArg verzichten, da diese durch FHEMWeb automatisch in der Raumübersicht angezeigt werden. Wenn man hier noArg spezifiziert, so werden diese nicht neben dem Modul in der Raumübersicht angezeigt und der User muß sich diese vie webCmd dann erst selbst definieren, was natürlich unschön ist

- der User kann sich in der Raumübersicht nach wie vor via webCmd eine entsprechende Steuerung anlegen.

=== X_Attr ===
Die Attr-Funktion implementiert Prüfungen der bei einem <code>attr</code> übergebenen Werte und eventuell zusätzliche Aktionen wenn ein Attribut gesetzt wird. Die Liste der möglichen Attribute wird in der <code>X_Initialize-Funktion</code> definiert (siehe oben). Fhem ruft bei einem Attr-Befehl die zuständige <code>X-Attr-Funktion</code> auf und wenn diese keine Fehlermelhung sondern <code>undef</code> zurückgibt, dann schreibt fhem.pl die bei <code>attr</code> angegebenen Werte in die jeweilige Datenstruktur <code>$attr{$name}-> ...</code>

Beispiel:

<pre>
X_Attr(@)
{
my ($cmd,$name,$aName,$aVal) = @_;
# $cmd can be "del" or "set"
# $name is device name
# aName and aVal are Attribute name and value
if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aVal/ };
if ($@) {
Log3 $name, 3, "X: Invalid regex in attr $name $aName $aVal: $@";
return "Invalid Regex $aVal";
}
}
}
return undef;
}
</pre>

Die Attr-Funktion bekommt nicht den Hash der Geräteinstanz übergeben, da sie ja auch keine Werte dort speichern muss sondern den Befehl <code>set</code> oder <code>del</code> je nachdem ob ein Attribut gesetzt oder gelöscht wird, den Namen der Geräteinstanz sowie den Namen des Attributs und seinen Wert.
Im obigen Beispiel wird für ein Attribut mit Namen Regex geprüft ob die Regex fehlerhaft ist. Falls sie ok ist, wird undef zurück gegegen und fhem.pl speichert den Wert des Attributs.

=== X_Read ===

Die X_Read-Funktion wird aus der Hauptschleife von FHEM aus aufgerufen wenn das Gerät, für das das Modul zuständig ist, Daten bereit gestellt hat, die gelesen werden können. Im folgenden Beispiel wird über eine serielle Schnittstelle (beziehungsweise über einen USB-To-Seriell-Konverter) von einem angeschlossenen Gerät gelesen. Dazu werden die bisher verfügbaren Daten mit der Funktion <code>DevIo_SimpleRead</code> gelesen. Da die Übertragung möglicherweise noch nicht vollständig ist, kann es sein, dass kurz darauf die X_Read-Funktion wieder aufgerufen wird und ein weiterer Teil oder der Rest der Daten gelesen werden kann.
Die Funktion muss daher prüfen ob schon alle erwarteten Daten angekommen sind und gegebenenfalls die bisher gelesenen Daten zwischenspeichern. Es bietet sich an, dies im Hash der Geräteinstanz zu tun. Im Beispiel ist dies <code>$hash->{buffer}</code> an den die jeweils gelesenen Daten angehängt werden bis die folgende Prüfung ein für das jeweilige Protokoll passendes Frame identifiziert.

<pre>
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# read from serial device
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );

# convert to hex string to make parsing with regex easier
$hash->{buffer} .= unpack ('H*', $buf);
Log3 $name, 5, "Current buffer content: " . $hash->{buffer};

# did we already get a full frame?
if ($hash->{buffer} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)")
...
</pre>

Die zu lesenden Nutzdaten können dann je nach Protokoll des Geräts beispielsweise an einer festgelegten Stelle im Frame (dann in <code>$hash->{buffer}</code>) stehen oder aus dem Kontext mit einem Regex-Match extrahiert werden und in Readings gespeichert werden (siehe unten).

=== X_Ready ===

muss noch beschrieben werden.

Beispiel:
<pre>
sub X_Ready($)
{
my ($hash) = @_;
return DevIo_OpenDev($hash, 1, undef )
if ( $hash->{STATE} eq "disconnected" );

# This is relevant for windows/USB only
my $po = $hash->{USBDev};
my ( $BlockingFlags, $InBytes, $OutBytes, $ErrorFlags ) = $po->status;
return ( $InBytes > 0 );
}
</pre>

== Lesen von Geräte und Speichern der Werte in Readings ==

FHEM führt Module normalerweise nicht parallel aus. Daher wäre es ungünstig wenn Module Werte von einem Gerät abfragen und dann auf die Antwort des Geräts warten. In dieser Zeit wäre der Rest von FHEM blockiert. Die Ein- und Ausgabe sollte ohne Blockieren erfolgen und die Verarbeitung mehrerer Ein- und Ausgabekanäle quasi parallel ermöglichen.

Dafür werden in FHEM zwei zentrale Listen gepflegt, in der die Filedeskriptoren der geöffneten Kommunikatonsverbindungen gespeichert sein können. Auf Linux- bzw. Unix-basierten Plattformen wird der select-Befehl des Betriebssystems verwendet und entsprechend gibt es in FHEM eine selectlist, in der die Filedeskriptoren der Geräedateien (z.B. /dev/ttyUSBx etc.) gespeichert sind.

In der zentralen Schleife von fhem.pl wird vereinfacht gesagt mit select überwacht, ob über eine der geöffneten Schnittstellen Daten zum Lesen anstehen. Wenn dies der Fall ist, dann wird die Lesefunktion (X_Read) des zuständigen Moduls aufgerufen, damit es die Daten entgegennimmt und die Schleife wird weiter ausgeführt.

Auf Windows-Systemen funktioniert dies anders. Hier können USB/Seriell-Geräte nicht per select überwacht werden. In FHEM unter Windows werden daher diese Schnittstellen kontinuierlich abgefragt ob Daten bereitstehen. Dafür müssen Module zusätzlich zur Lesefunktion eine Abfragefunktion (X_Ready) implementieren, die prüft ob Daten zum Lesen anstehen. Auch auf Linux/Unix-Plattformen hat diese Funktion eine Aufgabe. Falls nämlich eine Schnittstelle ausfällt beziehungsweise ein CUL oder USB-zu-Seriell Adapter ausgesteckt wird, dann wird über diese Funktion regelmäßig geprüft ob die Schnittstelle wieder verfügbar wird.

Innerhalb der eigentlichen Lesefunktion (X_Read) werden dann die Daten vom zugehörigen Gerät gelesen, das nötige Protokoll implementiert und Werte in Readings geschrieben.

Zum Setzen von Readings ist es wie oben schon erwähnt empfehlenswert die Funktionen <code>readingsBeginUpdate</code>, <code>readingsBulkUpdate</code>, <code>readingsEndUpdate</code> oder <code>readingsSingleUpdate</code> aufzurufen. Dabei kann man auch angeben, ob dabei ein Event ausgelöst werden soll oder nicht. Events erzeugen spürbare Last auf dem System (siehe NotifyFn), das Ändern von Readings ohne dass dabei Events erzeugt werden jedoch nicht.

Eine Sequenz zum Setzen von Readings könnte folgendermaßen aussehen:

<pre>
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</pre>

Die <code>1</code> beim Aufruf von <code>readingsEndUpdate</code> gibt an, dass Events ausgelöst werden, die auf Veränderungen der Readings reagieren.

== Pollen von Geräten ==
Wenn Geräte von sich aus keine Informationen senden sondern abgefragt werden müssen, kann man im Modul die Funktion <code>InternalTimer<code> verwenden. Man übergibt ihr den Zeitpunkt für den nächsten Aufruf, den Namen der Funktion, die aufgerufen werden soll, die zu übergebenden Parameter und ein Flag ob der erste Aufruf verzögert werden soll falls die Initialiserung des Geräts noch nicht abgeschlossen ist.

Beispielsweise könnte man für das Abfragen eines Geräts in der Define-Funktion den Timer folgendermassen setzen:

<pre>
# initial request after 2 secs, there timer is set to interval for further update
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash, 0);
</pre>

in der Funktion <code>X_GetUpdate</code> selbst wird dann der Timer neu gesetzt, so dass nach einem Intervall die Funktion erneut aufgerufen wird:

<pre>
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash, 1);
Log3 $name, 4, "X: GetUpdate called ...";
</pre>

Im weiteren Verlauf der Funktion könnte man dann das Gerät abfragen und die abgefragten Werte in Readings speichern. Falls das Abfragen der Werte jedoch zu einer Verzögerung und damit zu einer Blockade von FHEM führen kann, ist es möglich, in der GetUpdate-Funktion nur die Aufforderung zum Senden bestimmter Daten an das angeschlossene Gerät zu senden und dann das Lesen über die oben beschriebene Read-Funktion zu implementieren, die beim Anstehen von Daten aufgerufen wird.

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Protokollmeldung in die Fhem-Logdatei zu schreiben, wird die Funktion Log3 aufgerufen:
<pre>
Log3 $name, 3, "X: Problem erkannt ...";
</pre>

Die Parameter der Funktion Log3 sind der Name oder der Hash der Geräteinstanz, das Verbose-Level, in dem die Meldung sichtbar sein soll und die Meldung selbst.
Den Namen der Geräteinstanz kann man in den Funktionen, die den Hash übergeben bekommen einfach aus diesem Hash nehmen:

<pre>
my $name = $hash->{NAME};
</pre>

Um für ein neues Modul das Verbose-Level zu erhöhen, ohne gleich für das Gesamte FHEM alle Meldungen zu erzeugen kann man den Befehl
<code>attr gerätename verbose</code> verwenden. Beispielsweise <code>attr PM verbose 5</code>

Damit bietet es sich an im Modul Meldungen, die im normalen Betrieb nicht benötigt werden, beim Aufruf von Log3 mit dem Level 4 oder 5 anzugeben. Wenn man dann bei der Fehlersuche mehr Meldungen sehen möchte, erhöht man mit attr X verbose das Level für das betroffene Gerät.

== Noch zu beschreiben ==
* Zweistufiges Modell für Module
* Funktion X_Ready ...
* FW_summaryFn (wird von FHEMWEB aufgerufen fuer Raum-Uebersicht)
* FW_detailFn (wird von FHEMWEB aufgerufen fuer Detail-Ansicht)
* Bei der Beschreibung der von SetFn/GetFn zurueckgelieferten Meldung: Modifier fuer FHEMWEB wie :noArg, :slider, etc. -->2014-01-14: done. Bitte um Review der Beschreibung

[[Kategorie:Development]]

DevelopmentModuleIntro

2014-01-14T13:20:14Z

Fhemrocks: /* Noch zu beschreiben */

== Einleitung ==
Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden.
Insbesondere beschreibt der Text derzeit nur einstufige Module. Die Abgrenzung zu zweistufigen Modulen und deren Eigenschaften sollte noch ergänzt werden.

Um neue Geräte in FHEM verfügbar zu machen, kann man ein eigenes Modul in Perl schreiben, das automatisch von FHEM geladen wird, wenn ein passendes Gerät in FHEM definiert wird. Das Modul definiert dann wie mit dem Gerät kommuniziert wird, stellt Werte ("Readings") innerhalb von FHEM zur Verfügung oder erlaubt es das Gerät mit "Set"-Befehlen zu beeinflussen. Dieser Text soll den Einstieg in die Entwicklung eigener Module erleichtern.

Mit dem FHEM-Befehl "define", der typischerweise in die zentrale Konfigurationsdatei fhem.cfg eingetragen wird, werden Geräte in FHEM definiert. Der Befehl sorgt dafür dass ein neues Modul bei Bedarf geladen wird und die Initialisierungsfunktion des Moduls aufgerufen wird.

Damit das funktioniert müssen der Name des Geräts, der Name des Moduls und der Name der Initialisierungsfunktion zueinander passen. Das folgende Beispiel soll dies verdeutlichen:

Ein Jeelink USB-Stick in einer Fritz-Box könnte beispielsweise mit dem Befehl <code>define JeeLink1 JeeLink /dev/ttyUSB0@57600</code> definiert werden.

In der fhem.pl wird der define-Befehl verarbeitet, geprüft, ob ein Modul mit Namen JeeLink schon geladen ist und falls nicht ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (bei einer FritzBox z.B. /var/media/ftp/fhem/FHEM) gesucht und dann geladen.
Danach wird die Funktion JeeLink_Initialize aufgerufen.
Die Moduldatei muss also nach dem Namen des Geräts benannt werden und eine Funktion mit dem Namen des Geräts und einer _initialize Funktion enthalten.
In der Initialisierungsfunktion des Moduls werden dann die Namen der aller weiteren Funktionen des Moduls, die von fhem.pl aus aufgerufen werden, bekannt gemacht. Dazu wird der Hash - das ist die zentrale Datenstruktur für jede Instanz eines Gerätes - mit entsprechenden Werten gefüllt.

== Der Hash einer Geräteinstanz ==
Der zentrale Speicherort für Informationen einer Geräteinstanz ist ein Hash, der seinerseits in fhem.pl von einem globalen Hash referenziert wird.

<code>$defs{$d}</code> in fhem.pl verweist auf den Hash der Geräteinstanz mit Namen <code>$d</code>. Diesen Hash bekommen die Funktionen eines Moduls oft von fhem.pl übergeben. In ihm stehen beispielsweise die internen Werte des Geräts, die im GUI als "Internals" angezeigt werden oder die Readings des Geräts.

<code>$hash{NAME}</code> enthält beispielsweise den Namen der Geräteinstanz, <code>$hash{TYPE}</code> enthält den Namen des Typs des Geräts, der ja auch für den Namen des Moduls verwendet wird.

Ein Abfrageintervall, das beim define eines Geräts an die define-Funktion im Modul übergeben wird, würde typischerweise als "Internal" in <code>$hash->{INTERVAL}</code> abgelegt.

Die Readings sind hier als weitere Unterstruktur gespeichert, beispielsweise <code>$hash{READINGS}{$ReadingName}{VAL}</code> und <code>$hash{READINGS}{$ReadingName}{TIME}</code>. Innerhalb von fhem.pl könnten die selben Readings beispielsweise über <code>$defs{$d}{READINGS}{$ReadingName}{VAL}</code> adressiert werden, da <code>$defs{$d}</code> ja auf den gleichen Hash verweist, der dann den Modul-Funktionen übergeben wird und innerhalb der Funktionen typischerweise als <code>$hash</code> verwendet wird.

== Readings ==
Werte, die von einem Gerät gelesen werden und in FHEM zur Verfügung stehen werden Readings genannt. Sie werden wie oben beschrieben als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise <code>$hash{READINGS}{$Temp}{VAL}</code> für die Temperatur eines Fühlers, die als Reading gespeichert wurde.
Zum Setzen von Readings (siehe auch unten) ist es empfehlenswert die Funktionen <code>readingsBeginUpdate</code>, <code>readingsBulkUpdate</code>, <code>readingsEndUpdate</code> oder <code>readingsSingleUpdate</code> aufzurufen. Dabei kann man auch angeben, ob dabei ein Event ausgelöst werden soll oder nicht. Events erzeugen spürbare Last auf dem System (siehe NotifyFn), das Ändern von Readings ohne dass dabei Events erzeugt werden jedoch nicht.

für den lesenden Zugriff auf Readings steht die Funktion ReadingsVal($$$) zur Verfügung.

Readings werden im statefile von FHEM automatisch zwischengespeichert, damit sie nach einem Neustart sofort wieder zur Verfügung stehen, auch bevor sie vom Modul neu gesetzt oder aktualisiert werden.

== Internals ==
Werte, die das Modul intern als Teil des Hashes speichert, die aber keine Readings sind, nennt man Internals. Sie werden abenfalls als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielswiese <code>$hash->{INTERVAL}</code> für ein Abfrageintervall, das beim Define-Befehl übergeben wurde und als Internal gespeichert wird. Internals werden jedoch im Gegensatz zu Readings nicht im statefile zwischengespeichert.

== Attribute ==
Parameter eines Moduls können als so genannte Attribute gesetzt und damit dem Modul zur Verfügung gestellt werden. Attribute werden zusammen mit der Definition der Geräte beim Speichern der aktuellen Konfiguration von FHEM in die Konfigurationsdate geschrieben. Zur Laufzeit werden sie in der globalen Datenstruktur <code>$attr{$name}</code> gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielswiese mit <code>$attr{$name}{header}</code> adressiert (<code>$attr{$name}->{'header'}</code> wäre eine alternative aber unübliche Schreibweise für die selber Variable).

Zum Auslesen solcher Attribute sollte die Funktion <code>AttrVal($$$)</code> verwendet werden.

Welche Attribute ein Modul unterstützt sollte in der Funktion <code>X_Initialize</code> durch Setzen der Variable <code>$hash->{AttrList}</code> bekannt gemacht werden (siehe unten). Wenn beim Setzen von Attributen die Werte geprüft werden sollen oder zusätzliche Funktionalität implementiert werden muss, dann kann dies in der Funktion <code>X_Attr</code> (siehe unten) implementiert werden.

== Die wichtigsten Funktionen in einem Modul ==
Eine typische Grundfunktion eines einfachen Moduls ist das Auslesen von Werten von einem physischen Gerät und Bereitstellen dieser Werte innerhalb von FHEM als Readings. Das Geräte könnte beispielsweise an einem USB-Port angeschlossen sein. Folgende Funktionen könnte man beispielsweise in einem Modul mit Namen X implementieren:
* X_Initialize (initialisiert das Modul und gibt de Namen der zusätzlichen Funktionen bekannt)
* X_Define (wird beim <code>define</code> aufgerufen
* X_Undef (wird beim Löschen einer Geräteinstanz aufgerufen - Gegenteil zu <code>define</code>)
* X_Set (wird beim Befehl <code>set</code> aufgerufen um Daten an das Gerät zu senden)
* X_Get (wird beim Befehl <code>get</code> aufgerufen um Daten vom Gerät abzufragen)
* X_Attr (wird beim Befehl <code>attr</code> aufgerufen um beispielsweise Werte zu prüfen)
* X_Read (wird vom globalen select aufgerufen, falls Daten zur Verfuegung stehen)
* X_Parse (wird bei zweistufigen Modulen vom Dispatch aufgerufen und muss hier noch beschrieben werden)
* X_Ready (wird unter windows als ReadFn-Erstatz benoetigt bzw. um zu pruefen, ob ein Geraet wieder eingesteckt ist)
* X_Notify (falls man benachrichtigt werden will)
* X_Rename (falls ein Gerät umbenannt wird)

Die Funktionen werden im folgenden beschrieben (soweit diese Seite inzwischen vollständig ist):

=== X_Initialize ===

<pre>
sub X_Initialize($)
{
my ($hash) = @_;
...
</pre>

Das <code>X</code> im Namen muss dabei auf den Namen des Moduls bzw. des definierten Gerätetyps geändert werden. Im Modul mit der Datei <code>36_JeeLink.pm</code> beispielsweise ist der Name der Funktion <code>JeeLink_Initialize</code>. Die Funktion wird von Fhem.pl nach dem Laden des Moduls aufgerufen und bekommt einen Hash für das Modul als zentrale Datenstruktur übergeben.
Die Initialize-Funktion setzt dann weitere Funktionsnamen, die im Modul implementiert sind, in diesen Hash:

<pre>
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
</pre>

<code>X</code> ist wieder durch den Modulnamen ohne die vorangestellte Zahl zu ersetzen.
Entsprechend können auch die Funktionen <code>X_Read</code>, <code>X_Parse</code> etc. durch Zuweisung an <code>$hash->{ReadFn}</code> etc. bekannt gemacht werden.

Darüber hinaus sollten die vom Modul unterstützen Attribute definiert werden:

<pre>
$hash->{AttrList} =
"do_not_notify:1,0 " .
"header " .
$readingFnAttributes;
</pre>

In Fhem.pl werden dann die entsprechenden Werte beim Aufruf eines <code>attr</code>-Befehls in die globale Datenstruktur <code>$attr{$name}</code>, z.B. <code>$attr{$name}{header}</code> für das Attribut <code>header</code> gespeichert. Falls im Modul weitere Aktionen oder Prüfungen beim Setzen eines Attributs nötig sind, dann kann wie im Beispiel oben die Funktion <code>X_Attr</code> implementiert und in der Initialize-Funktion bekannt gemacht werden.

Die Variable <code>$readingFnAttributes</code>, die im obigen Beispiel an die Liste der unterstützten Attribute angefügt wird, definiert Attributnamen, die dann verfügbar werden wenn das Modul zum Setzen von Readings die Funktionen readingsBeginUpdate, readingsBulkUpdate, readingsEndUpdate oder readingsSingleUpdate verwendet. In diesen Funktionen werden Attribute wie <code>event-min-interval</code> oder auch <code>event-on-change-reading</code> ausgewertet. Für Details hierzu siehe commandref.

=== X_Define ===
Die Define-Funktion eines Moduls wird von Fhem aufgerufen wenn der Define-Befehl für ein Geräte ausgeführt wird und das Modul bereits geladen und mit der Initialize-Fubktion initialisiert ist. Sie ist typischerweise dazu da, die übergebenen Parameter zu prüfen und an geeigneter Stelle zu speichern sowie einen Kommunikationsweg zum Gerät zu öffnen (z.B. TCP-Verbindung, USB-Schnittstelle o.ä.)
Sie beginnt typischerweise mit:

<pre>
sub HTTPMOD_Define($$)
{
my ( $hash, $def ) = @_;
my @a = split( "[ \t][ \t]*", $def );
...
</pre>

Als Übergabeparameter bekommt die Define-Funktion den Hash der Geräteinstanz sowie den Rest der Parameter, die im Befehl angegeben wurden. Welche und wie viele Parameter
akzeptiert werden ist Sache dieser Funktion. Im obigen Beispiel wird alles nach dem übergebenen Hash in ein Array aufgeteilt und so können die vom Modul bzw. der Define-Funktion erwarteten Werte über das Array der Reihe nach verarbeitet werden:

<pre>
my $name = $a[0];
my $url = $a[2];
my $inter = 300;
if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5, default is 300";
}
}
</pre>

Damit die übergebenen Werte auch anderen Funktionen zur Verfügung stehen und an die jeweilige Geräteinstanz gebunden sind, werden die Werte typischerwiese als Internals im Hash der Geräteinstanz gespeichert:

<pre>
$hash->{url} = $url;
$hash->{Interval} = $inter;
</pre>

Wenn eine physische Schnittstelle geöffnet werden soll und dann bei verfügbaren Eingabedaten eine Lese-Funktion von Fhem aufgerufen werden soll, dann kann man in der Define-Funktion die Funktion DevIo_OpenDev aufrufen, die sich um alles weitere kümmert. Sie öffnet die Schnittstelle und fügt den Filedeskriptor an die globale Liste offener Verbindungen (selectlist / readyfnlist) an. Damit kann Fhem in seiner Hauptschleife erkennen, von welchem Gerät Daten bereit stehen und die zuständigen Funktionen aufrufen:

<pre>
my $ret = DevIo_OpenDev( $hash, 0, "X_DevInit" );
</pre>

Die optionale Funktion <code>X_DevIni</code>t wird zur weiteren Initialisierung der Verbindung von <code>DevIo_OpenDev</code> aufgerufen. Der zweite Übergabeparameter an <code>DevIo_OpenDev</code> (hier <code>0</code>) steht für reopen und wird benötigt, da die Funktion auch aufgerufen wird, wenn ein USB-Geräte beispielsweise im Betrieb aus- und wieder eingesteckt wird. In diesem Fall wird die Funktion mit <code>1</code> aufgerufen.

=== X_Undef ===

Die <code>Undef</code>-Funktion ist das Gegenstück zur <code>Define</code>-Funktion und wird aufgerufen wenn ein Gerät mit <code>delete</code> gelöscht wird. Entsprechend müssen in der Funktion typische Aufräumarbeiten durchgeführt werden wie das saubere Schließen von Verbindungen oder das entfernen von internen Timern sofern diese im Modul zum Pollen verwendet wurden (siehe später).

Beispiel:
<pre>
sub WKRCD4_Undef($$)
{
my ( $hash, $arg ) = @_;
DevIo_CloseDev($hash);
RemoveInternalTimer($hash);
return undef;
}
</pre>

=== X_Get ===
Die Get-Funktion wird aufgerufen wenn der Fhem-Befehl <code>get</code> mit einem Gerät dieses Moduls ausgeführt wird. Mit <code>get</code> werden typischerweise Werte von einem Gerät abgefragt. Einige Module verwenden für diese Funktion einen Hash im Modul, der die möglichen <code>get</code>-Optionen mit zusätzlichen Werten definiert:

<pre>
my X_gets = (
"TempSoll" => "XY",
"Steilheit" => "Z"
);
</pre>
In der Get-Funktion selbst werden dann die übergebenen Parameter gegen diesen Hash geprüft.

Beispiel:

<pre>
sub X_Get($@)
{
my ( $hash, @a ) = @_;
return "\"get X\" needs at least one argument" if ( @a < 2 );
my $name = shift @a;
my $opt = shift @a;
if(!$X_gets{$opt}) {
my @cList = keys %X_gets;
return "Unknown argument $attr, choose one of " . join(" ", @cList);
}
...
</pre>

Die Ausgabe der Meldung mit <code>... choose one of ...</code> ist dabei wichtig, da sie im GUI-Modul verwendet wird um die möglichen <code>get</code>-Optionen zu ermitteln und als Auswahl anzubieten. Im weiteren Verlauf der Get-Funktion könnte man dann mit dem physischen Gerät kommunizieren und den gefragten Wert abfragen und diesen als Return-Wert der Get-Funktion zurückgeben.

=== X_Set ===
Die Set-Funktion ist das Gegenteil zur Get-Funktion. Sie ist dafür gedacht, Werte zum physischen Gerät zu schicken. Falls nur interne Werte im Modul gesetzt werden sollen, so sollte statt Set die Attr-Funktion verwendet werden. Attribute werden bei Save-Config auch in der Fhem.cfg gesichert. Set-Befehle nicht.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch nach dem Namen der Option auch den zu setzenden Wert übergeben.

Beispiel:
<pre>
sub X_Set($@)
{
my ( $hash, @a ) = @_;
return "\"set X\" needs at least an argument" if ( @a < 2 );
my $name = shift @a;
my $opt = shift @a;
my $arg = join("", @a);

if(!defined($X_sets{$attr})) {
my @cList = keys %X_sets;
return "Unknown argument $attr, choose one of " . join(" ", @cList);
}
</pre>

Den einzelnen Befehlen, die das Modul versteht und die via set <name> <cmd> <arg1> übergeben werden kann man bei der Rückgabe auch zulässige Auswahlwerte für Kommando Argumente mitgeben. Aus diesen Auswahlwerten erzeugt FHEM-Web dann z.B. Drop-Down Boxen in der Detailansicht, mit denen der Anwender die jeweiligen Argumente auswählen kann. Dabei ist jeweils vor dem Doppelpunkt der Name des Kommandoes anzugeben und nach dem Doppelpunkt der jeweilige Auswahlwert.
Es gibt dabei folgende Möglichkeiten:

'''noArg'''

es werden keine weiteren Argumente mehr benötigt
<pre>on:noArg</pre>

'''slider'''

es wird ein Schieberegler für den Wert angezeigt. Dabei Minimum, Schrittweite und Maximum angeben
<pre>dim:slider,0,1,100</pre>

'''RGB'''

es wird ein Colorpicker angezeigt, der dem Anwender die Auswahl einer Farbe ermöglicht. Bitte dazu auch den Wiki Artikel zum Colorpicker lesen, da im Modul noch weiterer Code eingefügt werden muß.
<pre>rgb:colorpicker,RGB</pre>

'''Liste'''

Mit Kommata getrennte Werte ergeben eine Drop-Down Liste, mit der der User die Werte auswählen kann
<pre>loglevel:1,2,3,4,5
timer:30,120,300
mode:verbose,ultra,relaxed</pre>

'''Leer'''

Wird kein Doppelpunkt zum Kommando angegeben, so wird eine Eingabezeile angezeigt, die die freie Eingabe eines Wertes erlaubt

Damit die jeweiligen Auswahllisten bereits mit dem korrekten Wert, der aktuell im Modul gesetzt ist, befüllt wird, muß dass Get Kommando im Modul implementiert sein und den jeweiligen Wert zurück liefern.
Am Beispiel des Sliders oben:
der Wert heisst dim und soll per Slider dargestellt sein. Damit der aktuelle Wert des dim im Slider in der Oberfläche bereits richtig voreingestellt ist, sollte die Get Funktion auf Anfrage nach dim auch den aktuellen Wert von dim zurück liefern.

'''Hinweise'''

- bei den üblichen Kommandos wie on off sollte man auf noArg verzichten, da diese durch FHEMWeb automatisch in der Raumübersicht angezeigt werden. Wenn man hier noArg spezifiziert, so werden diese nicht neben dem Modul in der Raumübersicht angezeigt und der User muß sich diese vie webCmd dann erst selbst definieren, was natürlich unschön ist

- der User kann sich in der Raumübersicht nach wie vor via webCmd eine entsprechende Steuerung anlegen.

=== X_Attr ===
Die Attr-Funktion implementiert Prüfungen der bei einem <code>attr</code> übergebenen Werte und eventuell zusätzliche Aktionen wenn ein Attribut gesetzt wird. Die Liste der möglichen Attribute wird in der <code>X_Initialize-Funktion</code> definiert (siehe oben). Fhem ruft bei einem Attr-Befehl die zuständige <code>X-Attr-Funktion</code> auf und wenn diese keine Fehlermelhung sondern <code>undef</code> zurückgibt, dann schreibt fhem.pl die bei <code>attr</code> angegebenen Werte in die jeweilige Datenstruktur <code>$attr{$name}-> ...</code>

Beispiel:

<pre>
X_Attr(@)
{
my ($cmd,$name,$aName,$aVal) = @_;
# $cmd can be "del" or "set"
# $name is device name
# aName and aVal are Attribute name and value
if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aVal/ };
if ($@) {
Log3 $name, 3, "X: Invalid regex in attr $name $aName $aVal: $@";
return "Invalid Regex $aVal";
}
}
}
return undef;
}
</pre>

Die Attr-Funktion bekommt nicht den Hash der Geräteinstanz übergeben, da sie ja auch keine Werte dort speichern muss sondern den Befehl <code>set</code> oder <code>del</code> je nachdem ob ein Attribut gesetzt oder gelöscht wird, den Namen der Geräteinstanz sowie den Namen des Attributs und seinen Wert.
Im obigen Beispiel wird für ein Attribut mit Namen Regex geprüft ob die Regex fehlerhaft ist. Falls sie ok ist, wird undef zurück gegegen und fhem.pl speichert den Wert des Attributs.

=== X_Read ===

Die X_Read-Funktion wird aus der Hauptschleife von FHEM aus aufgerufen wenn das Gerät, für das das Modul zuständig ist, Daten bereit gestellt hat, die gelesen werden können. Im folgenden Beispiel wird über eine serielle Schnittstelle (beziehungsweise über einen USB-To-Seriell-Konverter) von einem angeschlossenen Gerät gelesen. Dazu werden die bisher verfügbaren Daten mit der Funktion <code>DevIo_SimpleRead</code> gelesen. Da die Übertragung möglicherweise noch nicht vollständig ist, kann es sein, dass kurz darauf die X_Read-Funktion wieder aufgerufen wird und ein weiterer Teil oder der Rest der Daten gelesen werden kann.
Die Funktion muss daher prüfen ob schon alle erwarteten Daten angekommen sind und gegebenenfalls die bisher gelesenen Daten zwischenspeichern. Es bietet sich an, dies im Hash der Geräteinstanz zu tun. Im Beispiel ist dies <code>$hash->{buffer}</code> an den die jeweils gelesenen Daten angehängt werden bis die folgende Prüfung ein für das jeweilige Protokoll passendes Frame identifiziert.

<pre>
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# read from serial device
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );

# convert to hex string to make parsing with regex easier
$hash->{buffer} .= unpack ('H*', $buf);
Log3 $name, 5, "Current buffer content: " . $hash->{buffer};

# did we already get a full frame?
if ($hash->{buffer} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)")
...
</pre>

Die zu lesenden Nutzdaten können dann je nach Protokoll des Geräts beispielsweise an einer festgelegten Stelle im Frame (dann in <code>$hash->{buffer}</code>) stehen oder aus dem Kontext mit einem Regex-Match extrahiert werden und in Readings gespeichert werden (siehe unten).

=== X_Ready ===

muss noch beschrieben werden.

Beispiel:
<pre>
sub X_Ready($)
{
my ($hash) = @_;
return DevIo_OpenDev($hash, 1, undef )
if ( $hash->{STATE} eq "disconnected" );

# This is relevant for windows/USB only
my $po = $hash->{USBDev};
my ( $BlockingFlags, $InBytes, $OutBytes, $ErrorFlags ) = $po->status;
return ( $InBytes > 0 );
}
</pre>

== Lesen von Geräte und Speichern der Werte in Readings ==

FHEM führt Module normalerweise nicht parallel aus. Daher wäre es ungünstig wenn Module Werte von einem Gerät abfragen und dann auf die Antwort des Geräts warten. In dieser Zeit wäre der Rest von FHEM blockiert. Die Ein- und Ausgabe sollte ohne Blockieren erfolgen und die Verarbeitung mehrerer Ein- und Ausgabekanäle quasi parallel ermöglichen.

Dafür werden in FHEM zwei zentrale Listen gepflegt, in der die Filedeskriptoren der geöffneten Kommunikatonsverbindungen gespeichert sein können. Auf Linux- bzw. Unix-basierten Plattformen wird der select-Befehl des Betriebssystems verwendet und entsprechend gibt es in FHEM eine selectlist, in der die Filedeskriptoren der Geräedateien (z.B. /dev/ttyUSBx etc.) gespeichert sind.

In der zentralen Schleife von fhem.pl wird vereinfacht gesagt mit select überwacht, ob über eine der geöffneten Schnittstellen Daten zum Lesen anstehen. Wenn dies der Fall ist, dann wird die Lesefunktion (X_Read) des zuständigen Moduls aufgerufen, damit es die Daten entgegennimmt und die Schleife wird weiter ausgeführt.

Auf Windows-Systemen funktioniert dies anders. Hier können USB/Seriell-Geräte nicht per select überwacht werden. In FHEM unter Windows werden daher diese Schnittstellen kontinuierlich abgefragt ob Daten bereitstehen. Dafür müssen Module zusätzlich zur Lesefunktion eine Abfragefunktion (X_Ready) implementieren, die prüft ob Daten zum Lesen anstehen. Auch auf Linux/Unix-Plattformen hat diese Funktion eine Aufgabe. Falls nämlich eine Schnittstelle ausfällt beziehungsweise ein CUL oder USB-zu-Seriell Adapter ausgesteckt wird, dann wird über diese Funktion regelmäßig geprüft ob die Schnittstelle wieder verfügbar wird.

Innerhalb der eigentlichen Lesefunktion (X_Read) werden dann die Daten vom zugehörigen Gerät gelesen, das nötige Protokoll implementiert und Werte in Readings geschrieben.

Zum Setzen von Readings ist es wie oben schon erwähnt empfehlenswert die Funktionen <code>readingsBeginUpdate</code>, <code>readingsBulkUpdate</code>, <code>readingsEndUpdate</code> oder <code>readingsSingleUpdate</code> aufzurufen. Dabei kann man auch angeben, ob dabei ein Event ausgelöst werden soll oder nicht. Events erzeugen spürbare Last auf dem System (siehe NotifyFn), das Ändern von Readings ohne dass dabei Events erzeugt werden jedoch nicht.

Eine Sequenz zum Setzen von Readings könnte folgendermaßen aussehen:

<pre>
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</pre>

Die <code>1</code> beim Aufruf von <code>readingsEndUpdate</code> gibt an, dass Events ausgelöst werden, die auf Veränderungen der Readings reagieren.

== Pollen von Geräten ==
Wenn Geräte von sich aus keine Informationen senden sondern abgefragt werden müssen, kann man im Modul die Funktion <code>InternalTimer<code> verwenden. Man übergibt ihr den Zeitpunkt für den nächsten Aufruf, den Namen der Funktion, die aufgerufen werden soll, die zu übergebenden Parameter und ein Flag ob der erste Aufruf verzögert werden soll falls die Initialiserung des Geräts noch nicht abgeschlossen ist.

Beispielsweise könnte man für das Abfragen eines Geräts in der Define-Funktion den Timer folgendermassen setzen:

<pre>
# initial request after 2 secs, there timer is set to interval for further update
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash, 0);
</pre>

in der Funktion <code>X_GetUpdate</code> selbst wird dann der Timer neu gesetzt, so dass nach einem Intervall die Funktion erneut aufgerufen wird:

<pre>
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash, 1);
Log3 $name, 4, "X: GetUpdate called ...";
</pre>

Im weiteren Verlauf der Funktion könnte man dann das Gerät abfragen und die abgefragten Werte in Readings speichern. Falls das Abfragen der Werte jedoch zu einer Verzögerung und damit zu einer Blockade von FHEM führen kann, ist es möglich, in der GetUpdate-Funktion nur die Aufforderung zum Senden bestimmter Daten an das angeschlossene Gerät zu senden und dann das Lesen über die oben beschriebene Read-Funktion zu implementieren, die beim Anstehen von Daten aufgerufen wird.

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Protokollmeldung in die Fhem-Logdatei zu schreiben, wird die Funktion Log3 aufgerufen:
<pre>
Log3 $name, 3, "X: Problem erkannt ...";
</pre>

Die Parameter der Funktion Log3 sind der Name oder der Hash der Geräteinstanz, das Verbose-Level, in dem die Meldung sichtbar sein soll und die Meldung selbst.
Den Namen der Geräteinstanz kann man in den Funktionen, die den Hash übergeben bekommen einfach aus diesem Hash nehmen:

<pre>
my $name = $hash->{NAME};
</pre>

Um für ein neues Modul das Verbose-Level zu erhöhen, ohne gleich für das Gesamte FHEM alle Meldungen zu erzeugen kann man den Befehl
<code>attr gerätename verbose</code> verwenden. Beispielsweise <code>attr PM verbose 5</code>

Damit bietet es sich an im Modul Meldungen, die im normalen Betrieb nicht benötigt werden, beim Aufruf von Log3 mit dem Level 4 oder 5 anzugeben. Wenn man dann bei der Fehlersuche mehr Meldungen sehen möchte, erhöht man mit attr X verbose das Level für das betroffene Gerät.

== Noch zu beschreiben ==
* Zweistufiges Modell für Module
* Funktion X_Ready ...
* FW_summaryFn (wird von FHEMWEB aufgerufen fuer Raum-Uebersicht)
* FW_detailFn (wird von FHEMWEB aufgerufen fuer Detail-Ansicht)
* Bei der Beschreibung der von SetFn/GetFn zurueckgelieferten Meldung: Modifier fuer FHEMWEB wie :noArg, :slider, etc.
-->2014-01-14: done. Bitte um Review der Beschreibung

[[Kategorie:Development]]

DevelopmentModuleIntro

2014-01-14T13:17:30Z

Fhemrocks: /* X_Set */

== Einleitung ==
Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden.
Insbesondere beschreibt der Text derzeit nur einstufige Module. Die Abgrenzung zu zweistufigen Modulen und deren Eigenschaften sollte noch ergänzt werden.

Um neue Geräte in FHEM verfügbar zu machen, kann man ein eigenes Modul in Perl schreiben, das automatisch von FHEM geladen wird, wenn ein passendes Gerät in FHEM definiert wird. Das Modul definiert dann wie mit dem Gerät kommuniziert wird, stellt Werte ("Readings") innerhalb von FHEM zur Verfügung oder erlaubt es das Gerät mit "Set"-Befehlen zu beeinflussen. Dieser Text soll den Einstieg in die Entwicklung eigener Module erleichtern.

Mit dem FHEM-Befehl "define", der typischerweise in die zentrale Konfigurationsdatei fhem.cfg eingetragen wird, werden Geräte in FHEM definiert. Der Befehl sorgt dafür dass ein neues Modul bei Bedarf geladen wird und die Initialisierungsfunktion des Moduls aufgerufen wird.

Damit das funktioniert müssen der Name des Geräts, der Name des Moduls und der Name der Initialisierungsfunktion zueinander passen. Das folgende Beispiel soll dies verdeutlichen:

Ein Jeelink USB-Stick in einer Fritz-Box könnte beispielsweise mit dem Befehl <code>define JeeLink1 JeeLink /dev/ttyUSB0@57600</code> definiert werden.

In der fhem.pl wird der define-Befehl verarbeitet, geprüft, ob ein Modul mit Namen JeeLink schon geladen ist und falls nicht ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (bei einer FritzBox z.B. /var/media/ftp/fhem/FHEM) gesucht und dann geladen.
Danach wird die Funktion JeeLink_Initialize aufgerufen.
Die Moduldatei muss also nach dem Namen des Geräts benannt werden und eine Funktion mit dem Namen des Geräts und einer _initialize Funktion enthalten.
In der Initialisierungsfunktion des Moduls werden dann die Namen der aller weiteren Funktionen des Moduls, die von fhem.pl aus aufgerufen werden, bekannt gemacht. Dazu wird der Hash - das ist die zentrale Datenstruktur für jede Instanz eines Gerätes - mit entsprechenden Werten gefüllt.

== Der Hash einer Geräteinstanz ==
Der zentrale Speicherort für Informationen einer Geräteinstanz ist ein Hash, der seinerseits in fhem.pl von einem globalen Hash referenziert wird.

<code>$defs{$d}</code> in fhem.pl verweist auf den Hash der Geräteinstanz mit Namen <code>$d</code>. Diesen Hash bekommen die Funktionen eines Moduls oft von fhem.pl übergeben. In ihm stehen beispielsweise die internen Werte des Geräts, die im GUI als "Internals" angezeigt werden oder die Readings des Geräts.

<code>$hash{NAME}</code> enthält beispielsweise den Namen der Geräteinstanz, <code>$hash{TYPE}</code> enthält den Namen des Typs des Geräts, der ja auch für den Namen des Moduls verwendet wird.

Ein Abfrageintervall, das beim define eines Geräts an die define-Funktion im Modul übergeben wird, würde typischerweise als "Internal" in <code>$hash->{INTERVAL}</code> abgelegt.

Die Readings sind hier als weitere Unterstruktur gespeichert, beispielsweise <code>$hash{READINGS}{$ReadingName}{VAL}</code> und <code>$hash{READINGS}{$ReadingName}{TIME}</code>. Innerhalb von fhem.pl könnten die selben Readings beispielsweise über <code>$defs{$d}{READINGS}{$ReadingName}{VAL}</code> adressiert werden, da <code>$defs{$d}</code> ja auf den gleichen Hash verweist, der dann den Modul-Funktionen übergeben wird und innerhalb der Funktionen typischerweise als <code>$hash</code> verwendet wird.

== Readings ==
Werte, die von einem Gerät gelesen werden und in FHEM zur Verfügung stehen werden Readings genannt. Sie werden wie oben beschrieben als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise <code>$hash{READINGS}{$Temp}{VAL}</code> für die Temperatur eines Fühlers, die als Reading gespeichert wurde.
Zum Setzen von Readings (siehe auch unten) ist es empfehlenswert die Funktionen <code>readingsBeginUpdate</code>, <code>readingsBulkUpdate</code>, <code>readingsEndUpdate</code> oder <code>readingsSingleUpdate</code> aufzurufen. Dabei kann man auch angeben, ob dabei ein Event ausgelöst werden soll oder nicht. Events erzeugen spürbare Last auf dem System (siehe NotifyFn), das Ändern von Readings ohne dass dabei Events erzeugt werden jedoch nicht.

für den lesenden Zugriff auf Readings steht die Funktion ReadingsVal($$$) zur Verfügung.

Readings werden im statefile von FHEM automatisch zwischengespeichert, damit sie nach einem Neustart sofort wieder zur Verfügung stehen, auch bevor sie vom Modul neu gesetzt oder aktualisiert werden.

== Internals ==
Werte, die das Modul intern als Teil des Hashes speichert, die aber keine Readings sind, nennt man Internals. Sie werden abenfalls als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielswiese <code>$hash->{INTERVAL}</code> für ein Abfrageintervall, das beim Define-Befehl übergeben wurde und als Internal gespeichert wird. Internals werden jedoch im Gegensatz zu Readings nicht im statefile zwischengespeichert.

== Attribute ==
Parameter eines Moduls können als so genannte Attribute gesetzt und damit dem Modul zur Verfügung gestellt werden. Attribute werden zusammen mit der Definition der Geräte beim Speichern der aktuellen Konfiguration von FHEM in die Konfigurationsdate geschrieben. Zur Laufzeit werden sie in der globalen Datenstruktur <code>$attr{$name}</code> gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielswiese mit <code>$attr{$name}{header}</code> adressiert (<code>$attr{$name}->{'header'}</code> wäre eine alternative aber unübliche Schreibweise für die selber Variable).

Zum Auslesen solcher Attribute sollte die Funktion <code>AttrVal($$$)</code> verwendet werden.

Welche Attribute ein Modul unterstützt sollte in der Funktion <code>X_Initialize</code> durch Setzen der Variable <code>$hash->{AttrList}</code> bekannt gemacht werden (siehe unten). Wenn beim Setzen von Attributen die Werte geprüft werden sollen oder zusätzliche Funktionalität implementiert werden muss, dann kann dies in der Funktion <code>X_Attr</code> (siehe unten) implementiert werden.

== Die wichtigsten Funktionen in einem Modul ==
Eine typische Grundfunktion eines einfachen Moduls ist das Auslesen von Werten von einem physischen Gerät und Bereitstellen dieser Werte innerhalb von FHEM als Readings. Das Geräte könnte beispielsweise an einem USB-Port angeschlossen sein. Folgende Funktionen könnte man beispielsweise in einem Modul mit Namen X implementieren:
* X_Initialize (initialisiert das Modul und gibt de Namen der zusätzlichen Funktionen bekannt)
* X_Define (wird beim <code>define</code> aufgerufen
* X_Undef (wird beim Löschen einer Geräteinstanz aufgerufen - Gegenteil zu <code>define</code>)
* X_Set (wird beim Befehl <code>set</code> aufgerufen um Daten an das Gerät zu senden)
* X_Get (wird beim Befehl <code>get</code> aufgerufen um Daten vom Gerät abzufragen)
* X_Attr (wird beim Befehl <code>attr</code> aufgerufen um beispielsweise Werte zu prüfen)
* X_Read (wird vom globalen select aufgerufen, falls Daten zur Verfuegung stehen)
* X_Parse (wird bei zweistufigen Modulen vom Dispatch aufgerufen und muss hier noch beschrieben werden)
* X_Ready (wird unter windows als ReadFn-Erstatz benoetigt bzw. um zu pruefen, ob ein Geraet wieder eingesteckt ist)
* X_Notify (falls man benachrichtigt werden will)
* X_Rename (falls ein Gerät umbenannt wird)

Die Funktionen werden im folgenden beschrieben (soweit diese Seite inzwischen vollständig ist):

=== X_Initialize ===

<pre>
sub X_Initialize($)
{
my ($hash) = @_;
...
</pre>

Das <code>X</code> im Namen muss dabei auf den Namen des Moduls bzw. des definierten Gerätetyps geändert werden. Im Modul mit der Datei <code>36_JeeLink.pm</code> beispielsweise ist der Name der Funktion <code>JeeLink_Initialize</code>. Die Funktion wird von Fhem.pl nach dem Laden des Moduls aufgerufen und bekommt einen Hash für das Modul als zentrale Datenstruktur übergeben.
Die Initialize-Funktion setzt dann weitere Funktionsnamen, die im Modul implementiert sind, in diesen Hash:

<pre>
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
</pre>

<code>X</code> ist wieder durch den Modulnamen ohne die vorangestellte Zahl zu ersetzen.
Entsprechend können auch die Funktionen <code>X_Read</code>, <code>X_Parse</code> etc. durch Zuweisung an <code>$hash->{ReadFn}</code> etc. bekannt gemacht werden.

Darüber hinaus sollten die vom Modul unterstützen Attribute definiert werden:

<pre>
$hash->{AttrList} =
"do_not_notify:1,0 " .
"header " .
$readingFnAttributes;
</pre>

In Fhem.pl werden dann die entsprechenden Werte beim Aufruf eines <code>attr</code>-Befehls in die globale Datenstruktur <code>$attr{$name}</code>, z.B. <code>$attr{$name}{header}</code> für das Attribut <code>header</code> gespeichert. Falls im Modul weitere Aktionen oder Prüfungen beim Setzen eines Attributs nötig sind, dann kann wie im Beispiel oben die Funktion <code>X_Attr</code> implementiert und in der Initialize-Funktion bekannt gemacht werden.

Die Variable <code>$readingFnAttributes</code>, die im obigen Beispiel an die Liste der unterstützten Attribute angefügt wird, definiert Attributnamen, die dann verfügbar werden wenn das Modul zum Setzen von Readings die Funktionen readingsBeginUpdate, readingsBulkUpdate, readingsEndUpdate oder readingsSingleUpdate verwendet. In diesen Funktionen werden Attribute wie <code>event-min-interval</code> oder auch <code>event-on-change-reading</code> ausgewertet. Für Details hierzu siehe commandref.

=== X_Define ===
Die Define-Funktion eines Moduls wird von Fhem aufgerufen wenn der Define-Befehl für ein Geräte ausgeführt wird und das Modul bereits geladen und mit der Initialize-Fubktion initialisiert ist. Sie ist typischerweise dazu da, die übergebenen Parameter zu prüfen und an geeigneter Stelle zu speichern sowie einen Kommunikationsweg zum Gerät zu öffnen (z.B. TCP-Verbindung, USB-Schnittstelle o.ä.)
Sie beginnt typischerweise mit:

<pre>
sub HTTPMOD_Define($$)
{
my ( $hash, $def ) = @_;
my @a = split( "[ \t][ \t]*", $def );
...
</pre>

Als Übergabeparameter bekommt die Define-Funktion den Hash der Geräteinstanz sowie den Rest der Parameter, die im Befehl angegeben wurden. Welche und wie viele Parameter
akzeptiert werden ist Sache dieser Funktion. Im obigen Beispiel wird alles nach dem übergebenen Hash in ein Array aufgeteilt und so können die vom Modul bzw. der Define-Funktion erwarteten Werte über das Array der Reihe nach verarbeitet werden:

<pre>
my $name = $a[0];
my $url = $a[2];
my $inter = 300;
if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5, default is 300";
}
}
</pre>

Damit die übergebenen Werte auch anderen Funktionen zur Verfügung stehen und an die jeweilige Geräteinstanz gebunden sind, werden die Werte typischerwiese als Internals im Hash der Geräteinstanz gespeichert:

<pre>
$hash->{url} = $url;
$hash->{Interval} = $inter;
</pre>

Wenn eine physische Schnittstelle geöffnet werden soll und dann bei verfügbaren Eingabedaten eine Lese-Funktion von Fhem aufgerufen werden soll, dann kann man in der Define-Funktion die Funktion DevIo_OpenDev aufrufen, die sich um alles weitere kümmert. Sie öffnet die Schnittstelle und fügt den Filedeskriptor an die globale Liste offener Verbindungen (selectlist / readyfnlist) an. Damit kann Fhem in seiner Hauptschleife erkennen, von welchem Gerät Daten bereit stehen und die zuständigen Funktionen aufrufen:

<pre>
my $ret = DevIo_OpenDev( $hash, 0, "X_DevInit" );
</pre>

Die optionale Funktion <code>X_DevIni</code>t wird zur weiteren Initialisierung der Verbindung von <code>DevIo_OpenDev</code> aufgerufen. Der zweite Übergabeparameter an <code>DevIo_OpenDev</code> (hier <code>0</code>) steht für reopen und wird benötigt, da die Funktion auch aufgerufen wird, wenn ein USB-Geräte beispielsweise im Betrieb aus- und wieder eingesteckt wird. In diesem Fall wird die Funktion mit <code>1</code> aufgerufen.

=== X_Undef ===

Die <code>Undef</code>-Funktion ist das Gegenstück zur <code>Define</code>-Funktion und wird aufgerufen wenn ein Gerät mit <code>delete</code> gelöscht wird. Entsprechend müssen in der Funktion typische Aufräumarbeiten durchgeführt werden wie das saubere Schließen von Verbindungen oder das entfernen von internen Timern sofern diese im Modul zum Pollen verwendet wurden (siehe später).

Beispiel:
<pre>
sub WKRCD4_Undef($$)
{
my ( $hash, $arg ) = @_;
DevIo_CloseDev($hash);
RemoveInternalTimer($hash);
return undef;
}
</pre>

=== X_Get ===
Die Get-Funktion wird aufgerufen wenn der Fhem-Befehl <code>get</code> mit einem Gerät dieses Moduls ausgeführt wird. Mit <code>get</code> werden typischerweise Werte von einem Gerät abgefragt. Einige Module verwenden für diese Funktion einen Hash im Modul, der die möglichen <code>get</code>-Optionen mit zusätzlichen Werten definiert:

<pre>
my X_gets = (
"TempSoll" => "XY",
"Steilheit" => "Z"
);
</pre>
In der Get-Funktion selbst werden dann die übergebenen Parameter gegen diesen Hash geprüft.

Beispiel:

<pre>
sub X_Get($@)
{
my ( $hash, @a ) = @_;
return "\"get X\" needs at least one argument" if ( @a < 2 );
my $name = shift @a;
my $opt = shift @a;
if(!$X_gets{$opt}) {
my @cList = keys %X_gets;
return "Unknown argument $attr, choose one of " . join(" ", @cList);
}
...
</pre>

Die Ausgabe der Meldung mit <code>... choose one of ...</code> ist dabei wichtig, da sie im GUI-Modul verwendet wird um die möglichen <code>get</code>-Optionen zu ermitteln und als Auswahl anzubieten. Im weiteren Verlauf der Get-Funktion könnte man dann mit dem physischen Gerät kommunizieren und den gefragten Wert abfragen und diesen als Return-Wert der Get-Funktion zurückgeben.

=== X_Set ===
Die Set-Funktion ist das Gegenteil zur Get-Funktion. Sie ist dafür gedacht, Werte zum physischen Gerät zu schicken. Falls nur interne Werte im Modul gesetzt werden sollen, so sollte statt Set die Attr-Funktion verwendet werden. Attribute werden bei Save-Config auch in der Fhem.cfg gesichert. Set-Befehle nicht.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch nach dem Namen der Option auch den zu setzenden Wert übergeben.

Beispiel:
<pre>
sub X_Set($@)
{
my ( $hash, @a ) = @_;
return "\"set X\" needs at least an argument" if ( @a < 2 );
my $name = shift @a;
my $opt = shift @a;
my $arg = join("", @a);

if(!defined($X_sets{$attr})) {
my @cList = keys %X_sets;
return "Unknown argument $attr, choose one of " . join(" ", @cList);
}
</pre>

Den einzelnen Befehlen, die das Modul versteht und die via set <name> <cmd> <arg1> übergeben werden kann man bei der Rückgabe auch zulässige Auswahlwerte für Kommando Argumente mitgeben. Aus diesen Auswahlwerten erzeugt FHEM-Web dann z.B. Drop-Down Boxen in der Detailansicht, mit denen der Anwender die jeweiligen Argumente auswählen kann. Dabei ist jeweils vor dem Doppelpunkt der Name des Kommandoes anzugeben und nach dem Doppelpunkt der jeweilige Auswahlwert.
Es gibt dabei folgende Möglichkeiten:

'''noArg'''

es werden keine weiteren Argumente mehr benötigt
<pre>on:noArg</pre>

'''slider'''

es wird ein Schieberegler für den Wert angezeigt. Dabei Minimum, Schrittweite und Maximum angeben
<pre>dim:slider,0,1,100</pre>

'''RGB'''

es wird ein Colorpicker angezeigt, der dem Anwender die Auswahl einer Farbe ermöglicht. Bitte dazu auch den Wiki Artikel zum Colorpicker lesen, da im Modul noch weiterer Code eingefügt werden muß.
<pre>rgb:colorpicker,RGB</pre>

'''Liste'''

Mit Kommata getrennte Werte ergeben eine Drop-Down Liste, mit der der User die Werte auswählen kann
<pre>loglevel:1,2,3,4,5
timer:30,120,300
mode:verbose,ultra,relaxed</pre>

'''Leer'''

Wird kein Doppelpunkt zum Kommando angegeben, so wird eine Eingabezeile angezeigt, die die freie Eingabe eines Wertes erlaubt

Damit die jeweiligen Auswahllisten bereits mit dem korrekten Wert, der aktuell im Modul gesetzt ist, befüllt wird, muß dass Get Kommando im Modul implementiert sein und den jeweiligen Wert zurück liefern.
Am Beispiel des Sliders oben:
der Wert heisst dim und soll per Slider dargestellt sein. Damit der aktuelle Wert des dim im Slider in der Oberfläche bereits richtig voreingestellt ist, sollte die Get Funktion auf Anfrage nach dim auch den aktuellen Wert von dim zurück liefern.

'''Hinweise'''

- bei den üblichen Kommandos wie on off sollte man auf noArg verzichten, da diese durch FHEMWeb automatisch in der Raumübersicht angezeigt werden. Wenn man hier noArg spezifiziert, so werden diese nicht neben dem Modul in der Raumübersicht angezeigt und der User muß sich diese vie webCmd dann erst selbst definieren, was natürlich unschön ist

- der User kann sich in der Raumübersicht nach wie vor via webCmd eine entsprechende Steuerung anlegen.

=== X_Attr ===
Die Attr-Funktion implementiert Prüfungen der bei einem <code>attr</code> übergebenen Werte und eventuell zusätzliche Aktionen wenn ein Attribut gesetzt wird. Die Liste der möglichen Attribute wird in der <code>X_Initialize-Funktion</code> definiert (siehe oben). Fhem ruft bei einem Attr-Befehl die zuständige <code>X-Attr-Funktion</code> auf und wenn diese keine Fehlermelhung sondern <code>undef</code> zurückgibt, dann schreibt fhem.pl die bei <code>attr</code> angegebenen Werte in die jeweilige Datenstruktur <code>$attr{$name}-> ...</code>

Beispiel:

<pre>
X_Attr(@)
{
my ($cmd,$name,$aName,$aVal) = @_;
# $cmd can be "del" or "set"
# $name is device name
# aName and aVal are Attribute name and value
if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aVal/ };
if ($@) {
Log3 $name, 3, "X: Invalid regex in attr $name $aName $aVal: $@";
return "Invalid Regex $aVal";
}
}
}
return undef;
}
</pre>

Die Attr-Funktion bekommt nicht den Hash der Geräteinstanz übergeben, da sie ja auch keine Werte dort speichern muss sondern den Befehl <code>set</code> oder <code>del</code> je nachdem ob ein Attribut gesetzt oder gelöscht wird, den Namen der Geräteinstanz sowie den Namen des Attributs und seinen Wert.
Im obigen Beispiel wird für ein Attribut mit Namen Regex geprüft ob die Regex fehlerhaft ist. Falls sie ok ist, wird undef zurück gegegen und fhem.pl speichert den Wert des Attributs.

=== X_Read ===

Die X_Read-Funktion wird aus der Hauptschleife von FHEM aus aufgerufen wenn das Gerät, für das das Modul zuständig ist, Daten bereit gestellt hat, die gelesen werden können. Im folgenden Beispiel wird über eine serielle Schnittstelle (beziehungsweise über einen USB-To-Seriell-Konverter) von einem angeschlossenen Gerät gelesen. Dazu werden die bisher verfügbaren Daten mit der Funktion <code>DevIo_SimpleRead</code> gelesen. Da die Übertragung möglicherweise noch nicht vollständig ist, kann es sein, dass kurz darauf die X_Read-Funktion wieder aufgerufen wird und ein weiterer Teil oder der Rest der Daten gelesen werden kann.
Die Funktion muss daher prüfen ob schon alle erwarteten Daten angekommen sind und gegebenenfalls die bisher gelesenen Daten zwischenspeichern. Es bietet sich an, dies im Hash der Geräteinstanz zu tun. Im Beispiel ist dies <code>$hash->{buffer}</code> an den die jeweils gelesenen Daten angehängt werden bis die folgende Prüfung ein für das jeweilige Protokoll passendes Frame identifiziert.

<pre>
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# read from serial device
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );

# convert to hex string to make parsing with regex easier
$hash->{buffer} .= unpack ('H*', $buf);
Log3 $name, 5, "Current buffer content: " . $hash->{buffer};

# did we already get a full frame?
if ($hash->{buffer} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)")
...
</pre>

Die zu lesenden Nutzdaten können dann je nach Protokoll des Geräts beispielsweise an einer festgelegten Stelle im Frame (dann in <code>$hash->{buffer}</code>) stehen oder aus dem Kontext mit einem Regex-Match extrahiert werden und in Readings gespeichert werden (siehe unten).

=== X_Ready ===

muss noch beschrieben werden.

Beispiel:
<pre>
sub X_Ready($)
{
my ($hash) = @_;
return DevIo_OpenDev($hash, 1, undef )
if ( $hash->{STATE} eq "disconnected" );

# This is relevant for windows/USB only
my $po = $hash->{USBDev};
my ( $BlockingFlags, $InBytes, $OutBytes, $ErrorFlags ) = $po->status;
return ( $InBytes > 0 );
}
</pre>

== Lesen von Geräte und Speichern der Werte in Readings ==

FHEM führt Module normalerweise nicht parallel aus. Daher wäre es ungünstig wenn Module Werte von einem Gerät abfragen und dann auf die Antwort des Geräts warten. In dieser Zeit wäre der Rest von FHEM blockiert. Die Ein- und Ausgabe sollte ohne Blockieren erfolgen und die Verarbeitung mehrerer Ein- und Ausgabekanäle quasi parallel ermöglichen.

Dafür werden in FHEM zwei zentrale Listen gepflegt, in der die Filedeskriptoren der geöffneten Kommunikatonsverbindungen gespeichert sein können. Auf Linux- bzw. Unix-basierten Plattformen wird der select-Befehl des Betriebssystems verwendet und entsprechend gibt es in FHEM eine selectlist, in der die Filedeskriptoren der Geräedateien (z.B. /dev/ttyUSBx etc.) gespeichert sind.

In der zentralen Schleife von fhem.pl wird vereinfacht gesagt mit select überwacht, ob über eine der geöffneten Schnittstellen Daten zum Lesen anstehen. Wenn dies der Fall ist, dann wird die Lesefunktion (X_Read) des zuständigen Moduls aufgerufen, damit es die Daten entgegennimmt und die Schleife wird weiter ausgeführt.

Auf Windows-Systemen funktioniert dies anders. Hier können USB/Seriell-Geräte nicht per select überwacht werden. In FHEM unter Windows werden daher diese Schnittstellen kontinuierlich abgefragt ob Daten bereitstehen. Dafür müssen Module zusätzlich zur Lesefunktion eine Abfragefunktion (X_Ready) implementieren, die prüft ob Daten zum Lesen anstehen. Auch auf Linux/Unix-Plattformen hat diese Funktion eine Aufgabe. Falls nämlich eine Schnittstelle ausfällt beziehungsweise ein CUL oder USB-zu-Seriell Adapter ausgesteckt wird, dann wird über diese Funktion regelmäßig geprüft ob die Schnittstelle wieder verfügbar wird.

Innerhalb der eigentlichen Lesefunktion (X_Read) werden dann die Daten vom zugehörigen Gerät gelesen, das nötige Protokoll implementiert und Werte in Readings geschrieben.

Zum Setzen von Readings ist es wie oben schon erwähnt empfehlenswert die Funktionen <code>readingsBeginUpdate</code>, <code>readingsBulkUpdate</code>, <code>readingsEndUpdate</code> oder <code>readingsSingleUpdate</code> aufzurufen. Dabei kann man auch angeben, ob dabei ein Event ausgelöst werden soll oder nicht. Events erzeugen spürbare Last auf dem System (siehe NotifyFn), das Ändern von Readings ohne dass dabei Events erzeugt werden jedoch nicht.

Eine Sequenz zum Setzen von Readings könnte folgendermaßen aussehen:

<pre>
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</pre>

Die <code>1</code> beim Aufruf von <code>readingsEndUpdate</code> gibt an, dass Events ausgelöst werden, die auf Veränderungen der Readings reagieren.

== Pollen von Geräten ==
Wenn Geräte von sich aus keine Informationen senden sondern abgefragt werden müssen, kann man im Modul die Funktion <code>InternalTimer<code> verwenden. Man übergibt ihr den Zeitpunkt für den nächsten Aufruf, den Namen der Funktion, die aufgerufen werden soll, die zu übergebenden Parameter und ein Flag ob der erste Aufruf verzögert werden soll falls die Initialiserung des Geräts noch nicht abgeschlossen ist.

Beispielsweise könnte man für das Abfragen eines Geräts in der Define-Funktion den Timer folgendermassen setzen:

<pre>
# initial request after 2 secs, there timer is set to interval for further update
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash, 0);
</pre>

in der Funktion <code>X_GetUpdate</code> selbst wird dann der Timer neu gesetzt, so dass nach einem Intervall die Funktion erneut aufgerufen wird:

<pre>
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash, 1);
Log3 $name, 4, "X: GetUpdate called ...";
</pre>

Im weiteren Verlauf der Funktion könnte man dann das Gerät abfragen und die abgefragten Werte in Readings speichern. Falls das Abfragen der Werte jedoch zu einer Verzögerung und damit zu einer Blockade von FHEM führen kann, ist es möglich, in der GetUpdate-Funktion nur die Aufforderung zum Senden bestimmter Daten an das angeschlossene Gerät zu senden und dann das Lesen über die oben beschriebene Read-Funktion zu implementieren, die beim Anstehen von Daten aufgerufen wird.

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Protokollmeldung in die Fhem-Logdatei zu schreiben, wird die Funktion Log3 aufgerufen:
<pre>
Log3 $name, 3, "X: Problem erkannt ...";
</pre>

Die Parameter der Funktion Log3 sind der Name oder der Hash der Geräteinstanz, das Verbose-Level, in dem die Meldung sichtbar sein soll und die Meldung selbst.
Den Namen der Geräteinstanz kann man in den Funktionen, die den Hash übergeben bekommen einfach aus diesem Hash nehmen:

<pre>
my $name = $hash->{NAME};
</pre>

Um für ein neues Modul das Verbose-Level zu erhöhen, ohne gleich für das Gesamte FHEM alle Meldungen zu erzeugen kann man den Befehl
<code>attr gerätename verbose</code> verwenden. Beispielsweise <code>attr PM verbose 5</code>

Damit bietet es sich an im Modul Meldungen, die im normalen Betrieb nicht benötigt werden, beim Aufruf von Log3 mit dem Level 4 oder 5 anzugeben. Wenn man dann bei der Fehlersuche mehr Meldungen sehen möchte, erhöht man mit attr X verbose das Level für das betroffene Gerät.

== Noch zu beschreiben ==
* Zweistufiges Modell für Module
* Funktion X_Ready ...
* FW_summaryFn (wird von FHEMWEB aufgerufen fuer Raum-Uebersicht)
* FW_detailFn (wird von FHEMWEB aufgerufen fuer Detail-Ansicht)
* Bei der Beschreibung der von SetFn/GetFn zurueckgelieferten Fehlermeldung: Modifier fuer FHEMWEB wie :noArg, :slider, etc.

[[Kategorie:Development]]