Ubidots ist ein Cloud-Dienst zur Darstellung von Sensor-Daten. Bekanntlich speichert das LoRaWAN-Netzwerk TTN keine Daten, sondern transportiert diese nur zu einem definierten Cloud-Dienst wie zum Beispiel Ubidots weiter. Erst dort werden Daten vom Sensor angezeigt und dargestellt. In diesem Artikel geht es um die Einrichtung der Webhook-Schnittstelle zwischen TTN (The Things Stack) und Ubidots.

Was kann Ubidots?

Ubidots sammelt über verschiedene Schnittstellen Daten von IoT-Geräten. Diese Daten werden von Ubidots gespeichert und in einem Dashboard grafisch dargestellt. Zusätzlich können über einzelne Werte auch Verlaufskurven erstellt werden. Grundsätzlich ist Ubidots STEM für den privaten Gebrauch und für Ausbildungszwecke mit bis zu drei Geräten kostenlos.

Voraussetzungen

Damit Ubditos Daten von TTN entgegennehmen kann, muss der Sensor bereits mit TTN kommunizieren. Außerdem muss ein entsprechender Payload-Decoder vorhanden sein. Als Beispiel für dieses Projekt wurde das LoRIS-Base System von ELV mit dem Temp-Hum1 Modul verwendet. Weitere Informationen dazu gibt es in diesem Video sowie auf der ELV Homepage.

1. TTN Plugin einfügen

Nach der Registrierung bei Ubditos wird unter dem Menüpunkt “Devices -> Data Plugin” ein neues TTN (The Things Stack) Plugin eingefügt:

2. Plugin Token

Der Token ist ein Schlüssel für die Schnittstelle. Dadurch wird sichergestellt, dass in diesem Fall nur TTN Daten an Ubidots senden kann. Mit der Registrierung wird automatisch ein Default-Token erstellt, der verwendet werden kann:

3. Plugin Name

Dem Data-Plugin kann ein Name sowie eine Beschreibung zugewiesen werden:

4. Data Plugin

Das Plugin ist direkt nach der Erstellung betriebsbereit. Als Nächstes wird das Plugin bearbeitet, um die für TTN Notwendigen Schlüssel zu bekommen:

5. Plugin-Übersicht mit Endpoint-URL

Die Endpoint-URL ist jene URL, über welche TTN die Nutzdaten an Ubidots übergibt. Wichtig ist dabei der Schlüssel am Ende der URL, denn der wird bei TTN im Webhook eingefügt:

6. Auth Token

Der Auth-Token wird ebenfalls bei TTN in das Ubditos-Webhook eingefügt. Es handelt sich dabei (wenn nicht anders gewählt) um den Default-Token:

7. Decoder anpassen

Ubdiots kann die LoRaWAN-Payload über den eigenen Decoder decodieren. Da TTN die Payload bereits decodiert und im JSON-Format an Ubidots übergibt, muss der interne Decoder deaktiviert werden. Dazu wird Zeile 37 auskommentiert und die Zeilen 41, 42 kommentiert:

Alternativ kann auch folgender Decoder eingesetzt werden:

function format_payload(args){
  var ubidots_payload = {};
  // Log received data for debugging purposes:
  // console.log(JSON.stringify(args));
  // Get RSSI and SNR variables using gateways data:
  var gateways = args['uplink_message']['rx_metadata'];
  for (const i in gateways) {  
    // Get gateway EUI and name
    var gw = gateways[i];
    var gw_eui = gw['gateway_ids']['eui'];
    var gw_id = gw['gateway_ids']['gateway_id'];
    // Build RSSI and SNR variables
    ubidots_payload['rssi-' + gw_id] = {
      "value": gw['rssi'],
      "context": {
        "channel_index": gw['channel_index'],
        "channel_rssi": gw['channel_rssi'],
        "gw_eui": gw_eui,
        "gw_id": gw_id,
        "uplink_token": gw['uplink_token']
      }
    }
    ubidots_payload['snr-' + gw_id] = gw['snr'];

  }
  
  // Get Fcnt and Port variables:
  ubidots_payload['f_cnt'] = args['uplink_message']['f_cnt'];
  ubidots_payload['f_port'] = args['uplink_message']['f_port'];
  
  // Get uplink's timestamp
  ubidots_payload['timestamp'] = new Date(args['uplink_message']['received_at']).getTime(); 
  
  // If you're already decoding in TTS using payload formatters, 
  // then uncomment the following line to use "uplink_message.decoded_payload".
  // PROTIP: Make sure the incoming decoded payload is an Ubidots-compatible JSON (See https://ubidots.com/docs/hw/#sending-data)
   var decoded_payload = args['uplink_message']['decoded_payload'];
 
  // By default, this plugin uses "uplink_message.frm_payload" and sends it to the decoding function "decodeUplink".
  // For more vendor-specific decoders, check out https://github.com/TheThingsNetwork/lorawan-devices/tree/master/vendor

  // Merge decoded payload into Ubidots payload
  Object.assign(ubidots_payload, decoded_payload);
  return ubidots_payload
}

module.exports = { format_payload };

8. TTN Webhook Ubidots

Nachdem Endpoint-URL und Token bekannt sind, wird bei TTN in der Application eine Webhook-Integration eingerichtet:

9. Keys einfügen

TTN benötigt jetzt die Plugin-ID (siehe Punkt 5) und den Ubidots-Token (siehe Punkt 6). Anschließend wird der Webhook angelegt:

10. Keys überprüfen

Sonderzeichen werden beim Kopieren oft umformatiert. Daher sollten beide Schlüssel nochmals überprüft werden:

11. Sensor bei Ubidots anzeigen

Sobald neue Daten vom Sensor bei TTN ankommen, werden diese ab sofort an Ubidots gesendet. Ubditos legt dazu automatisch ein neues Gerät an:

12. Sensor anzeigen

Klickt man auf das neue Gerät, so werden alle verfügbaren Werte angezeigt:

13. Dashboard mit Widgets

Auf der Startseite wird ein neues Dashboard erstellt, wo nur die gewünschten Daten angezeigt werden. Für jeden Messwert gibt es dazu verschiedene Widgets zur Auswahl:

14. Dashboard für LoRIS Base

Nachdem das Dashboard mit den Widgets nach den eigenen Bedürfnissen eingerichtet wurde, kann das folgendermaßen aussehen: