Skip to Content

Changes for page ThingsBoard

Last modified by Dilisi S on 2025/04/23 19:23
From version 22.1
edited by Dilisi S
on 2025/03/04 04:36
Change comment: Uploaded new attachment "Integrations-list.png", version {1}
To version 69.1
edited by Dilisi S
on 2025/03/08 03:35
Change comment: Deleted image "data-converter-list-showing-uplink-dc.png"

Summary

Details

Page properties
Content
... ... @@ -6,50 +6,109 @@
6 6  Draft Document
7 7  {{/warning}}
8 8  
9 -= Introduction =
10 10  
10 +
11 +
12 += 1. Introduction =
13 +
14 +
11 11  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.
12 12  
13 13  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**.
14 14  
15 15  
16 -= Add New Device =
20 += 2. Add New Device =
17 17  
18 -In the left navigation, click **Entities** and then click **Devices**.
19 19  
23 +First, we will add a device to simulate data using MQTT. This device does not represent a real physical device but serves as a common virtual device for all Dragino NB/CB devices.
20 20  
21 -[[image:ThingsBoard-Device.png]]
25 +In the left navigation, click **Entities** and then click **Devices**.
22 22  
27 +[[image:device-list-empty.png]]
23 23  
29 +
24 24  On the **Devices **page, click on the ‘**+**’ button, and then click on the **Add new device **from the dropdown menu.
25 25  
26 -
27 27  [[image:ThingsBoard-add-new-device.png||height="279" width="500"]]
28 28  
29 29  
35 +The **Add new device** window appears. Name the device, for example '**Virtual NB/CB device**'.
30 30  
31 -= Data Converters =
37 +Click on the **Next: Credentials** button.
32 32  
39 +[[image:new-device-device-details.png||height="529" width="500"]]
40 +
41 +
42 +Click the **Access token** button if it is not selected by default.
43 +
44 +Copy the **Access token** to a text editor, as you will need it in the section **'Sending data from an MQTT client'**.
45 +
46 +Click on the **Add** button.
47 +
48 +[[image:new-device-access-token.png||height="528" width="500"]]
49 +
50 +
51 +Click on the **MQTT** button.
52 +
53 +Then, select the operating system you are going to use with the **Mosquitto MQTT Broker**. This example shows sending a command from a computer running **MacOS**. First, install the necessary client tools on your computer.
54 +
55 +Copy the MQTT pub command in the '**Execute the following command**' section.
56 +
57 +{{code language="none"}}
58 +mosquitto_pub -d -q 1 -h mqtt.eu.thingsboard.cloud -p 1883 -t v1/devices/me/telemetry -u "24vk3w9h7sqdld1me5eh" -m "{temperature:25}"
59 +{{/code}}
60 +
61 +Note that the **State** is still shown as **'Inactive'** in the **Latest telemetry** section.
62 +
63 +[[image:new-device-check-connectivity.png||height="522" width="500"]]
64 +
65 +
66 +On the terminal, enter the command you copied. This command sends the MQTT payload **{temperature:25}** as telemetry data from a virtual device named **'me'**. Of course, you can replace **'me'** with a device name or use the wildcard character **'+'** to match any device name.
67 +
68 +
69 +[[image:mqtt-command-1.png||height="228" width="700"]]
70 +
71 +
72 +If the command is successful, you can see the telemetry data you sent under the **Latest telemetry** section. Note that the **State** is now **'Active'** in the **Latest telemetry** section.
73 +
74 +
75 +[[image:new-device-telemetry-test.png||height="520" width="500"]]
76 +
77 +
78 +Send the same command again, only changing the **temperature** value, to see how the **Latest telemetry** section updates its data.
79 +
80 +Once you are done experimenting with this, close the window by clicking the **Close** button.
81 +
82 +
83 +[[image:mqtt-command-2.png||height="227" width="700"]]
84 +
85 +
86 +
87 +[[image:virtual-device-active.png]]
88 +
89 +
90 += 3. Data Converters =
91 +
92 +
33 33  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.
34 34  
35 35  
36 -== Uplink ==
96 +== 3.1 Uplink ==
37 37  
98 +
38 38  In the left navigation, click **Integrations center**, and then click **Data converters**.
39 39  
101 +[[image:data-converter-list-page.png]]
40 40  
41 -[[image:ThingsBoard-Data-Converters.png]]
42 42  
43 -
44 44  On the **Data converters** page, click on the ‘+’ button, and then click on the **Create new converter** from the dropdown menu.
45 45  
46 -
47 47  [[image:ThingsBoard-new-data-converter.png||height="282" width="500"]]
48 48  
49 49  
50 -The **Add data converter** window will appear. Name it ‘**UDP Uplink Converter NB/CB**’ and select the Type as **Uplink**.
109 +The **Add data converter** window will appear. Name it ‘**MQTT Uplink Converter NB/CB**’ and select the Type as **Uplink**.
51 51  
52 -Click on the **JavaScript** button. Now copy and paste the following script to the **Decoder function** section:
111 +Click on the **JavaScript** button. Now copy and paste the following JavaScript to the **Decoder function** section. This decoder function is valid for both NB and CB series devices.
53 53  
54 54  {{code language="JavaScript"}}
55 55  //Version: 0.1
... ... @@ -174,29 +174,28 @@
174 174  
175 175  {{/code}}
176 176  
236 +
177 177  Click on the **Add** button.
178 178  
239 +[[image:uplink-data-converter.png||height="529" width="500"]]
179 179  
180 -[[image:ThingsBoard-add-data-converter-uplink.png||width="500"]]
181 181  
242 +You should see that the newly added **uplink data converter** is listed on the **Data Converters** page.
182 182  
183 -The uplink data converter is added to ThingsBoard and is listed on the **Data Converters** page.
244 +[[image:data-converter-list-showing-uplink-dc.png]]
184 184  
185 185  
186 -[[image:Data-converter-list-uplink-only.png]]
247 +== 3.2 Downlink ==
187 187  
188 188  
189 -== Downlink ==
190 -
191 191  On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu.
192 192  
193 -
194 194  [[image:ThingsBoard-new-data-converter.png||height="282" width="500"]]
195 195  
196 196  
197 -The **Add data converter** window will appear. Name it ‘**UDP Downlink Converter NB/CB**’ and select the Type as **Downlink**.
255 +The **Add data converter** window will appear. Name it ‘**MQTT Downlink Converter NB/CB**’ and select the Type as **Downlink**.
198 198  
199 -Click on the **JavaScript** button. Now copy and paste the following script to the **Encoder function **section:
257 +Click on the **JavaScript** button. Now copy and paste the following JavaScript to the **Encoder function **section. This encoder function is valid for both NB and CB series devices.
200 200  
201 201  
202 202  {{code language="JavaScript"}}
... ... @@ -231,40 +231,36 @@
231 231  
232 232  Click on the **Add** button.
233 233  
292 +[[image:downlink-data-converter.png||height="530" width="500"]]
234 234  
235 -[[image:ThingsBoard-add-data-converter-downlink.png||height="532" width="500"]]
236 236  
295 +You should see that the newly added **downlink data converter** is listed on the **Data Converters** page.
237 237  
238 -The downlink data converter is added to ThingsBoard and is listed on the **Data Converters** page.
297 +[[image:data-converter-list.png]]
239 239  
240 240  
241 -[[image:Data-converter-list.png]]
300 += 4. Add Integration =
242 242  
243 243  
244 -= Add Integration =
245 -
246 246  In the left navigation, click **Integrations center**, and then click **Integrations**.
247 247  
248 248  On the **Integrations** page, click on the '**+**' button.
249 249  
307 +[[image:data-converter-list-page.png]]
250 250  
251 -[[image:ThingsBoard-add-integration.png]]
252 252  
253 -
254 254  The **Add integration** window appears.
255 255  
256 -In the Add Integration window, configure the following settings:
312 +In the **Add integration** window, configure the following settings:
257 257  
258 258  
259 -
260 260  **Basic settings:**
261 261  
262 -* **Integration type**: UDP
263 -* **Name**: UDP Integration NB/CB
317 +* **Integration type**: MQTT
318 +* **Name**: MQTT integration NB/CB
264 264  
265 265  Click **Next** button.
266 266  
267 -
268 268  [[image:add-integration-basic-settings.png||height="511" width="500"]]
269 269  
270 270  
... ... @@ -271,44 +271,61 @@
271 271  **Uplink data converter:**
272 272  
273 273  * Click on the **Select existing** button.
274 -* **Uplink data converter**: Select **UDP Uplink Converter NB/CB **from the dropdown list.
328 +* **Uplink data converter**: Select **MQTT Uplink Converter NB/CB **from the dropdown list.
275 275  
276 276  Click **Next** button.
277 277  
332 +[[image:add-integration-uplink-data-converter.png||width="500"]]
278 278  
279 -[[image:add-integration-uplink-data-converter.png||height="511" width="500"]]
280 280  
281 -
282 282  **Downlink data converter:**
283 283  
284 284  * Click on the **Select existing** button.
285 -* **Downlink data converter**: Select **UDP Downlink Converter NB/CB **from the dropdown list.
338 +* **Downlink data converter**: Select **MQTT Downlink Converter NB/CB **from the dropdown list.
286 286  
287 287  Click **Next** button.
288 288  
342 +[[image:add-integration-downlink-data-converter.png||height="510" width="500"]]
289 289  
290 -[[image:add-integration-downlink-data-converter.png||height="512" width="500"]]
291 291  
292 -
293 293  **Connection:**
294 294  
295 -* **Port**: 11582
296 -* **Size of the buffer for inbound socket (in KB)**: 64
297 -* **Cache Size**: 10000000
298 -* **Cache time to live in minutes**: 1440
347 +* **Host**: mqtt.eu.thingsboard.cloud (This is the host name you copied from the device - See section xxxxx for more information)
348 +* **Port**: 1883 (This is the port number you copied from the device - See section xxxxx for more information)
349 +* **Credentials**: Basic
350 +* **Username**: Access token (This is the access token you copied from the device)
351 +* **Password** - Leave it as blank
352 +* **Topic** - v1/devices/+/telemetry (sightly modify the topic 'v1/devices/me/telemetry' you copied from the device to enable receiving data from any 'device name')
353 +* **QoS** - 0-At most once
299 299  
300 -Copy the two keys, **Integration key** and **Integration secret** into a text editor, as you will need them in the section ‘xxxxx’.
355 +Click on the **Check connection** button to verify the MQTT connection using the provided parameters.
301 301  
357 +[[image:add-integration-connection.png||width="500"]]
358 +
359 +
360 +If the connection is successful, you will see the **Connected** message.
361 +
302 302  Click on the **Add** button.
303 303  
364 +[[image:add-connection-success.png||height="511" width="500"]]
304 304  
305 -[[image:add-integration-connection.png||height="511" width="500"]]
306 306  
367 +You should see that the newly added integration is listed on the **Integrations** page.
307 307  
369 +Since we haven't received data from a device yet, the integration **Status** is shown as **Pending.**
308 308  
309 -= Verifying the receipt of data from the device =
371 +[[image:integrations-list-added-pending.png]]
310 310  
311 -Connect **S31B-NB** to transfer information. If the integration was performed without errors, after the transmission of the first telemetry, a new device with the name “xxxxx” 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.
312 312  
374 += 5. Verifying the receipt of data from the device =
313 313  
376 +
377 +On the terminal, issue the following MQTT command which simulates the device S31B-NB.
378 +
379 +{{code language="none"}}
380 +mosquitto_pub -d -q 1 -h mqtt.eu.thingsboard.cloud -p 1883 -t v1/devices/S31B-NB/telemetry -u "24vk3w9h7sqdld1me5eh" -m "{temperature:20}"
381 +{{/code}}
382 +
383 +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.
384 +
314 314  
Data-converter-list-uplink-only.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -128.6 KB
Content
Data-converter-list.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -128.6 KB
Content
Integrations-list.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -128.6 KB
Content
ThingsBoard-Data-Converters.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -100.3 KB
Content
ThingsBoard-Device.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -225.5 KB
Content
ThingsBoard-add-data-converter-downlink.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -128.6 KB
Content
ThingsBoard-add-data-converter-uplink.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -128.6 KB
Content
ThingsBoard-add-integration.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -128.6 KB
Content
add-integration-connection.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -124.4 KB
Content
add-integration-uplink-data-converter.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -120.7 KB
Content
data-converter-list-page.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +190.8 KB
Content
data-converter-list.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +202.8 KB
Content
device-list-empty.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +202.8 KB
Content
downlink-data-converter.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +207.8 KB
Content
integrations-list-added-pending.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +202.8 KB
Content
mqtt-command-1.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +202.8 KB
Content
mqtt-command-2.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +202.8 KB
Content
new-device-access-token.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +202.8 KB
Content
new-device-check-connectivity.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +202.8 KB
Content
new-device-device-details.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +88.4 KB
Content
new-device-telemetry-test.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +202.8 KB
Content
uplink-data-converter.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +128.6 KB
Content
virtual-device-active.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +202.8 KB
Content