Wiki source code of ThingsBoard

Version 221.1 by Dilisi S on 2025/04/23 01:38

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

Wiki source code of ThingsBoard

Applications

Navigation