Skip to Content

Changes for page ThingsBoard

Last modified by Dilisi S on 2025/04/23 19:23
From version 116.1
edited by Dilisi S
on 2025/03/08 20:12
Change comment: Uploaded new attachment "hivemq-8.png", version {1}
To version 16.1
edited by Dilisi S
on 2025/03/03 02:45
Change comment: Mar 2 edits - part 2

Summary

Details

Page properties
Content
... ... @@ -6,137 +6,215 @@
6 6  Draft Document
7 7  {{/warning}}
8 8  
9 += Introduction =
9 9  
11 +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 =
14 += Add New Device =
13 13  
16 +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**.
19 +[[image:ThingsBoard-Device.png]]
18 18  
19 19  
22 +On the ‘**Devices**’ page, click on the ‘**+**’ button, and then click on the ‘**Add new device**’ from the dropdown menu.
20 20  
21 21  
25 +[[image:ThingsBoard-add-new-device.png||height="279" width="500"]]
22 22  
23 -= 2. Data Converters =
24 24  
25 25  
26 -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.
29 += Data Converters =
27 27  
28 28  
29 -== 2.1 Uplink ==
32 +== Uplink ==
30 30  
34 +In the left navigation, click ‘Integrations center’, and then click ‘Data converters’.
31 31  
32 -In the left navigation, click **Integrations center**, and then click **Data converters**.
33 33  
37 +[[image:ThingsBoard-Data-Converters.png]]
34 34  
35 35  
36 -[[image:data-converters-list-empty.png]]
40 +On the ‘Data converters’ page, click on the ‘+’ button, and then click on the ‘Create new converter’ from the dropdown menu.
37 37  
38 38  
39 -On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu.
43 +[[image:ThingsBoard-new-data-converter.png||height="282" width="500"]]
40 40  
41 41  
46 +The ‘Add data converter’ window will appear. Name it ‘**UDP Uplink Converter NB/CB**’ and select the Type as ‘Uplink’.
42 42  
43 -[[image:create-new-converter-menu.png||height="259" width="500"]]
48 +Click on the ‘JavaScript’ button. Now copy and paste the following script to the ‘Decoder function’ section:
44 44  
45 -
46 -The **Add data converter** window will appear. Name it ‘**MQTT Uplink Converter NB/CB**’ and select the Type as **Uplink**.
47 -
48 -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.
49 -
50 50  {{code language="JavaScript"}}
51 -/** Decoder **/
52 -
51 +//Version: 0.1
53 53  // decode payload to string
54 54  var payloadStr = decodeToString(payload);
55 -var data = JSON.parse(payloadStr);
56 56  
57 -var deviceName = metadata.topic.split("/")[3];
58 58  // decode payload to JSON
59 -var deviceType = 'sensor';
56 +var objdata = {};
57 +var obj1 = {};
58 +var data = decodeToJson(payload);
59 +var deviceName = data.IMEI;
60 +delete data.IMEI;
61 +var modelname = "Dragino " + data.Model;
62 +//var mod = data.mod
63 +delete data.Model;
64 +//delete data.mod
65 +var timestamp = new Date().getTime();
60 60  
61 -// Result object with device attributes/telemetry data
67 +for (var key in data) {
68 +
69 + if (Number(key)) {
70 + obj1[key] = data[key];
71 + obj1[key][obj1[key].length - 1] = Number(new Date(
72 + obj1[key][obj1[key].length - 1]));
73 +
74 + }
75 +//Alec submitted25/02/25
76 +//turn old key into new
77 + else if (key === "Reading") {
78 + objdata["reading"] = data[key];
79 + } else if (key === "work mode") {
80 + objdata["work_mode"] = data[key];
81 + } else if (key === "hum") {
82 + objdata["humidity"] = data[key];
83 + }else if (key === "hum2") {
84 + objdata["humidity2"] = data[key];
85 + } else if (key === "hum3") {
86 + objdata["humidity3"] = data[key];
87 + } else if (key === "tem") {
88 + objdata["temperature"] = data[key];
89 + } else if (key === "tem2") {
90 + objdata["temperature2"] = data[key];
91 + } else if (key === "tem3") {
92 + objdata["temperature3"] = data[key];
93 + } else if (key === "DS18B20_Temp") {
94 + objdata["temperature_pro"] = data[key];
95 + } else if (key === "ds18b20_temperature") {
96 + objdata["temperature_pro"] = data[key];
97 + } else if (key === "DS18B20_temperature_pro") {
98 + objdata["temperature_pro"] = data[key];
99 + } else if (key === "tdc send flag") {
100 + objdata["tdc_send_flag"] = data[key];
101 + } else if (key === "trigger mode") {
102 + objdata["trigger_mode"] = data[key];
103 + } else if (key === "soil dielectric constant") {
104 + objdata["soil_dielectric_constant"] = data[key];
105 + } else if (key === "door open num") {
106 + objdata["door_open_num"] = data[key];
107 + } else if (key === "door duration") {
108 + objdata["door_duration"] = data[key];
109 + } else if (key === "count time") {
110 + objdata["count_time"] = data[key];
111 + } else if (key === "last open time2") {
112 + objdata["last_open_time2"] = data[key];
113 + } else if (key === "last open time3") {
114 + objdata["last_open_time3"] = data[key];
115 + }
116 +//Alec submitted25/02/25
117 + else {
118 + objdata[key] = data[key]
119 + }
120 +}
121 +var listdata = [{
122 + "ts": timestamp,
123 + "values": objdata
124 +}]
125 +for (var key1 in obj1) {
126 + if (modelname == "Dragino RS485-NB") {
127 + listdata.push({
128 + "ts": obj1[key1][obj1[key1].length - 1],
129 + "values": {
130 + "Payload": obj1[key1][0],
131 + }
132 + })
133 + } else {
134 + listdata.push({
135 + "ts": obj1[key1][obj1[key1].length - 1],
136 + "values": {
137 + "values": obj1[key1]
138 + },
139 + })
140 + }
141 +}
62 62  var result = {
143 +
63 63   deviceName: deviceName,
64 - deviceType: deviceType,
145 + deviceType: modelname,
65 65   attributes: {
66 - integrationName: metadata['integrationName'],
147 + model: modelname,
148 + //customerName: "NB-CB",
149 + //groupName: "NB-CB",
150 + //integrationName: metadata['integrationName']
151 +
67 67   },
68 - telemetry: {
69 - temperature: data.temperature,
70 - humidity: data.humidity,
71 - }
72 -};
153 + telemetry: listdata
154 +}
73 73  
74 -/** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/
156 +function decodeToString(payload) {
157 + return String.fromCharCode.apply(String, payload);
158 +}
75 75  
76 -return result;
77 -{{/code}}
160 +function decodeToJson(payload) {
161 + // covert payload to string.
162 + var str = decodeToString(payload);
78 78  
164 + // parse string to JSON
165 + var data = JSON.parse(str);
166 + return data;
167 +}
79 79  
80 -Click on the **Add** button.
169 +return result;
81 81  
171 +{{/code}}
82 82  
173 +Click on the ‘Add’ button.
83 83  
84 -[[image:add-uplink-data-converter.png||height="529" width="500"]]
85 85  
176 +[[image:ThingsBoard-add-data-converter-uplink.png||width="500"]]
86 86  
87 -You should see that the newly added **MQTT Uplink converter **NB/CB is listed on the **Data Converters** page.
88 88  
89 -[[image:data-converter-list-showing-uplink-dc.png]]
179 +The uplink data converter is added to ThingsBoard and appears on the ‘Data Converters’ page
90 90  
91 91  
182 +== Downlink ==
92 92  
93 -== 3.2 Downlink ==
184 +On the ‘Data converters’ page, click on the ‘+’ button, and then click on the ‘Create new converter’ from the dropdown menu.
94 94  
95 95  
96 -On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu.
187 +[[image:ThingsBoard-new-data-converter.png||height="282" width="500"]]
97 97  
98 98  
99 -[[image:create-new-converter-menu.png||width="500"]]
190 +The ‘**Add data converter**’ window will appear. Name it ‘**UDP Downlink Converter NB/CB**’ and select the Type as ‘**Downlink**’.
100 100  
192 +Click on the ‘**JavaScript**’ button. Now copy and paste the following script to the ‘**Encoder function**’ section:
101 101  
102 102  
103 -The **Add data converter** window will appear. Name it ‘**MQTT Downlink Converter NB/CB**’ and select the Type as **Downlink**.
104 -
105 -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.
106 -
107 -
108 108  {{code language="JavaScript"}}
109 -// Encode downlink data from incoming Rule Engine message
196 +function hexToBase64(hexString) {
197 + // 将16进制字符串两个字符转换为一个字节
198 + var bytes = hexString.match(/.{2}/g);
199 + // 对每个字节进行解析，并转换为对应的字符
200 + var binaryString = bytes.map(function(byte) {
201 + return String.fromCharCode(parseInt(byte, 16));
202 + }).join('');
203 +
204 + // 使用btoa进行base64编码
205 + return btoa(binaryString);
206 +}
110 110  
111 -// msg - JSON message payload downlink message json
112 -// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
113 -// metadata - list of key-value pairs with additional data about the message
114 -// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter
115 -
116 -/** Encoder **/
117 -
118 -var data = {};
119 -
120 -// Process data from incoming message and metadata
121 -
122 -data.tempFreq = msg.temperatureUploadFrequency;
123 -data.humFreq = msg.humidityUploadFrequency;
124 -
125 -data.devSerialNumber = metadata['ss_serialNumber'];
126 -
127 127  // Result object with encoded downlink payload
128 128  var result = {
129 -
130 130   // downlink data content type: JSON, TEXT or BINARY (base64 format)
131 - contentType: "JSON",
211 + contentType: "BINARY",
132 132  
133 133   // downlink data
134 - data: JSON.stringify(data),
214 + data:hexToBase64(metadata.shared_value)
135 135  
136 136   // Optional metadata object presented in key/value format
137 - metadata: {
138 - topic: metadata['deviceType']+'/'+metadata['deviceName']+'/upload'
139 - }
217 + //metadata: {}
140 140  
141 141  };
142 142  
... ... @@ -147,127 +147,80 @@
147 147  Click on the **Add** button.
148 148  
149 149  
228 +[[image:ThingsBoard-add-data-converter-downlink.png||height="532" width="500"]]
150 150  
151 -[[image:add-downlink-data-converter.png||height="529" width="500"]]
152 152  
231 += Add Integration =
153 153  
154 -You should see that the newly added **MQTT Downlink** Converter NB/CB is listed on the **Data Converters** page.
233 +In the left navigation, click ‘Integrations center’, and then click ‘Integrations’.
155 155  
235 +On the ‘Integrations’ page, click on the “+” button.
156 156  
157 -[[image:data-converters-list.png]]
158 158  
159 -(% class="wikigeneratedid" %)
238 +[[image:ThingsBoard-add-integration.png]]
160 160  
161 161  
162 -= 3. Add Integration =
241 +The ‘Add integration’ window appears.
163 163  
243 +In the Add Integration window, configure the following settings:
164 164  
165 -In the left navigation, click **Integrations center**, and then click **Integrations**.
166 -
167 -
168 -[[image:integrations-list-empty.png]]
169 -
170 -
171 -On the **Integrations** page, click on the '**+**' button.
172 -
173 -
174 -The **Add integration** window appears.
175 -
176 -In the **Add integration** window, configure the following settings:
177 -
178 -
179 179  **Basic settings:**
180 180  
181 -* **Integration type**: MQTT
182 -* **Name**: MQTT integration NB/CB
183 -* **Enable integration**: YES
184 -* **Allows create devices or assets**: YES
247 +* **Integration type**: UDP
248 +* **Name**: UDP Integration NB/CB
185 185  
186 186  Click **Next** button.
187 187  
188 188  
189 -
190 190  [[image:add-integration-basic-settings.png||height="511" width="500"]]
191 191  
192 192  
193 193  **Uplink data converter:**
194 194  
195 -* Click on the **Select existing** button.
196 -* **Uplink data converter**: Select **MQTT Uplink Converter NB/CB **from the dropdown list.
258 +* Click on the ‘**Select existing**’ button.
259 +* Uplink data converter: Select ‘**UDP Uplink Converter NB/CB**’ from the dropdown list.
197 197  
198 198  Click **Next** button.
199 199  
200 200  
201 -
202 202  [[image:add-integration-uplink-data-converter.png||height="511" width="500"]]
203 203  
204 204  
205 205  **Downlink data converter:**
206 206  
207 -* Click on the **Select existing** button.
208 -* **Downlink data converter**: Select **MQTT Downlink Converter NB/CB **from the dropdown list.
269 +* Click on the ‘**Select existing**’ button.
270 +* Downlink data converter: Select ‘**UDP Downlink Converter NB/CB**’ from the dropdown list.
209 209  
272 +
210 210  Click **Next** button.
211 211  
212 212  
276 +[[image:add-integration-downlink-data-converter.png||height="512" width="500"]]
213 213  
214 -[[image:add-integration-downlink-data-converter.png||height="511" width="500"]]
215 215  
216 -
217 217  **Connection:**
218 218  
219 -* **Host**: Cluster URL (Eg. 011731f7928541588a6cdfbbedfc63f4.s1.eu.hivemq.cloud)
220 -* **Port**: 8883
221 -* **Credentials**: Basic
222 -* **Enable SSL**: YES
223 -* **Username**: Username (from your HiveMQ Cloud Cluster with your credentials)
224 -* **Password:** Password (from your HiveMQ Cloud Cluster with your credentials)
225 -* **Topic:** tb/mqtt-integration-tutorial/sensors/+/telemetry (the + replaces any 'device name' and creates devices in the Entities -> Devices)
226 -* **QoS:** 0-At most once
281 +**Port**: 11582
227 227  
283 +**Size of the buffer for inbound socket (in KB)**: 64
228 228  
229 -[[image:add-integration-connection.png||height="511" width="500"]]
285 +**Cache Size**: 10000000
230 230  
287 +**Cache time to live in minutes**: 1440
231 231  
232 -Click on the **Advanced settings** button.
233 233  
234 -* **Clean session:** NO
235 -* **Retained**: NO
290 +Copy the two keys, **Integration key** and **Integration secret** into a text editor, as you will need them in the section ‘xxxxx’.
236 236  
237 -[[image:add-integration-connection-advanced-settings.png||height="510" width="500"]]
238 -
239 -
240 -Click on the **Check connection** button to verify the MQTT connection using the provided parameters.
241 -
242 -
243 -
244 -[[image:check-connection.png||height="83" width="300"]]
245 -
246 -
247 -If the connection is successful, you will see the **Connected** message.
248 -
249 -
250 -[[image:connection-success.png||height="511" width="500"]]
251 -
252 -
253 253  Click on the **Add** button.
254 254  
255 255  
295 +[[image:add-integration-connection.png||height="511" width="500"]]
256 256  
257 -You should see that the newly added integration is listed on the **Integrations** page.
258 258  
259 -Since we haven't received data from a device yet, the integration **Status** is shown as **Pending.**
260 260  
261 -[[image:integrations-list-added-pending.png]]
299 += Verifying the receipt of data from the device =
262 262  
301 +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.
263 263  
264 -= 5. Verifying the receipt of data from the device =
265 265  
266 -
267 -On the terminal, issue the following MQTT command which simulates the device S31B-NB.
268 -
269 -{{code language="none"}}
270 -mosquitto_pub -d -q 1 -h mqtt.eu.thingsboard.cloud -p 1883 -t v1/devices/S31B-NB/telemetry -u "24vk3w9h7sqdld1me5eh" -m "{temperature:20}"
271 -{{/code}}
272 -
273 -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.
304 +
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 -294.1 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