How to communice Dragino -NB and -CB series devices data by MQTT with Thingseye

Version 4.1 by Alec Chen on 2025/04/02 16:30

Table of Contents:

1. Introduction

This document guides you on integrating Dragino -NB and -CB series devices data with Thingseye.

The NB series devices end with the suffix -NB, and the CB series devices end with the suffix -CB. For example, S31B-NB is an NB device, and S31-CB is a CB device.

2. Prerequisites

To complete this tutorial, you need to have certificate files. lns1.thingseye.io is the Dragino's MQTT broker, which requires a CA certificate file, Certificate file, and the Private key file to use.

If customers need to use this MQTT connection with Thingseye, they need to contact TE team to obtain three license files or click this link to download the certificates..

ins1.png

3.General MQTT Connection

The NB-IoT Sensor can send packet to server use MQTT protocol. 

Below are the commands.

AT Commands:

AT+PRO=3,0                           //  Set to use MQTT protocol to uplink, Payload Type select Hex payload.
AT+SERVADDR=120.24.4.116,1883        //  Set MQTT server address and port
AT+CLIENT=CLIENT                     //  Set up the CLIENT of MQTT
AT+UNAME=UNAME                       //  Set the username of MQTT
AT+PWD=PWD                           //  Set the password of MQTT
AT+PUBTOPIC=NSE01_PUB                //  Set the sending topic of MQTT
AT+SUBTOPIC=NSE01_SUB                //  Set the subscription topic of MQTT

image-20230802112413-4.png

image-20230802112413-5.png

Notice: MQTT protocol has a much higher power consumption compare with UDP/CoAP protocol. Please check the power analyze document and adjust the uplink

period to a suitable interval.

4. Data Converters

In Thingseye, Data Converters are components used to transform incoming or outgoing data between different formats, typically to convert raw telemetry data from devices into a structured format that Thingseye can understand, or vice versa.

In the left navigation, click Integrations center, and then click Data converters.

On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.

1743578461281-635.png

The Add data converter window will appear.

Let's create an uplink data converter for the device named 'Device A'. Name it ‘MQTT Uplink Converter - Device A’ and select the Type as Uplink.

Click on the TBEL button if it has not been selected by default.

Modify the default TBEL function to match with your device as described below:

  • Uncomment line 11:

var data = decodeToJson(payload)

  • Line 13: Assign your device name to the deviceName field. - We used Device A as it is to match with our device, Device A in the Devices section.
  • From line 38: Modify the telemetry section to allow parsed data to be assigned to the fields.

telemetry: {
       temperature: data.temperature,
       humidity: data.humidity,
       rawData: payloadStr
   }

The modified uplink decoder function to match with Device A is shown below.

// 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 = 'Device A';
var deviceType = 'thermostat';
var customerName = 'Customer C';
var groupName = 'thermostat devices';
var manufacturer = 'Example corporation';
// use assetName and assetType instead of deviceName and deviceType
// to automatically create assets instead of devices.
// var assetName = 'Asset A';
// var assetType = 'building';

// Result object with device/asset attributes/telemetry data
var result = {
// Use deviceName and deviceType or assetName and assetType, but not both.
  deviceName: deviceName,
   deviceType: deviceType,
// assetName: assetName,
// assetType: assetType,
// customerName: customerName,
  groupName: groupName,
   attributes: {
       model: 'Model A',
       serialNumber: 'SN111',
       integrationName: metadata['integrationName'],
       manufacturer: manufacturer
   },
   telemetry: {
       temperature: data.temperature,
       humidity: data.humidity,
       rawData: payloadStr
   }
};

/** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/

return result;

Once you modify the decoder function, click on the Add button.

ul-data-converter-device-a.png

You should see that the newly added MQTT Uplink converter NB/CB is listed on the Data Converters page.

ul-data-converter-added.png

5. Add Integration

5.1. Creat new MQTT integration

In the left navigation, click Integrations center, and then click Integrations.

On the Integrations page, click on the '+' button.

1743578691561-822.png

The Add integration window appears.

In the Add integration window, configure the following settings:

Basic settings:

  • Integration type: MQTT
  • Name: MQTT integration
  • Enable integration: YES
  • Debug mode：YES
  • Allows create devices or assets: YES

Click Next button.

1743578960106-916.png

Uplink/downlink  data converter:

  • Next, directly select to create a new Uplink data converter .

Click Next button.

1743581191958-140.png

Downlink data converter:

  • Next, directly select to create a new Uplink data converter .

Click Skip button.

1743581287837-189.png

Connection:

  • Host: lns1.thingseye.io
  • Port: 8883
  • Credentials : PEM(Paste 3 certificates to boxs below)Click this link to download the certificates.
  • Password: Password or nothng
  • Enable SSL: YES
  • Topic:  It needs to align with the device's topic.
  • QoS: 0-At most once or an MQTT QoS level

Click Skip button.

1743579352961-586.png

1743580606618-281.png

Click on the Add button.

You should see that the newly added integration is listed on the Integrations page.

Since we haven't received data from a device yet, the integration Status is shown as Pending,  Active  instead if it have.

5.2. Setup uplink and downlink converters

First, you need to download the MQTT uplink/downlink JS code.

  • Uplink Converter

The purpose of the decoder function is to parse the incoming data and metadata to a format that ThingsBoard can consume. 

Go to the Integrations center -> Data converters page, and find that MQTT uplink converter that was newly created when the integration was created.

1743581830822-223.png

Enter edit mode and apply MQTT uplink JS code to this uplink converter.

1743581965585-763.png

  • Downlink Converter

Go to the Integrations center -> Data converters page, and find that MQTT downlink converter that was newly created when the integration was created.

Enter edit mode and apply MQTT downlink JS code to this downlink converter.

1743582084494-111.png

6. Configure Physical NB-IoT Sensor

Now, let's experiment with sending data to Thingseye using a real NB-IoT device. For example, we will use the TS01-NB.

First, configure the NB-IoT device with the necessary MQTT settings using AT commands. Below is a list of AT commands you can use.

AT Commands

  • AT+PRO=3,3    // Use MQTT to connect to Thingseye. Payload Type set to 3.
  • AT+SUBTOPIC=<MQTT subscribe topic> Eg: TS01-NB
  • AT+PUBTOPIC=<MQTT publish topic> Eg: TS01-NB
  • AT+CLIENT=null
  • AT+UNAME=<MQTT Username>
  • AT+PWD=<MQTT Password>
  • AT+SERVADDR=<Broker address, Port>

Test your uplink by pressing the ACT button for 1 second.
 

The following image shows the uplink payload of a real Dragino device. The publish topic is 'TS01-NB' that contains fields in the payload, IMEI, IMSI, Model, temperature, etc. Note that we have created a device named TS01-NB in the Devices section in advance.

image-4.png