Version 3.1 by Alec Chen on 2025/04/02 16:29
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
244
245
246 = 8. Configure Physical NB-IoT Sensor =
247
248 Now, let's experiment with sending data to Thingseye using a real NB-IoT device. For example, we will use the **TS01-NB**.
249
250 First, configure the NB-IoT device with the necessary MQTT settings using AT commands. Below is a list of AT commands you can use.
251
252 **AT Commands**
253
254 * **AT+PRO=3,3    **~/~/ Use MQTT to connect to Thingseye. Payload Type set to 3.
255 * **AT+SUBTOPIC=<MQTT subscribe topic> Eg: TS01-NB**
256 * **AT+PUBTOPIC=<MQTT publish topic> Eg: TS01-NB**
257 * **AT+CLIENT=null**
258 * **AT+UNAME=<MQTT Username>**
259 * **AT+PWD=<MQTT Password>**
260 * **AT+SERVADDR=<Broker address, Port>**
261
262 Test your uplink by pressing the ACT button for 1 second.
263
264
265 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.
266
267 [[image:https://wiki.dragino.com/xwiki/bin/download/Main/ThingsBoard/image-4.png?rev=1.2||alt="image-4.png"]]