Skip to Content

Wiki source code of ThingsBoard

Last modified by Dilisi S on 2025/04/23 19:23
Show last authors
1 **Table of Contents:**
2
3 {{toc/}}
4
5 {{warning}}
6 Draft Document
7 {{/warning}}
8
9
10
11
12 = 1. Introduction =
13
14
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.
16
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**.
18
19
20 = 2. Prerequisites =
21
22 To complete this tutorial, you need to have the following:
23
24 * ThingsBoard cloud account
25 * MQTT Broker (public or private) such as,
26 ** [[ThingsBoard MQTT broker>>https://thingsboard.io/docs/mqtt-broker/]] (TBMQ)
27 ** **[[HiveMQ Cloud>>https://www.hivemq.com]] **-** **You can create a free account to try it or subscribe for a paid account.
28 ** [[emqx>>https://www.emqx.com/zh/mqtt/public-mqtt5-broker]] - The public MQTT server is only used for MQTT learning and testing, and should not be used in the production environment.
29 ** [[lns1.thingseye.io>>http://lns1.thingseye.io/]] - This is Dragino's MQTT broker, which requires a CA certificate to use.
30
31 == 2.1 ThingsBoard Cloud ==
32
33
34 Go to [[https:~~/~~/thingsboard.io/>>https://thingsboard.io/]]
35
36 Click on the **Try it now**.
37
38
39 [[image:thingsboard-1.png]]
40
41
42 Select either the **North America** or **Europe** region. Here, we use the Europe region.
43
44 [[image:thingsboard-2.png]]
45
46
47 You can sign up with your **Google**, **GitHub**, **Facebook**, or **Apple** account. If not you can create an account with providing your **name**, **email address** and a **password**.
48
49 Click on the **Sign up** button.
50
51 [[image:thingsboard-3.png||height="651" width="500"]]
52
53
54 You will be navigated to the following page.
55
56 [[image:thingsboard-5.png||height="109" width="500"]]
57
58
59 simultaneously, you will receive an email to confirm your email address. Click on the **Activate Your Account** button.
60
61
62 [[image:thingsboard-4.png||height="249" width="500"]]
63
64
65 Now losing to the account using your credentials:
66
67
68 [[image:thingsboard-6.png||height="244" width="500"]]
69
70
71 == 2.2 MQTT Brokers ==
72
73 This section introduces some MQTT brokers that you can use to publish messages from the device side and subscribe from the ThingsBoard side.
74
75
76 === 2.2.1 ThingsBoard MQTT broker (TBMQ) ===
77
78 The complete instructions for installing, configuring, and using the TBMQ can be found [[here>>https://thingsboard.io/docs/mqtt-broker/getting-started/]].
79
80
81 === 2.2.2 HiveMQ Cloud ===
82
83
84 Go to [[https:~~/~~/www.hivemq.com>>https://www.hivemq.com]]
85
86 Click on the **Start Free** button.
87
88 [[image:hivwmq-1.png]]
89
90
91 Click on the **Sign Up FREE Now** button in the **HIVEMQ CLOUD** section.
92
93 [[image:hivemq-2.png]]
94
95
96 Click on the **Sign Up** button.
97
98 You can sign up with HiveMQ using your **GitHub**, **Google**, or **LinkedIn** account.
99
100 If not, provide your **email address** and a **password** to create an account by clicking on the **Sign Up** button.
101
102
103 [[image:hivemq-3.png]]
104
105
106 You will receive an email to verify your email address. Click on the **Confirm my account** button.
107
108
109 [[image:hivemq-4.jpg||height="889" width="400"]]
110
111
112 You will be redirected to a page asking you to complete your profile. Once done, click the **Continue** button.
113
114
115 [[image:hivemq-5.png||height="655" width="700"]]
116
117
118 Select the CloudMQ Cloud plan you need. For testing purposes, select the **Serverless FREE** plan by clicking on the **Create Serverless Cluster** button.
119
120
121 [[image:hivemq-6.png]]
122
123
124 You will be navigated to the **Your Clusters** page. Click on the **Manage Cluster** button.
125
126 [[image:hivemq-7.png]]
127
128
129 In your cluster page, you can find some useful parameters you need to create a MQTT connection.
130
131 **URL**: This is the host name. Click on the copy button to copy it.
132
133 **Port**: 8883
134
135
136 Click on the **Getting Started** tab to setup the username and the password as the connection credentials.
137
138
139 [[image:hivemq-8.png]]
140
141
142 In the '**Create Connection Credentials**' section, provide a **username** and **password**, then click the **Add** button.
143
144
145 [[image:hivemq-9.png]]
146
147
148
149 If everything is successful, you will see the following message.
150
151
152 [[image:hivemq-10.png||height="206" width="500"]]
153
154
155 You will need these MQTT connection parameters when configuring the MQTT integration in the '**Add Integration**' section.
156
157
158 === 2.2.3 emqx ===
159
160
161 The [[emqx>>https://www.emqx.com/zh/mqtt/public-mqtt5-broker]] public MQTT server is only used for MOTT learning and testing, and should not be used in the production environment.
162
163
164 [[image:emqx.png||height="420" width="500"]]
165
166
167 === 2.2.4 Ins1.thingseye.io ===
168
169 [[lns1.thingseye.io>>http://lns1.thingseye.io/]] is the Dragino's MQTT broker, which requires a CA certificate file, Certificate file, and the Private key file to use.
170
171 If customers need to use this MQTT connection with ThingsBoard, they need to contact the TE team to obtain three license files.
172
173 [[image:ins1.png||height="310" width="500"]]
174
175
176
177 = 3. Data Converters =
178
179
180 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.
181
182 **In this section, you will create a universal uplink data converter for all Dragino NB-IoT devices. The uplink decoder converts any MQTT message coming from a device into key-value pairs that can be used to display and visualize data using various widgets on the dashboard**.
183
184
185 == 3.1 Uplink ==
186
187
188 In the left navigation, click **Integrations center**, and then click **Data converters**.
189
190
191 [[image:data-converters-list-empty.png]]
192
193
194 On the **Data converters** page, click on the ‘**+**’ button, and then click on **Create new converter** from the dropdown menu.
195
196
197
198 [[image:create-new-converter-menu.png||height="259" width="500"]]
199
200
201 The **Add data converter** window appears.
202
203 Name it ‘**MQTT Uplink Converter**’ and select the Type as **Uplink**.
204
205 Click on the **TBEL** button if it has not been selected by default.
206
207 Replace the default TBEL decoder function with the following universal TBEL decoder function, which decodes MQTT payload from any Dragino NB-IoT device.
208
209
210 {{code language="JavaScript"}}
211 // decode payload to JSON
212 var pattern = "yyyy/MM/dd HH:mm:ss";
213 var objdata = {};
214 var obj1 = {};
215 var data = decodeToJson(payload);
216 var deviceName = data.IMEI;
217 data.remove("IMEI");
218 var modelname = "Dragino "+ data.Model;
219 //var mod = data.mod
220 data.remove("Model");
221 //delete data.mod
222 var timestamp = new Date().getTime();
223 foreach (entry: data.entrySet()) {
224 var key = entry.getKey();
225 var value = entry.getValue();
226 //objdata[key] = data[key]
227 if(key.matches("^-?\\d+$")){ //is number
228 obj1[key]=data[key];
229 var index = obj1[key].length-1;
230 obj1[key][index]=new Date(obj1[key][index],pattern).getTime();
231 }
232 else if (key==="bat"||key==="BAT"){
233 objdata["battery"] = data[key];
234 }
235 else{
236 objdata[key] = data[key];
237 }}
238 var listdata = [{"ts":timestamp,"values":objdata}];
239 foreach ( entry1: obj1.entrySet()){
240 var key1 = entry1.getKey();
241 var value1 = entry1.getValue();
242 var index = obj1[key1].length-1;
243 var ts = obj1[key1][index];
244 if (modelname=="Dragino RS485-NB"){
245 listdata.push({"ts":ts,"values":{"Payload":obj1[key1][0]}});
246 }
247 else{
248 listdata.push({"ts":ts,"values":{"values":obj1[key1]}});
249 }
250 }
251 var result = {
252 deviceName: deviceName,
253 deviceType: modelname,
254 attributes: {
255 model: modelname
256 //customerName: "NB-CB",
257 //groupName: "NB-CB",
258 //integrationName: metadata['integrationName']
259 },
260 telemetry: listdata
261 };
262 return result;
263 {{/code}}
264
265
266 Once you modify the decoder function, click on the **Add** button.
267
268
269 [[image:mqtt-uplink-converter.png||height="498" width="500"]]
270
271
272
273 You should see that the newly added **MQTT Uplink converter **NB/CB is listed on the **Data Converters** page.
274
275
276
277 [[image:data-converters-list.png]]
278
279
280 = 4. Add Integration =
281
282
283 In the left navigation, click **Integrations center**, and then click **Integrations**.
284
285
286 [[image:integrations-list-empty.png]]
287
288
289 On the **Integrations** page, click on the '**+**' button.
290
291
292 The **Add integration** window appears.
293
294 In the **Add integration** window, configure the following settings:
295
296
297 **Basic settings:**
298
299 * **Integration type**: MQTT
300 * **Name**: MQTT integration
301 * **Enable integration**: YES
302 * **Allow create devices or assets**: YES
303
304 Click **Next** button.
305
306
307
308 [[image:add-integration-part-1.png||height="483" width="500"]]
309
310
311 **Uplink data converter:**
312
313 * Click on the **Select existing** button.
314 * **Uplink data converter**: Select **MQTT Uplink Converter NB/CB **from the dropdown list.
315
316 Click **Next** button.
317
318
319
320 [[image:add-integration-part-2.png||height="484" width="500"]]
321
322
323 **Downlink data converter:**
324
325 Dragino NB/CB devices don't require a downlink data converter to decode their payloads, so you can skip this step.
326
327 * Click on the **Skip **button in the Downlink data converter section.
328
329 Click **Skip** button.
330
331
332 [[image:integration-dl-skip.png||height="511" width="500"]]
333
334
335
336 **Connection:**
337
338 * **Host**: Host URL (Eg, **//011731f7xxxxxxxxxxxfbbedfc63f4.s1.eu.hivemq.cloud//**)
339 * **Port**: 8883 (the port number may differ based on your MQTT broker)
340 * **Credentials type**: Basic
341 * **Username**: Username (from your HiveMQ Cloud Cluster with your credentials)
342 * **Password:** Password (from your HiveMQ Cloud Cluster with your credentials)
343 * **Enable SSL**: YES
344 * **Topic**: # (the # symbol indicates that it filters all topics).
345 * **QoS:** 0-At most once
346
347 [[image:add-integration-4.png||height="484" width="500"]]
348
349
350 Click on the **Advanced settings** button.
351
352 * **Clean session:** YES
353 * **Retained**: YES
354
355 [[image:add-integration-connection-advanced-settings.png||height="510" width="500"]]
356
357
358 Click on the **Check connection** button to verify the MQTT connection using the provided parameters.
359
360
361 [[image:check-connection.png||height="83" width="300"]]
362
363
364 If the connection is successful, you will see the **Connected** message. If not, check your connection parameters again.
365
366
367 [[image:connection-success.png||height="511" width="500"]]
368
369
370 Click on the **Add** button.
371
372 You should see that the newly added integration is listed on the **Integrations** page.
373
374 Since we haven't received data from a device yet, the integration **Status** is shown as **Pending.**
375
376
377
378 [[image:integrations-pending.png]]
379
380
381 = 5. Verifying the receipt of data from virtual devices =
382
383
384 == 5.1 How does it work? ==
385
386
387 We use the Mosquitto MQTT client to simulate MQTT messages, acting as a virtual device. First, install the Mosquitto client on your computer from [[this link>>url:https://mosquitto.org/download/]]. The Mosquitto client publishes messages to the MQTT broker (HiveMQ) on a specified MQTT topic. ThingsBoard subscribes to these messages using the same topic.
388
389 The Mosquitto client publishes messages (payloads) to a topic - for example, # or device/ts01-nb. You can, of course, use any topic you prefer.
390
391
392 (% id="cke_bm_37386S" style="display:none" %) (%%)The MQTT payload format is as follows. The **IMEI **and **Model **are mandatory fields. For other fields, you can use any number of key-value pairs.
393
394 {{code language="none"}}
395 {"IMEI":"350693903995577", "Model":"TS01-NB", "temperature":30, "humidity":80, "pressure":1005}
396 {{/code}}
397
398
399 == 5.2 Sending messages ==
400
401
402 On your computer's terminal, issue the following MQTT command, which simulates the device named '**350693903995577'**. The message payload contains the fields IMEI, Model, temperature, humidity, and pressure, which hold the values 350693903995577,  TS01-NB, 30, 80, and 1005 respectively. This payload is also (technically) known as telemetry.
403
404 {{code language="none"}}
405 mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -u "xxxxx" -P "xxxxx" -t "device/350693903995577" -m '{"IMEI":"350693903995577", "Model":"TS01-NB", "temperature":30, "humidity":80, "pressure":1005}'
406 {{/code}}
407
408 If the integration was performed without errors, a new device named **350693903995577 **is created in the **Devices **section.
409
410
411 [[image:new-device-1.png]]
412
413
414 The status of the integration also changes to '**Active**' after the first telemetry transmission.
415
416
417 [[image:Screenshot 2025-04-21 122154.png]]
418
419
420
421 **When ThingsBoard receives this message for the first time, it will automatically create a new device named '350693903995577' in the Devices section. The device name is based on the IMEI number. For subsequent messages with the same IMEI, no duplicate devices will be created. Each new IMEI number will result in a unique entry in the Devices section, representing a physical device.**
422
423
424 == 5.3 Viewing messages ==
425
426
427 Go back to the **Integrations** page.
428
429 Click on the **MQTT integration** in the **Integrations** page to see its details.
430
431 Click on the **Edit** button (//**pen icon**//).
432
433 Click on the **Disabled** button in the upper-right corner.
434
435 Turn on the **All messages (15 min)** option. This will enable displaying all messages in the **Events** tab. This setting will expire in 15 minutes, and you will need to repeat the same steps if you want to view the messages in the Events tab later.
436
437 Click on the **Apply** button.
438
439 Then click on the **Apply changes** (//**tick icon**//) button.
440
441
442
443 [[image:Screenshot 2025-04-21 122936.png||height="247" width="500"]]
444
445
446 Now go to the **Events** tab.
447
448 Select the **Event type** as **Debug** from the dropdown list.
449
450 Publish another message (of course, you can repeat the previous message by pressing the UP arrow on your keyboard and then press Enter key) to your MQTT broker from your terminal, for example:
451
452 {{code language="none"}}
453 mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -u "xxxxx" -P "xxxxx" -t "device/350693903995577" -m '{"IMEI":"350693903995577", "Model":"TS01-NB", "temperature":30, "humidity":82, "pressure":1005}'
454 {{/code}}
455
456 Now you can see that uplink message in the **Events** tab (Click the **refresh** button if you didn't see any messages in the Events tab). The status should be **OK **if there is no errors in your integration.
457
458
459 Then click on the **three dots (...)** in the **Message** column. You can see the uplink message's **payload** in the **Message** window.
460
461
462
463 [[image:Screenshot 2025-04-21 122909.png]]
464
465
466 Now, you have successfully tested your integration with a simulated uplink payload and verified that it is received by ThingsBoard, and the device is provisioned.
467
468
469 = 6. Creating a Dashboard =
470
471 ThingsBoard **Dashboards** provide a powerful way to visualize and monitor real-time and historical data from connected devices. They allow users to create interactive, customizable panels displaying telemetry data, device status, and other key metrics. With a variety of widgets, including charts, maps, and tables, dashboards help users gain insights, track trends, and manage IoT deployments efficiently.
472
473
474 This section guides you on how to create a dashboard to display temperature and humidity data from the device on a time-series chart. You may also use other widgets in ThingsBoard to display data according to your requirements.
475
476
477 In **ThingsBoard**, from the left navigation menu, click **Dashboards**. Then, click the **+** button and select **Create new dashboard** from the dropdown menu.
478
479
480 [[image:dashboard-1.png]]
481
482
483 In the **Title** text box, enter **NB/CB Test Dashboard** as the title of the dashboard.
484
485 Click on the **Add** button.
486
487
488 [[image:dashboard-2.png||height="526" width="500"]]
489
490
491 Click on the **Add widget / Add new widget** button.
492
493
494 [[image:dashboard-3.png]]
495
496
497 In the **Select widgets bundle** window, click **Charts**.
498
499
500 [[image:dashboard-4.png||height="537" width="700"]]
501
502
503
504 In the **Charts: select widget** window, click **Time series chart**.
505
506
507 [[image:dashboard-5.png||height="525" width="700"]]
508
509
510 Configure the **Time series chart** widget as follows:
511
512 * **Datasource** - select **350693903995577 **you provisioned.
513 * **Series**:
514 ** **temperature** - you can see this key by default.
515 ** **humidity** - Click **Add series** button. Then choose **humidity** for the key, and then type **%** as its unit.
516 ** pressure -  Click **Add series** button. Then choose **humidity** for the key, and then type Pa as its unit.
517 * Click on the **Add** button.
518
519 {{info}}
520 You can add only the relevant fields from the device's payload to display data on a widget. These fields are called 'keys'.
521 {{/info}}
522
523
524
525 [[image:Screenshot 2025-04-21 123647.png||height="466" width="700"]]
526
527
528 The time-series chart will appear in edit mode. Resize it by clicking and dragging the lower-right corner.
529
530 Click the **Save** button to add the widget to the dashboard.
531
532
533 [[image:Screenshot 2025-04-21 124145.png||height="443" width="700"]]
534
535
536 **Now send a few MQTT messages from the terminal to simulate the data. Use different values for temperature, humidity, and pressure in each message.**
537
538 **The chart will update with the values in real time, and you will see a live chart similar to this:**
539
540
541 [[image:Screenshot 2025-04-21 124054.png||height="441" width="700"]]
542
543
544 = 8. Configure Physical NB-IoT Sensor =
545
546
547 Now, let's experiment with sending data to ThingsBoard using a real NB-IoT device. For example, we will use the **TS01-NB**.
548
549 First, configure the NB-IoT device with the necessary MQTT settings using AT commands. Below is a list of AT commands you can use.
550
551
552 **AT Commands**
553
554 * **AT+PRO=3,3    **~/~/ Use MQTT to connect to ThingsBoard. Payload Type set to 3.
555 * **AT+SUBTOPIC=<MQTT subscribe topic> Eg: # -  **You can leave the SUBTOPIC configuration as it is, since we are not sending downlink messages to the device at the moment.
556 * **AT+PUBTOPIC=<MQTT publish topic> Eg: #**
557 * **AT+CLIENT=null**
558 * **AT+UNAME=<MQTT Username>**
559 * **AT+PWD=<MQTT Password>**
560 * **AT+SERVADDR=<Broker address, Port>**
561
562 Test your uplink by pressing the ACT button for 1 second.
563
564
565 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.
566
567
568 [[image:image-4.png]]