FRITZBOX

FRITZBOX
Zweck / Funktion
Steuerung einer Fritz!Box über Fhem
Allgemein
Typ	Gerätemodul
Details
Dokumentation	EN / DE
Support (Forum)	FRITZ!Box
Modulname	72_FRITZBOX.pm
Ersteller	tupol/Topos (Forum / Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

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

sudo apt-get install libjson-perl libwww-perl libsoap-lite-perl libjson-xs-perl

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 dieses Forenthema). Der zukunftssichere Zugriff auf die Fritzbox sollte also per TR-064 erfolgen. Der Vollständigkeit halber und für ältere Firmwareversionen:

1. 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
2. Auf dem System, auf dem Fhem läuft (Server) muss Telnet installiert sein; auf einem Raspberry Pi und unter Ubuntu z. B. mit dem Befehl

sudo apt-get install libnet-telnet-perl

Installation

Erste Schritte

Zur Erstinstallation reicht ein einfaches define FritzBox FRITZBOX, 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:

define FritzBox FRITZBOX

Wenn die Fritzbox nicht unter http://fritz.box erreichbar ist, IP im define setzen:

define FritzBox FRITZBOX 192.168.168.168

192.168.168.168 dabei natürlich durch die passende IP ersetzen... Alternativ kann statt der IP auch der Hostname eingegeben werden.

Wenn das Login auf der Benutzeroberfläche der FritzBox mit User und Passwort (und nicht nur per Passwort) geschieht, den User konfigurieren:

attr FritzBox boxUser Benutzername

Passwort konfigurieren:

set FritzBox password Passwort - legt das zugehörige Passwort fest (nur einmal --> gehört nicht in die cfg-Datei)

Manuelle TR-064 Kommandos erlauben (Das Auslesen der Readings per TR-064 funktioniert auch ohne dieses Attribut.):

attr FritzBox allowTR064Command 1

Telnet: Modul FRITZBOX für Zugriff auf einem externen Server einrichten

Anlegen des Attributs telnetUser

Bei Fernzugriff über Telnet sind weitere Schritte nötig:

1. Telnet auf der Fritzbox freischalten (Tastenkombination #96*7* am angeschlossenen Telefon (auch FritzFon)
2. TelnetUser definieren (wie im Screenshot gezeigt)
3. Passwort zum Benutzer auf der Fritzbox definieren

Passwort definieren

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

Wer stattdessen lieber das Befehl-Eingabefeld verwendet:

define FritzBox FRITZBOX

attr FritzBox telnetUser Benutzername - legt den Benutzer fest

set FritzBox password Passwort - 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:

attr FritzBox forceTelnetConnection 1

mögliche Fehlermeldungen

Sollte schon bei define FritzBox FRITZBOX die Fehlermeldung kommen, dass dieses Modul nicht existiert, dann bitte prüfen, ob Fhem auf dem aktuellen Stand ist und ggf. aktualisieren.

Kommt jetzt bei der erneuten Definition die Fehlermeldung Error: Perl modul Net::Telnet is missing on this system bitte wie oben schon erwähnt den Befehl

sudo apt-get install libnet-telnet-perl

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 commandref

Attribute

Siehe commandref

TR-064

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

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

AVM hat die Schnittstellenbeschreibung unter [1] 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)

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

Status-Symbol

attr <device> devStateIcon .*on.*off:WLAN_on_gWLAN_off .*on.*on.*:WLAN_on_gWLAN_on WLAN..off.*:WLAN_off

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 heruntergeladen werden.

Anwendungsbeispiele

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: get <device> tr064Command DeviceConfig:1 deviceconfig Reboot

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 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 Forenthread zur Anwesenheitserkennung und in diesem Blogpost. Auf dieser Basis könnte eine einfache Implementierung zum Beispiel so aussehen:

Funktion in 99_myUtils:

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
}

Nutzung dieser Funktion mit dem PRESENCE Modul definieren:

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

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 attr Fritzbox INTERVAL 60 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 attr <device> verbose 5 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.pm abgewandelt werden.

my @fbs = devspec2array("TYPE=FRITZBOX"); (Nur als Hinweis)

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

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");
  }
}

Hinweise:

• fhem("set anwesend_smartphone absent"); 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 (define anwesend_smartphone dummy).
• 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 attr Fritzbox event-on-change-reading mac_AA_BB_CC_DD_EE_FF Events nur auslösen, wenn sich der Status des Gerätes ändert. Will man mehrere Geräte abfragen, sollte man attr Fritzbox event-on-change-reading mac_AA_BB_CC_DD_EE_FF,mac_GG_HH_II_JJ_KK_LL 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 attr Fritzbox event-on-change-reading mac_AA_BB_CC_DD_EE_FF ein attr Fritzbox event-on-update-reading mac_AA_BB_CC_DD_EE_FF 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":

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");
  }
}

Das hilft allerdings nur beim Systemstart. Nicht, wenn FHEM aufgrund irgendwelcher Hänger eine Aktualisierung des Status' verpasst hat.

userReadings per get tr064Command

Um dem Gerätewert <userReadingName> den Wert von <VariabelName> aus der Rückgabe des get-Befehls tr064Command zuzuordnen

attr <device> userReadings <userReadingName> {my $resp=fhem("get <device> tr064Command <service> <control> <action> [[<argName1> <argValue1>] ...]",1);;$resp =~/\'<VariabelName>\' => '(.*)'/;;return $1;;}

Beispielsweise

attr Fritzbox userReadings Mobilteil_1 {my $resp=fhem("get Fritzbox tr064Command X_AVM-DE_OnTel:1 x_contact GetDECTHandsetInfo NewDectID 1",1);;$resp =~/'NewHandsetName' => '(.*)'/;;return $1;;}

Klingelton-Einstellung und Abspielen von Sprachnachrichten bei Fritz!OS-Versionen >6.24

Wenn die Fritzbox weder die Telnet- noch die webcmd-Schnittstelle hat, kann der Klingelton der Fritz!Fons nicht mehr verstellt werden.

Es gibt eine Behelfslösung über das Attribut useGuiHack. Dadurch wird eine Eingabe in die WebGUI der Fritzbox simuliert.

ACHTUNG Vor allem nach einem Update der FritzBox kann es durch dieses Attribut, zu ungewollten Verstellungen von Werten in der Fritzbox kommen.

Bei Verwendung der ring-Parameter "play:" und "say:" wird die abzuspielende URL in die Datei, die unter dem Reading M3U_LOCAL steht, eingetragen. Diese Datei kann man auch über das Attribute m3uFileLocal vorgeben. In dem Radioeintrag FHEM muss dann auf der FritzBox, die Web-Adresse der entsprechenden Datei eingetragen werden.

Bekannte Probleme

Modul bleibt im Status "Check APIs" hängen

Im Log steht die Meldung: "Error: Timeout when reading Fritz!Box data.".

Mögliche Ursache: Nutzung des FHEM-Befehls rereadcfg. Dieser verträgt sich nicht mit dem Modul "blocking.pm", das für parallel laufende FHEM-Prozesse genutzt wird.

Abhilfe schafft ein Neustart shutdown restart oder das Einfügen eines zusätzlichen, lokalen Telnet-Ports z.B. durch define tPortLocal telnet 7073

Nachtschaltung Doppel-WLAN

Beim Abschalten des WLAN über das Modul wird (über TR064) zuerst das 2.4 GHz und dann das 5 GHz WLAN ausgeschaltet. Bei der gleichzeitigen Nutzung der WLAN-Nachtschaltung (Anschalten über das Fritz!OS) wird dann jedoch nur noch das 5 GHz WLAN wieder angeschaltet. Die Box interpretiert den TR064-Befehl anscheinend als ein komplettes Abwählen des 2.4 GHz WLAN.

Abhilfe schafft hier nur ein notify auf das 5 GHz WLAN mit einem nachträglichem Anschalten des 2.4 GHz WLAN.

Kabelboxen

Bei Fritz!Boxen für den Kabelanschluss (z.B. Kabel Deutschland) scheint neben Telnet auch die TR064-API nicht zu funktionieren. Vermutlich wurde die API von AVM auf Betreiberwunsch deaktiviert, da man sonst Dinge ändern kann, die das gesamte Kabelnetz stören können.

Links

• Forenthread zu diesem Modul