Wiki source code of NDS01 - NB-IoT Door Sensor User Manual
Show last authors
author | version | line-number | content |
---|---|---|---|
1 | (% style="text-align:center" %) | ||
2 | [[image:image-20221112113258-1.jpeg]] | ||
3 | |||
4 | |||
5 | |||
6 | |||
7 | |||
8 | |||
9 | |||
10 | |||
11 | |||
12 | |||
13 | |||
14 | = 1. Introduction = | ||
15 | |||
16 | == 1.1 What is NDS01 NB-IoT Door Sensor == | ||
17 | |||
18 | |||
19 | The Dragino NDS01 is a NB-IOT Door Sensor for Internet of Things solution. It is used to detect the open/close event for door and uplink the event to IoT server via NB-IoT network. | ||
20 | |||
21 | Besides open/close event, NDS01 also has an internal temperature and humidity sensor which can detect the temperature and humidity inside the sensor. | ||
22 | |||
23 | **NarrowBand-Internet of Things (NB-IoT)** is a standards-based low power wide area (LPWA) technology developed to enable a wide range of new IoT devices and services. NB-IoT significantly improves the power consumption of user devices, system capacity and spectrum efficiency, especially in deep coverage. | ||
24 | |||
25 | NDS01 is powered by 2 x AAA batteries for long term use. | ||
26 | |||
27 | *The measured temperature is 2~~3 degree higher than the actually environment temperature out of NDS01. | ||
28 | |||
29 | |||
30 | [[image:1668224602353-769.png]] | ||
31 | |||
32 | |||
33 | |||
34 | == 1.2 Specifications == | ||
35 | |||
36 | |||
37 | **Common DC Characteristics:** | ||
38 | |||
39 | * Supply Voltage: 2.1v ~~ 3.6v | ||
40 | * Operating Temperature: -10 ~~ 50°C | ||
41 | |||
42 | **NB-IoT Spec:** | ||
43 | |||
44 | * - B1 @H-FDD: 2100MHz | ||
45 | * - B3 @H-FDD: 1800MHz | ||
46 | * - B8 @H-FDD: 900MHz | ||
47 | * - B5 @H-FDD: 850MHz | ||
48 | * - B20 @H-FDD: 800MHz | ||
49 | * - B28 @H-FDD: 700MHz | ||
50 | |||
51 | **Power Consumption** | ||
52 | |||
53 | * IDEL Mode: 10uA @ 3.3v | ||
54 | * Max transmit power: <500mA@3.3v | ||
55 | |||
56 | | ||
57 | |||
58 | |||
59 | == 1.3 Features == | ||
60 | |||
61 | |||
62 | * NB-IoT Bands: B1/B3/B5/B8/B20/B28 @H-FDD | ||
63 | * Ultra low power consumption | ||
64 | * Door Open / Close Detect | ||
65 | * Device remove alarm | ||
66 | * Uplink Protocol: TCP or UDP | ||
67 | * Uplink on periodically | ||
68 | * Micro SIM card slot for NB-IoT SIM | ||
69 | * 2 x AAA LR03 Batteries | ||
70 | |||
71 | == 1.4 Applications == | ||
72 | |||
73 | |||
74 | * Smart Buildings & Home Automation | ||
75 | * Logistics and Supply Chain Management | ||
76 | * Smart Cities | ||
77 | * Smart Factory | ||
78 | |||
79 | = 2. Use NDS01 to communicate with IoT Server = | ||
80 | |||
81 | == 2.1 How it works == | ||
82 | |||
83 | |||
84 | The NDS01 is equipped with a NB-IoT module, the pre-loaded firmware in NDS01 will get environment data from sensors and send the value to local NB-IoT network via the NB-IoT module. The NB-IoT network will forward this value to IoT server via the protocol defined by NDS01. | ||
85 | |||
86 | The diagram below shows the working flow in default firmware of NDS01: | ||
87 | |||
88 | |||
89 | == 2.2 Configure the NDS01 == | ||
90 | |||
91 | === 2.2.1 Test Requirement === | ||
92 | |||
93 | |||
94 | To use NDS01 in your city, make sure meet below requirements: | ||
95 | |||
96 | * Your local operator has already distributed a NB-IoT Network there. | ||
97 | * The local NB-IoT network used the band that NDS01 supports. | ||
98 | * Your operator is able to distribute the data received in their NB-IoT network to your IoT server. | ||
99 | |||
100 | Below figure shows our testing structure. Here we have NB-IoT network coverage by China Mobile, the band they use is B8. The NDS01 will use UDP(120.24.4.116:5601) or TCP(120.24.4.116:5600)protocol to send data to IoT server. | ||
101 | |||
102 | |||
103 | [[image:1668224789474-811.png]] | ||
104 | |||
105 | |||
106 | === 2.2.1 Insert SIM card === | ||
107 | |||
108 | |||
109 | Insert the NB-IoT Card get from your provider. | ||
110 | |||
111 | User need to take out the NB-IoT module and insert the SIM card like below: | ||
112 | |||
113 | |||
114 | [[image:1668224846067-276.png]] | ||
115 | |||
116 | |||
117 | === 2.2.3 Configure NDS01 === | ||
118 | |||
119 | |||
120 | User need to configure NDS01 via serial port to set the **Server Address** / **Uplink Topic** to define where and how-to uplink packets. NDS01 support AT Commands, user can use a USB to TTL adapter to connect to NDS01 and use AT Commands to configure it, NDS01 needs to be in the wake-up state when using AT commands,as below. | ||
121 | |||
122 | |||
123 | [[image:1668224930349-417.png]] | ||
124 | |||
125 | |||
126 | (% style="color:blue" %)**Connection:** | ||
127 | |||
128 | **~ (% style="background-color:yellow" %)USB TTL GND <~-~-~-~-> GND(%%)** | ||
129 | |||
130 | **~ (% style="background-color:yellow" %)USB TTL TXD <~-~-~-~-> UART_RXD(%%)** | ||
131 | |||
132 | **~ (% style="background-color:yellow" %)USB TTL RXD <~-~-~-~-> UART_TXD(%%)** | ||
133 | |||
134 | |||
135 | In the PC, use below serial tool settings: | ||
136 | |||
137 | * Baud: (% style="color:green" %)**9600** | ||
138 | * Data bits:** (% style="color:green" %)8(%%)** | ||
139 | * Stop bits: (% style="color:green" %)**1** | ||
140 | * Parity: (% style="color:green" %)**None** | ||
141 | * Flow Control: (% style="color:green" %)**None** | ||
142 | |||
143 | After powering on the NDS01, the following information will be printed | ||
144 | |||
145 | [[image:1668225099789-919.png]] | ||
146 | |||
147 | |||
148 | (% style="color:blue" %)**AT command set** | ||
149 | |||
150 | (% style="color:#037691" %)**1. Set and query the communication protocol** | ||
151 | |||
152 | Send: AT+PRO=<val> Val: 0:TCP 1:UDP | ||
153 | |||
154 | Reply: OK | ||
155 | |||
156 | Send: AT+PRO? ~/~/ Inquire | ||
157 | |||
158 | Reply: +PRO:0 | ||
159 | |||
160 | OK | ||
161 | |||
162 | |||
163 | (% style="color:#037691" %)**2. Set and query the server address** | ||
164 | |||
165 | Send: AT+SERVADDR=<server>,<port> | ||
166 | |||
167 | Reply: OK | ||
168 | |||
169 | Send: AT+SERVADDR? ~/~/ Inquire | ||
170 | |||
171 | Reply: +SERVADDR:<server>,<port> | ||
172 | |||
173 | OK | ||
174 | |||
175 | |||
176 | (% style="color:#037691" %)**3. Set and query the TDC** | ||
177 | |||
178 | Send:AT+TDC=<value> ~/~/ Heartbeat time, in seconds, the default is 86400s,which is 24 hours | ||
179 | |||
180 | Reply: OK | ||
181 | |||
182 | Send: AT+TDC? ~/~/ Inquire | ||
183 | |||
184 | Reply: +TDC:<value> | ||
185 | |||
186 | OK | ||
187 | |||
188 | |||
189 | (% style="color:#037691" %)**4. Query parameters** | ||
190 | |||
191 | Send: AT+CFG? | ||
192 | |||
193 | Reply: +PRO:0 | ||
194 | |||
195 | +SERVADDR:120.27.12.119,2023 | ||
196 | |||
197 | +TDC:86400 | ||
198 | |||
199 | +CSQ:31 | ||
200 | |||
201 | +IMEI:868163049937383 | ||
202 | |||
203 | +ICCID:898604611619C0854626 | ||
204 | |||
205 | +IMSI:460048118204626 | ||
206 | |||
207 | OK | ||
208 | |||
209 | |||
210 | (% style="color:#037691" %)**5. Set and query the APN** | ||
211 | |||
212 | Send: AT+APN="<apn>" ~/~/ Set APN | ||
213 | |||
214 | **Reply:** OK | ||
215 | |||
216 | **Send:** AT+APN? ~/~/ Inquire | ||
217 | |||
218 | **Reply:** +APN:"cmiot" | ||
219 | |||
220 | OK | ||
221 | |||
222 | |||
223 | (% style="color:#037691" %)**6. Alarm and Silencer** | ||
224 | |||
225 | **Send: **AT+ALARM=<value> ~/~/ 0~~1,0: mute 1: buzzer alarm (note that no data will be reported, only the buzzer and the red light are on, if it is in silent mode, only the red light is on) | ||
226 | |||
227 | **Reply:** OK | ||
228 | |||
229 | |||
230 | |||
231 | |||
232 | === 2.2.4 Use UDP protocol to uplink data (Default protocol) === | ||
233 | |||
234 | * (% style="color:blue" %)**AT+PRO=1 **(%%) ~/~/ Set to use UDP protocol to uplink | ||
235 | * (% style="color:blue" %)**AT+SERVADDR=119.91.62.30,1999 ** (%%) ~/~/ to set UDP server address and port | ||
236 | |||
237 | [[image:file:///C:/Users/93456/AppData/Local/Temp/msohtmlclip1/01/clip_image006.png]] | ||
238 | |||
239 | |||
240 | |||
241 | === 2.2.5 Use TCP protocol to uplink data === | ||
242 | |||
243 | * (% style="color:blue" %)**AT+PRO=0 ** (%%) ~/~/ Set to use TCP protocol to uplink | ||
244 | * (% style="color:blue" %)**AT+SERVADDR=119.91.62.30,2002 **(%%) ~/~/ to set TCP server address and port | ||
245 | |||
246 | [[image:file:///C:/Users/93456/AppData/Local/Temp/msohtmlclip1/01/clip_image007.png]] | ||
247 | |||
248 | |||
249 | |||
250 | |||
251 | === 2.2.6 Change Update Interval === | ||
252 | |||
253 | User can use below command to change the (% style="color:blue" %)**uplink interval**. | ||
254 | |||
255 | (% style="color:blue" %)**AT+TDC=86400 ** (%%)~/~/ Set Update Interval to 86400s | ||
256 | |||
257 | |||
258 | (% style="color:red" %)**NOTE:** | ||
259 | |||
260 | 1. By default, the device will send an uplink message every 24 hour (86400s). | ||
261 | |||
262 | [[image:file:///C:/Users/93456/AppData/Local/Temp/msohtmlclip1/01/clip_image008.png]] | ||
263 | |||
264 | |||
265 | |||
266 | |||
267 | == 2.3 Uplink Payload == | ||
268 | |||
269 | registration package, uplink payload includes in total 61 bytes | ||
270 | |||
271 | |||
272 | |((( | ||
273 | **Size** | ||
274 | |||
275 | **(bytes)** | ||
276 | )))|**2**|**1**|**1**|**1**|**1**|**15**|**15**|**20**|**1**|**1**|**3** | ||
277 | |**Value**|head|Version|data type|Data length|device type|device ID|IMSI|ICCID|BAT|Signal|tail | ||
278 | |||
279 | The payload is ASCII string, representative same HEX: 0x4B5710013401383639393735303334343431303832343630313133313138373433373332 | ||
280 | |||
281 | 38393836313132303232343031343339383736321E15494F54 where: | ||
282 | |||
283 | * Head: 0x4B57(fixed) | ||
284 | * Version: 0x10=”V1.0” | ||
285 | * Data type: 0x01=1(1:register,2:data sending) | ||
286 | * Data length: 0x34=52(Valid data is 52 bytes) | ||
287 | |||
288 | * Device type: 0x01 = 1(Representative NDS01) | ||
289 | * Device ID:0x383639393735303334343431303832=869975034441082(ASCII) | ||
290 | * IMSI: 0x343630313133313138373433373332 = 460113118743732(ASCII) | ||
291 | * ICCID: 0x3839383631313230323234303134333938373632=89861120224014398762(ASCII) | ||
292 | * Bat: 0x1E = 30/10=3.0V | ||
293 | * Signal: 0x15=21 | ||
294 | |||
295 | **0** -113dBm or less | ||
296 | |||
297 | **1** -111dBm | ||
298 | |||
299 | **2...30** -109dBm... -53dBm | ||
300 | |||
301 | **31** -51dBm or greater | ||
302 | |||
303 | **99** Not known or not detectable | ||
304 | |||
305 | * Tail:0x494F54(fixed) | ||
306 | |||
307 | data upload, uplink payload includes in total 32 bytes | ||
308 | |||
309 | |((( | ||
310 | **Size** | ||
311 | |||
312 | **(bytes)** | ||
313 | )))|**2**|**1**|**1**|**1**|**1**|**15**|**1**|**1**|**1**|**1**|**1**|**1**|**1**|**1**|**3** | ||
314 | |**Value**|head|Version|data type|Data length|device type|device ID|event type|Door magnetic state|BAT|Signal|((( | ||
315 | Temp | ||
316 | |||
317 | integer | ||
318 | )))|((( | ||
319 | Temp | ||
320 | |||
321 | decimal | ||
322 | )))|((( | ||
323 | Hum | ||
324 | |||
325 | integer | ||
326 | )))|((( | ||
327 | Hum | ||
328 | |||
329 | decimal | ||
330 | )))|tail | ||
331 | |||
332 | The payload is ASCII string, representative same HEX: 0x4B5710021401383639393735303334343431303832010020151c552312494F54 where: | ||
333 | |||
334 | * Head: 0x4B57(fixed) | ||
335 | * Version: 0x10=”V1.0” | ||
336 | * Data type: 0x02=2(1:register,2:data sending) | ||
337 | * Data length: 0x14=20(Valid data is 20 bytes) | ||
338 | |||
339 | * Device type: 0x01 = 1(Representative NDS01) | ||
340 | * Device ID:0x383639393735303334343431303832=869975034441082(ASCII) | ||
341 | * Event type:0x01 | ||
342 | |||
343 | 01:TDC | ||
344 | |||
345 | 02:alarm | ||
346 | |||
347 | 03:remove alarm | ||
348 | |||
349 | 04:dismantling alarm | ||
350 | |||
351 | 05:remove demolition alarm | ||
352 | |||
353 | 06:low voltage | ||
354 | |||
355 | 07:remove low voltage | ||
356 | |||
357 | * Door magnetic state: 0x00 | ||
358 | |||
359 | 00:Door sensor is close | ||
360 | |||
361 | 01:Door sensor is open | ||
362 | |||
363 | * Bat: 0x20 = 32/10=3.2V | ||
364 | * Signal: 0x15=21 | ||
365 | |||
366 | **0** -113dBm or less | ||
367 | |||
368 | **1** -111dBm | ||
369 | |||
370 | **2...30** -109dBm... -53dBm | ||
371 | |||
372 | **31** -51dBm or greater | ||
373 | |||
374 | **99** Not known or not detectable | ||
375 | |||
376 | * Temp integer:0x1c=28 | ||
377 | * Temp decimal:0x55=85 | ||
378 | |||
379 | Temp =Temp integer+(Temp decimal)/100=28+85/100=28.85℃ | ||
380 | |||
381 | * Hum integer:0x23=35 | ||
382 | * Hum decimal:0x12=18 | ||
383 | |||
384 | Hum =Hum integer+(Hum decimal)/100=35+18/100=35.18**%rh** | ||
385 | |||
386 | * Tail:0x494F54(fixed) | ||
387 | |||
388 | == 2.4 Node-Red Example == | ||
389 | |||
390 | Please refer to this link for the use of Node-RED: | ||
391 | |||
392 | [[http:~~/~~/8.211.40.43:8080/xwiki/bin/view/Main/Node-RED/>>url:http://8.211.40.43:8080/xwiki/bin/view/Main/Node-RED/]] | ||
393 | |||
394 | Please visit this link to download the Node-RED process: | ||
395 | |||
396 | [[https:~~/~~/github.com/dragino/dragino-end-node-decoder/tree/main/Node-RED>>url:https://github.com/dragino/dragino-end-node-decoder/tree/main/Node-RED]] | ||
397 | |||
398 | [[image:file:///C:/Users/93456/AppData/Local/Temp/msohtmlclip1/01/clip_image009.png]] | ||
399 | |||
400 | |||
401 | |||
402 | |||
403 | == 2.5 Buttons and LED and Mode == | ||
404 | |||
405 | Operating mode | ||
406 | |||
407 | (1) In the self-check mode (the default is the self-check mode when power on for the first time), the state change of the tamper switch does not trigger an alarm; | ||
408 | |||
409 | (2) In normal working mode, the state change of the tamper switch triggers an alarm; | ||
410 | |||
411 | (3) In silent mode (the default is non-silent mode when power on for the first time), the buzzer is silent. | ||
412 | |||
413 | |||
414 | led lights | ||
415 | |||
416 | (1) After the device is powered on, the green light flashes once; | ||
417 | |||
418 | (2) The device does not set server parameters or cannot connect to the server, and the green light flashes quickly; | ||
419 | |||
420 | (3) SIM card recognition fails, the green light is always on for 20s; | ||
421 | |||
422 | (4) The equipment signal is poor, and the green light flashes once every 3 seconds; | ||
423 | |||
424 | (5) When the device sends data, the green light flashes twice; | ||
425 | |||
426 | (6) The communication of the equipment is normal, and the green light flashes 3 times continuously; | ||
427 | |||
428 | (7) Trigger the tamper switch, the red light is always on for 30s, and goes out when the alarm is canceled; | ||
429 | |||
430 | (8) Trigger the door magnetic alarm, the red light is always on for 30s, and goes out when the alarm is canceled; | ||
431 | |||
432 | |||
433 | buzzer | ||
434 | |||
435 | (1) When the door magnetic alarm is triggered, the buzzer will sound for 30s; after the alarm is restored, the buzzer will be silenced; | ||
436 | |||
437 | (2) Enter the normal working mode (the tamper switch is closed for more than 5s or the door sensor is locked for more than 5s), the buzzer will sound for 1500ms; | ||
438 | |||
439 | (3) After entering the normal working mode, the tamper switch does not close, the buzzer sounds for 30s, the tamper switch is closed, and the buzzer sounds 1 time; | ||
440 | |||
441 | (4) When the door sensor does not alarm, press the button to trigger the alarm, and the buzzer will sound for 30s; when the door sensor alarms, press it once to cancel the alarm, and the buzzer will be silenced. | ||
442 | |||
443 | |||
444 | button | ||
445 | |||
446 | (1) When there is no alarm, press it once to trigger the alarm, and the buzzer will sound; when it alarms, press the buzzer to silence the sound. | ||
447 | |||
448 | (2) Press twice to silence the buzzer; | ||
449 | |||
450 | (3) Press the button three times or more, when the mute function is turned off, the mute function is turned on, and the green light flashes once; when the mute function is turned on, the mute function is turned off, and the green light flashes once. | ||
451 | |||
452 | |||
453 | data pack | ||
454 | |||
455 | (1) The device needs to send a registration packet and a heartbeat packet every time it is powered on and registered; | ||
456 | |||
457 | (2) The heartbeat time is reported once every 24 hours by default. | ||
458 | |||
459 | = 3. FAQ = | ||
460 | |||
461 | == 3.1 How to Upgrade Firmware == | ||
462 | |||
463 | User can upgrade the firmware for 1) bug fix, 2) new feature release. | ||
464 | |||
465 | Burning software please go to this link to download: | ||
466 | |||
467 | Note: | ||
468 | |||
469 | Disconnect one battery before starting the upgrade | ||
470 | |||
471 | Please use 1.8V USB TO TTL serial port | ||
472 | |||
473 | Connection: | ||
474 | |||
475 | USB TTL GND <~-~-~-~-> GND | ||
476 | |||
477 | USB TTL TXD <~-~-~-~-> UART_RXD | ||
478 | |||
479 | USB TTL RXD <~-~-~-~-> UART_TXD | ||
480 | |||
481 | 1. Double-click "FlashTool.exe" to start the program | ||
482 | |||
483 | [[image:file:///C:/Users/93456/AppData/Local/Temp/msohtmlclip1/01/clip_image010.png]] | ||
484 | |||
485 | [[image:file:///C:/Users/93456/AppData/Local/Temp/msohtmlclip1/01/clip_image011.png]] | ||
486 | |||
487 | 1. Select burn serial port and firmware package to complete the upgrade | ||
488 | |||
489 | [[image:file:///C:/Users/93456/AppData/Local/Temp/msohtmlclip1/01/clip_image012.png]] | ||
490 | |||
491 | [[image:file:///C:/Users/93456/AppData/Local/Temp/msohtmlclip1/01/clip_image013.png]] | ||
492 | |||
493 | 1. Install the battery to the node, and the upgrade will start at this time | ||
494 | |||
495 | [[image:file:///C:/Users/93456/AppData/Local/Temp/msohtmlclip1/01/clip_image014.png]] | ||
496 | |||
497 | 1. The following screenshot appears, indicating that the upgrade has been successful | ||
498 | |||
499 | [[image:file:///C:/Users/93456/AppData/Local/Temp/msohtmlclip1/01/clip_image015.png]] | ||
500 | |||
501 | |||
502 | = 4. Order Info = | ||
503 | |||
504 | Part Number: **NDS01** | ||
505 | |||
506 | |||
507 | = 5. Packing Info = | ||
508 | |||
509 | |||
510 | **Package Includes**: | ||
511 | |||
512 | * NDS01 NB-IoT Door Sensor | ||
513 | |||
514 | **Dimension and weight**: | ||
515 | |||
516 | * Device Size: | ||
517 | * Device Weight: | ||
518 | * Package Size / pcs : | ||
519 | * Weight / pcs : |