Skip to Content

Changes for page ThingsBoard

Last modified by Dilisi S on 2025/04/23 19:23
From version 48.1
edited by Dilisi S
on 2025/03/05 15:09
Change comment: Uploaded new attachment "add-connection-success.png", version {1}
To version 117.1
edited by Dilisi S
on 2025/03/08 20:16
Change comment: Mar 8 edits - part 1

Summary

Details

Page properties
Content
... ... @@ -6,223 +6,204 @@
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. Prerequisites =
17 17  
18 -In the left navigation, click **Entities** and then click **Devices**.
22 +To complete this tutorial, you need to have the following:
19 19  
24 +* ThingsBoard cloud account -
25 +* HiveMQ Cloud account
20 20  
21 -[[image:ThingsBoard-Device.png]]
22 22  
28 +== 2.1 HiveMQ Cloud ==
23 23  
24 -On the **Devices **page, click on the ‘**+**’ button, and then click on the **Add new device **from the dropdown menu.
25 25  
31 +Go to [[https:~~/~~/www.hivemq.com>>https://www.hivemq.com]]
26 26  
27 -[[image:ThingsBoard-add-new-device.png||height="279" width="500"]]
33 +Click on the **Start Free** button.
28 28  
35 +[[image:hivwmq-1.png]]
29 29  
30 30  
31 -= Data Converters =
38 +Click on the **Sign Up FREE Now** button in the **HIVEMQ CLOUD** section.
32 32  
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 +
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 +== 2.1 Uplink ==
37 37  
98 +
38 38  In the left navigation, click **Integrations center**, and then click **Data converters**.
39 39  
40 40  
41 -[[image:data-converter-list-page.png]]
42 42  
103 +[[image:data-converters-list-empty.png]]
43 43  
44 -On the **Data converters** page, click on the ‘+’ button, and then click on the **Create new converter** from the dropdown menu.
45 45  
106 +On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu.
46 46  
47 -[[image:ThingsBoard-new-data-converter.png||height="282" width="500"]]
48 48  
49 49  
110 +[[image:create-new-converter-menu.png||height="259" width="500"]]
111 +
112 +
50 50  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 JavaScript to the **Decoder function** section. This decoder function is valid for both NB and CB series devices.
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.
53 53  
54 54  {{code language="JavaScript"}}
55 -//Version: 0.1
118 +/** Decoder **/
119 +
56 56  // decode payload to string
57 57  var payloadStr = decodeToString(payload);
122 +var data = JSON.parse(payloadStr);
58 58  
124 +var deviceName = metadata.topic.split("/")[3];
59 59  // decode payload to JSON
60 -var objdata = {};
61 -var obj1 = {};
62 -var data = decodeToJson(payload);
63 -var deviceName = data.IMEI;
64 -delete data.IMEI;
65 -var modelname = "Dragino " + data.Model;
66 -//var mod = data.mod
67 -delete data.Model;
68 -//delete data.mod
69 -var timestamp = new Date().getTime();
126 +var deviceType = 'sensor';
70 70  
71 -for (var key in data) {
72 -
73 - if (Number(key)) {
74 - obj1[key] = data[key];
75 - obj1[key][obj1[key].length - 1] = Number(new Date(
76 - obj1[key][obj1[key].length - 1]));
77 -
78 - }
79 -//Alec submitted25/02/25
80 -//turn old key into new
81 - else if (key === "Reading") {
82 - objdata["reading"] = data[key];
83 - } else if (key === "work mode") {
84 - objdata["work_mode"] = data[key];
85 - } else if (key === "hum") {
86 - objdata["humidity"] = data[key];
87 - }else if (key === "hum2") {
88 - objdata["humidity2"] = data[key];
89 - } else if (key === "hum3") {
90 - objdata["humidity3"] = data[key];
91 - } else if (key === "tem") {
92 - objdata["temperature"] = data[key];
93 - } else if (key === "tem2") {
94 - objdata["temperature2"] = data[key];
95 - } else if (key === "tem3") {
96 - objdata["temperature3"] = data[key];
97 - } else if (key === "DS18B20_Temp") {
98 - objdata["temperature_pro"] = data[key];
99 - } else if (key === "ds18b20_temperature") {
100 - objdata["temperature_pro"] = data[key];
101 - } else if (key === "DS18B20_temperature_pro") {
102 - objdata["temperature_pro"] = data[key];
103 - } else if (key === "tdc send flag") {
104 - objdata["tdc_send_flag"] = data[key];
105 - } else if (key === "trigger mode") {
106 - objdata["trigger_mode"] = data[key];
107 - } else if (key === "soil dielectric constant") {
108 - objdata["soil_dielectric_constant"] = data[key];
109 - } else if (key === "door open num") {
110 - objdata["door_open_num"] = data[key];
111 - } else if (key === "door duration") {
112 - objdata["door_duration"] = data[key];
113 - } else if (key === "count time") {
114 - objdata["count_time"] = data[key];
115 - } else if (key === "last open time2") {
116 - objdata["last_open_time2"] = data[key];
117 - } else if (key === "last open time3") {
118 - objdata["last_open_time3"] = data[key];
119 - }
120 -//Alec submitted25/02/25
121 - else {
122 - objdata[key] = data[key]
123 - }
124 -}
125 -var listdata = [{
126 - "ts": timestamp,
127 - "values": objdata
128 -}]
129 -for (var key1 in obj1) {
130 - if (modelname == "Dragino RS485-NB") {
131 - listdata.push({
132 - "ts": obj1[key1][obj1[key1].length - 1],
133 - "values": {
134 - "Payload": obj1[key1][0],
135 - }
136 - })
137 - } else {
138 - listdata.push({
139 - "ts": obj1[key1][obj1[key1].length - 1],
140 - "values": {
141 - "values": obj1[key1]
142 - },
143 - })
144 - }
145 -}
128 +// Result object with device attributes/telemetry data
146 146  var result = {
147 -
148 148   deviceName: deviceName,
149 - deviceType: modelname,
131 + deviceType: deviceType,
150 150   attributes: {
151 - model: modelname,
152 - //customerName: "NB-CB",
153 - //groupName: "NB-CB",
154 - //integrationName: metadata['integrationName']
155 -
133 + integrationName: metadata['integrationName'],
156 156   },
157 - telemetry: listdata
158 -}
135 + telemetry: {
136 + temperature: data.temperature,
137 + humidity: data.humidity,
138 + }
139 +};
159 159  
160 -function decodeToString(payload) {
161 - return String.fromCharCode.apply(String, payload);
162 -}
141 +/** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/
163 163  
164 -function decodeToJson(payload) {
165 - // covert payload to string.
166 - var str = decodeToString(payload);
167 -
168 - // parse string to JSON
169 - var data = JSON.parse(str);
170 - return data;
171 -}
172 -
173 173  return result;
174 -
175 175  {{/code}}
176 176  
146 +
177 177  Click on the **Add** button.
178 178  
179 179  
180 -[[image:uplink-data-converter.png||height="529" width="500"]]
181 181  
151 +[[image:add-uplink-data-converter.png||height="529" width="500"]]
182 182  
183 183  
184 -You should see that the newly added **uplink data converter** is listed on the **Data Converters** page.
154 +You should see that the newly added **MQTT Uplink converter **NB/CB is listed on the **Data Converters** page.
185 185  
186 -
187 187  [[image:data-converter-list-showing-uplink-dc.png]]
188 188  
189 189  
190 -== Downlink ==
191 191  
160 +== 3.2 Downlink ==
161 +
162 +
192 192  On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu.
193 193  
194 194  
195 -[[image:ThingsBoard-new-data-converter.png||height="282" width="500"]]
166 +[[image:create-new-converter-menu.png||width="500"]]
196 196  
197 197  
169 +
198 198  The **Add data converter** window will appear. Name it ‘**MQTT Downlink Converter NB/CB**’ and select the Type as **Downlink**.
199 199  
200 -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.
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.
201 201  
202 202  
203 203  {{code language="JavaScript"}}
204 -function hexToBase64(hexString) {
205 - // 将16进制字符串两个字符转换为一个字节
206 - var bytes = hexString.match(/.{2}/g);
207 - // 对每个字节进行解析，并转换为对应的字符
208 - var binaryString = bytes.map(function(byte) {
209 - return String.fromCharCode(parseInt(byte, 16));
210 - }).join('');
211 -
212 - // 使用btoa进行base64编码
213 - return btoa(binaryString);
214 -}
176 +// Encode downlink data from incoming Rule Engine message
215 215  
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 +
216 216  // Result object with encoded downlink payload
217 217  var result = {
196 +
218 218   // downlink data content type: JSON, TEXT or BINARY (base64 format)
219 - contentType: "BINARY",
198 + contentType: "JSON",
220 220  
221 221   // downlink data
222 - data:hexToBase64(metadata.shared_value)
201 + data: JSON.stringify(data),
223 223  
224 224   // Optional metadata object presented in key/value format
225 - //metadata: {}
204 + metadata: {
205 + topic: metadata['deviceType']+'/'+metadata['deviceName']+'/upload'
206 + }
226 226  
227 227  };
228 228  
... ... @@ -233,26 +233,29 @@
233 233  Click on the **Add** button.
234 234  
235 235  
236 -[[image:downlink-data-converter.png||height="530" width="500"]]
237 237  
218 +[[image:add-downlink-data-converter.png||height="529" width="500"]]
238 238  
239 239  
240 -You should see that the newly added **downlink data converter** is listed on the **Data Converters** page.
221 +You should see that the newly added **MQTT Downlink** Converter NB/CB is listed on the **Data Converters** page.
241 241  
242 242  
243 -[[image:data-converter-list.png]]
224 +[[image:data-converters-list.png]]
244 244  
245 245  
246 -= Add Integration =
247 247  
228 += 3. Add Integration =
229 +
230 +
248 248  In the left navigation, click **Integrations center**, and then click **Integrations**.
249 249  
250 -On the **Integrations** page, click on the '**+**' button.
251 251  
234 +[[image:integrations-list-empty.png]]
252 252  
253 -[[image:ThingsBoard-add-integration.png]]
254 254  
237 +On the **Integrations** page, click on the '**+**' button.
255 255  
239 +
256 256  The **Add integration** window appears.
257 257  
258 258  In the **Add integration** window, configure the following settings:
... ... @@ -260,12 +260,15 @@
260 260  
261 261  **Basic settings:**
262 262  
263 -* **Integration type**: UDP
264 -* **Name**: UDP Integration NB/CB
247 +* **Integration type**: MQTT
248 +* **Name**: MQTT integration NB/CB
249 +* **Enable integration**: YES
250 +* **Allows create devices or assets**: YES
265 265  
266 266  Click **Next** button.
267 267  
268 268  
255 +
269 269  [[image:add-integration-basic-settings.png||height="511" width="500"]]
270 270  
271 271  
... ... @@ -272,11 +272,12 @@
272 272  **Uplink data converter:**
273 273  
274 274  * Click on the **Select existing** button.
275 -* **Uplink data converter**: Select **UDP Uplink Converter NB/CB **from the dropdown list.
262 +* **Uplink data converter**: Select **MQTT Uplink Converter NB/CB **from the dropdown list.
276 276  
277 277  Click **Next** button.
278 278  
279 279  
267 +
280 280  [[image:add-integration-uplink-data-converter.png||height="511" width="500"]]
281 281  
282 282  
... ... @@ -283,38 +283,67 @@
283 283  **Downlink data converter:**
284 284  
285 285  * Click on the **Select existing** button.
286 -* **Downlink data converter**: Select **UDP Downlink Converter NB/CB **from the dropdown list.
274 +* **Downlink data converter**: Select **MQTT Downlink Converter NB/CB **from the dropdown list.
287 287  
288 288  Click **Next** button.
289 289  
290 290  
291 -[[image:add-integration-downlink-data-converter.png||height="512" width="500"]]
292 292  
280 +[[image:add-integration-downlink-data-converter.png||height="511" width="500"]]
293 293  
282 +
294 294  **Connection:**
295 295  
296 -* **Port**: 11582
297 -* **Size of the buffer for inbound socket (in KB)**: 64
298 -* **Cache Size**: 10000000
299 -* **Cache time to live in minutes**: 1440
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
300 300  
301 -Copy the two keys, **Integration key** and **Integration secret** into a text editor, as you will need them in the section ‘xxxxx’.
294 +[[image:add-integration-connection.png||height="511" width="500"]]
302 302  
303 -Click on the **Add** button.
304 304  
297 +Click on the **Advanced settings** button.
305 305  
306 -[[image:add-integration-connection.png||height="511" width="500"]]
299 +* **Clean session:** NO
300 +* **Retained**: NO
307 307  
302 +[[image:add-integration-connection-advanced-settings.png||height="510" width="500"]]
308 308  
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 +
309 309  You should see that the newly added integration is listed on the **Integrations** page.
310 310  
311 311  Since we haven't received data from a device yet, the integration **Status** is shown as **Pending.**
312 312  
313 -[[image:Integrations-list.png]]
314 314  
315 315  
316 -= Verifying the receipt of data from the device =
325 +[[image:new-integration-pending.png]]
317 317  
318 -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.
319 319  
328 += 5. Verifying the receipt of data from the device =
320 320  
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.
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.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -128.6 KB
Content
ThingsBoard-add-new-device.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -89.7 KB
Content
ThingsBoard-new-data-converter.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -100.3 KB
Content
add-connection-success.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -202.8 KB
Content
data-converter-list-page.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -190.8 KB
Content
data-converter-list.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -202.8 KB
Content
downlink-data-converter.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -207.8 KB
Content
uplink-data-converter.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.pradeeka
Size
... ... @@ -1,1 +1,0 @@
1 -128.6 KB
Content
add-downlink-data-converter.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +175.2 KB
Content
add-integration-connection-advanced-settings.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +155.2 KB
Content
add-uplink-data-converter.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +174.1 KB
Content
check-connection.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +14.7 KB
Content
connection-success.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +90.0 KB
Content
create-new-converter-menu.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +31.5 KB
Content
data-converters-list-empty.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +260.7 KB
Content
data-converters-list.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +212.2 KB
Content
hivemq-2.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +300.7 KB
Content
hivemq-3.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +535.2 KB
Content
hivemq-4.jpg
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +309.8 KB
Content
hivemq-5.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +115.0 KB
Content
hivemq-6.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +321.0 KB
Content
hivemq-7.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +203.5 KB
Content
hivemq-8.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +294.1 KB
Content
hivwmq-1.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +380.3 KB
Content
integrations-list-empty.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +264.5 KB
Content
new-integration-pending.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pradeeka
Size
... ... @@ -1,0 +1,1 @@
1 +199.7 KB
Content