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