Wiki source code of ThingsBoard

Version 125.1 by Dilisi S on 2025/03/08 20:47

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