Wiki source code of ThingsBoard

Version 155.1 by Dilisi S on 2025/03/17 00:27

version	line-number	content
1.1	1	Table of Contents:
	2
	3	{{toc/}}
	4
16.1	5	{{warning}}
	6	Draft Document
	7	{{/warning}}
1.1	8
65.1	9
	10
	11
64.2	12	= 1. Introduction =
1.1	13
64.2	14
21.1	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.
2.1	16
21.1	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.
11.1	18
17.1	19
117.1	20	= 2. Prerequisites =
11.1	21
117.1	22	To complete this tutorial, you need to have the following:
64.2	23
121.1	24	* ThingsBoard cloud account
155.1	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.
59.1	29
121.1	30	== 2.1 ThingsBoard Cloud ==
117.1	31
	32
125.1	33	Go to [[https:~~/~~/thingsboard.io/>>https://thingsboard.io/]]
121.1	34
125.1	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
129.1	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.
125.1	47
129.1	48	Click on the Sign up button.
	49
125.1	50	[[image:thingsboard-3.png\|\|height="651" width="500"]]
	51
	52
129.1	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
155.1	70	(% class="wikigeneratedid" %)
121.1	71	== 2.2 HiveMQ Cloud ==
	72
155.1	73	=== 2.2.1 HiveMQ Cloud ===
121.1	74
155.1	75
117.1	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
121.1	128	Click on the Getting Started tab to setup the username and the password as the connection credentials.
117.1	129
	130
	131	[[image:hivemq-8.png]]
	132
	133
121.1	134	In the 'Create Connection Credentials' section, provide a username and password, then click the Add button.
117.1	135
11.1	136
121.1	137	[[image:hivemq-9.png]]
11.1	138
121.1	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
155.1	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
121.1	168	= 3. Data Converters =
	169
	170
93.1	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.
11.1	172
	173
121.1	174	== 3.1 Uplink ==
11.1	175
	176
93.1	177	In the left navigation, click Integrations center, and then click Data converters.
11.1	178
59.1	179
	180
93.1	181	[[image:data-converters-list-empty.png]]
59.1	182
	183
93.1	184	On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
59.1	185
	186
	187
93.1	188	[[image:create-new-converter-menu.png\|\|height="259" width="500"]]
59.1	189
	190
36.1	191	The Add data converter window will appear. Name it ‘MQTT Uplink Converter NB/CB’ and select the Type as Uplink.
11.1	192
93.1	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.
11.1	194
	195	{{code language="JavaScript"}}
93.1	196	/ Decoder /
	197
11.1	198	// decode payload to string
	199	var payloadStr = decodeToString(payload);
93.1	200	var data = JSON.parse(payloadStr);
11.1	201
93.1	202	var deviceName = metadata.topic.split("/")[3];
11.1	203	// decode payload to JSON
93.1	204	var deviceType = 'sensor';
11.1	205
93.1	206	// Result object with device attributes/telemetry data
11.1	207	var result = {
	208	deviceName: deviceName,
93.1	209	deviceType: deviceType,
11.1	210	attributes: {
93.1	211	integrationName: metadata['integrationName'],
11.1	212	},
93.1	213	telemetry: {
	214	temperature: data.temperature,
	215	humidity: data.humidity,
	216	}
	217	};
11.1	218
93.1	219	/ Helper functions 'decodeToString' and 'decodeToJson' are already built-in /
11.1	220
	221	return result;
	222	{{/code}}
	223
64.2	224
21.1	225	Click on the Add button.
11.1	226
	227
	228
93.1	229	[[image:add-uplink-data-converter.png\|\|height="529" width="500"]]
11.1	230
93.1	231
	232	You should see that the newly added MQTT Uplink converter NB/CB is listed on the Data Converters page.
	233
105.1	234	[[image:data-converter-list-showing-uplink-dc.png]]
21.1	235
	236
94.1	237
64.2	238	== 3.2 Downlink ==
11.1	239
64.2	240
21.1	241	On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
11.1	242
	243
105.1	244	[[image:create-new-converter-menu.png\|\|width="500"]]
11.1	245
105.1	246
	247
36.1	248	The Add data converter window will appear. Name it ‘MQTT Downlink Converter NB/CB’ and select the Type as Downlink.
11.1	249
93.1	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.
11.1	251
	252
	253	{{code language="JavaScript"}}
93.1	254	// Encode downlink data from incoming Rule Engine message
11.1	255
93.1	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
11.1	272	// Result object with encoded downlink payload
	273	var result = {
93.1	274
11.1	275	// downlink data content type: JSON, TEXT or BINARY (base64 format)
93.1	276	contentType: "JSON",
11.1	277
	278	// downlink data
93.1	279	data: JSON.stringify(data),
11.1	280
	281	// Optional metadata object presented in key/value format
93.1	282	metadata: {
	283	topic: metadata['deviceType']+'/'+metadata['deviceName']+'/upload'
	284	}
11.1	285
	286	};
	287
	288	return result;
	289	{{/code}}
	290
	291
	292	Click on the Add button.
	293
	294
	295
93.1	296	[[image:add-downlink-data-converter.png\|\|height="529" width="500"]]
21.1	297
	298
93.1	299	You should see that the newly added MQTT Downlink Converter NB/CB is listed on the Data Converters page.
21.1	300
11.1	301
93.1	302	[[image:data-converters-list.png]]
	303
105.1	304
	305
121.1	306	= 4. Add Integration =
93.1	307
	308
21.1	309	In the left navigation, click Integrations center, and then click Integrations.
11.1	310
105.1	311
	312	[[image:integrations-list-empty.png]]
	313
	314
21.1	315	On the Integrations page, click on the '+' button.
11.1	316
	317
21.1	318	The Add integration window appears.
11.1	319
24.1	320	In the Add integration window, configure the following settings:
11.1	321
21.1	322
11.1	323	Basic settings:
	324
49.1	325	* Integration type: MQTT
	326	* Name: MQTT integration NB/CB
105.1	327	* Enable integration: YES
	328	* Allows create devices or assets: YES
11.1	329
	330	Click Next button.
	331
105.1	332
	333
16.1	334	[[image:add-integration-basic-settings.png\|\|height="511" width="500"]]
11.1	335
	336
16.1	337	Uplink data converter:
11.1	338
21.1	339	* Click on the Select existing button.
49.1	340	* Uplink data converter: Select MQTT Uplink Converter NB/CB from the dropdown list.
16.1	341
	342	Click Next button.
	343
	344
	345
105.1	346	[[image:add-integration-uplink-data-converter.png\|\|height="511" width="500"]]
	347
	348
16.1	349	Downlink data converter:
	350
21.1	351	* Click on the Select existing button.
49.1	352	* Downlink data converter: Select MQTT Downlink Converter NB/CB from the dropdown list.
16.1	353
	354	Click Next button.
	355
	356
	357
105.1	358	[[image:add-integration-downlink-data-converter.png\|\|height="511" width="500"]]
	359
	360
16.1	361	Connection:
	362
93.1	363	* Host: Cluster URL (Eg. 011731f7928541588a6cdfbbedfc63f4.s1.eu.hivemq.cloud)
	364	* Port: 8883
49.1	365	* Credentials: Basic
93.1	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
105.1	371
	372	[[image:add-integration-connection.png\|\|height="511" width="500"]]
	373
	374
	375	Click on the Advanced settings button.
	376
151.1	377	* Clean session: YES
	378	* Retained: YES
16.1	379
105.1	380	[[image:add-integration-connection-advanced-settings.png\|\|height="510" width="500"]]
	381
	382
49.1	383	Click on the Check connection button to verify the MQTT connection using the provided parameters.
16.1	384
49.1	385
105.1	386	[[image:check-connection.png\|\|height="83" width="300"]]
	387
	388
117.1	389	If the connection is successful, you will see the Connected message. If not, check your connection parameters again.
49.1	390
105.1	391
	392	[[image:connection-success.png\|\|height="511" width="500"]]
	393
	394
16.1	395	Click on the Add button.
	396
59.1	397	You should see that the newly added integration is listed on the Integrations page.
49.1	398
59.1	399	Since we haven't received data from a device yet, the integration Status is shown as Pending.
49.1	400
	401
	402
117.1	403	[[image:new-integration-pending.png]]
	404
	405
130.1	406	= 5. Verifying the receipt of data from virtual devices =
49.1	407
16.1	408
130.1	409	== 5.1 How does it work? ==
64.1	410
141.1	411
130.1	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
141.1	425	1. v1/devices/LDS25-NB/telemetry
130.1	426
141.1	427	ThingsBoard will create two devices named S31B-NB and LDS25-NB in the //Devices// section.
130.1	428
	429
141.1	430	The MQTT payload format is as follows, which is common for all ~-~-NB and ~-~-CB series devices:
130.1	431
64.1	432	{{code language="none"}}
130.1	433	{"temperature":10.4, "humidity":85}
64.1	434	{{/code}}
	435
130.1	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"}}
150.1	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}'
130.1	444	{{/code}}
	445
141.1	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
145.1	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.
141.1	490
	491
145.1	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.
141.1	493
145.1	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
141.1	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
145.1	515	In the Select widgets bundle window, click Charts.
141.1	516
	517
145.1	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
149.1	530	* Datasource - select S31B-NB device you provisioned.
	531	* Series:
145.1	532	temperature** - you can see this key by default.
149.1	533	humidity - Click Add series button. Then add the humidity for the key and then type %** as its unit.
145.1	534	* Click on the Add button.
	535
	536	[[image:timeseries-1.png\|\|height="491" width="700"]]
	537
146.1	538
149.1	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"}}
150.1	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}'
149.1	552
150.1	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}'
149.1	554
150.1	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}'
149.1	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
146.1	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
149.1	575	* AT+PRO=3,3 ~/~/ Use MQTT to connect to ThingsBoard. Payload Type set to 3.
152.1	576	* AT+SUBTOPIC=<MQTT topic>
	577	* AT+PUBTOPIC=<MQTT topic>
150.1	578	* AT+CLIENT=null
	579	* AT+UNAME=<MQTT Username>
	580	* AT+PWD=<MQTT Password>
152.1	581	* AT+SERVADDR=<Broker address, Port>
146.1	582
150.1	583	Test your uplink by pressing the ACT button for 1 second.

Wiki source code of ThingsBoard

Applications

Navigation