Das The Things Network bietet verschiedene Möglichkeiten, um an die Daten der eigenen Applikation heranzukommen. Dazu gibt es verschiedene Möglichkeiten neben MQTT, die im The Things Network integrations heißen. Eine praktische ist der Data Storage. In diesem Fall werden die Daten mit ihrem Zeitstempel für maximal sieben Tage zwischengespeichert. Die Daten kann man einfach mit einem Abruf einer JSON-Datei herunterladen.
Vorarbeiten
Im The Things Network kann man die Rohdaten mit einem payload formatter dekodieren. Dieser Schritt ist nicht zwingend notwendig, da der Data Storage auch die Rohdaten speichert, aber bequemer und eleganter ist er in jedem Fall. Dazu klickt man auf den Reiter Payload Formats in der Applikation.
Im Editor-Bereich gibt man eine Javascript-Funktion zum Dekodieren der Rohdaten ein. Das ist nicht ganz einfach, wenn man nicht in JavaScript programmieren kann, aber mit einer grundlegenden Programmiererfahrung in einer anderen Sprache sollte das doch machbar sein.
Nehmen wir einmal die Rohdaten des Feinstaubsensors. In diesem Fall liegen die Daten in vier Bytes vor. Die wir mit der folgenden Funktion dekodieren.
function Decoder(bytes, port) {
pm25 = (bytes[0] << 8 | bytes[1]) / 10; // (high byte * 256 + low byte) / 10
pm10 = (bytes[2] << 8 | bytes[3]) / 10;
humidity = (bytes[4] << 8 | bytes[5]) / 10;
temperature = (bytes[6] << 8 | bytes[7]) / 10;
return {
pm25: pm25,
pm10: pm10,
pm_invalid: (bytes[0] === 0xff && bytes[1] === 0xff),
humidity: humidity,
temperature: temperature,
ht_invalid: (bytes[4] === 0xff && bytes[5] === 0xff)
};
}
Im ersten Byte (bytes[0]) liegt das high byte der Partikel mit 2,5 µm Größe. Diesen Wert müssen wir um acht Bits nach links schieben (<<). Das nächste Byte (bytes[1]) enthält das low byte des Werts. Wir verknüpfen es mit einem bitweisen Oder (|) mit der high byte. Alternativ kann man anstelle des Verschiebens um acht Bit mit 256 multiplizieren und statt des Oders addieren. Verschieben und Oder sind aber schneller. Das kann bei vielen Daten wichtig sein. Wenn wir das high byte und low byte wieder in einem Wert zusammengefügt haben, müssen wir noch durch zehn teilen, da unsere Rohdaten eine Nachkommastelle haben. In unserem Beispiel haben wir keine ports verwendet. Man kann mit ports verschiedene Kodierungen von Rohdaten umsetzen, wenn man in einer Applikation zum Beispiel verschiedene Sensoren hat. Die anderen Werte unseres Sensors werden nach demselben Schema dekodiert. Der Rückgabewert der Decoder()-Funktion ist ein JavaScript-Objekt (erkennbar an den Attribut-Wert-Paaren in geschweiften Klammern). Es sieht zwar etwas nach Stottern aus, aber pm25: pm25 weist zum Beispiel dem Attribut pm25 den Wert der Variablen pm25 zu. Man hätte die Berechnung auch direkt im Objekt durchführen können, wie das für die Fehlermarkierung pm_invalid gezeigt ist. Ein Fehler liegt dann vor, wenn die beiden Bytes den Wert 0xff haben. (Das dreifache Gleichheitszeichen vergleicht in JavaScript Wert und Datentyp.)
Die meisten Rohdaten sind in ähnlicher Weise kodiert. Mit Hilfe der Dokumentation und zur Not etwas Google-Fu sollte auch der JavaScript-Unkundige mit Hilfe des Test-Knopfs einen Dekoder für seinen Sensor implementieren können.
Konfiguration des Data Storage
Das Hinzufügen des Data Storage ist einfach. Man geht in der Applikation auf den Reiter Integrations
Hier klickt man auf add integration und bekommt eine Auswahl der integrations, die The Things Network kennt. Diese Auswahl kann sich mit der Zeit verändern. Hier interessiert uns nur der Data Storage.
Wenn wir die Fläche mit dem Data Storage anklicken, geht der Informationsdialog der integration auf.
Die wir mit einem Klick auf Add integration zu unserer Applikation hinzufügen. Jetzt haben wir in unserer Applikation den Data Storage hinzugefügt. The Things Network wird jetzt immer, wenn neue Daten in der Applikation eingehen sie mit unserem payload formatter dekodieren und die Daten im Data Storage speichern. Wie kommen wir jetzt an die Daten im Data Storage?
Abholen der Daten
Wenn wir im Integration Overview unserer Applikation (einfach auf Data Storage im Integrations-Reiter der Applikation klicken) auf go to platform klicken, öffnet sich eine Swagger-Seite im Browser.
Das sieht doch schon gut aus. Es gibt drei Knöpfe mit der Aufschrift GET. Damit sollten wir doch an unsere Daten kommen. Klickt man auf einen der Knöpfe, so wird die entsprechende Abfrage (query) expandiert und es erscheint ein freundlicher Try it out!-Knopf.
Irgendwelche Knöpfe drücken wir doch immer, wenn sie uns auffordern sie auszuprobieren…
… das sieht doch gut aus. Oder? Halt! Da steht etwas von not authorized. Wir dürfen nicht auf die Daten zugreifen! Das ist auch gut so, sonst könnte jeder unsere Daten abziehen. Wir müssen erst noch Swagger autorisieren auf unsere Daten zuzugreifen. Wir müssen erst noch zurück in die The Things Network Console und einen Zugriffsschlüssel anlegen.
Access Keys
Ganz unten auf der Seite mit unserer Applikation finden wir den Abschnitt Access Keys. Hier gibt es schon einen Schlüssel namens default key.
Access key heißt Zugangsschlüssel, also könnten wir den default key für den Zugriff aus Swagger einrichten. Besser ist aber verschiedene Schlüssel mit genau den Rechten, die gebraucht werden, für verschiedene Zugänge einzurichten. Also öffnen wir mit einem Klick auf manage keys die Schlüsselverwaltung.
Mit einem Klick auf generate new access key öffnet sich der Dialog zum Anlegen eines Schlüssels. Wir tragen als Name datastorage ein. (Der Name ist egal, hilft uns später, aber zu erkennen, wofür er gedacht ist.) Die Häkchen bei settings und devices löschen wir, damit mit diesem Schlüssel nur die Nachrichten zugänglich sind.
Ein Klick auf Generate Access Key legt den neuen Schlüssel an. Jetzt haben wir unseren access key für den Zugriff aus Swagger.
Wenn wir jetzt wieder auf den Reiter unserer Applikation klicken, finden wir ganz unten unseren neuen access key, den wir mit einem Klick auf das Kopieren-Icon in die Zwischenablage kopieren.
Authorisation in Swagger
Da wir jetzt den neuen access key in der Zwischenablage haben klicken wir oben rechts auf der Swagger-Seite auf Authorize und bekommen den Dialog zur Eingabe unseres Schlüssels angezeigt.
Hier fügen wir den Schlüssel aus der Zwischenablage ein. Mit dem Klick auf Authorize darf Swagger auf unsere Daten zugreifen.
Wenn wir jetzt wie oben auf Try it out! klicken bekommen wir ein Ergebnis. Das kann auch leer sein, wenn unser Sensor noch keine Daten geliefert hat. Man erkennt das am Response code 204.
Wenn der Sensor Daten geliefert hat, bekommt man als Response code 200 und das Ergebnis könnte so aussehen.
Schick! So können wir an unsere Daten aus dem Data Storage mit Swagger heran, aber bequem ist anders. Swagger ist eigentlich nur eine Testoberfläche. Das muss besser gehen.
Automatisierung
Die Daten bekommt man mit HTTP-GET-Request. Die Swagger-Seite gibt uns ein Beispiel, wie man mit dem Werkzeug curl die Daten aus dem Data Storage beziehen kann. Hat man auf seinem Rechner curl installiert (das haben die meisten Unix-artige Betriebssysteme), dann kann man die Zeile unter Curl in die Shell/Eingabeaufforderung kopieren und bekommt die Daten angezeigt.
curl -X GET --header 'Accept: application/json' \
--header 'Authorization: key ttn-account-v2.eK8RestGekuerzt' \
'https://mein-test.data.thethingsnetwork.org/api/v2/query'
Die Ausgabe kann man auch in eine JSON-Datei oder per Pipe an ein Programm zum Auswerten umleiten. Das ist aber ein eigenes Thema für einen Artikel. Da es nur ein HTTP-GET-Request ist, kann man die Abfrage aber auch direkt in seiner Lieblingsprogrammiersprache programmieren.
So kann man die Daten zum Beispiel in Python abfragen und als JSON ausgeben.
import urllib
# insert here the URL from the Swagger page
url = 'https://mein-test.data.thethingsnetwork.org/api/v2/query'
# insert here the duration you want to retrieve data for
args = '?last=2d'
# insert here the access key
access_key = 'ttn-account-v2.eK8RestGekuerzt'
headers = {
'Accept': 'application/json',
'Authorization': 'key ' + access_key
}
req = urllib.request.Request(url + args, headers=headers)
with urllib.request.urlopen(req) as f:
print(f.read().decode('utf-8'))
Für den Start in Python müssen Sie nur die beiden Werte für url und access_key an Ihre Applikation anpassen.
Fazit und Ausblick
Die Konfiguration des Data Storage im The Things Network ist nicht schwierig. Damit hebt The Things Network unsere Daten sieben Tage lang auf und wir können sie mit einem kleinen Programm leicht zum Auswerten herunterladen. Wer mag, kann die Daten danach in eine Excel- oder Calc-Datei umwandeln und damit auswerten. Daran habe ich aber zurzeit kein Interesse und werde diesen Pfad vorerst nicht weiter verfolgen. Mich interessiert mehr, wie ich in Python die Daten auswerten und darstellen kann. Das folgt in einem der nächsten Artikel.