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

= 3. Data Converters =

168

169

170

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

177

178

179

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

180

181

182

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

187

188

189

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

190

191

Click on the **JavaScript** button.

192

193

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.

194

195

196

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

202

var payloadStr = decodeToString(payload);

203

204

// decode payload to JSON

205

var objdata = {};

206

var obj1 = {};

207

var data = decodeToJson(payload);

208

var deviceName = data.IMEI;

209

delete data.IMEI;

210

var modelname = "Dragino " + data.Model;

//var mod = data.mod

delete data.Model;

//delete data.mod

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

215

216

for (var key in data) {

217

218

if (Number(key)) {

219

obj1[key] = data[key];

220

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

221

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

222

223

}

224

//Alec submitted25/02/25

225

//turn old key into new

226

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

227

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

228

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

229

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

230

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

231

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

232

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

233

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

234

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

235

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

236

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

237

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

238

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

239

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

240

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

241

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

242

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

243

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

244

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

245

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

246

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

247

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

248

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

249

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

250

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

251

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

252

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

253

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

254

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

255

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

256

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

257

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

258

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

259

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

260

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

261

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

262

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

263

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

264

}

265

//Alec submitted25/02/25

266

else {

267

objdata[key] = data[key]

}

}

var listdata = [{

"ts": timestamp,

"values": objdata

}]

for (var key1 in obj1) {

275

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

276

listdata.push({

277

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

278

"values": {

279

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

}

})

} else {

listdata.push({

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

"values": {

"values": obj1[key1]

},

})

}

}

var result = {

deviceName: deviceName,

294

deviceType: modelname,

295

attributes: {

296

model: modelname,

297

//customerName: "NB-CB",

298

//groupName: "NB-CB",

299

//integrationName: metadata['integrationName']

},

telemetry: listdata

}

function decodeToString(payload) {

306

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

307

}

308

309

function decodeToJson(payload) {

310

// covert payload to string.

311

var str = decodeToString(payload);

312

313

// parse string to JSON

314

var data = JSON.parse(str);

return data;

}

return result;

Click on the **Add** button.

323

324

325

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

330

331

332

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

333

334

335

= 4. Add Integration =

336

337

338

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

339

340

341

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

342

343

344

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

345

346

347

The **Add integration** window appears.

348

349

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

**Basic settings:**

* **Integration type**: MQTT

355

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

356

* **Enable integration**: YES

357

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

358

359

Click **Next** button.

360

361

362

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

363

364

365

**Uplink data converter:**

366

367

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

368

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

369

370

Click **Next** button.

371

372

373

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

374

375

376

**Downlink data converter:**

377

378

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

379

380

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

381

382

Click **Skip** button.

383

384

385

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

**Connection:**

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

392

* **Port**: 8883

393

* **Credentials**: Basic

394

* **Enable SSL**: YES

395

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

396

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

397

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

398

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

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

403

404

405

Click on the **Advanced settings** button.

406

407

* **Clean session:** YES

408

* **Retained**: YES

409

410

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

411

412

413

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

414

415

416

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

417

418

419

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

420

421

422

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

423

424

425

Click on the **Add** button.

426

427

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

428

429

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

430

431

432

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

433

434

435

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

436

437

438

== 5.1 How does it work? ==

439

440

441

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.

442

443

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

444

445

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

446

447

448

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

449

450

451

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

452

453

454

== 5.2 Sending messages ==

455

456

457

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.

458

459

460

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}'

461

462

463

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

464

465

466

[[image:integration-active.png]]

467

468

469

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

470

471

472

[[image:new-device.png]]

473

474

475

== 5.3 Viewing messages ==

476

477

478

Go back to the **Integrations** page.

479

480

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

481

482

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

483

484

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

485

486

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.

487

488

Click on the **Apply** button.

489

490

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

491

492

493

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

494

495

496

Now go to the **Events** tab.

497

498

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

499

500

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.

501

502

503

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

504

505

506

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

507

508

509

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

510

511

512

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.

513

514

515

= 6. Creating a Dashboard =

516

517

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.

518

519

520

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.

521

522

523

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

524

525

{{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}}

526

527

528

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

529

530

531

[[image:dashboard-1.png]]

532

533

534

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

535

536

Click on the **Add** button.

537

538

539

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

540

541

542

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

543

544

545

[[image:dashboard-3.png]]

546

547

548

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

549

550

551

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

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

556

557

558

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

559

560

561

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

562

563

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

564

* **Series**:

565

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

566

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

567

* Click on the **Add** button.

568

569

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

570

571

572

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

573

574

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

575

576

577

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

578

579

580

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}'

585

586

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}'

587

588

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.

593

594

595

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

596

597

598

= 7. Configure NB-IoT Sensor =

599

600

601

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

602

603

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.

609

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

610

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

611

* **AT+CLIENT=null**

612

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

613

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

614

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

615

616

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

621

622

623

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

624

625

626

[[image:image-4.png]]

627

628

629

Wiki source code of ThingsBoard

Applications

Navigation