====== digitalSTROM ======
[[https://www.digitalstrom.com/ueber-uns/corporate/|DigitalSTROM]] ist eine SmartHome Lösung der gleichnamigen Firma.

Im Folgenden ein einfaches Bash-Skript zum Auslesen von dSM-Zählerständen. Die Begriffe dSM und dSS werden hier nicht erläutert. Wer das System einsetzt, oder einsetzen möchte, sollte wissen wovon die Rede ist. 

===== Vorbereitungen =====

==== Voraussetzungen ====
  * VZClient
  * jsonclient
  * Python

[[/software/clients/vzclient|VZClient]] und [[https://github.com/volkszaehler/volkszaehler.org/blob/master/bin/jsonclient|jsonclient]] sind Teil von volkszaehler.org. Wie man einen eigenen Volkszähler installiert findet man unter [[/howto/getstarted]].\\

Python lässt sich schnell mit folgendem Befehl installieren: 
<code>sudo apt install python-minimal</code>

==== Erzeugen eines Application Tokens für den Zugriff auf den dSS ====
Aus der Doku von [[https://wiki.fhem.de/wiki/DigitalSTROM_einbinden|FHEM]]:
> 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 [[http://developer.digitalstrom.org/Architecture/system-interfaces.pdf|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.
\\  
Der dSS verwendet ein selbst signiertes Zertifikat. Das wird von manchen Browsern als Sicherheitsrisiko gesehen. Mit den folgenden Schritten erhält man den Token:
  * In die Adresszeile eines Browsers <code>https://<yourdss>:8080/json/system/requestApplicationToken?applicationName=volkszaehler</code>eingeben, eventuell die Sicherheitshinweise wegen den Zertifikat bestätigen.  
  * Angezeigt wird wird die .json Antwort des dSS mit den benötigten Token.
  * Den Token mit '//copy and paste//' sichern.
  * In Firefox auf die Startseite des dSS gehen.
  * Unten rechts ''Erweiterte Ansicht'' aktivieren.
  * In den Reiter ''System'' wechseln.
  * Unter ''Zugriffsberechtigung'' -> ''Applikation'' -> ''volkszaehler'' Zugriff erlauben\\ ''Uebernehmen'' nicht vergessen.

==== Volkszähler ====
In ''/etc/vzclient.conf'' ist die Middleware einzutragen, in der Regel localhost.
<code>:~$ sudo nano /etc/vzclient.conf
[default]
url:http://localhost/middleware.php
</code>
Über das Frontend werden die Kanäle angelegt.\\  
Benötigt wird pro dSM ein Kanal Typ "El. Energie (Zählerstände)" mit "Auflösung 1000".\\  

==== Verzeichnis ''/tmp'' ====
Das Script schreibt bei jeden Aufruf eine Datei nach ''/tmp'', und löscht diese wieder. Das ist tödlich für eine SD-Card. \\  
<note warning>Wer das Script auf einen RaspberryPi einsetzt, **muss** ''/tmp'' in eine RAM-Disk legen.</note>

===== Script =====

Das folgende Script vorzugsweise unter ''/usr/local/bin/'' ablegen. 

<file bash dsm.sh>
#!/bin/bash
#
# This is a simple bash script for reading digitalSTROM meters 
# connected to digitalSTROM server, and logs their values for the 
# project volkszaehler. The meter reading is queried, so it is 
# relatively unimportant how often it is queried.
# 
# Start it with a cronjob similar to this one:
# * * * * * sudo /<pfad>/dsm.sh >> /var/log/dsm.log
#
# @author Thomas Hoepfner
# 


# configuration
#
# jsonclient to disassemble
jc=jsonclient

# vzclient to save
# make sure vzclient.conf has middleware url configured or add below
vzc=vzclient

# digitalSTROM server
# api=https://<your server>:8080/json
api=https://<your server>:8080/json

# Authentication token see chapter 6 in:
# http://developer.digitalstrom.org/Architecture/system-interfaces.pdf
app_token=<personal token>


# Configuration of the actual counters according to the format 
# 			[uuid]=dSMeter 
# The <uuid> is created in the middleware as 
# "El. energy (counter readings)", resolution 1000.
# The <dSmeter> is easily determined from the json response. 
# Remove the comment character in the line: 
# cat "$tmp_file" > #/var/www/volkszaehler.org/htdocs/dsm.json (after get data)
# Run the script once. In dsm.json are all digitalSTROM meters with description.
# The digit after level "dSmeters:" is the corresponding dSM.
#
declare -A sensors
sensors=(
            [11111111-1111-1111-1111-111111111111]=0
            [22222222-2222-2222-2222-222222222222]=1
)

# loginto digitalSTROM server
token=$("$jc" --url "$api/system/loginApplication?loginToken=$app_token" -e result,token)
echo "Security token: $token"

# temp file for data
tmp_file=$(mktemp)

# get data - dsm power,consumption
"$jc" --url "$api/property/query?query=/apartment/dSMeters/*(dSUID,name,powerConsumption,energyMeterValue)&token=$token" > "$tmp_file"


# analyze json response
#
#cat "$tmp_file" > /var/www/volkszaehler.org/htdocs/dsm.json
#
#exit  # Exit script here for testing

# parse data
for uuid in "${!sensors[@]}"; do
 sensor=${sensors[$uuid]}
 val=$("$jc" --file "$tmp_file" -e result,dSMeters,$sensor,energyMeterValue)
 echo $uuid  $val
 # save to vzclient
  if [ -n "$val" ]; then
   int=$(echo "($val+0.5)/1" | bc) 
   if [ "$int" -gt 0 ]; then "$vzc" -u $uuid add data value=$val; fi
  fi
done

rm "$tmp_file"
</file>

Die Datei ausführbar machen,
<code>:~$ sudo chmod +x /usr/local/bin/dsm.sh</code>
und editieren
<code>:~$ sudo nano /usr/local/bin/dsm.sh

->Zeile 26: den dSS eintragen
api=https://<your server>:8080/json  

->Zeile 30: den Aplikation Token eintragen
app_token=<personal token>

->Zeile 62u.64: die 1.# entfernen
cat "$tmp_file" > /var/www/volkszaehler.org/htdocs/dsm.json
#
exit  # Exit script here for testing

-> speichern und Editor verlassen
</code>
Jetz wird das Script einmal ausgeführt.
<code>:~$ sudo /usr/local/bin/dsm.sh</code>
Kommen Fehlermedungen wie diese...<code>
Traceback (most recent call last):
  File "/var/www/volkszaehler.org/bin/jsonclient", line 58, in <module>
    f=urllib2.urlopen(url);
  File "/usr/lib/python2.7/urllib2.py", line 154, in urlopen
    return opener.open(url, data, timeout)
  File "/usr/lib/python2.7/urllib2.py", line 429, in open
    response = self._open(req, data)
  File "/usr/lib/python2.7/urllib2.py", line 447, in _open
    '_open', req)
  File "/usr/lib/python2.7/urllib2.py", line 407, in _call_chain
    result = func(*args)
  File "/usr/lib/python2.7/urllib2.py", line 1241, in https_open
    context=self._context)
  File "/usr/lib/python2.7/urllib2.py", line 1198, in do_open
    raise URLError(err)
urllib2.URLError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:726)></code>
...Hilft dieser Issue:[[https://github.com/volkszaehler/volkszaehler.org/pull/712/commits/d0215c7a39c05795b6ca6ab655e10c8b92ab4013]]

Läuft das Script fehlerfrei, liegt unter %%http://<volkszaehler>/dsm.json%% die Antwort des dSS.\\
Die Ziffer unterhalb der Ebene "dSmeters:" ist die dSM-ID die wir erfassen wollen.

Jetzt konfigurieren wir das Script abschließend:
<code>:~$ sudo nano /usr/local/bin/dsm.sh

->Zeile 62u.64: wieder auskommentieren
#cat "$tmp_file" > /var/www/volkszaehler.org/htdocs/dsm.json
#
#exit  # Exit script here for testing

->ab Zeile 45 werden die Meters eingeben [<VZ-UIID>]=<dSM-ID>
sensors=(
            [11111111-1111-1111-1111-111111111111]=0
            [22222222-2222-2222-2222-222222222222]=1
)
</code>

mit den Befehle <code>:/$ sudo /usr/local/bin/dsm.sh</code>speichern wir den 1.Wert. 
In der Konsole sollte eine ähnliche Ausgabe erscheinen:<code>
:/$ sudo /usr/local/bin/dsm.sh
Security token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
11111111-1111-1111-1111-111111111111 xx.xxxx
{"version":"0.3","rows":1}
22222222-2222-2222-2222-222222222222 xx.xxxx
{"version":"0.3","rows":1}
</code>

===== cron =====
Um regelmäßig Daten zu erhalten richtet man einen cronjob ein
<code>
:/$ sudo crontab -e
# Edit this file to introduce tasks to be run by cron.

*/3 * * * * sudo /usr/local/bin/dsm.sh
</code>
Jetzt sollte alle 3 Minuten ein Wert je dSM in der Datenbank ankommen.