Table of Contents:
- 1. Introduction
- 2. Add New Device
- 3. Data Converters
- 4. Add Integration
- 5. Verifying the receipt of data from the device
1. Introduction
This document guides you on integrating Dragino -NB and -CB series devices data with ThingsBoard. For this guide, we use ThingsBoard Cloud, which is one of the ThingsBoard versions that allows you to try it for free.
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. Add New Device
First, we will add a device to simulate data using MQTT. This device does not represent a real physical device but serves as a common virtual device for all Dragino NB/CB devices.
In the left navigation, click Entities and then click Devices.
On the Devices page, click on the ‘+’ button, and then click on the Add new device from the dropdown menu.
The Add new device window appears. Name the device, for example 'Virtual NB/CB device'.
Click on the Next: Credentials button.
Click the Access token button if it is not selected by default.
Copy the Access token to a text editor, as you will need it in the section 'Sending data from an MQTT client'.
Click on the Add button.
Click on the MQTT button.
Then, select the operating system you are going to use with the Mosquitto MQTT Broker. This example shows sending a command from a computer running MacOS. First, install the necessary client tools on your computer.
Copy the MQTT pub command in the 'Execute the following command' section.
Note that the State is still shown as 'Inactive' in the Latest telemetry section.
On the terminal, enter the command you copied. This command sends the MQTT payload {temperature:25} as telemetry data from a virtual device named 'me'. Of course, you can replace 'me' with a device name or use the wildcard character '+' to match any device name.
If the command is successful, you can see the telemetry data you sent under the Latest telemetry section. Note that the State is now 'Active' in the Latest telemetry section.
Send the same command again, only changing the temperature value, to see how the Latest telemetry section updates its data.
Once you are done experimenting with this, close the window by clicking the Close button.
3. Data Converters
In ThingsBoard, 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 ThingsBoard can understand, or vice versa.
3.1 Uplink
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.
The Add data converter window will appear. Name it ‘MQTT Uplink Converter NB/CB’ and select the Type as Uplink.
Click on the JavaScript button. Now copy and paste the following JavaScript to the Decoder function section. This decoder function is valid for both NB and CB series devices.
// decode payload to string
var payloadStr = decodeToString(payload);
// decode payload to JSON
var objdata = {};
var obj1 = {};
var data = decodeToJson(payload);
var deviceName = data.IMEI;
delete data.IMEI;
var modelname = "Dragino " + data.Model;
//var mod = data.mod
delete data.Model;
//delete data.mod
var timestamp = new Date().getTime();
for (var key in data) {
if (Number(key)) {
obj1[key] = data[key];
obj1[key][obj1[key].length - 1] = Number(new Date(
obj1[key][obj1[key].length - 1]));
}
//Alec submitted25/02/25
//turn old key into new
else if (key === "Reading") {
objdata["reading"] = data[key];
} else if (key === "work mode") {
objdata["work_mode"] = data[key];
} else if (key === "hum") {
objdata["humidity"] = data[key];
}else if (key === "hum2") {
objdata["humidity2"] = data[key];
} else if (key === "hum3") {
objdata["humidity3"] = data[key];
} else if (key === "tem") {
objdata["temperature"] = data[key];
} else if (key === "tem2") {
objdata["temperature2"] = data[key];
} else if (key === "tem3") {
objdata["temperature3"] = data[key];
} else if (key === "DS18B20_Temp") {
objdata["temperature_pro"] = data[key];
} else if (key === "ds18b20_temperature") {
objdata["temperature_pro"] = data[key];
} else if (key === "DS18B20_temperature_pro") {
objdata["temperature_pro"] = data[key];
} else if (key === "tdc send flag") {
objdata["tdc_send_flag"] = data[key];
} else if (key === "trigger mode") {
objdata["trigger_mode"] = data[key];
} else if (key === "soil dielectric constant") {
objdata["soil_dielectric_constant"] = data[key];
} else if (key === "door open num") {
objdata["door_open_num"] = data[key];
} else if (key === "door duration") {
objdata["door_duration"] = data[key];
} else if (key === "count time") {
objdata["count_time"] = data[key];
} else if (key === "last open time2") {
objdata["last_open_time2"] = data[key];
} else if (key === "last open time3") {
objdata["last_open_time3"] = data[key];
}
//Alec submitted25/02/25
else {
objdata[key] = data[key]
}
}
var listdata = [{
"ts": timestamp,
"values": objdata
}]
for (var key1 in obj1) {
if (modelname == "Dragino RS485-NB") {
listdata.push({
"ts": obj1[key1][obj1[key1].length - 1],
"values": {
"Payload": obj1[key1][0],
}
})
} else {
listdata.push({
"ts": obj1[key1][obj1[key1].length - 1],
"values": {
"values": obj1[key1]
},
})
}
}
var result = {
deviceName: deviceName,
deviceType: modelname,
attributes: {
model: modelname,
//customerName: "NB-CB",
//groupName: "NB-CB",
//integrationName: metadata['integrationName']
},
telemetry: listdata
}
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;
}
return result;
Click on the Add button.
You should see that the newly added uplink data converter is listed on the Data Converters page.
3.2 Downlink
On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
The Add data converter window will appear. Name it ‘MQTT Downlink Converter NB/CB’ and select the Type as Downlink.
Click on the JavaScript button. Now copy and paste the following JavaScript to the Encoder function section. This encoder function is valid for both NB and CB series devices.
// 将16进制字符串两个字符转换为一个字节
var bytes = hexString.match(/.{2}/g);
// 对每个字节进行解析，并转换为对应的字符
var binaryString = bytes.map(function(byte) {
return String.fromCharCode(parseInt(byte, 16));
}).join('');
// 使用btoa进行base64编码
return btoa(binaryString);
}
// Result object with encoded downlink payload
var result = {
// downlink data content type: JSON, TEXT or BINARY (base64 format)
contentType: "BINARY",
// downlink data
data:hexToBase64(metadata.shared_value)
// Optional metadata object presented in key/value format
//metadata: {}
};
return result;
Click on the Add button.
You should see that the newly added downlink data converter is listed on the Data Converters page.
4. Add Integration
In the left navigation, click Integrations center, and then click Integrations.
On the Integrations page, click on the '+' button.
The Add integration window appears.
In the Add integration window, configure the following settings:
Basic settings:
- Integration type: MQTT
- Name: MQTT integration NB/CB
Click Next button.
Uplink data converter:
- Click on the Select existing button.
- Uplink data converter: Select MQTT Uplink Converter NB/CB from the dropdown list.
Click Next button.
Downlink data converter:
- Click on the Select existing button.
- Downlink data converter: Select MQTT Downlink Converter NB/CB from the dropdown list.
Click Next button.
Connection:
- Host: mqtt.eu.thingsboard.cloud (This is the host name you copied from the device - See section xxxxx for more information)
- Port: 1883 (This is the port number you copied from the device - See section xxxxx for more information)
- Credentials: Basic
- Username: Access token (This is the access token you copied from the device)
- Password - Leave it as blank
- Topic - v1/devices/+/telemetry (sightly modify the topic 'v1/devices/me/telemetry' you copied from the device to enable receiving data from any 'device name')
- QoS - 0-At most once
Click on the Check connection button to verify the MQTT connection using the provided parameters.
If the connection is successful, you will see the Connected message.
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.
5. Verifying the receipt of data from the device
On the terminal, issue the following MQTT command which simulates the device S31B-NB.
If the integration was performed without errors, after the transmission of the first telemetry, a new device with the name “S31B-NB” will appear in the Devices → All. Also, you can verify the input and output data, respectively, before and after conversion in Data converters → UDP Uplink Converter NB/CB → Events.