Download Zone
Select the files you need to support your use of Quectel’s products
Loading...
Filter
File Type
Product Categories
Relevant Technologies
Welcome to the Quectel Download Zone!
Please use the search bar and filters to find the files you need to support your use of our products. You can also find these listed on the relevant pages of our Product Selector.
Access to most files will require a user account, so please either log in or register to download the files available to you.
Antenna Brochure
1 Contents 01 Quectel Antenna Services 01 Quectel Advantages 01 Instruments 02 5G Antennas 04 Cellular (4G/3G/2G) Antennas 08 GNSS Antennas 14 Wi-Fi & Bluetooth Antennas 15 Combo Antennas 17 ISM Antennas 17 Cable Assemblies Quectel Antenna Services Consulting & Evaluation ■ Feasibility & Architecture Study ■ Risk Identification ■ Initial Proof of Concept ■ Antenna Component Selection Testing & Certification ■ Antenna OTA Testing ■ Interference Mitigation ■ Support for CE/FCC/PTCRB Radio Approval ■ Pre-certification OTA Testing for 2G/3G/4G/5G Quectel Advantages Solutions for the Entire Wireless RF Front End Complete RF Antenna Testing Services Global One Stop Engineering Support Vertical Integration of Antenna Resources Approved for Use with Quectel Modules Instruments Design ■ Antenna Placement ■ Antenna Layout Design ■ RF Specification Design ■ Antenna System Design & Optimization ■ Gerber File Review Manufacturing ■ Antenna Samples ■ Tooling & Molding ■ Assembly and Production Testing ■ Delivery Antenna Module Engineering Support Keysight CATR2305G Rhode & Schwarz WPTC-XS RayZone2800 ETS-AMS-8923-150 1 Quectel Antennas 5G Antennas Product YE0001BA YE0003AA YE0007AA YE0025AA Frequency Bands (MHz) 600–6000 Technology 5G Cable Length (mm) n/a Connector Type SMA Male (center pin) Mounting Type Terminal Dimensions (mm) 221 × 26.95 × 13.5 Matched Quectel Modules 5G/4G/3G/2G/LPWA 699–5000 5G n/a SMA Male (center pin) Terminal 190 × Φ 16 600–6000 5G n/a SMA Male (center pin) Terminal 152.4 × 21.79 × 14.49 698–960,1710–5000 5G n/a SMA Male (center pin) Terminal 199 × 22 5G Antennas Product YE0027AA YE0028AA YE0037AA YXH001AA YBY00A0KA Frequency Bands (MHz) 699–5000 Technology 5G Cable Length (mm) 3000 Connector Type SMA Male (center pin) Mounting Type Magnetic Dimensions (mm) 221 × Φ 61 Matched Quectel Modules 5G/4G/3G/2G/LPWA 700–2700, 3300–5000 5G 1500 SMA Male (center pin) Magnetic 234 × Φ 60 700–5000 5G 1000 SMA Male (center pin) Magnetic 88 × Φ 30 700–960, 1710–2690, 3300–5000 5G 1000 SMA Male (center pin) Magnetic 285 × 45 700–960, 1710–2690, 3300–5000 5G n/a N-J (Male pin with internal thread) Terminal Φ 20 × 300 The parameters shall be subject to the Specification. 2 Quectel Antennas 5G Antennas Product YF0002AA YF0002BA YF0002CA YF0002DA Frequency Bands (MHz) 700-960, 1710-2700, 3300-5000 Technology 5G 1710-2700, 3300-5000 5G Cable Length (mm) n/a n/a Connector Type Spring contact Spring contact Mounting Type Screw Screw Dimensions (mm) 60.1 × 12.25 × 10.1 Matched Quectel Modules 5G/4G/3G/2G/LPWA 41.25 × 10.1 × 10.1 1710-2700, 3300-5000 5G n/a Spring contact Screw 37.25 × 9.6 × 10.1 700-960, 1710-2700, 3300-5000 5G n/a Spring contact Screw 50.25 × 20.1 × 10.1 5G Antennas Product YF0017AA YF0017BA YF0020AA YC0018AA YC0018AAEVB Frequency Bands (MHz) 1500–6000 Technology 5G Cable Length (mm) 193 ±3 Connector Type IPEX Ⅳ Mounting Type Adhesive Dimensions (mm) 49 × 13 × 0.13 Matched Quectel Modules 5G/4G/3G/2G/LPWA 1100–6000 5G 193 ±3 IPEX Ⅳ Adhesive 49 × 13 × 0.13 600–6000 5G 184 ±3 IPEX Ⅳ Adhesive 90.15 × 15.2 × 0.13 617-6000 5G n/a n/a SMD 42 × 7 × 3 617-6000 5G n/a n/a n/a 140 × 40.4 The parameters shall be subject to the Specification. 3 Quectel Antennas 5G Antennas Product YP0009AA YP0009BA YP0009CA Frequency Bands (MHz) 1500–6000 Technology 5G Cable Length (mm) 193 ±3 Connector Type IPEX Ⅳ Mounting Type Adhesive Dimensions (mm) 49 × 13 × 0.85 Matched Quectel Modules 5G/4G/3G/2G/LPWA 1100–6000 5G 193 ±3 IPEX Ⅳ Adhesive 49 × 13 × 0.85 600–6000 5G 188 ±3 IPEX Ⅳ Adhesive 78.5 × 14.2 × 0.85 Cellular (4G/3G/2G) Antennas Product YC0001AA YC0002AA YC0003AA YC0003AAEVB YC0017BA YC0017BAEVB Frequency Bands 698–960, (MHz) 1710–2690 Technology LTE (4G) Cable Length (mm) n/a Connector Type n/a Mounting Type SMD Dimensions (mm) 35.0 × 8.5 × 3.0 Matched Quectel Modules 4G/3G/2G/LPWA 698–960, 1710–2690 LTE (4G) n/a n/a SMD 42 × 10 × 3 The parameters shall be subject to the Specification. 4 698-2700 LTE (4G) n/a n/a SMD 40 × 7 × 3 698-2700 LTE (4G) n/a n/a n/a 120 × 43 698-3800 LTE (4G) n/a n/a SMD 26 × 8 × 3 698-3800 LTE (4G) n/a n/a n/a 140 × 36 Quectel Antennas Cellular (4G/3G/2G) Antennas Product YF0022AA YF0007BA YPCA004AA Frequency Bands (MHz) 700–2690 Technology LTE (4G) Cable Length (mm) 75 ±3 Connector Type RF1 Mounting Type Adhesive Dimensions (mm) 40 × 15 × 1.6 Matched Quectel Modules 4G/3G/2G/LPWA 600–960, 1427.9–1495.9, 1710–2170, 2300–2700 LTE (4G) 75 ±3 RF1 Adhesive 50 × 25 × 0.85 Cellular (4G/3G/2G) Antennas Product YFCA002AA YF0006DA 700–2690 LTE (4G) 100 ±3 IPEX Ⅰ Adhesive 40 ×10 × 1 YF0028AA Frequency Bands (MHz) 700–2690 Technology LTE (4G) Cable Length (mm) 75 ±3 Connector Type RF1 Mounting Type Adhesive Dimensions (mm) 30 × 20 × 0.13 Matched Quectel Modules 4G/3G/2G/LPWA 690–960, 1710–2170, 2300–2690 LTE (4G) 75±3 IPEX Ⅰ Adhesive 50 × 25 × 0.13 698-3000 LTE (4G) 150 ±2 IPEX Ⅰ Adhesive 96 × 21 × 0.2 The parameters shall be subject to the Specification. 5 Quectel Antennas Cellular (4G/3G/2G) Antennas Product YECT002AA YECT003AA YE0009AA YPR00A0AA YCN001AA Frequency Bands (MHz) 700–960,1710–2690 Technology LTE (4G) Cable Length (mm) n/a Connector Type SMA Male (center pin) Mounting Type Terminal Dimensions (mm) 196.2 × 16 × 13 Matched Quectel Modules 4G/3G/2G/LPWA 698-960, 1710-2700 LTE (4G) n/a SMA Male (center pin) Terminal 113× Φ 10 824–2700 LTE (4G) n/a SMA Male (center pin) Terminal 190 × 16 700–2700 LTE (4G) n/a SMA Male (center pin) Terminal 194.3 ×15.95 700–2700 LTE (4G) n/a SMA Male (center pin) Terminal 144 × Φ 13 Cellular (4G/3G/2G) Antennas Product YE0006AA YE0010AA YB0010AA YB0016AA Frequency Bands (MHz) 700–2700 Technology LTE (4G) Cable Length (mm) 1500 Connector Type SMA Male (center pin) Mounting Type Magnetic Dimensions (mm) 318 × Φ 30 Matched Quectel Modules 4G/3G/2G/LPWA 698–2700 LTE (4G) 1000 ±30 SMA Male (center pin) Adhesive 152 × 18 × 5.9 The parameters shall be subject to the Specification. 6 698–960, 1710–2690 LTE (4G) 2000 ±30 SMA Male Magnetic Φ 81.5 × 16 698–960, 1710–2700 LTE (4G) 3000 ±50 SMA Male (center pin) Screw 54 × 91 Quectel Antennas Cellular (4G/3G/2G) Antennas Product YE0012AA YE0021AA YE0029AA Frequency Bands 824–960, (MHz) 1710–2690 Technology LTE (4G) Cable Length (mm) 250 ±10 Connector Type SMA Male (center pin) Mounting Type Adhesive Dimensions (mm) 116.5 × 21.7 × 5.6 Matched Quectel Modules 4G/3G/2G/LPWA 690–960, 1710–2690 LTE (4G) 1500 ±30 SMA Male (center pin) Magnetic 112 × 29.8 700–2700 LTE (4G) 3000 ±50 SMA Male (center pin) Magnetic 88 × Φ 30 Cellular (4G/3G/2G) Antennas Product YDX001AA YE0002AA YE0013AA YGL001AA Frequency Bands (MHz) 824–2690 Technology LTE (4G) Cable Length (mm) n/a Connector Type SMA Male (center pin) Mounting Type Terminal Dimensions (mm) 208 × Φ 12 Matched Quectel Modules 4G/3G/2G/LPWA 699–2700 LTE (4G) n/a RP-SMA Male (center receptacle) Terminal 174.6 × 19.2 700–2700 LTE (4G) n/a SMA Male (center pin) Terminal 115.4 × 17.5 × Φ 10.2 700–960,1710–2690 LTE (4G) n/a SMA Male (center pin) Terminal 196.2 × 16 × 13 The parameters shall be subject to the Specification. 7 Quectel Antennas Cellular (4G/3G/2G) Antennas Product YE0008AA YE0011AA YKL001CA Frequency Bands (MHz) 824–960, 1710–2170 , 2500–2700 Technology LTE (4G) Cable Length (mm) n/a Connector Type SMA Male (center pin) Mounting Type Terminal Dimensions (mm) 52 × Φ 10 Matched Quectel Modules LPWA/3G/2G module series 824–960, 1710–2170, 2500–2700 LTE (4G) n/a SMA Male (center pin) Terminal 50 × Φ 10 NB: 800–1000, 1700–1900 2G/3G/NB-IoT 310 ±10 SMA Male (center pin) Screw 50 × 48 GNSS Antennas Product YC0013AA YC0013AAEVB YC0008AA YC0008AAEVB Frequency Bands (MHz) 1559-1606 Technology GNSS Cable Length (mm) n/a Connector Type n/a Mounting Type SMD Dimensions (mm) 3.2 × 1.6 × 0.6 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS n/a n/a n/a 90 × 50 The parameters shall be subject to the Specification. 8 1173, 1575 GNSS L1 & L5 (passive) n/a n/a SMD 30 × 5 × 5 GNSS L1/L5 module series 1173, 1575 GNSS L1 & L5 (passive) n/a n/a n/a 80 × 36 Quectel Antennas GNSS Antennas Product YCGA001AA YCGA002AA YG0038AA Frequency Bands (MHz) 1559-1606 Technology GNSS L1 Cable Length (mm) n/a Connector Type n/a Mounting Type Pin Mounting Dimensions (mm) 10 × 10 × 4 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS L1 n/a n/a Pin Mounting 12 × 12 × 4 1559-1606 GNSS L1 n/a n/a Pin Mounting 13 × 13 × 4 GNSS Antennas Product YG0043AA YG0046AA YG0005AA YG0062AA YG0048AA Frequency Bands (MHz) 1559-1606 Technology GNSS L1 Cable Length (mm) n/a Connector Type n/a Mounting Type Pin Mounting Dimensions (mm) 15 × 15 × 4 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS L1 n/a n/a Pin Mounting 18 × 18 × 2 1559-1606 GNSS L1 n/a n/a Pin Mounting 18 × 18 × 4 1559-1606 GNSS L1 n/a n/a Pin Mounting 25 × 25 × 4 1176, 1575 GNSS L1 & L5 n/a n/a Pin mounting 18 × 18 × 4 & 25 × 25 × 4 GNSS L1/L5 module series The parameters shall be subject to the Specification. 9 Quectel Antennas GNSS Antennas Product YCGO004AA YCGO005AA YCGO006AA YCGO007AA YG0034AA YG0021AA Frequency Bands (MHz) 1559-1606 Technology GNSS L1 (passive) 1559-1606 GNSS L1 (passive) Cable Length (mm) 50±2 50±2 Connector Type IPEX Ⅰ IPEX Ⅰ Mounting Type Cable Mounting Cable Mounting Dimensions (mm) 10 × 10 × 6.5 15 × 15 × 6.5 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS L1 (passive) 50±2 IPEX Ⅰ Cable Mounting 18 × 18 × 6.5 1559-1606 GNSS L1 (passive) 50±2 IPEX Ⅰ Cable Mounting 25 × 25 × 6.5 1559–1606 GNSS L1 (active) 35±2 IPEX Ⅰ Cable Mounting 13 ×13 × 6.8 1560–1605 GNSS L1 & B1 & G1 (active) 42 ±3 IPEX Ⅰ Cable Mounting 18.4 × 18.4 × 8.86 GNSS Antennas Product YG0032AA YG0015AA YCGO008AA YCGO009AA YCGO010AA YCGO011AA Frequency Bands (MHz) Technology Beidou: 1561 ±5 ; GPS: 1575 ±5 GNSS L1 & B1 & G1 (active) Cable Length (mm) 55 1559–1606 GNSS L1 (active) 55 ±3 Connector Type IPEX Ⅰ IPEX Ⅰ Mounting Type Cable Mounting Cable Mounting Dimensions (mm) 18 × 18 × 6.6 25 × 25 × 8.25 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS L1 (active) 50±3 IPEX Ⅰ Cable Mounting 10 × 10 × 6.5 1559-1606 GNSS L1 (active) 50±2 IPEX Ⅰ Cable Mounting 15 × 15 × 6.5 1559-1606 GNSS L1 (active) 50±3 IPEX Ⅰ Cable Mounting 18 × 18 × 6.5 1559-1606 GNSS L1 (active) 50±3 IPEX Ⅰ Cable Mounting 25 × 25 × 6.5 The parameters shall be subject to the Specification. 10 Quectel Antennas GNSS Antennas Product YCGS004AA YCGS005AA YCGS006AA Frequency Bands (MHz) 1560–1606 Technology GNSS L1 & G1 Cable Length (mm) n/a Connector Type n/a Mounting Type SMD Dimensions (mm) 9 × 9 × 4 Matched Quectel Modules GNSS L1 module series GNSS Antennas Product YAT001AA 1560–1606 GNSS L1 & G1 n/a n/a SMD 18 × 18 × 4 YAT001BA 1560–1606 GNSS L1 & G1 n/a n/a SMD 25 × 25 × 4 YBS00A1AA Frequency Bands (MHz) 1176, 1575 Technology GNSS L1 & L5 (active) Cable Length (mm) n/a Connector Type n/a Mounting Type Cable Mounting Dimensions (mm) 25 × 25 × 4 & 18 × 18 × 4 Matched Quectel Modules GNSS L1/L5 module series 1176, 1575 GNSS L1 & L5 (active) n/a n/a Cable Mounting 25 × 25 × 2 & 18 × 18 × 2 1176, 1575 GNSS L1 & L5 (active) n/a n/a Cable Mounting 40 × 40 × 4 & 45 × 45 × 6 The parameters shall be subject to the Specification. 11 Quectel Antennas GNSS Antennas Product YAT001CA YG0030AA YCGO014AA Frequency Bands (MHz) 1176, 1575 Technology GNSS L1 & L5 (active) Cable Length (mm) 40 ±2 Connector Type IPEX Ⅰ Mounting Type Cable Mounting Dimensions (mm) 25 × 25 × 2 & 18 × 18 × 4 Matched Quectel Modules GNSS L1/L5 module series 1176, 1575 GNSS L1 & L5 (passive) 100 ±2 IPEX Ⅰ Cable Mounting 52 × 52 × 9.9 L5: 1166–1186 L1: 1559–1606 GNSS L1 & L5 (passive) 142 IPEX Ⅰ Cable Mounting 50 × 50 × 19.0 GNSS Antennas Product YFGA001AA YFGA002AA YFGA003AA YFGA004AA Frequency Bands 1160–1270, (MHz) 1560–1605 Technology GNSS L1 & 2 & L5 & L6 Cable Length (mm) 100 Connector Type IPEX Ⅰ Mounting Type Adhesive Dimensions (mm) 74.56 × 24.5 × 0.25 Matched Quectel Modules GNSS L1/L5 module series 1559–1609 GNSS L1 100 IPEX Ⅰ Adhesive 61.15 × 11.24 GNSS L1 module series The parameters shall be subject to the Specification. 12 1559–1609 GNSS L1 100 IPEX Ⅰ Adhesive 39.45 x 13.25 1160–1270, 1560–1605 GNSS L1 & 2 & L5 & L6 100 IPEX Ⅰ Adhesive 43 × 24 × 0.12 GNSS L1/L5 modules Quectel Antennas GNSS Antennas Product YG0035AA YLY001CA YB0017AA YG0028AA Frequency Bands (MHz) 1561, 1575 Technology GNSS L1 & B1 & G1 (active) Cable Length (mm) 3000 ±20 Connector Type SMA Male (center pin) Mounting Type Magnetic Dimensions (mm) 50.3 × 38.4 × 17.1 Matched Quectel Modules GNSS L1 module series 1568 ±10 GNSS L1 & B1 & G1 (active) 2000 SMA Male (center pin) Magnetic 45.5 × 38 × 13.5 GPS L1/L5, BD B1/B2, GLONASS L1 1561–1602, 1166–1186 GNSS L1 & L5 (active) GNSS L1 & L5 (active) L = 3000 SMA Male (center pin) Magnetic 3000 SMA Male (center pin) Magnetic 61.5 × 56.5 × 23 Φ 54 × 38 GNSS L1/L5 module series GNSS Antennas Product YG0065AA YEGT001AA YEGT002AA YG0063AA Frequency Bands (MHz) 1575–1602 Technology GNSS L1 (active) Cable Length (mm) 3000 Connector Type FAKRA Female (Code C) Mounting Type Magnetic Dimensions (mm) 34.5 × 37.5 × 12.5 Matched Quectel Modules GNSS L1 modules 1559-1606 GNSS L1 n/a SMA Male (center pin) Terminal 50 × Ø10 All GNSS L1 modules 1559–1606 GNSS L1 n/a SMA Male (center pin) Terminal 52 × Ø10 GPS L1/L2/L5; BDS B1/B2/B3; GLONASS L1/L2; Galileo E1/E5a/E5b/E6; L-band All GNSS bands + L-band Corrections n/a TNC Female Screw Φ 165 × 68 All GNSS L1/L2/L5 modules The parameters shall be subject to the Specification. 13 Quectel Antennas Wi-Fi & Bluetooth Antennas Product YC0009AA YC0010AA YEWM001AA Frequency Bands (MHz) 2400–2500 Technology Wi-Fi (Bluetooth) Cable Length (mm) n/a Connector Type n/a Mounting Type SMD Dimensions (mm) 3.2 × 1.6 × 0.5 Matched Quectel Modules FC30R 2400–2500 Wi-Fi (Bluetooth) n/a n/a SMD 5.2 × 2.0 × 1.2 2400–2500 Wi-Fi (Bluetooth) 1500 SMA Male (center pin) Magnetic Φ 30 ×77.4 Wi-Fi & Bluetooth Antennas Product YF0011AA YF0026AA YF0027AA YF0029AA YF0023AA YF0023CA Frequency Bands 2400–2500, (MHz) 5150–5850 2400–2500, 4900–5850, 5925-7125 2400–2500, 4900–5850, 5925-7125 2410–2490 , 4920–5925 2400–2500, 5150–5850, 5925-7125 2400–2500, 5150–5850, 5925-7125 Technology Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Cable Length (mm) 44 ±13 100 ±2 100 ±2 100 ±2 100±2 Connector Type IPEX Ⅰ (U.FL Generation Ⅰ) IPEX Ⅰ (U.FL Generation Ⅰ) IPEX Ⅰ (U.FL Generation Ⅰ) IPEX Ⅰ (U.FL Generation Ⅰ) RF I Generation Mounting Type Adhesive Adhesive Adhesive Adhesive Adhesive 100±2 RF I Generation Adhesive Dimensions (mm) Matched Quectel Modules 38.9 × 9 × 0.12 All Wi-Fi/BT modules (Except Wi-Fi 6E) 28.9 × 11 × 0.2 All Wi-Fi/BT modules 42 × 7 × 0.2 30 × 30 × 0.25 All Wi-Fi/BT modules (Except Wi-Fi 6E) 22.90 × 11.70 All Wi-Fi/BT modules 37.80 × 7.50 The parameters shall be subject to the Specification. 14 Quectel Antennas Wi-Fi & Bluetooth Antennas Product YE0031AA YE0032AA YE0038AA YEWT004AA YEWN001AA Frequency Bands 2.4–2.5 GHz, (MHz) 5.15–5.85 GHz Technology Wi-Fi (Bluetooth) 2.4–2.5 GHz, 5.15–5.85 GHz Wi-Fi (Bluetooth) Cable Length (mm) n/a n/a Connector Type SMA Male (center pin) SMA Male (center pin) Mounting Type Terminal Terminal Dimensions (mm) 52 ±2 50 ±2 Matched Quectel Modules All Wi-Fi/BT modules (Except Wi-Fi 6E) 2400–2500, 5150–5850 Wi-Fi (Bluetooth) n/a SMA Male (center pin) Terminal 195 × 13 2400–2500, 5150–7150 Wi-Fi 6E (Bluetooth) n/a SMA Male (center pin) Terminal 109 × Φ 10 All Wi-Fi/BT modules 2400–2500, 5150–5850 Wi-Fi (Bluetooth) n/a RP-SMA Male (Center Receptacle) Terminal 200 × 13 All Wi-Fi/BT modules (Except Wi-Fi 6E) Combo Antennas Product YB0007AA YB0008AA YB0009AA YB0014AA Frequency Bands (MHz) Technology 700–960, 1710–2690 , 3300–5000 5G Cable Length (mm) 500 Connector Type SMA Male (center pin) Mounting Type Screw Dimensions (mm) Matched Quectel Modules Φ 120 × 43 All 5G modules (RM50xQ Series, RG50xQ Series) & All 4G/3G/2G modules & GNSS L1 modules 4G MAIN: 698–960, 1710–2690; GNSS: 1575.42 ±5, 1561.098 ±5; 4G DIV: 1710–2690 Main LTE & DIV LTE & GNSS 300 SMA Male (center pin) Adhesive Φ 84 × 17.5 4G: 824–960, 1710–2690; GPS, BD: 1575.42 ±10, 1561 ±10 LTE & GNSS 310 SMA Male (center pin) Screw 33 × 48 All 4G/3G/2G modules & GNSS L1 modules LTE Main & Div: 698–960, 1700–2700; GNSS: 1561–1571; 1602–1606 Main LTE & DIV LTE & GNSS 3000 SMA Male (center pin) Screw 81 × 27.5 The parameters shall be subject to the Specification. 15 Quectel Antennas Combo Antennas Product YB0015AA YKL001AA YB0032AA YB0033AA YB0022AA Frequency Bands (MHz) Technology LTE: 698–960, 1700–2700; Wi-Fi, Bluetooth: 2400– 2500; GNSS: 1561 ±5, 1575 ±5 LTE/GPS & BD/Wi-Fi Bluetooth: 2400–2500; 4G: 824–960; 1710–2690; GPS, BD: 1575.42 ±10, 1561 ±10 700–960, 1700–2700 LTE/GPS & BD/Wi-Fi Main LTE & DIV LTE Cable Length (mm) 300 310 2000 Connector Type SMA Male (center pin) SMA Male (center pin) SMA Male (Center Pin) Mounting Type Screw Screw Screw Dimensions (mm) 54 × 91 33 × 48 Φ 120 × 43 Matched Quectel Modules 4G/3G/2G modules & GNSS L1 modules & Wi-Fi modules All 4G/3G/2G modules LTE Main & Div: 700–960, 1700–2700 ; GNSS: 1559– 1610 (active) Main LTE & DIV LTE & GNSS 2000 LTE Main & Div: 700–2700; Wi-Fi: 2400–5850 ; GNSS: 1561/1575.42/1602 Main LTE & DIV LTE & GNSS & Wi-Fi1 & Wi-Fi2 1000 SMA Male (Center Pin) FME Female Connector Screw Screw Φ 120 × 43 All 4G/3G/2G modules & GNSS L1 modules Φ 120 × 43 4G/3G/2G modules & GNSS L1 modules & Wi-Fi, Bluetooth modules Combo Antennas Product YB0031AA YEMA003AA YEMA004AA YWL00A0AA YB0026AA YEWN004AA Frequency Bands (MHz) LTE: 698–960; 1710–2690; GNSS: 1575.42 ±5, 1561.098 ±5 LTE: 700–2700 1561/1575.42/1602 Technology LTE & GNSS LTE & GNSS Cable Length (mm) 300 3000 Connector Type SMA Male (center pin) 4G: FAKRA D GNSS: FAKRA C Mounting Type Dimensions (mm) Adhesive Φ 84 ×17.5 Adhesive Φ 84 × 17.5 Matched Quectel Modules All 4G/3G/2G modules & GNSS L1 modules 4G: 698–960 , 1710–2690 Wi-Fi & Bluetooth: 2400–2500 698–960, 1710–2690 LTE: 700–2700 ; Wi-Fi: 2400–5850; GNSS: 1561/1575.42/1602 2400–2500, 5150–5850 LTE & Wi-Fi Main LTE & DIV LTE LTE & GNSS & Wi-Fi1 & Wi-Fi2 Wi-Fi MIMO 900 1500 1000 300 GNSS: FAKRA_C, LTE: SMA Male (Center Pin) SMA Male (Center Pin) FAKRA_D, Wi-Fi 1: FAKRA_ SMA Male (Center Pin) I, Wi-Fi 2: FAKRA_I Screw Screw Screw Screw Φ 81 ×14.5 Φ 81 × 27.5 Φ 120 ×43 Φ 46 ×15 All 4G/3G/2G modules & Wi-Fi modules All 4G/3G/2G modules All 4G/3G/2G modules & GNSS L1 modules & Wi-Fi, Bluetooth modules Wi-Fi modules The parameters shall be subject to the Specification. 16 Quectel Antennas ISM Antennas Product YE0019AA YE0039BA YEIM001AA Frequency Bands (MHz) Technology Cable Length (mm) Connector Type Mounting Type Dimensions (mm) 450–470 ISM SMA Male (center pin) Terminal 109 × 10 430-470, 790-960 ISM 75 SMA Male (center pin) Adhesive 117 × 21.81 × 5.47 Cable Assemblies Product YM0003AA YM0015AA YM0003CA 465–475 ISM 2000 SMA Male (center pin) Magnetic Φ 30 × 131 YM0003AB YM0013AA Frequency Bands (MHz) Technology Cable Length (mm) Connector Type Mounting Type Dimensions (mm) Matched Quectel Modules 0–6000 0–6000 Cable Cable 100 150 SMA-female to IPEX Ⅰ SMA-female to IPEX Ⅰ Screw Screw 100 150 All modules (5G excluded) 0–6000 Cable 200 SMA-female to IPEX Ⅰ Screw 200 0–6000 Cable 200 RP-SMA-female to IPEX Ⅰ Screw 200 0–6000 Cable 300 SMA-female to IPEX Ⅰ Screw 300 Product YM0004AA YM0005AA YSAN001AA YBY00A0HA YBY00A0JA YBY00A0IA Frequency Bands (MHz) Technology Cable Length (mm) Connector Type Mounting Type Dimensions (mm) Matched Quectel Modules 0–6000 0–6000 0–6000 Cable Cable Cable 100 150 300 SMA-female to IPEX Ⅳ SMA-female to RF Ⅳ SMA-female to RF Ⅳ Screw Screw Screw 100 150 300 All 5G modules (RM50xQ Series, RG50xQ Series) 0–6000 Cable 200 0–6000 Cable 250 N-K-female to IPEX Ⅰ N-female to IPEX Ⅰ Screw Screw 200 250 All modules (5G excluded) Bracket - - All modules The parameters shall be subject to the Specification. 17 V1.7.4 2022.04
6.53 MB
Application Note
BG95&BG77&BG600L Series Network Searching Scheme Introduction LPWA Module Series Version: 2.0 Date: 2022-04-24 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 1 / 41 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 2 / 41 LPWA Module Series About the Document Revision History Revision Date Author Description 1.0 2020-01-13 Elvis SUN Initial 1. Added the applicable module BG600L-M3. 2. Updated the frequency bands of BG95 series and BG77: deleted the eMTC band B14 and NB-IoT B26 (Chapters 2.1 and 2.2). 3. Updated the RAT/PLMN selection procedure figure (Figure 2). 2.0 2022-04-24 Forest WANG 4. Updated notes of network searching AT commands (Chapter 5). 5. Updated the default setting of in AT+QCFG='iotopmode' (Chapter 5.3). 6. Added some typical problems and corresponding cause analysis (Chapters 7.3, 7.4 and 7.5). 7. Added the FAQ chapter (Chapter 8). BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 3 / 41 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 1.1. Applicable Modules .................................................................................................................... 7 2 Supported RATs and Bands .............................................................................................................. 8 2.1. Supported RATs and Bands of BG95 Series ............................................................................. 8 2.2. Supported RATs and Bands of BG77 ........................................................................................ 8 2.3. Supported RATs and Bands of BG600L-M3 .............................................................................. 9 3 Network Searching/Registration Processes .................................................................................. 10 4 Factors Influencing Network Registration Speed ......................................................................... 13 4.1. RAT/PLMN Selection ............................................................................................................... 13 4.2. LTE EARFCN Scan.................................................................................................................. 14 5 Network Searching Related AT Commands................................................................................... 16 5.1. AT+QCFG='nwscanseq' Configure RAT Searching Sequence ........................................... 16 5.2. AT+QCFG='nwscanmode' Configure RAT(s) to be Searched for........................................ 17 5.3. AT+QCFG='iotopmode' Configure Network Category to be Searched for under LTE RAT 18 5.4. AT+QCFG='band' Configure Frequency Band .................................................................... 19 6 Solutions to Speed up Network Searching .................................................................................... 23 6.1. Overview of NB-IoT Network Searching Time ......................................................................... 23 6.2. Solutions to Speed up Network Searching .............................................................................. 24 6.2.1. Disable NB-IoT and Enable Required RAT(s) .............................................................. 24 6.2.2. Enable NB-IoT Bands Supported by Current Operator Only........................................ 24 7 Typical Problems and Root Cause Analysis.................................................................................. 26 7.1. Network Searching Sequence Determined by (U)SIM Card Files .......................................... 26 7.2. Network Searching Sequence Determined by RPLMN/RPLMNACT Stored on Module Flash27 7.3. Long Network Registration Time in Roaming State ................................................................. 28 7.4. Network Registration Request Rejected by Network .............................................................. 30 7.5. Long Network Registration Time if AT Commands are Executed Frequently ......................... 34 8 FAQ..................................................................................................................................................... 35 9 Summary of CME ERROR Codes .................................................................................................... 37 10 Appendix References ....................................................................................................................... 39 BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 4 / 41 LPWA Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 7 Table 2: Frequency Bands of BG95 Series Module..................................................................................... 8 Table 3: Frequency Bands of BG77 Module ................................................................................................ 9 Table 4: Frequency Bands of BG600L-M3 Module...................................................................................... 9 Table 5: Network Searching Time of NB-IoT Bands with Different SNR ................................................... 14 Table 6: eMTC/NB-IoT Band Deployment over the World (For Reference Only)...................................... 15 Table 7: Solutions to Speed up Network Searching (Disable NB-IoT)....................................................... 24 Table 8: Solutions to Speed up Network Searching (Enable NB-IoT Bands Supported) .......................... 24 Table 9: Related Documents ...................................................................................................................... 39 Table 10: Terms and Abbreviations ............................................................................................................ 39 BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 5 / 41 LPWA Module Series Figure Index Figure 1: Network Searching and Registration Process............................................................................ 10 Figure 2: RAT/PLMN Selection .................................................................................................................. 13 Figure 3: RAT Searching Sequence Determined by (U)SIM Card Files.................................................... 26 Figure 4: RAT Searching Sequence Determined by RPLMN/RPLMNACT Stored on Module Flash ....... 27 Figure 5: Behaviour of the Module if (U)SIM is Card in Roaming State .................................................... 28 Figure 6: GMM Cause Information Element .............................................................................................. 31 Figure 7: EMM Cause Information Element............................................................................................... 32 Figure 8: Module Received Reject Cause Code........................................................................................ 33 Figure 9: Module Initiated T3247 Timer and Tried to Register Another Available Network ....................... 33 Figure 10: Restore the Network Information .............................................................................................. 35 BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 6 / 41 LPWA Module Series 1 Introduction This document outlines the supported RATs and frequency bands of Quectel BG95 series, BG77 and BG600L-M3 modules, and describes the network searching scheme by illustrating network searching/registration processes and related AT commands to help users understand the network searching mechanism of the modules. Furthermore, the document describes some problems observed in the process of network searching, and provides the corresponding root cause analysis. 1.1. Applicable Modules Table 1: Applicable Modules Module Series BG95 BG77 BG600L Model BG95-M1 BG95-M2 BG95-M3 BG95-M4 BG95-M5 BG95-M6 BG95-MF BG77 BG600L-M3 Description Cat M1 only Cat M1/Cat NB2 Cat M1/Cat NB2/EGPRS Cat M1/Cat NB2, 450 MHz Supported Cat M1/Cat NB2/EGPRS, Power Class 3 Cat M1/Cat NB2, Power Class 3 Cat M1/Cat NB2, Wi-Fi Positioning Cat M1/Cat NB2 Cat M1/Cat NB2/EGPRS BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 7 / 41 LPWA Module Series 2 Supported RATs and Bands 2.1. Supported RATs and Bands of BG95 Series Quectel BG95 series module supports three RATs: eMTC, NB-IoT and EGPRS. ⚫ Default RATs: eMTC, NB-IoT and EGPRS ⚫ Default searching sequence: eMTC → NB-IoT → EGPRS ⚫ If the three RATs need to be supported synchronously or other searching sequences are needed, set the relevant configuration values via AT commands. The details of AT commands are provided in Chapter 5. The following table lists the supported frequency bands of BG95 series module. Table 2: Frequency Bands of BG95 Series Module RAT Frequency Band eMTC B1/B2/B3/B4/B5/B8/B12/B13/B18/B19/B20/B25/B26/B27/B28/B31/B66/B72/B73/B85 NB-IoT B1/B2/B3/B4/B5/B8/B12/B13/B18/B19/B20/B25/B28/B31/B66/B71/B72/B73/B85 EGPRS GSM850, EGSM900, DCS1800, PCS1900 NOTE Quectel BG95 series includes multiple models with different RATs and frequency bands. For detailed information, see document [1]. 2.2. Supported RATs and Bands of BG77 Quectel BG77 module supports two RATs: eMTC and NB-IoT. BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 8 / 41 LPWA Module Series ⚫ Default RATs: eMTC and NB-IoT ⚫ Default searching sequence: eMTC → NB-IoT ⚫ If the two RATs need to be supported synchronously or other searching sequences are needed, set the relevant configuration values via AT commands. The details of AT commands are provided in Chapter 5. The following table lists the supported frequency bands of BG77. Table 3: Frequency Bands of BG77 Module RAT eMTC NB-IoT Frequency Band B1/B2/B3/B4/B5/B8/B12/B13/B18/B19/B20/B25/B26/B27/B28/B66/B85* B1/B2/B3/B4/B5/B8/B12/B13/B18/B19/B20/B25/B28/B66/B71/B85* 2.3. Supported RATs and Bands of BG600L-M3 Quectel BG600L-M3 module supports three RATs: eMTC, NB-IoT and EGPRS. ⚫ Default RATs: eMTC, NB-IoT and EGPRS ⚫ Default searching sequence: eMTC → NB-IoT → EGPRS ⚫ If the three RATs need to be supported synchronously or other searching sequences are needed, set the relevant configuration values via AT commands. The details of AT commands are provided in Chapter 5. The following table lists the supported frequency bands of BG600L-M3 module. Table 4: Frequency Bands of BG600L-M3 Module RAT Frequency Band eMTC B1/B2/B3/B4/B5/B8/B12/B13/B18/B19/B20/B25/B26/B27/B28/B66/B85 NB-IoT B1/B2/B3/B4/B5/B8/B12/B13/B18/B19/B20/B25/B28/B66/B71/B85 EGPRS GSM850, EGSM900, DCS1800, PCS1900 BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 9 / 41 LPWA Module Series 3 Network Searching/Registration Processes The network searching/registration processes of BG95 series, BG77 and BG600L-M3 modules are illustrated below: See 3GPP TS 24.301 Power On UE Initialization RAT/PLMN Selection (E)ARFCN Scan Cell Searching System Information Analysis Cell Selection Cell Camping Attach Request Random Access RRC Connection Request RRC Connection Setup Attach Accepted Attach Complete See 3GPP TS 31.102 See 3GPP TS 23.122 See 3GPP TS 36.211 See 3GPP TS 36.331 See 3GPP TS 36.304 See 3GPP TS 36.300 Figure 1: Network Searching and Registration Process BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 10 / 41 LPWA Module Series 1. UE Initialization UE initialization includes (U)SIM card recognition and reading of NVM related to network searching. 2. RAT/PLMM Selection ⚫ Set the RAT searching sequence and the RAT(s) allowed to be searched according to network searching related NVM and related (U)SIM EF files. ⚫ PLMN selection can be performed in either automatic or manual modes. ⚫ For more information, see Chapter 4.1. 3. (E)ARFCN Scan ⚫ LTE EARFCN scan includes system scan and band scan. ⚫ EGPRS ARFCN scan refers to power scan. ⚫ For more information, see Chapter 4.2. 4. Cell Searching Cell searching refers to cell recognition and downlink synchronization. 5. System Information Analysis This step includes reading and analyzing MIB and SIB information. For detailed definition of system information, see 3GPP TS 36.331 [5.2]. ⚫ MIB information: the number of antennas, downlink bandwidth, cell ID and registered (E)ARFCN. ⚫ SIB information: PLMN, cell ID, etc. 6. Cell Selection If the acquired band satisfies the signal strength requirement of UE, the UE will perform the next step (cell camping), otherwise it will continue (E)ARFCN scanning. 7. Cell Camping Cell camping is started after successful cell selection. 8. Attach Request/Location Update Request After the cell is camped, the UE will send the attach request/location update request. 9. Random Access UE performs uplink synchronization (random access) after sending attach request/location update request. 10. RRC Connection Request 11. RRC Connection Setup BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 11 / 41 12. Attach Accepted/Location Updating Accepted LPWA Module Series BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 12 / 41 LPWA Module Series 4 Factors Influencing Network Registration Speed Network registration speed is affected by RAT/PLMN selection and LTE EARFCN scan. The details about the two processes are provided below. 4.1. RAT/PLMN Selection This chapter describes the steps involved in RAT/PLMN selection. The following figure illustrates the overall processes of RAT/PLMN selection in automatic mode. As shown below, the search order during RAT/PLMN selection is determined not only by the module settings but also by some files on the (U)SIM card. By default, the files on the (U)SIM card have a higher priority. EF/NV/EFS In itia liza tion Auto Network Selecti on Mode Check RAT pr iority list (rat_acq_o rder) Yes PLMN = HPLMN Is EF L RP LMNSI set? No Check NVRPLMNACT RAT search orde r = EF HP LMNwACT Yes PLMN = RPLMN RAT search orde r = NV RP LMNACT LTE No RPLMN from EF EPS LOCI Is RPLMN valid? GERAN Check domain pr ef If domain prefere nce = CS only or CS +PS RPLMN from EF LOCI If domain prefere nce = PS onl y RPLMN from EF PS LO CI Figure 2: RAT/PLMN Selection BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 13 / 41 LPWA Module Series 4.2. LTE EARFCN Scan This chapter describes the effect of LTE EARFCN scan on the speed of network registration. LTE EARFCN scan includes system scan and band scan. When the module shuts down, it will store the current network registration information (e.g., EARFCN, PCI and so on). When the module powers on next time for network registration, UE will try to acquire the stored network registration information. This procedure is called system scan. This procedure will speed up the network registration process. If the network information acquisition failed in system scan, UE will attempt to scan all supported bands, which process constitutes the band scan. According to statistics, the scan for all bands under eMTC and EGPRS takes about tens of seconds. However, EARFCN scan will take longer under NB-IoT, due to the characteristics of NB-IoT network (especially the weak signal feature). The following table shows the test results of some of the NB-IoT bands, which displays the EARFCN scan time required in each band. Table 5: Network Searching Time of NB-IoT Bands with Different SNR Band B1 Band Width (MHz) 60 Searching Time with SNR 0 (Unit: s) 25 Searching Time with SNR 1 (Unit: s) 139 Searching Time with SNR 2 (Unit: s) 313 B2 60 26 132 310 B3 75 32 164 386 B4 45 20 104 229 B5 25 11 69 132 B8 35 15 77 185 B12 17 7 38 90 B13 10 4 21 49 B18 15 7 36 78 B19 15 6 39 77 B20 40 13 67 157 B25 65 15 86 183 B28 45 20 104 238 BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 14 / 41 LPWA Module Series As BG95 series, BG77 and BG600L-M3 modules support dozens of bands under NB-IoT, it is recommended to enable only the bands supported by the service operator. Table 6: eMTC/NB-IoT Band Deployment over the World (For Reference Only) Band B1 DL Freq. (MHz) 2100 Applicability as per 3GPP U.S. TS36.1.0.1 eMTC/NB-IoT China The Middle East Japan Korea Europe Australia ■ ■ B2 1900 eMTC/NB-IoT ■ B3 1800 eMTC/NB-IoT ■ ■ ■ ■ ■ B4 1700 eMTC ■ B5 850 eMTC/NB-IoT ■ ■ B8 900 eMTC/NB-IoT ■ ■ ■ ■ B12 700 eMTC/NB-IoT ■ B13 700 eMTC/NB-IoT ■ B18 800 eMTC/NB-IoT ■ B19 800 eMTC/NB-IoT ■ B20 800 eMTC/NB-IoT ■ B26 850 eMTC/NB-IoT ■ B28 700 eMTC/NB-IoT ■ ■ BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 15 / 41 LPWA Module Series 5 Network Searching Related AT Commands In order to optimize network searching/registration time, related AT commands can be used to set the RAT searching sequence, RAT(s) to be searched, network category to be searched under LTE RAT, and preferred bands to be searched. 5.1. AT+QCFG='nwscanseq' Configure RAT Searching Sequence This Write Command configures the searching sequence of RATs or queries the current setting. AT+QCFG='nwscanseq' Configure RAT Searching Sequence Write Command AT+QCFG='nwscanseq'[,[, ]] Response If the optional parameters are omitted, query the current setting. +QCFG: 'nwscanseq', OK If any of the optional parameters is specified, configure the RAT searching sequence. OK If there is an error related to ME functionality: +CME ERROR: Maximum Response Time Characteristics If there is any other error: ERROR 300 ms determines when the command will take effect. The configurations will be saved automatically. BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 16 / 41 Parameter LPWA Module Series Integer type. RAT searching sequence. (e.g.: 020301 stands for eMTC → NB-IoT → GSM) 00 Automatic (eMTC → NB-IoT → GSM) 01 GSM 02 eMTC 03 NB-IoT Integer type. When to take effect. 0 Take effect after UE reboots 1 Take effect immediately Integer type. Error code. See Chapter 9 for details. NOTE 1. This command is invalid on BG95-M1 module. 2. GSM RAT (=01) is valid only on BG95-M3, BG95-M5 and BG600L-M3 modules. 3. NB-IoT is disabled by default. 4. Don’t repeatedly select one RAT while specifying (for example '020202'), to prevent unexpected situations. 5.2. AT+QCFG='nwscanmode' Configure RAT(s) to be Searched for This Write Command configures the RAT(s) to be searched for or queries the current setting AT+QCFG='nwscanmode' Configure RAT(s) to be Searched for Write Command AT+QCFG='nwscanmode'[,[,]] Response If the optional parameters are omitted, query the current setting. +QCFG: 'nwscanmode', OK If any of the optional parameters is specified, configure the RAT(s) to be searched for: OK If there is an error related to ME functionality: +CME ERROR: If there is any other error: BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 17 / 41 LPWA Module Series Maximum Response Time Characteristics ERROR 300 ms determines when the command will take effect. The configurations will be saved automatically. Parameter Integer type. RAT(s) to be searched for. 0 Automatic (GSM and LTE) 1 GSM only 3 LTE only Integer type. When to take effect. 0 Take effect after UE reboots 1 Take effect immediately Integer type. Error code. See Chapter 9 for details. NOTE This command is valid only on BG95-M3, BG95-M5 and BG600L-M3 modules. 5.3. AT+QCFG='iotopmode' Configure Network Category to be Searched for under LTE RAT This Write Command configures the network category to be searched for under LTE RAT or queries the current setting. AT+QCFG='iotopmode' Configure Network Category to be Searched for under LTE RAT Write Command Response AT+QCFG='iotopmode'[,[,]] setting. +QCFG: 'iotopmode', OK If any of the optional parameters is specified, configure the network category to be searched for under LTE RAT: OK BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 18 / 41 LPWA Module Series Maximum Response Time Characteristics If there is an error related to ME functionality: +CME ERROR: If there is any other error: ERROR 300 ms determines when the command will take effect. The configurations will be saved automatically. Parameter Integer type. Network category to be searched for under LTE RAT. 0 eMTC 1 NB-IoT 2 eMTC and NB-IoT Integer type. When to take effect. 0 Take effect after UE reboots 1 Take effect immediately Integer type. Error code. See Chapter 9 for details. NOTE This command is invalid on BG95-M1 module. 5.4. AT+QCFG='band' Configure Frequency Band This Write Command configures the frequency bands to be searched for or queries the current setting. AT+QCFG='band' Configure Frequency Band Write Command AT+QCFG='band'[,, ,[ ,]] Response If the optional parameters are omitted, query the current setting. +QCFG: 'band',,, OK If any of the optional parameters is specified, configure the BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 19 / 41 LPWA Module Series Maximum Response Time Characteristics frequency bands to be searched for. OK If there is an error related to ME functionality: +CME ERROR: If there is any other error: ERROR 300 ms determines when the command will take effect. The configurations will be saved automatically. Parameter A hexadecimal value that specifies the GSM frequency band (e.g.: 0xa = 0x2(DCS1800) + 0x8(PCS1900)). If it is set to 0, it means not to change GSM frequency band. 0 No change 0x1 EGSM900 0x2 DCS1800 0x4 GSM850 0x8 PCS1900 0xF All of the supported bands above A hexadecimal value that specifies the eMTC frequency band (e.g.: 0x15 = 0x1(LTE B1) + 0x4(LTE B3) + 0x10(LTE B5)). If it is set to 0, it means not to change the eMTC frequency band. 0 No change 0x1 (BAND_PREF_LTE_BAND1) LTE B1 0x2 (BAND_PREF_LTE_BAND2) LTE B2 0x4 (BAND_PREF_LTE_BAND3) LTE B3 0x8 (BAND_PREF_LTE_BAND4) LTE B4 0x10 (BAND_PREF_LTE_BAND5) LTE B5 0x80 (BAND_PREF_LTE_BAND8) LTE B8 0x800 (BAND_PREF_LTE_BAND12) LTE B12 0x1000 (BAND_PREF_LTE_BAND13) LTE B13 0x20000 (BAND_PREF_LTE_BAND18) LTE B18 0x40000 (BAND_PREF_LTE_BAND19) LTE B19 0x80000 (BAND_PREF_LTE_BAND20) LTE B20 0x1000000 (BAND_PREF_LTE_BAND25) LTE B25 0x2000000 (BAND_PREF_LTE_BAND26) LTE B26 0x4000000 (BAND_PREF_LTE_BAND27) LTE B27 0x8000000 (BAND_PREF_LTE_BAND28) LTE B28 0x40000000 (BAND_PREF_LTE_BAND31) LTE B31 BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 20 / 41 LPWA Module Series 0x20000000000000000 (BAND_PREF_LTE_BAND66) LTE B66 0x800000000000000000 (BAND_PREF_LTE_BAND72 LTE B72 0x1000000000000000000 (BAND_PREF_LTE_BAND73) LTE B73 0x1000000000000000000000 (BAND_PREF_LTE_BAND85) LTE B85 A hexadecimal value that specifies the NB-IoT frequency band (e.g.: 0x15 = 0x1(LTE B1) + 0x4(LTE B3) + 0x10(LTE B5)). If it is set to 0, it means not to change the NB-IoT frequency band. 0 No change 0x1 (BAND_PREF_LTE_BAND1) LTE B1 0x2 (BAND_PREF_LTE_BAND2) LTE B2 0x4 (BAND_PREF_LTE_BAND3) LTE B3 0x8 (BAND_PREF_LTE_BAND4) LTE B4 0x10 (BAND_PREF_LTE_BAND5) LTE B5 0x80 (BAND_PREF_LTE_BAND8) LTE B8 0x800 (BAND_PREF_LTE_BAND12) LTE B12 0x1000 (BAND_PREF_LTE_BAND13) LTE B13 0x20000 (BAND_PREF_LTE_BAND18) LTE B18 0x40000 (BAND_PREF_LTE_BAND19) LTE B19 0x80000 (BAND_PREF_LTE_BAND20) LTE B20 0x1000000 (BAND_PREF_LTE_BAND25) LTE B25 0x8000000 (BAND_PREF_LTE_BAND28) LTE B28 0x40000000 (BAND_PREF_LTE_BAND31) LTE B31 0x20000000000000000 (BAND_PREF_LTE_BAND66) LTE B66 0x400000000000000000 (BAND_PREF_LTE_BAND71) LTE B71 0x800000000000000000 (BAND_PREF_LTE_BAND72) LTE B72 0x1000000000000000000 (BAND_PREF_LTE_BAND73) LTE B73 0x1000000000000000000000 (BAND_PREF_LTE_BAND85) LTE B85 Integer type. When to take effect. 0 Take effect after UE reboots 1 Take effect immediately Integer type. Error code. See Chapter 9 for details. NOTE 1. For the specific bands supported by each model, see corresponding specifications of the modules. ⚫ is valid only on BG95-M3, BG95-M5 and BG600L-M3 modules. ⚫ is invalid on BG95-M1 module. ⚫ LTE B31/B72/B73 is valid on BG95-M4 module only. 2. The value setting of when all eMTC bands are intended to be searched for: ⚫ 0x100182000000004F0E189F for BG95-M4 ⚫ 0x100002000000000F0E189F for BG77, BG600L-M3 and other BG95 series modules 3. The value setting of when all NB-IoT bands are intended to be searched for: ⚫ 0x10018200000000490E189F for BG95-M4 BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 21 / 41 LPWA Module Series ⚫ 0x10004200000000090E189F for BG77, BG600L-M3 and other BG95 series modules BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 22 / 41 LPWA Module Series 6 Solutions to Speed up Network Searching 6.1. Overview of NB-IoT Network Searching Time As per 3GPP specifications, NB-IoT is expected to be deployed in a much lower coverage area. Expected Maximum Coupling Loss for NB-IoT is 164 dB, whereas it is only around 155 dB for eMTC. This pushes the device to accommodate more SNR range to detect a possible NB-IoT cell deployment. In addition, eMTC has a 1.4 MHz bandwidth, whereas NB-IoT has a 200 KHz bandwidth. This means NB-IoT has much more candidates to scan and detect in a given LTE deployed area, which leads to much longer searching time for NB-IoT than eMTC. BG95 series, BG77 and BG600L-M3 modules divide the search process into three levels according to NB-IoT signal characteristics: ⚫ Frequency scan level 0 (SNR level 0): SNR value > 0 dB. This takes only few milliseconds for each raster. ⚫ Frequency scan level 1 (SNR level 1): SNR value ranges from 0 to -9 dB. This takes about 100 msec for each raster. ⚫ Frequency scan level 2 (SNR level 2): typical SNR value is about -12 dB. This takes about 400 to 500 msec for each raster. According to the test results in Table 5, NB-IoT network was searched for a long period of time. This, coupled with the dozens of bands supported by the modules, makes the total network searching time very long. ⚫ Under SNR level 0, searching the network takes only tens of seconds. ⚫ Under SNR level 1, the time for network searching is five to six times as long as the time for searching under SNR level 0. ⚫ Under SNR level 2, the time for network searching is ten to fifteen times as long as the time for searching under SNR level 0. To avoid the long network searching time, either of the following solutions should be used to optimize the network searching scheme of modules. BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 23 / 41 LPWA Module Series 6.2. Solutions to Speed up Network Searching 6.2.1. Disable NB-IoT and Enable Required RAT(s) Network searching can be sped up by disabling NB-IoT and enabling only the required RAT(s). Table 7: Solutions to Speed up Network Searching (Disable NB-IoT) Solutions Disable NB-IoT Enable Required RAT(s) Enable EGPRS only Enable eMTC only Enable eMTC and EGPRS both Related AT Commands Default configuration AT+QCFG='nwscanmode',1 AT+QCFG='iotopmode',0 AT+QCFG='nwscanmode',3 AT+QCFG='iotopmode',0 AT+QCFG='nwscanmode',0 6.2.2. Enable NB-IoT Bands Supported by Current Operator Only When NB-IoT is necessary, it is recommended to enable only the bands supported by the current service operator. Table 8: Solutions to Speed up Network Searching (Enable NB-IoT Bands Supported) Regions Solutions Related AT Commands U.S Europe Korea Enable the three RATs synchronously. Set B2, B4, B12 and B13 as the bands to be searched. Enable the three RATs synchronously. Set B3, B8 and B20 as the bands to be searched. Enable the three RATs synchronously. Set B3 and B5 as the bands to AT+QCFG='band',F,180A,180A AT+QCFG='iotopmode',2 AT+QCFG='nwscanseq',020301 AT+QCFG='nwscanmode',0 AT+QCFG='nwscanmode',3 (set only when EGPRS is not needed) AT+QCFG='band',F,80084,80084 AT+QCFG='iotopmode',2 AT+QCFG='nwscanseq',020301 AT+QCFG='nwscanmode',0 AT+QCFG='nwscanmode',3 (set only when EGPRS is not needed) AT+QCFG='band',F,14,14 AT+QCFG='iotopmode',2 AT+QCFG='nwscanseq',020301 BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 24 / 41 LPWA Module Series Australia The Middle East Japan China be searched. Enable the three RATs synchronously. Set B3 and B28 as the bands to be searched. Enable the three RATs synchronously. Set B3, B5 and B28 as the bands to be searched. Enable the three RATs synchronously. Set B1, B8, B18 and B19 as the bands to be searched. Enable the three RATs synchronously. Set B1, B3, B5, B8 and B26 as the bands to be searched. AT+QCFG='nwscanmode',0 AT+QCFG='nwscanmode',3 (set only when EGPRS is not needed) AT+QCFG='band',F,8000004,8000004 AT+QCFG='iotopmode',2 AT+QCFG='nwscanseq',020301 AT+QCFG='nwscanmode',0 AT+QCFG='nwscanmode',3 (set only when EGPRS is not needed) AT+QCFG='band',F,8000084,8000084 AT+QCFG='iotopmode',2 AT+QCFG='nwscanseq',020301 AT+QCFG='nwscanmode',0 AT+QCFG='nwscanmode',3 (set only when EGPRS is not needed) AT+QCFG='band',F,60081,60081 AT+QCFG='iotopmode',2 AT+QCFG='nwscanseq',020301 AT+QCFG='nwscanmode',0 AT+QCFG='nwscanmode',3 (set only when EGPRS is not needed) AT+QCFG='band',F,2000095,2000095 AT+QCFG='iotopmode',2 AT+QCFG='nwscanseq',020301 AT+QCFG='nwscanmode',0 AT+QCFG='nwscanmode',3 (set only when EGPRS is not needed) BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 25 / 41 LPWA Module Series 7 Typical Problems and Root Cause Analysis This chapter describes some typical problems and corresponding root cause analysis. 7.1. Network Searching Sequence Determined by (U)SIM Card Files Problem Description: The RAT searching sequence does not comply with the setting of AT+QCFG='nwscanseq'. Root Cause Analysis: The sequence is determined by some files in (U)SIM card, as illustrated in the example below. Figure 3: RAT Searching Sequence Determined by (U)SIM Card Files BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 26 / 41 LPWA Module Series 7.2. Network Searching Sequence Determined by RPLMN/RPLMNACT Stored on Module Flash Problem Description: The RAT searching sequence does not comply with the setting of AT+QCFG='nwscanseq'. Root Cause Analysis: In the example shown below, EFLRPLMNSI (0x6FDC, this file is optional in 3GPP protocol) does not exist on the (U)SIM card. The module thus searches RPLMN/RPLMNACT stored inside. Figure 4: RAT Searching Sequence Determined by RPLMN/RPLMNACT Stored on Module Flash BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 27 / 41 LPWA Module Series 7.3. Long Network Registration Time in Roaming State Problem Description: When the module is in roaming state, the network registration time becomes longer, especially when the module powers on for the first time in roaming state or when the module registers to NB-IoT network. Roaming State Introduction: When the PLMN of the module’s registered network is not consistent with the HPLMN or EHPLMN of (U)SIM card, the module is in the roaming state. In this case, returned by executing AT+CREG?/AT+CGREG?/AT+CEREG? is 5, which also indicates that the module is in the roaming state. The behaviour of the module if the (U)SIM card is in roaming state is described in the figure below: Power Up Registered Network NO Current PLMN is VPLMN YES HPLMN Search YES Start HPLMN Enable Search Timer NO IRAT Search Enable NO END YES Start IRAT Search Timer Figure 5: Behaviour of the Module if (U)SIM is Card in Roaming State BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 28 / 41 LPWA Module Series Root Cause Analysis: When the module is powered on for the first time with a roaming (U)SIM card, there is no RPLMN information on the (U)SIM card, thus the module needs to scan for high priority PLMN (HPLMN, EHPLMN and so on). It means that the module needs to scan all supported RATs and bands to confirm whether there is any available HPLMN around the cells first. Therefore, the network registration time of the module is always longer when powering on for the first time with a roaming (U)SIM card. Due to the NB-IoT network characteristics (200 kHz bandwidth), network scanning is much slower (For more details, see Chapter 6.1). For non-initial network registration, the last registered RPLMN information is saved on the (U)SIM card and the last registered network frequency information is saved in the module. It means that the module can find the target network as fast as possible. Therefore, the network registration time of the module is faster for non-initial network registration of a roaming (U)SIM card. According to 3GPP specification (3GPP TS 23.122 subclause 4.4.3.3), the module should attempt to access the HPLMN, EHPLMN or another high priority PLMN (hereinafter referred to as ''HPLMN search'') with HPLMN search timer when the module is in the roaming state. For BG95 series, BG77 or BG600L-M3 module, when the module is locked to one RAT, HPLMN search process is imperceptible for users, and the ongoing operation will not be affected. The module needs to scan all supported RATs and bands with HPLMN when there is no RPLMN information saved on the roaming (U)SIM card. The registered RPLMN information saved on the (U)SIM card and the network frequency information saved in the module can shorten registration time for an roaming (U)SIM card. Recommendation: ⚫ Lock as few as possible RATs and bands to shorten the network searching time. ⚫ Use normal power-down methods (such as executing AT+QPOWD=1, see document [2] for details) to power off the module, to make sure the network registration information is saved on the (U)SIM card and the module flash. It is not recommended to disconnect the power supply of the module directly. BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 29 / 41 LPWA Module Series 7.4. Network Registration Request Rejected by Network Problem Description: The module’s network registration request was rejected. Reject Cause Information Element Introduction: The purpose of the reject cause information element is to indicate the reason why a GMM/EMM request from the UE was rejected by the network. The GMM cause information element is defined in 3GPP TS 24.008, and the EMM cause information element is defined in 3GPP 24.301. The reject cause is a type 3 information element with the length of 2 octets (see Figure 6 for GMM cause value and Figure 7 for EMM cause value). When the module receives a reject cause code, it means that the module has searched the network, but the registration request was rejected by the network. The network searching sequence of the module complies with the 3GPP specification when the module receives a reject cause code, and the module will always try to search for available networks even if it receives a reject cause code from a certain network. BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 30 / 41 LPWA Module Series Figure 6: GMM Cause Information Element BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 31 / 41 LPWA Module Series Figure 7: EMM Cause Information Element Example Analysis: When the module receives a reject cause code from the network, it means that the module has searched the network and initiated an attach request. Then the module starts the T3247 timer, which is a random value ranging from 30 minutes to 60 minutes. After the timer expires, the module initiates network registration again on the PLMN, as illustrated in the figure below. BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 32 / 41 LPWA Module Series The module selects PLMN 46011 to send attach request. Attach request is rejected and the reject cause code is 14, then the module sets T3247 timer and the timer value is random from 30 to 60 minutes. The module uses another available PLMN 24601 to send attach request and set T3410 timer, the timer value is 10 seconds. If the attach request is still rejected, it will be sent again every 10 seconds, 4 times to retry, and 5 attempts in total. Figure 8: Module Received Reject Cause Code According to 3GPP, the module initiates T3247 timer after receiving reject cause code #14. The module tries to search and register another available network. Figure 9: Module Initiated T3247 Timer and Tried to Register Another Available Network BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 33 / 41 LPWA Module Series 7.5. Long Network Registration Time if AT Commands are Executed Frequently Problem Description: During the network searching progress, the network registration time becomes longer if some network-searching commands are executed frequently. Root Cause Analysis: Executing a network-searching command (see Chapter 5 for more information) immediately triggers a one-time network search even if network searching is already in progress. Therefore, frequent executing of network-searching commands may cause longer network registration time. Recommendation: Before executing any network-searching command, it is recommended to check whether the current network configuration of the module is the desired one. If it is, there is no need to reset the network configuration. Example AT+QCFG='nwscanmode' +QCFG: 'nwscanmode',3 //Query the current RAT(s) allowed to be searched for. //The module only searches for LTE bands. OK AT+QCFG='nwscanmode',1 OK //Change the network configuration if it is not the desired one. BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 34 / 41 LPWA Module Series 8 FAQ 1. Q: How does the module search for the network in OOS (Out of Service) state? A: When the module is in OOS (Out of Service) state, it will always periodically try to search for available networks, as shown in the figure below. Figure 10: Restore the Network Information Phase 1 a) Sleep for 30 seconds i. Attempt acquisition of full service and then limited service on the GSM and LTE acquisition list. ii. Go back to step a. and repeat 10 times. b) Sleep for 45 seconds i. Attempt acquisition of full service and then limited service on the GSM and LTE acquisition list. ii. Go back to step b. and repeat 10 times. Phase 2 c) Sleep for 60 seconds i. Attempt acquisition of full service and then limited service on the GSM and LTE acquisition list. ii. Go back to step c. and repeats continuously until a service is found. 2. Q: How to clear the registration information history of the module? A: a) If you want to clear the historical frequency information stored in the module, you can execute the following commands: ⚫ AT+QNVFD='/nv/item_files/modem/geran/grr/acq_db' under GSM. ⚫ AT+QNVFD='/nv/reg_files/modem/lte/rrc/csp/acq_db' under LTE (eMTC and NB-IoT). ⚫ AT+QNVFD='/nv/reg_files/modem/nb1/rrc/csp/acq_db' under NB-IoT. b) If you want to clear RPLMN information stored on (U)SIM card, you can execute the following commands: BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 35 / 41 LPWA Module Series ⚫ AT+CRSM=214,28542,0,0,11,'FFFFFFFFFFFFFFFFFFFFFF' to clear LOCI (including RPLMN). ⚫ AT+CRSM=214,28531,0,0,14,'FFFFFFFFFFFFFFFFFFFFFFFFFFFF' to clear PSLOCI. ⚫ AT+CRSM=214,28643,0,0,18,'FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF' to clear EPSLOCI. BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 36 / 41 LPWA Module Series 9 Summary of CME ERROR Codes Final result code +CME ERROR: indicates an error related to mobile equipment or network. The operation is similar to ERROR result code. values are mostly used by common message commands. The following table lists most of general and GPRS related ERROR codes. For some GSM protocol failure causes described in GSM specifications, the corresponding ERROR codes are not included. Table 1: Summary of CME ERROR Codes 0 1 2 3 4 5 6 7 10 11 12 13 14 15 Meaning Phone failure No connection to phone Phone-adaptor link reserved Operation not allowed Operation not supported PH-SIM PIN required PH-FSIM PIN required PH-FSIM PUK required (U)SIM not inserted (U)SIM PIN required (U)SIM PUK required (U)SIM failure (U)SIM busy (U)SIM wrong BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 37 / 41 LPWA Module Series 16 Incorrect password 17 (U)SIM PIN2 required 18 (U)SIM PUK2 required 20 Memory full 21 Invalid index 22 Not found 23 Memory failure 24 Text string too long 25 Invalid characters in text string 26 Dial string too long 27 Invalid characters in dial string 30 No network service 31 Network timeout 32 Network not allowed - emergency calls only 40 Network personalization PIN required 41 Network personalization PUK required 42 Network subset personalization PIN required 43 Network subset personalization PUK required 44 Service provider personalization PIN required 45 Service provider personalization PUK required 46 Corporate personalization PIN required 47 Corporate personalization PUK required BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 38 / 41 LPWA Module Series 10 Appendix References Table 9: Related Documents Document Name [1] Quectel_BG95_LPWA_Specification [2] Quectel_BG95&BG77&BG600L_Series_AT_Commands_Manual [3] Quectel_BG95&BG77&BG600L_Series_QCFG_AT_Commands_Manual Table 10: Terms and Abbreviations Abbreviation (U)SIM 3GPP ARFCN CS CSG EARFCN EF EFS EGPRS EHPLMN EMM eMTC EPS Description (Universal) Subscriber Identity Module 3rd Generation Partnership Project Absolute Radio Frequency Channel Number Circuit Switching Domain Closed Subscriber Group E-UTRA Absolute Radio Frequency Channel Number Elementary File Encrypt File System Enhanced General Packet Radio Service Equivalent Home PLMN EPS Mobility Management Enhanced Machine Type Communication Evolved Packet System BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 39 / 41 EPSLOCI ESM GMM GPRS GSM HLR HPLMN HSS IE IMEI IMSI IRAT LOCI LTE MAC ME MIB MS MSC NB-IoT NV NVM PCI PDP PLMN PS PSLOCI EPS Location Information EPS Session Management GPRS Mobility Management General Packet Radio Service Global System for Mobile Communications Home Location Register Home Public Land Mobile Network Home Subscriber Server Information Element International Mobile Equipment Identity International Mobile Subscriber Identity Inter-RAT Location Information Long Term Evolution Medium Access Control Mobile Equipment Master Information Block Mobile Station Mobile Switching Center Narrow Band Internet of Things Non-volatile Flash Memory Non-Volatile Memory Peripheral Component Interconnect Packet Data Protocol Public Land Mobile Network Packet Switching Domain Packet Switch Location Information LPWA Module Series BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 40 / 41 RAT RPLMN RRC SIB SNR UE VPLMN Radio Access Technology Registered Public Land Mobile Network Radio Resource Control System Information Block Signal Noise Ratio User Equipment Visiting Public Land Mobile Network LPWA Module Series BG95&BG77&BG600L_Series_Network_Searching_Scheme_Introduction 41 / 41
679.75 KB
BG770A-GL&BG95xA-GL FILE Application Note LPWA Module Series Version: 1.0 Date: 2022-05-05 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG770A-GL&BG95xA-GL_FILE_Application_Note 1 / 29 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG770A-GL&BG95xA-GL_FILE_Application_Note 2 / 29 LPWA Module Series About the Document Revision History Version Date Author - 2021-02-04 Damir KLICKOVIC 1.0 2022-05-05 Damir KLICKOVIC Description Creation of the document First official release BG770A-GL&BG95xA-GL_FILE_Application_Note 3 / 29 LPWA Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 5 1 Introduction .......................................................................................................................................... 6 1.1. Using FILE AT Commands.......................................................................................................... 6 1.2. Description of Data Mode ........................................................................................................... 7 2 Description of FILE AT Commands ................................................................................................... 8 2.1. AT Command Introduction .......................................................................................................... 8 2.1.1. Definitions......................................................................................................................... 8 2.1.2. AT Command Syntax ....................................................................................................... 8 2.2. Declaration of AT Command Examples ...................................................................................... 9 2.3. AT Command Description ........................................................................................................... 9 2.3.1. AT+QFLDS Get the Space Information of Storage Medium ......................................... 9 2.3.2. AT+QFLST List File Information in the Storage Medium ............................................ 10 2.3.3. AT+QFDEL Delete File(s) in the Storage Medium ...................................................... 12 2.3.4. AT+QFUPL Upload a File to the Storage Medium ...................................................... 13 2.3.5. AT+QFDWL Download a File from the Storage Medium ............................................ 15 2.3.6. AT+QFOPEN Open a File ........................................................................................... 16 2.3.7. AT+QFREAD Read a File............................................................................................ 17 2.3.8. AT+QFWRITE Write to a File ...................................................................................... 18 2.3.9. AT+QFSEEK Set File Pointer to a Position................................................................. 19 2.3.10. AT+QFPOSITION Get the Offset of a File Pointer...................................................... 20 2.3.11. AT+QFTUCAT Truncate a File from the File Pointer................................................... 20 2.3.12. AT+QFCLOSE Close a File......................................................................................... 21 2.3.13. AT+QFCRC Calculate the CRC of a Specified UFS File ............................................ 21 2.3.14. AT+QFCPY Make a Copy of a Specified File ............................................................. 22 3 Examples ............................................................................................................................................ 24 3.1. Upload and Download Files ...................................................................................................... 24 3.1.1. Upload a File .................................................................................................................. 24 3.1.2. Download a File ............................................................................................................. 25 3.2. Write to and Read Files ............................................................................................................ 25 3.2.1. Write to and Read a UFS File ........................................................................................ 25 3.2.2. Write to and Read an EUFS File.................................................................................... 25 4 Summary of Result Codes ................................................................................................................ 27 5 Appendix Reference .......................................................................................................................... 29 BG770A-GL&BG95xA-GL_FILE_Application_Note 4 / 29 LPWA Module Series Table Index Table 1: Types of AT Commands ................................................................................................................. 8 Table 2: Summary of Result Codes ........................................................................................................... 27 Table 3: Terms and Abbreviations .............................................................................................................. 29 BG770A-GL&BG95xA-GL_FILE_Application_Note 5 / 29 LPWA Module Series 1 Introduction Quectel BG770A-GL, BG950A-GL and BG951A-GL modules support AT commands for the operation of files on different physical storage mediums. This document is an application note to these commands. The supported storage mediums are: ⚫ UFS: User File Storage directory on the modem side; it is a special directory in the flash file system. ⚫ EUFS: Extended User File Storage on the application side. The file name indicates storage location. A file name beginning with the prefix 'UFS:' or without any prefix indicates that the file is in the UFS, while the one beginning with the prefix 'EUFS:' indicates that it is in the EUFS. 1.1. Using FILE AT Commands The general procedure for uploading/downloading, opening/creating, reading and writing to a file in the storage: Step 1: Upload a file to the storage with AT+QFUPL. If necessary, download the file with AT+QFDWL to verify its content, data integrity, etc. Step 2: Open the file with AT+QFOPEN. When the file is opened, you can write to it or read from it any time and from any location until the file is closed with AT+QFCLOSE. When opening a file with AT+QFOPEN, you can, for example, set the file into overwrite mode or read-only mode with parameter (see Chapter 2.3.6 for detailed information). After the file is opened, a is assigned to it, so that various file operations can be carried out. Step 3: After the file is opened, you can write to it with AT+QFWRITE or read the data content from the current file pointer position with AT+QFREAD. ⚫ You can set the file pointer position with AT+QFSEEK or query the current position with AT+QFPOSITION. ⚫ AT+QFTUCAT will truncate the file from the current position to the end of the file. Step 4: Close the file with AT+QFCLOSE, after which the becomes invalid. BG770A-GL&BG95xA-GL_FILE_Application_Note 6 / 29 Commonly used commands to manage files in the storage: 1) AT+QFLDS: Get storage space information. 2) AT+QFLST: List the file information in the specified storage. 3) AT+QFDEL: Delete the file(s) in the specified storage. LPWA Module Series 1.2. Description of Data Mode The COM port of the BG770A-GL, BG950A-GL and BG951A-GL modules has two working modes: AT command mode and data mode. In the AT command mode, the data inputted via the COM port are viewed as AT commands, whereas in the data mode, they are treated as data. ⚫ Enter Data Mode Execute AT+QFUPL, AT+QFDWL, AT+QFREAD or AT+QFWRITE to enter the data mode. If you input +++ or pull the MAIN_DTR pin up to make the port exit the data mode, the execution of these commands will be interrupted before the response is returned. In such a case, the COM port cannot re-enter the data mode if you execute ATO. ⚫ Exit Data Mode Input +++ or pull the MAIN_DTR pin up to make the COM port exit the data mode. To prevent the +++ from being misinterpreted as data, the following sequence should be followed: 1) Do not input any character for at least 1 second before and after inputting +++. 2) Input +++ within 1 second, and wait until OK is returned. Once OK is returned, the COM port exits the data mode and switches to AT command mode. If you are exiting the data mode by pulling the MAIN_DTR pin up, make sure to set AT&D1 first. BG770A-GL&BG95xA-GL_FILE_Application_Note 7 / 29 LPWA Module Series 2 Description of FILE AT Commands 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 1: Types of AT Commands Command Type Test Command Read Command Write Command Syntax Description AT+=? AT+? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. AT+=[,[,[...]]] Set user-definable parameter value. BG770A-GL&BG95xA-GL_FILE_Application_Note 8 / 29 Execution Command AT+ LPWA Module Series Return a specific information parameter or perform a specific action. 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 2.3. AT Command Description 2.3.1. AT+QFLDS Get Space Information of Storage Medium This command gets the space information of the specified storage medium. AT+QFLDS Get Space Information of Storage Medium Test Command AT+QFLDS=? Write Command AT+QFLDS= Response OK Response +QFLDS: , Execution Command AT+QFLDS Characteristics OK If there is an error related to the ME functionality: +CME ERROR: Response +QFLDS: , OK If there is any error: +CME ERROR: The command takes effect immediately; The configurations will not be saved. BG770A-GL&BG95xA-GL_FILE_Application_Note 9 / 29 LPWA Module Series Parameter String type. Storage medium type. 'UFS' UFS on modem side 'EUFS' Extended UFS on application side Integer type. Free space size of . Unit: byte. Integer type. Total size of . Unit: byte. Integer type. Size of all files in UFS. Unit: byte Integer type. Number of files in UFS. Integer type. Error code. See Chapter 4 for possible values. Example AT+QFLDS='UFS' +QFLDS: 1249984,1562624 OK AT+QFLST='*' +QFLST: 'Test1.txt',10 +QFLST: 'Test2.txt',16 +QFLST: 'Test3.txt',150 +QFLST: 'Test4.txt',2056 +QFLST: 'Test5.txt',98 OK AT+QFLDS +QFLDS: 2330,5 OK //Query the space information of UFS on modem side. //Query the size and number of all files in UFS. 2.3.2. AT+QFLST List File Information on Storage Medium This command lists the information of a single file or all files on a specified storage medium. AT+QFLST List File Information on Storage Medium Test Command AT+QFLST=? Write Command AT+QFLST= Response OK Response +QFLST: , [+QFLST: , […]] OK BG770A-GL&BG95xA-GL_FILE_Application_Note 10 / 29 LPWA Module Series Execution Command AT+QFLST Characteristics If there is any error: +CME ERROR: Response Return the information of UFS files: +QFLST: , [+QFLST: , […]] OK If there is any error: +CME ERROR: The command takes effect immediately; The configurations will not be saved. Parameter String type. File to be listed. '*' All files in UFS 'UFS:*' All files in UFS 'EUFS:/ufs/*' All files in the ufs directory of EUFS 'EUFS:/datatx/*' All files in the datatx directory of EUFS 'EUFS:*' All files in the ufs directory of EUFS '' A specified file in UFS 'UFS:' A specified file in UFS 'EUFS:' A specified file in ufs directory of EUFS 'EUFS:/ufs/' A specified file in ufs directory of EUFS 'EUFS:/datatx/' A specified file in datatx directory of EUFS String type. Exact name of file. Maximum length: 28 bytes. Integer type. File size. Unit: byte. Integer type. Error code. See Chapter 4 for possible values. Example AT+QFLST='*' +QFLST: 'F_M12-1.bmp',562554 +QFLST: 'F_M12-10.bmp',562554 +QFLST: 'F_M12-11.bmp',562554 OK AT+QFLST='Test1.txt' //List all files in UFS. //List a specified file 'Test1.txt' in UFS. BG770A-GL&BG95xA-GL_FILE_Application_Note 11 / 29 +QFLST: 'Test1.txt',2 OK AT+QFLST='EUFS:/ufs/*' +QFLST: 'EUFS:test.txt',10 +QFLST: 'EUFS:test2.txt',20 OK AT+QFLST='EUFS:test.txt' +QFLST: 'EUFS:test.txt',10 OK LPWA Module Series //List all files in ufs directory of EUFS . //List a specified file 'test.txt' in ufs directory of EUFS. 2.3.3. AT+QFDEL Delete File(s) on Storage Medium This command deletes a specified file or all files from a storage medium. AT+QFDEL Delete File(s) on Storage Medium Test Command AT+QFDEL=? Response +QFDEL: Write Command AT+QFDEL= OK Response OK Characteristics If there is any error: +CME ERROR: The command takes effect immediately; The configurations will not be saved. Parameter String type. Name of the file to be deleted. Maximum length: 28 bytes. '*' All files in UFS 'UFS:*' All files in UFS 'EUFS:/ufs/*' Delete all files in the ufs directory of EUFS (ufs directory remains) 'EUFS:/datatx/*' Delete all files in the datatx directory of EUFS (datatx directory remains) 'EUFS:*' Delete all files in the ufs directory of EUFS (ufs directory remains) 'UFS:' A specified file in UFS 'EUFS:' Delete a specified file in ufs directory of EUFS BG770A-GL&BG95xA-GL_FILE_Application_Note 12 / 29 LPWA Module Series 'EUFS:/ufs/' Delete a specified file in ufs directory of EUFS 'EUFS:/datatx/' Delete a specified file in datatx directory of EUFS String type. Exact name of file. Integer type. Error code. See Chapter 4 for possible values. Example AT+QFDEL='*' OK AT+QFDEL='Test1.txt' OK 2.3.4. AT+QFUPL Upload File to Storage Medium This command uploads a file to a storage medium. If any file on the storage medium has the same name as the uploaded file, an error will be reported. After the Write Command is executed and CONNECT is returned, the module will switch to the data mode. When the uploaded data reach , or if no other data are inputted when is reached, the module exits the data mode automatically. During data transmission, you can send +++ or pull the MAIN_DTR pin high to make the module exit the data mode. For more information, see Chapter 1.2. AT+QFUPL Upload File to Storage Medium Test Command AT+QFUPL=? Response +QFUPL: [,(1-)[,(range of supported s)[,(list of supported s)]]] Write Command AT+QFUPL=[,[, [,]]] OK Response CONNECT The TA switches to the data mode (transparent transmission mode), so the binary data of the file can be inputted. When the total size of the inputted data reaches or TA receives +++, TA will return to the command mode and report the following code: +QFUPL: , OK Characteristics If there is any error: +CME ERROR: The command takes effect immediately; BG770A-GL&BG95xA-GL_FILE_Application_Note 13 / 29 LPWA Module Series The configurations will not be saved. Parameter Integer type. Free space size of . See AT+QFLDS for more information about . String type. Name of the file to be uploaded. Maximum length: 28 bytes. '' Upload the file to UFS 'UFS:' Upload the file to UFS 'EUFS:' Upload the file to ufs directory of EUFS 'EUFS:/ufs/' Upload the file to ufs directory of EUFS 'EUFS:/datatx/' Upload the file to datatx directory of EUFS String type. The exact name of the file. Integer type. File size expected to be uploaded. Default value: 10240. Unit: byte. Maximum length is not greater than . Integer type. Actual size of uploaded data. Unit: byte. Integer type. Waiting time for inputting data to UART and USB. Range: 1–65535. Default value: 5. Unit: s. Integer type. Determines whether to use the ACK mode. 0 Turn ACK mode off. 1 Turn ACK mode on. Integer type. Checksum of uploaded data. Integer type. Error code. See Chapter 4 for possible values. NOTE 1. It is strongly recommended to use DOS 8.3 file name format for . 2. is a 16-bit checksum based on bitwise XOR. When the number of characters is odd, the last character is set as the high 8 bit, and the low 8 bit as 0, and then an XOR operator is used to calculate the checksum. Inputting +++ will make the TA end the data transmission and switch to the command mode. However, the previously uploaded data will be preserved in the file. 3. When executing the command, the data must be entered after CONNECT is returned. 4. The ACK mode is a safeguard against data loss when uploading a large file, if hardware flow control does not work. The ACK mode works as follows: 1) Run AT+QFUPL=,,,1 to enable the ACK mode. 2) The module outputs CONNECT. 3) The MCU sends 1 K bytes of data, to which the modules respond with an A. 4) The MCU receives the A and then sends the next 1 K bytes of data. 5) Steps 3 and 4 are repeated until the transfer is completed. For an example of ACK mode use, see Chapter 3.1.1.2 BG770A-GL&BG95xA-GL_FILE_Application_Note 14 / 29 LPWA Module Series 5. Due to the physical limitations of the platform, i.e., write speed to the NOR flash memory, the upload feature has 2 operational modes to guarantee that the entire file will be written without data loss. Two modes are: 1) without activated HW flow control 2) with activated HW flow control. 1) When the HW flow control is not activated, the maximum file size is limited to 200000 bytes. Attempting to send files larger than that will result in an error. Writing time can significantly vary depending on file size, content, and area of the flash where the file is being written. 2) When HW flow control is activated, by executing AT+IFC=2,2, there is no file size limitation other than the available disk space. To ensure safe file transfer in this mode, on the client side, RTS and CTS must be switched on before sending the file. Transmission time can be longer than in the mode without activated HW flow control. 2.3.5. AT+QFDWL Download File from Storage Medium This command downloads a specified file from a storage medium. AT+QFDWL Download File from Storage Medium Test Command AT+QFDWL=? Response +QFDWL: Write Command AT+QFDWL= OK Response CONNECT The TA switches to the data mode, so the binary data of the file can be outputted. When the content of the file is read or the TA receives +++, the TA will return to the command mode and report the following code:: +QFDWL: , OK Characteristics If there is any error: +CME ERROR: The command takes effect immediately; The configurations will not be saved. Parameter String type. Name of the file to be downloaded. Maximum length: 28 bytes. '' Download the file from UFS 'UFS:' Download the file from UFS 'EUFS: Download the file from the ufs directory of EUFS 'EUFS:/ufs/' Download the file from the ufs directory of EUFS 'EUFS:/datatx/' Download the file from the datatx directory of EUFS BG770A-GL&BG95xA-GL_FILE_Application_Note 15 / 29 LPWA Module Series String type. The exact name of the file. Integer type. Size of downloaded data. Unit: byte. Integer type. Checksum of downloaded data. Integer type. Error code. See Chapter 4 for possible values. NOTE 1. Inputting +++ causes the TA to end the data transmission and switch to the command mode. 2. is a 16-bit checksum based on bitwise XOR. 2.3.6. AT+QFOPEN Open a File This command opens a file and gets the file handle to be used in commands such as AT+QFREAD, AT+QFWRITE, AT+QFSEEK, AT+QFPOSITION, AT+QFTUCAT and AT+QFCLOSE. AT+QFOPEN Open a File Test Command AT+QFOPEN=? Response +QFOPEN: [,(range of supported s)] Read Command AT+QFOPEN? OK Response +QFOPEN: ,, [+QFOPEN: ,, […]] Write Command AT+QFOPEN=[,] OK Response +QFOPEN: OK Characteristics If there is any error: +CME ERROR: The command takes effect immediately; The configurations will not be saved. Parameter String type. Name of the file to be opened. Maximum length: 28 bytes. '' Open the file in UFS 'UFS:' Open the file in UFS 'EUFS:' Open the file of the ufs directory of EUFS. BG770A-GL&BG95xA-GL_FILE_Application_Note 16 / 29 LPWA Module Series 'EUFS:/ufs/' Open the file of the ufs directory of EUFS 'EUFS:/datatx/' Open the file of the datatx directory of EUFS String type. The exact name of the file. Integer type. Handle of the file to be used. Integer type. File opening mode. 0 If the file does not exist, it is created. If the file exists, it is opened directly. In both cases, the file can be read and written to. 1 If the file does not exist, it is created. If the file exists, it is overwritten. In both cases, the file can be read and written to. 2 If the file exists, it is opened directly as a read-only file. Otherwise, an error is returned. 3 If the file does not exist, it is created. If the file exists, data are appended at the end of the file. In both cases, the file can be read and written to. Integer type. Error code. See Chapter 4 for possible values. NOTE starts form 0 in UFS, whereas it starts from 20000 in EUFS. 2.3.7. AT+QFREAD Read a File This command reads the data of a file specified by the file handle. The data start from the current position of the file pointer that belongs to the file handle. AT+QFREAD Read a File Test Command AT+QFREAD=? Response +QFREAD: [] Write Command AT+QFREAD=[] OK Response CONNECT The TA switches to the data mode. When the total size of the data reaches (unit: byte), the TA will go back to the command mode, display the result and report the following code: OK Characteristics If there is any error: +CME ERROR: The command takes effect immediately; The configurations will not be saved. BG770A-GL&BG95xA-GL_FILE_Application_Note 17 / 29 LPWA Module Series Parameter Integer type. Handle of the file to be read. Integer type. Length of the file to be read. Default value: file length. Unit: byte. Integer type. Actual read length. Unit: byte. Integer type. Error code. See Chapter 4 for possible values. 2.3.8. AT+QFWRITE Write to a File This command writes data into a file. The data start from the current position of the file pointer that belongs to the file handle. AT+QFWRITE Write to a File Test Command AT+QFWRITE=? Response +QFWRITE: [[,]] Write Command AT+QFWRITE=[[,]] OK Response CONNECT The TA switches to the data mode. When the total size of the written data reaches (unit: byte) or the time reaches , the TA will go back to the command mode and report the following code: +QFWRITE: , OK Characteristics If there is any error: +CME ERROR: The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be written to. Integer type. Length of the file to be written to. Maximum value of this parameter is determined by of AT+QFUPL. Default value: 10240. Unit: byte. Integer type. Waiting time for inputting data to USB/UART. Range: 1–65535. Default value: 5. Unit: s. Integer type. Actual written length. Unit: byte. Integer type. Total file length. Unit: byte. Integer type. Error code. See Chapter 4 for possible values. BG770A-GL&BG95xA-GL_FILE_Application_Note 18 / 29 LPWA Module Series NOTE 1. Due to the physical limitations of the platform, i.e., write speed to the NOR flash memory, write feature has 2 operational modes to guarantee that the entire file will be written without data loss. Two modes are: 1) without activated HW flow control 2) with activated HW flow control. 1) If the HW flow control is not activated, the maximum file size is limited to 200000 bytes. Attempting to send files larger than that will result in an error. Writing time can vary significantly depending on file size, content, and area of the flash where the file is being written. 2) When HW flow is activated, by executing AT+IFC=2,2, there is no file size limitation other than the available disk space. To ensure safe file transfer in this mode, on the client side, the RTS and CTS must be switched on before sending the file. Transmission time can be longer than in the mode without activated HW flow control. 2.3.9. AT+QFSEEK Set File Pointer to a Position This command sets a file pointer to a specified position. This will decide the starting position of commands such as AT+QFREAD, AT+QFWRITE, AT+QFPOSITION and AT+QFTUCAT. AT+QFSEEK Set File Pointer to a Position Test Command AT+QFSEEK=? Response +QFSEEK: ,[,] Write Command AT+QFSEEK=,[,< position>] Characteristics OK Response OK If there is any error: +CME ERROR: The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file for which a pointer is set. Integer type. Number of bytes of the file pointer movement. Integer type. Pointer movement mode. 0 Move forward from the beginning of the file. 1 Move forward from the current position of the pointer. 2 Move backward from the end of the file. Integer type. Error code. See Chapter 4 for possible values. BG770A-GL&BG95xA-GL_FILE_Application_Note 19 / 29 LPWA Module Series NOTE 1. If =0/2 and exceed the file size, the command returns ERROR. 2. If =1 and the total size of and the current position of the pointer exceeds the file size, the command returns ERROR. 2.3.10. AT+QFPOSITION Get Offset of File Pointer This command gets the offset of a file pointer from the beginning of the file. AT+QFPOSITION Get Offset of File Pointer Test Command AT+QFPOSITION=? Response +QFPOSITION: Write Command AT+QFPOSITION= OK Response +QFPOSITION: OK Characteristics If there is any error: +CME ERROR: The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file for which the offset of file pointer is to be gotten. Integer type. Offset from the beginning of the file. Integer type. Error code. See Chapter 4 for possible values. 2.3.11. AT+QFTUCAT Truncate File from File Pointer This command truncates the file from the current pointer position to the end of the file. AT+QFTUCAT Truncate File from File Pointer Test Command AT+QFTUCAT=? Response +QFTUCAT: Write Command AT+QFTUCAT= OK Response OK BG770A-GL&BG95xA-GL_FILE_Application_Note 20 / 29 LPWA Module Series Characteristics If there is any error: +CME ERROR: The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be truncated. Integer type. Error code. See Chapter 4 for possible values. 2.3.12. AT+QFCLOSE Close a File This command closes a file and ends all file operations. After that, the file handle is released and should not be used again, unless the file is re-opened with AT+QFOPEN. AT+QFCLOSE Close a File Test Command AT+QFCLOSE=? Response +QFCLOSE: Write Command AT+QFCLOSE= OK Response OK Characteristics If there is any error: +CME ERROR: The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be closed. Integer type. Error code. See Chapter 4 for possible values. 2.3.13. AT+QFCRC Calculate CRC of a Specified UFS File This command calculates the CRC16, CRC16_CCITT and CRC32 checksums of a specified UFS file. AT+QFCRC Calculate CRC of a Specified UFS File Test Command AT+QFCRC=? Response +QFCRC: BG770A-GL&BG95xA-GL_FILE_Application_Note 21 / 29 LPWA Module Series Write Command AT+QFCRC= Characteristics OK Response When the specified file exists, the command returns 32-bit CRC, 16-bit CRC values and 16-bit CRC CCITT: +QFCRC: ,, OK When the file exists but has no bytes: +QFCRC: 0,0,0 If there is any error: +CME ERROR: The command takes effect immediately; The configurations will not be saved. Parameter String type. Input format: 'UFS:filename'. 'UFS:' can be omitted. 32-bit CRC value. 16-bit CRC value. 16-bit CRC CCITT value. Integer type. Error code. See Chapter 4 for possible values. NOTE This command applies to UFS files only. 2.3.14. AT+QFCPY Make a Copy of a Specified File This command copies the whole content of a source file to a destination file. ⚫ If the destination file already exists, the command returns an ERROR unless =1. ⚫ If the destination file has the same name as the source file, the command returns an ERROR. ⚫ If the remaining space of the file system is smaller than the file size to be copied, the command also returns an ERROR. AT+QFCPY Make a Copy of a Specified File Test Command AT+QFCPY=? Response +QFCPY: ,[,] BG770A-GL&BG95xA-GL_FILE_Application_Note 22 / 29 LPWA Module Series OK Write Command AT+QFCPY=,[,] Response OK Characteristics If there is any error: +CME ERROR: The command takes effect immediately; The configurations will not be saved. Parameter String type. Source file name. Input format: 'UFS:filename'. 'UFS:' can be omitted. String type. Destination file name. Input format: 'UFS:filename'. 'UFS:' can be omitted. Integer type. Determines whether to overwrite the existing file that has the same name as the destination file. 0 Disable 1 Enable Integer type. Error code. See Chapter 4 for possible values. NOTE This command applies to UFS files only. BG770A-GL&BG95xA-GL_FILE_Application_Note 23 / 29 LPWA Module Series 3 Examples 3.1. Upload and Download Files 3.1.1. Upload a File 3.1.1.1. Non-ACK Mode AT+QFUPL='test1.txt',10 CONNECT +QFUPL: 10,3938 OK AT+QFUPL='EUFS:test.txt',4 CONNECT +QFUPL: 4,6a05s OK //Upload the text file 'test1.txt' to UFS. //Upload the text file 'test.txt' to ufs directory of EUFS. 3.1.1.2. ACK Mode The ACK mode can make data transmission more reliable. When transmitting a large file without hardware flow control, the ACK mode is recommended to prevent the data loss. For more information about the ACK mode, see AT+QFUPL. AT+QFUPL='test.txt',3000,5,1 CONNECT A A //Upload the text file 'test.txt' to UFS. //After receiving 1024 bytes of data, the module returns A. Then the next 1024 bytes of data can be inputted. BG770A-GL&BG95xA-GL_FILE_Application_Note 24 / 29 +QFUPL: 3000,B34A OK 3.1.2. Download a File AT+QFDWL='test.txt' CONNECT +QFDWL: 10,613e OK LPWA Module Series //Download the text file 'test.txt' from UFS. //Size and checksum value of the downloaded data are returned. 3.2. Write to and Read Files 3.2.1. Write to and Read a UFS File AT+QFOPEN='test',0 +QFOPEN: 0 //Open the file to get the file handle. OK AT+QFWRITE=0,10 CONNECT +QFWRITE: 10,10 //Write 10 bytes to the file. //The actual written bytes and the size of the file are returned. OK AT+QFSEEK=0,0,0 OK AT+QFREAD=0,10 CONNECT 10 //Set the file pointer to the beginning of the file. //Read 10 bytes from the file. OK AT+QFCLOSE=0 OK //Close the file. 3.2.2. Write to and Read an EUFS File AT+QFLDS='EUFS' +QFLDS: 1388544,2435072 //Query the space information of EUFS. BG770A-GL&BG95xA-GL_FILE_Application_Note 25 / 29 OK AT+QFOPEN='EUFS:test',0 +QFOPEN: 20000 OK AT+QFWRITE=20000,10 CONNECT +QFWRITE: 10,10 OK AT+QFSEEK=20000,0,0 OK AT+QFREAD=20000,10 CONNECT 10 OK AT+QFCLOSE=20000 OK LPWA Module Series //Open the file to get the file handle. //Write 10 bytes to the file. //The actual written bytes and the size of the file are returned. //Set the file pointer to the beginning of the file. //Read 10 bytes from the file. //Close the file. BG770A-GL&BG95xA-GL_FILE_Application_Note 26 / 29 LPWA Module Series 4 Summary of Error Codes The error code indicates an error related to mobile equipment. The detailed information about is presented in the following table, which includes only the error codes related to the file operation of the module. Table 2: Summary of Error Codes 400 401 402 403 405 406 407 409 410 411 413 414 416 417 418 419 Meaning Invalid input value Larger than the size of the file Zero-byte read Drive full File not found Invalid file name File already exists Failed to write to the file Failed to open the file Failed to read the file Reached the max. number of files allowed to be opened The read-only file Invalid file descriptor Failed to list the file Failed to delete the file Failed to get disk info BG770A-GL&BG95xA-GL_FILE_Application_Note 27 / 29 LPWA Module Series 420 No space 421 Time-out 423 File too large 425 Invalid parameter 426 File already opened 427 Failed to allocate memory. If the file size is >200KB, IFC: 2,2 must be used 428 Maximum allowed number of files on the drive exceeded BG770A-GL&BG95xA-GL_FILE_Application_Note 28 / 29 LPWA Module Series 5 Appendix Reference Table 3: Terms and Abbreviations Abbreviation ACK COM CRC DOS EUFS MCU ME TA UART UFS USB XOR Description Acknowledgement Communication Port Cyclic Redundancy Check Disk Operating System Extended User File Storage Microprogrammed Control Unit Mobile Equipment Terminal Adapter Universal Asynchronous Receiver/Transmitter User File Storage Universal Serial Bus Exclusive OR BG770A-GL&BG95xA-GL_FILE_Application_Note 29 / 29
307.05 KB
BG77xA-GL&BG95xA-GL Positioning over LTE Application Note LPWA Module Series Version: 1.0 Date: 2022-03-11 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 1 / 33 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 2 / 33 LPWA Module Series About the Document Revision History Version 1.0 Date 2020-10-29 2022-03-11 Author Mladen VUKOVIC Mladen VUKOVIC Description Creation of the document First official release BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 3 / 33 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 1.1. Special Mark .............................................................................................................................. 7 2 Polte AT Commands........................................................................................................................... 8 2.1. AT Command Introduction ......................................................................................................... 8 2.1.1. Definitions........................................................................................................................ 8 2.1.2. AT Command Syntax ...................................................................................................... 8 2.2 Declaration of AT Command Examples .................................................................................... 9 2.3 Description of Polte AT Commands........................................................................................... 9 2.3.1 AT+QPOLTECFG Configure Parameters of Polte SR Feature ................................... 9 2.3.1.1 AT+QPOLTECFG='service' Enable/Disable Polte SR Service ....................... 9 2.3.1.2 AT+QPOLTECFG='polteev' Enable/Disable Polte SR URCs........................ 10 2.3.1.3 AT+QPOLTECFG='register' Initiate Registration to Polte Server.................. 12 2.3.1.4 AT+QPOLTECFG='serverauth' Provide UE with Authentication Parameters13 2.3.1.5 AT+QPOLTECFG='mqttconfig' Set MQTT Configuration.............................. 13 2.3.2 AT+QPOLTE Trigger Polte SR Functionality ............................................................. 14 2.3.2.1 AT+QPOLTE='aux' Update Compressed Binary Auxiliary Data.................... 15 2.3.2.2 AT+QPOLTE='crs' Capture and Save CRS Symbols.................................... 16 2.3.2.3 AT+QPOLTE='compress' Capture, Compress and Save CRS Symbols ...... 17 2.3.2.4 AT+QPOLTE='ver' Request Version.............................................................. 18 2.3.2.5 AT+QPOLTE='report' Send Report................................................................ 19 2.3.2.6 AT+QPOLTE='locate' Capture, Compress and Send CRS Symbols ............ 20 2.3.2.7 AT+QPOLTE='getreg' Get Registration Parameters ..................................... 21 2.3.3 AT+QPOLTECRCFG Configure Parameters of Polte CR Feature............................ 22 2.3.4 AT+QPOLTECR Send Polte CR Location Request................................................... 23 3 Description of URCs ......................................................................................................................... 24 3.1. +QPOLTEEVU: 'CRS' Notify CRS Symbol Capture Event.................................................. 24 3.2. +QPOLTEEVU: 'COMPRESS' Notify CRS Data Compression Event ................................ 25 3.3. +QPOLTEEVU: 'REGISTER' Notify Polte Server Registration Event ................................. 25 3.4. +QPOLTEEVU: 'LOCATION' Notify Result of SR Location Reception from Polte Server .. 26 3.5. +QPOLTEEVU: 'ALLOWSTAT' Notify Change in Applicability of Polte Service ................. 27 3.6. +QPOLTECR Notify Result of CR Location Reception from Polte Server ........................... 27 4 Examples ........................................................................................................................................... 29 4.1 Polte SR Example .................................................................................................................... 29 4.2 Polte CR Example.................................................................................................................... 31 5 Appendix References ....................................................................................................................... 32 BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 4 / 33 LPWA Module Series Table Index Table 1: Applicable Modules ........................................................................................................................ 6 Table 2: Special Mark................................................................................................................................... 7 Table 3: Types of AT Commands ................................................................................................................ 8 Table 4: Related Documents...................................................................................................................... 32 Table 5: Terms and Abbreviations ............................................................................................................. 32 BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 5 / 33 LPWA Module Series 1 Introduction This document describes AT commands associated with the Positioning Over LTE (Polte) feature of Quectel LPWA modules. Polte Compression Engine (CE) embedded in the cellular modem leverages the Cell-specific Reference Signals (CRS) to offer the highest level of location accuracy. The device itself does not do any computing. It sends a sample of the LTE signals to the Polte cloud, and then the location is calculated by the server. Polte offers two location positioning services, Polte SuperRes (SR) and Polte CoreRes (CR) depending on the configuration and capability of the device. Polte SR provides higher level of accuracy than that of Polte CR, but it can only be utilized when eMTC (Cat M1) is in use. On the other hand, Polte CR is available on both radio access technologies (eMTC and NB-IoT). Internally, Quectel's implementations of Polte SR and Polte CR differ in how they send data to Polte server. Polte SR uses MQTT protocol while Polte CR utilizes HTTP. The AT commands are grouped into two categories, one supporting the SuperRes and the other supporting CoreRes. AT commands AT+QPOLTECFG and AT+QPOLTE (Chapter 2.3.1 and Chapter 2.3.2) support Polte SR, while AT+QPOLTECRCFG and AT+QPOLTECR (Chapter 2.3.3 and Chapter 2.3.4) support Polte CR. Table 1: Applicable Modules Module Series BG77xA-GL BG95xA-GL Model BG770A-GL BG772A-GL BG950A-GL BG951A-GL BG952A-GL* BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 6 / 33 1.1. Special Mark LPWA Module Series Table 2: Special Mark Mark * Definition Unless otherwise specified, when an asterisk (*) is used after a function, feature, interface, pin name, AT command, or argument, it indicates that the function, feature, interface, pin, AT command, or argument is under development and currently not supported; and the asterisk (*) after a model indicates that the sample of the model is currently unavailable. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 7 / 33 LPWA Module Series 2 Polte AT Commands 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 3: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 8 / 33 LPWA Module Series 2.2 Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 2.3 Description of Polte AT Commands 2.3.1 AT+QPOLTECFG Configure Parameters of Polte SR Feature This command configures parameters for using Polte SR service. In addition, it enables SR URCs and configures MQTT settings. AT+QPOLTECFG Configure Parameters of Polte SR Feature Test Command AT+QPOLTECFG=? Response +QPOLTECFG: 'service',(list of supported s) +QPOLTECFG: 'polteev',(list of supported s),(list of supported s) +QPOLTECFG: 'register' +QPOLTECFG: 'serverauth' +QPOLTECFG: 'mqttconfig',,(list of supported s) Maximum Response Time OK 300 ms 2.3.1.1 AT+QPOLTECFG='service' Enable/Disable Polte SR Service This command enables or disables Polte SR service. AT+QPOLTECFG='service' Enable/Disable Polte SR Service Write Command Response AT+QPOLTECFG='service'[,] +QPOLTECFG: 'service', OK BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 9 / 33 LPWA Module Series Maximum Response Time Characteristics If the optional parameter is specified, configure Polte service. OK Or ERROR 300 ms The command takes effect after the module is rebooted. The configuration is saved automatically. Parameter Integer type. 0 Disable Polte SR service 1 Enable Polte SR service Example AT+QPOLTECFG='service' +QPOLTECFG: 'service',1 //Query if Polte SR is activated. OK AT+QPOLTECFG='service',0 OK //Disable Polte SR service. 2.3.1.2 AT+QPOLTECFG='polteev' Enable/Disable Polte SR URCs This command enables or disables Polte SR related unsolicited result codes. The URCs are used to notify the host of the information from Polte SR application. The value 'ALL' of activates or deactivates all events. AT+QPOLTECFG='polteev' Enable/Disable Polte SR URCs Write Command AT+QPOLTECFG='polteev'[,,] Response If the optional parameters are omitted, query the current settings for all events. +QPOLTECFG: 'polteev': 'CRS',,'COMPRESS ',,'REGISTER',,'LOCATION',,'ALLOWSTAT', OK If the optional parameters are specified, configure Polte BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 10 / 33 LPWA Module Series Maximum Response Time Characteristics URCs. OK Or ERROR 300 ms The command takes effect immediately. The configuration is not saved. Parameter String type. Indicates Polte SR URCs beginning with +QPOLTEEVU:. For details of the URCs, see Chapter 3. 'ALL' Enables or disables all events 'CRS' Event reported for an attempt to capture CRS symbols, triggered by AT+QPOLTE='crs', AT+QPOLTE='compress' or AT+QPOLTE='locate' 'COMPRESS' Event reported for an attempt to compress CRS data, triggered by AT+QPOLTE='compress' or AT+QPOLTE='locate' 'REGISTER' Event reported for an attempt to register to Polte server, triggered by AT+QPOLTE='register' 'LOCATION' Event reported for result of location reception from Polte server, triggered by AT+QPOLTE='report' or AT+QPOLTE='locate' 'ALLOWSTAT' Event reported for a change in applicability of Polte SR service Integer type. 0 Disable URC 1 Enable URC Example AT+QPOLTECFG='polteev' //Query URC configuration, i.e., shows which URCs are enabled. +QPOLTECFG: 'polteev': 'CRS',0,'COMPRESS',0,'REGISTER',0,'LOCATION',0,'ALLOWSTA T',0 OK AT+QPOLTECFG='polteev','all',1 OK //Enable all URCs. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 11 / 33 LPWA Module Series 2.3.1.3 AT+QPOLTECFG='register' Initiate Registration to Polte Server This command initiates registration to the Polte server using UE parameters. AT+QPOLTECFG='register' Initiate Registration to Polte Server Write Command AT+QPOLTECFG='register' Response +QPOLTECFG: 'REGISTER', Maximum Response Time Characteristics OK Or ERROR 300 ms The command takes effect immediately. The configuration is saved automatically. Parameter Integer type. 0 Success 1 No response from server 12 Operation failure Example AT+QPOLTECFG='register' +QPOLTECFG: 'REGISTER',0 OK //In order to get following URC, corresponding event must be enabled. +QPOLTEEVU: 'REGISTER',0,'PhFRuPUIlnh','xkfgGgmesCK' NOTE 1. Registration to the Polte server (AT+QPOLTECFG='register') is executed only once when Polte SR feature is used for the first time. 2. If the registration was successful, the URC +QPOLTEEVU: 'REGISTER' will be received along with MQTT credentials that are used for further server authorization. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 12 / 33 LPWA Module Series 2.3.1.4 AT+QPOLTECFG='serverauth' Provide UE with Authentication Parameters This command provides the UE with authentication parameters required for successful sending of the compressed binary data to the Polte server. The command is used for renewing server authorization after the module reboots or wakes up from PSM and e-I-DRX modes. Before using the command for the first time, it is necessary to register the device with AT+QPOLTECFG='register'. AT+QPOLTECFG='serverauth' Provide UE with Authentication Parameters Write Command AT+QPOLTECFG='serverauth' Response OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. The configuration is not saved. Example AT+QPOLTECFG='serverauth' OK NOTE 1. Registration to the Polte server (AT+QPOLTECFG='register') is done only once when Polte SR feature is used for the first time, while server authorization (AT+QPOLTECFG='serverauth') is necessary each time the module reboots or wakes up from PSM and e-I-DRX modes. 2. In case of unsuccessful authorization or an error, it is necessary to execute AT+QPOLTECFG='register' again in order to renew MQTT credentials used for authorization. 2.3.1.5 AT+QPOLTECFG='mqttconfig' Set MQTT Configuration This command configures MQTT parameters. AT+QPOLTECFG='mqttconfig' Set MQTT Configuration Write Command AT+QPOLTECFG='mqttconfig',, Response OK Or ERROR BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 13 / 33 LPWA Module Series Maximum Response Time Characteristics 300 ms The command takes effect immediately. The configuration is not saved. Parameter Integer type. Duration of a timer to allow MQTT session before clearing Polte client session parameters. Range: 5–60. Default value: 25. Unit: s. Integer type. 0 Do not disconnect from MQTT server if timer expires 1 Disconnect from MQTT server if timer expires 2.3.2 AT+QPOLTE Trigger Polte SR Functionality This command triggers Polte SR functionality. AT+QPOLTE Trigger Polte SR Functionality Test Command AT+QPOLTE=? Response +QPOLTE: 'aux' +QPOLTE: 'crs',(range of supported ),(list of supported s) +QPOLTE: 'compress',(range of supported ), (list of supported s) +QPOLTE: 'ver' +QPOLTE: 'report', (list of supported s), +QPOLTE: 'locate',(range of supported ),(list of supported s) +QPOLTE: 'getreg' Maximum Response Time Characteristics OK 300 ms The command takes effect immediately. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 14 / 33 LPWA Module Series 2.3.2.1 AT+QPOLTE='aux' Update Compressed Binary Auxiliary Data This command gets auxiliary data (including RTTD field) and updates it into compressed binary data. The command is applied when sending data to Polte server in ways other than using AT+QPOLTE='report', and has to be executed in RRC connected state. When sending data to the server through AT+QPOLTE='report', RTTD value is added to Polte compressed data and sent along with it to the server automatically. When sending data to the server by other means, you can execute AT+QPOLTE='aux' to connect to the network to get RTTD value and send the resultant data to the server immediately; or you can send the data without RTTD value with degraded accuracy. AT+QPOLTE='aux' Update Compressed Binary Auxiliary Data Write Command AT+QPOLTE='aux' Response +QPOLTE: 'AUX', Maximum Response Time Characteristics OK Or ERROR 300 ms The command takes effect immediately. Parameter Integer type. 0 Success. Serving cell remains unchanged 1 Success. Serving cell has changed 2 No compressed file 3 RTTD is unavailable 4 Not enough memory 5 Error in file reading 6 Error in writing into file 7 Error in getting auxiliary data 8 RTTD is already present in auxiliary data Example AT+QPOLTE='aux' +QPOLTE: 'AUX',0 OK BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 15 / 33 LPWA Module Series 2.3.2.2 AT+QPOLTE='crs' Capture and Save CRS Symbols This command captures CRS symbols and saves the results to the file system. It’s for debugging purpose and is not supposed to be sent to the Polte server. AT+QPOLTE='crs' Capture and Save CRS Symbols Write Command AT+QPOLTE='crs',, Response +QPOLTE: 'CRS', OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. Parameter Integer type. Number of frames for capturing CRS symbols. 0 Cancel CRS capture 1 Capture CRS symbols of 1 frame 2 Capture CRS symbols of 2 contiguous frames Integer type. 0 Save CRS symbols without waiting for RRC connected state 1 Wait for RRC connected state and get RTTD value before saving CRS symbols to file system Integer type. 0 Success 1 Invalid modem state 2 Wrong number of frames to capture 3 Not enough memory 4 Pending response from modem 5 Retrying capture attempt (previously buffered by application). It will try 3 times before it fails 7 Device ID unavailable 8 Capture attempt delayed due to ongoing paging 9 Flash read/write failure 12 A preceding operation has failed 13 Invalid RAT in use BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 16 / 33 LPWA Module Series Example AT+QPOLTE='crs',2,1 +QPOLTE: 'CRS',0 OK //To get the following URC, the corresponding event must be enabled +QPOLTEEVU: 'CRS',0,'863593050015320','0x10',544,5,'0x20f0d',395,6400,4,80,109,'b:/Polte/ polte-unpack' 2.3.2.3 AT+QPOLTE='compress' Capture, Compress and Save CRS Symbols This command captures CRS symbols, compresses them using the Compression-Engine (CE) and saves the results to the file system. AT+QPOLTE='compress' Capture, Compress and Save CRS Symbols Write Command AT+QPOLTE='compress',[,] Response +QPOLTE: 'COMPRESS', OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. Parameter Integer type. Number of frames for capturing CRS symbols. 0 Cancel CRS capture 1 Capture CRS symbols of 1 frame 2 Capture CRS symbols of 2 contiguous frames Integer type. 0 Save CRS symbols without waiting for RRC connected state 1 Wait for RRC connected state and get RTTD value before saving CRS symbols to file system Integer type. 0 Success 1 Invalid modem state 2 Wrong number of frames to capture BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 17 / 33 LPWA Module Series 3 Not enough memory 4 Pending response from modem 5 Retrying capture attempt (previously buffered by application). It will try 3 times before it fails 7 Device ID unavailable 8 Capture attempt delayed due to ongoing paging 9 Flash read/write failure 12 A preceding operation has failed 13 Invalid RAT in use Example AT+QPOLTE='compress',2,0 +QPOLTE: 'COMPRESS',0 OK // To get the following URCs, corresponding events must be enabled +QPOLTEEVU: 'CRS',0,'863593050015320','0x10',544,5,'0x20f0d',395,6400,4,80,652 +QPOLTEEVU: 'COMPRESS',0,1652,'b:/Polte/polte-compress' NOTE RTTD value is added by default when using AT+QPOLTE='report' and AT+QPOLTE='aux', thus there is no need to wait for RRC connected state when executing AT+QPOLTE='compress'. 2.3.2.4 AT+QPOLTE='ver' Request Version This command requests the versions of the Polte application and CE. AT+QPOLTE='ver' Write Command AT+QPOLTE='ver' Request Version Response +QPOLTE: 'VER',, Maximum Response Time Characteristics OK Or ERROR 300 ms The command takes effect immediately. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 18 / 33 Parameter String type. Polte application version. String type. CE version. Example AT+QPOLTE='ver' +QPOLTE: 'VER','1.0.0','1.1.13' OK LPWA Module Series 2.3.2.5 AT+QPOLTE='report' Send Report This command sends a report including compressed binary data and RTTD value to the Polte server. AT+QPOLTE='report' Send Report Write Command AT+QPOLTE='report',[,] Response OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. Parameter Integer type. 0 URC +QPOLTEEVU: 'LOCATION' is not expected, client shall disconnect from server immediately after data are sent. 1 URC +QPOLTEEVU: 'LOCATION' is expected, client shall not disconnect from server until the URC is received. String type. Optional path for sending file. By default, compressed binary data is stored at the directory b:/Polte/polte-compress (which is a path to store data after executing AT+QPOLTE='compress'), which will be used as a default file path for AT+QPOLTE='report'. In other cases, if user wants to send a file which is located at other locations on the disk, then the file path of other locations should be given accordingly. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 19 / 33 LPWA Module Series Example AT+QPOLTE='report',1 OK //To get the following URC, the corresponding event must be enabled +QPOLTEEVU: 'LOCATION',0,'44.823246574123395','20.413992050537633','1642512945','200' 2.3.2.6 AT+QPOLTE='locate' Capture, Compress and Send CRS Symbols This command combines the functions of AT+QPOLTE='compress' and AT+QPOLTE='report' into one action, which can reduce the need to save compressed data (i.e., the output of AT+QPOLTE='compress') to flash and read them before sending them to server. The command captures CRS symbols, compresses them and sends the results to server. AT+QPOLTE='locate' Capture, Compress and Send CRS Symbols Write Command AT+QPOLTE='locate',, Response +QPOLTE: 'LOCATE', OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. Parameter Integer type. Number of frames for capturing CRS symbols. 0 Cancel CRS capture 1 Capture CRS symbols of 1 frame 2 Capture CRS symbols of 2 contiguous frames Integer type. 0 Don't request to get location back 1 Request to get location back to the device after it has been generated by the server Integer type. 0 Success 1 Invalid modem state 2 Wrong number of frames to capture 3 Not enough memory BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 20 / 33 LPWA Module Series 4 Pending response from modem 5 Retrying capture attempt (previously buffered by application). It will try 3 times before it fails 7 Device ID unavailable 8 Capture attempt delayed because of ongoing paging 9 Flash read/write failure 10 Successful positioning during PSM 11 Unsuccessful positioning during PSM 12 A preceding operation failure 13 Invalid RAT in use Example AT+QPOLTE='locate',2,1 +QPOLTE: 'LOCATE',0 OK //To get the following URCs, corresponding events must be enabled. +QPOLTEEVU: 'CRS',0,'863593050015320','0x10',544,5,'0x20f0d',395,6400,4,80,133 +QPOLTEEVU: 'COMPRESS',0,906 +QPOLTEEVU: 'LOCATION',0,'44.82272508613134','20.414680280163452','1642512945', '149.60' 2.3.2.7 AT+QPOLTE='getreg' Get Registration Parameters This command provides UE with specific parameters needed to register the UE to the Polte server. AT+QPOLTE='getreg' Get Registration Parameters Write Command AT+QPOLTE='getreg' Response +QPOLTE: 'GETREG',,, , Maximum Response Time Characteristics OK Or ERROR 300 ms The command takes effect immediately. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 21 / 33 LPWA Module Series Parameter String type. Manufacturer token. Maximum size: 20 characters. String type. Model token. Maximum size: 20 characters. String type. Decimal format indicating device IMEI number. String type. Unique modem token. Maximum size: 256 characters. Example AT+QPOLTE='getreg' +QPOLTE: GETREG','a3de2b6e510','dc6a91c7883','863593050015320','ALT12508B9933A0C6 4505BE3FFE553B5FA3EFB3' OK 2.3.3 AT+QPOLTECRCFG Configure Parameters of Polte CR Feature This command configures parameters for using Polte CR service. Data is sent to the Polte server by using HTTP protocol in Polte CR service. Thus, it needs parameters such as Customer ID and API Token for setting HTTP URL and HTTP authorization process. The Customer ID and API Token can be acquired from Polte company upon registration, see Chapter 4.2 for details. AT+QPOLTECRCFG Configure Parameters of Polte CR Feature Write Command AT+QPOLTECRCFG= , Response OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. The configuration is saved. Parameter String type. Customer ID used for setting HTTP URL. String type. API token used for HTTP authorization. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 22 / 33 LPWA Module Series Example AT+QPOLTECRCFG='5fff4ee770e961101864cb1a','8d5d837a97f27f7da84264e5ad1ac24644c2a6 68256fa38a41a1ebf29a09eba34' OK 2.3.4 AT+QPOLTECR Send Polte CR Location Request This command sends Polte CR location request to Polte server. Internally, this command is executed in two phases. Firstly, it collects cell related data. After gathering all necessary data, it assembles payload which is then sent to Polte server using HTTP, then the location will be returned by the URC +QPOLTECR. AT+QPOLTECR Send Polte CR Location Request Write Command AT+QPOLTECR Response OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. Example AT+QPOLTECR OK +QPOLTECR:0,'44.826452','20.40706','1646213056','194' BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 23 / 33 LPWA Module Series 3 Description of URCs Polte URCs begin with +QPOLTEEVU: and they are mainly used to notify the host of the information from the Polte application. For detailed information about enabling Polte URCs, see Chapter 2.3.1.2. 3.1. +QPOLTEEVU: 'CRS' Notify CRS Symbol Capture Event The URC notifies the host of a CRS symbol capture event. +QPOLTEEVU: 'CRS' Notify CRS Symbol Capture Event +QPOLTEEVU: 'CRS',[,,,,,,,,,,[,]] Event reported for an attempt to capture CRS symbols, triggered by AT+QPOLTE='crs', AT+QPOLTE='compress' or AT+QPOLTE='locate'. Parameter Integer type. 0 Success 1 Invalid modem state 2 Not enough memory 12 Operation failure String type. Device IMEI number. String type. Two-byte tacking area code in hexadecimal format. Integer type. Three-digit value indicating mobile country code. Integer type. Three-digit value indicating mobile network code. String type. Four-byte E-UTRAN cell ID in hexadecimal format. Integer type. Physical cell ID value. Integer type. Stands for E-UTRA Absolute Radio Frequency Channel Number of the modem at the time of data capture. Integer type. Enumeration of E-UTRA bandwidths for serving cell. Unit of bandwidth: MHz. 0 0.18 1 1.4 2 3 BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 24 / 33 LPWA Module Series 3 5 4 10 5 15 6 20 Integer type. Number of captured contiguous OFDM symbols. Range: 0–80. Integer type. System frame number (SFN) of the first CRS data block. String type. File system path to the captured CRS data. 3.2. +QPOLTEEVU: 'COMPRESS' Notify CRS Data Compression Event This URC notifies the host of a CRS data compression event. +QPOLTEEVU: 'COMPRESS' Notify CRS Data Compression Event Event reported for an attempt to compress CRS data, +QPOLTEEVU: 'COMPRESS', triggered by AT+QPOLTE='compress' or [,[,]] AT+QPOLTE='locate'. Parameter Integer type. 0 Success 1 Invalid modem state 2 Not enough memory 12 Operation failure Integer type. Length of the compressed file. Range: 0–3000. Unit: byte. String type. File system path to save the compressed binary data. 3.3. +QPOLTEEVU: 'REGISTER' Notify Polte Server Registration Event This URC notifies the host of a Polte server registration event. +QPOLTEEVU: 'REGISTER' Notify Polte Server Registration Event +QPOLTEEVU: 'REGISTER',[, Event reported for an attempt to register to Polte server, ,] triggered by AT+QPOLTECFG='register'. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 25 / 33 Parameter LPWA Module Series Integer type. 0 Success 1 No response from server 12 Preceding operation failure String type. Username to the Polte server. Maximum size: 20 characters. String type. Password to the Polte server. Maximum size: 20 characters. 3.4. +QPOLTEEVU: 'LOCATION' Reception from Polte Server Notify Result of SR Location This URC notifies the host of the result of location reception from Polte server. +QPOLTEEVU: 'LOCATION' Notify Result of Location Reception from Polte Server +QPOLTEEVU: 'LOCATION', Event reported for result of location reception from Polte [,,,,] AT+QPOLTE='locate'. Parameter Integer type. 0 Success 1 No response from server 2 Operation failure String type. Contains floating value in quotes. Latitude is defined and returned by NMEA message GGA. Positive values represent 'North' and negative values represent 'South'. String type. Contains floating value in quotes. Longitude is defined and returned by NMEA message GGA. Positive values represent 'East' and negative values represent 'West'. Integer type. UTC timestamp of the position counted since January 1, 1970. Unit: ms. String type. Contains floating value in quotes. Confidence level as reported by Polte and represents certainty of fix in meters. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 26 / 33 LPWA Module Series 3.5. +QPOLTEEVU: 'ALLOWSTAT' Notify Change in Applicability of Polte Service This URC notifies the host of a change in applicability of Polte service. +QPOLTEEVU: 'ALLOWSTAT' Notify Change in Applicability of Polte Service +QPOLTEEVU: ALLOWSTAT', Event reported for a change in applicability of Polte service. Parameter Integer type. 0 Polte service is disabled, the modem cannot receive Polte-related AT commands 1 Polte service is enabled, the modem can receive Polte-related AT commands 3.6. +QPOLTECR Notify Result of CR Location Reception from Polte Server This URC notifies the host of the result of CR location reception from Polte server. +QPOLTECR Notify Result of CR Location Reception from Polte Server +QPOLTECR: [,,,,] server, triggered by AT+QPOLTECR. Parameter Integer type. 0 Success 1 No response from server 2 Operation failure String type. Contains floating value in quotes. Latitude is defined and returned by NMEA message GGA. Positive values represent 'North' and negative values represent 'South'. String type. Contains floating value in quotes. Longitude is defined and returned by NMEA message GGA. Positive values represent 'East' and BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 27 / 33 LPWA Module Series negative values represent 'West'. Integer type. UTC timestamp of the position counted since January 1, 1970. Unit: ms. String type. Contains floating value in quotes. Confidence level as reported by Polte and represents certainty of fix in meters. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 28 / 33 LPWA Module Series 4 Examples Examples of how to configure and use Polte features are presented in this chapter. 4.1. Polte SR Example To use Polte SR, the user has to register to https://polte.io. After log-in, the user should: ⚫ Add new device: User Equipment → BULK CLAIM ⚫ Choose 'IMEI' for 'Identifier Type' ⚫ Choose 'AT2' for 'Product Definition' ⚫ Download claimUeSample.csv file ⚫ Append the IMEI number at the bottom of the claimUeSample.csv file and reupload the file (click 'cloud' button) ⚫ Click on 'SUBMIT' Polte service has to be enabled (module reboot is required after this command in order to activate Polte): AT+QPOLTECFG='service',1 OK When using the Polte feature for the first time, device registration is necessary. If the registration is successful, the URC +QPOLTEEVU: 'REGISTER' will be received from the server along with MQTT credentials. Those credentials are necessary for further server authorization (AT+QPOLTECFG='serverauth'). AT+QPOLTECFG='polteev','register',1 OK AT+QPOLTECFG='register' +QPOLTECFG: 'REGISTER',0 OK +QPOLTEEVU: 'REGISTER',0,'mqtt_username','mqtt_password' Using Polte requires server authorization after each reboot: AT+QPOLTECFG='serverauth' OK BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 29 / 33 LPWA Module Series NOTE 1. Before first authorization, registration must be done (AT+QPOLTECFG='register'). 2. In case AT+QPOLTECFG='serverauth' returns ERROR or the authentication is unsuccessful for any reason, try to execute AT+QPOLTECFG='register' one more time to renew MQTT credentials used by AT+QPOLTECFG='serverauth'. To report device location, the users must: ⚫ Enable all +QPOLTEEVU URCs ⚫ Capture two frames: AT+QPOLTE='compress',2,0 ⚫ Report data to the cloud AT+QPOLTECFG='polteev','all',1 OK AT+QPOLTE='compress',2,0 +QPOLTE: 'COMPRESS',0 OK +QPOLTEEVU: 'CRS',0,'863593050015320','0x10',544,5,'0x20f0d',395,6400,4,80,652 +QPOLTEEVU: 'COMPRESS',0,1652,'b:/Polte/polte-compress' AT+QPOLTE='report',1 OK +QPOLTEEVU: 'LOCATION',0,'44.823246574123395','20.413992050537633','1642512945', '200' It is also possible to combine AT+QPOLTE='compress' and AT+QPOLTE='report' by using AT+QPOLTE='locate'. It is noted that AT+QPOLTE='locate' is not power optimized. Recommended flow is to use AT+QPOLTE='compress' and then AT+QPOLTE='report'. AT+QPOLTE='locate',2,1 +QPOLTE: 'LOCATE',0 OK +QPOLTEEVU: 'CRS',0,'863593050015320','0x10',544,5,'0x20f0d',395,6400,4,80,133 +QPOLTEEVU: 'COMPRESS',0,906 +QPOLTEEVU: 'LOCATION',0,'44.82272508613134','20.414680280163452','1642512945', '149.60' BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 30 / 33 LPWA Module Series 4.2. Polte CR Example To use Polte CR, the user must register to https://polte.io and acquire Customer ID and API Token. Customer ID can be found under 'Customer Profile' setting (upper right-hand corner), while API Token is created in the 'API Tokens' section (top of the window). When using Polte CR feature for the first time, the user must configure necessary parameters (Customer ID and API Token): AT+QPOLTECRCFG= '5fff4ee770e961101864cb1a','8d5d837a97f27f7da84264e5ad1ac24644c2a6 68256fa38a41a1ebf29a09eba34' OK Then you can send location request: AT+QPOLTECR OK +QPOLTECR:0,'44.826452','20.40706','1646213056','194' After successful locating, an URC carrying location information will be received. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 31 / 33 LPWA Module Series 5 Appendix References Table 4: Related Documents Document Name [1] Quectel_BG77xA-GL&BG95xA-GL_GNSS_Application_Note [2] Quectel_BG77xA-GL&BG95xA-GL_QuecLocator_Application_Note [3] Quectel_BG77xA-GL&BG95xA-GL_AT_Commands_Manual Table 5: Terms and Abbreviations Abbreviation CE CR CRS E-UTRA E-UTRAN GGA ID IMEI LTE MQTT NMEA OFDM Description Compression Engine CoreRes Cell Specific Reference Signal Evolved Universal Terrestrial Radio Access Evolved Universal Terrestrial Radio Access Network Global Positioning System Fix Data Identifier International Mobile Equipment Identity Long-Term Evolution Message Queuing Telemetry Transport National Marine Electronics Association Orthogonal Frequency-Division Multiplexing BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 32 / 33 Polte RRC RTTD SFN SR UE URC UTC Positioning Over LTE Radio Resource Control Receive Transmit Time Difference System Frame Number SuperRes User Equipment Unsolicited Result Code Coordinated Universal Time LPWA Module Series BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 33 / 33
314.11 KB
BG77xA-GL&BG95xA-GL Positioning over LTE Application Note LPWA Module Series Version: 1.0 Date: 2022-03-11 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 1 / 33 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 2 / 33 LPWA Module Series About the Document Revision History Version 1.0 Date 2020-10-29 2022-03-11 Author Mladen VUKOVIC Mladen VUKOVIC Description Creation of the document First official release BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 3 / 33 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 1.1. Special Mark .............................................................................................................................. 7 2 Polte AT Commands........................................................................................................................... 8 2.1. AT Command Introduction ......................................................................................................... 8 2.1.1. Definitions........................................................................................................................ 8 2.1.2. AT Command Syntax ...................................................................................................... 8 2.2 Declaration of AT Command Examples .................................................................................... 9 2.3 Description of Polte AT Commands........................................................................................... 9 2.3.1 AT+QPOLTECFG Configure Parameters of Polte SR Feature ................................... 9 2.3.1.1 AT+QPOLTECFG='service' Enable/Disable Polte SR Service ....................... 9 2.3.1.2 AT+QPOLTECFG='polteev' Enable/Disable Polte SR URCs........................ 10 2.3.1.3 AT+QPOLTECFG='register' Initiate Registration to Polte Server.................. 12 2.3.1.4 AT+QPOLTECFG='serverauth' Provide UE with Authentication Parameters13 2.3.1.5 AT+QPOLTECFG='mqttconfig' Set MQTT Configuration.............................. 13 2.3.2 AT+QPOLTE Trigger Polte SR Functionality ............................................................. 14 2.3.2.1 AT+QPOLTE='aux' Update Compressed Binary Auxiliary Data.................... 15 2.3.2.2 AT+QPOLTE='crs' Capture and Save CRS Symbols.................................... 16 2.3.2.3 AT+QPOLTE='compress' Capture, Compress and Save CRS Symbols ...... 17 2.3.2.4 AT+QPOLTE='ver' Request Version.............................................................. 18 2.3.2.5 AT+QPOLTE='report' Send Report................................................................ 19 2.3.2.6 AT+QPOLTE='locate' Capture, Compress and Send CRS Symbols ............ 20 2.3.2.7 AT+QPOLTE='getreg' Get Registration Parameters ..................................... 21 2.3.3 AT+QPOLTECRCFG Configure Parameters of Polte CR Feature............................ 22 2.3.4 AT+QPOLTECR Send Polte CR Location Request................................................... 23 3 Description of URCs ......................................................................................................................... 24 3.1. +QPOLTEEVU: 'CRS' Notify CRS Symbol Capture Event.................................................. 24 3.2. +QPOLTEEVU: 'COMPRESS' Notify CRS Data Compression Event ................................ 25 3.3. +QPOLTEEVU: 'REGISTER' Notify Polte Server Registration Event ................................. 25 3.4. +QPOLTEEVU: 'LOCATION' Notify Result of SR Location Reception from Polte Server .. 26 3.5. +QPOLTEEVU: 'ALLOWSTAT' Notify Change in Applicability of Polte Service ................. 27 3.6. +QPOLTECR Notify Result of CR Location Reception from Polte Server ........................... 27 4 Examples ........................................................................................................................................... 29 4.1 Polte SR Example .................................................................................................................... 29 4.2 Polte CR Example.................................................................................................................... 31 5 Appendix References ....................................................................................................................... 32 BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 4 / 33 LPWA Module Series Table Index Table 1: Applicable Modules ........................................................................................................................ 6 Table 2: Special Mark................................................................................................................................... 7 Table 3: Types of AT Commands ................................................................................................................ 8 Table 4: Related Documents...................................................................................................................... 32 Table 5: Terms and Abbreviations ............................................................................................................. 32 BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 5 / 33 LPWA Module Series 1 Introduction This document describes AT commands associated with the Positioning Over LTE (Polte) feature of Quectel LPWA modules. Polte Compression Engine (CE) embedded in the cellular modem leverages the Cell-specific Reference Signals (CRS) to offer the highest level of location accuracy. The device itself does not do any computing. It sends a sample of the LTE signals to the Polte cloud, and then the location is calculated by the server. Polte offers two location positioning services, Polte SuperRes (SR) and Polte CoreRes (CR) depending on the configuration and capability of the device. Polte SR provides higher level of accuracy than that of Polte CR, but it can only be utilized when eMTC (Cat M1) is in use. On the other hand, Polte CR is available on both radio access technologies (eMTC and NB-IoT). Internally, Quectel's implementations of Polte SR and Polte CR differ in how they send data to Polte server. Polte SR uses MQTT protocol while Polte CR utilizes HTTP. The AT commands are grouped into two categories, one supporting the SuperRes and the other supporting CoreRes. AT commands AT+QPOLTECFG and AT+QPOLTE (Chapter 2.3.1 and Chapter 2.3.2) support Polte SR, while AT+QPOLTECRCFG and AT+QPOLTECR (Chapter 2.3.3 and Chapter 2.3.4) support Polte CR. Table 1: Applicable Modules Module Series BG77xA-GL BG95xA-GL Model BG770A-GL BG772A-GL BG950A-GL BG951A-GL BG952A-GL* BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 6 / 33 1.1. Special Mark LPWA Module Series Table 2: Special Mark Mark * Definition Unless otherwise specified, when an asterisk (*) is used after a function, feature, interface, pin name, AT command, or argument, it indicates that the function, feature, interface, pin, AT command, or argument is under development and currently not supported; and the asterisk (*) after a model indicates that the sample of the model is currently unavailable. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 7 / 33 LPWA Module Series 2 Polte AT Commands 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 3: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 8 / 33 LPWA Module Series 2.2 Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 2.3 Description of Polte AT Commands 2.3.1 AT+QPOLTECFG Configure Parameters of Polte SR Feature This command configures parameters for using Polte SR service. In addition, it enables SR URCs and configures MQTT settings. AT+QPOLTECFG Configure Parameters of Polte SR Feature Test Command AT+QPOLTECFG=? Response +QPOLTECFG: 'service',(list of supported s) +QPOLTECFG: 'polteev',(list of supported s),(list of supported s) +QPOLTECFG: 'register' +QPOLTECFG: 'serverauth' +QPOLTECFG: 'mqttconfig',,(list of supported s) Maximum Response Time OK 300 ms 2.3.1.1 AT+QPOLTECFG='service' Enable/Disable Polte SR Service This command enables or disables Polte SR service. AT+QPOLTECFG='service' Enable/Disable Polte SR Service Write Command Response AT+QPOLTECFG='service'[,] +QPOLTECFG: 'service', OK BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 9 / 33 LPWA Module Series Maximum Response Time Characteristics If the optional parameter is specified, configure Polte service. OK Or ERROR 300 ms The command takes effect after the module is rebooted. The configuration is saved automatically. Parameter Integer type. 0 Disable Polte SR service 1 Enable Polte SR service Example AT+QPOLTECFG='service' +QPOLTECFG: 'service',1 //Query if Polte SR is activated. OK AT+QPOLTECFG='service',0 OK //Disable Polte SR service. 2.3.1.2 AT+QPOLTECFG='polteev' Enable/Disable Polte SR URCs This command enables or disables Polte SR related unsolicited result codes. The URCs are used to notify the host of the information from Polte SR application. The value 'ALL' of activates or deactivates all events. AT+QPOLTECFG='polteev' Enable/Disable Polte SR URCs Write Command AT+QPOLTECFG='polteev'[,,] Response If the optional parameters are omitted, query the current settings for all events. +QPOLTECFG: 'polteev': 'CRS',,'COMPRESS ',,'REGISTER',,'LOCATION',,'ALLOWSTAT', OK If the optional parameters are specified, configure Polte BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 10 / 33 LPWA Module Series Maximum Response Time Characteristics URCs. OK Or ERROR 300 ms The command takes effect immediately. The configuration is not saved. Parameter String type. Indicates Polte SR URCs beginning with +QPOLTEEVU:. For details of the URCs, see Chapter 3. 'ALL' Enables or disables all events 'CRS' Event reported for an attempt to capture CRS symbols, triggered by AT+QPOLTE='crs', AT+QPOLTE='compress' or AT+QPOLTE='locate' 'COMPRESS' Event reported for an attempt to compress CRS data, triggered by AT+QPOLTE='compress' or AT+QPOLTE='locate' 'REGISTER' Event reported for an attempt to register to Polte server, triggered by AT+QPOLTE='register' 'LOCATION' Event reported for result of location reception from Polte server, triggered by AT+QPOLTE='report' or AT+QPOLTE='locate' 'ALLOWSTAT' Event reported for a change in applicability of Polte SR service Integer type. 0 Disable URC 1 Enable URC Example AT+QPOLTECFG='polteev' //Query URC configuration, i.e., shows which URCs are enabled. +QPOLTECFG: 'polteev': 'CRS',0,'COMPRESS',0,'REGISTER',0,'LOCATION',0,'ALLOWSTA T',0 OK AT+QPOLTECFG='polteev','all',1 OK //Enable all URCs. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 11 / 33 LPWA Module Series 2.3.1.3 AT+QPOLTECFG='register' Initiate Registration to Polte Server This command initiates registration to the Polte server using UE parameters. AT+QPOLTECFG='register' Initiate Registration to Polte Server Write Command AT+QPOLTECFG='register' Response +QPOLTECFG: 'REGISTER', Maximum Response Time Characteristics OK Or ERROR 300 ms The command takes effect immediately. The configuration is saved automatically. Parameter Integer type. 0 Success 1 No response from server 12 Operation failure Example AT+QPOLTECFG='register' +QPOLTECFG: 'REGISTER',0 OK //In order to get following URC, corresponding event must be enabled. +QPOLTEEVU: 'REGISTER',0,'PhFRuPUIlnh','xkfgGgmesCK' NOTE 1. Registration to the Polte server (AT+QPOLTECFG='register') is executed only once when Polte SR feature is used for the first time. 2. If the registration was successful, the URC +QPOLTEEVU: 'REGISTER' will be received along with MQTT credentials that are used for further server authorization. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 12 / 33 LPWA Module Series 2.3.1.4 AT+QPOLTECFG='serverauth' Provide UE with Authentication Parameters This command provides the UE with authentication parameters required for successful sending of the compressed binary data to the Polte server. The command is used for renewing server authorization after the module reboots or wakes up from PSM and e-I-DRX modes. Before using the command for the first time, it is necessary to register the device with AT+QPOLTECFG='register'. AT+QPOLTECFG='serverauth' Provide UE with Authentication Parameters Write Command AT+QPOLTECFG='serverauth' Response OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. The configuration is not saved. Example AT+QPOLTECFG='serverauth' OK NOTE 1. Registration to the Polte server (AT+QPOLTECFG='register') is done only once when Polte SR feature is used for the first time, while server authorization (AT+QPOLTECFG='serverauth') is necessary each time the module reboots or wakes up from PSM and e-I-DRX modes. 2. In case of unsuccessful authorization or an error, it is necessary to execute AT+QPOLTECFG='register' again in order to renew MQTT credentials used for authorization. 2.3.1.5 AT+QPOLTECFG='mqttconfig' Set MQTT Configuration This command configures MQTT parameters. AT+QPOLTECFG='mqttconfig' Set MQTT Configuration Write Command AT+QPOLTECFG='mqttconfig',, Response OK Or ERROR BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 13 / 33 LPWA Module Series Maximum Response Time Characteristics 300 ms The command takes effect immediately. The configuration is not saved. Parameter Integer type. Duration of a timer to allow MQTT session before clearing Polte client session parameters. Range: 5–60. Default value: 25. Unit: s. Integer type. 0 Do not disconnect from MQTT server if timer expires 1 Disconnect from MQTT server if timer expires 2.3.2 AT+QPOLTE Trigger Polte SR Functionality This command triggers Polte SR functionality. AT+QPOLTE Trigger Polte SR Functionality Test Command AT+QPOLTE=? Response +QPOLTE: 'aux' +QPOLTE: 'crs',(range of supported ),(list of supported s) +QPOLTE: 'compress',(range of supported ), (list of supported s) +QPOLTE: 'ver' +QPOLTE: 'report', (list of supported s), +QPOLTE: 'locate',(range of supported ),(list of supported s) +QPOLTE: 'getreg' Maximum Response Time Characteristics OK 300 ms The command takes effect immediately. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 14 / 33 LPWA Module Series 2.3.2.1 AT+QPOLTE='aux' Update Compressed Binary Auxiliary Data This command gets auxiliary data (including RTTD field) and updates it into compressed binary data. The command is applied when sending data to Polte server in ways other than using AT+QPOLTE='report', and has to be executed in RRC connected state. When sending data to the server through AT+QPOLTE='report', RTTD value is added to Polte compressed data and sent along with it to the server automatically. When sending data to the server by other means, you can execute AT+QPOLTE='aux' to connect to the network to get RTTD value and send the resultant data to the server immediately; or you can send the data without RTTD value with degraded accuracy. AT+QPOLTE='aux' Update Compressed Binary Auxiliary Data Write Command AT+QPOLTE='aux' Response +QPOLTE: 'AUX', Maximum Response Time Characteristics OK Or ERROR 300 ms The command takes effect immediately. Parameter Integer type. 0 Success. Serving cell remains unchanged 1 Success. Serving cell has changed 2 No compressed file 3 RTTD is unavailable 4 Not enough memory 5 Error in file reading 6 Error in writing into file 7 Error in getting auxiliary data 8 RTTD is already present in auxiliary data Example AT+QPOLTE='aux' +QPOLTE: 'AUX',0 OK BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 15 / 33 LPWA Module Series 2.3.2.2 AT+QPOLTE='crs' Capture and Save CRS Symbols This command captures CRS symbols and saves the results to the file system. It’s for debugging purpose and is not supposed to be sent to the Polte server. AT+QPOLTE='crs' Capture and Save CRS Symbols Write Command AT+QPOLTE='crs',, Response +QPOLTE: 'CRS', OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. Parameter Integer type. Number of frames for capturing CRS symbols. 0 Cancel CRS capture 1 Capture CRS symbols of 1 frame 2 Capture CRS symbols of 2 contiguous frames Integer type. 0 Save CRS symbols without waiting for RRC connected state 1 Wait for RRC connected state and get RTTD value before saving CRS symbols to file system Integer type. 0 Success 1 Invalid modem state 2 Wrong number of frames to capture 3 Not enough memory 4 Pending response from modem 5 Retrying capture attempt (previously buffered by application). It will try 3 times before it fails 7 Device ID unavailable 8 Capture attempt delayed due to ongoing paging 9 Flash read/write failure 12 A preceding operation has failed 13 Invalid RAT in use BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 16 / 33 LPWA Module Series Example AT+QPOLTE='crs',2,1 +QPOLTE: 'CRS',0 OK //To get the following URC, the corresponding event must be enabled +QPOLTEEVU: 'CRS',0,'863593050015320','0x10',544,5,'0x20f0d',395,6400,4,80,109,'b:/Polte/ polte-unpack' 2.3.2.3 AT+QPOLTE='compress' Capture, Compress and Save CRS Symbols This command captures CRS symbols, compresses them using the Compression-Engine (CE) and saves the results to the file system. AT+QPOLTE='compress' Capture, Compress and Save CRS Symbols Write Command AT+QPOLTE='compress',[,] Response +QPOLTE: 'COMPRESS', OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. Parameter Integer type. Number of frames for capturing CRS symbols. 0 Cancel CRS capture 1 Capture CRS symbols of 1 frame 2 Capture CRS symbols of 2 contiguous frames Integer type. 0 Save CRS symbols without waiting for RRC connected state 1 Wait for RRC connected state and get RTTD value before saving CRS symbols to file system Integer type. 0 Success 1 Invalid modem state 2 Wrong number of frames to capture BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 17 / 33 LPWA Module Series 3 Not enough memory 4 Pending response from modem 5 Retrying capture attempt (previously buffered by application). It will try 3 times before it fails 7 Device ID unavailable 8 Capture attempt delayed due to ongoing paging 9 Flash read/write failure 12 A preceding operation has failed 13 Invalid RAT in use Example AT+QPOLTE='compress',2,0 +QPOLTE: 'COMPRESS',0 OK // To get the following URCs, corresponding events must be enabled +QPOLTEEVU: 'CRS',0,'863593050015320','0x10',544,5,'0x20f0d',395,6400,4,80,652 +QPOLTEEVU: 'COMPRESS',0,1652,'b:/Polte/polte-compress' NOTE RTTD value is added by default when using AT+QPOLTE='report' and AT+QPOLTE='aux', thus there is no need to wait for RRC connected state when executing AT+QPOLTE='compress'. 2.3.2.4 AT+QPOLTE='ver' Request Version This command requests the versions of the Polte application and CE. AT+QPOLTE='ver' Write Command AT+QPOLTE='ver' Request Version Response +QPOLTE: 'VER',, Maximum Response Time Characteristics OK Or ERROR 300 ms The command takes effect immediately. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 18 / 33 Parameter String type. Polte application version. String type. CE version. Example AT+QPOLTE='ver' +QPOLTE: 'VER','1.0.0','1.1.13' OK LPWA Module Series 2.3.2.5 AT+QPOLTE='report' Send Report This command sends a report including compressed binary data and RTTD value to the Polte server. AT+QPOLTE='report' Send Report Write Command AT+QPOLTE='report',[,] Response OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. Parameter Integer type. 0 URC +QPOLTEEVU: 'LOCATION' is not expected, client shall disconnect from server immediately after data are sent. 1 URC +QPOLTEEVU: 'LOCATION' is expected, client shall not disconnect from server until the URC is received. String type. Optional path for sending file. By default, compressed binary data is stored at the directory b:/Polte/polte-compress (which is a path to store data after executing AT+QPOLTE='compress'), which will be used as a default file path for AT+QPOLTE='report'. In other cases, if user wants to send a file which is located at other locations on the disk, then the file path of other locations should be given accordingly. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 19 / 33 LPWA Module Series Example AT+QPOLTE='report',1 OK //To get the following URC, the corresponding event must be enabled +QPOLTEEVU: 'LOCATION',0,'44.823246574123395','20.413992050537633','1642512945','200' 2.3.2.6 AT+QPOLTE='locate' Capture, Compress and Send CRS Symbols This command combines the functions of AT+QPOLTE='compress' and AT+QPOLTE='report' into one action, which can reduce the need to save compressed data (i.e., the output of AT+QPOLTE='compress') to flash and read them before sending them to server. The command captures CRS symbols, compresses them and sends the results to server. AT+QPOLTE='locate' Capture, Compress and Send CRS Symbols Write Command AT+QPOLTE='locate',, Response +QPOLTE: 'LOCATE', OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. Parameter Integer type. Number of frames for capturing CRS symbols. 0 Cancel CRS capture 1 Capture CRS symbols of 1 frame 2 Capture CRS symbols of 2 contiguous frames Integer type. 0 Don't request to get location back 1 Request to get location back to the device after it has been generated by the server Integer type. 0 Success 1 Invalid modem state 2 Wrong number of frames to capture 3 Not enough memory BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 20 / 33 LPWA Module Series 4 Pending response from modem 5 Retrying capture attempt (previously buffered by application). It will try 3 times before it fails 7 Device ID unavailable 8 Capture attempt delayed because of ongoing paging 9 Flash read/write failure 10 Successful positioning during PSM 11 Unsuccessful positioning during PSM 12 A preceding operation failure 13 Invalid RAT in use Example AT+QPOLTE='locate',2,1 +QPOLTE: 'LOCATE',0 OK //To get the following URCs, corresponding events must be enabled. +QPOLTEEVU: 'CRS',0,'863593050015320','0x10',544,5,'0x20f0d',395,6400,4,80,133 +QPOLTEEVU: 'COMPRESS',0,906 +QPOLTEEVU: 'LOCATION',0,'44.82272508613134','20.414680280163452','1642512945', '149.60' 2.3.2.7 AT+QPOLTE='getreg' Get Registration Parameters This command provides UE with specific parameters needed to register the UE to the Polte server. AT+QPOLTE='getreg' Get Registration Parameters Write Command AT+QPOLTE='getreg' Response +QPOLTE: 'GETREG',,, , Maximum Response Time Characteristics OK Or ERROR 300 ms The command takes effect immediately. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 21 / 33 LPWA Module Series Parameter String type. Manufacturer token. Maximum size: 20 characters. String type. Model token. Maximum size: 20 characters. String type. Decimal format indicating device IMEI number. String type. Unique modem token. Maximum size: 256 characters. Example AT+QPOLTE='getreg' +QPOLTE: GETREG','a3de2b6e510','dc6a91c7883','863593050015320','ALT12508B9933A0C6 4505BE3FFE553B5FA3EFB3' OK 2.3.3 AT+QPOLTECRCFG Configure Parameters of Polte CR Feature This command configures parameters for using Polte CR service. Data is sent to the Polte server by using HTTP protocol in Polte CR service. Thus, it needs parameters such as Customer ID and API Token for setting HTTP URL and HTTP authorization process. The Customer ID and API Token can be acquired from Polte company upon registration, see Chapter 4.2 for details. AT+QPOLTECRCFG Configure Parameters of Polte CR Feature Write Command AT+QPOLTECRCFG= , Response OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. The configuration is saved. Parameter String type. Customer ID used for setting HTTP URL. String type. API token used for HTTP authorization. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 22 / 33 LPWA Module Series Example AT+QPOLTECRCFG='5fff4ee770e961101864cb1a','8d5d837a97f27f7da84264e5ad1ac24644c2a6 68256fa38a41a1ebf29a09eba34' OK 2.3.4 AT+QPOLTECR Send Polte CR Location Request This command sends Polte CR location request to Polte server. Internally, this command is executed in two phases. Firstly, it collects cell related data. After gathering all necessary data, it assembles payload which is then sent to Polte server using HTTP, then the location will be returned by the URC +QPOLTECR. AT+QPOLTECR Send Polte CR Location Request Write Command AT+QPOLTECR Response OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. Example AT+QPOLTECR OK +QPOLTECR:0,'44.826452','20.40706','1646213056','194' BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 23 / 33 LPWA Module Series 3 Description of URCs Polte URCs begin with +QPOLTEEVU: and they are mainly used to notify the host of the information from the Polte application. For detailed information about enabling Polte URCs, see Chapter 2.3.1.2. 3.1. +QPOLTEEVU: 'CRS' Notify CRS Symbol Capture Event The URC notifies the host of a CRS symbol capture event. +QPOLTEEVU: 'CRS' Notify CRS Symbol Capture Event +QPOLTEEVU: 'CRS',[,,,,,,,,,,[,]] Event reported for an attempt to capture CRS symbols, triggered by AT+QPOLTE='crs', AT+QPOLTE='compress' or AT+QPOLTE='locate'. Parameter Integer type. 0 Success 1 Invalid modem state 2 Not enough memory 12 Operation failure String type. Device IMEI number. String type. Two-byte tacking area code in hexadecimal format. Integer type. Three-digit value indicating mobile country code. Integer type. Three-digit value indicating mobile network code. String type. Four-byte E-UTRAN cell ID in hexadecimal format. Integer type. Physical cell ID value. Integer type. Stands for E-UTRA Absolute Radio Frequency Channel Number of the modem at the time of data capture. Integer type. Enumeration of E-UTRA bandwidths for serving cell. Unit of bandwidth: MHz. 0 0.18 1 1.4 2 3 BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 24 / 33 LPWA Module Series 3 5 4 10 5 15 6 20 Integer type. Number of captured contiguous OFDM symbols. Range: 0–80. Integer type. System frame number (SFN) of the first CRS data block. String type. File system path to the captured CRS data. 3.2. +QPOLTEEVU: 'COMPRESS' Notify CRS Data Compression Event This URC notifies the host of a CRS data compression event. +QPOLTEEVU: 'COMPRESS' Notify CRS Data Compression Event Event reported for an attempt to compress CRS data, +QPOLTEEVU: 'COMPRESS', triggered by AT+QPOLTE='compress' or [,[,]] AT+QPOLTE='locate'. Parameter Integer type. 0 Success 1 Invalid modem state 2 Not enough memory 12 Operation failure Integer type. Length of the compressed file. Range: 0–3000. Unit: byte. String type. File system path to save the compressed binary data. 3.3. +QPOLTEEVU: 'REGISTER' Notify Polte Server Registration Event This URC notifies the host of a Polte server registration event. +QPOLTEEVU: 'REGISTER' Notify Polte Server Registration Event +QPOLTEEVU: 'REGISTER',[, Event reported for an attempt to register to Polte server, ,] triggered by AT+QPOLTECFG='register'. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 25 / 33 Parameter LPWA Module Series Integer type. 0 Success 1 No response from server 12 Preceding operation failure String type. Username to the Polte server. Maximum size: 20 characters. String type. Password to the Polte server. Maximum size: 20 characters. 3.4. +QPOLTEEVU: 'LOCATION' Reception from Polte Server Notify Result of SR Location This URC notifies the host of the result of location reception from Polte server. +QPOLTEEVU: 'LOCATION' Notify Result of Location Reception from Polte Server +QPOLTEEVU: 'LOCATION', Event reported for result of location reception from Polte [,,,,] AT+QPOLTE='locate'. Parameter Integer type. 0 Success 1 No response from server 2 Operation failure String type. Contains floating value in quotes. Latitude is defined and returned by NMEA message GGA. Positive values represent 'North' and negative values represent 'South'. String type. Contains floating value in quotes. Longitude is defined and returned by NMEA message GGA. Positive values represent 'East' and negative values represent 'West'. Integer type. UTC timestamp of the position counted since January 1, 1970. Unit: ms. String type. Contains floating value in quotes. Confidence level as reported by Polte and represents certainty of fix in meters. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 26 / 33 LPWA Module Series 3.5. +QPOLTEEVU: 'ALLOWSTAT' Notify Change in Applicability of Polte Service This URC notifies the host of a change in applicability of Polte service. +QPOLTEEVU: 'ALLOWSTAT' Notify Change in Applicability of Polte Service +QPOLTEEVU: ALLOWSTAT', Event reported for a change in applicability of Polte service. Parameter Integer type. 0 Polte service is disabled, the modem cannot receive Polte-related AT commands 1 Polte service is enabled, the modem can receive Polte-related AT commands 3.6. +QPOLTECR Notify Result of CR Location Reception from Polte Server This URC notifies the host of the result of CR location reception from Polte server. +QPOLTECR Notify Result of CR Location Reception from Polte Server +QPOLTECR: [,,,,] server, triggered by AT+QPOLTECR. Parameter Integer type. 0 Success 1 No response from server 2 Operation failure String type. Contains floating value in quotes. Latitude is defined and returned by NMEA message GGA. Positive values represent 'North' and negative values represent 'South'. String type. Contains floating value in quotes. Longitude is defined and returned by NMEA message GGA. Positive values represent 'East' and BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 27 / 33 LPWA Module Series negative values represent 'West'. Integer type. UTC timestamp of the position counted since January 1, 1970. Unit: ms. String type. Contains floating value in quotes. Confidence level as reported by Polte and represents certainty of fix in meters. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 28 / 33 LPWA Module Series 4 Examples Examples of how to configure and use Polte features are presented in this chapter. 4.1. Polte SR Example To use Polte SR, the user has to register to https://polte.io. After log-in, the user should: ⚫ Add new device: User Equipment → BULK CLAIM ⚫ Choose 'IMEI' for 'Identifier Type' ⚫ Choose 'AT2' for 'Product Definition' ⚫ Download claimUeSample.csv file ⚫ Append the IMEI number at the bottom of the claimUeSample.csv file and reupload the file (click 'cloud' button) ⚫ Click on 'SUBMIT' Polte service has to be enabled (module reboot is required after this command in order to activate Polte): AT+QPOLTECFG='service',1 OK When using the Polte feature for the first time, device registration is necessary. If the registration is successful, the URC +QPOLTEEVU: 'REGISTER' will be received from the server along with MQTT credentials. Those credentials are necessary for further server authorization (AT+QPOLTECFG='serverauth'). AT+QPOLTECFG='polteev','register',1 OK AT+QPOLTECFG='register' +QPOLTECFG: 'REGISTER',0 OK +QPOLTEEVU: 'REGISTER',0,'mqtt_username','mqtt_password' Using Polte requires server authorization after each reboot: AT+QPOLTECFG='serverauth' OK BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 29 / 33 LPWA Module Series NOTE 1. Before first authorization, registration must be done (AT+QPOLTECFG='register'). 2. In case AT+QPOLTECFG='serverauth' returns ERROR or the authentication is unsuccessful for any reason, try to execute AT+QPOLTECFG='register' one more time to renew MQTT credentials used by AT+QPOLTECFG='serverauth'. To report device location, the users must: ⚫ Enable all +QPOLTEEVU URCs ⚫ Capture two frames: AT+QPOLTE='compress',2,0 ⚫ Report data to the cloud AT+QPOLTECFG='polteev','all',1 OK AT+QPOLTE='compress',2,0 +QPOLTE: 'COMPRESS',0 OK +QPOLTEEVU: 'CRS',0,'863593050015320','0x10',544,5,'0x20f0d',395,6400,4,80,652 +QPOLTEEVU: 'COMPRESS',0,1652,'b:/Polte/polte-compress' AT+QPOLTE='report',1 OK +QPOLTEEVU: 'LOCATION',0,'44.823246574123395','20.413992050537633','1642512945', '200' It is also possible to combine AT+QPOLTE='compress' and AT+QPOLTE='report' by using AT+QPOLTE='locate'. It is noted that AT+QPOLTE='locate' is not power optimized. Recommended flow is to use AT+QPOLTE='compress' and then AT+QPOLTE='report'. AT+QPOLTE='locate',2,1 +QPOLTE: 'LOCATE',0 OK +QPOLTEEVU: 'CRS',0,'863593050015320','0x10',544,5,'0x20f0d',395,6400,4,80,133 +QPOLTEEVU: 'COMPRESS',0,906 +QPOLTEEVU: 'LOCATION',0,'44.82272508613134','20.414680280163452','1642512945', '149.60' BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 30 / 33 LPWA Module Series 4.2. Polte CR Example To use Polte CR, the user must register to https://polte.io and acquire Customer ID and API Token. Customer ID can be found under 'Customer Profile' setting (upper right-hand corner), while API Token is created in the 'API Tokens' section (top of the window). When using Polte CR feature for the first time, the user must configure necessary parameters (Customer ID and API Token): AT+QPOLTECRCFG= '5fff4ee770e961101864cb1a','8d5d837a97f27f7da84264e5ad1ac24644c2a6 68256fa38a41a1ebf29a09eba34' OK Then you can send location request: AT+QPOLTECR OK +QPOLTECR:0,'44.826452','20.40706','1646213056','194' After successful locating, an URC carrying location information will be received. BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 31 / 33 LPWA Module Series 5 Appendix References Table 4: Related Documents Document Name [1] Quectel_BG77xA-GL&BG95xA-GL_GNSS_Application_Note [2] Quectel_BG77xA-GL&BG95xA-GL_QuecLocator_Application_Note [3] Quectel_BG77xA-GL&BG95xA-GL_AT_Commands_Manual Table 5: Terms and Abbreviations Abbreviation CE CR CRS E-UTRA E-UTRAN GGA ID IMEI LTE MQTT NMEA OFDM Description Compression Engine CoreRes Cell Specific Reference Signal Evolved Universal Terrestrial Radio Access Evolved Universal Terrestrial Radio Access Network Global Positioning System Fix Data Identifier International Mobile Equipment Identity Long-Term Evolution Message Queuing Telemetry Transport National Marine Electronics Association Orthogonal Frequency-Division Multiplexing BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 32 / 33 Polte RRC RTTD SFN SR UE URC UTC Positioning Over LTE Radio Resource Control Receive Transmit Time Difference System Frame Number SuperRes User Equipment Unsolicited Result Code Coordinated Universal Time LPWA Module Series BG77xA-GL&BG95xA-GL_Positioning_Over_LTE_Application_Note 33 / 33
314.11 KB
BG95&BG77&BG600L Series GNSS Jamming Detection Application Note LPWA Module Series Version: 1.0 Date: 2022-02-25 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG95&BG77&BG600L_Series_GNSS_Jamming_Detection_Application_Note 1 / 13 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG95&BG77&BG600L_Series_GNSS_Jamming_Detection_Application_Note 2 / 13 LPWA Module Series About the Document Revision History Version 1.0 Date 2021-12-31 2022-02-25 Author Matt YE/ Kayn SHAO Matt YE/ Kayn SHAO Description Creation of the document First official release BG95&BG77&BG600L_Series_GNSS_Jamming_Detection_Application_Note 3 / 13 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 1.1. Applicable Modules .................................................................................................................... 6 1.2. GNSS Jamming Indicator .......................................................................................................... 6 1.3. Reference Noise Level (RNL) .................................................................................................... 7 1.4. Limitations .................................................................................................................................. 7 2 AT Command Description.................................................................................................................. 8 2.1. AT Command Introduction ......................................................................................................... 8 2.1.1. Definitions........................................................................................................................ 8 2.1.2. AT Command Syntax ...................................................................................................... 8 2.2. Declaration of AT Command Examples ..................................................................................... 9 2.3. Jamming Detection Related AT Command................................................................................ 9 2.3.1. AT+QGPSCFG='agnssjamming' Enable/Disable GNSS Jamming Detection ............ 9 3 Summary of Error Codes ................................................................................................................. 12 4 Appendix Reference ......................................................................................................................... 13 BG95&BG77&BG600L_Series_GNSS_Jamming_Detection_Application_Note 4 / 13 LPWA Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 6 Table 2: Summary of Error Codes.............................................................................................................. 12 Table 3: Terms and Abbreviations .............................................................................................................. 13 BG95&BG77&BG600L_Series_GNSS_Jamming_Detection_Application_Note 5 / 13 LPWA Module Series 1 Introduction This document describes how to implement GNSS jamming detection for Quectel BG95 series, BG77 and BG600L-M3 modules via AT commands. 1.1. Applicable Modules Table 1: Applicable Modules Module Series BG95 BG77 BG600L Model BG95-M1 BG95-M2 BG95-M3 BG95-M4 BG95-M5 BG95-M6 BG95-MF BG77 BG600L-M3 Description Cat M1 only Cat M1/Cat NB2 Cat M1/Cat NB2/EGPRS Cat M1/Cat NB2, 450 MHz Supported Cat M1/Cat NB2/EGPRS, Power Class 3 Cat M1/Cat NB2, Power Class 3 Cat M1/Cat NB2, Wi-Fi Positioning Cat M1/Cat NB2 Cat M1/Cat NB2/EGPRS 1.2. GNSS Jamming Indicator GNSS jamming indicator is a metric that is linearly proportional to the sum of jammer and noise power at the GNSS antenna port. The jamming indicator can be used to measure the relative increase in the current noise floor, including jammer, versus the observed reference noise level (RNL) — both measured at the GNSS receiver input. In an interference environment, the measured value of the GNSS jamming indicator will increase. BG95&BG77&BG600L_Series_GNSS_Jamming_Detection_Application_Note 6 / 13 LPWA Module Series Interference to the signal received by the module is assessed based on the comparison between the measured value of the GNSS jamming indicator and RNL. 1.3. Reference Noise Level (RNL) To detect jamming events, BG95 series, BG77 and BG600L-M3 modules use a relative measure of the noise level (i.e., RNL) at the input of the GNSS receiver. RNL value is unavailable by default. It will be automatically calculated and updated, once the following conditions are met. a. Jamming detection is enabled (See Chapter 2.3.1). b. GNSS is turned on and the module has been successfully positioned. c. Positioning accuracy is less than 20 m and lasts for 20 s. Therefore, the RNL is changing and automatically adapts to the environment. To avoid too frequent saving of the RNL value to NVRAM, RNL is saved to NVRAM only once at the first update after the module is powered on. The modules support setting an estimated RNL with AT+QGPSCFG='agnssjamming', which is otherwise not recommended, because the modules can update RNL automatically when jamming detection is enabled and the modules work properly. 1.4. Limitations GNSS jamming indicator is a relative measure, therefore there are certain limitations associated with it. Limitations on the use of GNSS jamming detection feature: a. When detecting jammers at the beginning of a GNSS tracking session, the jamming indicator assumes that the antenna input signal conditions are similar to those of a previous GNSS tracking session, i.e., the surrounding environment and the location of the device did not change dramatically. b. When GNSS signals are strong, it is possible to get a good GNSS position fix in the presence of jammers. Jammers can cause RNL bias by several dB, thus impacting RNL reliability in detecting them. c. 'Moderately' and 'severely' jammed conditions as well as their associated thresholds assume open sky and strong GNSS signal conditions. When the GNSS signals are weaker, jammer impact is more pronounced. For example, in challenging GNSS signal conditions, a 5 dB jammer may severely impact GNSS performance. d. Jamming detection cannot be supported when an active antenna is used for GNSS signal reception. BG95&BG77&BG600L_Series_GNSS_Jamming_Detection_Application_Note 7 / 13 LPWA Module Series 2 AT Command Description 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 1: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. BG95&BG77&BG600L_Series_GNSS_Jamming_Detection_Application_Note 8 / 13 LPWA Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 2.3. Jamming Detection Related AT Command 2.3.1. AT+QGPSCFG='agnssjamming' Enable/Disable GNSS Jamming Detection This command enables or disables GNSS jamming detection. AT+QGPSCFG='agnssjamming' Enable/Disable GNSS Jamming Detection Test Command AT+QGPSCFG=? Response: … +QGPSCFG: 'agnssjamming',(range of s),(range of supported s) ... supported Write Command AT+QGPSCFG='agnssjamming' [,[,]] OK Response If the optional parameters are omitted, query the current setting. +QGPSCFG: 'agnssjamming',,,[/], OK If any of the optional parameters is specified, enable/disable jamming detection and/or set the estimated RNL value. OK Maximum Response Time Characteristics If there is any error related to the ME functionality: +CME ERROR: 300 ms This command takes effect immediately. The configuration will be not saved. The configuration will be saved automatically. BG95&BG77&BG600L_Series_GNSS_Jamming_Detection_Application_Note 9 / 13 Parameter LPWA Module Series Integer type. Enable/disable GNSS jamming detection and configure URC reporting mode. 0 Disable jamming detection function 1 Enable jamming detection function and report URC every second 2 Enable jamming detection and report URC when the jamming state changes URC is presented below: +QGPSURC: 'jamming_ind',,, Integer type. Estimated Reference Noise Level. Range: 0–105. It is recommended NOT to set this value. Integer type. Jamming state. 0 Jamming does not exist 1 Jamming exists Integer type. Reference Noise Level. NULL means there is no valid RNL. Range: 0–105. Integer type. Jamming metric measured in real time. Unit: dB. Integer type. Error code. See Chapter 3 for more information. NOTE If has not been specified, the RNL returned by AT+QGPSCFG='agnssjamming' is the actual RNL, and NULL means there is no valid RNL. If has been specified, the RNL returned by AT+QGPSCFG='agnssjamming' is the estimated RNL, and it will be updated into the actual RNL after the RNL is available. Example AT+QGPSCFG='agnssjamming',1 OK AT+QGPS=1 OK //Enable jamming detection function and reporting URC every second. //Start GNSS, and wait until GNSS gets position fix and RNL is updated. AT+QGPSCFG='agnssjamming' +QGPSCFG: 'agnssjamming',1,1,55,55 //Query the current jamming detection and URC state. OK //When jammer is detected, the module reports GNSS jamming detection URCs +QGPSURC: 'jamming_ind',1,55,67 +QGPSURC: 'jamming_ind',1,55,67 BG95&BG77&BG600L_Series_GNSS_Jamming_Detection_Application_Note 10 / 13 +QGPSURC: 'jamming_ind',1,55,67 AT+QGPSCFG='agnssjamming',0 OK LPWA Module Series //Disable jamming detection function BG95&BG77&BG600L_Series_GNSS_Jamming_Detection_Application_Note 11 / 13 LPWA Module Series 3 Summary of Error Codes The indicates an error related to the GNSS operation. The details about are presented in the following table. Table 2: Summary of Error Codes 501 502 503 Meaning Invalid parameter Operation not supported GNSS subsystem busy 504 Active session 505 Inactive session 506 Operation timeout 549 Unknown error BG95&BG77&BG600L_Series_GNSS_Jamming_Detection_Application_Note 12 / 13 LPWA Module Series 4 Appendix Reference Table 3: Terms and Abbreviations Abbreviation EGPRS GNSS GPS LPWA NVRAM RNL URC Wi-Fi Description Enhanced General Packet Radio Service Global Navigation Satellite System Global Positioning System Low Power Wide Area Non-Volatile Random Access Memory Reference Noise Level Unsolicited Result Code Wireless Fidelity BG95&BG77&BG600L_Series_GNSS_Jamming_Detection_Application_Note 13 / 13
200.65 KB
BG96 Secure Boot Application Note LPWA Module Series Version: 1.0 Date: 2022-02-18 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG96_Secure_Boot_Application_Note 1 / 14 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG96_Secure_Boot_Application_Note 2 / 14 LPWA Module Series About the Document Revision History Version 1.0 Date 2021-12-22 2022-02-18 Author Justice HAN Justice HAN Description Creation of the document First Official Release BG96_Secure_Boot_Application_Note 3 / 14 LPWA Module Series Contents About the Document ................................................................................................................................3 Contents .................................................................................................................................................... 4 Table Index ...............................................................................................................................................5 1 Introduction .......................................................................................................................................6 2 Secure Boot Overview ......................................................................................................................7 2.1. Definition ..................................................................................................................................7 2.2. Secure Boot Process................................................................................................................7 2.3. Certificate Chain .......................................................................................................................8 2.4. Image Signing ..........................................................................................................................8 2.5. Hardware Foundation ...............................................................................................................8 2.6. Secure Boot Toolkit...................................................................................................................9 2.7. sec.dat....................................................................................................................................10 3 Enable Secure Boot ........................................................................................................................11 3.1. Procedure ............................................................................................................................... 11 3.1.1. Preparation .................................................................................................................. 11 3.1.2. Generate Certificates and Public Key Hash Value ....................................................... 11 3.1.3. Fill in Environment Variables........................................................................................ 11 3.1.4. Sign Images and Generate a Firmware Package ........................................................ 11 3.1.5. Flash Firmware ............................................................................................................12 3.2. Verification..............................................................................................................................12 3.2.1. AT+QSECBOOTSTAT Query Secure Boot Status.....................................................12 4 Appendix References .....................................................................................................................14 BG96_Secure_Boot_Application_Note 4 / 14 LPWA Module Series Table Index Table 1: Related Documents ................................................................................................................... 14 Table 2: Terms and Abbreviations............................................................................................................ 14 BG96_Secure_Boot_Application_Note 5 / 14 LPWA Module Series 1 Introduction This document describes Secure Boot details and how to enable Secure Boot on Quectel BG96 module. BG96_Secure_Boot_Application_Note 6 / 14 LPWA Module Series 2 Secure Boot Overview 2.1. Definition Secure Boot is defined as a boot sequence in which each firmware image to be loaded and executed is authorized using the previously authorized firmware. At each stage of the Secure Boot process, signature verification is performed to prevent any software without valid signature or maliciously modified software from running on the module. A root trusted entity is needed during the boot process. The Primary Boot Loader (PBL), embedded in the module as a firmware, is unmodifiable, and therefore can serve as the root trusted entity. 2.2. Secure Boot Process The Secure Boot process comprises multiple stages, and the image in each stage performs a specific function. After the Secure Boot is enabled, the image to be executed in each stage needs to be verified by the previously verified image. If the verification fails, the entire boot process stops, and the module cannot boot up. Quectel BG96 module follows the verification sequence of Primary Boot Loader (PBL) → Secondary Boot Loader (SBL) → ARM® TrustZone. ⚫ As the root of trust (RoT), the PBL is the firmware embedded in chips and cannot be modified. Therefore, it is considered as the most trusted entity in the boot process, and authenticates the image to be executed in the next boot stage. ⚫ The SBL is usually verified in the second boot stage. After it is successfully authenticated by the PBL, it can be executed and used to authenticate the image in the next stage. ⚫NOTE Secure Boot is disabled by default. For details on how to enable Secure Boot, see Chapter 3. BG96_Secure_Boot_Application_Note 7 / 14 LPWA Module Series 2.3. Certificate Chain Secure Boot supports 2048-bit RSA public keys with exponent 3 or F4 (= 65537) for signatures of the certificates and images. The format of the certificate signatures meets the PKCS #1 v1.2 standard and the SHA256 or SHA384 algorithm. The certificate chain of the module supports two-level certificate chain which includes attestation certificate and self-signed root certificate. The X.509 v1, v2 and v3 certificate formats are all supported. 2.4. Image Signing During Secure Boot, the images to be executed in each boot stage must be signed first. Quectel firmware images use the standard MBN format, and each image includes several segments indicating different types of information separately, wherein the hash table segment stores signature related information. The hash table segment also includes the hash values of each segment and the information about certificate trust chain. The images listed below must be signed in the Secure Boot process for Quectel BG96 modules. ⚫ apps.mbn ⚫ mba.mbn ⚫ qdsp6sw.mbn ⚫ ENPRG9x06.mbn ⚫ NPRG9x06.mbn ⚫ rpm.mbn ⚫ sbl1.mbn ⚫ tz.mbn 2.5. Hardware Foundation Quectel BG96 module includes a one-time programmable fuse. The initial state of the fuse is 0 (Secure Boot disabled). Once a writing operation is performed on the fuse (or the fuse is blown), the state of the fuse permanently becomes 1 (Secure Boot enabled). The state cannot be changed after the fuse is blown, which means that the Secure Boot enabling is an irreversible operation. BG96_Secure_Boot_Application_Note 8 / 14 LPWA Module Series 2.6. Secure Boot Toolkit Quectel provides a Secure Boot toolkit (Quectel SecBootTools) to generate related certificates and the sec.dat file, and to sign firmware images. The following document introduces the directory structure of Quectel SecBootTools in Windows system. Figure 1: Quectel SecBootTools Directory Structure Table 1: Quectel SecBootTools Directory Structure SN File/Folder 1 common 2 doc 3 firmwares 4 fw_orig 5 fw_signed 6 fw_signature.bat 7 gencerts.bat 8 contents.xml 9 README.txt 10 Release_History.txt Description Contains the toolchain for signature. Contains all reference documents on Secure Boot. Stores firmware packages to be signed and secure firehose configuration files. An intermediary for creating signed firmware packages. Stores signed firmware packages and intermediate files. Makes a signed firmware package. Generates the root certificate (qpsa_rootca.cer) and the attestation certificate (qpsa_attestca.cer) as well as the hash values. A configuration file used during signature. It cannot be modified. For more details about the above files or folders, refer to README.txt. Stores the release history of the tool. BG96_Secure_Boot_Application_Note 9 / 14 LPWA Module Series NOTE Contact Quectel Technical Support (support@quectel.com) to acquire the Secure Boot toolkit. 2.7. sec.dat The sec.dat file is vital for enabling Secure Boot, as it includes the configuration parameters for the following functions,. 1. Secure Boot enabling 2. JTAG access disabling 3. Anti-rollback enabling 4. Read/Write permissions disabling/enabling for fuses 5. Fuse blowing The sec.dat file is generated during the image signing procedure. See Chapter 3.1.4 for details. BG96_Secure_Boot_Application_Note 10 / 14 LPWA Module Series 3 Enable Secure Boot 3.1. Procedure 3.1.1. Preparation Store the original firmware package to be signed under fw_orig. Then, install Python and OpenSSL and check if paths of Python and OpenSSL defined in /common/scripts/env.bat are the same as the actual paths. 3.1.2. Generate Certificates and Public Key Hash Value Run gencerts.bat in the Secure Boot toolkit to generate a root certificate and an attestation certificate, as well as a public key hash value of the root certificate. The generated certificates are automatically stored in /fw_signed/output/certs, and they are used to sign images; and the hash value is used to verify the signed images. If any image does not pass verification, the loading of the image will fail. 3.1.3. Fill in Environment Variables Open fw_signature.bat and fill in the environment variables defined in fw_signature.bat with the firmware version to be signed. 3.1.4. Sign Images and Generate a Firmware Package Run fw_signature.bat in the toolkit to sign the necessary image files and generate a new firmware package. For the list of necessary images, see Chapter 2.4. The whole process includes: 1) Double click fw_signature.bat and then fw_signature.bat runs automatically to enter Stage 1. In Stage 1, sec.dat which contains the hash of the root CA is automatically generated and stored in /fw_signed/output/sec_dat. 2) Press any key to proceed to Stage 2, during which the necessary image files are signed one by one. Signed files are automatically stored in /fw_signed/output/9206tx. 3) Press any key to proceed to Stage 3, during which a new firmware package is automatically created BG96_Secure_Boot_Application_Note 11 / 14 LPWA Module Series in fw_signed and replaces the original image files with the signed image files of the same names. 4) Press any key to proceed to Stage 4, during which the firehose configuration file rawprogram_nand_p2K_b128K_update.xml in the new firmware package is replaced with a secure firehose configuration file rawprogram_nand_p2K_b128K_sec.xml, and partition_nand.xml is replaced with a secure-exclusive one. 3.1.5. Flash Firmware Flash the firmware with the signed package created in Chapter 3.1.4. For details about how to flash firmware, see document [1]. 3.2. Verification After firmware updating, send AT+QSECBOOTSTAT? to query whether Secure Boot is enabled on the module. 3.2.1. AT+QSECBOOTSTAT Query Secure Boot Status This command queries the current status of Secure Boot. AT+QSECBOOTSTAT Query Secure Boot Status Read Command AT+QSECBOOTSTAT? Response +QSECBOOTSTAT: OK Maximum Response Time Characteristics If there is any error related to ME functionality: ERROR 300 ms - Parameter Integer type. Secure Boot status. 0 Disabled 1 Enabled Example AT+QSECBOOTSTAT? //Query whether Secure Boot is enabled on the module. BG96_Secure_Boot_Application_Note 12 / 14 +QSECBOOTSTAT: 1 OK //Secure Boot is enabled. LPWA Module Series BG96_Secure_Boot_Application_Note 13 / 14 LPWA Module Series 4 Appendix References Table 2: Related Documents Document Name [1] Quectel_QFlash_User_Guide Table 3: Terms and Abbreviations Abbreviation ARM CA JTAG PBL PKCS RoT RSA SBL SHA Description Advanced RISC Machine Certificate Authority Joint Test Action Group Primary Boot Loader Public-Key Cryptography Standards Root of Trust Algorithm invented by Rivest, Adleman and Shamir Secondary Boot Loader Secure Hash Algorithm BG96_Secure_Boot_Application_Note 14 / 14
156.32 KB
BG96 RF FTM Application Note LPWA Module Series Version: 1.0 Date: 2022-02-18 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG96_RF_FTM_Application_Note 1 / 20 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG96_RF_FTM_Application_Note 2 / 20 LPWA Module Series About the Document Revision History Version Date Author - 2021-12-06 Hyman DING 1.0 2022-02-18 Hyman DING Description Creation of the document First official release BG96_RF_FTM_Application_Note 3 / 20 LPWA Module Series Contents About the Document ................................................................................................................................3 Contents .................................................................................................................................................... 4 Table Index ...............................................................................................................................................5 1 Introduction .......................................................................................................................................6 2 FTM AT Commands ..........................................................................................................................7 2.1. AT Command Introduction ........................................................................................................7 2.1.1. Definitions ......................................................................................................................7 2.1.2. AT Command Syntax .....................................................................................................7 2.2. Declaration of AT Command Examples ....................................................................................8 2.3. Description of AT Commands ...................................................................................................8 2.3.1. AT+QRFTESTMODE Enter/Exit FTM .........................................................................8 2.3.2. AT+QRFTEST Transmit in FTM ..................................................................................9 2.3.3. AT+QRXFTM Receive in FTM...................................................................................12 3 Examples .........................................................................................................................................15 3.1. Set the Module into FTM ........................................................................................................15 3.2. Transmit in FTM .....................................................................................................................15 3.3. Receive in FTM ......................................................................................................................18 4 Summary of CME ERROR Codes...................................................................................................19 5 Appendix References .....................................................................................................................20 BG96_RF_FTM_Application_Note 4 / 20 LPWA Module Series Table Index Table 1: Type of AT Commands and Responses ....................................................................................... 7 Table 2: Related CME ERROR Codes .................................................................................................... 19 Table 3: Terms and Abbreviations............................................................................................................ 20 BG96_RF_FTM_Application_Note 5 / 20 LPWA Module Series 1 Introduction The document describes the AT commands used to test the receiving and transmitting performance of Quectel BG96 module under FTM (Factory Test Mode), to facilitate RF calibration. BG96_RF_FTM_Application_Note 6 / 20 LPWA Module Series 2 FTM AT Commands 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 1: Type of AT Commands and Responses Command Type Syntax Description Test Command Read Command Write Command Execution Command AT+=? AT+? AT + < c m d > = < p 1 > [ , < p 2 > [ , < p 3 > [...]]] AT+ Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. Set user-definable parameter value. Return a specific information parameter or perform a specific action. BG96_RF_FTM_Application_Note 7 / 20 LPWA Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 2.3. Description of AT Commands 2.3.1. AT+QRFTESTMODE Enter/Exit FTM This command makes the module enter/exit FTM. AT+QRFTEST (see Chapter 2.3.2) and AT+QRXFTM (see Chapter 2.3.3) are available only when the module enters FTM with this command. AT+QRFTESTMODE Enter/Exit FTM Test Command AT+QRFTESTMODE=? Response +QRFTESTMODE: (list of supported s) Read Command AT+QRFTESTMODE? OK Response +QRFTESTMODE: Write Command AT+QRFTESTMODE= OK Response OK Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: If there is any other error: ERROR 300 ms This command takes effect after rebooting. The configuration will be saved automatically. BG96_RF_FTM_Application_Note 8 / 20 Parameter Integer type. Enter/exit FTM. 0 Exit 1 Enter See Chapter 4. LPWA Module Series 2.3.2. AT+QRFTEST Transmit in FTM This command forces the module to transmit in FTM. AT+QRFTEST Transmit in FTM Test Command Currently only returns the parameters supported by the Write Command in GSM AT+QRFTEST=? Response +QRFTEST: ,,,, OK Write Command In GSM: AT+QRFTEST=,,, , Response ALL ON OK Or ALL OFF OK If there is any error related to ME functionality: +CME ERROR: If there is any other error: ERROR Write Command In LTE-M: AT+QRFTEST=,,, , Response ALL ON OK Or ALL OFF OK If there is any error related to ME functionality: +CME ERROR: BG96_RF_FTM_Application_Note 9 / 20 LPWA Module Series If there is any other error: ERROR Write Command In NB-IoT: AT+QRFTEST=,,, ,,,,,, Response ALL ON OK Or ALL OFF OK If there is any error related to ME functionality: +CME ERROR: Maximum Response Time Characteristics If there is any other error: ERROR 300 ms This command takes effect immediately. The configurations will not be saved. Parameter String type. The supported bands in GSM/LTE. The possible values are: For GSM: 'GSM850' 'GSM900' 'GSM1800' 'GSM1900' For LTE: 'LTE BAND1' 'LTE BAND2' 'LTE BAND3' 'LTE BAND4' 'LTE BAND5' 'LTE BAND8' 'LTE BAND12' 'LTE BAND13' 'LTE BAND18' 'LTE BAND19' 'LTE BAND20' 'LTE BAND25' 'LTE BAND26' 'LTE BAND28' Integer type. The supported uplink channels in GSM/LTE. The corresponding channels BG96_RF_FTM_Application_Note 10 / 20 LPWA Module Series for different bands in GSM/LTE are as follows: Uplink Channels GSM band 128–251 GSM850 1–124, 975–1023 GSM900 512–885 GSM1800 512–810 GSM1900 Uplink Channels LTE band 18000–18599 LTE BAND1 18600–19199 LTE BAND2 19200–19949 LTE BAND3 19950-20399 LTE BAND4 20400–20649 LTE BAND5 21450–21799 LTE BAND8 23010–23179 LTE BAND12 23180–23279 LTE BAND13 23850–23999 LTE BAND18 24000–24149 LTE BAND19 24150–24449 LTE BAND20 26040–26689 LTE BAND25 26690–27039 LTE BAND26 27210–27659 LTE BAND28 String type. Enable/disable RF TX. 'ON' Enable 'OFF' Disable Integer type. 0 Continuous TX mode Integer type. GSM power level (GSM power in dBm × 100). Range: 0–3300. Recommended value: not to exceed 3100. Integer type. LTE power level. Range: 0–100. Recommended value: not to exceed 75. Integer type. 1 LTE modulated TX mode Integer type. Uplink carrier frequency offset. Range: -128 to 127. Integer type. Modulation type. 0 BPSK 1 QPSK Integer type. TX power in dBm. Range: -128 to 127. Integer type. Uplink tone bandwidth. 0 Single-tone, 3.75 kHz 1 Single-tone, 15 kHz 2 Multi-tone, 3 × 15 kHz 3 Multi-tone, 6 × 15 kHz 4 Multi-tone, 12 × 15 kHz Integer type. Tone start index. Range: 0–255. See Chapter 4. BG96_RF_FTM_Application_Note 11 / 20 LPWA Module Series NOTE 1. Please refer to Section 5.7.3F Carrier frequency and EARFCN for category NB1 and NB2 in 3GPP TS 36.101, to calculate the specific uplink carrier frequency offset, namely, the value of . 2. For LTE-M, the default bandwidth is 10 MHz currently. 2.3.3. AT+QRXFTM Receive in FTM This command forces the module to receive in FTM. AT+QRXFTM Receive in FTM Test Command AT+QRXFTM=? Response +QRXFTM: ,,,,, Read Command AT+QRXFTM? Write Command AT+QRXFTM=,,[,[,[,]]] OK Response OK Response +QRXFTM: , OK If there is any error related to ME functionality: +CME ERROR: Maximum Response Time Characteristics If there is any other error: ERROR 3000 ms The command takes effect immediately. The configurations will not be saved. Parameter Integer type. 1 LTE RX test String type. The supported bands in GSM/LTE. The possible values are: For GSM: 'GSM850' 'GSM900' 'GSM1800' 'GSM1900' BG96_RF_FTM_Application_Note 12 / 20 LPWA Module Series For LTE: 'LTE BAND1' 'LTE BAND2' 'LTE BAND3' 'LTE BAND4' 'LTE BAND5' 'LTE BAND8' 'LTE BAND12' 'LTE BAND13' 'LTE BAND18' 'LTE BAND19' 'LTE BAND20' 'LTE BAND26' 'LTE BAND28' Integer type. The supported downlink channels in GSM/LTE. The corresponding channels for different bands in GSM/LTE are as follows: Downlink Channels GSM band 128–251 GSM850 1–124, 975–1023 GSM900 512–885 GSM1800 512–810 GSM1900 Downlink Channels LTE band 0–599 LTE BAND1 600-1199 LTE BAND2 1200–1949 LTE BAND3 1950–2399 LTE BAND4 2400–2649 LTE BAND5 3450–3799 LTE BAND8 5010–5179 LTE BAND12 5180–5279 LTE BAND13 5850–5999 LTE BAND18 6000–6149 LTE BAND19 6150–6449 LTE BAND20 8690–9039 LTE BAND26 9210–9659 LTE BAND28 Integer type. 0 Main antenna path. Integer type. Gain stage. Range: 0–5. Default value: 0. Integer type. Bandwidth. Range: 0–5. This parameter is only valid for LTE RAT (i.e., not applicable for GSM RAT). 0 1.4 MHz 1 3 MHz 2 5 MHz 3 10 MHz BG96_RF_FTM_Application_Note 13 / 20 LPWA Module Series 4 15 MHz 5 20 MHz Integer type. The value of the received power. Integer type. Received power level in dBm converted from . See Chapter 4. NOTE 1. The responses of AT+QRXFTM=,,[,[,[,]]] are instantaneous values. 2. Currently, this command only supports LTE RX in FTM. 3. In LTE RAT, the value of is equal to the value of /10. BG96_RF_FTM_Application_Note 14 / 20 LPWA Module Series 3 Examples 3.1. Set the Module into FTM AT+QRFTESTMODE=? +QRFTESTMODE: (0,1) OK AT+QRFTESTMODE=1 OK //After the module reboots AT+QRFTESTMODE? +QRFTESTMODE: 1 OK AT+QRFTESTMODE=0 OK //After the module reboots AT+QRFTESTMODE? +QRFTESTMODE: 0 OK //Test command //Enter FTM //Query the current FTM state of the module //Exit FTM //Query the current FTM state of the module 3.2. Transmit in FTM AT+QRFTESTMODE=1 OK //After the module reboots //In GSM RAT AT+QRFTEST='GSM900',122,'ON',0,100 ALL ON //Enter FTM //Enable RF TX on 122 channel of GSM900 BG96_RF_FTM_Application_Note 15 / 20 LPWA Module Series OK AT+QRFTEST='GSM900',122,'OFF',0,100 ALL OFF //Disable RF TX on 122 channel of GSM900 OK //In LTE-M RAT AT+QRFTEST='LTE BAND1',18300,'ON',50,1 ALL ON //Enable RF TX on 18300 channel of LTE B1 OK AT+QRFTEST='LTE BAND1',18300,'OFF',50,1 ALL OFF //Disable RF TX on 18300 channel of LTE B1 OK AT+QRFTEST='LTE BAND2',18900,'ON',50,1 ALL ON //Enable RF TX on 18900 channel of LTE B2 OK AT+QRFTEST='LTE BAND2',18900,'OFF',50,1 ALL OFF //Disable RF TX on 18900 channel of LTE B2 OK AT+QRFTEST='LTE BAND12',23095,'ON',50,1 ALL ON //Enable RF TX on 23095 channel of LTE B12 OK AT+QRFTEST='LTE BAND12',23095,'OFF',50,1 ALL OFF //Disable RF TX on 23095 channel of LTE B12 OK AT+QRFTEST='LTE BAND20',24300,'ON',50,1 ALL ON //Enable RF TX on 24300 channel of LTE B20 OK AT+QRFTEST='LTE BAND20',24300,'OFF',50,1 ALL OFF //Disable RF TX on 24300 channel of LTE B20 OK AT+QRFTEST='LTE BAND28',27435,'ON',50,1 ALL ON //Enable RF TX on 27435 channel of LTE B28 OK AT+QRFTEST='LTE BAND28',27435,'OFF',50,1 //Disable RF TX on 27435 channel of LTE B28 BG96_RF_FTM_Application_Note 16 / 20 LPWA Module Series ALL OFF OK //In NB-IoT RAT AT+QRFTEST='LTE BAND1',18300,'ON',50,1,100,0,50,4,0 ALL ON //Enable RF TX on 18300 channel of LTE B1 OK AT+QRFTEST='LTE BAND1',18300,'OFF',50,1,100,0,50,4,0 ALL OFF //Disable RF TX on 18300 channel of LTE B1 OK AT+QRFTEST='LTE BAND2',18900,'ON',50,1,100,0,50,4,0 ALL ON //Enable RF TX on 18900 channel of LTE B2 OK AT+QRFTEST='LTE BAND2',18900,'OFF',50,1,100,0,50,4,0 ALL OFF //Disable RF TX on 18900 channel of LTE B2 OK AT+QRFTEST='LTE BAND20',24300,'ON',50,1,100,0,50,4,0 ALL ON //Enable RF TX on 24300 channel of LTE B20 OK AT+QRFTEST='LTE BAND20',24300,'OFF',50,1,100,0,50,4,0 ALL OFF //Disable RF TX on 24300 channel of LTE B20 OK AT+QRFTEST='LTE BAND28',27435,'ON',50,1,100,0,50,4,0 ALL ON //Enable RF TX on 27435 channel of LTE B28 OK AT+QRFTEST='LTE BAND28',27435,'OFF',50,1,100,0,50,4,0 ALL OFF //Disable RF TX on 27435 channel of LTE B28 BG96_RF_FTM_Application_Note 17 / 20 OK AT+QRFTESTMODE=0 OK //Reboot the module LPWA Module Series //Exit FTM 3.3. Receive in FTM AT+QRFTESTMODE=1 OK //Enter FTM //After the module reboots //In LTE RAT AT+QRXFTM=1,'LTE BAND1',300,0,0,0 +QRXFTM: -1100,-110 //Enable RF RX on 300 channel of LTE B1 OK AT+QRXFTM=1,'LTE BAND2',900,0,0,0 +QRXFTM: -1100,-110 //Enable RF RX on 900 channel of LTE B2 OK AT+QRXFTM=1,'LTE BAND12',5095,0,0,0 +QRXFTM: -1100,-110 //Enable RF RX on 5095 channel of LTE B12 OK AT+QRXFTM=1,'LTE BAND20',6300,0,0,0 +QRXFTM: -1100, -110 //Enable RF RX on 6300 channel of LTE B20 OK AT+QRXFTM=1,'LTE BAND28',9435,0,0,0 +QRXFTM: -1100,-110 //Enable RF RX on 9435 channel of LTE B28 OK AT+QRFTESTMODE=0 OK //Reboot the module //Exit FTM BG96_RF_FTM_Application_Note 18 / 20 LPWA Module Series 4 Summary of CME ERROR Codes The CME ERROR code indicates an error related to mobile equipment or network. The details about are described in the following table. Table 2: Related CME ERROR Codes Meaning 4 Incorrect AT command name or parameter -15 Invalid input parameter. BG96_RF_FTM_Application_Note 19 / 20 LPWA Module Series 5 Appendix References Table 3: Terms and Abbreviations Abbreviation BPSK LTE-M FTM GSM LNA LPWA LTE NB-IoT QPSK RAT RF RX TX Description Binary Phase Shift Keying LTE-MTC (Machine Type Communication) Factory Test Mode Global System for Mobile Communications Low Noise Amplifier Low-Power Wide-Area Long Term Evolution Narrowband Internet of Things Quadrature Phase Shift Keying Radio Access Technology Radio Frequency Receive Transmit BG96_RF_FTM_Application_Note 20 / 20
185.38 KB
L89 R2.0&LC29H&LC79H Firmware Upgrade Guide GNSS Module Series Version: 1.2 Date: 2022-04-12 Status: Released GNSS Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 1 / 27 GNSS Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 2 / 27 GNSS Module Series About the Document Document Information Title Subtitle Document Type Document Status L89 R2.0&LC29H&LC79H Firmware Upgrade Guide GNSS Module Series Firmware Upgrade Guide Released Revision History Version Date - 2021-04-28 1.0 2021-05-19 1.1 2021-08-18 1.2 2022-04-12 Description Creation of the document First official release Added the applicable module LC79H. 1. Added the default UART baud rate for firmware upgrades of the applicable modules. 2. Updated List of Constants and added a note on the format length for LC29H (BA, CA) (Table 1); 3. Added the information about DA files and updated the checksum code of DA file (Chapter 2.1.3); 4. Updated the diagram of Sync with DA and Get DA Report (Figure 7); 5. Updated the diagram of Format Flash (Figure 8); 6. Updated the diagram of Send FW File to Module, added checksum code of the FW packet, and added notes about the FW file and FW packet (Chapter 2.1.7); 7. Updated the upgrade implementation example (Chapter 3); 8. Deleted the chapter of Disconnect Module. L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 3 / 27 GNSS Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 2 Firmware Upgrade Process ............................................................................................................... 8 2.1. Communication Between Host and Module ............................................................................ 10 2.1.1. Handshake with Module................................................................................................ 11 2.1.2. Disable Module WDT .................................................................................................... 12 2.1.3. Send DA File to Module ................................................................................................ 13 2.1.4. Jump to DA.................................................................................................................... 14 2.1.5. Sync with DA ................................................................................................................. 14 2.1.6. Format Flash ................................................................................................................. 16 2.1.7. Send FW File to Module ............................................................................................... 17 3 Upgrade Implementation Example.................................................................................................. 19 4 Appendix Reference ......................................................................................................................... 27 L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 4 / 27 GNSS Module Series Table Index Table 1: List of Constants ............................................................................................................................ 8 Table 2: Terms and Abbreviations ............................................................................................................. 27 L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 5 / 27 GNSS Module Series Figure Index Figure 1: Firmware Upgrade Connection..................................................................................................... 7 Figure 2: Communication Between Host and Module ............................................................................... 10 Figure 3: Handshake .................................................................................................................................. 11 Figure 4: Disable Module WDT .................................................................................................................. 12 Figure 5: Send DA File to Module .............................................................................................................. 13 Figure 6: Jump to DA ................................................................................................................................. 14 Figure 7: Sync with DA and Get DA Report............................................................................................... 15 Figure 8: Format Flash ............................................................................................................................... 16 Figure 9: Send FW File to Module ............................................................................................................. 17 L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 6 / 27 GNSS Module Series 1 Introduction This document introduces the procedure to upgrade the firmware of the Quectel L89 R2.0, LC29H and LC79H GNSS modules. Following the procedure illustrated in this document, you can upgrade and download the firmware to the target GNSS module via the UART interface. The baud rate for firmware upgrade is 115200 bps by default. HOST UART GNSS Module Figure 1: Firmware Upgrade Connection L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 7 / 27 GNSS Module Series 2 Firmware Upgrade Process This chapter describes all the necessary steps in the firmware upgrade process. The following table defines all the constants used in this document. Table 1: List of Constants Constant Name Constant Value Steps BROM_ERROR Module WDT Register Address WDT Value DA Run/Start Address DA Length Flash Manufacturer ID Flash Device ID1 Flash Device ID2 Flash Mount Status Flash Base Address 0x1000 0xA2080000 0x0010 0x04204000 0x00006CF7 (DA file requiring 115200 bps for transmission) 0x00006DCB (DA file requiring 921600 bps for transmission) 0x00EF 0x0060 0x0016 0x00000000 0x08000000 Figure 4: Disable Module WDT Figure 5: Send DA File to Module Figure 6: Jump to DA Figure 4: Disable Module WDT Figure 4: Disable Module WDT Figure 5: Send DA File to Module Figure 6: Jump to DA Figure 5: Send DA File to Module Figure 7: Sync with DA and Get DA Report Figure 7: Sync with DA and Get DA Report Figure 7: Sync with DA and Get DA Report Figure 7: Sync with DA and Get DA Report Figure 7: Sync with DA and Get DA Report L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 8 / 27 Flash Size Format Physical Address Format Length 1) FW Flash Address FW Packet Length 0x00400000 0x08000000 0x00400000 0x08000000 (partition_table.bin) 0x08003000 (ag3335_bootloader.bin) 0x08013000 (gnss_demo.bin) 0x083FF000 (gnss_config.bin) 0x00001000 GNSS Module Series Figure 7: Sync with DA and Get DA Report Figure 8: Format Flash Figure 8: Format Flash Figure 9: Send FW File to Module Figure 9: Send FW File to Module NOTE 1. The bytes to be sent are transmitted in the big-endian format. 2. 1) When upgrading the firmware of LC29H (BA, CA), the Format Length must be set to 0x003EF000. L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 9 / 27 2.1. Communication Between Host and Module GNSS Module Series Module powers on Host sends handshaking command to the module via UART port Module response Disable module WDT Module response Send DA file to the module Module response Jump to DA Module response Sync with DA Module response Format flash Module response Send FW files to the module NO Has the host sent all the FW files? YES Reset the module END Figure 2: Communication Between Host and Module L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 10 / 27 GNSS Module Series The following sections illustrate how the host establishes communication with the module and sends commands and files to the module: ⚫ Handshake with the module ⚫ Disable module WDT (Watch Dog Timer) ⚫ Send DA (Download Agent) file to the module ⚫ Jump to DA ⚫ Sync with DA ⚫ Format flash ⚫ Send FW (firmware) files to the module 2.1.1. Handshake with Module This section describes the handshaking mechanism for the communication between the host and the module. After the module is powered on, it waits for 150 milliseconds for 0xA0 sent by the host. If it fails to receive the 0xA0, the handshake fails. Host Module waits for 150 milliseconds for 0xA0 sent by the Host SEND(0xA0) SEND(0xA0) RECEIVE(0x5F) SEND(0x0A) RECEIVE(0xF5) SEND(0x50) RECEIVE(0xAF) SEND(0x05) RECEIVE(0xFA) Module Module powers on Figure 3: Handshake NOTE The host sends 0xA0 repeatedly until it receives 0x5F from the module, and then sends 0x0A. L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 11 / 27 GNSS Module Series 2.1.2. Disable Module WDT The following diagram illustrates how to disable module WDT to avoid module reboot. Host Module SEND(0xD2) RECEIVE(0xD2) SEND(Module WDT register address, 4 bytes) RECEIVE(Module WDT register address, 4 bytes) SEND(0x00000001) RECEIVE(0x00000001) RECEIVE(Brom status, 2 bytes)1) SEND(WDT value, 2 bytes) RECEIVE(WDT value, 2 bytes) RECEIVE(Brom status, 2 bytes)1) Figure 4: Disable Module WDT NOTE 1) means Brom status must not be BROM_ERROR. L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 12 / 27 GNSS Module Series 2.1.3. Send DA File to Module The following diagram illustrates how to send a DA file to the module. You can use either of the two DA files provided: one requires the baud rate of 921600 bps for transmission, and the other requires the baud rate of 115200 bps. Host Module SEND(0xD7) RECEIVE(0xD7) SEND(DA run/start address, 4 bytes) RECEIVE(DA run/start address, 4 bytes) SEND(DA length, 4 bytes) RECEIVE(DA length, 4 bytes) SEND(0x00000000) RECEIVE(0x00000000) RECEIVE(Brom status, 2 bytes)1) SEND(DA data, 1024 bytes) SEND(DA data, 1024 bytes) SEND(DA data, length 1024 bytes) RECEIVE(Brom checksum of received DA, 2 bytes ) RECEIVE(Brom status, 2 bytes)1) Module keeps receiving DA data from Host Flash/FS until the entire DA file is sent. Checksum of the entire DA file Figure 5: Send DA File to Module NOTE 1) means Brom status must not be BROM_ERROR. Checksum Code of DA File uint16_t DA_compute_checksum (uint8_t *buf, uint32_t buf_len) { L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 13 / 27 GNSS Module Series uint16_t checksum = 0; if (buf == NULL || buf_len == 0) { return 0; } int i = 0; for (i = 0; i < buf_len / 2; i++) { checksum ^= *(uint16_t *) (buf + i * 2); } if ((buf_len % 2) == 1) { checksum ^= buf[i * 2]; } return checksum; } uint16_t local_check_sum ^= DA_compute_checksum(data_buf, len); 2.1.4. Jump to DA The following diagram illustrates how to inject the DA and how to execute it. Host SEND(0xD5) RECEIVE(0xD5) SEND(DA run/start address, 4 bytes) RECEIVE(DA run/start address, 4 bytes) RECEIVE(Brom status, 2 bytes)1) Module Figure 6: Jump to DA NOTE 1) means Brom status must not be BROM_ERROR. 2.1.5. Sync with DA The following diagram illustrates how to sync with DA and get the DA report in detail. L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 14 / 27 GNSS Module Series Host RECEIVE(0xC0) SEND(0x3F) RECEIVE(0x0C) SEND(0xF3) RECEIVE(0x3F) SEND(0xC0) RECEIVE(0xF3) SEND(0x0C00) RECEIVE(0x5A6969) SEND(0x5A00) RECEIVE(0x69) SEND(0x5A) RECEIVE(0x69) SEND(0x5A) SEND(0xC0) RECEIVE(0xC0) SEND(0x5A) RECEIVE(0x5A69) SEND(0x5A) Module Set UART baud rate to 115200 or 921600 bps, then sync with DA. (For the DA file that requires the baud rate of 921600 bps for transmission, change the UART baud rate to 921600 bps; for the other DA file, keep the baud rate at 115200 bps.) RECEIVE(Flash manufacturer ID, 2 bytes) RECEIVE(Flash device ID1, 2 bytes) RECEIVE(Flash device ID2, 2 bytes) RECEIVE(Flash mount status, 0, 4 bytes) RECEIVE(Flash base address, 4 bytes) RECEIVE(Flash size, 4 bytes) RECEIVE(0x5A) SEND(0x5A) Get DA report from the module. Figure 7: Sync with DA and Get DA Report L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 15 / 27 GNSS Module Series 2.1.6. Format Flash The following diagram illustrates how to format the module’s flash. Host SEND(0xD400) SEND(Format physical address, 4 bytes) SEND(Format length, 4 bytes) RECEIVE(0x5A5A) RECEIVE(0x00000BCD) RECEIVE(0x01) SEND(0x5A) RECEIVE(0x00000BCD) RECEIVE(0x02) SEND(0x5A) RECEIVE(0x00000BCD) RECEIVE(0x03) Module If the checksum verification fails, the module will return 0x5A and error code. Formatting progress SEND(0x5A) RECEIVE(0x00000BCD) RECEIVE(0x63) SEND(0x5A) RECEIVE(0x00000000) RECEIVE(0x64) SEND(0x5A) RECEIVE(0x5A) Figure 8: Format Flash L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 16 / 27 GNSS Module Series 2.1.7. Send FW File to Module The following diagram illustrates how to send FW files to the module. Host SEND(0xB2) SEND(FW flash address, 4 bytes) SEND(FW total length 1) , 4 bytes) SEND(FW packet length 2) , 4 bytes) RECEIVE(0x5A5A) SEND(FW packet, 4096 bytes) SEND(checksum of FW packet, 4 bytes) RECEIVE(0x69) SEND(FW packet, 4096 bytes) SEND(checksum of FW packet, 4 bytes) RECEIVE(0x69) Module If check fails, module will return 0x5A and error code. Host sends the FW file SEND(FW packet, 4096 bytes) SEND(checksum of FW packet, 4 bytes) RECEIVE(0x69) RECEIVE(0x5A) SEND(Total FW checksum, 4 bytes) RECEIVE(0x5A) SEND(0x5A/0xA5) RECEIVE(0x5A) If this FW is bootloader, send 0x5A, otherwise send 0xA5. Figure 9: Send FW File to Module L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 17 / 27 GNSS Module Series NOTE 1. 1) The FW total length must be an integer multiple of 4K. 2. 2) Size of each packet is 4096 bytes. Checksum Code of the FW Packet uint32_t CRC_compute_simple_checksum (uint8_t *buf, uint32_t buf_len) { uint32_t checksum = 0; if (buf == NULL || buf_len == 0) { return 0; } for (int i = 0; i < buf_len; i++) { checksum += *(buf + i); } return checksum; } uint32_t packet_checksum = CRC_compute_simple_checksum (buf, buf_len); //Total Checksum Code of the FW file: uint32_t Total_FW_checksum += packet_checksum; NOTE If the last FW packet is less than 4096 bytes, add '0xFF' at the end of the last FW packet. L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 18 / 27 GNSS Module Series 3 Upgrade Implementation Example Below is an example of the L89 R2.0 firmware upgrade. //Figure 3: Handshake //Host keeps sending 0xA0, and the module is powered on. A0 A0 A0 … A0 A0 A0 A0 //Module responds with 0x5F. 5F //Host sends 0x0A. 0A //Module responds with 0xF5. F5 //Host sends 0x50. 50 //Module responds with 0xAF. AF //Host sends 0x05. 05 //Module responds with 0xFA. FA //Figure 4: Disable Module WDT //Host sends 0xD2. D2 //Module responds with 0xD2. D2 //Host sends 0xA2080000. A2 08 00 00 //Module responds with 0xA2080000. A2 08 00 00 //Host sends 0x00000001. L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 19 / 27 GNSS Module Series 00 00 00 01 //Module responds with 0x00000001. 00 00 00 01 //Module responds with Brom status. 00 01 //Host sends 0x0010. 00 10 //Module responds with 0x0010. 00 10 //Module responds with Brom status. 00 01 //Figure 5: Send DA File to Module //Host sends 0xD7. D7 //Module responds with 0xD7. D7 //Host sends DA run/start address. 04 20 40 00 //Module responds with DA run/start address. 04 20 40 00 //Host sends DA length. (For DA file requiring the baud rate of 115200 bps for transmission, the DA length is '00 00 6C F7'; for DA file requiring the baud rate of 921600 bps for transmission, the DA length is '00 00 6D CB'.) 00 00 6C F7 //Module responds with DA length. 00 00 6C F7 //Host sends 0x00000000. 00 00 00 00 //Module responds with 0x00000000. 00 00 00 00 //Module responds with Brom status. 00 00 //Host sends DA data, in a chunk of 1 KB. 27 B6 11 49 11 4A 4F F0 00 00 91 42 00 F0 05 80 41 F8 04 0B 91 42 7F F6 …… //Host sends DA data, in a chunk of 1 KB. 23 48 08 3E 1F 46 89 46 92 46 FF F7 95 FF 10 23 33 60 34 68 1F 4D E3 06 …… …… //Host sends the last chunk of DA data. (length ≤ 1 KB) 65 73 73 28 30 78 25 78 29 20 74 6F 20 62 6C 6F 63 6B 20 69 6E 64 65 78 …… //Module responds with Brom checksum of the received DA (2 bytes). 46 1D (Checksum Code of DA File) //Module responds with Brom status. 00 00 //Figure 6: Jump to DA L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 20 / 27 GNSS Module Series //Host sends 0xD5. D5 //Module responds with 0xD5. D5 //Host sends DA run/start address. 04 20 40 00 //Module responds with DA run/start address. 04 20 40 00 //Module responds with Brom status. 00 00 //Figure 7: Sync with DA //Module responds with 0xC0. C0 //Host sends 0x3F. 3F //Module responds with 0x0C. 0C //Host sends 0xF3. F3 //Module responds with 0x3F. 3F //Host sends 0xC0. C0 //Module responds with 0xF3. F3 //Host sends 0x0C00. 0C 00 //Module responds with 0x5A6969. 5A 69 69 //Host sends 0x5A00. 5A 00 //Module responds with 0x69. 69 //Host sends 0x5A. 5A //Module responds with 0x69. 69 //Host sends 0x5A. 5A //Host sends 0xC0. (For the DA file that requires the baud rate of 921600 bps for transmission, change the UART baud rate to 921600 bps; for the other DA file, keep the baud rate at 115200 bps.) C0 //Module responds with 0xC0. C0 L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 21 / 27 GNSS Module Series //Host sends 0x5A. 5A //Module responds with 0x5A69. 5A 69 //Host sends 0x5A. 5A //Module responds with flash manufacturer ID. 00 EF //Module responds with flash device ID1. 00 60 //Module responds with flash device ID2. 00 16 //Module responds with flash mount status. 00 00 00 00 //Module responds with flash base address. 08 00 00 00 //Module responds with flash size. 00 40 00 00 //Module responds with 0x5A. 5A //Host sends 0x5A. 5A //Figure 8: Format Flash //Host sends 0xD400. D4 00 //Host sends format physical address. 08 00 00 00 //Host sends format length. (When upgrading the firmware of LC29H (BA, CA), the format length must be set to '00 3E F0 00'.) 00 40 00 00 //Module responds with 0x5A5A. 5A 5A //Module responds with 0x00000BCD and formatting progress. 00 00 0B CD 01 //Host sends 0x5A and waits for the module to respond with 0x00000BCD and formatting progress. 5A 00 00 0B CD 02 //Host sends 0x5A and waits for the module to respond with 0x00000BCD and formatting progress. 5A 00 00 0B CD 03 //Host sends 0x5A and waits for the module to respond with 0x00000BCD and formatting progress. 5A 00 00 0B CD 04 …… //Host sends 0x5A and waits for the module to respond with 0x00000BCD and formatting progress. 5A 00 00 0B CD 63 //Host sends 0x5A and waits for the module to respond with 0x00000000 and formatting progress. L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 22 / 27 GNSS Module Series 5A 00 00 00 00 64 //Host sends 0x5A. 5A //Module responds with 0x5A. 5A //Figure 9: Send FW File to Module //Host sends 0xB2. B2 //Host sends FW flash address (partition_table.bin). 08 00 00 00 //Host sends FW total length (partition_table.bin). 00 00 10 00 //Host sends FW packet length (4 bytes). 00 00 10 00 //Module responds with 0x5A5A. 5A 5A //Host sends FW packet (4096 bytes). 00 00 00 00 00 00 00 00 00 00 00 00 00 10 00 08 00 00 00 00 00 10 00 00 …… //Host sends checksum of FW packet (4 bytes). 00 0E 7B 22 (Checksum Code of the FW Packet) //Module responds with 0x695A. 69 5A //Host sends the total FW checksum (4 bytes). 00 0E 7B 22 (Checksum Code of the FW Packet) //Module responds with 0x5A. 5A //Host sends 0x5A/0xA5. (If this FW is ag3335_bootloader.bin, send 0x5A, otherwise send 0xA5.) A5 //Module responds with 0x5A. 5A //Host sends 0xB2. B2 //Host sends FW flash address (ag3335_bootloader.bin). 08 00 30 00 //Host sends FW total length (ag3335_bootloader.bin). (4K alignment: the FW total length must be an integer multiple of 4K.) 00 00 50 00 //Host sends FW packet length (4 bytes). 00 00 10 00 //Module responds with 0x5A5A. 5A 5A //Host sends FW packet (4096 bytes). DF F8 3C D0 72 B6 00 20 03 21 0E 4A 42 F8 04 0B 11 60 0D 4A 0D 4B 00 F0 …… //Host sends checksum of FW packet (4 bytes). L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 23 / 27 GNSS Module Series 00 05 AD 0C (Checksum Code of the FW Packet) //Module responds with 0x69. 69 //Host sends FW packet (4096 bytes). D4 30 00 20 10 BD 00 BF C7 28 00 04 4F F4 40 73 A1 F8 BC 30 4F F4 80 73 …… //Host sends checksum of FW packet (4 bytes). 00 05 67 E0 (Checksum Code of the FW Packet) //Module responds with 0x69. 69 //Host sends FW packet (4096 bytes). 65 6C 20 70 61 73 73 21 0D 0A 00 72 69 73 69 6E 67 20 66 72 65 71 20 74 …… //Host sends checksum of FW packet (4 bytes). 00 05 D5 53 (Checksum Code of the FW Packet) // Module responds with 0x69. 69 //Host sends FW packet (4096 bytes). 70 B5 D0 F8 C8 30 DA 06 04 46 0D 46 01 D4 FF F7 54 FF D4 F8 C8 30 DB 06 …… //Host sends checksum of FW packet (4 bytes). 00 06 D9 83 (Checksum Code of the FW Packet) //Module responds with 0x69. 69 //Host sends FW packet (4096 bytes). 06 48 04 E0 06 48 02 E0 06 48 00 E0 06 48 00 EB 81 00 FF F7 B3 BF 6F F0 …… //Host sends checksum of FW packet (4 bytes). 00 0D 0D 06 (Checksum Code of the FW Packet) //Module responds with 0x695A. 69 5A //Host sends the total FW checksum (4 bytes). 00 24 D0 C8 (Checksum Code of the FW Packet) //Module responds with 0x5A. 5A //Host sends 0x5A/0xA5. (If this FW is ag3335_bootloader.bin, send 0x5A, otherwise send 0xA5.) 5A //Module responds with 0x5A. 5A //Host sends 0xB2. B2 //Host sends FW flash address (gnss_demo.bin). 08 01 30 00 //Host sends FW total length (gnss_demo.bin). (4K alignment: the FW total length must be an integer multiple of 4K.) 00 11 50 00 //Host sends FW packet length (4 bytes). 00 00 10 00 L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 24 / 27 GNSS Module Series //Module responds with 0x5A5A. 5A 5A //Host sends FW packet (4096 bytes). DF F8 A0 D0 72 B6 28 48 80 47 28 48 28 49 01 60 28 48 29 49 01 60 29 48 …… //Host sends checksum of FW packet (4 bytes). 00 06 A7 58 (Checksum Code of the FW Packet) //Module responds with 0x69. 69 //Host sends FW packet (4096 bytes). C3 80 60 46 89 1A B1 FB F6 F2 AD B2 06 FB 12 11 45 EA 01 45 07 FB 02 F7 …… //Host sends checksum of FW packet (4 bytes). 00 06 26 F9 (Checksum Code of the FW Packet) //Module responds with 0x69. 69 //Host sends FW packet (4096 bytes). 20 46 0A 46 0B 46 00 F0 EF F9 3D E0 01 21 20 46 00 F0 C2 FA 24 49 2A 46 …… //Host sends checksum of FW packet (4 bytes). 00 06 25 D6 (Checksum Code of the FW Packet) //Module responds with 0x69. 69 …… //Host sends FW packet (4096 bytes). FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF …… //Host sends checksum of FW packet (4 bytes). 00 0F F0 00 (Checksum Code of the FW Packet) //Module responds with 0x695A. 69 5A //Host sends the total FW checksum (4 bytes). 07 B8 3C 46 (Checksum Code of the FW Packet) //Module responds with 0x5A. 5A //Host sends 0x5A/0xA5. (If this FW is ag3335_bootloader.bin, send 0x5A, otherwise send 0xA5.) A5 //Module responds with 0x5A. 5A //Host sends 0xB2. B2 //Host sends FW flash address (gnss_config.bin). 08 3F F0 00 //Host sends FW total length (gnss_config.bin). (4K alignment: the FW total length must be an integer multiple of 4K.) 00 00 10 00 //Host sends FW packet length (4 bytes). 00 00 10 00 L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 25 / 27 GNSS Module Series //Module responds with 0x5A5A. 5A 5A //Host sends FW packet (4096 bytes). 01 01 01 FF FF FF FF FF FF FF FF FF FF FF FF FF 01 64 00 00 00 FF FF FF …… //Host sends checksum of FW packet (4 bytes). 00 0E 46 9E (Checksum Code of the FW Packet) //Module responds with 0x695A. 69 5A //Host sends the total FW checksum (4 bytes). 00 0E 46 9E (Checksum Code of the FW Packet) //Module responds with 0x5A. 5A //Host sends 0x5A/0xA5. (If this FW is ag3335_bootloader.bin, send 0x5A, otherwise send 0xA5.) A5 //Module responds with 0x5A. 5A L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 26 / 27 GNSS Module Series 4 Appendix Reference Table 2: Terms and Abbreviations Abbreviation CRC DA FS FW GNSS UART WDT Description Cyclic Redundancy Check Download Agent File System Firmware Global Navigation Satellite System Universal Asynchronous Receiver/Transmitter Watchdog Timer L89_R2.0&LC29H&LC79H_Firmware_Upgrade_Guide 27 / 27
325.00 KB
BG770A-GL&BG95xA-GL MQTT Application Note LPWA Module Series Version: 1.0 Date: 2022-01-21 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG770A-GL&BG95xA-GL_MQTT_Application_Note 1 / 31 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG770A-GL&BG95xA-GL_MQTT_Application_Note 2 / 31 LPWA Module Series About the Document Revision History Version Date Author Description - 2021-05-18 Vladan RAKIC Creation of the document 1.0 2022-01-21 Vladan RAKIC First official release BG770A-GL&BG95xA-GL_MQTT_Application_Note 3 / 31 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 2 MQTT Data Interaction........................................................................................................................ 7 3 MQTT AT Commands ......................................................................................................................... 8 3.1. AT Command Introduction ......................................................................................................... 8 3.1.1. Definitions........................................................................................................................ 8 3.1.2. AT Command Syntax ...................................................................................................... 8 3.2. Declaration of AT Command Examples ..................................................................................... 9 3.3. Description of MQTT AT Commands ......................................................................................... 9 3.3.1. AT+QMTCFG Configure Optional Parameters of MQTT ............................................. 9 3.3.2. AT+QMTOPEN Open a Network Connection for MQTT Client ................................. 14 3.3.3. AT+QMTCLOSE Close a Network Connection for MQTT Client ............................... 15 3.3.4. AT+QMTCONN Connect a Client to MQTT Server.................................................... 15 3.3.5. AT+QMTDISC Disconnect a Client from MQTT Server ............................................. 17 3.3.6. AT+QMTSUB Subscribe to Topics ............................................................................. 18 3.3.7. AT+QMTUNS Unsubscribe from Topics ..................................................................... 19 3.3.8. AT+QMTPUB Publish Messages (Data Mode) .......................................................... 20 3.3.9. AT+QMTPUBEX Publish Messages (Command Mode) ............................................ 22 3.3.10. AT+QMTRECV Read Messages from Buffer ............................................................. 23 4 MQTT URCs ....................................................................................................................................... 25 4.1. +QMTSTAT: URC to Indicate State Change in MQTT Link Layer ........................................ 25 4.2. +QMTRECV: URC to Inform the Host to Read MQTT Packet Data..................................... 26 5 Examples ........................................................................................................................................... 27 5.1. Example of MQTT Operation without SSL .............................................................................. 27 5.2. Example of MQTT Operation with SSL.................................................................................... 29 6 Appendix References ....................................................................................................................... 31 BG770A-GL&BG95xA-GL_MQTT_Application_Note 4 / 31 LPWA Module Series Table Index Table 1: Error Codes of +QMTSTAT: URC................................................................................................. 25 Table 2: Related Documents ...................................................................................................................... 31 Table 3: Terms and Abbreviations .............................................................................................................. 31 BG770A-GL&BG95xA-GL_MQTT_Application_Note 5 / 31 LPWA Module Series 1 Introduction Message Queuing Telemetry Transport (MQTT) is a broker-based publish/subscribe messaging protocol designed to be open, simple, lightweight, and easy to implement. It is designed for connections with remote locations where a 'small code footprint' is required, or the network bandwidth is limited. This document explains how to use the MQTT function of Quectel BG770A-GL, BG950A-GL and BG951A-GL modules through AT commands. BG770A-GL&BG95xA-GL_MQTT_Application_Note 6 / 31 LPWA Module Series 2 MQTT Data Interaction This chapter illustrates the data interaction mechanism of the MQTT function. MCU Modem Link layer MQTT Server AT+QMTCFG='will',, AT+QMTCFG='timeout',, AT+QMTOPEN=,, OK TCP-REQ +QMTOPEN: , AT+QMTCONN AT+QMTCONN=,, OK +QMTCONN: ,[,] TCP established CONN-REQ Start timer T1, T2 CONN ACK-IND Stop T1 or handle Excep1 AT+QMTSUB AT+QMTSUB=,,, , OK SUB-REQ () Start timer T1 +QMTSUB: ,,[,] SUB ACK-IND () Stop T1 or handle Excep2 AT+QMTUNS AT+QMTUNS=,,, UNS-REQ () OK Start timer T1 +QMTUNS: ,, UNS ACK-IND () Stop T1 or handle Excep2 AT+QMTPUB=,,=0,, OK PUB-REQ AT+QMTPUB (=1) AT+QMTPUB=,,=1,, OK PUB-REQ () Start timer T1 +QMTPUB: ,,[,] PUB ACK-IND () Stop T1 or handle Excep2 AT+QMTPUB (=2) AT+QMTPUB=,,=2,, OK +QMTPUB: ,,[,] PUB-REQ () Start timer T1 PUB REC-IND () Stop T1 or handle Excep2 PUB REL-REQ () Start timer T1 PUB COMP-IND () Stop T1 or handle Excep2 TCP SYN TCP SYN+ACK TCP ACK Send connect packet Receive connect ACK packet Send subscribe packet Receive subscribe ACK packet Send unsubscribe packet Receive unsubscribe ACK packet Send publish packet Send publish packet Receive publish ACK packet Send publish packet Receive publish receive packet Send publish release packet Receive publish complete packet T1 is packet transmission timeout. T2 is keep alive timer. In the absence of a data-related message during the T2 time period, the client will send PINGREQ packet. Excep1: Disconnect the TCP connection. Excep2: Resend packets unless maximum retry times is reached. Retry times is set with AT+QMTCFG. Whether the timeout information is reported can be configured with AT+QMTCFG. Receive PUBLISH Receive message in the form of URC. +QMTRECV: ,, [,], AT+QMTDISC= OK +QMTDISC: , AT+QMTCLOSE= OK +QMTCLOSE: , PUB-IND () PUB ACK/REC-REQ () Reply accor.d..ing to DISC-REQ Receive publish packet Send publish reply packet Send disconnect packet TCP-REQ TCP disconnected TCP discon.n..ect request Note: refers to optional parameters. For more details about optional parameters, please refer to the description of corresponding AT command in Chapter 3.3. Figure 1: MQTT Data Interaction Diagram BG770A-GL&BG95xA-GL_MQTT_Application_Note 7 / 31 LPWA Module Series 3 MQTT AT Commands The AT commands for using the MQTT function are presented in this chapter. 3.1. AT Command Introduction 3.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 3.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 1: Types of AT Commands Command Type Test Command Read Command Write Command Syntax Description AT+=? AT+? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. AT+=[,[,[...]]] Set user-definable parameter value. BG770A-GL&BG95xA-GL_MQTT_Application_Note 8 / 31 Execution Command AT+ LPWA Module Series Return a specific information parameter or perform a specific action. 3.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 3.3. Description of MQTT AT Commands 3.3.1. AT+QMTCFG Configure Optional Parameters of MQTT This command configures optional parameters of MQTT. AT+QMTCFG Configure Optional Parameters of MQTT Test Command AT+QMTCFG=? Response +QMTCFG: 'version',(range of supported s),(list of supported s) +QMTCFG: 'pdpcid',(range of supported s),(range of supported s) +QMTCFG: 'ssl',(range of supported s),( list of supported s),(range of supported s) +QMTCFG: 'keepalive',(range of supported s),(range of supported s) +QMTCFG: 'session',(range of supported s),(list of supported s) +QMTCFG: 'timeout',(range of supported s),(range of supported s),(range of supported s),(list of supported s) +QMTCFG: 'will',(range of supported s),(list of supported s),(range of supported s),(list of supported s),, +QMTCFG: 'recv/mode',(range of supported s),(list of supported s),(list of supported s) +QMTCFG: 'aliauth',(range of supported s),,, BG770A-GL&BG95xA-GL_MQTT_Application_Note 9 / 31 LPWA Module Series Write Command Query/set the MQTT protocol version AT+QMTCFG='version',[,] OK Response If the optional parameter is omitted, query the MQTT protocol version: +QMTCFG: 'version', OK If the optional parameter is specified, set the MQTT protocol version: OK Write Command Query/set the PDP to be used by the MQTT client AT+QMTCFG='pdpcid',[,] If there is any error: ERROR Response If the optional parameter is omitted, query the PDP used by the MQTT client: +QMTCFG: 'pdpcid', OK If the optional parameter is specified, set the PDP to be used by the MQTT client: OK Write Command Query/set the MQTT SSL mode and SSL context index AT+QMTCFG='ssl',[,[,]] If there is any error: ERROR Response If the optional parameters are omitted, query the MQTT SSL mode and SSL context index: +QMTCFG: 'ssl',[,] OK If any of the optional parameters is specified, set the MQTT SSL mode and SSL context index: OK Write Command Query/set the keep-alive time AT+QMTCFG='keepalive',< client_idx>[,] If there is any error: ERROR Response If the optional parameter is omitted, query the keep-alive time: +QMTCFG: 'keepalive', OK BG770A-GL&BG95xA-GL_MQTT_Application_Note 10 / 31 LPWA Module Series If the optional parameter is specified, set the keep-alive time: OK Write Command Query/set the session type AT+QMTCFG='session',[, ] If there is any error: ERROR Response If the optional parameter is omitted, query the session type: +QMTCFG: 'session', OK If the optional parameter is specified, set the session type: OK Write Command Query/set the message delivery timeout AT+QMTCFG='timeout',[,[,< retry_times>][,]] If there is any error: ERROR Response If the optional parameters are omitted, query the message delivery timeout: +QMTCFG: 'timeout',,, OK If any of the optional parameters is specified, set the message delivery timeout: OK Write Command Query/set the Will information AT+QMTCFG='will',[,[,,, ,]] If there is any error: ERROR Response If the optional parameters are omitted, query the Will information: +QMTCFG: 'will',[,,,, ] OK If any of the optional parameters is specified, set the Will information: OK Write Command Query/set the MQTT If there is any error: ERROR Response If the optional parameters are omitted, query the MQTT message BG770A-GL&BG95xA-GL_MQTT_Application_Note 11 / 31 LPWA Module Series message receiving mode when the data are received from server AT+QMTCFG='recv/mode', [,[,]] receiving mode. +QMTCFG: 'recv/mode',[,] OK If any of the optional parameters is specified, set the MQTT message receiving mode: OK Write Command Query/set Alibaba device information for AliCloud AT+QMTCFG='aliauth',[,,< device_name>,] If there is any error: ERROR Response If the optional parameters are omitted, query the device information: [+QMTCFG: 'aliauth',,,] OK If the optional parameters are specified, set the device information: OK Maximum Response Time Characteristics If there is any error: ERROR Determined by the network. The command takes effect immediately. The configurations will not be saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. MQTT protocol version. 3 MQTT v3.1 4 MQTT v3.1.1 Integer type. PDP to be used by the MQTT client. Range: 1–5. Default value: 1 Integer type. Whether to configure the Will flag. 0 Ignore the Will flag configuration 1 Require the Will flag configuration Integer type. QoS level of message delivery. 0 At most once 1 At least once 2 Exactly once Integer type. Will Retain flag is only used for PUBLISH messages. BG770A-GL&BG95xA-GL_MQTT_Application_Note 12 / 31 LPWA Module Series 0 When a client sends a PUBLISH message to a server, the server will not retain the message after it has been delivered to the current subscribers. 1 When a client sends a PUBLISH message to a server, the server should retain the message after it has been delivered to the current subscribers. String type. Will topic. Maximum length: 255 bytes. String type. The Will message defines the content of the message published on the Will topic if the client is unexpectedly disconnected. It can be a zero-length message. Maximum length: 255 bytes. Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. Integer type. Whether to report timeout message when transmitting a packet. 0 Do not report 1 Report Integer type. Configures the session type. 0 The server must store the subscriptions of the client after it disconnects. 1 The server must discard any previously maintained information about the client after it disconnects and treat the connection as 'clean'. Integer type. Keep-alive time. Range: 0–3600. Default value: 120. Unit: second. It defines the maximum interval between messages received from a client. If the server does not receive a message from the client within 1.5 times of the keep-alive time value, it disconnects the client as if the client sent a DISCONNECT message. If the keep-alive time is 0, this means that the server is not required to disconnect the client on the grounds of inactivity. Integer type. MQTT SSL mode. 0 Use normal TCP connection for MQTT 1 Use SSL TCP secure connection for MQTT Integer type. SSL context index. Range: 0–5. Integer type. MQTT message receiving mode. 0 MQTT message received from server will be contained in URC 1 MQTT message received from server will not be contained in URC Integer type. 0 Length of MQTT message received from server will not be contained in URC 1 Length of MQTT message received from server will be contained in URC Product key issued by AliCloud. Device name issued by AliCloud. Device secret key issued by AliCloud. NOTE 1. If =1, then , , and must be specified. Otherwise, they are omitted. 2. =0 is only effective when the server supports the operation. BG770A-GL&BG95xA-GL_MQTT_Application_Note 13 / 31 LPWA Module Series 3. If MQTT connection is configured to SSL mode, must be specified, and AT+QSSLCFG must be used to configure the SSL version, cipher suite, secure level, CA certificate, client certificate, client key and ignorance of RTC time, which will be used in MQTT SSL handshake procedure. For more information on AT+QSSLCFG, see document [3]. 4. Care must be taken to ensure that message delivery does not time out while the sending process is in progress. 5. AT+QMTCFG='aliauth' is only used for AliCloud. If it is configured, and can be omitted in AT+QMTCONN. Once set, a specified session can only be used for AliCloud until reboot. 3.3.2. AT+QMTOPEN Open a Network Connection for MQTT Client This command opens a network connection for an MQTT client. AT+QMTOPEN Open a Network Connection for MQTT Client Test Command AT+QMTOPEN=? Response +QMTOPEN: (range of supported s),,(range of supported s) Read Command AT+QMTOPEN? OK Response [+QMTOPEN: ,,] Write Command AT+QMTOPEN=,, OK Response OK +QMTOPEN: , Maximum Response Time Characteristics If there is any error: ERROR Determined by the network / Parameter Integer type. MQTT client identifier. Range: 0–5. String type. Server address. It could be an IP address or a domain name. Maximum size: 128 bytes. Integer type. Server port number. Range: 0–65535. Integer type. Command execution result. -1 Failed to open a network BG770A-GL&BG95xA-GL_MQTT_Application_Note 14 / 31 0 Network opened successfully 1 Wrong parameter 2 MQTT client identifier is occupied 3 Failed to activate PDP 4 Failed to parse domain name 5 Network connection error LPWA Module Series 3.3.3. AT+QMTCLOSE Close a Network Connection for MQTT Client This command closes a network connection for an MQTT client. AT+QMTCLOSE Close a Network Connection for MQTT Client Test Command AT+QMTCLOSE=? Response +QMTCLOSE: (range of supported s) Write Command AT+QMTCLOSE= OK Response OK +QMTCLOSE: , Maximum Response Time Characteristics If there is any error: ERROR Determined by network / Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Command execution result. -1 Failed to close the network 0 Network closed successfully 3.3.4. AT+QMTCONN Connect a Client to MQTT Server This command is used when a client requests a connection to the MQTT server. When a TCP/IP socket connection is established between a client and a server, a protocol level session must be created using a CONNECT flow. BG770A-GL&BG95xA-GL_MQTT_Application_Note 15 / 31 LPWA Module Series AT+QMTCONN Connect a Client to MQTT Server Test Command AT+QMTCONN=? Response +QMTCONN: (range of supported s),,, Read Command AT+QMTCONN? OK Response [+QMTCONN: ,] Write Command AT+QMTCONN=,[,[,]] OK Response OK +QMTCONN: ,[,] Maximum Response Time Characteristics If there is any error: ERROR (default 5 s), determined by the network / Parameter Integer type. MQTT client identifier. Range: 0–5. Client identifier string. String type. Client username. It can be used for authentication. String type. The password corresponding to the client username. It can be used for authentication. Integer type. Command execution result. 0 Packet sent successfully and ACK received from the server 1 Packet retransmission 2 Failed to send the packet Integer type. MQTT connection state. 1 MQTT is initializing 2 MQTT is connecting 3 MQTT is connected 4 MQTT is disconnecting Integer type. Connection status return code. 0 Connection Accepted 1 Connection Refused: Unacceptable Protocol Version 2 Connection Refused: Identifier Rejected 3 Connection Refused: Server Unavailable BG770A-GL&BG95xA-GL_MQTT_Application_Note 16 / 31 LPWA Module Series 4 Connection Refused: Bad Username or Password 5 Connection Refused: Not Authorized Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: second. NOTE 1. If a client with the same Client ID is already connected to the server, the 'older' client must be disconnected by the server before completing the CONNECT flow of the new client. 2. AT+QMTCFG='aliauth' is only used for AliCloud. If it is configured, then and in AT+QMTCONN can be omitted. 3.3.5. AT+QMTDISC Disconnect a Client from MQTT Server This command requests a disconnection from MQTT server by a client. A DISCONNECT message is sent from the client to the server to indicate that it is about to close its TCP/IP connection. AT+QMTDISC Disconnect a Client from MQTT Server Test Command AT+QMTDISC=? Response +QMTDISC: (range of supported s) Write Command AT+QMTDISC= OK Response OK +QMTDISC: , Maximum Response Time Characteristics If there is any error: ERROR Determined by the network / Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Command execution result. -1 Failed to close the connection 0 Connection closed successfully BG770A-GL&BG95xA-GL_MQTT_Application_Note 17 / 31 LPWA Module Series NOTE Disconnecting a client closes the socket. 3.3.6. AT+QMTSUB Subscribe to Topics This command subscribes to one or more topics. A SUBSCRIBE message is sent to the server by a client to register interest in one or more topic names. Messages published on these topics are delivered from the server to the client as PUBLISH messages. AT+QMTSUB Subscribe to Topics Test Command AT+QMTSUB=? Response +QMTSUB: (range of supported s),(range of supported s),,(range of supported s) Write Command AT+QMTSUB=,,,[,,…] OK Response OK +QMTSUB: ,,[,] Maximum Response Time Characteristics If there is any error: ERROR × (default 15 s), determined by network The command takes effect immediately. The configurations will not be saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of a packet. Range: 1–65535. String type. Topic that the client wants to subscribe to or unsubscribe from. Integer type. QoS level at which the client wants to publish messages. 0 At most once 1 At least once 2 Exactly once Integer type. Command execution result. 0 Packet sent successfully and ACK received from the server 1 Packet retransmission 2 Failed to send a packet If is 0, it is a vector of granted QoS levels. BG770A-GL&BG95xA-GL_MQTT_Application_Note 18 / 31 LPWA Module Series If is 1, it is the number of times the packet has been retransmitted. If is 2, it will not be presented. Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. NOTE The is only present in messages where the QoS bits in the fixed header indicate QoS levels 1 or 2. It must be unique among the set of 'inflight' messages in a particular communication direction. It typically increases by 1 from one message to the next. 3.3.7. AT+QMTUNS Unsubscribe from Topics This command unsubscribes from one or more topics. An UNSUBSCRIBE message is sent by the client to the server to unsubscribe from the named topics. AT+QMTUNS Unsubscribe from Topics Test Command AT+QMTUNS=? Response +QMTUNS: (range of supported s),(range of supported s), Write Command AT+QMTUNS=,,[,…] OK Response OK +QMTUNS: ,, Maximum Response Time Characteristics If there is any error: ERROR × (default 15 s), determined by network The command takes effect immediately. The configurations will not be saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of a packet. Range: 1–65535. String type. Topic that the client wants to subscribe to or unsubscribe from. Integer type. Command execution result. 0 Packet sent successfully and ACK received from the server BG770A-GL&BG95xA-GL_MQTT_Application_Note 19 / 31 LPWA Module Series 1 Packet retransmission 2 Failed to send a packet Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. 3.3.8. AT+QMTPUB Publish Messages (Data Mode) This command publishes messages by a client to a server for distribution to interested subscribers. Each PUBLISH message is associated with a topic name. If a client subscribes to one or more topics, any message published on those topics is sent by the server to the client as a PUBLISH message. AT+QMTPUB Publish Messages (Data Mode) Test Command AT+QMTPUB=? Response +QMTPUB: (range of supported s),(range of supported s),(range of supported s),(list of supported s),,(range of supported s) Write Command Publish variable-length messages AT+QMTPUB=,, ,, OK Response > After > is reported, input the data to be sent. Press Ctrl+Z to send the data, or Esc to cancel the operation. OK +QMTPUB: ,,[,] Write Command Publish fixed-length messages AT+QMTPUB=,, ,,, If there is any error: ERROR Response > After > is responded, input the data to be sent. The number of bytes of input data must equal . OK +QMTPUB: ,,[,] Maximum Response Time If there is any error: ERROR × (default 15 s), determined by the network BG770A-GL&BG95xA-GL_MQTT_Application_Note 20 / 31 LPWA Module Series Characteristics / Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of a packet. Range: 0–65535. It will be 0 only when =0. Integer type. QoS level at which the client wants to publish messages. 0 At most once 1 At least once 2 Exactly once Integer type. Determines whether the server will retain the message after it has been delivered to the current subscribers. 0 The server will not retain the message after it has been delivered to the current subscribers 1 The server will retain the message after it has been delivered to the current subscribers String type. Topic that needs to be published. Integer type. Length of the message to be published. Range: 1–4096. Unit: byte. Integer type. Command execution result. 0 Packet sent successfully and ACK received from the server (message that is published when =0 does not require ACK) 1 Packet retransmission 2 Failed to send a packet If is 1, it means the number of times a packet has been retransmitted. If is 0 or 2, it will not be presented. Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. NOTE 1. If this command is executed successfully and OK is reported, the client can continue to publish new packets. The maximum quantity of the packet to be transmitted should not be greater than that of inflight windows (5). 2. After executing this command, the client will be ready to send data as a payload. The maximum length of data input at a time is 4096 bytes. To send the data, remember to press Ctrl+Z. 3. PUBLISH messages can be sent either from a publisher to the server, or from the server to a subscriber. When a server publishes messages to a subscriber, the following URC will be returned to notify the host to read the received data reported by the MQTT server: +QMTRECV: ,,[,], For more information on the URC description, see Chapter 4.2. BG770A-GL&BG95xA-GL_MQTT_Application_Note 21 / 31 LPWA Module Series 3.3.9. AT+QMTPUBEX Publish Messages (Command Mode) This command publishes messages. It provides the same functions as AT+QMTPUB, except that the format is different. AT+QMTPUBEX Publish Messages (Command Mode) Test Command AT+QMTPUBEX=? Response +QMTPUBEX: (range of supported s),( range of supported s),(range of supported s),(list of supported s),, Write Command AT+QMTPUBEX=,,,,, Maximum Response Time Characteristics OK Response OK +QMTPUB: ,,[,] If there is any error: ERROR × (default 15 s), determined by the network / Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of a packet. Range: 0–65535. It will be 0 only when =0. Integer type. QoS level at which the client wants to publish messages. 0 At most once 1 At least once 2 Exactly once Integer type. Determines whether the server will retain the message after it has been delivered to the current subscribers. 0 The server will not retain the message after it has been delivered to the current subscribers 1 The server will retain the message after it has been delivered to the current subscribers String type. Topic that needs to be published. String type. Message to be published. Maximum length: 560 bytes. Integer type. Command execution result. 0 Packet sent successfully and ACK received from the server (message that is published when =0 does not require ACK) 1 Packet retransmission BG770A-GL&BG95xA-GL_MQTT_Application_Note 22 / 31 LPWA Module Series 2 Failed to send a packet If is 1, it means the number of times a packet has been retransmitted. If is 0 or 2, it will not be presented. Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. NOTE The response flow of AT+QMTPUBEX will be the same as the response flow of AT+QMTPUB. 3.3.10. AT+QMTRECV Read Messages from Buffer This command reads messages from the storage buffer where the messages are stored after being reported by the server. AT+QMTRECV Read Messages from Buffer Test Command AT+QMTRECV=? Read Command AT+QMTRECV? Response OK Response +QMTRECV: ,,,,, OK Write Command AT+QMTRECV=[,] If there is no MQTT connection: OK Response List of (+QMTRECV: ,,,[,])s OK If no message has been received: OK Maximum Response Time If there is no MQTT connection: ERROR Determined by the network. BG770A-GL&BG95xA-GL_MQTT_Application_Note 23 / 31 LPWA Module Series Characteristics / Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Indicates if a message is stored in the buffer. As there can be maximum 5 messages in a buffer, the URC can report at most 5 messages simultaneously. 0 No stored messages 1 There are stored messages (up to 5) Integer type. Serial number of a received message. Range: 0–4. All buffer data will be read if this parameter is not specified. Integer type. Message identifier of the packet. Range: 0–65535. It will be 0 only when =0. String type. Topic that needs to be published. Integer type. Payload length. Unit: Byte. String type. Payload relating to topic name. BG770A-GL&BG95xA-GL_MQTT_Application_Note 24 / 31 LPWA Module Series 4 MQTT URCs This chapter describes the MQTT URCs. 4.1. +QMTSTAT: URC to Indicate State Change in MQTT Link Layer The URC that begins with +QMTSTAT will be reported when the state of an MQTT link layer is changed. +QMTSTAT: URC to Indicate State Change in MQTT Link Layer When the state of an MQTT link layer is changed, the client +QMTSTAT: , will close the MQTT connection and report the URC. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Error code. Refer to the table below for more information. Table 1: Error Codes of +QMTSTAT: URC 1 2 3 4 Description Solution Connection is closed or reset by a peer. Sending PINGREQ packet timed out or failed. Sending CONNECT packet timed out or failed. Receiving CONNACK packet timed out or failed. Execute AT+QMTOPEN command to reopen the MQTT connection. First, deactivate and activate the PDP. Then, reopen the MQTT connection. 1. Check whether the inputted username and password are correct. 2. Make sure the client ID is not used. 3. Reopen the MQTT connection and try to send CONNECT packet to the server again. 1. Check whether the inputted username and password are correct. 2. Make sure the client ID is not used. 3. Reopen the MQTT connection and try to send CONNECT packet to the server again. BG770A-GL&BG95xA-GL_MQTT_Application_Note 25 / 31 5 6 7 8–255 LPWA Module Series The client sends DISCONNECT packet to the sever and the server starts closing the MQTT connection. The client takes the initiative to close the MQTT connection due to constant packet sending failure. The link is not alive, or the server is unavailable. This is a normal process. 1. Make sure that the data are correct. 2. Try to reopen the MQTT connection since there may be a network congestion or an error. Make sure that the link is alive, or the server is currently available. Reserved for future uses. NOTE Error codes 5, 6 and 7 are currently not supported. 4.2. +QMTRECV: URC to Inform the Host to Read MQTT Packet Data The URC that begins with +QMTRECV: is mainly used to inform the host to read the received MQTT packet reported from the MQTT server. +QMTRECV: URC to Inform the Host to Read MQTT Packet Data +QMTRECV: ,,< topic>[,], +QMTRECV: ,[,] Notify the host to read the received data reported from the MQTT server. Notify that the message received from the MQTT server has been stored in a buffer. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of the packet. String type. Topic that has been received from the MQTT server. Integer type. Payload length. Unit: byte. String type. Payload relating to topic name. Integer type. Serial number of a received message. Range: 0–4. BG770A-GL&BG95xA-GL_MQTT_Application_Note 26 / 31 LPWA Module Series 5 Examples This chapter provides some examples that explain how to use the MQTT AT commands. 5.1. Example of MQTT Operation without SSL AT+QMTCFG='aliauth',0,'oyjtmPl5a5j','MQTT_TEST','wN9Y6pZSIIy7Exa5qVzcmigEGO4kAazZ' //Configure Alibaba device information for AliCloud. OK AT+QMTOPEN=? +QMTOPEN: (0-5),,(0-65535) OK AT+QMTOPEN=0,'iot-as-mqtt.cn-shanghai.aliyuncs.com',1883 //Open a network for MQTT client. OK +QMTOPEN: 0,0 //The MQTT client network opened successfully. AT+QMTOPEN? +QMTOPEN: 0,'iot-as-mqtt.cn-shanghai.aliyuncs.com',1883 OK AT+QMTCONN=? +QMTCONN: (0-5),,, OK //Connect a client to the MQTT server. //If AliCloud is connected, AT+QMTCFG='aliauth' can be used to configure the device information in advance. There is no need to provide the username/password from now on. AT+QMTCONN=0,'clientExample' OK +QMTCONN: 0,0,0 //The client has successfully connected to the MQTT server. AT+QMTSUB=? +QMTSUB: (0-5),(1-65535),,(0-2) BG770A-GL&BG95xA-GL_MQTT_Application_Note 27 / 31 LPWA Module Series OK //Subscribe to topics. AT+QMTSUB=0,1,'topic/example',2 OK +QMTSUB: 0,1,0,2 AT+QMTSUB=0,1,'topic/pub',0 OK +QMTSUB: 0,1,0,0 //If a client subscribed to a topic and other devices publish the same topic to the server, the module will report the following information. +QMTRECV: 0,0,'topic/example','This is the payload related to topic' //Unsubscribe from topics. AT+QMTUNS=0,1,'topic/example' OK +QMTUNS: 0,2,0 AT+QMTPUB=? +QMTPUB : (0-5),(0-65535),(0-2),(0,1),,(1-4096) OK //Publish messages. AT+QMTPUB=0,0,0,0,'topic/pub' >These are test data, hello MQTT. OK //After receiving >, input data These are test data, hello MQTT. and then send it. The maximum length of the data to be sent is 4096 bytes. All the data beyond 4096 bytes will be omitted. After inputting data, press Ctrl+Z to send them. +QMTPUB: 0,0,0 //If a client subscribed to a topic named 'topic/pub' and other devices publish the same topic to the server, the module will report the following information. +QMTRECV: 0,0,'topic/pub','These are test data, hello MQTT.' AT+QMTDISC=0 //Disconnect a client from the MQTT server. OK +QMTDISC: 0,0 //The connection closed successfully. BG770A-GL&BG95xA-GL_MQTT_Application_Note 28 / 31 LPWA Module Series 5.2. Example of MQTT Operation with SSL //Configure the MQTT session into SSL mode. AT+QMTCFG='ssl',0,1,2 OK //If SSL authentication mode is intended to be set as 'manage server and client authentication if requested by the remote server' (=2 in AT+QSSLCFG), upload a server root CA certificate, a client certificate, and a client private key to UFS. AT+QFUPL='cacert.pem',1758,100 //Upload a CA certificate to UFS. CONNECT +QFUPL: 1758,384a OK AT+QFUPL='client.pem',1220,100 //Upload a client certificate to UFS. CONNECT +QFUPL: 1220,2d53 OK AT+QFUPL='user_key.pem',1679,100 //Upload a client private key to UFS. CONNECT +QFUPL: 1679,335f OK //Configure the path of the CA certificate for SSL context 2. AT+QSSLCFG='cacert',2,'cacert.pem' OK //Configure the path of the client certificate for SSL context 2. AT+QSSLCFG='clientcert',2,'client.pem' OK //Configure the path of the client private key for SSL context 2. AT+QSSLCFG='clientkey',2,'user_key.pem' OK //Configure the authentication mode for SSL context 2. AT+QSSLCFG='seclevel',2,2 //SSL authentication mode: server and client authentication if requested by the remote server. BG770A-GL&BG95xA-GL_MQTT_Application_Note 29 / 31 LPWA Module Series OK AT+QSSLCFG='sslversion',2,4 OK AT+QSSLCFG='ciphersuite',2,0XFFFF OK AT+QSSLCFG='ignorelocaltime',2,1 OK //SSL authentication version //Cipher suite //Ignore the authentication time. //Start the MQTT SSL connection. AT+QMTOPEN=0,'a1zgnxur10j8ux.iot.us-east-1.amazonaws.com',8883 OK +QMTOPEN: 0,0 //Connect to the MQTT server. AT+QMTCONN=0,'MQTT-1' OK +QMTCONN: 0,0,0 //Subscribe to topics. AT+QMTSUB=0,1,'$aws/things/ MQTT-1/shadow/update/accepted',1 OK +QMTSUB: 0,1,0,1 //Publish messages. AT+QMTPUB=0,1,1,0,'$aws/things/MQTT-1/shadow/update/accepted' >These are published data from client OK +QMTPUB: 0,1,0 //If a client subscribed to a topic named '$aws/things/MQTT-1/shadow/update/accepted' and other devices publish the same topic to the server, the module will report the following information. +QMTRECV: 0,1,'$aws/things/MQTT-1/shadow/update/accepted','These are published data from client' //Disconnect a client from the MQTT server. AT+QMTDISC=0 OK +QMTDISC: 0,0 BG770A-GL&BG95xA-GL_MQTT_Application_Note 30 / 31 LPWA Module Series 6 Appendix References Table 2: Related Documents Document Name [1] MQTT V3.1 Protocol Specification [2] MQTT V3.1.1 Protocol Specification [3] Quectel_BG770A-GL&BG95×A-GL_SSL_Application_Note Table 3: Terms and Abbreviations Abbreviation ACK CA IP MQTT PDP QoS SSL TCP UFS URC Description Acknowledgement Certificate Authority Internet Protocol Message Queuing Telemetry Transport Packet Data Protocol Quality of Service Secure Sockets Layer Transmission Control Protocol User File System Unsolicited Result Code BG770A-GL&BG95xA-GL_MQTT_Application_Note 31 / 31
388.62 KB
BG770A-GL&BG95xA-GL MQTT Application Note LPWA Module Series Version: 1.0 Date: 2022-01-21 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG770A-GL&BG95xA-GL_MQTT_Application_Note 1 / 31 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG770A-GL&BG95xA-GL_MQTT_Application_Note 2 / 31 LPWA Module Series About the Document Revision History Version Date Author Description - 2021-05-18 Vladan RAKIC Creation of the document 1.0 2022-01-21 Vladan RAKIC First official release BG770A-GL&BG95xA-GL_MQTT_Application_Note 3 / 31 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 2 MQTT Data Interaction........................................................................................................................ 7 3 MQTT AT Commands ......................................................................................................................... 8 3.1. AT Command Introduction ......................................................................................................... 8 3.1.1. Definitions........................................................................................................................ 8 3.1.2. AT Command Syntax ...................................................................................................... 8 3.2. Declaration of AT Command Examples ..................................................................................... 9 3.3. Description of MQTT AT Commands ......................................................................................... 9 3.3.1. AT+QMTCFG Configure Optional Parameters of MQTT ............................................. 9 3.3.2. AT+QMTOPEN Open a Network Connection for MQTT Client ................................. 14 3.3.3. AT+QMTCLOSE Close a Network Connection for MQTT Client ............................... 15 3.3.4. AT+QMTCONN Connect a Client to MQTT Server.................................................... 15 3.3.5. AT+QMTDISC Disconnect a Client from MQTT Server ............................................. 17 3.3.6. AT+QMTSUB Subscribe to Topics ............................................................................. 18 3.3.7. AT+QMTUNS Unsubscribe from Topics ..................................................................... 19 3.3.8. AT+QMTPUB Publish Messages (Data Mode) .......................................................... 20 3.3.9. AT+QMTPUBEX Publish Messages (Command Mode) ............................................ 22 3.3.10. AT+QMTRECV Read Messages from Buffer ............................................................. 23 4 MQTT URCs ....................................................................................................................................... 25 4.1. +QMTSTAT: URC to Indicate State Change in MQTT Link Layer ........................................ 25 4.2. +QMTRECV: URC to Inform the Host to Read MQTT Packet Data..................................... 26 5 Examples ........................................................................................................................................... 27 5.1. Example of MQTT Operation without SSL .............................................................................. 27 5.2. Example of MQTT Operation with SSL.................................................................................... 29 6 Appendix References ....................................................................................................................... 31 BG770A-GL&BG95xA-GL_MQTT_Application_Note 4 / 31 LPWA Module Series Table Index Table 1: Error Codes of +QMTSTAT: URC................................................................................................. 25 Table 2: Related Documents ...................................................................................................................... 31 Table 3: Terms and Abbreviations .............................................................................................................. 31 BG770A-GL&BG95xA-GL_MQTT_Application_Note 5 / 31 LPWA Module Series 1 Introduction Message Queuing Telemetry Transport (MQTT) is a broker-based publish/subscribe messaging protocol designed to be open, simple, lightweight, and easy to implement. It is designed for connections with remote locations where a 'small code footprint' is required, or the network bandwidth is limited. This document explains how to use the MQTT function of Quectel BG770A-GL, BG950A-GL and BG951A-GL modules through AT commands. BG770A-GL&BG95xA-GL_MQTT_Application_Note 6 / 31 LPWA Module Series 2 MQTT Data Interaction This chapter illustrates the data interaction mechanism of the MQTT function. MCU Modem Link layer MQTT Server AT+QMTCFG='will',, AT+QMTCFG='timeout',, AT+QMTOPEN=,, OK TCP-REQ +QMTOPEN: , AT+QMTCONN AT+QMTCONN=,, OK +QMTCONN: ,[,] TCP established CONN-REQ Start timer T1, T2 CONN ACK-IND Stop T1 or handle Excep1 AT+QMTSUB AT+QMTSUB=,,, , OK SUB-REQ () Start timer T1 +QMTSUB: ,,[,] SUB ACK-IND () Stop T1 or handle Excep2 AT+QMTUNS AT+QMTUNS=,,, UNS-REQ () OK Start timer T1 +QMTUNS: ,, UNS ACK-IND () Stop T1 or handle Excep2 AT+QMTPUB=,,=0,, OK PUB-REQ AT+QMTPUB (=1) AT+QMTPUB=,,=1,, OK PUB-REQ () Start timer T1 +QMTPUB: ,,[,] PUB ACK-IND () Stop T1 or handle Excep2 AT+QMTPUB (=2) AT+QMTPUB=,,=2,, OK +QMTPUB: ,,[,] PUB-REQ () Start timer T1 PUB REC-IND () Stop T1 or handle Excep2 PUB REL-REQ () Start timer T1 PUB COMP-IND () Stop T1 or handle Excep2 TCP SYN TCP SYN+ACK TCP ACK Send connect packet Receive connect ACK packet Send subscribe packet Receive subscribe ACK packet Send unsubscribe packet Receive unsubscribe ACK packet Send publish packet Send publish packet Receive publish ACK packet Send publish packet Receive publish receive packet Send publish release packet Receive publish complete packet T1 is packet transmission timeout. T2 is keep alive timer. In the absence of a data-related message during the T2 time period, the client will send PINGREQ packet. Excep1: Disconnect the TCP connection. Excep2: Resend packets unless maximum retry times is reached. Retry times is set with AT+QMTCFG. Whether the timeout information is reported can be configured with AT+QMTCFG. Receive PUBLISH Receive message in the form of URC. +QMTRECV: ,, [,], AT+QMTDISC= OK +QMTDISC: , AT+QMTCLOSE= OK +QMTCLOSE: , PUB-IND () PUB ACK/REC-REQ () Reply accor.d..ing to DISC-REQ Receive publish packet Send publish reply packet Send disconnect packet TCP-REQ TCP disconnected TCP discon.n..ect request Note: refers to optional parameters. For more details about optional parameters, please refer to the description of corresponding AT command in Chapter 3.3. Figure 1: MQTT Data Interaction Diagram BG770A-GL&BG95xA-GL_MQTT_Application_Note 7 / 31 LPWA Module Series 3 MQTT AT Commands The AT commands for using the MQTT function are presented in this chapter. 3.1. AT Command Introduction 3.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 3.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 1: Types of AT Commands Command Type Test Command Read Command Write Command Syntax Description AT+=? AT+? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. AT+=[,[,[...]]] Set user-definable parameter value. BG770A-GL&BG95xA-GL_MQTT_Application_Note 8 / 31 Execution Command AT+ LPWA Module Series Return a specific information parameter or perform a specific action. 3.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 3.3. Description of MQTT AT Commands 3.3.1. AT+QMTCFG Configure Optional Parameters of MQTT This command configures optional parameters of MQTT. AT+QMTCFG Configure Optional Parameters of MQTT Test Command AT+QMTCFG=? Response +QMTCFG: 'version',(range of supported s),(list of supported s) +QMTCFG: 'pdpcid',(range of supported s),(range of supported s) +QMTCFG: 'ssl',(range of supported s),( list of supported s),(range of supported s) +QMTCFG: 'keepalive',(range of supported s),(range of supported s) +QMTCFG: 'session',(range of supported s),(list of supported s) +QMTCFG: 'timeout',(range of supported s),(range of supported s),(range of supported s),(list of supported s) +QMTCFG: 'will',(range of supported s),(list of supported s),(range of supported s),(list of supported s),, +QMTCFG: 'recv/mode',(range of supported s),(list of supported s),(list of supported s) +QMTCFG: 'aliauth',(range of supported s),,, BG770A-GL&BG95xA-GL_MQTT_Application_Note 9 / 31 LPWA Module Series Write Command Query/set the MQTT protocol version AT+QMTCFG='version',[,] OK Response If the optional parameter is omitted, query the MQTT protocol version: +QMTCFG: 'version', OK If the optional parameter is specified, set the MQTT protocol version: OK Write Command Query/set the PDP to be used by the MQTT client AT+QMTCFG='pdpcid',[,] If there is any error: ERROR Response If the optional parameter is omitted, query the PDP used by the MQTT client: +QMTCFG: 'pdpcid', OK If the optional parameter is specified, set the PDP to be used by the MQTT client: OK Write Command Query/set the MQTT SSL mode and SSL context index AT+QMTCFG='ssl',[,[,]] If there is any error: ERROR Response If the optional parameters are omitted, query the MQTT SSL mode and SSL context index: +QMTCFG: 'ssl',[,] OK If any of the optional parameters is specified, set the MQTT SSL mode and SSL context index: OK Write Command Query/set the keep-alive time AT+QMTCFG='keepalive',< client_idx>[,] If there is any error: ERROR Response If the optional parameter is omitted, query the keep-alive time: +QMTCFG: 'keepalive', OK BG770A-GL&BG95xA-GL_MQTT_Application_Note 10 / 31 LPWA Module Series If the optional parameter is specified, set the keep-alive time: OK Write Command Query/set the session type AT+QMTCFG='session',[, ] If there is any error: ERROR Response If the optional parameter is omitted, query the session type: +QMTCFG: 'session', OK If the optional parameter is specified, set the session type: OK Write Command Query/set the message delivery timeout AT+QMTCFG='timeout',[,[,< retry_times>][,]] If there is any error: ERROR Response If the optional parameters are omitted, query the message delivery timeout: +QMTCFG: 'timeout',,, OK If any of the optional parameters is specified, set the message delivery timeout: OK Write Command Query/set the Will information AT+QMTCFG='will',[,[,,, ,]] If there is any error: ERROR Response If the optional parameters are omitted, query the Will information: +QMTCFG: 'will',[,,,, ] OK If any of the optional parameters is specified, set the Will information: OK Write Command Query/set the MQTT If there is any error: ERROR Response If the optional parameters are omitted, query the MQTT message BG770A-GL&BG95xA-GL_MQTT_Application_Note 11 / 31 LPWA Module Series message receiving mode when the data are received from server AT+QMTCFG='recv/mode', [,[,]] receiving mode. +QMTCFG: 'recv/mode',[,] OK If any of the optional parameters is specified, set the MQTT message receiving mode: OK Write Command Query/set Alibaba device information for AliCloud AT+QMTCFG='aliauth',[,,< device_name>,] If there is any error: ERROR Response If the optional parameters are omitted, query the device information: [+QMTCFG: 'aliauth',,,] OK If the optional parameters are specified, set the device information: OK Maximum Response Time Characteristics If there is any error: ERROR Determined by the network. The command takes effect immediately. The configurations will not be saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. MQTT protocol version. 3 MQTT v3.1 4 MQTT v3.1.1 Integer type. PDP to be used by the MQTT client. Range: 1–5. Default value: 1 Integer type. Whether to configure the Will flag. 0 Ignore the Will flag configuration 1 Require the Will flag configuration Integer type. QoS level of message delivery. 0 At most once 1 At least once 2 Exactly once Integer type. Will Retain flag is only used for PUBLISH messages. BG770A-GL&BG95xA-GL_MQTT_Application_Note 12 / 31 LPWA Module Series 0 When a client sends a PUBLISH message to a server, the server will not retain the message after it has been delivered to the current subscribers. 1 When a client sends a PUBLISH message to a server, the server should retain the message after it has been delivered to the current subscribers. String type. Will topic. Maximum length: 255 bytes. String type. The Will message defines the content of the message published on the Will topic if the client is unexpectedly disconnected. It can be a zero-length message. Maximum length: 255 bytes. Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. Integer type. Whether to report timeout message when transmitting a packet. 0 Do not report 1 Report Integer type. Configures the session type. 0 The server must store the subscriptions of the client after it disconnects. 1 The server must discard any previously maintained information about the client after it disconnects and treat the connection as 'clean'. Integer type. Keep-alive time. Range: 0–3600. Default value: 120. Unit: second. It defines the maximum interval between messages received from a client. If the server does not receive a message from the client within 1.5 times of the keep-alive time value, it disconnects the client as if the client sent a DISCONNECT message. If the keep-alive time is 0, this means that the server is not required to disconnect the client on the grounds of inactivity. Integer type. MQTT SSL mode. 0 Use normal TCP connection for MQTT 1 Use SSL TCP secure connection for MQTT Integer type. SSL context index. Range: 0–5. Integer type. MQTT message receiving mode. 0 MQTT message received from server will be contained in URC 1 MQTT message received from server will not be contained in URC Integer type. 0 Length of MQTT message received from server will not be contained in URC 1 Length of MQTT message received from server will be contained in URC Product key issued by AliCloud. Device name issued by AliCloud. Device secret key issued by AliCloud. NOTE 1. If =1, then , , and must be specified. Otherwise, they are omitted. 2. =0 is only effective when the server supports the operation. BG770A-GL&BG95xA-GL_MQTT_Application_Note 13 / 31 LPWA Module Series 3. If MQTT connection is configured to SSL mode, must be specified, and AT+QSSLCFG must be used to configure the SSL version, cipher suite, secure level, CA certificate, client certificate, client key and ignorance of RTC time, which will be used in MQTT SSL handshake procedure. For more information on AT+QSSLCFG, see document [3]. 4. Care must be taken to ensure that message delivery does not time out while the sending process is in progress. 5. AT+QMTCFG='aliauth' is only used for AliCloud. If it is configured, and can be omitted in AT+QMTCONN. Once set, a specified session can only be used for AliCloud until reboot. 3.3.2. AT+QMTOPEN Open a Network Connection for MQTT Client This command opens a network connection for an MQTT client. AT+QMTOPEN Open a Network Connection for MQTT Client Test Command AT+QMTOPEN=? Response +QMTOPEN: (range of supported s),,(range of supported s) Read Command AT+QMTOPEN? OK Response [+QMTOPEN: ,,] Write Command AT+QMTOPEN=,, OK Response OK +QMTOPEN: , Maximum Response Time Characteristics If there is any error: ERROR Determined by the network / Parameter Integer type. MQTT client identifier. Range: 0–5. String type. Server address. It could be an IP address or a domain name. Maximum size: 128 bytes. Integer type. Server port number. Range: 0–65535. Integer type. Command execution result. -1 Failed to open a network BG770A-GL&BG95xA-GL_MQTT_Application_Note 14 / 31 0 Network opened successfully 1 Wrong parameter 2 MQTT client identifier is occupied 3 Failed to activate PDP 4 Failed to parse domain name 5 Network connection error LPWA Module Series 3.3.3. AT+QMTCLOSE Close a Network Connection for MQTT Client This command closes a network connection for an MQTT client. AT+QMTCLOSE Close a Network Connection for MQTT Client Test Command AT+QMTCLOSE=? Response +QMTCLOSE: (range of supported s) Write Command AT+QMTCLOSE= OK Response OK +QMTCLOSE: , Maximum Response Time Characteristics If there is any error: ERROR Determined by network / Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Command execution result. -1 Failed to close the network 0 Network closed successfully 3.3.4. AT+QMTCONN Connect a Client to MQTT Server This command is used when a client requests a connection to the MQTT server. When a TCP/IP socket connection is established between a client and a server, a protocol level session must be created using a CONNECT flow. BG770A-GL&BG95xA-GL_MQTT_Application_Note 15 / 31 LPWA Module Series AT+QMTCONN Connect a Client to MQTT Server Test Command AT+QMTCONN=? Response +QMTCONN: (range of supported s),,, Read Command AT+QMTCONN? OK Response [+QMTCONN: ,] Write Command AT+QMTCONN=,[,[,]] OK Response OK +QMTCONN: ,[,] Maximum Response Time Characteristics If there is any error: ERROR (default 5 s), determined by the network / Parameter Integer type. MQTT client identifier. Range: 0–5. Client identifier string. String type. Client username. It can be used for authentication. String type. The password corresponding to the client username. It can be used for authentication. Integer type. Command execution result. 0 Packet sent successfully and ACK received from the server 1 Packet retransmission 2 Failed to send the packet Integer type. MQTT connection state. 1 MQTT is initializing 2 MQTT is connecting 3 MQTT is connected 4 MQTT is disconnecting Integer type. Connection status return code. 0 Connection Accepted 1 Connection Refused: Unacceptable Protocol Version 2 Connection Refused: Identifier Rejected 3 Connection Refused: Server Unavailable BG770A-GL&BG95xA-GL_MQTT_Application_Note 16 / 31 LPWA Module Series 4 Connection Refused: Bad Username or Password 5 Connection Refused: Not Authorized Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: second. NOTE 1. If a client with the same Client ID is already connected to the server, the 'older' client must be disconnected by the server before completing the CONNECT flow of the new client. 2. AT+QMTCFG='aliauth' is only used for AliCloud. If it is configured, then and in AT+QMTCONN can be omitted. 3.3.5. AT+QMTDISC Disconnect a Client from MQTT Server This command requests a disconnection from MQTT server by a client. A DISCONNECT message is sent from the client to the server to indicate that it is about to close its TCP/IP connection. AT+QMTDISC Disconnect a Client from MQTT Server Test Command AT+QMTDISC=? Response +QMTDISC: (range of supported s) Write Command AT+QMTDISC= OK Response OK +QMTDISC: , Maximum Response Time Characteristics If there is any error: ERROR Determined by the network / Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Command execution result. -1 Failed to close the connection 0 Connection closed successfully BG770A-GL&BG95xA-GL_MQTT_Application_Note 17 / 31 LPWA Module Series NOTE Disconnecting a client closes the socket. 3.3.6. AT+QMTSUB Subscribe to Topics This command subscribes to one or more topics. A SUBSCRIBE message is sent to the server by a client to register interest in one or more topic names. Messages published on these topics are delivered from the server to the client as PUBLISH messages. AT+QMTSUB Subscribe to Topics Test Command AT+QMTSUB=? Response +QMTSUB: (range of supported s),(range of supported s),,(range of supported s) Write Command AT+QMTSUB=,,,[,,…] OK Response OK +QMTSUB: ,,[,] Maximum Response Time Characteristics If there is any error: ERROR × (default 15 s), determined by network The command takes effect immediately. The configurations will not be saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of a packet. Range: 1–65535. String type. Topic that the client wants to subscribe to or unsubscribe from. Integer type. QoS level at which the client wants to publish messages. 0 At most once 1 At least once 2 Exactly once Integer type. Command execution result. 0 Packet sent successfully and ACK received from the server 1 Packet retransmission 2 Failed to send a packet If is 0, it is a vector of granted QoS levels. BG770A-GL&BG95xA-GL_MQTT_Application_Note 18 / 31 LPWA Module Series If is 1, it is the number of times the packet has been retransmitted. If is 2, it will not be presented. Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. NOTE The is only present in messages where the QoS bits in the fixed header indicate QoS levels 1 or 2. It must be unique among the set of 'inflight' messages in a particular communication direction. It typically increases by 1 from one message to the next. 3.3.7. AT+QMTUNS Unsubscribe from Topics This command unsubscribes from one or more topics. An UNSUBSCRIBE message is sent by the client to the server to unsubscribe from the named topics. AT+QMTUNS Unsubscribe from Topics Test Command AT+QMTUNS=? Response +QMTUNS: (range of supported s),(range of supported s), Write Command AT+QMTUNS=,,[,…] OK Response OK +QMTUNS: ,, Maximum Response Time Characteristics If there is any error: ERROR × (default 15 s), determined by network The command takes effect immediately. The configurations will not be saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of a packet. Range: 1–65535. String type. Topic that the client wants to subscribe to or unsubscribe from. Integer type. Command execution result. 0 Packet sent successfully and ACK received from the server BG770A-GL&BG95xA-GL_MQTT_Application_Note 19 / 31 LPWA Module Series 1 Packet retransmission 2 Failed to send a packet Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. 3.3.8. AT+QMTPUB Publish Messages (Data Mode) This command publishes messages by a client to a server for distribution to interested subscribers. Each PUBLISH message is associated with a topic name. If a client subscribes to one or more topics, any message published on those topics is sent by the server to the client as a PUBLISH message. AT+QMTPUB Publish Messages (Data Mode) Test Command AT+QMTPUB=? Response +QMTPUB: (range of supported s),(range of supported s),(range of supported s),(list of supported s),,(range of supported s) Write Command Publish variable-length messages AT+QMTPUB=,, ,, OK Response > After > is reported, input the data to be sent. Press Ctrl+Z to send the data, or Esc to cancel the operation. OK +QMTPUB: ,,[,] Write Command Publish fixed-length messages AT+QMTPUB=,, ,,, If there is any error: ERROR Response > After > is responded, input the data to be sent. The number of bytes of input data must equal . OK +QMTPUB: ,,[,] Maximum Response Time If there is any error: ERROR × (default 15 s), determined by the network BG770A-GL&BG95xA-GL_MQTT_Application_Note 20 / 31 LPWA Module Series Characteristics / Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of a packet. Range: 0–65535. It will be 0 only when =0. Integer type. QoS level at which the client wants to publish messages. 0 At most once 1 At least once 2 Exactly once Integer type. Determines whether the server will retain the message after it has been delivered to the current subscribers. 0 The server will not retain the message after it has been delivered to the current subscribers 1 The server will retain the message after it has been delivered to the current subscribers String type. Topic that needs to be published. Integer type. Length of the message to be published. Range: 1–4096. Unit: byte. Integer type. Command execution result. 0 Packet sent successfully and ACK received from the server (message that is published when =0 does not require ACK) 1 Packet retransmission 2 Failed to send a packet If is 1, it means the number of times a packet has been retransmitted. If is 0 or 2, it will not be presented. Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. NOTE 1. If this command is executed successfully and OK is reported, the client can continue to publish new packets. The maximum quantity of the packet to be transmitted should not be greater than that of inflight windows (5). 2. After executing this command, the client will be ready to send data as a payload. The maximum length of data input at a time is 4096 bytes. To send the data, remember to press Ctrl+Z. 3. PUBLISH messages can be sent either from a publisher to the server, or from the server to a subscriber. When a server publishes messages to a subscriber, the following URC will be returned to notify the host to read the received data reported by the MQTT server: +QMTRECV: ,,[,], For more information on the URC description, see Chapter 4.2. BG770A-GL&BG95xA-GL_MQTT_Application_Note 21 / 31 LPWA Module Series 3.3.9. AT+QMTPUBEX Publish Messages (Command Mode) This command publishes messages. It provides the same functions as AT+QMTPUB, except that the format is different. AT+QMTPUBEX Publish Messages (Command Mode) Test Command AT+QMTPUBEX=? Response +QMTPUBEX: (range of supported s),( range of supported s),(range of supported s),(list of supported s),, Write Command AT+QMTPUBEX=,,,,, Maximum Response Time Characteristics OK Response OK +QMTPUB: ,,[,] If there is any error: ERROR × (default 15 s), determined by the network / Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of a packet. Range: 0–65535. It will be 0 only when =0. Integer type. QoS level at which the client wants to publish messages. 0 At most once 1 At least once 2 Exactly once Integer type. Determines whether the server will retain the message after it has been delivered to the current subscribers. 0 The server will not retain the message after it has been delivered to the current subscribers 1 The server will retain the message after it has been delivered to the current subscribers String type. Topic that needs to be published. String type. Message to be published. Maximum length: 560 bytes. Integer type. Command execution result. 0 Packet sent successfully and ACK received from the server (message that is published when =0 does not require ACK) 1 Packet retransmission BG770A-GL&BG95xA-GL_MQTT_Application_Note 22 / 31 LPWA Module Series 2 Failed to send a packet If is 1, it means the number of times a packet has been retransmitted. If is 0 or 2, it will not be presented. Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. NOTE The response flow of AT+QMTPUBEX will be the same as the response flow of AT+QMTPUB. 3.3.10. AT+QMTRECV Read Messages from Buffer This command reads messages from the storage buffer where the messages are stored after being reported by the server. AT+QMTRECV Read Messages from Buffer Test Command AT+QMTRECV=? Read Command AT+QMTRECV? Response OK Response +QMTRECV: ,,,,, OK Write Command AT+QMTRECV=[,] If there is no MQTT connection: OK Response List of (+QMTRECV: ,,,[,])s OK If no message has been received: OK Maximum Response Time If there is no MQTT connection: ERROR Determined by the network. BG770A-GL&BG95xA-GL_MQTT_Application_Note 23 / 31 LPWA Module Series Characteristics / Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Indicates if a message is stored in the buffer. As there can be maximum 5 messages in a buffer, the URC can report at most 5 messages simultaneously. 0 No stored messages 1 There are stored messages (up to 5) Integer type. Serial number of a received message. Range: 0–4. All buffer data will be read if this parameter is not specified. Integer type. Message identifier of the packet. Range: 0–65535. It will be 0 only when =0. String type. Topic that needs to be published. Integer type. Payload length. Unit: Byte. String type. Payload relating to topic name. BG770A-GL&BG95xA-GL_MQTT_Application_Note 24 / 31 LPWA Module Series 4 MQTT URCs This chapter describes the MQTT URCs. 4.1. +QMTSTAT: URC to Indicate State Change in MQTT Link Layer The URC that begins with +QMTSTAT will be reported when the state of an MQTT link layer is changed. +QMTSTAT: URC to Indicate State Change in MQTT Link Layer When the state of an MQTT link layer is changed, the client +QMTSTAT: , will close the MQTT connection and report the URC. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Error code. Refer to the table below for more information. Table 1: Error Codes of +QMTSTAT: URC 1 2 3 4 Description Solution Connection is closed or reset by a peer. Sending PINGREQ packet timed out or failed. Sending CONNECT packet timed out or failed. Receiving CONNACK packet timed out or failed. Execute AT+QMTOPEN command to reopen the MQTT connection. First, deactivate and activate the PDP. Then, reopen the MQTT connection. 1. Check whether the inputted username and password are correct. 2. Make sure the client ID is not used. 3. Reopen the MQTT connection and try to send CONNECT packet to the server again. 1. Check whether the inputted username and password are correct. 2. Make sure the client ID is not used. 3. Reopen the MQTT connection and try to send CONNECT packet to the server again. BG770A-GL&BG95xA-GL_MQTT_Application_Note 25 / 31 5 6 7 8–255 LPWA Module Series The client sends DISCONNECT packet to the sever and the server starts closing the MQTT connection. The client takes the initiative to close the MQTT connection due to constant packet sending failure. The link is not alive, or the server is unavailable. This is a normal process. 1. Make sure that the data are correct. 2. Try to reopen the MQTT connection since there may be a network congestion or an error. Make sure that the link is alive, or the server is currently available. Reserved for future uses. NOTE Error codes 5, 6 and 7 are currently not supported. 4.2. +QMTRECV: URC to Inform the Host to Read MQTT Packet Data The URC that begins with +QMTRECV: is mainly used to inform the host to read the received MQTT packet reported from the MQTT server. +QMTRECV: URC to Inform the Host to Read MQTT Packet Data +QMTRECV: ,,< topic>[,], +QMTRECV: ,[,] Notify the host to read the received data reported from the MQTT server. Notify that the message received from the MQTT server has been stored in a buffer. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of the packet. String type. Topic that has been received from the MQTT server. Integer type. Payload length. Unit: byte. String type. Payload relating to topic name. Integer type. Serial number of a received message. Range: 0–4. BG770A-GL&BG95xA-GL_MQTT_Application_Note 26 / 31 LPWA Module Series 5 Examples This chapter provides some examples that explain how to use the MQTT AT commands. 5.1. Example of MQTT Operation without SSL AT+QMTCFG='aliauth',0,'oyjtmPl5a5j','MQTT_TEST','wN9Y6pZSIIy7Exa5qVzcmigEGO4kAazZ' //Configure Alibaba device information for AliCloud. OK AT+QMTOPEN=? +QMTOPEN: (0-5),,(0-65535) OK AT+QMTOPEN=0,'iot-as-mqtt.cn-shanghai.aliyuncs.com',1883 //Open a network for MQTT client. OK +QMTOPEN: 0,0 //The MQTT client network opened successfully. AT+QMTOPEN? +QMTOPEN: 0,'iot-as-mqtt.cn-shanghai.aliyuncs.com',1883 OK AT+QMTCONN=? +QMTCONN: (0-5),,, OK //Connect a client to the MQTT server. //If AliCloud is connected, AT+QMTCFG='aliauth' can be used to configure the device information in advance. There is no need to provide the username/password from now on. AT+QMTCONN=0,'clientExample' OK +QMTCONN: 0,0,0 //The client has successfully connected to the MQTT server. AT+QMTSUB=? +QMTSUB: (0-5),(1-65535),,(0-2) BG770A-GL&BG95xA-GL_MQTT_Application_Note 27 / 31 LPWA Module Series OK //Subscribe to topics. AT+QMTSUB=0,1,'topic/example',2 OK +QMTSUB: 0,1,0,2 AT+QMTSUB=0,1,'topic/pub',0 OK +QMTSUB: 0,1,0,0 //If a client subscribed to a topic and other devices publish the same topic to the server, the module will report the following information. +QMTRECV: 0,0,'topic/example','This is the payload related to topic' //Unsubscribe from topics. AT+QMTUNS=0,1,'topic/example' OK +QMTUNS: 0,2,0 AT+QMTPUB=? +QMTPUB : (0-5),(0-65535),(0-2),(0,1),,(1-4096) OK //Publish messages. AT+QMTPUB=0,0,0,0,'topic/pub' >These are test data, hello MQTT. OK //After receiving >, input data These are test data, hello MQTT. and then send it. The maximum length of the data to be sent is 4096 bytes. All the data beyond 4096 bytes will be omitted. After inputting data, press Ctrl+Z to send them. +QMTPUB: 0,0,0 //If a client subscribed to a topic named 'topic/pub' and other devices publish the same topic to the server, the module will report the following information. +QMTRECV: 0,0,'topic/pub','These are test data, hello MQTT.' AT+QMTDISC=0 //Disconnect a client from the MQTT server. OK +QMTDISC: 0,0 //The connection closed successfully. BG770A-GL&BG95xA-GL_MQTT_Application_Note 28 / 31 LPWA Module Series 5.2. Example of MQTT Operation with SSL //Configure the MQTT session into SSL mode. AT+QMTCFG='ssl',0,1,2 OK //If SSL authentication mode is intended to be set as 'manage server and client authentication if requested by the remote server' (=2 in AT+QSSLCFG), upload a server root CA certificate, a client certificate, and a client private key to UFS. AT+QFUPL='cacert.pem',1758,100 //Upload a CA certificate to UFS. CONNECT +QFUPL: 1758,384a OK AT+QFUPL='client.pem',1220,100 //Upload a client certificate to UFS. CONNECT +QFUPL: 1220,2d53 OK AT+QFUPL='user_key.pem',1679,100 //Upload a client private key to UFS. CONNECT +QFUPL: 1679,335f OK //Configure the path of the CA certificate for SSL context 2. AT+QSSLCFG='cacert',2,'cacert.pem' OK //Configure the path of the client certificate for SSL context 2. AT+QSSLCFG='clientcert',2,'client.pem' OK //Configure the path of the client private key for SSL context 2. AT+QSSLCFG='clientkey',2,'user_key.pem' OK //Configure the authentication mode for SSL context 2. AT+QSSLCFG='seclevel',2,2 //SSL authentication mode: server and client authentication if requested by the remote server. BG770A-GL&BG95xA-GL_MQTT_Application_Note 29 / 31 LPWA Module Series OK AT+QSSLCFG='sslversion',2,4 OK AT+QSSLCFG='ciphersuite',2,0XFFFF OK AT+QSSLCFG='ignorelocaltime',2,1 OK //SSL authentication version //Cipher suite //Ignore the authentication time. //Start the MQTT SSL connection. AT+QMTOPEN=0,'a1zgnxur10j8ux.iot.us-east-1.amazonaws.com',8883 OK +QMTOPEN: 0,0 //Connect to the MQTT server. AT+QMTCONN=0,'MQTT-1' OK +QMTCONN: 0,0,0 //Subscribe to topics. AT+QMTSUB=0,1,'$aws/things/ MQTT-1/shadow/update/accepted',1 OK +QMTSUB: 0,1,0,1 //Publish messages. AT+QMTPUB=0,1,1,0,'$aws/things/MQTT-1/shadow/update/accepted' >These are published data from client OK +QMTPUB: 0,1,0 //If a client subscribed to a topic named '$aws/things/MQTT-1/shadow/update/accepted' and other devices publish the same topic to the server, the module will report the following information. +QMTRECV: 0,1,'$aws/things/MQTT-1/shadow/update/accepted','These are published data from client' //Disconnect a client from the MQTT server. AT+QMTDISC=0 OK +QMTDISC: 0,0 BG770A-GL&BG95xA-GL_MQTT_Application_Note 30 / 31 LPWA Module Series 6 Appendix References Table 2: Related Documents Document Name [1] MQTT V3.1 Protocol Specification [2] MQTT V3.1.1 Protocol Specification [3] Quectel_BG770A-GL&BG95×A-GL_SSL_Application_Note Table 3: Terms and Abbreviations Abbreviation ACK CA IP MQTT PDP QoS SSL TCP UFS URC Description Acknowledgement Certificate Authority Internet Protocol Message Queuing Telemetry Transport Packet Data Protocol Quality of Service Secure Sockets Layer Transmission Control Protocol User File System Unsolicited Result Code BG770A-GL&BG95xA-GL_MQTT_Application_Note 31 / 31
388.62 KB
BG770A-GL&BG95xA-GL PSM Application Note LPWA Module Series Version: 1.0 Date: 2022-01-14 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG770A-GL&BG95xA-GL_PSM_Application_Note 1 / 21 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG770A-GL&BG95xA-GL_PSM_Application_Note 2 / 21 LPWA Module Series About the Document Revision History Version Date Author Description - 2021-01-29 Igor STANCIC Creation of the document Igor STANCIC/ 1.0 2022-01-14 First official release Darko SAVIC BG770A-GL&BG95xA-GL_PSM_Application_Note 3 / 21 LPWA Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 5 Figure Index ................................................................................................................................................. 6 1 Introduction .......................................................................................................................................... 7 2 Description of PSM AT Commands ................................................................................................... 8 2.1. AT Command Introduction....................................................................................................... 8 2.1.1. Definitions......................................................................................................................... 8 2.1.2. AT Command Syntax ....................................................................................................... 8 2.2. Declaration of AT Command Examples .................................................................................. 9 2.3. Description of AT Commands .................................................................................................. 9 2.3.1. AT+CPSMS Power Saving Mode Setting ..................................................................... 9 2.3.2. AT+QPSMS Extended Power Saving Mode Setting ................................................... 11 2.3.3. AT+QPSMCFG PSM Feature and Minimum Threshold Value Setting ....................... 13 2.4. URC Description.................................................................................................................... 14 2.4.1. +QPSMTIMER Indicate the TAU Duration and Active Time Duration......................... 14 3 Waking Up from PSM......................................................................................................................... 16 3.1. Waking Up from PSM with the PON_TRIG Pin .................................................................... 16 3.2. Waking Up from PSM with the PWRKEY.............................................................................. 17 3.3. Waking Up from PSM when the T3412 Timer Expires.......................................................... 17 4 Typical Power Consumption Cycle.................................................................................................. 19 5 Appendix References ........................................................................................................................ 20 BG770A-GL&BG95xA-GL_PSM_Application_Note 4 / 21 LPWA Module Series Table Index Table 1: Related Documents ...................................................................................................................... 20 Table 2: Terms and Abbreviations .............................................................................................................. 20 BG770A-GL&BG95xA-GL_PSM_Application_Note 5 / 21 LPWA Module Series Figure Index Figure 1: Waking Up the Module from PSM with PON_TRIG ................................................................... 16 Figure 2: Waking up the Module from PSM with PWRKEY....................................................................... 17 BG770A-GL&BG95xA-GL_PSM_Application_Note 6 / 21 LPWA Module Series 1 Introduction This document describes the Power Saving Mode (PSM) feature and explains how to use the PSM function on the Quectel BG770A-GL, BG950A-GL and BG951A-GL modules. The PSM feature enables IoT devices to stay inactive or powered down most of the time to save power. The PSM function wakes up the device only during data transmission, which usually happens for a short period of time. The PSM feature is especially important for eMTC/NB-IoT devices and applications that have the following characteristics: ⚫ The eMTC/NB-IoT devices and applications are frequently inactive ⚫ Their active communication is of short duration ⚫ Data mainly originate from eMTC/NB-IoT devices (although the eMTC/NB-IoT devices can also download data when they are active) ⚫ There are power constraints (the devices are running on a battery) ⚫ The eMTC/NB-IoT devices require long battery life The PSM mode defined by 3GPP Release 13 is similar to power-off, but the UE (i.e., the BG770A-GL, BG950A-GL and BG951A-GL modules) remains registered on the network, so there is no need to re-attach or re-establish PDN connections. Therefore, the UE in PSM is not immediately available to mobile terminating services. The UE using PSM is available to mobile terminating services when it is in connected mode and during an Active Time that comes after the connected mode. The connected mode is caused by a mobile originated event like data transmission or signalling, e.g. after a periodic TAU procedure. The PSM is therefore suitable for UE that is expecting only infrequent mobile originating and terminating services, which can accept a corresponding latency in the mobile terminating communication. NOTE For a more detailed description of the PSM mode defined by 3GPP Release 13, see document [1]. BG770A-GL&BG95xA-GL_PSM_Application_Note 7 / 21 LPWA Module Series 2 Description of PSM AT Commands 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 1: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of a corresponding Write Command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. BG770A-GL&BG95xA-GL_PSM_Application_Note 8 / 21 LPWA Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 2.3. Description of AT Commands 2.3.1. AT+CPSMS Power Saving Mode Setting The Write Command configures the PSM parameters of a module. It controls: ⚫ whether the module wants to apply PSM or not, ⚫ the requested extended periodic TAU value in E-UTRAN, and ⚫ the requested Active Time value. See the URCs provided by AT+CEREG for the Active Time value and the extended periodic TAU value that are allocated to the module by the network in E-UTRAN. A special form of the command can be given as AT+CPSMS= (with all parameters omitted). In this form, the use of PSM is disabled (=0) and data for all parameters in the command are removed. The Read Command returns the current parameter values. The Test Command returns the supported s, the requested extended periodic TAU value in E-UTRAN and the requested Active Time value as compound values. AT+CPSMS Power Saving Mode Setting Test Command AT+CPSMS=? Response +CPSMS: (list of supported s),,,(list of supported s),(list of supported s) Read Command AT+CPSMS? OK Response +CPSMS: ,,,[],[] OK BG770A-GL&BG95xA-GL_PSM_Application_Note 9 / 21 LPWA Module Series Write Command AT+CPSMS=[,,[,[,]]] Response OK If there is any other error: ERROR Maximum Response Time 4000 ms Characteristics Reference 3GPP TS 27.007 The command takes effect immediately. The configurations will be saved automatically. Parameter Integer type. Disable or enable the use of PSM in the UE. 0 Disable the use of PSM 1 Enable the use of PSM String type. One byte in an 8-bit format. Requested extended periodic TAU value (T3412) to be allocated to the UE in E-UTRAN (e.g. '00001010' equals 100 minutes). In the Write Command, when is 1 and is omitted, the value that was configured last is used. Bits 5 to 1 represent the binary coded timer value. Bits 6 to 8 define the timer value unit as follows: Bits 8 7 6 0 0 0 value is incremented in multiples of 10 minutes 0 0 1 value is incremented in multiples of 1 hour 0 1 0 value is incremented in multiples of 10 hours 0 1 1 value is incremented in multiples of 2 seconds 1 0 0 value is incremented in multiples of 30 seconds 1 0 1 value is incremented in multiples of 1 minute String type. One byte in an 8-bit format. Requested Active Time value (T3324) to be allocated to UE (e.g., '00001111' equals 1 minute). Bits 5 to 1 represent the binary coded timer value. Bits 6 to 8 define the timer value unit as follows: Bits 8 7 6 0 0 0 value is incremented in multiples of 2 seconds 0 0 1 value is incremented in multiples of 1 minute 0 1 0 value is incremented in multiples of decihours 1 1 1 value indicates that the timer is deactivated. BG770A-GL&BG95xA-GL_PSM_Application_Note 10 / 21 LPWA Module Series Example AT+CPSMS=1,,,'00000100','00001111' //Set the requested T3412 value to 40 minutes, and set the OK requested T3324 value to 30 seconds. WARNING After entering PSM, all digital logic is powered down, therefore, it is prohibited to provide any external voltage to the module’s I/O ports that are not defined as a wake-up source. VDD_EXT pin can be used to monitor PSM activity and control the external logic. NOTE If the debugging mode is enabled (AT+QCFGEXT='debug'), depending on the logging activity load, the module can refuse to enter PSM mode. 2.3.2. AT+QPSMS Extended Power Saving Mode Setting This is an extended AT command, developed by Quectel, for setting PSM parameters. A special form of the command can be given as AT+QPSMS= (with all parameters omitted). In this form, the use of PSM is disabled (=0) and data for all parameters in the command are removed. It is similar to AT+CPSMS. AT+QPSMS Extended Power Saving Mode Setting Test Command AT+QPSMS=? Response +QPSMS: (list of supported s),,,(list of supported s),(list of supported s) Read Command AT+QPSMS? OK Response +QPSMS: ,,,[],[] Write Command AT+QPSMS=[,,[,[,]]]]] OK Response OK If there is any other error: ERROR Maximum Response Time 4000 ms Characteristics The command takes effect immediately. The configurations will be saved automatically. BG770A-GL&BG95xA-GL_PSM_Application_Note 11 / 21 LPWA Module Series Reference 3GPP TS 27.007 Parameter Integer type. Disable or enable the use of PSM in UE. 0 Disable the use of PSM 1 Enable the use of PSM String type. One byte in an 8-bit format. Requested extended periodic TAU value (T3412) to be allocated to UE in E-UTRAN (e.g., '00001010' equals 100 minutes). Bits 5 to 1 represent the binary coded timer value. Bits 6 to 8 define the timer value unit as follows: Bits 8 7 6 0 0 0 value is incremented in multiples of 10 minutes 0 0 1 value is incremented in multiples of 1 hour 0 1 0 value is incremented in multiples of 10 hours 0 1 1 value is incremented in multiples of 2 seconds 1 0 0 value is incremented in multiples of 30 seconds 1 0 1 value is incremented in multiples of 1 minute String type. One byte in an 8-bit format. Requested Active Time value (T3324) to be allocated to UE (e.g., '00001111' equals 1 minute). Bits 5 to 1 represent the binary coded timer value. Bits 6 to 8 define the timer value unit as follows: Bits 8 7 6 0 0 0 value is incremented in multiples of 2 seconds 0 0 1 value is incremented in multiples of 1 minute 0 1 0 value is incremented in multiples of decihours 1 1 1 value indicates that the timer is deactivated. Integer type. Extended periodic TAU value (T3412) to be allocated to UE in E-UTRAN. The value is specified by the network. Integer type. Active timer value (T3324) to be allocated to UE in E-UTRAN. The value is specified by the network. Example AT+QPSMS=1,,,'00000100','00001111' OK AT+QPSMS? //Set the requested T3412 value to 40 minutes, and set the requested T3324 value to 30 seconds. //Query the PSM mode, the periodic TAU and the active time specified by the network. BG770A-GL&BG95xA-GL_PSM_Application_Note 12 / 21 +QPSMS:1,,,'86400','2' OK LPWA Module Series WARNING After entering PSM, all digital logic is powered down, therefore, it is prohibited to provide any external voltage to the module’s I/O ports that are not defined as a wake-up source. VDD_EXT pin can be used to monitor PSM activity and control the external logic. NOTE If the debugging mode is enabled (AT+QCFGEXT='debug'), depending on the logging activity, the module can refuse to enter PSM mode. 2.3.3. AT+QPSMCFG PSM Feature and Minimum Threshold Value Setting The Write Command enables or disables the PSM feature and sets the minimum threshold value of the PSM cycle. A special form of the command can be given as AT+QPSMCFG= (with all parameters omitted). In this form, both parameters are set to their specific default values. AT+QPSMCFG PSM Feature and Minimum Threshold Value Setting Test Command AT+QPSMCFG=? Response +QPSMCFG: (range of supported s),(range of supported s) Write Command AT+QPSMCFG=[[,]] Read Command AT+QPSMCFG? OK Response OK If there is any error: ERROR Response +QPSMCFG: , Maximum Response Time Characteristics OK 300 ms The command takes effect after rebooting. The configurations will be saved automatically. Parameter Integer type. Minimum threshold value of the PSM cycle. BG770A-GL&BG95xA-GL_PSM_Application_Note 13 / 21 LPWA Module Series Condition to enter PSM: less than PSM cycle (= T3412 - T3324). Range: 20-4294967295. Unit: second. Integer type. Bitmask to indicate the PSM feature (1: Enable; 0: Disable). Each bit is configured independently. Range: 0-2-15. Bit 0 PSM without network coordination Bit 1 Rel-12 PSM without context retention Bit 2 Rel-12 PSM with context retention Bit 3 PSM in-between eDRX cycles Example AT+QPSMCFG=100 OK AT+QPSMCFG? +QPSMCFG: 100,4 OK //Set the threshold to 100 seconds. //Query the threshold value and the PSM version. 2.4. URC Description 2.4.1. +QPSMTIMER Indicate the TAU Duration and Active Time Duration The URC is used to indicate the TAU duration and active time duration of a module’s PSM. The URC is disabled by default and can be enabled with AT+QCFG='psm/urc',1. +QPSMTIMER Indicate the TAU Duration and Active Time Duration +QPSMTIMER: , module’s PSM. Parameter Integer type. The TAU duration of PSM. Unit: second. Integer type. The active time duration of PSM. Unit: second. Example AT+QCFG='psm/urc' +QCFG: 'psm/urc',0 OK AT+QCFG='psm/urc',1 OK BG770A-GL&BG95xA-GL_PSM_Application_Note 14 / 21 +QPSMTIMER: 86400,2 LPWA Module Series //The TAU and active timer value of PSM. BG770A-GL&BG95xA-GL_PSM_Application_Note 15 / 21 LPWA Module Series 3 Waking Up from PSM There are three scenarios to wake up the module: ⚫ Forced: Hold the PON_TRIG high to wake up the module. ⚫ Drive PWRKEY low to wake up the module. The UART port stays inaccessible until the PON_TRIG is pulled high. ⚫ Automatic: When the T3412 timer expires, the module wakes up automatically. The UART port stays inaccessible until the PON_TRIG is pulled high. 3.1. Waking Up from PSM with the PON_TRIG Pin To wake the module up from the PSM to realize communication between the module and the network. Step 1: Hold the PON_TRIG high and check if the module has been woken up from PSM. Step 2: Establish the active UL and/or DL communication. Figure 1: Waking Up the Module from PSM with PON_TRIG BG770A-GL&BG95xA-GL_PSM_Application_Note 16 / 21 LPWA Module Series 3.2. Waking Up from PSM with the PWRKEY Like the PON_TRIG solution, the module can be woken up from PSM through steps below to realize communication between the module and the network. Step 1: Drive PWRKEY low and check if the module has been woken up from PSM. The UART port stays inaccessible until the PON_TRIG is pulled high. Step 2: Establish the active UL and/or DL communication. Figure 2: Waking up the Module from PSM with PWRKEY 3.3. Waking Up from PSM when the T3412 Timer Expires When the T3412 (extended TAU timer) expires, the module automatically wakes up from PSM. The following figure illustrates the automatic procedure for waking up a module from PSM. BG770A-GL&BG95xA-GL_PSM_Application_Note 17 / 21 LPWA Module Series Module Network T3324 and/or T3412 Extended Value Attach Accept T3324 and/or T3412 Extended Value RRC Release T3324 T3412 PSM Tracking Area Update Request T3324 and/or T3412 Extended Value Tracking Area Update Accept T3324 and/or T3412 Extended Value RRC Release Figure 3: Waking Up the Module from PSM when T3412 Expires BG770A-GL&BG95xA-GL_PSM_Application_Note 18 / 21 LPWA Module Series 4 Typical Power Consumption Cycle The following figure shows the typical power consumption cycle of the module. Figure 4: Typical Power Consumption Cycle BG770A-GL&BG95xA-GL_PSM_Application_Note 19 / 21 LPWA Module Series 5 Appendix References Table 1: Related Documents Document Name [1] 3GPP TS 23.682 [2] 3GPP TS 23.401 [3] Quectel_BG770A-GL&BG95×A-GL_AT_Commands_Manual Table 2: Terms and Abbreviations Abbreviation 3GPP AP DL eDRX eMTC E-UTRAN MCU NB-IoT OOS PC PDN PSM RRC Description 3rd Generation Partnership Project Application Processor Downlink Extended Discontinuous Reception Enhanced Machine-Type Communication Evolved UMTS Terrestrial Radio Access Network Microcontroller Unit Narrow Band Internet of Things Out Of Service Personal Computer Packet Data Network Power Saving Mode Radio Resource Control BG770A-GL&BG95xA-GL_PSM_Application_Note 20 / 21 TAU UART UE UL URC LPWA Module Series Tracking Area Update Universal Asynchronous Receiver/Transmitter User Equipment (typically, the module) Uplink Unsolicited Result Code BG770A-GL&BG95xA-GL_PSM_Application_Note 21 / 21
291.98 KB
BG770A-GL&BG95xA-GL QuecLocator Application Note LPWA Module Series Version: 1.0 Date: 2022-01-14 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 1 / 18 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 2 / 18 LPWA Module Series About the Document Revision History Version Date Author Description - 2021-11-17 Jelena JOVANOVIC Creation of the document Jelena JOVANOVIC/ 1.0 2022-01-14 First official release Nikola BLAZIC BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 3 / 18 LPWA Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 5 1 Introduction .......................................................................................................................................... 6 2 QuecLocator® Authentication............................................................................................................. 7 3 QuecLocator® AT Commands ............................................................................................................ 8 3.1. AT Command Introduction .......................................................................................................... 8 3.1.1. Definitions......................................................................................................................... 8 3.1.2. AT Command Syntax ....................................................................................................... 8 3.2. Declaration of AT Command Examples ...................................................................................... 9 3.3. Description of QuecLocator AT Commands................................................................................ 9 3.3.1. AT+QLBSCFG Configure Parameters for QuecLocator ............................................... 9 3.3.2. AT+QLBS Get Location Information by QuecLocator ................................................. 14 4 Example .............................................................................................................................................. 16 5 Summary of Error Codes .................................................................................................................. 17 6 Appendix Reference .......................................................................................................................... 18 BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 4 / 18 LPWA Module Series Table Index Table 1: Types of AT Commands ................................................................................................................. 8 Table 2: Summary of Error Codes.............................................................................................................. 17 Table 3: Terms and Abbreviations .............................................................................................................. 18 BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 5 / 18 LPWA Module Series 1 Introduction This application note introduces the AT commands defined for the QuecLocator® service supported by Quectel BG770A-GL, BG950A-GL and BG951A-GL modules. QuecLocator® is an efficient positioning technology developed by Quectel. By integrating the cellular network information, it boosts the stand-alone GNSS performance, especially in challenging environments, such as urban canyons, indoors, parking garages, areas under overpasses, or in case the GNSS signal is blocked or intermittent. For more details about QuecLocator®, visit Quectel IoT Portal. NOTE QuecLocator® is a value-added function provided by Quectel. For more details about the service, contact Quectel sales representatives or Technical Support (support@quectel.com). BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 6 / 18 LPWA Module Series 2 QuecLocator® Authentication To use the QuecLocator service, an authorization token is necessary for identity authentication. The auth token remains valid after the module reboots or powers off. Execute AT+QLBSCFG='token' to confirm whether a token has already been configured when you use the service for the first time; if not, please input one. The general steps are illustrated in the flowchart below. MCU Module Configure Token AT+QLBSCFG='token' Query whether the token has been set +QLBSCFG: 'token','' No token has been set previously AT+QLBSCFG='token','1234567890ABXDEF' Input token AT+QLBSCFG='token' Query whether the token has been set +QLBSCFG: 'token','****************' The token has been set AT+QLBS Execute the command to get location information The token is saved after power-off. If no token has been set, input one. If the token exists, there is no need to input it. Figure 1: QuecLocator® Auth Token Configuration NOTE Consult Quectel Technical Support to apply for the token. BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 7 / 18 LPWA Module Series 3 QuecLocator® AT Commands 3.1. AT Command Introduction 3.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 3.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 1: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of a corresponding Write Command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 8 / 18 LPWA Module Series 3.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 3.3. Description of QuecLocator AT Commands 3.3.1. AT+QLBSCFG Configure Parameters for QuecLocator This command configures QuecLocator related parameters. AT+QLBSCFG Configure Parameters for QuecLocator Test Command AT+QLBSCFG=? Response +QLBSCFG: 'asynch',(list of supported s) +QLBSCFG: 'timeout',(range of supported s) +QLBSCFG: 'server', +QLBSCFG: 'token', +QLBSCFG: 'timeupdate',(list of supported s) +QLBSCFG: 'withtime',(list of supported s) +QLBSCFG: 'latorder',(list of supported s) +QLBSCFG: 'scanband',(list of supported s),(list of supported s) +QLBSCFG: 'singlecell',(list of supported s) Read Command AT+QLBSCFG? OK Response +QLBSCFG: 'asynch', +QLBSCFG: 'timeout', +QLBSCFG: 'server', +QLBSCFG: 'token', +QLBSCFG: 'timeupdate', +QLBSCFG: 'withtime', +QLBSCFG: 'latorder', +QLBSCFG: 'scanband',[,] +QLBSCFG: 'singlecell', OK BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 9 / 18 LPWA Module Series Write Command AT+QLBSCFG='asynch'[,] Response If the optional parameter is omitted, query the current setting: +QLBSCFG: 'asynch', OK If the optional parameter is specified, configure the execution mode of AT+QLBS: OK Write Command AT+QLBSCFG='timeout'[,] If there is an error related to ME functionality: +CME ERROR: Response If the optional parameter is omitted, query the current setting: +QLBSCFG: 'timeout', OK If the optional parameter is specified, configure the maximum response time of AT+QLBS: OK Write Command 1 AT+QLBSCFG='server'[,] If there is an error related to ME functionality: +CME ERROR: Response If the optional parameter is omitted, query the current setting: +QLBSCFG: 'server', OK If the optional parameter is specified, configure the domain name/IP address and port number of the server that provides the positioning service: OK Write Command AT+QLBSCFG='token'[,] If there is an error related to ME functionality: +CME ERROR: Response If the optional parameter is omitted, query the current setting: (1) If has been set previously: +QLBSCFG: 'token','*****************' 1 Usually, there is no need to configure . When a non-default server is used for positioning service, configure the domain name/IP address and port number of the server with this command. BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 10 / 18 LPWA Module Series OK (2) If has not been set previously: +QLBSCFG: 'token','' OK If the optional parameter is specified, configure the token value for server authentication: OK Write Command AT+QLBSCFG='timeupdate'[,< update_mode>] If there is an error related to ME functionality: +CME ERROR: Response If the optional parameter is omitted, query the current setting: +QLBSCFG: 'timeupdate', OK If the optional parameter is specified, configure whether to update to the RTC the time acquired at accessing the server that provides the positioning service: OK If there is an error related to ME functionality: +CME ERROR: Write Command Response AT+QLBSCFG='withtime'[,] +QLBSCFG: 'withtime', OK If the optional parameter is specified, configure whether to output in the response of AT+QLBS: OK Write Command AT+QLBSCFG='latorder'[,] If there is an error related to ME functionality: +CME ERROR: Response If the optional parameter is omitted, query the current setting: +QLBSCFG: 'latorder', OK BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 11 / 18 LPWA Module Series If the optional parameter is specified, configure the latitude and longitude output order in the location information acquired with AT+QLBS: OK Write Command AT+QLBSCFG='scanband'[,[,]] If there is an error related to ME functionality: +CME ERROR: Response If the optional parameters are omitted, query the current settings: +QLBSCFG: 'scanband',[,] OK If any of the optional parameters is specified, configure the scan mode and the eMTC frequency band to be scanned. can be specified only when =1. OK Write Command AT+QLBSCFG='singlecell'[,] If there is an error related to ME functionality: +CME ERROR: Response If the optional parameter is omitted, query the current setting: +QLBSCFG: 'singlecell', OK If the optional parameter is specified, enable or disable cellular positioning (positioning based on cell ID with algorithm): OK Maximum Response Time Characteristics If there is an error related to ME functionality: +CME ERROR: 300 ms The commands take effect immediately. The configurations will not be saved except those of and . Parameter Integer type. Command execution mode of AT+QLBS. In different modes, the response of the command varies. See Chapter 3.3.2 for details. 0 Synchronous mode (Not supported in eMTC network) 1 Asynchronous mode BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 12 / 18 LPWA Module Series Integer type. Maximum response time of AT+QLBS. If there is no response from the server within , the command times out. Range: 10–120. Default: 60. Unit: second. String type. Domain name/IP address and port number of the server. Format: 'domain name/IP address:port' (e.g. 'www.queclocator.com:80'). Port number range: 1–65535. Default value: 'www.queclocator.com:80'. String type. Value of the authentication token. Length: 16 bytes. Integer type. Whether to update to the RTC the time acquired at accessing the server that provides the positioning service. 0 Do not update the time to RTC 1 Update the time to RTC Integer type. Whether to output in the response of AT+QLBS. 0 Do not output 1 Output Integer type. Latitude and longitude output order in the location information acquired with AT+QLBS. 0 Output longitude before latitude: +QLBS: ,,[,] 1 Output latitude before longitude: +QLBS: ,,[,] See Chapter 3.3.2 for details of the parameters. Integer type. Scan mode. 0 Scan the currently attached band 1 Scan full bands or a specified band A hexadecimal value that specifies the eMTC frequency band to be scanned. For example, if it is set to 0x40000000, LTE B31 will be scanned. This parameter can be configured only when =1. 0x1 (BAND_PREF_LTE_BAND1) LTE B1 0x2 (BAND_PREF_LTE_BAND2) LTE B2 0x4 (BAND_PREF_LTE_BAND3) LTE B3 0x8 (BAND_PREF_LTE_BAND4) LTE B4 0x10 (BAND_PREF_LTE_BAND5) LTE B5 0x80 (BAND_PREF_LTE_BAND8) LTE B8 0x800 (BAND_PREF_LTE_BAND12) LTE B12 0x1000 (BAND_PREF_LTE_BAND13) LTE B13 0x20000 (BAND_PREF_LTE_BAND18) LTE B18 0x40000 (BAND_PREF_LTE_BAND19) LTE B19 0x80000 (BAND_PREF_LTE_BAND20) LTE B20 0x1000000 (BAND_PREF_LTE_BAND25) LTE B25 0x2000000 (BAND_PREF_LTE_BAND26) LTE B26 0x4000000 (BAND_PREF_LTE_BAND27) LTE B27 0x8000000 (BAND_PREF_LTE_BAND28) LTE B28 0x20000000000000000 (BAND_PREF_LTE_BAND66) LTE B66 Integer type. Enable or disable cellular positioning. BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 13 / 18 LPWA Module Series 0 Disable 1 Enable Integer type. Result code. See Chapter 5 for more information. NOTE 1. The is used for server authentication. Apply to Quectel for it in advance. 2. The is only supported in LTE-M (eMTC) network. The default band to be scanned is the one to which the module has attached. If =1 and is not specified, AT+QLBS is executed to scan full bands and you need to wait for more than 1 minute for the response. 3. When you configure , make sure the specified band is supported by the current operator. Otherwise, the module cannot get cell information of the band. 3.3.2. AT+QLBS Get Location Information by QuecLocator This command outputs the location information by QuecLocator. AT+QLBS Get Location Information by QuecLocator Test Command AT+QLBS=? Execution Command Output the location information with cellular positioning enabled. AT+QLBS Response OK Response If the module is in synchronous mode (=0) and the positioning succeeds: +QLBS: ,,[,] OK If the module is in synchronous mode and the positioning fails: +QLBS: OK If the module is in asynchronous mode (=1) and the positioning succeeds: OK +QLBS: ,,[,] If the module is in asynchronous mode and the positioning fails: OK +QLBS: BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 14 / 18 LPWA Module Series Maximum Response Time Characteristics If there is an error related to ME functionality: +CME ERROR: Depends on the in AT+QLBSCFG='timeout', . The command takes effect immediately. The configurations will not be saved. Parameter Float type. Latitude of the location information. This value is accurate to six decimal places. Range: -90.000000 to 90.000000. Float type. Longitude of the location information. This value is accurate to six decimal places. Range: -180.000000 to 180.000000. String type. Date and time obtained from HTTP header. Integer type. Positioning result. 0 Positioning succeeded Other values Positioning failed (See Chapter 5 for more information.) Integer type. Result code. See Chapter 5 for more information. BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 15 / 18 LPWA Module Series 4 Example //Activate network first, then make configurations and get locations referring to the steps below. AT+QLBSCFG='token' //Query the token value for authentication required by QuecLocator server. +QLBSCFG: 'token','' //No token has been set previously. OK AT+QLBSCFG='token','1234567890ABCDEF' OK AT+QLBSCFG='token' +QLBSCFG: 'token','****************' //Input the token value for authentication required by QuecLocator server. //Query the token value for authentication required by QuecLocator server. OK AT+QLBSCFG='latorder',1 OK AT+QLBSCFG='asynch',1 OK AT+QLBS OK //Configure the location output format into: +QLBS: ,, //Configure the execute mode of AT+QLBS to asynchronous mode. //Start cellular positioning. +QLBS: 0,31.847649,117.200134 BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 16 / 18 LPWA Module Series 5 Summary of Error Codes Table 2: Summary of Error Codes Code of 10000 Description of Error Codes QuecLocator fix failed 10001 10002 10003 10004 10005 Illegal IMEI number Token does not exist The number of devices using the same token exceeds the limit Times of positioning initiated by the same device in one day exceeds the limit Total times of positioning using the same token exceeds the limit 10006 10007 10008 10009 Token expired IMEI number not accepted by the server Times of positioning using the same token within one day exceeds the limit The frequency of positioning using the same token exceeds the limit NOTE QuecLocator uses HTTP protocol. If any HTTP error code is returned, see Quectel_BG770A-GL&BG95xA-GL_HTTP(S)_Application_Note for the description of the error code. BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 17 / 18 LPWA Module Series 6 Appendix Reference Table 3: Terms and Abbreviations Abbreviation eMTC GNSS HTTP IMEI IoT IP LPWA LTE-M MCU ME RTC TA URC Description Enhanced Machine Type of Communication Global Navigation Satellite System Hypertext Transfer Protocol International Mobile Equipment Identity Internet of Things Internet Protocol Low-Power Wide-Area Long Term Evolution for Machines Microcontroller Unit Mobile Equipment Real-Time Clock Terminal Adapter Unsolicited Result Code BG770A-GL&BG95xA-GL_QuecLocator_Application_Note 18 / 18
186.80 KB
BG770A-GL&BG95xA-GL TCP/IP Application Note LPWA Module Series Version: 1.1 Date: 2022-01-14 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 1 / 55 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 2 / 55 LPWA Module Series About the Document Revision History Version Date Author Description - 2021-02-01 Terrence YANG Creation of the Document Terrence YANG/ 1.0 2021-07-30 First official release Vladan RAKIC 1. Added the ways to return to transparent transmission mode (Chapter 1.3). 2. Added two notes for AT+QIOPEN (Chapter 2.3.5). 3. Enabled setting in AT+QICLOSE (Chapter 2.3.6). 4. Added in the responses of AT+QISTATE Read/Execution/Write Command (Chapter 2.3.7). 5. Added in the response of AT+QIDNSGIP Write Command (Chapter 2.3.11). 6. Added AT+QISENDEX (Chapter 2.3.12). 7. Added AT+QISWTMD (Chapter 2.3.13). 1.1 2022-01-14 Igor STANCIC 8. Added AT+QNTP (Chapter 2.3.14). 9. Added AT+QIDNSCFG (Chapter 2.3.15). 10. Added AT+QISDE (Chapter 2.3.16). 11. Added AT+QIGETERROR (Chapter 2.3.17). 12. Added in the URC indicating incoming data in buffer access mode (Chapter 2.4.2). 13. Added examples about TCP/UDP/PING operations under IPv6, an example about UDP client with RAI feature, an example about local time synchronization, and an example about getting the last error code (Chapter 3). BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 3 / 55 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 7 1 Introduction ......................................................................................................................................... 8 1.1. Special Mark ............................................................................................................................... 8 1.2. Use of TCP/IP AT Commands..................................................................................................... 8 1.3. Description of Data Access Modes........................................................................................... 10 2 TCP/IP AT Commands ...................................................................................................................... 12 2.1. AT Command Introduction ........................................................................................................ 12 2.1.1. Definitions .................................................................................................................... 12 2.1.2. AT Command Syntax ................................................................................................... 12 2.2. Declaration of AT Command Examples .................................................................................... 13 2.3. Description of TCP/IP AT Commands ....................................................................................... 13 2.3.1. AT+QICSGP Configure Parameters of a TCP/IP Context ........................................ 13 2.3.2. AT+QICFG Configure Optional Parameters ............................................................. 14 2.3.3. AT+QIACT Activate a PDP Context .......................................................................... 18 2.3.4. AT+QIDEACT Deactivate a PDP Context................................................................. 19 2.3.5. AT+QIOPEN Open a Socket Service........................................................................ 19 2.3.6. AT+QICLOSE Close a Socket Service ..................................................................... 21 2.3.7. AT+QISTATE Query Socket Service Status ............................................................. 22 2.3.8. AT+QISEND Send Data ............................................................................................ 24 2.3.9. AT+QIRD Retrieve the Received TCP/IP Data......................................................... 26 2.3.10. AT+QPING Ping a Remote Host............................................................................... 28 2.3.11. AT+QIDNSGIP Get IP Address by Domain Name.................................................... 29 2.3.12. AT+QISENDEX Send Hex String Data ..................................................................... 30 2.3.13. AT+QISWTMD Switch Data Access Mode ............................................................... 31 2.3.14. AT+QNTP Synchronize Local Time with NTP Server ............................................... 32 2.3.15. AT+QIDNSCFG Configure Address of DNS Server ................................................. 33 2.3.16. AT+QISDE Control Whether to Echo the Data for AT+QISEND .............................. 34 2.3.17. AT+QIGETERROR Query the Last Result Code...................................................... 34 2.4. Description of URCs ................................................................................................................. 35 2.4.1. +QIURC: 'closed' Indicate Connection Closed ........................................................ 35 2.4.2. +QIURC: 'recv' Indicate Incoming Data ................................................................... 35 2.4.3. +QIURC: 'incoming full' Indicate Incoming Connection Reaches the Limit............. 36 2.4.4. +QIURC: 'incoming' Indicate Incoming Connection ................................................ 36 2.4.5. +QIURC: 'pdpdeact' Indicate PDP Deactivation ...................................................... 37 3 Examples ........................................................................................................................................... 38 3.1. Configure and Activate a Context ............................................................................................. 38 3.1.1. Configure a Context..................................................................................................... 38 3.1.2. Activate a Context........................................................................................................ 38 BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 4 / 55 LPWA Module Series 3.1.3. Deactivate a Context ................................................................................................... 38 3.2. TCP Client Works in Buffer Access Mode under IPv4 .............................................................. 39 3.2.1. Set up a TCP Client Connection and Enter Buffer Access Mode ............................... 39 3.2.2. Send Data in Buffer Access Mode............................................................................... 39 3.2.3. Retrieve Data from Remote Server in Buffer Access Mode ........................................ 40 3.2.4. Close a Connection ..................................................................................................... 40 3.3. TCP Client Works in Buffer Access Mode under IPv6 .............................................................. 40 3.3.1. Set up a TCP Client Connection and Enter Buffer Access Mode ............................... 40 3.3.2. Send Data in Buffer Access Mode............................................................................... 41 3.3.3. Receive Data from Remote Server in Buffer Access Mode ........................................ 41 3.3.4. Close a Connection ..................................................................................................... 42 3.4. TCP Client Works in Transparent Transmission Mode............................................................. 42 3.4.1. Set up a TCP Client Connection and Enter Transparent Transmission Mode............ 42 3.4.2. Send Data in Transparent Transmission Mode ........................................................... 42 3.4.3. Retrieve Data from Remote Server in Transparent Transmission Mode .................... 42 3.4.4. Close a TCP Client ...................................................................................................... 42 3.5. TCP Client Works in Direct Push Mode .................................................................................... 43 3.5.1. Set up a TCP Client Connection and Enter Direct Push Mode ................................... 43 3.5.2. Send Data in Direct Push Mode .................................................................................. 43 3.5.3. Retrieve Data from Remote Server in Direct Push Mode ........................................... 43 3.5.4. Close a TCP Client ...................................................................................................... 44 3.6. TCP Server Works in Buffer Access Mode under IPv4 ............................................................ 44 3.6.1. Start a TCP Server....................................................................................................... 44 3.6.2. Accept TCP Incoming Connection............................................................................... 44 3.6.3. Retrieve Data from Incoming Connection ................................................................... 44 3.6.4. Close a TCP Server ..................................................................................................... 45 3.7. TCP Server Works in Buffer Access Mode under IPv6 ............................................................ 45 3.7.1. Start a TCP Server....................................................................................................... 45 3.7.2. Accept TCP Incoming Connection............................................................................... 45 3.7.3. Retrieve Data from Incoming Connection ................................................................... 45 3.7.4. Switch Incoming Connection to Transparent Transmission Mode .............................. 46 3.7.5. Close a TCP Server ..................................................................................................... 46 3.8. UDP Service under IPv4 ........................................................................................................... 46 3.8.1. Start a UDP Service..................................................................................................... 46 3.8.2. Send UDP Data to Remote Client ............................................................................... 47 3.8.3. Retrieve Data from Remote Client............................................................................... 47 3.8.4. Close a UDP Service ................................................................................................... 47 3.9. UDP Service under IPv6 ........................................................................................................... 48 3.9.1. Start a UDP Service..................................................................................................... 48 3.9.2. Send UDP Data to Remote Client ............................................................................... 48 3.9.3. Retrieve Data from Remote Client............................................................................... 48 3.9.4. Close a UDP Service ................................................................................................... 49 3.10. UDP Client with RAI Feature* ................................................................................................... 49 3.10.1. Start a UDP Client........................................................................................................ 49 BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 5 / 55 LPWA Module Series 3.10.2. Send UDP Data with RAI Information* ........................................................................ 49 3.10.3. Close a UDP Client ...................................................................................................... 50 3.11. PING.......................................................................................................................................... 50 3.11.1. PING under IPv4.......................................................................................................... 50 3.11.2. PING under IPv6.......................................................................................................... 50 3.12. Synchronize Local Time............................................................................................................ 51 3.13. Getting the Last Error Code ...................................................................................................... 51 4 Summary of Result Codes ............................................................................................................... 52 5 Appendix References ....................................................................................................................... 54 BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 6 / 55 LPWA Module Series Table Index Table 1: Special Mark ................................................................................................................................... 8 Table 2: Types of AT Commands ............................................................................................................... 12 Table 3: Summary of Result Codes ........................................................................................................... 52 Table 4: Related Documents ...................................................................................................................... 54 Table 5: Terms and Abbreviations .............................................................................................................. 54 BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 7 / 55 LPWA Module Series 1 Introduction Quectel BG770A-GL, BG950A-GL and BG951A-GL modules feature an embedded TCP/IP stack, which enables the host to access the Internet directly via AT commands. This significantly reduces the dependence on external PPP and TCP/IP protocol stacks and thus minimizes the cost. BG770A-GL, BG950A-GL and BG951A-GL modules provide the following socket services: ⚫ TCP client ⚫ UDP client ⚫ TCP LISTENER ⚫ UDP SERVICE NOTE See the firmware release notes of corresponding module models to check if the function is supported. 1.1. Special Mark Table 1: Special Mark Mark * Definition Unless otherwise specified, when an asterisk (*) is used after a function, feature, interface, pin name, AT command, or argument, it indicates that the function, feature, interface, pin, AT command, or argument is under development and currently not supported; and the asterisk (*) after a model indicates that the sample of such model is currently unavailable. 1.2. Use of TCP/IP AT Commands With TCP/IP AT commands, the host can configure a PDP context, activate/deactivate the PDP context, open/close a socket service and send/retrieve data via the socket service. The following figure illustrates how to use TCP/IP AT commands. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 8 / 55 LPWA Module Series Recommended Power on/off: For the proper power on/off procedure and timings, please check the hardware design manual of specified modules. Query (U)SIM Card Status: Execute AT+CPIN. Reboot the module if AT+CPIN? fails to identify (U)SIM card in 20 s. PS Service: 1. If of AT+CEREG? equals 1 or 5, it means that the module has registered on PS domain service in eMTC or NB-IoT network. 2. Go to next step no matter whether it is registered on PS domain service or not in 60 s. Configure a PDP Context: Configure APN, user name, password and auth type with AT+QICSGP. (AT+CGDCONT only can configure APN information.) Power on the module Send AT command and wait for the module to respond OK Query (U)SIM card status with AT+CPIN? If you fail to identify (U)SIM card in 20 s, then reboot the module. Identify (U)SIM card Query PS service in 60 s with AT+CEREG? If you fail to get PS registered status, configure the PDP context then switch the functionality level with AT+CFUN or reboot the module. Configure the PDP Context with AT+QICSGP/AT+CGDCONT Activate a PDP Context: 1. Activate the PDP context with AT+QIACT=. 2. Query IP address of the PDP context with AT+QIACT?. NOTE: a) All above commands should be executed together in sequence. b) Reboot the module if there is no response to AT+QIACT in 150 s. c) Reboot the module if it fails to deactivate the PDP context for 3 consecutive times. 3. Deactivate the PDP context: reboot the module if there is no response to AT+QIDEACT in 40 s. Reboot the module if there is no response in 40s. The PDP context is deactivated successfully Activate the PDP context with AT+QIACT= and AT+QIACT? 1. Reboot the module if there is no response in 150 s. 2. If you fail to deactivate the PDP context for 3 consecutive times, reboot the module. Failed to activate the PDP context Successfully activate PDP context Deactivate the PDP context with AT+QIDEACT= Open connection with AT+QIOPEN Open Connection: 1. If you fail to get the response to AT+QIOPEN in 150 s, close the connection. 2. If the module fails to open the connection for 5 consecutive times, deactivate the PDP context first, and then re-activate the PDP context and open connection again. 1. Failed to open the connection for 5 consecutive times. 2. No response in 150 s. +QIOPEN: , Send data with AT+QISEND= Get ACK in 90 s TCP Connection Maintenance and Detection: 1. Send data with AT+QISEND =[,]. It is recommended to periodically send a small data packet to the remote end to maintain and detect the TCP connection. 2. Query sending ACK with AT+QISEND=,0. If the package is still not acknowledged after two minutes (query every 5 seconds, 24 times in total), the TCP connection may be abnormal. Execute AT+QICLOSE to close the current connection, and then execute AT+QIOPEN to re-establish the TCP connection. Query sending ACK with AT+QISEND= ,0 Failed to get ACK in 90 s Close connection OK with AT+QICLOSE= Reboot the module if there is no response in 10 s. NOTE: 1. Please note that you need to wait for the final response (for example OK, CME ERROR, CMS ERROR) of the last AT command you entered before you enter the next AT command. You can reboot the module if the module fails to get response in 60 s. 2. Reboot the module if you do not get the response to AT+QIACT in 150 s, or response to AT+QICLOSE in 10 s and AT+QIDEACT in 40 s. 3. DO NOT reboot the module too frequently. If the module has been rebooted for 3 consecutive times due to a failed AT command, it can immediately be rebooted for the fourth time. If the command fails again, reboot the module for the fifth time in 10 minutes. If the command fails, reboot for the sixth time in 30 minutes, and if the command still fails, reboot for the seventh time in 1 h. Figure 1: Flow Chart of TCP/IP AT Command Use BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 9 / 55 LPWA Module Series 1.3. Description of Data Access Modes BG770A-GL, BG950A-GL and BG951A-GL modules support three data access modes: ⚫ Buffer access mode ⚫ Direct push mode ⚫ Transparent transmission mode When opening a socket service via AT+QIOPEN, you can specify the data access mode with . After the socket service is opened, the data access mode can be changed with AT+QISWTMD. 1. In buffer access mode, the module buffers data upon receiving them and reports a URC in the format of +QIURC: 'recv',[,] to notify the host of incoming data. In this case, the host can retrieve the buffered data with AT+QIRD. 2. In direct push mode, the module outputs the received data directly through a URC in the format of +QIURC: 'recv',, or +QIURC: 'recv',,,,. See Chapter 2.4.2 for more information. 3. In transparent transmission mode, the corresponding COM port is exclusively used for sending/receiving data directly to/from the Internet. It cannot be used for other purposes such as running AT commands, etc. ⚫ Exit transparent transmission mode To make the module exit transparent transmission mode either: 1) Execute +++. Follow the requirements below to prevent the +++ from being misinterpreted as data: a) Do not input any character for at least 1 second before and after inputting +++. b) Input +++ within 1 second, and wait until OK is returned. After OK is returned, the module switches to buffer access mode. OR 2) Change MAIN_DTR from LOW to HIGH to make the module enter command mode (the COM port can now be used for running AT commands, as well as for sending/retrieving data). In this case, set AT&D1 (see document [1]) before the module enters transparent transmission mode. ⚫ Return to transparent transmission mode To return to transparent transmission mode either: 1) Execute AT+QISWTMD. Before execution specify as 2. Once transparent transmission mode is entered successfully, CONNECT is returned. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 10 / 55 LPWA Module Series OR 2) Execute ATO. After a connection exits transparent transmission mode, executing ATO switches the data access mode back to transparent transmission mode. Once transparent transmission mode is entered successfully, CONNECT is returned. If no connection has entered transparent transmission mode, ATO returns NO CARRIER. NOTE 1. In buffer access mode, if the buffer is not empty, and the module receives data again, it does not report a new URC until all the received data have been retrieved with AT+QIRD from the buffer. 2. In transparent transmission mode, AT commands cannot be executed. If the socket connection is closed because of a network error or other errors, the module reports NO CARRIER and exits the transparent transmission mode. In this case, execute AT+QICLOSE to close the socket service. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 11 / 55 LPWA Module Series 2 TCP/IP AT Commands 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 2: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of a corresponding Write Command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 12 / 55 LPWA Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 2.3. Description of TCP/IP AT Commands 2.3.1. AT+QICSGP Configure Parameters of a TCP/IP Context This command configures the , , and other parameters of a TCP/IP context. AT+QICSGP Configure Parameters of a TCP/IP Context Test Command AT+QICSGP=? Response +QICSGP: (range of supported s),(range of supported s),,,,(range of supported s) OK Write Command Query/configure a specified context AT+QICSGP=[,,[,,< password>[,]]] Response If the optional parameters are omitted, query the current setting: +QICSGP: ,,,,< authentication> OK Maximum Response Time Characteristics If any of the optional parameters is specified, configure a specified context: OK Or ERROR 300 ms The command takes effect immediately (actually determined by network). The configuration is saved automatically. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 13 / 55 LPWA Module Series Parameter Integer type. Context ID. Range: 1–5. Integer type. Protocol type. 1 IPv4 2 IPv6 3 IPv4v6 String type. Access Point Name. String type. Username. String type. Password. Integer type. Authentication methods. 0 None 1 PAP 2 CHAP Example AT+QICSGP=1 +QICSGP: 1,'','','',0 OK AT+QICSGP=1,1,'CMNBIOT','','',1 OK //Query the configuration of context 1. //Configure context 1. China Mobile NB-IoT network APN: CMNBIOT. 2.3.2. AT+QICFG Configure Optional Parameters This command configures optional parameters. AT+QICFG Configure Optional Parameters Test Command AT+QICFG=? Response +QICFG: 'transpktsize',(range of supported s) +QICFG: 'transwaittm',(range of supported s) +QICFG: 'dataformat',(list of supported s),(list of supported s) +QICFG: 'viewmode',(list of supported s) +QICFG: 'recvind',(list of supported s) +QICFG: 'sack',(list of supported s) +QICFG: 'tcp/keepalive',(list of supported s),(range of supported s),(range of supported s),(range of supported >s) +QICFG: 'tcp/retranscfg',(range of supported s),(range of supported s) BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 14 / 55 LPWA Module Series Write Command Query/set the packet size for transparent transmission mode AT+QICFG='transpktsize'[,] OK Response If the optional parameter is omitted, query the current setting: +QICFG: 'transpktsize', OK Write Command Query/set the waiting time for transparent transmission mode AT+QICFG='transwaittm'[,] If the optional parameter is specified, set the packet size for transparent transmission mode: OK Or ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'transwaittm', OK If the optional parameter is specified, set the waiting time for transparent transmission mode: OK Or ERROR Write Command Response Query/set the format of the data to If the optional parameter is omitted, query the current setting: be sent and received (only for buffer +QICFG: 'dataformat',, mode) AT+QICFG='dataformat'[,,] If the optional parameter is specified, set the format of the data to be sent and received: OK Or ERROR Write Command Response Query/set the output format of If the optional parameter is omitted, query the current setting: received data (only for non- +QICFG: 'viewmode', transparent mode) AT+QICFG='viewmode'[,] If the optional parameter is specified, set the output format of received data: BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 15 / 55 LPWA Module Series OK Or ERROR Write Command Response Query/set the URC format in buffer If the optional parameter is omitted, query the current setting: access mode. +QICFG: 'recvind', AT+QICFG='recvind',[] OK Write Command Query/set whether to enable SACK option in TCP header. AT+QICFG='sack',[] If the optional parameter is specified, set the URC format in buffer access mode: OK Or ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'sack', OK If the optional parameter is specified, configure whether to enable SACK option in TCP header: OK Or ERROR Write Command Response Query/set whether to enable TCP If the optional parameters are omitted, query the current setting: keepalive feature and the relevant +QICFG: 'tcp/keepalive',,,, AT+QICFG='tcp/keepalive'[,[,,,]] If any of the optional parameter is specified, set whether to enable TCP keepalive feature and the relevant parameter values: OK Or ERROR Write Command Response Query/set the maximum interval If the optional parameters are omitted, query the current setting: and number of TCP +QICFG: 'tcp/retranscfg',, retransmissions AT+QICFG='tcp/retranscfg'[,,] If the optional parameters are specified, set the maximum interval BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 16 / 55 LPWA Module Series Maximum Response Time Characteristics and the number of TCP retransmissions: OK Or ERROR 300 ms The command takes effect immediately. The configuration is not saved. Parameter Integer type. Maximum length of the data packet to be sent. Range: 1–1460. Default value: 1024. Unit: byte. Integer type. In transparent transmission mode, if the length of data received from the port is less than the specified value of , after exceeding the time specified by , the data will be sent. Range: 0–20. Default value: 2. Unit: 100 ms. Integer type. Format of the data to be sent. 0 Text mode 1 Hex mode Integer type. Format of the data to be received. 0 Text mode 1 Hex mode Integer type. Output format of received data. 0 Output format of received data: data headerrndata. 1 Output format of received data: data header,data. Integer type. URC format. 0 URC without data length. URC format is +QIURC: 'recv',. 1 URC with data length. URC format is +QIURC: 'recv',,. Integer type. Whether to enable SACK option in TCP header. 0 Disable 1 Enable Integer type. Whether to enable TCP keepalive feature. When it is 0, , and should be ignored. 0 Disable 1 Enable Integer type. Default keepalive time. Range: 1–120. Unit: minute. Integer type. Interval between keepalive probes. Range: 25–100. Unit: second. Integer type. Maximum number of keepalive probes. Range: 3–10. Integer type. Maximum number of TCP retransmissions. Range: 3–20. Default value: 12. Integer type. Maximum interval between TCP retransmissions. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 17 / 55 LPWA Module Series Range: 5–1000. Default value: 600. Unit: 100 ms. NOTE The settings of AT+QICFG='tcp/retranscfg',, and AT+QICFG='tcp/kee palive',,,, take effect on all TCP sockets. 2.3.3. AT+QIACT Activate a PDP Context Before activating a PDP context with AT+QIACT, the context should be configured with AT+QICSGP. After activation, the IP address can be queried with AT+QIACT?. The range of is 1–5 and the module supports maximum three PDP contexts activated simultaneously under LTE Cat M1 and maximum two under LTE Cat NB2. Depending on the network, it may take max. 150 s to return OK or ERROR after executing AT+QIACT. Other AT commands can be executed only after the response is returned. AT+QIACT Activate a PDP Context Test Command AT+QIACT=? Response +QIACT: (range of supported s) Read command AT+QIACT? OK Response Return the list of the currently activated contexts and their IP addresses: +QIACT: 1,,[,] [... +QIACT: 5,,[,]] Write Command Activate a specified PDP context AT+QIACT= Maximum Response Time Characteristics OK Response OK Or ERROR 150 s, determined by the network. / Parameter Integer type. Context ID. Range: 1–5. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 18 / 55 LPWA Module Series Integer type. Context state. 0 Deactivated 1 Activated Integer type. Protocol type. 1 IPv4 2 IPv6 String type. Local IP address after the context is activated. 2.3.4. AT+QIDEACT Deactivate a PDP Context This command deactivates a specific context and closes all TCP/UDP connections set up in this context. Depending on the network, it may take max. 40 s to return OK or ERROR after executing AT+QIDEACT. Other AT commands can be executed only after the response is returned. AT+QIDEACT Deactivate a PDP Context Test Command AT+QIDEACT=? Response +QIDEACT: (range of supported s) Write Command AT+QIDEACT= Maximum Response Time Characteristics OK Response OK Or ERROR 40 s, determined by the network. / Parameter Integer type. Context ID. Range: 1–5. 2.3.5. AT+QIOPEN Open a Socket Service This command opens a socket service. The service type can be specified by . The data access mode (buffer access mode, direct push mode and transparent transmission mode) can be specified by . The response +QIOPEN: , indicates if the socket service has been opened successfully. 1. If is 'TCP LISTENER', the module works as a TCP server. After accepting a new TCP connection, the module automatically specifies a and reports the URC +QIURC: 'incoming',,,,. The range of is BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 19 / 55 LPWA Module Series 0–11. The type of this new incoming connection is 'TCP INCOMING' and the of 'TCP INCOMING' is the same as that of 'TCP LISTENER'. 2. If is 'UDP SERVICE', UDP data can be sent to or received from the remote IP via . ⚫ Send data: execute AT+QISEND=,,,. ⚫ Receive data in direct push mode: the module reports the URC +QIURC: 'recv',,,,. ⚫ Receive data in buffer access mode: the module reports the URC +QIURC: 'recv',[,], and then the received data can be retrieved with AT+QIRD=. 3. It is suggested to wait for 150 s for +QIOPEN: , to be outputted after executing the Write Command. If the response cannot be received in 150 s, use AT+QICLOSE to close the socket. AT+QIOPEN Open a Socket Service Test Command AT+QIOPEN=? Response +QIOPEN: (range of supported s),(range of supported s),'TCP/UDP/TCP LISTENER/UDP SERVICE','/',(range of supported s),(range of supported s),(range of supported s) OK Write Command AT+QIOPEN=,,,/,[,[,]] Response If in transparent transmission mode (=2) and the service is opened successfully: CONNECT If there is any error: ERROR If in buffer access mode (=0) or direct push mode (=1): OK Maximum Response Time Characteristics +QIOPEN: , is 0 when the service is opened successfully. In other cases, is not 0. 150 s, determined by the network. / BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 20 / 55 LPWA Module Series Parameter Integer type. Context ID. Range: 1–5. Integer type. Socket service index. Range: 0–11. String type. Socket service type. 'TCP' Start a TCP connection as a client 'UDP' Start a UDP connection as a client 'TCP LISTENER' Start a TCP server to listen for TCP incoming connections 'UDP SERVICE' Start a UDP service String type. If is 'TCP' or 'UDP', it indicates the IP address of remote server, such as '220.180.239.212'. If is 'TCP LISTENER' or 'UDP SERVICE', enter '127.0.0.1'. String type. Domain name address of the remote server. Integer type. Port number of the remote server. Range: 0–65535. If is 'TCP' or 'UDP', this parameter must be specified. Range: 1–65535. If is 'TCP LISTENER' or 'UDP SERVICE', specify this parameter as 0. Integer type. Local port number. Range: 0–65535. If is 'TCP LISTENER' or 'UDP SERVICE', this parameter must be specified. Range: 1–65535. If is 'TCP' or 'UDP', this parameter can be omitted and the default value is 0. The local port is assigned automatically if is 0. Otherwise, the local port is assigned as specified. Integer type. Data access mode of the socket service. 0 Buffer access mode 1 Direct push mode 2 Transparent transmission mode Integer type. Result code. See Chapter 4 for more information. NOTE 1. Only one socket service can be set to transparent transmission mode at a time. 2. If is 'TCP LISTENER', cannot be transparent transmission mode. When a remote client connects to the server, AT+QSWTMD can be used to switch the incoming connection to transparent transmission mode. 2.3.6. AT+QICLOSE Close a Socket Service The command closes a specified socket service. Depending on the network, it takes max. 10 s (default value, can be modified by ) to return OK or ERROR after executing AT+QICLOSE. Other AT commands can be executed only after the response is returned. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 21 / 55 LPWA Module Series AT+QICLOSE Close a Socket Service Test Command AT+QICLOSE=? Response +QICLOSE: (range of supported s),(range of supported s) Write Command AT+QICLOSE=>[,] OK Response If the socket service is closed successfully: OK Maximum Response Time Characteristics If the command failed to close the socket service: ERROR Determined by / Parameter Integer type. Socket service index. Range: 0–11. Integer type. Timeout value for the response to be outputted. If the FIN ACK of the other peer is not received within , the module will be forced to close the socket. Range: 0–65535. Default value: 10. Unit: second. 2.3.7. AT+QISTATE Query Socket Service Status The command queries the socket service status. If the is 0, it returns the status of all existing socket services in the specified context. If the is 1, it returns the status of a specified socket service. AT+QISTATE Query Socket Service Status Test Command AT+QISTATE=? Response OK Read/Execution Command AT+QISTATE? or AT+QISTATE Response Return the status of all existing connections: +QISTATE: ,,,,,,,,, […] OK BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 22 / 55 LPWA Module Series Write Command If is 0, query the connection status of a specified context AT+QISTATE=, Response Return the status of all existing connections in a specified context: +QISTATE: ,,,,,,,,, […] OK Write Command If is 1, query the connection status of a specified socket service AT+QISTATE=, Response +QISTATE: ,,,,,,,,, OK Maximum Response Time 300 ms Characteristics / Parameter Integer type. Query type. 0 Query connection status of all socket services in a specified context 1 Query connection status of a specified socket service Integer type. Context ID. Range: 1–5. Integer type. Socket service index. Range: 0–11. String type. Socket service type. 'TCP' Start a TCP connection as a client 'UDP' Start a UDP connection as a client 'TCP LISTENER' Start a TCP server to listen for TCP incoming connections 'TCP INCOMING' Start a TCP connection accepted by a TCP server 'UDP SERVICE' Start a UDP service String type. IP address. If is 'TCP' or 'UDP', it is the IP address of a remote server. If is 'TCP LISTENER' or 'UDP SERVICE', it is the local IP address. If is 'TCP INCOMING', it is the IP address of a remote client. Integer type. Remote port number. If is 'TCP' or 'UDP', it is the port of a remote server. If is 'TCP LISTENER' or 'UDP SERVICE', the port is invalid. If is 'TCP INCOMING', it is the port of a remote client. Integer type. Local port number. If is 0, then the local port is assigned automatically. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 23 / 55 LPWA Module Series Integer type. Socket service status. 0 'Initial': connection has not been established 1 'Opening': client is connecting or server is trying to listen 2 'Connected': client/incoming connection has been established 3 'Listening': server is listening 4 'Closing': connection is closing Integer type. Only valid when is 'TCP INCOMING'. represents the ID of the server that accepts the TCP incoming connection, and the value is the same as of 'TCP LISTENER'. Integer type. Data access mode. 0 Buffer access mode 1 Direct push mode 2 Transparent transmission mode String type. COM port of socket service. 'main' MAIN UART port 'aux' AUX UART port on BG770A-GL and Debug UART on BG95xA-GL 'emux' EMUX mode (see AT+QCFG='emux/urcport' in document [2]) 'usb' USB mode (see AT+QCFG='usb/urcport' in document [2]) (USB mode not supported currently) 2.3.8. AT+QISEND Send Data In buffer access mode (=0) or direct push mode (=1), the data can be sent with AT+QISEND. If the data have been sent to the module successfully, SEND OK is returned, otherwise SEND FAIL or ERROR is returned. ⚫ SEND FAIL indicates that the sending buffer is full. In this case, data can be resent. ⚫ ERROR indicates an error in the data sending process. In this case, wait for some time before you resend the data. ⚫ SEND OK means that the data have been sent to the peer, but it does not mean that they have reached the peer successfully. You can query whether the data have reached the peer with AT+QISEND=,0. AT+QISEND Send Data Test Command AT+QISEND=? Response +QISEND: (range of supported s),(range of supported s) OK Write Command Send variable-length data when is 'TCP', 'UDP' or 'TCP INCOMING' Response > After the response >, input the data to be sent. Tap Ctrl+Z to send the data, and tap Esc to cancel the sending operation BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 24 / 55 LPWA Module Series AT+QISEND= If the connection is established and the data are sent successfully: SEND OK If the connection is established but the sending buffer is full: SEND FAIL If the connection is not established, abnormally closed, or any parameter is incorrect: ERROR Write Command Send fixed-length data when is 'TCP', 'UDP' or 'TCP INCOMING' AT+QISEND=, Response > After the response >, input the data until the data length equals If the connection is established and the data are sent successfully: SEND OK If the connection is established but the sending buffer is full: SEND FAIL If the connection is not established, abnormally closed, or any parameter is incorrect: ERROR Write Command When is 'UDP SERVICE' AT+QISEND=,,, Response Send fixed length data to the specified remote IP address and remote port. The must be 'UDP SERVICE'. > After response >, type the data until the data length equals If the connection is established and the data are sent successfully: SEND OK If the connection is established but the sending buffer is full: SEND FAIL If the connection is not established, abnormally closed, or any parameter is incorrect: ERROR Write Command Response When is 0, query the If the specified exists: BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 25 / 55 sent data AT+QISEND=,0 Maximum Response Time Characteristics LPWA Module Series +QISEND: ,, OK If the specified does not exist, or there is any other error: ERROR 120 s, determined by network. / Parameter Integer type. Socket service index. Range: 0–11. Integer type. Length of the data to be sent. Range: 0–1460. String type. Remote IP address (must be dot format). Valid only when is 'UDP SERVICE'. Integer type. Remote port. Valid only when is 'UDP SERVICE'. Integer type. Total length of sent data. Unit: byte. Integer type. Total length of acknowledged data. Unit: byte. Integer type. Total length of unacknowledged data. Unit: byte. 2.3.9. AT+QIRD Retrieve the Received TCP/IP Data In buffer access mode, after receiving data, the module buffers them and reports +QIURC: 'recv',[,],, then the data can be retrieved with AT+QIRD. Please note that if the buffer is not empty, and the module receives data again, it does not report a new URC until all received data have been retrieved with AT+QIRD from the buffer. AT+QIRD Retrieve the Received TCP/IP Data Test Command AT+QIRD=? Response +QIRD: (range of supported s),(range of supported s) OK Write Command When is 'TCP', 'UDP' or 'TCP INCOMING' AT+QIRD=[,<read_length Response If the specified connection has received the data: +QIRD: BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 26 / 55 LPWA Module Series >] OK If there are no data: +QIRD: 0 OK Write Command When is 'UDP SERVICE' AT+QIRD= If the connection does not exist: ERROR Response If data exist: +QIRD: ,, OK If there are no data: +QIRD: 0 OK If the connection does not exist: ERROR Write Command When is 0, query the retrieved data length AT+QIRD=,0 Response If the specified connection exists: +QIRD: ,, OK Maximum Response Time Characteristics If there is any error: ERROR 120 s, determined by network. / Parameter Integer type. Socket service index. Range: 0–11. Integer type. Maximum length of the data to be retrieved. Range: 0–1500. Default value: 1500. Unit: byte. Integer type. Length of actually retrieved data. Unit: byte. String type. Remote IP address. Valid only when is 'UDP BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 27 / 55 LPWA Module Series SERVICE'. Integer type. Remote port number. Valid only when is 'UDP SERVICE'. String type. Retrieved data. Integer type. Total length of received data. Unit: byte. Integer type. Length of the data that have been retrieved. Unit: byte. Integer type. Length of the data that have not been retrieved. Unit: byte. 2.3.10. AT+QPING Ping a Remote Host This command tests the reachability of a host on an Internet protocol network. Before using the ping utility, the host should activate the context of the corresponding with AT+QIACT. The command returns the result within . AT+QPING Ping a Remote Host Test Command AT+QPING=? Response +QPING: (range of supported s),,(range of supported s),(range of supported s) OK Write Command Response AT+QPING=,[, If a remote host is pinged successfully: [,]] OK +QPING: [,,,,] […] +QPING: [,,,,,,] Maximum Response Time Characteristics If there is any error: ERROR 300 s / Parameter Integer type. Context ID. Range: 1–5. String type. Host address. It is a domain name or a dotted decimal IP address. Integer type. Maximum time to wait for the response of each ping request. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 28 / 55 LPWA Module Series Range: 1–255. Default value: 4. Unit: second. Integer type. Maximum number of ping requests. Range: 1–10. Default value: 4. Integer type. Result of each ping request. 0 Received the ping response from the host. In this case, it is followed by ,,,,. Others See Chapter 4 for specific result codes. String type. IP address of the remote host in dotted-decimal notation. Integer type. Length of each sent ping request. Unit: byte. Integer type. Waiting time for the response to the ping request. Unit: ms. Integer type. Time to live value of the response packet for the ping request. Integer type. Final result of the command. 0 Pinged successfully. It succeeded in activating the context and finding the host. In this case, it is followed by ,,,,,,. Others See Chapter 4 for specific result codes. Integer type. Total number of sent ping requests. Integer type. Total number of the ping requests that have received responses. Integer type. Total number of timed out ping requests. Integer type. Minimum response time. Unit: ms. Integer type. Maximum response time. Unit: ms. Integer type. Average response time. Unit: ms. 2.3.11. AT+QIDNSGIP Get IP Address by Domain Name This command gets an IP address by domain name. Before querying the DNS, the host should activate the context of corresponding with AT+QIACT. .AT+QIDNSGIP Get IP Address by Domain Name Test Command AT+QIDNSGIP=? Response +QIDNSGIP: (range of supported s), OK Write Command Response AT+QIDNSGIP=, +QIURC: 'dnsgip',,, [... +QIURC: 'dnsgip',] Maximum Response Time If there is any error: ERROR 60 s, determined by the network. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 29 / 55 LPWA Module Series Characteristics / Parameter Integer type. Context ID. Range: 1–5 String type. Domain name. Integer type. Result code. See Chapter 4 for more information. Integer type. Number of IP addresses corresponding to the . Integer type. Time to live of the DNS. Unit: second. String type. IP address of . 2.3.12. AT+QISENDEX Send Hex String Data This command sends hex string data and cannot be applied to 'UDP SERVICE' and 'TCP LISTENER' sockets. AT+QISENDEX Send Hex String Data Test Command AT+QISENDEX=? Response +QISENDEX: (range of supported s),, (range of supported s) OK Write Command AT+QISENDEX=,< hex_string>[,] Response If the hex string is sent successfully: SEND OK If the sending buffer is full: SEND FAIL Maximum Response Time Characteristics If the connection does not exist: ERROR 120 s, determined by network. / Parameter * Integer type. Socket service index. Range: 0–11. String type. Hex string data. Maximum length: 512 bytes. Integer type. RAI (Release Assistance Indication) information. 0 No RAI information available. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 30 / 55 LPWA Module Series 1 No further uplink or downlink data transmission. 2 Only a single downlink data transmission and no further uplink data transmission. NOTE 1. RAI (Release Assistance Indication) is introduced in 3GPP Release 14 and it is primarily a MAC layer feature. 2. The RAI feature is only applicable to NB-IoT RAT. This feature allows tracking the predictable nature of data traffic and requests for connection release when there are no additional data to be sent. It is essentially a ‘fast dormancy’ feature to save UE battery power. 2.3.13. AT+QISWTMD Switch Data Access Mode This command switches the data access mode among buffer access mode, direct push mode and transparent transmission mode. When starting a socket service, the data access mode can be specified via the of AT+QIOPEN. After opening a socket, the data access mode can be changed with AT+QISWTMD. AT+QISWTMD Switch Data Access Mode Test Command AT+QISWTMD=? Response +QISWTMD: (range of supported s),(range of supported s) OK Write Command AT+QISWTMD=, Response If is 0 or 1, and data access mode is switched successfully: OK If is 2 and data access mode is switched successfully, the module enters the intended data mode (i.e., transparent transmission mode): CONNECT Maximum Response Time Characteristics If there is any error: ERROR 300 ms / BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 31 / 55 Parameter LPWA Module Series Integer type. Socket service index. Range: 0–11. Integer type. Data access modes of the connection. 0 Buffer access mode 1 Direct push mode 2 Transparent transmission mode 2.3.14. AT+QNTP Synchronize Local Time with NTP Server This command synchronizes the local time with the Universal Time Coordinated (UTC) through the NTP server. Before time synchronization, the host should activate the context corresponding to with AT+QIACT. AT+QNTP Synchronize Local Time with NTP Server Test command AT+QNTP=? Response +QNTP: (range of supported s),,(range of supported s),(list of supported s) Read Command AT+QNTP? OK Response If in the process of local time synchronization: +QNTP: , Write command AT+QNTP=, [,[,]] OK Response If the local time is synchronized with NTP server successfully: OK +QNTP: , Maximum Response Time Characteristics If there is any error: ERROR 125 s, determined by the network. The command takes effect immediately (actually determined by network). The configuration is not saved. Parameter Integer type. Context ID. Range: 1–5. String type. NTP server address. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 32 / 55 LPWA Module Series Integer type. NTP server port number. Range: 1–65535. Default value: 123. Integer type. Whether to automatically set synchronized time as local time. 0 Not set 1 Set Integer type. Result code. See Chapter 4 for more information. String type. Time synchronized with NTP server. The format is 'YYYY/MM/DD,hh:mm:sszz'. Range of 'zz': -48 to 56. 2.3.15. AT+QIDNSCFG Configure Address of DNS Server Before setting the DNS server address, the host must activate the context of corresponding with AT+QIACT. AT+QIDNSCFG Configure Address of DNS Server Test Command AT+QIDNSCFG=? Response +QIDNSCFG: (range of supported s),, Write Command AT+QIDNSCFG=[,[,]] OK Response If the optional parameters are omitted, query the current DNS server addresses of a specified PDP context: +QIDNSCFG: ,, OK Maximum Response Time Characteristics If any of the parameters is specified, configure the primary and secondary DNS server addresses of a specified PDP context: OK Or ERROR 300 ms The command takes effect immediately. The configurations will not be saved. Parameter Integer type. PDP context ID. Range: 1–5. String type. Primary DNS server address. String type. Secondary DNS server address. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 33 / 55 LPWA Module Series 2.3.16. AT+QISDE Control Whether to Echo the Data for AT+QISEND This command controls whether to echo the data for AT+QISEND. AT+QISDE Control Whether to Echo the Data for AT+QISEND Test Command AT+QISDE=? Response +QISDE: (list of supported s) Read Command AT+QISDE? OK Response +QISDE: Write Command AT+QISDE= Maximum Response Time Characteristics OK Response OK Or ERROR 300 ms The command takes effect immediately. The configuration is not saved. Parameter Integer type. Whether to echo the data for AT+QISEND. 0 Do not echo the data 1 Echo the data 2.3.17. AT+QIGETERROR Query the Last Result Code If is returned after executing TCP/IP commands, the detailed information about a result code can be queried with AT+QIGETERROR. Please note that AT+QIGETERROR just returns the result code of the last TCP/IP AT command. AT+QIGETERROR Query the Last Result Code Test Command AT+QIGETERROR=? Execution Command AT+QIGETERROR Response OK Response +QIGETERROR: , OK BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 34 / 55 LPWA Module Series Maximum Response Time Characteristics 300 ms / Parameter Integer type. Result code. See Chapter 4 for more information. String type. Result code description. See Chapter 4 for more information. 2.4. Description of URCs The URC of TCP/IP AT commands will be reported to the host in the format that begins with +QIURC:. It contains the reports about incoming data, closed connection and incoming connection and etc. Actually, there is both before and after URC, but is intentionally not presented. 2.4.1. +QIURC: 'closed' Indicate Connection Closed When the TCP socket service is closed by a remote peer or due to a network error, the URC is outputted, and the status of the socket service is 'closing' (=4). AT+QICLOSE= can be used to change the to 'initial'. +QIURC: 'closed' Indicate Connection Closed +QIURC: 'closed', Socket service connection is closed. Parameter Integer type. Socket service index. Range: 0–11. 2.4.2. +QIURC: 'recv' Indicate Incoming Data In buffer access mode or direct push mode, after receiving data, the module reports a URC to the host. In buffer access mode, after receiving data, the module reports +QIURC: 'recv',[,] to notify the host. The host can then retrieve data with AT+QIRD. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 35 / 55 LPWA Module Series ⚫ NOTE If the buffer is not empty, and the module receives data again, it does not report a new URC until all the received data have been retrieved with AT+QIRD from the buffer. In direct push mode, the received data are outputted to COM port directly. +QIURC: 'recv' Indicate Incoming Data +QIURC: 'recv',[,] retrieve data via AT+QIRD. +QIURC: 'recv',, is 'TCP', 'UDP' or 'TCP INCOMING'. +QIURC: 'recv',,,,<remote_p is 'UDP SERVICE'. ort> Parameter Integer type. Socket service index. Range: 0–11. Integer type. Data length. Unit: byte. Integer type. Length of actually received data. String type. Remote IP address. Integer type. Remote port number. String type. Received data. 2.4.3. +QIURC: 'incoming full' Indicate Incoming Connection Reaches the Limit If the number of incoming connections reaches the limit, or no socket system resources can be allocated, the module reports +QIURC: 'incoming full' for the new incoming connection request. +QIURC: 'incoming full' Indicate Incoming Connection Reaches the Limit +QIURC: 'incoming full' Indicates that the number of incoming connections has reached the limit. 2.4.4. +QIURC: 'incoming' Indicate Incoming Connection If is 'TCP LISTENER', when a remote client connects to this server, the host automatically assigns a free to the new connection, and the range of is 0–11. In this case, the module reports +QIURC: 'incoming'. The of the new connection will be 'TCP INCOMING', and the will be buffer access mode. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 36 / 55 LPWA Module Series +QIURC: 'incoming' Indicate Incoming Connection +QIURC: 'incoming',,<s When the new incoming connection is accepted by , erverID>,, the allocated , and are informed by this URC. Parameter Integer type. Index of the socket service assigned to the incoming connection, which is automatically specified by the module. Range: 0–11. Integer type. ID of the listening socket whose is 'TCP LISTENER' and which accepts the incoming . String type. Remote IP address of the incoming . Integer type. Remote port number of the incoming . 2.4.5. +QIURC: 'pdpdeact' Indicate PDP Deactivation PDP context may be deactivated by the network. The module reports this URC to the host about PDP deactivation. In this case, the host must execute AT+QIDEACT to deactivate the context and reset all connections. +QIURC: 'pdpdeact' Indicate PDP Deactivation +QIURC: 'pdpdeact', context is deactivated. Parameter Integer type. Context ID. Range: 1–5. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 37 / 55 LPWA Module Series 3 Examples 3.1. Configure and Activate a Context 3.1.1. Configure a Context AT+QICSGP=1,1,'CMNBIOT','','',1 OK //Configure context 1. China Mobile NB-IoT network APN: CMNBIOT. 3.1.2. Activate a Context AT+QIACT=1 OK AT+QIACT? +QIACT: 1,1,1,'10.7.157.1' OK //Activate context 1. Depending on the network, the maximum response time is 150 s. //Activated the context successfully. //Query the context state, protocol type and IP address of context 1. 3.1.3. Deactivate a Context AT+QIDEACT=1 OK //Deactivate context 1. //Deactivated the context successfully. Depending on the network, the maximum response time is 40 s. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 38 / 55 LPWA Module Series 3.2. TCP Client Works in Buffer Access Mode under IPv4 3.2.1. Set up a TCP Client Connection and Enter Buffer Access Mode //Context is 1 and is 0. Before using AT+QIOPEN, the host should activate the context with AT+QIACT. AT+QIOPEN=1,0,'TCP','220.180.239.212',8009,0,0 OK +QIOPEN: 0,0 //TCP client connected successfully. It is suggested to wait for 150 s for the URC +QIOPEN: ,. If the URC cannot be received in 150 s, the host could use AT+QICLOSE to close the socket. AT+QISTATE=1,0 //Query connection status of socket service 1. +QISTATE: 0,'TCP','220.180.239.212',8009,65514,2,1,0,0,'main' OK 3.2.2. Send Data in Buffer Access Mode AT+QISEND=0 >test1 SEND OK AT+QISEND=0,4 >test SEND OK AT+QISEND=0,0 +QISEND: 9,9,0 //Send variable-length data. //SEND OK does not mean the data have been sent to the server successfully. The host can query whether the data have reached the server with AT+QISEND=0,0. //Send fixed-length data and the data length is 4 bytes. //Query the length of sent data, acknowledged data and unacknowledged data. //A total of 9 bytes of data have been sent, and 9 bytes of data have been acknowledged by the server. OK AT+QISENDEX=0,'3132333435' SEND OK AT+QISEND=0,0 //Send Hex string data. //Query the length of sent data, acknowledged data and unacknowledged data. +QISEND: 14,14,0 OK BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 39 / 55 LPWA Module Series 3.2.3. Retrieve Data from Remote Server in Buffer Access Mode +QIURC: 'recv',0 AT+QIRD=0,1500 +QIRD: 5 test1 //The 0 has received data. //Retrieve the data, and the maximum length of data to be retrieved is 1500 bytes. //The length of actually retrieved data is 5 bytes. OK AT+QIRD=0,1500 +QIRD: 0 //No data in buffer. OK AT+QIRD=0,0 +QIRD: 5,5,0 //Query the total length of received data, including read and unread data. OK 3.2.4. Close a Connection AT+QICLOSE=0 OK //Close a connection whose is 0. Depending on the network, the maximum response time is 10 s by default. 3.3. TCP Client Works in Buffer Access Mode under IPv6 3.3.1. Set up a TCP Client Connection and Enter Buffer Access Mode //Context is 1 and is 0. Before using AT+QIOPEN, the host should activate the context with AT+QIACT. AT+QIOPEN=1,0,'TCP','2001:468:2100:1:0:0:0:0',5001,0,0 OK +QIOPEN: 0,0 //TCP client is connected successfully. It is suggested to wait for 150 s for the URC +QIOPEN: ,. If the URC cannot be received in 150 s, the host can use AT+QICLOSE to close the socket. AT+QISTATE=1,0 //Query the connection status of socket service 1. +QISTATE: 0,'TCP','2001:468:2100:1:0:0:0:0',5001,11921,2,1,0,0,'main' OK BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 40 / 55 LPWA Module Series 3.3.2. Send Data in Buffer Access Mode AT+QISEND=0 >test1 SEND OK AT+QISEND=0,4 >test SEND OK AT+QISEND=0,0 +QISEND: 9,9,0 //Send variable-length data. //SEND OK does not mean the data have been sent to the server successfully. The host can query whether the data have reached the server with AT+QISEND=0,0. //Send fixed-length data and the data length is 4 bytes. //Query the length of sent data, acknowledged data and unacknowledged data. //A total of 9 bytes of data have been sent, and the 9 bytes of data have been acknowledged by the server. OK AT+QISENDEX=0,'3132333435' //Send Hex string data. SEND OK AT+QISEND=0,0 //Query the length of sent data, acknowledged data and unacknowledged data. +QISEND: 14,14,0 OK 3.3.3. Receive Data from Remote Server in Buffer Access Mode +QIURC: 'recv',0 AT+QIRD=0,1500 +QIRD: 5 test1 //The 0 has received data. //Retrieve the data, and the maximum length of data to be retrieved is 1500 bytes. //The length of actually retrieved data is 5 bytes. OK AT+QIRD=0,1500 +QIRD: 0 //No data in buffer. OK AT+QIRD=0,0 +QIRD: 5,5,0 //Query the total length of received data, including read and unread data. OK BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 41 / 55 LPWA Module Series 3.3.4. Close a Connection AT+QICLOSE=0 OK //Close a connection whose is 0. Depending on the network, the maximum response time is 10 s by default. 3.4. TCP Client Works in Transparent Transmission Mode 3.4.1. Set up a TCP Client Connection and Enter Transparent Transmission Mode //Context is 1 and is 0. Before using AT+QIOPEN, the host should activate the context with AT+QIACT. AT+QIOPEN=1,0,'TCP','220.180.239.212',8009,0,2 CONNECT //TCP client connected successfully. It is suggested to wait for 150 s for the URC CONNECT. If the URC cannot be received in 150 s, the host could use AT+QICLOSE to close the socket. 3.4.2. Send Data in Transparent Transmission Mode 3.4.3. Retrieve Data from Remote Server in Transparent Transmission Mode Test 1 3.4.4. Close a TCP Client //All data received from the Internet are outputted via the COM port directly. AT+QICLOSE=0 OK //After using +++ to exit the transparent transmission mode, the host could use AT+QICLOSE to close the TCP link. Depending on the network, the maximum response time is 10 s by default. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 42 / 55 LPWA Module Series 3.5. TCP Client Works in Direct Push Mode 3.5.1. Set up a TCP Client Connection and Enter Direct Push Mode //Context is 1 and is 0. Before using AT+QIOPEN, the host should activate the context via AT+QIACT. AT+QIOPEN=1,0,'TCP','220.180.239.212',8009,0,1 OK +QIOPEN: 0,0 //TCP client connected successfully. It is suggested to wait for 150 s for the URC +QIOPEN: ,. If the URC cannot be received in 150 s, the host could use AT+QICLOSE to close the socket. AT+QISTATE=1,0 //Query the connection state of socket service 0. +QISTATE: 0,'TCP','220.180.239.212',8009,65344,2,1,0,1,'main' OK 3.5.2. Send Data in Direct Push Mode AT+QISEND=0 >test1 SEND OK AT+QISEND=0,5 >test2 SEND OK AT+QISEND=0,0 +QISEND: 10,10,0 OK //Send variable-length data. //SEND OK does not mean the data have been sent to the server successfully. The host can query whether the data have reached the server with AT+QISEND=0,0. //Send fixed-length data and the data length is 5 bytes. //Query the length of sent data, acknowledged data and unacknowledged data. //A total of 10 bytes of data have been sent, and all 10 bytes have been acknowledged. 3.5.3. Retrieve Data from Remote Server in Direct Push Mode +QIURC: 'recv',0,4 test //Retrieve data from remote server. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 43 / 55 LPWA Module Series 3.5.4. Close a TCP Client AT+QICLOSE=0 OK //Close the connection whose is 0. Depending on the network, the maximum response time is 10 s by default. 3.6. TCP Server Works in Buffer Access Mode under IPv4 3.6.1. Start a TCP Server //Context is 1 and is 1. Before using AT+QIOPEN, the host should activate the context with AT+QIACT. AT+QIOPEN=1,1,'TCP LISTENER','127.0.0.1',0,2020,0 OK +QIOPEN: 1,0 //TCP server is opened successfully. AT+QISTATE=0,1 //Query the connection status of context 1. +QISTATE: 1,'TCP LISTENER','10.7.157.1',0,2020,3,1,1,0,'main' OK 3.6.2. Accept TCP Incoming Connection +QIURC: 'incoming',11,1,'172.31.242.222',54091 //A new TCP connection is accepted. The is 'TCP incoming', and is 11. 3.6.3. Retrieve Data from Incoming Connection +QIURC: 'recv',11 AT+QIRD=11,1500 +QIRD: 4 test OK AT+QIRD=11,1500 +QIRD: 0 OK //Received data from remote incoming connection. //Retrieve the data received from incoming connection. //Length of actually retrieved data is 4 bytes. //No data in buffer. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 44 / 55 AT+QIRD=11,0 +QIRD: 4,4,0 OK LPWA Module Series //Query the total length of received data, including read and unread data. 3.6.4. Close a TCP Server AT+QICLOSE=11 OK AT+QICLOSE=1 OK //Close the incoming connection. Depending on the network, the maximum response time is 10 s by default. //Close the listening TCP server. 3.7. TCP Server Works in Buffer Access Mode under IPv6 3.7.1. Start a TCP Server //Context is 1 and is 1. Before using AT+QIOPEN, the host should activate the context with AT+QIACT. AT+QIOPEN=1,1,'TCP LISTENER','0:0:0:0:0:0:0:1',0,12345,0 OK +QIOPEN: 1,0 //TCP server is opened successfully. AT+QISTATE=0,1 //Query the connection status of context 1. +QISTATE: 1,'TCP LISTENER','2001:468:2100:1:2001:468:2100:1',0,12345,3,1,1,0,'main' OK 3.7.2. Accept TCP Incoming Connection +QIURC: 'incoming',11,1,'2001:468:2100:1:0:0:0:0',54091 //A new TCP connection is accepted. The is 'TCP incoming', and is 11. 3.7.3. Retrieve Data from Incoming Connection +QIURC: 'recv',11 //Received data from remote incoming connection. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 45 / 55 AT+QIRD=11,1500 +QIRD: 4 test OK AT+QIRD=11,1500 +QIRD: 0 OK AT+QIRD=11,0 +QIRD: 4,4,0 OK LPWA Module Series //Retrieve the data received from incoming connection. //Length of actually retrieved data is 4 bytes. //No data in buffer. //Query the total length of received data, including read and unread data. 3.7.4. Switch Incoming Connection to Transparent Transmission Mode AT+QSWTMD=11,2 CONNECT 1234567890 +++ OK //Switch the incoming connection whose socket service index is 11 to transparent transmission mode. //Send data directly. //Exit transparent transmission mode. 3.7.5. Close a TCP Server AT+QICLOSE=11 OK AT+QICLOSE=1 OK //Close the incoming connection. Depending on the network, the maximum response time is 10 s by default. //Close the listening TCP server. 3.8. UDP Service under IPv4 3.8.1. Start a UDP Service //Start a UDP service whose is 2 and is 1. Before using AT+QIOPEN, the host should activate the context with AT+QIACT. AT+QIOPEN=1,2,'UDP SERVICE','127.0.0.1',0,3030,0 OK BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 46 / 55 LPWA Module Series +QIOPEN: 2,0 //UDP service is opened successfully. AT+QISTATE=0,1 //Query the connection status of context 1. +QISTATE: 2,'UDP SERVICE','10.7.157.1',0,3030,2,1,2,0,'main' OK 3.8.2. Send UDP Data to Remote Client AT+QISEND=2,10,'10.7.89.10',6969 >1234567890 SEND OK //Send 10-byte long data to a remote client whose IP is 10.7.89.10 and the remote port is 6969. 3.8.3. Retrieve Data from Remote Client +QIURC: 'recv',2 AT+QIRD=2 +QIRD: 4,'10.7.76.34',7687 AAAA //Data received from the remote client. //Retrieve UDP data. One whole UDP packet will be outputted. There is no need to specify the read length. //The retrieved data length is 4 bytes. The remote IP address is 10.7.76.34 and the remote port is 7687. OK AT+QIRD=2 +QIRD: 0 //Retrieve data. //No data in buffer. OK 3.8.4. Close a UDP Service AT+QICLOSE=2 OK //Close the service. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 47 / 55 LPWA Module Series 3.9. UDP Service under IPv6 3.9.1. Start a UDP Service //Start a UDP service whose is 2 and is 1. Before using AT+QIOPEN, the host should activate the context with AT+QIACT. AT+QIOPEN=1,2,'UDP SERVICE','0:0:0:0:0:0:0:1',0,12345,0 OK +QIOPEN: 2,0 //UDP service is opened successfully. AT+QISTATE=0,1 //Query the connection status of context 1. +QISTATE: 2,'UDP SERVICE','2001:468:2100:1:2001:468:2100:1',0,12345,2,1,2,0,'main' OK 3.9.2. Send UDP Data to Remote Client AT+QISEND=2,10,'2001:468:2100:1:0:0:0:0',5001 >1234567890 SEND OK //Send 10 bytes of data to a remote client whose IP is 2001:468:2100:1:0:0:0:0 and the port is 5001. 3.9.3. Retrieve Data from Remote Client +QIURC: 'recv',2 AT+QIRD=2 +QIRD: 4,'2001:468:2100:1:0:0:0:0',5001 AAAA //Received data from the remote client. //Retrieve UDP data. One whole UDP packet will be outputted. There is no need to specify the read length. //The retrieved data length is 4 bytes. The IP address of the remote client is 2001:468:2100:1:0:0:0:0 and the port is 5001. OK AT+QIRD=2 +QIRD: 0 //Retrieve data. //No data in buffer. OK BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 48 / 55 3.9.4. Close a UDP Service AT+QICLOSE=2 OK LPWA Module Series //Close the service. 3.10. UDP Client with RAI Feature* 3.10.1. Start a UDP Client //Start a UDP client whose is 0 and is 1. Before using AT+QIOPEN, the host should activate the context with AT+QIACT. AT+QIOPEN=1,0,'UDP','220.180.239.212',8009 OK 3.10.2. Send UDP Data with RAI Information* AT+QCSCON=1 OK AT+QISENDEX=0,'313233',0 SEND OK //18:48:14:649 +QCSCON: 1,1 //18:48:35:790 +QCSCON: 1,0 AT+QISENDEX=0,'313233',1 SEND OK //18:51:59:905 +QCSCON: 1,1 //18:52:01:135 +QCSCON: 1,0 AT+QISENDEX=0,'313233',2 SEND OK //19:00:28:037 +QCSCON: 1,1 //Enable RRC state reported via URC. //Send '123' without RAI information. //RRC connection set up successfully. //After 20 s, RRC connection is released. //Send '123' and release RRC connection right away. //RRC connection set up successfully. //Within 1 s, RRC connection is released. //Send '123' and release RRC connection after receiving a packet of downlink data. //RRC connection set up successfully. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 49 / 55 //19:00:35:115 +QIURC: 'recv',0 //19:00:35:264 +QCSCON: 1,0 3.10.3. Close a UDP Client AT+QICLOSE=0 OK LPWA Module Series //Receive a packet of downlink data from peer. //After receiving downlink data, RRC state became idle. //Close the client. 3.11. PING 3.11.1. PING under IPv4 AT+QPING=1,'www.baidu.com' OK +QPING: 0,'61.135.169.125',32,192,255 +QPING: 0,'61.135.169.125',32,240,255 +QPING: 0,'61.135.169.125',32,241,255 +QPING: 0,'61.135.169.125',32,479,255 +QPING: 0,4,4,0,192,479,287 //Ping www.baidu.com in context 1. Before pinging the destination IP address, the host should activate the context with AT+QIACT. 3.11.2. PING under IPv6 AT+QPING=1,'2001:468:2100:1:0:0:0:0' OK //Ping 2001:468:2100:1:0:0:0:0 in context 1. Before pinging the destination IP address, the host should activate the context with AT+QIACT first. BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 50 / 55 +QPING: 0,'2001:468:2100:1:0:0:0:0',32,58,255 +QPING: 0,'2001:468:2100:1:0:0:0:0',32,49,255 +QPING: 0,'2001:468:2100:1:0:0:0:0',32,39,255 +QPING: 0,'2001:468:2100:1:0:0:0:0',32,40,255 +QPING: 0,4,4,0,39,58,46 LPWA Module Series 3.12. Synchronize Local Time AT+QNTP=1,'202.120.2.101',123 OK +QNTP: 0,'2013/08/19,11:10:10+32' AT+CCLK? +CCLK: '13/08/19,11:10:57+32' OK //Synchronize local time with NTP server '202.120.2.101:123'. Before synchronizing the time, the host should activate the context with AT+QIACT. 3.13. Getting the Last Error Code AT+QIOPEN=1,'TCP','220.180.239.212',8009,0,1 ERROR AT+QIGETERROR +QIGETERROR: 552,invalid parameters //Send AT+QIOPEN with missing . OK BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 51 / 55 LPWA Module Series 4 Summary of Result Codes If is returned after executing TCP/IP AT commands, the detailed information about errors can be queried with AT+QIGETERROR. Please note that AT+QIGETERROR just returns the result code of the last TCP/IP AT command. Table 3: Summary of Result Codes 0 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 operate successfully unknown error operation blocked invalid parameters Memory allocation failed create socket failed operation not supported socket bind failed socket listen failed socket write failed socket read failed socket accept failed Activate pdp context failed Deactivate pdp context failed socket identity has been used dns busy BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 52 / 55 565 dns failed 566 socket connect failed 567 connection reset 568 system busy 569 operation timeout 570 pdp context deactivated 571 user cancel send 572 operation not allowed 573 port busy 574 pdp has been actived LPWA Module Series BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 53 / 55 LPWA Module Series 5 Appendix References Table 4: Related Documents Document Name [1] Quectel_BG770A-GL&BG95xA-GL_AT_Commands_Manual [2] Quectel_BG770A-GL&BG95xA-GL_QCFG_AT_Commands_Manual Table 5: Terms and Abbreviations Abbreviation 3GPP ACK APN CHAP DNS DTR FIN ID IP IPv4 IPv6 LTE NB-IoT NTP NVM PAP Description 3rd Generation Partnership Project Acknowledge Access Point Name Challenge Handshake Authentication Protocol Domain Name System Data Terminal Ready Finish Identifier Internet Protocol Internet Protocol version 4 Internet Protocol version 6 Long-Term Evolution Narrowband Internet of Things Network Time Protocol Non-Volatile Memory Password Authentication Protocol l BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 54 / 55 PDP PPP SACK TCP UART UDP URC USB UTC Packet Data Protocol Point-to-Point Protocol Selective Acknowledgment Transmission Control Protocol Universal Asynchronous Receiver & Transmitter User Datagram Protocol Unsolicited Result Code Universal Serial Bus Coordinated Universal Time LPWA Module Series BG770A-GL&BG95xA-GL_TCP/IP_Application_Note 55 / 55
486.98 KB
EG060V-EA USBnet Call Application Note LTE-A Module Series Version: 1.0 Date: 2021-12-29 Status: Released LTE-A Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. EG060V-EA_USBnet_Call_Application_Note 1 / 21 LTE-A Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2021. All rights reserved. EG060V-EA_USBnet_Call_Application_Note 2 / 21 LTE-A Module Series About the Document Revision History Version Date - 2021-11-15 1.0 2021-12-29 Author Paddy LI Paddy LI Description Creation of the document First official release EG060V-EA_USBnet_Call_Application_Note 3 / 21 LTE-A Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 2 USBnet Call Process .......................................................................................................................... 8 3 USBnet Call Description................................................................................................................... 10 3.1. Configure USBnet .................................................................................................................... 10 3.1.1. Configure Call Method .................................................................................................. 10 3.1.1.1. Configure Call Method in Windows.................................................................... 10 3.1.1.2. Configure Call Method in Linux .......................................................................... 10 3.1.2. Configure Call Mode ..................................................................................................... 10 3.2. Make Call ..................................................................................................................................11 3.3. Call Result.................................................................................................................................11 3.3.1. Call Result in Windows ..................................................................................................11 3.3.2. Call Result in Linux ....................................................................................................... 13 4 AT Command..................................................................................................................................... 14 4.1. AT Command Introduction ....................................................................................................... 14 4.1.1. Definitions...................................................................................................................... 14 4.1.2. AT Command Syntax .................................................................................................... 14 4.2. Declaration of AT Command Examples ................................................................................... 15 4.3. AT Command Description ........................................................................................................ 15 4.3.1. AT+QCFG Extended Configuration............................................................................ 15 4.3.1.1. AT+QCFG='usbnet' Configure Call Method ................................................... 15 4.3.1.2. AT+QCFG='nat' Configure Call Mode ............................................................ 16 4.3.2. AT+QICSGP Configure PDP Context......................................................................... 17 4.3.3. AT+QNETDEVCTL Make/Disconnect PDP Call ........................................................ 18 4.3.4. AT+QNETDEVSTATUS Query PDP Context ID Relevant Information...................... 19 5 Appendix References ....................................................................................................................... 21 EG060V-EA_USBnet_Call_Application_Note 4 / 21 LTE-A Module Series Table Index Table 1: Types of AT Commands .............................................................................................................. 14 Table 2: Related Document........................................................................................................................ 21 Table 3: Terms and Abbreviations .............................................................................................................. 21 EG060V-EA_USBnet_Call_Application_Note 5 / 21 LTE-A Module Series Figure Index Figure 1: USBnet Call Flowchart.................................................................................................................. 8 Figure 2: RNDIS USBnet in Windows.........................................................................................................11 Figure 3: USBnet Call Status in Windows.................................................................................................. 12 Figure 4: View IP Address of USBnet in Linux........................................................................................... 13 EG060V-EA_USBnet_Call_Application_Note 6 / 21 LTE-A Module Series 1 Introduction This document introduces how to use Quectel EG060V-EA module to make a USBnet call on a Windows host or a Linux host, including USBnet call methods, call procedures, call results, call status query and related AT commands. EG060V-EA_USBnet_Call_Application_Note 7 / 21 LTE-A Module Series 2 USBnet Call Process EG060V-EA网卡拨号数据流程 Exception Handling Mechanism 3: If data service is still unavailable after remaking a call and executing AT+CFUN, please reboot the module through hardware and try again. Exception Handling Mechanism 2: If data service is still unavailable after remaking a call, please try soft reset, execute AT+CFUN to shift functionality and then make a USBnet call after the registration succeeds. AT AT+CPIN? AT+CIMI AT+CGDCONT? AT+QICSGP=1 Whether the APN matches the PLMN YES NO AT+CGDCONT=1,'IP','APN' AT+QICSGP=1,1,'APN' AT+CFUN=0 AT+CFUN=1 Boot the module and confirm the availability of AT command functionality after ttyUSB is identified. Execute AT+CPIN?. The response of READY indicates the SIM ca·rd is read. APN Configuration Procedure: Execute AT+CIMI to identify the corresponding operator according to the returned PLMN, and set the APN of the corresponding operator (the client needs to maintain an APN l i s t of global operators whi c h can be f o u n d v i a Google). Common APNs of China domestic operators are as follows: China Mobile (CMNET):46000/02/04/07/08 China Unicom (3GNET):46001/06/09 China Telecom (CTNET):46003/05/11 At the same time, it is necessary to s a v e client configurations including username a n d password , and t o r e s e r v e a communication port to send AT commands for configuring authentication parameters so that the program can automatically match configurations and the end user can try to configure the program manually when APN cannot register to the network. Note: 1. When using an APN for the first time, the configuration of AT+CFUN=1 should be used. To this end, you can either execute AT+CFUN=0 followed by AT+CFUN=1, or reboot the module. 2. Skip the configuration procedure if there is no need to configure APN for the SIM card in use. AT+QNETDEVCTL=0,1,1 AT+CSQ AT+CEREG?/AT+CREG? AT+COPS? AT+QNWINFO AT+QNETDEVCTL=1,1,1 Exception Handling Mechanism 1: If data service is not available, please try to disconnect the call and then make a call again Start data service At the same time, the upper layer of application keeps the data alive and detects whether the data service is available or not NO Whether data service is available Execute AT+CSQ to query the signal strength. The practical range of is 0 to 31. Execute AT+CEREG?/AT+CREG?. 5 or 1 returned for the second parameter (i.e., ) in the response indicates a successful registration. If the program has not automatically registered within 2 minutes, the master application should remind the user to manually configure APN. Execute AT+COPS?to query the registered network mode. 7 returned for the last parameter (i.e., ) in the response indicates the current network mode is LTE. Execute AT+QNETDEVCTL=1,1,1 to m a k e a call, then execute AT+QNETDEVCTL? to query whether the c a l l is successful . The r e s p o n s e o f t h e q u e r y is +QNETDECTL:, , ,, where the returned values of , and are the values configured before or 0 if these parameters have not been configured, 1 returned for < s t a t e > indicates a successful c a l l (USBnet is bound) w h i l e 0 i n d i c a t e s a failed c a l l (USBnet is not bound). If there is disconnection or reconnection because of network disconnection and deactivation, URC reports automatically, such as +QNETDEVSTATUS: 1 +QNETDEVSTATUS: 0 To keep the data alive, it is recommended to ping the following websites every 1 to 2 minutes: www.baidu.com, 8.8. 8.8, 114.114. 114.114. If any of the websites can be pinged, the network is available. Figure 1: USBnet Call Flowchart EG060V-EA_USBnet_Call_Application_Note 8 / 21 LTE-A Module Series NOTE For details about the AT commands given in the figure above, see document [1]. EG060V-EA_USBnet_Call_Application_Note 9 / 21 LTE-A Module Series 3 USBnet Call Description This chapter introduces the specific procedures of making a USBnet call according to the USBnet call process of Chapter 2. You can configure the USBnet call method by executing AT+QCFG and make a call by executing AT+QNETDEVCTL. If the call is made successfully, you can view the USBnet call result by executing AT+QNETDEVSTATUS. See Chapter 4.3 for details of the above AT commands. 3.1. Configure USBnet 3.1.1. Configure Call Method 3.1.1.1. Configure Call Method in Windows Execute AT+QCFG='usbnet',3 to configure the call method as RNDIS. 3.1.1.2. Configure Call Method in Linux Execute AT+QCFG='usbnet',4 to configure the call method as NCM; or Execute AT+QCFG='usbnet',1 to configure the call method as ECM; or Execute AT+QCFG='usbnet',3 to configure the call method as RNDIS. 3.1.2. Configure Call Mode Execute AT+QCFG='nat',0 to configure the call mode as router mode; or Execute AT+QCFG='nat',1 to configure the call mode as bridge mode. NOTE The configurations of the above commands take effect after the module is rebooted. It is recommended to query the current call mode by executing AT+QCFG='nat' after startup. If the current configuration is different from your expectation, you can configure the module as described above and then reboot the module. EG060V-EA_USBnet_Call_Application_Note 10 / 21 LTE-A Module Series 3.2. Make Call Execute AT+QNETDEVCTL to make a USBnet call. For example, execute AT+QNETDEVCTL=2,1,1, which means a USBnet call is made with =1, and the module is enabled to automatically reconnect to network after disconnecting from network; and the URC that reports the call status is enabled. If the call is made successfully, you can check the call result. For details about the call result, see Chapter 3.3. 3.3. Call Result If the call is made successfully, the host computer creates a corresponding USBnet connection. You can check the call result by viewing the USBnet status. 3.3.1. Call Result in Windows Windows 10 is taken as an example. Open the 'Control Panel' window, click 'Network and Internet', then select the created RNDIS USBnet, double click the USBnet icon and then click 'Details' to view the USBnet call status. Figure 2: RNDIS USBnet in Windows EG060V-EA_USBnet_Call_Application_Note 11 / 21 LTE-A Module Series Figure 3: USBnet Call Status in Windows EG060V-EA_USBnet_Call_Application_Note 12 / 21 LTE-A Module Series 3.3.2. Call Result in Linux Execute ifconfig on the host computer to view IP address of the current USBnet, as shown in the following figure: Figure 4: View IP Address of USBnet in Linux EG060V-EA_USBnet_Call_Application_Note 13 / 21 LTE-A Module Series 4 AT Command 4.1. AT Command Introduction 4.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals to its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 4.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 1: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of corresponding Write Command and return information about the type, value, or range of its parameter. Check the current parameter value of a corresponding Write Command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. EG060V-EA_USBnet_Call_Application_Note 14 / 21 LTE-A Module Series 4.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendation or suggestions about how you should design a program flow or what status you should set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there exists a correlation among these examples, or that they should be executed in a given sequence. 4.3. AT Command Description 4.3.1. AT+QCFG Extended Configuration AT+QCFG Extended Configuration Test Command AT+QCFG=? Response +QCFG: 'usbnet',(list of supported s) +QCFG: 'nat',(list of supported s) … Maximum Response Time OK 300 ms 4.3.1.1. AT+QCFG='usbnet' Configure Call Method This command queries or configures the call method of USBnet. AT+QCFG='usbnet' Configure Call Method Write Command AT+QCFG='usbnet'[,] Response If the optional parameter is omitted, query the current setting. +QCFG: 'usbnet', OK Maximum Response Time If the optional parameter is specified, configure the call method. OK Or ERROR 300 ms EG060V-EA_USBnet_Call_Application_Note 15 / 21 LTE-A Module Series Characteristics The command takes effect after the module is rebooted. The configuration will be saved automatically. Parameter Integer type. Call method of USBnet. 1 ECM 3 RNDIS 4 NCM Example AT+QCFG='usbnet',4 OK //Configure the call method as NCM. 4.3.1.2. AT+QCFG='nat' Configure Call Mode This command queries or configures the call mode of USBnet. AT+QCFG='nat' Configure Call Mode Write Command AT+QCFG='nat'[,] Response If the optional parameter is omitted, query the current setting. +QCFG: 'nat', OK Maximum Response Time Characteristics If the optional parameter is specified, configure the call mode. OK Or ERROR 300 ms The command takes effect after the module is rebooted. The configuration will be saved automatically. Parameter Integer type. Call mode. 0 Router mode 1 Bridge mode EG060V-EA_USBnet_Call_Application_Note 16 / 21 LTE-A Module Series NOTE In router mode, the address obtained by the host is a private network address; while in bridge mode, the address obtained by the host is a public network address. Example AT+QCFG='nat',1 OK //Configure the call mode as bridge mode. 4.3.2. AT+QICSGP Configure PDP Context This command queries or configures relevant parameters for a specified PDP context. AT+QICSGP Configure PDP Context Test Command AT+QICSGP=? Response +QICSGP: (range of supported s),(range of supported s),,,,(range of supported s) Read Command AT+QICSGP? OK Response +QICSGP: ,,,,< password>, Write Command AT+QICSGP=[,,[, ,,]] OK Response If the optional parameters are omitted, query the configuration of the specified PDP context. +QICSGP: ,,,,< authentication> OK Maximum Response Time Characteristics If any of the optional parameters is specified, configure the specified PDP context. OK Or ERROR 300 ms The command takes effect immediately. The configuration will be saved automatically. EG060V-EA_USBnet_Call_Application_Note 17 / 21 LTE-A Module Series Parameter Integer type. PDP context ID. Range: 1–15. Integer type. Protocol type. 1 IPv4 2 IPv6 3 IPv4v6 String type. Access point name. String type. Username. Maximum length: 50 bytes. String type. Password. Maximum length: 50 bytes. Integer type. Authentication method. 0 NONE 1 PAP 2 CHAP Example AT+QICSGP=2,1,'','quectel','123456',1 OK //Configure =2. 4.3.3. AT+QNETDEVCTL Make/Disconnect PDP Call This command makes or disconnects a PDP call. AT+QNETDEVCTL Perform/Disconnect PDP Call Test Command AT+QNETDEVCTL=? Response +QNETDEVCTL: (range of supported s),(range of supported ),(list of supported s),(list of supported s) Read Command AT+QNETDEVCTL? OK Response +QNETDEVCTL: ,,,< state> Write Command Make a call through a specified PDP context AT+QNETDEVCTL=,[,] OK Response OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. The configuration will be saved automatically. EG060V-EA_USBnet_Call_Application_Note 18 / 21 LTE-A Module Series Parameter Integer type. Make or disconnect a call. 0 Disconnect a call 1 Make a call 2 Make a call and automatically remake a call after disconnecting from the network 3 Make a call and automatically remake a call after disconnecting from the network, and automatically make a call after startup Integer type. PDP context ID. Range: 1–15. Integer type. Whether to enable URC that reports the call status. 0 Disable 1 Enable Integer type. Call status. 0 Failed 1 Successful NOTE You can configure as 0/1/2 to disable automatically making a call after startup as needed. Example AT+QNETDEVCTL=2,1,1 OK //Configure =1 to make a call. 4.3.4. AT+QNETDEVSTATUS Query PDP Context ID Relevant Information This command queries relevant information of the specified PDP context ID. AT+QNETDEVSTATUS Query PDP Context ID Relevant Information Test Command AT+QNETDEVSTATUS=? Response +QNETDEVSTATUS: (list of activated s) Write Command AT+QNETDEVSTATUS= OK Response +QNETDEVSTATUS: ,,,,,, OK Or ERROR EG060V-EA_USBnet_Call_Application_Note 19 / 21 LTE-A Module Series Maximum Response Time Characteristics 300 ms / Parameter Integer type. PDP context ID. Range: 1–15. String type. Host IP address. Range: 0x0000_0000–0xFFFF_FFFF. String type. Subnet mask. Range: 0x0000_00FF–0xFCFF_FFFF. String type. Default gateway address. Range: 0x0000_0000–0xFFFF_FFFF. String type. DHCP server address. Range: 0x0000_0000–0xFFFF_FFFF. String type. Primary DNS address. Range: 0x0000_0000–0xFFFF_FFFF. String type. Secondary DNS address. Range: 0x0000_0000–0xFFFF_FFFF. Example AT+QNETDEVSTATUS=2 //Query the information of =2. +QNETDEVSTATUS: 2,'10.175.91.166','','','','211.138.180.2','211.138.180.3' OK EG060V-EA_USBnet_Call_Application_Note 20 / 21 LTE-A Module Series 5 Appendix References Table 2: Related Document Document Name [1] Quectel_EG060V-EA_AT_Commands_Manual Table 3: Terms and Abbreviations Abbreviation APN CHAP DHCP DNS ECM ID IP IPv4 IPv6 NCM PAP PDP RNDIS URC USB Description Access Point Name Challenge Handshake Authentication Protocol Dynamic Host Configuration Protocol Domain Name System Ethernet Control Model Identifier Internet Protocol Internet Protocol Version 4 Internet Protocol Version 6 Network Control Model Password Authentication Protocol Packet Data Protocol Remote Network Driver Interface Specification Unsolicited Result Code Universal Serial Bus EG060V-EA_USBnet_Call_Application_Note 21 / 21
488.01 KB
BC660K-GL SSL Application Note NB-IoT Module Series Version: 1.0 Date: 2021-12-29 Status: Released BC660K-GL_SSL_Application_Note 1 / 24 NB-IoT Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BC660K-GL_SSL_Application_Note 1 / 24 NB-IoT Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2021. All rights reserved. BC660K-GL_SSL_Application_Note 2 / 24 NB-IoT Module Series About the Document Revision History Version 1.0 Date 2021-09-09 2021-12-29 Author Randy LI Randy LI Description Creation of the document First official release BC660K-GL_SSL_Application_Note 3 / 24 NB-IoT Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 5 1 Introduction .......................................................................................................................................... 6 1.1. SSL Versions................................................................................................................................ 6 1.2. SSL Cipher Suites ........................................................................................................................ 6 1.3. DTLS Versions ............................................................................................................................. 7 2 SSL Related AT Commands ............................................................................................................... 8 2.1. AT Command Introduction ........................................................................................................... 8 2.1.1. Definitions........................................................................................................................... 8 2.1.2. AT Command Syntax ......................................................................................................... 8 2.2. Declaration of AT Command Examples ....................................................................................... 9 2.3. Description of AT Commands ...................................................................................................... 9 2.3.1. AT+QSSLCFG Configure Parameters of an SSL Context .............................................. 9 2.3.2. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server .......................... 15 2.3.3. AT+QSSLSEND Send Data Through SSL Connection................................................. 16 2.3.4. AT+QSSLCLOSE Close an SSL Connection ................................................................ 17 2.4. Description of URCs .................................................................................................................. 18 2.4.1. +QSSLURC: 'recv' Notify Incoming Data ..................................................................... 18 2.4.2. +QSSLURC: 'closed' Notify SSL Connection Disconnected ....................................... 19 3 Example .............................................................................................................................................. 20 3.1. SSL Function of Two-Way Authentication.................................................................................. 20 3.2. DTLS Function of Two-Way Authentication ............................................................................... 21 4 Result Codes ...................................................................................................................................... 23 5 Appendix References ........................................................................................................................ 24 BC660K-GL_SSL_Application_Note 4 / 24 NB-IoT Module Series Table Index Table 1: Supported SSL Versions ................................................................................................................ 6 Table 2: Supported SSL Cipher Suites (Official IANA Names) .................................................................... 6 Table 3: Supported DTLS Versions .............................................................................................................. 7 Table 4: Types of AT Commands.................................................................................................................. 8 Table 5: Summary of Result Codes ........................................................................................................... 23 Table 6: Related Documents ..................................................................................................................... 24 Table 7: Terms and Abbreviations .............................................................................................................. 24 BC660K-GL_SSL_Application_Note 5 / 24 NB-IoT Module Series 1 Introduction To keep the communication secure and prevent sensitive data from being eavesdropped, tampered, or forged during the communication process, SSL is used to safeguard the communication between the server and the client by using encryption algorithms. This document describes how to apply the SSL function of Quectel BC660K-GL module. 1.1. SSL Versions The following SSL versions are supported by BC660K-GL. Table 1: Supported SSL Versions SSL Version TLS1.0 TLS1.1 TLS1.2 1.2. SSL Cipher Suites The following table shows SSL cipher suites supported by Quectel BC660K-GL module. Please refer to https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml for details of the cipher suites. Table 2: Supported SSL Cipher Suites (Official IANA Names) Cipher Suite Code 0X002F Cipher Suite Name TLS_RSA_WITH_AES_128_CBC_SHA BC660K-GL_SSL_Application_Note 6 / 24 0X0035 0X000A 0X00FF NB-IoT Module Series TLS_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_3DES_EDE_CBC_SHA TLS_EMPTY_RENEGOTIATION_INFO_SCSV 1.3. DTLS Versions The following DTLS versions are supported by BC660K-GL. Table 3: Supported DTLS Versions DTLS Version DTLS1.0 DTLS1.2 BC660K-GL_SSL_Application_Note 7 / 24 NB-IoT Module Series 2 SSL Related AT Commands This chapter gives details of the AT Command set supported by the Quectel NB-IoT module BC660K-GL. 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals to its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 4: Types of AT Commands Command Type Syntax Test Command AT+=? Read Command AT+? Description Test the existence of corresponding Write Command and return information about the type, value, or range of its parameter. Check the current parameter value of a corresponding Write Command. BC660K-GL_SSL_Application_Note 8 / 24 NB-IoT Module Series Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about how to use the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendation or suggestions about how you should design a program flow or what status you should set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there exists a correlation among these examples and that they should be executed in a given sequence. 2.3. Description of AT Commands 2.3.1. AT+QSSLCFG Configure Parameters of an SSL Context The command configures optional parameters for SSL function. AT+QSSLCFG Configure Parameters of an SSL Context Test Command AT+QSSLCFG=? Response +QSSLCFG: (range of supported s),(range of supported s),'seclevel',(range of supported s) +QSSLCFG: (range of supported s),(range of supported s),'sslversion',(range of supported s) +QSSLCFG: (range of supported s),(range of supported s),'dataformat',(list of supported s),(list of supported s) +QSSLCFG: (range of supported s),(range of supported s),'timeout',(range of supported s) +QSSLCFG: (range of supported s),(range of supported s),'debug',(range of supported s) +QSSLCFG: (range of supported s),(range of supported s),'cacert' BC660K-GL_SSL_Application_Note 9 / 24 NB-IoT Module Series +QSSLCFG: (range of supported s),(range of supported s),'clientcert' +QSSLCFG: (range of supported s),(range of supported s),'clientkey' +QSSLCFG: (range of supported s),(range of supported s),'dtls',(list of supported s) +QSSLCFG: (range of supported s),(range of supported s),'dtlsversion',(range of supported s) OK Write Command Response Query all current settings of the +QSSLCFG: ,,'seclevel', AT+QSSLCFG=,<connec +QSSLCFG: ,,'sslversion', SL_version> +QSSLCFG: ,,'dataformat',, +QSSLCFG: ,,'timeout', +QSSLCFG: ,,'debug', +QSSLCFG: ,,'cacert', +QSSLCFG: ,,'clientcert', +QSSLCFG: ,,'clientkey', +QSSLCFG: ,,'dtls', +QSSLCFG: ,,'dtlsversion', OK Or ERROR Write Command Configure the authentication mode for the specified SSL context AT+QSSLCFG=,,'seclevel'[,] Response If the optional parameter is omitted, query the current setting: +QSSLCFG: ,,'seclevel', OK BC660K-GL_SSL_Application_Note 10 / 24 NB-IoT Module Series If the optional parameter is specified, set the authentication mode for the specified SSL context: OK If there is any error: ERROR Write Command Response Configure the SSL version for the If the optional parameter is omitted, query the current specified SSL context setting: AT+QSSLCFG=,<connec +QSSLCFG: ,,'sslversion',,'sslversion'[,] SL_version> OK If optional parameter is specified, set the SSL version for the specified SSL context: OK If there is any error: ERROR Write Command Configure the format of data to be sent/received AT+QSSLCFG=,,'dataformat'[,,] Response If the optional parameters are omitted, query the current setting: +QSSLCFG: ,,'dataformat',, OK If the optional parameters are specified, configure the format of data to be sent/received: OK If there is any error: ERROR Write Command Configure the timeout of connection and message delivery for the specified SSL context AT+QSSLCFG=,,'timeout'[,] Response If the optional parameter is omitted, query the current setting: +QSSLCFG: ,,'timeout', OK If the optional parameter is specified, configure the timeout BC660K-GL_SSL_Application_Note 11 / 24 NB-IoT Module Series of connection and message delivery for the specified SSL context: OK If there is any error: ERROR Write Command Configure the printable debug log level for the specified SSL context AT+QSSLCFG=,,'debug'[,] Response If the optional parameter is omitted, query the current setting: +QSSLCFG: ,,'debug', OK If optional parameter is specified, configure the printable debug log level for the specified SSL context: OK If there is any error: ERROR Write Command Response Configure the content of trusted CA > certificate in PEM format for the specified SSL context: AT+QSSLCFG=,,'cacert' After the above response, input the data to be sent. Then tap 'CTRL' + 'Z' to send the data or tap 'Esc' to cancel the operation.' +QSSLCFG: ,,'cacert', OK If there is any error: ERROR Write Command Response Configure the content of client certificate in PEM format for the specified SSL context: AT+QSSLCFG=, After the above response, input the data to be sent. Then tap 'CTRL' + 'Z' to send the data or tap 'Esc' to cancel the operation. tID>,'clientcert' +QSSLCFG: ,,'clientcert', OK If there is any error: ERROR BC660K-GL_SSL_Application_Note 12 / 24 NB-IoT Module Series Write Command Configure the content of client private key in PEM format for the specified SSL context: AT+QSSLCFG=,,'clientkey' Response > After the above response, input the data to be sent. Then tap 'CTRL' + 'Z' to send the data or tap 'Esc' to cancel the operation. +QSSLCFG: ,,'clientkey', OK If there is any error: ERROR Write Command Response Enable/disable the DTLS function for If the optional parameter is omitted, query the current the specified SSL context setting: AT+QSSLCFG=,<connec +QSSLCFG: ,,'dtls',,'dtls'[,] able> OK If the optional parameter is specified, enable/disable the DTLS function for the specified SSL context: OK If there is any error: ERROR Write Command Configure the DTLS version of the specified SSL context AT+QSSLCFG=,,'dtlsversion'[,] Response If the optional parameter is omitted, query the current setting: +QSSLCFG: ,,'dtlsversion', OK If the optional parameter is specified, configure the DTLS version of the specified SSL context: OK Maximum Response Time Characteristics If there is any error: ERROR 300 ms The command takes effect immediately. Except for the certificate configuration, other configurations BC660K-GL_SSL_Application_Note 13 / 24 will not be saved. NB-IoT Module Series Parameter Integer type. SSL context ID. Range: 0–10 (currently only 0 is supported). Integer type. SSL connect ID. Range: 0–4 (currently only 0 is supported). Integer type. The authentication mode. 0 No authentication 1 Perform server authentication 2 Perform server and client authentication if requested by the remote server Integer type. SSL version. 1 TLS 1.0 2 TLS 1.1 3 TLS 1.2 4 All protocols are supported, the specific protocol version used needs to be negotiated with the server. Integer type. The format of the sent data. 0 Text format 1 Hex format Integer type. The format of the received data. 0 Text format 1 Hex format Integer type. Timeout value of connection or message delivery. Range: 10–300. Default value: 90. Unit: second. Integer type. The printable debug log level. 0 No debug log 1 Error debug log 2 State debug log 3 Info debug log 4 Detail debug log Integer type. The length of certificate. Unit: byte. Integer type. Enable or disable DTLS feature. 0 Disable DTLS feature. 1 Enable DTLS feature . Integer type. DTLS version. 0 DTLS 1.0 1 DTLS 1.2 2 All protocols are supported, the specific protocol version used needs to be negotiated with the server. BC660K-GL_SSL_Application_Note 14 / 24 NB-IoT Module Series NOTE 1. is used during debugging only. And the bigger the value is, the more log will be generated. 2. If is set to 0, no certificates need to be configured. If is set to 1, server CA certificate needs to be configured. If is set to 2, server CA certificate, client certificate and client private key need to be configured. 3. The configuration of is only valid for TLS connection and invalid for DTLS connection. 2.3.2. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server This command opens an SSL socket to connect a remote server. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server Test Command AT+QSSLOPEN=? Response +QSSLOPEN: (range of supported s),(range of supported s),,(range of supp orted s),(list of supported s) Read Command AT+QSSLOPEN? Write Command AT+QSSLOPEN=,,,, OK Response OK Response OK +QSSLOPEN: ,, Maximum Response Time Characteristics If there is any error: ERROR It is determined by of AT+QSSLCFG (default value: 90 s) when a TLS server is connected. It is 123 s when a DTLS server is connected. The command takes effect immediately. The configurations will not be saved. Parameter Integer type. SSL context ID. Range: 0–10 (currently only 0 is supported). Integer type. SSL connect ID. Range: 0–4 (currently only 0 is supported). String type. IP address or domain name of SSL server. Maximum length: 150 bytes. Integer type. Port number of the remote server. Range: 1–65535. BC660K-GL_SSL_Application_Note 15 / 24 NB-IoT Module Series Integer type. Data transmission mode of the SSL connection. 0 Non-transparent mode 1 Transparent mode (not supported currently) Result code. 0 indicates a successful operation and any other value indicates an error. Please refer to Chapter 4 for more details. 2.3.3. AT+QSSLSEND Send Data Through SSL Connection This command sends data through the SSL connection after the connection is established. AT+QSSLSEND Send Data Through SSL Connection Test Command AT+QSSLSEND=? Response +QSSLSEND: (range of supported s),(range of supported s),(range of supported s) Read Command AT+QSSLSEND? Write Command Send variable-length data AT+QSSLSEND=, OK Response OK Response > After the above response, the module enters data mode and the data to be sent can be inputted directly. Tap 'CTRL' + 'Z' to send the data or tap 'Esc' to cancel the operation. If the SSL connection is established and the data is sent successfully: OK +QSSLSEND: ,, Write Command Send fixed-length data AT+QSSLSEND=,, If the SSL connection is not established, disconnected, or some other errors occur: ERROR Response > After the above response, the module enters data mode. After that, type the data to be sent until the data length reaches . If the SSL connection is established and the data is sent successfully: OK BC660K-GL_SSL_Application_Note 16 / 24 NB-IoT Module Series Maximum Response Time Characteristics +QSSLSEND: ,, If the SSL connection is not established, disconnected, or some other errors occur: ERROR of AT+QSSLCFG (default value: 90). The actual response time is determined by network. The command takes effect immediately. The configurations will not be saved. Parameter Integer type. SSL context ID. Range: 0–10 (currently only 0 is supported). Integer type. SSL connect ID. Range: 0–4 (currently only 0 is supported). Integer type. The length of the data to be sent. Range: 1–1024. Unit: byte. Integer type. The result of connection. 0 indicates a successful operation and any other value indicates an error. Please refer to Chapter 4 for more details. NOTE When in AT+QSSLCFG is set to 1 (hex format), the character length of the data to be inputted after executing AT+QSSLSEND=,, must be twice of value. 2.3.4. AT+QSSLCLOSE Close an SSL Connection This command closes an SSL connection. If all SSL connections of an SSL context are closed, the module will release the SSL context. AT+QSSLCLOSE Close an SSL Connection Test Command AT+QSSLCLOSE=? Response +QSSLCLOSE: (range of supported s),(range of supported s) Read Command AT+QSSLCLOSE? Write Command AT+QSSLCLOSE=, OK Response OK Response OK +QSSLCLOSE: ,, BC660K-GL_SSL_Application_Note 17 / 24 NB-IoT Module Series Maximum Response Time Characteristics If there is any error: ERROR 300 ms The command takes effect immediately. The configurations will not be saved. Parameter Integer type. SSL context ID. Range: 0–10 (currently only 0 is supported). Integer type. SSL connect ID. The range is 0–4 (currently only 0 is supported). Result code. 0 indicates a successful operation and any other value indicates an error. Please refer to Chapter 4 for more details. 2.4. Description of URCs SSL URCs begin with +QSSLURC: and they are mainly used to notify the host of incoming data or disconnected SSL connection. 2.4.1. +QSSLURC: 'recv' Notify Incoming Data The URC notifies the host of incoming data. +QSSLURC: 'recv' Notify Incoming Data +QSSLURC: 'recv',,,, Parameter Integer type. SSL context ID. Range: 0–10 (currently only 0 is supported). Integer type. SSL connect ID. Range: 0–4 (currently only 0 is supported). Integer type. The length of data. Range: 1–1400. Unit: byte. String type. The incoming data. BC660K-GL_SSL_Application_Note 18 / 24 NB-IoT Module Series 2.4.2. +QSSLURC: 'closed' Notify SSL Connection Disconnected The URC notifies the host that the SSL connection has been disconnected. When this URC is reported, the module closes the SSL connection automatically, and the host does not need to execute AT+QSSLCLOSE to close the SSL connection. +QSSLURC: 'closed' Notify SSL Connection Disconnected +QSSLURC: 'closed',, Parameter Integer type. SSL context ID. Range: 0–10 (currently only 0 is supported). Integer type. SSL connect ID. Range: 0–4 (currently only 0 is supported). BC660K-GL_SSL_Application_Note 19 / 24 NB-IoT Module Series 3 Example 3.1. SSL Function of Two-Way Authentication AT+QSCLK=0 //Disable sleep mode OK //Configure certificates and keys AT+QSSLCFG=0,0,'seclevel',2 //Perform server and client authentication OK AT+QSSLCFG=0,0,'cacert' //Configure CA certificate > //After the response >, input content of the trusted CA certificate in PEM format, tap 'CTRL' + 'Z' to send +QSSLCFG: 0,0,'cacert',1216 OK AT+QSSLCFG=0,0,'clientcert' //Configure client certificate > //After the response >, input content of the client certificate in PEM format, tap 'CTRL' + 'Z' to send. +QSSLCFG: 0,0,'clientcert',1224 OK AT+QSSLCFG=0,0,'clientkey' //Configure client private key > //After the response >, input content of the client private key in PEM format, tap 'CTRL' + 'Z' to send. +QSSLCFG: 0,0,'clientkey',1679 OK AT+QSSLOPEN=0,0,'hf.quectel.com',8164,0 //Open an SSL server connection OK +QSSLOPEN: 0,0,0 AT+QSSLSEND=0,0 //Send data to SSL server > //After the response >, input the data to be sent and tap 'CTRL' + 'Z' to send. OK +QSSLSEND: 0,0,0 BC660K-GL_SSL_Application_Note 20 / 24 NB-IoT Module Series +QSSLURC: 'recv',0,0,10,'1234567890' AT+QSSLCLOSE=0,0 OK +QSSLCLOSE: 0,0,0 AT+QSCLK=1 OK //Received data from SSL server //Close the SSL connection //Enable light sleep and deep sleep and wake up by PSM_EINT (falling edge) 3.2. DTLS Function of Two-Way Authentication AT+QSCLK=0 //Disable sleep mode OK //Configure certificates and keys AT+QSSLCFG=0,0,'dtls',1 //Enable DTLS feature OK //Configure certificates and keys AT+QSSLCFG=0,0,'seclevel',2 //Perform server and client authentication OK AT+QSSLCFG=0,0,'cacert' //Configure CA certificate > //After the response >, input content of the trusted CA certificate in PEM format, tap 'CTRL' + 'Z' to send +QSSLCFG: 0,0,'cacert',1216 OK AT+QSSLCFG=0,0,'clientcert' //Configure client certificate > //After the response >, input content of the client certificate in PEM format, tap 'CTRL' + 'Z' to send. +QSSLCFG: 0,0,'clientcert',1224 OK AT+QSSLCFG=0,0,'clientkey' //Configure client private key > //After the response >, input content of the client private key in PEM format, tap 'CTRL' + 'Z' to send. +QSSLCFG: 0,0,'clientkey',1679 OK AT+QSSLOPEN=0,0,'hf.quectel.com',8164,0 //Open an SSL server connection OK +QSSLOPEN: 0,0,0 BC660K-GL_SSL_Application_Note 21 / 24 NB-IoT Module Series AT+QSSLSEND=0,0 //Send data to SSL server > //After the response >, input the data to be sent and tap 'CTRL' + 'Z' to send. OK +QSSLSEND: 0,0,0 +QSSLURC: 'recv',0,0,10,'1234567890' AT+QSSLCLOSE=0,0 OK //Received data from SSL server //Close the SSL connection +QSSLCLOSE: 0,0,0 AT+QSCLK=1 OK //Enable light sleep and deep sleep and wake up by PSM_EINT (falling edge) NOTE For more details about AT+QSCLK, please refer to document [1]. BC660K-GL_SSL_Application_Note 22 / 24 4 Result Codes Table 5: Summary of Result Codes 0 -1 -2 -3 -4 -5 -6 -7 -9 Description Successful operation Exception error Connection error Certificate error Key error Cipher error State error Time out Other errors NB-IoT Module Series BC660K-GL_SSL_Application_Note 23 / 24 NB-IoT Module Series 5 Appendix References Table 6: Related Document Document Name [1] Quectel_BC660K-GL_AT_Commands_Manual Table 7: Terms and Abbreviations Abbreviation CA DTLS EINT IANA IP NB-IoT PEM PSK PSM SSL TA TLS URC URL Description Certificate Authority Datagram Transport Layer Security External Interrupt Internet Assigned Numbers Authority Internet Protocol Narrowband Internet of Things Privacy Enhanced Mail Pre-Shared Key Power Saving Mode Security Socket Layer Terminal Adapter Transport Layer Security Unsolicited Result Code Uniform Resource Locator BC660K-GL_SSL_Application_Note 24 / 24
224.46 KB
EG060V-EA Log Capture Guide LTE-A Module Series Version: 1.0 Date: 2021-12-21 Status: Released LTE-A Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. EG060V-EA_Log_Capture_Guide 1 / 27 LTE-A Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2021. All rights reserved. EG060V-EA_Log_Capture_Guide 2 / 27 LTE-A Module Series About the Document Revision History Version Date - 2021-11-10 1.0 2021-12-21 Author Paddy LI Paddy LI Description Creation of the document First official release EG060V-EA_Log_Capture_Guide 3 / 27 LTE-A Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 5 Figure Index ................................................................................................................................................. 6 1 Introduction .......................................................................................................................................... 7 2 Capture Log and Dump File in Windows........................................................................................... 8 2.1. Capture Log ................................................................................................................................ 8 2.1.1. Capture AP Log Through Serial Port Tool........................................................................ 8 2.1.2. Capture CP Log Through CATStudio ............................................................................... 9 2.2. Capture Dump File .................................................................................................................... 15 3 Capture Log and Dump File in Linux ............................................................................................... 16 3.1. Capture Log .............................................................................................................................. 16 3.1.1. Capture AP Log Through Serial Port Tool...................................................................... 16 3.1.2. Capture CP Log Through QLog (Log Saved in Linux)................................................... 16 3.1.3. Capture CP Log Through QLog (Log Saved in Windows)............................................. 18 3.2. Capture Dump File .................................................................................................................... 19 4 Dump Mode Related AT Commands................................................................................................ 22 4.1. AT Command Introduction ........................................................................................................ 22 4.1.1. Definitions....................................................................................................................... 22 4.1.2. AT Command Syntax ..................................................................................................... 22 4.2. AT Command Description ......................................................................................................... 23 4.2.1. AT+QCFG='aprstlevel' Set AP Dump Level ............................................................... 23 4.2.2. AT+QCFG='modemrstlevel' Set CP Dump Level....................................................... 23 5 Network State Checking Related AT Commands ........................................................................... 25 6 Appendix References ........................................................................................................................ 26 EG060V-EA_Log_Capture_Guide 4 / 27 LTE-A Module Series Table Index Table 1: Types of AT Commands ....................................................................................................................... 22 Table 2: Related Documents ............................................................................................................................. 26 Table 3: Terms and Abbreviations...................................................................................................................... 26 EG060V-EA_Log_Capture_Guide 5 / 27 LTE-A Module Series Figure Index Figure 1: Boot Log of the Module ........................................................................................................................ 8 Figure 2: CATStudio Mode Selection Interface ................................................................................................... 9 Figure 3: CATStudio Main Interface................................................................................................................... 10 Figure 4: Communication Settings Interface ..................................................................................................... 10 Figure 5: Logger Operation Interface .................................................................................................................11 Figure 6: Database Selection Interface ............................................................................................................. 12 Figure 7: Logger Interface Presented After Successful Database Pairing ........................................................ 12 Figure 8: CATStudio Main Interface Tool Bar .................................................................................................... 13 Figure 9: LogViewer Interface ........................................................................................................................... 13 Figure 10: Tool Bar Interface to Export Log....................................................................................................... 14 Figure 11: ExportLog Interface to Select Log Export Path ................................................................................ 14 Figure 12: AP Dump File Exported When AP Dumps........................................................................................ 15 Figure 13: CP Dump File Exported When CP Dumps....................................................................................... 15 Figure 14: Loaded Module Ports ....................................................................................................................... 16 Figure 15: Capture CP Log on Linux Device ..................................................................................................... 17 Figure 16: View CP Log on Linux Device .......................................................................................................... 17 Figure 17: Socket Port Selection Interface ........................................................................................................ 18 Figure 18: Connection Method of Capturing Dump File in Linux System ......................................................... 19 Figure 19: NIC Setting of Windows PC ............................................................................................................. 19 Figure 20: Printed Information After Successful Capture of Log by rdp_transfer.............................................. 21 EG060V-EA_Log_Capture_Guide 6 / 27 LTE-A Module Series 1 Introduction This document mainly introduces how to capture AP log, CP log and dump file on Quectel LTE-A EG060V-EA module through QLog, rdp_transfer, CATStudio and TFTPD32. When the module is in an abnormal condition, you can check the current network state of the module through AT commands (see Chapter 5 for details) to determine the cause of the problem based on the query results. If it is determined that the module is misconfigured, you can reconfigure the module with the corresponding AT command to resolve the problem. If the cause cannot be determined or the problem cannot be resolved, you can capture corresponding logs and send the logs to Quectel for further analysis and processing. NOTE 1. QLog is a log capture tool developed by Quectel, you can contact Quectel Technical Supports to obtain the installation package if necessary. 2. You can install rdp_transfer and CATStudio tool with the assistance of Quectel Technical Supports. 3. You can download TFTPD32 from official website: https://bitbucket.org/phjounin/tftpd64/downloads/. EG060V-EA_Log_Capture_Guide 7 / 27 LTE-A Module Series 2 Capture Log and Dump File in Windows 2.1. Capture Log 2.1.1. Capture AP Log Through Serial Port Tool Step 1: Connect the module to the host through the debug UART port using a serial port line. Open any serial port tool on the host, select the COM port loaded in the device manager window and set the baud rate to 115200 bps. Then disable flow control and power on the module. The boot log will be displayed in the serial port tool. Figure 1: Boot Log of the Module EG060V-EA_Log_Capture_Guide 8 / 27 LTE-A Module Series Step 2: Tap 'Enter' on the keyboard and then an 'OpenWrt login:' window will be popped up. Enter username 'boot' and password 'admin' in the 'OpenWrt login:' window to log in to the Linux system of the module. AP log contains kernel log and API log of QLog interface. Input echo 1 > /sys/module/printk/parameters/kernel_log_output at the debug port through the serial port tool to print kernel log; input logcat -b radio at the debug port through the serial port tool to print the API log of QLog interface. 2.1.2. Capture CP Log Through CATStudio In Windows system, the CP log of the module can be captured through the Diag port loaded by USB enumeration. Step 1: Open CATStudio on the host, select 'Generic Target Online' and then click 'OK'. Figure 2: CATStudio Mode Selection Interface Step 2: Select 'Device Communication' on the lower right corner of the CATStudio main interface. On 'Device Communication' interface, select 'Settings' corresponding to 'Device0'. Select 'Quectel USB DIAG Port' on 'Communication Settings' interface and set baud rate to 115200 bps, and then click 'OK'. EG060V-EA_Log_Capture_Guide 9 / 27 LTE-A Module Series Figure 3: CATStudio Main Interface Figure 4: Communication Settings Interface EG060V-EA_Log_Capture_Guide 10 / 27 LTE-A Module Series Step 3: Continue to select the 'Logger' tab on main interface, click 'CpLog Start' and then 'CpLogStart' changes into 'CpLogStop'. Then click 'Update' in 'Database' section to enter the 'Database' selection interface. Figure 5: Logger Operation Interface Step 4: On 'Database' selection interface, select 'Text' in 'Communication' section, and then select LWG_MDB.txt in 'Text file'; select 'Text' in 'Application' section, and then select Boerne_DIAG.mdb.txt in 'Text file', then click 'UpdateAll'. When the updating process completes, close the 'Database' selection interface and return to the 'Logger' interface, then two indicators turn green. EG060V-EA_Log_Capture_Guide 11 / 27 LTE-A Module Series Figure 6: Database Selection Interface Figure 7: Logger Interface Presented After Successful Database Pairing EG060V-EA_Log_Capture_Guide 12 / 27 LTE-A Module Series Step 5: Select 'Modules' in the tool bar of the main interface, then click 'LogViewer' to open the log capture interface. Figure 8: CATStudio Main Interface Tool Bar Figure 9: LogViewer Interface Step 6: After reproducing the problem, click 'Log' in the tool bar of main interface and select 'Export Log-File…' in the drop-down box. In the 'ExportLog' window popped up, set a custom path to save log files, and rename the log files to be exported, then click 'Output(O)' to export the log files. EG060V-EA_Log_Capture_Guide 13 / 27 LTE-A Module Series Figure 10: Tool Bar Interface to Export Log Figure 11: ExportLog Interface to Select Log Export Path NOTE LWG_MDB.txt and Boerne_DIAG.mdb.txt are database files, you can contact Quectel Technical Supports (Website: support@quectel.com) to obtain the files. EG060V-EA_Log_Capture_Guide 14 / 27 LTE-A Module Series 2.2. Capture Dump File In Windows system, the dump file generated when the module dumps can be exported through TFTPD32 in Windows. You can send the dump file to Quectel for further analysis. Step 1: Configure the module into dump mode by executing AT+QCFG='aprstlevel',0 and AT+QCFG='modemrstlevel',0. You have to reboot the module after OK is returned for both commands such that the commands can take effect. See Chapter 4 for more details about the commands mentioned above. Step 1: Open TFTPD32 in Windows. The module will automatically reboot after it dumps and automatically executes rdp_transfer app. When the execution completes, TFTPD32 will automatically export the dump file. ⚫ If the AP dumps, the dump file exported by TFTPD32 will contain a compressed package and a txt file. The txt file briefly describes the location of this dump to illustrate the problem more clearly. Figure 12: AP Dump File Exported When AP Dumps ⚫ If the CP dumps, the dump file exported by TFTPD32 will contain two bin files and a compressed package. Figure 13: CP Dump File Exported When CP Dumps EG060V-EA_Log_Capture_Guide 15 / 27 LTE-A Module Series 3 Capture Log and Dump File in Linux 3.1. Capture Log 3.1.1. Capture AP Log Through Serial Port Tool The steps for capturing AP log in Linux system are the same as those in Windows system. See Chapter 2.1.1 for more details. 3.1.2. Capture CP Log Through QLog (Log Saved in Linux) Step 1: Install Linux USB driver. You can contact Quectel Technical Supports to obtain the installation method. Step 2: Open Linux terminal window under the root directory of QLog. Execute make to generate an executable file named Qlog under the QLog directory. Execute dmesg -w in Linux terminal window to list the module ports. If no port is displayed when it is determined that the module is connected, then the USB driver may be failed to be installed and needs to be reinstalled. If the module ports are loaded successfully, then QLog will start to capture log. The following information will be printed after the ports are loaded successfully. Figure 14: Loaded Module Ports EG060V-EA_Log_Capture_Guide 16 / 27 LTE-A Module Series Step 3: Execute ./QLog –s log in Linux terminal window to open QLog to capture log. When log capture completes, click 'Ctrl' + 'C' to end the QLog process. Figure 15: Capture CP Log on Linux Device Step 4: View the corresponding log file. You can save and send the log file to Quectel Technical Supports for further analysis. Take viewing the log file 20210304_05630_0000.logel as an example: Figure 16: View CP Log on Linux Device EG060V-EA_Log_Capture_Guide 17 / 27 LTE-A Module Series 3.1.3. Capture CP Log Through QLog (Log Saved in Windows) Step 1: Connect user’s Linux CPE development board to Windows PC through LAN port, and configure a static address for the corresponding network port on the PC. For example, if the bridge address of the CPE development board is 192.168.1.x, then an address of the same network segment should be configured for the corresponding network port of the PC to ensure that the PC can ping the bridge address of the CPE development board. Step 2: Run the QLog on the Linux CPE development board and export the log through the TCP port by executing -s port in the terminal window of Linux CPE development board. For example, ./Qlog-s 9000 means creating a TCP service at port 9000. Open CATStudio on Windows device and select 'Socket' on 'Communication Settings' interface. Select 'TCP Client', enter the bridge address of the CPE development board and the specified port for running the log, then click 'OK' to view the log capture on the 'LogViewer' interface. Figure 17: Socket Port Selection Interface You can save and send the log to Quectel Technical Supports for further analysis. For the details of the step for saving the log, you can refer to Step 6 of Chapter 2.1.2. EG060V-EA_Log_Capture_Guide 18 / 27 LTE-A Module Series 3.2. Capture Dump File You can capture dump file through rdp_transfer in Linux. The module must be configured into dump mode firstly by executing AT+QCFG='aprstlevel',0 and AT+QCFG='modemrstlevel',0. You have to reboot the module after OK is returned for both commands such that the commands can take effect. See Chapter 4.2 for more details of the commands mentioned above. In Linux system, when module dumps, the dump file needs to be exported through the LAN port of the Windows PC. TFTPD32 rdp_transfer PC (Windows) 192.168.0.x LAN Linux 192.168.0.x USB EG060V-EA Figure 18: Connection Method of Capturing Dump File in Linux System The steps for capturing dump file in Linux are as follows: Step 1: Open the network management configuration interface on Windows PC and set up a private IP address for the LAN port network to connect the Linux device, for example, 192.168.0.10. Figure 19: NIC Setting of Windows PC EG060V-EA_Log_Capture_Guide 19 / 27 LTE-A Module Series Step 2: The Linux device (user’s Linux device or Ubuntu) uses a configuration file to set a static address (which can only be modified when the root permission is obtained by entering 'root' as user name and 'admin' as password to log in to the Linux system of the module). 1) Modify the configuration file interfaces in the directory /etc/network/, an example of which is illustrated as follows: # interfaces(5) file used by ifup(8) and ifdown(8) auto lo iface lo inet loopback auto eth0 iface eth0 inet static address 192.168.0.3 netmask 255.255.255.0 gateway 192.168.0.1 2) Modify the configuration file base in the directory /etc/resolvconf/resolv.conf.d/, an example of which is illustrated as follows: nameserver 10.0.0.1 nameserver 192.168.0.1 After rebooting the device, you can execute ifconfig to check whether the eth0 network port is configured successfully, then ping the Linux device and Windows device to ensure the connectivity between the two devices. Step 3: Test the module function and reproduce the dump problem. Firstly, compile the rdp_transfer source code into a rdp_transfer binary executable program on the host. The module automatically reboots after it dumps. Execute sudo ./rdp_transfer < windows PC IP > with root permission through the rdp_transfer process of the host and transmit the module's dump file to the Windows PC through the LAN port, and then export the log locally through TFTPD32 of Windows PC. EG060V-EA_Log_Capture_Guide 20 / 27 LTE-A Module Series Figure 20: Printed Information After Successful Capture of Log by rdp_transfer EG060V-EA_Log_Capture_Guide 21 / 27 LTE-A Module Series 4 Dump Mode Related AT Commands 4.1. AT Command Introduction 4.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals to its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 4.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 1: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of corresponding Write Command and return information about the type, value, or range of its parameter. Check the current parameter value of a corresponding Write Command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. EG060V-EA_Log_Capture_Guide 22 / 27 LTE-A Module Series 4.2. AT Command Description 4.2.1. AT+QCFG='aprstlevel' Set AP Dump Level This command queries or sets AP dump level. AT+QCFG='aprstlevel' Set AP Dump Level Write Command AT+QCFG='aprstlevel'[,] Response If the optional parameter is omitted, query the current setting: +QCFG: 'aprstlevel', OK If the optional parameter is specified, set AP dump level: OK Maximum Response Time Characteristics If there is any error: ERROR 300 ms The command takes effect after the module is rebooted. The configuration will be saved automatically. Parameter Integer type. AP dump level. 0 Open AP dump. Module restarts and enters dump mode when AP dump happens 1 Close AP dump. Module only restarts when AP dump happens 4.2.2. AT+QCFG='modemrstlevel' Set CP Dump Level This command queries sets CP (corresponding to modem) dump level. AT+QCFG='modemrstlevel' Set CP Dump Level Write Command Response AT+QCFG='modemrstlevel'[,] If the optional parameter is omitted, query the current setting: +QCFG: 'modemrstlevel', OK If the optional parameter is specified, set modem dump level: OK EG060V-EA_Log_Capture_Guide 23 / 27 LTE-A Module Series Maximum Response Time Characteristics If there is any error: ERROR 300 ms The command takes effect after the module is rebooted. The configuration will be saved automatically. Parameter Integer type. Modem dump level. 0 Open modem dump. Module restarts and enters dump mode when CP dump happens 1 Close modem dump. Only CP restarts when CP dump happens NOTE If it is required that the module can enter dump mode after either AP dump happens or CP dump happens, then the module has to be rebooted after AT+QCFG='aprstlevel',0 and AT+QCFG='modemrstlevel',0 are both executed successfully. EG060V-EA_Log_Capture_Guide 24 / 27 LTE-A Module Series 5 Network State Checking Related AT Commands The AT commands for checking the network state of the module are listed as follows: 1. AT+CFUN? Query the function mode of the module 2. AT+CPIN? Query the status of SIM card 3. AT+CEREG? Query EPS network registration status 4. AT+COPS? Query network status 5. AT+QENG='servingcell' Query serving cell information 6. AT+CGDCONT? Query PDP configuration 7. AT+CGPADDR Query PDP address 8. AT+CGACT? Query PDP activation status NOTE For more details about the AT commands mentioned above, please refer to document [1]. EG060V-EA_Log_Capture_Guide 25 / 27 LTE-A Module Series 6 Appendix References Table 2: Related Documents Document Name [1] Quectel_EG060V-EA_AT_Commands_Manual Table 3: Terms and Abbreviations Abbreviation AP API CP CPE ECM EPS IP LAN PC PDP PIN RNDIS SIM TA TCP Description Application Processor Application Programming Interface Central Processor Customer-Premise Equipment Ethernet Control Model Evolved Packet System Internet Protocol Local Area Network Personal Computer Packet Data Protocol Personal Identification Number Remote Network Driver Interface Specification Subscriber Identity Module Terminal Adapter Transmission Control Protocol EG060V-EA_Log_Capture_Guide 26 / 27 TFTP UART USB LTE-A Module Series Trivial File Transfer Protocol Universal Asynchronous Receiver/Transmitter Universal Serial Bus EG060V-EA_Log_Capture_Guide 27 / 27
1.46 MB
LC76F I2C Application Note GNSS Module Series Version: 1.0 Date: 2021-12-21 Status: Released GNSS Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. LC76F_I2C_Application_Note 1 / 34 GNSS Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2021. All rights reserved. LC76F_I2C_Application_Note 2 / 34 GNSS Module Series About the Document Document Information Title Subtitle Document Type Document Status LC76F I2C Application Note GNSS Module Series Application Note Released Revision History Version 1.0 Date 2021-10-29 2021-12-21 Description Creation of the document First official release LC76F_I2C_Application_Note 3 / 34 GNSS Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 2 NMEA Data Reading via I2C Bus....................................................................................................... 8 2.1. NMEA Data Reading Flow of the Master ................................................................................... 8 2.2. I2C Data Packets ....................................................................................................................... 9 2.2.1. Format of I2C Data Packet ............................................................................................. 9 2.2.2. Five Types of I2C Data Packets.................................................................................... 10 2.2.2.1. Type 1: Valid Data Bytes + Garbage Bytes........................................................ 10 2.2.2.2. Type 2: All Garbage Bytes ..................................................................................11 2.2.2.3. Type 3: Garbage Bytes + Valid Data Bytes........................................................ 12 2.2.2.4. Type 4: Garbage Bytes + Valid Data Bytes + Garbage Bytes ........................... 13 2.2.2.5. Type 5: Garbage Bytes + Valid Data Bytes + Garbage Bytes + Valid Data Bytes + Garbage Bytes ................................................................................................................. 14 2.2.3. How to Extract Valid NMEA Data from Several I2C Packets........................................ 16 3 Sending Messages via I2C Bus ....................................................................................................... 17 4 Procedures for I2C Data Reading and Writing .............................................................................. 18 4.1. Sequence Charts ..................................................................................................................... 18 4.2. Sample Code ........................................................................................................................... 19 5 Procedures for Receiving and Parsing NMEA Sentences ........................................................... 21 5.1. Flow Chart ................................................................................................................................ 21 5.2. Sample Code ........................................................................................................................... 22 6 Appendix References ....................................................................................................................... 34 LC76F_I2C_Application_Note 4 / 34 GNSS Module Series Table Index Table 1: Function Description..................................................................................................................... 22 Table 2: Related Document........................................................................................................................ 34 Table 3: Terms and Abbreviations .............................................................................................................. 34 LC76F_I2C_Application_Note 5 / 34 GNSS Module Series Figure Index Figure 1: NMEA Data Reading Flow of the Master in Polling Mode............................................................ 9 Figure 2: Format of I2C Data Packet ........................................................................................................... 9 Figure 3: Type 1 (Valid Data Bytes + Garbage Bytes) ............................................................................... 10 Figure 4: Example of Type 1 (Valid Data Bytes + Garbage Bytes).............................................................11 Figure 5: Type 2 (All Garbage Bytes)......................................................................................................... 12 Figure 6: Example of Type 2 (All Garbage Bytes) ..................................................................................... 12 Figure 7: Type 3 (Garbage Bytes + Valid Data Bytes) ............................................................................... 13 Figure 8: Example of Type 3 (Garbage Bytes + Valid Data Bytes)............................................................ 13 Figure 9: Type 4 (Garbage Bytes + Valid Data Bytes + Garbage Bytes) .................................................. 14 Figure 10: Example of Type 4 (Garbage Bytes + Valid Data Bytes + Garbage Bytes) ............................. 14 Figure 11: Type 5 (Garbage Bytes + Valid Data Bytes + Garbage Bytes + Valid Data Bytes + Garbage Bytes) .................................................................................................................................................. 15 Figure 12: Example of Type 5 (Garbage Bytes + Valid Data Bytes + Garbage Bytes + Valid Data Bytes + Garbage Bytes) ................................................................................................................................... 15 Figure 13: Sequence Chart for Reading Data from I2C Buffer.................................................................. 18 Figure 14: Sequence Chart for Writing Data to I2C Buffer ........................................................................ 18 Figure 15: Flow Chart for Receiving and Parsing NMEA Sentence .......................................................... 21 LC76F_I2C_Application_Note 6 / 34 GNSS Module Series 1 Introduction This document introduces the I2C function and usage. The module working as a slave provides an I2C interface which outputs NMEA data read by a master (client-side MCU). The module’s I2C interface includes the following features: ⚫ Supports fast mode, with bit rate up to 400 kbps ⚫ Supports 7-bit address ⚫ Works in slave mode ⚫ Default slave address values: Write: 0x20, Read: 0x21 ⚫ I2C pins: I2C_SDA and I2C_SCL This document also provides a detailed introduction as well as a flow chart and sample code to illustrate how the master reads/parses NMEA sentences and sends PGKC commands via the I2C bus. LC76F_I2C_Application_Note 7 / 34 GNSS Module Series 2 NMEA Data Reading via I2C Bus This chapter provides a detailed introduction on how the master reads and parses NMEA data packets via I2C bus. The master can read a 4096-byte data packet via I2C bus at a time and the data needs to be processed because they are not always useful. 2.1. NMEA Data Reading Flow of the Master The slave’s I2C buffer has a capacity of 4096 bytes, which means that the master can read one I2C data packet of a maximum size of 4096 bytes at a time. In order to get complete NMEA packet of one second, the master needs to read several I2C data packets and then extracts valid NMEA data from them. After reading one I2C data packet, set the master to sleep for 2 ms before it starts to receive the next I2C data packet, as the slave needs 2 ms to upload new I2C data into the I2C buffer. When the entire NMEA packet of one second is read, the master can sleep for a longer time (e.g. 500 ms) to wait for the entire NMEA packet of next second to be ready. The NMEA data packet can be read via I2C bus only in polling mode. To avoid data loss, the master should read the entire NMEA packet of one second in a polling interval. The interval can be configured with PGKC101 according to the GNSS fix interval, and it should be less than the GNSS fix interval. See document [1] for details on PGKC101. The following figure illustrates how the master reads NMEA data packets via I2C in polling mode. LC76F_I2C_Application_Note 8 / 34 GNSS Module Series Master reads one I2C packet: 4096 bytes Sleep for 500 ms Sleep for 2 ms YES NO Entire NMEA packet of one second is read or not Figure 1: NMEA Data Reading Flow of the Master in Polling Mode NOTE The figure above assumes that the GNSS fix interval is 1 s, and the recommended polling interval is 500 ms. 2.2. I2C Data Packets 2.2.1. Format of I2C Data Packet The data packet in the slave’s I2C buffer (I2C data packet) includes 4095 valid NMEA bytes at most and one end character , so the master can read maximally a 4096-byte I2C data packet at a time. The following figure illustrates I2C data packet format. NMEA 0A Valid NMEA data,less than or equal to 4095 bytes End Char 0A Figure 2: Format of I2C Data Packet LC76F_I2C_Application_Note 9 / 34 GNSS Module Series 2.2.2. Five Types of I2C Data Packets Regardless of whether NMEA data are stored in the I2C buffer, the master can read one I2C data packet at a time (4096 bytes) from the slave. There are five types of I2C data packets that the master can read from the slave. 2.2.2.1. Type 1: Valid Data Bytes + Garbage Bytes When the I2C buffer has already stored some data, the master will read the stored data first, and then garbage bytes. If 4095 valid NMEA bytes are all saved in the buffer, the last byte will be the end character . NMEA Garbage bytes 0A One I2C packet, total 4096 bytes Figure 3: Type 1 (Valid Data Bytes + Garbage Bytes) For example, if the slave I2C buffer has stored 254-byte NMEA data, the 4096-byte I2C data packet read by the master includes 254 valid data bytes and 3842 garbage bytes. An example is shown below: LC76F_I2C_Application_Note 10 / 34 GNSS Module Series Offset 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 00000000 2C 34 30 2C 31 33 2C 36 30 2C 33 34 33 2C 33 38 Vaild NMEA data bytes 00000010 2C 31 2A 37 42 0D 0A 24 42 44 47 53 56 2C 34 2C 00000020 32 2C 31 35 2C 32 38 2C 36 30 2C 31 39 33 2C 34 00000030 31 2C 31 36 2C 35 31 2C 31 38 35 2C 33 38 2C 32 00000040 37 2C 34 39 2C 33 30 32 2C 34 30 2C 33 33 2C 34 00000050 35 2C 30 33 38 2C 34 30 2C 31 2A 37 32 0D 0A 24 00000060 42 44 47 53 56 2C 34 2C 33 2C 31 35 2C 30 31 2C 00000070 34 33 2C 31 33 35 2C 33 36 2C 30 39 2C 33 31 2C 00000080 31 39 35 2C 33 33 2C 31 34 2C 32 31 2C 30 35 32 00000090 2C 33 34 2C 33 32 2C 31 37 2C 32 35 35 2C 33 34 000000A0 2C 31 2A 37 30 0D 0A 24 42 44 47 53 56 2C 34 2C 000000B0 34 2C 31 35 2C 34 33 2C 31 34 2C 31 35 39 2C 2C 000000C0 32 34 2C 31 30 2C 30 38 32 2C 33 34 2C 32 35 2C 000000D0 31 30 2C 31 33 35 2C 33 32 2C 31 2A 34 34 0D 0A 000000E0 24 42 44 52 4D 43 2C 30 32 30 36 35 34 2E 30 30 000000F0 30 2C 41 2C 33 31 34 39 2E 33 33 32 31 34 0A 0A 00000100 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000110 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A Garbage bytes 00000120 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000FD0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000FE0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000FF0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00001000 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A ASCII ,40,13,60,343,38 ,1*7Bˑˑ$BDGSV,4, 2,15,28,60,193,4 1,16,51,185,38,2 7,49,302,40,33,4 5,038,40,1*72ˑˑ$ BDGSV,4,3,15,01, 43,135,36,09,31, 195,33,14,21,052 ,34,32,17,255,34 ,1*70ˑˑ$BDGSV,4, 4,15,43,14,159,, 24,10,082,34,25, 10,135,32,1*44ˑˑ $BDRMC,020654.00 0,A,3149.33214ˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ End char Figure 4: Example of Type 1 (Valid Data Bytes + Garbage Bytes) NOTE Why are garbage bytes ‘0A’? If the slave’s I2C buffer is empty, the slave (LC76F) will output the last valid byte repeatedly until new data is uploaded into I2C buffer, and '0A' is the last valid byte in the NMEA packet. 2.2.2.2. Type 2: All Garbage Bytes When the slave I2C buffer is empty, the master will read only garbage bytes. LC76F_I2C_Application_Note 11 / 34 GNSS Module Series Garbage bytes 0A One I2C packet, total 4096 bytes, all data are garbage bytes 0A Figure 5: Type 2 (All Garbage Bytes) Offset 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 00000000 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000010 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A Garbage bytes 00000020 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000030 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000040 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000050 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000060 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000070 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000080 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000090 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 000000A0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 000000B0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 000000C0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 000000D0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 000000E0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 000000F0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000100 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000110 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000120 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000FA0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000FB0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000FC0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000FD0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000FE0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000FF0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00001000 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A ASCII ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ Figure 6: Example of Type 2 (All Garbage Bytes) 2.2.2.3. Type 3: Garbage Bytes + Valid Data Bytes If the slave I2C buffer is empty when the master starts reading, but the slave starts uploading new data into the I2C buffer before the reading is over, the master will read garbage bytes first and then valid NMEA data bytes. LC76F_I2C_Application_Note 12 / 34 Garbage bytes 0A GNSS Module Series NMEA One I2C packet, total 4096 bytes Figure 7: Type 3 (Garbage Bytes + Valid Data Bytes) Offset 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 00000000 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A Garbage bytes 00000010 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000020 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000030 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000040 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000050 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000F00 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000F10 2C 34 30 2C 31 33 2C 36 30 2C 33 34 33 2C 33 38 00000F20 2C 31 2A 37 42 0D 0A 24 42 44 47 53 56 2C 34 2C Vaild NMEA data bytes 00000F30 32 2C 31 35 2C 32 38 2C 36 30 2C 31 39 33 2C 34 00000F40 31 2C 31 36 2C 35 31 2C 31 38 35 2C 33 38 2C 32 00000F50 37 2C 34 39 2C 33 30 32 2C 34 30 2C 33 33 2C 34 00000F60 35 2C 30 33 38 2C 34 30 2C 31 2A 37 32 0D 0A 24 00000F70 42 44 47 53 56 2C 34 2C 33 2C 31 35 2C 30 31 2C 00000F80 34 33 2C 31 33 35 2C 33 36 2C 30 39 2C 33 31 2C 00000F90 31 39 35 2C 33 33 2C 31 34 2C 32 31 2C 30 35 32 00000FA0 2C 33 34 2C 33 32 2C 31 37 2C 32 35 35 2C 33 34 00000FB0 2C 31 2A 37 30 0D 0A 24 42 44 47 53 56 2C 34 2C 00000FC0 34 2C 31 35 2C 34 33 2C 31 34 2C 31 35 39 2C 2C 00000FD0 32 34 2C 31 30 2C 30 38 32 2C 33 34 2C 32 35 2C 00000FE0 31 30 2C 31 33 35 2C 33 32 2C 31 2A 34 34 0D 0A 00000FF0 24 42 44 52 4D 43 2C 30 32 30 36 35 34 2E 30 30 00001000 30 2C 41 2C 33 31 34 39 2E 33 33 32 31 34 0A ASCII ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ,40,13,60,343,38 ,1*7Bˑˑ$BDGSV,4, 2,15,28,60,193,4 1,16,51,185,38,2 7,49,302,40,33,4 5,038,40,1*72ˑˑ$ BDGSV,4,3,15,01, 43,135,36,09,31, 195,33,14,21,052 ,34,32,17,255,34 ,1*70ˑˑ$BDGSV,4, 4,15,43,14,159,, 24,10,082,34,25, 10,135,32,1*44ˑˑ $BDRMC,020654.00 0,A,3149.33214ˑ Figure 8: Example of Type 3 (Garbage Bytes + Valid Data Bytes) 2.2.2.4. Type 4: Garbage Bytes + Valid Data Bytes + Garbage Bytes If the slave I2C buffer is empty when the master starts reading, and then new data are uploaded into the I2C buffer but is not full before reading is over, the master will read garbage bytes first, and then valid NMEA data bytes and finally the garbage bytes. LC76F_I2C_Application_Note 13 / 34 Garbage bytes 0A GNSS Module Series NMEA Garbage bytes 0A One I2C packet, total 4096 bytes Figure 9: Type 4 (Garbage Bytes + Valid Data Bytes + Garbage Bytes) Offset 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 00000000 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A Garbage bytes 00000010 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000D30 2C 34 30 2C 31 33 2C 36 30 2C 33 34 33 2C 33 38 00000D40 2C 31 2A 37 42 0D 0A 24 42 44 47 53 56 2C 34 2C Vaild NMEA data bytes 00000D50 32 2C 31 35 2C 32 38 2C 36 30 2C 31 39 33 2C 34 00000D60 31 2C 31 36 2C 35 31 2C 31 38 35 2C 33 38 2C 32 00000D70 37 2C 34 39 2C 33 30 32 2C 34 30 2C 33 33 2C 34 00000D80 35 2C 30 33 38 2C 34 30 2C 31 2A 37 32 0D 0A 24 00000D90 42 44 47 53 56 2C 34 2C 33 2C 31 35 2C 30 31 2C 00000DA0 34 33 2C 31 33 35 2C 33 36 2C 30 39 2C 33 31 2C 00000DB0 31 39 35 2C 33 33 2C 31 34 2C 32 31 2C 30 35 32 00000DC0 2C 33 34 2C 33 32 2C 31 37 2C 32 35 35 2C 33 34 00000DE0 2C 31 2A 37 30 0D 0A 24 42 44 47 53 56 2C 34 2C 00000DF0 34 2C 31 35 2C 34 33 2C 31 34 2C 31 35 39 2C 2C 00000E00 32 34 2C 31 30 2C 30 38 32 2C 33 34 2C 32 35 2C 00000E10 31 30 2C 31 33 35 2C 33 32 2C 31 2A 34 34 0D 0A 00000E20 24 42 44 52 4D 43 2C 30 32 30 36 35 34 2E 30 30 00000E30 30 2C 41 2C 33 31 34 39 2E 33 33 32 31 34 0A 0A 00000E40 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0AG0Aa0rAb0Aa0gA e0A b0Ay0tAe0sA 0A 0A 0A 0A 0A 0A 0A 00000FE0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00000FF0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 00001000 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A ASCII ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ,40,13,60,343,38 ,1*7Bˑˑ$BDGSV,4, 2,15,28,60,193,4 1,16,51,185,38,2 7,49,302,40,33,4 5,038,40,1*72ˑˑ$ BDGSV,4,3,15,01, 43,135,36,09,31, 195,33,14,21,052 ,34,32,17,255,34 ,1*70ˑˑ$BDGSV,4, 4,15,43,14,159,, 24,10,082,34,25, 10,135,32,1*44ˑˑ $BDRMC,020654.00 0,A,3149.33214ˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ Figure 10: Example of Type 4 (Garbage Bytes + Valid Data Bytes + Garbage Bytes) 2.2.2.5. Type 5: Garbage Bytes + Valid Data Bytes + Garbage Bytes + Valid Data Bytes + Garbage Bytes The master will read garbage bytes, the valid NMEA data bytes, garbage bytes, the valid NMEA data bytes, and garbage bytes sequentially. While the master is reading, the slave updates the new data into the I2C buffer two times. LC76F_I2C_Application_Note 14 / 34 GNSS Module Series Garbage bytes 0A NMEA Garbage bytes 0A NMEA Garbage bytes 0A One I2C packet, total 4096 bytes Figure 11: Type 5 (Garbage Bytes + Valid Data Bytes + Garbage Bytes + Valid Data Bytes + Garbage Bytes) Offset 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII Garbage bytes 00000000 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ 00000010 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ 00000B30 2C 34 30 2C 31 33 2C 36 30 2C 33 34 33 2C 33 38 ,40,13,60,343,38 Vaild NMEA data bytes 00000B40 2C 31 2A 37 42 0D 0A 24 42 44 47 53 56 2C 34 2C ,1*7Bˑˑ$BDGSV,4, 00000B50 32 2C 31 35 2C 32 38 2C 36 30 2C 31 39 33 2C 34 2,15,28,60,193,4 00000B60 31 2C 31 36 2C 35 31 2C 31 38 35 2C 33 38 2C 32 1,16,51,185,38,2 00000B70 37 2C 34 39 2C 33 30 32 2C 34 30 2C 33 33 2C 34 7,49,302,40,33,4 00000B80 35 2C 30 33 38 2C 34 30 2C 31 2A 37 32 0D 0A 24 5,038,40,1*72ˑˑ$ 00000B90 42 44 47 53 56 2C 34 2C 33 2C 31 35 2C 30 31 2C BDGSV,4,3,15,01, 00000BA0 34 33 2C 31 33 35 2C 33 36 2C 30 39 2C 33 31 2C 43,135,36,09,31, Garbage bytes 00000BB0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ 00000DB0 31 39 35 2C 33 33 2C 31 34 2C 32 31 2C 30 35 32 195,33,14,21,052 Vaild NMEA data bytes 00000DC0 2C 33 34 2C 33 32 2C 31 37 2C 32 35 35 2C 33 34 ,34,32,17,255,34 00000DE0 2C 31 2A 37 30 0D 0A 24 42 44 47 53 56 2C 34 2C ,1*70ˑˑ$BDGSV,4, 00000DF0 34 2C 31 35 2C 34 33 2C 31 34 2C 31 35 39 2C 2C 4,15,43,14,159,, 00000E00 32 34 2C 31 30 2C 30 38 32 2C 33 34 2C 32 35 2C 24,10,082,34,25, 00000E10 31 30 2C 31 33 35 2C 33 32 2C 31 2A 34 34 0D 0A 10,135,32,1*44ˑˑ 00000E20 24 42 44 52 4D 43 2C 30 32 30 36 35 34 2E 30 30 $BDRMC,020654.00 00000E30 30 2C 41 2C 33 31 34 39 2E 33 33 32 31 34 0A 0A 0,A,3149.33214ˑˑ Garbage bytes 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ 00000FF0 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ 00001000 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A 0A ˑˑˑˑˑˑˑˑˑˑˑˑˑˑˑ Figure 12: Example of Type 5 (Garbage Bytes + Valid Data Bytes + Garbage Bytes + Valid Data Bytes + Garbage Bytes) LC76F_I2C_Application_Note 15 / 34 GNSS Module Series 2.2.3. How to Extract Valid NMEA Data from Several I2C Packets After the master reads sufficient I2C data packets, it needs to parse and extract valid NMEA data from these packets. See Chapter 5.2 for the sample code provided by Quectel to extract the valid data. NOTE When extracting NMEA data from I2C packets, all ‘0A’ characters should be discarded. The ‘0A’ character may come in the forms of: 1. End character of an I2C packet. 2. Garbage bytes. 3. End character of an NMEA sentence. If it is discarded, there is no effect on NMEA sentence parsing. LC76F_I2C_Application_Note 16 / 34 GNSS Module Series 3 Sending Messages via I2C Bus The master can send the messages to the slave via I2C bus. See document [1] for detailed information on the messages. As the slave’s I2C buffer has a maximum capacity of 4096 bytes, each message inputted by the master should be 4096 bytes at most. The interval between two input messages cannot be less than 10 ms as the slave needs 10 ms to process the input data. LC76F_I2C_Application_Note 17 / 34 GNSS Module Series 4 Procedures for I2C Data Reading and Writing The chapter provides the sequence charts and sample code for I2C buffer reading and writing. 4.1. Sequence Charts The sequence charts for reading data from and writing data to the I2C buffer are shown below. S T A R T SDA M S B W R I DEVICE T ADDRESS E - 0x21 S T A ONE BYTE OF WORD R ADDRESS - 0x00 T LR A A S/ C C BW K K DEVICE ADDRESS - 0x21 R E A D A C DATA n K DUMMY WRITE S T O P N O A C K Figure 13: Sequence Chart for Reading Data from I2C Buffer S T A DEVICE R ADD RESS T - 0x20 SDA M S B W R I T E LR A S/ C BW K DATA n S T O P A C K Figure 14: Sequence Chart for Writing Data to I2C Buffer LC76F_I2C_Application_Note 18 / 34 GNSS Module Series 4.2. Sample Code The sample code for reading data from and writing data to the I2C buffer is shown below. #define MAX_I2C_BUF_SIZE #define EE_DEV_ADDR #define I2C_WR 0 #define I2C_RD 1 4096 0x20 //Shift the 7-bit slave address (0x10) 1 bit to the left. bool I2c_Master_Read_Bytes(uint8_t *Data,uint32_t length) { I2c_Start(); I2c_Send_Byte(EE_DEV_ADDR | I2C_WR); if(I2c_Wait_Ack() != ACK) { I2c_Stop(); return false; } I2c_Send_Byte(0x00); if (I2c_Wait_Ack() != ACK) { I2c_Stop(); return false; } I2c_Start(); I2c_Send_Byte(EE_DEV_ADDR | I2C_RD); if (I2c_Wait_Ack() != ACK) { I2c_Stop(); return false; } for(int i = 0; i < length; i++) { *(Data + i) = I2c_Read_Byte(); if(i != (length - 1)) { I2c_Ack(); } else { I2c_NAck(); LC76F_I2C_Application_Note 19 / 34 GNSS Module Series } } I2c_Stop(); return true; } bool I2c_Master_Write_Bytes(uint8_t Address, uint8_t *Data, uint8_t Length) { I2c_Stop(); I2c_Start(); I2c_Send_Byte(Address); if (I2c_Wait_Ack() != ACK) { I2c_Stop(); return false; } for(int i = 0; i < Length; i++) { I2c_Send_Byte(*(Data+i)); if (I2c_Wait_Ack() != ACK) { I2c_Stop(); return false; } } I2c_Stop(); return true; } LC76F_I2C_Application_Note 20 / 34 GNSS Module Series 5 Procedures for Receiving and Parsing NMEA Sentences This chapter provides the flow chart and sample code on how the master receives and parses NMEA sentences via I2C. 5.1. Flow Chart The flow chart on how the master receives and parses NMEA sentences is shown below. Main Thread RX Thread Init Queue iop_init_pcrx() Read I2C package: 4096 bytes Application Thread Put receive bytes into queue Parser : iop_pcrx_nmea() Wait to receive NMEA event Get available NMEA packet info: iop_inst_avail() Set Event One complete NMEA sentence received Get NMEA sentence: iop_get_inst() (buffer) Ex: $GPGGA *31 in buffer Wait for a certain milliseconds and read the next I2C packet (4096 bytes) Figure 15: Flow Chart for Receiving and Parsing NMEA Sentence LC76F_I2C_Application_Note 21 / 34 GNSS Module Series 5.2. Sample Code This chapter provides the sample code for receiving and parsing NMEA sentences. The master will parse the received NMEA and debug data so as to discard garbage bytes and extract valid data from multiple data packets. The functions used in the sample code are presented in the following table. Table 1: Function Description Function Name iop_init_pcrx() iop_inst_avail() iop_get_inst() iop_pcrx_nmea() iop_pcrx_nmea_dbg_hbd_bytes() Description Initializes reception queue. Gets available NMEA sentence information. Gets NMEA sentence data from queue buffer. Processes I2C packets, gets valid NMEA data and discards garbage bytes. Processes I2C packets, gets valid NMEA data, debugs log code and discards garbage bytes. The sample code for receiving and parsing I2C NMEA sentences is shown below. #define IOP_LF_DATA 0x0A // #define IOP_CR_DATA 0x0D // #define IOP_START_DBG 0x23 //Debug log start char ‘#’ #define IOP_START_NMEA 0x24 //NMEA start char ‘$’ #define IOP_START_HBD1 'H' //HBD debug log start char ‘H’ #define IOP_START_HBD2 'B' #define IOP_START_HBD3 'D' #define NMEA_ID_QUE_SIZE 0x0100 #define NMEA_RX_QUE_SIZE 0x8000 typedef enum { RXS_DAT_HBD, //Receive HBD data RXS_PRM_HBD2, //Receive HBD preamble 2 RXS_PRM_HBD3, //Receive HBD preamble 3 RXS_DAT, //Receive NMEA data RXS_DAT_DBG, //Receive DBG data RXS_ETX, //End-of-packet } RX_SYNC_STATE_T; struct LC76F_I2C_Application_Note 22 / 34 GNSS Module Series { short inst_id; //1 - NMEA, 2 - DBG, 3 - HBD short dat_idx; short dat_siz; } id_que[NMEA_ID_QUE_SIZE]; char rx_que[NMEA_RX_QUE_SIZE]; unsigned short id_que_head; unsigned short id_que_tail; unsigned short rx_que_head; RX_SYNC_STATE_T rx_state; unsigned int u4SyncPkt; unsigned int u4OverflowPkt; unsigned int u4PktInQueue; //Queue Functions BOOL iop_init_pcrx( void ) { /*---------------------------------------------------------variables ----------------------------------------------------------*/ short i; /*---------------------------------------------------------initialize queue indexes ----------------------------------------------------------*/ id_que_head = 0; id_que_tail = 0; rx_que_head = 0; /*---------------------------------------------------------initialize identification queue ----------------------------------------------------------*/ for( i=0; i< NMEA_ID_QUE_SIZE; i++) { id_que[i].inst_id = -1; id_que[i].dat_idx = 0; } /*---------------------------------------------------------initialize receiving state ----------------------------------------------------------*/ rx_state = RXS_ETX; /*---------------------------------------------------------initialize statistic information ----------------------------------------------------------*/ u4SyncPkt = 0; u4OverflowPkt = 0; u4PktInQueue = 0; LC76F_I2C_Application_Note 23 / 34 GNSS Module Series return TRUE; } /********************************************************************* * PROCEDURE NAME: * iop_inst_avail - Get available NMEA sentence information * * DESCRIPTION: * inst_id - NMEA sentence type * dat_idx - Start data index in queue * dat_siz - NMEA sentence size *********************************************************************/ BOOL iop_inst_avail(short *inst_id, short *dat_idx, short *dat_siz) { /*---------------------------------------------------------variables ----------------------------------------------------------*/ BOOL inst_avail; /*---------------------------------------------------------if packet is available then return id and index ----------------------------------------------------------*/ if ( id_que_tail != id_que_head ) { *inst_id = id_que[ id_que_tail ].inst_id; *dat_idx = id_que[ id_que_tail ].dat_idx; *dat_siz = id_que[ id_que_tail ].dat_siz; id_que[ id_que_tail ].inst_id = -1; id_que_tail = ++id_que_tail & (unsigned short)(NMEA_ID_QUE_SIZE - 1); inst_avail = TRUE; if (u4PktInQueue > 0) { u4PktInQueue--; } } else { inst_avail = FALSE; } return ( inst_avail ); } /* iop_inst_avail() end */ /********************************************************************* * PROCEDURE NAME: * iop_get_inst - Get available NMEA sentence from queue * LC76F_I2C_Application_Note 24 / 34 GNSS Module Series * DESCRIPTION: * idx - Start data index in queue * size - NMEA sentence size * data - Data buffer used to save NMEA sentence *********************************************************************/ void iop_get_inst(short idx, short size, void *data) { /*---------------------------------------------------------variables ----------------------------------------------------------*/ short i; unsigned char *ptr; /*---------------------------------------------------------copy data from the receive queue to the data buffer ----------------------------------------------------------*/ ptr = (unsigned char *)data; for (i = 0; i < size; i++) { *ptr = rx_que[idx]; ptr++; idx = ++idx & (unsigned short)(NMEA_RX_QUE_SIZE - 1); } } /* iop_get_inst() end */ /********************************************************************* * PROCEDURE NAME: * iop_pcrx_nmea - Receive NMEA code * * DESCRIPTION: * The procedure fetches the characters between '$' and (including '$' and ). * That is, characters and are skipped. * And the maximum size of the sentence fetched by this procedure is 256. * $xxxxxx*AA * *********************************************************************/ void iop_pcrx_nmea( unsigned char data ) { /*---------------------------------------------------------determine the receiving state ----------------------------------------------------------*/ if (data == IOP_LF_DATA){ return; } switch (rx_state) { LC76F_I2C_Application_Note 25 / 34 GNSS Module Series case RXS_DAT: switch (data) { case IOP_CR_DATA: //Count total number of sync packets u4SyncPkt += 1; id_que_head = ++id_que_head & (unsigned short)(NMEA_ID_QUE_SIZE - 1); if (id_que_tail == id_que_head) { //Count total number of overflow packets u4OverflowPkt += 1; id_que_tail = ++id_que_tail & (unsigned short)(NMEA_ID_QUE_SIZE - 1); } else { u4PktInQueue++; } rx_state = RXS_ETX; /*---------------------------------------------------------set RxEvent signaled ----------------------------------------------------------*/ SetEvent(hRxEvent); break; case IOP_START_NMEA: { //Restart NMEA sentence collection rx_state = RXS_DAT; id_que[id_que_head].inst_id = 1; id_que[id_que_head].dat_idx = rx_que_head; id_que[id_que_head].dat_siz = 0; rx_que[rx_que_head] = data; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; break; } default: rx_que[rx_que_head] = data; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; //If NMEA sentence length > 256, stop NMEA sentence collection. if (id_que[id_que_head].dat_siz == MAX_NMEA_STN_LEN) { id_que[id_que_head].inst_id = -1; rx_state = RXS_ETX; LC76F_I2C_Application_Note 26 / 34 GNSS Module Series } break; } break; case RXS_ETX: if (data == IOP_START_NMEA) { rx_state = RXS_DAT; id_que[id_que_head].inst_id = 1; id_que[id_que_head].dat_idx = rx_que_head; id_que[id_que_head].dat_siz = 0; rx_que[rx_que_head] = data; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; } break; default: rx_state = RXS_ETX; break; } } /* iop_pcrx_nmea() end */ /********************************************************************* * PROCEDURE NAME: * void iop_pcrx_nmea_dbg_hbd_bytes(unsigned char aData[], int i4NumByte) * Receive NMEA and debug log code * * DESCRIPTION: * The procedure fetch the characters between '$' and (including '$' and ). * That is, characters and are skipped. * And the maximum size of the sentence fetched by this procedure is 256. * $xxxxxx*AA * *********************************************************************/ void iop_pcrx_nmea_dbg_hbd_bytes(unsigned char aData[], int i4NumByte) { int i; unsigned char data; for (i = 0; i < i4NumByte; i++) { data = aData[i]; if (data == IOP_LF_DATA){ continue; } /*---------------------------------------------------------- LC76F_I2C_Application_Note 27 / 34 GNSS Module Series determine the receiving state ----------------------------------------------------------*/ switch (rx_state) { case RXS_DAT: switch (data) { case IOP_CR_DATA: //Count total number of sync packets u4SyncPkt += 1; id_que_head = ++id_que_head & (unsigned short)(NMEA_ID_QUE_SIZE - 1); if (id_que_tail == id_que_head) { //Count total number of overflow packets u4OverflowPkt += 1; id_que_tail = ++id_que_tail & (unsigned short)(NMEA_ID_QUE_SIZE - 1); } else { u4PktInQueue++; } rx_state = RXS_ETX; /*---------------------------------------------------------set RxEvent signaled ----------------------------------------------------------*/ SetEvent(hRxEvent); break; case IOP_START_NMEA: { //Restart NMEA sentence collection rx_state = RXS_DAT; id_que[id_que_head].inst_id = 1; id_que[id_que_head].dat_idx = rx_que_head; id_que[id_que_head].dat_siz = 0; rx_que[rx_que_head] = data; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; break; } case IOP_START_DBG: { //Restart DBG sentence collection LC76F_I2C_Application_Note 28 / 34 GNSS Module Series rx_state = RXS_DAT_DBG; id_que[id_que_head].inst_id = 2; id_que[id_que_head].dat_idx = rx_que_head; id_que[id_que_head].dat_siz = 0; rx_que[rx_que_head] = data; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; break; } default: rx_que[rx_que_head] = data; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; //If NMEA sentence bytes > 256, stop NMEA sentence collection. if (id_que[id_que_head].dat_siz == MAX_NMEA_STN_LEN) { id_que[id_que_head].inst_id = -1; rx_state = RXS_ETX; } break; } break; case RXS_DAT_DBG: switch (data) { case IOP_CR_DATA: //Count total number of sync packets u4SyncPkt += 1; id_que_head = ++id_que_head & (unsigned short)(NMEA_ID_QUE_SIZE - 1) if (id_que_tail == id_que_head) { //Count total number of overflow packets u4OverflowPkt += 1; id_que_tail = ++id_que_tail & (unsigned short)(NMEA_ID_QUE_SIZE - 1); } else { u4PktInQueue++; } rx_state = RXS_ETX; /*---------------------------------------------------------set RxEvent signaled ----------------------------------------------------------*/ SetEvent(hRxEvent); LC76F_I2C_Application_Note 29 / 34 GNSS Module Series break; case IOP_START_NMEA: { //Restart NMEA sentence collection rx_state = RXS_DAT; id_que[id_que_head].inst_id = 1; id_que[id_que_head].dat_idx = rx_que_head; id_que[id_que_head].dat_siz = 0; rx_que[rx_que_head] = data; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; break; } case IOP_START_DBG: { //Restart DBG sentence collection rx_state = RXS_DAT_DBG; id_que[id_que_head].inst_id = 2; id_que[id_que_head].dat_idx = rx_que_head; id_que[id_que_head].dat_siz = 0; rx_que[rx_que_head] = data; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; break; } default: rx_que[rx_que_head] = data; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; //If NMEA sentence length > 256, stop NMEA sentence collection. if (id_que[id_que_head].dat_siz == MAX_NMEA_STN_LEN) { id_que[id_que_head].inst_id = -1; rx_state = RXS_ETX; } break; } break; case RXS_DAT_HBD: switch (data) { case IOP_CR_DATA: LC76F_I2C_Application_Note 30 / 34 GNSS Module Series //Count total number of sync packets u4SyncPkt += 1; id_que_head = ++id_que_head & (unsigned short)(NMEA_ID_QUE_SIZE - 1); if (id_que_tail == id_que_head) { //Count total number of overflow packets u4OverflowPkt += 1; id_que_tail = ++id_que_tail & (unsigned short)(NMEA_ID_QUE_SIZE - 1); } else { u4PktInQueue++; } rx_state = RXS_ETX; /*---------------------------------------------------------set RxEvent signaled ----------------------------------------------------------*/ SetEvent(hRxEvent); break; case IOP_START_NMEA: { //Restart NMEA sentence collection rx_state = RXS_DAT; id_que[id_que_head].inst_id = 1; id_que[id_que_head].dat_idx = rx_que_head; id_que[id_que_head].dat_siz = 0; rx_que[rx_que_head] = data; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; break; } case IOP_START_DBG: { //Restart DBG sentence collection rx_state = RXS_DAT_DBG; id_que[id_que_head].inst_id = 2; id_que[id_que_head].dat_idx = rx_que_head; id_que[id_que_head].dat_siz = 0; rx_que[rx_que_head] = data; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; break; } LC76F_I2C_Application_Note 31 / 34 GNSS Module Series default: rx_que[rx_que_head] = data; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; //If NMEA sentence bytes > 256, stop NMEA sentence collection. if (id_que[id_que_head].dat_siz == MAX_NMEA_STN_LEN) { id_que[id_que_head].inst_id = -1; rx_state = RXS_ETX; } break; } break; case RXS_ETX: if (data == IOP_START_NMEA) { rx_state = RXS_DAT; id_que[id_que_head].inst_id = 1; id_que[id_que_head].dat_idx = rx_que_head; id_que[id_que_head].dat_siz = 0; rx_que[rx_que_head] = data; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; } else if (data == IOP_START_DBG) { rx_state = RXS_DAT_DBG; id_que[id_que_head].inst_id = 2; id_que[id_que_head].dat_idx = rx_que_head; id_que[id_que_head].dat_siz = 0; rx_que[rx_que_head] = data; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; } else if (data == IOP_START_HBD1) { rx_state = RXS_PRM_HBD2; } break; case RXS_PRM_HBD2: if (data == IOP_START_HBD2) { rx_state = RXS_PRM_HBD3; LC76F_I2C_Application_Note 32 / 34 GNSS Module Series } else { rx_state = RXS_ETX; } break; case RXS_PRM_HBD3: if (data == IOP_START_HBD3) { rx_state = RXS_DAT_HBD; //Start to collect the packet id_que[id_que_head].inst_id = 3; id_que[id_que_head].dat_idx = rx_que_head; id_que[id_que_head].dat_siz = 0; rx_que[rx_que_head] = IOP_START_HBD1; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; rx_que[rx_que_head] = IOP_START_HBD2; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; rx_que[rx_que_head] = IOP_START_HBD3; rx_que_head = ++rx_que_head & (unsigned short)(NMEA_RX_QUE_SIZE - 1); id_que[id_que_head].dat_siz++; } else { rx_state = RXS_ETX; } break; default: rx_state = RXS_ETX; break; } } } /* iop_pcrx_nmea_dbg_hbd_bytes() end */ LC76F_I2C_Application_Note 33 / 34 GNSS Module Series 6 Appendix References Table 2: Related Document Document Name [1] Quectel_LC76F_GNSS_Protocol_Specification Table 3: Terms and Abbreviations Abbreviation ACK GNSS I2C MCU NMEA SCL SDA Description Acknowledge Global Navigation Satellite System Inter-Integrated Circuit Microcontroller Unit National Marine Electronics Association Serial Clock Serial Data LC76F_I2C_Application_Note 34 / 34
353.59 KB
LTE-A(Q) Series GNSS Application Note LTE-A Module Series Version: 1.1 Date: 2021-11-24 Status: Released LTE-A Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. LTE-A(Q)_Series_GNSS_Application_Note 1 / 48 LTE-A Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2021. All rights reserved. LTE-A(Q)_Series_GNSS_Application_Note 2 / 48 LTE-A Module Series About the Document Revision History Version 1.0 1.1 Date 2019-10-12 2021-11-24 Author Amos ZHANG/ Leonard LI Remy SHI/ Don XU Description Initial 1. Incorporated the information of EP06, EG06, and EM06 GNSS AT commands manual into this application note 2. Added applicable modules: EG060K-EA, EG120K-EA, EM060K-GL, EM120R-GL, EM121R-GL, EM160R-GL and EG512R-EA (Chapter 1.1) 3. Updated supported NMEA sentences (Chapter 1.3) 4. Updated description of AT+QGPSCFG='glonassnmeatype' (Chapter 2.3.1.4) 5. Updated description of AT+QGPSCFG='beidounmeatype' and updated NMEA sentences corresponding to (Chapter 2.3.1.6) 6. Added the enabling of QZSS in description of in AT+QGPSCFG='gnssconfig (Chapter 2.3.1.7) 7. Added the default value of and in AT+QGPSCFG='lbsapn' (Chapter 2.3.1.12) 8. Updated the value of in AT+QGPSCFG='agnssprotocol' (Chapter 2.3.1.14) 9. Deleted AT+QGPSCFG='appidname' (Chapter 2.3.1.15) 10. Added AT+QGPSCFG='multibandconfig' (Chapter 2.3.1.15) 11. Modified the format of , and and the range of in AT+QGPSLOC (Chapter 2.3.5) 12. Deleted the Read Command in AT+QGPSSUPLCA LTE-A(Q)_Series_GNSS_Application_Note 3 / 48 LTE-A Module Series (Chapter 2.3.11) 13. Added the operation examples of AGNSS function (Chapter 3.4) LTE-A(Q)_Series_GNSS_Application_Note 4 / 48 LTE-A Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 5 Table Index................................................................................................................................................... 7 1 Introduction .......................................................................................................................................... 8 1.1. Applicable Modules ..................................................................................................................... 8 1.2. GNSS Turning On/off Procedures .............................................................................................. 9 1.3. Supported NMEA Sentence Types............................................................................................. 9 1.4. XTRA Assistance Introduction .................................................................................................. 10 2 Description of GNSS AT Commands ............................................................................................... 12 2.1. AT Command Introduction ........................................................................................................ 12 2.1.1. Definitions....................................................................................................................... 12 2.1.2. AT Command Syntax ..................................................................................................... 12 2.2. Declaration of AT Command Examples ................................................................................... 13 2.3. AT Commands Description ....................................................................................................... 13 2.3.1. AT+QGPSCFG Configure GNSS................................................................................ 13 2.3.1.1. AT+QGPSCFG='outport' Configure Output Port of NMEA Sentences.......... 14 2.3.1.2. AT+QGPSCFG='nmeasrc' Enable/Disable Acquisition of NMEA Sentences Through AT+QGPSGNMEA................................................................................................. 15 2.3.1.3. AT+QGPSCFG='gpsnmeatype' Configure Output Type of GPS NMEA Sentences ............................................................................................................................ 16 2.3.1.4. AT+QGPSCFG='glonassnmeatype' Configure Output Type of GLONASS or GNSS Multi-constellations NMEA Sentences...................................................................... 17 2.3.1.5. AT+QGPSCFG='galileonmeatype' Configure Output Type of Galileo NMEA Sentences ............................................................................................................................ 18 2.3.1.6. AT+QGPSCFG='beidounmeatype' Configure Output Type of BeiDou and QZSS NMEA Sentences ...................................................................................................... 19 2.3.1.7. AT+QGPSCFG='gnssconfig' Configure Enabled GNSS Constellations ....... 20 2.3.1.8. AT+QGPSCFG='autogps' Enable/Disable GNSS to Run Automatically ....... 21 2.3.1.9. AT+QGPSCFG='dpoenable' Enable/Disable DPO Mode.............................. 22 2.3.1.10. AT+QGPSCFG='plane' Configure Plane Mode Used by MO AGPS Session23 2.3.1.11. AT+QGPSCFG='suplver' Configure SUPL Protocol Version ........................ 24 2.3.1.12. AT+QGPSCFG='lbsapn' Configure LBS APN ............................................... 25 2.3.1.13. AT+QGPSCFG='agpsposmode' Configure AGNSS Positioning Mode ......... 26 2.3.1.14. AT+QGPSCFG='agnssprotocol' Configure AGNSS Positioning Protocol..... 27 2.3.1.15. AT+QGPSCFG='multibandconfig' Configure GNSS Multiband ..................... 28 2.3.2. AT+QGPSDEL Delete Assistance Data...................................................................... 29 2.3.3. AT+QGPS Turn On GNSS .......................................................................................... 30 2.3.4. AT+QGPSEND Turn Off GNSS .................................................................................. 32 2.3.5. AT+QGPSLOC Acquire Positioning Information......................................................... 32 2.3.6. AT+QGPSGNMEA Acquire NMEA Sentences ........................................................... 34 LTE-A(Q)_Series_GNSS_Application_Note 5 / 48 LTE-A Module Series 2.3.7. 2.3.8. 2.3.9. 2.3.10. 2.3.11. AT+QGPSXTRA Enable/Disable XTRA Assistance ................................................... 37 AT+QGPSXTRATIME Inject XTRA Time.................................................................... 37 AT+QGPSXTRADATA Inject XTRA Data File ............................................................ 39 AT+QGPSSUPLURL Configure SUPL Server URL ................................................... 40 AT+QGPSSUPLCA Inject SUPL Certificate ............................................................... 41 3 Examples ............................................................................................................................................ 42 3.1. Turn On/off GNSS..................................................................................................................... 42 3.2. Application of GNSS ........................................................................................... 42 3.3. Operation Procedures of XTRA Assistance ............................................................................. 43 3.4. Operation Procedures of AGNSS ............................................................................................. 43 4 Summary of Error Codes .................................................................................................................. 45 5 Appendix References ........................................................................................................................ 46 LTE-A(Q)_Series_GNSS_Application_Note 6 / 48 LTE-A Module Series Table Index Table 1: Applicable Modules ........................................................................................................................ 8 Table 2: Types of AT Commands .............................................................................................................. 12 Table 3: Format of PQGSV and PQGSA Sentences................................................................................. 20 Table 4: Summary of Error Codes ............................................................................................................. 45 Table 5: Related Documents...................................................................................................................... 46 Table 6: Terms and Abbreviations ............................................................................................................. 46 LTE-A(Q)_Series_GNSS_Application_Note 7 / 48 LTE-A Module Series 1 Introduction Quectel LTE-A(Q) series modules integrate the multi-GNSS engine which supports GPS, BeiDou, QZSS, Galileo, GLONASS systems and also XTRA (that is gpsOneXTRA) assistance technology. The high-performance GNSS engine is suitable for various application scenarios with low cost and accurate positioning requirements, and supports location tracking without any network assistance. This makes Quectel LTE-A(Q) series modules widely used in the following fields such as turn-by-turn navigation, asset tracking, personnel tracking, location-aware games, as well as home and fleet management. 1.1. Applicable Modules Table 1: Applicable Modules Module Series LTE-A(Q) Module EG06 Series EM06 Series EP06 Series EG060K-EA EG120K-EA EM060K-GL EG12 Series EM12-G EG18 Series EM120R-GL EM121R-GL EM160R-GL LTE-A(Q)_Series_GNSS_Application_Note 8 / 48 EG512R-EA LTE-A Module Series 1.2. GNSS Turning On/Off Procedures The GNSS of LTE-A(Q) series modules support location calculation without any network assistance. GNSS turning on/off procedures are shown below: Step 1: Configure GNSS parameters through AT+QGPSCFG. Step 2: Turn on GNSS through AT+QGPS. Step 3: Obatin the positioning information in any of the following three ways after turning on GNSS and fixing position successfully: 1) NMEA sentences are outputted to 'usbnmea' port by default and can be obtained by reading the port. 2) Obtain positioning information such as latitude, longitude, height, GNSS positioning mode, time, number of satellites directly through AT+QGPSLOC. 3) Set AT+QGPSCFG='nmeasrc',1 to enable acquisition of specified NMEA sentences through AT+QGPSGNMEA. The specified NMEA sentences cannot be acquired through AT+QGPSGNMEA if AT+QGPSCFG='nmeasrc',0 is set. Step 4: Turn off GNSS through AT+QGPSEND. 1.3. Supported NMEA Sentence Types The default NMEA sentences of the modules are compatible with NMEA 0183 protocol, and five kinds of prefixes are available to differentiate NMEA sentences of different satellite systems, as illustrated below. GNSS Multi-constellations NMEA sentences have the prefix 'GN': ⚫ GNGSA – GNSS DOP and active satellites ⚫ GNGNS – GNSS fix data GPS NMEA sentences have the prefix 'GP': ⚫ GPGGA – Global positioning system fix data, such as time, position, etc. ⚫ GPRMC – Recommended minimum specific GNSS data ⚫ GPGSV – GNSS satellites in view, such as number of satellites in view, satellite ID numbers, etc. ⚫ GPGSA – GNSS DOP and active satellites ⚫ GPVTG – Course over ground and ground speed LTE-A(Q)_Series_GNSS_Application_Note 9 / 48 LTE-A Module Series GLONASS NMEA sentences have the prefix 'GL': ⚫ GLGSV – GNSS satellites in view, such as number of satellites in view, satellite ID numbers, etc. Galileo NMEA sentences have the prefix 'GA': ⚫ GAGGA – Global positioning system fix data, such as time, position, etc. ⚫ GARMC – Recommended minimum specific GNSS data ⚫ GAGSV – GNSS satellites in view, such as number of satellites in view, satellite ID numbers, etc. ⚫ GAGSA – GNSS DOP and active satellites ⚫ GAVTG – Course over ground and ground speed BeiDou NMEA sentences have the prefix 'PQ': ⚫ PQGSV – GNSS satellites in view, such as number of satellites in view, satellite ID numbers, etc. ⚫ PQGSA – GNSS DOP and active satellites QZSS NMEA sentences have the prefix 'PQ': ⚫ PQGSV – GNSS satellites in view, such as number of satellites in view, satellite ID numbers, etc. ⚫ PQGSA – GNSS DOP and active satellites ⚫ NOTE 1. BeiDou and QZSS NMEA sentences of LTE-A(Q) series modules have the prefix 'PQ', which is an extended sentence based on NMEA 0183 V4.10 protocol. 2. For Galileo NMEA sentences of EG06, EM06 and EP06 series modules, only GAGSV is supported. 1.4. XTRA Assistance Introduction XTRA assistance technology enhances the performance of GNSS, and provides simplified GNSS assistance delivery, including ephemeris, almanac, ionosphere, UTC, health and coarse time assistance for GNSS engine. After activating XTRA assistance, the TTFF can be reduced by 18–30 s (or more in harsh environments with weak signals). The assistance data which is obtained from one of the XTRA assistance web servers needs to be updated before expiration. Before using this function, please make sure the valid XTRA assistance data is available first. It is necessary to download a new XTRA binary file which contains the valid XTRA assistance data from one of the XTRA assistance web servers through URLs listed below. LTE-A(Q)_Series_GNSS_Application_Note 10 / 48 LTE-A Module Series ⚫ The files named with suffix 'xtra2.bin' are for GPS + GLONASS: http://xtrapath4.izatcloud.net/xtra2.bin http://xtrapath5.izatcloud.net/xtra2.bin http://xtrapath6.izatcloud.net/xtra2.bin ⚫ The files named with suffix 'xtra3grc.bin' are for GPS + GLONASS + BeiDou: http://xtrapath4.izatcloud.net/xtra3grc.bin http://xtrapath5.izatcloud.net/xtra3grc.bin http://xtrapath6.izatcloud.net/xtra3grc.bin ⚫ The files named with suffix 'xtra3grcej.bin' are for GPS + GLONASS + BeiDou + Galileo: http://xtrapath4.izatcloud.net/xtra3grcej.bin http://xtrapath5.izatcloud.net/xtra3grcej.bin http://xtrapath6.izatcloud.net/xtra3grcej.bin NOTE Not all applicable modules of this document support GPS + GLONASS + BeiDou + Galileo system data files with the suffix 'xtra3grcej.bin'. Please contact Quectel Technical Supports for details. XTRA assistance data needs to be updated regularly. The status of XTRA data files can be queried through AT+QGPSXTRADATA? before updating. The operation procedures of XTRA assistance are shown as follows: Step 1: For EM06, EG06 and EP06 series modules, XTRA assistance is disabled by default; and for other applicable modules, XTRA assistance is enabled by default. If it is disabled, enable it through AT+QGPSXTRA=1. Step 2: Query and confirm the current validity of XTRA data file through AT+QGPSXTRADATA?. If the data is invalid, perform Step 3–6; if the data is valid, turn on GNSS engine according to the procedures described in Chapter 1.2 directly. Step 3: Download file with suffix 'xtra2.bin' or 'xtra3grc.bin' or 'xtra3grcej.bin' to the module via URLs listed above. Step 4: Inject the correct XTRA time to GNSS engine through AT+QGPSXTRATIME. Step 5: Inject the valid XTRA data file to GNSS engine through AT+QGPSXTRADATA. Step 6: Turn on GNSS engine according to the procedures described in Chapter 1.2 NOTE 1. GNSS engine needs to be turned off before Step 1. 2. For more detailed information of the AT commands mentioned above, please refer to Chapters 2.3.7, 2.3.8 and 2.3.9. LTE-A(Q)_Series_GNSS_Application_Note 11 / 48 LTE-A Module Series 2 Description of GNSS AT Commands 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals to its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 2: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of corresponding Write Command and return information about the type, value, or range of its parameter. Check the current parameter value of a corresponding Write Command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. LTE-A(Q)_Series_GNSS_Application_Note 12 / 48 LTE-A Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about how to use the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendation or suggestions about how you should design a program flow or what status you should set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there exists a correlation among these examples and that they should be executed in a given sequence. 2.3. AT Commands Description 2.3.1. AT+QGPSCFG Configure GNSS This command queries and configures various GNSS settings, including the output port and output types of NMEA sentences, etc. AT+QGPSCFG Configure GNSS Test Command AT+QGPSCFG=? Response +QGPSCFG: 'outport',(list of supported s) +QGPSCFG: 'nmeasrc',(list of supported s) +QGPSCFG: 'gpsnmeatype',(range of supported s) +QGPSCFG: 'glonassnmeatype',(range of supported s) +QGPSCFG: 'galileonmeatype',(range of supported s) +QGPSCFG: 'beidounmeatype',(range of supported s) +QGPSCFG: 'gnssconfig',(range of supported s) +QGPSCFG: 'autogps',(list of supported s) +QGPSCFG: 'dpoenable',(range of supported s) +QGPSCFG: 'plane',(range of supported s) +QGPSCFG: 'suplver',(range of supported s) +QGPSCFG: 'lbsapn',(range of supported s),(range of supported s), +QGPSCFG: 'agpsposmode',(range of supported s) +QGPSCFG: 'agnssprotocol',(range of supported s),(range of supported s) +QGPSCFG:'multibandconfig',(range of supported s) OK NOTE Only some of the applicable modules of this document supports the configuration of GNSS multiband through AT command. Please contact Quectel Technical Supports for details. 2.3.1.1. AT+QGPSCFG='outport' Configure Output Port of NMEA Sentences This command configures the output port of NMEA sentences. AT+QGPSCFG='outport' Configure Output Port of NMEA Sentences Write Command AT+QGPSCFG='outport'[,] Response If the optional parameter is omitted, query the current configuration: +QGPSCFG: 'outport', OK If the optional parameter is specified, configure the output port of NMEA sentences: OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. The configuration will be saved to NVRAM automatically. Parameter String type. Configure output port of NMEA sentences. 'none' Close NMEA sentence output 'usbnmea' Output through USB NMEA port LTE-A(Q)_Series_GNSS_Application_Note 14 / 48 LTE-A Module Series 'uartdebug' Output through Debug UART port The error code of operation. See Chapter 4 for details. 2.3.1.2. AT+QGPSCFG='nmeasrc' Enable/Disable Acquisition of NMEA Sentences Through AT+QGPSGNMEA This command enables/disables acquisition of NMEA sentences through AT+QGPSGNMEA. AT+QGPSCFG='nmeasrc' Enable/Disable Acquisition of NMEA Sentences Through AT+QGPSGNMEA Write Command Response AT+QGPSCFG='nmeasrc'[,] configuration: +QGPSCFG: 'nmeasrc', OK If the optional parameter is specified, configure whether to enable acquisition of NMEA sentences through AT+QGPSGNMEA: OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. The configuration will be saved to NVRAM automatically. Parameter Integer type. Set whether to acquire the original NMEA sentences through AT+QGPSGNMEA. If enabled, after executing AT+QGPSGNMEA, NMEA sentences are outputted through the AT port as a return value. 0 Disable 1 Enable The error code of operation. See Chapter 4 for details. LTE-A(Q)_Series_GNSS_Application_Note 15 / 48 LTE-A Module Series 2.3.1.3. AT+QGPSCFG='gpsnmeatype' Configure Output Type of GPS NMEA Sentences This command configures the type of GPS NMEA sentences that will be outputted. AT+QGPSCFG='gpsnmeatype' Configure Output Type of GPS NMEA Sentences Write Command AT+QGPSCFG='gpsnmeatype'[,] Response If the optional parameter is omitted, query the current configuration: +QGPSCFG: 'gpsnmeatype', OK If the optional parameter is specified, configure the output type of GPS NMEA sentences: OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. The configuration will be saved to NVRAM automatically. Parameter Integer type. Configure output type of GPS NMEA sentences by XOR operation. 0 Disable 1 GPGGA 2 GPRMC 4 GPGSV 8 GPGSA 16 GPVTG 31 All the five types of sentences The error code of operation. See Chapter 4 for details. LTE-A(Q)_Series_GNSS_Application_Note 16 / 48 LTE-A Module Series 2.3.1.4. AT+QGPSCFG='glonassnmeatype' Configure Output Type of GLONASS or GNSS Multi-constellations NMEA Sentences This command configures the output type of GLONASS or GNSS Multi-constellations NMEA sentences. AT+QGPSCFG='glonassnmeatype' Configure Output Type of GLONASS or GNSS Multi-constellations NMEA Sentences Write Command AT+QGPSCFG='glonassnmeatype'[, ] Response If the optional parameter is omitted, query the current configuration: +QGPSCFG: 'glonassnmeatype', OK Maximum Response Time Characteristics If the optional parameter is specified, configure the output type of GLONASS or GNSS Multi-constellations NMEA sentences: OK Or ERROR If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. The configuration will be saved to NVRAM automatically. Parameter Integer type. Configure output type of GLONASS or GNSS Multi-constellations NMEA sentences by XOR operation. 0 Disable 1 GLGSV 2 GNGSA 4 GNGNS The error code of operation. See Chapter 4 for details. LTE-A(Q)_Series_GNSS_Application_Note 17 / 48 LTE-A Module Series 2.3.1.5. AT+QGPSCFG='galileonmeatype' Configure Output Type of Galileo NMEA Sentences This command configures the output type of Galileo NMEA sentences. AT+QGPSCFG='galileonmeatype' Configure Output Type of Galileo NMEA Sentences Write Command AT+QGPSCFG='galileonmeatype'[,< Galileo_NMEA_type>] Response If the optional parameter is omitted, query the current configuration: +QGPSCFG: 'galileonmeatype', OK If the optional parameter is specified, configure the output type of Galileo NMEA sentences: OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. The configuration will be saved to NVRAM automatically. Parameter Integer type. Configure output type of Galileo NMEA sentences by XOR operation. For EG06, EM06 and EP06 series modules, the supported values are as follows: 0 Disable 1 GAGSV For other applicable modules, the supported values are as follows: 0 Disable 1 GAGGA 2 GARMC 4 GAGSV 8 GAGSA 16 GAVTG The error code of operation. See Chapter 4 for details. LTE-A(Q)_Series_GNSS_Application_Note 18 / 48 LTE-A Module Series 2.3.1.6. AT+QGPSCFG='beidounmeatype' Configure Output Type of BeiDou and QZSS NMEA Sentences This command configures the output type of BeiDou and QZSS NMEA sentences. AT+QGPSCFG='beidounmeatype' Configure Output Type of BeiDou and QZSS NMEA Sentences Write Command AT+QGPSCFG='beidounmeatype'[, ] Response If the optional parameter is omitted, query the current configuration: +QGPSCFG: 'beidounmeatype', OK If the optional parameter is specified, configure the output type of BeiDou and QZSS NMEA sentences: OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. The configuration will be saved to NVRAM automatically. Parameter Integer type. Configure output type of BeiDou and QZSS NMEA sentences by XOR operation. 0 Disable 1 PQGSA 2 PQGSV The error code of operation. See Chapter 4 for details. NOTE This command configures the output type of BeiDou and QZSS NMEA sentences synchronously. For example, AT+QGPSCFG='beidounmeatype',1 indicates to configure the output type of BeiDou and QZSS NMEA sentences as PQGSA synchronously. LTE-A(Q)_Series_GNSS_Application_Note 19 / 48 LTE-A Module Series Table 3: Format of PQGSV and PQGSA Sentences Type PQGSV PQGSA Format $PQGSV,,,,,,,,...,, ,,,,* $PQGSA,,,,…,,,,,< SysID>* Parameter Total number of sentences. Range: 1–9. Sentence number. Range: 1–9. Total number of satellites in view. Range: 0–36. Satellite ID. Elevation degrees. Maximum: 90°. Azimuth degrees. Range: 000°–359°. Signal-to-noise ratio. Range: 00–99. Unit: dB-Hz. Null if not tracked. Signal ID. 0 indicates all signals. System ID. 4 BeiDou 5 QZSS Checksum. Fix mode 1. M Manual mode, force to 2D or 3D positioning A Automatic mode, automatically switch to 2D or 3D positioning. Fix mode 2. 1 No positioning 2 2D positioning 3 3D positioning. Position dilution of precision. Horizontal dilution of precision. Vertical dilution of precision. 2.3.1.7. AT+QGPSCFG='gnssconfig' Configure Enabled GNSS Constellations This command configures the enabled GNSS constellations of the module. LTE-A(Q)_Series_GNSS_Application_Note 20 / 48 LTE-A Module Series AT+QGPSCFG='gnssconfig' Configure Enabled GNSS Constellations Write Command AT+QGPSCFG='gnssconfig'[,] Response If the optional parameter is omitted, query the current configuration: +QGPSCFG: 'gnssconfig', OK If the optional parameter is specified, configure the enabled GNSS constellations: OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect after the module is rebooted. The configuration will be saved to NVRAM automatically. Parameter Integer type. Configure enabled GNSS constellations. GPS is always ON. 0 GLONASS OFF/BeiDou and QZSS OFF/Galileo OFF 1 GLONASS ON/BeiDou and QZSS ON/Galileo ON 2 GLONASS ON/BeiDou and QZSS ON/Galileo OFF 3 GLONASS ON/BeiDou and QZSS OFF/Galileo ON 4 GLONASS ON/BeiDou and QZSS OFF/Galileo OFF 5 GLONASS OFF/BeiDou and QZSS ON/Galileo ON 6 GLONASS OFF/BeiDou and QZSS OFF/Galileo ON 7 GLONASS OFF/BeiDou and QZSS ON/Galileo OFF The error code of operation. See Chapter 4 for details. 2.3.1.8. AT+QGPSCFG='autogps' Enable/Disable GNSS to Run Automatically This command enable/disable the automatic running of GNSS after the module is rebooted. AT+QGPSCFG='autogps' Enable/Disable GNSS to Run Automatically Write Command Response AT+QGPSCFG='autogps'[,] If the optional parameter is omitted, query the current LTE-A(Q)_Series_GNSS_Application_Note 21 / 48 LTE-A Module Series Maximum Response Time Characteristics configuration: +QGPSCFG: 'autogps', OK If the optional parameter is specified, enable/disable automatic running of GNSS: OK Or ERROR If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect after the module is rebooted. The configuration will be saved to NVRAM automatically. Parameter Integer type. Enable or disable GNSS to run automatically after the module is powered on. 0 Disable 1 Enable The error code of operation. See Chapter 4 for details. NOTE GNSS can only run automatically in standalone mode. 2.3.1.9. AT+QGPSCFG='dpoenable' Enable/Disable DPO Mode This command enables/disables the DPO mode. AT+QGPSCFG='dpoenable' Enable/Disable DPO Mode Write Command AT+QGPSCFG='dpoenable'[,] Response If the optional parameter is omitted, query the current configuration: +QGPSCFG: 'dpoenable', OK LTE-A(Q)_Series_GNSS_Application_Note 22 / 48 LTE-A Module Series Maximum Response Time Characteristics If the optional parameter is specified, enable/disable the DPO mode: OK Or ERROR If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect after the module is rebooted. The configuration will be saved to NVRAM automatically. Parameter Integer type. Enable/disable DPO. 0 Disable DPO 1 Enable DPO with dynamic duty cycle 2 Enable DPO only when the module is not connected to an external power supply (not running on battery) The error code of operation. See Chapter 4 for details. 2.3.1.10. AT+QGPSCFG='plane' Configure Plane Mode Used by MO AGPS Session This command configures the plane mode (control plane or user plane) to be used by the Mobile-Originated (MO) AGPS session. AT+QGPSCFG='plane' Configure Plane Mode Used by MO AGPS Session Write Command AT+QGPSCFG='plane'[,] Response If the optional parameter is omitted, query the current configuration: +QGPSCFG: 'plane', OK If the optional parameter is specified, configure the plane mode used by MO AGPS session: OK Or ERROR LTE-A(Q)_Series_GNSS_Application_Note 23 / 48 LTE-A Module Series Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect after the module is rebooted. The configuration will be saved to NVRAM automatically. Parameter Integer type. Plane mode used by MO AGPS session. 0 User plane without SSL 1 User plane with SSL 2 Control plane The error code of operation. See Chapter 4 for details. 2.3.1.11. AT+QGPSCFG='suplver' Configure SUPL Protocol Version This command configures the SUPL version in an SI (SET Initiated) session, and the most likely used SUPL version in an NI (Network Initiated) session. AT+QGPSCFG='suplver' Configure SUPL Protocol Version Write Command AT+QGPSCFG='suplver'[,] Response If the optional parameter is omitted, query the current configuration: +QGPSCFG: 'suplver', OK If the optional parameter is specified, configure the SUPL protocol version: OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect after the module is rebooted. The configuration will be saved to NVRAM automatically. LTE-A(Q)_Series_GNSS_Application_Note 24 / 48 LTE-A Module Series Parameter Integer type. SUPL protocol version. 1 SUPL V1.0 2 SUPL V2.0 3 SUPL V2.0.2 The error code of operation. See Chapter 4 for details. 2.3.1.12. AT+QGPSCFG='lbsapn' Configure LBS APN This command configures LBS APN. AT+QGPSCFG='lbsapn' Configure LBS APN Write Command AT+QGPSCFG='lbsapn'[,,,] Response If the optional parameters are omitted, query the current configuration: +QGPSCFG: 'lbsapn',,, OK If the optional parameters are specified, configure the LBS APN: OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect after the module is rebooted. The configuration will be saved to NVRAM automatically. Parameter Integer type. Configure the serving system of LBS APN by XOR operation. Range: 0–31. 0 Disable 1 CDMA 2 HDR 4 GSM 8 WCDMA LTE-A(Q)_Series_GNSS_Application_Note 25 / 48 LTE-A Module Series 16 LTE Integer type. PDP type of the LBS APN profile. 0 Disable 1 IPv4 2 IPv6 3 IPv4v6 4 PPP String type. Access point name. The error code of operation. See Chapter 4 for details. 2.3.1.13. AT+QGPSCFG='agpsposmode' Configure AGNSS Positioning Mode This command configures the AGNSS positioning mode. AT+QGPSCFG='agpsposmode' Configure AGNSS Positioning Mode Write Command AT+QGPSCFG='agpsposmode'[,] Response If the optional parameter is omitted, query the current configuration: +QGPSCFG: 'agpsposmode', OK If the optional parameter is specified, configure the AGNSS positioning mode: OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect after the module is rebooted. The configuration will be saved to NVRAM automatically. Parameter Integer type. AGNSS positioning mode. Each bit indicates a specified mode and see the following figure for details. Only bit 16 is relevant to enabling of autonomous fallback for SUPL-MSB. Setting bit to 1 enables the corresponding mode. Range: 0–33554431. Default value: 33488767 or 775. LTE-A(Q)_Series_GNSS_Application_Note 26 / 48 LTE-A Module Series The error code of operation. See Chapter 4 for details. NOTE When the China Unicom/China Telecom/China Mobile (U)SIM card is inserted, the default value of is 775. When any other card is inserted, the default value of is 33488767. 2.3.1.14. AT+QGPSCFG='agnssprotocol' Configure AGNSS Positioning Protocol This command configures the AGPS LPP positioning protocol and AGLONASS positioning protocol. AT+QGPSCFG='agnssprotocol' Configure AGNSS Positioning Protocol Write Command AT+QGPSCFG='agnssprotocol'[,,] Response If the optional parameters are omitted, query the current configuration: +QGPSCFG: 'agnssprotocol',, OK If the optional parameters are specified, configure AGPS LPP LTE-A(Q)_Series_GNSS_Application_Note 27 / 48 LTE-A Module Series Maximum Response Time Characteristics positioning protocol and AGLONASS positioning protocol: OK Or ERROR If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect after the module is rebooted. The configuration will be saved to NVRAM automatically. Parameter Integer type. Configure the AGPS LPP positioning protocol by XOR operation. 0 Disable ALL 1 User Plane LPP 2 Control Plane LPP 3 User Plane LPP and Control Plane LPP Integer type. Configure AGLONASS positioning protocol by XOR operation. Default value: 1286. 0 Disable ALL 1 Control Plane RRLP 2 Control Plane RRC 4 Control Plane LPP 256 User Plane RRLP 1024 User Plane LPP The error code of operation. See Chapter 4 for details. 2.3.1.15. AT+QGPSCFG='multibandconfig' Configure GNSS Multiband This command configures the GNSS multiband. AT+QGPSCFG='multibandconfig' Configure GNSS Multiband Write Command AT+QGPSCFG='multibandconfig',[< multiband>] Response If the optional parameter is omitted, query the current configuration: +QGPSCFG: 'multibandconfig', OK If the optional parameter is specified, configure the GNSS LTE-A(Q)_Series_GNSS_Application_Note 28 / 48 LTE-A Module Series Maximum Response Time Characteristics multiband: OK Or ERROR If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect after the module is rebooted. The configuration will be saved to NVRAM automatically. Parameter Integer type. GNSS multiband (in addition to L1) by XOR operation. Enable the corresponding band when bit is set to 1; disable the corresponding band when bit is set to 0. 0 Disable 1 GPS L5 2 Galileo E5a 4 Beidou B2a The error code of operation. See Chapter 4 for details. NOTE Only some of the applicable modules of this document supports the configuration of GNSS multiband through AT command. Please contact Quectel Technical Supports for details. 2.3.2. AT+QGPSDEL Delete Assistance Data This command deletes assistance data to perform cold start, hot start and warm start of GNSS. The command can only be executed when GNSS is turned off. After deleting the assistance data through this command, you can enforce the cold start of GNSS through AT+QGPS. Hot/warm start can also be performed if the corresponding conditions are satisfied. AT+QGPSDEL Delete Assistance Data Test Command AT+QGPSDEL=? Response +QGPSDEL: (range of supported s) Write Command AT+QGPSDEL= OK Response OK LTE-A(Q)_Series_GNSS_Application_Note 29 / 48 Maximum Response Time Characteristics LTE-A Module Series Or ERROR If there is any error related to ME functionality: +CME ERROR: 300 ms / Parameter Integer type. The type of GNSS assistance data to be deleted. 0 Delete all assistance data. Enforce cold start after starting GNSS. 1 Do not delete any data. Perform hot start if the conditions are satisfied after starting GNSS. 2 Delete some related data. Perform warm start if the conditions are satisfied after starting GNSS. 3 Delete the XTRA assistance data injected into GNSS engine. The error code of operation. See Chapter 4 for details. 2.3.3. AT+QGPS Turn On GNSS The command turns on GNSS. AT+QGPS Turn On GNSS Test Command AT+QGPS=? Response EG06, EM06 and EP06 series modules: +QGPS: (range of supported s),(range of supported s),(range of supported s),(range of supported s),(range of supported s) OK Other applicable modules: +QGPS: (range of supported s),(range of supported s),(range of supported s),(range of supported s) Read Command Read current GNSS state OK Response +QGPS: LTE-A(Q)_Series_GNSS_Application_Note 30 / 48 LTE-A Module Series AT+QGPS? OK Write Command EG06, EM06 and EP06 series modules AT+QGPS=[,[,[,[,]]]] Response OK Or ERROR If there is any error related to ME functionality: +CME ERROR: Write Command Other applicable modules AT+QGPS=[,[,[,]]] Response OK Or ERROR If there is any error related to ME functionality: +CME ERROR: Maximum Response Time 300 ms Characteristics The command takes effect immediately. The configurations will not be saved. Parameter Integer type. GNSS state. 0 GNSS OFF 1 GNSS ON Integer type. GNSS working mode. 1 Standalone 2 MSB 3 MSA 4 Quick positioning Integer type. Maximum positioning time, which includes the response time of GNSS receiver while measuring the GNSS pseudo range and the upper time limit of GNSS satellite searching. It also includes the time for demodulating the ephemeris data and calculating the position. Range: 1–255. Default value: 30. Unit: second. Integer type. Positioning accuracy threshold. Range: 1–1000. Default value: 50. Unit: meter. Integer type. Horizontal accuracy level. 1 Low accuracy 2 Medium accuracy 3 High accuracy Integer type. Count of positioning attempts. Range: 0–1000. Default value: 0. LTE-A(Q)_Series_GNSS_Application_Note 31 / 48 LTE-A Module Series 0 indicates continuous positioning; other value indicates the actual count of positioning attempts. Integer type. Interval time between each positioning. Range: 1–65535. Default value: 1. Unit: second. Integer type. Interval time between each positioning. Range: 100–65535. Default value: 1000. Unit: ms. The error code of operation. See Chapter 4 for details. 2.3.4. AT+QGPSEND Turn Off GNSS This command turns off GNSS. AT+QGPSEND Turn Off GNSS Test Command AT+QGPSEND=? Execution Command AT+QGPSEND Response OK Response OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms / Parameter The error code of operation. See Chapter 4 for details. 2.3.5. AT+QGPSLOC Acquire Positioning Information This command acquires positioning infomration. Before executing the command, turn on GNSS through AT+QGPS. If GNSS positioning fails, +CME ERROR: is returned to indicate the corresponding situation. AT+QGPSLOC Acquire Positioning Information Test Command AT+QGPSLOC=? Response +QGPSLOC: ,,,,,(list of supported s),,,, LTE-A(Q)_Series_GNSS_Application_Note 32 / 48 Write Command AT+QGPSLOC= Maximum Response Time Characteristics LTE-A Module Series , OK Response +QGPSLOC: ,,,,,,,,,, OK Or ERROR If there is any error related to ME functionality: +CME ERROR: 300 ms / Parameter Integer type. Latitude and longitude display format. 0 , format: ddmm.mmmmN/S,dddmm.mmmmE/W 1 , format: ddmm.mmmmmm,N/S,dddmm.mmmmmm,E/W 2 , format: (-)dd.ddddd,(-)ddd.ddddd UTC time. Format: hhmmss.ss. Latitude. If is 0: Format: ddmm.mmmmN/S dd Degree. Range: 00–89 mm.mmmm Minute. Range: 00.0000–59.9999 N/S North latitude/South latitude If is 1: Format: ddmm.mmmmmm,N/S dd Degree. Range: 00–89 mm.mmmmmm Minute. Range: 00.000000–59.999999 N/S North latitude/South latitude If is 2: Format: (-)dd.ddddd dd.ddddd Degree. Range: -89.99999–89.99999 - South latitude Longitude. If is 0: LTE-A(Q)_Series_GNSS_Application_Note 33 / 48 LTE-A Module Series Format: dddmm.mmmmE/W ddd Degree. Range: 000–179 mm.mmmm Minute. Range: 00.0000–59.9999 E/W East longitude/West longitude If is 1: Format: dddmm.mmmmmm,E/W ddd Degree. Range: 000–179 mm.mmmmmm Minute. Range: 00.000000–59.999999 E/W East longitude/West longitude If is 2: Format: (-)ddd.ddddd ddd.ddddd Degree. Range: -179.99999–179.99999 - West longitude Horizontal precision. Range: 0.5–99.9. Altitude of the antenna away from the sea level. Accurate to one decimal place. Unit: meter. Integer type. GNSS positioning mode. 2 2D positioning 3 3D positioning Course Over Ground based on true north. Format: x.x. Unit: degree. Range: 0.0–359.9. Speed over ground. Format: x.x. Unit: km/h. Accurate to one decimal place. Speed over ground. Format: x.x. Unit: knots. Accurate to one decimal place. UTC time when fixing position. Format: ddmmyy. dd Day mm Month yy Year Number of active satellites. Range: 00–80. Fixed as two-digit number. The error code of operation. See Chapter 4 for details. 2.3.6. AT+QGPSGNMEA Acquire NMEA Sentences This command acquires NMEA sentences. Before using this command, turn on GNSS through AT+QGPS, and set to 1 to enable acquisition of NMEA sentences through AT+QGPSGNMEA. The sentence output can be disabled through AT+QGPSCFG='gpsnmeatype',0, AT+QGPSCFG='glonassnmeatype',0, AT+QGPSCFG='galileonmeatype',0 and AT+QGPSCFG='beidounmeatype',0. If sentence output is disabled, AT+QGPSGNMEA can still be used to acquire NMEA sentences on condition that the GNSS has already acquired sentences through this command after its activation. LTE-A(Q)_Series_GNSS_Application_Note 34 / 48 LTE-A Module Series AT+QGPSGNMEA Acquire NMEA Sentences Test Command AT+QGPSGNMEA=? Response +QGPSGNMEA: (list of supported s) Write Command Query GGA sentence AT+QGPSGNMEA='GGA' OK Response [+QGPSGNMEA: ] […] OK Or ERROR Write Command Query RMC sentence AT+QGPSGNMEA='RMC' If there is any error related to ME functionality: +CME ERROR: Response [+QGPSGNMEA: ] […] OK Or ERROR Write Command Query GSV sentence AT+QGPSGNMEA='GSV' If there is any error related to ME functionality: +CME ERROR: Response [+QGPSGNMEA: ] […] OK Or ERROR Write Command Query GSA sentence AT+QGPSGNMEA='GSA' If there is any error related to ME functionality: +CME ERROR: Response [+QGPSGNMEA: ] […] OK Or ERROR LTE-A(Q)_Series_GNSS_Application_Note 35 / 48 LTE-A Module Series Write Command Query VTG sentence AT+QGPSGNMEA='VTG' Write Command Query GNS sentence AT+QGPSGNMEA='GNS' Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: Response [+QGPSGNMEA: ] […] OK Or ERROR If there is any error related to ME functionality: +CME ERROR: Response [+QGPSGNMEA: ] […] OK Or ERROR If there is any error related to ME functionality: +CME ERROR: 300 ms / Parameter NMEA sentence type. 'GGA' GGA sentence 'RMC' RMC sentence 'GSV' GSV sentence 'GSA' GSA sentence 'VTG' VTG sentence 'GNS' GNS sentence GGA sentence. RMC sentence. GSV sentence. GSA sentence. VTG sentence. GNS sentence. The error code of operation. See Chapter 4 for details. LTE-A(Q)_Series_GNSS_Application_Note 36 / 48 LTE-A Module Series 2.3.7. AT+QGPSXTRA Enable/Disable XTRA Assistance This command enables/disables XTRA assistance. AT+QGPSXTRA Enable/Disable XTRA Assistance Test Command AT+QGPSXTRA=? Response +QGPSXTRA: (list of supported s) Read Command AT+QGPSXTRA? OK Response +QGPSXTRA: Write Command AT+QGPSXTRA= OK Response OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. The configuration will be saved to NVRAM automatically. Parameter Integer type. Enable/disable XTRA assistance. For EM06, EG06 and EP06 series modules, XTRA assistance is disabled by default; and for other applicable modules, XTRA assistance is enabled by default. 0 Disable 1 Enable The error code of operation. See Chapter 4 for details. 2.3.8. AT+QGPSXTRATIME Inject XTRA Time This command injects XTRA time to GNSS engine. Before using the command, enable XTRA assistance through AT+QGPSXTRA=1. After the feature is activated, the GNSS engine asks for XTRA time and assistance data file. Before injecting XTRA data file, inject XTRA time first through this command. LTE-A(Q)_Series_GNSS_Application_Note 37 / 48 LTE-A Module Series AT+QGPSXTRATIME Inject XTRA Time Test Command AT+QGPSXTRATIME=? Response EG06, EM06 and EP06 series modules: +QGPSXTRATIME: ,(list of supported s),(list of supported s), OK Other applicable modules: +QGPSXTRATIME: , OK Write Command EG06, EM06 and EP06 series modules AT+QGPSXTRATIME=,[,[,,]] Response OK Or ERROR Write Command Other applicable modules AT+QGPSXTRATIME=, If there is any error related to ME functionality: +CME ERROR: Response OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. The configuration will not be saved. Parameter Integer type. Operation type. 0 Inject XTRA time String type. Time to be injected. For EG06, EM06 and EP06 series modules, the time type is defined by . For other applicable modules, the time type is UTC time. Format: 'YYYY/MM/DD,hh:mm:ss'. For example, '2019/01/05,08:30:30'. Integer type. Time type. 0 GPS time 1 UTC time LTE-A(Q)_Series_GNSS_Application_Note 38 / 48 LTE-A Module Series Integer type. Whether to force the GNSS subsystem to accept the injected time. 0 Do not force 1 Force Integer type. Uncertainty of time. It indicates the time difference between sending a request to the SNTP server and receiving a response from the SNTP server. Default value: 3500. Unit: ms. The error code of operation. See Chapter 4 for details. 2.3.9. AT+QGPSXTRADATA Inject XTRA Data File This command injects a XTRA assistance data file to GNSS engine. Before executing this command, please enable the XTRA assistance through AT+QGPSXTRA=1, then store the valid XTRA data file in UFS of the module through AT+QFUPL and inject the XTRA time to GNSS engine through AT+QGPSXTRATIME. After finishing all these operations, you can execute AT+QGPSXTRADATA to inject the XTRA assistance data file to GNSS engine. After executing this command successfully, you can delete the XTRA data file from UFS through AT+QFDEL. Whether the XTRA data file is injected successfully can be queried through AT+QGPSXTRADATA?. AT+QGPSXTRADATA Inject XTRA Data File Test Command AT+QGPSXTRADATA=? Response +QGPSXTRADATA: Read Command Query the status of XTRA data files AT+QGPSXTRADATA? OK Response +QGPSXTRADATA: , OK Or ERROR If there is any error related to ME functionality: +CME ERROR: Write Command AT+QGPSXTRADATA= Response OK Or ERROR If there is any error related to ME functionality: +CME ERROR: LTE-A(Q)_Series_GNSS_Application_Note 39 / 48 LTE-A Module Series Maximum Response Time Characteristics 1 s The command takes effect immediately. The configuration will be saved to NVRAM automatically. Parameter 'xtra2.bin' or 'xtra3grc.bin'. Integer type. Valid time of the injected XTRA data file. Unit: minute. 0 No XTRA file or the file is overdue 1440 For 1-day XTRA data file 4320 For 3-day XTRA data file 10080 For 7-day XTRA data file String type. Starting time of the validity period of the injected XTRA data file. Format: 'YYYY/MM/DD,hh:mm:ss', for example, '2016/01/03,15:34:50'. The error code of operation. See Chapter 4 for details. 2.3.10. AT+QGPSSUPLURL Configure SUPL Server URL This command configures the SUPL server URL. AT+QGPSSUPLURL Configure SUPL Server URL Test Command AT+QGPSSUPLURL=? Response +QGPSSUPLURL: Read Command Query the current SUPL server URL AT+QGPSSUPLURL? Write Command AT+QGPSSUPLURL= OK Response +QGPSSUPLURL: OK Response OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. The configuration will be saved to NVRAM automatically. LTE-A(Q)_Series_GNSS_Application_Note 40 / 48 LTE-A Module Series Parameter String type. SUPL server address. The address format is ':', where the can be omitted, for example, 'supl.server.com', '123.123.123.123' or 'supl.server.com:7275'. When the is omitted, the default value (7275) is used. The error code of operation. See Chapter 4 for details. 2.3.11. AT+QGPSSUPLCA Inject SUPL Certificate This command injects SUPL certificate. The certificate file to be injected should be put into file system by AT+QFUPL. The certificate is obtained from the operator or the server provider. AT+QGPSSUPLCA Inject SUPL Certificate Test Command AT+QGPSSUPLCA=? Response +QGPSSUPLCA: ,(range of supported s) Write Command AT+QGPSSUPLCA=[,] OK Response OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms / Parameter String type. Name of the SUPL certificate. Integer type. SUPL certificate ID. Range: 0–9. Default value: 0. The error code of operation. See Chapter 4 for details. LTE-A(Q)_Series_GNSS_Application_Note 41 / 48 LTE-A Module Series 3 Examples 3.1. Turn On/Off GNSS Default parameters are used in this example to turn on GNSS. After turning on GNSS, NMEA sentences are outputted from 'usbnmea' port by default; and GNSS can be turned off through AT+QGPSEND. AT+QGPS=1 //Set GNSS working mode to standalone and turn on GNSS. OK //After turning on GNSS, NMEA sentences are outputted from 'usbnmea' port by default. AT+QGPSLOC=0 //Obtain positioning information. +QGPSLOC: 061951.00,3150.7223N,11711.9293E,0.7,62.2,2,0.0,0.0,0.0,110513,09 OK AT+QGPSEND OK //Turn off GNSS. 3.2. Application of GNSS When GNSS is turned on and is set to 1, NMEA sentences can be acquired directly through AT+QGPSGNMEA. AT+QGPSCFG='nmeasrc',1 //Set to 1 to enable acquisition of NMEA sentences through AT+QGPSGNMEA. OK AT+QGPSGNMEA='GGA' //Obtain GGA sentence. +QGPSGNMEA: $GPGGA,103647.000,3150.721154,N,11711.925873,E,1,02,4.7,59.8,M,-2.0,M,,*77 OK AT+QGPSCFG='nmeasrc',0 //Set to 0 to disable acquisition of NMEA sentences through AT+QGPSGNMEA. OK AT+QGPSGNMEA='GGA' //Obtain GGA sentence. +CME ERROR: 507 //Because acquisition of NMEA sentences through AT+QGPSGNMEA is disabled, the GGA sentences cannot be obtained. LTE-A(Q)_Series_GNSS_Application_Note 42 / 48 LTE-A Module Series 3.3. Operation Procedures of XTRA Assistance This example shows the operation procedures of XTRA assistance. For information about FILE commands used to upload a file to UFS or delete a file from UFS, please refer to document [1]. AT+QGPSXTRA=1 //If XTRA assistance is disabled, enable it first and then perform the following procedures. OK //The XTRA assistance function is activated immediately. //If XTRA data file is valid (query through AT+QGPSXTRADATA?), turn on GNSS engine directly. //If XTRA data file is invalid (query through AT+QGPSXTRADATA?), perform the following procedures. //Users can download the XTRA data file to PC (or MCU) from URLs listed in Chapter 1.4. AT+QFUPL='UFS:xtra2.bin',59748,60 //Select a XTRA file and upload it to the module through QCOM. For more details about QCOM tool, please refer to document [2]. OK AT+QGPSXTRATIME='2019/01/05,08:30:30',3500 //Inject XTRA time to GNSS engine. The accuracy of the injected UTC time should be within 3.5 s. OK AT+QGPSXTRADATA='UFS:xtra2.bin' //Inject XTRA data file. OK //The XTRA data file is injected to GNSS engine successfully. AT+QFDEL='UFS:xtra2.bin' //Delete XTRA data file from UFS. This step is optional. OK AT+QGPS=1 //Turn on GNSS engine. OK 3.4. Operation Procedures of AGNSS This example shows the operation procedures of AGNSS. Please turn on the AGNSS function through AT+QGPSCFG='agpsposmode' before use. For information about FILE commands used to upload a file to UFS or delete a file from UFS, please refer to document [1]. AT+QGPSDEL=0 OK AT+QGPSCFG='plane',1 OK AT+CFUN=1,1 //Delete all the assistance data. //Set the plane mode used by MO AGPS session as user plane with SSL. If no certificate is needed for the service, configure the plane mode through AT+QGPSCFG='plane',0. //Restart the module. LTE-A(Q)_Series_GNSS_Application_Note 43 / 48 LTE-A Module Series OK AT+QGPSSUPLURL='supl.xxxx.com:7275' //Set the URL and port of SUPL service. The 'supl.xxxx.com' is an example which should be replaced by a real URL; and 7275 is the default port of SUPL service. OK AT+QFUPL='UFS:supl.xxxx.com.der',893 //Upload CA certificate. The 'supl.xxxx.com.der' is an example which should be replaced by a real CA certificate; and 893 is the size of 'supl.xxxx.com.der', which should be replaced by the size of the real CA certificate. This step can be omitted if the service requires no certificate. OK AT+QGPSSUPLCA='UFS:supl.xxxx.com.der' //Inject CA certificate. The 'supl.xxxx.com.der' is an example which should be replaced by a real CA certificate. OK AT+QFDEL='UFS:supl.xxxx.com.der' //Delete the certificate from UFS. This step is optional. OK AT+QGPS=2 //Turn on GNSS in MSB mode. This step needs to be performed after completing the configuration of network. After turning on GNSS, positioning can be completed in 10 seconds through the module. If there is a large time deviation, it indicates that the AGNSS does not take effect. OK LTE-A(Q)_Series_GNSS_Application_Note 44 / 48 LTE-A Module Series 4 Summary of Error Codes The indicates an error related to GNSS operation. The details about are described in the following table. Table 4: Summary of Error Codes Numeric Value 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 549 Verbose Value Invalid parameter(s) Operation not supported GNSS subsystem busy Session is ongoing Session not active Operation timeout Function not enabled Time information error XTRA not enabled XTRA file open error Bad CRC for XTRA data file Validity time is out of range Internal resource error GNSS locked End by E911 Not fixed now CMUX port is not opened Unknown error LTE-A(Q)_Series_GNSS_Application_Note 45 / 48 LTE-A Module Series 5 Appendix References Table 5: Related Documents Document Name [1] Quectel_LTE-A(Q)_Series_FILE_Application_Note [2] Quectel_QCOM_User_Guide Table 6: Terms and Abbreviations Abbreviation AGPS AGNSS APN BeiDou CDMA CMUX COG CRC DOP DPO Galileo GGA GLONASS GNS Description Assisted Global Positioning System Assisted Global Navigation Satellite System Access Point Name BeiDou Navigation Satellite System Code-Division Multiple Access Connection Multiplexing Course Over Ground Cyclic Redundancy Check Dilution of Precision Dynamic Power Optimization Galileo Satellite Navigation System Global Positioning System Fix Data Global Navigation Satellite System Global Network Service LTE-A(Q)_Series_GNSS_Application_Note 46 / 48 GNSS GPS GSA GSM GSV HDOP HDR ID IPv4 IPv6 LBS LPP LTE MCU ME MO MS MSA MSB NMEA NVRAM PC PDOP PDP PPP LTE-A Module Series Global Navigation Satellite System Global Positioning System GPS DOP and Active Satellites Global System for Mobile Communications Satellites in View Horizontal Dilution of Precision High Data Rate Identifier Internet Protocol version 4 Internet Protocol version 6 Location Based Services LTE Positioning Protocol Long-Term Evolution Micro Control Unit Mobile Equipment Mobile-Originated Mobile Station Mobile Station Assisted Mobile Station Based National Marine Electronics Association 0183 Interface Standard Non-Volatile Random Access Memory Private Computer Position Dilution of Precision Packet Data Protocol Point to Point Protocol LTE-A(Q)_Series_GNSS_Application_Note 47 / 48 RMC RRC RRLP SET SNR SNTP SSL SUPL TTFF UART UFS URL USB (U)SIM UTC VDOP VTG WCDMA XTRA LTE-A Module Series Recommended Minimum Specific GNSS Data Radio Resource Control Radio Resource Location Services Protocol SUPL Enabled Terminal Signal Noise Ratio Simple Network Time Protocol Secure Sockets Layer Secure User Plane Location Time to First Fix Universal Asynchronous Receiver & Transmitter User File System Uniform Resource Locator Universal Serial Bus (Universal) Subscriber Identity Module Universal Time Code Vertical Dilution of Precision Course Over Ground and Ground Speed Wideband Code Division Multiple Access An Auxiliary Positioning Technology Provided by Qualcomm LTE-A(Q)_Series_GNSS_Application_Note 48 / 48
556.61 KB
Lx0&Lx6&LC86L&LG77L AGNSS Application Note GNSS Module Series Version: 1.2 Date: 2022-05-09 Status: Released GNSS Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 1 / 47 GNSS Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 2 / 47 GNSS Module Series About the Document Document Information Title Lx0&Lx6&LC86L&LG77L AGNSS Application Note Subtitle GNSS Module Series Document Type Application Note Document Status Released Revision History Version 1.0 Date 2017-04-28 2017-04-28 1.1 2021-11-22 1.2 2022-05-09 Description Creation of the document First official release 1. Modified the structure of the document. 2. Added information on Host EPO including the difference between Host EPO and Flash EPO, AGNSS implementation with Host EPO and relevant example, and Host EPO testing with QGNSS. 3. Added applicable modules (L26, L76, L76-L, L86, L96, L26-LB, L76-LB, L70, L80, L70-R, L80-R, LC86L and LG77L). 4. Added AGNSS requirements (Chapter 1.3). 5. Added the structure of Binary Protocol (Figure 5). 6. Added the description of Binary Protocol fields (Table 6). 7. Added AGNSS procedure with Flash EPO and description of the procedure (Chapter 3.1.3). 8. Added the following messages PMTK127, PMTK713, PMTK721, PMTK740 and PMTK741 (Chapter 4). 9. Added the content of Flash EPO testing with QGNSS (Chapter 5.1). 10. Added the example on Flash EPO implementation (Chapter 6.1). 11. Deleted the description of error handing in data transfer procedure. 1. Added a note for MTK_BIN_ACK_EPO (Chapter 3.1.1.1). Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 3 / 47 GNSS Module Series 2. Modified the description of Result in MTK_BIN_EPO (Table 13). 3. Added optional extended parameters for PMTK_ACK (Chapter 4.1). Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 4 / 47 GNSS Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 5 Table Index................................................................................................................................................... 7 Figure Index ................................................................................................................................................. 8 1 Introduction .......................................................................................................................................... 9 1.1. Differences Between Host EPO and Flash EPO....................................................................... 9 1.2. Applicable Modules ................................................................................................................. 10 1.3. AGNSS Requirements............................................................................................................. 11 2 Download of EPO Files...................................................................................................................... 12 2.1. Get EPO Files from Server...................................................................................................... 12 2.2. EPO Files Format .................................................................................................................... 13 2.2.1. EPO Files Format – GPS Only ...................................................................................... 13 2.2.2. EPO Files Format – GPS + GLONASS ......................................................................... 14 2.3. Types of EPO Files .................................................................................................................. 15 2.4. Recommended Download Procedures of EPO Files .............................................................. 16 2.5. The Validity Period of EPO Files ............................................................................................. 16 3 AGNSS Implementation..................................................................................................................... 18 3.1. AGNSS with Flash EPO .......................................................................................................... 18 3.1.1. Binary Protocol ............................................................................................................... 18 3.1.1.1. MTK_BIN_EPO (MsgID = 723)............................................................................... 19 3.1.1.2. MTK_BIN_ACK_EPO (Msg = 2) ............................................................................. 20 3.1.1.3. Change UART Format Packet (MsgID = 253) ........................................................ 21 3.1.1.4. ACK Packet (MsgID = 1)......................................................................................... 22 3.1.2. EPO Data Transfer Protocol .......................................................................................... 23 3.1.2.1. Pseudo Code for EPO Data Transfer Protocol ....................................................... 23 3.1.3. AGNSS Procedure with Flash EPO ............................................................................... 26 3.2. AGNSS with Host EPO............................................................................................................ 27 3.2.1. Recommended Sequence for Host EPO ....................................................................... 27 3.2.2. Sample Code of Sending EPO ...................................................................................... 28 4 AGNSS Related Messages ................................................................................................................ 31 4.1. PMTK001 PMTK_ACK ............................................................................................................ 31 4.2. PMTK127 PMTK_CMD_CLEAR_EPO.................................................................................... 31 4.3. PMTK253 PMTK_SET_OUTPUT_FMT .................................................................................. 32 4.4. PMTK607 PMTK_Q_EPO_INFO ............................................................................................ 33 4.5. PMTK707 PMTK_DT_EPO_INFO .......................................................................................... 34 4.6. PMTK713 PMTK_DT_LOC ..................................................................................................... 35 4.7. PMTK721 PMTK_DT_SV_EPO .............................................................................................. 36 4.8. PMTK740 PMTK_DT_UTC ..................................................................................................... 37 4.9. PMTK741 PMTK_DT_POS ..................................................................................................... 37 Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 5 / 47 GNSS Module Series 5 EPO Usage Through QGNSS ............................................................................................................ 39 5.1. Testing Flash EPO with QGNSS ............................................................................................. 39 5.2. Testing Host EPO with QGNSS............................................................................................... 41 6 AGNSS Implementation Example..................................................................................................... 43 6.1. Flash EPO Implementation...................................................................................................... 43 6.2. Host EPO Implementation ....................................................................................................... 44 7 Appendix References ........................................................................................................................ 47 Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 6 / 47 GNSS Module Series Table Index Table 1: Differences Between Flash EPO and Host EPO ........................................................................... 9 Table 2: Type of EPO Supported on Applicable Modules .......................................................................... 10 Table 3: AGNSS Related Commands .........................................................................................................11 Table 4: Download URL of EPO Files ........................................................................................................ 12 Table 5: Types of EPO Files ....................................................................................................................... 15 Table 6: Description of Binary Protocol Fields ........................................................................................... 19 Table 7: MTK_BIN_EPO Format ................................................................................................................ 19 Table 8: Format for MTK_BIN_EPO with 2 SAT Data................................................................................ 20 Table 9: Format for MTK_BIN_EPO with 1 SAT Data................................................................................ 20 Table 10: Format for MTK_BIN_EPO with No SAT Data ........................................................................... 20 Table 11: Description of MTK_BIN_EPO Fields......................................................................................... 20 Table 12: MTK_BIN_ACK_EPO Format .................................................................................................... 21 Table 13: Description of MTK_BIN_ACK_EPO Fields ............................................................................... 21 Table 14: Format for Change UART Format Packet.................................................................................. 21 Table 15: Description of Change UART Format Packet Fields.................................................................. 22 Table 16: ACK Packet Format .................................................................................................................... 22 Table 17: Description of ACK Packet Fields .............................................................................................. 23 Table 18: Almanac, Ephemeris and EPO................................................................................................... 47 Table 19: Terms and Abbreviations ............................................................................................................ 47 Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 7 / 47 GNSS Module Series Figure Index Figure 1: EPO Files Format – GPS Only ................................................................................................... 13 Figure 2: Format for Several Segments of EPO Files ............................................................................... 14 Figure 3: EPO Files Format – GPS + GLONASS ...................................................................................... 14 Figure 4: Recommended Download Procedures of EPO Files ................................................................. 16 Figure 5: Structure of Binary Protocol........................................................................................................ 18 Figure 6: AGNSS Procedure with Flash EPO ............................................................................................ 26 Figure 7: Recommended Sequence for Host EPO.................................................................................... 28 Figure 8: AGNSS Setting Interface of QGNSS .......................................................................................... 39 Figure 9: EPO File Downloading................................................................................................................ 40 Figure 10: Static TTFF Testing ................................................................................................................... 40 Figure 11: TTFF Setting ............................................................................................................................. 41 Figure 12: Static TTFF Testing ................................................................................................................... 41 Figure 13: TTFF Setting ............................................................................................................................. 42 Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 8 / 47 GNSS Module Series 1 Introduction EPOTM (Extended Prediction Orbit) is an AGNSS feature provided by the chipset supplier, which can improve sensitivity and shorten TTFF. This document mainly describes the download of EPOTM files, AGNSS implementation, EPOTM related PMTK commands and how to evaluate the EPOTM functionality through QGNSS tool. 1.1. Differences Between Host EPO and Flash EPO Both Flash EPO and Host EPO allow the GNSS receiver to achieve a shorter TTFF, but their differences make each of them suitable for different applications. Host EPO (also called Real Time AGNSS) allows the receiver to store in RAM up to 6 hours of assistance data which are sent to the receiver through NMEA PMTK commands listed in Chapter 4. For Host EPO, there is no data retention after the GNSS receiver reboots and the data should be re-downloaded. Flash EPO, on the other hand, allows the receiver to store in flash 7 or 14 days’ assistance data which are sent to the receiver through Binary Protocol defined by the chipset supplier. Flash EPO enables the receiver to reuse all assistance information stored in flash before the information expires. See Chapter 2.5 for the validity period of EPO files. Table 1: Differences Between Flash EPO and Host EPO Item Storage Space Storage Capacity Protocol Flash EPO Flash 7 or 14 days’ assistance data Binary Host EPO RAM 6 hours’ assistance data NMEA Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 9 / 47 GNSS Module Series NOTE The maximum period that EPO data can be stored in flash is 14 days for GPS-only EPO files, and 7 days for GPS+GLONASS EPO files. If a 30-day GPS-only EPO file is sent, only the first 14 days of EPO data will be stored. If a 30-day GPS+GLONASS EPO file is sent, only the first 7 days of EPO data will be stored. 1.2. Applicable Modules Not all the applicable modules support both Flash EPO and Host EPO. See the following table for the applicable modules of this document and the type of EPO supported on each module. Table 2: Type of EPO Supported on Applicable Modules Series Lx0 Lx6 LC86L LG77L Module L70 L80 L70-R L80-R L26 L76 L76-L L86 L96 L26-LB L76-LB LC86L LG77L Flash EPO Host EPO Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 10 / 47 GNSS Module Series 1.3. AGNSS Requirements The host needs to provide the Reference Time, Reference Position and EPO data to the GNSS receiver. The information provided by the host needs to meet the following requirements so that the GNSS receiver can make better use of EPO: ⚫ The Reference Time should be accurate within 3 s and must be specified in UTC time. ⚫ The Reference Position should be accurate within 30 km from the receiver actual location. Keep in mind that if the receiver’s view of the sky is limited, the accuracy of the Reference Position needs to be increased. ⚫ The EPO data should be valid. The receiver can benefit from any of the assistance data to improve the TTFF. All assistance data (Reference Time, Reference Position and EPO data) are useful but none of them are mandatory. If some of them are unavailable or have expired, it is recommended to avoid using them. The host can send the Reference Time, Reference Position and EPO data to the GNSS receiver through the messages listed in following table. See Chapter 4 for a detailed description of these messages. Table 3: AGNSS Related Commands Packet Type PMTK713 PMTK721 PMTK740 PMTK741 Data Content Reference Position. GPS/GLONASS EPO data for a single satellite. Reference UTC Time. Reference Time and Position. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 11 / 47 GNSS Module Series 2 Download of EPO Files Quectel does not provide any Service Level Agreement for EPO files. Quectel is asking users to download EPO data to their own servers and send them to devices so as to ensure the availability of EPO data. 2.1. Get EPO Files from Server Table 4: Download URL of EPO Files EPO Type Unified QEPO Unified QEPO EPO EPO GNSS Type GPS only GPS + GLONASS GPS only GPS + GLONASS EPO File URL File Name http://wpepodownload.mediatek.com/ QGPS.DAT?vendorinfo http://wpepodownload.mediatek.com/ QG_R.DAT?vendorinfo http://wpepodownload.mediatek.com/ EPO_GPS_3_X.DAT?vendorinfo http://wpepodownload.mediatek.com/ EPO_GR_3_X.DAT?vendorinfo Single name: QGPS.DAT Single name: QG_R.DAT X = 1–10 EPO_GPS_3_1.DAT to EPO_GPS_3_10.DAT X = 1–10 EPO_GR_3_1.DAT to EPO_GR_3_10.DAT The following shows a complete URL sample: http://wpepodownload.mediatek.com/QGPS.DAT?vendor=AAA&project=BBB&device_id=CCC ⚫ The query string starts with '?' and is separated by '&'. ⚫ The values of 'vendor' and 'project' (AAA, BBB in the example) are issued by Quectel, contact Quectel Technical Support to get the value. ⚫ The value of 'device_id' (CCC in the example) contains two parts – one is assigned by Quectel and the other assigned by users. For example: if CCC = XXX_YYY, the value XXX is provided by Quectel and users can contact Quectel Technical Support to get the value, while YYY can be assigned by users and it must be a unique value, such as IMEI. Each device must have a unique ID. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 12 / 47 GNSS Module Series NOTE As there can be a maximum of 30 days’ predictions, there will be up to 10 files. Slices of 30-day EPO: _1 for days 1 to 3, _2 for days 4 to 6, ... _10 for days 28 to 30. 2.2. EPO Files Format This part mainly illustrates the format of EPO files for GPS only and for GPS + GLONASS. 2.2.1. EPO Files Format – GPS Only Day1 Day2 ... Day29 Day30 EPO Format (1 day) Segment UTC Segment1 0:00-6:00 Segment2 6:00-12:00 Segment3 12:00-18:00 Segment4 18:00-24:00 EPO Format (1 Segment) SV1 SV2 ... SV31 SV32 EPO Format (1 SV) Data GPS_Hour ... Byte offset 0[LSB]~2[MSB] 3 Data ... Byte offset ... ... 4~7 ... 64~67 ... 8~11 CheckSum 68~71 Figure 1: EPO Files Format – GPS Only GPS_Secs = GPS_Hour * 3600 GPS_Week Number = GPS_Secs / 604800 GPS TOW = GPS_Secs % 604800 Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 13 / 47 SAT data SAT data GNSS Module Series An EPO file contains GPS Time (GPS_Week, GPS_Hour and GPS_Secs). The maximum unit in GPS Time is GPS week which starts at approximately midnight of January 5th to 6th, 1980. The following figure illustrates the format for several segments of EPO files. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 EPO SET 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 EPO SET 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 EPO SET Figure 2: Format for Several Segments of EPO Files The basic unit of an EPO file is SAT Data and the size of each SAT Data is 72 bytes. One EPO SET contains 32 SAT Data, so the data size of an EPO SET is 2304 bytes. Each EPO file contains several EPO SETs, so the file size must be a multiple of 2304 bytes. An EPO SET is valid for 6 hours. Therefore, there will be 4 EPO SETs for one day. 2.2.2. EPO Files Format – GPS + GLONASS SAT data SAT data 1 2 1 2 31 32 65 66 31 32 65 66 87 88 87 88 1 2 31 32 65 66 87 88 GPS EPO SET GLONASS EPO SET Figure 3: EPO Files Format – GPS + GLONASS The basic unit of an EPO file is SAT Data, and the size of a SAT Data is 72 bytes. In GPS + GLONASS EPO files, one EPO SET contains 56 SAT Data, so the data size for an EPO SET is 4032 bytes. Each Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 14 / 47 GNSS Module Series EPO file contains several EPO SETs. The file size must be a multiple of 4032 bytes. An EPO SET is valid for 6 hours. Therefore, there will be 4 EPO SETs for one day. 2.3. Types of EPO Files The EPO data can be downloaded in the form of files. Users can select the most suitable file to download based on the availability of a data connection and storage space of the application. See Table 4: Download URL of EPO Files and Table 5: Types of EPO Files to decide on the file type to be downloaded. Table 5: Types of EPO Files EPO Type Unified QEPO GNSS Type GPS only Unified QEPO GPS + GLONASS EPO EPO GPS only GPS + GLONASS Description 6-hour prediction orbit (ephemeris). Single file containing the latest GPS EPO data available. 6-hour prediction orbit (ephemeris). Single file containing the latest GPS + GLONASS EPO data available. 3-30 days’ prediction orbit (ephemeris). Split in 10 files and each contains 3-day information. 3-30 days’ prediction orbit (ephemeris). Split in 10 files and each contains 3-day information. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 15 / 47 GNSS Module Series 2.4. Recommended Download Procedures of EPO Files Set daily timer to check EPO effectiveness Daily timer expires Power on GNSS receiver Will EPO files expire today?1) Yes Download 3-day EPO files for back up Have valid EPO files?3) Yes No Download unified QEPO files EPO aiding with backup file Verify downloaded Data2) Verify downloaded data Position fixed Backup prepared EPO files Position fixed Figure 4: Recommended Download Procedures of EPO Files NOTE 1. Users must know the current UTC time so as to download the valid EPO files. 2. Download MD5 checksum file by replacing file extension 'DAT' with 'MD5' for checking whether the data are correct. 3. If the device is powered off for a long time, EPO files stored in flash may expire. 2.5. The Validity Period of EPO Files EPO validity period is related to the current UTC time. The EPO validity period can be obtained from the last segment of the EPO file. See Figure 1: EPO Files Format – GPS Only for the sample of how to calculate EPO validity period (GPS_Hour + 6). It is necessary to download the EPO file 12 hours in advance. The following codes show the conversion between UTC time and GPS time. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 16 / 47 GNSS Module Series void utc_to_gpstime(kal_uint32 year, //Input year kal_uint8 mon, //Input month: 1~12 kal_uint8 day, //Input day: 1~31 kal_uint8 hour, //Input hour: 0~23 kal_uint8 min, //Input Minute: 0~59 kal_uint8 sec, //Input second: 0~59 kal_int32* wn, //Output GPS week number double* tow) //Output GPS time of week { kal_int32 iYearsElapsed; //Elapsed years since 1980 kal_int32 iDaysElapsed; //Elapsed days since Jan 5/Jan 6, 1980 kal_int32 iLeapDays; //Leap days since Jan 5/Jan 6, 1980 kal_int32 i; //Number of days at the start of each month (ignore leap years). kal_uint16 doy[12] = {0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334}; iYearsElapsed = year - 1980; i = 0; iLeapDays = 0; while (i <= iYearsElapsed) { if ((i % 100) == 20) { if ((i % 400) == 20) { iLeapDays++; } } else if ((i % 4) == 0) { iLeapDays++; } i++; } /* iLeapDays = iYearsElapsed / 4 + 1; */. if ((iYearsElapsed % 100) == 20) { if (((iYearsElapsed % 400) == 20) && (mon <= 2)) { iLeapDays--; } } else if (((iYearsElapsed % 4) == 0) && (mon <= 2)) { iLeapDays--; } iDaysElapsed = iYearsElapsed * 365 + doy[mon - 1] + day + iLeapDays - 6; //Convert time to GPS weeks and seconds. *wn = iDaysElapsed / 7; *tow = (double)(iDaysElapsed % 7) * 86400 + hour * 3600 + min * 60 + sec; } Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 17 / 47 GNSS Module Series 3 AGNSS Implementation This chapter describes two AGNSS implementation methods: Host EPO and Flash EPO. ⚫ Implement AGNSS with Host EPO The host sends EPO data to the GNSS receiver through NMEA PMTK command, such as $PMTK721. ⚫ Implement AGNSS with Flash EPO The EPO data are downloaded to the flash of GNSS receiver through Binary Protocol. Flash EPO keeps data for a longer time than Host EPO. 3.1. AGNSS with Flash EPO Flash EPO can store 7 or 14 days’ EPO assistance data on flash, which enables the receiver to make use of the available data since boot time. The communication protocol of Flash EPO is Binary Protocol. In order to download assistance data to the receiver, users first need to set the device to Binary mode through $PMTK253 so that the assistance data are downloaded in the binary format specified in this document. See Chapter 3.1.2 and Chapter 3.1.3 for details. 3.1.1. Binary Protocol The preamble of the frame, fixed as 0x04 0x24 2-byte Message 2-byte Message ID Preamble Length MsgID Payload The range for checksum calculation 1-byte The tail of the frame, Checksum fixed as 0x0D 0x0A Checksum Tail Figure 5: Structure of Binary Protocol Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 18 / 47 GNSS Module Series Table 6: Description of Binary Protocol Fields Field Preamble Length MsgID Payload Checksum Tail Length (Byte) 2 2 2 Variable 1 2 Description Fixed as 0x04 0x24. Use little endian. Total length of the messages from Preamble to Tail. Unit: byte. Maximum packet size: 256 bytes. Use little endian. Message ID. Payload data to be transferred. The checksum is the 8-bit exclusive OR of all bytes in the message between (but not including) the Preamble and the Checksum. Fixed as 0x0D 0x0A. Use little endian. 3.1.1.1. MTK_BIN_EPO (MsgID = 723) EPO binary packet is named as MTK_BIN_EPO (MsgID = 723) for convenience. Table 7: MTK_BIN_EPO Format Preamble Length MsgID 0x04 0x24 0x00E3 0x02D3 2 Bytes 2 Bytes 2 Bytes EPO SEQ 2 Bytes Payload SAT Data 72 Bytes SAT Data 72 Bytes SAT Data 72 Bytes Checksum 0x** 1 Byte Tail 0x0D 0x0A 2 Bytes An EPO file contains several SAT Data which are encapsulated in several MTK_BIN_EPO packets to be transferred to GNSS receiver. Each MTK_BIN_EPO packet contains a 2-byte EPO SEQ and 3 SAT Data fields. The length of MTK_BIN_EPO is 227 bytes. The EPO SEQ is used for synchronizing MTK_BIN_EPO packets in transfer protocol. Sometimes, there is no enough EPO data to complete the three SAT Data fields. Some of the three fields can be left as blank, that is, to be filled with 0x00. An MTK_BIN_EPO packet that only contains 0–2 SAT Data is possible and acceptable. The following three MTK_BIN_EPO packets are examples: 4.NOTE It is recommended to confirm the validity of the EPO file before sending it. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 19 / 47 GNSS Module Series Table 8: Format for MTK_BIN_EPO with 2 SAT Data Preamble Length MsgID 0x04 0x24 0x00E3 0x02D3 2 Bytes 2 Bytes 2 Bytes EPO SEQ 2 Bytes Payload SAT Data 72 Bytes SAT Data 72 Bytes 0x00 72 Bytes Checksum 0x** 1 Byte Tail 0x0D 0x0A 2 Bytes Table 9: Format for MTK_BIN_EPO with 1 SAT Data Preamble Length MsgID 0x04 0x24 0x00E3 0x02D3 2 Bytes 2 Bytes 2 Bytes EPO SEQ 2 Bytes Payload SAT Data 72 Bytes 0x00 72 Bytes 0x00 72 Bytes Checksum 0x** 1 Byte Tail 0x0D 0x0A 2 Bytes Table 10: Format for MTK_BIN_EPO with No SAT Data Preamble Length MsgID 0x04 0x24 0x00E3 0x02D3 2 Bytes 2 Bytes 2 Bytes EPO SEQ 2 Bytes Payload Checksum 0x00 0x00 0x00 0x** 72 72 72 1 Byte Bytes Bytes Bytes Tail 0x0D 0x0A 2 Bytes Table 11: Description of MTK_BIN_EPO Fields Field EPO SEQ SAT Data Length (Byte) 2 72 Description Sequence number to indicate the corresponding received MTK_BIN_EPO. Satellite EPO data. GNSS receiver will return an ACK packet for each received MTK_BIN_EPO. The packet is named as MTK_BIN_ACK_EPO (MsgID = 2) for convenience. See Chapter 3.1.1.2 for details. 3.1.1.2. MTK_BIN_ACK_EPO (Msg = 2) This packet is usually returned after receiving an MTK_BIN_EPO packet. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 20 / 47 Table 12: MTK_BIN_ACK_EPO Format Preamble Length MsgID 0x04 0x24 0x000C 0x0002 2 Bytes 2 Bytes 2 Bytes Payload EPO SEQ Result 2 Bytes 1 Byte GNSS Module Series Checksum Tail 0x** 0x0D 0x0A 1 Byte 2 Bytes Table 13: Description of MTK_BIN_ACK_EPO Fields Field EPO SEQ Result Length (Byte) 2 1 Description Sequence number to indicate the corresponding received MTK_BIN_EPO. Result. 0: Failed to receive the packet 1: Successfully received the packet Example: //Successfully received the EPO packet whose sequence number is 0x56: 0x04 0x24 0x0C 0x00 0x02 0x00 0x56 0x00 0x01 0x59 0x0D 0x0A //Failed to receive the EPO packet whose sequence number is 0x56: 0x04 0x24 0x0C 0x00 0x02 0x00 0x56 0x00 0x00 0x58 0x0D 0x0A 3.1.1.3. Change UART Format Packet (MsgID = 253) This packet changes UART communication protocol and sets baud rate. Table 14: Format for Change UART Format Packet Preamble Length 0x04 0x24 0x000E 2 Bytes 2 Bytes MsgID 0x00FD 2 Bytes Payload Protocol Baudrate 1 Byte 4 Bytes Checksum Tail 0x** 0x0D 0x0A 1 Byte 2 Bytes Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 21 / 47 GNSS Module Series Table 15: Description of Change UART Format Packet Fields Field Protocol Length (Byte) 1 Baudrate 4 Description Protocol. 0x00 = NMEA PMTK protocol 0x01 = Binary Protocol UART baud rate. 0x00000000 = Default baud rate 0x00002580 = 9600 0x00004B00 = 19200 0x00009600 = 38400 0x0000E100 = 57600 0x0001C200 = 115200 0x00038400 = 230400 0x00070800 = 460800 0x000E1000 = 921600 Use little endian. Example: //Change UART to Binary Protocol and use baud rate 115200: 0x04 0x24 0x0E 0x00 0xFD 0x00 0x01 0x00 0xC2 0x01 0x00 0x31 0x0D 0x0A //Change UART to PMTK protocol and use default baud rate: 0x04 0x24 0x0E 0x00 0xFD 0x00 0x00 0x00 0x00 0x00 0x00 0xF3 0x0D 0x0A 3.1.1.4. ACK Packet (MsgID = 1) This packet is usually returned after receiving Change UART Format Packet (MsgID = 253). Table 16: ACK Packet Format Preamble Length MsgID 0x04 0x24 0x000C 0x0001 2 Bytes 2 Bytes 2 Bytes Payload Responding MsgID Flag 2 Bytes 1 Byte Checksum Tail 0x** 0x0D 0x0A 1 Byte 2 Bytes Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 22 / 47 GNSS Module Series Table 17: Description of ACK Packet Fields Field Responding MsgID Flag Length (Byte) 2 1 Description Responding message ID. ACK flag. 0x00, 0x01: Invalid: the baud rate is invalid. 0x02: Failure: failed to set baud rate. 0x03: Success: succeeded to set baud rate. Example: //Received a valid binary packet and returned a success flag: 0x04 0x24 0x0C 0x00 0x01 0x00 0xFD 0x00 0x03 0xF3 0x0D 0x0A 3.1.2. EPO Data Transfer Protocol EPO data are packed in MTK_BIN_EPO packets and then transferred to GNSS receiver. At the beginning of the transfer procedure, the host should split the EPO files and encapsulate them into several MTK_BIN_EPO packets, then assign a sequence number starting from zero for each MTK_BIN_EPO packet to make sure the MTK_BIN_EPO packets are transferred in correct order and not missed. The host should follow the EPO Data Transfer Protocol when transferring EPO data to GNSS receiver. 3.1.2.1. Pseudo Code for EPO Data Transfer Protocol The following shows pseudo codes for EPO data transfer procedure, which are for reference only. #define MTKBIN_3EPO_PKT_LNG 227 //At first, the protocol of the communication UART is supposed to be PMTK Protocol. Since EPO data are transferred by using binary packet, the protocol should be changed to Binary Protocol. //Before starting EPO data transfer procedure, change the UART protocol set by $PMTK253. See Chapter 4.3 for the details of $PMTK253. //The SendPmtkCmd() function must be implemented by the programmer. //It is recommended to explicitly specify a baud rate when changing UART packet protocol, for example, $PMTK253,1,115200*00. SendPmtkCmd ('$PMTK253,1,0*37rn'); //Now the data transferred via the UART port will be regarded as binary packet format. Please create a thread to transmit/receive binary packets for the UART. And the thread TMtkBinCmdThread() must be implemented by the programmer. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 23 / 47 GNSS Module Series pMtkBinCmdThread() =new TMtkBinCmdThread(); //Read data in the EPO file, and then verify the validity of EPO data. If the inputted EPO file is not a valid EPO format, the programmer shall terminate the procedure. //Please check whether the file size is a multiple of 2304 bytes or 4032 bytes. //The fgEPO_Verify_File() function must be implemented by the programmer. if (!fgEPO_Verify_File (pEpoFile)) return; //Get total length of MTK_BIN_EPO packets that will be sent. //Total number=ceil ((file size/72)/3) //The i2EPO_Get_Num_Pkt function must be implemented by the programmer. i4NumSvEpoPkt = i2EPO_Get_Num_Pkt(pEpoFile); //Start EPO data transfer procedure to send EPO data. u2EpoSeq=0; u2LastEpoSeq=0; for (i = 0; iSendData(szPktData, MTKBIN_3EPO_PKT_LNG); //Update sequence number. u2LastEpoSeq = u2EpoSeq; u2EpoSeq++; } } //Generate final MTK_BIN_EPO packet to indicate the GNSS receiver that the process is finished. //The fgEPO_Get_Final_Pkt function must be implemented by the programmer. vEPO_Get_Final_Pkt(szPktData); //Send final MTK_BIN_EPO packet to the GNSS receiver. The packet size of MTK_BIN_EPO is MTKBIN_3EPO_PKT_LNG. //Then the process is finished. //The SendData function must be implemented by the programmer. pPortMtkBinThread->SendData(szPktData, MTKBIN_3EPO_PKT_LNG); //Switch UART protocol setting to PMTK packet format and change the baud rate to 115200 for the communication UART. See Chapter 3.1.1.3 for details. //The SendMtkBinCmd function must be implemented by the programmer. SendMtkBinCmd(0x04 0x24 0x0E 0x00 0xFD 0x00 0x00 0x00 0xC2 0x01 0x00 0x30 0x0D 0x0A); Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 25 / 47 3.1.3. AGNSS Procedure with Flash EPO Power on GNSS GNSS Module Series Have EPO file? NO YES Has expired EPO file? YES Erase EPO file NO Send Reference Time Download EPO files with MTK_BIN_EPO Verify downloaded data Restart GNSS Send Reference Position Position fixed Figure 6: AGNSS Procedure with Flash EPO 1. Power on the GNSS module. 2. Check whether there are EPO data in GNSS module through $PMTK607. 3. If there exists EPO data, go to the next step to check the data validity. Otherwise, download EPO data to GNSS module and verify downloaded data, then restart GNSS module and directly go to Step 6. 4. Check whether the EPO file in GNSS module has expired. 5. If not, go to next step. Otherwise, erase expired EPO file through $PMTK127 and download a new EPO file. 6. Send Reference Time to GNSS module with $PMTK740. 7. Send Reference Position to GNSS module with $PMTK741 or $PMTK713. 8. Wait for GNSS module to fix position. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 26 / 47 GNSS Module Series 3.2. AGNSS with Host EPO Host EPO allows for a simpler text-based implementation which enables the receiver to perform a fast start up where assistance data must be sent to the receiver each time it boots. When using Host EPO, the receiver can only receive one block of assistance data valid for 6 hours. Implementing Host EPO only requires a few PMTK sentences and all data transfer can be done in NMEA mode. See Chapter 4 for a detailed description of $PMTK713, $PMTK721, $PMTK740 and $PMTK741. Both Reference Time and Position can be sent through $PMTK741. 3.2.1. Recommended Sequence for Host EPO After the GNSS receiver is powered on, it will output a start-up message $PMTK010,001*2E to notify the host that it has finished initialization and is capable of receiving PMTK commands. After the host receives the system startup message, it can send the assistance data in sequence shown in the Figure 7: Recommended Sequence for Host EPO. The sequence of assistance data is Reference Time, Reference Position and EPO data. The Host EPO procedure consists of the following steps: 1. GNSS module starts up. 2. The host sends Reference Time. 3. The host sends Reference Position. 4. The host sends EPO data. The supplied Reference Time, Reference Position and EPO data must comply with the requirements listed in Chapter 1.3. NOTE In the current implementation, the host needs to wait for a $PMTK001 packet to be returned before sending another segment of EPO data. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 27 / 47 GNSS Receiver Host EPO Sequence GNSS Module Series Host GNSS Module Powers Up Start up message Assistance Data(Time) $PMTK001(ACK) Assistance Data(Position) $PMTK001(ACK) Loop [Repeats until all EPO data are sent] EPO Assistance Data Segment 001 $PMTK001(ACK) EPO Assistance Data Segment 002 $PMTK001(ACK) The host needs to wait for $PMTK001 ACK packages Figure 7: Recommended Sequence for Host EPO 3.2.2. Sample Code of Sending EPO The following is the reference code to send one segment of EPO data to GNSS receiver. It reveals how to extract correct EPO segment from an EPO file and how to construct PMTK messages for GNSS receiver. PMTK messages for Reference Time, Reference Position, and second EPO segment are not included in this example. #include #include #define MTKEPO_SV_NUMBER 32 #define MTKEPO_RECORD_SIZE 72 #define MTKEPO_SEGMENT_NUM (30 * 4) unsigned char calc_nmea_checksum(const char* sentence) { unsigned char checksum = 0; Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 28 / 47 GNSS Module Series while (*sentence) { checksum ^= (unsigned char)*sentence++; } return checksum; } // translate UTC to GPS_Hour int utc_to_gps_hour(int iYr, int iMo, int iDay, int iHr) { int iYearsElapsed; // Years since 1980 int iDaysElapsed; // Days elapsed since Jan 6, 1980 int iLeapDays; // Leap days since Jan 6, 1980 int i; // Number of days into the year at the start of each month (ignoring leap years) const unsigned short doy[12] = {0,31,59,90,120,151,181,212,243,273,304,334}; iYearsElapsed = iYr - 1980; i = 0; iLeapDays = 0; while (i <= iYearsElapsed) { if ((i % 100) == 20) { if ((i % 400) == 20) { iLeapDays++; } } else if ((i % 4) == 0) { iLeapDays++; } i++; } if ((iYearsElapsed % 100) == 20) { if (((iYearsElapsed % 400) == 20) && (iMo <= 2)) { iLeapDays--; } } else if (((iYearsElapsed % 4) == 0) && (iMo <= 2)) { iLeapDays--; } iDaysElapsed = iYearsElapsed * 365 + (int)doy[iMo - 1] + iDay + iLeapDays - 6; // Convert time to GPS weeks and seconds return (iDaysElapsed * 24 + iHr); } void send_assistance_data(int iYr, int iMo, int iDay, int iHr) { FILE* fp; int i, segment, epo_gps_hour, current_gps_hour; unsigned epobuf[MTKEPO_RECORD_SIZE/sizeof(unsigned)]; char strbuf[200], outbuf[200]; Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 29 / 47 GNSS Module Series // open EPO file and read the header (assume EPO file has passed integrity check) if (NULL == (fp = fopen('MTKEPO.bin', 'rb'))) { return; } fread(&epo_gps_hour, 4, 1, fp); epo_gps_hour &= 0x00FFFFFF; // determine the segment to use current_gps_hour = utc_to_gps_hour(iYr, iMo, iDay, iHr); segment = (current_gps_hour - epo_gps_hour) / 6; if ((segment < 0) || (segment >= MTKEPO_SEGMENT_NUM)) { return; } // read binary EPO data and sent it to MT3339 fseek(fp, segment*(MTKEPO_RECORD_SIZE)*(MTKEPO_SV_NUMBER), SEEK_SET); for (i = 0; i < MTKEPO_SV_NUMBER; i++) { fread(epobuf, MTKEPO_RECORD_SIZE, 1, fp); // assume host system is little-endian sprintf(strbuf,'PMTK721,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X', i+1, epobuf[0], epobuf[1], epobuf[2], epobuf[3], epobuf[4], epobuf[5], epobuf[6], epobuf[7], epobuf[8], epobuf[9], epobuf[10], epobuf[11], epobuf[12], epobuf[13], epobuf[14], epobuf[15], epobuf[16], epobuf[17]); sprintf(outbuf, '$%s*Xrn', strbuf, calc_nmea_checksum(strbuf)); // send them by UART // uart_send(outbuf, strlen(outbuf)); printf('%s', outbuf); // for demo } fclose(fp); } int main (void) { // get current system time // ... time(); // send assistance data of current time send_assistance_data(2009, 8, 3, 22); return 0; } Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 30 / 47 GNSS Module Series 4 AGNSS Related Messages 4.1. PMTK001 PMTK_ACK Acknowledges a PMTK command. This message is returned to inform the sender that the receiver has received the packet. Type: Output Synopsis: $PMTK001,,[,,…,]* Parameter: Field Format Unit Numeric - Numeric - [,,…,] Numeric - Description The packet type that the acknowledgement responds. ACK flag. 0 = Invalid command 1 = Unsupported command type 2 = Valid command, but action failed 3 = Valid command, and action succeeded Extended parameters (optional). Example: $PMTK001,0,3*30 4.2. PMTK127 PMTK_CMD_CLEAR_EPO Erases the EPO data stored in the GNSS receiver. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 31 / 47 Type: Command Synopsis: $PMTK127* Parameter: None Result: Returns a $PMTK001 message. Example: $PMTK127*36 $PMTK001,127,3*34 GNSS Module Series 4.3. PMTK253 PMTK_SET_OUTPUT_FMT Sets data output format and baud rate for current port. Type: Set Synopsis: $PMTK253,,* Parameter: Field Unit - bps Default 0 115200 Description Protocol mode. 0 = NMEA mode 1 = Binary mode Baud rate for the new output mode. 0: use default baud rate (not recommended) It is highly recommended to specify an explicit baud rate. Possible values will be: 9600 19200 Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 32 / 47 GNSS Module Series 38400 57600 115200 230400 460800 921600 Result: Returns a $PMTK001 message. Example: //Switch from NMEA mode to Binary mode, and use default baud rate 115200 bps: $PMTK253,1,0*37 //Switch from Binary mode to NMEA mode, and use baud rate 9600 bps: $PMTK253,0,9600*09 $PMTK001,253,3*34 NOTE When switching from Binary mode to NMEA mode, a binary ACK packet ($PMTK001) will be returned after this message is executed. When switching from NMEA mode to Binary mode, no ACK packet is returned. 4.4. PMTK607 PMTK_Q_EPO_INFO Queries the EPO data stored in the GNSS chip. Type: Query Synopsis: $PMTK607* Parameter: None Result: Returns a $PMTK707 message. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 33 / 47 Example: $PMTK607*33 $PMTK707,56,1468,172800,1470,151200,1468,259200,1468,259200*1F GNSS Module Series 4.5. PMTK707 PMTK_DT_EPO_INFO This message is returned after receiving $PMTK607 and it contains EPO data stored in GNSS chip. Type: Output Synopsis: $PMTK707,,,,,,,,,* Parameter: Field Unit - - - - - - - - - Default Description - Total number of EPO SET stored in GNSS chip - GPS week number of the first EPO SET stored in GNSS chip - GPS TOW of the first EPO SET stored in GNSS chip - GPS week number of the last EPO SET stored in GNSS chip - GPS TOW of the last EPO SET stored in GNSS chip - GPS week number of the first EPO SET currently used - GPS TOW of the first EPO SET currently used - GPS week number of the last EPO SET currently used - GPS TOW of the last EPO SET currently used Result: None Example: $PMTK707,56,1468,172800,1470,151200,1468,259200,1468,259200*1F Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 34 / 47 GNSS Module Series 4.6. PMTK713 PMTK_DT_LOC Sends Reference Position to the GNSS receiver. To have a quick TTFF, the Reference Position shall be accurate within 30 km. Type: Input Synopsis: $PMTK713,,,,,,,* Parameter: Field Unit Range Description Degree Degree -90.0 to 90.0 -180.0 to 180.0 WGS84 geodetic latitude. It is recommended to express this value in floating-point with 6 decimal points. WGS84 geodetic longitude. It is recommended to express this value in floating-point with 6 decimal points. Meter - WGS84 ellipsoidal altitude. Meter > 0 Standard deviation of semi-major axis of error ellipse. Meter > 0 Standard deviation of semi-minor axis of error ellipse. Degree 0–179 Orientation of semi-major axis of error ellipse. Meter > 0 % 0–100 Vertical uncertainty. The confidence by which the position of a target entity is known to be within the shape description. Result: Returns a $PMTK001 message. Example: $PMTK713,24.772816,121.022636,160,333,333,6,50,67*08 $PMTK001,713,3,24.772816,121.022636,160.000000,333.000000,333.000000,6,50.000000,67*0A Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 35 / 47 GNSS Module Series NOTE We use Ellipsoid Point with altitude and uncertainty ellipsoid to describe poosition error shape. 4.7. PMTK721 PMTK_DT_SV_EPO Sends GPS/GLONASS EPO data for a single satellite to GNSS receiver. GPS satellites are identified by their PRN number, which ranges from 1 to 32. GLONASS satellites are identified by their slot number which ranges from 1 to 24 for the full constellation of 24 satellites. for GLONASS is assigned by slot number plus 64, which ranges from 65 to 88. Type: Input Synopsis: $PMTK721,,,...,* Parameter: Field Unit - - Range GPS: 1–32 GLONASS: 65–88 - Description Satellite PRN number [represented in HEX characters] for the EPO data to follow. 18 words [LSB first] of one EPO segment data (total 72 bytes). Result: Returns a $PMTK001 message. Example: $PMTK721,4,40568B0,D6C83E84,70E8E10,FA414370,F913650C,70E71F8,F8D266CF,8732D6FD,7F1D 9CE,E59383DF,76BFB93,A60319DF,C36C3289,20173F8D,959E4561,1000001C,40000,8B94CFB6*2C $PMTK001,721,17,00000000*32 Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 36 / 47 GNSS Module Series 4.8. PMTK740 PMTK_DT_UTC Sends current Reference UTC Time to GNSS receiver. Local time should be avoided due to time-zone offset. To have a faster TTFF, the Reference Time should be accurate with 3 s and must be specified in UTC time. Type: Input Synopsis: $PMTK740,,,,,,* Parameter: Field Unit Year Month Day Hour Minute Second Range > 1980 1–12 1–31 0–23 0–59 0–59 Description UTC time: year in 4 digits. UTC time: month. UTC time: day. UTC time: hour. UTC time: minute. UTC time: second. Result: Returns a $PMTK001 message. Example: $PMTK740,2010,2,10,9,0,58*05 $PMTK001,740,3,2010,2,10,9,0,58*07 4.9. PMTK741 PMTK_DT_POS Injects Reference Position and Reference UTC Time into GNSS receiver to have a faster TTFF. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 37 / 47 GNSS Module Series Type: Input Synopsis: $PMTK741,,,,,,,,,* Parameter: Field Unit Range Description Degree Degree -90.0 to 0.0 -180.0 to 180.0 WGS84 geodetic latitude. It is recommended to express this value in floating-point with 6 decimal points. Minus: south; Plus: north. WGS84 geodetic longitude. It is recommended to express this value in floating-point with 6 decimal points. Minus: west; Plus: east. Meter - WGS84 ellipsoidal altitude. Year > 1980 UTC time: year in 4 digits. Month 01–12 UTC time: month. Day 01–31 UTC time: day. Hour 00–23 UTC time: hour. Minute 00–59 UTC time: minute. Second 00–59 UTC time: second. Result: Returns a $PMTK001 message. Example: $PMTK741,24.772816,121.022636,160,2016,01,01,12,00,00*17 $PMTK001,741,3,24.772816,121.022636,160.000000,2016,1,1,12,0,0*3B Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 38 / 47 GNSS Module Series 5 EPO Usage Through QGNSS QGNSS is a Quectel official tool which allows users to evaluate the receiver performance as well as to perform different measurements on the receiver. Visit http://220.180.239.212:8177 for details on QGNSS. This chapter describes how to evaluate the EPO functionality through QGNSS. 5.1. Testing Flash EPO with QGNSS Steps to test Flash EPO with the QGNSS tool: 1. Run the QGNSS tool. 2. In the main interface, click 'AGNSS' → 'Assistant GNSS Offline' as shown below. Figure 8: AGNSS Setting Interface of QGNSS 3. Download EPO file to the module. a) Click the 'Connect' button to connect to the FTP server. b) Select EPO file. c) Click the 'Download selected file' button to download the EPO file to computer. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 39 / 47 d) Click 'Download to module' to download the EPO file to module. GNSS Module Series Figure 9: EPO File Downloading 4. Click 'Tools' → 'Static TTFF Testing' to enter TTFF testing window. Figure 10: Static TTFF Testing 5. Check 'Use AGNSS' and click 'Run' to run the TTFF testing. Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 40 / 47 GNSS Module Series Figure 11: TTFF Setting 5.2. Testing Host EPO with QGNSS The steps to test Host EPO with the QGNSS tool: 1. Run QGNSS tool. 2. In the main interface, click 'Tools' -> 'Static TTFF Testing' to enter the TTFF testing window. Figure 12: Static TTFF Testing Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 41 / 47 GNSS Module Series 3. Configure parameter: a) Click 'Set AGNSS' and check 'Use AGNSS' to enter the Assistant GNSS Online window. b) Click 'Connect' button to connect to FTP server. c) Select EPO file and click 'Download selected file' button to download the EPO file to computer. d) Check 'Using UTC time', 'Cold start', 'Position' and 'AGNSS Data'. e) Enter the latitude and longitude or click 'Use Current Position' to automatically select the last fixed position. f) Click 'Run' to test TTFF. Figure 13: TTFF Setting NOTE 1. If the Flash EPO has been tested first, use $PMTK127*36 to clear the Flash EPO data before users perform the Host EPO testing. A Host EPO file can be selected according to UTC time: 0:00 to 6:00: EPO file 1 6:00 to 12:00: EPO file 2 12:00 to 18:00: EPO file 3 18:00 to 24:00: EPO file 4 Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 42 / 47 GNSS Module Series 6 AGNSS Implementation Example This chapter gives examples to show how EPO files can be downloaded to the module. 6.1. Flash EPO Implementation Blue: Send data Red: ACK information //Host sends $PMTK253,1,0*37 for switching from NMEA mode to binary mode, NO ACK will be sent from module: 24 50 4D 54 4B 32 35 33 2C 31 2C 30 2A 33 37 0D 0A //Host sends EPO file: 04 24 E3 00 D3 02 00 00 DC 93 05 01 C6 03 F8 9F 59 DE 0A 73 39 0F 54 00 23 25 FD 02 F4 21 0A 73 ……0D 0A //Module will erase the area where the EPO saved. 24 43 4C 52 2C 45 50 4F 2C 30 30 30 61 38 30 30 30 2A 35 45 0D 0A 24 43 4C 52 2C 45 50 4F 2C 30 30 30 61 39 0D 0A 24 43 4C 52 2C 45 50 4F 2C 30 30 30 61 39 30 30 30 2A 35 46 0D 0A 24 43 4C 52 2C 45 50 4F 2C 30 30 30 61 61 30 30 30 2A 30 37 0D 0A 24 43 4C 52 2C 45 50 4F 2C 30 30 30 61 62 30 30 30 2A 30 34 0D 0A 24 43 4C 52 2C 45 50 4F 2C 30 30 30 61 63 30 30 30 2A 30 35 0D 0A …… //Module returns a $PMTK001 message: 04 24 0C 00 20 00 00 00 01 0F 0D 0A //Host sends EPO data: 04 24 E3 00 D3 02 01 00 DC 93 05 04 B2 02 F8 01 C7 71 0A 73 A6 5F 49 FC A9 68 D9 FC C9 71 0A 73 ……. 0D 0A //Module returns a $PMTK001 message: 04 24 0C 00 02 00 01 00 01 0E 0D 0A //Host sends EPO data: 04 24 E3 00 D3 02 02 00 DC 93 05 07 1B 03 F8 3E F8 41 0A 73 2B 74 62 03 A8 4D 5F 04 C9 41 0A 73 Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 43 / 47 ……0D 0A //Module returns a $PMTK001 message: 04 24 0C 00 02 00 02 00 01 0D 0D 0A //Host send EPO data: 04 24 E3 00 D3 02 03 00 DC 93 05 ……. 0D 0A //Module returns a $PMTK001 message: 04 24 0C 00 02 00 03 00 01 0C OD 0A …… //Host send EPO data: 04 24 E3 00 D3 02 6A 00 DC 93 05 ……. 0D 0A //Module returns a $PMTK001 message: 04 24 0C 00 02 00 6A 00 01 65 0D 0A //End of host sending, no data any more: 04 24 E3 00 D3 02 FF FF 00 00 00 00 00 00 00 00……0D 0A //End of module reception: 04 24 0C 00 02 00 FF FF 01 0F 0D 0A //Host changes UART to PMTK protocol and use default baud rate: 04 24 0E 00 FD 00 00 00 00 00 00 F3 0D 0A GNSS Module Series 6.2. Host EPO Implementation Blue: Send data Red: ACK information //Host Sends cold start command: $PMTK103*30: 24 50 4D 54 4B 31 30 33 2A 33 30 0D 0A //Host sends the current UTC time command: $PMTK740,2021,09,18,07,34,14*35: 24 50 4D 54 4B 37 34 30 2C 32 30 32 31 2C 30 39 2C 31 38 2C 30 37 2C 33 34 2C 31 34 2A 33 35 0D 0A //Module returns a $PMTK001 message: $PMTK001,740,2,2021,9,18,7,34,14*36: 24 50 4D 54 4B 30 30 31 2C 37 34 30 2C 32 2C 32 30 32 31 2C 39 2C 31 38 2C 37 2C 33 34 2C 31 34 2A 33 36 0D 0A //Host sends the current location information command: Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 44 / 47 GNSS Module Series $PMTK741,31.822218,117.115247,49.200000,2021,09,18,07,34,14*0B 24 50 4D 54 4B 37 34 31 2C 33 31 2E 38 32 32 32 31 38 2C 31 31 37 2E 31 31 35 32 34 37 2C 34 39 2E 32 30 30 30 30 30 2C 32 30 32 31 2C 30 39 2C 31 38 2C 30 37 2C 33 34 2C 31 34 2A 30 42 0D 0A //Module returns a $PMTK001 message: $PMTK001,741,3,31.822218,117.115247,49.200000,2021,9,18,7,34,14*09 24 50 4D 54 4B 30 30 31 2C 37 34 31 2C 33 2C 33 31 2E 38 32 32 32 31 38 2C 31 31 37 2E 31 31 35 32 34 37 2C 34 39 2E 32 30 30 30 30 30 2C 32 30 32 31 2C 39 2C 31 38 2C 37 2C 33 34 2C 31 34 2A 30 39 0D 0A //Host sends EPO data: $PMTK721,1,10593EE,9FFC01C0,84D8DE59,E250EA6,F6326A6,84D8DE3E,75D098A,855C5F41,6F1 8520,CAD37EAE,2A797EC,A60346B9,25302423,2F28853F,24458AEA,1000001C,0000000,4B65EDB 3*19 24 50 4D 54 4B 37 32 31 2C 31 2C 31 30 35 39 33 45 45 2C 39 46 46 43 30 31 43 30 2C 38 34 44 38 44 45 35 39 2C 45 32 35 30 45 41 36 2C 46 36 33 32 36 41 36 2C 38 34 44 38 44 45 33 45 2C 37 35 44 30 39 38 41 2C 38 35 35 43 35 46 34 31 2C 36 46 31 38 35 32 30 2C 43 41 44 33 37 45 41 45 2C 32 41 37 39 37 45 43 2C 41 36 30 33 34 36 42 39 2C 32 35 33 30 32 34 32 33 2C 32 46 32 38 38 35 33 46 2C 32 34 34 35 38 41 45 41 2C 31 30 30 30 30 30 31 43 2C 30 30 30 30 30 30 30 2C 34 42 36 35 45 44 42 33 2A 31 39 0D 0A //Module returns a $PMTK001 message: $PMTK001,721,3, 1,00000000*25: 24 50 4D 54 4B 30 30 31 2C 37 32 31 2C 33 2C 20 31 2C 30 30 30 30 30 30 30 30 2A 32 35 0D 0A //Host sends EPO data: $PMTK721,2,20593EE,EEFC02B5,84D8EE28,DF12534,E55186E,84D8EEFF,F8B63471,83655362, 6F18E3E,DFA23AA6,D6EB7E5,A6001FC7,19B59076,20492A75,C32F2503,1000001C,0000000,C604 863*1C 24 50 4D 54 4B 37 32 31 2C 32 2C 32 30 35 39 33 45 45 2C 45 45 46 43 30 32 42 35 2C 38 34 44 38 45 45 32 38 2C 44 46 31 32 35 33 34 2C 45 35 35 31 38 36 45 2C 38 34 44 38 45 45 46 46 2C 46 38 42 36 33 34 37 31 2C 38 33 36 35 35 33 36 32 2C 36 46 31 38 45 33 45 2C 44 46 41 32 33 41 41 36 2C 44 36 45 42 37 45 35 2C 41 36 30 30 31 46 43 37 2C 31 39 42 35 39 30 37 36 2C 32 30 34 39 32 41 37 35 2C 43 33 32 46 32 35 30 33 2C 31 30 30 30 30 30 31 43 2C 30 30 30 30 30 30 30 2C 43 36 30 34 38 36 33 2A 31 43 0D 0A //Module returns a $PMTK001 message: $PMTK001,721,3, 2,00000000*26: 24 50 4D 54 4B 30 30 31 2C 37 32 31 2C 33 2C 20 32 2C 30 30 30 30 30 30 30 30 2A 32 36 0D 0A …… …… //Host sends EPO data: $PMTK721,20,200593EE,E2FC0257,84DACE24,FE391CC7,FD6A2881,84DA31D2,F8FB23C7,82F3C2 84,6F39D87,4190A41C,590822F,A601FD64,71D66A59,2004BD1E,9F31A748,100 Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 45 / 47 GNSS Module Series D1E,9F31A748,1000001C,1000000,80B38D89*53 35 41 35 37 32 42 41 2A 31 36 0D 0A 24 50 4D 54 4B 37 32 31 2C 32 30 2C 32 30 30 35 39 33 45 45 2C 45 32 46 43 30 32 35 37 2C 38 34 44 41 43 45 32 34 2C 46 45 33 39 31 43 43 37 2C 46 44 36 41 32 38 38 31 2C 38 34 44 41 33 31 44 32 2C 46 38 46 42 32 33 43 37 2C 38 32 46 33 43 32 38 34 2C 36 46 33 39 44 38 37 2C 34 31 39 30 41 34 31 43 2C 35 39 30 38 32 32 46 2C 41 36 30 31 46 44 36 34 2C 37 31 44 36 36 41 35 39 2C 32 30 30 34 42 44 31 45 2C 39 46 33 31 41 37 34 38 2C 31 30 30 30 30 30 31 43 2C 31 30 30 30 30 30 30 2C 38 30 42 33 38 44 38 39 2A 35 33 0D 0A //Module returns a $PMTK001 message: $PMTK001,721,3, 32,00000000*35: 0A 24 50 4D 54 4B 30 30 31 2C 37 32 31 2C 33 2C 33 32 2C 30 30 30 30 30 30 30 30 2A 33 35 0D 0A Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 46 / 47 GNSS Module Series 7 Appendix References Table 18: Almanac, Ephemeris and EPO Type Source Validity Period Effect Almanac Satellites Several weeks Satellites searching Ephemeris Satellites < 4 hours Positioning EPO Chipset supplier’s server 6 hours to 30 days Satellites searching & positioning Table 19: Terms and Abbreviations Abbreviation EPO FTP GLONASS GNSS GPS TTFF TOW UART UTC URL ACK SV Description Extended Prediction Orbit File Transfer Protocol Global Navigation Satellite System Global Navigation Satellite System Global Positioning System Time to First Fix Time of Week Universal Asynchronous Receiver/Transmitter Coordinated Universal Time Uniform Resource Locator Acknowledgement Satellite Vehicle Lx0&Lx6&LC86L&LG77L_AGNSS_Application_Note 47 / 47
893.19 KB
LC76F Firmware Upgrade Guide GNSS Module Series Version: 1.0. Date: 2021-09-14 Status: Released GNSS Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. LC76F_Firmware_Upgrade_Guide 1 / 22 GNSS Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2021. All rights reserved. LC76F_Firmware_Upgrade_Guide 2 / 22 GNSS Module Series About the Document Document Information Title Subtitle Document Type Document Status LC76F Firmware Upgrade Guide GNSS Module Series Firmware Upgrade Guide Released Revision History Version 1.0 Date 2021-06-25 2021-09-14 Description Creation of the document First official release LC76F_Firmware_Upgrade_Guide 3 / 22 GNSS Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 2 Firmware Upgrade Process ............................................................................................................... 8 2.1. Communication Between Host and Module ............................................................................ 10 2.1.1. Handshake with Module................................................................................................ 11 2.1.2. Send BE ........................................................................................................................ 12 2.1.3. Jump to BE.................................................................................................................... 13 2.1.4. Sync with BE ................................................................................................................. 13 2.1.5. Download Firmware ...................................................................................................... 14 2.1.6. Reset ............................................................................................................................. 15 2.2. Sample Code for Checksum .................................................................................................... 16 3 Upgrade Implementation Example.................................................................................................. 17 4 Appendix Reference ......................................................................................................................... 22 LC76F_Firmware_Upgrade_Guide 4 / 22 GNSS Module Series Table Index Table 1: List of Constants ............................................................................................................................ 8 Table 2: Baudrate......................................................................................................................................... 9 Table 3: Terms and Abbreviations ............................................................................................................. 22 LC76F_Firmware_Upgrade_Guide 5 / 22 GNSS Module Series Figure Index Figure 1: Firmware Upgrade Connection..................................................................................................... 7 Figure 2: Communication Between Host and Module ............................................................................... 10 Figure 3: Handshake .................................................................................................................................. 11 Figure 4: Send BE ...................................................................................................................................... 12 Figure 5: Jump to BE.................................................................................................................................. 13 Figure 6: Sync with BE ............................................................................................................................... 13 Figure 7: Download Firmware .................................................................................................................... 14 Figure 8: Reset ........................................................................................................................................... 15 LC76F_Firmware_Upgrade_Guide 6 / 22 GNSS Module Series 1 Introduction This document explains how to upgrade the firmware on Quectel LC76F GNSS module. Following the procedure illustrated in this document, you can upgrade and download the firmware to the target GNSS module via the UART interface. HOST UART GNSS Module Figure 1: Firmware Upgrade Connection LC76F_Firmware_Upgrade_Guide 7 / 22 GNSS Module Series 2 Firmware Upgrade Process This chapter explains all the necessary steps in the firmware upgrade process. The following table defines all the constants used in this document. Table 1: List of Constants Constant Name NMEA_START_CMD BOOT_ROM_WRITE_CMD BOOT_ROM_CHECKSUM_CMD BE_START_ADDR BOOT_ROM_JUMP_CMD SYNC_CHAR BE_MAJOR_VER BE_MINOR_VER BE_SPEED_CMD BAUDRATE_FULL_SYNC_COUNT ACK FW_START_ADDR FW_END_ADDR BE_MEM_CMD BE_WRITE_CMD BE_FINISH_CMD Constant Value $PGKC75*1Drn 0xA1 0xA4 0x00000C00 0xA8 0xB0 0x01 0x00 0xE1 0X00 0x6B 0x00000000 0x0008E00B 0xE2 0xE3 0xE5 Steps Figure 3: Handshake Figure 4: Send BE Figure 4: Send BE Figure 4: Send BE Figure 5: Jump to BE Figure 5: Jump to BE Figure 6: Sync with BE Figure 6: Sync with BE Figure 6: Sync with BE Figure 6: Sync with BE Figure 6: Sync with BE Figure 6: Sync with BE Figure 7: Download Firmware Figure 7: Download Firmware Figure 7: Download Firmware Figure 7: Download Firmware Figure 7: Download Firmware Figure 7: Download Firmware LC76F_Firmware_Upgrade_Guide 8 / 22 PACKET_LENGTH CONT_CHAR NMEA_CLEAR_CMD NMEA_RESET_CMD GNSS Module Series 0x00000400 0xB9 $PGKC41*1Arn $PGKC30,3,1*1Ern Figure 7: Download Firmware Figure 7: Download Firmware Figure 8: Reset Figure 8: Reset Table 2: Baudrate Constant Name UART_BAUD_921600 UART_BAUD_460800 UART_BAUD_230400 UART_BAUD_115200 UART_BAUD_57600 UART_BAUD_38400 UART_BAUD_19200 UART_BAUD_14400 UART_BAUD_9600 Baudrate ID 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 Baudrate (bps) 921600 460800 230400 115200 57600 38400 19200 14400 9600 NOTE The bytes to be sent are transmitted in the big-endian format. LC76F_Firmware_Upgrade_Guide 9 / 22 2.1. Communication Between Host and Module GNSS Module Series Module powers on Host sends handshaking command to the module via UART port Module Response Send BE Module Response Jump to BE Module Response Sync with BE Module Response Download Firmware Module Response Reset END Figure 2: Communication Between Host and Module The following sections provide a guide on how the host communicates with module and sends commands and files to the module: ⚫ Handshake with module ⚫ Send BE (Burn Engine) ⚫ Jump to BE ⚫ Sync with BE ⚫ Download firmware ⚫ Reset LC76F_Firmware_Upgrade_Guide 10 / 22 GNSS Module Series 2.1.1. Handshake with Module This section describes the handshake protocol in detail. Host can send command $PGKC75*1D make the module reset. After the module is reset, it will wait for '0x90' sent by the host for 300 milliseconds. If the '0x90' is not received, the handshake fails. Host Start Module Power on No No Over Max. Retry(20)? Yes Error Exit Yes Over Max. Retry(50)? No No No Send NMEA_START_CMD $PGKC75*1D Send Sync Byte 0x90 10 ms once... Send Sync Byte 0x90 0x90 0x90 0x90 No Receive 0x6F Yes Send Sync Byte 0x09 0x6F 0x09 Receive 0xF6 Yes Send Sync Byte 0x60 0xF6 0x60 Receive 0x9F Yes Send Sync Byte 0x06 0x9F 0x06 Receive 0xF9 Yes Burn Engine 0xF9 Receive Command? Yes Module Reset Receive No 0x90 Yes Send Sync Byte 0x6F No Delay 500 ms Try All different Baudrate? No Yes No Timeout Receive 0x09 Yes Flash Have Firmware? Yes Send Sync Byte Execute Firmware 0xF6 No Receive 0x60 Yes Send Sync Byte 0x9F No Receive 0x06 Yes Send Sync Byte 0xF9 Burn Engine Change Baudrate Figure 3: Handshake LC76F_Firmware_Upgrade_Guide 11 / 22 2.1.2. Send BE This section describes how to send the BE to the module. GNSS Module Series Host Module Send (BOOT_ROM_WRITE_CMD, 1 Byte) Receive (BOOT_ROM_WRITE_CMD, 1 Byte) Send (BE_START_ADDR, 4 Bytes) Receive (BE_START_ADDR, 4 Bytes) Send (BE Length Num of Word, 4 Bytes) Receive (BE Length Num of Word, 4 Bytes) Send (BE Data, 256 Bytes) Receive (BE Data, 256 Bytes) Send (BE Data, 256 Bytes) Receive (BE Data, 256 Bytes) Send (BE Data, xxx<=256 Bytes) Receive (BE Data, xxx<=256 Bytes) Send (BOOT_ROM_CHECKSUM_CMD) Receive (BOOT_ROM_CHECKSUM_CMD) Send (BE_START_ADDR, 4 Bytes) Receive (BE_START_ADDR, 4 Bytes) Send (BE Length Num of Word, 4 Bytes) Receive (BE Length Num of Word, 4 Bytes) Receive (Checksum of Receive BE, 2 Bytes ) Figure 4: Send BE LC76F_Firmware_Upgrade_Guide 12 / 22 GNSS Module Series 2.1.3. Jump to BE This section describes how to jump to BE and run it. Host Send (BOOT_ROM_JUMP_CMD) Receive (BOOT_ROM_JUMP_CMD) Send (BE_START_ADDR, 4 Bytes) Receive (BE_START_ADDR, 4 Bytes) Module Figure 5: Jump to BE 2.1.4. Sync with BE This section describes how to sync with BE in detail. Host Module Receive (SYNC_CHAR) Receive (BE_MAJOR_VER) Receive (BE_MINOR_VER) Send (BE_SPEED_CMD) Send (UART_BAUD_921600) Send (BAUDRATE_FULL_SYNC_COUNT) Receive (ACK) Host Change Baudrate Send (SYNC_CHAR) Send (SYNC_CHAR) Receive (SYNC_CHAR) Send (ACK) Receive (ACK) Figure 6: Sync with BE LC76F_Firmware_Upgrade_Guide 13 / 22 GNSS Module Series 2.1.5. Download Firmware This section describes how to download firmware to flash. Host Module Send (BE_MEM_CMD) Send (0x01) Send (FW_START_ADDR, 4 Bytes) Send (FW_END_ADDR, 4 Bytes) Receive (ACK) Receive (Num of Unchanged Data Blocks, 1 Bytes) Send (BE_WRITE_CMD) Send (PACKET_LENGTH, 4 Bytes) Send (FW First 4 Bytes, 4 Bytes) Receive (ACK) Receive (ACK) Send (FW Packet, 1024 Bytes) Send (Checksum of FW Packet, 2 Bytes) Receive (CONT_CHAR) Send (FW packet, 1024 Bytes) Send (Checksum of FW Packet, 2 Bytes) Receive (CONT_CHAR) Send (FW Packet, <=1024 Bytes) Send (Checksum of FW Packet, 2 Bytes) Receive (CONT_CHAR) Receive (ACK) Receive (ACK) SEND (BE_FINISH_CMD) Figure 7: Download Firmware LC76F_Firmware_Upgrade_Guide 14 / 22 GNSS Module Series 2.1.6. Reset This section describes how to reset the module. After firmware download process is finished, the module will output NMEA message normally. Host will try to receive NMEA message in different baud rate. Once host receive NMEA head '$', it will send NMEA_CLEAR_CMD and NMEA_RESET_CMD to reset the module in current baud rate. The firmware upgrade is completed after the module is reset. Host Module Start Start Change Baudrate No Receive NMEA Head $? Yes Send NMEA_CLEAR_CMD NMEA_RESET_CMD Receive Send Finish Output NMEA Message Receive CMD? Yes Clear and Reset Figure 8: Reset Finish LC76F_Firmware_Upgrade_Guide 15 / 22 2.2. Sample Code for Checksum Checksum Code of BE File uint16_t BE_compute_checksum (uint8_t *buf, uint32_t buf_len) { uint16_t checksum = 0; if (buf == NULL || buf_len == 0) { return 0; } int i = 0; for (i = 0; i < buf_len / 2; i++) { checksum ^= *(uint16_t *) (buf + i * 2); } if ((buf_len % 2) == 1) { checksum ^= buf[i * 2]; } return checksum; } Checksum Code of FW Packet uint32_t FW_compute_simple_checksum (uint8_t *buf, uint32_t buf_len) { uint32_t checksum = 0; if (buf == NULL || buf_len == 0) { return 0; } for (int i = 0; i < buf_len; i++) { checksum += *(buf + i); } return checksum; } GNSS Module Series LC76F_Firmware_Upgrade_Guide 16 / 22 GNSS Module Series 3 Upgrade Implementation Example In this chapter you can find the example of firmware upgrade procedure. //Host sends NMEA_START_CMD //$PGKC75*1D 24 50 47 4B 43 37 35 2A 31 44 0D 0A //Module will reset later //Host continuously sends 0x90 90 //Module outputs NMEA message as before 45 //Host continuously sends 0x90 90 //Module outputs NMEA message as before 0D //Host continuously sends 0x90 90 //Module outputs NMEA message as before 0D //Host continuously sends 0x90 90 //Module resets //Host continuously sends 0x90 90 90 //Module responds with 0x6F 6F //Host sends 0x09 09 //Module responds with 0x6F as before 6F //Module receives 0x09 and responds with 0xF6 F6 //Host sends 0x60 60 //Module responds with 0x9F 9F LC76F_Firmware_Upgrade_Guide 17 / 22 //Host sends 0x06 06 //Module responds with 0xF9 F9 //Host sends BOOT_ROM_WRITE_CMD 0xA1 A1 //Module responds with 0xA1 A1 //Host sends BE_START_ADDR 00 00 0C 00 //Module responds with BE_START_ADDR 00 00 0C 00 //Host sends BE Length Num of Word 00 00 11 80 //Module responds with BE Length Num of Word 00 00 11 80 //Host sends first Burn Engine packet (256 Bytes) 00 00 E1 A0 00 00 E1 0F 10 C0 E3 A0 00 01 E1 80 … //Module responds with first Burn Engine packet (256 Bytes) 00 00 E1 A0 00 00 E1 0F 10 C0 E3 A0 00 01 E1 80 … //Host sends second Burn Engine packet (256 Bytes) 20 00 E0 82 00 00 20 83 00 04 21 50 30 08 85 91 … //Module responds with second Burn Engine packet (256 Bytes) 20 00 E0 82 00 00 20 83 00 04 21 50 30 08 85 91 … … //Host sends last Burn Engine packet (<= 256 Bytes) 00 00 00 40 00 00 00 00 00 08 00 00 20 00 00 00 … //Module responds with last Burn Engine packet (<=256 Bytes) 00 00 00 40 00 00 00 00 00 08 00 00 20 00 00 00 … //Host sends BOOT_ROM_CHECKSUM_CMD A4 //Module responds with BOOT_ROM_CHECKSUM_CMD A4 //Host sends BE_START_ADDR 00 00 0C 00 //Module responds with BE_START_ADDR 00 00 0C 00 //Host sends BE Length Num of Word 00 00 11 80 //Module responds with BE Length Num of Word 00 00 11 80 //Module responds with checksum 40 69 //Host sends BOOT_ROM_JUMP_CMD LC76F_Firmware_Upgrade_Guide GNSS Module Series 18 / 22 A8 //Module responds with BOOT_ROM_JUMP_CMD A8 //Host sends BE_START_ADDR 00 00 0C 00 //Module responds with BE_START_ADDR 00 00 0C 00 //Module responds with SYNC_CHAR B0 //Module responds with BE_MAJOR_VER 01 //Module responds with BE_MINOR_VER 00 //Host sends BE_SPEED_CMD E1 //Host sends UART_BAUD_921600 01 //Host sends BAUDRATE_FULL_SYNC_COUNT 00 //Module responds with ACK 6B //Host changes baud rate to 921600 //Host sends SYNC_CHAR B0 //Module tries to respond with SYNC_CHAR in difference baud rate 00 //Host sends SYNC_CHAR B0 //Module tries to respond with SYNC_CHAR in difference baud rate 00 //Host sends SYNC_CHAR B0 //Module tries to respond with SYNC_CHAR in difference baud rate AA //Host sends SYNC_CHAR B0 //Module tries to respond with SYNC_CHAR in difference baud rate //Sync success B0 //Host sends ACK 6B //Module responds with ACK 6B //Host sends BE_MEM_CMD LC76F_Firmware_Upgrade_Guide GNSS Module Series 19 / 22 E2 //Host sends 0x01 01 //Host sends FW_START_ADDR 00 00 00 00 //Host sends FW_END_ADDR 00 08 E0 0B //Module responds with ACK 6B //Module responds with number of unchanged data blocks 00 //Host sends BE_WRITE_CMD E3 //Host sends packet length //0x00000400 = 1024 Bytes 00 00 04 00 //Host sends firmware first 4 bytes 82 DA 39 D6 //Module responds with ACK when burn engine has saved unchanged data 6B //Module responds with ACK when sector erase done 6B //Host sends first firmware packet except first 4 Bytes (1024 Bytes) F9 CD F9 B7 DE 21 2E 3C 94 58 17 58 95 71 2D 83 … //Host sends checksum of first firmware packet (2 Bytes) F2 4D //Module responds with CONT_CHAR (continue char) B9 //Host sends second firmware packet (1024 Bytes) C2 B7 FA 50 50 75 7B 3C 49 45 96 BF 7E E9 97 52 … //Host sends checksum of first firmware packet (2 Bytes) F4 27 //Module responds with CONT_CHAR (continue char) B9 … //Host sends last firmware packet (<= 1024 Bytes) 7B AD BA 9B 90 94 8D 57 //Host sends checksum of last firmware packet (2 Bytes) 04 85 //Module responds with CONT_CHAR (continue char) B9 //Module responds with ACK when firmware upgrade was done 6B //Module responds with ACK when checksum was done GNSS Module Series LC76F_Firmware_Upgrade_Guide 20 / 22 6B //Host sends BE_FINISH_CMD E5 //Host changes baud rate to 9600 //Module sends NMEA messages ($GNTXT,GK9501*7Crn) 24 47 4E 54 58 54 2C 47 4B 39 35 30 31 2A 37 43 0D 0A //Host sends NMEA_CLEAR_CMD ($PGKC41*1Arn) 24 50 47 4B 43 34 31 2A 31 41 0D 0A //Host sends NMEA_RESET_CMD ($PGKC30,3,1*1Ern) 24 50 47 4B 43 33 30 2C 33 2C 31 2A 31 45 0D 0A GNSS Module Series LC76F_Firmware_Upgrade_Guide 21 / 22 GNSS Module Series 4 Appendix Reference Table 3: Terms and Abbreviations Abbreviation ACK BE CMD FW GNSS NMEA UART Description Acknowledge Burn Engine Command Firmware Global Navigation Satellite System NMEA (National Marine Electronics Association) 0183 Interface Standard Universal Asynchronous Receiver/Transmitter LC76F_Firmware_Upgrade_Guide 22 / 22
236.46 KB
EP06&EG06&EM06 Series Software Configuration for AT&T Data Only LTE-A Module Series Version: 1.0 Date: 2021-11-11 Status: Released LTE-A Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. EP06&EG06&EM06_Series_Software_Configuration_for_AT&T_Data_Only 1 / 11 LTE-A Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2021. All rights reserved. EP06&EG06&EM06_Series_Software_Configuration_for_AT&T_Data_Only 2 / 11 LTE-A Module Series About the Document Revision History Version 1.0 Date 2021-07-05 2021-11-11 Author Description Dennis FENG Creation of the document Dennis FENG First official release EP06&EG06&EM06_Series_Software_Configuration_for_AT&T_Data_Only 3 / 11 LTE-A Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 2 Background ......................................................................................................................................... 7 3 Software Configuration ...................................................................................................................... 8 3.1. Disable Voice and ECC ............................................................................................................. 8 3.2. Configure ue_usage_setting ...................................................................................................... 8 3.3. Disable IMS ................................................................................................................................ 9 3.4. Configure SMS Only .................................................................................................................. 9 3.5. Set Correct APN......................................................................................................................... 9 3.5.1. AT&T (U)SIM Card.......................................................................................................... 9 3.5.2. FirstNet (U)SIM Card .................................................................................................... 10 3.6. Reboot the Module................................................................................................................... 10 4 Appendix References ....................................................................................................................... 11 EP06&EG06&EM06_Series_Software_Configuration_for_AT&T_Data_Only 4 / 11 LTE-A Module Series Table Index Table 1: Related Documents...................................................................................................................... 11 Table 2: Terms and Abbreviations ............................................................................................................. 11 EP06&EG06&EM06_Series_Software_Configuration_for_AT&T_Data_Only 5 / 11 LTE-A Module Series 1 Introduction AT&T requires devices certified as Data Only (only data supported) to use modules certified as Data Only. To help users optimize the operation of their devices for AT&T technology approval test requirements and reduce the time required for completing device certification, AT&T Data Only certification requires Quectel Data + Voice modules (both voice and data supported) to be configured on the device used. This document mainly explains how to switch the following Quectel modules from Data + Voice to Data Only through software configuration. ⚫ EP06-A ⚫ EG06-A ⚫ EM06-A EP06&EG06&EM06_Series_Software_Configuration_for_AT&T_Data_Only 6 / 11 LTE-A Module Series 2 Background AT&T 13340 V21.1 has the following configuration requirements for Data Only modules and devices. Figure 1: Background of AT&T Requirements for Data Only Modules and Devices EP06&EG06&EM06_Series_Software_Configuration_for_AT&T_Data_Only 7 / 11 LTE-A Module Series 3 Software Configuration This chapter mainly introduces steps of switching the module from Data + Voice to Data Only through software configuration. 3.1. Disable Voice and ECC Execute the following commands to disable voice and ECC. AT+QNVW=5280,0,'0102000000000000' OK AT+QNVR=5280,0 +QNVR: '0102000000000000' //Disable voice and ECC //Query current configuration OK 3.2. Configure ue_usage_setting Sequentially execute the following commands to configure ue_usage_setting as Data Centric as required by AT&T. AT+QNVFW='/nv/item_files/modem/mmode/ue_usage_setting',01 OK AT+QNVFR='/nv/item_files/modem/mmode/ue_usage_setting' +QNVFR: 01 //Configure ue_usage_setting as Data Centric //Query current configuration OK EP06&EG06&EM06_Series_Software_Configuration_for_AT&T_Data_Only 8 / 11 LTE-A Module Series 3.3. Disable IMS Sequentially execute the following commands to disable IMS. AT+QNVFW='/nv/item_files/ims/IMS_enable',00 OK AT+QNVFR='/nv/item_files/ims/IMS_enable' +QNVFR: 00 OK //Disable IMS //Query current configuration 3.4. Configure SMS Only Sequentially execute the following commands to configure UE as SMS Only (only SMS supported). AT+QNVFW='/nv/item_files/modem/mmode/sms_only',01 OK AT+QNVFR='/nv/item_files/modem/mmode/sms_only' +QNVFR: 01 //Configure the UE as SMS Only according to AT&T requirements for Data Only device //Query current configuration OK 3.5. Set Correct APN According to the (U)SIM card being used, sequentially execute the following commands to configure the first APN as the specified APN. See document [1] for more information on the AT commands given below. 3.5.1. AT&T (U)SIM Card If you insert an AT&T (U)SIM card, execute the following commands to configure the first APN as 'broadband'. AT+CGDCONT=1,'IPV4V6','broadband' //Set the first APN to AT&T’s default Data Only APN 'broadband'. If there is a customized APN, please EP06&EG06&EM06_Series_Software_Configuration_for_AT&T_Data_Only 9 / 11 LTE-A Module Series replace 'broadband' with the customized APN AT+CGDCONT? //Query current configuration +CGDCONT: 1,'IPV4V6','broadband','0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0',0,0,0,0 +CGDCONT: 2,'IPV4V6','ims','0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0',0,0,0,0 +CGDCONT: 3,'IPV4V6','SOS','0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0',0,0,0,1 OK 3.5.2. FirstNet (U)SIM Card If you insert an AT&T FirstNet (U)SIM card, execute the following commands to configure the first APN as 'firstnet-broadband'. AT+CGDCONT=1,'IPV4V6','firstnet-broadband' // Set the first APN as AT&T FirstNet’s default Data Only APN 'firstnet-broadband'. If there is a customized APN, please replace 'firstnet-broadband' with the customized APN OK AT+CGDCONT? //Query current configuration +CGDCONT: 1,'IPV4V6','firstnet-broadband','0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0',0,0,0,0 +CGDCONT: 2,'IPV4V6','ims','0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0',0,0,0,0 +CGDCONT: 3,'IPV4V6','SOS','0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0',0,0,0,1 OK 3.6. Reboot the Module Manually reboot the module to allow the above configurations to take effect. ⚫NOTE Every time the module is switched to an AT&T or AT&T FirstNet (U)SIM card from a (U)SIM card of another carrier or switches between the AT&T (U)SIM card and the FirstNet (U)SIM card, reconfigure the module software as Data Only according to the description in Chapter 3. EP06&EG06&EM06_Series_Software_Configuration_for_AT&T_Data_Only 10 / 11 LTE-A Module Series 4 Appendix References Table 1: Related Documents Document Name [1] Quectel_EP06&EG06&EM06_AT_Commands_Manual Table 2: Terms and Abbreviations Abbreviation APN CS ECC EPS IMSI IMS IoT LTE PS SMS TA TAU UE (U)SIM Description Access Point Name Circuit Switched Emergency Call Code Evolved Packet System International Mobile Subscriber Identity IP Multimedia Subsystem Internet of Things Long-Term Evolution Packet Switched Short Message Service Terminal Adapter Tracking Area Update User Equipment (Universal) Subscriber Identity Module EP06&EG06&EM06_Series_Software_Configuration_for_AT&T_Data_Only 11 / 11
330.89 KB
LC29D AGNSS Application Note GNSS Module Series Version: 1.0 Date: 2021-11-01 Status: Released GNSS Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. LC29D_AGNSS_Application_Note 1 / 18 GNSS Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2021. All rights reserved. LC29D_AGNSS_Application_Note 2 / 18 GNSS Module Series About the Document Document Information Title Subtitle Document Type Document Status LC29D AGNSS Application Note GNSS Module Series Application Note Released Revision History Version 1.0 Date 2021-08-16 2021-11-01 Description Creation of the document First official release LC29D_AGNSS_Application_Note 3 / 18 GNSS Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 2 AGNSS Implementation...................................................................................................................... 7 2.1. Bream Messages for AGNSS Implementation .......................................................................... 7 2.1.1. BRM-AST-LTO (0x13 0x20) ............................................................................................ 7 2.1.2. BRM-AST-REF_LOCATION (0x13 0x40) ....................................................................... 8 2.1.3. BRM-AST-REF_TIME_UTC (0x13 0x40) ....................................................................... 9 2.2. Download LTO File from AGNSS Server ................................................................................. 10 2.3. LTO File Format ........................................................................................................................11 2.4. Send LTO Data to the Module ..................................................................................................11 3 AGNSS Testing Procedures ............................................................................................................ 13 3.1. Prerequisites ............................................................................................................................ 13 3.2. Procedures ............................................................................................................................... 13 3.3. Results ..................................................................................................................................... 17 4 Appendix References ....................................................................................................................... 18 LC29D_AGNSS_Application_Note 4 / 18 GNSS Module Series Table Index Table 1: BRM-AST-LTO Message Structure ................................................................................................ 7 Table 2: BRM-AST-LTO Message Content .................................................................................................. 7 Table 3: BRM-AST-REF_LOCATION Message Structure ........................................................................... 8 Table 4: BRM-AST-REF_LOCATION Message Content ............................................................................. 8 Table 5: BRM-AST-REF_TIME_UTC Message Structure............................................................................ 9 Table 6: BRM-AST-REF_TIME_UTC Message Content ............................................................................. 9 Table 7: Related Documents ...................................................................................................................... 18 Table 8: Terms and Abbreviations .............................................................................................................. 18 LC29D_AGNSS_Application_Note 5 / 18 GNSS Module Series 1 Introduction The LC29D GNSS module supports the AGNSS feature that significantly reduces the module’s TTFF, especially in challenging signal conditions scenarios. To implement the AGNSS feature, the module should get the assistance data including the current time, rough position, and LTO data. Consult the following chapter to find out how to send the assistance data to the module. The list of Bream messages used by the AGNSS feature is also provided for your reference. Before using the AGNSS feature, make sure to verify that everything is set up correctly. For more information on testing the module, see Chapter 3. LC29D_AGNSS_Application_Note 6 / 18 GNSS Module Series 2 AGNSS Implementation This chapter explains AGNSS implementation on the LC29D GNSS module and the procedure for sending LTO data to the module. It also includes the list of Bream messages. 2.1. Bream Messages for AGNSS Implementation The LC29D module can be controlled and configured through Bream input messages defined by the chipset supplier. 2.1.1. BRM-AST-LTO (0x13 0x20) Message for injecting a six-hour Bream LTO page into the GNSS device. You can download the Bream LTO file from Quectel AGNSS server. For details, see Chapter 2.2. Type: Input. Table 1: BRM-AST-LTO Message Structure Header 0xB5 0x62 Message Group 0x13 Message Number 0x20 Length (Bytes) 76 Content Checksum See Table 2: BRM-AST-LTO CHK1 CHK2 Message Content. Table 2: BRM-AST-LTO Message Content Byte Offset C99 0 uint8_t 1 uint8_t 2 uint8_t Scaling Name - Type - Version - SvID Unit Description - Message type (0x00). - Message version (0x00). Satellite identifier. For details, see - document [1]. LC29D_AGNSS_Application_Note 7 / 18 GNSS Module Series GNSS identifier. For details, see 3 uint8_t - GNSS_ID - document [1]. 4 uint8_t - Year - Years since 2000. 5 uint8_t - Month - Month (1–12). 6 uint8_t - Day - Day (1–31). 7 uint8_t - Reserved - Reserved. 8 uint8_t[64] - Data - Assistance data. 72 uint8_t[4] - FCT s Full-cycle time (FCT). 2.1.2. BRM-AST-REF_LOCATION (0x13 0x40) Reference position assistance. The message allows the delivery of position-assistance data to the GNSS device. Type: Input. Table 3: BRM-AST-REF_LOCATION Message Structure Header Message Group Message Number Length (Bytes) 0xB5 0x62 0x13 0x40 20 Content See Table 4: BRM-AST-REF_LOCATION Message Content. Checksum CHK1 CHK2 Table 4: BRM-AST-REF_LOCATION Message Content Byte Offset C99 Scaling Name Unit 0 uint8_t - Type - 1 uint8_t - Reserved1 - 2 uint8_t[2] - Reserved2 - 4 int32_t 1e-7 Lat Degree 8 int32_t 1e-7 Lon Degree Description Message type (0x01). Reserved. Reserved. WGS84 latitude. WGS84 longitude. LC29D_AGNSS_Application_Note 8 / 18 GNSS Module Series 12 int32_t - Alt cm WGS84 altitude. Position accuracy (standard deviation 16 uint32_t - PosAcc cm in 3D, both horizontal and vertical). NOTE Supplying position assistance inaccurate by more than the specified position accuracy may lead to substantially degraded receiver performance. 2.1.3. BRM-AST-REF_TIME_UTC (0x13 0x40) Reference time assistance. The message allows the delivery of UTC time assistance to the GNSS device. Type: Input. Table 5: BRM-AST-REF_TIME_UTC Message Structure Header 0xB5 0x62 Message Group 0x13 Message Number Length (Bytes) 0x40 24 Content Checksum See Table 6: BRM-AST-REF_TIME_UTC Message Content. CHK1 CHK2 Table 6: BRM-AST-REF_TIME_UTC Message Content Byte Offset C99 0 uint8_t 1 uint8_t 2 uint8_t 3 int8_t 4 uint16_t 6 uint8_t 7 uint8_t Scaling Name Unit - Type - - Version - - Reserved1 - - LeapSecs s - Year - - Month - - Day - Description Message type (0x10). Message version (0x00). Reserved. Number of leap seconds since 1980 (or 0x80 = –128 if unknown). Year. Month (1–12). Day (1–31). LC29D_AGNSS_Application_Note 9 / 18 GNSS Module Series 8 uint8_t - Hour - Hour (0–23). 9 uint8_t - Minute - Minute (0–59). 10 uint8_t - Second - Seconds (0–59). 11 uint8_t - Reserved2 - Reserved. 12 uint32_t - Nano - Nanoseconds (0–999,999,999). 16 uint16_t - TAccS s Seconds part of time accuracy. 18 uint8_t[2] - Reserved3 - Reserved. Nanoseconds part of time accuracy 20 uint32_t - TAccNs ns (0–999,999,999). NOTE Supplying the time-assistance data surpassing the specified time accuracy may lead to substantially degraded receiver performance. 2.2. Download LTO File from AGNSS Server Before sending LTO data to the module, the host must download the LTO file. The LTO file can be downloaded from Quectel AGNSS server, and it is valid up to 7 days. Quectel AGNSS server: ftp://agnss.queclocator.com Quectel AGNSS server supports the download of LTO files that have 2 or 7-day validity. The LTO files have the ' ltoXdv5.brm' naming structure, where the X refers to the days of validity and can be either of the following options: 2 or 7. NOTE 1. Quectel AGNSS server is free of charge and there is no SLA while using the server. However, you must have an account to access and use the Quectel AGNSS server. Contact Quectel’s Technical Support Team (support@quectel.com) to apply for an account. 2. You must create your own server instance and download the LTO files. LC29D_AGNSS_Application_Note 10 / 18 GNSS Module Series 2.3. LTO File Format The LTO file is composed of multiple BRM-AST-LTO messages as can be seen from the following figure. Figure 1: LTO File Format 2.4. Send LTO Data to the Module Before sending LTO data to the module, the host must read BRM-AST-LTO messages from the LTO file, and check if the time is valid (within 3 hours before or after the current time). Once the validity of time is confirmed, the host sends successive valid BRM-AST-LTO messages to the module, until the end of LTO file is reached. LC29D_AGNSS_Application_Note 11 / 18 Sample code for checking LTO message validity: int64_t time_unix = get_unix_epoch(); int64_t time_diff = FCT+315964800 - time_unix; int64_t time_threshold = 10800; // 3 hours if((time_diff > -time_threshold) && (time_diff < time_threshold)) { // Current BRM-AST-LTO message is valid. } else { // Current BRM-AST-LTO message is not valid. } GNSS Module Series LC29D_AGNSS_Application_Note 12 / 18 GNSS Module Series 3 AGNSS Testing Procedures This chapter illustrates how to test the AGNSS feature by using the Quectel’s QGNSS tool. 3.1. Prerequisites Before testing the AGNSS function, make sure that you have done the following: 1. You have connected the LC29D EVB to your computer. 2. You have downloaded the QGNSS tool and set the corresponding serial port number, baud rate 1), and the module’s model. 3. You have created the account for Quectel AGNSS server 2), and you are connected to the AGNSS server through the QGNSS tool. To make the effect of the AGNSS feature on TTFF value more noticeable, you could first get a position fix without using the AGNSS feature. After the testing procedure, you can compare the TTFF results. NOTE 1. 1) The default baud rate of the LC29D module is 115200 bps. 2. 2) Contact Quectel’s Technical Support Team (support@quectel.com) for information on how to get access to Quectel AGNSS server. 3.2. Procedures To test the AGNSS function in a cold start session: 1. Send BRM-STP-RESET command to the module to perform a cold start. For details, see document [1]. 2. Send BRM-AST-REF_LOCATION command to the module to inject the assistance position. 3. Send BRM-AST-REF_TIME_UTC command to the module to inject the assistance time. LC29D_AGNSS_Application_Note 13 / 18 GNSS Module Series 4. Send LTO data to the module: 1) Download the LTO file from the AGNSS server. 2) Check BRM-AST-LTO message validity. 3) If messages are valid, send the BRM-AST-LTO messages to the module. Example: 1. The steps on QGNSS tool. a) Run the QGNSS tool. b) In the main interface, click 'AGNSS' -> 'Assistant GNSS Online' to enter the Download window. c) Click the 'Connect' button to connect the FTP server and select the LTO file with 2 or 7-day validity. d) Click the 'Download selected file' button to download the LTO file to your computer. e) Click the 'Select file' button to select the LTO file downloaded to your computer and then click 'Using UTC time', 'Cold start', 'Position' and 'AGNSS Data'. f) Enter latitude and longitude manually. g) Click the 'Reset and Transfer' button to send the LTO file to the module. LC29D_AGNSS_Application_Note 14 / 18 GNSS Module Series 2. Detailed commands for each step. a) Host sends a cold start command. B5 62 06 04 04 00 FF FF 02 00 0E 61 // NMEA messages output from the module: $GNGNS,000001.00,,,,,NNNNNN,00,99.0,,,,,V*18 $GNRMC,000001.00,V,,,,,,,010712,,,N,V*1D $GNGNS,000001.00,,,,,NNNNNN,00,99.0,,,,,V*18 $GPGSV,1,1,01,05,,,38,1*6B $GNRMC,000001.00,V,,,,,,,010712,,,N,V*1D $GNGNS,000002.00,,,,,NNNNNN,00,99.0,,,,,V*1B $GPGSV,1,1,01,05,,,38,1*6B $GNRMC,000002.00,V,,,,,,,010712,,,N,V*1E $GNGNS,000003.00,,,,,NNNNNN,00,99.0,,,,,V*1A $GPGSV,1,1,01,05,,,41,1*65 $GNRMC,000003.00,V,,,,,,,010712,,,N,V*1F … LC29D_AGNSS_Application_Note 15 / 18 GNSS Module Series b) Host injects the assistance position to the module. B5 62 13 40 14 00 01 00 00 00 8A AF F7 12 C1 5C CE 45 00 00 00 00 00 00 00 00 DA 1A c) Host injects the assistance time to the module. B5 62 13 40 18 00 10 00 00 80 E5 07 09 02 01 25 22 00 00 00 00 00 00 00 00 00 00 00 00 00 3A 88 d) Host injects the LTO data to the module. B5 62 13 20 4C 00 00 00 02 00 15 08 1F 00 00 CC BB 00 DB 60 00 06 1F A0 78 47 DF AE 95 FD FD 18 9C FD DA 39 4D 75 2E 85 AE FD 35 85 5D FB C4 FD 86 D0 CC FF E2 9D 17 17 43 8A D1 49 0D 00 39 09 95 12 22 FC C1 B0 81 B2 E8 FF 00 40 1F D0 D0 4C 59 4E 1C E4 B5 62 13 20 4C 00 00 00 03 00 15 08 1F 00 00 CC BB 00 C0 60 00 0A 1F A0 78 87 D4 84 BB F1 A3 17 93 FB 77 B7 64 D9 FD 80 39 7C A5 08 F9 57 68 22 87 D0 0B C0 E2 1D 63 16 B3 D5 E2 C9 08 40 02 87 67 72 2F ED D5 49 43 9C EA 3F 00 40 1F 4A D0 4C 59 4E C2 DC … // NMEA messages output from the module. $GNGNS,070006.00,,,,,NNNNNN,00,99.0,,,,,V*18 $GPGSV,1,1,01,05,,,38,1*6B $GNRMC,070006.00,V,,,,,,,010921,,,N,V*13 $GNGNS,070007.00,,,,,NNNNNN,00,99.0,,,,,V*19 $GPGSV,1,1,01,05,,,40,1*64 $GNRMC,070007.00,V,,,,,,,010921,,,N,V*12 $GNGNS,070008.00,,,,,NNNNNN,00,99.0,,,,,V*16 $GPGSV,1,1,03,05,,,40,13,,,41,15,,,40,1*61 $GNRMC,070008.00,V,,,,,,,010921,,,N,V*1D $GNGNS,070009.00,,,,,NNNNNN,00,99.0,,,,,V*17 $GPGSV,1,1,04,05,,,40,13,,,41,15,,,43,18,,,40,1*68 $GNRMC,070009.00,V,,,,,,,010921,,,N,V*1C $GNGNS,070010.00,,,,,NNNNNN,00,99.0,,,,,V*1F $GPGSV,2,1,05,05,,,41,13,,,41,15,,,43,18,,,40,1*6B $GPGSV,2,2,05,23,,,37,1*64 $GNRMC,070010.00,V,,,,,,,010921,,,N,V*14 $GNGNS,070011.00,,,,,NNNNNN,00,1.6,,,,,V*29 $GPGSV,2,1,06,05,46,068,41,13,,,42,15,73,348,43,18,48,314,40,1*56 $GPGSV,2,2,06,23,25,301,38,29,27,227,38,1*6F $GNRMC,070011.00,V,,,,,,,010921,,,N,V*15 // 1st second // 2nd second // 3rd second // 4th second // 5th second // 6th second // Module gets a fix in the 7th second. $GNGNS,070012.00,3149.331528,N,11706.913889,E,AANNNN,06,1.4,63.6,-3.3,,,V*09 $GPGSV,2,1,06,05,46,068,40,13,,,42,15,73,348,43,18,48,314,40,1*57 $GPGSV,2,2,06,23,25,301,37,29,27,227,38,1*60 $GLGSV,1,1,01,78,23,082,37,1*49 $GNRMC,070012.00,A,3149.331528,N,11706.913889,E,000.0,,010921,,,E,V*1D $GNGNS,070014.80,3149.333195,N,11706.913018,E,AANNNN,06,1.4,61.8,-3.3,,,V*0B LC29D_AGNSS_Application_Note 16 / 18 GNSS Module Series $GPGSV,2,1,06,05,46,068,41,13,,,42,15,73,349,43,18,48,314,41,1*56 $GPGSV,2,2,06,23,25,301,38,29,27,227,39,1*6E $GLGSV,1,1,02,78,23,081,37,70,,,25,1*49 $GNRMC,070014.80,A,3149.333195,N,11706.913018,E,001.0,190.1,010921,,,E,V*35 $GNGNS,070015.79,3149.333138,N,11706.912789,E,AANANN,07,1.1,61.6,-3.3,,,V*00 $GPGSV,2,1,06,05,46,068,41,13,,,42,15,73,349,44,18,48,314,41,1*51 $GPGSV,2,2,06,23,25,301,38,29,27,227,39,1*6E $GLGSV,1,1,01,78,23,081,36,1*4B $GBGSV,1,1,02,206,60,219,36,209,43,217,35,1*77 $GNRMC,070015.79,A,3149.333138,N,11706.912789,E,000.0,,010921,,,E,V*1D 3.3. Results When the GNSS engine is started, the module will try to get a position fix. If the AGNSS feature is not enabled, the module gets a position fix within about 30 seconds of a cold start. If the AGNSS feature is enabled, the module gets a position fix in about 10 seconds or less. LC29D_AGNSS_Application_Note 17 / 18 GNSS Module Series 4 Appendix References Table 7: Related Documents Document Name [1] Quectel_LC29D_GNSS_Protocol_Specification [2] Quectel_QGNSS_User_Guide Table 8: Terms and Abbreviations Abbreviation AGNSS C99 EVB FCT FTP GNSS LTO SLA TTFF UTC WGS84 Description Assisted GNSS ISO/IEC 9899:1999 - Programming languages - C Evaluation Board Full-Cycle Time File Transfer Protocol Global Navigation Satellite System Long Term Orbit Software License Agreement Time to First Fix Universal Time Coordinated World Geodetic System 1984 LC29D_AGNSS_Application_Note 18 / 18
338.51 KB
LC79D (A) Firmware Upgrade Guide GNSS Module Series Ver. LC79D(A)_Firmware_Upgrade_Guide_V1.0 Date: 2020-07-28 Status: Released www.quectel.com GNSS Module Series LC79D (A) Firmware Upgrade Guide Our aim is to provide customers with timely and comprehensive service. For any assistance, please contact our company headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local office. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm or email to support@quectel.com. GENERAL NOTES QUECTEL OFFERS THE INFORMATION AS A SERVICE TO ITS CUSTOMERS. THE INFORMATION PROVIDED IS BASED UPON CUSTOMERS’ REQUIREMENTS. QUECTEL MAKES EVERY EFFORT TO ENSURE THE QUALITY OF THE INFORMATION IT MAKES AVAILABLE. QUECTEL DOES NOT MAKE ANY WARRANTY AS TO THE INFORMATION CONTAINED HEREIN, AND DOES NOT ACCEPT ANY LIABILITY FOR ANY INJURY, LOSS OR DAMAGE OF ANY KIND INCURRED BY USE OF OR RELIANCE UPON THE INFORMATION. ALL INFORMATION SUPPLIED HEREIN IS SUBJECT TO CHANGE WITHOUT PRIOR NOTICE. DISCLAIMER WHILE QUECTEL HAS MADE EFFORTS TO ENSURE THAT THE FUNCTIONS AND FEATURES UNDER DEVELOPMENT ARE FREE FROM ERRORS, IT IS POSSIBLE THAT THESE FUNCTIONS AND FEATURES COULD CONTAIN ERRORS, INACCURACIES AND OMISSIONS. UNLESS OTHERWISE PROVIDED BY VALID AGREEMENT, QUECTEL MAKES NO WARRANTIES OF ANY KIND, IMPLIED OR EXPRESS, WITH RESPECT TO THE USE OF FEATURES AND FUNCTIONS UNDER DEVELOPMENT. TO THE MAXIMUM EXTENT PERMITTED BY LAW, QUECTEL EXCLUDES ALL LIABILITY FOR ANY LOSS OR DAMAGE SUFFERED IN CONNECTION WITH THE USE OF THE FUNCTIONS AND FEATURES UNDER DEVELOPMENT, REGARDLESS OF WHETHER SUCH LOSS OR DAMAGE MAY HAVE BEEN FORESEEABLE. COPYRIGHT THE INFORMATION CONTAINED HERE IS PROPRIETARY TECHNICAL INFORMATION OF QUECTEL WIRELESS SOLUTIONS CO., LTD. TRANSMITTING, REPRODUCTION, DISSEMINATION AND EDITING OF THIS DOCUMENT AS WELL AS UTILIZATION OF THE CONTENT WITHOUT PERMISSION ARE FORBIDDEN. OFFENDERS WILL BE HELD LIABLE FOR PAYMENT OF DAMAGES. ALL RIGHTS ARE RESERVED IN THE EVENT OF A PATENT GRANT OR REGISTRATION OF A UTILITY MODEL OR DESIGN. Copyright © Quectel Wireless Solutions Co., Ltd. 2020. All rights reserved. LC79D(A)_Firmware_Upgrade_Guide 1 / 15 GNSS Module Series LC79D (A) Firmware Upgrade Guide About the Document Revision History Version 1.0 Date Author Description 2020-07-28 Jenn XIANG Initial LC79D(A)_Firmware_Upgrade_Guide 2 / 15 GNSS Module Series LC79D (A) Firmware Upgrade Guide Contents About the Document .................................................................................................................................. 2 Contents ...................................................................................................................................................... 3 Table Index.................................................................................................................................................. 4 Figure Index ................................................................................................................................................ 5 1 Introduction ......................................................................................................................................... 6 2 Firmware Upgrade Process ............................................................................................................... 7 2.1. Connect the Module ................................................................................................................... 7 2.2. Send Firmware Upgrade Command .......................................................................................... 7 2.3. Synchronize Module .................................................................................................................. 8 2.4. Write Options and Change UART Baud Rate............................................................................ 9 2.5. Erase Code .............................................................................................................................. 10 2.6. Erase NVM and LTO .................................................................................................................11 2.7. Send Data .................................................................................................................................11 2.8. CRC Error Check ......................................................................................................................11 2.9. Upgrade Flowchart................................................................................................................... 12 3 Upgrade Implementation Example.................................................................................................. 13 4 Appendix A References.................................................................................................................... 15 LC79D(A)_Firmware_Upgrade_Guide 3 / 15 GNSS Module Series LC79D (A) Firmware Upgrade Guide Table Index Table 1: List of Constants ............................................................................................................................. 7 Table 2: Structure of the Binary Image Options ........................................................................................... 9 Table 3: Related Documents ...................................................................................................................... 15 Table 4: Terms and Abbreviations .............................................................................................................. 15 LC79D(A)_Firmware_Upgrade_Guide 4 / 15 GNSS Module Series LC79D (A) Firmware Upgrade Guide Figure Index Figure 1: Firmware Upgrade Connection..................................................................................................... 6 Figure 2: Firmware Upgrade Flowchart ..................................................................................................... 12 LC79D(A)_Firmware_Upgrade_Guide 5 / 15 GNSS Module Series LC79D (A) Firmware Upgrade Guide 1 Introduction This document introduces how to upgrade the firmware on Quectel LC79D (A) module. Following this procedure, you can download the firmware to the target side via UART. HOST UART GNSS Module Figure 1: Firmware Upgrade Connection LC79D(A)_Firmware_Upgrade_Guide 6 / 15 GNSS Module Series LC79D (A) Firmware Upgrade Guide 2 Firmware Upgrade Process This section introduces all the necessary steps of the firmware upgrade process. Make sure that the GNSS software is installed on the module before you start with the firmware upgrade process. For the communication with the module, QGNSS tool can be used. For more information about the tool, see document [1]. The following table defines all the constants used in this document. Table 1: List of Constants Constant Name FLASHER_IDENTIFIER FLASHER_SYNC DEVICE_START_COMMUNICATION FLASHER_READY ACK NAK Constant Value 0x047755B1 0x5142131C 0xA3 0x4A 0xCC 0xDD 2.1. Connect the Module Connect the module to the host via an NMEA port. 2.2. Send Firmware Upgrade Command After the module is connected to the host, the firmware upgrade command $PQFWUPGRADE starts the firmware upgrade procedure. The firmware upgrade command is described as follows: LC79D(A)_Firmware_Upgrade_Guide 7 / 15 Synopsis $PQFWUPGRADE* GNSS Module Series LC79D (A) Firmware Upgrade Guide Arguments Parameter checksum Format Hexadecimal, 2 digits Description Checksum of the message bytes between but not including the $ and * characters Result In case of a successful execution of the command, the module responds with the following message, indicating that the module invalidates current firmware and switches into the firmware upgrade mode until a new firmware is downloaded and validated: $PSTMFWUPGRADEOK* In case of an error, the following message is returned by the module, indicating that the host can quit the upgrade process when an error occurs on the module’s side: $PSTMFWUPGRADEERROR* NOTE Commands are transmitted in the string format via an NMEA port. 2.3. Synchronize Module As soon as the module receives the firmware upgrade command, GNSS firmware resets the hardware and enters into firmware upgrade mode. The software running on the host can then start to synchronize with the module. In this phase the host continuously sends FLASHER_IDENTIFIER; at the same time, it checks whether there is a response from the module. In order to complete the synchronization phase, the module sends back the FLASHER_SYNC. Host software can use a timeout of 3 seconds (recommended waiting time); if no response is received in this time interval, host software returns a timeout error. As soon as the host receives FLASHER_SYNC, it sends DEVICE_START_COMMUNICATION and waits LC79D(A)_Firmware_Upgrade_Guide 8 / 15 for ACK response from the module. GNSS Module Series LC79D (A) Firmware Upgrade Guide NOTE All the constant values are transmitted in the little-endian format. For example, the constant value for FLASHER_IDENTIFIER is 0x047755B1, which the host transmits as B1 55 77 04. 2.4. Write Options and Change UART Baud Rate Right after the synchronization with the device, the host must send the binary image options. These options are packed inside the following structure: //Binary image options struct ImageOptions { byte eraseNVM; byte eraseLTO; byte reserved; byte baudRate; int firmwareSize; uint firmwareCRC; int reserved0; int reserved1; }; The total size of the structure is 20 bytes, which means that the size of int type is 4 bytes. In the table below, you can find more details about the structure of the binary image options. Table 2: Structure of the Binary Image Options Field eraseNVM eraseLTO reserved baudRate Type byte byte byte byte Description The possible values are true (1) or false (0). If true, the NVM flash memory area will be erased during upgrade. The possible values are true (1) or false (0). If true, the LTO area will be erased during upgrade. Must be 0 The new UART baud rate used to download the firmware. The possible values are: LC79D(A)_Firmware_Upgrade_Guide 9 / 15 GNSS Module Series LC79D (A) Firmware Upgrade Guide firmwareSize int firmwareCRC uint reserved0 int Reserved1 int 0 = 57600 bps 1 = 115200 bps 2 = 230400 bps 3 = 460800 bps 4 = 921600 bps The file size of the firmware binary image (in little-endian format). The CRC32 code calculated first on the field of an image file size (in little-endian format) and then over entire firmware image payload. Must be 0x0010000 (in little-endian format). Must be 0x0010000 (in little-endian format). After receiving the correct option bytes, if the baud rate option is changed, the module switches to the new baud rate and waits for FLASHER_READY. The host keeps sending FLASHER_READY. Once the module gets the correct FLASHER_READY, it sends ACK twice back to the host and then erases the code area. Example 00 00 00 04 00 20 04 00 E8 FD 91 F0 00 00 10 00 00 00 10 00 //eraseNVM = 0 //eraseLTO = 0 //reserved = 0 //baudRate = 4(921600bps) //firmwareSize = 0x00042000 //firmwareCRC = 0xF091FDE8 //reserved0 = 0x00100000 //reserved1 = 0x00100000 NOTES 1. eraseLTO is only supported on LC79D (A); for other Quectel modules, keep it as reserved. 2. The option bytes are also transmitted in the little-endian format. 2.5. Erase Code The host software must wait for an ACK response from the module as a confirmation that code area has been erased. In this case, the host software can use a timeout of 30 seconds (recommended waiting time). If no response is received in this time interval, the host software returns a timeout error. LC79D(A)_Firmware_Upgrade_Guide 10 / 15 GNSS Module Series LC79D (A) Firmware Upgrade Guide 2.6. Erase NVM and LTO If eraseNVM field is set to true, the host software must wait for an ACK response from the module as a confirmation that the flash NVM area has been erased. If eraseLTO field is set to true, the host software must wait for an ACK response from the module as a confirmation that the flash LTO area has been erased. In both cases the host software can use a timeout of 10 seconds (recommended waiting time); if no response is received in this time interval, host software returns a timeout error. 2.7. Send Data At this point the host can send data to upgrade the firmware inside the module’s flash area. The software running on the host must split the binary image data into n chunks of 16 KB. The size of the last chunk must be equal to the remaining bytes’ number. Each data chunk is acknowledged with an ACK response from the module. 2.8. CRC Error Check At this point the module bootloader software performs a CRC error check on the image data received by the host. If the check has passed, an ACK response is sent back to the host and the new downloaded firmware is regarded as validated. Otherwise, an NAK response is sent. In both cases the module resets itself and needs to re-upgrade. LC79D(A)_Firmware_Upgrade_Guide 11 / 15 GNSS Module Series LC79D (A) Firmware Upgrade Guide 2.9. Upgrade Flowchart Firmware upgrade command is sent over an NMEA port. Response is ERROR Host can quit the upgrade If there is something wrong happened on module side. Response is OK Module enters the Upgrade mode. Host repeatedly sends the FLASHER_IDENTIFIER command. Host timeout. Synchronization has failed Module sends FLASH_SYNC Host sends the DEVICE_START_COMMUNICATION command. Host timeout. Synchronization Has failed Module sends ACK Host sends the binary image options. Both host and module change UART baud rates. Host repeatedly sends the FLASHER_READY command. Host timeout. Baud rate change has failed Module sends ACK twice Module erases flash program area. Host timeout. Erase process has failed Module sends ACK Module erases flash NVM area if set. Module sends ACK Module erases flash LTO area if set. Module sends ACK Module validates new firmware and resets. Module restarts in the Upgrade mode. CRC passed CRC failed Host sends data to the device. Transfer complete. Module sends ACK' Module calculates CRC and compares it with the value received by the host. Module sends ACK for each data chunk. Figure 2: Firmware Upgrade Flowchart LC79D(A)_Firmware_Upgrade_Guide 12 / 15 GNSS Module Series LC79D (A) Firmware Upgrade Guide 3 Upgrade Implementation Example In this chapter you can find the example of firmware upgrade procedure. //Host sends the upgrade command: $PQFWUPGRADE*40 24 50 51 46 57 55 50 47 52 41 44 45 2A 34 30 0D 0A //Module responds with $PQFWUPGRADEOK*44 24 50 51 46 57 55 50 47 52 41 44 45 4F 4B 2A 34 34 0D 0A //Host continuously sends FLASHER_IDENTIFIER. B1 55 77 04 B1 55 77 04 B1 55 77 04 B1 55 77 04 B1 55 77 04 B1 55 77 04 B1 55 77 04 B1 55 77 04 B1 55 77 04 B1 55 77 04 B1 55 77 04 B1 55 77 04 //Module responds with FLASHER_SYNC. 1C 13 42 51 //Host sends DEVICE_START_COMMUNICATION. A3 //Module responds with ACK. CC //Host sends the binary image options and then changes to the new baud rate. 00 00 00 04 00 20 04 00 E8 FD 91 F0 00 00 10 00 00 00 10 00 //Host sends FLASHER_READY. 4A //Module responds with two ACK messages with new baud rate. CC CC //Module responds with ACK when code area has been successfully erased. CC //Host sends firmware data, in a chunk of 16 Kbytes. 00 B1 75 47 02 AC 08 04 00 00 20 04 00 EB 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 … //Module responds with ACK. LC79D(A)_Firmware_Upgrade_Guide 13 / 15 GNSS Module Series LC79D (A) Firmware Upgrade Guide CC //Host sends firmware data, in a chunk of 16 Kbytes. 21 0F F2 54 00 0F F4 AA F2 11 4D 00 20 28 70 12 F4 16 F4 58 B1 30 68 00 04 08 00 00 00 00 … //Module response ACK. CC //Host sends firmware data, in a chunk of 16 Kbytes. 20 70 BD 20 78 03 28 04 BF 00 21 17 F4 A7 F3 01 20 68 70 70 BD 50 05 91 00 31 13 80 00 E8 … // Module responds with ACK. CC … //Host sends the last chunk of firmware data 5F 68 73 69 2E 63 00 38 B5 DF F8 5C 5D 04 46 28 68 38 B9 14 F4 C0 F5 00 F0 70 60 DF //Module responds with ACK. CC //Module responds with ACK if CRC check has passed. CC //Module restarts automatically. LC79D(A)_Firmware_Upgrade_Guide 14 / 15 GNSS Module Series LC79D (A) Firmware Upgrade Guide 4 Appendix A References Table 3: Related Documents SN Document Name Remark [1] Quectel_LC79D_QGNSS_User_Guide QGNSS User Guide for LC79D Module GNSS Protocol Specification for LC79D (A) [2] Quectel_LC79D(A)_GNSS_Protocol_Specification Module [3] Quectel_LC79D(A)_EVB_User_Guide EVB User Guide for LC79D (A) Module [4] Quectel_LC79D_Hardware_Design LC79D Hardware Design Table 4: Terms and Abbreviations Abbreviation CRC FW GNSS LTO NVM UART Description Cyclic Redundancy Check Firmware Global Navigation Satellite System Long Term Orbits Non-Volatile Memory Universal Asynchronous Receiver/Transmitter LC79D(A)_Firmware_Upgrade_Guide 15 / 15
796.04 KB
LC79D (A) AGNSS Application Note GNSS Module Series Rev. LC79D(A)_AGNSS_Application_Note_V1.0 Date: 2020-07-03 Status: Released www.quectel.com GNSS Module Series LC79D (A) AGNSS Application Note Our aim is to provide customers with timely and comprehensive service. For any assistance, please contact our company headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local office. For more information, please visit: http://www.quectel.com/support/sales.htm For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm Or email to: support@quectel.com GENERAL NOTES QUECTEL OFFERS THE INFORMATION AS A SERVICE TO ITS CUSTOMERS. THE INFORMATION PROVIDED IS BASED UPON CUSTOMERS’ REQUIREMENTS. QUECTEL MAKES EVERY EFFORT TO ENSURE THE QUALITY OF THE INFORMATION IT MAKES AVAILABLE. QUECTEL DOES NOT MAKE ANY WARRANTY AS TO THE INFORMATION CONTAINED HEREIN, AND DOES NOT ACCEPT ANY LIABILITY FOR ANY INJURY, LOSS OR DAMAGE OF ANY KIND INCURRED BY USE OF OR RELIANCE UPON THE INFORMATION. ALL INFORMATION SUPPLIED HEREIN IS SUBJECT TO CHANGE WITHOUT PRIOR NOTICE. COPYRIGHT THE INFORMATION CONTAINED HERE IS PROPRIETARY TECHNICAL INFORMATION OF QUECTEL WIRELESS SOLUTIONS CO., LTD. TRANSMITTING, REPRODUCTION, DISSEMINATION AND EDITING OF THIS DOCUMENT AS WELL AS UTILIZATION OF THE CONTENT WITHOUT PERMISSION ARE FORBIDDEN. OFFENDERS WILL BE HELD LIABLE FOR PAYMENT OF DAMAGES. ALL RIGHTS ARE RESERVED IN THE EVENT OF A PATENT GRANT OR REGISTRATION OF A UTILITY MODEL OR DESIGN. Copyright © Quectel Wireless Solutions Co., Ltd. 2020. All rights reserved. LC79D(A)_AGNSS_Application_Note 1 / 25 GNSS Module Series LC79D (A) AGNSS Application Note About the Document Revision History Version Date Author Description 1.0 2020-07-03 Jenn XIANG Initial LC79D(A)_AGNSS_Application_Note 2 / 25 GNSS Module Series LC79D (A) AGNSS Application Note Contents About the Document .................................................................................................................................. 2 Contents ...................................................................................................................................................... 3 Table Index.................................................................................................................................................. 4 Figure Index ................................................................................................................................................ 5 1 Introduction ......................................................................................................................................... 6 2 AGNSS Implementation...................................................................................................................... 7 2.1. NMEA Commands for AGNSS Implementation ......................................................................... 7 2.1.1. $PQSTARTGNSS ........................................................................................................... 7 2.1.2. $PQSTOPGNSS ............................................................................................................. 8 2.1.3. $PQSETASSPOS ........................................................................................................... 8 2.1.4. $PQSETASSTIME .......................................................................................................... 9 2.1.5. $PQSETASSGNSS ....................................................................................................... 10 2.1.6. $PQLTODOWNLOAD ................................................................................................... 12 2.2. Sending LTO Data to the Module............................................................................................. 12 2.2.1. Download LTO File from Server.................................................................................... 12 2.2.2. Send LTO Data to the Module....................................................................................... 13 2.2.2.1. Enter LTO Data Downloading Mode .................................................................. 15 2.2.2.2. Send LTO File Information to Module ................................................................ 15 2.2.2.3. Erase LTO Data Area ......................................................................................... 17 2.2.2.4. Send LTO Data to Module.................................................................................. 17 2.2.2.5. Perform CRC32 Verification ............................................................................... 17 3 AGNSS Testing Procedure .............................................................................................................. 18 3.1. Prerequisites ............................................................................................................................ 18 3.2. Procedure................................................................................................................................. 19 3.3. Results ..................................................................................................................................... 24 4 Appendix A References.................................................................................................................... 25 LC79D(A)_AGNSS_Application_Note 3 / 25 GNSS Module Series LC79D (A) AGNSS Application Note Table Index Table 1: The List of NMEA Proprietary Commands for AGNSS Implementation......................................... 7 Table 2: File Information’s Format.............................................................................................................. 16 Table 3: List of Constants ........................................................................................................................... 16 Table 4: Related Documents ...................................................................................................................... 25 Table 5: Terms and Abbreviations .............................................................................................................. 25 LC79D(A)_AGNSS_Application_Note 4 / 25 GNSS Module Series LC79D (A) AGNSS Application Note Figure Index Figure 1: Flowchart for Sending LTO Data to the Module ......................................................................... 14 Figure 2: Example Procedure for Sending LTO Data to the Module ......................................................... 15 LC79D(A)_AGNSS_Application_Note 5 / 25 GNSS Module Series LC79D (A) AGNSS Application Note 1 Introduction The LC79D (A) GNSS module supports AGNSS feature that significantly reduces the module’s TTFF, especially in lower signal conditions. To implement AGNSS feature, the module should get the assistance data including the current time, rough position, and LTO data. Consult the following document to find out how to send the assistance data to the module. The list of all NMEA commands that are used by AGNSS feature is also given for your reference. Before using the AGNSS feature, make sure to verify that everything is correctly set. For more information on testing the module, see the chapter AGNSS Testing Procedure. LC79D(A)_AGNSS_Application_Note 6 / 25 GNSS Module Series LC79D (A) AGNSS Application Note 2 AGNSS Implementation The chapter introduces the AGNSS implementation on LC79D (A) GNSS module, which includes the list of NMEA proprietary commands and the procedure for sending LTO data to the module. 2.1. NMEA Commands for AGNSS Implementation The LC79D(A) module can be controlled and configured through NMEA proprietary commands defined by Quectel (PQ commands). Table 1: The List of NMEA Proprietary Commands for AGNSS Implementation Command Description $PQSTARTGNSS Start the GNSS engine $PQSTOPGNSS Stop the GNSS engine $PQSETASSPOS Send the assistance position to the module $PQSETASSTIME Send the assistance time to the module $PQSETASSGNSS Send the assistance position and time to the module $PQLTODOWNLOAD Set the module into LTO-data downloading mode 2.1.1. $PQSTARTGNSS The $PQSTARTGNSS command starts the GNSS engine. Synopsis: $PQSTARTGNSS* Arguments: None. LC79D(A)_AGNSS_Application_Note 7 / 25 GNSS Module Series LC79D (A) AGNSS Application Note Results: In case of no error, the GNSS engine is started with the following message: $PQSTARTGNSSOK*4C In case of any errors, the returned message is: $PQSTARTGNSSERROR*10 Example: $PQSTARTGNSS*48 $PQSTARTGNSSOK*4C 2.1.2. $PQSTOPGNSS The $PQSTOPGNSS command stops the GNSS engine. Synopsis: $PQSTOPGNSS* Arguments: None. Results: In case of no error, the GNSS engine is stopped with the following message: $PQSTOPGNSSOK*14 In case of any errors, the returned message is: $PQSTOPGNSSERROR*48 Example: $PQSTOPGNSS*10 $PQSTOPGNSSOK*14 2.1.3. $PQSETASSPOS The $PQSETASSPOS command sends the assistance position to the module. LC79D(A)_AGNSS_Application_Note 8 / 25 GNSS Module Series LC79D (A) AGNSS Application Note Synopsis: $PQSETASSPOS,,,[,,]* Arguments: Parameter lat lon alt hor_acc ver_acc checksum Format DD.DDDDDD DDD.DDDDDD Decimal dddd.d-Decimal dddd.d-Decimal Hexadecimal, 2 digits Description Latitude (-90 to 90 degrees) Longitude (-180 to 180 degrees) Altitude in meters. Optional. Horizontal accuracy Optional. Vertical accuracy Checksum of the message bytes between but not including the $ and * characters Results: In case of no error, the returned message is: $PQSETASSPOSOK*4A In case any errors, the returned message is: $PQSETASSPOSERROR*16 Example: $PQSETASSPOS,31.786545,112.455235,12.2*40 $PQSETASSPOSOK*4A NOTES 1. The GNSS engine must be stopped before sending the assistance position. 2. The overall accuracy of the assistance position must be within 30 km range. 2.1.4. $PQSETASSTIME The $PQSETASSTIME command sends the assistance time to the module in the UTC format. The time must be after May 2019. Synopsis: $PQSETASSTIME,,,,,,* LC79D(A)_AGNSS_Application_Note 9 / 25 GNSS Module Series LC79D (A) AGNSS Application Note Arguments: Parameter year month day hour min sec checksum Format Integer Integer Integer Integer Integer Integer Hexadecimal, 2 digits Description Year (2019–…) Month (01–12) Day of month (01–31) Hour (00–23) Minute (00–59) Second (00–59) Checksum of the message bytes between but not including the $ and * characters Results: In case of no error, the returned message is: $PQSETASSTIMEOK*13 In case of any errors, the returned message is: $PQSETASSTIMEERROR*4F Example: $PQSETASSTIME,2019,06,06,18,20,32*17 $PQSETASSTIMEOK*13 NOTES 1. The GNSS engine must be stopped before sending the assistance time. 2. The overall accuracy of the assistance time must be lower than 3 seconds. 2.1.5. $PQSETASSGNSS The $PQSETASSGNSS command sends the assistance location and the assistance time in the UTC format to the module. The time must be after May 2019. Synopsis: $PQSETASSGNSS,,,,,,,,,*< LF> LC79D(A)_AGNSS_Application_Note 10 / 25 GNSS Module Series LC79D (A) AGNSS Application Note Arguments: Parameter lat lon alt year month day hour min sec checksum Format DD.DDDDDD DDD.DDDDDD Decimal Integer Integer Integer Integer Integer Integer Hexadecimal, 2 digits Description Latitude (-90 to 90 degrees) Longitude (-180 to 180 degrees) Altitude in meters Year (2019–…) Month (01–12) Day of month (01–31) Hour (00–23) Minute (00–59) Second (00–9) Checksum of the message bytes between but not including the $ and * characters Results: In case of no error, the returned message is: $PQSETASSGNSSOK*0F In case of any errors, the returned message is: $PQSETASSGNSSERROR*53 Example: $PQSETASSGNSS,31.786545,112.455235,12.2,2019,06,06,18,20,32*05 $PQSETASSGNSSOK*0F NOTES 1. The GNSS engine must be stopped before sending the assistance position and time. 2. The accuracy of the assistance position must be lower than 30 kilometers and the accuracy of assistance time must be less than 3 seconds. LC79D(A)_AGNSS_Application_Note 11 / 25 GNSS Module Series LC79D (A) AGNSS Application Note 2.1.6. $PQLTODOWNLOAD The $PQLTODOWNLOAD command stops the GNSS engine and sets the module into LTO-data downloading mode, so that it is ready for receiving the data sent from the host side. Synopsis: $PQLTODOWNLOAD* Arguments: None. Results: In case of no error, the returned message is: $PQLTODOWNLOADOK*46 In case of any errors, the returned message is: $PQLTODOWNLOADERROR*1A Example: $PQLTODOWNLOAD*42 $PQLTODOWNLOADOK*46 2.2. Sending LTO Data to the Module 2.2.1. Download LTO File from Server Before sending LTO data to the module, the host has to download the LTO file. The LTO file can be downloaded from Quectel AGNSS server, and it’s valid up to 7 days. Quectel AGNSS server: ftp://agnss.queclocator.com Quectel AGNSS server supports the download of LTO files that have 2, 4 or 7-day validity. The LTO files have the 'lto2_xday.dat' naming structure, where the x refers to the days of validity and can be each one of the following options: 2, 4 or 7. LC79D(A)_AGNSS_Application_Note 12 / 25 GNSS Module Series LC79D (A) AGNSS Application Note NOTES 1. Quectel AGNSS server is free of charge and there is no SLA while using the server. However, to access and use the Quectel AGNSS server, customers must have an account. Contact Quectel’s Technical Support team (support@quectel.com) to apply for the account. 2. Customers must create their own server’s instance and download the LTO files to their own server instances. 2.2.2. Send LTO Data to the Module The following chart illustrates the procedure for sending LTO data to the module. NOTE In addition to transferring the LTO data to the module directly through the host, the LTO file can also be uploaded to the module with a QGNSS tool. For details, see Chapter 3. For more information on the QGNSS tool, see document [2]. LC79D(A)_AGNSS_Application_Note 13 / 25 GNSS Module Series LC79D (A) AGNSS Application Note Host sends command to start LTO data downloading procedure N Response is OK? Y Module enters LTO data downloading mode. Host sends LTO file information frame to the module. LTO file Information N received OK? Y Module sends 'LTO_ACK' Module is erasing flash LTO data area. Module erases flash with N success? Y Module sends 'LTO_ACK' HOST sends LTO data to the module. N Transfer complete? Y Module calculates CRC and compares it with the value received in LTO information frame by the HOST. N CRC passed? Y Module sends 'LTO_ACK' Module sends 'LTO_NACK' Module exits LTO download mode. Figure 1: Flowchart for Sending LTO Data to the Module LC79D(A)_AGNSS_Application_Note 14 / 25 GNSS Module Series LC79D (A) AGNSS Application Note HOST LC79D Send command to LC79D Send LTO file info to LC79D (see the example) $PQLTODOWNLOAD*42 $PQLTODOWNLOADOK*46 AA 01 01 08 4D A4 01 00 4E 6E 07 E6 21 55 CC CC Packet1 LC79D receives it with success LC79D responds with 'ACK' LC79D responds with 'ACK' if flash is erased CC Send LTO data to LC79D, 16KB for each packet, except the last one Packet2 CC ... PacketN LC79D responds with 'ACK' for each packet it successfully receives CC CC LC79D sends 'ACK' if CRC verification is OK. Figure 2: Example Procedure for Sending LTO Data to the Module 2.2.2.1. Enter LTO Data Downloading Mode $PQLTODOWNLOAD command starts the LTO data downloading procedure. If the module receives this command successfully, it enters the LTO data downloading mode. Example: $PQLTODOWNLOAD*42 $PQLTODOWNLOADOK*46 2.2.2.2. Send LTO File Information to Module Before sending LTO data to the module, the host must send the LTO file information to the module. The file information includes the file size and CRC32 value. The following illustrates the format of file LC79D(A)_AGNSS_Application_Note 15 / 25 information frames: GNSS Module Series LC79D (A) AGNSS Application Note Table 2: File Information’s Format File Information Frame Format Header 0xAA Class 0x01 ID 0x01 Length 0x08 LTO File Size 4 Bytes LTO File CRC32 4 Bytes Checksum Trailer 1 Byte 0x55 Description Fixed as 0xAA Fixed as 0x01 Fixed as 0x01 Payload length (LTO File Size field and LTO File CRC32 field) Byte size of LTO file: 4 bytes; use little-endian mode This is the CRC32 code calculated first on the LTO file size field and then over the entire LTO file payload: 4 bytes in little-endian mode Use XOR to calculate LTO File Size field and LTO File CRC32 field Fixed as 0x55 If the module receives the file information frames successfully, the module returns LTO_ACK; otherwise, LTO_NACK is sent. Table 3: List of Constants Constant’s Name LTO_ACK LTO_NACK Constant’s Value 0xCC 0xDD Example: //In Hex mode AA 01 01 08 4D A4 01 00 4E 6E 07 E6 21 55 //The host sends LTO file information frames to the module CC //The module receives the frames successfully LC79D(A)_AGNSS_Application_Note 16 / 25 GNSS Module Series LC79D (A) AGNSS Application Note 2.2.2.3. Erase LTO Data Area After the module has received LTO file information frames and returned LTO_ACK, the module erases the LTO data area in flash. After the flash erasure process is finished, LTO_ACK is returned once again. 2.2.2.4. Send LTO Data to Module When the previous step is completed, the host can send LTO data to the module, which saves the LTO data to flash. The host must split the LTO data into N chunks of 16 KB. The last chunk size should be equal to the remaining bytes, which means that its size might be less than 16 KB. Each data chunk is acknowledged with LTO_ACK response from the module. If there is any error, LTO_NACK is returned. 2.2.2.5. Perform CRC32 Verification After LTO data sending, the module performs CRC32 verification on the LTO data received from the host. If the verification is passed, the module returns LTO_ACK to the host; otherwise, LTO_NACK is returned. LC79D(A)_AGNSS_Application_Note 17 / 25 GNSS Module Series LC79D (A) AGNSS Application Note 3 AGNSS Testing Procedure This chapter illustrates how to test the AGNSS feature by using the Quectel’s QGNSS tool. The QGNSS tool is a Quectel’s tool used for testing GNSS features. The QGNSS runs on Windows OS only and is compatible with Windows 7 and later versions of Windows. The procedure described in this chapter is a general one and is relevant even if you use a different tool or have a Linux or Mac OS machine. 3.1. Prerequisites Before testing the AGNSS function, make sure that you have done the following: 1) You have connected LC79D (A) EVB with your computer. 2) You have installed the QGNSS tool 1) and have set the corresponding serial port number, baud rate 2), and the module’s model. 3) You have created the account for Quectel AGNSS Server 3), and you have connected the AGNSS Server to the QGNSS tool. To better see the effect of AGNSS feature on TTFF value, you could first get a fix without using AGNSS feature. After the testing procedure, you can compare the TTFF results. NOTES 1. 1) For more information on how to install and set up QGNSS, see document [2]. 2. 2) The default baud rate of the LC79D module is 115200 bps. 3. 3) Contact Quectel’s Technical Support (support@quectel.com) for information on how to get access to Quectel AGNSS Server. LC79D(A)_AGNSS_Application_Note 18 / 25 GNSS Module Series LC79D (A) AGNSS Application Note 3.2. Procedure To test the AGNSS function in a cold start session with the QGNSS tool 1), do the following: 1) Send the LTO data to the module. 2) Send $PQCOLD command to the module to perform a cold start. 3) Send $PQSTOPGNSS command to the module to stop the GNSS engine. 4) Send the assistance position and time to the module with $PQSETASSGNSS command 2), or with $PQSETASSPOS and $PQSETASSTIME commands 3). 5) Send $PQSTARTGNSS command to the module to start the GNSS engine 4). NOTES 1. 1) The QGNSS tool only supports the download of LTO files that have 4-day validity. If you need the LTO file with 2 or 7-day validity, or you don’t want to use the QGNSS tool, you can send the LTO file and LTO data directly to the module with PQ commands. For details, see Chapter 2.2. 2. 2) It is recommended to use $PQSETASSGNSS command to inject the position and time at the same time. 3. 3) If you use $PQSETASSPOS and $PQSETASSTIME commands, inject first the position with $PQSETASSPOS command, and then inject time with $PQSETASSTIME command. 4. 4) It is important to start the GNSS engine immediately after you set the assistance position and time. Example: 1. Send the LTO data to the module. a) Run the QGNSS tool. b) In the main interface, click 'Windows -> Download (LTO)' to enter the Download window. c) Click the 'Download LTO' button to download the LTO file to your computer. The file size and CRC information are shown in the corresponding fields. d) Click the 'Load' button to upload the LTO data and then click 'Start'. The QGNSS sends both the LTO file and LTO data to the module. e) When the transfer is successfully finished ('Status' bar is 100% green), close the window. LC79D(A)_AGNSS_Application_Note 19 / 25 GNSS Module Series LC79D (A) AGNSS Application Note 2. Go to the 'PortInfo' window and perform a cold start. $PQCOLD*05 //Module’s response $GNRMC,000001.00,V,,,,,,,020712,,,N,V*1E $GNGGA,000001.00,,,,,0,00,99.0,,M,,M,,*49 $GNGLL,,,,,000001.00,V,N*55 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,1*03 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,2*00 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,3*01 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,4*06 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,5*07 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,6*04 $GNVTG,,T,,M,,N,,K,N*32 … 3. Stop the GNSS engine: $PQSTOPGNSS*10 //Module’s response $PQSTOPGNSSOK*14 4. Inject the module’s position and current time information: $PQSETASSGNSS,31.821730,117.114608,0,2020,6,29,12,32,20*1A //module’s response $PQSETASSGNSSOK*0F 5. Start the GNSS engine: $PQSTARTGNSS*48 LC79D(A)_AGNSS_Application_Note 20 / 25 GNSS Module Series LC79D (A) AGNSS Application Note //Module’s response $PQSTARTGNSSOK*4C $GNRMC,123224.11,V,,,,,,,290620,,,N,V*12 // 1st second $GNGGA,123224.11,,,,,0,00,99.0,,M,,M,,*4C $GNGLL,,,,,123224.11,V,N*50 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,1*03 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,2*00 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,3*01 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,4*06 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,5*07 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,6*04 $GNVTG,,T,,M,,N,,K,N*32 $GNRMC,123225.11,V,,,,,,,290620,,,N,V*13 // 2nd second $GNGGA,123225.11,,,,,0,00,99.0,,M,,M,,*4D $GNGLL,,,,,123225.11,V,N*51 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,1*03 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,2*00 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,3*01 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,4*06 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,5*07 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,6*04 $GNVTG,,T,,M,,N,,K,N*32 $GNRMC,123225.30,V,,,,,,,290620,,,N,V*10 // 3rd second $GNGGA,123225.30,,,,,0,00,99.0,,M,,M,,*4E $GNGLL,,,,,123225.30,V,N*52 $GPGSV,1,1,01,10,01,291,33,1*5F $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,1*03 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,2*00 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,3*01 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,4*06 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,5*07 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,6*04 $GNVTG,,T,,M,,N,,K,N*32 $GNRMC,123226.11,V,,,,,,,290620,,,N,V*10 // 4th second $GNGGA,123226.11,,,,,0,00,99.0,,M,,M,,*4E $GNGLL,,,,,123226.11,V,N*52 $GPGSV,2,1,05,10,01,291,35,18,57,308,35,20,27,306,41,21,19,318,31,1*6C $GPGSV,2,2,05,29,21,219,39,1*59 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,1*03 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,2*00 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,3*01 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,4*06 LC79D(A)_AGNSS_Application_Note 21 / 25 GNSS Module Series LC79D (A) AGNSS Application Note $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,5*07 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,6*04 $GNVTG,,T,,M,,N,,K,N*32 $GNRMC,123227.11,V,,,,,,,290620,,,N,V*11 // 5th second $GNGGA,123227.11,,,,,0,00,99.0,,M,,M,,*4F $GNGLL,,,,,123227.11,V,N*53 $GPGSV,2,1,05,10,01,291,35,18,57,308,37,20,27,306,44,21,19,318,33,1*69 $GPGSV,2,2,05,29,21,219,42,1*55 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,1*03 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,2*00 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,3*01 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,4*06 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,5*07 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,6*04 $GNVTG,,T,,M,,N,,K,N*32 $GNRMC,123228.11,V,,,,,,,290620,,,N,V*1E // 6th second $GNGGA,123228.11,,,,,0,00,99.0,,M,,M,,*40 $GNGLL,,,,,123228.11,V,N*5C $GPGSV,2,1,08,05,,,14,10,01,291,34,13,,,20,15,69,005,22,1*6C $GPGSV,2,2,08,18,57,308,37,20,27,306,44,21,19,318,34,29,21,219,42,1*68 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,1*03 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,2*00 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,3*01 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,4*06 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,5*07 $GNGSA,A,1,,,,,,,,,,,,,99.0,99.0,99.0,6*04 $GNVTG,,T,,M,,N,,K,N*32 // Get a fix in the 7th second. $GNRMC,123229.11,A,3149.305975,N,11706.914899,E,0.0,,290620,,,A,V*15 $GNGGA,123229.11,3149.305975,N,11706.914899,E,1,10,1.8,53.6,M,-3.6,M,,*5C $GNGLL,3149.305975,N,11706.914899,E,123229.11,A,A*79 $GPGSV,2,1,08,05,25,090,15,10,01,291,34,13,,,22,15,69,005,24,1*57 $GPGSV,2,2,08,18,57,308,36,20,27,306,45,21,19,318,35,29,21,219,42,1*69 $GLGSV,1,1,04,87,08,335,41,85,36,198,31,71,48,330,36,72,19,279,42,1*79 $GQGSV,2,1,03,01,65,059,21,02,25,136,21,1*6A $GNGSA,A,3,10,15,18,20,21,29,,,,,,,2.4,1.8,1.7,1*3E $GNGSA,A,3,71,72,85,87,,,,,,,,,2.4,1.8,1.7,2*3A $GNGSA,A,3,,,,,,,,,,,,,2.4,1.8,1.7,3*3A $GNGSA,A,3,,,,,,,,,,,,,2.4,1.8,1.7,4*3D $GNGSA,A,3,,,,,,,,,,,,,2.4,1.8,1.7,5*3C $GNGSA,A,3,,,,,,,,,,,,,2.4,1.8,1.7,6*3F $GNVTG,,T,,M,0.0,N,0.0,K,A*3D $GNRMC,123230.11,A,3149.305882,N,11706.914849,E,0.0,,290620,,,A,V*19 $GNGGA,123230.11,3149.305882,N,11706.914849,E,1,12,1.8,68.6,M,-3.6,M,,*5A LC79D(A)_AGNSS_Application_Note 22 / 25 GNSS Module Series LC79D (A) AGNSS Application Note $GNGLL,3149.305882,N,11706.914849,E,123230.11,A,A*75 $GPGSV,2,1,08,05,25,090,14,10,01,291,33,13,42,039,24,15,69,005,24,1*6B $GPGSV,2,2,08,18,57,308,36,20,27,306,45,21,19,318,34,29,21,219,42,1*68 $GLGSV,1,1,04,87,08,335,44,85,36,198,30,71,48,330,35,72,19,279,47,1*7B $GBGSV,2,1,05,206,77,276,38,209,51,240,31,211,35,210,35,213,81,287,38,1*79 $GBGSV,2,2,05,216,72,266,41,1*74 $GQGSV,2,1,04,01,,,22,02,25,136,21,03,22,175,22,1*61 $GNGSA,A,3,10,13,18,20,21,,,,,,,,2.4,1.8,1.7,1*33 $GNGSA,A,3,71,72,87,,,,,,,,,,2.4,1.8,1.7,2*37 $GNGSA,A,3,,,,,,,,,,,,,2.4,1.8,1.7,3*3A $GNGSA,A,3,206,209,213,216,,,,,,,,,2.4,1.8,1.7,4*37 $GNGSA,A,3,,,,,,,,,,,,,2.4,1.8,1.7,5*3C $GNGSA,A,3,,,,,,,,,,,,,2.4,1.8,1.7,6*3F $GNVTG,,T,,M,0.0,N,0.0,K,A*3D $GNRMC,123231.11,A,3149.305310,N,11706.915521,E,0.0,,290620,,,A,V*1A $GNGGA,123231.11,3149.305310,N,11706.915521,E,1,12,2.1,65.6,M,-3.6,M,,*5E $GNGLL,3149.305310,N,11706.915521,E,123231.11,A,A*76 $GPGSV,2,1,08,05,25,090,14,10,01,291,33,13,42,039,24,15,69,005,25,1*6A $GPGSV,2,2,08,18,57,308,35,20,27,306,45,21,19,318,33,29,21,219,42,1*6C $GLGSV,1,1,04,87,08,335,44,85,36,198,28,71,48,330,33,72,19,279,47,1*74 $GBGSV,2,1,06,206,77,276,38,209,51,240,30,211,35,210,36,213,81,287,38,1*78 $GBGSV,2,2,06,214,54,321,29,216,72,266,41,1*7A $GQGSV,2,1,04,01,65,059,23,02,25,136,20,03,22,175,22,1*5E $GNGSA,A,3,10,18,20,21,,,,,,,,,2.7,2.1,1.6,1*39 $GNGSA,A,3,72,87,,,,,,,,,,,2.7,2.1,1.6,2*39 $GNGSA,A,3,,,,,,,,,,,,,2.7,2.1,1.6,3*32 $GNGSA,A,3,206,209,211,213,214,216,,,,,,,2.7,2.1,1.6,4*3A $GNGSA,A,3,,,,,,,,,,,,,2.7,2.1,1.6,5*34 $GNGSA,A,3,,,,,,,,,,,,,2.7,2.1,1.6,6*37 $GNVTG,,T,,M,0.0,N,0.0,K,A*3D $GNRMC,123232.11,A,3149.304881,N,11706.916022,E,0.0,,290620,,,A,V*1E $GNGGA,123232.11,3149.304881,N,11706.916022,E,1,12,2.1,66.6,M,-3.6,M,,*59 $GNGLL,3149.304881,N,11706.916022,E,123232.11,A,A*72 $GPGSV,3,1,09,05,25,090,13,10,01,291,34,13,42,039,25,15,69,005,25,1*6B $GPGSV,3,2,09,18,57,308,34,20,27,306,45,21,19,318,33,29,21,219,42,1*6D $GLGSV,2,1,05,73,19,137,22,87,08,335,44,85,36,198,26,71,48,330,34,1*74 $GLGSV,2,2,05,72,19,279,46,1*4E $GBGSV,2,1,06,206,77,276,38,209,51,240,30,211,35,210,36,213,81,287,38,1*78 $GBGSV,2,2,06,214,54,321,29,216,72,266,41,1*7A $GQGSV,2,1,04,01,,,23,02,25,136,20,03,22,175,21,1*62 $GNGSA,A,3,10,18,20,21,,,,,,,,,2.7,2.1,1.6,1*39 $GNGSA,A,3,72,87,,,,,,,,,,,2.7,2.1,1.6,2*39 $GNGSA,A,3,,,,,,,,,,,,,2.7,2.1,1.6,3*32 $GNGSA,A,3,206,209,211,213,214,216,,,,,,,2.7,2.1,1.6,4*3A LC79D(A)_AGNSS_Application_Note 23 / 25 $GNGSA,A,3,,,,,,,,,,,,,2.7,2.1,1.6,5*34 $GNGSA,A,3,,,,,,,,,,,,,2.7,2.1,1.6,6*37 $GNVTG,,T,,M,0.0,N,0.0,K,A*3D GNSS Module Series LC79D (A) AGNSS Application Note 3.3. Results When the GNSS engine is started, the module will try to get a fix. Without the AGNSS feature, the module gets a fix in about 30 seconds after a cold start. With the AGNSS feature enabled, the module gets a fix in about 10 seconds or less. In this example, the TTFF is 7s. As NMEA messages (RMC, GGA, GSV, GSA, VTG, and so on) are output every second, by counting the number of RMC or GGA for example, you can calculate how many seconds have passed before getting a first fix. If you have previously got a fix without an AGNSS feature, you can now compare the results. If everything went well, the TTFF value should be significantly reduced. LC79D(A)_AGNSS_Application_Note 24 / 25 GNSS Module Series LC79D (A) AGNSS Application Note 4 Appendix A References Table 4: Related Documents SN Document Name [1] LC79D(A)_GNSS_Protocol_Specification [2] Quectel_LC79D_QGNSS_User_Guide Remark LC79D (A) GNSS Protocol Specification QGNSS Tool User Guide Table 5: Terms and Abbreviations Abbreviation AGNSS FTP GNSS HEX LTO NMEA SLA TTFF UART UTC Description Assisted GNSS File Transfer Protocol Global Navigation Satellite System Hexadecimal Long Term Orbit National Marine Electronics Association Software License Agreement Time to First Fix Universal Asynchronous Receiver/Transmitter Universal Time Coordinated LC79D(A)_AGNSS_Application_Note 25 / 25
535.69 KB
BG95&BG77&BG600L Series SSL Application Note LPWA Module Series Version: 1.1 Date: 2021-10-22 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG95&BG77&BG600L_Series_SSL_Application_Note 1 / 38 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2021. All rights reserve BG95&BG77&BG600L_Series_SSL_Application_Note 2 / 38 LPWA Module Series About the Document Revision History Version Date Author Description 1.0 2019-10-12 Terrence YANG Initial 1. Added an applicable module BG600L-M3. 2. Updated the supported SSL cipher suites (Table 3 and Chapter 2.3.1). 3. Added AT+QSSLCFG='renegotiation' (Chapter 2.3.1). 1.1 2021-10-22 Terrence YANG 4. Added AT+QSSLRECV=,0 (Chapter 2.3.4). 5. Added AT+QSSLCRYPT (Chapter 2.3.7). 6. Added an example about setting up a DTLS connection based on PSK encryption (Chapter 3.6). BG95&BG77&BG600L_Series_SSL_Application_Note 3 / 38 LPWA Module Series Contents About the Document ................................................................................................................................ 3 Contents.................................................................................................................................................... 4 Table Index ............................................................................................................................................... 6 1 Introduction ....................................................................................................................................... 7 1.1. Applicable Modules .................................................................................................................. 7 1.2. SSL Versions and Cipher Suites............................................................................................... 8 1.3. Using SSL Function ................................................................................................................ 10 1.4. Description of Data Access Modes ......................................................................................... 10 1.5. Certificate Validity Check .........................................................................................................11 1.6. Server Name Indication .......................................................................................................... 12 2 Description of SSL AT Commands ................................................................................................ 13 2.1. AT Command Introduction ...................................................................................................... 13 2.1.1. Definitions .................................................................................................................... 13 2.1.2. AT Command Syntax ................................................................................................... 13 2.2. Declaration of AT Command Examples .................................................................................. 14 2.3. Description of SSL AT Commands.......................................................................................... 14 2.3.1. AT+QSSLCFG Configure Parameters of an SSL Context ......................................... 14 2.3.2. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server ....................... 21 2.3.3. AT+QSSLSEND Send Data via SSL Connection ...................................................... 22 2.3.4. AT+QSSLRECV Retrieve Data Through SSL Connection ........................................ 24 2.3.5. AT+QSSLCLOSE Close an SSL Connection ............................................................ 25 2.3.6. AT+QSSLSTATE Query the State of SSL Connections............................................. 25 2.3.7. AT+QSSLCRYPT Encrypt/Decrypt Data with a Specified Algorithm ......................... 27 2.4. Description of URCs ............................................................................................................... 28 2.4.1. +QSSLURC: 'recv' Notify Received Data ................................................................. 28 2.4.2. +QSSLURC: 'closed' Notify Abnormal Disconnection .............................................. 28 3 Examples ......................................................................................................................................... 29 3.1. Configure and Activate a PDP Context ................................................................................... 29 3.1.1. Configure a PDP Context............................................................................................. 29 3.1.2. Activate a PDP Context ............................................................................................... 29 3.1.3. Deactivate a PDP Context ........................................................................................... 29 3.2. Configure an SSL Context ...................................................................................................... 29 3.3. SSL Client in Buffer Access Mode .......................................................................................... 30 3.3.1. Set up an SSL Connection and Enter Buffer Access Mode ......................................... 30 3.3.2. Send Data in Buffer Access Mode ............................................................................... 30 3.3.3. Retrieve Data in Buffer Access Mode .......................................................................... 30 3.3.4. Close an SSL Connection ............................................................................................ 31 3.4. SSL Client in Direct Push Mode ............................................................................................. 31 3.4.1. Set up an SSL Connection and Enter Direct Push Mode............................................. 31 3.4.2. Send Data in Direct Push Mode................................................................................... 31 BG95&BG77&BG600L_Series_SSL_Application_Note 4 / 38 LPWA Module Series 3.4.3. Retrieve Data in Direct Push Mode.............................................................................. 31 3.4.4. Close an SSL Connection ............................................................................................ 32 3.5. SSL Client in Transparent Access Mode................................................................................. 32 3.5.1. Set up an SSL Connection and Send Data in Transparent Access Mode.................... 32 3.5.2. Set up an SSL Connection and Retrieve Data in Transparent Access Mode ............... 32 3.5.3. Close an SSL Connection ............................................................................................ 32 3.6. DTLS Connection Based on PSK Encryption ......................................................................... 33 3.6.1. Set up a DTLS Connection .......................................................................................... 33 3.6.2. Close an SSL Connection ............................................................................................ 33 4 Check for Failure in SSL Connection ............................................................................................ 34 5 Summary of Error Codes................................................................................................................ 35 6 Appendix References ..................................................................................................................... 37 BG95&BG77&BG600L_Series_SSL_Application_Note 5 / 38 LPWA Module Series Table Index Table 1: Applicable Modules ...................................................................................................................... 7 Table 2: Supported SSL Versions .............................................................................................................. 8 Table 3: Supported SSL Cipher Suites ...................................................................................................... 8 Table 4: Types of AT Commands ............................................................................................................. 13 Table 5: Summary of Error Codes ........................................................................................................... 35 Table 6: Related Documents ................................................................................................................... 37 Table 7: Terms and Abbreviations............................................................................................................ 37 BG95&BG77&BG600L_Series_SSL_Application_Note 6 / 38 LPWA Module Series 1 Introduction Quectel BG95 series, BG77 and BG600L-M3 modules support SSL function. SSL (Secure Sockets Layer) is a networking protocol designed for securing connections between web clients and web servers over an insecure network, such as the internet. The SSL function is to ensure the privacy of communication. In some cases, the communication between the server and the client should be encrypted to prevent tampering, eavesdropping attacks, or data forging. 1.1. Applicable Modules Table 1: Applicable Modules Module Series Model BG95-M1 BG95-M2 BG95-M3 BG95 BG95-M4 BG95-M5 BG95-M6 BG95-MF BG77 BG77 BG600L BG600L-M3 Description Cat M1 only Cat M1/Cat NB2 Cat M1/Cat NB2/EGPRS Cat M1/Cat NB2, 450 MHz Supported Cat M1/Cat NB2/EGPRS, Power Class 3 Cat M1/Cat NB2, Power Class 3 Cat M1/Cat NB2, Wi-Fi Positioning Cat M1/Cat NB2 Cat M1/Cat NB2/EGPRS BG95&BG77&BG600L_Series_SSL_Application_Note 7 / 38 LPWA Module Series 1.2. SSL Versions and Cipher Suites The following SSL versions are supported by BG95 series, BG77 and BG600L-M3 modules. Table 2: Supported SSL Versions SSL Version SSL3.0 TLS1.0 TLS1.1 TLS1.2 SSL cipher suites supported by the modules are presented in the table below. For detailed description of cipher suites, refer to RFC 2246: The TLS Protocol Version 1.0. Table 3: Supported SSL Cipher Suites Cipher Suite Cide 0X0035 0X002F 0X0005 0X0004 0X000A 0X003D 0XC002 0XC003 0XC004 0XC005 0XC007 Cipher Suite Name TLS_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_RC4_128_SHA TLS_RSA_WITH_RC4_128_MD5 TLS_RSA_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_ECDH_ECDSA_WITH_RC4_128_SHA TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_RC4_128_SHA BG95&BG77&BG600L_Series_SSL_Application_Note 8 / 38 0XC008 0XC009 0XC00A 0XC011 0XC012 0XC013 0XC014 0XC00C 0XC00D 0XC00E 0XC00F 0XC023 0XC024 0XC025 0XC026 0XC027 0XC028 0XC029 0XC02A 0XC02B 0XC02F 0XC0A8 0X00AE 0XC0AE LPWA Module Series TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_RC4_128_SHA TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_ECDH_RSA_WITH_RC4_128_SHA TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDH_RSA_WITH_AES_128_CBC_SHA TLS_ECDH_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 TLS-ECDHE-ECDSA-WITH-AES-128-GCM-SHA256 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_PSK_WITH_AES_128_CCM_8 TLS_PSK_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 BG95&BG77&BG600L_Series_SSL_Application_Note 9 / 38 0XFFFF Support all cipher suites above LPWA Module Series 1.3. Using SSL Function Step 1: Configure , , and other parameters of a PDP context with AT+QICSGP. See document [1] for detailed information. Step 2: Activate the PDP context with AT+QIACT, then the assigned IP address can be queried with AT+QIACT?. See document [1] for detailed information. Step 3: Configure the SSL version, cipher suite, trusted CA certificate path and the security level for a specified SSL context with AT+QSSLCFG. Step 4: Open an SSL socket to connect a remote server with AT+QSSLOPEN. is used to specify SSL context, and is used to specify data access mode. Step 5: After the SSL connection has been established, data will be sent or received via the connection. For detailed information about how to send and receive data in each data access mode, see Chapter 1.4 Step 6: Close SSL connection with AT+QSSLCLOSE. Step 7: Deactivate the PDP context with AT+QIDEACT. See document [1] for detailed information. 1.4. Description of Data Access Modes The SSL connection supports three data access modes: ⚫ Buffer access mode ⚫ Direct push mode ⚫ Transparent transmission mode When opening an SSL connection via AT+QSSLOPEN, you can specify the data access mode with . After the SSL connection is established, you can switch the data access mode with AT+QISWTMD (see document [1] for details). 1. In buffer access mode, the module buffers data upon receiving them and reports a URC in the format of +QSSLURC: 'recv', to notify the host of the incoming data. In such a case, the host can retrieve the buffered data with AT+QSSLRECV. BG95&BG77&BG600L_Series_SSL_Application_Note 10 / 38 LPWA Module Series 2. In direct push mode, the module outputs the received data directly through UART1, USB modem or USB AT port as URC of +QSSLURC: 'recv',,. 3. In transparent transmission mode, the corresponding COM port (UART port, USB modem port, etc.) enters exclusive mode, in which the data received from the port are directly sent to the Internet, and data received from the Internet are directly outputted via the port. ⚫ Exit from transparent transmission mode The module can exit from transparent transmission mode through either of the following ways. 1) Execute +++. Follow the requirements below to prevent the +++ from being misinterpreted as data: a) Do not input any character within 1 second before and after inputting +++. b) Input +++ within 1 second, and wait until OK is returned. When OK is returned, the module is switched to buffer access mode. 2) Change MAIN_DTR from LOW to HIGH to make the module enter command mode. In this case, set AT&D1 (see document [2]) before the module enters transparent transmission mode. ⚫ Return to transparent transmission mode 1) By AT+QISWTMD. Specify as 2 when executing this command. When transparent transmission mode is entered successfully, CONNECT is returned. 2) By ATO (see document [2]). After a connection exits from transparent transmission mode, executing ATO will switch the data access mode back to transparent transmission mode. When transparent transmission mode is entered successfully, CONNECT is returned. If no connection has entered transparent transmission mode before, ATO returns NO CARRIER. 1.5. Certificate Validity Check To check certificate validity, compare your local time against certificate validity range ('Not before' and 'Not after'). If the local time is earlier than the 'Not before' time or later than the 'Not after' time the certificate has expired. When certificate validity check is required (set as 0 when executing AT+QSSLCFG), to avoid validity period check failure, execute AT+CCLK to configure the module time within the certificate validity period. See document [2] for detailed information about AT+CCLK. BG95&BG77&BG600L_Series_SSL_Application_Note 11 / 38 LPWA Module Series 1.6. Server Name Indication SNI (Server Name Indication) allows the server to safely host multiple TLS Certificates since it provides Server Host Name information as an extension in the client hello message. It thus enhances connection security with multiple virtual servers based on a single IP address. This feature is only applicable to TLS protocol. BG95&BG77&BG600L_Series_SSL_Application_Note 12 / 38 LPWA Module Series 2 Description of SSL AT Commands 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals to its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 4: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of corresponding Write Command and return information about the type, value, or range of its parameter. Check the current parameter value of a corresponding Write Command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. BG95&BG77&BG600L_Series_SSL_Application_Note 13 / 38 LPWA Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about how to use the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendation or suggestions about how you should design a program flow or what status you should set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there exists a correlation among these examples and that they should be executed in a given sequence. 2.3. Description of SSL AT Commands 2.3.1. AT+QSSLCFG Configure Parameters of an SSL Context The command configures the SSL version, cipher suite, security level, CA certificate, client certificate and client key. These parameters will be used in the handshake procedure. is the index of the SSL context. The module supports 6 SSL contexts at most. Several SSL connections can be established based on one SSL context. The settings such as the SSL version and the cipher suite are stored in the SSL context, and they will be applied to the new SSL connections associated with the SSL context. AT+QSSLCFG Configure Parameters of an SSL Context Test Command AT+QSSLCFG=? Response +QSSLCFG: 'sslversion',(range of supported s),(range of supported s) +QSSLCFG: 'ciphersuite',(range of supported s),(list of supported s) +QSSLCFG: 'cacert',(range of supported s), +QSSLCFG: 'clientcert',(range of supported s), +QSSLCFG: 'clientkey',(range of supported s), +QSSLCFG: 'seclevel',(range of supported s),(range of supported s) +QSSLCFG: 'session',(range of supported s),(list of supported s) +QSSLCFG: 'sni',(range of supported s),(list of supported s) +QSSLCFG: 'checkhost',(range of supported s),(list of supported s) BG95&BG77&BG600L_Series_SSL_Application_Note 14 / 38 LPWA Module Series +QSSLCFG: 'ignorelocaltime',(range of supported s),(list of supported s) +QSSLCFG: 'negotiatetime',(range of supported s),(range of supported s) +QSSLCFG: 'renegotiation',(range of supported s),(list of supported s) +QSSLCFG: 'dtls',(range of supported s),(list of supported s) +QSSLCFG: 'dtlsversion',(range of supported s),(range of supported s) Write Command AT+QSSLCFG='sslversion',[,] OK Response If the optional parameter is omitted, query the current SSL version of the specified SSL context: +QSSLCFG: 'sslversion',, OK Write Command AT+QSSLCFG='ciphersuite',[,] If the optional parameter is specified, set the SSL version for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query the current SSL cipher suite of the specified SSL context: +QSSLCFG: 'ciphersuite',, OK Write Command AT+QSSLCFG='cacert',[, ] If the optional parameter is specified, set the SSL cipher suite for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query the current path of trusted CA certificate for the specified SSL context: +QSSLCFG: 'cacert',, OK BG95&BG77&BG600L_Series_SSL_Application_Note 15 / 38 LPWA Module Series Write Command AT+QSSLCFG='clientcert',[,] If the optional parameter is specified, set the path of trusted CA certificate for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query the current path of client certificate for the specified SSL context: +QSSLCFG: 'clientcert',, OK Write Command AT+QSSLCFG='clientkey',[,] If the optional parameter is specified, set the path of client certificate for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query the current path of client private key for the specified SSL context: +QSSLCFG: 'clientkey',, OK Write Command AT+QSSLCFG='seclevel',[,] If the optional parameter is specified, set the path of the client private key for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query the current authentication mode of the specified SSL context: +QSSLCFG: 'seclevel',, Write Command AT+QSSLCFG='session',[,] OK If the optional parameter is specified, set the authentication mode for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether SSL Resumption feature is enabled for the specified SSL context: +QSSLCFG: 'session',, BG95&BG77&BG600L_Series_SSL_Application_Note 16 / 38 LPWA Module Series OK Write Command AT+QSSLCFG='sni',[,] If the optional parameter is specified, enable/disable SSL Resumption feature for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether server name indication feature is enabled for the specified SSL context: +QSSLCFG: 'sni',, OK Write Command AT+QSSLCFG='checkhost',[,] If the optional parameter is specified, enable/disable server name indication feature for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the hostname validation feature is enabled for the specified SSL context: +QSSLCFG: 'checkhost',, OK Write Command AT+QSSLCFG='ignorelocaltime',[,] If the optional parameter is specified, enable/disable hostname validation feature for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the certificate validity check is ignored for the specified SSL context: +QSSLCFG: 'ignorelocaltime',, OK If the optional parameter is specified, set whether or not to BG95&BG77&BG600L_Series_SSL_Application_Note 17 / 38 LPWA Module Series Write Command AT+QSSLCFG='negotiatetime',[,] ignore certificate validity check for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query the maximum timeout of SSL negotiation for the specified SSL context: +QSSLCFG: 'negotiatetime',, OK Write Command AT+QSSLCFG='renegotiation',[,] If the optional parameter is specified, set the maximum timeout of SSL negotiation for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether support for TLS renegotiation is enabled for the specified SSL context: +QSSLCFG: 'renegotiation',, OK Write Command AT+QSSLCFG='dtls',[,] If the optional parameter is specified, set whether to enable support for TLS renegotiation for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether DTLS feature is enabled for the specified SSL context: +QSSLCFG: 'dtls',, OK If the optional parameter is specified, set whether to enable DTLS feature for the specified SSL context: OK Or ERROR BG95&BG77&BG600L_Series_SSL_Application_Note 18 / 38 LPWA Module Series Write Command AT+QSSLCFG='dtlsversion',[,] Response If the optional parameter is omitted, query the current DTLS version of the specified SSL context: +QSSLCFG: 'dtlsversion',, OK Maximum Response Time Characteristics If the optional parameter is specified, set the DTLS version of the specified SSL context: OK Or ERROR 300 ms The command takes effect immediately. The configurations will not be saved. Parameter Integer type. SSL context ID. Range: 0–5. Integer type. SSL Version. 0 SSL3.0 1 TLS1.0 2 TLS1.1 3 TLS1.2 4 All Numeric type in HEX format. SSL cipher suites. 0X0035 TLS_RSA_WITH_AES_256_CBC_SHA 0X002F TLS_RSA_WITH_AES_128_CBC_SHA 0X0005 TLS_RSA_WITH_RC4_128_SHA 0X0004 TLS_RSA_WITH_RC4_128_MD5 0X000A TLS_RSA_WITH_3DES_EDE_CBC_SHA 0X003D TLS_RSA_WITH_AES_256_CBC_SHA256 0XC002 TLS_ECDH_ECDSA_WITH_RC4_128_SHA 0XC003 TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 0XC004 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 0XC005 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 0XC007 TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 0XC008 TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 0XC009 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 0XC00A TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 0XC011 TLS_ECDHE_RSA_WITH_RC4_128_SHA 0XC012 TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA BG95&BG77&BG600L_Series_SSL_Application_Note 19 / 38 LPWA Module Series 0XC013 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 0XC014 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 0XC00C TLS_ECDH_RSA_WITH_RC4_128_SHA 0XC00D TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 0XC00E TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 0XC00F TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 0XC023 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 0XC024 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 0XC025 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 0XC026 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 0XC027 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 0XC028 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 0XC029 TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 0XC02A TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 0XC02B TLS-ECDHE-ECDSA-WITH-AES-128-GCM-SHA256 0XC02F TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 0XC0A8 TLS_PSK_WITH_AES_128_CCM_8 0X00AE 0XC0AE TLS_PSK_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 0XFFFF Support all String type. The path of the trusted CA certificate. String type. The path of the client certificate. String type. The path of the client private key. Integer type. Authentication mode. 0 No authentication 1 Perform server authentication 2 Perform server and client authentication if requested by the remote server Integer type. Enable or disable SSL Resumption feature. 0 Disable 1 Enable Integer type. Enable or disable Server Name Indication feature. DNS hostnames are currently the only supported server names. 0 Disable 1 Enable Integer type. Enable or disable hostname validation feature (Subject Common Name (CN) matches the specified host name). 0 Disable 1 Enable Integer type. Whether or not to ignore certificate validity check. 0 Not to ignore 1 Ignore Integer type. The maximum timeout of SSL negotiation. Range: 10–300. Default value: 300. Unit: second. BG95&BG77&BG600L_Series_SSL_Application_Note 20 / 38 LPWA Module Series Integer type. Enable or disable support for TLS renegotiation. 0 Disable 1 Enable Integer type. Enable or disable DTLS feature. 0 Disable 1 Enable Integer type. DTLS version. 0 DTLS1.0 1 DTLS1.2 2 Both 2.3.2. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server The command sets up an SSL connection. During the negotiation between the module and the Internet, parameters configured with AT+QSSLCFG will be used in the handshake procedure. After successful handshake with the Internet, the module can send or receive data via this SSL connection. In addition, the module can set up several SSL connections based on one SSL context. According to steps mentioned in Chapter 1.3, execute AT+QIACT first to activate the PDP context and then execute AT+QSSLOPEN. It is suggested to wait for a specific period of time (refer to the Maximum Response Time below) for +QSSLOPEN: , URC to be outputted. If the URC cannot be received during that time, use AT+QSSLCLOSE to close the SSL connection. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server Test Command AT+QSSLOPEN =? Response +QSSLOPEN: (range of supported s),(range of supported s),(range of supported s),,,(range of supported s) Write Command AT+QSSLOPEN=,,,,[,] OK Response If the =2 (transparent access mode) and the SSL connection is successfully set up: CONNECT If the =0/1 (buffer access mode or direct push mode): OK BG95&BG77&BG600L_Series_SSL_Application_Note 21 / 38 LPWA Module Series Maximum Response Time Characteristics +QSSLOPEN: , If there is any error: ERROR Maximum network response time of 150 s, plus configured time of . The command takes effect immediately. The configurations will not be saved. Parameter Integer type. PDP context ID. Range: 1–16. Integer type. SSL context ID. Range: 0–5. Integer type. Socket index. Range: 0–11. String type. Remote server address. Integer type. The listening port of remote server. Range: 0–65535. Integer type. The data access mode of SSL connection. 0 Buffer access mode 1 Direct push mode 2 Transparent transmission mode The error code of the operation. See Chapter 5. Integer type. The maximum timeout of SSL negotiation. Range: 10–300. Default value: 300. Unit: second. NOTE Error description can be got via AT+QIGETERROR. For more details, refer to document [1]. 2.3.3. AT+QSSLSEND Send Data via SSL Connection After the connection is established, the module can send data through the SSL connection. AT+QSSLSEND Send Data via SSL Connection Test Command AT+QSSLSEND=? Response +QSSLSEND: (range of supported s), (range of supported s) Write Command Send variable-length data OK Response > BG95&BG77&BG600L_Series_SSL_Application_Note 22 / 38 AT+QSSLSEND= Write Command Send fixed-length data AT+QSSLSEND=, Maximum Response Time Characteristics LPWA Module Series After the above response, input the data to be sent. Tap CTRL+Z to send, and tap ESC to cancel the operation. If the connection has been established and sending is successful: SEND OK If the connection has been established but sending buffer is full: SEND FAIL If the connection has not been established, abnormally closed, or any parameter is incorrect: ERROR Response > After the above response, input the data until the data length equals . If the connection has been established and sending is successful: SEND OK If the connection has been established butsending buffer is full: SEND FAIL If the connection has not been established, abnormally closed, or the parameter is incorrect: ERROR 300 ms / Parameter Integer type. Socket index. Range: 0–11. Integer type. The length of data to be sent. Range: 1–1460. Unit: byte. BG95&BG77&BG600L_Series_SSL_Application_Note 23 / 38 LPWA Module Series 2.3.4. AT+QSSLRECV Retrieve Data Through SSL Connection When an SSL connection is opened with specified as 0 (buffer access mode), the module reports URC +QSSLURC: 'recv', when it receives data from the Internet. You can read the data from buffer with AT+QSSLRECV. AT+QSSLRECV Retrieve Data Through SSL Connection Test Command AT+QSSLRECV=? Response +QSSLRECV: (range of supported s),(range of supported s) Write Command When is not 0, retrieve the data in specified length AT+QSSLRECV=[,] OK Response If the specified connection has received data: +QSSLRECV: OK When the buffer is empty: +QSSLRECV: 0 Write Command When is 0, query the retrieved data length AT+QSSLRECV=,0 OK If any parameter is incorrect or the connection cannot be established: ERROR Response If the specified connection exists: +QSSLRECV: ,, OK Maximum Response Time Characteristics If there is any error: ERROR 300 ms / Parameter Integer type. Socket index. Range: 0–11. Integer type. The length of data to be retrieved. Range: 0–1500. Default BG95&BG77&BG600L_Series_SSL_Application_Note 24 / 38 LPWA Module Series value: 1500. Unit: byte. Integer type. Length of the data that have been actually retrieved. Unit: byte. String type. Retrieved data. Integer type. Total length of received data. Unit: byte. Integer type. Length of the data that have been retrieved. Unit: byte. Integer type. Length of the data that have not been retrieved. Unit: byte. 2.3.5. AT+QSSLCLOSE Close an SSL Connection The command closes an SSL connection. If all the SSL connections based on the same SSL context are closed, the module releases the SSL context. AT+QSSLCLOSE Close an SSL Connection Test Command AT+QSSLCLOSE=? Response +QSSLCLOSE: (range of supported s),(range of supported s) Write Command AT+QSSLCLOSE=[,] Maximum Response Time Characteristics OK Response OK Or ERROR 10 s by default, determined by parameter The command takes effect immediately. The configuration will not be saved. Parameter Integer type. Socket index. Range: 0–11. Integer type. The timeout value of AT+QSSLCLOSE. Range: 0–65535. Default value: 10. Unit: second. 0 means closing immediately. 2.3.6. AT+QSSLSTATE Query the State of SSL Connections The command queries the state of SSL connections. AT+QSSLSTATE Query the State of SSL Connections Test Command AT+QSSLSTATE=? Write Command AT+QSSLSTATE= Response OK Response +QSSLSTATE: ,'SSLClient',,,,,,,,< AT_port>, OK Response +QSSLSTATE: ,'SSLClient',,,,,,,,< AT_port>, [...] OK 300 ms / Parameter Integer type. Socket index. Range: 0–11. String type. Remote server address. Integer type. Remote server port. Range: 0–65535. Integer type. Local port. Range: 0–65535. Integer type. The state of SSL connection. 0 'Initial' Connection has not been established. 1 'Opening' Client is connecting. 2 'Connected' Connection has been established. 4 'Closing' Connection is closing Integer type. PDP context ID. Range: 1–16. Integer type. Reserved. The value is usually the same as . Integer type. The data access mode of SSL connection. 0 Buffer access mode 1 Direct push mode 2 Transparent transmission mode String type. COM port. Integer type. SSL context ID. Range: 0–5. BG95&BG77&BG600L_Series_SSL_Application_Note 26 / 38 LPWA Module Series 2.3.7. AT+QSSLCRYPT Encrypt/Decrypt Data with a Specified Algorithm This command encrypts/decrypts data with a specified algorithm. It supports AES-128-CBC encryption/decryption and MD5 encryption. AT+ QSSLCRYPT Encrypt/Decrypt Data with a Specified Algorithm Test Command AT+QSSLCRYPT=? Response +QSSLCRYPT: ('AES','MD5'),,(list of supported s),(list of supported s), Write Command AT+QSSLCRYPT='AES',,, OK Response +QSSLCRYPT: 'AES', OK Write Command AT+QSSLCRYPT='MD5', If there is any error: ERROR Response +QSSLCRYPT: 'MD5', OK Maximum Response Time Characteristic If there is any error: ERROR 300 ms / Parameter In AES-128-CBC mode: The data to be encrypted or decrypted. The data format is specified by . The maximum length of is 256 bytes. The length of data to be encrypted/decrypted with AES-128-CBC should be a multiple of 16 bytes. In MD5 mode: String type. The data to be encrypted. The maximum length of is 256 bytes. Integer type. The format of input data. 0 String format 1 Hex format Integer type. AES-128-CBC mode. 0 AES-128-CBC decryption BG95&BG77&BG600L_Series_SSL_Application_Note 27 / 38 LPWA Module Series 1 AES-128-CBC encryption String type. The encryption/decryption key of AES-128-CBC. The length must be 16 bytes. Hex String type. The encrypted data or decrypted data. 2.4. Description of URCs 2.4.1. +QSSLURC: 'recv' Notify Received Data The URC notifies the data received from peer in buffer access mode and direct push mode. +QSSLURC: 'recv' Notify Received Data +QSSLURC: 'recv', +QSSLURC: 'recv',, The URC of SSL data incoming in buffer access mode. SSL data can be retrieved with AT+QSSLRECV. The URC of SSL data incoming in direct push mode. Parameter Integer type. Socket index. Range: 0–11. Integer type. The length of actual received data. Unit: byte. The actual received data. 2.4.2. +QSSLURC: 'closed' Notify Abnormal Disconnection The URC notifies that the SSL connection has been disconnected. Disconnection can be caused by many reasons. For example, the Internet closes the connection or the state of GPRS PDP is deactivated, and the SSL connection state based on the specified socket may be 'closing'. In such case, AT+QSSLCLOSE= must be executed to change the SSL connection state to 'initial'. +QSSLURC: 'closed' Notify Abnormal Disconnection +QSSLURC: 'closed', The SSL connection based on the specified socket is closed. Parameter Integer type. Socket index. Range: 0–11. BG95&BG77&BG600L_Series_SSL_Application_Note 28 / 38 LPWA Module Series 3 Examples 3.1. Configure and Activate a PDP Context 3.1.1. Configure a PDP Context AT+QICSGP=1,1,'CMNBIOT','','',1 OK //Configure PDP context as 1. APN is 'CMNBIOT' for China Mobile NB-IoT network 3.1.2. Activate a PDP Context AT+QIACT=1 OK AT+QIACT? +QIACT: 1,1,1,'100.142.162.0' OK //Activate PDP context 1. //Activated the context successfully. //Query the context state, protocol type and IP address of PDP context 1. 3.1.3. Deactivate a PDP Context AT+QIDEACT=1 OK //Deactivate PDP context 1. //Deactivated the context successfully. 3.2. Configure an SSL Context AT+QSSLCFG='sslversion',1,1 OK AT+QSSLCFG='ciphersuite',1,0X0035 OK AT+QSSLCFG='seclevel',1,1 //Set SSL context ID as 1 and SSL version as TLS1.0. //Set SSL context ID as 1 and cipher suite as TLS_RSA_WITH_AES_256_CBC_SHA. //Set SSL context ID as 1 and authentication mode as BG95&BG77&BG600L_Series_SSL_Application_Note 29 / 38 LPWA Module Series server OK AT+QSSLCFG='cacert',1,'cacert.pem' OK authentication. //Set path of the trusted CA certificate of SSL context ID 1 3.3. SSL Client in Buffer Access Mode 3.3.1. Set up an SSL Connection and Enter Buffer Access Mode AT+QSSLOPEN=1,1,4,'220.180.239.212',8010,0 //Set up an SSL connection. OK +QSSLOPEN: 4,0 //Set up the SSL connection successfully. AT+QSSLSTATE //Query the state of SSL connections. +QSSLSTATE: 4,'SSLClient','220.180.239.212',8010,65344,2,1,4,0,'usbmodem',1 OK 3.3.2. Send Data in Buffer Access Mode AT+QSSLSEND=4 > Test data from SSL SEND OK AT+QSSLSEND=4,18 > Test data from SSL SEND OK //Send variable-length data. //Send fixed-length data and the data length is 18 bytes. 3.3.3. Retrieve Data in Buffer Access Mode +QSSLURC: 'recv',4 AT+QSSLRECV=4,1500 +QSSLRECV: 18 Test data from SSL //The Socket 4 (=4) has received data. //Retrieve the data. The length of data to be retrieved is 1500 bytes. //The retrieved data length is 18 bytes. OK AT+QSSLRECV=4,1500 +QSSLRECV: 0 //The buffer is empty. BG95&BG77&BG600L_Series_SSL_Application_Note 30 / 38 LPWA Module Series OK 3.3.4. Close an SSL Connection AT+QSSLCLOSE=4 OK //Close the connection (=4). Depending on the network, the maximum response time is 10 s. 3.4. SSL Client in Direct Push Mode 3.4.1. Set up an SSL Connection and Enter Direct Push Mode AT+QSSLOPEN= 1,1,4,'220.180.239.212',8011,1 //Set up an SSL connection. OK +QSSLOPEN: 4,0 //Set up the SSL connection successfully. AT+QSSLSTATE //Query the status of SSL connections. +QSSLSTATE: 4,'SSLClient','220.180.239.212',8011,65047,2,1,4,1,'usbmodem',1 OK 3.4.2. Send Data in Direct Push Mode AT+QSSLSEND=4 > Test data from SSL //Send variable-length data. SEND OK AT+QSSLSEND=4,18 > Test data from SSL //Send fixed-length data and the data length is 18 bytes. SEND OK 3.4.3. Retrieve Data in Direct Push Mode +QSSLURC: 'recv',4,18 Test data from SSL BG95&BG77&BG600L_Series_SSL_Application_Note 31 / 38 LPWA Module Series 3.4.4. Close an SSL Connection AT+QSSLCLOSE=4 OK //Close the connection (=4). Depending on the network, the maximum response time is 10 s. 3.5. SSL Client in Transparent Access Mode 3.5.1. Set up an SSL Connection and Send Data in Transparent Access Mode AT+QSSLOPEN= 1,1,4,'220.180.239.212',8011,2 CONNECT OK server //Set up an SSL connection. //Enter transparent transmission mode. //The client is sending data from COM port to the Internet directly. (The data are not visible in the example.) //Use +++ or MAIN_DTR (set AT&D1 first) to exit transparent transmission mode. The NO CARRIER result code indicates that the has stopped the SSL connection. 3.5.2. Set up an SSL Connection and Retrieve Data in Transparent Access Mode AT+QSSLOPEN= 1,1,4,'220.180.239.212',8011,2 CONNECT OK //Set up an SSL connection. //The client is reading the data. //Use +++ or MAIN_DTR (set AT&D1 first) to exit transparent transmission mode. The NO CARRIER result code indicates that the server has stopped the SSL connection. 3.5.3. Close an SSL Connection AT+QSSLCLOSE=4 OK //Close the connection (=4). Depending on the network, the maximum response time is 10 s. BG95&BG77&BG600L_Series_SSL_Application_Note 32 / 38 LPWA Module Series 3.6. DTLS Connection Based on PSK Encryption 3.6.1. Set up a DTLS Connection AT+QFUPL='0_server.psk' CONNECT +QFUPL: 24,553 //Upload PSK file first. The PSK file should be named as SSL_ctxID_server.psk (0_server.psk for instance) and the content of the file should be in the format of & (e.g., DTLS_Client&1a2b3c4d). OK AT+QSSLCFG='dtls',0,1 //Enable DTLS feature for SSL context 0. OK AT+QSSLCFG='dtlsversion',0,0 //Configure DTLS version to DTLS1.0 for SSL context 0. OK AT+QSSLCFG='ciphersuite',0,0X00AE //Configure cipher suite for SSL context 0. OK AT+QSSLOPEN=1,0,0,'220.180.239.201',8010,0 OK +QSSLOPEN: 0,0 //Set up the SSL connection successfully. AT+QSSLSTATE //Query the status of SSL connections. +QSSLSTATE: 0,'SSLClient','220.180.239.201',8010,65344,2,1,4,0,'usbmodem',1 OK 3.6.2. Close an SSL Connection AT+QSSLCLOSE=0 OK //Close the connection (=0). Depending on the network, the maximum response time is 10 s. BG95&BG77&BG600L_Series_SSL_Application_Note 33 / 38 LPWA Module Series 4 Check for Failure in SSL Connection Please find reasons for the failure to open an SSL connection as follows: 1. Query the status of the specified PDP context with AT+QIACT? to check whether the specified PDP context has been activated. 2. If the address of server is a domain name, please check whether the address of DNS server is valid with AT+QIDNSCFG=. Because an invalid DNS server address cannot convert domain name to IP address. 3. Check the SSL configuration with AT+QSSLCFG, especially the SSL version and cipher suite, to make sure that they are supported on server side. If has been configured as 1 or 2, then the trusted CA certificate has to be uploaded to the module with AT+QFUPL (see document [3]). If the server has configured 'SSLVerifyClient required', the client certificate and client private key have to be uploaded to the module with AT+QFUPL (see document [3]). For detailed information about certificate validity check, see Chapter 1.5. And for more information about related FILE AT commands, see document [2]. BG95&BG77&BG600L_Series_SSL_Application_Note 34 / 38 LPWA Module Series 5 Summary of Error Codes If an ERROR is returned after executing SSL AT commands, the details of error can be queried by AT+QIGETERROR. Please note that AT+QIGETERROR just returns error code of the last SSL AT command. Table 5: Summary of Error Codes 0 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 Meaning Operation successful Unknown error Operation blocked Invalid parameter Memory not enough Create socket failed Operation not supported Socket bind failed Socket listen failed Socket write failed Socket read failed Socket accept failed Open PDP context failed Close PDP context failed Socket identity has been used DNS busy BG95&BG77&BG600L_Series_SSL_Application_Note 35 / 38 565 DNS parse failed 566 Socket connection failed 567 Socket has been closed 568 Operation busy 569 Operation timeout 570 PDP context break down 571 Cancel send 572 Operation not allowed 573 APN not configured 574 Port busy LPWA Module Series BG95&BG77&BG600L_Series_SSL_Application_Note 36 / 38 LPWA Module Series 6 Appendix References Table 6: Related Documents Document Name [1] Quectel_BG95&BG77&BG600L_Series_TCP(IP)_Application_Note [2] Quectel_BG95&BG77&BG600L_Series_AT_Commands_Manual_V2.0 [3] Quectel_BG95&BG77&BG600L_Series_FILE_Application_Note Table 7: Terms and Abbreviations Abbreviation APN CA CR DNS DTR DTLS EGPRS GPRS ID IP LF PDP SNI Description Access Point Name Certificate Authority Carriage Return Domain Name Server Data Terminal Ready Datagram Transport Layer Security Enhanced General Packet Radio Service General Packet Radio Service Identifier Internet Protocol Line Feed Packet Data Protocol Server Name Indication BG95&BG77&BG600L_Series_SSL_Application_Note 37 / 38 SSL TCP TLS UART URC USB LPWA Module Series Secure Sockets Layer Transmission Control Protocol Transport Layer Security Universal Asynchronous Receiver/Transmitter Unsolicited Result Code Universal Serial Bus BG95&BG77&BG600L_Series_SSL_Application_Note 38 / 38
273.17 KB
GSM RF Test Application Note GSM/GPRS/GNSS Module Series Version: 1.0 Date: 2021-10-27 Status: Released GSM/GPRS/GNSS Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. GSM_RF_Test_Application_Note 1 / 21 GSM/GPRS/GNSS Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2021. All rights reserved. GSM_RF_Test_Application_Note 2 / 21 GSM/GPRS/GNSS Module Series About the Document Revision History Version 1.0 Date Author 2021-10-27 Waner PAN 2021-10-27 Waner PAN Description Creation of the document First official release GSM_RF_Test_Application_Note 3 / 21 GSM/GPRS/GNSS Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 1.1. Applicable Modules .................................................................................................................... 6 2 Application Note.................................................................................................................................. 7 2.1. AT Command Introduction ......................................................................................................... 7 2.1.1. Definitions........................................................................................................................ 7 2.1.2. AT Command Syntax ...................................................................................................... 7 2.2. Declaration of AT Command Examples ..................................................................................... 8 2.3. M66/M66 R2.0/M66-DS/M72 R3.0/M89/M95 R2.0/MC60/MC90 .............................................. 8 2.3.1. AT+QRFTEST Transmit/Receive in FTM Mode........................................................... 8 2.3.2. AT+QMAXTXPWR Limit the Maximum Transmit Power............................................ 10 2.3.3. AT+CDETXPW Decrease or Increase the Power of Certain PCL ..............................11 2.4. M08-R/M65/M95-R/MC65........................................................................................................ 13 2.4.1. AT+QRFTEST Transmit/Receive in FTM Mode......................................................... 13 2.4.2. AT+QMAXTXPWR Limit the Maximum Transmit Power............................................ 14 2.4.3. AT+CDETXPW Decrease or Increase the Power of Certain PCL ............................. 15 3 Examples ........................................................................................................................................... 18 3.1. AT+QRFTEST .......................................................................................................................... 18 3.2. AT+QMAXTXPWR ................................................................................................................... 18 3.3. AT+CDETXPW......................................................................................................................... 19 4 Summary of CME ERROR Codes .................................................................................................... 20 5 Appendix Reference ......................................................................................................................... 21 GSM_RF_Test_Application_Note 4 / 21 GSM/GPRS/GNSS Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 6 Table 2: Type of AT Commands ................................................................................................................... 7 Table 3: Related CME ERROR Codes (1) ................................................................................................. 20 Table 4: Related CME ERROR Codes (2) ................................................................................................. 20 Table 5: Terms and Abbreviations .............................................................................................................. 21 GSM_RF_Test_Application_Note 5 / 21 GSM/GPRS/GNSS Module Series 1 Introduction This document is a reference guide for AT commands and responses of GSM RF test. 1.1. Applicable Modules Table 1: Applicable Modules Module Series Mxx MCxx Module M66 M66 R2.0 M66-DS M72 R3.0 M89 M95 R2.0 M08-R M65 M95-R MC60 MC90 MC65 GSM_RF_Test_Application_Note 6 / 21 GSM/GPRS/GNSS Module Series 2 Application Note 2.1. AT Command Introduction 2.1.1. Definitions ⚫ ⚫ ⚫ ⚫ [...] Carriage return character. Line feed character. Parameter name. Angle brackets do not appear on the command line. Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals to its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 2: Type of AT Commands Command Type Syntax Description Test Command Read Command Write Command AT+=? Test the existence of corresponding Write Command and return information about the type, value, or range of its parameter. AT+? Check the current parameter value of a corresponding Write Command. AT + < c m d > = < p 1 > [ , < p 2 > [ , < p 3 > Set user-definable parameter value. [...]]] Execution Command AT+ Return a specific information parameter or GSM_RF_Test_Application_Note 7 / 21 GSM/GPRS/GNSS Module Series perform a specific action. 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about how to use the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendation or suggestions about how you should design a program flow or what status you should set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there exists a correlation among these examples and that they should be executed in a given sequence. 2.3. M66/M66 R2.0/M66-DS/M72 R3.0/M89/M95 R2.0/MC60/MC90 2.3.1.AT+QRFTEST Transmit/Receive in FTM Mode AT+QRFTEST Transmit/Receive in FTM Mode Test Command AT+QRFTEST=? Response +QRFTEST: (1-TX,2-RX),(band:0-3),(arfcn:0-1023),/,(burst type:0-6/pattern:0-1) Write Command When =1, transmit in FTM mode AT+QRFTEST=,,,,,, OK Response OK If the error is related to ME functionality: +CME ERROR: Write Command When =2, receive in FTM mode AT+QRFTEST=,,,, If there is any other error: ERROR Response OK If the error is related to ME functionality: +CME ERROR: If there is any other error: ERROR GSM_RF_Test_Application_Note 8 / 21 GSM/GPRS/GNSS Module Series Maximum Response Time Characteristics 300 ms This command takes effect immediately. The configuration will not be saved. Parameter Integer type. Transmit/Receive in FTM mode. 1 Transmit in FTM mode 2 Receive in FTM mode Integer type. The supported band in GSM. 0 EGSM900 1 DCS1800 2 PCS1900 3 GSM850 Integer type. ARFCN of supported channels in GSM. 0–124, 975–1023 EGSM900 512–885 DCS1800 512–810 PCS1900 128–251 GSM850 Integer type. Time slot. Range: 0–7. Integer type. Power control level. 5–19 GSM850/EGSM900 0–15 DCS1800/PCS1900 The compensation value of automatic frequency control. It is only valid for 4100 Hz. Integer type. The mode for transmitted pulse. 0 Random 0 or 1 to be transmitted with timeslot 1 1 to be transmitted without timeslot 2 Random 0 or 1 to be transmitted with synchronous sequence 3 0 to be transmitted continuously 4 1 to be transmitted continuously 5 Alternate bits to be transmitted continuously 6 Pseudo random number to be transmitted continuously Integer type. The gain value of the RF receiving circuit. It is only valid for 40 dBm. Integer type. Receiving mode. 0 Receive continuously 1 Receive burst Error code. See Chapter 4 for details. NOTE This command is available only when the parameter of AT+CFUN=,[] is 0. GSM_RF_Test_Application_Note 9 / 21 GSM/GPRS/GNSS Module Series 2.3.2.AT+QMAXTXPWR Limit the Maximum Transmit Power AT+QMAXTXPWR Limit the Maximum Transmit Power Test Command AT+QMAXTXPWR=? Response +QMAXTXPWR: (list of supported s) OK If error is related to ME functionality: +CME ERROR: Read Command AT+QMAXTXPWR? If there is any other error: ERROR Response +QMAXTXPWR: OK If the error is related to ME functionality: +CME ERROR: Write Command AT+QMAXTXPWR= If there is any other error: ERROR Response OK If error is related to ME functionality: +CME ERROR: Maximum Response Time Characteristics If there is any other error: ERROR 300 ms This command takes effect immediately. The configuration will not be saved. Parameter Integer type. The maximum transmit power. Unit: dBm. 18–33 Custom scope 255 The maximum power value is not defined Error code. See Chapter 4 for details. GSM_RF_Test_Application_Note 10 / 21 GSM/GPRS/GNSS Module Series 2.3.3.AT+CDETXPW Decrease or Increase the Power of Certain PCL AT+CDETXPW Decrease or Increase the Power of Certain PCL Test Command AT+CDETXPW=? Response +CDETXPW=(list of supported s),(list of supported s),, [,] Read Command AT+CDETXPW? OK Response +CDETXPW: (dB) 850: {,,,} 900: {,,,} 1800: {,,,} 1900: {,,,} Write Command AT+CDETXPW=,[ ,[,[,]]] OK Response OK If all the optional parameters are omitted, query the decreased or increased power of all PCL with certain slot in certain band: +CDETXPW: (dB) (): {,,…,} OK If and are omitted, query the decreased or increased power of certain PCL with certain slot in certain band: +CDETXPW: (dB) ()[]: OK If is omitted, set to decrease the power of certainPCL with certain slot in certain band: OK If optional parameters are specified, set to decrease or increase the power of certain PCL with certain slot in GSM_RF_Test_Application_Note 11 / 21 GSM/GPRS/GNSS Module Series Maximum Response Time Characteristics certain band: OK If the error is related to ME functionality: +CME ERROR: If there is any other error: ERROR 300 ms This command takes effect immediately. The configuration will be saved to NVRAM automatically. Parameter Integer type. Specify the band. 850 GSM850 900 EGSM900 1800 DCS1800 1900 PCS1900 Integer type. Specify the slot number of TX. 1 2 3 4 Integer type. The value of TX slot. Unit: dBm. Integer type. The power control level. 5–19 For GSM850 and EGSM900 0–15 For DCS1800 and PCS1900 255 Apply to every PCLs for the specific band Integer type. Decreased/Increased value of power. Unit: dBm. Integer type. Decreased or increased mode. 0 Decreased mode 1 Increased mode Error code. See Chapter 4 for details. NOTE Some modules do not support the parameter . For the specific modules, please contact Quectel Technical Supports. GSM_RF_Test_Application_Note 12 / 21 GSM/GPRS/GNSS Module Series 2.4. M08-R/M65/M95-R/MC65 2.4.1.AT+QRFTEST Transmit/Receive in FTM Mode AT+QRFTEST Transmit/Receive in FTM Mode Test Command AT+QRFTEST=? Response +QRFTEST: (list of supported s),(list of supported s),(list of supported s),(list of supported s),(list of supported s) Write Command When =1, transmit in FTM mode AT+QRFTEST=,,,,< pcl> OK Response OK If the error is related to ME functionality: +CME ERROR: If there is any other error: ERROR Write Command When =2, receive in FTM mode AT+QRFTEST=,,, Response +QRFTEST: OK If the error is related to ME functionality: +CME ERROR: Maximum Response Time Characteristics If there is any other error: ERROR 300 ms This command takes effect immediately. The configuration will not be saved. Parameter Integer type. Transmit/Receive in FTM mode. 0 Exit from TX/RX mode 1 Transmit in FTM mode 2 Receive in FTM mode Integer type. The supported band in GSM. GSM_RF_Test_Application_Note 13 / 21 GSM/GPRS/GNSS Module Series 0 EGSM900 1 DCS1800 2 PCS1900 3 GSM850 Integer type. ARFCN of supported channels in GSM. EGSM900: 0–124, 975–1023 DCS1800: 512–885 PCS1900: 512–810 GSM850: 128–251 Integer type. Time slot. Range: 0–7. Integer type. Power control level. GSM850/EGSM900: 5–19 DCS1800/PCS1900: 0–15 Integer type. Expected power. Range: -110 to -15. Unit: dBm. Integer type. Received power. Unit: dBm. Error code. See Chapter 4 for details. NOTE This command takes effect only after AT^REBOOT=2 has been executed. 2.4.2.AT+QMAXTXPWR Limit the Maximum Transmit Power AT+QMAXTXPWR Limit the Maximum Transmit Power Test Command AT+QMAXTXPWR=? Response +QMAXTXPWR: (list of supported s) OK If error is related to ME functionality: +CME ERROR: Read Command AT+QMAXTXPWR? If there is any other error: ERROR Response +QMAXTXPWR: OK If the error is related to ME functionality: +CME ERROR: GSM_RF_Test_Application_Note 14 / 21 GSM/GPRS/GNSS Module Series Write Command AT+QMAXTXPWR= Maximum Response Time Characteristics If there is any other error: ERROR Response OK If error is related to ME functionality: +CME ERROR: If there is any other error: ERROR 300 ms This command takes effect immediately. The configuration will be saved automatically Parameter Integer type. The maximum transmit power. Unit: dBm. 18–26,29 Custom scope 255 The maximum power value is not defined Error code. See Chapter 4 for details. 2.4.3.AT+CDETXPW Decrease or Increase the Power of Certain PCL AT+CDETXPW Decrease or Increase the Power of Certain PCL Test Command AT+CDETXPW=? Response +CDETXPW: (list of supported s),(list of supported s),, [,] Read Command AT+CDETXPW? OK Response +CDETXPW: (dB) 850: {,,,} 900: {,,,} 1800: {,,,} 1900: {,,,} Write Command AT+CDETXPW=,[ OK Response OK GSM_RF_Test_Application_Note 15 / 21 GSM/GPRS/GNSS Module Series ,[,[,]]] Maximum Response Time Characteristics If all the optional parameters are omitted, query the decreased or increased power of all PCL with certain slot in certain band: +CDETXPW: (dB) (): {,,…,} OK If and are omitted, query the decreased or increased power of certain PCL with certain slot in certain band: +CDETXPW: (dB) ()[]: OK If is omitted, set to decrease the power of certain PCL with certain slot in certain band: OK If optional parameters are specified, set to decrease or increase the power of certain PCL with certain slot in certain band: OK If the error is related to ME functionality: +CME ERROR: If there is any other error: ERROR 300 ms This command takes effect immediately. The configuration will be saved to NVRAM automatically. Parameter Integer type. Specify the band. 850 GSM850 900 EGSM900 1800 DCS1800 1900 PCS1900 GSM_RF_Test_Application_Note 16 / 21 GSM/GPRS/GNSS Module Series Integer type. Specify the slot number of TX. 1 2 3 4 Integer type. The value of TX slot. Unit: dBm. Integer type. The power control level. 5–19 For GSM850 and EGSM900 0–15 For DCS800 and PCS1900 255 Apply to every PCLs for the specific band Integer type. Decreased/Increased value of power. Unit: dBm. Integer type. Decreased or increased mode. 0 Decreased mode 1 Increased mode Error code. See Chapter 4 for details. NOTE Some modules do not support the parameter . For the specific modules, please contact Quectel Technical Supports. GSM_RF_Test_Application_Note 17 / 21 GSM/GPRS/GNSS Module Series 3 Examples 3.1. AT+QRFTEST //M66/M66 R2.0/M66-DS/M72 R3.0/M89/M95 R2.0/MC60/MC90 modules AT+CFUN=0 //Disable GSM protocol stack. OK AT+QRFTEST=1,0,9,0,19,4100,0 //Transmit in FTM mode. OK AT+QRFTEST=2,0,9,40,0 //Receive in FTM mode. OK //M08-R/M65/M95-R/MC65 modules AT^REBOOT=2 OK AT+QRFTEST=1,0,80,0,10 //Transmit in FTM mode. OK AT+QRFTEST=2,0,62,-70 //Receive in FTM mode. +QRFTEST: -71 OK AT^REBOOT=0 OK 3.2. AT+QMAXTXPWR //M08-R/M65/M95-R/MC65 modules AT+QMAXTXPWR=? +QMAXTXPWR: (18-26,29,255) OK //M66/M66 R2.0/M66-DS/M72 R3.0/M89/M95 R2.0/MC60/MC90 modules AT+QMAXTXPWR=? +QMAXTXPWR: (18-33,255) OK GSM_RF_Test_Application_Note 18 / 21 AT+QMAXTXPWR? +QMAXTXPWR: 255 OK AT+QMAXTXPWR=28 OK AT+QMAXTXPWR? +QMAXTXPWR: 28 OK GSM/GPRS/GNSS Module Series //Query the current settings. //There is no customized maximum power value at present. //The maximum transmit power is set to 28 dBm. //Query the current configuration. //The value of current customized maximum power is 28 dBm. 3.3. AT+CDETXPW AT+CDETXPW=850,2,7,2 //Decrease 2 dBm of PCL 7 with TX slot 2 in the 850 MHz band. OK AT+CDETXPW=900,1,255,2 //Decrease 2 dBm of every PCL (5–19) with TX slot 1 in the 900 MHz band. OK AT+CDETXPW=900,1,255,2,1 //Increase 2 dBm of every PCL (5–19) with TX slot 1 in the 900 MHz band. OK AT+CDETXPW=900,1 //Query the power of all PCL (5–19) with TX slot 1 in the 900 MHz band. +CDETXPW: (dB) 900(1): {2,2,2,2,2,2,2,2,2,2,2,2,2,2,2} OK AT+CDETXPW=900,1,5 +CDETXPW: (dB) 900(1)[5]: 2 //Query the power of the PCL 5 with TX slot 1 in the 900 MHz band. OK AT+CDETXPW=850,2,7 +CDETXPW: (dB) 850(2)[7]: -2 //Query the power of the PCL 7 with TX slot 2 in the 850 MHz band. OK GSM_RF_Test_Application_Note 19 / 21 GSM/GPRS/GNSS Module Series 4 Summary of CME ERROR Codes The CME ERROR code indicates an error related to mobile equipment or network. The details about for M66, M66 R2.0, M66-DS, M72 R3.0, M89, M95 R2.0, MC60 and MC90 modules are described in the Table 3. Table 3: Related CME ERROR Codes (1) 4 603 3518 3765 3773 3774 Meaning Operation not supported Syntax error Invalid parameter Invalid input value Invalid CFUN state Invalid ARFCN The details about for M08-R, M65, M95-R and MC65 modules are described in the Table 4. Table 4: Related CME ERROR Codes (2) 49 53 Meaning Invalid parameter Operation not supported GSM_RF_Test_Application_Note 20 / 21 GSM/GPRS/GNSS Module Series 5 Appendix Reference Table 5: Terms and Abbreviations Abbreviation ARFCN FTM GSM PCL RF RX TX Description Absolute Radio-Frequency Channel Number Factory Test Mode Global System for Mobile Communications Power Control Level Radio Frequency Receive Transmit GSM_RF_Test_Application_Note 21 / 21
239.86 KB
LTE-A(Q) IMS Application Note LTE-A Module Series Version: 1.0 Date: 2021-08-18 Status: Released LTE-A Module Series Our aim is to provide customers with timely and comprehensive service. For any assistance, please contact our company headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local office. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm Or email to support@quectel.com. General Notes Quectel offers the information as a service to its customers. The information provided is based upon customers’ requirements. Quectel makes every effort to ensure the quality of the information it makes available. Quectel does not make any warranty as to the information contained herein, and does not accept any liability for any injury, loss or damage of any kind incurred by use of or reliance upon the information. All information supplied herein is subject to change without prior notice. Disclaimer While Quectel has made efforts to ensure that the functions and features under development are free from errors, it is possible that these functions and features could contain errors, inaccuracies and omissions. Unless otherwise provided by valid agreement, Quectel makes no warranties of any kind, implied or express, with respect to the use of features and functions under development. To the maximum extent permitted by law, Quectel excludes all liability for any loss or damage suffered in connection with the use of the functions and features under development, regardless of whether such loss or damage may have been foreseeable. Duty of Confidentiality The Receiving Party shall keep confidential all documentation and information provided by Quectel, except when the specific permission has been granted by Quectel. The Receiving Party shall not access or use Quectel’s documentation and information for any purpose except as expressly provided herein. Furthermore, the Receiving Party shall not disclose any of the Quectel's documentation and information to any third party without the prior written consent by Quectel. For any noncompliance to the above requirements, unauthorized use, or other illegal or malicious use of the documentation and information, Quectel will reserve the right to take legal action. LTE-A(Q)_IMS_Application_Note 1 / 27 LTE-A Module Series Copyright The information contained here is proprietary technical information of Quectel. Transmitting, reproducing, disseminating and editing this document as well as using the content without permission are forbidden. Offenders will be held liable for payment of damages. All rights are reserved in the event of a patent grant or registration of a utility model or design. Copyright © Quectel Wireless Solutions Co., Ltd. 2021. All rights reserved. LTE-A(Q)_IMS_Application_Note 2 / 27 LTE-A Module Series About the Document Revision History Version 1.0 Date 2021-01-25 2021-08-18 Author Wythe WANG/ Yosef ZHANG Wythe WANG/ Yosef ZHANG Description Creation of the document First official release LTE-A(Q)_IMS_Application_Note 3 / 27 LTE-A Module Series Contents About the Document ................................................................................................................................3 Contents .................................................................................................................................................... 4 Table Index ...............................................................................................................................................5 Figure Index ..............................................................................................................................................6 1 Introduction .......................................................................................................................................7 1.1. Applicable Modules ..................................................................................................................7 1.2. Introduction of MBN..................................................................................................................8 1.2.1. MBN File ........................................................................................................................8 1.2.2. MBN Type ......................................................................................................................8 1.2.3. MBN Selection ...............................................................................................................9 1.3. Introduction of IMS ...................................................................................................................9 1.3.1. IMS Registration Process ............................................................................................10 1.3.2. Processes of Services over IMS .................................................................................. 11 1.3.2.1. VoLTE ............................................................................................................... 11 1.3.2.2. SMS ..................................................................................................................12 1.3.2.3. Emergency Call.................................................................................................13 1.3.2.4. DTMF ................................................................................................................13 1.3.2.5. SRVCC .............................................................................................................14 2 IMS Related AT Command..............................................................................................................16 2.1. AT Command Introduction ......................................................................................................16 2.1.1. Definitions ....................................................................................................................16 2.1.2. AT Command Syntax ...................................................................................................16 2.2. Declaration of AT Command Examples ..................................................................................17 2.3. Description of AT Command ...................................................................................................17 2.3.1. AT+QCFG='ims' Configure IMS ...............................................................................17 2.3.2. AT+QMBNCFG Extended MBN Configuration ..........................................................18 2.3.2.1. AT+QMBNCFG='List' List All MBN Files........................................................18 2.3.2.2. AT+QMBNCFG='Select' Select a Specific MBN File .....................................19 2.3.2.3. AT+QMBNCFG='Deactivate' Deactivate MBN Files......................................20 2.3.2.4. AT+QMBNCFG='AutoSel' Configure MBN Automatic Selection....................20 2.3.2.5. AT+QMBNCFG='Delete' Delete a Specified MBN File ....................