Version 2.2 by Alec Chen on 2025/04/02 16:28
Show last authors
1 **Table of Contents:**
2
3 = 1. Introduction =
4
5 This document guides you on integrating Dragino **-NB** and **-CB** series devices data with Thingseye.
6
7 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**.
8
9 = 2. Prerequisites =
10
11 To complete this tutorial, you need to have certificate files. [[lns1.thingseye.io>>url: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.
12
13 If customers need to use this MQTT connection with Thingseye, they need to contact TE team to obtain three license files or click this [[link>>url:https://www.dropbox.com/scl/fo/d5s1wf36f4syv30a8laup/AK8FjVpNXYXCWodRnnQ1Hig?rlkey=jrz1ip0f0xwwq5z2m2gu1tuij&e=1&st=kl4caub0&dl=0]] to download the certificates..
14
15 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/ins1.png?width=500&height=310&rev=1.1||alt="ins1.png" height="310" width="500"]]
16
17
18 = 3.General MQTT Connection =
19
20 The NB-IoT Sensor can send packet to server use MQTT protocol.
21
22 Below are the commands.
23
24 **AT Commands:**
25
26 {{code language="none"}}
27 AT+PRO=3,0                           //  Set to use MQTT protocol to uplink, Payload Type select Hex payload.
28 AT+SERVADDR=120.24.4.116,1883        //  Set MQTT server address and port
29 AT+CLIENT=CLIENT                     //  Set up the CLIENT of MQTT
30 AT+UNAME=UNAME                       //  Set the username of MQTT
31 AT+PWD=PWD                           //  Set the password of MQTT
32 AT+PUBTOPIC=NSE01_PUB                //  Set the sending topic of MQTT
33 AT+SUBTOPIC=NSE01_SUB                //  Set the subscription topic of MQTT
34 {{/code}}
35
36 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/General%20Configure%20to%20Connect%20to%20IoT%20server%20for%20-NB%20%26%20-NS%20NB-IoT%20models/WebHome/image-20230802112413-4.png?rev=1.1||alt="image-20230802112413-4.png"]]
37
38 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/General%20Configure%20to%20Connect%20to%20IoT%20server%20for%20-NB%20%26%20-NS%20NB-IoT%20models/WebHome/image-20230802112413-5.png?width=987&height=530&rev=1.1||alt="image-20230802112413-5.png" height="530" width="987"]]
39
40 (% class="text-uppercase small mark" %)##**Notice: MQTT protocol has a much higher power consumption compare with UDP/CoAP protocol. Please check the power analyze document and adjust the uplink**##
41
42 (% class="text-uppercase small mark" %)##**period to a suitable interval.**##
43
44 = 4. Data Converters =
45
46 In **Thingseye**, **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 Thingseye can understand, or vice versa.
47
48 == 4.1 Uplink ==
49
50 In the left navigation, click **Integrations center**, and then click **Data converters**.
51
52 On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu.
53
54 [[image:1743578461281-635.png]]
55
56
57
58
59 The **Add data converter** window will appear.
60
61 Let's create an uplink data converter for the device named '**Device A**'. Name it ‘**MQTT Uplink Converter - Device A**’ and select the Type as **Uplink**.
62
63 Click on the **TBEL** button if it has not been selected by default.
64
65 Modify the default TBEL function to match with your device as described below:
66
67 * Uncomment** line 11**:
68
69 //var data = decodeToJson(payload)//
70
71 * **Line 13**: Assign your device name to the **deviceName** field. - We used **Device A** as it is to match with our device, **Device A **in the Devices section.
72 * From **line 38**: Modify the telemetry section to allow parsed data to be assigned to the fields.
73
74 //telemetry: {
75 temperature: data.temperature,
76 humidity: data.humidity,
77 rawData: payloadStr
78 }//
79
80 The modified uplink decoder function to match with **Device A** is shown below.
81
82 {{code language="nono"}}
83 // Decode an uplink message from a buffer
84 // payload - array of bytes
85 // metadata - key/value object
86
87 /** Decoder **/
88
89 // decode payload to string
90 var payloadStr = decodeToString(payload);
91
92 // decode payload to JSON
93 var data = decodeToJson(payload);
94
95 var deviceName = 'Device A';
96 var deviceType = 'thermostat';
97 var customerName = 'Customer C';
98 var groupName = 'thermostat devices';
99 var manufacturer = 'Example corporation';
100 // use assetName and assetType instead of deviceName and deviceType
101 // to automatically create assets instead of devices.
102 // var assetName = 'Asset A';
103 // var assetType = 'building';
104
105 // Result object with device/asset attributes/telemetry data
106 var result = {
107 // Use deviceName and deviceType or assetName and assetType, but not both.
108   deviceName: deviceName,
109    deviceType: deviceType,
110 // assetName: assetName,
111 // assetType: assetType,
112 // customerName: customerName,
113   groupName: groupName,
114    attributes: {
115        model: 'Model A',
116        serialNumber: 'SN111',
117        integrationName: metadata['integrationName'],
118        manufacturer: manufacturer
119    },
120    telemetry: {
121        temperature: data.temperature,
122        humidity: data.humidity,
123        rawData: payloadStr
124    }
125 };
126
127 /** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/
128
129 return result;
130 {{/code}}
131
132 Once you modify the decoder function, click on the **Add** button.
133
134 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/ul-data-converter-device-a.png?width=500&height=524&rev=1.1||alt="ul-data-converter-device-a.png"]]
135
136 You should see that the newly added **MQTT Uplink converter **NB/CB is listed on the **Data Converters** page.
137
138 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/ul-data-converter-added.png?height=257&rev=1.1||alt="ul-data-converter-added.png"]]
139
140 = 5. Add Integration =
141
142 == 5.1. Creat new MQTT integration ==
143
144 In the left navigation, click **Integrations center**, and then click **Integrations**.
145
146 On the **Integrations** page, click on the '**+**' button.
147
148 [[image:1743578691561-822.png]]
149
150
151 The **Add integration** window appears.
152
153 In the **Add integration** window, configure the following settings:
154
155 **Basic settings:**
156
157 * **Integration type**: MQTT
158 * **Name**: MQTT integration
159 * **Enable integration**: YES
160 * **Debug mode**：YES
161 * **Allows create devices or assets**: YES
162
163 Click **Next** button.
164
165 [[image:1743578960106-916.png||height="549" width="547"]]
166
167
168 **Uplink/downlink  data converter:**
169
170 * (((
171 Next, directly select to create a new Uplink data converter .
172 )))
173
174 Click **Next** button.
175
176 [[image:1743581191958-140.png||height="547" width="543"]]
177
178
179
180 **Downlink data converter:**
181
182 * Next, directly select to create a new Uplink data converter .
183
184 Click **Skip** button.
185
186 [[image:1743581287837-189.png||height="547" width="542"]]
187
188
189 **Connection:**
190
191 * **Host**: [[lns1.thingseye.io>>url:http://lns1.thingseye.io/]]
192 * **Port**: 8883
193 * **Credentials **: PEM(Paste 3 certificates to boxs below)Click this [[link>>url:https://www.dropbox.com/scl/fo/d5s1wf36f4syv30a8laup/AK8FjVpNXYXCWodRnnQ1Hig?rlkey=jrz1ip0f0xwwq5z2m2gu1tuij&e=1&st=kl4caub0&dl=0]] to download the certificates.
194 * **Password:** Password or nothng
195 * **Enable SSL**: YES
196 * **Topic: ** **It needs to align with the device's topic.**
197 * **QoS:** 0-At most once or an MQTT QoS level
198
199 Click **Skip** button.
200
201 [[image:1743579352961-586.png||height="507" width="502"]]
202
203 [[image:1743580606618-281.png||height="495" width="504"]]
204
205
206 Click on the **Add** button.
207
208 You should see that the newly added integration is listed on the **Integrations** page.
209
210 Since we haven't received data from a device yet, the integration **Status** is shown as **Pending,  Active  instead if it have.**
211
212
213
214
215
216 == 5.2. Setup uplink and downlink converters ==
217
218 First, you need to download the [[**MQTT uplink/downlink JS** **code**>>url:https://www.dropbox.com/scl/fo/d5s1wf36f4syv30a8laup/AK8FjVpNXYXCWodRnnQ1Hig?rlkey=jrz1ip0f0xwwq5z2m2gu1tuij&e=1&st=kl4caub0&dl=0]].
219
220 * **Uplink Converter**
221
222 The purpose of the decoder function is to parse the incoming data and metadata to a format that ThingsBoard can consume.
223
224 Go to the **Integrations center** -> **Data converters** page, and find that MQTT uplink converter that was newly created when the integration was created.
225
226 [[image:1743581830822-223.png]]
227
228
229 Enter edit mode and apply **MQTT uplink JS code** to this uplink converter.
230
231 [[image:1743581965585-763.png]]
232
233
234 * **Downlink Converter**
235
236 Go to the **Integrations center** -> **Data converters** page, and find that MQTT downlink converter that was newly created when the integration was created.
237
238
239 Enter edit mode and apply **MQTT downlink JS code** to this downlink converter.
240
241 [[image:1743582084494-111.png]]
242
243 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/General%20Configure%20to%20Connect%20to%20IoT%20server%20for%20-NB%20%26%20-NS%20NB-IoT%20models/WebHome/image-20241126190737-17.png?width=1114&height=527&rev=1.1||alt="image-20241126190737-17.png" height="527" width="1114"]]
244
245
246
247 == ==
248
249 == 6. Verifying the receipt of data from virtual devices ==
250
251 == 6.1 How does it work? ==
252
253 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.
254
255 The Mosquitto client publishes messages (payloads) on the topic **/device/a**. Of course, you can use any topic for testing.
256
257 The MQTT payload format is as follows:
258
259 {{code language="none"}}
260 {"IMEI": "350693903995577", "temperature":25, "humidity":80, "pressure":1005}
261 {{/code}}
262
263 Once Thingseye receives this message, it forwards this payload to the matching device through the integration.
264
265 == 5.2 Sending messages ==
266
267 On your computer's terminal, issue the following MQTT command which simulates the device '**Device A'**. The message payload contains the fields IMEI, temperature, humidity, and pressure, which hold the values 350693903995577, 30, 80, and 1005 respectively. This payload is also (technically) known as telemetry.
268
269 {{code language="none"}}
270 mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -u "xxxxx" -P "xxxxx" -t "device/a" -m '{"IMEI":"350693903995577", "temperature":30, "humidity":80, "pressure":1005}'
271 {{/code}}
272
273 If the integration was performed without errors, the status of the integration changes to 'Active' after the first telemetry transmission.
274
275 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/integration-active.png?rev=1.2||alt="integration-active.png"]]
276
277 == 6.3 Viewing messages ==
278
279 Go back to the **Integrations** page.
280
281 Click on the **MQTT integration NB/CB** in the **Integrations** page to see its details.
282
283 Click on the **Edit** button (//**pen icon**//).
284
285 Click on the **Disabled** button in the upper-right corner.
286
287 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.
288
289 Click on the **Apply** button.
290
291 Then click on the **Apply changes** (//**tick icon**//) button.
292
293 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/debug-enabled.png?width=700&height=301&rev=1.1||alt="debug-enabled.png"]]
294
295 Now go to the **Events** tab.
296
297 Select the **Event type** as **Debug** from the dropdown list.
298
299 Publish another message (of course, you can repeat the previous message by pressing the UP arrow on your keyboard and then press Enter key) to your MQTT broker from your terminal, for example:
300
301 mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -u "xxxxx" -P "xxxxx" -t "device/a" -m '{"IMEI":"350693903995577", "temperature":30, "humidity":80, "pressure":1005}'
302
303 Now you can see that uplink message in the **Events** tab (Click the **refresh** button if you didn't see any messages in the Events tab). The status should be **OK **if there is no errors in your integration.
304
305 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/Screenshot%202025-03-26%20at%2019.49.31.png?rev=1.1||alt="Screenshot 2025-03-26 at 19.49.31.png"]]
306
307 Then click on the **three dots (...)** in the **Message** column. You can see the uplink message's **payload** in the **Message** window.
308
309 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/Screenshot%202025-03-26%20at%2019.47.52.png?rev=1.1||alt="Screenshot 2025-03-26 at 19.47.52.png"]]
310
311 Now, you have successfully tested your integration with a simulated uplink payload and verified that it is received by Thingseye, and the device is provisioned.
312
313 = 7. Creating a Dashboard =
314
315 Thingseye **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.
316
317 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 Thingseye to display data according to your requirements.
318
319 First simulate a few messages using MQTT. This time, we have added the 'humidity' field to the payload. Eg:
320
321 {{code language="none"}}
322 mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -u "xxxxx" -P "xxxxx" -t "device/a" -m '{"IMEI":"350693903995577", "temperature":22, "humidity":80, "pressure":1005}'
323
324 {{/code}}
325
326 In **Thingseye**, from the left navigation menu, click **Dashboards**. Then, click the **+** button and select **Create new dashboard** from the dropdown menu.
327
328 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/dashboard-1.png?rev=1.1||alt="dashboard-1.png"]]
329
330 In the **Title** text box, enter **NB/CB Test Dashboard** as the title of the dashboard.
331
332 Click on the **Add** button.
333
334 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/dashboard-2.png?width=500&height=526&rev=1.1||alt="dashboard-2.png"]]
335
336 Click on the **Add widget / Add new widget** button.
337
338 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/dashboard-3.png?rev=1.1||alt="dashboard-3.png"]]
339
340 In the **Select widgets bundle** window, click **Charts**.
341
342 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/dashboard-4.png?width=700&height=537&rev=1.1||alt="dashboard-4.png"]]
343
344 In the **Charts: select widget** window, click **Time series chart**.
345
346 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/dashboard-5.png?width=700&height=525&rev=1.1||alt="dashboard-5.png"]]
347
348 Configure the **Time series chart** widget as follows:
349
350 * **Datasource** - select **Device A** device you provisioned.
351 * **Series**:
352 ** **temperature** - you can see this key by default.
353 ** **humidity** - Click **Add series** button. Then add the **humidity** for the key and then type **%** as its unit.
354 * Click on the **Add** button.
355
356 (% class="box infomessage" %)
357 (((
358 You can add only the relevant fields from the device's payload to display data on a widget. These fields are called 'keys'.
359 )))
360
361 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/Screenshot%202025-03-31%20at%2006.51.15.png?width=700&height=485&rev=1.1||alt="Screenshot 2025-03-31 at 06.51.15.png"]]
362
363 The time-series chart will appear in edit mode. Resize it by clicking and dragging the lower-right corner.
364
365 Click the **Save** button to add the widget to the dashboard.
366
367 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/timeseries-3.png?width=700&height=347&rev=1.1||alt="timeseries-3.png"]]
368
369 Now send the following MQTT messages from the terminal to simulate the data.
370
371 {{code language="none"}}
372 mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -u "xxxxx" -P "xxxxx" -t "device/a" -m '{"IMEI":"350693903995577", "temperature":22, "humidity":70, "pressure":1005}'
373
374 mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -u "xxxxx" -P "xxxxx" -t "device/a" -m '{"IMEI":"350693903995577", "temperature":27, "humidity":72, "pressure":1005}'
375
376 mosquitto_pub -d -q 1 -h 011731f7928xxxxx.s1.eu.hivemq.cloud -p 8883 -u "xxxxx" -P "xxxxx" -t "device/a" -m '{"IMEI":"350693903995577", "temperature":19, "humidity":80, "pressure":1005}'
377 {{/code}}
378
379 The chart will update with the values in realtime, as shown in the below image.
380
381 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/timeseries-4.png?width=700&height=316&rev=1.1||alt="timeseries-4.png"]]
382
383 = 8. Configure Physical NB-IoT Sensor =
384
385 Now, let's experiment with sending data to Thingseye using a real NB-IoT device. For example, we will use the **TS01-NB**.
386
387 First, configure the NB-IoT device with the necessary MQTT settings using AT commands. Below is a list of AT commands you can use.
388
389 **AT Commands**
390
391 * **AT+PRO=3,3    **~/~/ Use MQTT to connect to Thingseye. Payload Type set to 3.
392 * **AT+SUBTOPIC=<MQTT subscribe topic> Eg: TS01-NB**
393 * **AT+PUBTOPIC=<MQTT publish topic> Eg: TS01-NB**
394 * **AT+CLIENT=null**
395 * **AT+UNAME=<MQTT Username>**
396 * **AT+PWD=<MQTT Password>**
397 * **AT+SERVADDR=<Broker address, Port>**
398
399 Test your uplink by pressing the ACT button for 1 second.
400
401
402 The following image shows the uplink payload of a real Dragino device. The publish topic is '**TS01-NB' that contains fields in the payload, IMEI, IMSI, Model, temperature, etc**. Note that we have created a device named **TS01-NB** in the **Devices** section in advance.
403
404 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/image-4.png?rev=1.2||alt="image-4.png"]]