{{SEITENTITEL:cmdalias}}
{{Infobox Modul
|ModPurpose=Erstellen von Benutzer-definierten Befehlen in FHEM
|ModType=cmd
|ModCmdRef=cmdalias
|ModForumArea=FHEM
|ModTechName=98_cmdalias.pm
|ModOwner={{Link2FU|8|Rudolf König}}
}}

Der Fhem-Befehl [[cmdalias]] dient zur Erstellung von benutzerdefinierten Befehlen.

= Zielsetzung =
Die jeweiligen Befehlsketten können mit ''cmdalias'' verkürzt oder sogar verändert werden.
Ein schönes Beispiel dafür ist, dass sogar [[:Kategorie:FhemBefehl|interne Befehle]] wie "shutdown restart" ersetzt werden können durch einen alias der genau so heißt aber zusätzlich vorher noch z.B. ein "save" ausführt.

= Einbindung in Fhem =
{{Randnotiz|RNTyp=y|RNText=Die folgenden Codebeispiele sind, sofern nicht anders erwähnt, als Einzeiler '''ohne''' Zeilenumbrüche einzugeben.}}
<source lang="perl">define <name> cmdalias <cmd> [parameter] AS newcommand..."</source>

'''Beispieldefinition'''
<source lang="perl">define s1 cmdalias shutdown update AS save;;shutdown</source>
<source lang="perl">define s2 cmdalias set lamp .* AS { Log 1, "$EVENT";; fhem("set $EVENT") }</source>

= Aufruf in Fhem =
[[Datei:cmdalias_eingabe_telnet.png|mini|right|400px|Ausgabe Telnet]]
Die aliase können entweder in der FHEM Befehlzeile oder direkt im Telnet eingegeben werden.

[[Datei:cmdalias_eingabe_fhemweb.png|mini|right|400px|Ausgabe in FHEMWEB]]
= Beispiele =
== ls ==
Verkürzter Aufruf von list mit Wildcard Suche
<source lang="perl">define c_ls cmdalias ls .* AS list .*$EVENT.*</source>

== hostname ==
Hostname des FHEM Rechners anzeigen
<source lang="perl">define c_hostname cmdalias hostname AS {(split('\.', qx(hostname)))[0]}</source>

== atexec ==
Triggert einen AT Timer
Aufruf mit <source lang="perl">atexec <at-device-name></source>
<source lang="perl">define c_atexec cmdalias atexec .* AS { if($defs{$EVENT}) { if($defs{$EVENT}->{TYPE} eq "at") { at_Exec($defs{$EVENT});; 0;; } else { return "$EVENT is not of TYPE at!";; }} else { return "Device $EVENT does not exist!";; }}</source>

== dellog ==
Leert das aktuelle FHEM Logfile
<source lang="perl">define c_dellog cmdalias dellog AS {qx(truncate $currlogfile --size 0);;Log 1, "Logfile gelöscht";;}</source>

== lastloglines ==
Zeigt die letzten Zeilen aus dem FHEM Logfile an. Mit dem Aufruf <source lang="perl">lastloglines 10</source> werden die letzten 10 Einträge angezeigt. Der Alias wird mit der folgenden Definition angelegt:
<source lang="perl">define c_lastloglines cmdalias lastloglines .* AS {qx(tail -n $EVENT $currlogfile)}</source>

== showignoreddevices ==
Auflisten von Geräten, die in FHEM das Attribut "ignore" gesetzt haben:
<source lang="perl">define c_showignoreddevices cmdalias showignoreddevices AS { join("\n", grep { $attr{$_}{ignore} } sort keys %attr ) }</source>

== shownotypedevices ==
Auflisten von Geräten ohne TYPE Definition (sollte nur bei einer fehlerhaften Definition eine Ausgabe erstellen):
<source lang="perl">define c_shownotypedevices cmdalias shownotypedevices AS { join("\n", grep { !defined($defs{$_}{TYPE}) } keys %defs) }</source>

== v5 ==
Setzen des "Verbose Level" in FHEM auf 5
<source lang="perl">define c_v5 cmdalias v5 .* AS {fhem ("attr ".($EVENT||="global")." verbose 5")}</source>

== v3 ==
Setzen des "Verbose Level" in FHEM auf 3
<source lang="perl">define c_v3 cmdalias v3 .* AS {fhem ("attr ".($EVENT||="global")." verbose 3")}</source>

== Änderung von Geräte Aktionen ==
In diesem Beispiel wird dem Gerät MiLight_1 nicht erlaubt ausgeschaltet zu werden
<source lang="perl">define c_aliasMiLight_1 cmdalias set MiLight_1 off AS set HMSchaltaktor_1 off</source>

== say ==
Verkürzter Befehlsaufruf des TTS Moduls
<source lang="perl">define c_say cmdalias say .* AS set MyTTS tts '$EVENT'</source>

== roomadd ==
Erstellt einen neuen Raum und füllt diesen mit Geräten entsprechend der angegeben Device-Spezifikation.

Aufruf: <source lang="perl">roomadd <devspec> <new_room></source>
<source lang="perl">define c_roomadd cmdalias roomadd .* AS { for my $name (devspec2array("$EVTPART0")){ my $old_room = AttrVal($name,'room','');; if (index($old_room, $EVTPART1) == -1) {my $new_room = AttrVal($name,'room','') . ",$EVTPART1";; fhem("attr $name room $new_room")} } }</source>

== roomrename ==
Umbenennen eines FHEM Raumes '''Aufruf roomrename <oldroom> <newroom>'''
<source lang="perl">define c_roomrename cmdalias roomrename .* AS { for my $name (devspec2array("room=$EVTPART0")){ map {s/$EVTPART0/$EVTPART1/;; fhem("attr $name room $_")} AttrVal($name,'room','') } }</source>

== roomdelete ==
Löschen eines FHEM Raumes '''Aufruf: roomdelete <roomName>'''
<source lang="perl">define c_roomdelete cmdalias roomdelete .* AS { for my $name (devspec2array("room=$EVENT")){ map { /^$EVENT$/ ? fhem("deleteattr $name room") : do{s/,$EVENT|$EVENT,//;; fhem("attr $name room $_")} } AttrVal($name,'room','') } }</source>

== regroup ==
Umfangreicher alias zum automatischen Setzen verschiedener Gruppen in FHEM Räumen

<source lang="perl">define c_regroup cmdalias regroup .* AS { my @EVTPART=split(' ',$EVENT);; $EVTPART[2] =~ s/\|/:FILTER=/g if($EVTPART[2]);; for my $name (devspec2array("group=".($EVTPART[0] ? $EVTPART[0] : '.*').($EVTPART[2] ? ":FILTER=$EVTPART[2]" : ''))){ map { ($_ && /^$EVTPART[0]$/ && !$EVTPART[1]) ? fhem("deleteattr $name group") : do{ if(!$EVTPART[1]){$EVTPART[0]=",$EVTPART[0]|$EVTPART[0],";; $EVTPART[1]='';;} s/$EVTPART[0]/$EVTPART[1]/;; fhem("attr $name group $_")} } AttrVal($name,'group',0) } }</source>

Die zusätzlichen Gruppen, in welchen sich die devices sonst noch befinden, bleiben unberührt. Als FILTER kann alles was der normale fhem-devspec Filter verarbeiten kann angegeben werden. Es sollte nur aufgepasst werden, wenn ein "Device" mehrere ähnliche Gruppenbennungen wie "attr name group test2,test" hat. Wenn man hier ein 'regroup test test3' macht, könnte es passieren, dass man dadurch bei diesem device die Gruppe 'test2' nach 'test32' umbenennt. In dem Beispiel müsste man den Befehl z.B. mit 'regroup test$ test3' angeben, damit das nicht passiert.

Beispiele:
<pre>regroup <oldGroup> [<newGroup> [<FILTER>][|<FILTER2>]...]

# Allen devices ohne group die Gruppe 'myGroup' setzen:
regroup 0 myGroup

# Nur den devices im Raum 'myRoom' welche keine group haben die Gruppe 'myGroup' setzen:
regroup 0 myGroup room=myRoom

# Alle devices aus 'oldGroup' in 'newGroup' verschieben
regroup oldGroup newGroup

# Nur die devices im Raum 'myRoom' aus 'oldGroup' in 'newGroup' verschieben
regroup oldGroup newGroup room=myRoom

# Gruppe 'myGroup' löschen
regroup myGroup

# Nur die devices im Raum 'myRoom' aus der Gruppe 'myGroup' löschen.
regroup myGroup 0 room=myRoom

# Devices aus allen Gruppen welche mit 'licht' beginnen aus Raum 'Obergeschoss' entfernen.
regroup licht.* 0 room=Obergeschoss

# Devices aus dem Raum 'myRoom' aus allen Gruppen entfernen und in die Gruppe 'myGroup' verschieben.
regroup .* myGroup room=myRoom

# Devices ohne Gruppe aus dem Raum 'myRoom' mit dem TYPE 'CUL_HM' und welche ebenfalls 'Licht' im Namen enthalten die Gruppe 'myGroup' hinzufügen
regroup 0 myGroup room=myRoom|TYPE=CUL_HM|NAME=.*Licht.*</pre>

== autocreate ==
Schnelles (de)aktivieren der [[autocreate]] Funktion:
<source lang="perl">
define c_autocreate_off cmdalias set autocreate off AS attr autocreate disable 1
define c_autocreate_on cmdalias set autocreate on AS attr autocreate disable 0
</source>

Optional kann noch das autocreate Icon definiert werden:
<source lang="perl">attr autocreate devStateIcon disabled:ios-off:on active:ios-on-blue:off</source>

== renamehm ==
{{Randnotiz|RNText=Dieser Alias ist mittlerweile nicht mehr erforderlich, da [[HomeMatic]] Devices den Befehl (''set'') [[rename|deviceRename]] anbieten}}
Sehr viele HomeMatic Devices haben zusätzlichen Kanäle (z.B: HM-ES-PMSw1-PI legt die Kanäle HM_12345B, HM_12345B_Pwr, HM_12345B_SenF, HM_12345B_SenI, HM_12345B_SenPwr, HM_12345B_SenU, HM_12345B_Sw als separate Devices an). Um diese umzubenennen kann man mit der folgenden Funktion den Prefix von HM_12345B auf einen beliebigen Ändern. Diese wird nach Definition via "<code>renamehm HM_12345B NEW_DEVICE_PREFIX</code>" ausgeführt:
<source lang="perl">define c_renamehm cmdalias renamehm .* AS { for my $name (devspec2array("$EVTPART0.*")){ my $newname=$name;;$newname =~ s/$EVTPART0/$EVTPART1/gi;; fhem("rename $name $newname");;} }</source>

= Links =
* Thread über das Modul im {{Link2Forum|Topic=15648|LinkText=Fhem Forum}}
* Thread mit {{Link2Forum|Topic=42211|LinkText=weiteren Informationen}}

[[Kategorie:Code Snippets]]

Cmdalias

2016-05-22T20:30:37Z

Stormmurdoc: /* Beispiele */ lastloglines hinzugefügt

XBMC

2016-02-07T08:44:30Z

2015-11-29T13:32:23Z

Stormmurdoc: Hersteller Link korrigiert

<div style="float:right">{{Infobox Modul
|Name=PIONEERAVR
|ModPurpose=Steuern von Pioneer AV Receivern (MAIN Zone)
|ModType=d

|ModCmdRef=PIONEERAVR
|ModForumArea=Multimedia
|ModTechName=70_PIONEERAVR.pm
|ModOwner=hofrichter
}}
{{Infobox Modul
|Name=PIONEERAVRZONE
|ModPurpose=Steuern von Pioneer AV Receivern (weitere Zonen)
|ModType=d

|ModCmdRef=PIONEERAVRZONE
|ModForumArea=Multimedia
|ModTechName=70_PIONEERAVRZONE.pm
|ModOwner=hofrichter}}
</div>

'''Pioneer AV-Receiver''' sind Mehrkanal-Hi-Fi-Verstärker der Firma Pioneer, die verschiedene Audio- und Videoquellen auf ihre analogen und digitalen Ausgänge schalten können.

== Features / Funktionen ==
Die Haupteigenschaften von Pioneer AV-Receiver sind
* Audio- und Video-Umschalter
* Mehrkanalton-Decoder
* Radio-Tuner

== Hinweise zum Betrieb mit Fhem ==
Um das Gerät von Fhem aus ansprechen zu können wird/werden benötigt...
# Pioneer AV-Receiver,
# Fhem Server,
# Datenverbindung zwischen den beiden
## per Ethernet oder
## via serielle Schnittstelle (RS232) UNGETESTET!

Einige Pioneer AV-Receiver unterstützen Ausgänge in mehreren Zonen. Dies wird in Fhem durch mehrere devices abgebildet:
* ein PIONEERAVR device:
** dieses empfängt und sendet an den Pioneer AV-Receiver
** steuert die Main-Zone
* je Zone ein PIONEERAVRZONE device
** wird automatisch angelegt, sobald das PIONEERAVR device Daten vom Pioneer AV-Receiver für eine Zone empfängt

== Einbinden in Fhem ==
<pre>define <name> PIONEERAVR telnet <IPAddress:Port></pre>

== Bekannte Probleme ==

== Weblinks ==
* {{Link2Forum|Topic=12573}} im Forum
* Hersteller: [http://www.pioneer.eu/ Pioneer]

[[Kategorie:Unterhaltungselektronik]]

Cmdalias

2015-10-20T19:18:29Z

Stormmurdoc: /* Beispiele */

Beispiel Eingabe cmdalias

Cmdalias

2015-10-18T06:43:25Z

Stormmurdoc: /* Aufruf in Fhem */

Cmdalias

2015-10-18T06:42:56Z

Stormmurdoc:

Datei:Cmdalias eingabe telnet.png

2015-10-18T06:41:30Z

FRITZBOX

2015-09-07T10:34:47Z

Stormmurdoc: /* Anwesenheitserkennung per Notify */ Fehler im Notify korrigiert

{{Infobox Modul
|ModPurpose=Steuerung einer Fritz!Box über Fhem
|ModType=d
|ModForumArea=FRITZ!Box
|ModTechName=72_FRITZBOX.pm
|ModOwner=tupol/Topos ([http://forum.fhem.de/index.php?action=profile;u=5432 Forum] / [[Benutzer Diskussion:Topos|Wiki]])}}

Das Modul [[FRITZBOX]] ermöglicht die Steuerung einer [[AVM Fritz!Box]] und von AVM FRITZ!WLAN Repeatern durch Fhem. An Fritzboxen können sowohl Geräte abgefragt werden, auf denen FHEM selbst läuft (lokaler Modus), als auch um eine entfernte (externe) Geräte.

== Voraussetzungen ==
=== Remote-Zugang ===
Für den Remote-Zugang müssen die Module JSON:XS, LWP und SOAP::Lite installiert sein; auf einem [[Raspberry Pi]] oder unter Ubuntu z. B. mit dem Befehl
:::<code>sudo apt-get install libjson-perl libwww-perl libsoap-lite-perl libjson-xs-perl</code>

Teilweise ist derzeit zusätzlich die Installation der telnet Libraries erforderlich, auch wenn der Telnet-Zugang nicht genutzt werden soll. Siehe dazu den nachfolgenden Abschnitt.

=== Telnet ===
Das Modul basierte ursprünglich auf dem Zugriff auf die Fritzbox per Telnet. Ab FRITZ!OS 6.2x baut AVM den abgekündigten Telnet-Zugang sowie die webcm-Schnittstelle sukzessive zurück bzw. hat dies, je nach Firmware, schon ganz abgestellt (siehe {{Link2Forum|Topic=38586|LinkText=dieses Forenthema}}). Der zukunftssichere Zugriff auf die Fritzbox sollte also per TR-064 erfolgen. Der Vollständigkeit halber und für ältere Firmwareversionen:

# Wer den Zugang per Telnet (noch) nutzen (kann und) möchte, muss dies zuerst freischalten. Üblicherweise durch Eingabe von #96*7* an einem direkt an der entsprechenden FritzBox angeschlosssenen Telefon

# Auf dem System, auf dem Fhem läuft ([[Systemübersicht#Server|Server]]) muss Telnet installiert sein; auf einem [[Raspberry Pi]] und unter Ubuntu z. B. mit dem Befehl
:::<code>sudo apt-get install libnet-telnet-perl</code>

== Installation ==

=== Erste Schritte ===
Zur Erstinstallation reicht ein einfaches <code>define FritzBox FRITZBOX</code>, dieses Modul funktioniert lokal (FHEM auf Fritzbox) sowie per Fernzugriff (FHEM auf einem anderen Server im Netz, siehe nächsten Schritt).

==== TR-064: Modul FRITZBOX für Zugriff auf einem externen Server einrichten ====
Für den Fernzugriff über TR-064 auf eine oder mehrere Fritzboxen und/oder einen FRITZ!WLAN Repeater sind die folgenden Schritte nötig (für jedes Gerät):

Fritzbox definieren:
:<code>define FritzBox FRITZBOX</code>

Wenn das Login auf der Benutzeroberfläche der FritzBox mit User und Passwort (und nicht nur per Passwort) geschieht, den User konfigurieren:
:<code>attr FritzBox boxUser ''Benutzername'' </code>

Passwort konfigurieren:
:<code>set FritzBox password ''Passwort'' </code> - legt das zugehörige Passwort fest

Manuelle TR-064 Kommandos erlauben (die Abfrage per TR-064 funktioniert auch ohne dieses Attribut):
:<code>attr FritzBox allowTR064Command 1</code>

Wenn die Fritzbox nicht unter http://fritz.box erreichbar ist, IP setzen:
:<code>attr FritzBox fritzBoxIP 192.168.168.168</code>
192.168.168.168 dabei natürlich durch die passende IP ersetzen... Alternativ kann bei fritzBoxIP - trotz des Namens des Attributs - statt der IP auch der Hostname eingegeben werden, eine DNS-Auflösung findet statt.

Manchmal ist ein Neustart von FHEM erforderlich, damit die Fritzbox mit der veränderten IP gefunden wird.

==== Telnet: Modul FRITZBOX für Zugriff auf einem externen Server einrichten ====
[[Datei:Screenshot_FritzBox_TelnetUser.png|mini|300px|rechts|Anlegen des Attributs telnetUser]]
Bei Fernzugriff über Telnet sind weitere Schritte nötig:
# Telnet auf der Fritzbox freischalten (Tastenkombination #96*7* am angeschlossenen Telefon (auch FritzFon)
# TelnetUser definieren (wie im Screenshot gezeigt)
# Passwort zum Benutzer auf der Fritzbox definieren

[[Datei:Screenshot_FritzBox_Passwort.png|mini|300px|rechts|Passwort definieren]]

(bitte die Buttons {{Taste|set}} und {{Taste|attr}} bei der Definition der jeweiligen Einträge nicht vergessen)

Wer stattdessen lieber das [[Konfiguration|Befehl-Eingabefeld]] verwendet:

:<code>define FritzBox FRITZBOX</code>
:<code>attr FritzBox telnetUser ''Benutzername'' </code> - legt den Benutzer fest
:<code>set FritzBox password ''Passwort'' </code> - legt das zugehörige Passwort fest

Wer keinen User konfiguriert hat, kann das Feld "telnetUser" leer lassen.

Wer sicher gehen möchte, dass auch tatsächlich Telnet und nicht andere Zugriffe benutzt werden, sollte außerdem noch setzen:

:<code>attr FritzBox forceTelnetConnection 1</code>

=== mögliche Fehlermeldungen ===
Sollte schon bei <code>define FritzBox FRITZBOX</code> die Fehlermeldung kommen, dass dieses Modul nicht existiert, dann bitte prüfen, ob Fhem auf dem aktuellen Stand ist und ggf. [[Update|aktualisieren]].

Kommt jetzt bei der erneuten Definition die Fehlermeldung <code>Error: Perl modul Net::Telnet is missing on this system</code> bitte wie oben schon erwähnt den Befehl
:<code>sudo apt-get install libnet-telnet-perl</code>
direkt per Telnet/SSH auf dem FHEM-Server ausführen und neu starten.
Sollte alles geklappt haben, seht ihr nun eure Fritzbox und könnt diverse Einstellungen manuell vornehmen und/oder automatisch vornehmen lassen.

== Anwendung ==
=== Define ===
Siehe [http://fhem.de/commandref_DE.html#FRITZBOX commandref]

=== Attribute ===
Siehe commandref

=== TR-064 ===
Die offizielle Programmier-Schnittstelle der Fritz!Box läuft über das Protokoll TR-064.

mit dem Attribute<br/>
<code>attr <device> allowTR064Command 1</code><br/>
kann man den Befehl<br/>
<code>get <device> tr064Command <service> <control> <action> [[parameterName1 parameterValue1] ...]</code><br/>
freischalten und damit auf diese Schnittstelle zugreifen.

AVM hat die Schnittstellenbeschreibung unter [http://avm.de/service/schnittstellen/] veröffentlicht. Ein weitere Einstiegspunkt befindet sich auch auf der Box unter http://fritz.box:49000/tr64desc.xml

Folgende Service und Controls existieren (für den get-Befehl werden nur die fett formatierten Wörter benötigt)

{| class="wikitable"
|-
!serviceType!!controlURL!!XML!!Dokument bei AVM
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''DeviceInfo:1'''||/upnp/control/'''deviceinfo'''||[http://fritz.box:49000/deviceinfoSCPD.xml deviceinfoSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/deviceinfoSCPD.pdf deviceinfoSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''DeviceConfig:1'''||/upnp/control/'''deviceconfig'''||[http://fritz.box:49000/deviceconfigSCPD.xml deviceconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/deviceconfigSCPD.pdf deviceconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''Layer3Forwarding:1'''||/upnp/control/'''layer3forwarding'''||[http://fritz.box:49000//layer3forwardingSCPD.xml layer3forwardingSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/layer3forwardingSCPD.pdf layer3forwardingSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''LANConfigSecurity:1'''||/upnp/control/'''lanconfigsecurity'''||[http://fritz.box:49000//lanconfigsecuritySCPD.xml lanconfigsecuritySCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/lanconfigsecuritySCPD.pdf lanconfigsecuritySCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''ManagementServer:1'''||/upnp/control/'''mgmsrv'''||[http://fritz.box:49000//mgmsrvSCPD.xml mgmsrvSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/mgmsrvSCPD.pdf mgmsrvSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''Time:1'''||/upnp/control/'''time'''||[http://fritz.box:49000//timeSCPD.xml timeSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/timeSCPD.pdf timeSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''UserInterface:1'''||/upnp/control/'''userif'''||[http://fritz.box:49000//userifSCPD.xml userifSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/userifSCPD.pdf userifSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_VoIP:1'''||/upnp/control/'''x_voip'''||[http://fritz.box:49000//x_voipSCPD.xml x_voipSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_voipSCPD.pdf x_voipSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_Storage:1'''||/upnp/control/'''x_storage'''||[http://fritz.box:49000//x_storageSCPD.xml x_storageSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_storageSCPD.pdf x_storageSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_OnTel:1'''||/upnp/control/'''x_contact'''||[http://fritz.box:49000//x_contactSCPD.xml x_contactSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_contactSCPD.pdf x_contactSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_WebDAVClient:1'''||/upnp/control/'''x_webdav'''||[http://fritz.box:49000//x_webdavSCPD.xml x_webdavSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_webdavSCPD.pdf x_webdavSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_UPnP:1'''||/upnp/control/'''x_upnp'''||[http://fritz.box:49000//x_upnpSCPD.xml x_upnpSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_upnp.pdf x_upnp.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_RemoteAccess:1'''||/upnp/control/'''x_remote'''||[http://fritz.box:49000/x_remoteSCPD.xml x_remoteSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_remoteSCPD.pdf x_remoteSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_MyFritz:1'''||/upnp/control/'''x_myfritz'''||[http://fritz.box:49000/x_myfritzSCPD.xml x_myfritzSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_myfritzSCPD.pdf x_myfritzSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_TAM:1'''||/upnp/control/'''x_tam'''||[http://fritz.box:49000/x_tamSCPD.xml x_tamSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_tam.pdf x_tam.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_AppSetup:1'''||/upnp/control/'''x_appsetup'''||[http://fritz.box:49000/x_homeautoSCPD.xml x_homeautoSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_appsetupSCPD.pdf x_appsetupSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_Homeauto:1'''||/upnp/control/'''x_homeauto'''||[http://fritz.box:49000/x_homeautoSCPD.xml x_homeautoSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_homeautoSCPD.pdf x_homeautoSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WLANConfiguration:1'''||/upnp/control/'''wlanconfig1'''||[http://fritz.box:49000/wlanconfigSCPD.xml wlanconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wlanconfigSCPD.pdf wlanconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WLANConfiguration:2'''||/upnp/control/'''wlanconfig2'''||[http://fritz.box:49000/wlanconfigSCPD.xml wlanconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wlanconfigSCPD.pdf wlanconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WLANConfiguration:3'''||/upnp/control/'''wlanconfig3'''||[http://fritz.box:49000/wlanconfigSCPD.xml wlanconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wlanconfigSCPD.pdf wlanconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''Hosts:1'''||/upnp/control/'''hosts'''||[http://fritz.box:49000/hostsSCPD.xml hostsSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/hostsSCPD.pdf hostsSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''LANEthernetInterfaceConfig:1'''||/upnp/control/'''lanethernetifcfg'''||[http://fritz.box:49000/lanifconfigSCPD.xml lanifconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/lanifconfigSCPD.pdf lanifconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''LANHostConfigManagement:1'''||/upnp/control/'''lanhostconfigmgm'''||[http://fritz.box:49000/lanhostconfigmgmSCPD.xml lanhostconfigmgmSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/lanhostconfigmgmSCPD.pdf lanhostconfigmgmSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANCommonInterfaceConfig:1'''||/upnp/control/'''wancommonifconfig1'''||[http://fritz.box:49000/wancommonifconfigSCPD.xml wancommonifconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wancommonifconfigSCPD.pdf wancommonifconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANDSLInterfaceConfig:1'''||/upnp/control/'''wandslifconfig1'''||[http://fritz.box:49000/wandslifconfigSCPD.xml wandslifconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wandslifconfigSCPD.pdf wandslifconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANDSLLinkConfig:1'''||/upnp/control/'''wandsllinkconfig1'''||[http://fritz.box:49000/wandsllinkconfigSCPD.xml wandsllinkconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wandsllinkconfigSCPD.pdf wandsllinkconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANEthernetLinkConfig:1'''||/upnp/control/'''wanethlinkconfig1'''||[http://fritz.box:49000/wanethlinkconfigSCPD.xml wanethlinkconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wanethlinkconfigSCPD.pdf wanethlinkconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANPPPConnection:1'''||/upnp/control/'''wanpppconn1'''||[http://fritz.box:49000/wanpppconnSCPD.xml wanpppconnSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wanpppconnSCPD.pdf wanpppconnSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANIPConnection:1'''||/upnp/control/'''wanipconnection1'''||[http://fritz.box:49000/wanipconnSCPD.xml wanipconnSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wanipconnSCPD.pdf wanipconnSCPD.pdf]
|-
|}

=== Status-Symbol ===
<code>attr <device> devStateIcon .*on.*off:WLAN_on_gWLAN_off .*on.*on.*:WLAN_on_gWLAN_on WLAN..off.*:WLAN_off</code>

Im Verzeichnis www/images/default müssen die passenden Dateien "WLAN_on_gWLAN_off.png", "WLAN_on_gWLAN_on.png" und "WLAN_off.png" liegen. Wenn die PNGs fehlen, können sie hier [http://forum.fhem.de/index.php/topic,29725.msg318113.html#msg318113] heruntergeladen werden.

== Anwendungsbeispiele ==
[[Datei:Screenshot_FritzBox1.png|mini|300px|rechts|FRITZBOX Gerät auf der Fhem Oberfläche]]
Sollte alles geklappt haben, seht ihr nun unter "Unsortiert" den im nebenstehenden Screenshot gezeigten Eintrag für das "Gerät" (hier mit dem Icon "it_router").

=== TR-064 Bespiele ===

*Box Reboot: <code>get <device> tr064Command DeviceConfig:1 deviceconfig Reboot</code>

=== Klingel- und Sprachausgabe per TR-064 ===

Das geht derzeit nicht, da entsprechende Kommandos per TR-064 nicht verfügbar sind. Da Telnet sukzessive abgestellt wird, sollten sich Interessenten per Feature-Request an AVM wenden, wie hier [http://forum.fhem.de/index.php/topic,38586.0.html] beschrieben.

=== Anwesenheitserkennung per regelmäßiger Abfrage über das PRESENCE Modul ===

Fritzboxen und die FRITZ!WLAN Repeater speichern den Status angemeldeter Geräte. Dieser Status lässt sich mittels des FRITZBOX Moduls über Readings abfragen, die das Format mac_AA_AA_AA_AA_AA_AA haben und die MAC-Adressen der jeweils angemeldeten Geräte (AA:AA:AA:AA:AA:AA) enthalten. Das Reading existiert, wenn das Gerät angemeldet ist. Wenn das Gerät abgemeldet ist, existiert es nicht mehr. Es gibt auch noch den Zwischenstatus "inactive", der anscheinend gesetzt wird, bevor das Reading gelöscht wird.

Mit Hilfe des PRESENCE Moduls (vgl. [[Anwesenheitserkennung]]) kann man auf diese Weise den Anwesenheitsstatus abfragen. Anregungen dazu gibt es im zugehörigen {{Link2Forum|Topic=39433|LinkText=Forenthread}} zur Anwesenheitserkennung und in einem Blogpost: [http://heinz-otto.blogspot.de/2015/07/die-zeiten-andern-sich.html]. Auf dieser Basis könnte eine einfache Implementierung zum Beispiel so aussehen:

Funktion in 99_myUtils.pm:

<pre>sub checkFritzMACpresent($$) {
# Benötigt: Name der zu testenden Fritzbox ($Device),
# zu suchende MAC ($MAC),
# Rückgabe: 1 = Gerät gefunden
# 0 = Gerät nicht gefunden
my ($Device, $MAC) = @_;
my $Status = 0;
$MAC =~ tr/:/_/;
$MAC = "mac_".uc($MAC);
my $StatusFritz = ReadingsVal($Device, $MAC, "weg");
if ($StatusFritz eq "weg") {
Log 1, ("checkFritzMACpresent ($Device): $MAC nicht gefunden, abwesend.");
$Status = 0;
} elsif ($StatusFritz eq "inactive") {
Log 1, ("checkFritzMACpresent ($Device): $MAC ist >inactive<, also abwesend.");
$Status = 0;
} else {
# Reading existiert, Rückgabewert ist nicht "inactive", also ist das Gerät per WLAN angemeldet.
Log 1, ("checkFritzMACpresent ($Device): $MAC gefunden, Gerät heißt >$StatusFritz<.");
$Status = 1;
}
return $Status
}
</pre>

Nutzung dieser Funktion mit dem PRESENCE Modul definieren:

<code>define <Name> PRESENCE function {checkFritzMACpresent("Fritzbox","AA:BB:CC:DD:EE:FF")} 60 60</code>

wobei
*<Name> ein beliebig zu wählender Name für die PRESENCE-Funktion ist,
*Fritzbox der Name ist, mit dem ihr die abzufragende Fritzbox als FRITZBOX definiert habt,
*AA:BB:CC:DD:EE:FF die MAC-Adresse des gesuchten Geräts ist.
* "60 60" sagt, dass der Anwesenheitsstatus im 60-Sekunden-Takt abgefragt wird. Das macht natürlich nur Sinn, wenn ihr mit <code>attr Fritzbox INTERVAL 60</code> den Abfrageinterval bei der Fritzbox auch entsprechend hochgesetzt habt. Der Standard ist 300.
* "Log 1" führt immer zum Loggen. Das ist zum Einrichten praktisch, ohne dass man gleich für das ganze Modul oder ganz FHEM <code>attr <device> verbose 5</code> setzen muss. Wenn es läuft, können die "Log 1"-Zeilen gelöscht, auskommentiert (# an den Zeilenanfang) oder in "Log 5" geändert werden.

==== Mehrere Fritzboxen oder Repeater und Fritzbox (wird noch bearbeitet) ====
Existiert ein AVM Repeater im Netzwerk, kann der als eigenständiges Gerät mit FRITZBOX definiert werden. WLAN Geräte an der Fritzbox werden in der Instanz der Fritzbox gelistet und WLAN Geräte am Repeater in der Repeater Instanz. Um trotzdem die Anwesenheit im Netzwerk einfach zu erkennen muss die Subroutine in 99_myUtils abgewandelt werden.

<pre>my @fbs = devspec2array("TYPE=FRITZBOX"); (Nur als Hinweis)
</pre>

Existiert eine zweite Fritzbox im Accesspointmodus werden die WLAN Geräte im Netzwerk alle in der Hauptfritzbox an einem LAN Anschluss gelistet. D.h. man sieht an der Hauptfritzbox nicht, dass sie im WLAN sind. Eine zweite Instanz mit dem FRITZBOX Modul muss wegen der Anwesenheitserkennung nicht gemacht werden.

Weitere Hinweise zu komplexeren Abfragen mehrere Boxen auf einmal etc. findet ihr auch im {{Link2Forum|Topic=39433|LinkText=Forenthread}}.

=== Anwesenheitserkennung per Notify ===
Der von Fritzboxen und Fritz!WLAN Repeatern gespeicherte Status zum Status angemeldeter Geräte lässt sich (statt per PRESENCE, s.o.) auch per Notify anfragen:

<pre>define <Name> notify Fritzbox:mac_AA_BB_CC_DD_EE_FF:.* {
if (ReadingsVal("Fritzbox", "mac_AA_BB_CC_DD_EE_FF", "inactive") eq "inactive")
{
fhem("set anwesend_smartphone absent");
}
else
{
fhem("set anwesend_smartphone present");
}
}</pre>

Hinweise:
*[code]fhem("set anwesend_smartphone absent");[/code] ist nur ein Beispiel, das einen Dummy auf den Status "absent" bzw. "present" setzt. Man kann hier natürlich auch gleich entsprechende Aktionen durchführen. Wer das Beispiel übernehmen möchte, sollte den Dummy vorher definieren ([code]define anwesend_smartphone dummy[/code]).
*mac_AA_BB_CC_DD_EE_FF ist die MAC-Adresse des gesuchten Geräts.
*"Fritzbox" ist der Name, unter dem die Fritzbox als FRITZBOX-Modul definiert wurde.
*Das Notify funktioniert, weil Geräte, wenn sie sich abgemeldet haben, erst den Status "inactive" erhalten. Ist das Gerät ganz abgemeldet, verschwindet das mac_.*-Reading. Dabei löst das Notify nicht mehr aus. Da das mac-.*-Reading aber vorher auf "inactive" stand, wurde die Abwesend-Aktion schon ausgeführt.
*Damit der Notify nicht andauernd losgeht, sollte man mittels [code]attr Fritzbox event-on-change-reading mac_AA_BB_CC_DD_EE_FF[/code] Events nur auslösen, wenn sich der Status des Gerätes ändert. Will man mehrere Geräte abfragen, sollte man [code]attr Fritzbox event-on-change-reading mac_AA_BB_CC_DD_EE_FF,mac_GG_HH_II_JJ_KK_LL[/code] setzen, damit bei der Änderung jedes Readings ein Event ausgelöst wird.

=== Vergleich Anwesenheitserkennung PRESENCE/Notify ===
Die Anwesenheitserkennung per regelmäßiger PRESENCE-Abfrage hat den Vorteil, dass sie im Turnus der regelmäßigen Abfragen immer einen aktuellen Status produziert. Sie hat dafür den Nachteil, dass die PRESENCE-Funktionen regelmäßig abgearbeitet werden müssen, auch wenn sich gar nichts ändert. Außerdem aktualisiert sich der Status nicht sofort, sondern erst bei der nächsten regelmäßigen Abfrage. Durch häufiges Abfragen, kann dieser Nachteil verringert werden (bei entsprechend höherer Systemlast).

Die Anwesenheitserkennung per Notify hat den Vorteil, dass ein sich ändernder Status sofort abgebildet wird. Ändert sich kein Status, werden keine Routinen ausgeführt, was die Systemlast gering hält. Der Nachteil ist, dass - z.B. nach einem Systemstart - die entsprechende Aktion erst bei einer Änderung des Status ausgeführt wird. D.h. ist das zu testende Gerät anwesend, wird dann FHEM beendet, das Gerät entfernt und FHEM wieder gestartet, ist der Status in FHEM immer noch "anwesend". Da das Reading für das Gerät nicht existiert, wird darauf auch erst wieder ein Notify ausgeführt, wenn sich der Status des Geräts wieder ändert, d.h. es wieder ankommt. Bis dahin ist der Status im System falsch.
Der Nachteil des Notify kann verringert werden, wenn man statt [code]attr Fritzbox event-on-change-reading mac_AA_BB_CC_DD_EE_FF[/code] ein [code]attr Fritzbox event-on-update-reading mac_AA_BB_CC_DD_EE_FF[/code] setzt. Das erhöht allerdings die Systemlast und funktioniert auch nur für den Status "anwesend". Bei "abwesend" ist kein Reading vorhanden, so dass auch event-on-update-reading nicht ausgeführt wird.
Eine weitere Möglichkeit, den Nachteil der Notify-Methode auszugleichen, ist, die Statusabfrage beim Systemstart einmal manuell auszuführen, durch ein notify auf "GLOBAL:initialized":
<pre>
global:INITIALIZED {
Reset_Variables;
if (ReadingsVal("Fritzbox", "mac_AA_BB_CC_DD_EE_FF", "inactive") eq "inactive") {
fhem("set anwesend_smartphone absent");
} else
fhem("set anwesend_smartphone present");
}
}
</pre>
Das hilft allerdings nur beim Systemstart. Nicht, wenn FHEM aufgrund irgendwelcher Hänger eine Aktualisierung des Status' verpasst hat.

== Links ==
* {{Link2Forum|Topic=29725|LinkText=Forenthread}} zu diesem Modul

[[Kategorie:FritzBox]]

FRITZBOX

2015-09-07T10:33:37Z

Stormmurdoc: /* Anwesenheitserkennung per regelmäßiger Abfrage über das PRESENCE Modul */

{{Infobox Modul
|ModPurpose=Steuerung einer Fritz!Box über Fhem
|ModType=d
|ModForumArea=FRITZ!Box
|ModTechName=72_FRITZBOX.pm
|ModOwner=tupol/Topos ([http://forum.fhem.de/index.php?action=profile;u=5432 Forum] / [[Benutzer Diskussion:Topos|Wiki]])}}

Das Modul [[FRITZBOX]] ermöglicht die Steuerung einer [[AVM Fritz!Box]] und von AVM FRITZ!WLAN Repeatern durch Fhem. An Fritzboxen können sowohl Geräte abgefragt werden, auf denen FHEM selbst läuft (lokaler Modus), als auch um eine entfernte (externe) Geräte.

== Voraussetzungen ==
=== Remote-Zugang ===
Für den Remote-Zugang müssen die Module JSON:XS, LWP und SOAP::Lite installiert sein; auf einem [[Raspberry Pi]] oder unter Ubuntu z. B. mit dem Befehl
:::<code>sudo apt-get install libjson-perl libwww-perl libsoap-lite-perl libjson-xs-perl</code>

Teilweise ist derzeit zusätzlich die Installation der telnet Libraries erforderlich, auch wenn der Telnet-Zugang nicht genutzt werden soll. Siehe dazu den nachfolgenden Abschnitt.

=== Telnet ===
Das Modul basierte ursprünglich auf dem Zugriff auf die Fritzbox per Telnet. Ab FRITZ!OS 6.2x baut AVM den abgekündigten Telnet-Zugang sowie die webcm-Schnittstelle sukzessive zurück bzw. hat dies, je nach Firmware, schon ganz abgestellt (siehe {{Link2Forum|Topic=38586|LinkText=dieses Forenthema}}). Der zukunftssichere Zugriff auf die Fritzbox sollte also per TR-064 erfolgen. Der Vollständigkeit halber und für ältere Firmwareversionen:

# Wer den Zugang per Telnet (noch) nutzen (kann und) möchte, muss dies zuerst freischalten. Üblicherweise durch Eingabe von #96*7* an einem direkt an der entsprechenden FritzBox angeschlosssenen Telefon

# Auf dem System, auf dem Fhem läuft ([[Systemübersicht#Server|Server]]) muss Telnet installiert sein; auf einem [[Raspberry Pi]] und unter Ubuntu z. B. mit dem Befehl
:::<code>sudo apt-get install libnet-telnet-perl</code>

== Installation ==

=== Erste Schritte ===
Zur Erstinstallation reicht ein einfaches <code>define FritzBox FRITZBOX</code>, dieses Modul funktioniert lokal (FHEM auf Fritzbox) sowie per Fernzugriff (FHEM auf einem anderen Server im Netz, siehe nächsten Schritt).

==== TR-064: Modul FRITZBOX für Zugriff auf einem externen Server einrichten ====
Für den Fernzugriff über TR-064 auf eine oder mehrere Fritzboxen und/oder einen FRITZ!WLAN Repeater sind die folgenden Schritte nötig (für jedes Gerät):

Fritzbox definieren:
:<code>define FritzBox FRITZBOX</code>

Wenn das Login auf der Benutzeroberfläche der FritzBox mit User und Passwort (und nicht nur per Passwort) geschieht, den User konfigurieren:
:<code>attr FritzBox boxUser ''Benutzername'' </code>

Passwort konfigurieren:
:<code>set FritzBox password ''Passwort'' </code> - legt das zugehörige Passwort fest

Manuelle TR-064 Kommandos erlauben (die Abfrage per TR-064 funktioniert auch ohne dieses Attribut):
:<code>attr FritzBox allowTR064Command 1</code>

Wenn die Fritzbox nicht unter http://fritz.box erreichbar ist, IP setzen:
:<code>attr FritzBox fritzBoxIP 192.168.168.168</code>
192.168.168.168 dabei natürlich durch die passende IP ersetzen... Alternativ kann bei fritzBoxIP - trotz des Namens des Attributs - statt der IP auch der Hostname eingegeben werden, eine DNS-Auflösung findet statt.

Manchmal ist ein Neustart von FHEM erforderlich, damit die Fritzbox mit der veränderten IP gefunden wird.

==== Telnet: Modul FRITZBOX für Zugriff auf einem externen Server einrichten ====
[[Datei:Screenshot_FritzBox_TelnetUser.png|mini|300px|rechts|Anlegen des Attributs telnetUser]]
Bei Fernzugriff über Telnet sind weitere Schritte nötig:
# Telnet auf der Fritzbox freischalten (Tastenkombination #96*7* am angeschlossenen Telefon (auch FritzFon)
# TelnetUser definieren (wie im Screenshot gezeigt)
# Passwort zum Benutzer auf der Fritzbox definieren

[[Datei:Screenshot_FritzBox_Passwort.png|mini|300px|rechts|Passwort definieren]]

(bitte die Buttons {{Taste|set}} und {{Taste|attr}} bei der Definition der jeweiligen Einträge nicht vergessen)

Wer stattdessen lieber das [[Konfiguration|Befehl-Eingabefeld]] verwendet:

:<code>define FritzBox FRITZBOX</code>
:<code>attr FritzBox telnetUser ''Benutzername'' </code> - legt den Benutzer fest
:<code>set FritzBox password ''Passwort'' </code> - legt das zugehörige Passwort fest

Wer keinen User konfiguriert hat, kann das Feld "telnetUser" leer lassen.

Wer sicher gehen möchte, dass auch tatsächlich Telnet und nicht andere Zugriffe benutzt werden, sollte außerdem noch setzen:

:<code>attr FritzBox forceTelnetConnection 1</code>

=== mögliche Fehlermeldungen ===
Sollte schon bei <code>define FritzBox FRITZBOX</code> die Fehlermeldung kommen, dass dieses Modul nicht existiert, dann bitte prüfen, ob Fhem auf dem aktuellen Stand ist und ggf. [[Update|aktualisieren]].

Kommt jetzt bei der erneuten Definition die Fehlermeldung <code>Error: Perl modul Net::Telnet is missing on this system</code> bitte wie oben schon erwähnt den Befehl
:<code>sudo apt-get install libnet-telnet-perl</code>
direkt per Telnet/SSH auf dem FHEM-Server ausführen und neu starten.
Sollte alles geklappt haben, seht ihr nun eure Fritzbox und könnt diverse Einstellungen manuell vornehmen und/oder automatisch vornehmen lassen.

== Anwendung ==
=== Define ===
Siehe [http://fhem.de/commandref_DE.html#FRITZBOX commandref]

=== Attribute ===
Siehe commandref

=== TR-064 ===
Die offizielle Programmier-Schnittstelle der Fritz!Box läuft über das Protokoll TR-064.

mit dem Attribute<br/>
<code>attr <device> allowTR064Command 1</code><br/>
kann man den Befehl<br/>
<code>get <device> tr064Command <service> <control> <action> [[parameterName1 parameterValue1] ...]</code><br/>
freischalten und damit auf diese Schnittstelle zugreifen.

AVM hat die Schnittstellenbeschreibung unter [http://avm.de/service/schnittstellen/] veröffentlicht. Ein weitere Einstiegspunkt befindet sich auch auf der Box unter http://fritz.box:49000/tr64desc.xml

Folgende Service und Controls existieren (für den get-Befehl werden nur die fett formatierten Wörter benötigt)

{| class="wikitable"
|-
!serviceType!!controlURL!!XML!!Dokument bei AVM
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''DeviceInfo:1'''||/upnp/control/'''deviceinfo'''||[http://fritz.box:49000/deviceinfoSCPD.xml deviceinfoSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/deviceinfoSCPD.pdf deviceinfoSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''DeviceConfig:1'''||/upnp/control/'''deviceconfig'''||[http://fritz.box:49000/deviceconfigSCPD.xml deviceconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/deviceconfigSCPD.pdf deviceconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''Layer3Forwarding:1'''||/upnp/control/'''layer3forwarding'''||[http://fritz.box:49000//layer3forwardingSCPD.xml layer3forwardingSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/layer3forwardingSCPD.pdf layer3forwardingSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''LANConfigSecurity:1'''||/upnp/control/'''lanconfigsecurity'''||[http://fritz.box:49000//lanconfigsecuritySCPD.xml lanconfigsecuritySCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/lanconfigsecuritySCPD.pdf lanconfigsecuritySCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''ManagementServer:1'''||/upnp/control/'''mgmsrv'''||[http://fritz.box:49000//mgmsrvSCPD.xml mgmsrvSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/mgmsrvSCPD.pdf mgmsrvSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''Time:1'''||/upnp/control/'''time'''||[http://fritz.box:49000//timeSCPD.xml timeSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/timeSCPD.pdf timeSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''UserInterface:1'''||/upnp/control/'''userif'''||[http://fritz.box:49000//userifSCPD.xml userifSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/userifSCPD.pdf userifSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_VoIP:1'''||/upnp/control/'''x_voip'''||[http://fritz.box:49000//x_voipSCPD.xml x_voipSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_voipSCPD.pdf x_voipSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_Storage:1'''||/upnp/control/'''x_storage'''||[http://fritz.box:49000//x_storageSCPD.xml x_storageSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_storageSCPD.pdf x_storageSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_OnTel:1'''||/upnp/control/'''x_contact'''||[http://fritz.box:49000//x_contactSCPD.xml x_contactSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_contactSCPD.pdf x_contactSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_WebDAVClient:1'''||/upnp/control/'''x_webdav'''||[http://fritz.box:49000//x_webdavSCPD.xml x_webdavSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_webdavSCPD.pdf x_webdavSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_UPnP:1'''||/upnp/control/'''x_upnp'''||[http://fritz.box:49000//x_upnpSCPD.xml x_upnpSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_upnp.pdf x_upnp.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_RemoteAccess:1'''||/upnp/control/'''x_remote'''||[http://fritz.box:49000/x_remoteSCPD.xml x_remoteSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_remoteSCPD.pdf x_remoteSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_MyFritz:1'''||/upnp/control/'''x_myfritz'''||[http://fritz.box:49000/x_myfritzSCPD.xml x_myfritzSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_myfritzSCPD.pdf x_myfritzSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_TAM:1'''||/upnp/control/'''x_tam'''||[http://fritz.box:49000/x_tamSCPD.xml x_tamSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_tam.pdf x_tam.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_AppSetup:1'''||/upnp/control/'''x_appsetup'''||[http://fritz.box:49000/x_homeautoSCPD.xml x_homeautoSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_appsetupSCPD.pdf x_appsetupSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_Homeauto:1'''||/upnp/control/'''x_homeauto'''||[http://fritz.box:49000/x_homeautoSCPD.xml x_homeautoSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_homeautoSCPD.pdf x_homeautoSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WLANConfiguration:1'''||/upnp/control/'''wlanconfig1'''||[http://fritz.box:49000/wlanconfigSCPD.xml wlanconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wlanconfigSCPD.pdf wlanconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WLANConfiguration:2'''||/upnp/control/'''wlanconfig2'''||[http://fritz.box:49000/wlanconfigSCPD.xml wlanconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wlanconfigSCPD.pdf wlanconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WLANConfiguration:3'''||/upnp/control/'''wlanconfig3'''||[http://fritz.box:49000/wlanconfigSCPD.xml wlanconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wlanconfigSCPD.pdf wlanconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''Hosts:1'''||/upnp/control/'''hosts'''||[http://fritz.box:49000/hostsSCPD.xml hostsSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/hostsSCPD.pdf hostsSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''LANEthernetInterfaceConfig:1'''||/upnp/control/'''lanethernetifcfg'''||[http://fritz.box:49000/lanifconfigSCPD.xml lanifconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/lanifconfigSCPD.pdf lanifconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''LANHostConfigManagement:1'''||/upnp/control/'''lanhostconfigmgm'''||[http://fritz.box:49000/lanhostconfigmgmSCPD.xml lanhostconfigmgmSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/lanhostconfigmgmSCPD.pdf lanhostconfigmgmSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANCommonInterfaceConfig:1'''||/upnp/control/'''wancommonifconfig1'''||[http://fritz.box:49000/wancommonifconfigSCPD.xml wancommonifconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wancommonifconfigSCPD.pdf wancommonifconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANDSLInterfaceConfig:1'''||/upnp/control/'''wandslifconfig1'''||[http://fritz.box:49000/wandslifconfigSCPD.xml wandslifconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wandslifconfigSCPD.pdf wandslifconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANDSLLinkConfig:1'''||/upnp/control/'''wandsllinkconfig1'''||[http://fritz.box:49000/wandsllinkconfigSCPD.xml wandsllinkconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wandsllinkconfigSCPD.pdf wandsllinkconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANEthernetLinkConfig:1'''||/upnp/control/'''wanethlinkconfig1'''||[http://fritz.box:49000/wanethlinkconfigSCPD.xml wanethlinkconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wanethlinkconfigSCPD.pdf wanethlinkconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANPPPConnection:1'''||/upnp/control/'''wanpppconn1'''||[http://fritz.box:49000/wanpppconnSCPD.xml wanpppconnSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wanpppconnSCPD.pdf wanpppconnSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANIPConnection:1'''||/upnp/control/'''wanipconnection1'''||[http://fritz.box:49000/wanipconnSCPD.xml wanipconnSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wanipconnSCPD.pdf wanipconnSCPD.pdf]
|-
|}

=== Status-Symbol ===
<code>attr <device> devStateIcon .*on.*off:WLAN_on_gWLAN_off .*on.*on.*:WLAN_on_gWLAN_on WLAN..off.*:WLAN_off</code>

Im Verzeichnis www/images/default müssen die passenden Dateien "WLAN_on_gWLAN_off.png", "WLAN_on_gWLAN_on.png" und "WLAN_off.png" liegen. Wenn die PNGs fehlen, können sie hier [http://forum.fhem.de/index.php/topic,29725.msg318113.html#msg318113] heruntergeladen werden.

== Anwendungsbeispiele ==
[[Datei:Screenshot_FritzBox1.png|mini|300px|rechts|FRITZBOX Gerät auf der Fhem Oberfläche]]
Sollte alles geklappt haben, seht ihr nun unter "Unsortiert" den im nebenstehenden Screenshot gezeigten Eintrag für das "Gerät" (hier mit dem Icon "it_router").

=== TR-064 Bespiele ===

*Box Reboot: <code>get <device> tr064Command DeviceConfig:1 deviceconfig Reboot</code>

=== Klingel- und Sprachausgabe per TR-064 ===

Das geht derzeit nicht, da entsprechende Kommandos per TR-064 nicht verfügbar sind. Da Telnet sukzessive abgestellt wird, sollten sich Interessenten per Feature-Request an AVM wenden, wie hier [http://forum.fhem.de/index.php/topic,38586.0.html] beschrieben.

=== Anwesenheitserkennung per regelmäßiger Abfrage über das PRESENCE Modul ===

Fritzboxen und die FRITZ!WLAN Repeater speichern den Status angemeldeter Geräte. Dieser Status lässt sich mittels des FRITZBOX Moduls über Readings abfragen, die das Format mac_AA_AA_AA_AA_AA_AA haben und die MAC-Adressen der jeweils angemeldeten Geräte (AA:AA:AA:AA:AA:AA) enthalten. Das Reading existiert, wenn das Gerät angemeldet ist. Wenn das Gerät abgemeldet ist, existiert es nicht mehr. Es gibt auch noch den Zwischenstatus "inactive", der anscheinend gesetzt wird, bevor das Reading gelöscht wird.

Mit Hilfe des PRESENCE Moduls (vgl. [[Anwesenheitserkennung]]) kann man auf diese Weise den Anwesenheitsstatus abfragen. Anregungen dazu gibt es im zugehörigen {{Link2Forum|Topic=39433|LinkText=Forenthread}} zur Anwesenheitserkennung und in einem Blogpost: [http://heinz-otto.blogspot.de/2015/07/die-zeiten-andern-sich.html]. Auf dieser Basis könnte eine einfache Implementierung zum Beispiel so aussehen:

Funktion in 99_myUtils.pm:

<pre>sub checkFritzMACpresent($$) {
# Benötigt: Name der zu testenden Fritzbox ($Device),
# zu suchende MAC ($MAC),
# Rückgabe: 1 = Gerät gefunden
# 0 = Gerät nicht gefunden
my ($Device, $MAC) = @_;
my $Status = 0;
$MAC =~ tr/:/_/;
$MAC = "mac_".uc($MAC);
my $StatusFritz = ReadingsVal($Device, $MAC, "weg");
if ($StatusFritz eq "weg") {
Log 1, ("checkFritzMACpresent ($Device): $MAC nicht gefunden, abwesend.");
$Status = 0;
} elsif ($StatusFritz eq "inactive") {
Log 1, ("checkFritzMACpresent ($Device): $MAC ist >inactive<, also abwesend.");
$Status = 0;
} else {
# Reading existiert, Rückgabewert ist nicht "inactive", also ist das Gerät per WLAN angemeldet.
Log 1, ("checkFritzMACpresent ($Device): $MAC gefunden, Gerät heißt >$StatusFritz<.");
$Status = 1;
}
return $Status
}
</pre>

Nutzung dieser Funktion mit dem PRESENCE Modul definieren:

<code>define <Name> PRESENCE function {checkFritzMACpresent("Fritzbox","AA:BB:CC:DD:EE:FF")} 60 60</code>

wobei
*<Name> ein beliebig zu wählender Name für die PRESENCE-Funktion ist,
*Fritzbox der Name ist, mit dem ihr die abzufragende Fritzbox als FRITZBOX definiert habt,
*AA:BB:CC:DD:EE:FF die MAC-Adresse des gesuchten Geräts ist.
* "60 60" sagt, dass der Anwesenheitsstatus im 60-Sekunden-Takt abgefragt wird. Das macht natürlich nur Sinn, wenn ihr mit <code>attr Fritzbox INTERVAL 60</code> den Abfrageinterval bei der Fritzbox auch entsprechend hochgesetzt habt. Der Standard ist 300.
* "Log 1" führt immer zum Loggen. Das ist zum Einrichten praktisch, ohne dass man gleich für das ganze Modul oder ganz FHEM <code>attr <device> verbose 5</code> setzen muss. Wenn es läuft, können die "Log 1"-Zeilen gelöscht, auskommentiert (# an den Zeilenanfang) oder in "Log 5" geändert werden.

==== Mehrere Fritzboxen oder Repeater und Fritzbox (wird noch bearbeitet) ====
Existiert ein AVM Repeater im Netzwerk, kann der als eigenständiges Gerät mit FRITZBOX definiert werden. WLAN Geräte an der Fritzbox werden in der Instanz der Fritzbox gelistet und WLAN Geräte am Repeater in der Repeater Instanz. Um trotzdem die Anwesenheit im Netzwerk einfach zu erkennen muss die Subroutine in 99_myUtils abgewandelt werden.

<pre>my @fbs = devspec2array("TYPE=FRITZBOX"); (Nur als Hinweis)
</pre>

Existiert eine zweite Fritzbox im Accesspointmodus werden die WLAN Geräte im Netzwerk alle in der Hauptfritzbox an einem LAN Anschluss gelistet. D.h. man sieht an der Hauptfritzbox nicht, dass sie im WLAN sind. Eine zweite Instanz mit dem FRITZBOX Modul muss wegen der Anwesenheitserkennung nicht gemacht werden.

Weitere Hinweise zu komplexeren Abfragen mehrere Boxen auf einmal etc. findet ihr auch im {{Link2Forum|Topic=39433|LinkText=Forenthread}}.

=== Anwesenheitserkennung per Notify ===
Der von Fritzboxen und Fritz!WLAN Repeatern gespeicherte Status zum Status angemeldeter Geräte lässt sich (statt per PRESENCE, s.o.) auch per Notify anfragen:

<pre>define <Name> notify Fritzbox:mac_AA_BB_CC_DD_EE_FF:.* {
if (ReadingsVal("Fritzbox", "mac_AA_BB_CC_DD_EE_FF", "inactive") eq "inactive") {
fhem("set anwesend_smartphone absent");
} else
fhem("set anwesend_smartphone present");
}
}</pre>

Hinweise:
*[code]fhem("set anwesend_smartphone absent");[/code] ist nur ein Beispiel, das einen Dummy auf den Status "absent" bzw. "present" setzt. Man kann hier natürlich auch gleich entsprechende Aktionen durchführen. Wer das Beispiel übernehmen möchte, sollte den Dummy vorher definieren ([code]define anwesend_smartphone dummy[/code]).
*mac_AA_BB_CC_DD_EE_FF ist die MAC-Adresse des gesuchten Geräts.
*"Fritzbox" ist der Name, unter dem die Fritzbox als FRITZBOX-Modul definiert wurde.
*Das Notify funktioniert, weil Geräte, wenn sie sich abgemeldet haben, erst den Status "inactive" erhalten. Ist das Gerät ganz abgemeldet, verschwindet das mac_.*-Reading. Dabei löst das Notify nicht mehr aus. Da das mac-.*-Reading aber vorher auf "inactive" stand, wurde die Abwesend-Aktion schon ausgeführt.
*Damit der Notify nicht andauernd losgeht, sollte man mittels [code]attr Fritzbox event-on-change-reading mac_AA_BB_CC_DD_EE_FF[/code] Events nur auslösen, wenn sich der Status des Gerätes ändert. Will man mehrere Geräte abfragen, sollte man [code]attr Fritzbox event-on-change-reading mac_AA_BB_CC_DD_EE_FF,mac_GG_HH_II_JJ_KK_LL[/code] setzen, damit bei der Änderung jedes Readings ein Event ausgelöst wird.

=== Vergleich Anwesenheitserkennung PRESENCE/Notify ===
Die Anwesenheitserkennung per regelmäßiger PRESENCE-Abfrage hat den Vorteil, dass sie im Turnus der regelmäßigen Abfragen immer einen aktuellen Status produziert. Sie hat dafür den Nachteil, dass die PRESENCE-Funktionen regelmäßig abgearbeitet werden müssen, auch wenn sich gar nichts ändert. Außerdem aktualisiert sich der Status nicht sofort, sondern erst bei der nächsten regelmäßigen Abfrage. Durch häufiges Abfragen, kann dieser Nachteil verringert werden (bei entsprechend höherer Systemlast).

Die Anwesenheitserkennung per Notify hat den Vorteil, dass ein sich ändernder Status sofort abgebildet wird. Ändert sich kein Status, werden keine Routinen ausgeführt, was die Systemlast gering hält. Der Nachteil ist, dass - z.B. nach einem Systemstart - die entsprechende Aktion erst bei einer Änderung des Status ausgeführt wird. D.h. ist das zu testende Gerät anwesend, wird dann FHEM beendet, das Gerät entfernt und FHEM wieder gestartet, ist der Status in FHEM immer noch "anwesend". Da das Reading für das Gerät nicht existiert, wird darauf auch erst wieder ein Notify ausgeführt, wenn sich der Status des Geräts wieder ändert, d.h. es wieder ankommt. Bis dahin ist der Status im System falsch.
Der Nachteil des Notify kann verringert werden, wenn man statt [code]attr Fritzbox event-on-change-reading mac_AA_BB_CC_DD_EE_FF[/code] ein [code]attr Fritzbox event-on-update-reading mac_AA_BB_CC_DD_EE_FF[/code] setzt. Das erhöht allerdings die Systemlast und funktioniert auch nur für den Status "anwesend". Bei "abwesend" ist kein Reading vorhanden, so dass auch event-on-update-reading nicht ausgeführt wird.
Eine weitere Möglichkeit, den Nachteil der Notify-Methode auszugleichen, ist, die Statusabfrage beim Systemstart einmal manuell auszuführen, durch ein notify auf "GLOBAL:initialized":
<pre>
global:INITIALIZED {
Reset_Variables;
if (ReadingsVal("Fritzbox", "mac_AA_BB_CC_DD_EE_FF", "inactive") eq "inactive") {
fhem("set anwesend_smartphone absent");
} else
fhem("set anwesend_smartphone present");
}
}
</pre>
Das hilft allerdings nur beim Systemstart. Nicht, wenn FHEM aufgrund irgendwelcher Hänger eine Aktualisierung des Status' verpasst hat.

== Links ==
* {{Link2Forum|Topic=29725|LinkText=Forenthread}} zu diesem Modul

[[Kategorie:FritzBox]]

FRITZBOX

2015-06-29T19:04:40Z

Stormmurdoc: libjson-xs-perl hinzugefuegt

{{Infobox Modul
|ModPurpose=Steuerung einer Fritz!Box über Fhem
|ModType=d
|ModForumArea=Sonstiges
|ModTechName=72_FRITZBOX.pm
|ModOwner=tupol/Topos ([http://forum.fhem.de/index.php?action=profile;u=5432 Forum] / [[Benutzer Diskussion:Topos|Wiki]])}}

Das Modul [[FRITZBOX]] ermöglicht die Steuerung einer [[AVM Fritz!Box]] durch Fhem. Dabei kann es sich dabei sowohl um eine FritzBox handeln, auf der Fhem selbst läuft (lokaler Modus), als auch um eine entfernte (externe) FritzBox.

== Voraussetzungen ==
Um das Modul für den Zugriff auf eine externe FritzBox benutzen zu können, muss
# Telnet auf der entsprechenden FritzBox erlaubt/freigeschaltet sein (üblicherweise durch Eingabe von #96*7* an einem direkt an der entsprechenden FritzBox angeschlosssenen Telefon)
# Auf dem System, auf dem Fhem läuft ([[Systemübersicht#Server|Server]]) muss Telnet installiert sein; auf einem [[Raspberry Pi]] z. B. mit dem Befehl
:::<code>sudo apt-get install libnet-telnet-perl</code>
Für einen (begrenzten) Remote-Zugang ohne Telnet müssen die Module JSON:XS, LWP und SOAP::Lite installiert sein; auf einem [[Raspberry Pi]] z. B. mit dem Befehl
:::<code>sudo apt-get install libjson-perl libwww-perl libsoap-lite-perl libjson-xs-perl</code>

== Installation ==

=== Erste Schritte ===
Zur Erstinstallation reicht ein einfaches <code>define FritzBox FRITZBOX</code>, dieses Modul funktioniert lokal (FHEM auf Fritzbox) sowie per Fernzugriff(FHEM auf einem anderen Server im Netz, siehe nächsten Schritt).

==== Modul FRITZBOX für Zugriff auf einem externen Server einrichten ====
[[Datei:Screenshot_FritzBox_TelnetUser.png|mini|300px|rechts|Anlegen des Attributs telnetUser]]
Bei Fernzugriff sind weitere Schritte nötig:
# Telnet auf der Fritzbox freischalten (Tastenkombination #96*7* am angeschlossenen Telefon (auch FritzFon)
# TelnetUser definieren (wie im Screenshot gezeigt)
# Passwort zum Benutzer auf der Fritzbox definieren

[[Datei:Screenshot_FritzBox_Passwort.png|mini|300px|rechts|Passwort definieren]]

(bitte die Buttons {{Taste|set}} und {{Taste|attr}} bei der Definition der jeweiligen Einträge nicht vergessen)

==== ...für die Profis ====
(die Telnet auf ihrer FritzBox vermutlich ohnehin längst aktiviert haben)

hier die Befehle für das [[Konfiguration|Befehl-Eingabefeld]]:

:<code>define FritzBox FRITZBOX</code>
:<code>attr Fritzbox telnetUser ''Benutzername'' </code> - legt den Benutzer fest
:<code>set Fritzbox password ''Passwort'' </code> - legt das zugehörige Passwort fest

=== mögliche Fehlermeldungen ===
Sollte schon bei <code>define FritzBox FRITZBOX</code> die Fehlermeldung kommen, dass dieses Modul nicht existiert, dann bitte prüfen, ob Fhem auf dem aktuellen Stand ist und ggf. [[Update|aktualisieren]].

Kommt jetzt bei der erneuten Definition die Fehlermeldung <code>Error: Perl modul Net::Telnet is missing on this system</code> bitte wie oben schon erwähnt den Befehl
:<code>sudo apt-get install libnet-telnet-perl</code>
direkt per Telnet/SSH auf dem FHEM-Server ausführen und neu starten.
Sollte alles geklappt haben, seht ihr nun eure Fritzbox und könnt diverse Einstellungen manuell vornehmen und/oder automatisch vornehmen lassen.

== Anwendung ==
=== Define ===
Siehe [http://fhem.de/commandref_DE.html#FRITZBOX commandref]

=== Attribute ===
Siehe commandref

====Status-Symbol====
<code>attr <device> devStateIcon .*on.*off:WLAN_on_gWLAN_off .*on.*on.*:WLAN_on_gWLAN_on WLAN..off.*:WLAN_off</code>

Im Verzeichnis www/images/default müssen die passenden Dateien "WLAN_on_gWLAN_off.png", "WLAN_on_gWLAN_on.png" und "WLAN_off.png" liegen.

== Anwendungsbeispiele ==
[[Datei:Screenshot_FritzBox1.png|mini|300px|rechts|FRITZBOX Gerät auf der Fhem Oberfläche]]
Sollte alles geklappt haben, seht ihr nun unter "Unsortiert" den im nebenstehenden Screenshot gezeigten Eintrag für das "Gerät" (hier mit dem Icon "it_router").

== TR-064 ==
Die offizielle Programmier-Schnittstelle der Fritz!Box läuft über das Protokoll TR-064.

mit dem Attribute<br/>
<code>attr <device> allowTR064Command 1</code><br/>
kann man den Befehl<br/>
<code>get <device> tr064Command <service> <control> <action> [[parameterName1 parameterValue1] ...]</code><br/>
freischalten und damit auf diese Schnittstelle zugreifen.

AVM hat die Schnittstellenbeschreibung unter [http://avm.de/service/schnittstellen/] veröffentlicht. Ein weitere Einstiegspunkt befindet sich auch auf der Box unter http://fritz.box:49000/tr64desc.xml

Folgende Service und Controls existieren (für den get-Befehl werden nur die fett formatierten Wörter benötigt)

{| class="wikitable"
|-
!serviceType!!controlURL!!XML!!Dokument bei AVM
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''DeviceInfo:1'''||/upnp/control/'''deviceinfo'''||[http://fritz.box:49000/deviceinfoSCPD.xml deviceinfoSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/deviceinfoSCPD.pdf deviceinfoSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''DeviceConfig:1'''||/upnp/control/'''deviceconfig'''||[http://fritz.box:49000/deviceconfigSCPD.xml deviceconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/deviceconfigSCPD.pdf deviceconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''Layer3Forwarding:1'''||/upnp/control/'''layer3forwarding'''||[http://fritz.box:49000//layer3forwardingSCPD.xml layer3forwardingSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/layer3forwardingSCPD.pdf layer3forwardingSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''LANConfigSecurity:1'''||/upnp/control/'''lanconfigsecurity'''||[http://fritz.box:49000//lanconfigsecuritySCPD.xml lanconfigsecuritySCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/lanconfigsecuritySCPD.pdf lanconfigsecuritySCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''ManagementServer:1'''||/upnp/control/'''mgmsrv'''||[http://fritz.box:49000//mgmsrvSCPD.xml mgmsrvSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/mgmsrvSCPD.pdf mgmsrvSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''Time:1'''||/upnp/control/'''time'''||[http://fritz.box:49000//timeSCPD.xml timeSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/timeSCPD.pdf timeSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''UserInterface:1'''||/upnp/control/'''userif'''||[http://fritz.box:49000//userifSCPD.xml userifSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/userifSCPD.pdf userifSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_VoIP:1'''||/upnp/control/'''x_voip'''||[http://fritz.box:49000//x_voipSCPD.xml x_voipSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_voipSCPD.pdf x_voipSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_Storage:1'''||/upnp/control/'''x_storage'''||[http://fritz.box:49000//x_storageSCPD.xml x_storageSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_storageSCPD.pdf x_storageSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_OnTel:1'''||/upnp/control/'''x_contact'''||[http://fritz.box:49000//x_contactSCPD.xml x_contactSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_contactSCPD.pdf x_contactSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_WebDAVClient:1'''||/upnp/control/'''x_webdav'''||[http://fritz.box:49000//x_webdavSCPD.xml x_webdavSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_webdavSCPD.pdf x_webdavSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_UPnP:1'''||/upnp/control/'''x_upnp'''||[http://fritz.box:49000//x_upnpSCPD.xml x_upnpSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_upnp.pdf x_upnp.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_RemoteAccess:1'''||/upnp/control/'''x_remote'''||[http://fritz.box:49000/x_remoteSCPD.xml x_remoteSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_remoteSCPD.pdf x_remoteSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_MyFritz:1'''||/upnp/control/'''x_myfritz'''||[http://fritz.box:49000/x_myfritzSCPD.xml x_myfritzSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_myfritzSCPD.pdf x_myfritzSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_TAM:1'''||/upnp/control/'''x_tam'''||[http://fritz.box:49000/x_tamSCPD.xml x_tamSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_tam.pdf x_tam.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_AppSetup:1'''||/upnp/control/'''x_appsetup'''||[http://fritz.box:49000/x_homeautoSCPD.xml x_homeautoSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_appsetupSCPD.pdf x_appsetupSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''X_AVM-DE_Homeauto:1'''||/upnp/control/'''x_homeauto'''||[http://fritz.box:49000/x_homeautoSCPD.xml x_homeautoSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/x_homeautoSCPD.pdf x_homeautoSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WLANConfiguration:1'''||/upnp/control/'''wlanconfig1'''||[http://fritz.box:49000/wlanconfigSCPD.xml wlanconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wlanconfigSCPD.pdf wlanconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WLANConfiguration:2'''||/upnp/control/'''wlanconfig2'''||[http://fritz.box:49000/wlanconfigSCPD.xml wlanconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wlanconfigSCPD.pdf wlanconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WLANConfiguration:3'''||/upnp/control/'''wlanconfig3'''||[http://fritz.box:49000/wlanconfigSCPD.xml wlanconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wlanconfigSCPD.pdf wlanconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''Hosts:1'''||/upnp/control/'''hosts'''||[http://fritz.box:49000/hostsSCPD.xml hostsSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/hostsSCPD.pdf hostsSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''LANEthernetInterfaceConfig:1'''||/upnp/control/'''lanethernetifcfg'''||[http://fritz.box:49000/lanifconfigSCPD.xml lanifconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/lanifconfigSCPD.pdf lanifconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''LANHostConfigManagement:1'''||/upnp/control/'''lanhostconfigmgm'''||[http://fritz.box:49000/lanhostconfigmgmSCPD.xml lanhostconfigmgmSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/lanhostconfigmgmSCPD.pdf lanhostconfigmgmSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANCommonInterfaceConfig:1'''||/upnp/control/'''wancommonifconfig1'''||[http://fritz.box:49000/wancommonifconfigSCPD.xml wancommonifconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wancommonifconfigSCPD.pdf wancommonifconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANDSLInterfaceConfig:1'''||/upnp/control/'''wandslifconfig1'''||[http://fritz.box:49000/wandslifconfigSCPD.xml wandslifconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wandslifconfigSCPD.pdf wandslifconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANDSLLinkConfig:1'''||/upnp/control/'''wandsllinkconfig1'''||[http://fritz.box:49000/wandsllinkconfigSCPD.xml wandsllinkconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wandsllinkconfigSCPD.pdf wandsllinkconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANEthernetLinkConfig:1'''||/upnp/control/'''wanethlinkconfig1'''||[http://fritz.box:49000/wanethlinkconfigSCPD.xml wanethlinkconfigSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wanethlinkconfigSCPD.pdf wanethlinkconfigSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANPPPConnection:1'''||/upnp/control/'''wanpppconn1'''||[http://fritz.box:49000/wanpppconnSCPD.xml wanpppconnSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wanpppconnSCPD.pdf wanpppconnSCPD.pdf]
|-
|<nowiki>urn:dslforum-org:service:</nowiki>'''WANIPConnection:1'''||/upnp/control/'''wanipconnection1'''||[http://fritz.box:49000/wanipconnSCPD.xml wanipconnSCPD.xml]||[http://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/wanipconnSCPD.pdf wanipconnSCPD.pdf]
|-
|}

== TR-064 Bespiele ==

*Box Reboot: <code>get <device> tr064Command DeviceConfig:1 deviceconfig Reboot</code>

== Links ==
* {{Link2Forum|Topic=29725|LinkText=Forenthread}} zu diesem Modul

[[Kategorie:FritzBox]]

DevelopmentModuleIntro

2015-03-08T16:18:43Z

Stormmurdoc: Hello World hinzugefügt

== 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 ==
Eine Besonderheit in Perl sind [http://de.wikipedia.org/wiki/Assoziatives_Array#Perl assoziative Arrays], (nicht ganz richtig als "Hash" bezeichnet) in denen die Adressierung nicht über eine Zählvariable erfolgt, sondern über einen beliebigen String. Die internen Abläufe bei der Adressierung führen dazu, dass die Speicherung in und der Abruf aus Hashes relativ langsam ist.

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

<code>$defs{''Devicename''}</code> in fhem.pl verweist auf den Hash der Geräteinstanz. Diesen Verweis (also nur die Adresse) bekommen die Funktionen eines Moduls übergeben, das direkt von fhem.pl aufgerufen wird. In dem Hash stehen beispielsweise die internen Werte des Geräts, die im GUI als "Internals" angezeigt werden oder die Readings des Geräts. Beispiele:
*<code>$hash{NAME}</code> enthält den Namen der Geräteinstanz,
*<code>$hash{TYPE}</code> enthält die Typbezeichnung des Geräts
*<code>$hash->{INTERVAL}</code> enthält ein Abfrageintervall

==Ausführung von Modulen==
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 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.

== Readings ==
Werte, die von einem Gerät gelesen werden und in FHEM zur Verfügung stehen werden Readings genannt. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise
*<code>$hash{READINGS}{Temp}{VAL}</code> für die Temperatur eines Fühlers
*<code>$hash{READINGS}{Temp}{TIME}</code> für den Zeitstempel der Messung

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.

Zum Setzen von Readings sollen
*bei Gruppen von Readings der Funktionsblock <code>readingsBeginUpdate</code>, <code>readingsBulkUpdate</code> (mehrfach wiederholt), <code>readingsEndUpdate</code>
*bei einzelnen Updates die Funktion <code>readingsSingleUpdate</code>
aufgerufen werden. 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>

== Internals ==
Werte, die das Modul intern als Teil des Hashes speichert, die aber keine Readings sind, nennt man Internals. Sie werden ebenfalls 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.

Falls Werte wie das gerade erwähnte Intervall nicht über den Define-Befehl gesetzt werden sollen und im Betrieb einfach änderbar sein sollen, ist eine alternative Möglichkeit die Speicherung in so genannten Attributen. Dann würde man den Define-Befehl so implementieren, dass er kein Intervall übergeben bekommt und statt dessen nach dem Define-Befehl zusätzlich den Befehl <code>attr</code> erwarten.

== Attribute ==
Parameter einer Geräteinstanz können mit dem Befehl <code>attr</code> 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 Konfigurationsdatei geschrieben, die auch bei jedem Neustart von FHEM wieder gelesen wird. Zur Laufzeit werden Attribute in der globalen Datenstruktur <code>$attr{$name}</code> gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielsweise mit <code>$attr{$name}{header}</code> adressiert (<code>$attr{$name}->{'header'}</code> wäre eine alternative aber unübliche Schreibweise für die selbe 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|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|X_Attr]]</code> ([[#X_Attr|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|X_Initialize]] (initialisiert das Modul und gibt de Namen der zusätzlichen Funktionen bekannt)
* [[#X_Define|X_Define]] (wird beim <code>define</code> aufgerufen)
* [[#X_Undef|X_Undef]] (wird beim Löschen einer Geräteinstanz aufgerufen - Gegenteil zu <code>define</code>)
* [[#X_Set|X_Set]] (wird beim Befehl <code>set</code> aufgerufen um Daten an das Gerät zu senden)
* [[#X_Get|X_Get]] (wird beim Befehl <code>get</code> aufgerufen um Daten vom Gerät abzufragen)
* [[#X_Attr|X_Attr]] (wird beim Befehl <code>attr</code> aufgerufen um beispielsweise Werte zu prüfen)
* [[#X_Read|X_Read]] (wird vom globalen select aufgerufen, falls Daten zur Verfuegung stehen)
* [[#X_Parse|X_Parse]] (wird bei zweistufigen Modulen vom Dispatch aufgerufen und muss hier noch beschrieben werden)
* [[#X_Ready|X_Ready]] (wird unter windows als ReadFn-Erstatz benoetigt bzw. um zu pruefen, ob ein Geraet wieder eingesteckt ist)
* [[#X_Notify|X_Notify]] (falls man benachrichtigt werden will)
* [[#X_Rename|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.

Dieser Hash wird im globalen Hash %modules gespeichert. <code>$modules{$ModulName}</code> wäre dabei der Hash für das Modul mit dem Namen <code>$ModulName</code>. Es handelt sich also nicht um den oben beschriebenen Hash der Geräteinstanzen sondern einen Hash, der je Modul Werte enthält, beispielsweise auch die Namen der Funktionen, die das Modul implementiert und die fhem.pl aufrufen soll. Die Initialize-Funktion setzt diese Funktionsnamen, in den Hash des Moduls:

<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-Funktion 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 typischerweise 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_DevInit</code> 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 oder bei der Abarbeitung des Befehls rereadcfg, der ebenfalls alle Geräte löscht und danach das Konfigurationsfile neu abarbeitet. 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).

Zugewiesene Variablen im Hash der Geräteinstanz, Internals oder Readings müssen hier nicht gelöscht werden. In fhem.pl werden die entsprechenden Strukturen beim Löschen der Geräteinstanz ohnehin vollständig gelöscht.

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 $opt, choose one of " . join(" ", @cList);
}
...
</pre>

Die Ausgabe der Meldung mit <code>unknown ... 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 $value = join("", @a);

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

Das GUI FHEM-Web kann für die einzelnen Set-Optionen, die das Modul versteht auch automatisch Eingabehilfen wie Drop-Down Boxen oder Slider erzeugen. In der Detailansicht des GUI kann der Anwender dann die jeweiligen Werte komfortabel auswählen. Dafür muss die Set-Funktion, wenn sie mit der Option <code>?</code> aufgerufen wird, nicht nur einen Text mit <code>"Unknwon ... choose one of ..."</code> zurückgeben sondern den einzelnen Set-Optionen in diesem Rückgabetext nach einem Doppelpunkt Zusatzinformationen anhängen.
Meist prüft man in den Modulen gar nicht auf die Option <code>?</code> sondern gibt generell bei unbekannten Optionen diesen Text zurück.

Beispiel:
<pre>
if(!defined($X_sets{$opt})) {
return "Unknown argument $opt, choose one of mode:verbose,ultra,relaxed turbo:NoArg";
}
</pre>

Die möglichen Zusatzinformationen sind:

'''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 muss.
<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>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

'''Hinweise'''

- Damit in einer Eingabe bereits der aktuelle Wert vorbelegt bzw. in einer Auswahlliste der aktuelle Wert vorselektiert ist, muss es im Modul bzw. Gerät ein Reading mit dem gleichen Namen wie die Set-Option geben. Der Wert des gleichnamigen Readings wird dann als Vorbelegung / Vorselektion verwendet.

- 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 muss 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|X_Initialize]]-Funktion</code> definiert ([[#X_Initialize|siehe oben]]). Fhem ruft bei einem Attr-Befehl die zuständige <code>X-Attr-Funktion</code> auf und wenn diese keine Fehlermeldung 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 <code>undef</code> zurückgegeben und fhem.pl speichert den Wert des Attributs.

Falls man Attribute mit Platzhaltern definiert (Wildcard-Attribute), z.B. mit
<pre>
$hash->{AttrList} =
"reading[0-9]*Name " .
# usw.
</pre>
dann können Anwender Attribute wie reading01Name, reading02Name etc. setzen. Leider funktioniert das bisher nicht durch Klicken, da Fhemweb nicht alle denkbaren Ausprägungen in einem Dropdown anbieten kann. Der Benutzer muß solche Attribute über den <code>attr</code> Befehl eintippen.

Man kann jedoch in der Attr-Funktion neu gesetzte Ausprägungen von Wildcard-Attributen an die gerätespezifische userattr-Variable anfügen. Dann können bereits gesetzte Attribute in Fhemweb durch Klicken ausgewählt und geändert werden.
Dazu reicht ein Aufruf von

<pre>
addToDevAttrList($name, $aName);
</pre>

in der Attr-Funktion wenn ein Attribut gesetzt wird.

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

=== X_Notify ===

Die X_Notify-Funktion wird aus der Funktion DoTrigger in fhem.pl heraus aufgerufen wenn ein Modul Events erzeugt hat. Damit kann ein Modul auf Events anderer Module reagieren. Typische Beispiele sind das Filelog-Modul oder das Average-Modul. Average reagiert auf Events anderer Module und erweitert diese mit der Berechnung von Tages- und Monats-Durchschnittswerten.

Die Notify-Funktion bekommt dafür zwei Hashes übergeben: den Hash des eigenen Geräts und den Hash des Geräts, das die Events erzeugt hat.
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.
Über den Hash des Geräts, das die Events erzeugt hat, kann es die Events verarbeiten. Events werden je Gerät in einem Array, das über das Internal <code>CHANGED</code> referenziert wird, gespeichert.

Beispiel:
<pre>
sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash
my $devName = $dev_hash->{NAME}; # Device that created the events

return "" if(AttrVal($ownName, "disable", undef)); # Abbruch wenn das Attribut disable gesetzt ist

my $max = int(@{$dev_hash->{CHANGED}}); # number of events / changes

for (my $i = 0; $i < $max; $i++) {
my $s = $dev->{CHANGED}[$i];

</pre>

Da die Notify-Funktion für jedes Gerät mit allen seinen Events aufgerufen wird, muss sie in einer Schleife alle Events prüfen und entscheiden, ob es mit dem jeweiligen Event etwas tun möchte. Ein Gerät, das die Notify-Funktion implementiert sieht dafür typischerweise einen regulären Ausdruck vor, der für die Filterung verwendet wird.
Als anschauliches Beispiel und für weitere Details eignet sich das Modul 98_Average.pm

=== X_DbLog_splitFn ===
Mit der DbLog_SplitFn kann der Modulautor selbst festlegen, wie die Events des Moduls in die Bestandteile Reading/Value/Unit zerlegt werden um ein korrektes Logging per DbLog zu gewährleisten.<br>
Eingangsparameter: Das generierte Event<br>
Rückgabewerte: Array: Reading/Value/Unit

Beispiel:
<pre>
sub X_DbLog_splitFn($)
{
my ($event) = @_;
my ($reading, $value, $unit);

if($event =~ m/temperature/) {
$reading = 'temperature';
$value = substr($event,12,4);
$unit = '°C';
}

return ($reading, $value, $unit);
}
</pre>

== 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, den zu übergebenden Parameter und ein Flag ob der erste Aufruf verzögert werden soll falls die Initialiserung des Geräts noch nicht abgeschlossen ist. Als zu übergebender Parameter wird üblicherweise der Hash der betroffenen Geräteinstanz verwendet. Damit hat die aufgerufene Funktion Zugriff auf alle wichtigen Daten der Geräteinstanz. Eventuell zusätzlich benötigte Werte können einfach als weitere Internals über den Hash zugänglich gemacht werden.

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.

== Zweistufiges Modell für Module ==
siehe auch
* [http://forum.fhem.de/index.php/topic,18920.msg128100.html#msg128100|The FHEM two-level model]
* [http://forum.fhem.de/index.php/topic,13438.msg83643.html#msg83643|Zum Initialize bei physikalischen und logischen Geräten]

Das zweistufige Modell besteht aus
* physisches Modul - z.B. für CUL (00_CUL.pm), der mehrer Protokolle empfängt, u.a. FS20
* logische Modul(e) - z.B. das Protokoll FS20 (10_FS20.pm)

Das physische Modul öffnet die Datenverbindung zum Gerät.

=== Kommunikation vom Gerät zu den logischen Modulen ===
Die [[#X_Read|X_Read]]-Funktion wird aus der Hauptschleife von Fhem aufgerufen sobald das Gerät, für das das Modul zuständig ist, Daten bereit gestellt hat, die gelesen werden können.

Unter Windows funktioniert "select" nur für Geräte, die via TCP verbunden sind. Für alle anderen Geräte ist eine [[#X_Ready|X_Ready]]-Funktion von Nöten, die 10x pro Sekunde das Gerät abfrägt und "true" zurück gibt, sollten Daten bereit stehen.

Die X_Read-Funktion stellt sicher, dass die Daten
* komplett und
* korrekt
sind und sie ruft die globale Funktion Dispatch() mit einer Nachricht auf.

Dispatch() sucht nach einem passenden lokalen Modul via
* $hash->{Clients} oder $hash->{MatchList} im physischen Modul
* $hash->{Match} in allen passenden logischen Modulen
und ruft X_Parse in den gefundenen Modulen auf.

X_Parse
* untersucht die übergebenen Daten (von Dispatch() übergeben)
* setzt alle [[#Readings|readings]] via readings*update Funktionen
* gibt den Namen des logischen Device zurück

Es findet kein Event-Triggering statt, wenn die readings*update Funktionen
* von X_Parse aufgerufen werden und
* X_Parse wiederum von Dispatch() aufgerufen wurde.
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )

Dispatch() triggert das Event-Handling für das von X_Parse zurückgegebene logische Device.

=== Kommunikation von den logischen Modulen zum Gerät ===

Um von einem logischen Modul an ein physisches Gerät zu senden, wird im logischen Modul das Attribut IODev mit dem namen des physischen Devices gesetzt.
Der Befehl
<code>AssignIoPort($hash);</code>
in der X_Define-Funktion des logischen Devices erledigt das.

Als Befehl zum Schreiben vom logischen ins physische Gerät soll <code>IOWrite()</code> verwendet werden. IOWrite() ruft im physischen Gerät die X_Write-Funktion auf.

Wenn es keine direkte Kommunikation zwischen dem logischen und dem physischen Gerät gibt(keine direkten Aufrufe von Funktionen, kein direktes überprüfen von $hash Werten,...) so können die Module hintereinander geschaltet werden (z.B. für Routerfunktionen wie in RFR) oder mittels FHEM2FHEM:RAW zwei Fhem Installationen verbunden werden und die logischen Devices werden dennoch funktionieren.

== Ergänzende Hinweise ==
Die Wahl der vorangestellten Nummer für den Dateinamen eines neuen Moduls hat keine Bedeutung mehr, es sei denn die Nummer ist 99. Module, die mit 99_ beginnen, werden von FHEM automatisch geladen. Module mit einer anderen Nummer nur wenn ein <code>define</code>-Befehl dafür sorgt, dass das Modul geladen wird.

Wenn ein Modul Initialisierungsdaten benötigt, sollten diese im Modul selbst enthalten sein. Eine zusätzliche Datei oder sogar ein Unterverzeichnis mit mehreren Dateien ist bei FHEM nicht üblich und sollte bei Modulen, die mit FHEM ausgeliefert werden nur in Rücksprache mit Rudolf König angelegt werden, da sie sonst bei einem Update nicht verteilt werden.

== Weitere Informationen ==
Wenn man weitere Details wissen möchte, ist ein erster sinnvoller Schritt ein Blick in die Datei fhem.pl. Dort sieht man im Perl-Code wie die Module aufgerufen werden, was vorher passiert und was danach. Am Anfang der Datei (ca. ab Zeile 130) findet man beispielsweise eine Liste der globalen Variablen, die den Modulen zur Verfügung stehen sowie Details zu den wichtigen Hashes %modules und %defs. Wer mit Perl noch nicht so gut klar kommt, dem hilft eventuell ein Blick auf die Perldoc Website[http://perldoc.perl.org/] oder in das Perl-Buch seiner Wahl. Auch die FHEM Commandref [http://fhem.de/commandref.html] sollte nicht unterschätzt werden. Es stehen oft mehr interessante Details auch für Modulentwickler darin als man zunächst vermuten könnte.

== "Hello World" Beispiel ==

98_Hello.pm

<pre>
package main;
use strict;
use warnings;

my %Hello_gets = (
"whatyouwant" => "can't",
"whatyouneed" => "try sometimes",
"satisfaction" => "no"
);

sub Hello_Initialize($) {
my ($hash) = @_;

$hash->{DefFn} = 'Hello_Define';
$hash->{UndefFn} = 'Hello_Undef';
$hash->{SetFn} = 'Hello_Set';
$hash->{GetFn} = 'Hello_Get';
$hash->{AttrFn} = 'Hello_Attr';
$hash->{ReadFn} = 'Hello_Read';

$hash->{AttrList} =
"formal:yes,no "
. $readingFnAttributes;
}

sub Hello_Define($$) {
my ($hash, $def) = @_;
my @param = split('[ \t]+', $def);

if(int(@param) < 3) {
return "too few parameters: define <name> Hello <greet>";
}

my $hash->{name} = $param[0];
my $hash->{greet} = $param[2];

return undef;
}

sub Hello_Undef($$) {
my ($hash, $arg) = @_;
# nothing to do
return undef;
}

sub Hello_Get($@) {
my ($hash, @param) = @_;

return '"get Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
if(!$Hello_gets{$opt}) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}

if($attr{$name}{formal} eq 'yes') {
return $Hello_gets{$opt}.', sir';
}
return $Hello_gets{$opt};
}

sub Hello_Set($@) {
my ($hash, @param) = @_;

return '"set Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
my $value = join("", @param);

if(!defined($Hello_gets{$opt})) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}
$hash->{STATE} = $Hello_gets{$opt} = $value;

return "$opt set to $value. Try to get it.";
}

sub Hello_Attr(@) {
my ($cmd,$name,$attr_name,$attr_value) = @_;
if($cmd eq "set") {
if($attr_name eq "formal") {
if($attr_value !~ /^yes|no$/) {
my $err = "Invalid argument $attr_value to $attr_name. Must be yes or no.";
Log 3, "Hello: ".$err;
return $err;
}
} else {
return "Unknown attr $attr_name";
}
}
return undef;
}

1;

=pod
=begin html

<a name="Hello"></a>
<h3>Hello</h3>
<ul>
<i>Hello</i> implements the classical "Hello World" as a starting point for module development.
You may want to copy 98_Hello.pm to start implementing a module of your very own. See
<a href="http://www.fhemwiki.de/wiki/DevelopmentModuleIntro">DevelopmentModuleIntro</a> for an
in-depth instruction to your first module.
<br><br>
<a name="Hellodefine"></a>
<b>Define</b>
<ul>
<code>define <name> Hello <greet></code>
<br><br>
Example: <code>define HELLO Hello TurnUrRadioOn</code>
<br><br>
The "greet" parameter has no further meaning, it just demonstrates
how to set a so called "Internal" value. See <a href="http://fhem.de/commandref.html#define">commandref#define</a>
for more info about the define command.
</ul>
<br>

<a name="Helloset"></a>
<b>Set</b><br>
<ul>
<code>set <name> <option> <value></code>
<br><br>
You can <i>set</i> any value to any of the following options. They're just there to
<i>get</i> them. See <a href="http://fhem.de/commandref.html#set">commandref#set</a>
for more info about the set command.
<br><br>
Options:
<ul>
<li><i>satisfaction</i><br>
Defaults to "no"</li>
<li><i>whatyouwant</i><br>
Defaults to "can't"</li>
<li><i>whatyouneed</i><br>
Defaults to "try sometimes"</li>
</ul>
</ul>
<br>

<a name="Helloget"></a>
<b>Get</b><br>
<ul>
<code>get <name> <option></code>
<br><br>
You can <i>get</i> the value of any of the options described in
<a href="#Helloset">paragraph "Set" above</a>. See
<a href="http://fhem.de/commandref.html#get">commandref#get</a> for more info about
the get command.
</ul>
<br>

<a name="Helloattr"></a>
<b>Attributes</b>
<ul>
<code>attr <name> <attribute> <value></code>
<br><br>
See <a href="http://fhem.de/commandref.html#attr">commandref#attr</a> for more info about
the attr command.
<br><br>
Attributes:
<ul>
<li><i>formal</i> no|yes<br>
When you set formal to "yes", all output of <i>get</i> will be in a
more formal language. Default is "no".
</li>
</ul>
</ul>
</ul>

=end html

=cut
</pre>

== Noch zu beschreiben ==
* Zweistufiges Modell für Module
* Funktion X_Ready ...
* Funktion X_State_Fn: {{Link2Forum|Topic=32680}}, siehe auch [[DevelopmentState]]
* FW_summaryFn (wird von FHEMWEB aufgerufen fuer Raum-Uebersicht)
* FW_detailFn (wird von FHEMWEB aufgerufen fuer Detail-Ansicht)
* DevIO

[[Kategorie:Development]]