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

* MQTT Broker (public or private) such as,

26

** **[[HiveMQ Cloud>>https://www.hivemq.com]] - You can create a free account to try it or subscribe for a paid account. - We use HiveMQ Cloud as the MQTT broker to build example in this tutorial.**

27

** [[emqx>>https://www.emqx.com/zh/mqtt/public-mqtt5-broker]] - The public MQTT server is only used for MOTT learning and testing, and should not be used in the production environment.

28

** [[lns1.thingseye.io>>http://lns1.thingseye.io/]] - This is Dragino's MQTT broker, which requires a CA certificate to use.

29

30

== 2.1 ThingsBoard Cloud ==

31

32

33

Go to [[https:~~/~~/thingsboard.io/>>https://thingsboard.io/]]

34

35

Click on the **Try it now**.

36

37

38

[[image:thingsboard-1.png]]

39

40

41

Select either the **North America** or **Europe** region. Here, we use the Europe region.

42

43

[[image:thingsboard-2.png]]

44

45

46

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

47

48

Click on the **Sign up** button.

49

50

[[image:thingsboard-3.png||height="651" width="500"]]

51

52

53

You will be navigated to the following page.

54

55

[[image:thingsboard-5.png||height="109" width="500"]]

56

57

58

simultaneously, you will receive an email to confirm your email address. Click on the **Activate Your Account** button.

59

60

61

[[image:thingsboard-4.png||height="249" width="500"]]

62

63

64

Now losing to the account using your credentials:

65

66

67

[[image:thingsboard-6.png||height="244" width="500"]]

68

69

70

== 2.2 HiveMQ Cloud ==

71

72

=== 2.2.1 HiveMQ Cloud ===

73

74

75

Go to [[https:~~/~~/www.hivemq.com>>https://www.hivemq.com]]

76

77

Click on the **Start Free** button.

78

79

[[image:hivwmq-1.png]]

80

81

82

Click on the **Sign Up FREE Now** button in the **HIVEMQ CLOUD** section.

83

84

[[image:hivemq-2.png]]

85

86

87

Click on the **Sign Up** button.

88

89

You can sign up with HiveMQ using your **GitHub**, **Google**, or **LinkedIn** account.

90

91

If not, provide your **email address** and a **password** to create an account by clicking on the **Sign Up** button.

92

93

94

[[image:hivemq-3.png]]

95

96

97

You will receive an email to verify your email address. Click on the **Confirm my account** button.

98

99

100

[[image:hivemq-4.jpg||height="889" width="400"]]

101

102

103

You will be redirected to a page asking you to complete your profile. Once done, click the **Continue** button.

104

105

106

[[image:hivemq-5.png||height="655" width="700"]]

107

108

109

Select the CloudMQ Cloud plan you need. For testing purposes, select the **Serverless FREE** plan by clicking on the **Create Serverless Cluster** button.

110

111

112

[[image:hivemq-6.png]]

113

114

115

You will be navigated to the **Your Clusters** page. Click on the **Manage Cluster** button.

116

117

[[image:hivemq-7.png]]

118

119

120

In your cluster page, you can find some useful parameters you need to create a MQTT connection.

121

122

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

128

129

130

[[image:hivemq-8.png]]

131

132

133

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

134

135

136

[[image:hivemq-9.png]]

If everything is successful, you will see the following message.

141

142

143

[[image:hivemq-10.png||height="206" width="500"]]

144

145

146

You will need these MQTT connection parameters when configuring the MQTT integration in the '**Add Integration**' section.

=== 2.2.2 emqx ===

The [[emqx>>https://www.emqx.com/zh/mqtt/public-mqtt5-broker]] public MQTT server is only used for MOTT learning and testing, and should not be used in the production environment.

153

154

155

[[image:emqx.png||height="420" width="500"]]

156

157

158

=== 2.2.3 Ins1.thingseye.io ===

159

160

[[lns1.thingseye.io>>http://lns1.thingseye.io/]] is the Dragino's MQTT broker, which requires a CA certificate file, Certificate file, and the Private key file to use.

161

162

If customers need to use this MQTT connection with ThingsBoard, they need to contact the TE team to obtain three license files.

163

164

[[image:ins1.png||height="310" width="500"]]

165

166

167

(% class="wikigeneratedid" %)

168

= 3. Creating Devices =

169

170

171

First, you need to create devices in ThingsBoard to represent your physical devices. For example, you can name it **Device A**, and the second device could be **Device B** or any name you prefer. The device name should be unique within the **Devices** space.

172

173

174

In the left navigation, click Entities -> Devices.

175

176

Click the **Add Device** button (the button with the **+** sign), and from the dropdown menu, click **Add new device**.

177

178

In the **Add new device** dialog box, enter the device name in the **Name** text box. For example, we will use **Device A**.

179

180

Click the **Add** button.

181

182

Skip the **connectivity testing** by clicking the **Close** button.

183

184

The device is created and listed on the **Devices** page. Note that its initial state is **Inactive** because it has not received any data yet.

185

186

187

= 4. Data Converters =

188

189

190

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.

== 4.1 Uplink ==

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

197

198

199

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

200

201

202

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

207

208

209

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

210

211

Click on the **JavaScript** button.

212

213

Delete the default decoder function in the code editor. Now copy and paste the following decoder function written in **JavaScript** in to the **code editor**. This decoder function is compatible for both NB and CB series devices.

214

215

216

Please note that the value assigned to the IMEI field in the payload will be used by ThingsBoard to create a device on the platform with the same name.

//Version: 0.1

// decode payload to string

222

var payloadStr = decodeToString(payload);

223

224

// decode payload to JSON

225

var objdata = {};

226

var obj1 = {};

227

var data = decodeToJson(payload);

228

var deviceName = data.IMEI;

229

delete data.IMEI;

230

var modelname = "Dragino " + data.Model;

//var mod = data.mod

delete data.Model;

//delete data.mod

var timestamp = new Date().getTime();

235

236

for (var key in data) {

237

238

if (Number(key)) {

239

obj1[key] = data[key];

240

obj1[key][obj1[key].length - 1] = Number(new Date(

241

obj1[key][obj1[key].length - 1]));

242

243

}

244

//Alec submitted25/02/25

245

//turn old key into new

246

else if (key === "Reading") {

247

objdata["reading"] = data[key];

248

} else if (key === "work mode") {

249

objdata["work_mode"] = data[key];

250

} else if (key === "hum") {

251

objdata["humidity"] = data[key];

252

}else if (key === "hum2") {

253

objdata["humidity2"] = data[key];

254

} else if (key === "hum3") {

255

objdata["humidity3"] = data[key];

256

} else if (key === "tem") {

257

objdata["temperature"] = data[key];

258

} else if (key === "tem2") {

259

objdata["temperature2"] = data[key];

260

} else if (key === "tem3") {

261

objdata["temperature3"] = data[key];

262

} else if (key === "DS18B20_Temp") {

263

objdata["temperature_pro"] = data[key];

264

} else if (key === "ds18b20_temperature") {

265

objdata["temperature_pro"] = data[key];

266

} else if (key === "DS18B20_temperature_pro") {

267

objdata["temperature_pro"] = data[key];

268

} else if (key === "tdc send flag") {

269

objdata["tdc_send_flag"] = data[key];

270

} else if (key === "trigger mode") {

271

objdata["trigger_mode"] = data[key];

272

} else if (key === "soil dielectric constant") {

273

objdata["soil_dielectric_constant"] = data[key];

274

} else if (key === "door open num") {

275

objdata["door_open_num"] = data[key];

276

} else if (key === "door duration") {

277

objdata["door_duration"] = data[key];

278

} else if (key === "count time") {

279

objdata["count_time"] = data[key];

280

} else if (key === "last open time2") {

281

objdata["last_open_time2"] = data[key];

282

} else if (key === "last open time3") {

283

objdata["last_open_time3"] = data[key];

284

}

285

//Alec submitted25/02/25

286

else {

287

objdata[key] = data[key]

}

}

var listdata = [{

"ts": timestamp,

"values": objdata

}]

for (var key1 in obj1) {

295

if (modelname == "Dragino RS485-NB") {

296

listdata.push({

297

"ts": obj1[key1][obj1[key1].length - 1],

298

"values": {

299

"Payload": obj1[key1][0],

}

})

} else {

listdata.push({

"ts": obj1[key1][obj1[key1].length - 1],

"values": {

"values": obj1[key1]

},

})

}

}

var result = {

deviceName: deviceName,

314

deviceType: modelname,

315

attributes: {

316

model: modelname,

317

//customerName: "NB-CB",

318

//groupName: "NB-CB",

319

//integrationName: metadata['integrationName']

},

telemetry: listdata

}

function decodeToString(payload) {

326

return String.fromCharCode.apply(String, payload);

327

}

328

329

function decodeToJson(payload) {

330

// covert payload to string.

331

var str = decodeToString(payload);

332

333

// parse string to JSON

334

var data = JSON.parse(str);

return data;

}

return result;

Click on the **Add** button.

343

344

345

[[image:mqtt-uplink.png||width="500"]]

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

350

351

352

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

353

354

355

= 5. Add Integration =

356

357

358

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

359

360

361

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

362

363

364

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

365

366

367

The **Add integration** window appears.

368

369

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

**Basic settings:**

* **Integration type**: MQTT

375

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

376

* **Enable integration**: YES

377

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

378

379

Click **Next** button.

380

381

382

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

383

384

385

**Uplink data converter:**

386

387

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

388

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

389

390

Click **Next** button.

391

392

393

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

394

395

396

**Downlink data converter:**

397

398

Dragino NB/CB devices don't require a downlink data converter to decode their payloads, so you can skip this step.

399

400

* Click on the **Skip **button in the Downlink data converter section.

401

402

Click **Skip** button.

403

404

405

[[image:integration-dl-skip.png||height="511" width="500"]]

**Connection:**

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

412

* **Port**: 8883

413

* **Credentials**: Basic

414

* **Enable SSL**: YES

415

* **Username**: Username (from your HiveMQ Cloud Cluster with your credentials)

416

* **Password:** Password (from your HiveMQ Cloud Cluster with your credentials)

417

* **Topic: v1/devices/me/telemetry** (The topic can be anything; you can even use just the device name. For example, you can use your device name here, such as S31B-NB.)

418

* **QoS:** 0-At most once

419

420

421

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

422

423

424

Click on the **Advanced settings** button.

425

426

* **Clean session:** YES

427

* **Retained**: YES

428

429

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

430

431

432

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

433

434

435

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

436

437

438

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

439

440

441

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

442

443

444

Click on the **Add** button.

445

446

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

447

448

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

449

450

451

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

452

453

454

= 6. Verifying the receipt of data from virtual devices =

455

456

457

== 6.1 How does it work? ==

458

459

460

We use the Mosquitto MQTT client to simulate MQTT messages, acting as a virtual device. First, install the Mosquitto client on your computer from [[this link>>url:https://mosquitto.org/download/]]. The Mosquitto client publishes messages to the MQTT broker (HiveMQ) on a specified MQTT topic. ThingsBoard subscribes to these messages using the same topic.

461

462

The Mosquitto client publishes messages (payloads) on the topic **v1/devices/me/telemetry**. Of course, you can use any topic for testing.

463

464

(% id="cke_bm_37386S" style="display:none" %) (%%)The MQTT payload format is as follows, which is common for all **~-~-NB** and **~-~-CB** series devices. The **IMEI** field is mandatory and is used to provision a new device with the name assigned to it in ThingsBoard.

465

466

467

{"IMEI": "S31B-NB", "temperature": 27, ......}

468

469

470

Once ThingsBoard receives this message, it automatically creates (provisions) the device mentioned in the **IMEI**, for example, S31B-NB.

471

472

473

== 5.2 Sending messages ==

474

475

476

On the terminal, issue the following MQTT command which simulates the device S31B-NB. The message payload contains the fields temperature and humidity, which hold the values S31B-NB and 27, respectively. This payload is also (technically) known as telemetry.

477

478

479

mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -t "v1/devices/me/telemetry" -u "xxxxx" -P "xxxxx" -m '{"IMEI": "S31B-NB", "temperature": 27}'

480

481

482

If the integration was performed without errors, the status of the integration changes to 'Active' after the first telemetry transmission.

483

484

485

[[image:integration-active.png]]

486

487

488

Also, a new device named **S31B-NB** will appear under **//Entities -> Devices -> All//**. This means the first MQTT message triggers ThingsBoard to provision a device named **S31B-NB**.

489

490

491

[[image:new-device.png]]

492

493

494

== 6.3 Viewing messages ==

495

496

497

Go back to the **Integrations** page.

498

499

Click on the **MQTT integration NB/CB** in the **Integrations** page to see its details.

500

501

Click on the **Edit** button (//**pen icon**//).

502

503

Click on the **Disabled** button in the upper-right corner.

504

505

Turn on the **All messages (15 min)** option. This will enable displaying all messages in the **Events** tab. This setting will expire in 15 minutes, and you will need to repeat the same steps if you want to view the messages in the Events tab later.

506

507

Click on the **Apply** button.

508

509

Then click on the **Apply changes** (//**tick icon**//) button.

510

511

512

[[image:Screenshot 2025-03-18 at 09.23.10.png]]

513

514

515

Now go to the **Events** tab.

516

517

Select the Event type as **Debug** from the dropdown list.

518

519

Now you can see all the Uplink messages you are simulating through the MQTT broker. The status should be OK if there is no errors in your integration.

520

521

522

[[image:Screenshot 2025-03-16 at 18.38.59.png]]

523

524

525

Then click on the **three dots (...)** in the **Message** column. You can see the uplink message's **payload** in the **Message** window.

526

527

528

[[image:Screenshot 2025-03-16 at 18.39.12.png]]

529

530

531

Now, you have successfully tested your integration with a simulated uplink payload and verified that it is received by ThingsBoard, and the device is provisioned.

532

533

534

= 7. Creating a Dashboard =

535

536

ThingsBoard **Dashboards** provide a powerful way to visualize and monitor real-time and historical data from connected devices. They allow users to create interactive, customizable panels displaying telemetry data, device status, and other key metrics. With a variety of widgets, including charts, maps, and tables, dashboards help users gain insights, track trends, and manage IoT deployments efficiently.

537

538

539

This section guides you on how to create a dashboard to display temperature and humidity data from the device on a time-series chart. You may also use other widgets in ThingsBoard to display data according to your requirements.

540

541

542

First simulate a few messages using MQTT. This time, we have added the 'humidity' field to the payload. Eg:

543

544

{{code language="none"}}mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -t "v1/devices/me/telemetry" -u "xxxxx" -P "xxxxx" -m '{"IMEI": "S31B-NB", "temperature": 22, "humidity":80}'{{/code}}

545

546

547

In **ThingsBoard**, from the left navigation menu, click **Dashboards**. Then, click the **+** button and select **Create new dashboard** from the dropdown menu.

548

549

550

[[image:dashboard-1.png]]

551

552

553

In the **Title** text box, enter **NB/CB Test Dashboard** as the title of the dashboard.

554

555

Click on the **Add** button.

556

557

558

[[image:dashboard-2.png||height="526" width="500"]]

559

560

561

Click on the **Add widget / Add new widget** button.

562

563

564

[[image:dashboard-3.png]]

565

566

567

In the **Select widgets bundle** window, click **Charts**.

568

569

570

[[image:dashboard-4.png||height="537" width="700"]]

In the **Charts: select widget** window, click **Time series chart**.

575

576

577

[[image:dashboard-5.png||height="525" width="700"]]

578

579

580

Configure the **Time series chart** widget as follows:

581

582

* **Datasource** - select S31B-NB device you provisioned.

583

* **Series**:

584

** **temperature** - you can see this key by default.

585

** **humidity** - Click **Add series** button. Then add the **humidity** for the key and then type **%** as its unit.

586

* Click on the **Add** button.

587

588

[[image:timeseries-1.png||height="491" width="700"]]

589

590

591

The time-series chart will appear in edit mode. Resize it by clicking and dragging the lower-right corner.

592

593

Click the **Save** button to add the widget to the dashboard.

594

595

596

[[image:timeseries-3.png||height="347" width="700"]]

597

598

599

Now send the following MQTT messages from the terminal to simulate the data.

mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -t "v1/devices/me/telemetry" -u "xxxxx" -P "xxxxx" -m '{"IMEI": "S31B-NB", "temperature": 22, "humidity":70}'

604

605

mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -t "v1/devices/me/telemetry" -u "xxxxx" -P "xxxxx" -m '{"IMEI": "S31B-NB", "temperature": 27, "humidity":72}'

606

607

mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -t "v1/devices/me/telemetry" -u "xxxxx" -P "xxxxx" -m '{"IMEI": "S31B-NB", "temperature": 19, "humidity":80}'

The chart will update with the values in realtime, as shown in the below image.

612

613

614

[[image:timeseries-4.png||height="316" width="700"]]

615

616

617

= 8. Configure NB-IoT Sensor =

618

619

620

Now, let's experiment with sending data to ThingsBoard using a real NB-IoT device. For example, we will use the **TS01-NB**.

621

622

First, configure the NB-IoT device with the necessary MQTT settings using AT commands. Below is a list of AT commands you can use.

**AT Commands**

* **AT+PRO=3,3 **~/~/ Use MQTT to connect to ThingsBoard. Payload Type set to 3.

628

* **AT+SUBTOPIC=<MQTT subscribe topic> Eg: TS01-NB**

629

* **AT+PUBTOPIC=<MQTT publish topic> Eg: TS01-NB**

630

* **AT+CLIENT=null**

631

* **AT+UNAME=<MQTT Username>**

632

* **AT+PWD=<MQTT Password>**

633

* **AT+SERVADDR=<Broker address, Port>**

634

635

Test your uplink by pressing the ACT button for 1 second.

The following image shows the uplink payload of a real Dragino device. The publish topic is **TS01-NB**, and the device name is **861275077962896**, which is represented by the **IMEI**.

640

641

642

The ThingsBoard uses the device's IMEI number included in the payload to create a device in the Devices section.

643

644

645

[[image:image-4.png]]

646

647

648

Wiki source code of ThingsBoard

Applications

Navigation