Wiki source code of ThingsBoard

Version 146.1 by Dilisi S on 2025/03/09 15:12

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
117.1	25	* HiveMQ Cloud account
59.1	26
121.1	27	== 2.1 ThingsBoard Cloud ==
117.1	28
	29
125.1	30	Go to [[https:~~/~~/thingsboard.io/>>https://thingsboard.io/]]
121.1	31
125.1	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
129.1	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.
125.1	44
129.1	45	Click on the Sign up button.
	46
125.1	47	[[image:thingsboard-3.png\|\|height="651" width="500"]]
	48
	49
129.1	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
121.1	67	== 2.2 HiveMQ Cloud ==
	68
	69
117.1	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
121.1	122	Click on the Getting Started tab to setup the username and the password as the connection credentials.
117.1	123
	124
	125	[[image:hivemq-8.png]]
	126
	127
121.1	128	In the 'Create Connection Credentials' section, provide a username and password, then click the Add button.
117.1	129
11.1	130
121.1	131	[[image:hivemq-9.png]]
11.1	132
121.1	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
93.1	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.
11.1	148
	149
121.1	150	== 3.1 Uplink ==
11.1	151
	152
93.1	153	In the left navigation, click Integrations center, and then click Data converters.
11.1	154
59.1	155
	156
93.1	157	[[image:data-converters-list-empty.png]]
59.1	158
	159
93.1	160	On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
59.1	161
	162
	163
93.1	164	[[image:create-new-converter-menu.png\|\|height="259" width="500"]]
59.1	165
	166
36.1	167	The Add data converter window will appear. Name it ‘MQTT Uplink Converter NB/CB’ and select the Type as Uplink.
11.1	168
93.1	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.
11.1	170
	171	{{code language="JavaScript"}}
93.1	172	/ Decoder /
	173
11.1	174	// decode payload to string
	175	var payloadStr = decodeToString(payload);
93.1	176	var data = JSON.parse(payloadStr);
11.1	177
93.1	178	var deviceName = metadata.topic.split("/")[3];
11.1	179	// decode payload to JSON
93.1	180	var deviceType = 'sensor';
11.1	181
93.1	182	// Result object with device attributes/telemetry data
11.1	183	var result = {
	184	deviceName: deviceName,
93.1	185	deviceType: deviceType,
11.1	186	attributes: {
93.1	187	integrationName: metadata['integrationName'],
11.1	188	},
93.1	189	telemetry: {
	190	temperature: data.temperature,
	191	humidity: data.humidity,
	192	}
	193	};
11.1	194
93.1	195	/ Helper functions 'decodeToString' and 'decodeToJson' are already built-in /
11.1	196
	197	return result;
	198	{{/code}}
	199
64.2	200
21.1	201	Click on the Add button.
11.1	202
	203
	204
93.1	205	[[image:add-uplink-data-converter.png\|\|height="529" width="500"]]
11.1	206
93.1	207
	208	You should see that the newly added MQTT Uplink converter NB/CB is listed on the Data Converters page.
	209
105.1	210	[[image:data-converter-list-showing-uplink-dc.png]]
21.1	211
	212
94.1	213
64.2	214	== 3.2 Downlink ==
11.1	215
64.2	216
21.1	217	On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
11.1	218
	219
105.1	220	[[image:create-new-converter-menu.png\|\|width="500"]]
11.1	221
105.1	222
	223
36.1	224	The Add data converter window will appear. Name it ‘MQTT Downlink Converter NB/CB’ and select the Type as Downlink.
11.1	225
93.1	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.
11.1	227
	228
	229	{{code language="JavaScript"}}
93.1	230	// Encode downlink data from incoming Rule Engine message
11.1	231
93.1	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
11.1	248	// Result object with encoded downlink payload
	249	var result = {
93.1	250
11.1	251	// downlink data content type: JSON, TEXT or BINARY (base64 format)
93.1	252	contentType: "JSON",
11.1	253
	254	// downlink data
93.1	255	data: JSON.stringify(data),
11.1	256
	257	// Optional metadata object presented in key/value format
93.1	258	metadata: {
	259	topic: metadata['deviceType']+'/'+metadata['deviceName']+'/upload'
	260	}
11.1	261
	262	};
	263
	264	return result;
	265	{{/code}}
	266
	267
	268	Click on the Add button.
	269
	270
	271
93.1	272	[[image:add-downlink-data-converter.png\|\|height="529" width="500"]]
21.1	273
	274
93.1	275	You should see that the newly added MQTT Downlink Converter NB/CB is listed on the Data Converters page.
21.1	276
11.1	277
93.1	278	[[image:data-converters-list.png]]
	279
105.1	280
	281
121.1	282	= 4. Add Integration =
93.1	283
	284
21.1	285	In the left navigation, click Integrations center, and then click Integrations.
11.1	286
105.1	287
	288	[[image:integrations-list-empty.png]]
	289
	290
21.1	291	On the Integrations page, click on the '+' button.
11.1	292
	293
21.1	294	The Add integration window appears.
11.1	295
24.1	296	In the Add integration window, configure the following settings:
11.1	297
21.1	298
11.1	299	Basic settings:
	300
49.1	301	* Integration type: MQTT
	302	* Name: MQTT integration NB/CB
105.1	303	* Enable integration: YES
	304	* Allows create devices or assets: YES
11.1	305
	306	Click Next button.
	307
105.1	308
	309
16.1	310	[[image:add-integration-basic-settings.png\|\|height="511" width="500"]]
11.1	311
	312
16.1	313	Uplink data converter:
11.1	314
21.1	315	* Click on the Select existing button.
49.1	316	* Uplink data converter: Select MQTT Uplink Converter NB/CB from the dropdown list.
16.1	317
	318	Click Next button.
	319
	320
	321
105.1	322	[[image:add-integration-uplink-data-converter.png\|\|height="511" width="500"]]
	323
	324
16.1	325	Downlink data converter:
	326
21.1	327	* Click on the Select existing button.
49.1	328	* Downlink data converter: Select MQTT Downlink Converter NB/CB from the dropdown list.
16.1	329
	330	Click Next button.
	331
	332
	333
105.1	334	[[image:add-integration-downlink-data-converter.png\|\|height="511" width="500"]]
	335
	336
16.1	337	Connection:
	338
93.1	339	* Host: Cluster URL (Eg. 011731f7928541588a6cdfbbedfc63f4.s1.eu.hivemq.cloud)
	340	* Port: 8883
49.1	341	* Credentials: Basic
93.1	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
105.1	347
	348	[[image:add-integration-connection.png\|\|height="511" width="500"]]
	349
	350
	351	Click on the Advanced settings button.
	352
93.1	353	* Clean session: NO
	354	* Retained: NO
16.1	355
105.1	356	[[image:add-integration-connection-advanced-settings.png\|\|height="510" width="500"]]
	357
	358
49.1	359	Click on the Check connection button to verify the MQTT connection using the provided parameters.
16.1	360
49.1	361
105.1	362	[[image:check-connection.png\|\|height="83" width="300"]]
	363
	364
117.1	365	If the connection is successful, you will see the Connected message. If not, check your connection parameters again.
49.1	366
105.1	367
	368	[[image:connection-success.png\|\|height="511" width="500"]]
	369
	370
16.1	371	Click on the Add button.
	372
59.1	373	You should see that the newly added integration is listed on the Integrations page.
49.1	374
59.1	375	Since we haven't received data from a device yet, the integration Status is shown as Pending.
49.1	376
	377
	378
117.1	379	[[image:new-integration-pending.png]]
	380
	381
130.1	382	= 5. Verifying the receipt of data from virtual devices =
49.1	383
16.1	384
130.1	385	== 5.1 How does it work? ==
64.1	386
141.1	387
130.1	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
141.1	401	1. v1/devices/LDS25-NB/telemetry
130.1	402
141.1	403	ThingsBoard will create two devices named S31B-NB and LDS25-NB in the //Devices// section.
130.1	404
	405
141.1	406	The MQTT payload format is as follows, which is common for all ~-~-NB and ~-~-CB series devices:
130.1	407
64.1	408	{{code language="none"}}
130.1	409	{"temperature":10.4, "humidity":85}
64.1	410	{{/code}}
	411
130.1	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"}}
141.1	419	mosquitto_pub -d -q 1 -h 011731f7928541588a6cdfbbedfc63f4.s1.eu.hivemq.cloud -p 8883 -t "tb/mqtt-integration-tutorial/sensors/S31B-NB/telemetry" -u "pradeeka" -P "Kalpani123@" -m '{"temperature":10.4, "humidity":85}'
130.1	420	{{/code}}
	421
141.1	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
145.1	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.
141.1	466
	467
145.1	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.
141.1	469
145.1	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
141.1	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
145.1	491	In the Select widgets bundle window, click Charts.
141.1	492
	493
145.1	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 to add the humidity and then type %** as its unit.
	510	* Click on the Add button.
	511
	512	[[image:timeseries-1.png\|\|height="491" width="700"]]
	513
146.1	514
	515	= 7. Configure NB-IoT Sensor =
	516
	517
	518	Now, let's experiment with sending data to ThingsBoard using a real NB-IoT device. For example, we will use the S31B-NB.
	519
	520	First, configure the NB-IoT device with the necessary MQTT settings using AT commands. Below is a list of AT commands you can use.
	521
	522
	523	AT Commands
	524
	525	* AT+PRO=3,3 ~/~/ Use MQTT to connect to ThingsBoard. Payload Type set to 3.
	526
	527	* AT+SUBTOPIC=<device name> Eg.
	528
	529	* AT+PUBTOPIC=<device name>
	530
	531	* AT+CLIENT=<device name> or User Defined
	532
	533	* AT+UNAME=<device name> or User Defined
	534
	535	* AT+PWD=<device name> or User Defined
	536
	537	Test Uplink by click the button for 1 second
	538
	539

Wiki source code of ThingsBoard

Applications

Navigation