Skip to Content

Changes for page ThingsBoard

Last modified by Dilisi S on 2025/04/23 19:23
From version 16.1
edited by Dilisi S
on 2025/03/03 02:45
Change comment: Mar 2 edits - part 2
To version 93.1
edited by Dilisi S
on 2025/03/08 03:59
Change comment: Mar 7 edits -part 1

Summary

Details

Page properties
Content
... ... @@ -6,215 +6,134 @@
6 6  Draft Document
7 7  {{/warning}}
8 8  
9 -= Introduction =
10 10  
11 -This document guides you on integrating Dragino -NB and -CB series devices with ThingsBoard. For this guide, we use ThingsBoard Cloud, which is one of the ThingsBoard versions that allows you to try it for free.
12 12  
13 13  
14 -= Add New Device =
12 += 1. Introduction =
15 15  
16 -In the left navigation, click **Entities** and then click **Devices**.
17 17  
15 +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.
18 18  
19 -[[image:ThingsBoard-Device.png]]
17 +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**.
20 20  
21 21  
22 -On the ‘**Devices**’ page, click on the ‘**+**’ button, and then click on the ‘**Add new device**’ from the dropdown menu.
23 23  
24 24  
25 -[[image:ThingsBoard-add-new-device.png||height="279" width="500"]]
26 26  
23 += 2. Data Converters =
27 27  
28 28  
29 -= Data Converters =
26 +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.
30 30  
31 31  
32 -== Uplink ==
29 +== 2.1 Uplink ==
33 33  
34 -In the left navigation, click ‘Integrations center’, and then click ‘Data converters’.
35 35  
32 +In the left navigation, click **Integrations center**, and then click **Data converters**.
36 36  
37 -[[image:ThingsBoard-Data-Converters.png]]
38 38  
39 39  
40 -On the ‘Data converters’ page, click on the ‘+’ button, and then click on the ‘Create new converter’ from the dropdown menu.
36 +[[image:data-converters-list-empty.png]]
41 41  
42 42  
43 -[[image:ThingsBoard-new-data-converter.png||height="282" width="500"]]
39 +On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu.
44 44  
45 45  
46 -The ‘Add data converter’ window will appear. Name it ‘**UDP Uplink Converter NB/CB**’ and select the Type as ‘Uplink’.
47 47  
48 -Click on the ‘JavaScript’ button. Now copy and paste the following script to the ‘Decoder function’ section:
43 +[[image:create-new-converter-menu.png||height="259" width="500"]]
49 49  
45 +
46 +The **Add data converter** window will appear. Name it ‘**MQTT Uplink Converter NB/CB**’ and select the Type as **Uplink**.
47 +
48 +Click on the **TBEL** button if not selected it by default. Delete the existing decoder function in the code editor. Now copy and paste the following decoder function written in **TBEL (ThingsBoard Expression Language)** in to the **code editor**. This decoder function is compatible for both NB and CB series devices.
49 +
50 50  {{code language="JavaScript"}}
51 -//Version: 0.1
51 +/** Decoder **/
52 +
52 52  // decode payload to string
53 53  var payloadStr = decodeToString(payload);
55 +var data = JSON.parse(payloadStr);
54 54  
57 +var deviceName = metadata.topic.split("/")[3];
55 55  // decode payload to JSON
56 -var objdata = {};
57 -var obj1 = {};
58 -var data = decodeToJson(payload);
59 -var deviceName = data.IMEI;
60 -delete data.IMEI;
61 -var modelname = "Dragino " + data.Model;
62 -//var mod = data.mod
63 -delete data.Model;
64 -//delete data.mod
65 -var timestamp = new Date().getTime();
59 +var deviceType = 'sensor';
66 66  
67 -for (var key in data) {
68 -
69 - if (Number(key)) {
70 - obj1[key] = data[key];
71 - obj1[key][obj1[key].length - 1] = Number(new Date(
72 - obj1[key][obj1[key].length - 1]));
73 -
74 - }
75 -//Alec submitted25/02/25
76 -//turn old key into new
77 - else if (key === "Reading") {
78 - objdata["reading"] = data[key];
79 - } else if (key === "work mode") {
80 - objdata["work_mode"] = data[key];
81 - } else if (key === "hum") {
82 - objdata["humidity"] = data[key];
83 - }else if (key === "hum2") {
84 - objdata["humidity2"] = data[key];
85 - } else if (key === "hum3") {
86 - objdata["humidity3"] = data[key];
87 - } else if (key === "tem") {
88 - objdata["temperature"] = data[key];
89 - } else if (key === "tem2") {
90 - objdata["temperature2"] = data[key];
91 - } else if (key === "tem3") {
92 - objdata["temperature3"] = data[key];
93 - } else if (key === "DS18B20_Temp") {
94 - objdata["temperature_pro"] = data[key];
95 - } else if (key === "ds18b20_temperature") {
96 - objdata["temperature_pro"] = data[key];
97 - } else if (key === "DS18B20_temperature_pro") {
98 - objdata["temperature_pro"] = data[key];
99 - } else if (key === "tdc send flag") {
100 - objdata["tdc_send_flag"] = data[key];
101 - } else if (key === "trigger mode") {
102 - objdata["trigger_mode"] = data[key];
103 - } else if (key === "soil dielectric constant") {
104 - objdata["soil_dielectric_constant"] = data[key];
105 - } else if (key === "door open num") {
106 - objdata["door_open_num"] = data[key];
107 - } else if (key === "door duration") {
108 - objdata["door_duration"] = data[key];
109 - } else if (key === "count time") {
110 - objdata["count_time"] = data[key];
111 - } else if (key === "last open time2") {
112 - objdata["last_open_time2"] = data[key];
113 - } else if (key === "last open time3") {
114 - objdata["last_open_time3"] = data[key];
115 - }
116 -//Alec submitted25/02/25
117 - else {
118 - objdata[key] = data[key]
119 - }
120 -}
121 -var listdata = [{
122 - "ts": timestamp,
123 - "values": objdata
124 -}]
125 -for (var key1 in obj1) {
126 - if (modelname == "Dragino RS485-NB") {
127 - listdata.push({
128 - "ts": obj1[key1][obj1[key1].length - 1],
129 - "values": {
130 - "Payload": obj1[key1][0],
131 - }
132 - })
133 - } else {
134 - listdata.push({
135 - "ts": obj1[key1][obj1[key1].length - 1],
136 - "values": {
137 - "values": obj1[key1]
138 - },
139 - })
140 - }
141 -}
61 +// Result object with device attributes/telemetry data
142 142  var result = {
143 -
144 144   deviceName: deviceName,
145 - deviceType: modelname,
64 + deviceType: deviceType,
146 146   attributes: {
147 - model: modelname,
148 - //customerName: "NB-CB",
149 - //groupName: "NB-CB",
150 - //integrationName: metadata['integrationName']
151 -
66 + integrationName: metadata['integrationName'],
152 152   },
153 - telemetry: listdata
154 -}
68 + telemetry: {
69 + temperature: data.temperature,
70 + humidity: data.humidity,
71 + }
72 +};
155 155  
156 -function decodeToString(payload) {
157 - return String.fromCharCode.apply(String, payload);
158 -}
74 +/** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/
159 159  
160 -function decodeToJson(payload) {
161 - // covert payload to string.
162 - var str = decodeToString(payload);
76 +return result;
77 +{{/code}}
163 163  
164 - // parse string to JSON
165 - var data = JSON.parse(str);
166 - return data;
167 -}
168 168  
169 -return result;
80 +Click on the **Add** button.
170 170  
171 -{{/code}}
172 172  
173 -Click on the ‘Add’ button.
174 174  
84 +[[image:add-uplink-data-converter.png||height="529" width="500"]]
175 175  
176 -[[image:ThingsBoard-add-data-converter-uplink.png||width="500"]]
177 177  
87 +You should see that the newly added **MQTT Uplink converter **NB/CB is listed on the **Data Converters** page.
178 178  
179 -The uplink data converter is added to ThingsBoard and appears on the ‘Data Converters’ page
89 +[[image:data-converter-list-showing-uplink-dc.png]]
180 180  
181 181  
182 -== Downlink ==
92 +== 3.2 Downlink ==
183 183  
184 -On the ‘Data converters’ page, click on the ‘+’ button, and then click on the ‘Create new converter’ from the dropdown menu.
185 185  
95 +On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu.
186 186  
187 187  [[image:ThingsBoard-new-data-converter.png||height="282" width="500"]]
188 188  
189 189  
190 -The ‘**Add data converter**’ window will appear. Name it ‘**UDP Downlink Converter NB/CB**’ and select the Type as ‘**Downlink**’.
100 +The **Add data converter** window will appear. Name it ‘**MQTT Downlink Converter NB/CB**’ and select the Type as **Downlink**.
191 191  
192 -Click on the ‘**JavaScript**’ button. Now copy and paste the following script to the ‘**Encoder function**’ section:
102 +Click on the **TBEL** button if not selected it by default. Now copy and paste the following encoder function written in **TBEL (ThingsBoard Expression Language)** in to the **code editor**. This encoder function is compatible for both NB and CB series devices.
193 193  
194 194  
195 195  {{code language="JavaScript"}}
196 -function hexToBase64(hexString) {
197 - // 将16进制字符串两个字符转换为一个字节
198 - var bytes = hexString.match(/.{2}/g);
199 - // 对每个字节进行解析，并转换为对应的字符
200 - var binaryString = bytes.map(function(byte) {
201 - return String.fromCharCode(parseInt(byte, 16));
202 - }).join('');
203 -
204 - // 使用btoa进行base64编码
205 - return btoa(binaryString);
206 -}
106 +// Encode downlink data from incoming Rule Engine message
207 207  
108 +// msg - JSON message payload downlink message json
109 +// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
110 +// metadata - list of key-value pairs with additional data about the message
111 +// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter
112 +
113 +/** Encoder **/
114 +
115 +var data = {};
116 +
117 +// Process data from incoming message and metadata
118 +
119 +data.tempFreq = msg.temperatureUploadFrequency;
120 +data.humFreq = msg.humidityUploadFrequency;
121 +
122 +data.devSerialNumber = metadata['ss_serialNumber'];
123 +
208 208  // Result object with encoded downlink payload
209 209  var result = {
126 +
210 210   // downlink data content type: JSON, TEXT or BINARY (base64 format)
211 - contentType: "BINARY",
128 + contentType: "JSON",
212 212  
213 213   // downlink data
214 - data:hexToBase64(metadata.shared_value)
131 + data: JSON.stringify(data),
215 215  
216 216   // Optional metadata object presented in key/value format
217 - //metadata: {}
134 + metadata: {
135 + topic: metadata['deviceType']+'/'+metadata['deviceName']+'/upload'
136 + }
218 218  
219 219  };
220 220  
... ... @@ -225,80 +225,102 @@
225 225  Click on the **Add** button.
226 226  
227 227  
228 -[[image:ThingsBoard-add-data-converter-downlink.png||height="532" width="500"]]
229 229  
148 +[[image:add-downlink-data-converter.png||height="529" width="500"]]
230 230  
231 -= Add Integration =
232 232  
233 -In the left navigation, click ‘Integrations center’, and then click ‘Integrations’.
151 +You should see that the newly added **MQTT Downlink** Converter NB/CB is listed on the **Data Converters** page.
234 234  
235 -On the ‘Integrations’ page, click on the “+” button.
236 236  
237 237  
238 -[[image:ThingsBoard-add-integration.png]]
155 +[[image:data-converters-list.png]]
239 239  
157 += 3. Add Integration =
240 240  
241 -The ‘Add integration’ window appears.
242 242  
243 -In the Add Integration window, configure the following settings:
160 +In the left navigation, click **Integrations center**, and then click **Integrations**.
244 244  
162 +On the **Integrations** page, click on the '**+**' button.
163 +
164 +[[image:data-converter-list-page.png]]
165 +
166 +
167 +The **Add integration** window appears.
168 +
169 +In the **Add integration** window, configure the following settings:
170 +
171 +
245 245  **Basic settings:**
246 246  
247 -* **Integration type**: UDP
248 -* **Name**: UDP Integration NB/CB
174 +* **Integration type**: MQTT
175 +* **Name**: MQTT integration NB/CB
249 249  
250 250  Click **Next** button.
251 251  
252 -
253 253  [[image:add-integration-basic-settings.png||height="511" width="500"]]
254 254  
255 255  
256 256  **Uplink data converter:**
257 257  
258 -* Click on the ‘**Select existing**’ button.
259 -* Uplink data converter: Select ‘**UDP Uplink Converter NB/CB**’ from the dropdown list.
184 +* Click on the **Select existing** button.
185 +* **Uplink data converter**: Select **MQTT Uplink Converter NB/CB **from the dropdown list.
260 260  
261 261  Click **Next** button.
262 262  
189 +[[image:add-integration-uplink-data-converter.png||width="500"]]
263 263  
264 -[[image:add-integration-uplink-data-converter.png||height="511" width="500"]]
265 265  
266 -
267 267  **Downlink data converter:**
268 268  
269 -* Click on the ‘**Select existing**’ button.
270 -* Downlink data converter: Select ‘**UDP Downlink Converter NB/CB**’ from the dropdown list.
194 +* Click on the **Select existing** button.
195 +* **Downlink data converter**: Select **MQTT Downlink Converter NB/CB **from the dropdown list.
271 271  
272 -
273 273  Click **Next** button.
274 274  
199 +[[image:add-integration-downlink-data-converter.png||height="510" width="500"]]
275 275  
276 -[[image:add-integration-downlink-data-converter.png||height="512" width="500"]]
277 277  
278 -
279 279  **Connection:**
280 280  
281 -**Port**: 11582
204 +* **Host**: Cluster URL (Eg. 011731f7928541588a6cdfbbedfc63f4.s1.eu.hivemq.cloud)
205 +* **Port**: 8883
206 +* **Credentials**: Basic
207 +* **Enable SSL**: YES
208 +* **Username**: Username (from your HiveMQ Cloud Cluster with your credentials)
209 +* **Password:** Password (from your HiveMQ Cloud Cluster with your credentials)
210 +* **Topic:** tb/mqtt-integration-tutorial/sensors/+/telemetry (the + replaces any 'device name' and creates devices in the Entities -> Devices)
211 +* **QoS:** 0-At most once
212 +* **Clean session:** NO
213 +* **Retained**: NO
282 282  
283 -**Size of the buffer for inbound socket (in KB)**: 64
215 +Click on the **Check connection** button to verify the MQTT connection using the provided parameters.
284 284  
285 -**Cache Size**: 10000000
217 +[[image:add-integration-connection.png||width="500"]]
286 286  
287 -**Cache time to live in minutes**: 1440
288 288  
220 +If the connection is successful, you will see the **Connected** message.
289 289  
290 -Copy the two keys, **Integration key** and **Integration secret** into a text editor, as you will need them in the section ‘xxxxx’.
291 -
292 292  Click on the **Add** button.
293 293  
224 +[[image:add-connection-success.png||height="511" width="500"]]
294 294  
295 -[[image:add-integration-connection.png||height="511" width="500"]]
296 296  
227 +You should see that the newly added integration is listed on the **Integrations** page.
297 297  
229 +Since we haven't received data from a device yet, the integration **Status** is shown as **Pending.**
298 298  
299 -= Verifying the receipt of data from the device =
231 +[[image:integrations-list-added-pending.png]]
300 300  
301 -Connect **S31B-NB** to transfer information. If the integration was performed without errors, after the transmission of the first telemetry, a new device with the name “xxxxx” 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.
302 302  
234 += 5. Verifying the receipt of data from the device =
303 303  
236 +
237 +On the terminal, issue the following MQTT command which simulates the device S31B-NB.
238 +
239 +{{code language="none"}}
240 +mosquitto_pub -d -q 1 -h mqtt.eu.thingsboard.cloud -p 1883 -t v1/devices/S31B-NB/telemetry -u "24vk3w9h7sqdld1me5eh" -m "{temperature:20}"
241 +{{/code}}
242 +
243 +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.
244 +
304 304  
ThingsBoard-Data-Converters.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -100.3 KB
Content
ThingsBoard-Device.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -225.5 KB
Content
ThingsBoard-add-data-converter-downlink.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -128.6 KB
Content
ThingsBoard-add-data-converter-uplink.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -128.6 KB
Content
ThingsBoard-add-data-converter.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -128.6 KB
Content
ThingsBoard-add-integration.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -128.6 KB
Content
ThingsBoard-add-new-device.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -89.7 KB
Content
ThingsBoard-new-data-converter.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -100.3 KB
Content
add-integration-basic-settings.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -122.5 KB
Content
add-integration-connection.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -124.4 KB
Content
add-integration-downlink-data-converter.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -123.0 KB
Content
add-integration-uplink-data-converter.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -120.7 KB
Content
add-downlink-data-converter.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +175.2 KB
Content
add-uplink-data-converter.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +174.1 KB
Content
create-new-converter-menu.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +31.5 KB
Content
data-converters-list-empty.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +260.7 KB
Content
data-converters-list.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +212.2 KB
Content