Wiki source code of ThingsBoard

Version 119.1 by Dilisi S on 2025/03/08 20:22

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