The Things Stack & Network (TTS, TTN)#

About#

Receive and decode telemetry data from devices on the LoRaWAN network controller implementation The Things Stack (TTS) / The Things Network (TTN), using HTTP webhooks, and store it into timeseries databases for near real-time querying.

The Things Network logo

Overview#

%%{init: {"flowchart": {"defaultRenderer": "dagre", "htmlLabels": false}} }%% flowchart LR subgraph sensors [sensor domain] direction LR Device end subgraph network [The Things Network] direction TB TTS[The Things Stack\nLoRaWAN Network Server] TTS -.-> Webhook[HTTP Webhook] end subgraph backend direction LR Kotori --> InfluxDB Kotori --> Grafana end sensors -.- RF/ISM/LoRaWAN -.-> network network ==> backend

Background#

The TTS documentation states that their long-term data storage feature is not suitable for real-time querying.

The TTS Storage Integration should not be used for querying realtime data. For scalability reasons, writes to the Storage Integration database are performed in batches and there may be a delay after an uplink is received, before it is available. For realtime alerts, use Webhooks.

Glossary#

The Things Stack (TTS):

A robust, yet flexible LoRaWAN Network Server for demanding LoRaWAN deployments, from covering the essentials to advanced security configurations and device life cycle management.

The Things Network (TTN):

An open community-based initiative to build a low-power, wide-area network for the Internet of Things.

TTS Webhooks:

Allows The Things Stack to send application related messages to specific HTTP(S) endpoints.

Setup#

Getting the system configured properly is important, please read this section carefully.

Creating a custom webhook#

You will need to use The Things Network Console at https://console.cloud.thethings.network/, in order to configure a custom Webhook.

On the custom webhook configuration dialog, please enter the following settings:

  • Webhook ID

    An arbitrary label identifying the Webhook.

  • Webhook format

    Choose JSON here.

  • Base URL

    Like outlined at the HTTP documentation section, this setting will obtain the full URL to the data acquisition channel, modulo the /data suffix, which will be added per “Enabled event types” configuration option.

  • Filter event data

    If you want to filter the submitted telemetry payload, and only submit the nested decoded_payload data structure, you can use a path accessor expression like up.uplink_message.decoded_payload. Check out all available filter paths.

  • Enabled event types

    For the event type Uplink message, add the URL path suffix /data.

This screenshot of the corresponding dialog in TTS guides you which parameters to configure correspondingly.

The Things Network Console Webhook configuration

The Things Network Console Webhook configuration#

Important

If you want to receive the full TTN message payload, in order to decode additional metadata, for example gateway information, please leave the Filter event data field empty.

Now, when the TTN infrastructure receives uplink messages from your device(s), they will be delivered to the configured HTTP endpoint in JSON format. Kotori will decode those messages transparently.

Single-device connectivity#

If you only want to connect a few devices, and want to configure individual webhooks for them, you may find it acceptable to create a dedicated TTS Application per device.

A corresponding set of example default values, when using the “wide” channel addressing scheme, in order to dispatch messages to channels of individual devices, would be:

Webhook ID:             expert-bassoon
Webhook format:         JSON
Base URL:               https://daq.example.org/api/sensorwan-1/testdrive/area42/node1
Filter event data:      up.uplink_message.decoded_payload
Enabled event types:    /data

Note

With this configuration variant, you will configure the full-qualified SensorWAN address within the “Base URL” field of your application.

Multi-tenant connectivity#

The multi-tenant connectivity option allows you to use a single TTS Application to serve multiple SensorWAN 3.0 networks, in order to support a fleet of devices, without needing to create individual, per-device webhooks.

This is a corresponding set of example default values, when using the “direct” channel addressing scheme, in order to multiplex channels of different devices using a single HTTP endpoint, effectively implementing trunking data acquisition:

Webhook ID:             fuzzy-carnival
Webhook format:         JSON
Base URL:               https://daq.example.org/api/sensorwan-1/channel{/devID}
Filter event data:
Enabled event types:    /data

Note

This example uses a single webhook configuration based on using the {/devID} path variable within the “Base URL” field of your application. You can learn about other path variables at TTS Webhook Path Variables.

It also leaves the “Filter event data” field empty, so you will receive full payloads, including metrics from gateways, etc.

Dry-run examples#

By using the following examples, you can exercise the transmission procedure within a dry-run environment / sandbox.

{
  "uplink_message": {
    "decoded_payload": {
      "temperature_1": 53.3,
      "voltage_4": 3.3
    }
  }
}

Acquire and submit a minimal TTN JSON payload to Kotori’s HTTP API.

wget https://github.com/daq-tools/kotori/raw/main/test/test_tts_ttn_minimal.json
cat test_tts_ttn_minimal.json | \
    http POST https://daq.example.org/api/sensorwan-1/testdrive/area42/node1/data

Acquire and submit a full TTN JSON payload to Kotori’s HTTP API.

wget https://github.com/daq-tools/kotori/raw/main/test/test_tts_ttn_full.json
cat test_tts_ttn_full.json | \
    http POST https://daq.example.org/api/sensorwan-1/testdrive/area42/node1/data

Note

Addressing the same channel using the “direct” variant means replacing
/testdrive/area42/node1 by
/channel/testdrive-area42-node1.

A full-qualified URL example is:

https://daq.example.org/api/sensorwan-1/channel/testdrive-area42-node1/data

Tip

For submitting JSON data to the HTTP endpoint of Kotori, the examples above are using the excellent HTTPie program. Note that the same requests can also be submitted by using the curl program, or any other HTTP client.

Grafana screenshot#

This is an example screenshot of a Grafana dashboard, which demonstrates the outcome of LoRaWAN transmissions.

LoRaWAN/TTN Grafana example dashboard