Wiki source code of ThingsBoard

Version 181.1 by Dilisi S on 2025/03/27 02:49

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

Wiki source code of ThingsBoard

Applications

Navigation