Wiki source code of ThingsBoard

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