Wiki source code of ThingsBoard
Hide last authors
author | 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 | |
![]() |
121.1 | 24 | * ThingsBoard cloud account |
![]() |
155.1 | 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. | ||
![]() |
59.1 | 29 | |
![]() |
121.1 | 30 | == 2.1 ThingsBoard Cloud == |
![]() |
117.1 | 31 | |
32 | |||
![]() |
125.1 | 33 | Go to [[https:~~/~~/thingsboard.io/>>https://thingsboard.io/]] |
![]() |
121.1 | 34 | |
![]() |
125.1 | 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 | |||
![]() |
129.1 | 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**. |
![]() |
125.1 | 47 | |
![]() |
129.1 | 48 | Click on the **Sign up** button. |
49 | |||
![]() |
125.1 | 50 | [[image:thingsboard-3.png||height="651" width="500"]] |
51 | |||
52 | |||
![]() |
129.1 | 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 | |||
![]() |
121.1 | 70 | == 2.2 HiveMQ Cloud == |
71 | |||
![]() |
155.1 | 72 | === 2.2.1 HiveMQ Cloud === |
![]() |
121.1 | 73 | |
![]() |
155.1 | 74 | |
![]() |
117.1 | 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. | ||
123 | |||
124 | **Port**: 8883 | ||
125 | |||
126 | |||
![]() |
121.1 | 127 | Click on the **Getting Started** tab to setup the username and the password as the connection credentials. |
![]() |
117.1 | 128 | |
129 | |||
130 | [[image:hivemq-8.png]] | ||
131 | |||
132 | |||
![]() |
121.1 | 133 | In the '**Create Connection Credentials**' section, provide a **username** and **password**, then click the **Add** button. |
![]() |
117.1 | 134 | |
![]() |
11.1 | 135 | |
![]() |
121.1 | 136 | [[image:hivemq-9.png]] |
![]() |
11.1 | 137 | |
![]() |
121.1 | 138 | |
139 | |||
140 | 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. | ||
147 | |||
148 | |||
![]() |
155.1 | 149 | === 2.2.2 emqx === |
150 | |||
151 | |||
152 | 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 | |||
![]() |
121.1 | 167 | = 3. Data Converters = |
168 | |||
169 | |||
![]() |
93.1 | 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. |
![]() |
11.1 | 171 | |
172 | |||
![]() |
121.1 | 173 | == 3.1 Uplink == |
![]() |
11.1 | 174 | |
175 | |||
![]() |
93.1 | 176 | In the left navigation, click **Integrations center**, and then click **Data converters**. |
![]() |
11.1 | 177 | |
![]() |
59.1 | 178 | |
![]() |
93.1 | 179 | [[image:data-converters-list-empty.png]] |
![]() |
59.1 | 180 | |
181 | |||
![]() |
93.1 | 182 | On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu. |
![]() |
59.1 | 183 | |
184 | |||
185 | |||
![]() |
93.1 | 186 | [[image:create-new-converter-menu.png||height="259" width="500"]] |
![]() |
59.1 | 187 | |
188 | |||
![]() |
36.1 | 189 | The **Add data converter** window will appear. Name it ‘**MQTT Uplink Converter NB/CB**’ and select the Type as **Uplink**. |
![]() |
11.1 | 190 | |
![]() |
157.1 | 191 | Click on the **JavaScript** button. |
![]() |
11.1 | 192 | |
![]() |
157.1 | 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 | |||
![]() |
11.1 | 196 | {{code language="JavaScript"}} |
![]() |
157.1 | 197 | //Version: 0.1 |
![]() |
11.1 | 198 | // decode payload to string |
199 | var payloadStr = decodeToString(payload); | ||
200 | |||
201 | // decode payload to JSON | ||
![]() |
157.1 | 202 | var objdata = {}; |
203 | var obj1 = {}; | ||
204 | var data = decodeToJson(payload); | ||
205 | var deviceName = data.IMEI; | ||
206 | delete data.IMEI; | ||
207 | var modelname = "Dragino " + data.Model; | ||
208 | //var mod = data.mod | ||
209 | delete data.Model; | ||
210 | //delete data.mod | ||
211 | var timestamp = new Date().getTime(); | ||
![]() |
11.1 | 212 | |
![]() |
157.1 | 213 | for (var key in data) { |
214 | |||
215 | if (Number(key)) { | ||
216 | obj1[key] = data[key]; | ||
217 | obj1[key][obj1[key].length - 1] = Number(new Date( | ||
218 | obj1[key][obj1[key].length - 1])); | ||
219 | |||
220 | } | ||
221 | //Alec submitted25/02/25 | ||
222 | //turn old key into new | ||
223 | else if (key === "Reading") { | ||
224 | objdata["reading"] = data[key]; | ||
225 | } else if (key === "work mode") { | ||
226 | objdata["work_mode"] = data[key]; | ||
227 | } else if (key === "hum") { | ||
228 | objdata["humidity"] = data[key]; | ||
229 | }else if (key === "hum2") { | ||
230 | objdata["humidity2"] = data[key]; | ||
231 | } else if (key === "hum3") { | ||
232 | objdata["humidity3"] = data[key]; | ||
233 | } else if (key === "tem") { | ||
234 | objdata["temperature"] = data[key]; | ||
235 | } else if (key === "tem2") { | ||
236 | objdata["temperature2"] = data[key]; | ||
237 | } else if (key === "tem3") { | ||
238 | objdata["temperature3"] = data[key]; | ||
239 | } else if (key === "DS18B20_Temp") { | ||
240 | objdata["temperature_pro"] = data[key]; | ||
241 | } else if (key === "ds18b20_temperature") { | ||
242 | objdata["temperature_pro"] = data[key]; | ||
243 | } else if (key === "DS18B20_temperature_pro") { | ||
244 | objdata["temperature_pro"] = data[key]; | ||
245 | } else if (key === "tdc send flag") { | ||
246 | objdata["tdc_send_flag"] = data[key]; | ||
247 | } else if (key === "trigger mode") { | ||
248 | objdata["trigger_mode"] = data[key]; | ||
249 | } else if (key === "soil dielectric constant") { | ||
250 | objdata["soil_dielectric_constant"] = data[key]; | ||
251 | } else if (key === "door open num") { | ||
252 | objdata["door_open_num"] = data[key]; | ||
253 | } else if (key === "door duration") { | ||
254 | objdata["door_duration"] = data[key]; | ||
255 | } else if (key === "count time") { | ||
256 | objdata["count_time"] = data[key]; | ||
257 | } else if (key === "last open time2") { | ||
258 | objdata["last_open_time2"] = data[key]; | ||
259 | } else if (key === "last open time3") { | ||
260 | objdata["last_open_time3"] = data[key]; | ||
261 | } | ||
262 | //Alec submitted25/02/25 | ||
263 | else { | ||
264 | objdata[key] = data[key] | ||
265 | } | ||
266 | } | ||
267 | var listdata = [{ | ||
268 | "ts": timestamp, | ||
269 | "values": objdata | ||
270 | }] | ||
271 | for (var key1 in obj1) { | ||
272 | if (modelname == "Dragino RS485-NB") { | ||
273 | listdata.push({ | ||
274 | "ts": obj1[key1][obj1[key1].length - 1], | ||
275 | "values": { | ||
276 | "Payload": obj1[key1][0], | ||
277 | } | ||
278 | }) | ||
279 | } else { | ||
280 | listdata.push({ | ||
281 | "ts": obj1[key1][obj1[key1].length - 1], | ||
282 | "values": { | ||
283 | "values": obj1[key1] | ||
284 | }, | ||
285 | }) | ||
286 | } | ||
287 | } | ||
![]() |
11.1 | 288 | var result = { |
![]() |
157.1 | 289 | |
![]() |
11.1 | 290 | deviceName: deviceName, |
![]() |
157.1 | 291 | deviceType: modelname, |
![]() |
11.1 | 292 | attributes: { |
![]() |
157.1 | 293 | model: modelname, |
294 | //customerName: "NB-CB", | ||
295 | //groupName: "NB-CB", | ||
296 | //integrationName: metadata['integrationName'] | ||
297 | |||
![]() |
11.1 | 298 | }, |
![]() |
157.1 | 299 | telemetry: listdata |
300 | } | ||
![]() |
11.1 | 301 | |
![]() |
157.1 | 302 | function decodeToString(payload) { |
303 | return String.fromCharCode.apply(String, payload); | ||
304 | } | ||
![]() |
11.1 | 305 | |
![]() |
157.1 | 306 | function decodeToJson(payload) { |
307 | // covert payload to string. | ||
308 | var str = decodeToString(payload); | ||
309 | |||
310 | // parse string to JSON | ||
311 | var data = JSON.parse(str); | ||
312 | return data; | ||
313 | } | ||
314 | |||
![]() |
11.1 | 315 | return result; |
316 | {{/code}} | ||
317 | |||
![]() |
64.2 | 318 | |
![]() |
21.1 | 319 | Click on the **Add** button. |
![]() |
11.1 | 320 | |
321 | |||
![]() |
157.1 | 322 | [[image:mqtt-uplink.png||width="500"]] |
![]() |
11.1 | 323 | |
324 | |||
![]() |
93.1 | 325 | |
326 | You should see that the newly added **MQTT Uplink converter **NB/CB is listed on the **Data Converters** page. | ||
327 | |||
![]() |
157.1 | 328 | |
![]() |
105.1 | 329 | [[image:data-converter-list-showing-uplink-dc.png]] |
![]() |
21.1 | 330 | |
331 | |||
![]() |
64.2 | 332 | == 3.2 Downlink == |
![]() |
11.1 | 333 | |
![]() |
64.2 | 334 | |
![]() |
21.1 | 335 | On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu. |
![]() |
11.1 | 336 | |
337 | |||
![]() |
105.1 | 338 | [[image:create-new-converter-menu.png||width="500"]] |
![]() |
11.1 | 339 | |
![]() |
105.1 | 340 | |
341 | |||
![]() |
36.1 | 342 | The **Add data converter** window will appear. Name it ‘**MQTT Downlink Converter NB/CB**’ and select the Type as **Downlink**. |
![]() |
11.1 | 343 | |
![]() |
93.1 | 344 | 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 | 345 | |
346 | |||
347 | {{code language="JavaScript"}} | ||
![]() |
93.1 | 348 | // Encode downlink data from incoming Rule Engine message |
![]() |
11.1 | 349 | |
![]() |
93.1 | 350 | // msg - JSON message payload downlink message json |
351 | // msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc. | ||
352 | // metadata - list of key-value pairs with additional data about the message | ||
353 | // integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter | ||
354 | |||
355 | /** Encoder **/ | ||
356 | |||
357 | var data = {}; | ||
358 | |||
359 | // Process data from incoming message and metadata | ||
360 | |||
361 | data.tempFreq = msg.temperatureUploadFrequency; | ||
362 | data.humFreq = msg.humidityUploadFrequency; | ||
363 | |||
364 | data.devSerialNumber = metadata['ss_serialNumber']; | ||
365 | |||
![]() |
11.1 | 366 | // Result object with encoded downlink payload |
367 | var result = { | ||
![]() |
93.1 | 368 | |
![]() |
11.1 | 369 | // downlink data content type: JSON, TEXT or BINARY (base64 format) |
![]() |
93.1 | 370 | contentType: "JSON", |
![]() |
11.1 | 371 | |
372 | // downlink data | ||
![]() |
93.1 | 373 | data: JSON.stringify(data), |
![]() |
11.1 | 374 | |
375 | // Optional metadata object presented in key/value format | ||
![]() |
93.1 | 376 | metadata: { |
377 | topic: metadata['deviceType']+'/'+metadata['deviceName']+'/upload' | ||
378 | } | ||
![]() |
11.1 | 379 | |
380 | }; | ||
381 | |||
382 | return result; | ||
383 | {{/code}} | ||
384 | |||
385 | |||
386 | Click on the **Add** button. | ||
387 | |||
388 | |||
![]() |
93.1 | 389 | [[image:add-downlink-data-converter.png||height="529" width="500"]] |
![]() |
21.1 | 390 | |
391 | |||
![]() |
93.1 | 392 | You should see that the newly added **MQTT Downlink** Converter NB/CB is listed on the **Data Converters** page. |
![]() |
21.1 | 393 | |
![]() |
11.1 | 394 | |
![]() |
93.1 | 395 | [[image:data-converters-list.png]] |
396 | |||
![]() |
105.1 | 397 | |
![]() |
121.1 | 398 | = 4. Add Integration = |
![]() |
93.1 | 399 | |
400 | |||
![]() |
21.1 | 401 | In the left navigation, click **Integrations center**, and then click **Integrations**. |
![]() |
11.1 | 402 | |
![]() |
105.1 | 403 | |
404 | [[image:integrations-list-empty.png]] | ||
405 | |||
406 | |||
![]() |
21.1 | 407 | On the **Integrations** page, click on the '**+**' button. |
![]() |
11.1 | 408 | |
409 | |||
![]() |
21.1 | 410 | The **Add integration** window appears. |
![]() |
11.1 | 411 | |
![]() |
24.1 | 412 | In the **Add integration** window, configure the following settings: |
![]() |
11.1 | 413 | |
![]() |
21.1 | 414 | |
![]() |
11.1 | 415 | **Basic settings:** |
416 | |||
![]() |
49.1 | 417 | * **Integration type**: MQTT |
418 | * **Name**: MQTT integration NB/CB | ||
![]() |
105.1 | 419 | * **Enable integration**: YES |
420 | * **Allows create devices or assets**: YES | ||
![]() |
11.1 | 421 | |
422 | Click **Next** button. | ||
423 | |||
![]() |
105.1 | 424 | |
![]() |
16.1 | 425 | [[image:add-integration-basic-settings.png||height="511" width="500"]] |
![]() |
11.1 | 426 | |
427 | |||
![]() |
16.1 | 428 | **Uplink data converter:** |
![]() |
11.1 | 429 | |
![]() |
21.1 | 430 | * Click on the **Select existing** button. |
![]() |
49.1 | 431 | * **Uplink data converter**: Select **MQTT Uplink Converter NB/CB **from the dropdown list. |
![]() |
16.1 | 432 | |
433 | Click **Next** button. | ||
434 | |||
435 | |||
![]() |
105.1 | 436 | [[image:add-integration-uplink-data-converter.png||height="511" width="500"]] |
437 | |||
438 | |||
![]() |
16.1 | 439 | **Downlink data converter:** |
440 | |||
![]() |
21.1 | 441 | * Click on the **Select existing** button. |
![]() |
49.1 | 442 | * **Downlink data converter**: Select **MQTT Downlink Converter NB/CB **from the dropdown list. |
![]() |
16.1 | 443 | |
444 | Click **Next** button. | ||
445 | |||
446 | |||
![]() |
105.1 | 447 | [[image:add-integration-downlink-data-converter.png||height="511" width="500"]] |
448 | |||
449 | |||
![]() |
16.1 | 450 | **Connection:** |
451 | |||
![]() |
157.1 | 452 | * **Host**: Cluster URL (Eg. 011731f7xxxxxxxxxxxfbbedfc63f4.s1.eu.hivemq.cloud) |
![]() |
93.1 | 453 | * **Port**: 8883 |
![]() |
49.1 | 454 | * **Credentials**: Basic |
![]() |
93.1 | 455 | * **Enable SSL**: YES |
456 | * **Username**: Username (from your HiveMQ Cloud Cluster with your credentials) | ||
457 | * **Password:** Password (from your HiveMQ Cloud Cluster with your credentials) | ||
![]() |
157.1 | 458 | * **Topic: v1/devices/+/telemetry** (the + replaces any 'device name' will create a device in the Entities -> Devices) |
![]() |
93.1 | 459 | * **QoS:** 0-At most once |
![]() |
105.1 | 460 | |
461 | [[image:add-integration-connection.png||height="511" width="500"]] | ||
462 | |||
463 | |||
464 | Click on the **Advanced settings** button. | ||
465 | |||
![]() |
151.1 | 466 | * **Clean session:** YES |
467 | * **Retained**: YES | ||
![]() |
16.1 | 468 | |
![]() |
105.1 | 469 | [[image:add-integration-connection-advanced-settings.png||height="510" width="500"]] |
470 | |||
471 | |||
![]() |
49.1 | 472 | Click on the **Check connection** button to verify the MQTT connection using the provided parameters. |
![]() |
16.1 | 473 | |
![]() |
49.1 | 474 | |
![]() |
105.1 | 475 | [[image:check-connection.png||height="83" width="300"]] |
476 | |||
477 | |||
![]() |
117.1 | 478 | If the connection is successful, you will see the **Connected** message. If not, check your connection parameters again. |
![]() |
49.1 | 479 | |
![]() |
105.1 | 480 | |
481 | [[image:connection-success.png||height="511" width="500"]] | ||
482 | |||
483 | |||
![]() |
16.1 | 484 | Click on the **Add** button. |
485 | |||
![]() |
59.1 | 486 | You should see that the newly added integration is listed on the **Integrations** page. |
![]() |
49.1 | 487 | |
![]() |
59.1 | 488 | Since we haven't received data from a device yet, the integration **Status** is shown as **Pending.** |
![]() |
49.1 | 489 | |
490 | |||
491 | |||
![]() |
117.1 | 492 | [[image:new-integration-pending.png]] |
493 | |||
494 | |||
![]() |
130.1 | 495 | = 5. Verifying the receipt of data from virtual devices = |
![]() |
49.1 | 496 | |
![]() |
16.1 | 497 | |
![]() |
130.1 | 498 | == 5.1 How does it work? == |
![]() |
64.1 | 499 | |
![]() |
141.1 | 500 | |
![]() |
130.1 | 501 | 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. |
502 | |||
![]() |
159.1 | 503 | The Mosquitto client publishes messages (payloads) on the topic **v1/devices/me/telemetry**. Of course, you can use any topic for testing. |
![]() |
130.1 | 504 | |
![]() |
159.1 | 505 | (% 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. |
![]() |
130.1 | 506 | |
![]() |
64.1 | 507 | {{code language="none"}} |
![]() |
159.1 | 508 | {"IMEI": "S31B-NB", "temperature": 27, ......} |
![]() |
64.1 | 509 | {{/code}} |
510 | |||
![]() |
159.1 | 511 | Once ThingsBoard receives this message, it automatically creates (provisions) the device mentioned in the **IMEI**, for example, S31B-NB. |
![]() |
130.1 | 512 | |
![]() |
159.1 | 513 | |
![]() |
130.1 | 514 | == 5.2 Sending messages == |
515 | |||
516 | |||
![]() |
161.1 | 517 | 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. |
![]() |
130.1 | 518 | |
519 | {{code language="none"}} | ||
![]() |
161.1 | 520 | 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}' |
![]() |
130.1 | 521 | {{/code}} |
522 | |||
![]() |
141.1 | 523 | If the integration was performed without errors, the status of the integration changes to 'Active' after the first telemetry transmission. |
524 | |||
525 | |||
526 | [[image:integration-active.png]] | ||
527 | |||
528 | |||
529 | 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**. | ||
530 | |||
531 | |||
![]() |
161.1 | 532 | [[image:new-device.png]] |
![]() |
141.1 | 533 | |
![]() |
161.1 | 534 | |
![]() |
167.1 | 535 | == 5.3 Viewing messages == |
![]() |
141.1 | 536 | |
537 | |||
![]() |
167.1 | 538 | Go back to the **Integrations** page. |
![]() |
141.1 | 539 | |
![]() |
167.1 | 540 | Click on the **MQTT integration NB/CB** in the **Integrations** page to see its details. |
![]() |
141.1 | 541 | |
![]() |
167.1 | 542 | Click on the **Edit** button (//**pen icon**//). |
![]() |
141.1 | 543 | |
![]() |
167.1 | 544 | Click on the **Disabled** button in the upper-right corner. |
![]() |
141.1 | 545 | |
![]() |
167.1 | 546 | 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. |
![]() |
141.1 | 547 | |
![]() |
167.1 | 548 | Click on the **Apply** button. |
![]() |
141.1 | 549 | |
![]() |
167.1 | 550 | Then click on the **Apply changes** (//**tick icon**//) button. |
![]() |
141.1 | 551 | |
![]() |
167.1 | 552 | |
553 | [[image:Screenshot 2025-03-18 at 09.23.10.png]] | ||
554 | |||
555 | |||
556 | Now go to the **Events** tab. | ||
557 | |||
558 | Select the Event type as **Debug** from the dropdown list. | ||
559 | |||
![]() |
169.1 | 560 | 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. |
![]() |
167.1 | 561 | |
562 | |||
563 | [[image:Screenshot 2025-03-16 at 18.38.59.png]] | ||
564 | |||
565 | |||
566 | Then click on the **three dots (...)** in the **Message** column. You can see the uplink message's **payload** in the **Message** window. | ||
567 | |||
568 | |||
![]() |
164.1 | 569 | [[image:Screenshot 2025-03-16 at 18.39.12.png]] |
![]() |
141.1 | 570 | |
571 | |||
![]() |
164.1 | 572 | 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. |
![]() |
141.1 | 573 | |
574 | |||
575 | = 6. Creating a Dashboard = | ||
576 | |||
![]() |
145.1 | 577 | 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. |
![]() |
141.1 | 578 | |
579 | |||
![]() |
145.1 | 580 | 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. |
![]() |
141.1 | 581 | |
![]() |
145.1 | 582 | |
![]() |
169.1 | 583 | First simulate a few messages using MQTT. This time, we have added the 'humidity' field to the payload. Eg: |
584 | |||
585 | {{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}' | ||
586 | {{/code}} | ||
587 | |||
588 | |||
![]() |
145.1 | 589 | In **ThingsBoard**, from the left navigation menu, click **Dashboards**. Then, click the **+** button and select **Create new dashboard** from the dropdown menu. |
590 | |||
591 | |||
![]() |
141.1 | 592 | [[image:dashboard-1.png]] |
593 | |||
594 | |||
595 | In the **Title** text box, enter **NB/CB Test Dashboard** as the title of the dashboard. | ||
596 | |||
597 | Click on the **Add** button. | ||
598 | |||
599 | |||
600 | [[image:dashboard-2.png||height="526" width="500"]] | ||
601 | |||
602 | |||
603 | Click on the **Add widget / Add new widget** button. | ||
604 | |||
605 | |||
606 | [[image:dashboard-3.png]] | ||
607 | |||
608 | |||
![]() |
145.1 | 609 | In the **Select widgets bundle** window, click **Charts**. |
![]() |
141.1 | 610 | |
611 | |||
![]() |
145.1 | 612 | [[image:dashboard-4.png||height="537" width="700"]] |
613 | |||
614 | |||
615 | |||
616 | In the **Charts: select widget** window, click **Time series chart**. | ||
617 | |||
618 | |||
619 | [[image:dashboard-5.png||height="525" width="700"]] | ||
620 | |||
621 | |||
622 | Configure the **Time series chart** widget as follows: | ||
623 | |||
![]() |
149.1 | 624 | * **Datasource** - select S31B-NB device you provisioned. |
625 | * **Series**: | ||
![]() |
145.1 | 626 | ** **temperature** - you can see this key by default. |
![]() |
149.1 | 627 | ** **humidity** - Click **Add series** button. Then add the **humidity** for the key and then type **%** as its unit. |
![]() |
145.1 | 628 | * Click on the **Add** button. |
629 | |||
630 | [[image:timeseries-1.png||height="491" width="700"]] | ||
631 | |||
![]() |
146.1 | 632 | |
![]() |
149.1 | 633 | The time-series chart will appear in edit mode. Resize it by clicking and dragging the lower-right corner. |
634 | |||
635 | Click the **Save** button to add the widget to the dashboard. | ||
636 | |||
637 | |||
638 | [[image:timeseries-3.png||height="347" width="700"]] | ||
639 | |||
640 | |||
641 | Now send the following MQTT messages from the terminal to simulate the data. | ||
642 | |||
643 | |||
644 | {{code language="none"}} | ||
![]() |
169.1 | 645 | 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}' |
![]() |
149.1 | 646 | |
![]() |
169.1 | 647 | 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}' |
![]() |
149.1 | 648 | |
![]() |
169.1 | 649 | 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}' |
![]() |
149.1 | 650 | |
651 | {{/code}} | ||
652 | |||
653 | The chart will update with the values in realtime, as shown in the below image. | ||
654 | |||
655 | |||
656 | [[image:timeseries-4.png||height="316" width="700"]] | ||
657 | |||
658 | |||
![]() |
146.1 | 659 | = 7. Configure NB-IoT Sensor = |
660 | |||
661 | |||
662 | Now, let's experiment with sending data to ThingsBoard using a real NB-IoT device. For example, we will use the **S31B-NB**. | ||
663 | |||
664 | First, configure the NB-IoT device with the necessary MQTT settings using AT commands. Below is a list of AT commands you can use. | ||
665 | |||
666 | |||
667 | **AT Commands** | ||
668 | |||
![]() |
149.1 | 669 | * **AT+PRO=3,3 **~/~/ Use MQTT to connect to ThingsBoard. Payload Type set to 3. |
![]() |
169.1 | 670 | * **AT+SUBTOPIC=<MQTT subscribe topic> ** |
671 | * **AT+PUBTOPIC=<MQTT publish topic> Eg: TS01-NB** | ||
![]() |
150.1 | 672 | * **AT+CLIENT=null** |
673 | * **AT+UNAME=<MQTT Username>** | ||
674 | * **AT+PWD=<MQTT Password>** | ||
![]() |
152.1 | 675 | * **AT+SERVADDR=<Broker address, Port>** |
![]() |
146.1 | 676 | |
![]() |
150.1 | 677 | Test your uplink by pressing the ACT button for 1 second. |
![]() |
167.1 | 678 | |
679 | |||
![]() |
169.1 | 680 | 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**. |
![]() |
167.1 | 681 | |
![]() |
169.1 | 682 | [[image:image-4.png]] |
683 | |||
684 | |||
![]() |
167.1 | 685 |