Wiki source code of ThingsBoard

Version 214.1 by Dilisi S on 2025/04/21 18:30

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
121.1	70	== 2.2 HiveMQ Cloud ==
	71
155.1	72	=== 2.2.1 HiveMQ Cloud ===
121.1	73
155.1	74
117.1	75	Go to [[https:~~/~~/www.hivemq.com>>https://www.hivemq.com]]
	76
	77	Click on the Start Free button.
	78
	79	[[image:hivwmq-1.png]]
	80
	81
	82	Click on the Sign Up FREE Now button in the HIVEMQ CLOUD section.
	83
	84	[[image:hivemq-2.png]]
	85
	86
	87	Click on the Sign Up button.
	88
	89	You can sign up with HiveMQ using your GitHub, Google, or LinkedIn account.
	90
	91	If not, provide your email address and a password to create an account by clicking on the Sign Up button.
	92
	93
	94	[[image:hivemq-3.png]]
	95
	96
	97	You will receive an email to verify your email address. Click on the Confirm my account button.
	98
	99
	100	[[image:hivemq-4.jpg\|\|height="889" width="400"]]
	101
	102
	103	You will be redirected to a page asking you to complete your profile. Once done, click the Continue button.
	104
	105
	106	[[image:hivemq-5.png\|\|height="655" width="700"]]
	107
	108
	109	Select the CloudMQ Cloud plan you need. For testing purposes, select the Serverless FREE plan by clicking on the Create Serverless Cluster button.
	110
	111
	112	[[image:hivemq-6.png]]
	113
	114
	115	You will be navigated to the Your Clusters page. Click on the Manage Cluster button.
	116
	117	[[image:hivemq-7.png]]
	118
	119
	120	In your cluster page, you can find some useful parameters you need to create a MQTT connection.
	121
	122	URL: This is the host name. Click on the copy button to copy it.
	123
	124	Port: 8883
	125
	126
121.1	127	Click on the Getting Started tab to setup the username and the password as the connection credentials.
117.1	128
	129
	130	[[image:hivemq-8.png]]
	131
	132
121.1	133	In the 'Create Connection Credentials' section, provide a username and password, then click the Add button.
117.1	134
11.1	135
121.1	136	[[image:hivemq-9.png]]
11.1	137
121.1	138
	139
	140	If everything is successful, you will see the following message.
	141
	142
	143	[[image:hivemq-10.png\|\|height="206" width="500"]]
	144
	145
	146	You will need these MQTT connection parameters when configuring the MQTT integration in the 'Add Integration' section.
	147
	148
155.1	149	=== 2.2.2 emqx ===
	150
	151
	152	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.
	153
	154
	155	[[image:emqx.png\|\|height="420" width="500"]]
	156
	157
	158	=== 2.2.3 Ins1.thingseye.io ===
	159
	160	[[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.
	161
	162	If customers need to use this MQTT connection with ThingsBoard, they need to contact the TE team to obtain three license files.
	163
	164	[[image:ins1.png\|\|height="310" width="500"]]
	165
	166
121.1	167
204.1	168	= 3. Data Converters =
121.1	169
176.1	170
204.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.
176.1	172
204.1	173	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.
176.1	174
	175
204.1	176	== 3.1 Uplink ==
176.1	177
	178
93.1	179	In the left navigation, click Integrations center, and then click Data converters.
11.1	180
59.1	181
93.1	182	[[image:data-converters-list-empty.png]]
59.1	183
	184
204.1	185	On the Data converters page, click on the ‘+’ button, and then click on Create new converter from the dropdown menu.
59.1	186
	187
	188
93.1	189	[[image:create-new-converter-menu.png\|\|height="259" width="500"]]
59.1	190
	191
204.1	192	The Add data converter window appears.
11.1	193
204.1	194	Name it ‘MQTT Uplink Converter’ and select the Type as Uplink.
189.1	195
177.1	196	Click on the TBEL button if it has not been selected by default.
11.1	197
204.1	198	Replace the default TBEL decoder function with the following universal TBEL decoder function, which decodes MQTT payload from any Dragino NB-IoT device.
157.1	199
	200
11.1	201	{{code language="JavaScript"}}
	202	// decode payload to JSON
204.1	203	var pattern = "yyyy/MM/dd HH:mm:ss";
	204	var objdata = {};
	205	var obj1 = {};
179.1	206	var data = decodeToJson(payload);
204.1	207	var deviceName = data.IMEI;
	208	data.remove("IMEI");
	209	var modelname = "Dragino "+ data.Model;
	210	//var mod = data.mod
	211	data.remove("Model");
	212	//delete data.mod
	213	var timestamp = new Date().getTime();
	214	foreach (entry: data.entrySet()) {
	215	var key = entry.getKey();
	216	var value = entry.getValue();
	217	//objdata[key] = data[key]
	218	if(key.matches("^-?\\d+$")){ //is number
	219	obj1[key]=data[key];
	220	var index = obj1[key].length-1;
	221	obj1[key][index]=new Date(obj1[key][index],pattern).getTime();
	222	}
	223	else if (key==="bat"\|\|key==="BAT"){
	224	objdata["battery"] = data[key];
	225	}
	226	else{
	227	objdata[key] = data[key];
	228	}}
	229	var listdata = [{"ts":timestamp,"values":objdata}];
	230	foreach ( entry1: obj1.entrySet()){
	231	var key1 = entry1.getKey();
	232	var value1 = entry1.getValue();
	233	var index = obj1[key1].length-1;
	234	var ts = obj1[key1][index];
	235	if (modelname=="Dragino RS485-NB"){
	236	listdata.push({"ts":ts,"values":{"Payload":obj1[key1][0]}});
	237	}
	238	else{
	239	listdata.push({"ts":ts,"values":{"values":obj1[key1]}});
	240	}
	241	}
	242	var result = {
	243	deviceName: deviceName,
	244	deviceType: modelname,
	245	attributes: {
	246	model: modelname
	247	//customerName: "NB-CB",
	248	//groupName: "NB-CB",
	249	//integrationName: metadata['integrationName']
	250	},
	251	telemetry: listdata
177.1	252	};
	253	return result;
	254	{{/code}}
11.1	255
	256
177.1	257	Once you modify the decoder function, click on the Add button.
11.1	258
	259
204.1	260	[[image:mqtt-uplink-converter.png\|\|height="498" width="500"]]
11.1	261
	262
93.1	263
	264	You should see that the newly added MQTT Uplink converter NB/CB is listed on the Data Converters page.
	265
157.1	266
21.1	267
204.1	268	[[image:data-converters-list.png]]
21.1	269
189.1	270
204.1	271	= 4. Add Integration =
93.1	272
	273
21.1	274	In the left navigation, click Integrations center, and then click Integrations.
11.1	275
105.1	276
	277	[[image:integrations-list-empty.png]]
	278
	279
21.1	280	On the Integrations page, click on the '+' button.
11.1	281
	282
21.1	283	The Add integration window appears.
11.1	284
24.1	285	In the Add integration window, configure the following settings:
11.1	286
21.1	287
11.1	288	Basic settings:
	289
49.1	290	* Integration type: MQTT
208.1	291	* Name: MQTT integration
105.1	292	* Enable integration: YES
201.1	293	* Allow create devices or assets: YES
11.1	294
	295	Click Next button.
	296
105.1	297
11.1	298
208.1	299	[[image:add-integration-part-1.png\|\|height="483" width="500"]]
11.1	300
189.1	301
16.1	302	Uplink data converter:
11.1	303
21.1	304	* Click on the Select existing button.
49.1	305	* Uplink data converter: Select MQTT Uplink Converter NB/CB from the dropdown list.
16.1	306
	307	Click Next button.
	308
	309
105.1	310
208.1	311	[[image:add-integration-part-2.png\|\|height="484" width="500"]]
105.1	312
189.1	313
16.1	314	Downlink data converter:
	315
172.1	316	Dragino NB/CB devices don't require a downlink data converter to decode their payloads, so you can skip this step.
16.1	317
172.1	318	* Click on the Skip button in the Downlink data converter section.
16.1	319
172.1	320	Click Skip button.
16.1	321
105.1	322
172.1	323	[[image:integration-dl-skip.png\|\|height="511" width="500"]]
105.1	324
172.1	325
	326
16.1	327	Connection:
	328
208.1	329	* Host: Host URL (Eg, //011731f7xxxxxxxxxxxfbbedfc63f4.s1.eu.hivemq.cloud//)
	330	* Port: 8883 (the port number may differ based on your MQTT broker)
182.1	331	* Credentials type: Basic
93.1	332	* Username: Username (from your HiveMQ Cloud Cluster with your credentials)
	333	* Password: Password (from your HiveMQ Cloud Cluster with your credentials)
182.1	334	* Enable SSL: YES
208.1	335	* Topic: # (the # symbol indicates that it filters all topics).
93.1	336	* QoS: 0-At most once
105.1	337
189.1	338
208.1	339	[[image:add-integration-4.png\|\|height="484" width="500"]]
	340
	341
105.1	342	Click on the Advanced settings button.
	343
151.1	344	* Clean session: YES
	345	* Retained: YES
16.1	346
105.1	347	[[image:add-integration-connection-advanced-settings.png\|\|height="510" width="500"]]
	348
	349
49.1	350	Click on the Check connection button to verify the MQTT connection using the provided parameters.
16.1	351
49.1	352
105.1	353	[[image:check-connection.png\|\|height="83" width="300"]]
	354
	355
117.1	356	If the connection is successful, you will see the Connected message. If not, check your connection parameters again.
49.1	357
105.1	358
	359	[[image:connection-success.png\|\|height="511" width="500"]]
	360
	361
16.1	362	Click on the Add button.
	363
59.1	364	You should see that the newly added integration is listed on the Integrations page.
49.1	365
59.1	366	Since we haven't received data from a device yet, the integration Status is shown as Pending.
49.1	367
	368
117.1	369
213.1	370	[[image:integrations-pending.png]]
117.1	371
193.1	372
204.1	373	= 5. Verifying the receipt of data from virtual devices =
49.1	374
16.1	375
204.1	376	== 5.1 How does it work? ==
64.1	377
141.1	378
130.1	379	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.
	380
213.1	381	The Mosquitto client publishes messages (payloads) to a topic - for example, # or device/ts01-nb. You can, of course, use any topic you prefer.
130.1	382
	383
213.1	384	(% 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.
	385
64.1	386	{{code language="none"}}
213.1	387	{"IMEI":"350693903995577", "Model":"TS01-NB", "temperature":30, "humidity":80, "pressure":1005}
64.1	388	{{/code}}
	389
130.1	390
	391	== 5.2 Sending messages ==
	392
	393
213.1	394	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.
130.1	395
	396	{{code language="none"}}
213.1	397	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}'
130.1	398	{{/code}}
	399
213.1	400	If the integration was performed without errors, a new device named 350693903995577 is created in the Devices section.
141.1	401
	402
213.1	403	[[image:new-device-1.png]]
141.1	404
	405
213.1	406	The status of the integration also changes to 'Active' after the first telemetry transmission.
	407
	408
	409	[[image:Screenshot 2025-04-21 122154.png]]
	410
	411
	412
	413	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.
	414
	415
204.1	416	== 5.3 Viewing messages ==
141.1	417
	418
167.1	419	Go back to the Integrations page.
141.1	420
167.1	421	Click on the MQTT integration NB/CB in the Integrations page to see its details.
141.1	422
167.1	423	Click on the Edit button (//pen icon//).
141.1	424
167.1	425	Click on the Disabled button in the upper-right corner.
141.1	426
167.1	427	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.
141.1	428
167.1	429	Click on the Apply button.
141.1	430
167.1	431	Then click on the Apply changes (//tick icon//) button.
141.1	432
167.1	433
193.1	434	[[image:debug-enabled.png\|\|height="301" width="700"]]
167.1	435
	436
193.1	437
	438
167.1	439	Now go to the Events tab.
	440
193.1	441	Select the Event type as Debug from the dropdown list.
167.1	442
193.1	443	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:
167.1	444
193.1	445	{{code language="none"}}
	446	mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -u "xxxxx" -P "xxxxx" -t "device/a" -m '{"IMEI":"350693903995577", "temperature":30, "humidity":80, "pressure":1005}'
	447	{{/code}}
167.1	448
193.1	449	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.
	450
	451
182.1	452	[[image:Screenshot 2025-03-26 at 19.49.31.png]]
167.1	453
	454
182.1	455
167.1	456	Then click on the three dots (...) in the Message column. You can see the uplink message's payload in the Message window.
	457
	458
182.1	459	[[image:Screenshot 2025-03-26 at 19.47.52.png]]
141.1	460
	461
182.1	462
	463
164.1	464	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.
141.1	465
	466
204.1	467	= 6. Creating a Dashboard =
141.1	468
145.1	469	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	470
	471
145.1	472	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	473
145.1	474
169.1	475	First simulate a few messages using MQTT. This time, we have added the 'humidity' field to the payload. Eg:
	476
196.1	477	{{code language="none"}}mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -u "xxxxx" -P "xxxxx" -t "device/a" -m '{"IMEI":"350693903995577", "temperature":22, "humidity":80, "pressure":1005}'{{/code}}
169.1	478
	479
145.1	480	In ThingsBoard, from the left navigation menu, click Dashboards. Then, click the + button and select Create new dashboard from the dropdown menu.
	481
	482
141.1	483	[[image:dashboard-1.png]]
	484
	485
	486	In the Title text box, enter NB/CB Test Dashboard as the title of the dashboard.
	487
	488	Click on the Add button.
	489
	490
	491	[[image:dashboard-2.png\|\|height="526" width="500"]]
	492
	493
	494	Click on the Add widget / Add new widget button.
	495
	496
	497	[[image:dashboard-3.png]]
	498
	499
145.1	500	In the Select widgets bundle window, click Charts.
141.1	501
	502
145.1	503	[[image:dashboard-4.png\|\|height="537" width="700"]]
	504
	505
	506
	507	In the Charts: select widget window, click Time series chart.
	508
	509
	510	[[image:dashboard-5.png\|\|height="525" width="700"]]
	511
	512
	513	Configure the Time series chart widget as follows:
	514
196.1	515	* Datasource - select Device A device you provisioned.
149.1	516	* Series:
145.1	517	temperature** - you can see this key by default.
149.1	518	humidity - Click Add series button. Then add the humidity for the key and then type %** as its unit.
145.1	519	* Click on the Add button.
	520
200.1	521	{{info}}
	522	You can add only the relevant fields from the device's payload to display data on a widget. These fields are called 'keys'.
	523	{{/info}}
145.1	524
198.1	525	[[image:Screenshot 2025-03-31 at 06.51.15.png\|\|height="485" width="700"]]
	526
	527
149.1	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:timeseries-3.png\|\|height="347" width="700"]]
	534
	535
	536	Now send the following MQTT messages from the terminal to simulate the data.
	537
	538
	539	{{code language="none"}}
196.1	540	mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -u "xxxxx" -P "xxxxx" -t "device/a" -m '{"IMEI":"350693903995577", "temperature":22, "humidity":70, "pressure":1005}'
149.1	541
196.1	542	mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -u "xxxxx" -P "xxxxx" -t "device/a" -m '{"IMEI":"350693903995577", "temperature":27, "humidity":72, "pressure":1005}'
149.1	543
196.1	544	mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -u "xxxxx" -P "xxxxx" -t "device/a" -m '{"IMEI":"350693903995577", "temperature":19, "humidity":80, "pressure":1005}'
149.1	545	{{/code}}
	546
	547	The chart will update with the values in realtime, as shown in the below image.
	548
	549
	550	[[image:timeseries-4.png\|\|height="316" width="700"]]
	551
	552
198.1	553	= 8. Configure Physical NB-IoT Sensor =
146.1	554
	555
172.1	556	Now, let's experiment with sending data to ThingsBoard using a real NB-IoT device. For example, we will use the TS01-NB.
146.1	557
	558	First, configure the NB-IoT device with the necessary MQTT settings using AT commands. Below is a list of AT commands you can use.
	559
	560
	561	AT Commands
	562
149.1	563	* AT+PRO=3,3 ~/~/ Use MQTT to connect to ThingsBoard. Payload Type set to 3.
175.1	564	* AT+SUBTOPIC=<MQTT subscribe topic> Eg: TS01-NB
169.1	565	* AT+PUBTOPIC=<MQTT publish topic> Eg: TS01-NB
150.1	566	* AT+CLIENT=null
	567	* AT+UNAME=<MQTT Username>
	568	* AT+PWD=<MQTT Password>
152.1	569	* AT+SERVADDR=<Broker address, Port>
146.1	570
150.1	571	Test your uplink by pressing the ACT button for 1 second.
172.1	572
167.1	573
	574
196.1	575	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.
167.1	576
172.1	577
169.1	578	[[image:image-4.png]]

Wiki source code of ThingsBoard

Applications

Navigation