Wiki source code of ThingsBoard

Version 156.1 by Dilisi S on 2025/03/17 00:34
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 ** **[[HiveMQ Cloud>>https://www.hivemq.com]] - You can create a free account to try it or subscribe for a paid account. - We use HiveMQ Cloud as the MQTT broker to build example in this tutorial.**
27 ** [[emqx>>https://www.emqx.com/zh/mqtt/public-mqtt5-broker]] - The public MQTT server is only used for MOTT learning and testing, and should not be used in the production environment.
28 ** [[lns1.thingseye.io>>http://lns1.thingseye.io/]] - This is Dragino's MQTT broker, which requires a CA certificate to use.
29
30 == 2.1 ThingsBoard Cloud ==
31
32
33 Go to [[https:~~/~~/thingsboard.io/>>https://thingsboard.io/]]
34
35 Click on the **Try it now**.
36
37
38 [[image:thingsboard-1.png]]
39
40
41 Select either the **North America** or **Europe** region. Here, we use the Europe region.
42
43 [[image:thingsboard-2.png]]
44
45
46 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**.
47
48 Click on the **Sign up** button.
49
50 [[image:thingsboard-3.png||height="651" width="500"]]
51
52
53 You will be navigated to the following page.
54
55 [[image:thingsboard-5.png||height="109" width="500"]]
56
57
58 simultaneously, you will receive an email to confirm your email address. Click on the **Activate Your Account** button.
59
60
61 [[image:thingsboard-4.png||height="249" width="500"]]
62
63
64 Now losing to the account using your credentials:
65
66
67 [[image:thingsboard-6.png||height="244" width="500"]]
68
69
70 (% class="wikigeneratedid" %)
71 == 2.2 HiveMQ Cloud ==
72
73 === 2.2.1 HiveMQ Cloud ===
74
75
76 Go to [[https:~~/~~/www.hivemq.com>>https://www.hivemq.com]]
77
78 Click on the **Start Free** button.
79
80 [[image:hivwmq-1.png]]
81
82
83 Click on the **Sign Up FREE Now** button in the **HIVEMQ CLOUD** section.
84
85 [[image:hivemq-2.png]]
86
87
88 Click on the **Sign Up** button.
89
90 You can sign up with HiveMQ using your **GitHub**, **Google**, or **LinkedIn** account.
91
92 If not, provide your **email address** and a **password** to create an account by clicking on the **Sign Up** button.
93
94
95 [[image:hivemq-3.png]]
96
97
98 You will receive an email to verify your email address. Click on the **Confirm my account** button.
99
100
101 [[image:hivemq-4.jpg||height="889" width="400"]]
102
103
104 You will be redirected to a page asking you to complete your profile. Once done, click the **Continue** button.
105
106
107 [[image:hivemq-5.png||height="655" width="700"]]
108
109
110 Select the CloudMQ Cloud plan you need. For testing purposes, select the **Serverless FREE** plan by clicking on the **Create Serverless Cluster** button.
111
112
113 [[image:hivemq-6.png]]
114
115
116 You will be navigated to the **Your Clusters** page. Click on the **Manage Cluster** button.
117
118 [[image:hivemq-7.png]]
119
120
121 In your cluster page, you can find some useful parameters you need to create a MQTT connection.
122
123 **URL**: This is the host name. Click on the copy button to copy it.
124
125 **Port**: 8883
126
127
128 Click on the **Getting Started** tab to setup the username and the password as the connection credentials.
129
130
131 [[image:hivemq-8.png]]
132
133
134 In the '**Create Connection Credentials**' section, provide a **username** and **password**, then click the **Add** button.
135
136
137 [[image:hivemq-9.png]]
138
139
140
141 If everything is successful, you will see the following message.
142
143
144 [[image:hivemq-10.png||height="206" width="500"]]
145
146
147 You will need these MQTT connection parameters when configuring the MQTT integration in the '**Add Integration**' section.
148
149
150 === 2.2.2 emqx ===
151
152
153 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.
154
155
156 [[image:emqx.png||height="420" width="500"]]
157
158
159 === 2.2.3 Ins1.thingseye.io ===
160
161 [[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.
162
163 If customers need to use this MQTT connection with ThingsBoard, they need to contact the TE team to obtain three license files.
164
165 [[image:ins1.png||height="310" width="500"]]
166
167
168 = 3. Data Converters =
169
170
171 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.
172
173
174 == 3.1 Uplink ==
175
176
177 In the left navigation, click **Integrations center**, and then click **Data converters**.
178
179
180
181 [[image:data-converters-list-empty.png]]
182
183
184 On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu.
185
186
187
188 [[image:create-new-converter-menu.png||height="259" width="500"]]
189
190
191 The **Add data converter** window will appear. Name it ‘**MQTT Uplink Converter NB/CB**’ and select the Type as **Uplink**.
192
193 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.
194
195 {{code language="JavaScript"}}
196 /** Decoder **/
197
198 // decode payload to string
199 var payloadStr = decodeToString(payload);
200 var data = JSON.parse(payloadStr);
201
202 var deviceName = metadata.topic.split("/")[3];
203 // decode payload to JSON
204 var deviceType = 'sensor';
205
206 // Result object with device attributes/telemetry data
207 var result = {
208 deviceName: deviceName,
209 deviceType: deviceType,
210 attributes: {
211 integrationName: metadata['integrationName'],
212 },
213 telemetry: {
214 temperature: data.temperature,
215 humidity: data.humidity,
216 }
217 };
218
219 /** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/
220
221 return result;
222 {{/code}}
223
224
225 Click on the **Add** button.
226
227
228
229 [[image:add-uplink-data-converter.png||height="529" width="500"]]
230
231
232 You should see that the newly added **MQTT Uplink converter **NB/CB is listed on the **Data Converters** page.
233
234 [[image:data-converter-list-showing-uplink-dc.png]]
235
236
237
238 == 3.2 Downlink ==
239
240
241 On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu.
242
243
244 [[image:create-new-converter-menu.png||width="500"]]
245
246
247
248 The **Add data converter** window will appear. Name it ‘**MQTT Downlink Converter NB/CB**’ and select the Type as **Downlink**.
249
250 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.
251
252
253 {{code language="JavaScript"}}
254 // Encode downlink data from incoming Rule Engine message
255
256 // msg - JSON message payload downlink message json
257 // msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
258 // metadata - list of key-value pairs with additional data about the message
259 // integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter
260
261 /** Encoder **/
262
263 var data = {};
264
265 // Process data from incoming message and metadata
266
267 data.tempFreq = msg.temperatureUploadFrequency;
268 data.humFreq = msg.humidityUploadFrequency;
269
270 data.devSerialNumber = metadata['ss_serialNumber'];
271
272 // Result object with encoded downlink payload
273 var result = {
274
275 // downlink data content type: JSON, TEXT or BINARY (base64 format)
276 contentType: "JSON",
277
278 // downlink data
279 data: JSON.stringify(data),
280
281 // Optional metadata object presented in key/value format
282 metadata: {
283 topic: metadata['deviceType']+'/'+metadata['deviceName']+'/upload'
284 }
285
286 };
287
288 return result;
289 {{/code}}
290
291
292 Click on the **Add** button.
293
294
295
296 [[image:add-downlink-data-converter.png||height="529" width="500"]]
297
298
299 You should see that the newly added **MQTT Downlink** Converter NB/CB is listed on the **Data Converters** page.
300
301
302 [[image:data-converters-list.png]]
303
304
305
306 = 4. Add Integration =
307
308
309 In the left navigation, click **Integrations center**, and then click **Integrations**.
310
311
312 [[image:integrations-list-empty.png]]
313
314
315 On the **Integrations** page, click on the '**+**' button.
316
317
318 The **Add integration** window appears.
319
320 In the **Add integration** window, configure the following settings:
321
322
323 **Basic settings:**
324
325 * **Integration type**: MQTT
326 * **Name**: MQTT integration NB/CB
327 * **Enable integration**: YES
328 * **Allows create devices or assets**: YES
329
330 Click **Next** button.
331
332
333
334 [[image:add-integration-basic-settings.png||height="511" width="500"]]
335
336
337 **Uplink data converter:**
338
339 * Click on the **Select existing** button.
340 * **Uplink data converter**: Select **MQTT Uplink Converter NB/CB **from the dropdown list.
341
342 Click **Next** button.
343
344
345
346 [[image:add-integration-uplink-data-converter.png||height="511" width="500"]]
347
348
349 **Downlink data converter:**
350
351 * Click on the **Select existing** button.
352 * **Downlink data converter**: Select **MQTT Downlink Converter NB/CB **from the dropdown list.
353
354 Click **Next** button.
355
356
357
358 [[image:add-integration-downlink-data-converter.png||height="511" width="500"]]
359
360
361 **Connection:**
362
363 * **Host**: Cluster URL (Eg. 011731f7928541588a6cdfbbedfc63f4.s1.eu.hivemq.cloud)
364 * **Port**: 8883
365 * **Credentials**: Basic
366 * **Enable SSL**: YES
367 * **Username**: Username (from your HiveMQ Cloud Cluster with your credentials)
368 * **Password:** Password (from your HiveMQ Cloud Cluster with your credentials)
369 * **Topic:** tb/mqtt-integration-tutorial/sensors/+/telemetry (the + replaces any 'device name' and creates devices in the Entities -> Devices)
370 * **QoS:** 0-At most once
371
372 [[image:add-integration-connection.png||height="511" width="500"]]
373
374
375 Click on the **Advanced settings** button.
376
377 * **Clean session:** YES
378 * **Retained**: YES
379
380 [[image:add-integration-connection-advanced-settings.png||height="510" width="500"]]
381
382
383 Click on the **Check connection** button to verify the MQTT connection using the provided parameters.
384
385
386 [[image:check-connection.png||height="83" width="300"]]
387
388
389 If the connection is successful, you will see the **Connected** message. If not, check your connection parameters again.
390
391
392 [[image:connection-success.png||height="511" width="500"]]
393
394
395 Click on the **Add** button.
396
397 You should see that the newly added integration is listed on the **Integrations** page.
398
399 Since we haven't received data from a device yet, the integration **Status** is shown as **Pending.**
400
401
402
403 [[image:new-integration-pending.png]]
404
405
406 = 5. Verifying the receipt of data from virtual devices =
407
408
409 == 5.1 How does it work? ==
410
411
412 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.
413
414 The Mosquitto client publishes messages on the topic v1/devices/[device_name]/telemetry. The [device_name]placeholder can be replaced with any device name, for example, 'S31B-NB'. Then, the MQTT topic would be v1/devices/S31B-NB/telemetry.
415
416 On the ThingsBoard side, we configure the MQTT topic subscription as v1/devices/+/telemetry. The + wildcard represents any device name and allows ThingsBoard to automatically create (provision) a device with that name, such as S31B-NB, for example.
417
418
419 **The new device is created the first time the MQTT topic is received. For subsequent MQTT topics with the same device name, no duplicate devices will be created.**
420
421
422 For example, if you send two MQTT messages with different device names in the topic:
423
424 1. v1/devices/**S31B-NB**/telemetry
425 1. v1/devices/**LDS25-NB**/telemetry
426
427 ThingsBoard will create two devices named **S31B-NB** and **LDS25-NB** in the **//Devices//** section.
428
429
430 The MQTT payload format is as follows, which is common for all ~-~-NB and ~-~-CB series devices:
431
432 {{code language="none"}}
433 {"temperature":10.4, "humidity":85}
434 {{/code}}
435
436
437 == 5.2 Sending messages ==
438
439
440 On the terminal, issue the following MQTT command which simulates the device S31B-NB. The message payload contains the fields temperature and humidity, which hold the values 10.4 and 85, respectively. This payload is also (technically) known as telemetry.
441
442 {{code language="none"}}
443 mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -t "tb/mqtt-integration-tutorial/sensors/S31B-NB/telemetry" -u "xxxxx" -P "xxxxx" -m '{"temperature":10.4, "humidity":85}'
444 {{/code}}
445
446 If the integration was performed without errors, the status of the integration changes to 'Active' after the first telemetry transmission.
447
448
449 [[image:integration-active.png]]
450
451
452 Also, a new device named **S31B-NB** will appear under **//Entities -> Devices -> All//**. This means the first MQTT message triggers ThingsBoard to provision a device named **S31B-NB**.
453
454
455 [[image:device-provision-1.png]]
456
457
458 Click on the device S31B-NB on the devices list to see its details.
459
460 Then go to the **Latest telemetry** tab.
461
462 You can see the fields temperature and humidity with the values you previously sent using the MQTT message.
463
464
465 [[image:telemetry-1.png]]
466
467
468 Now, change the values of the fields and send the MQTT message again. For example, set temperature to 20 and humidity to 70. Observe how the values update in //Latest Telemetry//.
469
470
471 [[image:telemetry-2.png]]
472
473
474 Let's provision the second device named **LDS25-NB **with initial telemetry. Use the following MQTT message.
475
476
477 {{code language="none"}}
478 mosquitto_pub -d -q 1 -h 011731f7928541588a6cdfbbedfc63f4.s1.eu.hivemq.cloud -p 8883 -t "tb/mqtt-integration-tutorial/sensors/LDS25-NB/telemetry" -u "pradeeka" -P "Kalpani123@" -m '{"temperature":11, "humidity":87}'
479 {{/code}}
480
481 Now, refresh the **Devices** page, and you will see the second device, **LDS25-NB**, which was recently provisioned.
482
483
484 [[image:device-provision-2.png]]
485
486
487 = 6. Creating a Dashboard =
488
489 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.
490
491
492 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.
493
494
495 In **ThingsBoard**, from the left navigation menu, click **Dashboards**. Then, click the **+** button and select **Create new dashboard** from the dropdown menu.
496
497
498 [[image:dashboard-1.png]]
499
500
501 In the **Title** text box, enter **NB/CB Test Dashboard** as the title of the dashboard.
502
503 Click on the **Add** button.
504
505
506 [[image:dashboard-2.png||height="526" width="500"]]
507
508
509 Click on the **Add widget / Add new widget** button.
510
511
512 [[image:dashboard-3.png]]
513
514
515 In the **Select widgets bundle** window, click **Charts**.
516
517
518 [[image:dashboard-4.png||height="537" width="700"]]
519
520
521
522 In the **Charts: select widget** window, click **Time series chart**.
523
524
525 [[image:dashboard-5.png||height="525" width="700"]]
526
527
528 Configure the **Time series chart** widget as follows:
529
530 * **Datasource** - select S31B-NB device you provisioned.
531 * **Series**:
532 ** **temperature** - you can see this key by default.
533 ** **humidity** - Click **Add series** button. Then add the **humidity** for the key and then type **%** as its unit.
534 * Click on the **Add** button.
535
536 [[image:timeseries-1.png||height="491" width="700"]]
537
538
539 The time-series chart will appear in edit mode. Resize it by clicking and dragging the lower-right corner.
540
541 Click the **Save** button to add the widget to the dashboard.
542
543
544 [[image:timeseries-3.png||height="347" width="700"]]
545
546
547 Now send the following MQTT messages from the terminal to simulate the data.
548
549
550 {{code language="none"}}
551 mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -t "tb/mqtt-integration-tutorial/sensors/S31B-NB/telemetry" -u "xxxxx" -P "xxxxx" -m '{"temperature":20, "humidity":70}'
552
553 mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -t "tb/mqtt-integration-tutorial/sensors/S31B-NB/telemetry" -u "xxxxx" -P "xxxxx" -m '{"temperature":22, "humidity":71}'
554
555 mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -t "tb/mqtt-integration-tutorial/sensors/S31B-NB/telemetry" -u "xxxxx" -P "xxxxx" -m '{"temperature":18, "humidity":79}'
556
557 {{/code}}
558
559 The chart will update with the values in realtime, as shown in the below image.
560
561
562 [[image:timeseries-4.png||height="316" width="700"]]
563
564
565 = 7. Configure NB-IoT Sensor =
566
567
568 Now, let's experiment with sending data to ThingsBoard using a real NB-IoT device. For example, we will use the **S31B-NB**.
569
570 First, configure the NB-IoT device with the necessary MQTT settings using AT commands. Below is a list of AT commands you can use.
571
572
573 **AT Commands**
574
575 * **AT+PRO=3,3    **~/~/ Use MQTT to connect to ThingsBoard. Payload Type set to 3.
576 * **AT+SUBTOPIC=<MQTT topic>**
577 * **AT+PUBTOPIC=<MQTT topic>**
578 * **AT+CLIENT=null**
579 * **AT+UNAME=<MQTT Username>**
580 * **AT+PWD=<MQTT Password>**
581 * **AT+SERVADDR=<Broker address, Port>**
582
583 Test your uplink by pressing the ACT button for 1 second.

Applications

Navigation

Copyright ©2010-2024 Dragino Technology Co., LTD. All rights reserved
Dragino Wiki v2.0