Skip to Content

Changes for page ThingsBoard

Last modified by Dilisi S on 2025/04/23 19:23
From version 119.1
edited by Dilisi S
on 2025/03/08 20:22
Change comment: Uploaded new attachment "hivemq-9.png", version {1}
To version 15.1
edited by Dilisi S
on 2025/03/03 02:41
Change comment: Uploaded new attachment "add-integration-connection.png", version {1}

Summary

Details

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