ThingsBoard - DRAGINO

1

**Table of Contents:**

2

Draft Document

= 1. Introduction =

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.

16

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**.

= 2. Prerequisites =

To complete this tutorial, you need to have the following:

23

24

* ThingsBoard cloud account

25

* HiveMQ Cloud account

26

27

28

== 2.1 ThingsBoard Cloud ==

Add details here

== 2.2 HiveMQ Cloud ==

34

35

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.

**Port**: 8883

Click on the **Getting Started** tab to setup the username and the password as the connection credentials.

89

90

91

[[image:hivemq-8.png]]

92

93

94

In the '**Create Connection Credentials**' section, provide a **username** and **password**, then click the **Add** button.

95

96

97

[[image:hivemq-9.png]]

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

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.

== 3.1 Uplink ==

In the left navigation, click **Integrations center**, and then click **Data converters**.

[[image:data-converters-list-empty.png]]

124

125

126

On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu.

[[image:create-new-converter-menu.png||height="259" width="500"]]

131

132

133

The **Add data converter** window will appear. Name it ‘**MQTT Uplink Converter NB/CB**’ and select the Type as **Uplink**.

134

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.

/** Decoder **/

// decode payload to string

141

var payloadStr = decodeToString(payload);

142

var data = JSON.parse(payloadStr);

143

144

var deviceName = metadata.topic.split("/")[3];

145

// decode payload to JSON

146

var deviceType = 'sensor';

147

148

// Result object with device attributes/telemetry data

149

var result = {

150

deviceName: deviceName,

151

deviceType: deviceType,

152

attributes: {

153

integrationName: metadata['integrationName'],

154

},

155

telemetry: {

156

temperature: data.temperature,

157

humidity: data.humidity,

}

};

/** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/

return result;

Click on the **Add** button.

[[image:add-uplink-data-converter.png||height="529" width="500"]]

172

173

174

You should see that the newly added **MQTT Uplink converter **NB/CB is listed on the **Data Converters** page.

175

176

[[image:data-converter-list-showing-uplink-dc.png]]

== 3.2 Downlink ==

On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu.

184

185

186

[[image:create-new-converter-menu.png||width="500"]]

The **Add data converter** window will appear. Name it ‘**MQTT Downlink Converter NB/CB**’ and select the Type as **Downlink**.

191

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.

// Encode downlink data from incoming Rule Engine message

197

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

/** Encoder **/

var data = {};

// 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

214

// Result object with encoded downlink payload

215

var result = {

216

217

// downlink data content type: JSON, TEXT or BINARY (base64 format)

contentType: "JSON",

// downlink data

data: JSON.stringify(data),

222

223

// Optional metadata object presented in key/value format

224

metadata: {

225

topic: metadata['deviceType']+'/'+metadata['deviceName']+'/upload'

}

};

return result;

Click on the **Add** button.

[[image:add-downlink-data-converter.png||height="529" width="500"]]

239

240

241

You should see that the newly added **MQTT Downlink** Converter NB/CB is listed on the **Data Converters** page.

242

243

244

[[image:data-converters-list.png]]

= 4. Add Integration =

249

250

251

In the left navigation, click **Integrations center**, and then click **Integrations**.

252

253

254

[[image:integrations-list-empty.png]]

255

256

257

On the **Integrations** page, click on the '**+**' button.

258

259

260

The **Add integration** window appears.

261

262

In the **Add integration** window, configure the following settings:

**Basic settings:**

* **Integration type**: MQTT

268

* **Name**: MQTT integration NB/CB

269

* **Enable integration**: YES

270

* **Allows create devices or assets**: YES

271

272

Click **Next** button.

[[image:add-integration-basic-settings.png||height="511" width="500"]]

277

278

279

**Uplink data converter:**

280

281

* Click on the **Select existing** button.

282

* **Uplink data converter**: Select **MQTT Uplink Converter NB/CB **from the dropdown list.

283

284

Click **Next** button.

[[image:add-integration-uplink-data-converter.png||height="511" width="500"]]

289

290

291

**Downlink data converter:**

292

293

* Click on the **Select existing** button.

294

* **Downlink data converter**: Select **MQTT Downlink Converter NB/CB **from the dropdown list.

295

296

Click **Next** button.

[[image:add-integration-downlink-data-converter.png||height="511" width="500"]]

**Connection:**

* **Host**: Cluster URL (Eg. 011731f7928541588a6cdfbbedfc63f4.s1.eu.hivemq.cloud)

306

* **Port**: 8883

307

* **Credentials**: Basic

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

313

314

[[image:add-integration-connection.png||height="511" width="500"]]

315

316

317

Click on the **Advanced settings** button.

318

319

* **Clean session:** NO

320

* **Retained**: NO

321

322

[[image:add-integration-connection-advanced-settings.png||height="510" width="500"]]

323

324

325

Click on the **Check connection** button to verify the MQTT connection using the provided parameters.

326

327

328

[[image:check-connection.png||height="83" width="300"]]

329

330

331

If the connection is successful, you will see the **Connected** message. If not, check your connection parameters again.

332

333

334

[[image:connection-success.png||height="511" width="500"]]

335

336

337

Click on the **Add** button.

338

339

You should see that the newly added integration is listed on the **Integrations** page.

340

341

Since we haven't received data from a device yet, the integration **Status** is shown as **Pending.**

[[image:new-integration-pending.png]]

346

347

348

= 5. Verifying the receipt of data from the device =

349

350

351

On the terminal, issue the following MQTT command which simulates the device S31B-NB.

352

353

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

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

author	version	line-number	content
		1	Table of Contents:
		2
		3	{{toc/}}
		4
		5	{{warning}}
		6	Draft Document
		7	{{/warning}}
		8
		9
		10
		11
		12	= 1. Introduction =
		13
		14
		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.
		16
		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.
		18
		19
		20	= 2. Prerequisites =
		21
		22	To complete this tutorial, you need to have the following:
		23
		24	* ThingsBoard cloud account
		25	* HiveMQ Cloud account
		26
		27
		28	== 2.1 ThingsBoard Cloud ==
		29
		30
		31	Add details here
		32
		33	== 2.2 HiveMQ Cloud ==
		34
		35
		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
		88	Click on the Getting Started tab to setup the username and the password as the connection credentials.
		89
		90
		91	[[image:hivemq-8.png]]
		92
		93
		94	In the 'Create Connection Credentials' section, provide a username and password, then click the Add button.
		95
		96
		97	[[image:hivemq-9.png]]
		98
		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
		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.
		114
		115
		116	== 3.1 Uplink ==
		117
		118
		119	In the left navigation, click Integrations center, and then click Data converters.
		120
		121
		122
		123	[[image:data-converters-list-empty.png]]
		124
		125
		126	On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
		127
		128
		129
		130	[[image:create-new-converter-menu.png\|\|height="259" width="500"]]
		131
		132
		133	The Add data converter window will appear. Name it ‘MQTT Uplink Converter NB/CB’ and select the Type as Uplink.
		134
		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.
		136
		137	{{code language="JavaScript"}}
		138	/ Decoder /
		139
		140	// decode payload to string
		141	var payloadStr = decodeToString(payload);
		142	var data = JSON.parse(payloadStr);
		143
		144	var deviceName = metadata.topic.split("/")[3];
		145	// decode payload to JSON
		146	var deviceType = 'sensor';
		147
		148	// Result object with device attributes/telemetry data
		149	var result = {
		150	deviceName: deviceName,
		151	deviceType: deviceType,
		152	attributes: {
		153	integrationName: metadata['integrationName'],
		154	},
		155	telemetry: {
		156	temperature: data.temperature,
		157	humidity: data.humidity,
		158	}
		159	};
		160
		161	/ Helper functions 'decodeToString' and 'decodeToJson' are already built-in /
		162
		163	return result;
		164	{{/code}}
		165
		166
		167	Click on the Add button.
		168
		169
		170
		171	[[image:add-uplink-data-converter.png\|\|height="529" width="500"]]
		172
		173
		174	You should see that the newly added MQTT Uplink converter NB/CB is listed on the Data Converters page.
		175
		176	[[image:data-converter-list-showing-uplink-dc.png]]
		177
		178
		179
		180	== 3.2 Downlink ==
		181
		182
		183	On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
		184
		185
		186	[[image:create-new-converter-menu.png\|\|width="500"]]
		187
		188
		189
		190	The Add data converter window will appear. Name it ‘MQTT Downlink Converter NB/CB’ and select the Type as Downlink.
		191
		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.
		193
		194
		195	{{code language="JavaScript"}}
		196	// Encode downlink data from incoming Rule Engine message
		197
		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
		214	// Result object with encoded downlink payload
		215	var result = {
		216
		217	// downlink data content type: JSON, TEXT or BINARY (base64 format)
		218	contentType: "JSON",
		219
		220	// downlink data
		221	data: JSON.stringify(data),
		222
		223	// Optional metadata object presented in key/value format
		224	metadata: {
		225	topic: metadata['deviceType']+'/'+metadata['deviceName']+'/upload'
		226	}
		227
		228	};
		229
		230	return result;
		231	{{/code}}
		232
		233
		234	Click on the Add button.
		235
		236
		237
		238	[[image:add-downlink-data-converter.png\|\|height="529" width="500"]]
		239
		240
		241	You should see that the newly added MQTT Downlink Converter NB/CB is listed on the Data Converters page.
		242
		243
		244	[[image:data-converters-list.png]]
		245
		246
		247
		248	= 4. Add Integration =
		249
		250
		251	In the left navigation, click Integrations center, and then click Integrations.
		252
		253
		254	[[image:integrations-list-empty.png]]
		255
		256
		257	On the Integrations page, click on the '+' button.
		258
		259
		260	The Add integration window appears.
		261
		262	In the Add integration window, configure the following settings:
		263
		264
		265	Basic settings:
		266
		267	* Integration type: MQTT
		268	* Name: MQTT integration NB/CB
		269	* Enable integration: YES
		270	* Allows create devices or assets: YES
		271
		272	Click Next button.
		273
		274
		275
		276	[[image:add-integration-basic-settings.png\|\|height="511" width="500"]]
		277
		278
		279	Uplink data converter:
		280
		281	* Click on the Select existing button.
		282	* Uplink data converter: Select MQTT Uplink Converter NB/CB from the dropdown list.
		283
		284	Click Next button.
		285
		286
		287
		288	[[image:add-integration-uplink-data-converter.png\|\|height="511" width="500"]]
		289
		290
		291	Downlink data converter:
		292
		293	* Click on the Select existing button.
		294	* Downlink data converter: Select MQTT Downlink Converter NB/CB from the dropdown list.
		295
		296	Click Next button.
		297
		298
		299
		300	[[image:add-integration-downlink-data-converter.png\|\|height="511" width="500"]]
		301
		302
		303	Connection:
		304
		305	* Host: Cluster URL (Eg. 011731f7928541588a6cdfbbedfc63f4.s1.eu.hivemq.cloud)
		306	* Port: 8883
		307	* Credentials: Basic
		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
		313
		314	[[image:add-integration-connection.png\|\|height="511" width="500"]]
		315
		316
		317	Click on the Advanced settings button.
		318
		319	* Clean session: NO
		320	* Retained: NO
		321
		322	[[image:add-integration-connection-advanced-settings.png\|\|height="510" width="500"]]
		323
		324
		325	Click on the Check connection button to verify the MQTT connection using the provided parameters.
		326
		327
		328	[[image:check-connection.png\|\|height="83" width="300"]]
		329
		330
		331	If the connection is successful, you will see the Connected message. If not, check your connection parameters again.
		332
		333
		334	[[image:connection-success.png\|\|height="511" width="500"]]
		335
		336
		337	Click on the Add button.
		338
		339	You should see that the newly added integration is listed on the Integrations page.
		340
		341	Since we haven't received data from a device yet, the integration Status is shown as Pending.
		342
		343
		344
		345	[[image:new-integration-pending.png]]
		346
		347
		348	= 5. Verifying the receipt of data from the device =
		349
		350
		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.