Wiki source code of ThingsBoard

Version 203.1 by Dilisi S on 2025/04/21 16:48

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
195.1	167	= 3. Creating Devices (Optional) =
121.1	168
195.1	169	{{info}}
201.1	170	The following procedure is optional. If you haven't created any device in ThingsBoard first, ThingsBoard will automatically create a device for you based on the integration settings (the device name defined in the uplink decoder) just after it receives the first uplink from your device.
195.1	171	{{/info}}
121.1	172
176.1	173	First, you need to create devices in ThingsBoard to represent your physical devices. For example, you can name it Device A, and the second device could be Device B or any name you prefer. The device name should be unique within the Devices space.
	174
	175
194.1	176	In the left navigation, click Entities -> Devices.
176.1	177
	178	Click the Add Device button (the button with the + sign), and from the dropdown menu, click Add new device.
	179
	180	In the Add new device dialog box, enter the device name in the Name text box. For example, we will use Device A.
	181
	182	Click the Add button.
	183
	184	Skip the connectivity testing by clicking the Close button.
	185
	186	The device is created and listed on the Devices page. Note that its initial state is Inactive because it has not received any data yet.
	187
	188
	189	= 4. Data Converters =
	190
	191
93.1	192	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	193
	194
176.1	195	== 4.1 Uplink ==
11.1	196
	197
93.1	198	In the left navigation, click Integrations center, and then click Data converters.
11.1	199
59.1	200
93.1	201	[[image:data-converters-list-empty.png]]
59.1	202
	203
93.1	204	On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
59.1	205
	206
	207
93.1	208	[[image:create-new-converter-menu.png\|\|height="259" width="500"]]
59.1	209
	210
189.1	211	The Add data converter window will appear.
11.1	212
189.1	213	Let's create an uplink data converter for the device named 'Device A'. Name it ‘MQTT Uplink Converter - Device A’ and select the Type as Uplink.
	214
177.1	215	Click on the TBEL button if it has not been selected by default.
11.1	216
179.1	217	Modify the default TBEL function to match with your device as described below:
157.1	218
	219
182.1	220	* Uncomment line 11:
179.1	221
182.1	222	//var data = decodeToJson(payload)//
179.1	223
	224
201.1	225	* Line 13: Assign your device name to the deviceName field. - We used Device A as it is to match with our device, Device A in the Devices section.
182.1	226	* From line 38: Modify the telemetry section to allow parsed data to be assigned to the fields.
179.1	227
182.1	228	//telemetry: {
179.1	229	temperature: data.temperature,
	230	humidity: data.humidity,
	231	rawData: payloadStr
182.1	232	}//
179.1	233
	234
182.1	235	The modified uplink decoder function to match with Device A is shown below.
179.1	236
11.1	237	{{code language="JavaScript"}}
177.1	238	// Decode an uplink message from a buffer
	239	// payload - array of bytes
	240	// metadata - key/value object
	241
	242	/ Decoder /
	243
11.1	244	// decode payload to string
	245	var payloadStr = decodeToString(payload);
	246
	247	// decode payload to JSON
179.1	248	var data = decodeToJson(payload);
11.1	249
182.1	250	var deviceName = 'Device A';
177.1	251	var deviceType = 'thermostat';
	252	var customerName = 'Customer C';
	253	var groupName = 'thermostat devices';
	254	var manufacturer = 'Example corporation';
	255	// use assetName and assetType instead of deviceName and deviceType
	256	// to automatically create assets instead of devices.
	257	// var assetName = 'Asset A';
	258	// var assetType = 'building';
157.1	259
177.1	260	// Result object with device/asset attributes/telemetry data
11.1	261	var result = {
177.1	262	// Use deviceName and deviceType or assetName and assetType, but not both.
	263	deviceName: deviceName,
	264	deviceType: deviceType,
	265	// assetName: assetName,
	266	// assetType: assetType,
	267	// customerName: customerName,
	268	groupName: groupName,
	269	attributes: {
	270	model: 'Model A',
	271	serialNumber: 'SN111',
	272	integrationName: metadata['integrationName'],
	273	manufacturer: manufacturer
	274	},
	275	telemetry: {
179.1	276	temperature: data.temperature,
	277	humidity: data.humidity,
177.1	278	rawData: payloadStr
	279	}
	280	};
157.1	281
177.1	282	/ Helper functions 'decodeToString' and 'decodeToJson' are already built-in /
157.1	283
177.1	284	return result;
	285	{{/code}}
11.1	286
	287
177.1	288	Once you modify the decoder function, click on the Add button.
11.1	289
	290
	291
189.1	292	[[image:ul-data-converter-device-a.png\|\|height="524" width="500"]]
11.1	293
93.1	294
	295	You should see that the newly added MQTT Uplink converter NB/CB is listed on the Data Converters page.
	296
157.1	297
189.1	298	[[image:ul-data-converter-added.png\|\|height="257"]]
21.1	299
	300
189.1	301
176.1	302	= 5. Add Integration =
93.1	303
	304
21.1	305	In the left navigation, click Integrations center, and then click Integrations.
11.1	306
105.1	307
	308	[[image:integrations-list-empty.png]]
	309
	310
21.1	311	On the Integrations page, click on the '+' button.
11.1	312
	313
21.1	314	The Add integration window appears.
11.1	315
24.1	316	In the Add integration window, configure the following settings:
11.1	317
21.1	318
11.1	319	Basic settings:
	320
49.1	321	* Integration type: MQTT
189.1	322	* Name: MQTT integration - Device A
105.1	323	* Enable integration: YES
201.1	324	* Allow create devices or assets: YES
11.1	325
	326	Click Next button.
	327
105.1	328
189.1	329	[[image:add-integration-basic-settings.png\|\|height="504" width="500"]]
11.1	330
	331
189.1	332
	333
16.1	334	Uplink data converter:
11.1	335
21.1	336	* Click on the Select existing button.
49.1	337	* Uplink data converter: Select MQTT Uplink Converter NB/CB from the dropdown list.
16.1	338
	339	Click Next button.
	340
	341
189.1	342	[[image:add-integration-ul-data-converter.png\|\|height="505" width="500"]]
105.1	343
	344
189.1	345
16.1	346	Downlink data converter:
	347
172.1	348	Dragino NB/CB devices don't require a downlink data converter to decode their payloads, so you can skip this step.
16.1	349
172.1	350	* Click on the Skip button in the Downlink data converter section.
16.1	351
172.1	352	Click Skip button.
16.1	353
105.1	354
172.1	355	[[image:integration-dl-skip.png\|\|height="511" width="500"]]
105.1	356
172.1	357
	358
16.1	359	Connection:
	360
182.1	361	* Host: Host URL (Eg. //011731f7xxxxxxxxxxxfbbedfc63f4.s1.eu.hivemq.cloud//)
93.1	362	* Port: 8883
182.1	363	* Credentials type: Basic
93.1	364	* Username: Username (from your HiveMQ Cloud Cluster with your credentials)
	365	* Password: Password (from your HiveMQ Cloud Cluster with your credentials)
182.1	366	* Enable SSL: YES
	367	* Topic: device/a (The topic can be anything; you can even use just the device name.)
93.1	368	* QoS: 0-At most once
105.1	369
189.1	370	[[image:add-integartion-connection.png\|\|height="505" width="500"]]
	371
	372
105.1	373	Click on the Advanced settings button.
	374
151.1	375	* Clean session: YES
	376	* Retained: YES
16.1	377
105.1	378	[[image:add-integration-connection-advanced-settings.png\|\|height="510" width="500"]]
	379
	380
49.1	381	Click on the Check connection button to verify the MQTT connection using the provided parameters.
16.1	382
49.1	383
105.1	384	[[image:check-connection.png\|\|height="83" width="300"]]
	385
	386
117.1	387	If the connection is successful, you will see the Connected message. If not, check your connection parameters again.
49.1	388
105.1	389
	390	[[image:connection-success.png\|\|height="511" width="500"]]
	391
	392
16.1	393	Click on the Add button.
	394
59.1	395	You should see that the newly added integration is listed on the Integrations page.
49.1	396
59.1	397	Since we haven't received data from a device yet, the integration Status is shown as Pending.
49.1	398
	399
193.1	400	[[image:integration-added.png]]
117.1	401
	402
193.1	403
176.1	404	= 6. Verifying the receipt of data from virtual devices =
49.1	405
16.1	406
176.1	407	== 6.1 How does it work? ==
64.1	408
141.1	409
130.1	410	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.
	411
182.1	412	The Mosquitto client publishes messages (payloads) on the topic /device/a. Of course, you can use any topic for testing.
130.1	413
182.1	414	(% id="cke_bm_37386S" style="display:none" %) (%%)The MQTT payload format is as follows:
130.1	415
64.1	416	{{code language="none"}}
182.1	417	{"IMEI": "350693903995577", "temperature":25, "humidity":80, "pressure":1005}
64.1	418	{{/code}}
	419
182.1	420	Once ThingsBoard receives this message, it forwards this payload to the matching device through the integration.
130.1	421
159.1	422
130.1	423	== 5.2 Sending messages ==
	424
	425
193.1	426	On your computer's terminal, issue the following MQTT command which simulates the device 'Device A'. The message payload contains the fields IMEI, temperature, humidity, and pressure, which hold the values 350693903995577, 30, 80, and 1005 respectively. This payload is also (technically) known as telemetry.
130.1	427
	428	{{code language="none"}}
182.1	429	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}'
130.1	430	{{/code}}
	431
141.1	432	If the integration was performed without errors, the status of the integration changes to 'Active' after the first telemetry transmission.
	433
	434
	435	[[image:integration-active.png]]
	436
	437
176.1	438	== 6.3 Viewing messages ==
141.1	439
	440
167.1	441	Go back to the Integrations page.
141.1	442
167.1	443	Click on the MQTT integration NB/CB in the Integrations page to see its details.
141.1	444
167.1	445	Click on the Edit button (//pen icon//).
141.1	446
167.1	447	Click on the Disabled button in the upper-right corner.
141.1	448
167.1	449	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	450
167.1	451	Click on the Apply button.
141.1	452
167.1	453	Then click on the Apply changes (//tick icon//) button.
141.1	454
167.1	455
193.1	456	[[image:debug-enabled.png\|\|height="301" width="700"]]
167.1	457
	458
193.1	459
	460
167.1	461	Now go to the Events tab.
	462
193.1	463	Select the Event type as Debug from the dropdown list.
167.1	464
193.1	465	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	466
193.1	467	{{code language="none"}}
	468	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}'
	469	{{/code}}
167.1	470
193.1	471	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.
	472
	473
182.1	474	[[image:Screenshot 2025-03-26 at 19.49.31.png]]
167.1	475
	476
182.1	477
167.1	478	Then click on the three dots (...) in the Message column. You can see the uplink message's payload in the Message window.
	479
	480
182.1	481	[[image:Screenshot 2025-03-26 at 19.47.52.png]]
141.1	482
	483
182.1	484
	485
164.1	486	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	487
	488
176.1	489	= 7. Creating a Dashboard =
141.1	490
145.1	491	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	492
	493
145.1	494	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	495
145.1	496
169.1	497	First simulate a few messages using MQTT. This time, we have added the 'humidity' field to the payload. Eg:
	498
196.1	499	{{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	500
	501
145.1	502	In ThingsBoard, from the left navigation menu, click Dashboards. Then, click the + button and select Create new dashboard from the dropdown menu.
	503
	504
141.1	505	[[image:dashboard-1.png]]
	506
	507
	508	In the Title text box, enter NB/CB Test Dashboard as the title of the dashboard.
	509
	510	Click on the Add button.
	511
	512
	513	[[image:dashboard-2.png\|\|height="526" width="500"]]
	514
	515
	516	Click on the Add widget / Add new widget button.
	517
	518
	519	[[image:dashboard-3.png]]
	520
	521
145.1	522	In the Select widgets bundle window, click Charts.
141.1	523
	524
145.1	525	[[image:dashboard-4.png\|\|height="537" width="700"]]
	526
	527
	528
	529	In the Charts: select widget window, click Time series chart.
	530
	531
	532	[[image:dashboard-5.png\|\|height="525" width="700"]]
	533
	534
	535	Configure the Time series chart widget as follows:
	536
196.1	537	* Datasource - select Device A device you provisioned.
149.1	538	* Series:
145.1	539	temperature** - you can see this key by default.
149.1	540	humidity - Click Add series button. Then add the humidity for the key and then type %** as its unit.
145.1	541	* Click on the Add button.
	542
200.1	543	{{info}}
	544	You can add only the relevant fields from the device's payload to display data on a widget. These fields are called 'keys'.
	545	{{/info}}
145.1	546
198.1	547	[[image:Screenshot 2025-03-31 at 06.51.15.png\|\|height="485" width="700"]]
	548
	549
149.1	550	The time-series chart will appear in edit mode. Resize it by clicking and dragging the lower-right corner.
	551
	552	Click the Save button to add the widget to the dashboard.
	553
	554
	555	[[image:timeseries-3.png\|\|height="347" width="700"]]
	556
	557
	558	Now send the following MQTT messages from the terminal to simulate the data.
	559
	560
	561	{{code language="none"}}
196.1	562	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	563
196.1	564	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	565
196.1	566	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	567	{{/code}}
	568
	569	The chart will update with the values in realtime, as shown in the below image.
	570
	571
	572	[[image:timeseries-4.png\|\|height="316" width="700"]]
	573
	574
198.1	575	= 8. Configure Physical NB-IoT Sensor =
146.1	576
	577
172.1	578	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	579
	580	First, configure the NB-IoT device with the necessary MQTT settings using AT commands. Below is a list of AT commands you can use.
	581
	582
	583	AT Commands
	584
149.1	585	* AT+PRO=3,3 ~/~/ Use MQTT to connect to ThingsBoard. Payload Type set to 3.
175.1	586	* AT+SUBTOPIC=<MQTT subscribe topic> Eg: TS01-NB
169.1	587	* AT+PUBTOPIC=<MQTT publish topic> Eg: TS01-NB
150.1	588	* AT+CLIENT=null
	589	* AT+UNAME=<MQTT Username>
	590	* AT+PWD=<MQTT Password>
152.1	591	* AT+SERVADDR=<Broker address, Port>
146.1	592
150.1	593	Test your uplink by pressing the ACT button for 1 second.
172.1	594
167.1	595
	596
196.1	597	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	598
172.1	599
169.1	600	[[image:image-4.png]]

Wiki source code of ThingsBoard

Applications

Navigation