u-blox short range stand-alone multiradio modules

Transcription

1 u-cnnectxpress u-blx shrt range stand-alne multiradi mdules Applicatin Nte Abstract This Applicatin nte describes hw t cnnect and cnfigure Message Queuing Telemetry Transprt () using u-cnnectxpress sftware. UBX R01

2 Dcument Infrmatin Title Subtitle Dcument type Dcument number u-cnnectxpress u-blx shrt range stand-alne multiradi mdules Applicatin Nte UBX Revisin and date R01 19-Mar-2019 Disclsure Restrictin This dcument applies t the fllwing prducts: Prduct name Sftware versin PCN reference ODIN-W x nwards N/A ODIN-W x nwards N/A u-blx r third parties may hld intellectual prperty rights in the prducts, names, lgs and designs included in this dcument. Cpying, reprductin, mdificatin r disclsure t third parties f this dcument r any part theref is nly permitted with the express written permissin f u-blx. The infrmatin cntained herein is prvided as is and u-blx assumes n liability fr its use. N warranty, either express r implied, is given, including but nt limited t, with respect t the accuracy, crrectness, reliability and fitness fr a particular purpse f the infrmatin. This dcument may be revised by u-blx at any time withut ntice. Fr the mst recent dcuments, visit Cpyright u-blx AG. UBX R01 Page 2 f 16

3 Cntents Dcument Infrmatin... 2 Cntents Overview SN Gateway Cnnect -SN Gateway t Brker URL Frmat (fr AT+UDCP and AT+UDDRP) Example Msquitt test brker SN Client Cnnect / Discnnect SN Client Publish SN Client Subscribe SN Client PING SN Sleeping Clients Client Gateway Cnnect Client Gateway t Brker...13 Appendix A Glssary Related dcuments Revisin histry Cntact UBX R01 Page 3 f 16

4 1 Overview Message Queuing Telemetry Transprt () is a publish/subscribe, simple messaging prtcl, designed fr cmmunicatin between multiple devices. This applicatin nte describes hw t cnnect and cnfigure using u-cnnectxpress sftware. It is pssible t cnfigure the gateway as an -SN Gateway. This is intended fr end devices that d nt supprt TCP/TLS directly; instead, an end device cnnects t the gateway using a serial cnnectin such as Bluetth SPS r SPP and cmmunicates with the gateway using the -SN prtcl. It is als pssible t cnfigure the gateway as an Client Gateway. The hst f the gateway can then transmit r receive transparent data directly ver the UART. Brker TCP / TLS -SN Gateway Client Gateway SPP r SPS -SN Hst UART End Device End Device End Device Different cmbinatins f the abve mentined cnfiguratins can als be achieved. Hence, it is pssible fr the hst, and the end devices t cmmunicate with the brker via the same gateway simultaneusly. See the ODIN-W2 Getting Started [1] fr infrmatin abut hw t get started with the ODIN-W2 mdule. See the u-cnnect AT Cmmands manual [2] fr details f the AT cmmands that can be used with u-blx shrt range stand-alne mdules. Refer t the -SN v1.2 prtcl specificatin available at fr infrmatin abut the -SN prtcl. UBX R01 Cntents Page 4 f 16

5 2 -SN Gateway An -SN (SN=Sensr Netwrk) gateway enables end devices with n TCP/TLS supprt t cmmunicate with an brker (which requires TCP/TLS). The end device cnnects t the gateway using a serial cnnectin, such as Bluetth SPS r SPP, and cmmunicates using the -SN prtcl. The gateway then cnverts the -SN packets, frm the end device, t packets and sends t the brker and vice versa. End Device (e.g. NINA- B1/2/3) -SN -SN Gateway (ODIN-W2) Brker SPP r SPS TCP/TLS The -SN gateway is an aggregating gateway, which means that there is nly ne TCP r TLS cnnectin t the brker. Hence, multiple end devices d nt require ne cnnectin each as in the case f a transparent gateway. This is gd since many brkers limit the number f cnnectins and it is then better fr many end ndes t share ne TCP/TLS cnnectin. The end device will act as an -SN client (r client frm here n) and it can publish r subscribe t data identified by a unique tpic string. The brker is data agnstic meaning it cnsiders all data t be a byte array. Hence, a publish data packet cnsists f: A tpic string that uniquely identifies the data Data as a byte array. The steps t get the -SN gateway cnfigured and running typically are: 1. Create ne r mre streams by using the AT cmmands - AT+UDCP r AT+UDDRP. The first created stream will setup the actual TCP/TLS cnnectin t the brker. 2. Create ne r mre end device streams, Bluetth SPS r SPP, by using the AT cmmands - AT+UDCP, AT+UDDRP r by enabling ne f the assciated services, AT+UDSC, fr the end device t cnnect t the gateway. 3. Bind the stream with the end device stream using ne f the fllwing: a. Dynamic bind, AT cmmand AT+UDBIND (requires hst t execute the cmmand) b. Static bind cnfigured using sys.sid key in stream URL (autmatic bind nce bth the cnnectins are active) Streams bund End Device (e.g. NINA- B1/2/3) -SN SPS sps mqtt n TCP/TLS Brker Gateway The end device must transmit and receive -SN packets n the Bluetth SPS r SPP link. Hence, sme basic -SN packet parsing is required by the end device. UBX R01 Cntents Page 5 f 16

6 The gateway des nt supprt the full -SN specificatin. Only the fllwing packet types are supprted: CONNECT / CONNACK (client cnnects t the gateway) DISCONNECT (client discnnects frm the gateway r enter sleep mde) REGISTER / REGACK (client register tpic t the gateway) PUBLISH / PUBACK (client r gateway frwards data) SUBSCRIBE / SUBACK (client subscribes t data identified with tpic) PINGREQ / PINGRESP (client checks cnnectin t the gateway r plls fr data when in sleep mde) T ease implementatin f a prpriety -SN end device, it is recmmended t use the - SN packet parser cde available at Cnnect -SN Gateway t Brker The -SN gateway is cnfigured using either the cnnect peer AT cmmand, AT+UDCP, r the default remte peer AT cmmand, AT+UDDRP. Gateway n TCP/TLS Brker One stream must be setup fr every cnnected -SN end device. Fr example, if the gateway must handle 5 parallel Bluetth LE cnnected end devices, then 5 streams must be activated. Hwever, fr sleeping clients, it is pssible t have mre clients than the streams as lng as they d nt need t be cnnected simultaneusly URL Frmat (fr AT+UDCP and AT+UDDRP) mqtt://<hst address>:<prt>/?<keys> <hst address>: Hst name r IP address (e.g. test.msquitt.rg r ) <prt>: IP address prt number (e.g. 1883) <keys>: key=value (with separating & character) fr gateway t brker cnnectin related keys: client: Client name (e.g. client=my_client). user: User name (e.g. user=my_user) passwd: User passwrd (e.g. passwd=my_passwd) keepalive: Keep alive timeut in secnds (e.g. keepalive=60) The end devices must ensure that data is transmitted t the brker within the keep-alive timeut. If nt, the brker may discnnect. maxsnclients: Number f -SN clients supprted (e.g. maxsnclients=24). Default is 16. UBX R01 Cntents Page 6 f 16

7 TLS related keys: encr: TLS encryptin withut validating certificates if set t 1 (encr=1) ca: Server CA fr gateway t validate the server (e.g. ca=ca.pem) cert: Gateway client certificate (e.g. cert=client.pem) privkey: Gateway client private key (e.g. privkey=client.key) Static bind key: sys.sid: Static bind f the stream t anther stream (e.g. sys.sid=100). sys.sid : Incming SPS service cnnectins sys.sid : Incming SPP service cnnectins A new incming service cnnectin will use the lwest free id currently. sys.sid < 100: Used t bind tw streams cnfigured using +UDCP r +UDDRP. Fr this case, use the same id fr bth streams. The static bind will be activated when bth streams have been cnnected r recnnected. Since all streams share the same cnnectin t the brker, mst f the abve parameters must be identical fr all the streams. The exceptin is the sys.sid key, which will be different between the streams. The certificates must be upladed t the gateway using the security manager AT cmmand - AT+USECMNG (r by using the s-center tl Advanced cnnectin and settings->wi-fi certificates tab Example Msquitt test brker List certificates t make sure they are already upladed AT+USECMNG=3 "CA","msquitt.rg.crt" "CC","client.pem" "PK","client.key" OK TCP at+udcp=mqtt://test.msquitt.rg:1883/?sys.sid=100 +UDCP:1 OK +UUDPC:1,2,2, ,0, ,1883 TLS Encryptin at+udcp=mqtt://test.msquitt.rg:8883/?encr=1&sys.sid=100 +UDCP:1 OK +UUDPC:1,2,2, ,0, ,8883 TLS 1-way authenticatin at+udcp=mqtt://test.msquitt.rg:8883/?ca=msquitt.rg.crt&sys.sid=100 +UDCP:1 OK +UUDPC:1,2,2, ,0, ,8883 TLS 2-way-authenticatin UBX R01 Cntents Page 7 f 16

8 at+udcp=mqtt://test.msquitt.rg:8884/?ca=msquitt.rg.crt&cert=client.pem&privkey=clien t.key&sys.sid=100 +UDCP:1 OK +UUDPC:1,2,2, ,0, ,8884 Fr the tests, the Msquitt test brker ( is used. Nte that this is an pen server and published data is visible t anyne. Hence, use nly fr initial testing. The sys.sid=100 key wuld autmatically bind the -SN stream t the first incming SPS cnnectin. Fr the +UUDPC event, the lcal IP and prt is nt supprted and is always set t SN Client Cnnect / Discnnect Fr an end device t setup an -SN cnnectin t the gateway, the CONNECT packet must be sent. T terminate a previusly setup -SN cnnectin, the DISCONNECT packet is sent. Sample packets: CONNECT: 0x0A Length: 0x0A Type: 0x04 (CONNECT) Flags: 0x00 Prtcl id: 0x01 Duratin: 0x0040 (Keep alive duratin in secnds) Client id: 0x ( ABCD ) CONNACK 0x Length: 0x03 Type: 0x05 (CONNACK) Result: 0x00 (OK) UBX R01 Cntents Page 8 f 16

9 DISCONNECT: 0x0218 Length: 0x02 Type: 0x18 (DISCONNECT) It is recmmended t set duratin fr the cnnect message. This prevents the gateway frm keeping track f clients that are n lnger available. When the duratin timer fr a client has elapsed, the gateway will delete the client. If the cnnectin (fr example, SPS r SPP) is lst and setup again, the end device shuld send anther CONNECT( unique client id ) r PINGREQ( unique client id) t identify itself nce again. Fr the CONNECT flags parameter, will is nt supprted SN Client Publish Befre an -SN client can publish data t the brker, it must first register the data tpic t the gateway. It registers the tpic name (string) and gets back a tw-byte id, which is then used fr publishing data f that tpic. Sample packets: REGISTER: 0x090A Length: 0x09 Type: 0x0A (REGISTER) Tpic Id: 0x0000 Message id: 0x1234 (id r sequence number returned in the REGACK message) Tpic name: 0x ( 012 ) REGACK 0x070B Length: 0x07 Type: 0x0B (REGACK) Tpic Id: 0x0001 (Returned tpic id t used in PUBLISH) Message id: 0x1234 (id r sequence number f the REGISTER message) Result: 0x00 (OK) PUBLISH: 0x0A0C Length: 0x0A Type: 0x0C (PUBLISH) Flags: 0x00 Tpic Id: 0x0001 UBX R01 Cntents Page 9 f 16

10 Message id: 0x2345 (id r sequence number returned in the PUBACK message) Data: 0x PUBACK 0x070D Length: 0x07 Type: 0x0D (PUBACK) Tpic Id: 0x0001 Message id: 0x2345 (id r sequence number f the PUBLISH message) Result: 0x00 (OK) The maximum message size is the sum f (256 8 tpic len ). Set the PUBLISH flags parameter t 0 as it is nt supprted. The gateway will use DUP=0 (first time), QS=0 (send nce), Retain=0 (d nt stre), Will=0 (n will), TpicIdType=0 (nrmal tpic id, which is 2-byte id) 2.4 -SN Client Subscribe An -SN client can subscribe n tpics using the SUBSCRIBE message. When data fr a subscribed tpic is updated, the PUBLISH message is received frm the gateway. SUBSCRIBE: 0x Length: 0x08 Type: 0x12 (SUBSCRIBE) Flags: 0x00 Message id: 0x1234 (id r sequence number returned in the SUBACK message) Tpic name: 0x ( 012 ) SUBACK 0x Length: 0x08 Type: 0x13 (SUBACK) Flags: 0x00 Tpic Id: 0x0001 (Returned tpic id used in PUBLISH) Message id: 0x1234 (id r sequence number f the SUBSCRIBE message) Result: 0x00 (OK) PUBLISH: 0x0A0C Length: 0x0A Type: 0x0C (PUBLISH) Flags: 0x00 Tpic Id: 0x0001 Message id: 0x0000 (nt used by gateway fr PUBLISH messages) Data: 0x UBX R01 Cntents Page 10 f 16

11 Flags in the SUBSCRIBE message is nt supprted. Hence, set t 0. Gateway will use DUP=0 (first time), QS=0 (send nce), TpicIdType=0 (tpic name as string). The message id (sequence number) f the PUBLISH message is always 0 when sent by the gateway. Fr the subscribe tpic, neither the multi-level character, #, r the single-level character, +, is supprted SN Client PING An -SN client may use the PING message t check that the cnnectin t the gateway is alive. Als, if the keep-alive duratin fr the -SN cnnectin is set, it is the client that must assure that data is transmitted t avid a discnnectin. The PINGREQ can then be used. The PINGREQ with client identifier can als be used if the serial cnnectin (e.g. SPS r SPP) is lst and recnnected. It may then be necessary fr the client t identify itself in rder fr the gateway t assciate the client with a new stream. Hence, it is recmmended t always start with a PINGREQ including the unique client id after a recnnectin f the serial link (fr example, SPS r SPP). PINGREQ: 0x0216 Length: 0x02 Type: 0x16 (PINGREQ) PINGREQ with client id: 0x C49454E54 Length: 0x08 Type: 0x16 (PINGREQ) Client id: 0x434C49454E54 ( CLIENT ) PINGRESP 0x0217 Length: 0x02 Type: 0x17 (PINGRESP) If a respnse t a PINGREQ is a DISCONNECT (instead f a PINGRESP), it means that the gateway has lst track f the client r even deleted it. It may then be needed t d a CONNECT, REGISTER, SUBSCRIBE t restre the cnnectin. UBX R01 Cntents Page 11 f 16

12 2.6 -SN Sleeping Clients It is pssible fr an -SN client that is in sleep mde t terminate the serial cnnectin (fr example, SPS r SPP), enter lw pwer mde (t save pwer), wake-up and setup the serial cnnectin and pll if there has been any data transmitted t the client while asleep. The gateway will stre the messages subscribed by the client while asleep. Once the client has set up the cnnectin, it uses the PINGREQ message with the unique client identifier t pll the gateway fr data. The gateway then sends stred messages t the client and ends with the PINGRESP message t indicate that n mre data is available. The gateway nly stres the latest update fr each tpic. By default, the gateway can serve a maximum f 16 clients. It is pssible t change this by using the URL maxsnclients keywrd when cnfiguring the stream(s). If the gateway needs t stre a lt f messages fr many clients, it is pssible that it may run ut f RAM memry, which will cause the gateway t restart. Hence, it is very imprtant t test every specific cnfiguratin t make sure that the gateway is nt verladed. The number f active -SN streams limits the number f parallel active clients. UBX R01 Cntents Page 12 f 16

13 3 Client Gateway The gateway can als be cnfigured as an client gateway and nt as a full -SN gateway. It is then pssible fr a hst t transmit and receive data n the UART transparently. In data mde, transmitted data will be published t ne cnfigured publish tpic and received data will be received frm ne cnfigured subscribe tpic. In EDM (extended data mde) mde, it is pssible t cnfigure ne publish tpic and ne subscribe tpic fr every EDM channel. The hst can then transmit and receive data n separate channels and thus publish and subscribe t as many tpics as there are defined by the channels. Hst UART (data mde r EDM) Gateway (e.g. ODIN-W2) TCP/TLS Brker The data transmitted and received n the UART is the actual data nly withut any tpic infrmatin (cnfiguratin specifies what tpic it is). Fr the data mde, it means that if the hst transmits tw cnsecutive packets f size 5 and 10 bytes, it may be written t the Brker as ne packet f 15 bytes since there is n delimiting infrmatin. Fr EDM, this is nt an issue since every EDM write packet is transmitted separately t the brker. An client stream is cnfigured using the cmmands - +UDCP r +UDDRP. The first created stream will setup the actual TCP/TLS cnnectin t the -Brker. 3.1 Cnnect Client Gateway t Brker The client gateway supprt is implemented as an stream accrding t the u-cnnect sftware cncepts. This means that it is cnfigured using URLs either with the cnnect cmmand (AT+UDCP) r the default remte peer cmmand (AT+UDDRP). Gateway n TCP/TLS Brker The URL frmat is similar t the -SN URL frmat, except fr the fllwing keys: pt: Publish tpic (e.g. pt=ubx/test/1) st: Subscribe tpic (e.g. st=ubx/test/1) maxsnclients: Nt used If an stream is cnfigured withut the pt and st keys, the stream will be an -SN stream. If any f the pt r st keys are used, the stream will be an client stream. Fr the subscribe tpic, the multi-level character, #, is supprted (as in st=ubx/test/#). The singlelevel character - + is nt supprted. UBX R01 Cntents Page 13 f 16

14 Appendix A Glssary Abbreviatin CA EDM IP LE SN SPP SPS TCP TLS UART Definitin Certificatin Authrity Extended Data Mde Internet Prtcl Lw Energy Message Queuing Telemetry Transprt Sensr Netwrk Serial Prt Prfile Serial Prt Service Transmissin Cntrl Prtcl Transprt Layer Security Universal Asynchrnus Receiver/Transmitter Table 1: Explanatin f the abbreviatins and terms used UBX R01 Appendix Page 14 f 16

15 Related dcuments [1] ODIN-W2 Getting Started, Dc. N. UBX [2] u-cnnectxpress User Guide, Dc. N. UBX [3] u-cnnect AT Cmmands Manual, Dc. N. UBX Fr regular updates t u-blx dcumentatin and t receive prduct change ntificatins, register n ur hmepage ( Revisin histry Revisin Date Name Cmments R01 19-Mar-2019 tfri, cmag Initial release. UBX R01 Related dcuments Page 15 f 16

16 Cntact Fr cmplete cntact infrmatin, visit us at u-blx Offices Nrth, Central and Suth America u-blx America, Inc. Phne: Reginal Office West Cast: Phne: Technical Supprt: Phne: Headquarters Eurpe, Middle East, Africa u-blx AG Phne: Supprt: Asia, Australia, Pacific u-blx Singapre Pte. Ltd. Phne: Supprt: Reginal Office Australia: Phne: inf_anz@u-blx.cm Supprt: supprt_ap@u-blx.cm Reginal Office China (Beijing): Phne: inf_cn@u-blx.cm Supprt: supprt_cn@u-blx.cm Reginal Office China (Chngqing): Phne: inf_cn@u-blx.cm Supprt: supprt_cn@u-blx.cm Reginal Office China (Shanghai): Phne: inf_cn@u-blx.cm Supprt: supprt_cn@u-blx.cm Reginal Office China (Shenzhen): Phne: inf_cn@u-blx.cm Supprt: supprt_cn@u-blx.cm Reginal Office India: Phne: inf_in@u-blx.cm Supprt: supprt_in@u-blx.cm Reginal Office Japan (Osaka): Phne: inf_jp@u-blx.cm Supprt: supprt_jp@u-blx.cm Reginal Office Japan (Tky): Phne: inf_jp@u-blx.cm Supprt: supprt_jp@u-blx.cm Reginal Office Krea: Phne: inf_kr@u-blx.cm Supprt: supprt_kr@u-blx.cm Reginal Office Taiwan: Phne: inf_tw@u-blx.cm Supprt: supprt_tw@u-blx.cm UBX R01 Cntact Page 16 f 16