This guide will help you to start working with the thingsHub IoT Middleware. You will learn ...

  1. How to setup a network connection to your LoRaWAN (server)

  2. How to pull device drivers from SmartMakers official driver registry

  3. How to assign a device driver to your device

  4. How to setup an MQTT integration to push device data to your business application

  5. How to visualize retrieved data from your IoT devices using the visualizer

To demonstrate the above we will use a simple Elsys Room Sensor which transfers its data using Loriot´s LoRaWAN Network (Server).

If you have any questions that are not covered by this guide, check out the rest of our documentation or reach out to our support team at https://help.smartmakers.io

Let’s get started.

Retrieve Access Token for thingsHub API

We take securing your IoT application seriously. In order to interact with the thingsHub API, clients need to authorize themselves using an access token. Detailed instructions for obtaining the access token are available in this documentation page: REST API

1) Set up the network connection to your LoRaWAN network (server)

All sensor / IoT device data is beeing retrieved using so-called network connectors. Such a connector is implemented to support specific features of the respective network server. In our example, we do want to use the Loriot Network by connecting to the Loriot Network Server. This can be done using the following REST-API endpoint

/api/v3/network-servers/connections
CODE

The thingsHub network connector for Loriot uses a Web Sockets based interface to receive uplinks from and send downlinks to LoRaWAN devices. As for the moment, we do only support paid / private Loriot accounts which allow using secure API-Keys for the communication. If you are using a free account please have a look at the documentation page Loriot Network Server to see if things have changed.

Within Loriots web user interface you have to create an API Key. Please follow these steps:

Enter a meaningful name into the field "Custom comment for key" and click on "Generate new API key". As you can see from the screenshot your new API key should appear in the list above the button.

Setup Network Server Connection


In a next step, you can use the following API endpoint to set up a connection to your network server. In our step by step example here please set "auto_activate" to "true" as we want existing or newly created devices in Loriot to be automatically created in thingsHub.

BODY JSON
AttributeDescription
auto_activateIf this is set to "true" thingsHub will check for each received uplink if the transmitting device is a known device in thingsHub and automatically create a new device record if this isn´t the case
config / api_keyYour Loriot API key
config / app_idID of the Loriot application which you want to receive data and send downlinks to devices 
config / serverHTTPS URL to your Loriot network server
nameName for your network server connection
type

Type of the network server connection

POST /api/v3/network-servers/connections
CODE

Create new Loriot network server connection

curl -v -X POST http://demo.thingshub.smartmakers.de/api/v3/network-servers/connections \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
-d '
{
      "auto_activate": true,
      "config": {
        "api_key": "<YOUR-API-KEY>",
        "app_id": "BE7A12B8",
        "server": "https://eu1.loriot.io"
      },
      "name": "Loriot LoRaWAN Network",
      "type": "loriot"
    }'
JS

2) Pull device drivers from SmartMakers official device driver registry

Each thingsHub instance / tenant have its own so-called Driver Registry. The driver registry is used to manage, rollout and distribute Device Drivers. You can import our carefully implemented device drivers from the official SmartMakers driver registry or build your own device drivers and use them in your thingsHub instance.

Pull device drivers from SmartMakers registry


In a fresh installation of thingsHub, the driver registry is empty. To import all drivers from the SmartMakers driver registry you can use the following API endpoint command:

URL PARAMETERS
ParameterDescription
?authorWill pull / download all drivers with the specified author
?nameWill pull / download all drivers with the specified author
POST /api/v3/registry/pull
CODE

Pull drivers from SmartMakers driver registry

curl -v -X POST http://demo.thingshub.smartmakers.de/api/v3/registry/pull?author=smartmakers \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR-ACCESS-TOKEN>"
JS

3) Assign the device driver to your room sensor

Since you set "auto_activate": true in the configuration (see above) your devices will be automatically registerd in thingsHub. For this to happen thingsHub would need to receive an uplink from each device which should get registered / auto activated.

If your application in Loriot does not contain any device yet you can follow the steps below to register an Elsys Room Sensor: If you already have a registered device you may continue with "Check if devices have been auto activated in thingsHub".

1) Click on "Import OTAA" if you want to register the device via OTAA

2) Enter the OTAA credentials from your device

3) Click on "Devices" to see the list of registered devices

4) Check if your device is sending uplinks by looking to the table "Last data (10 latest records)"

If your device send uplinks it will be auto-activated in thingsHub.

Check if devices have been auto activated in thingsHub


With the following API call you can see a list of known / registered devices in thingsHub:

GET /api/v3/devices
CODE

List all known / registered devices

curl -v -X GET "http://demo.thingshub.smartmakers.de/api/v3/devices" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR-ACCESS-TOKEN>"
JS

The rest API call above should lead to a json result showing you the newly OTAA registered device from Loriot in thingsHub:

{
  "collection": [
    {
      "driver": "",
      "id": 4,
      "labels": null,
      "name": "",
      "ns_connection_id": 4,
      "ns_device_id": "A81758FFFXXXXXX",
      "state": {
        "desired": {},
        "reported": {
          "RawPayload": "0100f0021c040097050006037a070e4f"
        }
      }
    }
  ]
}
JS

As you can see the driver is not set but the state does show the latest received "RawPayload" from the device.

Assign a device driver to this device


Using the following API endpoint you can assign the "Elsys ERS Lite" device driver from your driver registry. Read more on how to find the right device driver on the following documentation page: Device Drivers & Driver Repository.


Make sure you have set {id} to the devices id in your thingsHub. 

This API call should lead to a json result showing the newly assigned device driver for your device:

{
  "driver": "smartmakers/elsys-ers-lite:latest",
  "id": 4,
  "labels": null,
  "name": "thingsHub Documentation Elsys Room Sensor",
  "ns_connection_id": 4,
  "ns_device_id": "A81758FFFXXXXXX",
  "state": {
    "desired": {},
    "reported": {
      "RawPayload": "0100f4021c0400730501060392070e4f"
    }
  }
}
CODE

Check if the device driver works

If you have been assigning the correct device driver for the device which you are using in this tutorial, thingsHub will be able to decode the next incoming uplink and start building up what we call the Device Reported State. In addition to this Device State the system will forward decoded data to third party systems using Integrations like MQTT, Websockets and many others.

Here is an example how the device state for our demo device does look like after we assigned the correct device driver:

{
  "driver": "smartmakers/elsys-ers-lite:latest",
  "id": 4,
  "labels": null,
  "name": "thingsHub Documentation Elsys Room Sensor",
  "ns_connection_id": 4,
  "ns_device_id": "A81758FFFXXXXXX",
  "state": {
    "desired": {},
    "reported": {
      "RawPayload": "0100f7021c04004a0502060404070e4f",
      "co2": 1028,
      "humidity": 28,
      "light": 74,
      "motion": 2,
      "temperature": 247,
      "vdd": 3663
    }
  }
}
CODE

As you can see all data from the devices sensors like temperature and humidity have been exposed as fields in the reported device state.

PUT /api/v3/devices/{id}
CODE

Create new Loriot network server connection

curl -v -X PUT http://demo.thingshub.smartmakers.de/api/v3/devices/4 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
-d '{
  "driver": "smartmakers/elsys-ers-lite:latest"
}'
JS

4) Setup MQTT integration to push device data to your business application

Last but not least you want to use an system like thingsHub to connect IoT devices to the IT systems and applications you are already using or building. For this purpose thingsHub does provide so called Integrations which allow to send data from one or many devices to one or many systems. Use labels to group your devices and use these labels as the selection mechanism in the integration.

Assign labels to your device


Using the devices API endpoint with a PUT command you can create and assign labels to you device.   

PUT /api/v3/devices/{id}
CODE

Adding labels to a device

curl -v -X PUT http://demo.thingshub.smartmakers.de/api/v3/devices/3 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
-d '{
  "labels": [
    {
      "key": "label-1",
      "value": "label-1-value"
    },
    {
      "key": "label-2",
      "value": "label-2-value"
    }
  ]
}'
JS

This API call should lead to a json result showing the newly assigned labels on your device:

{
  "id": 3,
  "labels": [
    {
      "id": "label-1:label-1-value",
      "key": "label-1",
      "value": "label-1-value"
    },
    {
      "id": "label-2:label-2-value",
      "key": "label-2",
      "value": "label-2-value"
    }
  ],
  "name": "thingsHub Demo Device",
  "ns_connection_id": 2,
  "ns_device_id": "A81758FFFE036518",
  "state": {
    }
  }
}
CODE


Create MQTT integration



POST /api/v3/integrations
CODE

Adding labels to a device

curl -v -X POST http://demo.thingshub.smartmakers.de/api/v3/integrations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
-d '{
  "name": "thingsHub Documentation Integration",
  "type": "MQTT"
}'
JS

Use labels in your integration


To select the devices your integration will publish data from you can use the previously assigned label of your devices as a selector. Do the following to select all devices using the label "label-1": "label-1-value".

PUT /api/v3/integrations/{id}
CODE

Adding labels to a device

curl -v -X POST http://demo.thingshub.smartmakers.de/api/v3/integrations/3 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
-d '{
 "labels": [
   {
     "key": "label-1",
     "value": "label-1-value"
   }
 ]
}'
JS

Connect via a MQTT client


When creating MQTT integrations thingsHub automatically set up a topic your MQTT client can connect to. To see what topic name thingsHub have created you can use the following REST call:



The result will look like this:

{
  "id": 1,
  "labels": [
    {
      "id": "network-connector:loriot-thingshub-demo",
      "key": "network-connector",
      "value": "loriot-thingshub-demo"
    }
  ],
  "name": "thingsHub Documentation MQTT Demo",
  "params": {
    "topic": "thingshub_documentation_mqtt_demo-1",
    "url": "demo.thingshub.smartmakers.de"
  },
  "type": "MQTT"
}
CODE

The fields "topics" and "urls" do show you where to connect. In this example you would need to set your MQTT client to:




Adding labels to a device

curl -v -X PUT http://demo.thingshub.smartmakers.de/api/v3/devices/3 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR-ACCESS-TOKEN>"
JS