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:

1. Aufruf einer beliebigen User Defined Action (UDA) im digitalSTROM-System
2. Polling des Presence-State der digitalSTROM-Installation (incl. Visualisierung)
3. 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

1. Aufruf einer beliebigen User Defined Action (UDA) im dSS-System
2. 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:

1. Über das HTTPMOD-Devices und die sid*-Attribute wird die zweistufige Authentifizierung mittels Application-Token und session-Token implementiert
2. Über das JSON-API wird mit /json/property/getString?... der PresentState der digitalSTROM-Installation abgefragt
3. Über die set01*-Parameter wird ein weiterer JSON-Call auf den dSS implementiert über den die UDA angetriggert werden kann
4. 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

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

1. Über das HTTPMOD-Devices und die sid*-Attribute wird die zweistufige Authentifizierung mittels Application-Token und Session-Token implementiert
2. Über das JSON-API wird mit /json/circuit/getConsumption?... der aktuelle Verbrauch im Stromkreis (auf dem dSM) in der digitalSTROM-Installation abgefragt
3. 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

• http://www.digitalstrom.com/Partner/Support/Bedienungsanleitungen/

HTTPMOD

• HTTPMOD im Wiki
• HTTPMOD in der FHEM-Command Reference