Tutorial: openSenseMap

openSenseMap ist eine offene Web-Plattform für den Austausch von Sensordaten, die jeder nutzen kann. Dieses Tutorial beschreibt, wie man aktuelle Messwerte von Querx an diese Plattform übermitteln kann. Unabhängig von der ausgewählten Cloud zeigt dieses Tutorial, wie man Querx an neue Cloud-Dienste anpassen kann.

Registrierung bei openSenseMap

Zunächst muss das Gerät bei openSenseMap registriert werden. Dazu ist eine gültige E-Mailadresse erforderlich.

Während die Eingangsseite zur Registrierung noch in Deutsch erscheint, geht es danach in Englisch weiter. Diese sollte aber kein Problem darstellen. Durch Aktivieren der Bestätigung I agree stimmt man zu, dass der angegebene Standort des Geräts veröffentlicht wird. Die eingegebene E-Mailadresse wird nur genutzt, um über Aktualisierungen zu informieren und wird nicht an Dritte weitergegeben.

Anschließend vergibt man einen Namen für das Gerät, z.B. Querx und gibt an, ob sich die Sensoren im Innenraum (indoor) oder im Freien (outdoor) befinden, oder ob diese mobil (mobile) sind.

Im nächsten Schritt wird der Standort des Geräts bestimmt. Dies funktioniert intuitiv mit Hilfe einer Straßenkarte.

Zuletzt wird noch die verwendete Hardware abgefragt. Da Querx nicht direkt unterstützt wird, wählt man hier die manuelle Konfiguration. Durch Klicken auf Add sensor kann ein Sensor eingerichtet werden.

Auf der nächsten Seite bestätigt man, dass die vom Sensor gesendeten Daten von jedermann frei genutzt werden dürfen.

Auf der letzten Seite findet man eine Zusammenfassung des registrierten Geräts, darunter einen Identifikator für das Gerät (senseBox ID) 1 und einen weiteren Identifikator für den Sensor 2. Diese werden später bei der Konfiguration des Querx benötigt.

In einer Textbox bekommt man noch den Quellcode für Arduino, den wir für Querx nicht benötigen. Dieser Code wird zusätzlich als Anhang an die genannte E-Mailadresse geschickt.

Konfiguration des Querx

Seit der Firmwareversion 4.2 ist es möglich, das Format für den Datenexport über eigene Template-Dateien anzupassen. Dadurch ist man nicht mehr darauf angewiesen, dass die Firmware eine bestimmte Cloud direkt unterstützt, sondern kann Querx flexibel an die Anforderungen der Cloud anpassen.

openSenseMap erwartet einen JSON-String in folgender Form:

{"value": Messwert}

Dieser wird dann per POST an die folgende URL geschickt, wobei ID1 und ID2 die beiden Identifikatoren sind, die wir bei der Registrierung erhalten haben:

ingress.opensensemap.org/boxes/ID1/ID2

Nun benötigt Querx noch eine einfache Textdatei, ein sogenanntes Template, mit folgendem Inhalt:

add=/tpl/j/osem.tpl

Content-Type: application/json
{# #}
{"value": {{sensortab_value.0}}}

Wir erstellen diese Datei unter dem Namen osem.tpl mit einem Texteditor (Notepad, vi etc.) auf dem PC. Die erste Zeile bestimmt, unter welchem Pfadnamen die Datei im Speicher des Querx abgelegt wird. Danach muss eine Leerzeile folgen. Die nächsten Zeilen bestimmen den Inhalt der Daten, die an die Cloud geschickt werden und gestatten es, zusätzliche Kopfzeilen zu dem HTTP-POST hinzuzufügen. Hier verwenden wir nur eine Kopfzeile (Content-Type) zur Bestimmung des Datentyps JSON.

Kopfzeilen werden bei HTTP durch eine Leerzeile vom Inhalt getrennt. Im Querx wird die Datei später vom Template-Interpreter umgesetzt, der aber einfache Leerzeilen entfernt. Mit einer Kommentarzeile gelingt aber die Erzeugung einer Leerzeile. Der Kommentar {# #} wird vom Interpreter später entfernt, die Zeile selbst bleibt aber erhalten. Die letzte Zeile enthält dann den von openSenseMap erwarteten JSON-String, wobei der Template-Interpreter im Querx den Teil {{sensortab_value.0}} durch den aktuellen Messwert des ersten Sensors ersetzt.

Wenn die Datei auf dem PC gespeichert wurde, kann Sie über das Webinterface von Querx unter Konfiguration / Wartung / Firmware / Content installieren auf dem Gerät installiert werden.

Nun kann Querx so eingestellt werden, dass der Sensorwert in regelmäßigen Abständen an openSenseMap gesendet wird.

Ab Firmwareversion 6 wurde die Unterstützung für Clouds überarbeitet. Wenn Sie noch mit einer älteren Firmware arbeiten, finden Sie weiter unten die entsprechenden Schritte.

Wählen Sie die Konfigurationsseite Schnittstellen / Aktionen und wählen Sie HTTP-Push als Aktionstyp und Zeitintervall als Ereignistyp.

Klicken Sie auf Anlegen, um die neue Aktion zu konfigurieren. Tragen Sie die folgende URL ein:

ingress.opensensemap.org/boxes/ID1/ID2

Ersetzen Sie dabei ID1 durch den Identifikator für das Gerät (senseBox ID) und ID2 durch den Identifikator für den Sensor. Geben Sie POST als HTTP-Methode ein und wählen Sie die Template-Datei aus, die zuvor heraufgeladen wurde.

Nach Eingabe der Aktualisierungsrate (in Minuten) und der Aktivierung der Aktion über die Schaltfläche Aktivieren wird Querx regelmäßig in dem konfigurierten Zeitabstand den aktuellen Sensorwert an openSenseMap übermitteln. Wenn Sie nicht solange warten wollen, können Sie mit der Schaltfläche Test eine sofortige Übertragung auslösen. Das Ergebnis erscheint als Syslog-Nachricht unten auf der Seite.

Falls Ihr Querx noch mit der Firmwareversion 5 arbeitet, finden Sie die entsprechende Konfigurationsseite noch unter Schnittstellen / HTTP Push.

Für Querxe mit Firmwareversion 4 ist ebenfalls die Konfigurationsseite unter Schnittstellen / HTTP Push zu finden.

 

 

Leider überschreitet die Länge der URL das in dieser Firmware gesetzte Limit des Eingabefeldes von 63 Zeichen. Dies Problem wird dadurch gelöst, dass wir in der URL die Platzhalter (Variablen) $1 und $2 verwenden und die langen Identifikatoren als Variableninhalte eingeben. Sollten Sie später auf eine höhere Firmwareversion 5 oder 6 wechseln, müssen Sie Identifikatoren wieder direkt in die URL eingeben, da hier keine Platzhalter mehr unterstützt werden.

Unter Schnittstellen / Syslog kann die laufende Kommunikation mit der Cloud überprüft werden.

Ergebnis

Wenn alles wie vorgesehen funktioniert, können wir die Daten von openSenseMap unter der URL

https://opensensemap.org/explore/ID1

abrufen, wobei ID1 wieder durch den Identifikator des Gerätes zu ersetzen ist.

Damit wurde erfolgreich demonstriert, wie sich Querx in neue Cloud-Umgebungen integrieren lässt, ohne dass diese direkt vom Gerät unterstützt werden.

Dabei traten Probleme mit älteren Versionen der Firmware auf. Die für die Version 4 zu lange URL konnte über den Umweg mit den Platzhaltern implementiert werden. Bis zur Version 5 gab es keine Möglichkeit für die Übermittlung von Messwerten mehrerer Sensoren innerhalb eines Geräts. openSenseMap fordert für jeden Sensor eine eigene URL, während sich im Querx nur eine URL konfigurieren lässt. Erst die Version 6 bietet ausreichend flexible Konfigurationsmöglichkeiten.