Wiki source code of ThingsBoard

Version 190.1 by Dilisi S on 2025/03/27 23:15

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
176.1	167	= 3. Creating Devices =
121.1	168
	169
176.1	170	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.
	171
	172
	173	In the left navigation, click Entities -> Devices.
	174
	175	Click the Add Device button (the button with the + sign), and from the dropdown menu, click Add new device.
	176
	177	In the Add new device dialog box, enter the device name in the Name text box. For example, we will use Device A.
	178
	179	Click the Add button.
	180
	181	Skip the connectivity testing by clicking the Close button.
	182
	183	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.
	184
	185
	186	= 4. Data Converters =
	187
	188
93.1	189	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	190
	191
176.1	192	== 4.1 Uplink ==
11.1	193
	194
93.1	195	In the left navigation, click Integrations center, and then click Data converters.
11.1	196
59.1	197
93.1	198	[[image:data-converters-list-empty.png]]
59.1	199
	200
93.1	201	On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
59.1	202
	203
	204
93.1	205	[[image:create-new-converter-menu.png\|\|height="259" width="500"]]
59.1	206
	207
189.1	208	The Add data converter window will appear.
11.1	209
189.1	210	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.
	211
177.1	212	Click on the TBEL button if it has not been selected by default.
11.1	213
179.1	214	Modify the default TBEL function to match with your device as described below:
157.1	215
	216
182.1	217	* Uncomment line 11:
179.1	218
182.1	219	//var data = decodeToJson(payload)//
179.1	220
	221
182.1	222	* 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.
	223	* From line 38: Modify the telemetry section to allow parsed data to be assigned to the fields.
179.1	224
182.1	225	//telemetry: {
179.1	226	temperature: data.temperature,
	227	humidity: data.humidity,
	228	rawData: payloadStr
182.1	229	}//
179.1	230
	231
182.1	232	The modified uplink decoder function to match with Device A is shown below.
179.1	233
11.1	234	{{code language="JavaScript"}}
177.1	235	// Decode an uplink message from a buffer
	236	// payload - array of bytes
	237	// metadata - key/value object
	238
	239	/ Decoder /
	240
11.1	241	// decode payload to string
	242	var payloadStr = decodeToString(payload);
	243
	244	// decode payload to JSON
179.1	245	var data = decodeToJson(payload);
11.1	246
182.1	247	var deviceName = 'Device A';
177.1	248	var deviceType = 'thermostat';
	249	var customerName = 'Customer C';
	250	var groupName = 'thermostat devices';
	251	var manufacturer = 'Example corporation';
	252	// use assetName and assetType instead of deviceName and deviceType
	253	// to automatically create assets instead of devices.
	254	// var assetName = 'Asset A';
	255	// var assetType = 'building';
157.1	256
177.1	257	// Result object with device/asset attributes/telemetry data
11.1	258	var result = {
177.1	259	// Use deviceName and deviceType or assetName and assetType, but not both.
	260	deviceName: deviceName,
	261	deviceType: deviceType,
	262	// assetName: assetName,
	263	// assetType: assetType,
	264	// customerName: customerName,
	265	groupName: groupName,
	266	attributes: {
	267	model: 'Model A',
	268	serialNumber: 'SN111',
	269	integrationName: metadata['integrationName'],
	270	manufacturer: manufacturer
	271	},
	272	telemetry: {
179.1	273	temperature: data.temperature,
	274	humidity: data.humidity,
177.1	275	rawData: payloadStr
	276	}
	277	};
157.1	278
177.1	279	/ Helper functions 'decodeToString' and 'decodeToJson' are already built-in /
157.1	280
177.1	281	return result;
	282	{{/code}}
11.1	283
	284
177.1	285	Once you modify the decoder function, click on the Add button.
11.1	286
	287
	288
189.1	289	[[image:ul-data-converter-device-a.png\|\|height="524" width="500"]]
11.1	290
93.1	291
	292	You should see that the newly added MQTT Uplink converter NB/CB is listed on the Data Converters page.
	293
157.1	294
189.1	295	[[image:ul-data-converter-added.png\|\|height="257"]]
21.1	296
	297
189.1	298
176.1	299	= 5. Add Integration =
93.1	300
	301
21.1	302	In the left navigation, click Integrations center, and then click Integrations.
11.1	303
105.1	304
	305	[[image:integrations-list-empty.png]]
	306
	307
21.1	308	On the Integrations page, click on the '+' button.
11.1	309
	310
21.1	311	The Add integration window appears.
11.1	312
24.1	313	In the Add integration window, configure the following settings:
11.1	314
21.1	315
11.1	316	Basic settings:
	317
49.1	318	* Integration type: MQTT
189.1	319	* Name: MQTT integration - Device A
105.1	320	* Enable integration: YES
	321	* Allows create devices or assets: YES
11.1	322
	323	Click Next button.
	324
105.1	325
189.1	326	[[image:add-integration-basic-settings.png\|\|height="504" width="500"]]
11.1	327
	328
189.1	329
	330
16.1	331	Uplink data converter:
11.1	332
21.1	333	* Click on the Select existing button.
49.1	334	* Uplink data converter: Select MQTT Uplink Converter NB/CB from the dropdown list.
16.1	335
	336	Click Next button.
	337
	338
189.1	339	[[image:add-integration-ul-data-converter.png\|\|height="505" width="500"]]
105.1	340
	341
189.1	342
16.1	343	Downlink data converter:
	344
172.1	345	Dragino NB/CB devices don't require a downlink data converter to decode their payloads, so you can skip this step.
16.1	346
172.1	347	* Click on the Skip button in the Downlink data converter section.
16.1	348
172.1	349	Click Skip button.
16.1	350
105.1	351
172.1	352	[[image:integration-dl-skip.png\|\|height="511" width="500"]]
105.1	353
172.1	354
	355
16.1	356	Connection:
	357
182.1	358	* Host: Host URL (Eg. //011731f7xxxxxxxxxxxfbbedfc63f4.s1.eu.hivemq.cloud//)
93.1	359	* Port: 8883
182.1	360	* Credentials type: Basic
93.1	361	* Username: Username (from your HiveMQ Cloud Cluster with your credentials)
	362	* Password: Password (from your HiveMQ Cloud Cluster with your credentials)
182.1	363	* Enable SSL: YES
	364	* Topic: device/a (The topic can be anything; you can even use just the device name.)
93.1	365	* QoS: 0-At most once
105.1	366
	367
	368
189.1	369	[[image:add-integartion-connection.png\|\|height="505" width="500"]]
	370
	371
105.1	372	Click on the Advanced settings button.
	373
151.1	374	* Clean session: YES
	375	* Retained: YES
16.1	376
105.1	377	[[image:add-integration-connection-advanced-settings.png\|\|height="510" width="500"]]
	378
	379
49.1	380	Click on the Check connection button to verify the MQTT connection using the provided parameters.
16.1	381
49.1	382
105.1	383	[[image:check-connection.png\|\|height="83" width="300"]]
	384
	385
117.1	386	If the connection is successful, you will see the Connected message. If not, check your connection parameters again.
49.1	387
105.1	388
	389	[[image:connection-success.png\|\|height="511" width="500"]]
	390
	391
16.1	392	Click on the Add button.
	393
59.1	394	You should see that the newly added integration is listed on the Integrations page.
49.1	395
59.1	396	Since we haven't received data from a device yet, the integration Status is shown as Pending.
49.1	397
	398
117.1	399	[[image:new-integration-pending.png]]
	400
	401
176.1	402	= 6. Verifying the receipt of data from virtual devices =
49.1	403
16.1	404
176.1	405	== 6.1 How does it work? ==
64.1	406
141.1	407
130.1	408	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.
	409
182.1	410	The Mosquitto client publishes messages (payloads) on the topic /device/a. Of course, you can use any topic for testing.
130.1	411
182.1	412	(% id="cke_bm_37386S" style="display:none" %) (%%)The MQTT payload format is as follows:
130.1	413
64.1	414	{{code language="none"}}
182.1	415	{"IMEI": "350693903995577", "temperature":25, "humidity":80, "pressure":1005}
64.1	416	{{/code}}
	417
182.1	418	Once ThingsBoard receives this message, it forwards this payload to the matching device through the integration.
130.1	419
159.1	420
130.1	421	== 5.2 Sending messages ==
	422
	423
161.1	424	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 S31B-NB and 27, respectively. This payload is also (technically) known as telemetry.
130.1	425
	426	{{code language="none"}}
182.1	427	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	428	{{/code}}
	429
141.1	430	If the integration was performed without errors, the status of the integration changes to 'Active' after the first telemetry transmission.
	431
	432
	433	[[image:integration-active.png]]
	434
	435
	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
	456	[[image:Screenshot 2025-03-18 at 09.23.10.png]]
	457
	458
	459	Now go to the Events tab.
	460
	461	Select the Event type as Debug from the dropdown list.
	462
182.1	463	Now you can see all the Uplink messages you are simulating through the MQTT broker. The status should be OK if there is no errors in your integration.
167.1	464
	465
182.1	466	[[image:Screenshot 2025-03-26 at 19.49.31.png]]
167.1	467
	468
182.1	469
	470
167.1	471	Then click on the three dots (...) in the Message column. You can see the uplink message's payload in the Message window.
	472
	473
182.1	474	[[image:Screenshot 2025-03-26 at 19.47.52.png]]
141.1	475
	476
182.1	477
	478
164.1	479	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	480
	481
176.1	482	= 7. Creating a Dashboard =
141.1	483
145.1	484	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	485
	486
145.1	487	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	488
145.1	489
169.1	490	First simulate a few messages using MQTT. This time, we have added the 'humidity' field to the payload. Eg:
	491
170.1	492	{{code language="none"}}mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -t "v1/devices/me/telemetry" -u "xxxxx" -P "xxxxx" -m '{"IMEI": "S31B-NB", "temperature": 22, "humidity":80}'{{/code}}
169.1	493
	494
145.1	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"}}
169.1	551	mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -t "v1/devices/me/telemetry" -u "xxxxx" -P "xxxxx" -m '{"IMEI": "S31B-NB", "temperature": 22, "humidity":70}'
149.1	552
169.1	553	mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -t "v1/devices/me/telemetry" -u "xxxxx" -P "xxxxx" -m '{"IMEI": "S31B-NB", "temperature": 27, "humidity":72}'
149.1	554
169.1	555	mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -t "v1/devices/me/telemetry" -u "xxxxx" -P "xxxxx" -m '{"IMEI": "S31B-NB", "temperature": 19, "humidity":80}'
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
176.1	565	= 8. Configure NB-IoT Sensor =
146.1	566
	567
172.1	568	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	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.
175.1	576	* AT+SUBTOPIC=<MQTT subscribe topic> Eg: TS01-NB
169.1	577	* AT+PUBTOPIC=<MQTT publish topic> Eg: TS01-NB
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.
172.1	584
167.1	585
	586
169.1	587	The following image shows the uplink payload of a real Dragino device. The publish topic is TS01-NB, and the device name is 861275077962896, which is represented by the IMEI.
167.1	588
172.1	589	{{info}}
	590	The ThingsBoard uses the device's IMEI number included in the payload to create a device in the Devices section.
	591	{{/info}}
	592
169.1	593	[[image:image-4.png]]
	594
	595

Wiki source code of ThingsBoard

Applications

Navigation