Stop the war

Stand with Ukraine flag

Support Ukraine
Try it now Pricing
Professional Edition
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Getting Started
Devices Library Guides Installation Architecture API FAQ
On this page

ChirpStack Integration

Doc info icon
ThingsBoard PE Feature

Only Professional Edition supports Platform Integrations feature.
Use ThingsBoard Cloud or install your own platform instance.

Overview

The ChirpStack open-source LoRaWAN Network Server stack provides open-source components for LoRaWAN networks.
After integrating ChirpStack with ThingsBoard, you can connect, communicate, process and visualize data from devices in the ThingsBoard IoT platform.

ChirpStack configuration

In order to get data you should have configured instance of ChirpStack Network server stack.
In this guide we will use the configured local instance, installed by docker compose. How to install ChirpStack Network server stack using docker compose.
Also, we have connected device, how to connect it you can find in Connection guide from the official site.
When device connected and the data appears in the DEVICE DATA tab - we can start to configure the integration to the ThingsBoard.

Before creating the integration, you need to create an Uplink converter in Data converters. Uplink is necessary in order to convert the incoming data from the device into the required format for displaying them in ThingsBoard. Click on the “plus” and on “Create new converter”. To view the events, enable Debug. In the function decoder field, specify a script to parse and transform data.

NOTE Although the Debug mode is very useful for development and troubleshooting, leaving it enabled in production mode may tremendously increase the disk space, used by the database, because all the debugging data is stored there. It is highly recommended to turn the Debug mode off when done debugging.

Create uplink converter
Create uplink converter

Let’s review sample uplink message from ChirpStack:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
    "applicationID": "1",
    "applicationName": "Application",
    "deviceName": "Device_1",
    "devEUI": "e3EP8SqeZiw=",
    "rxInfo": [],
    "txInfo": {
        "frequency": 868100000,
        "modulation": "LORA",
        "loRaModulationInfo": {
            "bandwidth": 125,
            "spreadingFactor": 10,
            "codeRate": "4/5",
            "polarizationInversion": false
        }
    },
    "adr": false,
    "dr": 2,
    "fCnt": 22,
    "fPort": 2,
    "data": "GVAy",
    "objectJSON": "",
    "tags": {},
    "confirmedUplink": false,
    "devAddr": "AJTrGg==",
    "publishedAt": "2021-09-17T13:45:00.342008687Z"
}

As you can see the device name arrives in the “deviceName” field. We will use it as a device name in ThingsBoard. Device data is encoded in the “data” field. The Base64 encoded data here is:

1

"data": "GVAy"

Let’s convert them into flags, battery and light values.

In the decoded form we have the following string: 258050

25 is the value for flags.
80 is the value for battery.
50 is the value for light.

In the converter it will be indicated like this:

1
2
3

var flags = parseInt(incomingHexData.substring(0, 2), 16);
var battery = parseInt(incomingHexData.substring(2, 4), 16);
var light = parseInt(incomingHexData.substring(4, 6), 16);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

// Decode an uplink message from a buffer
// payload - array of bytes
// metadata - key/value object

/** Decoder **/

// decode payload to string
var payloadStr = decodeToString(payload);

// decode payload to JSON
var data = decodeToJson(payload);

var deviceName = data.deviceName;
var deviceType = data.applicationName;

var incomingHexData = base64ToHex(data.data);
var flags = parseInt(incomingHexData.substring(0, 2), 16);
var battery = parseInt(incomingHexData.substring(2, 4), 16);
var light = parseInt(incomingHexData.substring(4, 6), 16);

var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {
       applicationId: data.applicationId,
       DevEUI: base64ToHex(data.devEUI),
       integrationName: metadata['integrationName'],
       txInfo: data.txInfo,
       fPort: data.fPort,
       devAddr: base64ToHex(data.devAddr),
       dr: data.dr
   },
   telemetry: {
       flags: flags,
       battery: battery,
       light: light
   }
};

/** Helper functions **/

function decodeToString(payload) {
   return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
   // covert payload to string.
   var str = decodeToString(payload);

   // parse string to JSON
   var data = JSON.parse(str);
   return data;
}

function base64ToHex(str) {
  var raw = atob(str);
  var res = "";
  for (var i = 0; i < raw.length; i++) {
    var hex = raw.charCodeAt(i).toString(16);
    res += (hex.length === 2 ? hex : '0' + hex);
  }
  return res.toUpperCase();
}

return result;

You can change the decoder function while creating the converter or after creating it. If the converter has already been created, then click on the “pencil” icon to edit it. Copy the configuration example for the converter (or your own configuration) and insert it into the decoder function. Save changes by clicking on the “checkmark” icon.

Create Integration

To create integration on ThingsBoard we need the following parts:

  • Uplink converter
  • Application server url
  • Application API key from application server

To get the API key we need to open Application server UI, open API keys tab from the left top menu and create an API key.

Open API keys
Open API keys
Create API key
Create API key
Copy created API key
Copy created API key

Now that the Uplink converter has been created, and we have all required data, it is possible to create an integration.

NOTE: It is recommended to enable Debug mode for debug purposes to see uplink/downlink events on integration.

Create integration
Create integration

In order for data to be transferred from ChirpStack to ThingsBoard, you need to configure an Integration for your ChirpStack application.
To create integration on ChirpStack Network server stack, we need to do the following steps:

  1. Login to ChirpStack Network server stack user interface (Default login/password - admin/admin).
  2. We go to the tab Applications in the left menu and open our application (our application is named Application).
  3. Open the Integrations tab and create a HTTP integration.
  4. Let`s go to the Integrations tab in ThingsBoard. Find your ChirpStack integration and click on it. There you can find the HTTP endpoint URL. Click on the icon to copy the url.
  5. Fill the fields with endpoint url from ThingsBoard integration.
Create integration
Create integration
Set integration name and endpoint url
Set integration name and endpoint url

When device sends uplink message, you will receive an uplink event on integration and data from the device.

The created device with data can be seen in the section Device groups -> All

Device Device_1 was created
Device **Device_1** was created

Received data can be viewed in the Uplink converter. In the “In” and “Out” blocks of the Events tab:

Example of incoming data to converter from ChirpStack
Example of incoming data to converter from ChirpStack
Example of outgoing data from converter
Example of outgoing data from converter

Use the Dashboards to work with data. Dashboards are a modern format for collecting and visualizing data sets. Visibility of data presentation is achieved through a variety of widgets.

ThingsBoard has examples of several types of dashboards that you can use. You can find them in Solution templates tab.

How to work with dashboards read here

Create Downlink in Data converters. To see events - enable Debug.

You can customize the downlink according to your configuration.
Let’s consider an example where we send an attribute update message. So we should change code in the downlink encoder function under line //downlink data input`

1

data: msg.downlink

Also, indicate the required parameters in the metadata:

1
2
3
4

metadata: {
  "EUI": "$Device_EUI",
  "port": 1
}

Example for downlink converter:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// Encode downlink data from incoming Rule Engine message

// msg - JSON message payload downlink message json
// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
// metadata - list of key-value pairs with additional data about the message
// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter

/** Encoder **/

// Result object with encoded downlink payload
var result = {

    // downlink data content type: JSON, TEXT or BINARY (base64 format)
    contentType: "TEXT",

    // downlink data
    data: btoa(msg.downlink),

    // Optional metadata object presented in key/value format
    metadata: {
            DevEUI: metadata.cs_DevEUI,
            fPort: metadata.cs_fPort
    }

};

return result;

Where DevEUI is device EUI, it will be taken from the device uplink message.
A fPort can be from 1 to 223, it will be taken from the device uplink message.

Add a converter to the integration.
You can do this at the stage of creating an integration or editing it.

In order to send Downlink, we use the rule chain to process shared attribute update.
To get fPort and DevEUI from device we have to import rule-chain.
You can find it here.

Import downlink rule-chain
Import downlink rule-chain
Open integration downlink rule node configuration by pressing on pencil
Open integration downlink rule node configuration by pressing on pencil
Select your integration from the list, save rule node by pressing
Select your integration from the list, save rule node by pressing
Save rule chain by pressing on checkmark
Save rule chain by pressing on checkmark

Also, we have to configure the root rule-chain:

Add check relation rule-node
Add check relation rule-node
Configure check relation rule-node
Configure check relation rule-node
Add rule-chain rule node, set the newly imported rule chain and save it by pressing on pencil icon
Add rule-chain rule node, set the newly imported rule chain and save it by pressing on pencil icon
Add "True" relation to rule-chain node from check relation rule-node
Add **"True"** relation to rule-chain node from check relation rule-node
Save root rule-chain
Save root rule-chain

We go to the Device group section in the All folder, to see this with an example.
We have indicated the downlink of the device in the Shared attributes.
Now we edit it by clicking on the “pencil” icon.
Then we make changes to the attribute (change the downlink to 01040206) and save the data.

Received data and data that was sent can be viewed in the downlink converter. In the “In” block of the Events tab, we see what data entered and the “Out” field displays messages to device:

Example of input to downlink converter
Example of input to downlink converter
Example of output from downlink converter
Example of output from downlink converter

Next steps