Wiki source code of ThingsBoard

Version 138.1 by Dilisi S on 2025/03/09 03:31

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
117.1	25	* HiveMQ Cloud account
59.1	26
121.1	27	== 2.1 ThingsBoard Cloud ==
117.1	28
	29
125.1	30	Go to [[https:~~/~~/thingsboard.io/>>https://thingsboard.io/]]
121.1	31
125.1	32	Click on the Try it now.
	33
	34
	35	[[image:thingsboard-1.png]]
	36
	37
	38	Select either the North America or Europe region. Here, we use the Europe region.
	39
	40	[[image:thingsboard-2.png]]
	41
	42
129.1	43	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	44
129.1	45	Click on the Sign up button.
	46
125.1	47	[[image:thingsboard-3.png\|\|height="651" width="500"]]
	48
	49
129.1	50	You will be navigated to the following page.
	51
	52	[[image:thingsboard-5.png\|\|height="109" width="500"]]
	53
	54
	55	simultaneously, you will receive an email to confirm your email address. Click on the Activate Your Account button.
	56
	57
	58	[[image:thingsboard-4.png\|\|height="249" width="500"]]
	59
	60
	61	Now losing to the account using your credentials:
	62
	63
	64	[[image:thingsboard-6.png\|\|height="244" width="500"]]
	65
	66
121.1	67	== 2.2 HiveMQ Cloud ==
	68
	69
117.1	70	Go to [[https:~~/~~/www.hivemq.com>>https://www.hivemq.com]]
	71
	72	Click on the Start Free button.
	73
	74	[[image:hivwmq-1.png]]
	75
	76
	77	Click on the Sign Up FREE Now button in the HIVEMQ CLOUD section.
	78
	79	[[image:hivemq-2.png]]
	80
	81
	82	Click on the Sign Up button.
	83
	84	You can sign up with HiveMQ using your GitHub, Google, or LinkedIn account.
	85
	86	If not, provide your email address and a password to create an account by clicking on the Sign Up button.
	87
	88
	89	[[image:hivemq-3.png]]
	90
	91
	92	You will receive an email to verify your email address. Click on the Confirm my account button.
	93
	94
	95	[[image:hivemq-4.jpg\|\|height="889" width="400"]]
	96
	97
	98	You will be redirected to a page asking you to complete your profile. Once done, click the Continue button.
	99
	100
	101	[[image:hivemq-5.png\|\|height="655" width="700"]]
	102
	103
	104	Select the CloudMQ Cloud plan you need. For testing purposes, select the Serverless FREE plan by clicking on the Create Serverless Cluster button.
	105
	106
	107	[[image:hivemq-6.png]]
	108
	109
	110	You will be navigated to the Your Clusters page. Click on the Manage Cluster button.
	111
	112	[[image:hivemq-7.png]]
	113
	114
	115	In your cluster page, you can find some useful parameters you need to create a MQTT connection.
	116
	117	URL: This is the host name. Click on the copy button to copy it.
	118
	119	Port: 8883
	120
	121
121.1	122	Click on the Getting Started tab to setup the username and the password as the connection credentials.
117.1	123
	124
	125	[[image:hivemq-8.png]]
	126
	127
121.1	128	In the 'Create Connection Credentials' section, provide a username and password, then click the Add button.
117.1	129
11.1	130
121.1	131	[[image:hivemq-9.png]]
11.1	132
121.1	133
	134
	135	If everything is successful, you will see the following message.
	136
	137
	138	[[image:hivemq-10.png\|\|height="206" width="500"]]
	139
	140
	141	You will need these MQTT connection parameters when configuring the MQTT integration in the 'Add Integration' section.
	142
	143
	144	= 3. Data Converters =
	145
	146
93.1	147	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	148
	149
121.1	150	== 3.1 Uplink ==
11.1	151
	152
93.1	153	In the left navigation, click Integrations center, and then click Data converters.
11.1	154
59.1	155
	156
93.1	157	[[image:data-converters-list-empty.png]]
59.1	158
	159
93.1	160	On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
59.1	161
	162
	163
93.1	164	[[image:create-new-converter-menu.png\|\|height="259" width="500"]]
59.1	165
	166
36.1	167	The Add data converter window will appear. Name it ‘MQTT Uplink Converter NB/CB’ and select the Type as Uplink.
11.1	168
93.1	169	Click on the TBEL button if not selected it by default. Delete the existing decoder function in the code editor. Now copy and paste the following decoder function written in TBEL (ThingsBoard Expression Language) in to the code editor. This decoder function is compatible for both NB and CB series devices.
11.1	170
	171	{{code language="JavaScript"}}
93.1	172	/ Decoder /
	173
11.1	174	// decode payload to string
	175	var payloadStr = decodeToString(payload);
93.1	176	var data = JSON.parse(payloadStr);
11.1	177
93.1	178	var deviceName = metadata.topic.split("/")[3];
11.1	179	// decode payload to JSON
93.1	180	var deviceType = 'sensor';
11.1	181
93.1	182	// Result object with device attributes/telemetry data
11.1	183	var result = {
	184	deviceName: deviceName,
93.1	185	deviceType: deviceType,
11.1	186	attributes: {
93.1	187	integrationName: metadata['integrationName'],
11.1	188	},
93.1	189	telemetry: {
	190	temperature: data.temperature,
	191	humidity: data.humidity,
	192	}
	193	};
11.1	194
93.1	195	/ Helper functions 'decodeToString' and 'decodeToJson' are already built-in /
11.1	196
	197	return result;
	198	{{/code}}
	199
64.2	200
21.1	201	Click on the Add button.
11.1	202
	203
	204
93.1	205	[[image:add-uplink-data-converter.png\|\|height="529" width="500"]]
11.1	206
93.1	207
	208	You should see that the newly added MQTT Uplink converter NB/CB is listed on the Data Converters page.
	209
105.1	210	[[image:data-converter-list-showing-uplink-dc.png]]
21.1	211
	212
94.1	213
64.2	214	== 3.2 Downlink ==
11.1	215
64.2	216
21.1	217	On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
11.1	218
	219
105.1	220	[[image:create-new-converter-menu.png\|\|width="500"]]
11.1	221
105.1	222
	223
36.1	224	The Add data converter window will appear. Name it ‘MQTT Downlink Converter NB/CB’ and select the Type as Downlink.
11.1	225
93.1	226	Click on the TBEL button if not selected it by default. Now copy and paste the following encoder function written in TBEL (ThingsBoard Expression Language) in to the code editor. This encoder function is compatible for both NB and CB series devices.
11.1	227
	228
	229	{{code language="JavaScript"}}
93.1	230	// Encode downlink data from incoming Rule Engine message
11.1	231
93.1	232	// msg - JSON message payload downlink message json
	233	// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
	234	// metadata - list of key-value pairs with additional data about the message
	235	// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter
	236
	237	/ Encoder /
	238
	239	var data = {};
	240
	241	// Process data from incoming message and metadata
	242
	243	data.tempFreq = msg.temperatureUploadFrequency;
	244	data.humFreq = msg.humidityUploadFrequency;
	245
	246	data.devSerialNumber = metadata['ss_serialNumber'];
	247
11.1	248	// Result object with encoded downlink payload
	249	var result = {
93.1	250
11.1	251	// downlink data content type: JSON, TEXT or BINARY (base64 format)
93.1	252	contentType: "JSON",
11.1	253
	254	// downlink data
93.1	255	data: JSON.stringify(data),
11.1	256
	257	// Optional metadata object presented in key/value format
93.1	258	metadata: {
	259	topic: metadata['deviceType']+'/'+metadata['deviceName']+'/upload'
	260	}
11.1	261
	262	};
	263
	264	return result;
	265	{{/code}}
	266
	267
	268	Click on the Add button.
	269
	270
	271
93.1	272	[[image:add-downlink-data-converter.png\|\|height="529" width="500"]]
21.1	273
	274
93.1	275	You should see that the newly added MQTT Downlink Converter NB/CB is listed on the Data Converters page.
21.1	276
11.1	277
93.1	278	[[image:data-converters-list.png]]
	279
105.1	280
	281
121.1	282	= 4. Add Integration =
93.1	283
	284
21.1	285	In the left navigation, click Integrations center, and then click Integrations.
11.1	286
105.1	287
	288	[[image:integrations-list-empty.png]]
	289
	290
21.1	291	On the Integrations page, click on the '+' button.
11.1	292
	293
21.1	294	The Add integration window appears.
11.1	295
24.1	296	In the Add integration window, configure the following settings:
11.1	297
21.1	298
11.1	299	Basic settings:
	300
49.1	301	* Integration type: MQTT
	302	* Name: MQTT integration NB/CB
105.1	303	* Enable integration: YES
	304	* Allows create devices or assets: YES
11.1	305
	306	Click Next button.
	307
105.1	308
	309
16.1	310	[[image:add-integration-basic-settings.png\|\|height="511" width="500"]]
11.1	311
	312
16.1	313	Uplink data converter:
11.1	314
21.1	315	* Click on the Select existing button.
49.1	316	* Uplink data converter: Select MQTT Uplink Converter NB/CB from the dropdown list.
16.1	317
	318	Click Next button.
	319
	320
	321
105.1	322	[[image:add-integration-uplink-data-converter.png\|\|height="511" width="500"]]
	323
	324
16.1	325	Downlink data converter:
	326
21.1	327	* Click on the Select existing button.
49.1	328	* Downlink data converter: Select MQTT Downlink Converter NB/CB from the dropdown list.
16.1	329
	330	Click Next button.
	331
	332
	333
105.1	334	[[image:add-integration-downlink-data-converter.png\|\|height="511" width="500"]]
	335
	336
16.1	337	Connection:
	338
93.1	339	* Host: Cluster URL (Eg. 011731f7928541588a6cdfbbedfc63f4.s1.eu.hivemq.cloud)
	340	* Port: 8883
49.1	341	* Credentials: Basic
93.1	342	* Enable SSL: YES
	343	* Username: Username (from your HiveMQ Cloud Cluster with your credentials)
	344	* Password: Password (from your HiveMQ Cloud Cluster with your credentials)
	345	* Topic: tb/mqtt-integration-tutorial/sensors/+/telemetry (the + replaces any 'device name' and creates devices in the Entities -> Devices)
	346	* QoS: 0-At most once
105.1	347
	348	[[image:add-integration-connection.png\|\|height="511" width="500"]]
	349
	350
	351	Click on the Advanced settings button.
	352
93.1	353	* Clean session: NO
	354	* Retained: NO
16.1	355
105.1	356	[[image:add-integration-connection-advanced-settings.png\|\|height="510" width="500"]]
	357
	358
49.1	359	Click on the Check connection button to verify the MQTT connection using the provided parameters.
16.1	360
49.1	361
105.1	362	[[image:check-connection.png\|\|height="83" width="300"]]
	363
	364
117.1	365	If the connection is successful, you will see the Connected message. If not, check your connection parameters again.
49.1	366
105.1	367
	368	[[image:connection-success.png\|\|height="511" width="500"]]
	369
	370
16.1	371	Click on the Add button.
	372
59.1	373	You should see that the newly added integration is listed on the Integrations page.
49.1	374
59.1	375	Since we haven't received data from a device yet, the integration Status is shown as Pending.
49.1	376
	377
	378
117.1	379	[[image:new-integration-pending.png]]
	380
	381
130.1	382	= 5. Verifying the receipt of data from virtual devices =
49.1	383
16.1	384
130.1	385	== 5.1 How does it work? ==
64.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
	389	The Mosquitto client publishes messages on the topic v1/devices/[device_name]/telemetry. The [device_name]placeholder can be replaced with any device name, for example, 'S31B-NB'. Then, the MQTT topic would be v1/devices/S31B-NB/telemetry.
	390
	391	On the ThingsBoard side, we configure the MQTT topic subscription as v1/devices/+/telemetry. The + wildcard represents any device name and allows ThingsBoard to automatically create (provision) a device with that name, such as S31B-NB, for example.
	392
	393
	394	The new device is created the first time the MQTT topic is received. For subsequent MQTT topics with the same device name, no duplicate devices will be created.
	395
	396
	397	For example, if you send two MQTT messages with different device names in the topic:
	398
	399	1. v1/devices/S31B-NB/telemetry
	400	1. v1/devices/S31B-CB/telemetry
	401
	402	ThingsBoard will create two devices named S31B-NB and S31B-CB in the //Devices// section.
	403
	404
	405	The MQTT payload format is as follows, for example:
	406
64.1	407	{{code language="none"}}
130.1	408	{"temperature":10.4, "humidity":85}
64.1	409	{{/code}}
	410
130.1	411
	412	== 5.2 Sending messages ==
	413
	414
	415	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 10.4 and 85, respectively. This payload is also (technically) known as telemetry.
	416
	417	{{code language="none"}}
	418	mosquitto_pub -d -q 1 -h 011731f7928541588a6cdfbbedfc63f4.s1.eu.hivemq.cloud -p 8883 -t "tb/mqtt-integration-tutorial/sensors/SN-001/telemetry" -u "pradeeka" -P "Kalpani123@" -m '{"temperature":10.4, "humidity":85}'
	419	{{/code}}
	420
64.1	421	If the integration was performed without errors, after the transmission of the first telemetry, a new device with the name “S31B-NB” will appear in the Devices → All. Also, you can verify the input and output data, respectively, before and after conversion in Data converters → UDP Uplink Converter NB/CB → Events.

Wiki source code of ThingsBoard

Applications

Navigation