Version 3.1 by Alec Chen on 2025/04/02 16:29
Hide last authors
Alec Chen 2.1 1 **Table of Contents:**
2
Alec Chen 1.1 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
Alec Chen 2.2 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..
Alec Chen 1.1 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
Alec Chen 2.2 18 = 3.General MQTT Connection =
Alec Chen 1.1 19
Alec Chen 2.2 20 The NB-IoT Sensor can send packet to server use MQTT protocol.
Alec Chen 1.1 21
Alec Chen 2.2 22 Below are the commands.
Alec Chen 1.1 23
Alec Chen 2.2 24 **AT Commands:**
Alec Chen 1.1 25
Alec Chen 2.2 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}}
Alec Chen 1.1 35
Alec Chen 2.2 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"]]
Alec Chen 1.1 37
Alec Chen 2.2 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"]]
Alec Chen 1.1 39
Alec Chen 2.2 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**##
Alec Chen 1.1 41
Alec Chen 2.2 42 (% class="text-uppercase small mark" %)##**period to a suitable interval.**##
Alec Chen 1.1 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
Alec Chen 2.2 54 [[image:1743578461281-635.png]]
Alec Chen 1.1 55
Alec Chen 2.2 56
57
58
Alec Chen 1.1 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
Alec Chen 2.2 142 == 5.1. Creat new MQTT integration ==
143
Alec Chen 1.1 144 In the left navigation, click **Integrations center**, and then click **Integrations**.
145
146 On the **Integrations** page, click on the '**+**' button.
147
Alec Chen 2.2 148 [[image:1743578691561-822.png]]
149
150
Alec Chen 1.1 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
Alec Chen 2.2 158 * **Name**: MQTT integration
Alec Chen 1.1 159 * **Enable integration**: YES
Alec Chen 2.2 160 * **Debug mode**：YES
Alec Chen 1.1 161 * **Allows create devices or assets**: YES
162
163 Click **Next** button.
164
Alec Chen 2.2 165 [[image:1743578960106-916.png||height="549" width="547"]]
Alec Chen 1.1 166
167
Alec Chen 2.2 168 **Uplink/downlink  data converter:**
Alec Chen 1.1 169
Alec Chen 2.2 170 * (((
171 Next, directly select to create a new Uplink data converter .
172 )))
173
Alec Chen 1.1 174 Click **Next** button.
175
Alec Chen 2.2 176 [[image:1743581191958-140.png||height="547" width="543"]]
Alec Chen 1.1 177
Alec Chen 2.2 178
179
Alec Chen 1.1 180 **Downlink data converter:**
181
Alec Chen 2.2 182 * Next, directly select to create a new Uplink data converter .
Alec Chen 1.1 183
184 Click **Skip** button.
185
Alec Chen 2.2 186 [[image:1743581287837-189.png||height="547" width="542"]]
Alec Chen 1.1 187
Alec Chen 2.2 188
Alec Chen 1.1 189 **Connection:**
190
Alec Chen 2.2 191 * **Host**: [[lns1.thingseye.io>>url:http://lns1.thingseye.io/]]
Alec Chen 1.1 192 * **Port**: 8883
Alec Chen 2.2 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
Alec Chen 1.1 195 * **Enable SSL**: YES
Alec Chen 2.2 196 * **Topic: ** **It needs to align with the device's topic.**
197 * **QoS:** 0-At most once or an MQTT QoS level
Alec Chen 1.1 198
Alec Chen 2.2 199 Click **Skip** button.
Alec Chen 1.1 200
Alec Chen 2.2 201 [[image:1743579352961-586.png||height="507" width="502"]]
Alec Chen 1.1 202
Alec Chen 2.2 203 [[image:1743580606618-281.png||height="495" width="504"]]
Alec Chen 1.1 204
205
Alec Chen 2.2 206 Click on the **Add** button.
Alec Chen 1.1 207
Alec Chen 2.2 208 You should see that the newly added integration is listed on the **Integrations** page.
Alec Chen 1.1 209
Alec Chen 2.2 210 Since we haven't received data from a device yet, the integration **Status** is shown as **Pending,  Active  instead if it have.**
Alec Chen 1.1 211
212
213
214
215
Alec Chen 2.2 216 == 5.2. Setup uplink and downlink converters ==
Alec Chen 1.1 217
Alec Chen 2.2 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]].
Alec Chen 1.1 219
Alec Chen 2.2 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
Alec Chen 1.1 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"]]