DigitalSTROM einbinden
Diese Anleitung beschreibt einen einfachen Mechanismus, um in einer digitalSTROM-Installation Aktionen auszulösen und durch polling Daten der Installation abzufragen. Verwendet wird dafür HTTPMOD.
Funktionen:
- Aufruf einer beliebigen User Defined Action (UDA) im digitalSTROM-System
- Polling des Presence-State der digitalSTROM-Installation (incl. Visualisierung)
- Polling des aktuellen Verbrauchs eines Stromkreises durch Abfrage auf dem zugehörigen dSM (incl. Visualisierung)
Ein grundsätzliches Verständnis über eine digitalSTROM-Installation und der Bedienung des digitalSTROM-Konfigurators wird vorausgesetzt. Ebenso über FHEM im Allgemeinen.
Vorbereitungen auf dem digitalSTROM-Server (dSS)
Erzeugen eines Application Tokens für den Zugriff auf den dSS
Die Authentifizierung im dSS erfolgt über einen zweistufigen Mechanismus mit Application-Token und Session-Token.
Im ersten Schritt wird ein Application Token erzeugt und anschliessend über den dS-Konfigurator aktiviert. Dieser Schritt muss nur einmal durchgeführt werden. Eine Anleitung dazu findet sich in der Dokumentation digitalSTROM API (Kapitel 6). Mit Hilfe dieses Application Tokens wird dann ein Session Token generiert, das bei den einzelnen Calls auf das JSON-API benutzt wird.
Definition einer User Defined Action (UDA) im digitalSTROM-Konfigurator (dS-Konfigurator)
Über User Defined Actions (deutsch: Benutzerdefinierte Aktionen) können nahezu alle Aktionen in einer dS-Installation angetriggert werden. Über den dS-Konfigurator und die dSS-App "Benutzerdefinierte Aktionen" werden die UDAs angelegt. Neben den auszuführenden Aktionen können auch Bedingungen (wie z.B. nur Nachts, nur bei Abwesenheit) hinterlegt werden.
Beispiel für eine UDA:
Um die UDA über FHEM aufzurufen, wird ihre ID benötigt. Im dS-Konfigurator, Erweiterte Ansicht aktiv, Tab System, Menü Systemeigenschaften befindet sich der dSS-Property-Tree. Im Property-Tree unter dSS/usr/events findet man die UDAs mit ihrer ID.
Beispiel:
Ermitteln der dSID des digitalSTROM-Meters (dSM)
Um die Funktion aktueller Verbrauch im Stromkreis zu implementieren, wird die dSID des zugehörigen dSM benötigt. Im dS-Konfigurator, Erweiterte Ansicht aktiv, Tab System, Menü Systemeigenschaften befindet sich der dSS-Property-Tree. Im Property-Tree unter dSS/apartment/dSMeters/ unter dem entsprechenden dSM findet man die dSID. Bitte nicht verwechseln mit der dSUID oder der dSM-ID wie sie im Hardware-Tab angezeigt wird.
Beispiel:
Definition in der fhem.cfg
Definition eines HTTPMOD-Device in FHEM zum Aufruf der UDAs und für die Abfrage des Presence States
Der folgende Code implementiert die Funktionen
- Aufruf einer beliebigen User Defined Action (UDA) im dSS-System
- Polling des Presence-State der digitalSTROM-Installation (incl. Visualisierung)
In der fhem.cfg wird dazu folgender Abschnitt definiert:
############################################################### # define a dSS ############################################################### define dSS HTTPMOD https://hierstehtdieipdesdSS:8080/json/property/getString?path=/usr/states/presence/value&token=$sid 60 attr dSS userattr reAuthRegex reading1Name reading1Regex sid1IDRegex sidHeader1 sidURL stateFormat verbose attr dSS reAuthRegex .*not logged in.* attr dSS sid1IDRegex {"result":{"token":"([\d(abcdef)]+)" attr dSS sidHeader1 Content-Type: application/json attr dSS sidURL https://hierstehtdieipdesdSS:8080/json/system/loginApplication?loginToken=hierstehtdasapplicationtoken attr dSS verbose 5 attr dSS group dSS attr dSS room digitalSTROM # read presence state attr dSS reading1Name PresentState attr dSS reading1Regex "result":{"value":"([presentabsent]*) attr dSS stateFormat {sprintf("HomeState: %s", ReadingsVal($name,"PresentState",0))} # call a user defined action by ID attr dSS set01Name callUDA attr dSS set01URL https://hierstehtdieipdesdSS:8080/json/event/raise?parameter=id%3D$val&name=highlevelevent&token=$sid attr dSS set01ReAuthRegex .*not logged in.* # define logfile for dSS define FileLog_dSS FileLog ./log/dSS-%Y.log dSS attr FileLog_dSS room digitalSTROM # plot presence state define Plot_dSS SVG FileLog_dSS:dSS:CURRENT attr Plot_dSS captionLeft 1 attr Plot_dSS label "dSS PresentState: Min $data{min1}, Max $data{max1}, Last $data{currval1}" attr Plot_dSS room digitalSTROM
Hinweise:
- Über das HTTPMOD-Devices und die sid*-Attribute wird die zweistufige Authentifizierung mittels Application-Token und session-Token implementiert
- Über das JSON-API wird mit /json/property/getString?... der PresentState der digitalSTROM-Installation abgefragt
- Über die set01*-Parameter wird ein weiterer JSON-Call auf den dSS implementiert über den die UDA angetriggert werden kann
- Die Definition für das Logfile und den Plot des presence-states sind FHEM-Standard
Auslösen einer UDA in FHEM
Die vorher definierte UDA kann nun jederzeit über FHEM mittels
set dSS callUDA hierstehtdieIdderUDA
aufgerufen werden.
Definition eines HTTPMOD-Device in FHEM zum Pollen des aktuellen Verbrauchs in einem Stromkreis
Der folgende Code implementiert die Funktion
- Polling des aktuellen Verbrauchs eines Stromkreises durch Abfrage auf dem zugehörigen dSM (incl. Visualisierung)
In der fhem.cfg wird dazu folgender Abschnitt definiert:
############################################################### # define a dSM ############################################################### define dSM_0000131e HTTPMOD https://hierstehtdieipdesdSS:8080/json/circuit/getConsumption?id=hierstehtdiedSIDdesdSM&token=$sid 60 attr dSM_0000131e userattr reAuthRegex reading1Name reading1Regex sid1IDRegex sidHeader1 sidURL stateFormat verbose attr dSM_0000131e reAuthRegex .*not logged in.* attr dSM_0000131e sid1IDRegex {"result":{"token":"([\d(abcdef)]+)" attr dSM_0000131e sidHeader1 Content-Type: application/json attr dSM_0000131e sidURL https://hierstehtdieipdesdSS:8080/json/system/loginApplication?loginToken=hierstehtdasapplicationtoken attr dSM_0000131e stateFormat {sprintf("dSID: %s - Watt: %d", "hierstehtdiedSIDdesdSM", ReadingsVal($name,"Consumption",0))} attr dSM_0000131e verbose 1 attr dSM_0000131e group dSM attr dSM_0000131e room digitalSTROM # read consumption attr dSM_0000131e reading1Name Consumption attr dSM_0000131e reading1Regex {"result":{"consumption":([\d]+) # define logfile for dSM define FileLog_dSM_0000131e FileLog ./log/dSM-hierstehtdiedSIDdesdSM-%Y.log dSM_0000131e attr FileLog_dSM_0000131e room digitalSTROM # plot consumption for the dSM define Plot_dSM_0000131e SVG FileLog_dSM_0000131e:dSM:CURRENT attr Plot_dSM_0000131e captionLeft 1 attr Plot_dSM_0000131e label "Verbrauch Esszimmer/Flur: Min $data{min1}, Max $data{max1}, Last $data{currval1}" attr Plot_dSM_0000131e room digitalSTROM
Hinweise:
- Über das HTTPMOD-Devices und die sid*-Attribute wird die zweistufige Authentifizierung mittels Application-Token und Session-Token implementiert
- Über das JSON-API wird mit /json/circuit/getConsumption?... der aktuelle Verbrauch im Stromkreis (auf dem dSM) in der digitalSTROM-Installation abgefragt
- Die Definitionen für das Logfile und den Verbrauch sind FHEM-Standard
gplot-Dateien für die Visualisierung
Für die Visualisierungen werden zwei gplot-Dateien angelegt.
dSM.gplot
# Created by FHEM/98_SVG.pm, 2015-12-17 19:16:49 set terminal png transparent size <SIZE> crop set output '<OUT>.png' set xdata time set timefmt "%Y-%m-%d_%H:%M:%S" set xlabel " " set title '<L1>' set ytics nomirror set y2tics set grid ytics set ylabel "Verbrauch (W)" set y2label "" #FileLog_dSM_0000131e 4:dSM_0000131e.Consumption\x3a:0: plot "<IN>" using 1:2 axes x1y2 title 'Verbrauch (W)' ls lw 1 with lines
dSS.gplot
# Created by FHEM/98_SVG.pm, 2015-12-17 19:28:23 set terminal png transparent size <SIZE> crop set output '<OUT>.png' set xdata time set timefmt "%Y-%m-%d_%H:%M:%S" set xlabel " " set title '<L1>' set ytics nomirror set y2tics set grid ytics set ylabel "Verbrauch (W)" set y2label "" #FileLog_dSS 4:dSS.PresentState\x3a:0:$fld[3]=~"present"?1:0 plot "<IN>" using 1:2 axes x1y2 title 'Present/Absent' ls lw 1 with steps
Ergebnis der Visualisierung in FHEM
Weiterführende Informationen
digitalSTROM-API
- http://developer.digitalstrom.org/Architecture/system-interfaces.pdf
- http://developer.digitalstrom.org/Architecture/dss-json.pdf
digitalSTROM-Bedienungsanleitungen
HTTPMOD