Version 5.1 by Alec Chen on 2025/04/02 16:33
Hide last authors
Alec Chen 2.1 1 **Table of Contents:**
2
Alec Chen 4.1 3 {{toc/}}
4
Alec Chen 1.1 5 = 1. Introduction =
6
7 This document guides you on integrating Dragino **-NB** and **-CB** series devices data with Thingseye.
8
9 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**.
10
11 = 2. Prerequisites =
12
13 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.
14
Alec Chen 2.2 15 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 16
17 [[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"]]
18
19
Alec Chen 2.2 20 = 3.General MQTT Connection =
Alec Chen 1.1 21
Alec Chen 2.2 22 The NB-IoT Sensor can send packet to server use MQTT protocol.
Alec Chen 1.1 23
Alec Chen 2.2 24 Below are the commands.
Alec Chen 1.1 25
Alec Chen 2.2 26 **AT Commands:**
Alec Chen 1.1 27
Alec Chen 2.2 28 {{code language="none"}}
29 AT+PRO=3,0                           //  Set to use MQTT protocol to uplink, Payload Type select Hex payload.
30 AT+SERVADDR=120.24.4.116,1883        //  Set MQTT server address and port
31 AT+CLIENT=CLIENT                     //  Set up the CLIENT of MQTT
32 AT+UNAME=UNAME                       //  Set the username of MQTT
33 AT+PWD=PWD                           //  Set the password of MQTT
34 AT+PUBTOPIC=NSE01_PUB                //  Set the sending topic of MQTT
35 AT+SUBTOPIC=NSE01_SUB                //  Set the subscription topic of MQTT
36 {{/code}}
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-4.png?rev=1.1||alt="image-20230802112413-4.png"]]
Alec Chen 1.1 39
Alec Chen 2.2 40 [[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 41
Alec Chen 4.1 42 (% class="mark small text-uppercase" %)##**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 43
Alec Chen 4.1 44 (% class="mark small text-uppercase" %)##**period to a suitable interval.**##
Alec Chen 1.1 45
46 = 4. Data Converters =
47
48 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.
49
50 == 4.1 Uplink ==
51
52 In the left navigation, click **Integrations center**, and then click **Data converters**.
53
54 On the **Data converters** page, click on the ‘**+**’ button, and then click on the **Create new converter** from the dropdown menu.
55
Alec Chen 2.2 56 [[image:1743578461281-635.png]]
Alec Chen 1.1 57
Alec Chen 2.2 58
59
60
Alec Chen 1.1 61 The **Add data converter** window will appear.
62
63 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**.
64
65 Click on the **TBEL** button if it has not been selected by default.
66
67 Modify the default TBEL function to match with your device as described below:
68
69 * Uncomment** line 11**:
70
71 //var data = decodeToJson(payload)//
72
73 * **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.
74 * From **line 38**: Modify the telemetry section to allow parsed data to be assigned to the fields.
75
76 //telemetry: {
77 temperature: data.temperature,
78 humidity: data.humidity,
79 rawData: payloadStr
80 }//
81
82 The modified uplink decoder function to match with **Device A** is shown below.
83
84 {{code language="nono"}}
85 // Decode an uplink message from a buffer
86 // payload - array of bytes
87 // metadata - key/value object
88
89 /** Decoder **/
90
91 // decode payload to string
92 var payloadStr = decodeToString(payload);
93
94 // decode payload to JSON
95 var data = decodeToJson(payload);
96
97 var deviceName = 'Device A';
98 var deviceType = 'thermostat';
99 var customerName = 'Customer C';
100 var groupName = 'thermostat devices';
101 var manufacturer = 'Example corporation';
102 // use assetName and assetType instead of deviceName and deviceType
103 // to automatically create assets instead of devices.
104 // var assetName = 'Asset A';
105 // var assetType = 'building';
106
107 // Result object with device/asset attributes/telemetry data
108 var result = {
109 // Use deviceName and deviceType or assetName and assetType, but not both.
110   deviceName: deviceName,
111    deviceType: deviceType,
112 // assetName: assetName,
113 // assetType: assetType,
114 // customerName: customerName,
115   groupName: groupName,
116    attributes: {
117        model: 'Model A',
118        serialNumber: 'SN111',
119        integrationName: metadata['integrationName'],
120        manufacturer: manufacturer
121    },
122    telemetry: {
123        temperature: data.temperature,
124        humidity: data.humidity,
125        rawData: payloadStr
126    }
127 };
128
129 /** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/
130
131 return result;
132 {{/code}}
133
134 Once you modify the decoder function, click on the **Add** button.
135
136 [[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"]]
137
138 You should see that the newly added **MQTT Uplink converter **NB/CB is listed on the **Data Converters** page.
139
140 [[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"]]
141
142 = 5. Add Integration =
143
Alec Chen 2.2 144 == 5.1. Creat new MQTT integration ==
145
Alec Chen 1.1 146 In the left navigation, click **Integrations center**, and then click **Integrations**.
147
148 On the **Integrations** page, click on the '**+**' button.
149
Alec Chen 2.2 150 [[image:1743578691561-822.png]]
151
152
Alec Chen 1.1 153 The **Add integration** window appears.
154
155 In the **Add integration** window, configure the following settings:
156
157 **Basic settings:**
158
159 * **Integration type**: MQTT
Alec Chen 2.2 160 * **Name**: MQTT integration
Alec Chen 1.1 161 * **Enable integration**: YES
Alec Chen 2.2 162 * **Debug mode**：YES
Alec Chen 1.1 163 * **Allows create devices or assets**: YES
164
165 Click **Next** button.
166
Alec Chen 2.2 167 [[image:1743578960106-916.png||height="549" width="547"]]
Alec Chen 1.1 168
169
Alec Chen 2.2 170 **Uplink/downlink  data converter:**
Alec Chen 1.1 171
Alec Chen 2.2 172 * (((
173 Next, directly select to create a new Uplink data converter .
174 )))
175
Alec Chen 1.1 176 Click **Next** button.
177
Alec Chen 2.2 178 [[image:1743581191958-140.png||height="547" width="543"]]
Alec Chen 1.1 179
Alec Chen 2.2 180
181
Alec Chen 1.1 182 **Downlink data converter:**
183
Alec Chen 2.2 184 * Next, directly select to create a new Uplink data converter .
Alec Chen 1.1 185
186 Click **Skip** button.
187
Alec Chen 2.2 188 [[image:1743581287837-189.png||height="547" width="542"]]
Alec Chen 1.1 189
Alec Chen 2.2 190
Alec Chen 1.1 191 **Connection:**
192
Alec Chen 2.2 193 * **Host**: [[lns1.thingseye.io>>url:http://lns1.thingseye.io/]]
Alec Chen 1.1 194 * **Port**: 8883
Alec Chen 2.2 195 * **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.
196 * **Password:** Password or nothng
Alec Chen 1.1 197 * **Enable SSL**: YES
Alec Chen 2.2 198 * **Topic: ** **It needs to align with the device's topic.**
199 * **QoS:** 0-At most once or an MQTT QoS level
Alec Chen 1.1 200
Alec Chen 2.2 201 Click **Skip** button.
Alec Chen 1.1 202
Alec Chen 2.2 203 [[image:1743579352961-586.png||height="507" width="502"]]
Alec Chen 1.1 204
Alec Chen 2.2 205 [[image:1743580606618-281.png||height="495" width="504"]]
Alec Chen 1.1 206
207
Alec Chen 2.2 208 Click on the **Add** button.
Alec Chen 1.1 209
Alec Chen 2.2 210 You should see that the newly added integration is listed on the **Integrations** page.
Alec Chen 1.1 211
Alec Chen 2.2 212 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 213
214
215
216
217
Alec Chen 2.2 218 == 5.2. Setup uplink and downlink converters ==
Alec Chen 1.1 219
Alec Chen 2.2 220 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 221
Alec Chen 2.2 222 * **Uplink Converter**
223
224 The purpose of the decoder function is to parse the incoming data and metadata to a format that ThingsBoard can consume.
225
226 Go to the **Integrations center** -> **Data converters** page, and find that MQTT uplink converter that was newly created when the integration was created.
227
228 [[image:1743581830822-223.png]]
229
230
231 Enter edit mode and apply **MQTT uplink JS code** to this uplink converter.
232
233 [[image:1743581965585-763.png]]
234
235
236 * **Downlink Converter**
237
238 Go to the **Integrations center** -> **Data converters** page, and find that MQTT downlink converter that was newly created when the integration was created.
239
240
241 Enter edit mode and apply **MQTT downlink JS code** to this downlink converter.
242
243 [[image:1743582084494-111.png]]
244
245
Alec Chen 4.1 246 = 6. Configure Physical NB-IoT Sensor =
Alec Chen 2.2 247
Alec Chen 1.1 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"]]