FHEMWiki - Benutzerbeiträge [de]

Ladezustand des Nissan Leaf nutzbar machen

2018-12-30T15:52:38Z

C2j2: Reihenfolge logischer ;)

== Idee: Ladezustand des Leaf in FHEM nutzbar zu machen ==

Hier wird beschrieben, wie man auf den Ladezustand des Antriebsakkus eines Elektroautos '''Nissan Leaf''' (ZE0 und ZE1) in FHEM zugreifen kann. Dadurch kann man - beispielsweise über eine mehr oder weniger intelligente Perl-Routine - den Ladevorgang abbrechen, wenn das Auto den entsprechenden Maximal-SOC erreicht hat. Somit wird - wie empfohlen - das Auto beispielsweise bis maximal 80% geladen, um den Akku nicht durch Volladung stärker als nötig zu belasten:

<syntaxhighlight lang=perl>
my $leafBatSOC = ReadingsNum("Leaf", "BatterySOC", 0);
my $leafBatSOCMax = ReadingsNum("MaxSOC", "state", 100);

if ($leafBatSOC < $leafBatSOCMax)
{
// charge
}
else
{
// do not charge
}
</syntaxhighlight>

Das Ganze sieht dann so aus:

[[Datei:Ladesteuerung an der PV-Anlage.png|noframe|Ladesteuerung an der PV-Anlage]]

wobei die Abschaltlogik hier im Bild noch nicht implementiert ist, aber man sieht, wie die Lade-Leistung mit der Photovoltaikleistung geregelt wird - und da fehlt dann nur noch das Abschalten.

== Vorgehensweise ==
Es gibt zwei Möglichkeiten, an die internen Werte des '''Leaf''' heranzukommen:

# über die Smartphone-App '''Leaf Spy'''
# über eine Abfrage über eine Web-URL ('''CARWINGS-API''')

=== Alternative '''Leaf Spy''' ===

'''Leaf Spy''' ist eine Smartphone-App für das Elektroauto '''Nissan Leaf''', die interne Daten aus dem Leaf per Bluetooth ODB II-Adapter auslesen und darstellen kann wie Akkuzustand, Ladezustand, ... Innenraumtemperatur und so weiter:

[http://www.electricvehiclewiki.com/Leaf_Spy_Pro Leaf_Spy_Pro Wiki] und
[http://www.leafspypro.com/wp-content/uploads/2017/09/LeafSpy-Help-1_2_1-iOS.pdf Dokumentation der App]

'''Leaf Spy''' kann diese Daten glücklicherweise an einen Server per REST-API (HTTP-Request mit den Werten als Parameter) übergeben. Und das in kurzen Intervallen, wenn man möchte.

Um nun beispielsweise des SOC ("State of Charge")-Wert des Fahrakkus nutzen zu können, um die Ladung der Akkuschonung wegen nur bis 80% SOC durchzuführen, würde man die Daten gern in der Automationssoftware FHEM für das Laden haben.

Also braucht man einen kleinen Server, der die HTTP-Daten vom '''Leaf Spy''' empfängt und an FHEM weiterreicht, um dort Dummy-Variablen zur Weiterverarbeitung zu setzen.

Was liegt näher, als diesen Server auf dem ''Raspberry Pi'' einzurichten, auf dem auch FHEM läuft? Der langweilt sich doch eh zu Tode. Eine Möglichkeit dazu ist "Flask", der die REST-URL im Handumdrehen auseinandernimmt.

==== Voraussetzungen: ====
* eine konstante IP oder per DynDNS ansprechbare Adresse haben, über die der Raspi von außen ansprechbar ist (hat man vermutlich ohnehin, wenn man FHEM von außen erreichen möchte).

* LeafSpy installiert und funktionsfähig

==== Die Arbeit ====

* "Flask" installieren (bitte im Netz schauen, welches - hängt von der auf dem Raspi installierten Python-Version ab, gegebenenfalls muß man eine virtuelle Umgebung "venv" einrichten - findet man aber alles irgendwie: Stichwörter sind also "Flask" und "venv"). Das ist der Hauptschritt.

* ein kleines Python-Skript als "Proxy" einrichten (siehe unten), kann man z.B. in "/home/pi/leaf-fhem-bridge/" unterbringen

* und eine Dummy-Variable "Leaf" FHEM einrichten mit diversen Readings ("BatterySOC" etc), die durch das Python-Script gesetzt werden. Siehe auch unten.

* in FHEM die <code>WEBapi</code> einrichten ([[CsrfToken-HowTo]]) für den problemlosen internen Zugriff

* Testen mit "http://raspberrypi:5000/app?SOC=80", dann müßte im FHEM im korrespondierende Dummy "Leaf" das Reading "BatterySOC" auf 80 gesetzt werden.

* wenn alles klappt, diesen Flask-Server bei jedem Boot des ''Raspiberry Pi'' starten lassen (Google...)

* von außen testen über "https://meine-IP/leaf?SOC=80" - natürlich sind der Name und der Redirect entsprechend anzupassen, gegebenenfalls über Port-Angabe. Da kocht jeder sein eigenes Süppchen...

Bei mir ist das alles derzeit noch "Trockenübung", da mein Auto noch nicht hier in der Garage steht. Ich hoffe, dass das <code>return ""</code> in Ordnung ist, mangels Auto kann ich das noch nicht testen. Ich werde das notfalls hier korrigieren.

=== Alternative '''CARWINGS''' API ===

Diese API (Zugriff über einen Internet-Request auf eine feste Seite des Betreibers mit zum Auto passenden Zugangsdaten) ist die "offizielle" Methode, an die Daten heranzukommen - und man kann damit beispielsweise auch die Klimaanlage steuern. Also geeignet für ehrgeizigere Projekte.

Vorteile:
* nicht abhängig vom Akku eines Smartphones (dessen Verbrauch kann aber optimiert werden mit Tasker, AutomateIt und ähnlichen Apps)
* man kann auch die Klimatisierung ein- und ausstellen
* und den Ort des Autos abfragen.

Nachteile:
* langsames Update: eine SOC-Abfrage braucht knapp 2 Minuten (was aber egal ist, da das eh periodisch durchgeführt wird)

Dazu habe ich mittlerweile ein Modul für FHEM gebaut, dass das alles in FHEM einbindbar ist: [https://forum.fhem.de/index.php/topic,92163.0.html].
Mittlerweile setze ich voll auf dieses Modul.

== Anhänge ==

==== Das Server-Skript für Leaf Spy ====
Das Skript, das (auf dem ''Raspberry Pi'' mit dem Aufruf "phython <skriptname>.py" gestartet wird:

<syntaxhighlight lang=py>
import urllib
import urllib2
from flask import Flask
from flask import request

app = Flask(__name__)

def post_fhem(key, value):
# Annahme: läuft auf dem gleichen RASPI wie FHEM
# Annahme: WEBapi benutzt Port 8088
url = "http://127.0.0.1:8088/fhem?cmd=setreading%20Leaf%20" + key + "%20" + value + "&XHR=1"
req = urllib2.Request(url)
response = urllib2.urlopen(req)
page = response.read()
return page

@app.route('/app', methods = ['GET', 'POST'])
def api_echo():
if 'SOC' in request.args:
post_fhem('BatterySOC', request.args['SOC'])
if 'Ahr' in request.args:
post_fhem('BatteryCapacity', request.args['Ahr'])
if 'BatTemp' in request.args:
post_fhem('BatteryTemp', request.args['BatTemp'])
if 'Gids' in request.args:
post_fhem('BatteryGids', request.args['Gids'])
if 'Amb' in request.args:
post_fhem('AmbientTemp', request.args['Amb'])
if 'DevBat' in request.args:
post_fhem('SmartphoneSOC', request.args['DevBat'])
return ""

if __name__ == '__main__':
app.run(debug=True, host='0.0.0.0', port=5000)
</syntaxhighlight>

==== und der dazu passende '''Leaf'''-Dummy ====

Internals:
CFGFN
NAME Leaf
NR 3481
STATE SOC=79% Gids=88, Temp=50°C
TYPE dummy
Attributes:
readingList BatterySOC,BatteryGids,BatteryTemp,BatteryCapacity,AmbientTemp,SmartphoneSOC
room Auto
stateFormat { sprintf("SOC=%d%% Gids=%d, Temp=%d°C", ReadingsNum("Leaf", "BatterySOC", 0), ReadingsNum("Leaf", "BatteryGids", 0), ReadingsNum("Leaf", "AmbientTemp", 0)); }

[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]

Ladezustand des Nissan Leaf nutzbar machen

2018-12-30T15:51:25Z

C2j2: Hinweis auf mein neues Modul eingebaut, und die Pro-Contra-Liste anhand der neuen Erkenntnisse korrigiert.

== Idee: Ladezustand des Leaf in FHEM nutzbar zu machen ==

Hier wird beschrieben, wie man auf den Ladezustand des Antriebsakkus eines Elektroautos '''Nissan Leaf''' (ZE0 und ZE1) in FHEM zugreifen kann. Dadurch kann man - beispielsweise über eine mehr oder weniger intelligente Perl-Routine - den Ladevorgang abbrechen, wenn das Auto den entsprechenden Maximal-SOC erreicht hat. Somit wird - wie empfohlen - das Auto beispielsweise bis maximal 80% geladen, um den Akku nicht durch Volladung stärker als nötig zu belasten:

<syntaxhighlight lang=perl>
my $leafBatSOC = ReadingsNum("Leaf", "BatterySOC", 0);
my $leafBatSOCMax = ReadingsNum("MaxSOC", "state", 100);

if ($leafBatSOC < $leafBatSOCMax)
{
// charge
}
else
{
// do not charge
}
</syntaxhighlight>

Das Ganze sieht dann so aus:

[[Datei:Ladesteuerung an der PV-Anlage.png|noframe|Ladesteuerung an der PV-Anlage]]

wobei die Abschaltlogik hier im Bild noch nicht implementiert ist, aber man sieht, wie die Lade-Leistung mit der Photovoltaikleistung geregelt wird - und da fehlt dann nur noch das Abschalten.

== Vorgehensweise ==
Es gibt zwei Möglichkeiten, an die internen Werte des '''Leaf''' heranzukommen:

# über die Smartphone-App '''Leaf Spy'''
# über eine Abfrage über eine Web-URL ('''CARWINGS-API''')

=== Alternative '''Leaf Spy''' ===

'''Leaf Spy''' ist eine Smartphone-App für das Elektroauto '''Nissan Leaf''', die interne Daten aus dem Leaf per Bluetooth ODB II-Adapter auslesen und darstellen kann wie Akkuzustand, Ladezustand, ... Innenraumtemperatur und so weiter:

[http://www.electricvehiclewiki.com/Leaf_Spy_Pro Leaf_Spy_Pro Wiki] und
[http://www.leafspypro.com/wp-content/uploads/2017/09/LeafSpy-Help-1_2_1-iOS.pdf Dokumentation der App]

'''Leaf Spy''' kann diese Daten glücklicherweise an einen Server per REST-API (HTTP-Request mit den Werten als Parameter) übergeben. Und das in kurzen Intervallen, wenn man möchte.

Um nun beispielsweise des SOC ("State of Charge")-Wert des Fahrakkus nutzen zu können, um die Ladung der Akkuschonung wegen nur bis 80% SOC durchzuführen, würde man die Daten gern in der Automationssoftware FHEM für das Laden haben.

Also braucht man einen kleinen Server, der die HTTP-Daten vom '''Leaf Spy''' empfängt und an FHEM weiterreicht, um dort Dummy-Variablen zur Weiterverarbeitung zu setzen.

Was liegt näher, als diesen Server auf dem ''Raspberry Pi'' einzurichten, auf dem auch FHEM läuft? Der langweilt sich doch eh zu Tode. Eine Möglichkeit dazu ist "Flask", der die REST-URL im Handumdrehen auseinandernimmt.

==== Voraussetzungen: ====
* eine konstante IP oder per DynDNS ansprechbare Adresse haben, über die der Raspi von außen ansprechbar ist (hat man vermutlich ohnehin, wenn man FHEM von außen erreichen möchte).

* LeafSpy installiert und funktionsfähig

==== Die Arbeit ====

* "Flask" installieren (bitte im Netz schauen, welches - hängt von der auf dem Raspi installierten Python-Version ab, gegebenenfalls muß man eine virtuelle Umgebung "venv" einrichten - findet man aber alles irgendwie: Stichwörter sind also "Flask" und "venv"). Das ist der Hauptschritt.

* ein kleines Python-Skript als "Proxy" einrichten (siehe unten), kann man z.B. in "/home/pi/leaf-fhem-bridge/" unterbringen

* und eine Dummy-Variable "Leaf" FHEM einrichten mit diversen Readings ("BatterySOC" etc), die durch das Python-Script gesetzt werden. Siehe auch unten.

* in FHEM die <code>WEBapi</code> einrichten ([[CsrfToken-HowTo]]) für den problemlosen internen Zugriff

* Testen mit "http://raspberrypi:5000/app?SOC=80", dann müßte im FHEM im korrespondierende Dummy "Leaf" das Reading "BatterySOC" auf 80 gesetzt werden.

* wenn alles klappt, diesen Flask-Server bei jedem Boot des ''Raspiberry Pi'' starten lassen (Google...)

* von außen testen über "https://meine-IP/leaf?SOC=80" - natürlich sind der Name und der Redirect entsprechend anzupassen, gegebenenfalls über Port-Angabe. Da kocht jeder sein eigenes Süppchen...

Bei mir ist das alles derzeit noch "Trockenübung", da mein Auto noch nicht hier in der Garage steht. Ich hoffe, dass das <code>return ""</code> in Ordnung ist, mangels Auto kann ich das noch nicht testen. Ich werde das notfalls hier korrigieren.

=== Alternative '''CARWINGS''' API ===

Diese API (Zugriff über einen Internet-Request auf eine feste Seite des Betreibers mit zum Auto passenden Zugangsdaten) ist die "offizielle" Methode, an die Daten heranzukommen - und man kann damit beispielsweise auch die Klimaanlage steuern. Also geeignet für ehrgeizigere Projekte.

Mittlerweile setze ich voll auf dieses Modul.

Vorteile:
* nicht abhängig vom Akku eines Smartphones (dessen Verbrauch kann aber optimiert werden mit Tasker, AutomateIt und ähnlichen Apps)
* man kann auch die Klimatisierung ein- und ausstellen
* und den Ort des Autos abfragen.

Nachteile:
* langsames Update: eine SOC-Abfrage braucht knapp 2 Minuten (was aber egal ist, da das eh periodisch durchgeführt wird)

Dazu habe ich mittlerweile ein Modul für FHEM gebaut, dass das alles in FHEM einbindbar ist: https://forum.fhem.de/index.php/topic,92163.0.html.

== Anhänge ==

==== Das Server-Skript für Leaf Spy ====
Das Skript, das (auf dem ''Raspberry Pi'' mit dem Aufruf "phython <skriptname>.py" gestartet wird:

<syntaxhighlight lang=py>
import urllib
import urllib2
from flask import Flask
from flask import request

app = Flask(__name__)

def post_fhem(key, value):
# Annahme: läuft auf dem gleichen RASPI wie FHEM
# Annahme: WEBapi benutzt Port 8088
url = "http://127.0.0.1:8088/fhem?cmd=setreading%20Leaf%20" + key + "%20" + value + "&XHR=1"
req = urllib2.Request(url)
response = urllib2.urlopen(req)
page = response.read()
return page

@app.route('/app', methods = ['GET', 'POST'])
def api_echo():
if 'SOC' in request.args:
post_fhem('BatterySOC', request.args['SOC'])
if 'Ahr' in request.args:
post_fhem('BatteryCapacity', request.args['Ahr'])
if 'BatTemp' in request.args:
post_fhem('BatteryTemp', request.args['BatTemp'])
if 'Gids' in request.args:
post_fhem('BatteryGids', request.args['Gids'])
if 'Amb' in request.args:
post_fhem('AmbientTemp', request.args['Amb'])
if 'DevBat' in request.args:
post_fhem('SmartphoneSOC', request.args['DevBat'])
return ""

if __name__ == '__main__':
app.run(debug=True, host='0.0.0.0', port=5000)
</syntaxhighlight>

==== und der dazu passende '''Leaf'''-Dummy ====

Internals:
CFGFN
NAME Leaf
NR 3481
STATE SOC=79% Gids=88, Temp=50°C
TYPE dummy
Attributes:
readingList BatterySOC,BatteryGids,BatteryTemp,BatteryCapacity,AmbientTemp,SmartphoneSOC
room Auto
stateFormat { sprintf("SOC=%d%% Gids=%d, Temp=%d°C", ReadingsNum("Leaf", "BatterySOC", 0), ReadingsNum("Leaf", "BatteryGids", 0), ReadingsNum("Leaf", "AmbientTemp", 0)); }

[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]

Ladezustand des Nissan Leaf nutzbar machen

2018-09-26T16:19:10Z

C2j2: Bereitstellung interner Daten des Elektroautos Nissan Leaf in FHEM

== Idee: Ladezustand des Leaf in FHEM nutzbar zu machen ==

Hier wird beschrieben, wie man auf den Ladezustand des Antriebsakkus eines Elektroautos '''Nissan Leaf''' (ZE0 und ZE1) in FHEM zugreifen kann. Dadurch kann man - beispielsweise über eine mehr oder weniger intelligente Perl-Routine - den Ladevorgang abbrechen, wenn das Auto den entsprechenden Maximal-SOC erreicht hat. Somit wird - wie empfohlen - das Auto beispielsweise bis maximal 80% geladen, um den Akku nicht durch Volladung stärker als nötig zu belasten:

<syntaxhighlight lang=perl>
my $leafBatSOC = ReadingsNum("Leaf", "BatterySOC", 0);
my $leafBatSOCMax = ReadingsNum("MaxSOC", "state", 100);

if ($leafBatSOC < $leafBatSOCMax)
{
// charge
}
else
{
// do not charge
}
</syntaxhighlight>

Das Ganze sieht dann so aus:

[[Datei:Ladesteuerung an der PV-Anlage.png|noframe|Ladesteuerung an der PV-Anlage]]

wobei die Abschaltlogik hier im Bild noch nicht implementiert ist, aber man sieht, wie die Lade-Leistung mit der Photovoltaikleistung geregelt wird - und da fehlt dann nur noch das Abschalten.

== Vorgehensweise ==
Es gibt zwei Möglichkeiten, an die internen Werte des '''Leaf''' heranzukommen:

# über die Smartphone-App '''Leaf Spy'''
# über eine Abfrage über eine Web-URL ('''CARWINGS-API''')

=== Alternative '''Leaf Spy''' ===

'''Leaf Spy''' ist eine Smartphone-App für das Elektroauto '''Nissan Leaf''', die interne Daten aus dem Leaf per Bluetooth ODB II-Adapter auslesen und darstellen kann wie Akkuzustand, Ladezustand, ... Innenraumtemperatur und so weiter:

[http://www.electricvehiclewiki.com/Leaf_Spy_Pro Leaf_Spy_Pro Wiki] und
[http://www.leafspypro.com/wp-content/uploads/2017/09/LeafSpy-Help-1_2_1-iOS.pdf Dokumentation der App]

'''Leaf Spy''' kann diese Daten glücklicherweise an einen Server per REST-API (HTTP-Request mit den Werten als Parameter) übergeben. Und das in kurzen Intervallen, wenn man möchte.

Um nun beispielsweise des SOC ("State of Charge")-Wert des Fahrakkus nutzen zu können, um die Ladung der Akkuschonung wegen nur bis 80% SOC durchzuführen, würde man die Daten gern in der Automationssoftware FHEM für das Laden haben.

Also braucht man einen kleinen Server, der die HTTP-Daten vom '''Leaf Spy''' empfängt und an FHEM weiterreicht, um dort Dummy-Variablen zur Weiterverarbeitung zu setzen.

Was liegt näher, als diesen Server auf dem ''Raspberry Pi'' einzurichten, auf dem auch FHEM läuft? Der langweilt sich doch eh zu Tode. Eine Möglichkeit dazu ist "Flask", der die REST-URL im Handumdrehen auseinandernimmt.

==== Voraussetzungen: ====
* eine konstante IP oder per DynDNS ansprechbare Adresse haben, über die der Raspi von außen ansprechbar ist (hat man vermutlich ohnehin, wenn man FHEM von außen erreichen möchte).

* LeafSpy installiert und funktionsfähig

==== Die Arbeit ====

* "Flask" installieren (bitte im Netz schauen, welches - hängt von der auf dem Raspi installierten Python-Version ab, gegebenenfalls muß man eine virtuelle Umgebung "venv" einrichten - findet man aber alles irgendwie: Stichwörter sind also "Flask" und "venv"). Das ist der Hauptschritt.

* ein kleines Python-Skript als "Proxy" einrichten (siehe unten), kann man z.B. in "/home/pi/leaf-fhem-bridge/" unterbringen

* und eine Dummy-Variable "Leaf" FHEM einrichten mit diversen Readings ("BatterySOC" etc), die durch das Python-Script gesetzt werden. Siehe auch unten.

* in FHEM die <code>WEBapi</code> einrichten ([[CsrfToken-HowTo]]) für den problemlosen internen Zugriff

* Testen mit "http://raspberrypi:5000/app?SOC=80", dann müßte im FHEM im korrespondierende Dummy "Leaf" das Reading "BatterySOC" auf 80 gesetzt werden.

* wenn alles klappt, diesen Flask-Server bei jedem Boot des ''Raspiberry Pi'' starten lassen (Google...)

* von außen testen über "https://meine-IP/leaf?SOC=80" - natürlich sind der Name und der Redirect entsprechend anzupassen, gegebenenfalls über Port-Angabe. Da kocht jeder sein eigenes Süppchen...

Bei mir ist das alles derzeit noch "Trockenübung", da mein Auto noch nicht hier in der Garage steht. Ich hoffe, dass das <code>return ""</code> in Ordnung ist, mangels Auto kann ich das noch nicht testen. Ich werde das notfalls hier korrigieren.

=== Alternative '''CARWINGS''' API ===

Diese API (Zugriff über einen Internet-Request auf eine feste Seite des Betreibers mit zum Auto passenden Zugangsdaten) ist die "offizielle" Methode, an die Daten heranzukommen - und man kann damit beispielsweise auch die Klimaanlage steuern. Also geeignet für ehrgeizigere Projekte.

Vorteile:
* nicht abhängig vom Akku eines Smartphones (dessen Verbrauch kann aber optimiert werden mit Tasker und ähnlichen Apps)
* man kann auch die Klimatisierung ein- und ausstellen

Nachteile:
* nicht lokal im WLAN (benötigt Internet)
* langsames Update: angeblich maximal alle 20 Minuten, da die Abfrage über GSM geht. Dadurch auch anhängig vom Handynetz in der Garage.
* das GSM-Modul im Leaf belastet den Autoakku (nicht den Fahrakku!)

Hierfür muss man also einen kleinen Server bauen, der periodisch den Zustand abfragt und den bekannten"Leaf"-Dumnmy beziehungsweise dessen Readings setzt.

* [https://community.openenergymonitor.org/t/nissan-leaf-ev-status-control-via-mqtt/2672 Github: CARWINGS-MQTT-Schnittstelle]
* [https://github.com/snaptec/openWB/tree/master/modules/soc_leaf Github: Leaf-Modul in OpenWB]

== Anhänge ==

==== Das Server-Skript für Leaf Spy ====
Das Skript, das (auf dem ''Raspberry Pi'' mit dem Aufruf "phython <skriptname>.py" gestartet wird:

<syntaxhighlight lang=py>
import urllib
import urllib2
from flask import Flask
from flask import request

app = Flask(__name__)

def post_fhem(key, value):
# Annahme: läuft auf dem gleichen RASPI wie FHEM
# Annahme: WEBapi benutzt Port 8088
url = "http://127.0.0.1:8088/fhem?cmd=setreading%20Leaf%20" + key + "%20" + value + "&XHR=1"
req = urllib2.Request(url)
response = urllib2.urlopen(req)
page = response.read()
return page

@app.route('/app', methods = ['GET', 'POST'])
def api_echo():
if 'SOC' in request.args:
post_fhem('BatterySOC', request.args['SOC'])
if 'Ahr' in request.args:
post_fhem('BatteryCapacity', request.args['Ahr'])
if 'BatTemp' in request.args:
post_fhem('BatteryTemp', request.args['BatTemp'])
if 'Gids' in request.args:
post_fhem('BatteryGids', request.args['Gids'])
if 'Amb' in request.args:
post_fhem('AmbientTemp', request.args['Amb'])
if 'DevBat' in request.args:
post_fhem('SmartphoneSOC', request.args['DevBat'])
return ""

if __name__ == '__main__':
app.run(debug=True, host='0.0.0.0', port=5000)
</syntaxhighlight>

==== und der dazu passende '''Leaf'''-Dummy ====

Internals:
CFGFN
NAME Leaf
NR 3481
STATE SOC=79% Gids=88, Temp=50°C
TYPE dummy
Attributes:
readingList BatterySOC,BatteryGids,BatteryTemp,BatteryCapacity,AmbientTemp,SmartphoneSOC
room Auto
stateFormat { sprintf("SOC=%d%% Gids=%d, Temp=%d°C", ReadingsNum("Leaf", "BatterySOC", 0), ReadingsNum("Leaf", "BatteryGids", 0), ReadingsNum("Leaf", "AmbientTemp", 0)); }

Ladezustand des Nissan Leaf nutzbar machen

2018-09-25T21:05:49Z

C2j2: /* Alternative Leaf Spy */

== Idee: Ladezustand des Leaf in FHEM nutzbar zu machen ==

Hier wird beschrieben, wie man auf den Ladezustand des Antriebsakkus eines Elektroautos, hier '''Nissan Leaf''' in FHEM zugreifen kann. Dadurch kann man - beispielsweise über eine mehr oder weniger intelligente Perl-Routine - den Ladevorgang abbrechen, wenn das Auto den entsprechenden Maximal-SOC erreicht hat. Somit wird das Auto beispielsweise bis maximal 80% geladen, um den Aku nicht durch Volladung stärker als nötig zu belasten:

<syntaxhighlight lang=perl>
my $leafBatSOC = ReadingsNum("Leaf", "BatterySOC", 0);
my $leafBatSOCMax = ReadingsNum("MaxSOC", "state", 100);

if ($leafBatSOC < $leafBatSOCMax)
{
// charge
}
else
{
// do not charge
}
</syntaxhighlight>

Das Ganze sieht dann so aus:

[[Datei:Ladesteuerung an der PV-Anlage.png|noframe|Ladesteuerung an der PV-Anlage]]

wobei hier die Abschaltlogik noch nicht implementiert ist für dieses Bild, aber man sieht, wie die Lade-Leistung mit der Photovoltaikleistung geregelt wird.

Es gibt zwei Möglichkeiten, an die internen Werte heranzukommen:

# über die App '''Leaf Spy'''
# über eine Web-URL (CARWINGS-API)

== Alternative Leaf Spy ==

'''Leaf Spy''' ist eine App für das Elektroauto '''Nissan Leaf''', die interne Daten aus dem Leaf per Bluetooth ODB II-Adapter auslesen und darstellen kann wie Akkuzustand, Ladezustand, ... Innenraumtemperatur und so weiter:

[http://www.electricvehiclewiki.com/Leaf_Spy_Pro Leaf_Spy_Pro Wiki] und
[http://www.leafspypro.com/wp-content/uploads/2017/09/LeafSpy-Help-1_2_1-iOS.pdf Dokumentation der App]

'''Leaf Spy''' kann diese Daten glücklicherweise an einen Server per REST-API (HTTP-Request mit den Werten als Parameter) übergeben. Und das in kurzen Intervallen, wenn man möchte.

Um nun beispielsweise des SOC ("State of Charge")-Wert des Fahrakkus nutzen zu können, um die Ladung der Akkuschonung wegen nur bis 80% SOC durchzuführen, würde man die Daten gern in der Automationssoftware FHEM für das Laden haben.

Also braucht man einen kleinen Server, der die HTTP-Daten vom '''Leaf Spy''' empfängt und an FHEM weiterreicht, um dort Dummy-Variablen zur Weiterverarbeitung zu setzen.

Was liegt näher, als diesen Server auf dem ''Raspberry Pi'' einzurichten, auf dem auch FHEM läuft? Der langweilt sich doch eh zu Tode. Eine Möglichkeit dazu ist "Flask", der die REST-URL im Handumdrehen auseinandernimmt.

==== Voraussetzungen: ====
* eine konstante IP oder per DynDNS ansprechbare Adresse haben, über die der Raspi von außen ansprechbar ist (hat man vermutlich ohnehin, wenn man FHEM von außen erreichen möchte).

* LeafSpy installiert und funktionsfähig

=== Die Arbeit ===

* "Flask" installieren (bitte im Netz schauen, welches - hängt von der auf dem Raspi installierten Python-Version ab, gegebenenfalls muß man eine virtuelle Umgebung "venv" einrichten - findet man aber alles irgendwie: Stichwörter sind also "Flask" und "venv"). Das ist der Hauptschritt.

* ein kleines Python-Skript als "Proxy" einrichten (siehe unten), kann man z.B. in "/home/pi/leaf-fhem-bridge/" unterbringen

* und eine Dummy-Variable "Leaf" FHEM einrichten mit diversen Readings ("BatterySOC" etc), die durch das Python-Script gesetzt werden. Siehe auch unten.

* in FHEM die <code>WEBapi</code> einrichten ([[CsrfToken-HowTo]]) für den problemlosen internen Zugriff

* Testen mit "http://raspberrypi:5000/app?SOC=80", dann müßte im FHEM im korrespondierende Dummy "Leaf" das Reading "BatterySOC" auf 80 gesetzt werden.

* wenn alles klappt, diesen Flask-Server bei jedem Boot des ''Raspiberry Pi'' starten lassen (Google...)

* von außen testen über "https://meine-IP/leaf?SOC=80" - natürlich sind der Name und der Redirect entsprechend anzupassen, gegebenenfalls über Port-Angabe. Da kocht jeder sein eigenes Süppchen...

Bei mir ist das alles derzeit noch "Trockenübung", da mein Auto noch nicht hier in der Garage steht. Ich hoffe, dass das <code>return ""</code> in Ordnung ist, mangels Auto kann ich das noch nicht testen. Ich werde das notfalls hier korrigieren.

== Alternative CARWINGS API ==

Diese API ist die "offizielle" Methode, an die Daten heranzukommen - und man kann damit beispielsweise auch die Klimaanlage steuern. Also geeignet für ehrgeizigere Projekte.

Vorteile:
* nicht abhängig vom Akku eines Smartphones (dessen Verbrauch kann aber optimiert werden mit Tasker und ähnlichen Apps)
* man kann auch die Klimatisierung ein- und ausstellen

Nachteile:
* nicht lokal im WLAN (benötigt Internet)
* langsames Update: angeblich maximal alle 20 Minuten, da die Abfrage über GSM geht. Dadurch auch anhängig vom Handynetz in der Garage.
* das GSM-Modul im Leaf belastet den Autoakku (nicht den Fahrakku!)

Hierfür muss man also einen kleinen Server bauen, der periodisch den Zustand abfragt und den bekannten"Leaf"-Dumnmy beziehungsweise dessen Readings setzt.

* [https://community.openenergymonitor.org/t/nissan-leaf-ev-status-control-via-mqtt/2672 Github: CARWINGS-MQTT-Schnittstelle]
* [https://github.com/snaptec/openWB/tree/master/modules/soc_leaf Github: Leaf-Modul in OpenWB]

== Anhänge ==

==== Das Server-Skript für Leaf Spy ====
Das Skript, das (auf dem ''Raspberry Pi'' mit dem Aufruf "phython <skriptname>.py" gestartet wird:

<syntaxhighlight lang=py>
import urllib
import urllib2
from flask import Flask
from flask import request

app = Flask(__name__)

def post_fhem(key, value):
# Annahme: läuft auf dem gleichen RASPI wie FHEM
# Annahme: WEBapi benutzt Port 8088
url = "http://127.0.0.1:8088/fhem?cmd=setreading%20Leaf%20" + key + "%20" + value + "&XHR=1"
req = urllib2.Request(url)
response = urllib2.urlopen(req)
page = response.read()
return page

@app.route('/app', methods = ['GET', 'POST'])
def api_echo():
if 'SOC' in request.args:
post_fhem('BatterySOC', request.args['SOC'])
if 'Ahr' in request.args:
post_fhem('BatteryCapacity', request.args['Ahr'])
if 'BatTemp' in request.args:
post_fhem('BatteryTemp', request.args['BatTemp'])
if 'Gids' in request.args:
post_fhem('BatteryGids', request.args['Gids'])
if 'Amb' in request.args:
post_fhem('AmbientTemp', request.args['Amb'])
if 'DevBat' in request.args:
post_fhem('SmartphoneSOC', request.args['DevBat'])
return ""

if __name__ == '__main__':
app.run(debug=True, host='0.0.0.0', port=5000)
</syntaxhighlight>

==== und der "Leaf"-Dummy ====

Internals:
CFGFN
NAME Leaf
NR 3481
STATE SOC=79% Gids=88, Temp=50°C
TYPE dummy
Attributes:
readingList BatterySOC,BatteryGids,BatteryTemp,BatteryCapacity,AmbientTemp,SmartphoneSOC
room Auto
stateFormat { sprintf("SOC=%d%% Gids=%d, Temp=%d°C", ReadingsNum("Leaf", "BatterySOC", 0), ReadingsNum("Leaf", "BatteryGids", 0), ReadingsNum("Leaf", "AmbientTemp", 0)); }

Ladezustand des Nissan Leaf nutzbar machen

2018-09-25T21:05:04Z

C2j2: /* Alternative CARWINGS API */

== Idee: Ladezustand des Leaf in FHEM nutzbar zu machen ==

Hier wird beschrieben, wie man auf den Ladezustand des Antriebsakkus eines Elektroautos, hier '''Nissan Leaf''' in FHEM zugreifen kann. Dadurch kann man - beispielsweise über eine mehr oder weniger intelligente Perl-Routine - den Ladevorgang abbrechen, wenn das Auto den entsprechenden Maximal-SOC erreicht hat. Somit wird das Auto beispielsweise bis maximal 80% geladen, um den Aku nicht durch Volladung stärker als nötig zu belasten:

<syntaxhighlight lang=perl>
my $leafBatSOC = ReadingsNum("Leaf", "BatterySOC", 0);
my $leafBatSOCMax = ReadingsNum("MaxSOC", "state", 100);

if ($leafBatSOC < $leafBatSOCMax)
{
// charge
}
else
{
// do not charge
}
</syntaxhighlight>

Das Ganze sieht dann so aus:

[[Datei:Ladesteuerung an der PV-Anlage.png|noframe|Ladesteuerung an der PV-Anlage]]

wobei hier die Abschaltlogik noch nicht implementiert ist für dieses Bild, aber man sieht, wie die Lade-Leistung mit der Photovoltaikleistung geregelt wird.

Es gibt zwei Möglichkeiten, an die internen Werte heranzukommen:

# über die App '''Leaf Spy'''
# über eine Web-URL (CARWINGS-API)

== Alternative Leaf Spy ==

'''Leaf Spy''' ist eine App für das Elektroauto '''Nissan Leaf''', die interne Daten aus dem Leaf per Bluetooth ODB II-Adapter auslesen und darstellen kann wie Akkuzustand, Ladezustand, ... Innenraumtemperatur und so weiter:

[http://www.electricvehiclewiki.com/Leaf_Spy_Pro Leaf_Spy_Pro Wiki] und
[http://www.leafspypro.com/wp-content/uploads/2017/09/LeafSpy-Help-1_2_1-iOS.pdf Dokumentation der App]

'''Leaf Spy''' kann diese Daten glücklicherweise an einen Server per REST-API (HTTP-Request mit den Werten als Parameter) übergeben.

Um nun beispielsweise des SOC ("State of Charge")-Wert des Fahrakkus nutzen zu können, um die Ladung der Akkuschonung wegen nur bis 80% SOC durchzuführen, würde man die Daten gern in der Automationssoftware FHEM für das Laden haben.

Also braucht man einen kleinen Server, der die HTTP-Daten vom '''Leaf Spy''' empfängt und an FHEM weiterreicht, um dort Dummy-Variablen zur Weiterverarbeitung zu setzen.

Was liegt näher, als diesen Server auf dem ''Raspberry Pi'' einzurichten, auf dem auch FHEM läuft? Der langweilt sich doch eh zu Tode. Eine Möglichkeit dazu ist "Flask", der die REST-URL im Handumdrehen auseinandernimmt.

==== Voraussetzungen: ====
* eine konstante IP oder per DynDNS ansprechbare Adresse haben, über die der Raspi von außen ansprechbar ist (hat man vermutlich ohnehin, wenn man FHEM von außen erreichen möchte).

* LeafSpy installiert und funktionsfähig

=== Die Arbeit ===

* "Flask" installieren (bitte im Netz schauen, welches - hängt von der auf dem Raspi installierten Python-Version ab, gegebenenfalls muß man eine virtuelle Umgebung "venv" einrichten - findet man aber alles irgendwie: Stichwörter sind also "Flask" und "venv"). Das ist der Hauptschritt.

* ein kleines Python-Skript als "Proxy" einrichten (siehe unten), kann man z.B. in "/home/pi/leaf-fhem-bridge/" unterbringen

* und eine Dummy-Variable "Leaf" FHEM einrichten mit diversen Readings ("BatterySOC" etc), die durch das Python-Script gesetzt werden. Siehe auch unten.

* in FHEM die <code>WEBapi</code> einrichten ([[CsrfToken-HowTo]]) für den problemlosen internen Zugriff

* Testen mit "http://raspberrypi:5000/app?SOC=80", dann müßte im FHEM im korrespondierende Dummy "Leaf" das Reading "BatterySOC" auf 80 gesetzt werden.

* wenn alles klappt, diesen Flask-Server bei jedem Boot des ''Raspiberry Pi'' starten lassen (Google...)

* von außen testen über "https://meine-IP/leaf?SOC=80" - natürlich sind der Name und der Redirect entsprechend anzupassen, gegebenenfalls über Port-Angabe. Da kocht jeder sein eigenes Süppchen...

Bei mir ist das alles derzeit noch "Trockenübung", da mein Auto noch nicht hier in der Garage steht. Ich hoffe, dass das <code>return ""</code> in Ordnung ist, mangels Auto kann ich das noch nicht testen. Ich werde das notfalls hier korrigieren.

== Alternative CARWINGS API ==

Diese API ist die "offizielle" Methode, an die Daten heranzukommen - und man kann damit beispielsweise auch die Klimaanlage steuern. Also geeignet für ehrgeizigere Projekte.

Vorteile:
* nicht abhängig vom Akku eines Smartphones (dessen Verbrauch kann aber optimiert werden mit Tasker und ähnlichen Apps)
* man kann auch die Klimatisierung ein- und ausstellen

Nachteile:
* nicht lokal im WLAN (benötigt Internet)
* langsames Update: angeblich maximal alle 20 Minuten, da die Abfrage über GSM geht. Dadurch auch anhängig vom Handynetz in der Garage.
* das GSM-Modul im Leaf belastet den Autoakku (nicht den Fahrakku!)

Hierfür muss man also einen kleinen Server bauen, der periodisch den Zustand abfragt und den bekannten"Leaf"-Dumnmy beziehungsweise dessen Readings setzt.

* [https://community.openenergymonitor.org/t/nissan-leaf-ev-status-control-via-mqtt/2672 Github: CARWINGS-MQTT-Schnittstelle]
* [https://github.com/snaptec/openWB/tree/master/modules/soc_leaf Github: Leaf-Modul in OpenWB]

== Anhänge ==

==== Das Server-Skript für Leaf Spy ====
Das Skript, das (auf dem ''Raspberry Pi'' mit dem Aufruf "phython <skriptname>.py" gestartet wird:

<syntaxhighlight lang=py>
import urllib
import urllib2
from flask import Flask
from flask import request

app = Flask(__name__)

def post_fhem(key, value):
# Annahme: läuft auf dem gleichen RASPI wie FHEM
# Annahme: WEBapi benutzt Port 8088
url = "http://127.0.0.1:8088/fhem?cmd=setreading%20Leaf%20" + key + "%20" + value + "&XHR=1"
req = urllib2.Request(url)
response = urllib2.urlopen(req)
page = response.read()
return page

@app.route('/app', methods = ['GET', 'POST'])
def api_echo():
if 'SOC' in request.args:
post_fhem('BatterySOC', request.args['SOC'])
if 'Ahr' in request.args:
post_fhem('BatteryCapacity', request.args['Ahr'])
if 'BatTemp' in request.args:
post_fhem('BatteryTemp', request.args['BatTemp'])
if 'Gids' in request.args:
post_fhem('BatteryGids', request.args['Gids'])
if 'Amb' in request.args:
post_fhem('AmbientTemp', request.args['Amb'])
if 'DevBat' in request.args:
post_fhem('SmartphoneSOC', request.args['DevBat'])
return ""

if __name__ == '__main__':
app.run(debug=True, host='0.0.0.0', port=5000)
</syntaxhighlight>

==== und der "Leaf"-Dummy ====

Internals:
CFGFN
NAME Leaf
NR 3481
STATE SOC=79% Gids=88, Temp=50°C
TYPE dummy
Attributes:
readingList BatterySOC,BatteryGids,BatteryTemp,BatteryCapacity,AmbientTemp,SmartphoneSOC
room Auto
stateFormat { sprintf("SOC=%d%% Gids=%d, Temp=%d°C", ReadingsNum("Leaf", "BatterySOC", 0), ReadingsNum("Leaf", "BatteryGids", 0), ReadingsNum("Leaf", "AmbientTemp", 0)); }

Ladezustand des Nissan Leaf nutzbar machen

2018-09-25T21:04:47Z

C2j2: /* Alternative CARWINGS API */

== Idee: Ladezustand des Leaf in FHEM nutzbar zu machen ==

Hier wird beschrieben, wie man auf den Ladezustand des Antriebsakkus eines Elektroautos, hier '''Nissan Leaf''' in FHEM zugreifen kann. Dadurch kann man - beispielsweise über eine mehr oder weniger intelligente Perl-Routine - den Ladevorgang abbrechen, wenn das Auto den entsprechenden Maximal-SOC erreicht hat. Somit wird das Auto beispielsweise bis maximal 80% geladen, um den Aku nicht durch Volladung stärker als nötig zu belasten:

<syntaxhighlight lang=perl>
my $leafBatSOC = ReadingsNum("Leaf", "BatterySOC", 0);
my $leafBatSOCMax = ReadingsNum("MaxSOC", "state", 100);

if ($leafBatSOC < $leafBatSOCMax)
{
// charge
}
else
{
// do not charge
}
</syntaxhighlight>

Das Ganze sieht dann so aus:

[[Datei:Ladesteuerung an der PV-Anlage.png|noframe|Ladesteuerung an der PV-Anlage]]

wobei hier die Abschaltlogik noch nicht implementiert ist für dieses Bild, aber man sieht, wie die Lade-Leistung mit der Photovoltaikleistung geregelt wird.

Es gibt zwei Möglichkeiten, an die internen Werte heranzukommen:

# über die App '''Leaf Spy'''
# über eine Web-URL (CARWINGS-API)

== Alternative Leaf Spy ==

'''Leaf Spy''' ist eine App für das Elektroauto '''Nissan Leaf''', die interne Daten aus dem Leaf per Bluetooth ODB II-Adapter auslesen und darstellen kann wie Akkuzustand, Ladezustand, ... Innenraumtemperatur und so weiter:

[http://www.electricvehiclewiki.com/Leaf_Spy_Pro Leaf_Spy_Pro Wiki] und
[http://www.leafspypro.com/wp-content/uploads/2017/09/LeafSpy-Help-1_2_1-iOS.pdf Dokumentation der App]

'''Leaf Spy''' kann diese Daten glücklicherweise an einen Server per REST-API (HTTP-Request mit den Werten als Parameter) übergeben.

Um nun beispielsweise des SOC ("State of Charge")-Wert des Fahrakkus nutzen zu können, um die Ladung der Akkuschonung wegen nur bis 80% SOC durchzuführen, würde man die Daten gern in der Automationssoftware FHEM für das Laden haben.

Also braucht man einen kleinen Server, der die HTTP-Daten vom '''Leaf Spy''' empfängt und an FHEM weiterreicht, um dort Dummy-Variablen zur Weiterverarbeitung zu setzen.

Was liegt näher, als diesen Server auf dem ''Raspberry Pi'' einzurichten, auf dem auch FHEM läuft? Der langweilt sich doch eh zu Tode. Eine Möglichkeit dazu ist "Flask", der die REST-URL im Handumdrehen auseinandernimmt.

==== Voraussetzungen: ====
* eine konstante IP oder per DynDNS ansprechbare Adresse haben, über die der Raspi von außen ansprechbar ist (hat man vermutlich ohnehin, wenn man FHEM von außen erreichen möchte).

* LeafSpy installiert und funktionsfähig

=== Die Arbeit ===

* "Flask" installieren (bitte im Netz schauen, welches - hängt von der auf dem Raspi installierten Python-Version ab, gegebenenfalls muß man eine virtuelle Umgebung "venv" einrichten - findet man aber alles irgendwie: Stichwörter sind also "Flask" und "venv"). Das ist der Hauptschritt.

* ein kleines Python-Skript als "Proxy" einrichten (siehe unten), kann man z.B. in "/home/pi/leaf-fhem-bridge/" unterbringen

* und eine Dummy-Variable "Leaf" FHEM einrichten mit diversen Readings ("BatterySOC" etc), die durch das Python-Script gesetzt werden. Siehe auch unten.

* in FHEM die <code>WEBapi</code> einrichten ([[CsrfToken-HowTo]]) für den problemlosen internen Zugriff

* Testen mit "http://raspberrypi:5000/app?SOC=80", dann müßte im FHEM im korrespondierende Dummy "Leaf" das Reading "BatterySOC" auf 80 gesetzt werden.

* wenn alles klappt, diesen Flask-Server bei jedem Boot des ''Raspiberry Pi'' starten lassen (Google...)

* von außen testen über "https://meine-IP/leaf?SOC=80" - natürlich sind der Name und der Redirect entsprechend anzupassen, gegebenenfalls über Port-Angabe. Da kocht jeder sein eigenes Süppchen...

Bei mir ist das alles derzeit noch "Trockenübung", da mein Auto noch nicht hier in der Garage steht. Ich hoffe, dass das <code>return ""</code> in Ordnung ist, mangels Auto kann ich das noch nicht testen. Ich werde das notfalls hier korrigieren.

== Alternative CARWINGS API ==

Diese API ist die "offizielle" Methode, an die Daten heranzukommen - und man kann damit beispielsweise auch die Klimaanlage steuern. Also geeignet für ehrgeizigere Projekte.

Vorteile:
* nicht abhängig vom Akku eines Smartphones (dessen Verbrauch kann aber optimiert werden mit Tasker und ähnlichen Apps)
* man kann auch die Klimatisierung ein- und ausstellen

Nachteile:
* nicht lokal im WLAN (benötigt Internet)
* langsames Update: angeblich maximal alle 20 Minuten, da die Abfrage über GSM geht. Dadurch auch anhängig vom Handynetz in der Garage.
* das GSM-Modul im Leaf belastet den Autoakku (nicht den Fahrakku!)

Hierfür muss man also einen kleinen Server bauen, der periodisch den Zustand abfragt und den bekannten"Leaf"-Dumnmy bwziehungsweise dessen Readings setzt.

* [https://community.openenergymonitor.org/t/nissan-leaf-ev-status-control-via-mqtt/2672 Github: CARWINGS-MQTT-Schnittstelle]
* [https://github.com/snaptec/openWB/tree/master/modules/soc_leaf Github: Leaf-Modul in OpenWB]

== Anhänge ==

==== Das Server-Skript für Leaf Spy ====
Das Skript, das (auf dem ''Raspberry Pi'' mit dem Aufruf "phython <skriptname>.py" gestartet wird:

<syntaxhighlight lang=py>
import urllib
import urllib2
from flask import Flask
from flask import request

app = Flask(__name__)

def post_fhem(key, value):
# Annahme: läuft auf dem gleichen RASPI wie FHEM
# Annahme: WEBapi benutzt Port 8088
url = "http://127.0.0.1:8088/fhem?cmd=setreading%20Leaf%20" + key + "%20" + value + "&XHR=1"
req = urllib2.Request(url)
response = urllib2.urlopen(req)
page = response.read()
return page

@app.route('/app', methods = ['GET', 'POST'])
def api_echo():
if 'SOC' in request.args:
post_fhem('BatterySOC', request.args['SOC'])
if 'Ahr' in request.args:
post_fhem('BatteryCapacity', request.args['Ahr'])
if 'BatTemp' in request.args:
post_fhem('BatteryTemp', request.args['BatTemp'])
if 'Gids' in request.args:
post_fhem('BatteryGids', request.args['Gids'])
if 'Amb' in request.args:
post_fhem('AmbientTemp', request.args['Amb'])
if 'DevBat' in request.args:
post_fhem('SmartphoneSOC', request.args['DevBat'])
return ""

if __name__ == '__main__':
app.run(debug=True, host='0.0.0.0', port=5000)
</syntaxhighlight>

==== und der "Leaf"-Dummy ====

Internals:
CFGFN
NAME Leaf
NR 3481
STATE SOC=79% Gids=88, Temp=50°C
TYPE dummy
Attributes:
readingList BatterySOC,BatteryGids,BatteryTemp,BatteryCapacity,AmbientTemp,SmartphoneSOC
room Auto
stateFormat { sprintf("SOC=%d%% Gids=%d, Temp=%d°C", ReadingsNum("Leaf", "BatterySOC", 0), ReadingsNum("Leaf", "BatteryGids", 0), ReadingsNum("Leaf", "AmbientTemp", 0)); }

Ladezustand des Nissan Leaf nutzbar machen

2018-09-25T20:50:03Z

C2j2: Bild prominenter eingebaut

== Idee: Ladezustand des Leaf in FHEM nutzbar zu machen ==

Hier wird beschrieben, wie man auf den Ladezustand des Antriebsakkus eines Elektroautos, hier '''Nissan Leaf''' in FHEM zugreifen kann. Dadurch kann man - beispielsweise über eine mehr oder weniger intelligente Perl-Routine - den Ladevorgang abbrechen, wenn das Auto den entsprechenden Maximal-SOC erreicht hat. Somit wird das Auto beispielsweise bis maximal 80% geladen, um den Aku nicht durch Volladung stärker als nötig zu belasten:

<syntaxhighlight lang=perl>
my $leafBatSOC = ReadingsNum("Leaf", "BatterySOC", 0);
my $leafBatSOCMax = ReadingsNum("MaxSOC", "state", 100);

if ($leafBatSOC < $leafBatSOCMax)
{
// charge
}
else
{
// do not charge
}
</syntaxhighlight>

Das Ganze sieht dann so aus:

[[Datei:Ladesteuerung an der PV-Anlage.png|noframe|Ladesteuerung an der PV-Anlage]]

wobei hier die Abschaltlogik noch nicht implementiert ist für dieses Bild, aber man sieht, wie die Lade-Leistung mit der Photovoltaikleistung geregelt wird.

Es gibt zwei Möglichkeiten, an die internen Werte heranzukommen:

# über die App '''Leaf Spy'''
# über eine Web-URL (CARWINGS-API)

== Alternative Leaf Spy ==

'''Leaf Spy''' ist eine App für das Elektroauto '''Nissan Leaf''', die interne Daten aus dem Leaf per Bluetooth ODB II-Adapter auslesen und darstellen kann wie Akkuzustand, Ladezustand, ... Innenraumtemperatur und so weiter:

[http://www.electricvehiclewiki.com/Leaf_Spy_Pro Leaf_Spy_Pro Wiki] und
[http://www.leafspypro.com/wp-content/uploads/2017/09/LeafSpy-Help-1_2_1-iOS.pdf Dokumentation der App]

'''Leaf Spy''' kann diese Daten glücklicherweise an einen Server per REST-API (HTTP-Request mit den Werten als Parameter) übergeben.

Um nun beispielsweise des SOC ("State of Charge")-Wert des Fahrakkus nutzen zu können, um die Ladung der Akkuschonung wegen nur bis 80% SOC durchzuführen, würde man die Daten gern in der Automationssoftware FHEM für das Laden haben.

Also braucht man einen kleinen Server, der die HTTP-Daten vom '''Leaf Spy''' empfängt und an FHEM weiterreicht, um dort Dummy-Variablen zur Weiterverarbeitung zu setzen.

Was liegt näher, als diesen Server auf dem ''Raspberry Pi'' einzurichten, auf dem auch FHEM läuft? Der langweilt sich doch eh zu Tode. Eine Möglichkeit dazu ist "Flask", der die REST-URL im Handumdrehen auseinandernimmt.

==== Voraussetzungen: ====
* eine konstante IP oder per DynDNS ansprechbare Adresse haben, über die der Raspi von außen ansprechbar ist (hat man vermutlich ohnehin, wenn man FHEM von außen erreichen möchte).

* LeafSpy installiert und funktionsfähig

=== Die Arbeit ===

* "Flask" installieren (bitte im Netz schauen, welches - hängt von der auf dem Raspi installierten Python-Version ab, gegebenenfalls muß man eine virtuelle Umgebung "venv" einrichten - findet man aber alles irgendwie: Stichwörter sind also "Flask" und "venv"). Das ist der Hauptschritt.

* ein kleines Python-Skript als "Proxy" einrichten (siehe unten), kann man z.B. in "/home/pi/leaf-fhem-bridge/" unterbringen

* und eine Dummy-Variable "Leaf" FHEM einrichten mit diversen Readings ("BatterySOC" etc), die durch das Python-Script gesetzt werden. Siehe auch unten.

* in FHEM die <code>WEBapi</code> einrichten ([[CsrfToken-HowTo]]) für den problemlosen internen Zugriff

* Testen mit "http://raspberrypi:5000/app?SOC=80", dann müßte im FHEM im korrespondierende Dummy "Leaf" das Reading "BatterySOC" auf 80 gesetzt werden.

* wenn alles klappt, diesen Flask-Server bei jedem Boot des ''Raspiberry Pi'' starten lassen (Google...)

* von außen testen über "https://meine-IP/leaf?SOC=80" - natürlich sind der Name und der Redirect entsprechend anzupassen, gegebenenfalls über Port-Angabe. Da kocht jeder sein eigenes Süppchen...

Bei mir ist das alles derzeit noch "Trockenübung", da mein Auto noch nicht hier in der Garage steht. Ich hoffe, dass das <code>return ""</code> in Ordnung ist, mangels Auto kann ich das noch nicht testen. Ich werde das notfalls hier korrigieren.

== Alternative CARWINGS API ==

Diese API ist die "offizielle" Methode, an die Daten heranzukommen - und man kann damit beispielsweise auch die Klimaanlage steuern. Also geeignet für ehrgeizigere Projekte.

Nachteil ist für mich, dass man diese API anscheinend nicht so häufig aufrufen darf oder kann, maximal etwa alle 20 Minuten, eine Abfrage aktiviert das GSM-Modul des Leaf und wartet die Antwort ab. Das reicht allerdings gut für die Ladung zuhause. Um das auszunutzen man einen kleinen Web-Client laufen lassen, der die API benutzt und die Werte ebenso an unseren "Leaf"-Dummy übergibt. Hat jemand Lust? ;)

* [https://community.openenergymonitor.org/t/nissan-leaf-ev-status-control-via-mqtt/2672 Github: CARWINGS-MQTT-Schnittstelle]
* [https://github.com/snaptec/openWB/tree/master/modules/soc_leaf Github: Leaf-Modul in OpenWB]

== Anhänge ==

==== Das Server-Skript für Leaf Spy ====
Das Skript, das (auf dem ''Raspberry Pi'' mit dem Aufruf "phython <skriptname>.py" gestartet wird:

<syntaxhighlight lang=py>
import urllib
import urllib2
from flask import Flask
from flask import request

app = Flask(__name__)

def post_fhem(key, value):
# Annahme: läuft auf dem gleichen RASPI wie FHEM
# Annahme: WEBapi benutzt Port 8088
url = "http://127.0.0.1:8088/fhem?cmd=setreading%20Leaf%20" + key + "%20" + value + "&XHR=1"
req = urllib2.Request(url)
response = urllib2.urlopen(req)
page = response.read()
return page

@app.route('/app', methods = ['GET', 'POST'])
def api_echo():
if 'SOC' in request.args:
post_fhem('BatterySOC', request.args['SOC'])
if 'Ahr' in request.args:
post_fhem('BatteryCapacity', request.args['Ahr'])
if 'BatTemp' in request.args:
post_fhem('BatteryTemp', request.args['BatTemp'])
if 'Gids' in request.args:
post_fhem('BatteryGids', request.args['Gids'])
if 'Amb' in request.args:
post_fhem('AmbientTemp', request.args['Amb'])
if 'DevBat' in request.args:
post_fhem('SmartphoneSOC', request.args['DevBat'])
return ""

if __name__ == '__main__':
app.run(debug=True, host='0.0.0.0', port=5000)
</syntaxhighlight>

==== und der "Leaf"-Dummy ====

Internals:
CFGFN
NAME Leaf
NR 3481
STATE SOC=79% Gids=88, Temp=50°C
TYPE dummy
Attributes:
readingList BatterySOC,BatteryGids,BatteryTemp,BatteryCapacity,AmbientTemp,SmartphoneSOC
room Auto
stateFormat { sprintf("SOC=%d%% Gids=%d, Temp=%d°C", ReadingsNum("Leaf", "BatterySOC", 0), ReadingsNum("Leaf", "BatteryGids", 0), ReadingsNum("Leaf", "AmbientTemp", 0)); }

Ladezustand des Nissan Leaf nutzbar machen

2018-09-25T20:48:43Z

C2j2:

== Idee: Ladezustand des Leaf in FHEM nutzbar zu machen ==

Hier wird beschrieben, wie man auf den Ladezustand des Antriebsakkus eines Elektroautos, hier '''Nissan Leaf''' in FHEM zugreifen kann. Dadurch kann man - beispielsweise über eine mehr oder weniger intelligente Perl-Routine - den Ladevorgang abbrechen, wenn das Auto den entsprechenden Maximal-SOC erreicht hat. Somit wird das Auto beispielsweise bis maximal 80% geladen, um den Aku nicht durch Volladung stärker als nötig zu belasten:

<syntaxhighlight lang=perl>
my $leafBatSOC = ReadingsNum("Leaf", "BatterySOC", 0);
my $leafBatSOCMax = ReadingsNum("MaxSOC", "state", 100);

if ($leafBatSOC < $leafBatSOCMax)
{
// charge
}
else
{
// do not charge
}
</syntaxhighlight>

Das Ganze sieht dann so aus:

[[Datei:Ladesteuerung an der PV-Anlage.png|mini|Ladesteuerung an der PV-Anlage]]

wobei hier die Abschaltlogik noch nicht implementiert ist für dieses Bild, aber man sieht, wie die Lade-Leistung mit der Photovoltaikleistung geregelt wird.

Es gibt zwei Möglichkeiten, an die internen Werte heranzukommen:

# über die App '''Leaf Spy'''
# über eine Web-URL (CARWINGS-API)

== Alternative Leaf Spy ==

'''Leaf Spy''' ist eine App für das Elektroauto '''Nissan Leaf''', die interne Daten aus dem Leaf per Bluetooth ODB II-Adapter auslesen und darstellen kann wie Akkuzustand, Ladezustand, ... Innenraumtemperatur und so weiter:

[http://www.electricvehiclewiki.com/Leaf_Spy_Pro Leaf_Spy_Pro Wiki] und
[http://www.leafspypro.com/wp-content/uploads/2017/09/LeafSpy-Help-1_2_1-iOS.pdf Dokumentation der App]

'''Leaf Spy''' kann diese Daten glücklicherweise an einen Server per REST-API (HTTP-Request mit den Werten als Parameter) übergeben.

Um nun beispielsweise des SOC ("State of Charge")-Wert des Fahrakkus nutzen zu können, um die Ladung der Akkuschonung wegen nur bis 80% SOC durchzuführen, würde man die Daten gern in der Automationssoftware FHEM für das Laden haben.

Also braucht man einen kleinen Server, der die HTTP-Daten vom '''Leaf Spy''' empfängt und an FHEM weiterreicht, um dort Dummy-Variablen zur Weiterverarbeitung zu setzen.

Was liegt näher, als diesen Server auf dem ''Raspberry Pi'' einzurichten, auf dem auch FHEM läuft? Der langweilt sich doch eh zu Tode. Eine Möglichkeit dazu ist "Flask", der die REST-URL im Handumdrehen auseinandernimmt.

==== Voraussetzungen: ====
* eine konstante IP oder per DynDNS ansprechbare Adresse haben, über die der Raspi von außen ansprechbar ist (hat man vermutlich ohnehin, wenn man FHEM von außen erreichen möchte).

* LeafSpy installiert und funktionsfähig

=== Die Arbeit ===

* "Flask" installieren (bitte im Netz schauen, welches - hängt von der auf dem Raspi installierten Python-Version ab, gegebenenfalls muß man eine virtuelle Umgebung "venv" einrichten - findet man aber alles irgendwie: Stichwörter sind also "Flask" und "venv"). Das ist der Hauptschritt.

* ein kleines Python-Skript als "Proxy" einrichten (siehe unten), kann man z.B. in "/home/pi/leaf-fhem-bridge/" unterbringen

* und eine Dummy-Variable "Leaf" FHEM einrichten mit diversen Readings ("BatterySOC" etc), die durch das Python-Script gesetzt werden. Siehe auch unten.

* in FHEM die <code>WEBapi</code> einrichten ([[CsrfToken-HowTo]]) für den problemlosen internen Zugriff

* Testen mit "http://raspberrypi:5000/app?SOC=80", dann müßte im FHEM im korrespondierende Dummy "Leaf" das Reading "BatterySOC" auf 80 gesetzt werden.

* wenn alles klappt, diesen Flask-Server bei jedem Boot des ''Raspiberry Pi'' starten lassen (Google...)

* von außen testen über "https://meine-IP/leaf?SOC=80" - natürlich sind der Name und der Redirect entsprechend anzupassen, gegebenenfalls über Port-Angabe. Da kocht jeder sein eigenes Süppchen...

Bei mir ist das alles derzeit noch "Trockenübung", da mein Auto noch nicht hier in der Garage steht. Ich hoffe, dass das <code>return ""</code> in Ordnung ist, mangels Auto kann ich das noch nicht testen. Ich werde das notfalls hier korrigieren.

== Alternative CARWINGS API ==

Diese API ist die "offizielle" Methode, an die Daten heranzukommen - und man kann damit beispielsweise auch die Klimaanlage steuern. Also geeignet für ehrgeizigere Projekte.

Nachteil ist für mich, dass man diese API anscheinend nicht so häufig aufrufen darf oder kann, maximal etwa alle 20 Minuten, eine Abfrage aktiviert das GSM-Modul des Leaf und wartet die Antwort ab. Das reicht allerdings gut für die Ladung zuhause. Um das auszunutzen man einen kleinen Web-Client laufen lassen, der die API benutzt und die Werte ebenso an unseren "Leaf"-Dummy übergibt. Hat jemand Lust? ;)

* [https://community.openenergymonitor.org/t/nissan-leaf-ev-status-control-via-mqtt/2672 Github: CARWINGS-MQTT-Schnittstelle]
* [https://github.com/snaptec/openWB/tree/master/modules/soc_leaf Github: Leaf-Modul in OpenWB]

== Anhänge ==

==== Das Server-Skript für Leaf Spy ====
Das Skript, das (auf dem ''Raspberry Pi'' mit dem Aufruf "phython <skriptname>.py" gestartet wird:

<syntaxhighlight lang=py>
import urllib
import urllib2
from flask import Flask
from flask import request

app = Flask(__name__)

def post_fhem(key, value):
# Annahme: läuft auf dem gleichen RASPI wie FHEM
# Annahme: WEBapi benutzt Port 8088
url = "http://127.0.0.1:8088/fhem?cmd=setreading%20Leaf%20" + key + "%20" + value + "&XHR=1"
req = urllib2.Request(url)
response = urllib2.urlopen(req)
page = response.read()
return page

@app.route('/app', methods = ['GET', 'POST'])
def api_echo():
if 'SOC' in request.args:
post_fhem('BatterySOC', request.args['SOC'])
if 'Ahr' in request.args:
post_fhem('BatteryCapacity', request.args['Ahr'])
if 'BatTemp' in request.args:
post_fhem('BatteryTemp', request.args['BatTemp'])
if 'Gids' in request.args:
post_fhem('BatteryGids', request.args['Gids'])
if 'Amb' in request.args:
post_fhem('AmbientTemp', request.args['Amb'])
if 'DevBat' in request.args:
post_fhem('SmartphoneSOC', request.args['DevBat'])
return ""

if __name__ == '__main__':
app.run(debug=True, host='0.0.0.0', port=5000)
</syntaxhighlight>

==== und der "Leaf"-Dummy ====

Internals:
CFGFN
NAME Leaf
NR 3481
STATE SOC=79% Gids=88, Temp=50°C
TYPE dummy
Attributes:
readingList BatterySOC,BatteryGids,BatteryTemp,BatteryCapacity,AmbientTemp,SmartphoneSOC
room Auto
stateFormat { sprintf("SOC=%d%% Gids=%d, Temp=%d°C", ReadingsNum("Leaf", "BatterySOC", 0), ReadingsNum("Leaf", "BatteryGids", 0), ReadingsNum("Leaf", "AmbientTemp", 0)); }

Datei:Ladesteuerung an der PV-Anlage.png

2018-09-25T20:48:23Z

C2j2:

Hier ist die SOC-Begrenzun einzubauen...

Ladezustand des Nissan Leaf nutzbar machen

2018-09-25T20:41:12Z

C2j2:

== Idee: Ladezustand des Leaf in FHEM nutzbar zu machen ==

Hier wird beschrieben, wie man auf den Ladezustand des Antriebsakkus eines Elektroautos, hier '''Nissan Leaf''' in FHEM zugreifen kann. Dadurch kann man - beispielsweise über eine mehr oder weniger intelligente Perl-Routine - den Ladevorgang abbrechen, wenn das Auto den entsprechenden Maximal-SOC erreicht hat. Somit wird das Auto beispielsweise bis maximal 80% geladen, um den Aku nicht durch Volladung stärker als nötig zu belasten:

<syntaxhighlight lang=perl>
my $leafBatSOC = ReadingsNum("Leaf", "BatterySOC", 0);
my $leafBatSOCMax = ReadingsNum("MaxSOC", "state", 100);

if ($leafBatSOC < $leafBatSOCMax)
{
// charge
}
else
{
// do not charge
}
</syntaxhighlight>

Es gibt zwei Möglichkeiten, an die internen Werte heranzukommen:

# über die App '''Leaf Spy'''
# über eine Web-URL (CARWINGS-API)

== Alternative Leaf Spy ==

'''Leaf Spy''' ist eine App für das Elektroauto '''Nissan Leaf''', die interne Daten aus dem Leaf per Bluetooth ODB II-Adapter auslesen und darstellen kann wie Akkuzustand, Ladezustand, ... Innenraumtemperatur und so weiter:

[http://www.electricvehiclewiki.com/Leaf_Spy_Pro Leaf_Spy_Pro Wiki] und
[http://www.leafspypro.com/wp-content/uploads/2017/09/LeafSpy-Help-1_2_1-iOS.pdf Dokumentation der App]

'''Leaf Spy''' kann diese Daten glücklicherweise an einen Server per REST-API (HTTP-Request mit den Werten als Parameter) übergeben.

Um nun beispielsweise des SOC ("State of Charge")-Wert des Fahrakkus nutzen zu können, um die Ladung der Akkuschonung wegen nur bis 80% SOC durchzuführen, würde man die Daten gern in der Automationssoftware FHEM für das Laden haben.

Also braucht man einen kleinen Server, der die HTTP-Daten vom '''Leaf Spy''' empfängt und an FHEM weiterreicht, um dort Dummy-Variablen zur Weiterverarbeitung zu setzen.

Was liegt näher, als diesen Server auf dem ''Raspberry Pi'' einzurichten, auf dem auch FHEM läuft? Der langweilt sich doch eh zu Tode. Eine Möglichkeit dazu ist "Flask", der die REST-URL im Handumdrehen auseinandernimmt.

==== Voraussetzungen: ====
* eine konstante IP oder per DynDNS ansprechbare Adresse haben, über die der Raspi von außen ansprechbar ist (hat man vermutlich ohnehin, wenn man FHEM von außen erreichen möchte).

* LeafSpy installiert und funktionsfähig

=== Die Arbeit ===

* "Flask" installieren (bitte im Netz schauen, welches - hängt von der auf dem Raspi installierten Python-Version ab, gegebenenfalls muß man eine virtuelle Umgebung "venv" einrichten - findet man aber alles irgendwie: Stichwörter sind also "Flask" und "venv"). Das ist der Hauptschritt.

* ein kleines Python-Skript als "Proxy" einrichten (siehe unten), kann man z.B. in "/home/pi/leaf-fhem-bridge/" unterbringen

* und eine Dummy-Variable "Leaf" FHEM einrichten mit diversen Readings ("BatterySOC" etc), die durch das Python-Script gesetzt werden. Siehe auch unten.

* in FHEM die <code>WEBapi</code> einrichten ([[CsrfToken-HowTo]]) für den problemlosen internen Zugriff

* Testen mit "http://raspberrypi:5000/app?SOC=80", dann müßte im FHEM im korrespondierende Dummy "Leaf" das Reading "BatterySOC" auf 80 gesetzt werden.

* wenn alles klappt, diesen Flask-Server bei jedem Boot des ''Raspiberry Pi'' starten lassen (Google...)

* von außen testen über "https://meine-IP/leaf?SOC=80" - natürlich sind der Name und der Redirect entsprechend anzupassen, gegebenenfalls über Port-Angabe. Da kocht jeder sein eigenes Süppchen...

Bei mir ist das alles derzeit noch "Trockenübung", da mein Auto noch nicht hier in der Garage steht. Ich hoffe, dass das <code>return ""</code> in Ordnung ist, mangels Auto kann ich das noch nicht testen. Ich werde das notfalls hier korrigieren.

== Alternative CARWINGS API ==

Diese API ist die "offizielle" Methode, an die Daten heranzukommen - und man kann damit beispielsweise auch die Klimaanlage steuern. Also geeignet für ehrgeizigere Projekte.

Nachteil ist für mich, dass man diese API anscheinend nicht so häufig aufrufen darf oder kann, maximal etwa alle 20 Minuten, eine Abfrage aktiviert das GSM-Modul des Leaf und wartet die Antwort ab. Das reicht allerdings gut für die Ladung zuhause. Um das auszunutzen man einen kleinen Web-Client laufen lassen, der die API benutzt und die Werte ebenso an unseren "Leaf"-Dummy übergibt. Hat jemand Lust? ;)

* [https://community.openenergymonitor.org/t/nissan-leaf-ev-status-control-via-mqtt/2672 Github: CARWINGS-MQTT-Schnittstelle]
* [https://github.com/snaptec/openWB/tree/master/modules/soc_leaf Github: Leaf-Modul in OpenWB]

== Anhänge ==

==== Das Server-Skript für Leaf Spy ====
Das Skript, das (auf dem ''Raspberry Pi'' mit dem Aufruf "phython <skriptname>.py" gestartet wird:

<syntaxhighlight lang=py>
import urllib
import urllib2
from flask import Flask
from flask import request

app = Flask(__name__)

def post_fhem(key, value):
# Annahme: läuft auf dem gleichen RASPI wie FHEM
# Annahme: WEBapi benutzt Port 8088
url = "http://127.0.0.1:8088/fhem?cmd=setreading%20Leaf%20" + key + "%20" + value + "&XHR=1"
req = urllib2.Request(url)
response = urllib2.urlopen(req)
page = response.read()
return page

@app.route('/app', methods = ['GET', 'POST'])
def api_echo():
if 'SOC' in request.args:
post_fhem('BatterySOC', request.args['SOC'])
if 'Ahr' in request.args:
post_fhem('BatteryCapacity', request.args['Ahr'])
if 'BatTemp' in request.args:
post_fhem('BatteryTemp', request.args['BatTemp'])
if 'Gids' in request.args:
post_fhem('BatteryGids', request.args['Gids'])
if 'Amb' in request.args:
post_fhem('AmbientTemp', request.args['Amb'])
if 'DevBat' in request.args:
post_fhem('SmartphoneSOC', request.args['DevBat'])
return ""

if __name__ == '__main__':
app.run(debug=True, host='0.0.0.0', port=5000)
</syntaxhighlight>

==== und der "Leaf"-Dummy ====

Internals:
CFGFN
NAME Leaf
NR 3481
STATE SOC=79% Gids=88, Temp=50°C
TYPE dummy
Attributes:
readingList BatterySOC,BatteryGids,BatteryTemp,BatteryCapacity,AmbientTemp,SmartphoneSOC
room Auto
stateFormat { sprintf("SOC=%d%% Gids=%d, Temp=%d°C", ReadingsNum("Leaf", "BatterySOC", 0), ReadingsNum("Leaf", "BatteryGids", 0), ReadingsNum("Leaf", "AmbientTemp", 0)); }

LeafSpy

2018-09-25T20:39:28Z

C2j2: C2j2 verschob die Seite LeafSpy nach Ladezustand des Nissan Leaf nutzbar machen: Die CARWINGS-API kam noch dazu, so dass es nicht nur eine Seite für Leaf Spy ist

#WEITERLEITUNG [[Ladezustand des Nissan Leaf nutzbar machen]]

Ladezustand des Nissan Leaf nutzbar machen

2018-09-25T20:39:28Z

C2j2: C2j2 verschob die Seite LeafSpy nach Ladezustand des Nissan Leaf nutzbar machen: Die CARWINGS-API kam noch dazu, so dass es nicht nur eine Seite für Leaf Spy ist

{{Todo|Bitte noch ergänzen, wie z.B. die Einbindung in FHEM funktioniert und was die Einbindung hier genau bedeutet - vielleicht mit einem Screenshot?}}

== Idee: Ladezustand des Leaf in FHEM nutzbar zu machen ==

Hier wird beschrieben, wie man auf den Ladezustand des Antriebsakkus eines Elektroautos, hier '''Nissan Leaf''' in FHEM zugreifen kann. Dadurch kann man - beispielsweise über eine mehr oder weniger intelligente Perl-Routine - den Ladevorgang abbrechen, wenn das Auto den entsprechenden Maximal-SOC erreicht hat. Somit wird das Auto beispielsweise bis maximal 80% geladen, um den Aku nicht durch Volladung stärker als nötig zu belasten:

<syntaxhighlight lang=perl>
my $leafBatSOC = ReadingsNum("Leaf", "BatterySOC", 0);
my $leafBatSOCMax = ReadingsNum("MaxSOC", "state", 100);

if ($leafBatSOC < $leafBatSOCMax)
{
// charge
}
else
{
// do not charge
}
</syntaxhighlight>

Es gibt zwei Möglichkeiten, an die internen Werte heranzukommen:

# über die App '''Leaf Spy'''
# über eine Web-URL (CARWINGS-API)

== Alternative Leaf Spy ==

'''Leaf Spy''' ist eine App für das Elektroauto '''Nissan Leaf''', die interne Daten aus dem Leaf per Bluetooth ODB II-Adapter auslesen und darstellen kann wie Akkuzustand, Ladezustand, ... Innenraumtemperatur und so weiter:

[http://www.electricvehiclewiki.com/Leaf_Spy_Pro Leaf_Spy_Pro Wiki] und
[http://www.leafspypro.com/wp-content/uploads/2017/09/LeafSpy-Help-1_2_1-iOS.pdf Dokumentation der App]

'''Leaf Spy''' kann diese Daten glücklicherweise an einen Server per REST-API (HTTP-Request mit den Werten als Parameter) übergeben.

Um nun beispielsweise des SOC ("State of Charge")-Wert des Fahrakkus nutzen zu können, um die Ladung der Akkuschonung wegen nur bis 80% SOC durchzuführen, würde man die Daten gern in der Automationssoftware FHEM für das Laden haben.

Also braucht man einen kleinen Server, der die HTTP-Daten vom '''Leaf Spy''' empfängt und an FHEM weiterreicht, um dort Dummy-Variablen zur Weiterverarbeitung zu setzen.

Was liegt näher, als diesen Server auf dem ''Raspberry Pi'' einzurichten, auf dem auch FHEM läuft? Der langweilt sich doch eh zu Tode. Eine Möglichkeit dazu ist "Flask", der die REST-URL im Handumdrehen auseinandernimmt.

==== Voraussetzungen: ====
* eine konstante IP oder per DynDNS ansprechbare Adresse haben, über die der Raspi von außen ansprechbar ist (hat man vermutlich ohnehin, wenn man FHEM von außen erreichen möchte).

* LeafSpy installiert und funktionsfähig

=== Die Arbeit ===

* "Flask" installieren (bitte im Netz schauen, welches - hängt von der auf dem Raspi installierten Python-Version ab, gegebenenfalls muß man eine virtuelle Umgebung "venv" einrichten - findet man aber alles irgendwie: Stichwörter sind also "Flask" und "venv"). Das ist der Hauptschritt.

* ein kleines Python-Skript als "Proxy" einrichten (siehe unten), kann man z.B. in "/home/pi/leaf-fhem-bridge/" unterbringen

* und eine Dummy-Variable "Leaf" FHEM einrichten mit diversen Readings ("BatterySOC" etc), die durch das Python-Script gesetzt werden. Siehe auch unten.

* in FHEM die <code>WEBapi</code> einrichten ([[CsrfToken-HowTo]]) für den problemlosen internen Zugriff

* Testen mit "http://raspberrypi:5000/app?SOC=80", dann müßte im FHEM im korrespondierende Dummy "Leaf" das Reading "BatterySOC" auf 80 gesetzt werden.

* wenn alles klappt, diesen Flask-Server bei jedem Boot des ''Raspiberry Pi'' starten lassen (Google...)

* von außen testen über "https://meine-IP/leaf?SOC=80" - natürlich sind der Name und der Redirect entsprechend anzupassen, gegebenenfalls über Port-Angabe. Da kocht jeder sein eigenes Süppchen...

Bei mir ist das alles derzeit noch "Trockenübung", da mein Auto noch nicht hier in der Garage steht. Ich hoffe, dass das <code>return ""</code> in Ordnung ist, mangels Auto kann ich das noch nicht testen. Ich werde das notfalls hier korrigieren.

== Alternative CARWINGS API ==

Diese API ist die "offizielle" Methode, an die Daten heranzukommen - und man kann damit beispielsweise auch die Klimaanlage steuern. Also geeignet für ehrgeizigere Projekte.

Nachteil ist für mich, dass man diese API anscheinend nicht so häufig aufrufen darf oder kann, maximal etwa alle 20 Minuten, eine Abfrage aktiviert das GSM-Modul des Leaf und wartet die Antwort ab. Das reicht allerdings gut für die Ladung zuhause. Um das auszunutzen man einen kleinen Web-Client laufen lassen, der die API benutzt und die Werte ebenso an unseren "Leaf"-Dummy übergibt. Hat jemand Lust? ;)

* [https://community.openenergymonitor.org/t/nissan-leaf-ev-status-control-via-mqtt/2672 Github: CARWINGS-MQTT-Schnittstelle]
* [https://github.com/snaptec/openWB/tree/master/modules/soc_leaf Github: Leaf-Modul in OpenWB]

== Anhänge ==

==== Das Server-Skript für Leaf Spy ====
Das Skript, das (auf dem ''Raspberry Pi'' mit dem Aufruf "phython <skriptname>.py" gestartet wird:

<syntaxhighlight lang=py>
import urllib
import urllib2
from flask import Flask
from flask import request

app = Flask(__name__)

def post_fhem(key, value):
# Annahme: läuft auf dem gleichen RASPI wie FHEM
# Annahme: WEBapi benutzt Port 8088
url = "http://127.0.0.1:8088/fhem?cmd=setreading%20Leaf%20" + key + "%20" + value + "&XHR=1"
req = urllib2.Request(url)
response = urllib2.urlopen(req)
page = response.read()
return page

@app.route('/app', methods = ['GET', 'POST'])
def api_echo():
if 'SOC' in request.args:
post_fhem('BatterySOC', request.args['SOC'])
if 'Ahr' in request.args:
post_fhem('BatteryCapacity', request.args['Ahr'])
if 'BatTemp' in request.args:
post_fhem('BatteryTemp', request.args['BatTemp'])
if 'Gids' in request.args:
post_fhem('BatteryGids', request.args['Gids'])
if 'Amb' in request.args:
post_fhem('AmbientTemp', request.args['Amb'])
if 'DevBat' in request.args:
post_fhem('SmartphoneSOC', request.args['DevBat'])
return ""

if __name__ == '__main__':
app.run(debug=True, host='0.0.0.0', port=5000)
</syntaxhighlight>

==== und der "Leaf"-Dummy ====

Internals:
CFGFN
NAME Leaf
NR 3481
STATE SOC=79% Gids=88, Temp=50°C
TYPE dummy
Attributes:
readingList BatterySOC,BatteryGids,BatteryTemp,BatteryCapacity,AmbientTemp,SmartphoneSOC
room Auto
stateFormat { sprintf("SOC=%d%% Gids=%d, Temp=%d°C", ReadingsNum("Leaf", "BatterySOC", 0), ReadingsNum("Leaf", "BatteryGids", 0), ReadingsNum("Leaf", "AmbientTemp", 0)); }

Ladezustand des Nissan Leaf nutzbar machen

2018-09-25T20:38:17Z

C2j2:

Ladezustand des Nissan Leaf nutzbar machen

2018-09-24T16:02:39Z

C2j2: /* Dann die Arbeit */

'''Leaf Spy''' ist eine App für das Elektroauto '''Nissan Leaf''', die interne Daten aus dem Leaf per Bluetooth ODB II-Adapter auslesen und darstellen kann wie Akkuzustand, Ladezustand, ... Innenraumtemperatur und so weiter:

[http://www.electricvehiclewiki.com/Leaf_Spy_Pro Leaf_Spy_Pro Wiki] und
[http://www.leafspypro.com/wp-content/uploads/2017/09/LeafSpy-Help-1_2_1-iOS.pdf Dokumentation der App]

'''Leaf Spy''' kann diese Daten glücklicherweise an einen Server per REST-API (HTTP-Request mit den Werten als Parameter) übergeben.

Um nun beispielsweise des SOC ("State of Charge")-Wert des Fahrakkus nutzen zu können, um die Ladung der Akkuschonung wegen nur bis 80% SOC durchzuführen, würde man die Daten gern in der Automationssoftware für das Laden haben. Bei mir ist das - oh Wunder - FHEM.

Also braucht man einen kleinen Server, der die HTTP-Daten vom '''Leaf Spy''' empfängt und an FHEM weiterreicht, um dort Dummy-Variablen zur Weiterverarbeitung zu setzen.

Was liegt näher, als diesen Server auf dem ''Raspberry Pi'' einzurichten, auf dem auch FHEM läuft? Der langweilt sich doch eh zu Tode. Ich habe dazu "Flask" als Mini-Server genommen. Also:

==== Voraussetzungen: ====

* eine konstante IP oder per DynDNS ansprechbare Adresse haben, über die der Raspi von außen ansprechbar ist (hat man vermutlich ohnehin, wenn man FHEM von außen erreichen möchte). Hier bei mir ist das noch etwas komplexer, über ein QNAP-NAS mit Apache und einem redirect, so dass "https://meinname.myqnapcloud.com/leaf" intern ungeleitet wird auf "http://raspberrypi:5000/app" und somit auf mein Proxy-Skript. Die Einrichtung, auf diese Weise SSL-Zugriff auf FHEM zu haben und nun auch auf das Skript, kostete viele Stunden, macht im Nachhinein aber reich und schön. ;)

* LeafSpy installiert und funktionsfähig

==== Dann die Arbeit ====

* "Flask" installieren (bitte im Netz schauen, welches - hängt von der auf dem Raspi installierten Python-Version ab, gegebenenfalls muß man eine virtuelle Umgebung "venv" einrichten - findet man aber alles irgendwie: Stichwörter sind also "Flask" und "venv"). Das ist der Hauptschritt.

* ein kleines Python-Skript als "Proxy" einrichten (siehe unten), bei mir in "/home/pi/leaf-fhem-bridge/"

* und die paar Dummy-Variablen in FHEM einrichten (<code>LEAF_Battery_...</code> und so, siehe Skript)

* in FHEM die <code>WEBapi</code> einrichten ([[CsrfToken-HowTo]]) für den problemlosen internen Zugriff

* Testen mit "http://raspberrypi:5000/app?SOC=80", dann müßte im FHEM das korrespondierende Dummy "Leaf_Battery_SOC" auf 80 gesetzt werden.

* wenn alles klappt, diesen Flask-Server bei jedem boot des ''Raspiberry Pi'' starten lassen.

* von außen testen über "https://meine-IP/leaf?SOC=80" - natürlich sind der Name und der Redirect entsprechend anzupassen, gegebenenfalls über Port-Angabe. Da kocht jeder sein eigenes Süppchen...

Bei mir ist das alles derzeit noch "Trockenübung", da mein Auto noch nicht hier in der Garage steht. Ich hoffe dass das <code>return ""</code> in Ordnung ist, mangels Auto kann ich das noch nicht testen. Ich werde das notfalls hier korrigieren.

==== Das Skript, das über "phython <skriptname>.py" gestartet wird: ====

<syntaxhighlight>
import urllib
import urllib2
from flask import Flask
from flask import request

app = Flask(__name__)

def post_fhem(key, value):
url = "http://127.0.0.1:8088/fhem?cmd=set%20" + key + "%20" + value + "&XHR=1"
req = urllib2.Request(url)
response = urllib2.urlopen(req)
page = response.read()
return page

@app.route('/app', methods = ['GET', 'POST'])
def api_echo():
if 'SOC' in request.args:
post_fhem('Leaf_Battery_SOC', request.args['SOC'])
if 'Ahr' in request.args:
post_fhem('Leaf_Battery_Capacity', request.args['Ahr'])
if 'BatTemp' in request.args:
post_fhem('Leaf_Battery_Temp', request.args['BatTemp'])
if 'Gids' in request.args:
post_fhem('Leaf_Battery_Gids', request.args['Gids'])
if 'Amb' in request.args:
post_fhem('Leaf_Ambient_Temp', request.args['Amb'])
if 'DevBat' in request.args:
post_fhem('Leaf_Device_SOC', request.args['DevBat'])
return ""

if __name__ == '__main__':
app.run(debug=True, host='0.0.0.0', port=5000)
</syntaxhighlight>

Ladezustand des Nissan Leaf nutzbar machen

2018-09-24T16:00:49Z

C2j2: Daten der "LeafSpy"-App in FHEM nutzbar zu machen, um die Nissan Leaf-Informationen in FHEM nutzen zu können

'''Leaf Spy''' ist eine App für das Elektroauto '''Nissan Leaf''', die interne Daten aus dem Leaf per Bluetooth ODB II-Adapter auslesen und darstellen kann wie Akkuzustand, Ladezustand, ... Innenraumtemperatur und so weiter:

[http://www.electricvehiclewiki.com/Leaf_Spy_Pro Leaf_Spy_Pro Wiki] und
[http://www.leafspypro.com/wp-content/uploads/2017/09/LeafSpy-Help-1_2_1-iOS.pdf Dokumentation der App]

'''Leaf Spy''' kann diese Daten glücklicherweise an einen Server per REST-API (HTTP-Request mit den Werten als Parameter) übergeben.

Um nun beispielsweise des SOC ("State of Charge")-Wert des Fahrakkus nutzen zu können, um die Ladung der Akkuschonung wegen nur bis 80% SOC durchzuführen, würde man die Daten gern in der Automationssoftware für das Laden haben. Bei mir ist das - oh Wunder - FHEM.

Also braucht man einen kleinen Server, der die HTTP-Daten vom '''Leaf Spy''' empfängt und an FHEM weiterreicht, um dort Dummy-Variablen zur Weiterverarbeitung zu setzen.

Was liegt näher, als diesen Server auf dem ''Raspberry Pi'' einzurichten, auf dem auch FHEM läuft? Der langweilt sich doch eh zu Tode. Ich habe dazu "Flask" als Mini-Server genommen. Also:

==== Voraussetzungen: ====

* eine konstante IP oder per DynDNS ansprechbare Adresse haben, über die der Raspi von außen ansprechbar ist (hat man vermutlich ohnehin, wenn man FHEM von außen erreichen möchte). Hier bei mir ist das noch etwas komplexer, über ein QNAP-NAS mit Apache und einem redirect, so dass "https://meinname.myqnapcloud.com/leaf" intern ungeleitet wird auf "http://raspberrypi:5000/app" und somit auf mein Proxy-Skript. Die Einrichtung, auf diese Weise SSL-Zugriff auf FHEM zu haben und nun auch auf das Skript, kostete viele Stunden, macht im Nachhinein aber reich und schön. ;)

* LeafSpy installiert und funktionsfähig

==== Dann die Arbeit ====

* "Flask" installieren (bitte im Netz schauen, welches - hängt von der auf dem Raspi installierten Python-Version ab, gegebenenfalls muß man eine virtuelle Umgebung "venv" einrichten - findet man aber alles irgendwie: Stichwörter sind also "Flask" und "venv"). Das ist der Hauptschritt.

* ein kleines Python-Skript als "Proxy" einrichten (siehe unten), bei mir in "/home/pi/leaf-fhem-bridge/"

* und die paar Dummy-Variablen in FHEM einrichten (<code>LEAF_Battery_...</code> und so, siehe Skript)

* in FHEM die <code>WEBapi</code> einrichten ([[CsrfToken-HowTo]]) für den problemlosen internen Zugriff

* wenn alles klappt, diesen Flask-Server bei jedem boot des ''Raspiberry Pi'' starten lassen. Testen mit "http://raspberrypi:5000/app?SOC=80", dann müßte im FHEM das korrespondierende Dummy "Leaf_Battery_SOC" auf 80 gesetzt werden.

* von außen testen über "https://meine-IP/leaf?SOC=80" - natürlich sind der Name und der Redirect entsprechend anzupassen, gegebenenfalls über Port-Angabe. Da kocht jeder sein eigenes Süppchen...

Bei mir ist das alles derzeit noch "Trockenübung", da mein Auto noch nicht hier in der Garage steht. Ich hoffe dass das <code>return ""</code> in Ordnung ist, mangels Auto kann ich das noch nicht testen. Ich werde das notfalls hier korrigieren.

==== Das Skript, das über "phython <skriptname>.py" gestartet wird: ====

<syntaxhighlight>
import urllib
import urllib2
from flask import Flask
from flask import request

app = Flask(__name__)

def post_fhem(key, value):
url = "http://127.0.0.1:8088/fhem?cmd=set%20" + key + "%20" + value + "&XHR=1"
req = urllib2.Request(url)
response = urllib2.urlopen(req)
page = response.read()
return page

@app.route('/app', methods = ['GET', 'POST'])
def api_echo():
if 'SOC' in request.args:
post_fhem('Leaf_Battery_SOC', request.args['SOC'])
if 'Ahr' in request.args:
post_fhem('Leaf_Battery_Capacity', request.args['Ahr'])
if 'BatTemp' in request.args:
post_fhem('Leaf_Battery_Temp', request.args['BatTemp'])
if 'Gids' in request.args:
post_fhem('Leaf_Battery_Gids', request.args['Gids'])
if 'Amb' in request.args:
post_fhem('Leaf_Ambient_Temp', request.args['Amb'])
if 'DevBat' in request.args:
post_fhem('Leaf_Device_SOC', request.args['DevBat'])
return ""

if __name__ == '__main__':
app.run(debug=True, host='0.0.0.0', port=5000)
</syntaxhighlight>

Sonnenspeicher

2018-09-15T10:53:34Z

C2j2:

== Hinweise zur Einbindung des Speichersystems von sonnen (https://sonnen.de/stromspeicher/) per HTTPMOD ==

Im Kürze:
<pre>
define sonnenbatterie HTTPMOD http://x.x.x.x:8080/api/v1/status 60
attr sonnenbatterie extractAllJSON 1
attr sonnenbatterie stateFormat {sprintf("Verbrauch %d W: %d W aus PV + %d W %s Speicher + %d W %s Grid, SOC %d%%",
ReadingsVal($name,"Consumption_W",0),
ReadingsVal($name,"Production_W",0),
abs(ReadingsVal($name,"Pac_total_W",0)),
ReadingsVal($name,"FlowConsumptionBattery",1) !=0 ? "aus" : "in",
abs(ReadingsVal($name,"GridFeedIn_W",0)),
ReadingsVal($name,"FlowConsumptionGrid",1) !=0 ? "aus" : "in",
ReadingsVal($name,"RSOC","-1")
)}
</pre>

Sonnenspeicher

2018-09-13T09:41:15Z

C2j2: /* Hinweise zur schnellen Einbindung des Speichersystems von sonnen (https://sonnen.de/stromspeicher/) per HTTPMOD */

== Hinweise zur Einbindung des Speichersystems von sonnen (https://sonnen.de/stromspeicher/) per HTTPMOD ==

Im Kürze:
<pre>
define sonnenbatterie HTTPMOD http://x.x.x.x:8080/api/v1/status 60
attr sonnenbatterie extractAllJSON 1
attr sonnenbatterie stateFormat {sprintf("PV %d W -> Verbrauch %d W + %d W %s Speicher + %d W %s Grid, SOC %d%%",\
ReadingsVal($name,"Production_W",0),\
ReadingsVal($name,"Consumption_W",0),\
abs(ReadingsVal($name,"Pac_total_W",0)),\
ReadingsVal($name,"flowProductionBattery",0) > 0 ? "aus" : "in",\
ReadingsVal($name,"GridFeedIn_W",0),\
ReadingsVal($name,"flowConsumptionGrid",0) > 0 ? "aus" : "in",\
ReadingsVal($name,"RSOC","-1")\
)}
</pre>

Sonnenspeicher

2018-09-13T09:40:29Z

C2j2:

== Hinweise zur schnellen Einbindung des Speichersystems von sonnen (https://sonnen.de/stromspeicher/) per HTTPMOD ==

Im Kürze:
<pre>
define sonnenbatterie HTTPMOD http://x.x.x.x:8080/api/v1/status 60
attr sonnenbatterie extractAllJSON 1
attr sonnenbatterie stateFormat {sprintf("PV %d W -> Verbrauch %d W + %d W %s Speicher + %d W %s Grid, SOC %d%%",\
ReadingsVal($name,"Production_W",0),\
ReadingsVal($name,"Consumption_W",0),\
abs(ReadingsVal($name,"Pac_total_W",0)),\
ReadingsVal($name,"flowProductionBattery",0) > 0 ? "aus" : "in",\
ReadingsVal($name,"GridFeedIn_W",0),\
ReadingsVal($name,"flowConsumptionGrid",0) > 0 ? "aus" : "in",\
ReadingsVal($name,"RSOC","-1")\
)}
</pre>

Leere Seite 2

2018-09-12T21:20:06Z

C2j2:

== Hinweise zur schnellen Einbindung von go-eCharger (https://go-e.co/de/) per HTTPMOD ==

Voraussetzung ist, dass die HTTP-API aktiviert ist:
* Smartphone mit e-goCharger WLAN verbinden
* in "Cloud", "erweiterte Einstellungen" das HTTP-Protokoll aktivieren
* "Neustart" auswählen (ohne diesen war bei mir die Box nicht zu erreichen)
* fertig, Smartphone kann wieder ins normale WLAN

Dann in FHEM:
<pre>
define go_eCharger HTTPMOD http://go-eCharger/status 30
attr go_eCharger extractAllJSON 1
attr go_eCharger stateFormat {sprintf("%s: %s Current %d A, ETO=%.1f kWh",\
ReadingsVal($name,"car",0)==1?"ready, waiting for car":\
ReadingsVal($name,"car",0)==2?"car loading":\
ReadingsVal($name,"car",0)==3?"waiting for car":\
ReadingsVal($name,"car",0)==4?"charge finished, but connected":"unknown",\
ReadingsVal($name,"err",0)==1?"error RCCB: ":\
ReadingsVal($name,"err",0)==3?"error PHASE: ":\
ReadingsVal($name,"err",0)==8?"error NO_GROUND: ":\
ReadingsVal($name,"err",0)==10?"error INTERNAL: ":"",\
ReadingsVal($name,"amp",0),\
ReadingsVal($name,"eto",0)/10,\
""\
)}
</pre>

Das dürfte so das Wichtigste sein, um die Werte auszulesen.

HTTPMOD

2018-09-12T20:41:16Z

C2j2: /* Links */

{{Infobox Modul
|ModPurpose=Extract information from devices with an HTTP interface (or, more generic, from any URL) or send information to such devices
|ModType=d
|ModCmdRef=HTTPMOD
|ModForumArea=Sonstiges
|ModTechName=98_HTTPMOD.pm
|ModOwner=StefanStrobel ({{Link2FU|3960|Forum}} / [[Benutzer:StefanStrobel|Wiki]])
}}

HTTPMOD provides a generic way to retrieve information from devices with an HTTP Interface and store them in Readings or send information to such devices. It queries a given URL with Headers and data defined by attributes.

From the HTTP response it extracts readings named in attributes using Regexes, JSON or XPath parsing also defined by attributes.

In an advanced [[Konfiguration|configuration]] the module can also send information to devices. To do this, a generic <code>set</code> option can be configured using attributes.

== Availability ==
The module is part of the regular FHEM distribution.

== Prerequisites ==
This module uses the non blocking HTTP function <code>HttpUtils_NonblockingGet</code> provided by FHEM's [[HttpUtils]] in a new version published in December 2013.
If not already installed in your environment, please [[update]] FHEM or install it manually using appropriate commands from your environment.
Please also note that FHEM HttpUtils need the global attribute dnsServer to be set in order to work really non blocking even when dns requests can not be answered.

== Define ==
<syntaxhighlight lang="perl">
define <name> HTTPMOD <URL> <Interval>
</syntaxhighlight>
The module connects to the given <code>URL</code> every <code>Interval</code> seconds, sends optional headers and data and then parses the response with regular expressions, xpath or json to set readings.

URL can be "none" and Interval can be 0 if you prefer to only query data with a get command and not in a defined interval.

Example:
<syntaxhighlight lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60
</syntaxhighlight>

== Set-Commands ==
can be defined using attributes, see advanced configuration

If you set the attribute enableControlSet to 1, the following additional built in set commands are available:
;interval
:set new interval time in seconds and restart the timer
;reread
:request the defined URL and try to parse it just like the automatic update would do it every Interval seconds without modifying the running timer.
;stop
:stop interval timer.
;start
:restart interval timer to call GetUpdate after interval seconds
;upgradeAttributes
:convert outdated attributes for older HTTPMOD-Versions that are still defined for this device from the old syntax to the new one.
:attributes with the description "this attribute should not be used anymore" or similar will be translated to the new syntax, e.g. readingsName1 to reading01Name.
;storeKeyValue
:stores a key value pair in an obfuscated form in the file system. Such values can then be used in replacements where the mode is "key" e.g. to avoid storing passwords in the configuration in clear text

== Get-Commands ==
can be defined using attributes, see advanced configuration

== simple Attributes ==
;enableControlSet
:enables the built in set commands ''interval'', ''stop'', ''start'', ''reread'', ''upgradeAttributes'', ''storeKeyValue''

;enableCookies
:enables the cookie handling inside HTTPMOD. It is advisable to always set this attribute and allow HTTPMOD to track the state of cookies and set them for following HTTP-requests

;enforceGoodReadingNames
:makes sure that HTTPMOD only creates readings that are allowd for Fhem (especially if reading names are dynamically created from JSON object names with extractAllJSON. It is advisable to always set this attribute.

;handleRedirects
:enables the redirect handling inside HTTPMOD which should be used together with the cookie handling of HTTPMOD. HTTPMOD will then automatically follow redirects from a web server and keep track of cookies at the same time. It is advisable to always set this attribute.

;requestHeader.*
:Define an additional HTTP Header to set in the HTTP request

;requestData
:POST Data to be sent in the request. If not defined, it will be a GET request as defined in HttpUtils used by this module

;reading[0-9]+(-[0-9]+)?Name
:the name of a reading to extract with the corresponding readingRegex

;reading[0-9]*(-[0-9]+)?OExpr
:defines an expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

;reading[0-9]*(-[0-9]+)?OMap
:Output Map. Defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb". If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*OMap.

;reading[0-9]*(-[0-9]+)?Format
:Defines a format string that will be used in sprintf to format a reading value. If specified as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.

;reading[0-9]*(-[0-9]+)?Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 instead of utf8.

;reading[0-9]*(-[0-9]+)?Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.

;reading[0-9]+Regex
:defines the regex to be used for extracting the reading. The value to extract should be in a capture group / sub expression
:e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)

;reading[0-9]+XPath
:defines an xpath to one or more readings when parsing HTML data (see examples below)

;reading[0-9]+XPath-Strict
:defines an xpath to one or more readings when parsing XML data (see examples below)

;reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names with an underscore as delimiter (see the example below)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;timeout
:time in seconds to wait for an answer. Default value is 2

;do_not_notify

;readingFnAttributes

== Simple Configuration of HTTP Devices ==
If your device expects special HTTP-headers then specify them as <code>attr requestHeader1</code> to <code>attr requestHeaderX</code>.
If your Device expects an HTTP POST instead of HTTP GET then the POST-data can be specified as <code>attr requestData</code>.
To get the readings, specify pairs of <code>attr readingXName</code> and <code>attr readingXRegex</code>, <code>attr readingXXPath</code>, <code>attr readingXXPath-Strict</code> or <code>attr readingXJSON</code> to define which readings you want to extract from the HTTP response and how to extract them. (The old syntax <code>attr readingsNameX</code> and <code>attr readingsRegexX</code> is still supported but the new one with <code>attr readingXName</code> and <code>attr readingXRegex</code> should be preferred. The actual values to be extracted have to be sub expressions within () in the regex (see example below)

=== Example for a PoolManager 5: ===
The PoolManager Web GUI can be queried with HTTP POST Requests like this one:

<syntaxhighlight lang="perl">
POST /cgi-bin/webgui.fcgi HTTP/1.1
Host: 192.168.70.90
Accept: */*
Content-Type: application/json;charset=UTF-8
Content-Length: 60

{"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value"]}
</syntaxhighlight>

The resulting HTTP Response would look like this:

<syntaxhighlight lang="perl">
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
Expires: 0
Cache-Control: no-cache
Date: Sun, 12 Jan 2014 12:23:11 GMT
Server: lighttpd/1.4.26
Content-Length: 179

{
"data": {
"34.4001.value": "7.00",
"34.4008.value": "0.52",
"34.4033.value": "24.8"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</syntaxhighlight>

To configure HTTPMOD for a PoolManager one would first define a PoolManager device with e.g. the name PM, the URL and an interval of e.g. 60 seconds.

Then the data to be sent in the request needs to be defined because in this example the device expects a POST request so the query is not contained in the URL but in the request data.

Also as seen above the device expects special HTTP headers in the request so these headers also need to be defined as <code>attr PM requestHeader1</code> and <code>attr PM requestHeader2</code>

Then the names of the readings to be extracted would be set with attributes

Then for each reading value to be extracted a regular expression needs to be set that will match the value in question within ().

Example:
<syntaxhighlight lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60

attr PM enableControlSet 1
attr PM enableCookies 1
attr PM enforceGoodReadingNames 1
attr PM handleRedirects 1

attr PM reading01Name PH
attr PM reading01Regex 34.4001.value":[ \t]+"([\d\.]+)"

attr PM reading02Name CL
attr PM reading02Regex 34.4008.value":[ \t]+"([\d\.]+)"

attr PM reading03Name3TEMP
attr PM reading03Regex 34.4033.value":[ \t]+"([\d\.]+)"

attr PM requestData {"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value", "14.16601.value", "14.16602.value"]}
attr PM requestHeader1 Content-Type: application/json
attr PM requestHeader2 Accept: */*
attr PM stateFormat {sprintf("%.1f Grad, PH %.1f, %.1f mg/l Chlor", ReadingsVal($name,"TEMP",0), ReadingsVal($name,"PH",0), ReadingsVal($name,"CL",0))}
</syntaxhighlight>

=== Example for AmbientMonitor ===
AmbientMonitor is a webbased visualisation for sensors connected to an Arduino device. Its web interface can also be queried with HTTMOD to grab the data into readings.

This example was provided by locutus. The hardware configuration is an Arduino + Ethercard with ENC28J60 Controller + DHT22 Sensor and software can be downloaded from https://github.com/lucadentella/AmbientMonitor

In this example an HTTP GET is sufficent, so no <code>requestData</code> is needed. The device provides temperature and humidity readings in an HTTP response that looks like:
<syntaxhighlight lang="perl">
HTTP/1.0 200 OK
Content-Type: text/html

myCB({'temperature':22.00,'humidity':46.00})
</syntaxhighlight>

the definition could be:
<syntaxhighlight lang="perl">
define AmbientMonitor HTTPMOD http://192.168.1.221/?callback=? 300

attr AmbientMonitor enableControlSet 1
attr AmbientMonitor enableCookies 1
attr AmbientMonitor enforceGoodReadingNames 1
attr AmbientMonitor handleRedirects 1

attr AmbientMonitor requestHeader Content-Type: application/json
attr AmbientMonitor reading1Name Temperatur
attr AmbientMonitor reading1Regex temperature':([\d\.]+)
attr AmbientMonitor reading2Name Feuchtigkeit
attr AmbientMonitor reading2Regex humidity':([\d\.]+)
attr AmbientMonitor stateFormat {sprintf("Temperatur %.1f C, Feuchtigkeit %.1f %", ReadingsVal($name,"Temperatur",0), ReadingsVal($name,"Feuchtigkeit",0))}
</syntaxhighlight>

== formatting and manipulating values / readings ==
Values that are parsed from an HTTP response can be further treated or formatted with the following attributes:

* <code>(reading|get)[0-9]*(-[0-9]+)?OExpr</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?OMap</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Format</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Decode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Encode</code>

They can all be specified for an individual reading, for all readings in one match (e.g. if a regular expression has several capture groups) or for all readings in a get command (defined by getXX) or for all readings in the main reading list (defined by readingXX):
<syntaxhighlight lang="perl">
reading01Format %.1f
</syntaxhighlight>

will format the reading with the name specified by the attribute reading01Name to be numerical with one digit after the decimal point.
If the attribute reading01Regex is used and contains several capture groups then the format will be applied to all readings parsed by this regex unless these readings have their own format specified by reading01-1Format, reading01-2Format and so on.

<syntaxhighlight lang="perl">
reading01-2Format %.1f
</syntaxhighlight>

Can be used in cases where a regular expression specified as reading01regex contains several capture groups or an xpath specified as reading01XPath creates several readings.
In this case reading01-2Format specifies the format to be applied to the second match.

<syntaxhighlight lang="perl">
readingFormat %.1f
</syntaxhighlight>

applies to all readings defined by a reading-Attribute that have no more specific format.

If you need to do some calculation on a raw value before it is used as a reading, you can define the attribute <code>readingOExpr</code>.
It defines a Perl expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

Example for an expression:
<syntaxhighlight lang="perl">
attr PM reading03OExpr $val * 10
</syntaxhighlight>
Just like in the above example of the readingFormat attributes, readingOExpr and the other following attributes can be applied on several levels.

To map a numerical value to a name, you can use the readingOMap attribute.
It defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".

Example for a map:
<syntaxhighlight lang="perl">
attr PM reading02-3OMap 0:kalt, 1:warm, 2:sehr warm
</syntaxhighlight>

To convert character sets, the module can first decode a string read from the device and then encode it again. For example:
<syntaxhighlight lang="perl">
attr PM getDecode UTF-8
</syntaxhighlight>

This applies to all readings defined for Get-Commands.

== Some help with Regular Expressions ==
{{Randnotiz|RNTyp=y|RNText=Starting with version ''2018-02-10'' the internal that holds the HTTP response is no longer called '''''buf''''' but rather '''''httpbody''''', and it is only displayed when attribute '''''showBody''''' is set to "1".}}
If HTTPMOD seems not to work and the FHEM Logfile contains a message like
:<code>HTTPMOD: Response didn't match Reading ...</code>
then you should check if the value you want to extract is read into the internal with the name buf. Internals are visible when you click on the defined HTTPMOD Device. buf is an internal variable that contains the HTTP Response read. If the value is there and you get the mentioned message then probably something is wrong with your regular expression. Please note that buf might contain special characters like newlines but they are not shown in fhemweb. If you are new to regular expressions then the introduction at http://perldoc.perl.org/perlretut.html might be helpful.

For a typical HTTPMOD use case where you want to extract a number out of a HTTP-Response you can use something like <code>[\d\.]+</code> to match the number itself. The expression matches the number characters (<code>\d</code>) or a <code>.</code> if one of these characters occurs at least once.

To tell HTTPMOD that the number is what you want to use for the reading, you have to put the expression in between <code>()</code>. A <code>([\d\.]+)</code> alone would match the longest number in the HTTP Response which is very likely not the number you are looking for so you need to add something to the expression to give it a context and define how to find the number that you are looking for.

If there is a title text before the number or a special text after the number you can put this in the regex. In one of the examples above <code>humidity':([\d\.]+)</code> is looking for the number that immediately follows the text <code>humidity':</code> without any blanks in between.
Be careful if the text you are getting from your device contains special characters like newline. You don't see such special characters in the fhem webinterface as contents of the internal buf but they might cause your regular expression to fail.

If you have trouble defining a regular expression that matches a certain name, then many complicated characters and then a number, it might be helpful to use a negation in matching like <code>temp[^\d]+([\d\.]).*</code>. In this examle <code>[^\d]+</code> means any character that is not a numerical digit, more than once.

=== Regular Expressions with multiple capture Groups ===
The regular expressions used in the above example for a Poolmanager will take the value that matches one capture group. This is the part of the regular expression inside (). In the above example "([\d\.]+)" refers to numerical digits or points between double quotation marks. Only the string consiting of digits and points will match inside (). This piece is assigned to the reading.

You can also use regular expressions that have several capture groups which might be helpful when parsing tables. In this case an attribute like

<syntaxhighlight lang="perl">
reading02Regex something[ \t]+([\d\.]+)[ \t]+([\d\.]+)
</syntaxhighlight>

could match two numbers. When you specify only one reading02Name like
<syntaxhighlight lang="perl">
reading02Name Temp
</syntaxhighlight>

the name Temp will be used with the extension -1 and -2 thus giving a reading Temp-1 for the first number and Temp-2 for the second. You can also specify individual names for several readings that get parsed from one regular expression with several capture groups by defining attributes

<syntaxhighlight lang="perl">
reading02-1Name
reading02-2Name
...
</syntaxhighlight>
The same notation can be used for formatting attributes like readingXOMap, readingXFormat and so on.

The usual way to define readings is however to have an individual regular expression with just one capture group per reading as shown in the above example.

== Parsing JSON ==

If a webservice delivers data in JSON format, HTTPMOD can directly parse JSON which might be easier in this case than definig regular expressions.
The next example shows the data that can be requested from a Poolmanager with the following partial configuration:

<syntaxhighlight lang="perl">
define test2 HTTPMOD none 0
attr test2 get01Name Chlor
attr test2 getURL http://192.168.70.90/cgi-bin/webgui.fcgi
attr test2 getHeader1 Content-Type: application/json
attr test2 getHeader2 Accept: */*
attr test2 getData {"get" :["34.4008.value"]}
</syntaxhighlight>

The data in the HTTP response looks like this:

<syntaxhighlight lang="perl">
{
"data": {
"34.4008.value": "0.25"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</syntaxhighlight>

the classic way to extract the value 0.25 into a reading with the name Chlor with a regex would have been
<syntaxhighlight lang="perl">
attr test2 get01Regex 34.4008.value":[ \t]+"([\d\.]+)"
</syntaxhighlight>

with JSON you can write
<syntaxhighlight lang="perl">
attr test2 get01JSON data_34.4008.value
</syntaxhighlight>
which will create a reading with the Name "Chlor" (as shown above) and take the value 0.25 from the JSON string.

or if you don't care about the naming of your readings, you can simply extract all JSON data with
<syntaxhighlight lang="perl">
attr test2 extractAllJSON
</syntaxhighlight>

which would apply to all data read from this device and create the following readings out of the HTTP response shown above:

{| class="wikitable"
| data_34.4008.value || 0.25
|-
| event_data || 48.30000.0
|-
| event_type || 1
|-
| status_code || 0
|}

or you can specify
<syntaxhighlight lang="perl">
attr test2 get01ExtractAllJSON
</syntaxhighlight>
which would only apply to all data read as response to the get command defined as get01.

It might seem very simple at first sight to use extractAllJSON but if you prefer readings with a meaningful name you should instead define these readings with readingXXName and readingXXJSON or getXXName and getXXJSON individually. Of Course it would be possible to create additional user readings outside HTTPMOD but doing calculations, naming and formatting inside HTTPMOD is more efficient.

=== JSON Lists ===

imagine the HTTP Response contains:

<syntaxhighlight lang="perl">
{ "power":"0",
"modes":["Off","SimpleColor","RainbowChase"],
"code1":3,
"code2":4
}
</syntaxhighlight>

then a configuration like

<syntaxhighlight lang="perl">
attr device reading01JSON modes
attr device reading01Name Mode
</syntaxhighlight>

will create a list of Subreadings just like a regex with multiple matches can create multiple subreadings:

{| class="wikitable"
| Mode-1 || Off
|-
| Mode-2 || SimpleColor
|-
| Mode-3 || RainbowChase
|}

if you don't want several subreadings but one reading that contains the list of modes, you can specify a recombine expression:

<syntaxhighlight lang="perl">
attr device reading01Name Modes
attr device reading01RecombineExpr join ",", @matchlist
</syntaxhighlight>

which will create one reading containing a list:

{| class="wikitable"
| Modes || Off,SimpleColor,RainbowChase
|}

JSON parsing specifications also don't Need to match exactly. If there is no exact match for a defined reading, the HTTPMOD will try to Interpret the specification as a regex and look for json object paths that match the specification as a regex. For example:

<syntaxhighlight lang="perl">
attr device reading01Name CodeElem
attr device reading01JSON code
</syntaxhighlight>

which will create a list of readings:

{| class="wikitable"
| CodeElem-1|| 3
|-
| CodeElem-2 || 4
|}

and of course they could also be recombined into one reading with a RecombineExpr Attribute.

== Parsing http / XML using xpath ==
Another alternative to regex parsing is the use of XPath to extract values from HTTP responses.
The following example shows how XML data can be parsed with XPath-Strict or HTML Data can be parsed with XPath.
Both work similar and the example uses XML Data parsed with the XPath-Strict option:

If The XML data in the HTTP response looks like this:

<syntaxhighlight lang="xml">
<root xmlns:foo="http://www.foo.org/" xmlns:bar="http://www.bar.org">
<actors>
<actor id="1">Peter X</actor>
<actor id="2">Charles Y</actor>
<actor id="3">John Doe</actor>
</actor>
</root>
</syntaxhighlight>

with XPath you can write
<syntaxhighlight lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor[2]/text()
</syntaxhighlight>

This will create a reading with the Name "Actor" and the value "Charles Y".

Since XPath specifications can define several values / matches, HTTPMOD can also interpret these and store them in multiple readings:
<syntaxhighlight lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor/text()
</syntaxhighlight>

will create the readings

{| class="wikitable"
| Actor-1 || Peter X
|-
| Actor-2 || Charles Y
|-
| Actor-3 || John Doe
|}

== Further replacements of URL, header or post data ==
sometimes it might be helpful to dynamically change parts of a URL, HTTP header or post data depending on existing readings, internals or
perl expressions at runtime. This might be needed to pass further variables to a server, a current date or other things.

To support this HTTPMOD offers generic replacements that are applied to a request before it is sent to the server. A replacement can be defined with the attributes

* <code>replacement[0-9]*Regex</code>
* <code>replacement[0-9]*Mode</code>
* <code>replacement[0-9]*Value</code>
* <code>[gs]et[0-9]*Replacement[0-9]*Value</code>

a replacement always replaces a match of a regular expression.

'''replacement[0-9]*Mode:'''
The way the replacement value is defined can be specified with the replacement mode.
* If the <code>replacement[0-9]*Mode</code> is <code>reading</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of a ''reading'' of the same device or as ''device:reading'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>internal</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of an ''internal'' of the same device or as ''device:internal'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>text</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as a static text
* If the <code>replacement[0-9]*Mode</code> is <code>expression</code>, then the corresponding <code>replacement[0-9]*Value</code> is evaluated as a perl expression to compute the replacement. Inside such a replacement expression it is possible to refer to capture groups of the replacement regex.
* If the <code>replacement[0-9]*Mode</code> is <code>key</code>, then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.

Example:

<syntaxhighlight lang="perl">
attr mydevice getData {"get" :["%%value%%.value"]}
attr mydevice replacement01Mode text
attr mydevice replacement01Regex %%value%%

attr mydevice get01Name Chlor
attr mydevice get01Replacement01Value 34.4008

attr mydevice get02Name Something
attr mydevice get02Replacement01Value 31.4024

attr mydevice get05Name profile
attr mydevice get05URL http://www.mydevice.local/getprofile?password=%%password%%
attr mydevice replacement02Mode key
attr mydevice replacement02Regex %%password%%
attr mydevice get05Replacement02Value password
</syntaxhighlight>

defines that <code>%%value%%</code> will be replaced by a static text.

All Get commands will be HTTP post requests of a similar form. Only the <code>%%value%%</code> will be different from get to get.
The first get will set the reading named Chlor and for the request it will take the generic getData and replace %%value%% with 34.4008.

A second get will look the same except a different name and replacement value.

With the command <code>set storeKeyValue password geheim</code> you can store the password geheim in an obfuscated form in the file system.
To use this password and send it in a request you can use the above replacement with mode key. The value password will then refer to the ofuscated string stored with the key password.

The mode <code>expression</code> allows you to define your own replacement syntax:
<syntaxhighlight lang="perl">
attr mydevice replacement01Mode expression
attr mydevice replacement01Regex {{([^}]+)}}
attr mydevice replacement01Value ReadingsVal("mydevice", $1, "")
attr mydevice getData {"get" :["{{temp}}.value"]}
</syntaxhighlight>

In this example any <code><nowiki>{{name}}</nowiki></code> in a URL, header or post data will be passed on to the perl function ReadingsVal
which uses the string between <code><nowiki>{{}}</nowiki></code> as second parameter. This way one defined replacement can be used for many different
readings.

HTTPMOD has two built in replacements: One for session Ids and another one for the input value in a set command.
The placeholder $sid is always replaced with the internal <code>$hash->{sid}</code> which contains the session id after it is extracted from a previous HTTP response.
If you don't like to use the placeholder $sid then you can define your own replacement for example like:

<syntaxhighlight lang="perl">
attr mydevice replacement01Mode internal
attr mydevice replacement01Regex %session%
attr mydevice replacement01Value sid
</syntaxhighlight>

Now the internal <code>$hash->{sid}</code> will be used as a replacement for the placeholder %session%.

In the same way a value that is passed to a set-command can be put into a request with a user defined replacement.
In this case the internal <code>$hash->{value}</code> will contain the value passed to the set command.
<code>$hash->{value}</code> might even be a string containing several values that could be put into several different positions in a request by using user defined replacements.

'''Other example : steering a pellet stove from Rika'''

The stove API of Rika on https://www.rika-firenet.com/web/ delivers a JSON string with all settings and values, and can be piloted with a data string containing all the "set" values at once.

Delivered JSON on get https://www.rika-firenet.com/api/client/xxxxxxxx/status : (xxxxxxxx must be replaced with the unique stove ID)
<syntaxhighlight lang="perl">
{
"name": "Vorzimmer",
"stoveID": "xxxxxxxxx",
"lastSeenMinutes": 1,
"lastConfirmedRevision": 1504385700,
"controls": {
"revision": 1504385700,
"onOff": true,
"operatingMode": 2,
"heatingPower": 65,
"targetTemperature": 24,
"heatingTimesActive": false,
"heatingTimesActiveForComfort": true,
"setBackTemperature": 18,
"convectionFan1Active": false,
"convectionFan1Level": 0,
"convectionFan1Area": 0,
"convectionFan2Active": false,
"convectionFan2Level": 0,
"convectionFan2Area": 0,
"frostProtectionActive": false,
"frostProtectionTemperature": 5
},
"sensors": {
"statusError": 0,
"statusWarning": 0,
"statusService": 0,
"statusMainState": 1,
"statusSubState": 3,
"statusFrostStarted": false,
"inputFlameTemperature": 21,
"inputRoomTemperature": 21,
"inputExternalRequest": true,
"outputDischargeMotor": 0,
"outputInsertionMotor": 0,
"outputIDFan": 0,
"outputAirFlaps": 0,
"outputIgnition": false,
"parameterStoveTypeNumber": 13,
"parameterVersionMainBoard": 223,
"parameterVersionTFT": 223,
"parameterRuntimePellets": 11,
"parameterRuntimeLogs": 0,
"parameterFeedRateTotal": 17,
"parameterFeedRateService": 683,
"parameterOnOffCycles": 2
},
"stoveType": "DOMO MultiAir",
"stoveFeatures": {
"multiAir1": true,
"multiAir2": true,
"insertionMotor": false,
"airFlaps": false,
"logRuntime": false
}
}
</syntaxhighlight>

Data string to send to https://www.rika-firenet.com/api/client/xxxxxxxx/controls in order to set values:
<syntaxhighlight lang="perl">
heatingTimesActiveForComfort=true&frostProtectionTemperature=3&setBackTemperature=18&targetTemperature=24&convectionFan2Level=0&convectionFan2Active=false&convectionFan1Level=0&onOff=true&convectionFan1Active=false&convectionFan2Area=0&revision=1505550101&heatingTimesActive=false&convectionFan1Area=0&frostProtectionActive=false&operatingMode=2&heatingPower=65
</syntaxhighlight>

Code in 99_myUtils.pm:
<syntaxhighlight lang="perl">
use JSON;
...
sub
replaceJSON ($$) {
my ($valToReplace, $value) = @_;

#$value in the parameters is a default value
#It has to be replaced through the real value nnn passed in the set command "set <device> valToset nnn"
$value = InternalVal("Ofen", "value", $value);
Log3 ("Ofen", 3, "replaceJSON Internalvalue: $value");

#Force an update to avoid outdated revision number
fhem ("get Ofen revision");

#Get all the controls as json
my $json = ReadingsVal("Ofen", "controlsJSON","");
Log3 ("Ofen", 3, "replaceJSON configsJSON: $json");

# When starting FHEM or rereading config, the reading controlsJSON is empty
return if ($json eq "");

my $decoded = decode_json($json);
my $result;
for my $key ( keys %$decoded ) {
$result .= "$key=";
if ($key eq $valToReplace) {
$result .= $value."&";
} else {
$result .= $decoded->{$key}."&";
}
}
chop($result); #remove last &
Log3("Ofen", 3, "replaceJSON Result: $result");
return $result;
}
</syntaxhighlight>

Define stove in fhem:
<syntaxhighlight lang="perl">
defmod Ofen HTTPMOD https://www.rika-firenet.com/api/client/xxxxxxxx/status 60

attr Ofen enableCookies 1
attr Ofen reAuthRegex id="login"|Unauthorized
attr Ofen sid01Data email=xx@xx&password=xx
attr Ofen sid01URL https://www.rika-firenet.com/web/login

attr Ofen reading01JSON sensors_inputRoomTemperature
attr Ofen reading01Name RaumTemp
attr Ofen reading02JSON controls_setBackTemperature
attr Ofen reading02Name Absenkung
attr Ofen reading03JSON controls_frostProtectionTemperature
attr Ofen reading03Name Frostschutz
attr Ofen reading10Name controlsJSON
attr Ofen reading10Regex (?s)controls.*?({.*?})

attr Ofen get09Name revision
attr Ofen get09URL https://www.rika-firenet.com/api/client/xxxxxxxx/status

attr Ofen setURL https://www.rika-firenet.com/api/client/xxxxxxxx/controls
attr Ofen setData {{data}}
attr Ofen replacement01Mode expression
attr Ofen replacement01Regex {{data}}

attr Ofen set11Name frostProtectionTemperature
attr Ofen set11Replacement01Value replaceJSON("frostProtectionTemperature", 2)

attr Ofen set12Name targetTemperature
attr Ofen set12Replacement01Value replaceJSON("targetTemperature", 24)
</syntaxhighlight>

A detailed explanation (in german) of the login process can be found here: [https://forum.fhem.de/index.php/topic,76220.msg682514.html#msg682514]
and the explanation of the other parameters here: [https://forum.fhem.de/index.php/topic,76220.msg685710.html#msg685710]

== replacing reading values when they have not been updated / the device did not respond ==
If a device does not respond then the values stored in readings will keep the same and only their timestamp shows that they are outdated.
If you want to modify reading values that have not been updated for a number of seconds, you can use the attributes

* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAge</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacementMode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacement</code>

Every time the module tries to read from a device, it will also check if readings have not been updated
for longer than the <code>MaxAge</code> attributes allow. If readings are outdated, the <code>MaxAgeReplacementMode</code> defines how the affected
reading values should be replaced. <code>MaxAgeReplacementMode</code> can be <code>text</code>, <code>reading</code>, <code>internal</code>, <code>expression</code> or <code>delete</code>.

<code>MaxAge</code> specifies the number of seconds that a reading should remain untouched before it is replaced.

<code>MaxAgeReplacement</code> contains either a static text that is used as replacement value or a Perl expression that is evaluated to
give the replacement value. This can be used for example to replace a temperature that has not bee updated for more than 5 minutes
with the string "outdated - was 12":
<syntaxhighlight lang="perl">
attr PM readingMaxAge 300
attr PM readingMaxAgeReplacement "outdated - was " . $val
attr PM readingMaxAgeReplacementMode expression
</syntaxhighlight>
The variable <code>$val</code> contains the value of the reading before it became outdated.

Or to show that a device was offline:
<syntaxhighlight lang="perl">
attr MyLight reading01Name color
attr MyLight reading01JSON result_02_color
attr MyLight reading01MaxAge 300
attr MyLight reading01MaxAgeReplacement "offline"
attr MyLight reading01MaxAgeReplacementMode text
</syntaxhighlight>

== Note on determining how to send requests to a special device ==
If you don't know which URLs, headers or POST data your web GUI uses, you might try a local proxy like BurpSuite [http://portswigger.net/burp/ BurpSuite] to track requests and responses. This is a tedious task but probably the best way to achieve a successful result.

Let us consider an example. The Telekom Speedport W724V has a login-site that is famous for being cumbersome. Burp allows to monitor each step in the login procedure. In the case of a speedport the following steps occur:

First burp shows that a get command is issued
##################################################################################################
GET / HTTP/1.1
Host: speedport.ip
Cache-Control: max-age=0
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
Accept-Language: de-DE,de;q=0.8,en-US;q=0.6,en;q=0.4
Cookie: lang=de
Connection: close
In order to mimic the behavior of a real person calling the website HTTPMOD should copy all necessary steps. Host, Cookie and the GET-command are usually necessary. The same cannot be said of the User-Agent because the website can be called from any mobile or desktop computer.

Then, the speedport will answer with a command that consists of several lines. By going through every line for every step in the login procedure one will finally arrive at the information that is necessary to successfully enter the login of the speedport (in case of the W724V, for example, it is necessary to copy a token called _httoken and to include the referer).

== Advanced configuration to define a <code>set</code> command and send data to a device ==

When a set option is defined by attributes, the module will use the value given to the set command and integrate it into an HTTP-Request that sends the value to the device. The definitions for URL, headers and post data can contain the placeholder $val which will be replaced by the value given to the set command.

This can be as simple as:
<syntaxhighlight lang="perl">
# No cyclic requests and no main URL needed in this example
define MyDevice HTTPMOD none 0

attr MyDevice set01Name Licht
attr MyDevice set01URL http://192.168.1.22/switch=$val
</syntaxhighlight>

A user command
<syntaxhighlight lang="perl">
set MyDevice Licht 1
</syntaxhighlight>

will be translated into the http GET request
<syntaxhighlight lang="perl">
http://192.168.1.22/switch=1
</syntaxhighlight>

In this example a map would also be helpful, that translates on / off to 0 or 1 and allows the user to select on/of in fhemweb:
<syntaxhighlight lang="perl">
attr MyDevive set01IMap 0:off, 1:on
</syntaxhighlight>
This also provides input validation to make sure that only on and off can be used with the set command.

In more complex Scenarios you might need to login before sending a command and the Login might create a session id that has to be part of further requests either in the URL, in headers or in the post data.

Extension to the above example for a PoolManager 5 where a set needs a session id in the URL and the values have to be passed in JSON strings as post data:
<syntaxhighlight lang="perl">
attr PM set01Name HeizungSoll
attr PM set01URL http://MyPoolManager/cgi-bin/webgui.fcgi?sid=$sid
attr PM set01Hint 6,10,20,30
attr PM set01Min 6
attr PM set01Max 30
attr PM setHeader1 Content-Type: application/json
attr PM set01Data {"set" :{"34.3118.value" :"$val" }}
</syntaxhighlight>

This example defines a set option with the name HeizungSoll.
By issuing <code>set PM HeizungSoll 10</code> in FHEM, the value 10 will be sent in the defined HTTP
Post to URL <code>http://MyPoolManager/cgi-bin/webgui.fcgi</code> in the Post Data as

<syntaxhighlight lang="html4strict">
{"set" :{"34.3118.value" :"10" }}
</syntaxhighlight>

The optional attributes set01Min and set01Max define input validations that will be checked in the set function.
The optional attribute set01Hint will define a selection list for the FHEMweb GUI.

The HTTP response to such a request will be ignored unless you specify the attribute <code>setParseResponse</code>
for all set commands or <code>set01ParseResponse</code> for the set command with number 01.
If the HTTP response to a set command is parsed then this is done like the parsing of responses to get commands and you can use the attributes ending e.g. on Format, Encode, Decode, OMap and OExpr to manipulate / format the values read.

If a parameter to a set command is not numeric but should be passed on to the device as text, then you can specify the attribute setTextArg. For example:
<syntaxhighlight lang="perl">
attr PM set01TextArg
</syntaxhighlight>

If a set command should not require a parameter at all, then you can specify the attribute NoArg. For example:
<syntaxhighlight lang="perl">
attr PM set03Name On
attr PM set03NoArg
</syntaxhighlight>

== Advanced configuration to create a valid session id that might be necessary ==
In simple cases logging in works with basic authentication. In the case HTTPMOD accepts a username and password as part of the URL in the form
<syntaxhighlight lang="perl">
http://User:Password@192.168.1.18/something
</syntaxhighlight>

However basic auth is seldom used. If you need to fill in a username and password in a HTML form and the session is then managed by a session id, here is how to configure this:

when sending data to an HTTP-Device in a set, HTTPMOD will replace any <code>$sid</code> in the URL, Headers and Post data with the internal <code>$hash->{sid}</code>. To authenticate towards the device and give this internal a value, you can use an optional multi step login procedure defined by the following attributes:

* <code>sid[0-9]*URL</code>
* <code>sid[0-9]*Data.*</code>
* <code>sid[0-9]*Header.*</code>
* <code>sid[0-9]*IgnoreRedirects</code>
* <code>idRegex</code>
* <code>idJSON</code>
* <code>idXPath</code>
* <code>idXPath-Strict</code>
* <code>(get|set|sid)[0-9]*IdRegex</code>
* <code>(get|set|sid)[0-9]*IdJSON</code>
* <code>(get|set|sid)[0-9]*IdXPath</code>
* <code>(get|set|sid)[0-9]*IdXPath-Strict</code>

Each step can have a URL, Headers, Post Data pieces and a Regex to extract a resulting Session ID into <code>$hash->{sid}</code>.
HTTPMOD will create a sorted list of steps (the numbers between sid and URL / Data / Header) and the loop through these steps and send the corresponding requests to the device. For each step a $sid in a Header or Post Data will be replaced with the current content of <code>$hash->{sid}</code>.

Using this feature, HTTPMOD can perform a forms based authentication and send user name, password or other necessary data to the device and save the session id for further requests.

To determine when this login procedure is necessary, HTTPMOD will first try to send a request without
doing the login procedure. If the result contains an error that authentication is necessary, then a login is performed.
To detect such an error in the HTTP response, you can again use a regular expression, JSON or XPath, this time with the attributes

* <code>reAuthRegex</code>
* <code>reAuthJSON</code>
* <code>reAuthXPath</code>
* <code>reAuthXPath-Strict</code>
* <code>(get|set)[0-9]*ReAuthRegex</code>
* <code>(get|set)[0-9]*ReAuthJSON</code>
* <code>(get|set)[0-9]*ReAuthXPath</code>
* <code>(get|set)[0-9]*ReAuthXPath-Strict</code>

reAuthJSON or reAuthXPath typically only extract one piece of data from a response.
If the existence of the specified piece of data is sufficent to start a login procedure, then nothing more needs to be defined to detect this situation.
If however the indicator is a status code that contains different values depending on a successful request and a failed request if a new authentication is needed,
then you can combine things like reAuthJSON with reAuthRegex. In this case the regex is only matched to the data extracted by JSON (or XPath).
This way you can easily extract the status code using JSON parsing and then specify the code that means "authentication needed" as a regular expression.

If for one step not all of the URL, Data or Header Attributes are set, then HTTPMOD tries to use a
<code>sidURL</code>, <code>sidData.*</code> or <code>sidHeader.*</code> Attribute (without the step number after sid). This way parts that are the same for all steps don't need to be defined redundantly.

=== Example for a multi step login procedure: ===
<syntaxhighlight lang="perl">
attr PM reAuthRegex /html/dummy_login.htm
attr PM sidURL http://192.168.70.90/cgi-bin/webgui.fcgi?sid=$sid
attr PM sidHeader1 Content-Type: application/json
attr PM sid1IDRegex wui.init\('([^']+)'
attr PM sid2Data {"set" :{"9.17401.user" :"fhem" ,"9.17401.pass" :"password" }}
attr PM sid3Data {"set" :{"35.5062.value" :"128" }}
attr PM sid4Data {"set" :{"42.8026.code" :"pincode" }}
</syntaxhighlight>

In this case HTTPMOD detects that a login is necessary by looking for the pattern /html/dummy_login.htm in the HTTP response.
If it matches, it starts a login sequence. In the above example all steps request the same URL. In step 1 only the defined Header is sent in an HTTP get request. The response will contain a session id that is extraced with the regex wui.init\('([^']+)'.

In the next step this session id is sent in a post request to the same URL where tha post data contains a username and password. The a third and a fourth request follow that set a value and a code. The result will be a valid and authorized session id that can be used in other requests where $sid is part of a URL, header or post data and will be replaced with the session id extracted above.

In the special case where a session id is set as a HTTP-Cookie (with the header Set-cookie: in the HTTP response) HTTPMOD offers an even simpler way. With the attribute enableCookies a very basic cookie handling mechanism is activated that stores all cookies that the server sends to the HTTPMOD device and puts them back as cookie headers in the following requests.

For such cases no sidIdRegex and no $sid in a user defined header is necessary.

== Advanced configuration to define a <code>get</code> and request additional data with its own request from a device ==

The normal automatic HTTP request that is done repeatedly after the defined interval has elapsed works well in cases where all required readings can be requested in one common HTTP request. If however a device needs individual requests with different URLs or different POST data for each value, then another method is necessary.
For such cases a <code>get</code> option can be defined and the user can either issue FHEM <code>get</code> commands each time he needs the reading or the user can set an attribute to request the reading automatically together with the normal iteration.
For each <code>get</code> option attributes define an individual URL, optional headers, and post data as well as individual regular expressions and formatting options.

When a get option is defined by attributes, the module allows querying additional values from the device that require individual HTTP-Requests or special parameters to be sent

Extension to the above example:

<syntaxhighlight lang="perl">
attr PM get01Name MyGetValue <br>
attr PM get01URL http://MyPoolManager/cgi-bin/directory/webgui.fcgi?special=1?sid=$sid <br>
attr PM getHeader1 Content-Type: application/json <br>
attr PM get01Data {"get" :{"30.1234.value"}} <br>
</syntaxhighlight>

This example defines a get option with the name MyGetValue.
By issuing <code>get PM MyGetValue</code> in FHEM, the defined HTTP request is sent to the device.
The HTTP response is then parsed using the same readingXXName and readingXXRegex attributes as above so
additional pairs will probably be needed there for additional values.

if you prefer to define the parsing and formatting of readings individually per get command, you can use
attributes like get01Regex, get01XPath, get01Format, get01OMap and so on just like for reading01...

You can also include parameters / values that are passed to the get command in the request just like for set commands.
The placeholder $val will be replaced with the value given to the get command or you can specify your own replacement as described above.

If the new get parameter should also be queried regularly, you can define the following optional attributes:

<syntaxhighlight lang="perl">
attr PM get01Poll 1
attr PM get01PollDelay 300
</syntaxhighlight>

The first attribute includes this reading in the automatic update cycle and the second defines an alternative lower update frequency. When the interval defined initially in the define is over and the normal readings are read from the device, the update function will check for additional get parameters that should be included in the update cycle.

If a PollDelay is specified for a get parameter, the update function also checks if the time passed since it has last read this value is more than the given PollDelay. If not, this reading is skipped and it will be rechecked in the next cycle when interval is over again. So the effective PollDelay will always be a multiple of the interval specified in the initial define.

Please note that each defined get command that is included in the regular update cycle will create its own HTTP request. So if you want to extract several values from the same request, it is much more efficient to do this by defining readingXXName and readingXXRegex, XPath or JSON attributes and to specify an interval and a URL in the define of the HTTPMOD device.

Example for a Siemens webserver provided by Lanhydrock:
<syntaxhighlight lang="perl">
define ozw672 HTTPMOD https://192.168.178.8/api/auth/login.json?user=test&pwd=test 300

attr ozw672 get1Name tempAussen
attr ozw672 get1URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1960
attr ozw672 get1Poll 1
attr ozw672 get1PollDelay 1800

attr ozw672 get2Name tempAussenGemischt
attr ozw672 get2URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1964
attr ozw672 get2Poll 1
attr ozw672 get2PollDelay 1800

attr ozw672 get3Name tempTWW
attr ozw672 get3URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1996
attr ozw672 get3Poll 1

attr ozw672 get4Name tempKesselSoll
attr ozw672 get4URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1910
attr ozw672 get4Poll 1

attr ozw672 get5Name tempKesselRuecklauf
attr ozw672 get5URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1915
attr ozw672 get5Poll 1

attr ozw672 get6Name tempKesselRuecklaufSoll
attr ozw672 get6URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1916
attr ozw672 get6Poll 1

attr ozw672 get7Name anzahlStartsBrenner
attr ozw672 get7URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1927
attr ozw672 get7PollDelay 1800
attr ozw672 get7Poll 1

attr ozw672 get8Name statusKessel
attr ozw672 get8URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1898
attr ozw672 get8Poll 1
attr ozw672 get8Regex Value": "([a-zA-Zü ]*)"
attr ozw672 get8OMap Aus:0, Nachlauf aktiv:5, Freigegeben für TWW:10, Freigegeben für HK:20, In Teillastbetrieb für TWW:40, In Teillastbetrieb für HK:50, In Betrieb für Trinkwasser:90, In Betrieb für Heizkreis:100

attr ozw672 getRegex Value": "[ ]*([-.0-9]*)"

attr ozw672 reAuthRegex .*session not valid.*
attr ozw672 sid1IDRegex .*"(.*-.*-.*-[0-9a-z]*).*
attr ozw672 sid1URL https://192.168.178.8/api/auth/login.json?user=test&pwd=test
</syntaxhighlight>

== All attributes ==
;reading[0-9]+Name
:the name of a reading to extract with the corresponding readingRegex, readingJSON, readingXPath or readingXPath-Strict
:Please note that the old syntax <b>readingsName.*</b> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.

;(get|set)[0-9]+Name
:Name of a get or set command
:If the HTTP response that is received after the command is parsed with an individual parse option then this name is also used as a reading name. Please note that no individual parsing needs to be defined for a get or set. If no regex, XPath or JSON is specified for the command, then HTTPMOD will try to parse the response using all the defined readingRegex, reading XPath or readingJSON attributes.

;(get|set|reading)[0-9]+Regex
:If this attribute is specified, the Regex defined here is used to extract the value from the HTTP Response and assign it to a Reading with the name defined in the (get|set|reading)[0-9]+Name attribute.
:If this attribute is not specified for an individual Reading or get or set but without the numbers in the middle, e.g. as getRegex or readingRegex, then it applies to all the other readings / get / set commands where no specific Regex is defined.<br>
:The value to extract should be in a capture group / sub expression e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)
:Using this attribute for a set command (setXXRegex) only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
:Please note that the old syntax <code>readingsRegex.*</code> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.
:If for get or set commands neither a generic Regex attribute without numbers nor a specific (get|set)[0-9]+Regex attribute is specified and also no XPath or JSON parsing specification is given for the get or set command, then HTTPMOD tries to use the parsing definitions for general readings defined in reading[0-9]+Name, reading[0-9]+Regex or XPath or JSON attributes and assigns the Readings that match here.

;(get|set|reading)[0-9]+RegOpt
:Lets the user specify regular expression modifiers. For example if the same regular expression should be matched as often as possible in the HTTP response, then you can specify RegOpt g which will case the matching to be done as /regex/g
:The results will be trated the same way as multiple capture groups so the reading name will be extended with -number.
:For other possible regular expression modifiers see http://perldoc.perl.org/perlre.html#Modifiers

;(get|set|reading)[0-9]+XPath
:defines an xpath to one or more values when parsing HTML data (see examples above)
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;get|set|reading[0-9]+XPath-Strict
:defines an xpath to one or more values when parsing XML data (see examples above)
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]+AutoNumLen
:In cases where a regular expression or an XPath results in multiple results and these results are stored in a common reading name with extension -number, then you can modify the format of this number to have a fixed length with leading zeros. AutoNumLen 3 for example will lead to reading names ending with -001 -002 and so on.

;(get|set|reading)[0-9]+AlwaysNum
:if set to 1 this attributes forces reading names to end with a -1, -01 (depending on the above described AutoNumLen) even if just one value is parsed.

;get|set|reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names. See the above example.
:If you don't know the paths, then start by using extractAllJSON and the use the names of the readings as values for the JSON attribute.<br>
:Please don't forget to also specify a name for a reading, get or set.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]*RecombineExpr
:defines an expression that is used in an eval to compute one reading value out of the list of matches.
:This is supposed to be used for regexes or xpath specifications that produce multiple results if only one result that combines them is wanted. The list of matches will be in the variable @matchlist.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;get[0-9]*CheckAllReadings
:this attribute modifies the behavior of HTTPMOD when the HTTP Response of a get command is parsed. <br>
:If this attribute is set to 1, then additionally to the matching of the corresponding get specific regex (get[0-9]*Regex), XPath or JSON attribute also all the reading names and parse definitions defined in Reading[0-9]+Name and Reading[0-9]+Regex, XPath or JSON attributes are checked and if they match, the coresponding Readings are assigned as well.
:Please note that this does not mean that get01CheckAllReadings will cause a get02Regex to be used. Only the corresponding get01Regex will be used but additionally all the readingXYRegex attributes.
:This is automatically done if a get or set command is defined without its own parse attributes.

;(get|reading)[0-9]*OExpr
:defines an optional expression that is used in an eval to compute / format a readings value after parsing an HTTP response
:The raw value from the parsing will be in the variable $val.
:If specified as readingOExpr then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Expr.
:Please note that the old syntax <b>readingsExpr.*</b> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.

;(get|reading)[0-9]*Expr
:This is the old syntax for (get|reading)[0-9]*OExpr. It should be replaced by (get|reading)[0-9]*OExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;(get|reading)[0-9]*OMap
:Map that defines a mapping from raw value parsed to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".
:If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Map.<br>
:The individual options in a map are separated by a komma and an optional space. Spaces are allowed to appear in a visible value however kommas are not possible.

;(get|reading)[0-9]*Map
:This is the old syntax for (get|reading)[0-9]*OMap. It should be replaced by (get|reading)[0-9]*OMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;(get|set|reading)[0-9]*Format
:Defines a format string that will be used in sprintf to format a reading value.
:If specified without the numbers in the middle e.g. as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.<br>

;(get|set|reading)[0-9]*Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading.
:This can be used if the device delivers strings in an encoding like cp850 instead of utf8.
:If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]*Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading.
:This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.
:If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set)[0-9]*URL
:URL to be requested for the set or get command. If this option is missing, the URL specified during define will be used.

;(get|set)[0-9]*Data
:Data to be sent to the device as POST data when the get or set command is executed. if this attribute is not specified, an HTTP GET method will be used instead of an HTTP POST

;(get|set)[0-9]*NoData
:can be used to override a more generic attribute that specifies POST data for all get or set commands. With NoData no data is sent and therefor the request will be an HTTP GET.

;(get|set)[0-9]*Header.*
:HTTP Headers to be sent to the device when the set is executed

;requestHeader.*
:Define an optional additional HTTP Header to set in the HTTP request of the main loop

;requestData
:optional POST Data to be sent in the request of the main loop. If not defined, it will be an HTTP GET request as defined in HttpUtils which is used by this module

;get[0-9]+Poll
:if set to 1 the get is executed automatically during the normal update cycle (after the interval provided in the define command has elapsed)

;get[0-9]+PollDelay
:if the value should not be read in each iteration (after the interval given to the define command), then a minimum delay can be specified with this attribute. This has only an effect if the above Poll attribute has also been set. Every time the update function is called, it checks if since this get has been read the last time, the defined delay has elapsed. If not, then it is skipped this time.
:PollDelay can be specified as seconds or as x[0-9]+ which means a multiple of the interval in the define command.

;(get|set)[0-9]*TextArg
:For a get command this defines that the command accepts a text value after the option name. By default a get command doesn't accept optional values after the command name.
:If TextArg is specified and a value is passed after the get name then this value can then be used in a request URL, header or data as replacement for $val or in a user defined replacement that uses the internal "value" ($hash->{value}).
:If used for a set command then it defines that the value to be set doesn't require any validation / conversion.
:The raw value is passed on as text to the device. By default a set command expects a numerical value or a text value that is converted to a numeric value using a map.

;set[0-9]+Min
:Minimum value for input validation.

;set[0-9]+Max
:Maximum value for input validation.

;set[0-9]+IExpr
:Perl Expression to compute the raw value to be sent to the device from the input value passed to the set.

;set[0-9]+Expr
:This is the old syntax for (get|reading)[0-9]*IExpr. It should be replaced by (get|reading)[0-9]*IExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;set[0-9]+IMap
:Map that defines a mapping from raw to input values like "0:mittig, 1:oberhalb, 2:unterhalb". This attribute atomatically creates a hint for FHEMWEB so the user can choose one of the input values.

;set[0-9]+Map
:This is the old syntax for (get|reading)[0-9]*IMap. It should be replaced by (get|reading)[0-9]*IMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;set[0-9]+Hint
:Explicit hint for fhemWEB that will be returned when set ? is seen. Can be used to get a slider or a list of values to choose from.

;set[0-9]*NoArg
:Defines that this set option doesn't require arguments. It allows sets like "on" or "off" without further values.

;set[0-9]*ParseResponse
:defines that the HTTP response to the set will be parsed as if it was the response to a get command.

;(get|set)[0-9]*URLExpr
:Defines a Perl expression to specify the HTTP Headers for this request. This overwrites any other header specification and should be used carefully only if needed. The original Header is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;(get|set)[0-9]*DatExpr
:Defines a Perl expression to specify the HTTP Post data for this request. This overwrites any other post data specification and should be used carefully only if needed. The original Data is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;(get|set)[0-9]*HdrExpr
:Defines a Perl expression to specify the URL for this request. This overwrites any other URL specification and should be used carefully only if needed. The original URL is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;ReAuthRegex
:regular Expression to match an error page indicating that a session has expired and a new authentication for read access needs to be done.
:This attribute only makes sense if you need a forms based authentication for reading data and if you specify a multi step login procedure based on the sid.. attributes.
:This attribute is used for all requests. For set and get operations you can however specify individual reAuthRegexes with the (get|set)[0-9]*ReAuthRegex attributes.

;(get|set)[0-9]*ReAuthRegex
:Regex that will detect when a session has expired during a set operation and a new login needs to be performed.
:It works like the global reAuthRegex but is used for set operations.

;sid[0-9]*URL
:different URLs or one common URL to be used for each step of an optional login procedure.

;sid[0-9]*IDRegex
:different Regexes per login procedure step or one common Regex for all steps to extract the session ID from the HTTP response

;sid[0-9]*Data.*
:data part for each step to be sent as POST data to the corresponding URL

;sid[0-9]*Header.*
:HTTP Headers to be sent to the URL for the corresponding step

;sid[0-9]*IgnoreRedirects
:Tells the HttpUtils to not follow HTTP Redirects for this Request. Might be needed for some devices that set a session cookie within a 303 Redirect.

;clearSIdBeforeAuth
:will set the session id to "" before doing the authentication steps

;authRetries
:number of retries for authentication procedure - defaults to 1

;replacement[0-9]*Regex
:Defines a replacement to be applied to an HTTP request header, data or URL before it is sent. This allows any part of the request to be modified based on a reading, an internal or an expression.
:The regex defines which part of a header, data or URL should be replaced. The replacement is defined with the following attributes:

;replacement[0-9]*Mode
:Defines how the replacement should be done and what replacementValue means. Valid options are text, reading, internal and expression.

;replacement[0-9]*Value
:Defines the replacement. If the corresponding replacementMode is <code>text</code>, then value is a static text that is used as the replacement.
:If replacementMode is <code>reading</code> then Value can be the name of a reading of this device or it can be a reading of a different device referred to by devicename:reading.
:If replacementMode is <code>internal</code> the Value can be the name of an internal of this device or it can be an internal of a different device referred to by devicename:internal.
:If replacementMode is <code>expression</code> the the Value is treated as a Perl expression that computes the replacement value. The expression can use $1, $2 and so on to refer to capture groups of the corresponding regex that is matched against the original URL, header or post data.
:If replacementMode is <code>key</code> then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.

;[gs]et[0-9]*Replacement[0-9]*Value
:This attribute can be used to override the replacement value for a specific get or set.

;get|reading[0-9]*MaxAge
:Defines how long a reading is valid before it is automatically overwritten with a replacement when the read function is called the next time.

;get|reading[0-9]*MaxAgeReplacement
:specifies the replacement for MaxAge - either as a static text or as a perl expression.

;get|reading[0-9]*MaxAgeReplacementMode
:specifies how the replacement is interpreted: can be text, expression and delete.

;get|reading[0-9]*DeleteIfUnmatched
:If set to 1 this attribute causes certain readings to be deleted when the parsing of the website does not match the specified reading. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation does not parse this reading again. This is especially useful for parsing that creates several matches / readings and the number of matches can vary from request to request. For example if reading01Regex creates 4 readings in one update cycle and in the next cycle it only matches two times then the readings containing the remaining values from the last round will be deleted.
:Please note that this mechanism will not work in all cases after a restart. Especially when a get definition does not contain its own parsing definition but ExtractAllJSON or relies on HTTPMOD to use all defined reading.* attributes to parse the responsee to a get command, old readings might not be deleted after a restart of fhem.
;get|reading[0-9]*DeleteOnError
:If set to 1 this attribute causes certain readings to be deleted when the website can not be reached and the HTTP request returns an error. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation returns an error.
The same restrictions as for DeleteIfUnmatched apply regarding a fhem restart.

;httpVersion
:defines the HTTP-Version to be sent to the server. This defaults to 1.0.

;sslVersion
:defines the SSL Version for the negotiation with the server. The attribute is evaluated by HttpUtils. If it is not specified, HttpUtils assumes SSLv23:!SSLv3:!SSLv2

;sslArgs
:defines a list that is converted to a key / value hash and gets passed to HttpUtils. To avoid certificate validation for broken servers you can for example specify
:<code>attr myDevice sslArgs SSL_verify_mode,SSL_VERIFY_NONE</code>

;alignTime
:Aligns each periodic read request for the defined interval to this base time. This is typcally something like 00:00 (see the FHEM at command)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;enableControlSet
:enables the built in set commands interval, stop, start, reread, upgradeAttributes, storeKeyValue.

;enableCookies
:enables the built in cookie handling if set to 1. With cookie handling each HTTPMOD device will remember cookies that the server sets and send them back to the server in the following requests.
:This simplifies session magamenet in cases where the server uses a session ID in a cookie. In such cases enabling cookies should be sufficient and no sidRegex and no manual definition of a cookie header should be necessary.

;showMatched
:if set to 1 then HTTPMOD will create a reading with the name MATCHED_READINGS that contains the names of all readings that could be matched in the last request as well as UNMATCHED_READINGS and LAST_REQUEST.

;showError
:if set to 1 then HTTPMOD will create a reading and event with the Name LAST_ERROR that contains the error message of the last error returned from HttpUtils.

;removeBuf
:if set to 1 then HTTPMOD removes the internal named buf when a HTTP-response has been received.
:$hash->{buf} is used internally be Fhem httpUtils and in some use cases it is desireable to remove this internal after reception
:because it contains a very long response which looks ugly in Fhemweb.

;timeout
:time in seconds to wait for an answer. Default value is 2

;queueDelay
:HTTP Requests will be sent from a queue in order to avoid blocking when several Requests have to be sent in sequence. This attribute defines the delay between calls to the function that handles the send queue. It defaults to one second.

;queueMax
:Defines the maximum size of the send queue. If it is reached then further HTTP Requests will be dropped and not be added to the queue

;minSendDelay
:Defines the minimum time between two HTTP Requests.

== Links ==
* Beispiel: [[Wetter_und_Wettervorhersagen#Wetter_von_Weather_Underground|Wetter von WeatherUnderground auslesen]]
* Beispiel: [[Pollenflug]]
* Beispiel: [[HTTPMOD Beispielkonfiguration zur Anbindung einer Daikin Klimaanlage mit WLAN-Modul]]
* Beispiel: [[Go-eCharger|Auslesen der Information der Wallbox go-eCharger]]
* Beispiel: [[Sonnenspeicher|Einbindung des Speichersystems von sonnen (https://sonnen.de/stromspeicher/)]]
* {{Link2Forum|Topic=17804|LinkText=Thread}} in FHEM Forum that discusses the first version of this module
* {{Link2Forum|Topic=29471|LinkText=Thread}} in FHEM Forum that discusses the second major version of this module
* {{Link2Forum|Topic=45176|LinkText=Thread}} in FHEM Forum that discusses the third major version of this module
* [http://perldoc.perl.org/perlretut.html Introduction to regular expressions]
* [http://portswigger.net/burp/ BurpSuite]: Tool (local proxy) to help analyze http traffic

[[Kategorie:IP Components]]

Sonnenspeicher

2018-09-12T20:40:10Z

C2j2: Einbindung des Speichersystems von sonnen per HTTPMOD

== Hinweise zur schnellen Einbindung des Speichersystems von sonnen (https://sonnen.de/stromspeicher/) per HTTPMOD ==

Im Kürze:
<pre>
define sonnenbatterie HTTPMOD http://x.x.x.x:8080/api/v1/status 60
attr sonnenbatterie extractAllJSON 1
attr sonnenbatterie stateFormat {sprintf("PV %d W -> Haushalt %d W + Grid %d W + %d W, SOC %d%%", \
ReadingsVal($name,"Production_W",0),\
ReadingsVal($name,"Consumption_W",0),\
ReadingsVal($name,"GridFeedIn_W",0),\
ReadingsVal($name,"Pac_total_W",0),\
ReadingsVal($name,"RSOC","-1")\
)}
</pre>

Leere Seite 2

2018-09-12T20:21:27Z

C2j2:

== Hinweise zur schnellen Einbindung von go-eCharger (https://go-e.co/de/) per HTTPMOD ==

Voraussetzung ist, dass die HTTP-API aktiviert ist:
* Smartphone mit e-goCharger WLAN verbinden
* in "Cloud", "erweiterte Einstellungen" das HTTP-Protokoll aktivieren
* "Neustart" auswählen (ohne diesen war bei mir die Box nicht zu erreichen)
* fertig, Smartphone kann wieder ins normale WLAN

Dann in FHEM:
<pre>
define go_eCharger HTTPMOD http://go-eCharger/status 30
attr go_eCharger extractAllJSON 1
attr go_eCharger stateFormat {sprintf("%s: %s Current %d A, ETO=%d kWh",\
ReadingsVal($name,"car",0)==1?"ready, waiting for car":\
ReadingsVal($name,"car",0)==2?"car loading":\
ReadingsVal($name,"car",0)==3?"waiting for car":\
ReadingsVal($name,"car",0)==4?"charge finished, but connected":"unknown",\
ReadingsVal($name,"err",0)==1?"error RCCB: ":\
ReadingsVal($name,"err",0)==3?"error PHASE: ":\
ReadingsVal($name,"err",0)==8?"error NO_GROUND: ":\
ReadingsVal($name,"err",0)==10?"error INTERNAL: ":"",\
ReadingsVal($name,"amp",0),\
ReadingsVal($name,"eto",0)/10,\
""\
)}
</pre>

Das dürfte so das Wichtigste sein, um die Werte auszulesen.

HTTPMOD

2018-09-12T20:17:59Z

C2j2: /* Links */

{{Infobox Modul
|ModPurpose=Extract information from devices with an HTTP interface (or, more generic, from any URL) or send information to such devices
|ModType=d
|ModCmdRef=HTTPMOD
|ModForumArea=Sonstiges
|ModTechName=98_HTTPMOD.pm
|ModOwner=StefanStrobel ({{Link2FU|3960|Forum}} / [[Benutzer:StefanStrobel|Wiki]])
}}

HTTPMOD provides a generic way to retrieve information from devices with an HTTP Interface and store them in Readings or send information to such devices. It queries a given URL with Headers and data defined by attributes.

From the HTTP response it extracts readings named in attributes using Regexes, JSON or XPath parsing also defined by attributes.

In an advanced [[Konfiguration|configuration]] the module can also send information to devices. To do this, a generic <code>set</code> option can be configured using attributes.

== Availability ==
The module is part of the regular FHEM distribution.

== Prerequisites ==
This module uses the non blocking HTTP function <code>HttpUtils_NonblockingGet</code> provided by FHEM's [[HttpUtils]] in a new version published in December 2013.
If not already installed in your environment, please [[update]] FHEM or install it manually using appropriate commands from your environment.
Please also note that FHEM HttpUtils need the global attribute dnsServer to be set in order to work really non blocking even when dns requests can not be answered.

== Define ==
<syntaxhighlight lang="perl">
define <name> HTTPMOD <URL> <Interval>
</syntaxhighlight>
The module connects to the given <code>URL</code> every <code>Interval</code> seconds, sends optional headers and data and then parses the response with regular expressions, xpath or json to set readings.

URL can be "none" and Interval can be 0 if you prefer to only query data with a get command and not in a defined interval.

Example:
<syntaxhighlight lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60
</syntaxhighlight>

== Set-Commands ==
can be defined using attributes, see advanced configuration

If you set the attribute enableControlSet to 1, the following additional built in set commands are available:
;interval
:set new interval time in seconds and restart the timer
;reread
:request the defined URL and try to parse it just like the automatic update would do it every Interval seconds without modifying the running timer.
;stop
:stop interval timer.
;start
:restart interval timer to call GetUpdate after interval seconds
;upgradeAttributes
:convert outdated attributes for older HTTPMOD-Versions that are still defined for this device from the old syntax to the new one.
:attributes with the description "this attribute should not be used anymore" or similar will be translated to the new syntax, e.g. readingsName1 to reading01Name.
;storeKeyValue
:stores a key value pair in an obfuscated form in the file system. Such values can then be used in replacements where the mode is "key" e.g. to avoid storing passwords in the configuration in clear text

== Get-Commands ==
can be defined using attributes, see advanced configuration

== simple Attributes ==
;enableControlSet
:enables the built in set commands ''interval'', ''stop'', ''start'', ''reread'', ''upgradeAttributes'', ''storeKeyValue''

;enableCookies
:enables the cookie handling inside HTTPMOD. It is advisable to always set this attribute and allow HTTPMOD to track the state of cookies and set them for following HTTP-requests

;enforceGoodReadingNames
:makes sure that HTTPMOD only creates readings that are allowd for Fhem (especially if reading names are dynamically created from JSON object names with extractAllJSON. It is advisable to always set this attribute.

;handleRedirects
:enables the redirect handling inside HTTPMOD which should be used together with the cookie handling of HTTPMOD. HTTPMOD will then automatically follow redirects from a web server and keep track of cookies at the same time. It is advisable to always set this attribute.

;requestHeader.*
:Define an additional HTTP Header to set in the HTTP request

;requestData
:POST Data to be sent in the request. If not defined, it will be a GET request as defined in HttpUtils used by this module

;reading[0-9]+(-[0-9]+)?Name
:the name of a reading to extract with the corresponding readingRegex

;reading[0-9]*(-[0-9]+)?OExpr
:defines an expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

;reading[0-9]*(-[0-9]+)?OMap
:Output Map. Defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb". If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*OMap.

;reading[0-9]*(-[0-9]+)?Format
:Defines a format string that will be used in sprintf to format a reading value. If specified as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.

;reading[0-9]*(-[0-9]+)?Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 instead of utf8.

;reading[0-9]*(-[0-9]+)?Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.

;reading[0-9]+Regex
:defines the regex to be used for extracting the reading. The value to extract should be in a capture group / sub expression
:e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)

;reading[0-9]+XPath
:defines an xpath to one or more readings when parsing HTML data (see examples below)

;reading[0-9]+XPath-Strict
:defines an xpath to one or more readings when parsing XML data (see examples below)

;reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names with an underscore as delimiter (see the example below)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;timeout
:time in seconds to wait for an answer. Default value is 2

;do_not_notify

;readingFnAttributes

== Simple Configuration of HTTP Devices ==
If your device expects special HTTP-headers then specify them as <code>attr requestHeader1</code> to <code>attr requestHeaderX</code>.
If your Device expects an HTTP POST instead of HTTP GET then the POST-data can be specified as <code>attr requestData</code>.
To get the readings, specify pairs of <code>attr readingXName</code> and <code>attr readingXRegex</code>, <code>attr readingXXPath</code>, <code>attr readingXXPath-Strict</code> or <code>attr readingXJSON</code> to define which readings you want to extract from the HTTP response and how to extract them. (The old syntax <code>attr readingsNameX</code> and <code>attr readingsRegexX</code> is still supported but the new one with <code>attr readingXName</code> and <code>attr readingXRegex</code> should be preferred. The actual values to be extracted have to be sub expressions within () in the regex (see example below)

=== Example for a PoolManager 5: ===
The PoolManager Web GUI can be queried with HTTP POST Requests like this one:

<syntaxhighlight lang="perl">
POST /cgi-bin/webgui.fcgi HTTP/1.1
Host: 192.168.70.90
Accept: */*
Content-Type: application/json;charset=UTF-8
Content-Length: 60

{"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value"]}
</syntaxhighlight>

The resulting HTTP Response would look like this:

<syntaxhighlight lang="perl">
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
Expires: 0
Cache-Control: no-cache
Date: Sun, 12 Jan 2014 12:23:11 GMT
Server: lighttpd/1.4.26
Content-Length: 179

{
"data": {
"34.4001.value": "7.00",
"34.4008.value": "0.52",
"34.4033.value": "24.8"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</syntaxhighlight>

To configure HTTPMOD for a PoolManager one would first define a PoolManager device with e.g. the name PM, the URL and an interval of e.g. 60 seconds.

Then the data to be sent in the request needs to be defined because in this example the device expects a POST request so the query is not contained in the URL but in the request data.

Also as seen above the device expects special HTTP headers in the request so these headers also need to be defined as <code>attr PM requestHeader1</code> and <code>attr PM requestHeader2</code>

Then the names of the readings to be extracted would be set with attributes

Then for each reading value to be extracted a regular expression needs to be set that will match the value in question within ().

Example:
<syntaxhighlight lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60

attr PM enableControlSet 1
attr PM enableCookies 1
attr PM enforceGoodReadingNames 1
attr PM handleRedirects 1

attr PM reading01Name PH
attr PM reading01Regex 34.4001.value":[ \t]+"([\d\.]+)"

attr PM reading02Name CL
attr PM reading02Regex 34.4008.value":[ \t]+"([\d\.]+)"

attr PM reading03Name3TEMP
attr PM reading03Regex 34.4033.value":[ \t]+"([\d\.]+)"

attr PM requestData {"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value", "14.16601.value", "14.16602.value"]}
attr PM requestHeader1 Content-Type: application/json
attr PM requestHeader2 Accept: */*
attr PM stateFormat {sprintf("%.1f Grad, PH %.1f, %.1f mg/l Chlor", ReadingsVal($name,"TEMP",0), ReadingsVal($name,"PH",0), ReadingsVal($name,"CL",0))}
</syntaxhighlight>

=== Example for AmbientMonitor ===
AmbientMonitor is a webbased visualisation for sensors connected to an Arduino device. Its web interface can also be queried with HTTMOD to grab the data into readings.

This example was provided by locutus. The hardware configuration is an Arduino + Ethercard with ENC28J60 Controller + DHT22 Sensor and software can be downloaded from https://github.com/lucadentella/AmbientMonitor

In this example an HTTP GET is sufficent, so no <code>requestData</code> is needed. The device provides temperature and humidity readings in an HTTP response that looks like:
<syntaxhighlight lang="perl">
HTTP/1.0 200 OK
Content-Type: text/html

myCB({'temperature':22.00,'humidity':46.00})
</syntaxhighlight>

the definition could be:
<syntaxhighlight lang="perl">
define AmbientMonitor HTTPMOD http://192.168.1.221/?callback=? 300

attr AmbientMonitor enableControlSet 1
attr AmbientMonitor enableCookies 1
attr AmbientMonitor enforceGoodReadingNames 1
attr AmbientMonitor handleRedirects 1

attr AmbientMonitor requestHeader Content-Type: application/json
attr AmbientMonitor reading1Name Temperatur
attr AmbientMonitor reading1Regex temperature':([\d\.]+)
attr AmbientMonitor reading2Name Feuchtigkeit
attr AmbientMonitor reading2Regex humidity':([\d\.]+)
attr AmbientMonitor stateFormat {sprintf("Temperatur %.1f C, Feuchtigkeit %.1f %", ReadingsVal($name,"Temperatur",0), ReadingsVal($name,"Feuchtigkeit",0))}
</syntaxhighlight>

== formatting and manipulating values / readings ==
Values that are parsed from an HTTP response can be further treated or formatted with the following attributes:

* <code>(reading|get)[0-9]*(-[0-9]+)?OExpr</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?OMap</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Format</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Decode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Encode</code>

They can all be specified for an individual reading, for all readings in one match (e.g. if a regular expression has several capture groups) or for all readings in a get command (defined by getXX) or for all readings in the main reading list (defined by readingXX):
<syntaxhighlight lang="perl">
reading01Format %.1f
</syntaxhighlight>

will format the reading with the name specified by the attribute reading01Name to be numerical with one digit after the decimal point.
If the attribute reading01Regex is used and contains several capture groups then the format will be applied to all readings parsed by this regex unless these readings have their own format specified by reading01-1Format, reading01-2Format and so on.

<syntaxhighlight lang="perl">
reading01-2Format %.1f
</syntaxhighlight>

Can be used in cases where a regular expression specified as reading01regex contains several capture groups or an xpath specified as reading01XPath creates several readings.
In this case reading01-2Format specifies the format to be applied to the second match.

<syntaxhighlight lang="perl">
readingFormat %.1f
</syntaxhighlight>

applies to all readings defined by a reading-Attribute that have no more specific format.

If you need to do some calculation on a raw value before it is used as a reading, you can define the attribute <code>readingOExpr</code>.
It defines a Perl expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

Example for an expression:
<syntaxhighlight lang="perl">
attr PM reading03OExpr $val * 10
</syntaxhighlight>
Just like in the above example of the readingFormat attributes, readingOExpr and the other following attributes can be applied on several levels.

To map a numerical value to a name, you can use the readingOMap attribute.
It defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".

Example for a map:
<syntaxhighlight lang="perl">
attr PM reading02-3OMap 0:kalt, 1:warm, 2:sehr warm
</syntaxhighlight>

To convert character sets, the module can first decode a string read from the device and then encode it again. For example:
<syntaxhighlight lang="perl">
attr PM getDecode UTF-8
</syntaxhighlight>

This applies to all readings defined for Get-Commands.

== Some help with Regular Expressions ==
{{Randnotiz|RNTyp=y|RNText=Starting with version ''2018-02-10'' the internal that holds the HTTP response is no longer called '''''buf''''' but rather '''''httpbody''''', and it is only displayed when attribute '''''showBody''''' is set to "1".}}
If HTTPMOD seems not to work and the FHEM Logfile contains a message like
:<code>HTTPMOD: Response didn't match Reading ...</code>
then you should check if the value you want to extract is read into the internal with the name buf. Internals are visible when you click on the defined HTTPMOD Device. buf is an internal variable that contains the HTTP Response read. If the value is there and you get the mentioned message then probably something is wrong with your regular expression. Please note that buf might contain special characters like newlines but they are not shown in fhemweb. If you are new to regular expressions then the introduction at http://perldoc.perl.org/perlretut.html might be helpful.

For a typical HTTPMOD use case where you want to extract a number out of a HTTP-Response you can use something like <code>[\d\.]+</code> to match the number itself. The expression matches the number characters (<code>\d</code>) or a <code>.</code> if one of these characters occurs at least once.

To tell HTTPMOD that the number is what you want to use for the reading, you have to put the expression in between <code>()</code>. A <code>([\d\.]+)</code> alone would match the longest number in the HTTP Response which is very likely not the number you are looking for so you need to add something to the expression to give it a context and define how to find the number that you are looking for.

If there is a title text before the number or a special text after the number you can put this in the regex. In one of the examples above <code>humidity':([\d\.]+)</code> is looking for the number that immediately follows the text <code>humidity':</code> without any blanks in between.
Be careful if the text you are getting from your device contains special characters like newline. You don't see such special characters in the fhem webinterface as contents of the internal buf but they might cause your regular expression to fail.

If you have trouble defining a regular expression that matches a certain name, then many complicated characters and then a number, it might be helpful to use a negation in matching like <code>temp[^\d]+([\d\.]).*</code>. In this examle <code>[^\d]+</code> means any character that is not a numerical digit, more than once.

=== Regular Expressions with multiple capture Groups ===
The regular expressions used in the above example for a Poolmanager will take the value that matches one capture group. This is the part of the regular expression inside (). In the above example "([\d\.]+)" refers to numerical digits or points between double quotation marks. Only the string consiting of digits and points will match inside (). This piece is assigned to the reading.

You can also use regular expressions that have several capture groups which might be helpful when parsing tables. In this case an attribute like

<syntaxhighlight lang="perl">
reading02Regex something[ \t]+([\d\.]+)[ \t]+([\d\.]+)
</syntaxhighlight>

could match two numbers. When you specify only one reading02Name like
<syntaxhighlight lang="perl">
reading02Name Temp
</syntaxhighlight>

the name Temp will be used with the extension -1 and -2 thus giving a reading Temp-1 for the first number and Temp-2 for the second. You can also specify individual names for several readings that get parsed from one regular expression with several capture groups by defining attributes

<syntaxhighlight lang="perl">
reading02-1Name
reading02-2Name
...
</syntaxhighlight>
The same notation can be used for formatting attributes like readingXOMap, readingXFormat and so on.

The usual way to define readings is however to have an individual regular expression with just one capture group per reading as shown in the above example.

== Parsing JSON ==

If a webservice delivers data in JSON format, HTTPMOD can directly parse JSON which might be easier in this case than definig regular expressions.
The next example shows the data that can be requested from a Poolmanager with the following partial configuration:

<syntaxhighlight lang="perl">
define test2 HTTPMOD none 0
attr test2 get01Name Chlor
attr test2 getURL http://192.168.70.90/cgi-bin/webgui.fcgi
attr test2 getHeader1 Content-Type: application/json
attr test2 getHeader2 Accept: */*
attr test2 getData {"get" :["34.4008.value"]}
</syntaxhighlight>

The data in the HTTP response looks like this:

<syntaxhighlight lang="perl">
{
"data": {
"34.4008.value": "0.25"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</syntaxhighlight>

the classic way to extract the value 0.25 into a reading with the name Chlor with a regex would have been
<syntaxhighlight lang="perl">
attr test2 get01Regex 34.4008.value":[ \t]+"([\d\.]+)"
</syntaxhighlight>

with JSON you can write
<syntaxhighlight lang="perl">
attr test2 get01JSON data_34.4008.value
</syntaxhighlight>
which will create a reading with the Name "Chlor" (as shown above) and take the value 0.25 from the JSON string.

or if you don't care about the naming of your readings, you can simply extract all JSON data with
<syntaxhighlight lang="perl">
attr test2 extractAllJSON
</syntaxhighlight>

which would apply to all data read from this device and create the following readings out of the HTTP response shown above:

{| class="wikitable"
| data_34.4008.value || 0.25
|-
| event_data || 48.30000.0
|-
| event_type || 1
|-
| status_code || 0
|}

or you can specify
<syntaxhighlight lang="perl">
attr test2 get01ExtractAllJSON
</syntaxhighlight>
which would only apply to all data read as response to the get command defined as get01.

It might seem very simple at first sight to use extractAllJSON but if you prefer readings with a meaningful name you should instead define these readings with readingXXName and readingXXJSON or getXXName and getXXJSON individually. Of Course it would be possible to create additional user readings outside HTTPMOD but doing calculations, naming and formatting inside HTTPMOD is more efficient.

=== JSON Lists ===

imagine the HTTP Response contains:

<syntaxhighlight lang="perl">
{ "power":"0",
"modes":["Off","SimpleColor","RainbowChase"],
"code1":3,
"code2":4
}
</syntaxhighlight>

then a configuration like

<syntaxhighlight lang="perl">
attr device reading01JSON modes
attr device reading01Name Mode
</syntaxhighlight>

will create a list of Subreadings just like a regex with multiple matches can create multiple subreadings:

{| class="wikitable"
| Mode-1 || Off
|-
| Mode-2 || SimpleColor
|-
| Mode-3 || RainbowChase
|}

if you don't want several subreadings but one reading that contains the list of modes, you can specify a recombine expression:

<syntaxhighlight lang="perl">
attr device reading01Name Modes
attr device reading01RecombineExpr join ",", @matchlist
</syntaxhighlight>

which will create one reading containing a list:

{| class="wikitable"
| Modes || Off,SimpleColor,RainbowChase
|}

JSON parsing specifications also don't Need to match exactly. If there is no exact match for a defined reading, the HTTPMOD will try to Interpret the specification as a regex and look for json object paths that match the specification as a regex. For example:

<syntaxhighlight lang="perl">
attr device reading01Name CodeElem
attr device reading01JSON code
</syntaxhighlight>

which will create a list of readings:

{| class="wikitable"
| CodeElem-1|| 3
|-
| CodeElem-2 || 4
|}

and of course they could also be recombined into one reading with a RecombineExpr Attribute.

== Parsing http / XML using xpath ==
Another alternative to regex parsing is the use of XPath to extract values from HTTP responses.
The following example shows how XML data can be parsed with XPath-Strict or HTML Data can be parsed with XPath.
Both work similar and the example uses XML Data parsed with the XPath-Strict option:

If The XML data in the HTTP response looks like this:

<syntaxhighlight lang="xml">
<root xmlns:foo="http://www.foo.org/" xmlns:bar="http://www.bar.org">
<actors>
<actor id="1">Peter X</actor>
<actor id="2">Charles Y</actor>
<actor id="3">John Doe</actor>
</actor>
</root>
</syntaxhighlight>

with XPath you can write
<syntaxhighlight lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor[2]/text()
</syntaxhighlight>

This will create a reading with the Name "Actor" and the value "Charles Y".

Since XPath specifications can define several values / matches, HTTPMOD can also interpret these and store them in multiple readings:
<syntaxhighlight lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor/text()
</syntaxhighlight>

will create the readings

{| class="wikitable"
| Actor-1 || Peter X
|-
| Actor-2 || Charles Y
|-
| Actor-3 || John Doe
|}

== Further replacements of URL, header or post data ==
sometimes it might be helpful to dynamically change parts of a URL, HTTP header or post data depending on existing readings, internals or
perl expressions at runtime. This might be needed to pass further variables to a server, a current date or other things.

To support this HTTPMOD offers generic replacements that are applied to a request before it is sent to the server. A replacement can be defined with the attributes

* <code>replacement[0-9]*Regex</code>
* <code>replacement[0-9]*Mode</code>
* <code>replacement[0-9]*Value</code>
* <code>[gs]et[0-9]*Replacement[0-9]*Value</code>

a replacement always replaces a match of a regular expression.

'''replacement[0-9]*Mode:'''
The way the replacement value is defined can be specified with the replacement mode.
* If the <code>replacement[0-9]*Mode</code> is <code>reading</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of a ''reading'' of the same device or as ''device:reading'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>internal</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of an ''internal'' of the same device or as ''device:internal'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>text</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as a static text
* If the <code>replacement[0-9]*Mode</code> is <code>expression</code>, then the corresponding <code>replacement[0-9]*Value</code> is evaluated as a perl expression to compute the replacement. Inside such a replacement expression it is possible to refer to capture groups of the replacement regex.
* If the <code>replacement[0-9]*Mode</code> is <code>key</code>, then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.

Example:

<syntaxhighlight lang="perl">
attr mydevice getData {"get" :["%%value%%.value"]}
attr mydevice replacement01Mode text
attr mydevice replacement01Regex %%value%%

attr mydevice get01Name Chlor
attr mydevice get01Replacement01Value 34.4008

attr mydevice get02Name Something
attr mydevice get02Replacement01Value 31.4024

attr mydevice get05Name profile
attr mydevice get05URL http://www.mydevice.local/getprofile?password=%%password%%
attr mydevice replacement02Mode key
attr mydevice replacement02Regex %%password%%
attr mydevice get05Replacement02Value password
</syntaxhighlight>

defines that <code>%%value%%</code> will be replaced by a static text.

All Get commands will be HTTP post requests of a similar form. Only the <code>%%value%%</code> will be different from get to get.
The first get will set the reading named Chlor and for the request it will take the generic getData and replace %%value%% with 34.4008.

A second get will look the same except a different name and replacement value.

With the command <code>set storeKeyValue password geheim</code> you can store the password geheim in an obfuscated form in the file system.
To use this password and send it in a request you can use the above replacement with mode key. The value password will then refer to the ofuscated string stored with the key password.

The mode <code>expression</code> allows you to define your own replacement syntax:
<syntaxhighlight lang="perl">
attr mydevice replacement01Mode expression
attr mydevice replacement01Regex {{([^}]+)}}
attr mydevice replacement01Value ReadingsVal("mydevice", $1, "")
attr mydevice getData {"get" :["{{temp}}.value"]}
</syntaxhighlight>

In this example any <code><nowiki>{{name}}</nowiki></code> in a URL, header or post data will be passed on to the perl function ReadingsVal
which uses the string between <code><nowiki>{{}}</nowiki></code> as second parameter. This way one defined replacement can be used for many different
readings.

HTTPMOD has two built in replacements: One for session Ids and another one for the input value in a set command.
The placeholder $sid is always replaced with the internal <code>$hash->{sid}</code> which contains the session id after it is extracted from a previous HTTP response.
If you don't like to use the placeholder $sid then you can define your own replacement for example like:

<syntaxhighlight lang="perl">
attr mydevice replacement01Mode internal
attr mydevice replacement01Regex %session%
attr mydevice replacement01Value sid
</syntaxhighlight>

Now the internal <code>$hash->{sid}</code> will be used as a replacement for the placeholder %session%.

In the same way a value that is passed to a set-command can be put into a request with a user defined replacement.
In this case the internal <code>$hash->{value}</code> will contain the value passed to the set command.
<code>$hash->{value}</code> might even be a string containing several values that could be put into several different positions in a request by using user defined replacements.

'''Other example : steering a pellet stove from Rika'''

The stove API of Rika on https://www.rika-firenet.com/web/ delivers a JSON string with all settings and values, and can be piloted with a data string containing all the "set" values at once.

Delivered JSON on get https://www.rika-firenet.com/api/client/xxxxxxxx/status : (xxxxxxxx must be replaced with the unique stove ID)
<syntaxhighlight lang="perl">
{
"name": "Vorzimmer",
"stoveID": "xxxxxxxxx",
"lastSeenMinutes": 1,
"lastConfirmedRevision": 1504385700,
"controls": {
"revision": 1504385700,
"onOff": true,
"operatingMode": 2,
"heatingPower": 65,
"targetTemperature": 24,
"heatingTimesActive": false,
"heatingTimesActiveForComfort": true,
"setBackTemperature": 18,
"convectionFan1Active": false,
"convectionFan1Level": 0,
"convectionFan1Area": 0,
"convectionFan2Active": false,
"convectionFan2Level": 0,
"convectionFan2Area": 0,
"frostProtectionActive": false,
"frostProtectionTemperature": 5
},
"sensors": {
"statusError": 0,
"statusWarning": 0,
"statusService": 0,
"statusMainState": 1,
"statusSubState": 3,
"statusFrostStarted": false,
"inputFlameTemperature": 21,
"inputRoomTemperature": 21,
"inputExternalRequest": true,
"outputDischargeMotor": 0,
"outputInsertionMotor": 0,
"outputIDFan": 0,
"outputAirFlaps": 0,
"outputIgnition": false,
"parameterStoveTypeNumber": 13,
"parameterVersionMainBoard": 223,
"parameterVersionTFT": 223,
"parameterRuntimePellets": 11,
"parameterRuntimeLogs": 0,
"parameterFeedRateTotal": 17,
"parameterFeedRateService": 683,
"parameterOnOffCycles": 2
},
"stoveType": "DOMO MultiAir",
"stoveFeatures": {
"multiAir1": true,
"multiAir2": true,
"insertionMotor": false,
"airFlaps": false,
"logRuntime": false
}
}
</syntaxhighlight>

Data string to send to https://www.rika-firenet.com/api/client/xxxxxxxx/controls in order to set values:
<syntaxhighlight lang="perl">
heatingTimesActiveForComfort=true&frostProtectionTemperature=3&setBackTemperature=18&targetTemperature=24&convectionFan2Level=0&convectionFan2Active=false&convectionFan1Level=0&onOff=true&convectionFan1Active=false&convectionFan2Area=0&revision=1505550101&heatingTimesActive=false&convectionFan1Area=0&frostProtectionActive=false&operatingMode=2&heatingPower=65
</syntaxhighlight>

Code in 99_myUtils.pm:
<syntaxhighlight lang="perl">
use JSON;
...
sub
replaceJSON ($$) {
my ($valToReplace, $value) = @_;

#$value in the parameters is a default value
#It has to be replaced through the real value nnn passed in the set command "set <device> valToset nnn"
$value = InternalVal("Ofen", "value", $value);
Log3 ("Ofen", 3, "replaceJSON Internalvalue: $value");

#Force an update to avoid outdated revision number
fhem ("get Ofen revision");

#Get all the controls as json
my $json = ReadingsVal("Ofen", "controlsJSON","");
Log3 ("Ofen", 3, "replaceJSON configsJSON: $json");

# When starting FHEM or rereading config, the reading controlsJSON is empty
return if ($json eq "");

my $decoded = decode_json($json);
my $result;
for my $key ( keys %$decoded ) {
$result .= "$key=";
if ($key eq $valToReplace) {
$result .= $value."&";
} else {
$result .= $decoded->{$key}."&";
}
}
chop($result); #remove last &
Log3("Ofen", 3, "replaceJSON Result: $result");
return $result;
}
</syntaxhighlight>

Define stove in fhem:
<syntaxhighlight lang="perl">
defmod Ofen HTTPMOD https://www.rika-firenet.com/api/client/xxxxxxxx/status 60

attr Ofen enableCookies 1
attr Ofen reAuthRegex id="login"|Unauthorized
attr Ofen sid01Data email=xx@xx&password=xx
attr Ofen sid01URL https://www.rika-firenet.com/web/login

attr Ofen reading01JSON sensors_inputRoomTemperature
attr Ofen reading01Name RaumTemp
attr Ofen reading02JSON controls_setBackTemperature
attr Ofen reading02Name Absenkung
attr Ofen reading03JSON controls_frostProtectionTemperature
attr Ofen reading03Name Frostschutz
attr Ofen reading10Name controlsJSON
attr Ofen reading10Regex (?s)controls.*?({.*?})

attr Ofen get09Name revision
attr Ofen get09URL https://www.rika-firenet.com/api/client/xxxxxxxx/status

attr Ofen setURL https://www.rika-firenet.com/api/client/xxxxxxxx/controls
attr Ofen setData {{data}}
attr Ofen replacement01Mode expression
attr Ofen replacement01Regex {{data}}

attr Ofen set11Name frostProtectionTemperature
attr Ofen set11Replacement01Value replaceJSON("frostProtectionTemperature", 2)

attr Ofen set12Name targetTemperature
attr Ofen set12Replacement01Value replaceJSON("targetTemperature", 24)
</syntaxhighlight>

A detailed explanation (in german) of the login process can be found here: [https://forum.fhem.de/index.php/topic,76220.msg682514.html#msg682514]
and the explanation of the other parameters here: [https://forum.fhem.de/index.php/topic,76220.msg685710.html#msg685710]

== replacing reading values when they have not been updated / the device did not respond ==
If a device does not respond then the values stored in readings will keep the same and only their timestamp shows that they are outdated.
If you want to modify reading values that have not been updated for a number of seconds, you can use the attributes

* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAge</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacementMode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacement</code>

Every time the module tries to read from a device, it will also check if readings have not been updated
for longer than the <code>MaxAge</code> attributes allow. If readings are outdated, the <code>MaxAgeReplacementMode</code> defines how the affected
reading values should be replaced. <code>MaxAgeReplacementMode</code> can be <code>text</code>, <code>reading</code>, <code>internal</code>, <code>expression</code> or <code>delete</code>.

<code>MaxAge</code> specifies the number of seconds that a reading should remain untouched before it is replaced.

<code>MaxAgeReplacement</code> contains either a static text that is used as replacement value or a Perl expression that is evaluated to
give the replacement value. This can be used for example to replace a temperature that has not bee updated for more than 5 minutes
with the string "outdated - was 12":
<syntaxhighlight lang="perl">
attr PM readingMaxAge 300
attr PM readingMaxAgeReplacement "outdated - was " . $val
attr PM readingMaxAgeReplacementMode expression
</syntaxhighlight>
The variable <code>$val</code> contains the value of the reading before it became outdated.

Or to show that a device was offline:
<syntaxhighlight lang="perl">
attr MyLight reading01Name color
attr MyLight reading01JSON result_02_color
attr MyLight reading01MaxAge 300
attr MyLight reading01MaxAgeReplacement "offline"
attr MyLight reading01MaxAgeReplacementMode text
</syntaxhighlight>

== Note on determining how to send requests to a special device ==
If you don't know which URLs, headers or POST data your web GUI uses, you might try a local proxy like BurpSuite [http://portswigger.net/burp/ BurpSuite] to track requests and responses. This is a tedious task but probably the best way to achieve a successful result.

Let us consider an example. The Telekom Speedport W724V has a login-site that is famous for being cumbersome. Burp allows to monitor each step in the login procedure. In the case of a speedport the following steps occur:

First burp shows that a get command is issued
##################################################################################################
GET / HTTP/1.1
Host: speedport.ip
Cache-Control: max-age=0
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
Accept-Language: de-DE,de;q=0.8,en-US;q=0.6,en;q=0.4
Cookie: lang=de
Connection: close
In order to mimic the behavior of a real person calling the website HTTPMOD should copy all necessary steps. Host, Cookie and the GET-command are usually necessary. The same cannot be said of the User-Agent because the website can be called from any mobile or desktop computer.

Then, the speedport will answer with a command that consists of several lines. By going through every line for every step in the login procedure one will finally arrive at the information that is necessary to successfully enter the login of the speedport (in case of the W724V, for example, it is necessary to copy a token called _httoken and to include the referer).

== Advanced configuration to define a <code>set</code> command and send data to a device ==

When a set option is defined by attributes, the module will use the value given to the set command and integrate it into an HTTP-Request that sends the value to the device. The definitions for URL, headers and post data can contain the placeholder $val which will be replaced by the value given to the set command.

This can be as simple as:
<syntaxhighlight lang="perl">
# No cyclic requests and no main URL needed in this example
define MyDevice HTTPMOD none 0

attr MyDevice set01Name Licht
attr MyDevice set01URL http://192.168.1.22/switch=$val
</syntaxhighlight>

A user command
<syntaxhighlight lang="perl">
set MyDevice Licht 1
</syntaxhighlight>

will be translated into the http GET request
<syntaxhighlight lang="perl">
http://192.168.1.22/switch=1
</syntaxhighlight>

In this example a map would also be helpful, that translates on / off to 0 or 1 and allows the user to select on/of in fhemweb:
<syntaxhighlight lang="perl">
attr MyDevive set01IMap 0:off, 1:on
</syntaxhighlight>
This also provides input validation to make sure that only on and off can be used with the set command.

In more complex Scenarios you might need to login before sending a command and the Login might create a session id that has to be part of further requests either in the URL, in headers or in the post data.

Extension to the above example for a PoolManager 5 where a set needs a session id in the URL and the values have to be passed in JSON strings as post data:
<syntaxhighlight lang="perl">
attr PM set01Name HeizungSoll
attr PM set01URL http://MyPoolManager/cgi-bin/webgui.fcgi?sid=$sid
attr PM set01Hint 6,10,20,30
attr PM set01Min 6
attr PM set01Max 30
attr PM setHeader1 Content-Type: application/json
attr PM set01Data {"set" :{"34.3118.value" :"$val" }}
</syntaxhighlight>

This example defines a set option with the name HeizungSoll.
By issuing <code>set PM HeizungSoll 10</code> in FHEM, the value 10 will be sent in the defined HTTP
Post to URL <code>http://MyPoolManager/cgi-bin/webgui.fcgi</code> in the Post Data as

<syntaxhighlight lang="html4strict">
{"set" :{"34.3118.value" :"10" }}
</syntaxhighlight>

The optional attributes set01Min and set01Max define input validations that will be checked in the set function.
The optional attribute set01Hint will define a selection list for the FHEMweb GUI.

The HTTP response to such a request will be ignored unless you specify the attribute <code>setParseResponse</code>
for all set commands or <code>set01ParseResponse</code> for the set command with number 01.
If the HTTP response to a set command is parsed then this is done like the parsing of responses to get commands and you can use the attributes ending e.g. on Format, Encode, Decode, OMap and OExpr to manipulate / format the values read.

If a parameter to a set command is not numeric but should be passed on to the device as text, then you can specify the attribute setTextArg. For example:
<syntaxhighlight lang="perl">
attr PM set01TextArg
</syntaxhighlight>

If a set command should not require a parameter at all, then you can specify the attribute NoArg. For example:
<syntaxhighlight lang="perl">
attr PM set03Name On
attr PM set03NoArg
</syntaxhighlight>

== Advanced configuration to create a valid session id that might be necessary ==
In simple cases logging in works with basic authentication. In the case HTTPMOD accepts a username and password as part of the URL in the form
<syntaxhighlight lang="perl">
http://User:Password@192.168.1.18/something
</syntaxhighlight>

However basic auth is seldom used. If you need to fill in a username and password in a HTML form and the session is then managed by a session id, here is how to configure this:

when sending data to an HTTP-Device in a set, HTTPMOD will replace any <code>$sid</code> in the URL, Headers and Post data with the internal <code>$hash->{sid}</code>. To authenticate towards the device and give this internal a value, you can use an optional multi step login procedure defined by the following attributes:

* <code>sid[0-9]*URL</code>
* <code>sid[0-9]*Data.*</code>
* <code>sid[0-9]*Header.*</code>
* <code>sid[0-9]*IgnoreRedirects</code>
* <code>idRegex</code>
* <code>idJSON</code>
* <code>idXPath</code>
* <code>idXPath-Strict</code>
* <code>(get|set|sid)[0-9]*IdRegex</code>
* <code>(get|set|sid)[0-9]*IdJSON</code>
* <code>(get|set|sid)[0-9]*IdXPath</code>
* <code>(get|set|sid)[0-9]*IdXPath-Strict</code>

Each step can have a URL, Headers, Post Data pieces and a Regex to extract a resulting Session ID into <code>$hash->{sid}</code>.
HTTPMOD will create a sorted list of steps (the numbers between sid and URL / Data / Header) and the loop through these steps and send the corresponding requests to the device. For each step a $sid in a Header or Post Data will be replaced with the current content of <code>$hash->{sid}</code>.

Using this feature, HTTPMOD can perform a forms based authentication and send user name, password or other necessary data to the device and save the session id for further requests.

To determine when this login procedure is necessary, HTTPMOD will first try to send a request without
doing the login procedure. If the result contains an error that authentication is necessary, then a login is performed.
To detect such an error in the HTTP response, you can again use a regular expression, JSON or XPath, this time with the attributes

* <code>reAuthRegex</code>
* <code>reAuthJSON</code>
* <code>reAuthXPath</code>
* <code>reAuthXPath-Strict</code>
* <code>(get|set)[0-9]*ReAuthRegex</code>
* <code>(get|set)[0-9]*ReAuthJSON</code>
* <code>(get|set)[0-9]*ReAuthXPath</code>
* <code>(get|set)[0-9]*ReAuthXPath-Strict</code>

reAuthJSON or reAuthXPath typically only extract one piece of data from a response.
If the existence of the specified piece of data is sufficent to start a login procedure, then nothing more needs to be defined to detect this situation.
If however the indicator is a status code that contains different values depending on a successful request and a failed request if a new authentication is needed,
then you can combine things like reAuthJSON with reAuthRegex. In this case the regex is only matched to the data extracted by JSON (or XPath).
This way you can easily extract the status code using JSON parsing and then specify the code that means "authentication needed" as a regular expression.

If for one step not all of the URL, Data or Header Attributes are set, then HTTPMOD tries to use a
<code>sidURL</code>, <code>sidData.*</code> or <code>sidHeader.*</code> Attribute (without the step number after sid). This way parts that are the same for all steps don't need to be defined redundantly.

=== Example for a multi step login procedure: ===
<syntaxhighlight lang="perl">
attr PM reAuthRegex /html/dummy_login.htm
attr PM sidURL http://192.168.70.90/cgi-bin/webgui.fcgi?sid=$sid
attr PM sidHeader1 Content-Type: application/json
attr PM sid1IDRegex wui.init\('([^']+)'
attr PM sid2Data {"set" :{"9.17401.user" :"fhem" ,"9.17401.pass" :"password" }}
attr PM sid3Data {"set" :{"35.5062.value" :"128" }}
attr PM sid4Data {"set" :{"42.8026.code" :"pincode" }}
</syntaxhighlight>

In this case HTTPMOD detects that a login is necessary by looking for the pattern /html/dummy_login.htm in the HTTP response.
If it matches, it starts a login sequence. In the above example all steps request the same URL. In step 1 only the defined Header is sent in an HTTP get request. The response will contain a session id that is extraced with the regex wui.init\('([^']+)'.

In the next step this session id is sent in a post request to the same URL where tha post data contains a username and password. The a third and a fourth request follow that set a value and a code. The result will be a valid and authorized session id that can be used in other requests where $sid is part of a URL, header or post data and will be replaced with the session id extracted above.

In the special case where a session id is set as a HTTP-Cookie (with the header Set-cookie: in the HTTP response) HTTPMOD offers an even simpler way. With the attribute enableCookies a very basic cookie handling mechanism is activated that stores all cookies that the server sends to the HTTPMOD device and puts them back as cookie headers in the following requests.

For such cases no sidIdRegex and no $sid in a user defined header is necessary.

== Advanced configuration to define a <code>get</code> and request additional data with its own request from a device ==

The normal automatic HTTP request that is done repeatedly after the defined interval has elapsed works well in cases where all required readings can be requested in one common HTTP request. If however a device needs individual requests with different URLs or different POST data for each value, then another method is necessary.
For such cases a <code>get</code> option can be defined and the user can either issue FHEM <code>get</code> commands each time he needs the reading or the user can set an attribute to request the reading automatically together with the normal iteration.
For each <code>get</code> option attributes define an individual URL, optional headers, and post data as well as individual regular expressions and formatting options.

When a get option is defined by attributes, the module allows querying additional values from the device that require individual HTTP-Requests or special parameters to be sent

Extension to the above example:

<syntaxhighlight lang="perl">
attr PM get01Name MyGetValue <br>
attr PM get01URL http://MyPoolManager/cgi-bin/directory/webgui.fcgi?special=1?sid=$sid <br>
attr PM getHeader1 Content-Type: application/json <br>
attr PM get01Data {"get" :{"30.1234.value"}} <br>
</syntaxhighlight>

This example defines a get option with the name MyGetValue.
By issuing <code>get PM MyGetValue</code> in FHEM, the defined HTTP request is sent to the device.
The HTTP response is then parsed using the same readingXXName and readingXXRegex attributes as above so
additional pairs will probably be needed there for additional values.

if you prefer to define the parsing and formatting of readings individually per get command, you can use
attributes like get01Regex, get01XPath, get01Format, get01OMap and so on just like for reading01...

You can also include parameters / values that are passed to the get command in the request just like for set commands.
The placeholder $val will be replaced with the value given to the get command or you can specify your own replacement as described above.

If the new get parameter should also be queried regularly, you can define the following optional attributes:

<syntaxhighlight lang="perl">
attr PM get01Poll 1
attr PM get01PollDelay 300
</syntaxhighlight>

The first attribute includes this reading in the automatic update cycle and the second defines an alternative lower update frequency. When the interval defined initially in the define is over and the normal readings are read from the device, the update function will check for additional get parameters that should be included in the update cycle.

If a PollDelay is specified for a get parameter, the update function also checks if the time passed since it has last read this value is more than the given PollDelay. If not, this reading is skipped and it will be rechecked in the next cycle when interval is over again. So the effective PollDelay will always be a multiple of the interval specified in the initial define.

Please note that each defined get command that is included in the regular update cycle will create its own HTTP request. So if you want to extract several values from the same request, it is much more efficient to do this by defining readingXXName and readingXXRegex, XPath or JSON attributes and to specify an interval and a URL in the define of the HTTPMOD device.

Example for a Siemens webserver provided by Lanhydrock:
<syntaxhighlight lang="perl">
define ozw672 HTTPMOD https://192.168.178.8/api/auth/login.json?user=test&pwd=test 300

attr ozw672 get1Name tempAussen
attr ozw672 get1URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1960
attr ozw672 get1Poll 1
attr ozw672 get1PollDelay 1800

attr ozw672 get2Name tempAussenGemischt
attr ozw672 get2URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1964
attr ozw672 get2Poll 1
attr ozw672 get2PollDelay 1800

attr ozw672 get3Name tempTWW
attr ozw672 get3URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1996
attr ozw672 get3Poll 1

attr ozw672 get4Name tempKesselSoll
attr ozw672 get4URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1910
attr ozw672 get4Poll 1

attr ozw672 get5Name tempKesselRuecklauf
attr ozw672 get5URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1915
attr ozw672 get5Poll 1

attr ozw672 get6Name tempKesselRuecklaufSoll
attr ozw672 get6URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1916
attr ozw672 get6Poll 1

attr ozw672 get7Name anzahlStartsBrenner
attr ozw672 get7URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1927
attr ozw672 get7PollDelay 1800
attr ozw672 get7Poll 1

attr ozw672 get8Name statusKessel
attr ozw672 get8URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1898
attr ozw672 get8Poll 1
attr ozw672 get8Regex Value": "([a-zA-Zü ]*)"
attr ozw672 get8OMap Aus:0, Nachlauf aktiv:5, Freigegeben für TWW:10, Freigegeben für HK:20, In Teillastbetrieb für TWW:40, In Teillastbetrieb für HK:50, In Betrieb für Trinkwasser:90, In Betrieb für Heizkreis:100

attr ozw672 getRegex Value": "[ ]*([-.0-9]*)"

attr ozw672 reAuthRegex .*session not valid.*
attr ozw672 sid1IDRegex .*"(.*-.*-.*-[0-9a-z]*).*
attr ozw672 sid1URL https://192.168.178.8/api/auth/login.json?user=test&pwd=test
</syntaxhighlight>

== All attributes ==
;reading[0-9]+Name
:the name of a reading to extract with the corresponding readingRegex, readingJSON, readingXPath or readingXPath-Strict
:Please note that the old syntax <b>readingsName.*</b> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.

;(get|set)[0-9]+Name
:Name of a get or set command
:If the HTTP response that is received after the command is parsed with an individual parse option then this name is also used as a reading name. Please note that no individual parsing needs to be defined for a get or set. If no regex, XPath or JSON is specified for the command, then HTTPMOD will try to parse the response using all the defined readingRegex, reading XPath or readingJSON attributes.

;(get|set|reading)[0-9]+Regex
:If this attribute is specified, the Regex defined here is used to extract the value from the HTTP Response and assign it to a Reading with the name defined in the (get|set|reading)[0-9]+Name attribute.
:If this attribute is not specified for an individual Reading or get or set but without the numbers in the middle, e.g. as getRegex or readingRegex, then it applies to all the other readings / get / set commands where no specific Regex is defined.<br>
:The value to extract should be in a capture group / sub expression e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)
:Using this attribute for a set command (setXXRegex) only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
:Please note that the old syntax <code>readingsRegex.*</code> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.
:If for get or set commands neither a generic Regex attribute without numbers nor a specific (get|set)[0-9]+Regex attribute is specified and also no XPath or JSON parsing specification is given for the get or set command, then HTTPMOD tries to use the parsing definitions for general readings defined in reading[0-9]+Name, reading[0-9]+Regex or XPath or JSON attributes and assigns the Readings that match here.

;(get|set|reading)[0-9]+RegOpt
:Lets the user specify regular expression modifiers. For example if the same regular expression should be matched as often as possible in the HTTP response, then you can specify RegOpt g which will case the matching to be done as /regex/g
:The results will be trated the same way as multiple capture groups so the reading name will be extended with -number.
:For other possible regular expression modifiers see http://perldoc.perl.org/perlre.html#Modifiers

;(get|set|reading)[0-9]+XPath
:defines an xpath to one or more values when parsing HTML data (see examples above)
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;get|set|reading[0-9]+XPath-Strict
:defines an xpath to one or more values when parsing XML data (see examples above)
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]+AutoNumLen
:In cases where a regular expression or an XPath results in multiple results and these results are stored in a common reading name with extension -number, then you can modify the format of this number to have a fixed length with leading zeros. AutoNumLen 3 for example will lead to reading names ending with -001 -002 and so on.

;(get|set|reading)[0-9]+AlwaysNum
:if set to 1 this attributes forces reading names to end with a -1, -01 (depending on the above described AutoNumLen) even if just one value is parsed.

;get|set|reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names. See the above example.
:If you don't know the paths, then start by using extractAllJSON and the use the names of the readings as values for the JSON attribute.<br>
:Please don't forget to also specify a name for a reading, get or set.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]*RecombineExpr
:defines an expression that is used in an eval to compute one reading value out of the list of matches.
:This is supposed to be used for regexes or xpath specifications that produce multiple results if only one result that combines them is wanted. The list of matches will be in the variable @matchlist.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;get[0-9]*CheckAllReadings
:this attribute modifies the behavior of HTTPMOD when the HTTP Response of a get command is parsed. <br>
:If this attribute is set to 1, then additionally to the matching of the corresponding get specific regex (get[0-9]*Regex), XPath or JSON attribute also all the reading names and parse definitions defined in Reading[0-9]+Name and Reading[0-9]+Regex, XPath or JSON attributes are checked and if they match, the coresponding Readings are assigned as well.
:Please note that this does not mean that get01CheckAllReadings will cause a get02Regex to be used. Only the corresponding get01Regex will be used but additionally all the readingXYRegex attributes.
:This is automatically done if a get or set command is defined without its own parse attributes.

;(get|reading)[0-9]*OExpr
:defines an optional expression that is used in an eval to compute / format a readings value after parsing an HTTP response
:The raw value from the parsing will be in the variable $val.
:If specified as readingOExpr then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Expr.
:Please note that the old syntax <b>readingsExpr.*</b> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.

;(get|reading)[0-9]*Expr
:This is the old syntax for (get|reading)[0-9]*OExpr. It should be replaced by (get|reading)[0-9]*OExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;(get|reading)[0-9]*OMap
:Map that defines a mapping from raw value parsed to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".
:If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Map.<br>
:The individual options in a map are separated by a komma and an optional space. Spaces are allowed to appear in a visible value however kommas are not possible.

;(get|reading)[0-9]*Map
:This is the old syntax for (get|reading)[0-9]*OMap. It should be replaced by (get|reading)[0-9]*OMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;(get|set|reading)[0-9]*Format
:Defines a format string that will be used in sprintf to format a reading value.
:If specified without the numbers in the middle e.g. as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.<br>

;(get|set|reading)[0-9]*Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading.
:This can be used if the device delivers strings in an encoding like cp850 instead of utf8.
:If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]*Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading.
:This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.
:If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set)[0-9]*URL
:URL to be requested for the set or get command. If this option is missing, the URL specified during define will be used.

;(get|set)[0-9]*Data
:Data to be sent to the device as POST data when the get or set command is executed. if this attribute is not specified, an HTTP GET method will be used instead of an HTTP POST

;(get|set)[0-9]*NoData
:can be used to override a more generic attribute that specifies POST data for all get or set commands. With NoData no data is sent and therefor the request will be an HTTP GET.

;(get|set)[0-9]*Header.*
:HTTP Headers to be sent to the device when the set is executed

;requestHeader.*
:Define an optional additional HTTP Header to set in the HTTP request of the main loop

;requestData
:optional POST Data to be sent in the request of the main loop. If not defined, it will be an HTTP GET request as defined in HttpUtils which is used by this module

;get[0-9]+Poll
:if set to 1 the get is executed automatically during the normal update cycle (after the interval provided in the define command has elapsed)

;get[0-9]+PollDelay
:if the value should not be read in each iteration (after the interval given to the define command), then a minimum delay can be specified with this attribute. This has only an effect if the above Poll attribute has also been set. Every time the update function is called, it checks if since this get has been read the last time, the defined delay has elapsed. If not, then it is skipped this time.
:PollDelay can be specified as seconds or as x[0-9]+ which means a multiple of the interval in the define command.

;(get|set)[0-9]*TextArg
:For a get command this defines that the command accepts a text value after the option name. By default a get command doesn't accept optional values after the command name.
:If TextArg is specified and a value is passed after the get name then this value can then be used in a request URL, header or data as replacement for $val or in a user defined replacement that uses the internal "value" ($hash->{value}).
:If used for a set command then it defines that the value to be set doesn't require any validation / conversion.
:The raw value is passed on as text to the device. By default a set command expects a numerical value or a text value that is converted to a numeric value using a map.

;set[0-9]+Min
:Minimum value for input validation.

;set[0-9]+Max
:Maximum value for input validation.

;set[0-9]+IExpr
:Perl Expression to compute the raw value to be sent to the device from the input value passed to the set.

;set[0-9]+Expr
:This is the old syntax for (get|reading)[0-9]*IExpr. It should be replaced by (get|reading)[0-9]*IExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;set[0-9]+IMap
:Map that defines a mapping from raw to input values like "0:mittig, 1:oberhalb, 2:unterhalb". This attribute atomatically creates a hint for FHEMWEB so the user can choose one of the input values.

;set[0-9]+Map
:This is the old syntax for (get|reading)[0-9]*IMap. It should be replaced by (get|reading)[0-9]*IMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;set[0-9]+Hint
:Explicit hint for fhemWEB that will be returned when set ? is seen. Can be used to get a slider or a list of values to choose from.

;set[0-9]*NoArg
:Defines that this set option doesn't require arguments. It allows sets like "on" or "off" without further values.

;set[0-9]*ParseResponse
:defines that the HTTP response to the set will be parsed as if it was the response to a get command.

;(get|set)[0-9]*URLExpr
:Defines a Perl expression to specify the HTTP Headers for this request. This overwrites any other header specification and should be used carefully only if needed. The original Header is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;(get|set)[0-9]*DatExpr
:Defines a Perl expression to specify the HTTP Post data for this request. This overwrites any other post data specification and should be used carefully only if needed. The original Data is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;(get|set)[0-9]*HdrExpr
:Defines a Perl expression to specify the URL for this request. This overwrites any other URL specification and should be used carefully only if needed. The original URL is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;ReAuthRegex
:regular Expression to match an error page indicating that a session has expired and a new authentication for read access needs to be done.
:This attribute only makes sense if you need a forms based authentication for reading data and if you specify a multi step login procedure based on the sid.. attributes.
:This attribute is used for all requests. For set and get operations you can however specify individual reAuthRegexes with the (get|set)[0-9]*ReAuthRegex attributes.

;(get|set)[0-9]*ReAuthRegex
:Regex that will detect when a session has expired during a set operation and a new login needs to be performed.
:It works like the global reAuthRegex but is used for set operations.

;sid[0-9]*URL
:different URLs or one common URL to be used for each step of an optional login procedure.

;sid[0-9]*IDRegex
:different Regexes per login procedure step or one common Regex for all steps to extract the session ID from the HTTP response

;sid[0-9]*Data.*
:data part for each step to be sent as POST data to the corresponding URL

;sid[0-9]*Header.*
:HTTP Headers to be sent to the URL for the corresponding step

;sid[0-9]*IgnoreRedirects
:Tells the HttpUtils to not follow HTTP Redirects for this Request. Might be needed for some devices that set a session cookie within a 303 Redirect.

;clearSIdBeforeAuth
:will set the session id to "" before doing the authentication steps

;authRetries
:number of retries for authentication procedure - defaults to 1

;replacement[0-9]*Regex
:Defines a replacement to be applied to an HTTP request header, data or URL before it is sent. This allows any part of the request to be modified based on a reading, an internal or an expression.
:The regex defines which part of a header, data or URL should be replaced. The replacement is defined with the following attributes:

;replacement[0-9]*Mode
:Defines how the replacement should be done and what replacementValue means. Valid options are text, reading, internal and expression.

;replacement[0-9]*Value
:Defines the replacement. If the corresponding replacementMode is <code>text</code>, then value is a static text that is used as the replacement.
:If replacementMode is <code>reading</code> then Value can be the name of a reading of this device or it can be a reading of a different device referred to by devicename:reading.
:If replacementMode is <code>internal</code> the Value can be the name of an internal of this device or it can be an internal of a different device referred to by devicename:internal.
:If replacementMode is <code>expression</code> the the Value is treated as a Perl expression that computes the replacement value. The expression can use $1, $2 and so on to refer to capture groups of the corresponding regex that is matched against the original URL, header or post data.
:If replacementMode is <code>key</code> then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.

;[gs]et[0-9]*Replacement[0-9]*Value
:This attribute can be used to override the replacement value for a specific get or set.

;get|reading[0-9]*MaxAge
:Defines how long a reading is valid before it is automatically overwritten with a replacement when the read function is called the next time.

;get|reading[0-9]*MaxAgeReplacement
:specifies the replacement for MaxAge - either as a static text or as a perl expression.

;get|reading[0-9]*MaxAgeReplacementMode
:specifies how the replacement is interpreted: can be text, expression and delete.

;get|reading[0-9]*DeleteIfUnmatched
:If set to 1 this attribute causes certain readings to be deleted when the parsing of the website does not match the specified reading. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation does not parse this reading again. This is especially useful for parsing that creates several matches / readings and the number of matches can vary from request to request. For example if reading01Regex creates 4 readings in one update cycle and in the next cycle it only matches two times then the readings containing the remaining values from the last round will be deleted.
:Please note that this mechanism will not work in all cases after a restart. Especially when a get definition does not contain its own parsing definition but ExtractAllJSON or relies on HTTPMOD to use all defined reading.* attributes to parse the responsee to a get command, old readings might not be deleted after a restart of fhem.
;get|reading[0-9]*DeleteOnError
:If set to 1 this attribute causes certain readings to be deleted when the website can not be reached and the HTTP request returns an error. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation returns an error.
The same restrictions as for DeleteIfUnmatched apply regarding a fhem restart.

;httpVersion
:defines the HTTP-Version to be sent to the server. This defaults to 1.0.

;sslVersion
:defines the SSL Version for the negotiation with the server. The attribute is evaluated by HttpUtils. If it is not specified, HttpUtils assumes SSLv23:!SSLv3:!SSLv2

;sslArgs
:defines a list that is converted to a key / value hash and gets passed to HttpUtils. To avoid certificate validation for broken servers you can for example specify
:<code>attr myDevice sslArgs SSL_verify_mode,SSL_VERIFY_NONE</code>

;alignTime
:Aligns each periodic read request for the defined interval to this base time. This is typcally something like 00:00 (see the FHEM at command)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;enableControlSet
:enables the built in set commands interval, stop, start, reread, upgradeAttributes, storeKeyValue.

;enableCookies
:enables the built in cookie handling if set to 1. With cookie handling each HTTPMOD device will remember cookies that the server sets and send them back to the server in the following requests.
:This simplifies session magamenet in cases where the server uses a session ID in a cookie. In such cases enabling cookies should be sufficient and no sidRegex and no manual definition of a cookie header should be necessary.

;showMatched
:if set to 1 then HTTPMOD will create a reading with the name MATCHED_READINGS that contains the names of all readings that could be matched in the last request as well as UNMATCHED_READINGS and LAST_REQUEST.

;showError
:if set to 1 then HTTPMOD will create a reading and event with the Name LAST_ERROR that contains the error message of the last error returned from HttpUtils.

;removeBuf
:if set to 1 then HTTPMOD removes the internal named buf when a HTTP-response has been received.
:$hash->{buf} is used internally be Fhem httpUtils and in some use cases it is desireable to remove this internal after reception
:because it contains a very long response which looks ugly in Fhemweb.

;timeout
:time in seconds to wait for an answer. Default value is 2

;queueDelay
:HTTP Requests will be sent from a queue in order to avoid blocking when several Requests have to be sent in sequence. This attribute defines the delay between calls to the function that handles the send queue. It defaults to one second.

;queueMax
:Defines the maximum size of the send queue. If it is reached then further HTTP Requests will be dropped and not be added to the queue

;minSendDelay
:Defines the minimum time between two HTTP Requests.

== Links ==
* Beispiel: [[Wetter_und_Wettervorhersagen#Wetter_von_Weather_Underground|Wetter von WeatherUnderground auslesen]]
* Beispiel: [[Pollenflug]]
* Beispiel: [[HTTPMOD Beispielkonfiguration zur Anbindung einer Daikin Klimaanlage mit WLAN-Modul]]
* Beispiel: [[Go-eCharger|Auslesen der Information der Wallbox go-eCharger]]
* {{Link2Forum|Topic=17804|LinkText=Thread}} in FHEM Forum that discusses the first version of this module
* {{Link2Forum|Topic=29471|LinkText=Thread}} in FHEM Forum that discusses the second major version of this module
* {{Link2Forum|Topic=45176|LinkText=Thread}} in FHEM Forum that discusses the third major version of this module
* [http://perldoc.perl.org/perlretut.html Introduction to regular expressions]
* [http://portswigger.net/burp/ BurpSuite]: Tool (local proxy) to help analyze http traffic

[[Kategorie:IP Components]]

Leere Seite 2

2018-09-12T20:16:13Z

C2j2: Erfassung der Werte des go-eChargers, einer Wallbox für Elektroautos

== Hinweise zur schnellen Einbindung von go-eCharger (https://go-e.co/de/) per HTTP-Protokoll ==

Voraussetzung ist, dass die HTTP-API aktiviert ist:
* Smartphone mit e-goCharger WLAN verbinden
* in "Cloud", "erweiterte Einstellungen" das HTTP-Protokoll aktivieren
* "Neustart" auswählen (ohne diesen war bei mir die Box nicht zu erreichen)
* fertig, Smartphone kann wieder ins normale WLAN

Dann in FHEM:
<pre>
define go_eCharger HTTPMOD http://go-eCharger/status 30
attr go_eCharger extractAllJSON 1
attr go_eCharger stateFormat {sprintf("%s: %s Current %d A, ETO=%d kWh",\
ReadingsVal($name,"car",0)==1?"ready, waiting for car":\
ReadingsVal($name,"car",0)==2?"car loading":\
ReadingsVal($name,"car",0)==3?"waiting for car":\
ReadingsVal($name,"car",0)==4?"charge finished, but connected":"unknown",\
ReadingsVal($name,"err",0)==1?"error RCCB: ":\
ReadingsVal($name,"err",0)==3?"error PHASE: ":\
ReadingsVal($name,"err",0)==8?"error NO_GROUND: ":\
ReadingsVal($name,"err",0)==10?"error INTERNAL: ":"",\
ReadingsVal($name,"amp",0),\
ReadingsVal($name,"eto",0)/10,\
""\
)}
</pre>

Das dürfte so das Wichtigste sein, um die Werte auszulesen.

FRITZBOX

2016-12-25T21:13:46Z

C2j2: /* Bekannte Probleme / Fehlersuche */: Ergänzung zur Fehlermeldung "Old SID not valid anymore"

{{Infobox Modul
|ModPurpose=Steuerung einer Fritz!Box über Fhem
|ModType=d
|ModForumArea=FRITZ!Box
|ModTechName=72_FRITZBOX.pm
|ModOwner=tupol/Topos ({{Link2FU|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 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 die Fritzbox nicht unter <nowiki>http://fritz.box</nowiki> erreichbar ist, IP im define setzen:
:<code>define FritzBox FRITZBOX 192.168.168.168</code>
192.168.168.168 dabei natürlich durch die passende IP ersetzen... Alternativ kann statt der IP auch der Hostname eingegeben werden.

Wenn ('''und nur 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>
In der Fritzbox muss dann auch "Anmeldung mit FRITZ!Box-Benutzernamen und Kennwort" ausgewählt sein.

Passwort konfigurieren:
:<code>set FritzBox password ''Passwort''</code> - 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.):
:<code>attr FritzBox allowTR064Command 1</code>

==== 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. Diese wird jedoch nur sehr sporadisch gepflegt.<br>
Ein besserer Einstiegspunkt befindet sich auf der Box unter http://fritz.box:49000/tr64desc.xml.<br>
Die möglichen TR-064-Aktionen kann man auch über den Befehl <code>get <device> tr064ServiceList</code> auslesen.

Folgende Service und Controls existieren (für den get-Befehl ''tr064Command'' 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 {{Link2Forum|Topic=29725|Message=318113|LinkText=hier}} 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 Beispiele ===
*Box Reboot: <code>get <device> tr064Command DeviceConfig:1 deviceconfig Reboot</code>
*Internet Reconnect: <code>get <device> tr064Command WANIPConnection:1 wanipconnection1 ForceTermination</code>
*Daten eines Smart-Home-Gerätes auslesen: <code>get <device> tr064Command X_AVM-DE_Homeauto:1 x_homeauto GetGenericDeviceInfos NewIndex 0</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 {{Link2Forum|Topic=38586|LinkText=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 {{Link2Forum|Topic=39433|LinkText=Forenthread}} zur Anwesenheitserkennung und in [http://heinz-otto.blogspot.de/2015/07/die-zeiten-andern-sich.html diesem Blogpost]. Auf dieser Basis könnte eine einfache Implementierung zum Beispiel so aussehen:

Funktion in [[99_myUtils anlegen|99_myUtils]]:

<source lang='perl'>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
}
</source>

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.

=== Anwesenheitserkennung über mehrere Fritzboxen oder AVM Repeater und Fritzbox ===
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.

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. Die folgende Routine kann aber universell eingesetzt werden, unabhängig von der Anzahl der FRITZBOX Instanzen. Wer mitloggen will, kann das analog zur obigen Routine einbauen

<source lang='perl'>sub checkAllFritzMACpresent($) {
# Benötigt: nur die zu suchende MAC ($MAC),
# Es werden alle Instanzen vom Type FRITZBOX abgefragt
#
# Rückgabe: 1 = Gerät gefunden
# 0 = Gerät nicht gefunden
my ($MAC) = @_;
# Wird in keiner Instanz die MAC Adresse gefunden bleibt der Status 0
my $Status = 0;
$MAC =~ tr/:/_/;
$MAC = "mac_".uc($MAC);
my @FBS = devspec2array("TYPE=FRITZBOX");
foreach( @FBS ) {
my $StatusFritz = ReadingsVal($_, $MAC, "weg");
if ($StatusFritz eq "weg") {
} elsif ($StatusFritz eq "inactive") {
} else {
# Reading existiert, Rückgabewert ist nicht "inactive", also ist das Gerät am Netzwerk angemeldet.
$Status = 1;
}
}
return $Status
}
</source>

Da hiermit nach allen Instanzen mit dem TYPE=FRITZBOX durchsucht wird, braucht der Name der Fritzbox nicht angegeben werden.

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

Weitere Hinweise zu komplexeren Abfragen mehrere Boxen auf einmal etc. findet ihr auch im diesem {{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:

<source lang="perl">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");
}
}</source>

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":
<source lang="perl">
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");
}
}
</source>
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
<pre>
attr <device> userReadings <userReadingName> {my $resp=fhem("get <device> tr064Command <service> <control> <action> [[<argName1> <argValue1>] ...]",1);;$resp =~/\'<VariabelName>\' => '(.*)'/;;return $1;;}
</pre>
Beispielsweise
<pre>attr Fritzbox userReadings urMobilteil_1 {my $resp=fhem("get Fritzbox tr064Command X_AVM-DE_OnTel:1 x_contact GetDECTHandsetInfo NewDectID 1",1);;$resp =~/'NewHandsetName' => '(.*)'/;;return $1;;},
urDownstreamDSLRate {my $resp=fhem("get Fritzbox tr064Command WANDSLInterfaceConfig:1 wandslifconfig1 GetInfo",1);;$resp =~/'NewDownstreamCurrRate' => '(.*)'/;;return $1;;},
urUpstreamDSLRate {my $resp=fhem("get Fritzbox tr064Command WANDSLInterfaceConfig:1 wandslifconfig1 GetInfo",1);;$resp =~/'NewUpstreamCurrRate' => '(.*)'/;;return $1;;}</pre>

=== 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 und auch keine Sprachnachricht über ein Fritz!Fon ausgegeben 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 ungewolltem Verstellen von Werten in der Fritzbox kommen.

Bei Verwendung der ring-Parameter "play:" und "say:" wird die abzuspielende URL in die M3U-Datei, die unter dem Internal ''M3U_LOCAL'' steht, eingetragen.<br>
Standardmäßig wird versucht, diese Datei im image-Verzeichnis von FHEM abzulegen. Diese kann dann vom Fritz!Fon über [[FHEMWEB]] abgespielt werden (IP-Freigaben beachten). Direkt nach dem ersten Anlegen der m3u-Datei kennt [[FHEMWEB]] diese noch nicht, daher bitte entweder ''set <webdevice> rereadicons'' ausführen oder FHEM neu starten.<br>

Aufgrund der Beschränkungen von [[FHEMWEB]] oder auch bei Authentifizierungsanforderungen ist es empfehlenswert, die Datei über das Attribute ''m3uFileLocal'' selber vorzugeben. Am besten auf einem Webserver, der auf dem FHEM-Server läuft und dessen Seiten-Verzeichnis durch FHEM beschreibbar ist.<br>
Beispiel: <code>attr Fritzbox m3uFileLocal /var/www/mp3/Fritzbox.m3u</code>

In dem Radioeintrag ''FHEM'' muss dann '''auf der FritzBox''', die '''Web'''-Adresse der entsprechenden Datei eingetragen werden. Dieser Sender sollte zu Testzwecken dann auch einmal am Fritz!Fon von Hand gestartet werden.<br>
Das Modul versucht, beim Start die einzutragende Radio-URL im image-Verzeichnis selber zu ermitteln (IP-Freigabe beachten). Gelingt dies, so steht diese im Internal ''M3U_URL''.

=== Ring auf mehreren Telefonen gleichzeitig ===

Damit mehrere Telefone per ring gleichzeitig Klingel, muss in der Fritzbox eine Rufgruppe definiert werden.
Sollte eine Türsprechanlage schon in Benutzung sein, kann die eventuell hierfür bereits eingerichtete Gruppe verwendet werden.
Das anlegen der Gruppe erfolgt wie in folgender AVM Anleitung erledigt werden. [http://http://avm.de/service/fritzbox/fritzbox-7390/wissensdatenbank/publication/show/1148_Interne-Rufgruppe-in-FRITZ-Box-einrichten-Gruppenruf/ AVM Interne Rufgruppe anlegen]

Es muss eine Kurzwahl bei der Gruppe zwingend hinterlegt sein.
Danach kann mit folgendem Beispiel Code gearbeitet werden:

<code>set FritzBox ring 791 15 show:Türklingel</code>

Name des Devices, Rufgruppen Nummer, Länge und gezeigter Text auf das gewünschte anpassen.

== Bekannte Probleme / Fehlersuche ==
=== 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 [[FHEM_Command_Beispiele#rereadcfg|rereadcfg]]. Dieser verträgt sich nicht mit dem Modul "blocking.pm", das für parallel laufende FHEM-Prozesse genutzt wird.

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

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

Alternativ kann das Ausschalten des WLANs nicht direkt über TR064-Kommandos, sondern über einen indirekten Weg erfolgen: über TR064 ein set call abzusetzen und hier den Tastencode zum Ausschalten des WLANs einzugeben, bei einer FritzBox 7490 wäre dies z. B. #96*0*.
Schaltet man über diese Methode das WLAN aus, kann es über die Nachtschaltung wieder automatisch auf beiden Frequenzen angeschaltet werden.

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

=== Wenn's nicht klingelt ===
Das Klingeln erfolgt über die Wählhilfe. Eventuell muss über die Weboberfläche der Fritz!Box ein anderer Port eingestellt werden. Der aktuelle steht in "box_stdDialPort".

=== TR064-Transport-Error: 500 Can't connect to ...:49443 (certificate verify failed) ===
Eventuell hilft es, die Perl Module Net::HTTPS, Net::SSL und IO::Socket::SSL zu aktualisieren.

=== "Error: Old SID not valid anymore." nach Erlauben von IPv6 auf der Fritzbox ===
Ohne hier den genauen Grund zu kennen - helfen tut die Angabe der IPv4-Adresse, also statt <code>define FritzBox FRITZBOX</code> dann <code>define FritzBox FRITZBOX <IP></code> (z.B. <code>define FritzBox FRITZBOX 192.168.10.1</code>), so dass das Modul nicht über IPv6 geht.

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

[[Kategorie:FritzBox]]

RFXtrx

2016-12-01T17:32:18Z

C2j2: /* Decodierung der Steckdosen-Zuordnung */

Fhem unterstützt viele durch einen '''RFXtrx'''433 Transceiver erreichbare Geräte durch eigene Module.

== Übersicht ==
[[File:Rfxtrx433.png|500px|right]]

RFXtrx433 ist ein Transceiver (Funkempfänger und Funksender) mit USB-Anschluss für den Frenzbereich 433,92 MHz. Die Stromversorgung erfolgt über USB. Das Gerät hat einen FTDI-FT232R-USB-Interface-Chip installiert. Um RFXtrx433 nutzen zu können, muss das Betriebssystem einen entsprechenden Treiber für diesen Chip haben. Genutzt wird RFXtrx433 von Anwendern mit FHEM unter Linux, Fritzbox 7390 oder Windows.

Mit der mitgelieferten Firmware können viele Funksensoren in diesem Frequenzbereich empfangen werden und es ist möglich bestimmte Protokolle auch zu senden. Die unterstützten Protokolle sind von der installierten Firmware abhängig, die über das Windows-Programm [http://www.rfxcom.com/Downloads RFXflash] aktualisiert werden kann. Die neueste Firmware ist unter [http://www.rfxcom.com/Downloads http://www.rfxcom.com/Downloads] zu finden.

Weitere Informationen zu den von diesem Transceiver verfügbaren Protokolle beim Hersteller unter [http://www.rfxcom.com www.rfxcom.com]. Da der Hersteller die Anzahl der Geräte ständig aktualisiert und die FHEM-Treiber in der Freizeit des Autors geschrieben werden, sind in den FHEM-Treibern nur eine Untermenge implementiert. Sollte ein Gerät/Protokoll fehlen, das die Firma RFXCOM unterstützt, können Sie im [http://forum.fhem.de/ FHEM-Forum] in der Untergruppe RFXTRX nachfragen, ob dieses implementiert werden kann.

TRXtrx433 wird derzeit von FHEM mit den Modulen TRX, TRX_LIGHT, TRX-SECURITY und TRX_WEATHER für eine Reihe von Protokollen unterstützt.

Nachfolgend werden nur Geräte aufgezeigt, die bei der Erstellung dieses WIKI-Eintrages eingepflegt werden.

== FHEM-Modul: TRX_WEATHER ==
Dieses Modul unterstützt Wettersensoren, insbesondere Sensoren des Herstellers Oregon-Scientific. Unter [http://www.rfxcom.com/oregon.htm Wetter-Sensoren] finden Sie eine Liste der von der RFXtrx433-Firmware unterstützten Wetter-Sensoren (Oregon-Scientific, Cresta, La Crosse, TFA, UPM, ...). Das FHEM-Modul TRX_WEATHER implementiert derzeit den Empfang folgender Sensorentypen und Sensoren:

- '''Temperatursensoren''':

* "THR128": Oregon-Scientific THR128/138, THC138
* "THGR132N": Oregon-Scientific THC238/268,THN132,THWR288,THRN122,THN122,AW129/131
* "THWR800": Oregon-Scientific THWR800
* "RTHN318": Oregon-Scientific RTHN318
* "TS15C": TS15C
* "VIKING_02811" : Viking 02811
* "WS2300" : La Crosse WS2300
* "RUBICSON" : RUBiCSON
* "TFA_303133" : TFA 30.3133

- '''Temperatur-/Luftffeuchtigkeitssensoren''':

* "THGR228N": Oregon-Scientific THGN122/123, THGN132, THGR122/228/238/268 [[File:Thgr228n.png|92px|right|thumb|THGR228N]]
* "THGR810": Oregon-Scientific THGR810
* "RTGR328": Oregon-Scientific RTGR328
* "THGR328": Oregon-Scientific THGR328
* "WTGR800_T": Oregon-Scientific WTGR800
* "THGR918": Oregon-Scientific THGR918, THGRN228, THGN500
* "TFATS34C": TFA TS34C (Kat. Nr. 30.3150)
* "WT450H": UPM WT450H
* "TX3_T": LaCrosse TX3, TX4, TX17
[[File:TX3TH.jpg|92px|right|thumb|TX3TH]]

* '''Nicht unterstützt werden von der RFXCOM-Firmware:''' TFA 30.3166

- '''Temperatur-/Luftffeuchtigkeits-/Luftdrucksensoren''':

* "BTHR918": Oregon-Scientific BTHR918
* "BTHR918N": Oregon-Scientific/Huger BTHR918N, BTHR968 [[File:Bthr918n.png|96px|right|thumb|BTHR918N]]

- '''Regensensoren''':

* "RGR918": Oregon-Scientific RGR126/682/918
* "PCR800": Oregon-Scientific PCR800
* "TFA_RAIN": TFA-Regensensor (Kat. Nr. 30.3148)
* "RG700": UPM RG700

- '''Windsensoren''':

* "WTGR800_A": Oregon-Scientific WTGR800
* "WGR800_A": Oregon-Scientific WGR800
* "WGR918": Oregon-Scientific STR918, WGR918
* "TFA_WIND": TFA-Windsensor (Kat. Nr. 30.3149)
* "WDS500" : UPM WDS500

- '''UV-Sensoren''':

* "UVN128": Oregon UVN128, UV138
* "UVN800": Oregon UVN800
* "TFA_UV": TFA_UV-Sensor

- '''Waagen''':

* "BWR101": Oregon Scientific BWR101
* "GR101": Oregon Scientific GR101

- '''Energiesensoren''':

* "CM160": OWL CM119 und CM160
* "CM180": OWL CM180

Der Autor des Module setzt derzeit folgende Sensoren ein:

* Oregon Scientific: BTHR918, BTHR918N, PCR800, RGR918, THGR228N, THR128, THWR288A, WTGR800, WGR918

Von Nutzern wurde die Funktion folgender weiterer Sensoren gemeldet:

* Oregon Scientific GR101
* Oregon Scientific RTGR-328 (T/H)
* Honeywell TF-ATS34C (T/H)
* TFA Regensender 433 MHz, Kat. Nr. 30.3148, siehe [http://tfa-dostmann.de/index.php?id=57 TFA]
* TFA Windsender 433 MHz, Kat. Nr. 30.3149, siehe [http://tfa-dostmann.de/index.php?id=57 TFA]
* TFA T/H-Sender 433 MHz, Kat. Nr. 30.3150, siehe [http://tfa-dostmann.de/index.php?id=57 TFA]
* OWL CM160

=== FAQ: Wie bringe ich FHEM dazu nicht alle paar Sekunden den Zustand der Sensoren zu loggen? ===

Den ein oder anderen hat es schon genervt, dass die Oregon-Sensoren sehr gesprächig sind und damit das Filelog sehr groß wird.

Abhilfe: Hierzu kann man event-min-interval verwenden, um festzulegen, dass Events nur alle x Minuten generiert werden. event-on-change-reading kann man verwenden, dass Änderungen trotzdem sofort bemerkt werden.

Nachfolgend wird ein Oregon-Sensor BTHR918 so konfiguriert, dass er nur alle 10 Minuten loggt, aber beim State die Änderungen sofort geloggt werden.

define Alte_Garage TRX_WEATHER BTHR918
attr Alte_Garage event-min-interval state:600
attr Alte_Garage event-on-change-reading state
attr Alte_Garage event-on-update-reading .*

Damit man nicht alles loggt, kann man das Logging auf die Zeilen beschränken, die mit T: beginnen:

define FileLog_Alte_Garage FileLog /var/log/fhem/Alte_Garage-%Y.log Alte_Garage:T\x3a.*
attr FileLog_Alte_Garage logtype temp4press8:Temp/Press,temp4hum6dew10:Temp/Hum,text

Damit hat man dann folgendes im Log:

2013-08-27_12:21:29 Alte_Garage T: 19.9 H: 69 P: 1005 BAT: low
2013-08-27_12:31:37 Alte_Garage T: 19.9 H: 69 P: 1005 BAT: low
2013-08-27_12:41:45 Alte_Garage T: 19.9 H: 69 P: 1005 BAT: low
2013-08-27_12:47:27 Alte_Garage T: 20 H: 68 P: 1005 D: BAT: low
2013-08-27_12:57:35 Alte_Garage T: 20 H: 68 P: 1005 D: BAT: low

Wie man sieht, wird normalerweise alle 10 Minuten geloggt. Um 12:47:27 hat sich die Temperatur verändert und damit wurde ausserhalb der Reihe sofort ein Event generiert.

Ja, stimmt, ich muss noch die Batterie des Sensors wechseln (BAT: low) ;-)

== FHEM-Modul: TRX_SECURITY ==
Empfängt Security-Sensoren der Protokolle X10-Security, KD101 und Visonic.

'''KD101 kompatible Rauchmelder'''
Es wurden folgende KD101-Versionen gemeldet, die mit RXFtrx433 empfangen werden können:

* KD101LD
* KD101LA
* Flamingo FA20RF
* Elro RM150RF
* Unitec 46779

Die Rauchmelder KD101 (KD101LD, KD101LA, Flamingo FA20RF, Elro RM150RF) haben folgendes Verhalten:

* Wenn der KD101 selbst Rauch feststellt, kann man diesen Alarm über Funk nicht stoppen. Er sendet "alert" über Funk.
* Wenn man "alarm" über Funk an einen Rauchmelder sendet, dauert der Alarm nur wenige Sekunden. Für einen dauerhaften Alarm muss man also "alert" immer wieder senden.
* Wenn man die KD101 pairt, bekommen alle gepairten KD101 dieselbe ID.
* Wenn einer Rauch erkennt, triggert er alle KD101 mit derselben ID (also die gepairten).
* Nach Drücken der Taste "Test" am Rauchmelder sendet dieser "alert". Dadurch wird per autocreate der Rauchmelder angelegt.
* Ein KD101 sendet kein Keepalive-Signal. Man kann also nur testen, ob ein Rauchmelder noch funktioniert, indem man die Test-Taste drückt.

Mittels RFXtrx433 kann man die Befehle "alert" und "pair" an einen Rauchmelder senden.

Beispiel:

* set TRX_KD101_a5ca00 alert

Dies sendet den panic-Befehl an den Rauchmelder. Damit hört man ca. 3 Sekunden lang den nervigen Ton des Rauchmelders. Wer diesen länger haben will, muss das set nach ca. 3 Sekunden erneut auslösen.
Wer man also ein "set DEVICE alert" an einen Rauchmelder schickt, der mit anderen gepairt ist, dann wird der Alarm bei allen gepairten Rauchmeldern ausgelöst.

'''X10-Security-Sensoren'''
Folgende X10-Security-Sensoren werden erfolgreich eingesetzt:

* Türsensoren:
** X10 Türsensor Powerhouse DS10A ([http://www.domotica.famschenk.eu/DS10A_op_433Mhz.html Umbau auf 433 Mhz])
** Marmitek Türsensor DS90
* Bewegungssensoren:
** X10 Bewegungssensor Powerhouse MS10A ([http://www.domotica.famschenk.eu/MS10A-433.html Umbau auf 433 Mhz])[[File:Ms10a.png|70px|right|thumb|MS10A]]<div class="tright" style="clear:none">[[File:Ms90.png|82px|mini|ohne|MS90]]</div>
** Marmitek Bewegungssensor MS10E/BNL (kompatibel mit X10 MS10)
** Marmitek Bewegungssensor MS90
* Rauchmelder:
** Marmitek Rauchmelder SD90

Die oben genannten Sensoren können auch parallel zum RFXtrx433 mit der Marmitek-Alarmanlage SC9000 eingesetzt werden.

* Fernbedienungen:
** Marmitek KR21E [[File:Kr21e.png|60px|right|thumb|KR21E]]<div class="tright" style="clear:none">[[File:Sh624.png|75px|mini|ohne|SH624]]</div>
** Marmitek SH624

X10-Security-Sensoren senden etwa jede Stunde ein Keepalive-Paket, welches auch Informationen über den Batterieladestand enthält.

*Bewegungsmelder
** Oregon MSR939 (benötigt den RFXtrx433e), theoretisch 32 Adressen möglich, 5 Stück erfolgreich eingebunden (mehr Sensoren hatte ich nicht zur Hand)

== FHEM-Modul: TRX_LIGHT.pm ==
Empfängt die Protokolle X10, ARC, ELRO AB400D, Waveman, Chacon EMW200, IMPULS, RisingSun, Philips SBC, AC, HomeEasy EU sowie ANSLUT lighting devices (switches and remote control).

ARC ist ein a Protokoll, welches von Geräten HomeEasy, KlikAanKlikUit, ByeByeStandBy, Intertechno, ELRO, AB600, Duewi, DomiaLite und COCO genutzt wird. Typisch ist, dass diese Geräte einen Drehschalter haben, um die Protkolladresse einzustellen.

Das ARC-Protokoll kennt keinen Dim-Befehl. Daher hat die Firmware vom RFXtrx433 und auch das FHEM-Modul TRX_LIGHT keinen solchen Befehl. Die verkauften Dimmer mit ARC-Protokoll starten gemäß meiner Information das Hoch-Dimmen nach Empfang zweier ON-Kommandos. Sobald dann das nächste ON oder OFF Kommando empfangen wird, wird das Dimmen beendet.
Das ganze ist also zeitabhängig und eigentlich nicht für die Hausautomatisierung gedacht, sondern für den Menschen, der sieht, ob der Dim-Level ok ist. Automatisiert bekommt man keine exakte prozentuale Dimmung hin, da man Dimmen nur über Timing erreichen kann.
Da FHEM nicht sehen kann wie weit gedimmt wurde, ist das allerdings nicht wirklich praktikabel und auch vom Gerät abhängig.
Unterschiedliche Geräte auch unterschiedliches Zeitverhalten.

AC ist ein Protokoll, welches verschiedene Hersteller nutzen, die die Adresse über einen LEARN-Button lernen: KlikAanKlikUit, NEXA, CHACON, HomeEasy UK.

''Achtung:''Es sollte beachtet werden, dass Tür- und Bewegungssensoren des AC-Protokolls (HomeEasy alt, Chacon, KlikAanKlikUit, NEXA...) teilweise für 3-5 Sekunden etwa 50 Funkpakete generieren, was zu Kollisionen mit anderen Paketen führen kann. Siehe [http://www.domoticaforum.eu/viewtopic.php?f=7&t=7276 Hinweis zur Nutzung von Bewegungssensoren]. Ich rate daher vom Einsatz von Bewegungssensoren mit dem AC-Protokoll ab.

Der Autor des Moduls setzt derzeit folgende Geräte ein:

* Eagle EyeMS14a Bewegungssensor ([http://www.domotica.famschenk.eu/MS14A_OP_433.92.html Umbau auf 433 Mhz])
* Elro AB600 Funksender und Steckdosen

Nutzer haben die Funktion folgender Geräte gemeldet:

* KAKU AWST-6000 (Bewegungsmelder, sendet on/off)
* KAKU AMST-606 (Tür-/Fenster-Kontakt, sendet all_level/off)
* KAKU AWMT-230 (Unterputzsender, sendet on/off)
* KAKU APA3-1500R (Schalter & Handsender, nur on/off/all_off)
* KAKU CDB-6500AC (Türklingel, sendet nur chime)

== PT2262 empfangen und senden mit TRX_LIGHT.pm ==
'''WARNUNG:'''PT2262-Codes sollten nur verwendet werden, wenn unbedingt erforderlich. Normalerweise reicht die Nutzung der von RFXCOM vordefinierten Dekodierungen wie das ARC-Protokoll aus. Bei manchen Geräten mit dem Chip PT2262 kann dies evtl. nicht ausreichen. Sinnvollerweise sollte man prüfen, ob das Gerät wirklich einen Funk-Encoder-IC PT2262 oder SC2262 enthält.

'''ACHTUNG:''' Es können nur PT2262-Codes empfangen werden, wenn das Pulse-Timung 350 usec ist (Siehe Kapitel 8 im RFXtrx User Guide). Gemäß Seite 6 im Dokument http://www.escol.com.my/Datasheets_specs/pt2262_1.pdf‎ sollte für den Oszillator normalerweise ein 3,3 Mega-Ohm-Widerstand eingebaut sein.

=== PT2262-Format empfangen ===
Das Funk-Encoder-IC PT2262 der Firma PTC Taiwan (siehe [http://pdf.dzsc.com/88889/21967.pdf http://pdf.dzsc.com/88889/21967.pdf]) wird häufig in Fernbedienungen von Funksteckdosen und auch anderen Funkgeräten im 433-Mhz-Bereich verwendet. Es gibt viele PIN kompatible ICs wie z.B. der SC2262.

Es werden hierbei 12 Zeichen im Tristate-Format (0, 1, 2 bzw. f) übertragen. Der erste Teil der Zeichen stellt die Adresse und die darauffolgenden Zeichen die Datenbits (Zeichen 0 oder 1) dar.
Die verwendeten Fernbedienungen haben häufig Dip-Schalter mit drei Zuständen (also 0,1,2), mit denen sich die Adressen einstellen lassen.

Das Protokoll ist vom Aufbau ähnlich zum ARC-Protokoll.

Dabei lassen sich die ersten 6-12 Zeichen als Adressen (A0 bis A11) und die letzten 0-6 Zeichen (D5-D0) als Datenbits nutzen. Es sind damit insgesamt folgende Kombinationen der Bits möglich:

<nowiki>A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 A11
A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 D0
A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 D1 D0
A0 A1 A2 A3 A4 A5 A6 A7 A8 D2 D1 D0
A0 A1 A2 A3 A4 A5 A6 A7 D3 D2 D1 D0
A0 A1 A2 A3 A4 A5 A6 D4 D3 D2 D1 D0
A0 A1 A2 A3 A4 A5 D5 D4 D3 D2 D1 D0</nowiki>
Damit lassen sich also maximal 6-Bit-Daten übertragen. Dies reicht für einfache Schaltaufgaben, aber nicht für Anwendungen wie beispielsweise Thermometer.

RFXtrx433 läßt sich über RFXmngr so konfigurieren, dass die 12-Zeichen-Datagramme des PT2262-Formats als 24-Bit-Nutzdaten bzw. 3 Bytes empfangen werden können. Dazu kann man in RFXmngr das Protokoll Lighting4 einschalten.
Hinweise zur Nutzung sind in [http://www.rfxcom.com/WebRoot/StoreNL2/Shops/78165469/MediaGallery/Downloads/RFXtrx_User_Guide.pdf RFXtrx User Guide] (Kapitel "15. Transmit undecoded ARC commands") zu finden.

Das FHEM-Modul TRX_LIGHT erlaubt die Verarbeitung des PT2262-Formates.

Sobald Lighting4 eingeschaltet wird, werden die einzelnen Bits dem Gerät TRX_PT2262 zugeordnet. Sofern dieses noch nicht vorhanden ist, wird diesen per Autocreate definiert und ein entsprechendes Filelog angelegt.

Wenn beispielsweise ein Nutzer einen Taster einer ELRO AB600 Fernbedienung drückt, werden je nach Codierung der Adresse folgende Codes im Filelog generiert:

* Drücken der Taste "on":
<nowiki>2012-12-30_21:40:42 TRX_PT2262 111101110111</nowiki>
* Drücken von "off":
<nowiki>2012-12-30_21:40:47 TRX_PT2262 111101110110</nowiki>
Auf diese Weise kann ein Nutzer sehen, welche PT2262-Codes von RFXtrx433 empfangen werden.

Der Nutzer muss danach selbst entscheiden, welche Zeichen Adressen und welche Daten darstellen und was die Daten bedeuten. Im oben genannten Beispiel ist dies relativ einfach. Man sieht, dass sich nur das letzte Bit ändern und die Zustände 0 und 1 annimmt. Es ist daher anzunehmen, dass die ersten 11 Zeichen die Adresse repräsentieren.

TRX_LIGHT bietet die Möglichkeit den Adressprefix, die sogenannte deviceid selbst in einem define-Statement festzulegen.
Die Konvention ist dabei, dass die einzelnen Zeichen der Base4-Codierung angegeben werden müssen:

<nowiki>define <name> TRX_LIGHT PT2262 <deviceid> <devicelog> [<commandcodes>]</nowiki>
In commandcodes gibt man optional an wie die Ziffern Strings wie beispielsweise "on" oder "off" zugeordnet werden sollen. Dabei können über Komma getrennt wie die Ziffern den einzelnen Strings zugeordnet werden sollen. Jede einzelne Zuordnung wird über : angegeben. Zusätzlich sollte ein entsprechendes FileLog definiert werden.

Beispiel:

define TRX_MYREMOTE1 TRX_LIGHT PT2262 11110111011 light 0:off,1:on

define FileLog_TRX_MYREMOTE1 FileLog /var/log/fhem/TRX_MYREMOTE1-%Y.log TRX_MYREMOTE1

In diesem Fall wird die Ziffer 0 "off" und die Ziffer 1 "on" zugeordnet.

Damit werden nach Drücken der Tasten on und off folgende Einträge im Filelog wie folgt generiert:

==> TRX_MYREMOTE1-2012.log <==
2012-12-30_21:54:56 TRX_MYREMOTE1 light: on
2012-12-30_21:54:56 TRX_MYREMOTE1 on

==> TRX_MYREMOTE1-2012.log <==
2012-12-30_21:54:59 TRX_MYREMOTE1 light: off
2012-12-30_21:54:59 TRX_MYREMOTE1 off

=== PT2262-Format senden ===
Mit dem Funk-Decoder-IC PT2272 lassen sich Signale von PT2262-Sendern empfangen.
RFXtrx433 ist in der Lage Funksignale im PT2262-Format zu senden, die dann mit Geräten empfangen werden können, die über den Funk-Decoder-IC PT2272 verfügen. Dazu ist es nicht erforderlich in RFXmngr das Protokoll Lighting4 einzuschalten.

PT2262-Codes können über ein set-Kommando des vorher zu definierenden PT2262-Devices gesendet werden. Die Definition wurde auch schon bei "PT2262-Format empfangen" beschrieben.

<nowiki>define <name> TRX_LIGHT PT2262 <deviceid> <devicelog> [<commandcodes>]</nowiki>
Beispiel:

<nowiki>define TRX_MYREMOTE1 TRX_LIGHT PT2262 11110111011 light 0:off,1:on</nowiki>
Sobald das Device definiert wurde, kann der Code mittels set gesendet werden. Dabei kann man entweder der Base4-Code direkt angegeben werden oder der String der in <commandcodes> definiert wurde.

Beispiele (senden von 1):

<nowiki>set TRX_MYREMOTE1 1</nowiki>
<nowiki>set TRX_MYREMOTE1 on</nowiki>
<nowiki>set TRX_MYREMOTE1 off</nowiki>
Damit ein PT2262 Code gesendet werden kann, muss der Base4-Code bestehend aus <deviceid> und den Daten genau 12 Base4-Zeichen haben.

Die mittels <commandcodes> definierten Strings werden in der Auswahlliste von set in der Weboberfläche von FHEM berücksichtigt.

=== PT2262-Format am Beispiel der Brennenstuhl (RCS 2044 N) Steckdosen ===

Etwas verwirrend ist die Base-4-Codierung in FHEM und die Binärcodierung im RFXtrx, und weil mich das ein paar Minuten beschäftigt hat, beschreibe ich mal die Vorgehensweise exemplarisch mit dem o.a. Funk-Schaltdosensystem.

==== Vorbereitung (Hardware einstellen) ====

Zuallererst muss man sicherstellen, dass der "System-"Code aller Geräte, sprich des Senders und jedes Empfängers gleich ist, das sind die DIP-Switches (aka "Mäuseklavier") 1-5. "ON" ist eine 0, "OFF" eine 1. Dieser Konfiguration werden wir gleich noch begegnen. Stellen Sie also mal gleich alle Geräte auf eine andere Konfiguration als die ausgelieferte (sonst schalten Sie möglicherweise die Steckdosen des netten Nachbars), aber alle Geräte auf die gleiche Konfiguration.

Wer will, teste nun alle Steckdosen, ob sie mit der Fernbedienung schaltbar sind, ob also die Switches alle passen.

==== Konfiguration für FHEM ====

Nun zu FHEM: Erst einmal probiert man ja verschiedene Protokolle im ''RfxMgr''. Also den Empfänger an den PC anschließen und im ''RfxMgr'' die Verbindung aufbauen. Im ''User Guide'' steht, dass das nötige Protokoll ''Lighting4'' ist, also ankreuzen und ''Set Mode'' anklicken. Wenn man nun eine Taste der Fernbedienung drückt, kommt so was wie

<nowiki>Packettype = Lighting4
subtype = PT2262
Sequence nbr = 6
Code = 455451 decimal:4543569
S1- S24 = 0100 0101 0101 0100 0101 0001
Pulse = 325 usec
Signal level = 7 -64dBm
------------------------------------------------
------------------------------------------------
Packettype = Lighting4
subtype = PT2262
Sequence nbr = 7
Code = 45555F decimal:4543839
S1- S24 = 0100 0101 0101 0101 0101 1111
Pulse = 324 usec
Signal level = 7 -64dBm</nowiki>

Hier kommen meist 2 Meldungen, zuerst das Kommando. Die zweite Meldung kann uns egal sein, sie kommt nicht immer und hat denselben Wert, egal ob eine Steckdose geschaltet wird oder nicht (also kein Fehlerstatus), und egal ob sie ein- oder ausgeschaltet ist.

===== Decodierung des Systemcodes =====

Nun steht überall hier im Artikel "12 Base4-Zeichen". Wir haben 24 Binärzeichen. Das läßt sich übersetzen, indem man immer 2 Binärzeichen zu einem Base4-Zeichen zusammenfasst:
<nowiki>0100 0101 0101 0100 0101 0001
1 0 1 1 1 1 1 0 1 1 0 1</nowiki>

nach dem Prinzip:
<nowiki>00 = 0, 01 = 1, 10 = 2, 11 = 3</nowiki>

Und wenn man sich die DIP-Switches anschaut, und den Wert oben (hier "101111101101" durchgeht, fällt einem auf: die ersten 5 Zahlen sind genau die Stellungen der DIP-Switches:
<nowiki>10111 = OFF ON OFF OFF OFF</nowiki>

Und tatsächlich sind diese 5 Zahlen bei allen Tasten gleich: die Decodierung der ersten 5 Zahlen ist geschafft.

===== Decodierung der Steckdosen-Zuordnung =====

Dann geht man die verschiedenen Steckdosen-IDs durch, jeweils der "EIN"-Schalter, ergibt (suggestiv formatiert):

<nowiki>EIN=10111 01111 01, AUS=10111 01111 11 (Steckdose 1)
EIN=10111 10111 01, AUS=10111 10111 11 (Steckdose 2)
EIN=10111 11011 01, AUS=10111 11011 11 (Steckdose 3)
EIN=10111 11101 01, AUS=10111 11101 11 (Steckdose 4)</nowiki>

Also sind die nächsten 5 Zahlen die Zuordnung der Steckdosen. Jede Stelle beschreibt den Zustand des passenden DIP-Switches "A" bis "E", wie üblich "0" ist "ON", "1" ist "OFF". Ob die Steckdosen mit mehr als einem auf OFF gelegten "A" bis "E"-Switch funktionieren, habe ich nicht getestet, aber es erscheint logisch, man könnte dann bis zu 32 Steckdosen auf den gleichen Systemcode legen, und ein Nachbar mit Fernbedienung kann nichts Böses anrichten! FHEM kann es egal sein, man kann ja verschiedene Systemcodes angeben, das geht bei der Fernbedienung nicht. Die ausserdem auch nur einen der "A" bis "D"-Switches adressiert.

===== Ein/Aus-Kommando =====

Bleiben noch 2 Zahlen. Wenn man auf den "AN"-Taster drückt, ist der Wert "01", bei "AUS" "11". Da hier wieder alles invertiert ist, steht zu vermuten, dass davon nur die erste Zahl den gewünschten Schaltzustand beschreibt, "01" -> "0" -> "EIN". "11" -> "1" -> "AUS". Was die letzte Stelle ist: keine Ahnung.

Geschafft: jetzt ist die Fernbedienung in FHEM folgendermassen zu konfigurieren:

<nowiki>defmod Steckdose_brennenstuhl_aussen TRX_LIGHT PT2262 1011101111 light 01:on,10:off
defmod Steckdose_brennenstuhl_1 TRX_LIGHT PT2262 1011110111 light 01:on,10:off
defmod Steckdose_brennenstuhl_2 TRX_LIGHT PT2262 1011111011 light 01:on,10:off
defmod Steckdose_brennenstuhl_3 TRX_LIGHT PT2262 1011111101 light 01:on,10:off
attr Steckdose_brennenstuhl_.* Funksteckdosen,RFXcom
</nowiki>

(Natürlich sind die ersten 5 Zahlen bei Ihrem System anders als meine, insbesondere wenn Sie direkt neben mir wohnen, bitte ;))

'''Hinweis''': Man kann natürlich auch bei jeder Steckdose die ersten 5 Switches anders einstellen, also alle 10 Stellen, aber dann kann man die Fernbedienung nicht mehr verwenden, um mehrere zu schalten.

Adventsbeleuchtung gefällig?

<nowiki>define di_adventsbeleuchtung DOIF ([{sunset(-1800)}-24:00]) (set Steckdose_brennenstuhl_aussen on) DOELSE (set Steckdose_brennenstuhl_aussen off)
define di_adventsbeleuchtung_2 DOIF ([05:45-{sunrise(+1800)}]) (set Steckdose_brennenstuhl_aussen on) DOELSE (set Steckdose_brennenstuhl_aussen off)
define di_adventsbeleuchtung_3 DOIF ([{sunset(-1800)}-01:00]) (set Steckdose_brennenstuhl_1 on) DOELSE (set Steckdose_brennenstuhl_1 off)
define di_adventsbeleuchtung_4 DOIF ([05:35-{sunrise(+1800)}]) (set Steckdose_brennenstuhl_1 on) DOELSE (set Steckdose_brennenstuhl_1 off)</nowiki>

== Fragen und Antworten (FAQ) ==

=== Warum wird mein RFXtrx433 nicht erkannt? ===

Das Gerät hat einen FTDI-FT232R-USB-Interface-Chip installiert. Um RFXtrx433 nutzen zu können, muss das Betriebssystem einen entsprechenden Treiber für diesen Chip haben. Dies ist normalerweise bei Linux oder Fritzbox 7390 der Fall. Bei Windows muss ein entsprechender Treiber installiert werden. Siehe auch http://www.rfxcom.com/Documents/RFXtrx%20User%20Guide.pdf .

Bei Fritzbox 7270 und 7170 werden vom Hersteller AVM mit der Firmware keine Treiber für den FTDI-FT232R-USB-Interface-Chip mitgeliefert.

=== Warum werden die Tasten meiner Fernbedienung nicht alle erkannt? ===
Ist geklärt, dass die Fernbedienung von der Firmware supportet wird? Gerade beim ARC-Protokoll ist es häufig so, dass die Hersteller unterschiedliche Codierungen verwenden.

Es wurde berichtet, dass die Tasten folgende Fernbedienungen von der Firnware des RFXtrx433 nicht alle richtig erkannt werden:
* ELRO AB440RA
Bei folgende Fernbedienungen wurden berichtet, dass diese richtig erkannt werden:
* ELRO AB600RA

Bitte weitere Fernbedienungen melden!
[[Kategorie:Interfaces]]
[[Kategorie:Temperatursensoren]]
[[Kategorie:Bewegungs- und Anwesenheitsmelder]]
[[Kategorie:Rauchmelder]]
[[Kategorie:Luftdrucksensor]]
[[Kategorie:Regensensor]]
[[Kategorie:Wetterstationen]]
[[Kategorie:Dimmer]]
[[Kategorie:Feuchtesensoren]]
[[Kategorie:Other_Components]]
[[Kategorie:Waagen]]
[[Kategorie:Lichtsensoren]]
[[Kategorie:Energieverbrauchsmessung]]
[[Kategorie:Energieerzeugungsmessung]]

RFXtrx

2016-12-01T17:26:54Z

C2j2: Beispiel-Anleitung für die Konfiguration von Brennenstuhl Funksteckdosen

Fhem unterstützt viele durch einen '''RFXtrx'''433 Transceiver erreichbare Geräte durch eigene Module.

== Übersicht ==
[[File:Rfxtrx433.png|500px|right]]

RFXtrx433 ist ein Transceiver (Funkempfänger und Funksender) mit USB-Anschluss für den Frenzbereich 433,92 MHz. Die Stromversorgung erfolgt über USB. Das Gerät hat einen FTDI-FT232R-USB-Interface-Chip installiert. Um RFXtrx433 nutzen zu können, muss das Betriebssystem einen entsprechenden Treiber für diesen Chip haben. Genutzt wird RFXtrx433 von Anwendern mit FHEM unter Linux, Fritzbox 7390 oder Windows.

Mit der mitgelieferten Firmware können viele Funksensoren in diesem Frequenzbereich empfangen werden und es ist möglich bestimmte Protokolle auch zu senden. Die unterstützten Protokolle sind von der installierten Firmware abhängig, die über das Windows-Programm [http://www.rfxcom.com/Downloads RFXflash] aktualisiert werden kann. Die neueste Firmware ist unter [http://www.rfxcom.com/Downloads http://www.rfxcom.com/Downloads] zu finden.

Weitere Informationen zu den von diesem Transceiver verfügbaren Protokolle beim Hersteller unter [http://www.rfxcom.com www.rfxcom.com]. Da der Hersteller die Anzahl der Geräte ständig aktualisiert und die FHEM-Treiber in der Freizeit des Autors geschrieben werden, sind in den FHEM-Treibern nur eine Untermenge implementiert. Sollte ein Gerät/Protokoll fehlen, das die Firma RFXCOM unterstützt, können Sie im [http://forum.fhem.de/ FHEM-Forum] in der Untergruppe RFXTRX nachfragen, ob dieses implementiert werden kann.

TRXtrx433 wird derzeit von FHEM mit den Modulen TRX, TRX_LIGHT, TRX-SECURITY und TRX_WEATHER für eine Reihe von Protokollen unterstützt.

Nachfolgend werden nur Geräte aufgezeigt, die bei der Erstellung dieses WIKI-Eintrages eingepflegt werden.

== FHEM-Modul: TRX_WEATHER ==
Dieses Modul unterstützt Wettersensoren, insbesondere Sensoren des Herstellers Oregon-Scientific. Unter [http://www.rfxcom.com/oregon.htm Wetter-Sensoren] finden Sie eine Liste der von der RFXtrx433-Firmware unterstützten Wetter-Sensoren (Oregon-Scientific, Cresta, La Crosse, TFA, UPM, ...). Das FHEM-Modul TRX_WEATHER implementiert derzeit den Empfang folgender Sensorentypen und Sensoren:

- '''Temperatursensoren''':

* "THR128": Oregon-Scientific THR128/138, THC138
* "THGR132N": Oregon-Scientific THC238/268,THN132,THWR288,THRN122,THN122,AW129/131
* "THWR800": Oregon-Scientific THWR800
* "RTHN318": Oregon-Scientific RTHN318
* "TS15C": TS15C
* "VIKING_02811" : Viking 02811
* "WS2300" : La Crosse WS2300
* "RUBICSON" : RUBiCSON
* "TFA_303133" : TFA 30.3133

- '''Temperatur-/Luftffeuchtigkeitssensoren''':

* "THGR228N": Oregon-Scientific THGN122/123, THGN132, THGR122/228/238/268 [[File:Thgr228n.png|92px|right|thumb|THGR228N]]
* "THGR810": Oregon-Scientific THGR810
* "RTGR328": Oregon-Scientific RTGR328
* "THGR328": Oregon-Scientific THGR328
* "WTGR800_T": Oregon-Scientific WTGR800
* "THGR918": Oregon-Scientific THGR918, THGRN228, THGN500
* "TFATS34C": TFA TS34C (Kat. Nr. 30.3150)
* "WT450H": UPM WT450H
* "TX3_T": LaCrosse TX3, TX4, TX17
[[File:TX3TH.jpg|92px|right|thumb|TX3TH]]

* '''Nicht unterstützt werden von der RFXCOM-Firmware:''' TFA 30.3166

- '''Temperatur-/Luftffeuchtigkeits-/Luftdrucksensoren''':

* "BTHR918": Oregon-Scientific BTHR918
* "BTHR918N": Oregon-Scientific/Huger BTHR918N, BTHR968 [[File:Bthr918n.png|96px|right|thumb|BTHR918N]]

- '''Regensensoren''':

* "RGR918": Oregon-Scientific RGR126/682/918
* "PCR800": Oregon-Scientific PCR800
* "TFA_RAIN": TFA-Regensensor (Kat. Nr. 30.3148)
* "RG700": UPM RG700

- '''Windsensoren''':

* "WTGR800_A": Oregon-Scientific WTGR800
* "WGR800_A": Oregon-Scientific WGR800
* "WGR918": Oregon-Scientific STR918, WGR918
* "TFA_WIND": TFA-Windsensor (Kat. Nr. 30.3149)
* "WDS500" : UPM WDS500

- '''UV-Sensoren''':

* "UVN128": Oregon UVN128, UV138
* "UVN800": Oregon UVN800
* "TFA_UV": TFA_UV-Sensor

- '''Waagen''':

* "BWR101": Oregon Scientific BWR101
* "GR101": Oregon Scientific GR101

- '''Energiesensoren''':

* "CM160": OWL CM119 und CM160
* "CM180": OWL CM180

Der Autor des Module setzt derzeit folgende Sensoren ein:

* Oregon Scientific: BTHR918, BTHR918N, PCR800, RGR918, THGR228N, THR128, THWR288A, WTGR800, WGR918

Von Nutzern wurde die Funktion folgender weiterer Sensoren gemeldet:

* Oregon Scientific GR101
* Oregon Scientific RTGR-328 (T/H)
* Honeywell TF-ATS34C (T/H)
* TFA Regensender 433 MHz, Kat. Nr. 30.3148, siehe [http://tfa-dostmann.de/index.php?id=57 TFA]
* TFA Windsender 433 MHz, Kat. Nr. 30.3149, siehe [http://tfa-dostmann.de/index.php?id=57 TFA]
* TFA T/H-Sender 433 MHz, Kat. Nr. 30.3150, siehe [http://tfa-dostmann.de/index.php?id=57 TFA]
* OWL CM160

=== FAQ: Wie bringe ich FHEM dazu nicht alle paar Sekunden den Zustand der Sensoren zu loggen? ===

Den ein oder anderen hat es schon genervt, dass die Oregon-Sensoren sehr gesprächig sind und damit das Filelog sehr groß wird.

Abhilfe: Hierzu kann man event-min-interval verwenden, um festzulegen, dass Events nur alle x Minuten generiert werden. event-on-change-reading kann man verwenden, dass Änderungen trotzdem sofort bemerkt werden.

Nachfolgend wird ein Oregon-Sensor BTHR918 so konfiguriert, dass er nur alle 10 Minuten loggt, aber beim State die Änderungen sofort geloggt werden.

define Alte_Garage TRX_WEATHER BTHR918
attr Alte_Garage event-min-interval state:600
attr Alte_Garage event-on-change-reading state
attr Alte_Garage event-on-update-reading .*

Damit man nicht alles loggt, kann man das Logging auf die Zeilen beschränken, die mit T: beginnen:

define FileLog_Alte_Garage FileLog /var/log/fhem/Alte_Garage-%Y.log Alte_Garage:T\x3a.*
attr FileLog_Alte_Garage logtype temp4press8:Temp/Press,temp4hum6dew10:Temp/Hum,text

Damit hat man dann folgendes im Log:

2013-08-27_12:21:29 Alte_Garage T: 19.9 H: 69 P: 1005 BAT: low
2013-08-27_12:31:37 Alte_Garage T: 19.9 H: 69 P: 1005 BAT: low
2013-08-27_12:41:45 Alte_Garage T: 19.9 H: 69 P: 1005 BAT: low
2013-08-27_12:47:27 Alte_Garage T: 20 H: 68 P: 1005 D: BAT: low
2013-08-27_12:57:35 Alte_Garage T: 20 H: 68 P: 1005 D: BAT: low

Wie man sieht, wird normalerweise alle 10 Minuten geloggt. Um 12:47:27 hat sich die Temperatur verändert und damit wurde ausserhalb der Reihe sofort ein Event generiert.

Ja, stimmt, ich muss noch die Batterie des Sensors wechseln (BAT: low) ;-)

== FHEM-Modul: TRX_SECURITY ==
Empfängt Security-Sensoren der Protokolle X10-Security, KD101 und Visonic.

'''KD101 kompatible Rauchmelder'''
Es wurden folgende KD101-Versionen gemeldet, die mit RXFtrx433 empfangen werden können:

* KD101LD
* KD101LA
* Flamingo FA20RF
* Elro RM150RF
* Unitec 46779

Die Rauchmelder KD101 (KD101LD, KD101LA, Flamingo FA20RF, Elro RM150RF) haben folgendes Verhalten:

* Wenn der KD101 selbst Rauch feststellt, kann man diesen Alarm über Funk nicht stoppen. Er sendet "alert" über Funk.
* Wenn man "alarm" über Funk an einen Rauchmelder sendet, dauert der Alarm nur wenige Sekunden. Für einen dauerhaften Alarm muss man also "alert" immer wieder senden.
* Wenn man die KD101 pairt, bekommen alle gepairten KD101 dieselbe ID.
* Wenn einer Rauch erkennt, triggert er alle KD101 mit derselben ID (also die gepairten).
* Nach Drücken der Taste "Test" am Rauchmelder sendet dieser "alert". Dadurch wird per autocreate der Rauchmelder angelegt.
* Ein KD101 sendet kein Keepalive-Signal. Man kann also nur testen, ob ein Rauchmelder noch funktioniert, indem man die Test-Taste drückt.

Mittels RFXtrx433 kann man die Befehle "alert" und "pair" an einen Rauchmelder senden.

Beispiel:

* set TRX_KD101_a5ca00 alert

Dies sendet den panic-Befehl an den Rauchmelder. Damit hört man ca. 3 Sekunden lang den nervigen Ton des Rauchmelders. Wer diesen länger haben will, muss das set nach ca. 3 Sekunden erneut auslösen.
Wer man also ein "set DEVICE alert" an einen Rauchmelder schickt, der mit anderen gepairt ist, dann wird der Alarm bei allen gepairten Rauchmeldern ausgelöst.

'''X10-Security-Sensoren'''
Folgende X10-Security-Sensoren werden erfolgreich eingesetzt:

* Türsensoren:
** X10 Türsensor Powerhouse DS10A ([http://www.domotica.famschenk.eu/DS10A_op_433Mhz.html Umbau auf 433 Mhz])
** Marmitek Türsensor DS90
* Bewegungssensoren:
** X10 Bewegungssensor Powerhouse MS10A ([http://www.domotica.famschenk.eu/MS10A-433.html Umbau auf 433 Mhz])[[File:Ms10a.png|70px|right|thumb|MS10A]]<div class="tright" style="clear:none">[[File:Ms90.png|82px|mini|ohne|MS90]]</div>
** Marmitek Bewegungssensor MS10E/BNL (kompatibel mit X10 MS10)
** Marmitek Bewegungssensor MS90
* Rauchmelder:
** Marmitek Rauchmelder SD90

Die oben genannten Sensoren können auch parallel zum RFXtrx433 mit der Marmitek-Alarmanlage SC9000 eingesetzt werden.

* Fernbedienungen:
** Marmitek KR21E [[File:Kr21e.png|60px|right|thumb|KR21E]]<div class="tright" style="clear:none">[[File:Sh624.png|75px|mini|ohne|SH624]]</div>
** Marmitek SH624

X10-Security-Sensoren senden etwa jede Stunde ein Keepalive-Paket, welches auch Informationen über den Batterieladestand enthält.

*Bewegungsmelder
** Oregon MSR939 (benötigt den RFXtrx433e), theoretisch 32 Adressen möglich, 5 Stück erfolgreich eingebunden (mehr Sensoren hatte ich nicht zur Hand)

== FHEM-Modul: TRX_LIGHT.pm ==
Empfängt die Protokolle X10, ARC, ELRO AB400D, Waveman, Chacon EMW200, IMPULS, RisingSun, Philips SBC, AC, HomeEasy EU sowie ANSLUT lighting devices (switches and remote control).

ARC ist ein a Protokoll, welches von Geräten HomeEasy, KlikAanKlikUit, ByeByeStandBy, Intertechno, ELRO, AB600, Duewi, DomiaLite und COCO genutzt wird. Typisch ist, dass diese Geräte einen Drehschalter haben, um die Protkolladresse einzustellen.

Das ARC-Protokoll kennt keinen Dim-Befehl. Daher hat die Firmware vom RFXtrx433 und auch das FHEM-Modul TRX_LIGHT keinen solchen Befehl. Die verkauften Dimmer mit ARC-Protokoll starten gemäß meiner Information das Hoch-Dimmen nach Empfang zweier ON-Kommandos. Sobald dann das nächste ON oder OFF Kommando empfangen wird, wird das Dimmen beendet.
Das ganze ist also zeitabhängig und eigentlich nicht für die Hausautomatisierung gedacht, sondern für den Menschen, der sieht, ob der Dim-Level ok ist. Automatisiert bekommt man keine exakte prozentuale Dimmung hin, da man Dimmen nur über Timing erreichen kann.
Da FHEM nicht sehen kann wie weit gedimmt wurde, ist das allerdings nicht wirklich praktikabel und auch vom Gerät abhängig.
Unterschiedliche Geräte auch unterschiedliches Zeitverhalten.

AC ist ein Protokoll, welches verschiedene Hersteller nutzen, die die Adresse über einen LEARN-Button lernen: KlikAanKlikUit, NEXA, CHACON, HomeEasy UK.

''Achtung:''Es sollte beachtet werden, dass Tür- und Bewegungssensoren des AC-Protokolls (HomeEasy alt, Chacon, KlikAanKlikUit, NEXA...) teilweise für 3-5 Sekunden etwa 50 Funkpakete generieren, was zu Kollisionen mit anderen Paketen führen kann. Siehe [http://www.domoticaforum.eu/viewtopic.php?f=7&t=7276 Hinweis zur Nutzung von Bewegungssensoren]. Ich rate daher vom Einsatz von Bewegungssensoren mit dem AC-Protokoll ab.

Der Autor des Moduls setzt derzeit folgende Geräte ein:

* Eagle EyeMS14a Bewegungssensor ([http://www.domotica.famschenk.eu/MS14A_OP_433.92.html Umbau auf 433 Mhz])
* Elro AB600 Funksender und Steckdosen

Nutzer haben die Funktion folgender Geräte gemeldet:

* KAKU AWST-6000 (Bewegungsmelder, sendet on/off)
* KAKU AMST-606 (Tür-/Fenster-Kontakt, sendet all_level/off)
* KAKU AWMT-230 (Unterputzsender, sendet on/off)
* KAKU APA3-1500R (Schalter & Handsender, nur on/off/all_off)
* KAKU CDB-6500AC (Türklingel, sendet nur chime)

== PT2262 empfangen und senden mit TRX_LIGHT.pm ==
'''WARNUNG:'''PT2262-Codes sollten nur verwendet werden, wenn unbedingt erforderlich. Normalerweise reicht die Nutzung der von RFXCOM vordefinierten Dekodierungen wie das ARC-Protokoll aus. Bei manchen Geräten mit dem Chip PT2262 kann dies evtl. nicht ausreichen. Sinnvollerweise sollte man prüfen, ob das Gerät wirklich einen Funk-Encoder-IC PT2262 oder SC2262 enthält.

'''ACHTUNG:''' Es können nur PT2262-Codes empfangen werden, wenn das Pulse-Timung 350 usec ist (Siehe Kapitel 8 im RFXtrx User Guide). Gemäß Seite 6 im Dokument http://www.escol.com.my/Datasheets_specs/pt2262_1.pdf‎ sollte für den Oszillator normalerweise ein 3,3 Mega-Ohm-Widerstand eingebaut sein.

=== PT2262-Format empfangen ===
Das Funk-Encoder-IC PT2262 der Firma PTC Taiwan (siehe [http://pdf.dzsc.com/88889/21967.pdf http://pdf.dzsc.com/88889/21967.pdf]) wird häufig in Fernbedienungen von Funksteckdosen und auch anderen Funkgeräten im 433-Mhz-Bereich verwendet. Es gibt viele PIN kompatible ICs wie z.B. der SC2262.

Es werden hierbei 12 Zeichen im Tristate-Format (0, 1, 2 bzw. f) übertragen. Der erste Teil der Zeichen stellt die Adresse und die darauffolgenden Zeichen die Datenbits (Zeichen 0 oder 1) dar.
Die verwendeten Fernbedienungen haben häufig Dip-Schalter mit drei Zuständen (also 0,1,2), mit denen sich die Adressen einstellen lassen.

Das Protokoll ist vom Aufbau ähnlich zum ARC-Protokoll.

Dabei lassen sich die ersten 6-12 Zeichen als Adressen (A0 bis A11) und die letzten 0-6 Zeichen (D5-D0) als Datenbits nutzen. Es sind damit insgesamt folgende Kombinationen der Bits möglich:

<nowiki>A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 A11
A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 D0
A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 D1 D0
A0 A1 A2 A3 A4 A5 A6 A7 A8 D2 D1 D0
A0 A1 A2 A3 A4 A5 A6 A7 D3 D2 D1 D0
A0 A1 A2 A3 A4 A5 A6 D4 D3 D2 D1 D0
A0 A1 A2 A3 A4 A5 D5 D4 D3 D2 D1 D0</nowiki>
Damit lassen sich also maximal 6-Bit-Daten übertragen. Dies reicht für einfache Schaltaufgaben, aber nicht für Anwendungen wie beispielsweise Thermometer.

RFXtrx433 läßt sich über RFXmngr so konfigurieren, dass die 12-Zeichen-Datagramme des PT2262-Formats als 24-Bit-Nutzdaten bzw. 3 Bytes empfangen werden können. Dazu kann man in RFXmngr das Protokoll Lighting4 einschalten.
Hinweise zur Nutzung sind in [http://www.rfxcom.com/WebRoot/StoreNL2/Shops/78165469/MediaGallery/Downloads/RFXtrx_User_Guide.pdf RFXtrx User Guide] (Kapitel "15. Transmit undecoded ARC commands") zu finden.

Das FHEM-Modul TRX_LIGHT erlaubt die Verarbeitung des PT2262-Formates.

Sobald Lighting4 eingeschaltet wird, werden die einzelnen Bits dem Gerät TRX_PT2262 zugeordnet. Sofern dieses noch nicht vorhanden ist, wird diesen per Autocreate definiert und ein entsprechendes Filelog angelegt.

Wenn beispielsweise ein Nutzer einen Taster einer ELRO AB600 Fernbedienung drückt, werden je nach Codierung der Adresse folgende Codes im Filelog generiert:

* Drücken der Taste "on":
<nowiki>2012-12-30_21:40:42 TRX_PT2262 111101110111</nowiki>
* Drücken von "off":
<nowiki>2012-12-30_21:40:47 TRX_PT2262 111101110110</nowiki>
Auf diese Weise kann ein Nutzer sehen, welche PT2262-Codes von RFXtrx433 empfangen werden.

Der Nutzer muss danach selbst entscheiden, welche Zeichen Adressen und welche Daten darstellen und was die Daten bedeuten. Im oben genannten Beispiel ist dies relativ einfach. Man sieht, dass sich nur das letzte Bit ändern und die Zustände 0 und 1 annimmt. Es ist daher anzunehmen, dass die ersten 11 Zeichen die Adresse repräsentieren.

TRX_LIGHT bietet die Möglichkeit den Adressprefix, die sogenannte deviceid selbst in einem define-Statement festzulegen.
Die Konvention ist dabei, dass die einzelnen Zeichen der Base4-Codierung angegeben werden müssen:

<nowiki>define <name> TRX_LIGHT PT2262 <deviceid> <devicelog> [<commandcodes>]</nowiki>
In commandcodes gibt man optional an wie die Ziffern Strings wie beispielsweise "on" oder "off" zugeordnet werden sollen. Dabei können über Komma getrennt wie die Ziffern den einzelnen Strings zugeordnet werden sollen. Jede einzelne Zuordnung wird über : angegeben. Zusätzlich sollte ein entsprechendes FileLog definiert werden.

Beispiel:

define TRX_MYREMOTE1 TRX_LIGHT PT2262 11110111011 light 0:off,1:on

define FileLog_TRX_MYREMOTE1 FileLog /var/log/fhem/TRX_MYREMOTE1-%Y.log TRX_MYREMOTE1

In diesem Fall wird die Ziffer 0 "off" und die Ziffer 1 "on" zugeordnet.

Damit werden nach Drücken der Tasten on und off folgende Einträge im Filelog wie folgt generiert:

==> TRX_MYREMOTE1-2012.log <==
2012-12-30_21:54:56 TRX_MYREMOTE1 light: on
2012-12-30_21:54:56 TRX_MYREMOTE1 on

==> TRX_MYREMOTE1-2012.log <==
2012-12-30_21:54:59 TRX_MYREMOTE1 light: off
2012-12-30_21:54:59 TRX_MYREMOTE1 off

=== PT2262-Format senden ===
Mit dem Funk-Decoder-IC PT2272 lassen sich Signale von PT2262-Sendern empfangen.
RFXtrx433 ist in der Lage Funksignale im PT2262-Format zu senden, die dann mit Geräten empfangen werden können, die über den Funk-Decoder-IC PT2272 verfügen. Dazu ist es nicht erforderlich in RFXmngr das Protokoll Lighting4 einzuschalten.

PT2262-Codes können über ein set-Kommando des vorher zu definierenden PT2262-Devices gesendet werden. Die Definition wurde auch schon bei "PT2262-Format empfangen" beschrieben.

<nowiki>define <name> TRX_LIGHT PT2262 <deviceid> <devicelog> [<commandcodes>]</nowiki>
Beispiel:

<nowiki>define TRX_MYREMOTE1 TRX_LIGHT PT2262 11110111011 light 0:off,1:on</nowiki>
Sobald das Device definiert wurde, kann der Code mittels set gesendet werden. Dabei kann man entweder der Base4-Code direkt angegeben werden oder der String der in <commandcodes> definiert wurde.

Beispiele (senden von 1):

<nowiki>set TRX_MYREMOTE1 1</nowiki>
<nowiki>set TRX_MYREMOTE1 on</nowiki>
<nowiki>set TRX_MYREMOTE1 off</nowiki>
Damit ein PT2262 Code gesendet werden kann, muss der Base4-Code bestehend aus <deviceid> und den Daten genau 12 Base4-Zeichen haben.

Die mittels <commandcodes> definierten Strings werden in der Auswahlliste von set in der Weboberfläche von FHEM berücksichtigt.

=== PT2262-Format am Beispiel der Brennenstuhl (RCS 2044 N) Steckdosen ===

Etwas verwirrend ist die Base-4-Codierung in FHEM und die Binärcodierung im RFXtrx, und weil mich das ein paar Minuten beschäftigt hat, beschreibe ich mal die Vorgehensweise exemplarisch mit dem o.a. Funk-Schaltdosensystem.

==== Vorbereitung (Hardware einstellen) ====

Zuallererst muss man sicherstellen, dass der "System-"Code aller Geräte, sprich des Senders und jedes Empfängers gleich ist, das sind die DIP-Switches (aka "Mäuseklavier") 1-5. "ON" ist eine 0, "OFF" eine 1. Dieser Konfiguration werden wir gleich noch begegnen. Stellen Sie also mal gleich alle Geräte auf eine andere Konfiguration als die ausgelieferte (sonst schalten Sie möglicherweise die Steckdosen des netten Nachbars), aber alle Geräte auf die gleiche Konfiguration.

Wer will, teste nun alle Steckdosen, ob sie mit der Fernbedienung schaltbar sind, ob also die Switches alle passen.

==== Konfiguration für FHEM ====

Nun zu FHEM: Erst einmal probiert man ja verschiedene Protokolle im ''RfxMgr''. Also den Empfänger an den PC anschließen und im ''RfxMgr'' die Verbindung aufbauen. Im ''User Guide'' steht, dass das nötige Protokoll ''Lighting4'' ist, also ankreuzen und ''Set Mode'' anklicken. Wenn man nun eine Taste der Fernbedienung drückt, kommt so was wie

<nowiki>Packettype = Lighting4
subtype = PT2262
Sequence nbr = 6
Code = 455451 decimal:4543569
S1- S24 = 0100 0101 0101 0100 0101 0001
Pulse = 325 usec
Signal level = 7 -64dBm
------------------------------------------------
------------------------------------------------
Packettype = Lighting4
subtype = PT2262
Sequence nbr = 7
Code = 45555F decimal:4543839
S1- S24 = 0100 0101 0101 0101 0101 1111
Pulse = 324 usec
Signal level = 7 -64dBm</nowiki>

Hier kommen meist 2 Meldungen, zuerst das Kommando. Die zweite Meldung kann uns egal sein, sie kommt nicht immer und hat denselben Wert, egal ob eine Steckdose geschaltet wird oder nicht (also kein Fehlerstatus), und egal ob sie ein- oder ausgeschaltet ist.

===== Decodierung des Systemcodes =====

Nun steht überall hier im Artikel "12 Base4-Zeichen". Wir haben 24 Binärzeichen. Das läßt sich übersetzen, indem man immer 2 Binärzeichen zu einem Base4-Zeichen zusammenfasst:
<nowiki>0100 0101 0101 0100 0101 0001
1 0 1 1 1 1 1 0 1 1 0 1</nowiki>

nach dem Prinzip:
<nowiki>00 = 0, 01 = 1, 10 = 2, 11 = 3</nowiki>

Und wenn man sich die DIP-Switches anschaut, und den Wert oben (hier "101111101101" durchgeht, fällt einem auf: die ersten 5 Zahlen sind genau die Stellungen der DIP-Switches:
<nowiki>10111 = OFF ON OFF OFF OFF</nowiki>

Und tatsächlich sind diese 5 Zahlen bei allen Tasten gleich: die Decodierung der ersten 5 Zahlen ist geschafft.

===== Decodierung der Steckdosen-Zuordnung =====

Dann geht man die verschiedenen Steckdosen-IDs durch, jeweils der "EIN"-Schalter, ergibt (suggestiv formatiert):

<nowiki>EIN=10111 01111 01, AUS=10111 01111 11 (Steckdose 1)
EIN=10111 10111 01, AUS=10111 10111 11 (Steckdose 2)
EIN=10111 11011 01, AUS=10111 11011 11 (Steckdose 3)
EIN=10111 11101 01, AUS=10111 11101 11 (Steckdose 4)</nowiki>

Also sind die nächsten 5 Zahlen die Zuordnung der Steckdosen. Jede Stelle beschreibt den Zustand des passenden DIP-Switches "A" bis "E", wie üblich "0" ist "ON", "1" ist "OFF". Ob die Steckdosen mit mehr als einem auf OFF gelegten "A" bis "E"-Switch funktionieren, habe ich nicht getestet, aber es erscheint logisch, man könnte dann bis zu 32 Steckdosen auf den gleichen Systemcode legen. FHEM kann es egal sein, man kann ja verschiedene Systemcodes angeben, das geht bei der Fernbedienung nicht. Die ausserdem auch nur einen der "A" bis "D"-Switches adressiert.

===== Ein/Aus-Kommando =====

Bleiben noch 2 Zahlen. Wenn man auf den "AN"-Taster drückt, ist der Wert "01", bei "AUS" "11". Da hier wieder alles invertiert ist, steht zu vermuten, dass davon nur die erste Zahl den gewünschten Schaltzustand beschreibt, "01" -> "0" -> "EIN". "11" -> "1" -> "AUS". Was die letzte Stelle ist: keine Ahnung.

Geschafft: jetzt ist die Fernbedienung in FHEM folgendermassen zu konfigurieren:

<nowiki>defmod Steckdose_brennenstuhl_aussen TRX_LIGHT PT2262 1011101111 light 01:on,10:off
defmod Steckdose_brennenstuhl_1 TRX_LIGHT PT2262 1011110111 light 01:on,10:off
defmod Steckdose_brennenstuhl_2 TRX_LIGHT PT2262 1011111011 light 01:on,10:off
defmod Steckdose_brennenstuhl_3 TRX_LIGHT PT2262 1011111101 light 01:on,10:off
attr Steckdose_brennenstuhl_.* Funksteckdosen,RFXcom
</nowiki>

(Natürlich sind die ersten 5 Zahlen bei Ihrem System anders als meine, insbesondere wenn Sie direkt neben mir wohnen, bitte ;))

'''Hinweis''': Man kann natürlich auch bei jeder Steckdose die ersten 5 Switches anders einstellen, also alle 10 Stellen, aber dann kann man die Fernbedienung nicht mehr verwenden, um mehrere zu schalten.

Adventsbeleuchtung gefällig?

<nowiki>define di_adventsbeleuchtung DOIF ([{sunset(-1800)}-24:00]) (set Steckdose_brennenstuhl_aussen on) DOELSE (set Steckdose_brennenstuhl_aussen off)
define di_adventsbeleuchtung_2 DOIF ([05:45-{sunrise(+1800)}]) (set Steckdose_brennenstuhl_aussen on) DOELSE (set Steckdose_brennenstuhl_aussen off)
define di_adventsbeleuchtung_3 DOIF ([{sunset(-1800)}-01:00]) (set Steckdose_brennenstuhl_1 on) DOELSE (set Steckdose_brennenstuhl_1 off)
define di_adventsbeleuchtung_4 DOIF ([05:35-{sunrise(+1800)}]) (set Steckdose_brennenstuhl_1 on) DOELSE (set Steckdose_brennenstuhl_1 off)</nowiki>

== Fragen und Antworten (FAQ) ==

=== Warum wird mein RFXtrx433 nicht erkannt? ===

Das Gerät hat einen FTDI-FT232R-USB-Interface-Chip installiert. Um RFXtrx433 nutzen zu können, muss das Betriebssystem einen entsprechenden Treiber für diesen Chip haben. Dies ist normalerweise bei Linux oder Fritzbox 7390 der Fall. Bei Windows muss ein entsprechender Treiber installiert werden. Siehe auch http://www.rfxcom.com/Documents/RFXtrx%20User%20Guide.pdf .

Bei Fritzbox 7270 und 7170 werden vom Hersteller AVM mit der Firmware keine Treiber für den FTDI-FT232R-USB-Interface-Chip mitgeliefert.

=== Warum werden die Tasten meiner Fernbedienung nicht alle erkannt? ===
Ist geklärt, dass die Fernbedienung von der Firmware supportet wird? Gerade beim ARC-Protokoll ist es häufig so, dass die Hersteller unterschiedliche Codierungen verwenden.

Es wurde berichtet, dass die Tasten folgende Fernbedienungen von der Firnware des RFXtrx433 nicht alle richtig erkannt werden:
* ELRO AB440RA
Bei folgende Fernbedienungen wurden berichtet, dass diese richtig erkannt werden:
* ELRO AB600RA

Bitte weitere Fernbedienungen melden!
[[Kategorie:Interfaces]]
[[Kategorie:Temperatursensoren]]
[[Kategorie:Bewegungs- und Anwesenheitsmelder]]
[[Kategorie:Rauchmelder]]
[[Kategorie:Luftdrucksensor]]
[[Kategorie:Regensensor]]
[[Kategorie:Wetterstationen]]
[[Kategorie:Dimmer]]
[[Kategorie:Feuchtesensoren]]
[[Kategorie:Other_Components]]
[[Kategorie:Waagen]]
[[Kategorie:Lichtsensoren]]
[[Kategorie:Energieverbrauchsmessung]]
[[Kategorie:Energieerzeugungsmessung]]