Wiki source code of ThingsBoard

Version 121.1 by Dilisi S on 2025/03/08 20:30

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
117.1	27
121.1	28	== 2.1 ThingsBoard Cloud ==
117.1	29
	30
121.1	31	Add details here
	32
	33	== 2.2 HiveMQ Cloud ==
	34
	35
117.1	36	Go to [[https:~~/~~/www.hivemq.com>>https://www.hivemq.com]]
	37
	38	Click on the Start Free button.
	39
	40	[[image:hivwmq-1.png]]
	41
	42
	43	Click on the Sign Up FREE Now button in the HIVEMQ CLOUD section.
	44
	45	[[image:hivemq-2.png]]
	46
	47
	48	Click on the Sign Up button.
	49
	50	You can sign up with HiveMQ using your GitHub, Google, or LinkedIn account.
	51
	52	If not, provide your email address and a password to create an account by clicking on the Sign Up button.
	53
	54
	55	[[image:hivemq-3.png]]
	56
	57
	58	You will receive an email to verify your email address. Click on the Confirm my account button.
	59
	60
	61	[[image:hivemq-4.jpg\|\|height="889" width="400"]]
	62
	63
	64	You will be redirected to a page asking you to complete your profile. Once done, click the Continue button.
	65
	66
	67	[[image:hivemq-5.png\|\|height="655" width="700"]]
	68
	69
	70	Select the CloudMQ Cloud plan you need. For testing purposes, select the Serverless FREE plan by clicking on the Create Serverless Cluster button.
	71
	72
	73	[[image:hivemq-6.png]]
	74
	75
	76	You will be navigated to the Your Clusters page. Click on the Manage Cluster button.
	77
	78	[[image:hivemq-7.png]]
	79
	80
	81	In your cluster page, you can find some useful parameters you need to create a MQTT connection.
	82
	83	URL: This is the host name. Click on the copy button to copy it.
	84
	85	Port: 8883
	86
	87
121.1	88	Click on the Getting Started tab to setup the username and the password as the connection credentials.
117.1	89
	90
	91	[[image:hivemq-8.png]]
	92
	93
121.1	94	In the 'Create Connection Credentials' section, provide a username and password, then click the Add button.
117.1	95
11.1	96
121.1	97	[[image:hivemq-9.png]]
11.1	98
121.1	99
	100
	101	If everything is successful, you will see the following message.
	102
	103
	104	[[image:hivemq-10.png\|\|height="206" width="500"]]
	105
	106
	107	You will need these MQTT connection parameters when configuring the MQTT integration in the 'Add Integration' section.
	108
	109
	110	= 3. Data Converters =
	111
	112
93.1	113	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	114
	115
121.1	116	== 3.1 Uplink ==
11.1	117
	118
93.1	119	In the left navigation, click Integrations center, and then click Data converters.
11.1	120
59.1	121
	122
93.1	123	[[image:data-converters-list-empty.png]]
59.1	124
	125
93.1	126	On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
59.1	127
	128
	129
93.1	130	[[image:create-new-converter-menu.png\|\|height="259" width="500"]]
59.1	131
	132
36.1	133	The Add data converter window will appear. Name it ‘MQTT Uplink Converter NB/CB’ and select the Type as Uplink.
11.1	134
93.1	135	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	136
	137	{{code language="JavaScript"}}
93.1	138	/ Decoder /
	139
11.1	140	// decode payload to string
	141	var payloadStr = decodeToString(payload);
93.1	142	var data = JSON.parse(payloadStr);
11.1	143
93.1	144	var deviceName = metadata.topic.split("/")[3];
11.1	145	// decode payload to JSON
93.1	146	var deviceType = 'sensor';
11.1	147
93.1	148	// Result object with device attributes/telemetry data
11.1	149	var result = {
	150	deviceName: deviceName,
93.1	151	deviceType: deviceType,
11.1	152	attributes: {
93.1	153	integrationName: metadata['integrationName'],
11.1	154	},
93.1	155	telemetry: {
	156	temperature: data.temperature,
	157	humidity: data.humidity,
	158	}
	159	};
11.1	160
93.1	161	/ Helper functions 'decodeToString' and 'decodeToJson' are already built-in /
11.1	162
	163	return result;
	164	{{/code}}
	165
64.2	166
21.1	167	Click on the Add button.
11.1	168
	169
	170
93.1	171	[[image:add-uplink-data-converter.png\|\|height="529" width="500"]]
11.1	172
93.1	173
	174	You should see that the newly added MQTT Uplink converter NB/CB is listed on the Data Converters page.
	175
105.1	176	[[image:data-converter-list-showing-uplink-dc.png]]
21.1	177
	178
94.1	179
64.2	180	== 3.2 Downlink ==
11.1	181
64.2	182
21.1	183	On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
11.1	184
	185
105.1	186	[[image:create-new-converter-menu.png\|\|width="500"]]
11.1	187
105.1	188
	189
36.1	190	The Add data converter window will appear. Name it ‘MQTT Downlink Converter NB/CB’ and select the Type as Downlink.
11.1	191
93.1	192	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	193
	194
	195	{{code language="JavaScript"}}
93.1	196	// Encode downlink data from incoming Rule Engine message
11.1	197
93.1	198	// msg - JSON message payload downlink message json
	199	// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
	200	// metadata - list of key-value pairs with additional data about the message
	201	// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter
	202
	203	/ Encoder /
	204
	205	var data = {};
	206
	207	// Process data from incoming message and metadata
	208
	209	data.tempFreq = msg.temperatureUploadFrequency;
	210	data.humFreq = msg.humidityUploadFrequency;
	211
	212	data.devSerialNumber = metadata['ss_serialNumber'];
	213
11.1	214	// Result object with encoded downlink payload
	215	var result = {
93.1	216
11.1	217	// downlink data content type: JSON, TEXT or BINARY (base64 format)
93.1	218	contentType: "JSON",
11.1	219
	220	// downlink data
93.1	221	data: JSON.stringify(data),
11.1	222
	223	// Optional metadata object presented in key/value format
93.1	224	metadata: {
	225	topic: metadata['deviceType']+'/'+metadata['deviceName']+'/upload'
	226	}
11.1	227
	228	};
	229
	230	return result;
	231	{{/code}}
	232
	233
	234	Click on the Add button.
	235
	236
	237
93.1	238	[[image:add-downlink-data-converter.png\|\|height="529" width="500"]]
21.1	239
	240
93.1	241	You should see that the newly added MQTT Downlink Converter NB/CB is listed on the Data Converters page.
21.1	242
11.1	243
93.1	244	[[image:data-converters-list.png]]
	245
105.1	246
	247
121.1	248	= 4. Add Integration =
93.1	249
	250
21.1	251	In the left navigation, click Integrations center, and then click Integrations.
11.1	252
105.1	253
	254	[[image:integrations-list-empty.png]]
	255
	256
21.1	257	On the Integrations page, click on the '+' button.
11.1	258
	259
21.1	260	The Add integration window appears.
11.1	261
24.1	262	In the Add integration window, configure the following settings:
11.1	263
21.1	264
11.1	265	Basic settings:
	266
49.1	267	* Integration type: MQTT
	268	* Name: MQTT integration NB/CB
105.1	269	* Enable integration: YES
	270	* Allows create devices or assets: YES
11.1	271
	272	Click Next button.
	273
105.1	274
	275
16.1	276	[[image:add-integration-basic-settings.png\|\|height="511" width="500"]]
11.1	277
	278
16.1	279	Uplink data converter:
11.1	280
21.1	281	* Click on the Select existing button.
49.1	282	* Uplink data converter: Select MQTT Uplink Converter NB/CB from the dropdown list.
16.1	283
	284	Click Next button.
	285
	286
	287
105.1	288	[[image:add-integration-uplink-data-converter.png\|\|height="511" width="500"]]
	289
	290
16.1	291	Downlink data converter:
	292
21.1	293	* Click on the Select existing button.
49.1	294	* Downlink data converter: Select MQTT Downlink Converter NB/CB from the dropdown list.
16.1	295
	296	Click Next button.
	297
	298
	299
105.1	300	[[image:add-integration-downlink-data-converter.png\|\|height="511" width="500"]]
	301
	302
16.1	303	Connection:
	304
93.1	305	* Host: Cluster URL (Eg. 011731f7928541588a6cdfbbedfc63f4.s1.eu.hivemq.cloud)
	306	* Port: 8883
49.1	307	* Credentials: Basic
93.1	308	* Enable SSL: YES
	309	* Username: Username (from your HiveMQ Cloud Cluster with your credentials)
	310	* Password: Password (from your HiveMQ Cloud Cluster with your credentials)
	311	* Topic: tb/mqtt-integration-tutorial/sensors/+/telemetry (the + replaces any 'device name' and creates devices in the Entities -> Devices)
	312	* QoS: 0-At most once
105.1	313
	314	[[image:add-integration-connection.png\|\|height="511" width="500"]]
	315
	316
	317	Click on the Advanced settings button.
	318
93.1	319	* Clean session: NO
	320	* Retained: NO
16.1	321
105.1	322	[[image:add-integration-connection-advanced-settings.png\|\|height="510" width="500"]]
	323
	324
49.1	325	Click on the Check connection button to verify the MQTT connection using the provided parameters.
16.1	326
49.1	327
105.1	328	[[image:check-connection.png\|\|height="83" width="300"]]
	329
	330
117.1	331	If the connection is successful, you will see the Connected message. If not, check your connection parameters again.
49.1	332
105.1	333
	334	[[image:connection-success.png\|\|height="511" width="500"]]
	335
	336
16.1	337	Click on the Add button.
	338
59.1	339	You should see that the newly added integration is listed on the Integrations page.
49.1	340
59.1	341	Since we haven't received data from a device yet, the integration Status is shown as Pending.
49.1	342
	343
	344
117.1	345	[[image:new-integration-pending.png]]
	346
	347
64.2	348	= 5. Verifying the receipt of data from the device =
49.1	349
16.1	350
64.1	351	On the terminal, issue the following MQTT command which simulates the device S31B-NB.
	352
	353	{{code language="none"}}
	354	mosquitto_pub -d -q 1 -h mqtt.eu.thingsboard.cloud -p 1883 -t v1/devices/S31B-NB/telemetry -u "24vk3w9h7sqdld1me5eh" -m "{temperature:20}"
	355	{{/code}}
	356
	357	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