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

**Port**: 8883

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

84

85

86

[[image:hivemq-8.png]]

= 2. Data Converters =

91

92

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.

== 2.1 Uplink ==

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

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

104

105

106

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"]]

111

112

113

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

114

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.

/** Decoder **/

// decode payload to string

121

var payloadStr = decodeToString(payload);

122

var data = JSON.parse(payloadStr);

123

124

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

125

// decode payload to JSON

126

var deviceType = 'sensor';

127

128

// Result object with device attributes/telemetry data

129

var result = {

130

deviceName: deviceName,

131

deviceType: deviceType,

132

attributes: {

133

integrationName: metadata['integrationName'],

134

},

135

telemetry: {

136

temperature: data.temperature,

137

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"]]

152

153

154

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

155

156

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

164

165

166

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

171

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.

// Encode downlink data from incoming Rule Engine message

177

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

/** Encoder **/

var data = {};

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

194

// Result object with encoded downlink payload

195

var result = {

196

197

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

contentType: "JSON",

// downlink data

data: JSON.stringify(data),

202

203

// Optional metadata object presented in key/value format

204

metadata: {

205

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

}

};

return result;

Click on the **Add** button.

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

219

220

221

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

222

223

224

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

= 3. Add Integration =

229

230

231

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

232

233

234

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

235

236

237

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

238

239

240

The **Add integration** window appears.

241

242

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

**Basic settings:**

* **Integration type**: MQTT

248

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

249

* **Enable integration**: YES

250

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

251

252

Click **Next** button.

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

257

258

259

**Uplink data converter:**

260

261

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

262

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

263

264

Click **Next** button.

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

269

270

271

**Downlink data converter:**

272

273

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

274

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

275

276

Click **Next** button.

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

**Connection:**

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

286

* **Port**: 8883

287

* **Credentials**: Basic

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

293

294

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

295

296

297

Click on the **Advanced settings** button.

298

299

* **Clean session:** NO

300

* **Retained**: NO

301

302

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

303

304

305

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

306

307

308

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

309

310

311

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

312

313

314

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

315

316

317

Click on the **Add** button.

318

319

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

320

321

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

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

326

327

328

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

329

330

331

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

332

333

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

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

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 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
		90	= 2. Data Converters =
		91
		92
		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.
		94
		95
		96	== 2.1 Uplink ==
		97
		98
		99	In the left navigation, click Integrations center, and then click Data converters.
		100
		101
		102
		103	[[image:data-converters-list-empty.png]]
		104
		105
		106	On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
		107
		108
		109
		110	[[image:create-new-converter-menu.png\|\|height="259" width="500"]]
		111
		112
		113	The Add data converter window will appear. Name it ‘MQTT Uplink Converter NB/CB’ and select the Type as Uplink.
		114
		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.
		116
		117	{{code language="JavaScript"}}
		118	/ Decoder /
		119
		120	// decode payload to string
		121	var payloadStr = decodeToString(payload);
		122	var data = JSON.parse(payloadStr);
		123
		124	var deviceName = metadata.topic.split("/")[3];
		125	// decode payload to JSON
		126	var deviceType = 'sensor';
		127
		128	// Result object with device attributes/telemetry data
		129	var result = {
		130	deviceName: deviceName,
		131	deviceType: deviceType,
		132	attributes: {
		133	integrationName: metadata['integrationName'],
		134	},
		135	telemetry: {
		136	temperature: data.temperature,
		137	humidity: data.humidity,
		138	}
		139	};
		140
		141	/ Helper functions 'decodeToString' and 'decodeToJson' are already built-in /
		142
		143	return result;
		144	{{/code}}
		145
		146
		147	Click on the Add button.
		148
		149
		150
		151	[[image:add-uplink-data-converter.png\|\|height="529" width="500"]]
		152
		153
		154	You should see that the newly added MQTT Uplink converter NB/CB is listed on the Data Converters page.
		155
		156	[[image:data-converter-list-showing-uplink-dc.png]]
		157
		158
		159
		160	== 3.2 Downlink ==
		161
		162
		163	On the Data converters page, click on the ‘+’ button, and then click on the Create new converter from the dropdown menu.
		164
		165
		166	[[image:create-new-converter-menu.png\|\|width="500"]]
		167
		168
		169
		170	The Add data converter window will appear. Name it ‘MQTT Downlink Converter NB/CB’ and select the Type as Downlink.
		171
		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.
		173
		174
		175	{{code language="JavaScript"}}
		176	// Encode downlink data from incoming Rule Engine message
		177
		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
		194	// Result object with encoded downlink payload
		195	var result = {
		196
		197	// downlink data content type: JSON, TEXT or BINARY (base64 format)
		198	contentType: "JSON",
		199
		200	// downlink data
		201	data: JSON.stringify(data),
		202
		203	// Optional metadata object presented in key/value format
		204	metadata: {
		205	topic: metadata['deviceType']+'/'+metadata['deviceName']+'/upload'
		206	}
		207
		208	};
		209
		210	return result;
		211	{{/code}}
		212
		213
		214	Click on the Add button.
		215
		216
		217
		218	[[image:add-downlink-data-converter.png\|\|height="529" width="500"]]
		219
		220
		221	You should see that the newly added MQTT Downlink Converter NB/CB is listed on the Data Converters page.
		222
		223
		224	[[image:data-converters-list.png]]
		225
		226
		227
		228	= 3. Add Integration =
		229
		230
		231	In the left navigation, click Integrations center, and then click Integrations.
		232
		233
		234	[[image:integrations-list-empty.png]]
		235
		236
		237	On the Integrations page, click on the '+' button.
		238
		239
		240	The Add integration window appears.
		241
		242	In the Add integration window, configure the following settings:
		243
		244
		245	Basic settings:
		246
		247	* Integration type: MQTT
		248	* Name: MQTT integration NB/CB
		249	* Enable integration: YES
		250	* Allows create devices or assets: YES
		251
		252	Click Next button.
		253
		254
		255
		256	[[image:add-integration-basic-settings.png\|\|height="511" width="500"]]
		257
		258
		259	Uplink data converter:
		260
		261	* Click on the Select existing button.
		262	* Uplink data converter: Select MQTT Uplink Converter NB/CB from the dropdown list.
		263
		264	Click Next button.
		265
		266
		267
		268	[[image:add-integration-uplink-data-converter.png\|\|height="511" width="500"]]
		269
		270
		271	Downlink data converter:
		272
		273	* Click on the Select existing button.
		274	* Downlink data converter: Select MQTT Downlink Converter NB/CB from the dropdown list.
		275
		276	Click Next button.
		277
		278
		279
		280	[[image:add-integration-downlink-data-converter.png\|\|height="511" width="500"]]
		281
		282
		283	Connection:
		284
		285	* Host: Cluster URL (Eg. 011731f7928541588a6cdfbbedfc63f4.s1.eu.hivemq.cloud)
		286	* Port: 8883
		287	* Credentials: Basic
		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
		293
		294	[[image:add-integration-connection.png\|\|height="511" width="500"]]
		295
		296
		297	Click on the Advanced settings button.
		298
		299	* Clean session: NO
		300	* Retained: NO
		301
		302	[[image:add-integration-connection-advanced-settings.png\|\|height="510" width="500"]]
		303
		304
		305	Click on the Check connection button to verify the MQTT connection using the provided parameters.
		306
		307
		308	[[image:check-connection.png\|\|height="83" width="300"]]
		309
		310
		311	If the connection is successful, you will see the Connected message. If not, check your connection parameters again.
		312
		313
		314	[[image:connection-success.png\|\|height="511" width="500"]]
		315
		316
		317	Click on the Add button.
		318
		319	You should see that the newly added integration is listed on the Integrations page.
		320
		321	Since we haven't received data from a device yet, the integration Status is shown as Pending.
		322
		323
		324
		325	[[image:new-integration-pending.png]]
		326
		327
		328	= 5. Verifying the receipt of data from the device =
		329
		330
		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.