Documentation

Integrations / Connection guides / The Things Stack

The Things Stack

The Things Stack provides an open-source network where LoRaWAN devices can be connected. The Things Network and the Things Industries are both using The Things Stack, this connection guide is relevant in both cases. The Blockbax Platform provides a native integration with The Things Stack, such that your devices can publish measurements to your Blockbax project.

Goal

The goal is to configure a device via The Things Network to publish measurements to Blockbax.

Prerequisites
  1. Blockbax project
  2. The Things Network account or The Things Industries account
Preparing an inbound connector in Blockbax

Before we can setup communication to Blockbax we first have to setup an inbound connector in Blockbax. This wil be used as an endpoint where the incoming payload is converted and ingested into Blockbax.

  1. Open the Blockbax web app and go to ‘Settings’ -> ‘Inbound connectors’.

  2. Press the ‘+’ icon or ‘Create inbound connector’ button.

  3. Configure the inbound connector with the HTTP POST ‘Protocol’ and JSON ‘Payload format’.

  4. The payload conversion script depends on the way the payload is formatted before it is being sent to Blockbax. By default when you add a known device in The Things Stack it comes with a payload formatter submitted by the device manufacturer from the device repository. In most cases data is returned as a simple JavaScript object containing numeric and text values as properties.

    In this case everything will work with the simple conversion script below. If not, you need to align the payload conversion script to the way your device formatter(s) output the payload. We will explain how to do this later. In any case it is a good starting point to start with the following script in your inbound connector.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    
    /**
     * @param {JsonPayload} payload
     * @param {Context} context
     */
    function convertPayload(payload, context) {
        const timestamp = date(payload.received_at);
        const subjectExternalId = payload.end_device_ids.device_id;
        for (const [metricExternalId, value] of Object.entries(payload.uplink_message.decoded_payload)) {
            if (value != null) {
                context.addMeasurement(subjectExternalId + "$" + metricExternalId, value, timestamp);
            }
        }
    }
    
  5. Optionally you can check ‘Automatically create subjects’. This will create a subject automatically if a subject does not exist.

  6. Press ‘Save Changes’.

  7. Copy the ‘Endpoint’ to your notes, you will need it for for configuring the The Things Stack later on.

Create a webhook in The Things Stack

Now we can create a webhook in The Things Stack to forward device payload to Blockbax.

  1. Go to The Things Network Console or The Things Industries Console and go to your application.

  2. In the left menu select ‘Integrations’ and ‘Webhooks’.

  3. Click on ‘Add webhook’ and select the ‘Custom webhook’ tile.

  4. Enter the information according to the table below.

    Field Value
    Webhook ID Your own identifier (enter an arbitrary value)
    Webhook Format JSON
    Base URL Your inbound connector endpoint that you noted during the preparation
    Additional Headers Add a header entry with name Authorization and the value ApiKey <ACCESS_TOKEN_SECRET> from your access token.
  5. At ‘Enabled event types’ make sure to tick the checkbox at ‘Uplink message’ without specifying a path.

Further set up your Blockbax project

Once you’ve added the webhook, payload are sent to Blockbax. Now we are going to create a subject type which matches your device type(s) and further align your inbound connector if necessary.

  1. Make sure your The Things Stack device is connected and has sent at least one payload.

  2. Open the inbound connector you created in the previous step.

  3. In the ‘Executions’ section expand the latest execution.

    As an example we use the Oyster of Digital Matter, but you should see something similar to the execution logs below.

    Example execution logs from an Oyster device from Digital Matter

    In Blockbax ingestion IDs are used to map The Things Stack data to your subjects and metrics. By default ingestion IDs are derived from the subjects’ external IDs and metrics’ external IDs (e.g. subjectExternalId$metricExternalId) but you can also override these with custom ones. The inbound connector script configured in the previous step combines your device ID from The Things Stack and the property name returned by the payload formatter(s) into an ingestion ID (e.g. example-device$type). This allows for easy setup if you make sure your subject external IDs and metric external IDs match the ones you configure in Blockbax.

  4. Create a subject type with a metric of the correct type for each external ID in your execution logs.

    For this example you would need to create ingested metrics with the following types and external IDs (highlighted also in the screenshot of the execution logs above):

    Type External ID
    Text type
    Number inTrip
    Number batV
    Number fixFailed
    Location latLonDeg*
    Number headingDeg
    Number speedKmph
  5. If you have enabled the setting to automatically create subjects in the inbound connector they will be created automatically when measurements are received and the metric external ID can be linked to one subject type. If you wish to create subjects manually the subject’s external IDs need to match the device IDs configured in The Things Stack. For this example that would be a subject with external ID example-device.

  6. (*) As you might have noted the latLonDeg external ID is not highlighted in the execution logs. This is because we do not to have the latitudeDeg and longitudeDeg as separate number metrics but as a location metric. In this way you are able to use the full location-based functionality in the Blockbax Platform such as viewing routes and setting geofences. You can do this by changing the conversion script to the one below.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    
    /**
     * @param {JsonPayload} payload
     * @param {Context} context
     */
    function convertPayload(payload, context) {
        const timestamp = date(payload.received_at);
        const subjectExternalId = payload.end_device_ids.device_id;
        const location = {};
        for (const [metricExternalId, value] of Object.entries(payload.uplink_message.decoded_payload)) {
            if (value != null) {
                if (metricExternalId === "latitudeDeg") {
                    location.lat = value;
                } else if (metricExternalId === "longitudeDeg") {
                    location.lon = value;
                } else {
                    context.addMeasurement(subjectExternalId + "$" + metricExternalId, value, timestamp);
                }
            }
        }
        if (location.lat && location.lon) {
            context.addMeasurement(subjectExternalId + "$" + "latLonDeg", location, timestamp);
        }
    }
    

Now you are all set up, check your Blockbax project to see the measurements coming in!

Digital Matter Oyster2 in Blockbax

If you are familiar with JavaScript another option to determine the external IDs for the ingested metrics is to look at the source code of the device specific payload formatter. In this case you are also sure you do not miss any metrics which are only sent under certain conditions.

In our example we used the Oyster of Digital Matter. The source code for the related payload formatter can be found here. The property names of the `decoded` object should be set as metric external IDs.