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
L26-DR (UDR&ADRC) DR Application Note GNSS Module Series Version: 1.0 Date: 2022-06-28 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. L26-DR(UDR&ADRC)_DR_Application_Note 1 / 24 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. L26-DR(UDR&ADRC)_DR_Application_Note 2 / 24 GNSS Module Series About the Document Document Information Title Subtitle Document Type Document Status L26-DR (UDR&ADRC) DR Application Note GNSS Module Series Application Note Released Revision History Version Date - 2022-04-15 1.0 2022-06-28 Description Creation of the document First official release L26-DR(UDR&ADRC)_DR_Application_Note 3 / 24 GNSS Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index .................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 2 Configuration....................................................................................................................................... 8 2.1. Orientation .............................................................................................................................. 8 2.2. Mounting ................................................................................................................................. 9 2.3. DR Calibration ...................................................................................................................... 10 2.4. Configuration Bits ..................................................................................................................11 2.4.1. Set the Configuration Bits ..............................................................................................11 2.4.2. Get the Configuration Bits ............................................................................................. 13 3 Messages ........................................................................................................................................... 14 3.1. PQ Messages ....................................................................................................................... 14 3.1.1. PQSOL .......................................................................................................................... 14 3.1.2. PQGNSS ....................................................................................................................... 16 3.1.3. PQSNR,21..................................................................................................................... 18 3.1.4. PQSNR,23..................................................................................................................... 19 3.1.5. PQEND.......................................................................................................................... 20 3.2. PSTM Messages .................................................................................................................. 20 3.2.1. PSTMDRSENMSG ....................................................................................................... 20 3.2.1.1. IMU Temperature Message (MsgID = 24) ............................................................ 21 3.2.1.2. IMU Accelerometer Message (MsgID = 30) ......................................................... 21 3.2.1.3. IMU Gyroscope Message (MsgID = 31)............................................................... 22 3.2.2. PSTMIMUSELFTESTCMD ........................................................................................... 23 4 Appendix References ....................................................................................................................... 24 L26-DR(UDR&ADRC)_DR_Application_Note 4 / 24 GNSS Module Series Table Index Table 1: List of Configuration Bits ...............................................................................................................11 Table 2: Terms and Abbreviations .............................................................................................................. 24 L26-DR(UDR&ADRC)_DR_Application_Note 5 / 24 GNSS Module Series Figure Index Figure 1: Module Orientation........................................................................................................................ 8 Figure 2: Module and Vehicle Installation Diagram ..................................................................................... 9 L26-DR(UDR&ADRC)_DR_Application_Note 6 / 24 GNSS Module Series 1 Introduction This document describes the dead reckoning (DR) feature, including orientation, mounting, calibration, configuration bits and messages related to the Dead Reckoning functionality of the Quectel L26-DR module. Quectel offers a two DR product portfolio. The first one is ADRC which combines a 6-axis inertial sensor (3-axis gyroscope and 3-axis accelerometer) and an attached sensor like a wheel speed sensor. The L26-DR (ADRC) module is mainly used for two-wheel applications like motorcycles and scooters. Another one is UDR. The L26-DR (UDR) can be used for 4-wheel applications without the addition of the wheel speed sensor. The use of the additional wheel speed sensor allows for the dead reckoning to be maintained for longer in situations of GNSS outages than it is possible with untethered UDR where only the internal IMU is used and no additional tethering is implemented on the vehicle. L26-DR (ADRC) module is typically used in OEM cases and L26-DR (UDR) is typically used in aftermarket products. This document applies to the following variants of the L26-DR module: ⚫ L26-DR (UDR) ⚫ L26-DR (ADRC) Module L26-DR (UDR) L26-DR (ADRC) Vehicle Type Four-wheeler Two-wheeler Connect Speed or Not No Yes L26-DR(UDR&ADRC)_DR_Application_Note 7 / 24 GNSS Module Series 2 Configuration 2.1. Orientation The L26-DR module is designed to work on two-wheel or four-wheel vehicles. User must install the module embedding GNSS and motion sensor ICs steadily constrained to vehicle body. No relative movement is allowed between vehicle and device and maximum isolation from both shock and vibration must be provided. Manually holding the board is not accepted. The best way to guarantee good installation is to firmly screw the device down to the vehicle frame. Mounting location should permit easy access to power supply and GNSS antenna, and should not be exposed to excessive heat. Z Yaw Pitch X Y Roll Figure 1: Module Orientation NOTE Rigidly mount module tight to the vehicle body. Select a structurally sound location that is not prone to flexing (bending motion of the vehicle chassis). L26-DR(UDR&ADRC)_DR_Application_Note 8 / 24 GNSS Module Series 2.2. Mounting The Quectel L26-DR module can be mounted on a vehicle in any orientation, but one axis (recommend the Z axis ) must be perpendicular to the horizontal plane. The reference model is as follows: Yaw X Pitch β -β Roll γ -γ Figure 2: Module and Vehicle Installation Diagram Referring to the above installation model, there is no limit to the α angle during the installation process of the module (0° ≤ α ≤ 360°). In order to make the module work in the best state, it is recommended that the β angle and the γ angle should be less than 15 degrees (-15° ≤ β ≤ 15°, -15° ≤ γ≤ 15°). In other words, it is to ensure that the angle between the plane where the module is located and the horizontal plane should L26-DR(UDR&ADRC)_DR_Application_Note 9 / 24 be less than 15 degrees. GNSS Module Series NOTE 1. Only Yaw Angle is unlimited. 2. Module positioning performance degradation occurs when the β and γ angle exceeds 15 degrees. 2.3. DR Calibration The module needs to be calibrated before the dead reckoning functionality will be useful. The DR calibration steps are as follows: Step 1: Fix the module on the vehicle frame firmly. Any displacement, rotation or tilt of the device, however small relative to the vehicle plane may cause performance issues and/or void calibration. Step 2: Calibration should be performed under good GNSS signal and clear sky conditions. Step 3: Do not interfere with or move the device after powering on. Step 4: After the initial power on, the vehicle should be stationary between 30 seconds and 1 minute. Once driving, the vehicle needs to have one or two dynamic changes (in the case of satellite signals), such as waiting for traffic lights, acceleration and deceleration and other normal driving scenes. Step 5: The calibration process ends when the of $PQSOL message indicates a combined solution (GNSS + DR). See Chapter 3.1.1 for details about the message. After the calibration, there is no limit to driving trajectory and driving dynamics, you can perform verification tests by referring to the following scenarios: 1) Open sky area, urban main road (check good satellite signal). 2) Urban tunnels (assessment of absence of satellite signals). 3) Urban viaduct (assessment of weak satellite signals). 4) Underground vehicle park (assess the absence of satellite signal). 5) Surrounding areas with dense buildings (assessing multi-path of canyon in the city). 6) City boulevards (assessment of weak satellite signals). 7) High rise dense area (examine the serious condition of canyon multipath in the city). L26-DR(UDR&ADRC)_DR_Application_Note 10 / 24 2.4. Configuration Bits GNSS Module Series Table 1: List of Configuration Bits Bit 22, 23 24 25 26 27 28 29 30 Bitmask (32 bits) 0x000000 0x400000 0x800000 0xC00000 0x1000000 0x2000000 0x4000000 0x8000000 0x10000000 0x20000000 0x40000000 Function Fix rate control. 1 Hz (default). Fix rate control. 5 Hz. Fix rate control. 10 Hz (UART baud rate ≥ 230400 bps). Fix rate control. 20 Hz (UART baud rate ≥ 230400 bps). Enable $PQSOL message. Enable $PQGNSS message. Enable $PQSNR,21 and $PQEND messages. Enable $PQSNR,23 message. Enable $PSTMDRSENMSG message. Enable/Disable DR feature. 0 = Enable 1 = Disable Enable/Disable DR hot start feature. 0 = Disable 1 = Enable 2.4.1. Set the Configuration Bits 1) Clear the bitmask. $PSTMSETPAR,1228,,2* ⚫ If successful, the module returns: $PSTMSETPAROK,1228* ⚫ If failed, the module returns: $PSTMSETPARERROR,1228* L26-DR(UDR&ADRC)_DR_Application_Note 11 / 24 2) Set the bitmask. $PSTMSETPAR,1228,,1* ⚫ If successful, the module returns: $PSTMSETPAROK,1228* ⚫ If failed, the module returns: $PSTMSETPARERROR,1228* 3) Save the parameters. $PSTMSAVEPAR*58 ⚫ If successful, the module returns: $PSTMSAVEPAROK* ⚫ If failed, the module returns: $PSTMSAVEPARERROR* 4) Restart the module. $PSTMSRR*49 Example: 1) Set the fix rate to 5 Hz. //Clear the bitmask: $PSTMSETPAR,1228,0xC00000,2*32 $PSTMSETPAROK,1228*3A //Set the bitmask: $PSTMSETPAR,1228,0x400000,1*43 $PSTMSETPAROK,1228*3A //Save the parameter: $PSTMSAVEPAR*58 $PSTMSAVEPAROK*5C //Restart: $PSTMSRR*49 2) Disable $PQSOL message //Clear the bitmask: L26-DR(UDR&ADRC)_DR_Application_Note GNSS Module Series 12 / 24 $PSTMSETPAR,1228,0x1000000,2*75 $PSTMSETPAROK,1228*3A //Save the parameter: $PSTMSAVEPAR*58 $PSTMSAVEPAROK*5C //Restart: $PSTMSRR*49 3) Enable $PQSOL message //Set the bitmask: $PSTMSETPAR,1228,0x1000000,1*76 $PSTMSETPAROK,1228*3A //Save the parameter: $PSTMSAVEPAR*58 $PSTMSAVEPAROK*5C //Restart: $PSTMSRR*49 2.4.2. Get the Configuration Bits Command: $PSTMGETPAR,1228*2A ⚫ If successful, the module returns: $PSTMSETPAR,1228,* ⚫ If failed, the module returns: $PSTMGETPARERROR* Example: $PSTMGETPAR,1228*2A $PSTMSETPAR,1228,0x11000000*5B GNSS Module Series L26-DR(UDR&ADRC)_DR_Application_Note 13 / 24 GNSS Module Series 3 Messages 3.1. PQ Messages This chapter introduces the PQ messages (proprietary NMEA messages defined by Quectel) supported by Quectel L26-DR module. 3.1.1. PQSOL This message reports the navigation results. Type: Output Synopsis: $PQSOL,,,,,,,,,,< TOW>,,,,,,,,,,,,,,,,,,,,,,,,,,,* Parameter: Field Format Numeric Numeric Numeric Numeric Numeric Numeric Numeric Unit Description - Message Subtype ID, fixed as 1. Year Year. Month Month. Range: 1–12. Day Day. Range: 1–31. Hour Hour. Range: 0–23. Minute Minutes. Range: 0–59. Millisecond Milliseconds. Range: 0–59950 (20 Hz fix L26-DR(UDR&ADRC)_DR_Application_Note 14 / 24 Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric GNSS Module Series Millisecond rate); 0–59900 (10 Hz fix rate); 0–59800 (5 Hz fix rate); 0–59000 (1 Hz fix rate). Milliseconds since power on. 32-bit unsigned integer. Week GPS week number, including rollover. Millisecond Time of week. Navigation mode. 0 = No navigation. Bit 0: Reserved. Bit 1: GNSS-only. Bit 2: DR-only. Bit 3: Combined solution (GNSS + DR). Bit 4–8: Reserved. Bit 9: Odometer (wheel tick) in use. Bit 10, 11: Reserved. Bit 12: DGNSS (not including satellite-based correction source). Bit 13–31: Reserved. Degree Latitude, scaled by 10^7. Degree Longitude, scaled by 10^7. cm Ellipsoidal height. cm Height above mean sea level. cm/s Northward velocity. cm/s Eastward velocity. cm/s Downward velocity. cm/s Speed over ground. cm Traveled distance since power on. Degree Roll angle, scaled by 100. Degree Pitch angle, scaled by 100. Degree Heading angle, scaled by 100. - - - - Uncertainty of position in northward cm direction. L26-DR(UDR&ADRC)_DR_Application_Note 15 / 24 GNSS Module Series Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric cm cm cm/s cm/s cm/s Degree Degree Degree Degree Degree Degree Uncertainty of position in eastward direction. Uncertainty of position in downward direction. Northward velocity uncertainty. Eastward velocity uncertainty. Downward velocity uncertainty. Roll angle uncertainty, scaled by 100. Pitch angle uncertainty, scaled by 100. Yaw angle uncertainty, scaled by 100. Roll angle misalignment, scaled by 100. Pitch angle misalignment, scaled by 100. Yaw angle misalignment, scaled by 100. Example: $PQSOL,1,2021,12,21,8,25,4000,61300,2189,203121999,2,318221924,1171155060,6587,6618,-3,4,0,5 ,156,1182,331,0,0,0,3267,6444,3273,211,206,137,20,10,10,0,0,0*68 NOTE Attitude-related values (including roll, yaw and pitch) are invalid in GNSS-only mode. 3.1.2. PQGNSS This message reports GNSS-only fix information. Type: Output Synopsis: $PQGNSS,,,,,,,,,,,,,,,,,,,,, ,,,,,,,,,,* L26-DR(UDR&ADRC)_DR_Application_Note 16 / 24 Parameter: Field Format Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric GNSS Module Series Unit Description - Message Subtype ID, fixed as 6. Year UTC year. Month UTC month. Day UTC day. Hour UTC hour. Minute UTC minutes. Second UTC seconds. Week GPS week number, including rollover. Millisecond Time of week. - Number of satellites in use. Degree Latitude, scaled by 10^7. Degree Longitude, scaled by 10^7. cm Ellipsoidal height. cm/s Speed over ground. Degree Heading angle, scaled by 100. cm Horizontal accuracy. cm/s Northward velocity. cm/s Eastward velocity. cm/s Downward velocity. - - - - cm Uncertainty of position in northward direction. cm Uncertainty of position in eastward direction. cm Uncertainty of position in downward direction. cm/s Northward velocity uncertainty. cm/s Eastward velocity uncertainty. L26-DR(UDR&ADRC)_DR_Application_Note 17 / 24 GNSS Module Series Numeric Numeric Numeric Numeric Numeric cm/s Second cm - Downward velocity uncertainty. Leap seconds. Height above mean sea level. - Example: $PQGNSS,6,2022,4,15,11,20,34,2205,472852000,11,318221499,1171158627,3673,5,0,2421,1,5,-1,0,0, 1580,1834,1632,272,232,285,18,0,3704,12*34 3.1.3. PQSNR,21 This message reports sensor data. Type: Output Synopsis: $PQSNR,,{,,,,,,,< Z_ACC>,,}* Parameter: Field Format Unit Description Numeric - 21 = Mixed DR sensor data. Numeric - Number of data set(s). Start of repeat block. Repeat times: . Numeric ms Milliseconds since power on. 32-bit unsigned integer. Numeric Deg/s X-axis angular velocity of gyroscope, scaled by 1000. Numeric Deg/s Y-axis angular velocity of gyroscope, scaled by 1000. Numeric Deg/s Z-axis angular velocity of gyroscope, scaled by 1000. Numeric m/s^2 X-axis acceleration of accelerometer, scaled by 1000. Numeric m/s^2 Y-axis acceleration of accelerometer, scaled by 1000. L26-DR(UDR&ADRC)_DR_Application_Note 18 / 24 GNSS Module Series Numeric Numeric Numeric End of repeat block. m/s^2 m/s - Z-axis acceleration of accelerometer, scaled by 1000. Vehicle speed, scaled by 100. Vehicle direction. 0 = Forward 1 = Reverse 8 = Unknow Example: $PQSNR,21,10,9800,449,-447,-178,566,1937,9589,0,8,9900,465,-412,-110,562,1937,9593,0,8,10000,5 21,-420,-128,567,1946,9596,0,8,10100,448,-441,-94,565,1937,9591,0,8,10200,454,-437,-118,565,1942, 9599,0,8,10300,487,-403,-129,559,1946,9603,0,8,10400,472,-461,-110,563,1940,9590,0,8,10500,443,-4 31,-121,561,1940,9587,0,8,10600,473,-416,-122,563,1943,9600,0,8,10700,474,-441,-86,564,1947,9597 ,0,8*4B 3.1.4. PQSNR,23 This message reports raw sensor data. The message only exists in NHz build. The entire block is comprised of multiple messages. Type: Output Synopsis: $PQSNR,,,,,,,,* Parameter: Field Format Numeric Numeric Numeric Numeric Numeric Numeric Unit ms Deg/s Deg/s Deg/s m/s2 Description 23 = Raw sensor data Milliseconds since power on. 32-bit unsigned integer. X-axis angular velocity of gyroscope, scaled by 1000. Y-axis angular velocity of gyroscope, scaled by 1000. Z-axis angular velocity of gyroscope, scaled by 1000. X-axis acceleration of accelerometer, scaled by 1000. L26-DR(UDR&ADRC)_DR_Application_Note 19 / 24 GNSS Module Series Numeric Numeric m/s2 m/s2 Y-axis acceleration of accelerometer, scaled by 1000. Z-axis acceleration of accelerometer, scaled by 1000. Example: $PQSNR,23,3100,399,-519,-454,466,-511,9906*5C 3.1.5. PQEND This message indicates the end of an epoch. Type: Output Synopsis: $PQEND,,* Parameter: Field Format Numeric Numeric Unit Description - Fixed as 255. - Fixed as 255. Example: $PQEND,255,255*4E 3.2. PSTM Messages 3.2.1. PSTMDRSENMSG This message outputs the IMU raw data. Type: Output Synopsis: $PSTMDRSENMSG,[,]* L26-DR(UDR&ADRC)_DR_Application_Note 20 / 24 Parameter: Field Format Unit Numeric - - - GNSS Module Series Description Message ID. 24 = IMU temperature. 30 = IMU accelerometer. 31 = IMU gyroscope. This field varies with the message type. See Chapter 3.2.1.1, 3.2.1.2, and 3.2.1.3 for details. 3.2.1.1.IMU Temperature Message (MsgID = 24) This message outputs the IMU temperature. Type: Output Synopsis: $PSTMDRSENMSG,24,,,* Parameter: Field Format Numeric Numeric Numeric Unit Description - CPU ticks count since power on. IMU temperature. - The real temperature in Celsius degree: Celsius degree = / 256 + 25.0 Validity. - 0 = Temperature is not valid. 1 = Temperature is valid. Example: $PSTMDRSENMSG,24,3248649605,-486,1*28 3.2.1.2.IMU Accelerometer Message (MsgID = 30) This message outputs the IMU accelerometer. FS = ±2g Sensitivity = 0.061mg / LSB L26-DR(UDR&ADRC)_DR_Application_Note 21 / 24 GNSS Module Series Type: Output Synopsis: $PSTMDRSENMSG,30,,,,* Parameter: Field Format Numeric Numeric Numeric Numeric Unit Description - CPU tick count since power on. Raw signed 16-bit integer X-axis acceleration data - in sensor frame. Raw signed 16-bit integer Y-axis acceleration data in sensor frame. Raw signed 16-bit integer Z-axis acceleration data in sensor frame. Example: $PSTMDRSENMSG,30,3248512115,299,-35,16514*02 $PSTMDRSENMSG,30,3248570594,302,-37,16524*09 3.2.1.3.IMU Gyroscope Message (MsgID = 31) This message outputs the IMU gyroscope. FS = ±125 dps Sensitivity = 4.375 mdps / LSB Type: Output Synopsis: $PSTMDRSENMSG,31,,,,* Parameter: Field Format Numeric Numeric Unit Description - CPU ticks count since power on. Raw signed 16-bit integer X-axis angular rate data - in sensor frame. L26-DR(UDR&ADRC)_DR_Application_Note 22 / 24 GNSS Module Series Numeric - Numeric - Raw signed 16-bit integer Y-axis angular rate data in sensor frame. Raw signed 16-bit integer Z-axis angular rate data in sensor frame. Example: $PSTMDRSENMSG,31,5855224,62,-119,-49*2A $PSTMDRSENMSG,31,5913732,68,-117,-43*25 3.2.2. PSTMIMUSELFTESTCMD The command executes the self-test procedure in IMU. Type: Command Synopsis: $PSTMIMUSELFTESTCMD,* Parameter: Field Format Numeric Unit Description IMU type. - 0 = Accelerometer 1 = Gyroscope Result: ⚫ If successful, the module returns: $PSTMIMUSELFTESTCMDOK* ⚫ In failed, the module returns: $PSTMIMUSELFTESTCMDKO* ⚫ If the self-test command is not supported by the mounted IMU or not supported by the FW (sensor layer not present in FW), the module returns: $PSTMIMUSELFTESTCMDERROR* Example: $PSTMIMUSELFTESTCMD,1*16 $PSTMIMUSELFTESTCMDOK*0F L26-DR(UDR&ADRC)_DR_Application_Note 23 / 24 GNSS Module Series 4 Appendix References Table 2: Terms and Abbreviations Abbreviation DR UDR FW GNSS IMU LSB NMEA UART UTC Description Dead Reckoning Untethered Dead Reckoning Firmware Global Navigation Satellite System Inertial Measurement Unit Least Significant Bit NMEA (National Marine Electronics Association) 0183 Interface Standard Universal Asynchronous Receiver/Transmitter Coordinated Universal Time L26-DR(UDR&ADRC)_DR_Application_Note 24 / 24
546.71 KB
BG77xA-GL&BG95xA-GL QCFG AT Commands Manual LPWA Module Series Version: 1.0 Date: 2022-05-31 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. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 1 / 49 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. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 2 / 49 LPWA Module Series About the Document Revision History Version 1.0 Date 2021-01-29 2022-05-31 Author Igor STANCIC/ Aleksandar PAUNOVIC/ Mladen VUKOVIC Igor STANCIC/ Aleksandar PAUNOVIC/ Mladen VUKOVIC Description Creation of the document First official release BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 3 / 49 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 6 1 Introduction ......................................................................................................................................... 7 1.1. Definitions .................................................................................................................................. 7 1.2. AT Command Syntax ................................................................................................................. 7 1.3. AT Command Responses .......................................................................................................... 8 1.4. Declaration of AT Command Examples ..................................................................................... 9 2 Description of AT+QCFG Commands............................................................................................. 10 2.1. AT+QCFG Extended Configuration Settings ........................................................................... 10 2.1.1. Network-Related AT Commands....................................................................................11 2.1.1.1. AT+QCFG='nwscanmode' Configure RAT(s) to be Searched for...................11 2.1.1.2. AT+QCFG='servicedomain' Configure Service Domain ................................ 12 2.1.1.3. AT+QCFG='nwscanseq' Configure RATs Searching Sequence .................... 13 2.1.1.4. AT+QCFG='band' Configure Frequency Band............................................... 14 2.1.1.5. AT+QCFG='iotopmode' Configure Network Category to be Searched Under LTE RAT ............................................................................................................................ 16 2.1.1.6. AT+QCFG='celevel' Query NB-IoT Coverage Enhancement Level .............. 17 2.1.1.7. AT+QCFG='psm/enter' Trigger the Module into PSM Immediately ............... 18 2.1.1.8. AT+QCFG='psm/urc' Enable/Disable PSM Entering Indication..................... 19 2.1.1.9. AT+QCFG='lapiconf' Set LAPI Value (Low Access Priority Indicator) ........... 20 2.1.2. Platform-Related AT Commands .................................................................................. 21 2.1.2.1. AT+QCFG='urc/ri/ring' Configure MAIN_RI Behavior in Case of RING URC 21 2.1.2.2. AT+QCFG='urc/ri/smsincoming' Configure MAIN_RI Behavior in Case of Incoming SMS URCs ........................................................................................................... 22 2.1.2.3. AT+QCFG='urc/ri/other' Configure MAIN_RI Behavior in Case of Other URCs23 2.1.2.4. AT+QCFG='risignaltype' Configure MAIN_RI Signal Output Carrier ............. 24 2.1.2.5. AT+QCFG='urc/delay' Configure URC Output Time ...................................... 25 2.1.2.6. AT+QCFG='gpio' Configure GPIO Status ...................................................... 26 2.1.2.7. AT+QCFG='airplanecontrol' Enable/Disable Airplane Mode Control via W_DISABLE# ....................................................................................................................... 28 2.1.2.8. AT+QCFG='emux/urcport' Configure URC Output Port in EMUX Mode ....... 30 2.1.2.9. AT+QCFG='apready'* Configure AP_READY* Behavior............................... 30 2.1.2.10. AT+QCFG='apn/display' Enable/Disable Showing APN ................................ 32 2.1.2.11. AT+QCFG='lwm2m' Enable/Disable LwM2M ................................................ 33 2.1.2.12. AT+QCFG='nwoper' Configure Network Operator Mode of the Modem ....... 33 2.1.2.13. AT+QCFG='ps_dev_mob_type' Configure Device Mobility Type Flag .......... 34 2.1.2.14. AT+QCFG='netupd' Enable/Disable Network Override for Specified LTE Parameters ........................................................................................................................... 35 2.1.2.15. AT+QCFG='edrxusimact' Activate/Deactivate (U)SIM in eDRX Mode .......... 37 BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 4 / 49 LPWA Module Series 2.1.2.16. AT+QCFG='setcfg' Set Configuration Field to the NV memory ..................... 38 2.1.2.17. AT+QCFG='setsyscfg' Set Value(s) to System Configuration Files............... 39 2.1.2.18. AT+QCFG='uartmapping' Show Port and Function Mapping ........................ 40 2.1.2.19. AT+QCFG='uartmapping/profile' Read/Write Port Profile Mapping Configuration ........................................................................................................................ 41 2.1.2.20. AT+QCFG='usb' Activate/Deactivate USB Interface ..................................... 42 2.1.2.21. AT+QCFG='usb/urcport' Configure URC Output Port in USB Interface Mode43 2.1.2.22. AT+QCFG='lte/bandprior' Configure Band Scan Priority under LTE ............. 44 2.1.2.23. AT+QCFG='stored/cell' Delete Stored Cell Acquisition DB ........................... 45 3 Summary of +CME ERROR Codes.................................................................................................. 46 4 Appendix References ....................................................................................................................... 48 BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 5 / 49 LPWA Module Series Table Index Table 1: Types of AT Commands ................................................................................................................. 8 Table 2: Summary of +CME ERROR Codes ............................................................................................. 46 Table 3: Related Document........................................................................................................................ 48 Table 4: Terms and Abbreviations .............................................................................................................. 48 BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 6 / 49 LPWA Module Series 1 Introduction This document describes the AT+QCFG commands supported on Quectel BG770A-GL, BG772A-GL, BG950A-GL, BG951A-GL, BG952A-GL and BG955A-GL modules. 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. 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. AT+QCFG commands implemented by the module are in 'Extended' syntax, as illustrated below. ⚫ Extended Extended commands can be executed in several modes, as shown in the following table: BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 7 / 49 LPWA Module Series 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. Multiple commands can be placed on a single line using a semi-colon (;) between commands. In such cases, only the first command should have AT prefix. Commands can be in upper or lower case. Spaces should be ignored when you enter AT commands, except in the following cases: ⚫ Within quoted strings, where spaces are preserved; ⚫ Within an unquoted string or a numeric parameter; ⚫ Within an IP address; ⚫ Within the AT command name up to and including a =, ? or =?. On input, at least a carriage return is required. A newline character is ignored so it is permissible to use carriage return/line feed pairs on the input. If no command is entered after the AT token, OK will be returned. If an invalid command is entered, ERROR will be returned. Optional parameters, unless explicitly stated, need to be provided up to the last entered parameter. 1.3. AT Command Responses When the AT command processor has finished processing a line, it will output OK, ERROR or +CME ERROR: to indicate that it is ready to accept a new command. Solicited information responses are sent before the final OK, ERROR or +CME ERROR: . Responses will be in the format of: +CMD1: OK BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 8 / 49 LPWA Module Series 1.4. 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. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 9 / 49 LPWA Module Series 2 Description of AT+QCFG Commands 2.1. AT+QCFG Extended Configuration Settings The following Test Command shows the supported extended configuration settings of the module. AT+QCFG Extended Configuration Settings Test Command AT+QCFG=? Response +QCFG: 'nwscanmode',(list of supported s),(list of supported s) +QCFG: 'servicedomain',(list of supported s) +QCFG: 'nwscanseq',(range of supported s),(list of supported s) +QCFG: 'band',(range of supported s),(range of supported s),(list of supported s) +QCFG: 'iotopmode',(range of supported s),(list of supported s) +QCFG: 'celevel',(range of supported s) +QCFG: 'urc/ri/ring',(list of supported s),(range of supported s),(range of supported s),(range of supported s),(list of supported s),(range of supported s) +QCFG: 'urc/ri/smsincoming',(list of supported s),(range of supported s),(range of supported s) +QCFG: 'urc/ri/other',(list of supported s),(range of supported s),(range of supported s) +QCFG: 'risignaltype',(list of supported s) +QCFG: 'urc/delay',(list of supported s) +QCFG: 'ledmode',(list of supported s) +QCFG: 'gpio',(range of supported s),(list of supported s),(list of supported s),(range of supported s),(list of supported s),(list of supported s),(list of supported s) +QCFG: 'airplanecontrol',(list of supported BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 10 / 49 Maximum Response Time LPWA Module Series s) +QCFG: 'emux/urcport',(range of supported s) +QCFG: 'apready',(list of supported s),(list of supported s),(range of supported s) +QCFG: 'psm/enter',(list of supported s) +QCFG: 'psm/urc',(list of supported s) +QCFG: 'apn/display',(list of supported s) +QCFG: 'lwm2m',(list of supported s) +QCFG: 'nwoper',(list of supported s) +QCFG: 'ps_dev_mob_type',(list of supported s) +QCFG: 'netupd',(list of supported s) ,(list of supported s) +QCFG: 'edrxusimact',(range of supported s) +QCFG: 'setcfg',(list of supported s),(list of supported s) +QCFG: 'setsyscfg',(list of supported s),(range of supported s),(list of supported s),(range of supported s),(range of supported s),(range of supported s) +QCFG: 'uartmapping' +QCFG: 'usb',(list of supported s) +QCFG: 'usb/urcport',(range of supported s) OK 300 ms 2.1.1. Network-Related AT Commands 2.1.1.1. AT+QCFG='nwscanmode' Configure RAT(s) to be Searched for The command queries and configures the RAT(s) to be searched for. AT+QCFG='nwscanmode' Configure RAT(s) to be Searched for Write Command AT+QCFG='nwscanmo'[,[,]] Response If the optional parameter is omitted, query the current settings: +QCFG: 'nwscanmode', OK If any of the optional parameter is specified, configure the RAT(s) to be searched for: OK BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 11 / 49 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 are 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 rebooting 1 Take effect immediately Error code. See Chapter 3 for more information. NOTE This command is valid only on BG955A-GL module. 2.1.1.2. AT+QCFG='servicedomain' Configure Service Domain The command queries and configures the service domain to be registered. AT+QCFG='servicedomain' Configure Service Domain Write Command Response AT+QCFG='servicedomain'[,] +QCFG: 'servicedomain', OK If the optional parameter is specified, configure the service domain to be registered: OK If there is an error related to ME functionality: BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 12 / 49 Maximum Response Time Characteristics LPWA Module Series +CME ERROR: If there is any other error: ERROR 300 ms The configurations are saved automatically. Parameter Integer type. Service domain. 1 PS only Integer type. Error code. See Chapter 3 for more information. 2.1.1.3. AT+QCFG='nwscanseq' Configure RATs Searching Sequence The command queries and configures RATs searching sequence. AT+QCFG='nwscanseq' Configure RATs Searching Sequence Write Command Response AT+QCFG='nwscanseq'[,[ If optional parameters are omitted, query the current settings: ,effect]] +QCFG: 'nwscanseq', OK If any of the optional parameters is specified, configure RATs 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 takes effect. The configurations are saved automatically. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 13 / 49 LPWA Module Series Parameter Integer type. RATs searching sequence. (e.g.: 020301 stands for eMTC → NB-IoT → GSM) 00 Automatic (eMTC → NB-IoT) 01 GSM 02 eMTC 03 NB-IoT Integer type. Determines when the command takes effect. 0 Take effect after the module reboots 1 Take effect immediately Integer type. Error code. See Chapter 3 for more information. 2.1.1.4. AT+QCFG='band' Configure Frequency Band The command queries and configures the frequency bands to be searched. AT+QCFG='band' Configure Frequency Band Write Command AT+QCFG='band'[,, ,[ ,]] Response If optional parameters are omitted, query the current settings: +QCFG: 'band',,, OK If any of the optional parameters is specified, configure the frequency bands to be searched. OK If there is an error related to ME functionality: +CME ERROR: Maximum Response Time Characteristics If there is any other error: ERROR 4500 ms determines when the command takes effect. The configurations are saved automatically. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 14 / 49 LPWA Module Series 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 = 0x01(LTE B1) + 0x04(LTE B3) + 0x10(LTE B5)). If it is set to 0, the eMTC frequency band will not be changed. By default, all bands are set. 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 0x20000000000000000 (BAND_PREF_LTE_BAND66) LTE B66 A hexadecimal value that specifies the NB-IoT frequency band (e.g.: 0x15 = 0x01(LTE B1) + 0x04(LTE B3) + 0x10(LTE B5)). If it is set to 0, the NB-IoT frequency band will not be changed. By default, all bands are set. 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 BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 15 / 49 LPWA Module Series 0x10000 (BAND_PREF_LTE_BAND17) LTE B17 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 0x20000000000000000 (BAND_PREF_LTE_BAND66) LTE B66 Integer type. Determines when the command takes effect. 0 Take effect after the module reboots 1 Take effect immediately Integer type. Error code. See Chapter 3 for more information. NOTE is valid only on BG955A-GL module. 2.1.1.5. AT+QCFG='iotopmode' Configure Network Category to be Searched Under LTE RAT The command queries and configures the network category to be searched under LTE RAT. AT+QCFG='iotopmode' Configure Network Category to be Searched Under LTE RAT Write Command Response AT+QCFG='iotopmode'[,[,]] settings: +QCFG: 'iotopmode', OK If any of the optional parameters is specified, configure the network category to be searched under LTE RAT: OK Maximum Response Time Characteristics If there is an error related to ME functionality: +CME ERROR: If there is any other error: ERROR 4500 ms determines when the command takes effect. The configurations are saved automatically. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 16 / 49 LPWA Module Series Parameter Integer type. Network category to be searched under LTE RAT. 0 eMTC 1 NB-IoT 2 eMTC and NB-IoT Integer type. Determines when the command takes effect. 0 Take effect after the module reboots 1 Take effect immediately Integer type. Error code. See Chapter 3 for more information. 2.1.1.6. AT+QCFG='celevel' Query NB-IoT Coverage Enhancement Level The command queries the NB-IoT coverage enhancement (CE) level. AT+QCFG='celevel' Query NB-IoT Coverage Enhancement Level Write Command AT+QCFG='celevel' Response: +QCFG: 'celevel', 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 / Parameter Integer type. NB-IoT coverage enhancement level. 0 CE level 0 1 CE level 1 2 CE level 2 Integer type. Error code. See Chapter 3 for more information. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 17 / 49 LPWA Module Series 2.1.1.7. AT+QCFG='psm/enter' Trigger the Module into PSM Immediately The command queries the current settings or sets whether to trigger the module into the Power Saving Mode (PSM) immediately after the RRC connection release is received. When =1, the module skips the active timer (T3324) and enters PSM immediately after the RRC connection release is received. AT+QCFG='psm/enter' Trigger the Module into PSM Immediately Write Command AT+QCFG='psm/enter'[,] Response If the optional parameter is omitted, query the current settings: +QCFG: 'psm/enter', OK If the optional parameter is specified, set whether to trigger the module into PSM immediately after the RRC connection release is received: 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 The command takes effect immediately. The configuration is not saved. Parameter Integer type. Sets whether to trigger the module into PSM. 0 Enter PSM after T3324 expires 1 Enter PSM immediately after the RRC connection release is received. Integer type. Error code. See Chapter 3 for more information. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 18 / 49 LPWA Module Series 2.1.1.8. AT+QCFG='psm/urc' Enable/Disable PSM Entering Indication The command queries the current settings and enables/disables the output of URC +QPSMTIMER: ,, which indicates the TAU duration and active time duration of the module’s PSM. When the PSM function is enabled and the RRC connection release is received, the active timer (T3324) is started, and the indication URC is reported. AT+QCFG='psm/urc' Enable/Disable PSM Entering Indication Write Command AT+QCFG='psm/urc'[,] Response If the optional parameter is omitted, query the current settings: +QCFG: 'psm/urc', OK If the optional parameter is specified, set whether to enable PSM entering indication. 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 The command takes effect immediately. The configuration is saved automatically. Parameter Integer type. Enable/disable the output of URC +QPSMTIMER: , . If enabled, the URC will be reported when the RRC connection release is received. 0 Disable 1 Enable Integer type. Error code. See Chapter 3 for more information. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 19 / 49 LPWA Module Series NOTE When AT+QCFG='psm/urc',1 and AT+QCFG='psm/enter',1 are executed at the same time, it is possible that the URC +QPSMTIMER cannot be outputted because the module enters PSM right away. 2.1.1.9. AT+QCFG='lapiconf' Set LAPI Value (Low Access Priority Indicator) The command queries the current settings or configures the Low Access Priority Indicator. AT+QCFG='lapiconf' Set LAPI Value (Low Access Priority Indicator) Write Command AT+QCFG='lapiconf'[,][,] Response If the optional parameter is omitted, query the current settings: +QCFG: 'lapiconf',[,] OK If the optional parameter is specified, configure the URC output port in USB Interface mode: 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 The configuration is saved automatically. Parameter Integer type. Whether to enable low access priority indication feature 0 Disable. Forced to disable 1 Enable. Forced to enable 2 Auto. Determined by EFS file Integer type. 0 Disable 1 Enable Integer type. Error code. See Chapter 3 for more information. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 20 / 49 LPWA Module Series 2.1.2. Platform-Related AT Commands Among the following AT commands, AT+QCFG='urc/ri/ring', AT+QCFG='urc/ri/smsincoming' and AT+QCFG='urc/ri/other' commands control the behavior of the MAIN_RI pin when a URC is reported. The MAIN_RI pin is active low. 2.1.2.1. AT+QCFG='urc/ri/ring' Configure MAIN_RI Behavior in Case of RING URC The command queries and configures the behavior of MAIN_RI pin when RING URC is reported to indicate an incoming call. The sum of and and determines the interval of RING indications when a call is coming. AT+QCFG='urc/ri/ring' Configure MAIN_RI Behavior in Case of RING URC Write Command AT+QCFG='urc/ri/ring'[,[,[,[,[,[,]]]]]] Response If optional parameters are omitted, query the current settings: +QCFG: 'urc/ri/ring',,,,,, OK If any of the optional parameters is specified, configure the behavior of MAIN_RI pin when RING URC is reported. 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 The command takes effect immediately. The configurations are saved automatically. Parameter String type. MAIN_RI behavior when RING URCs are reported. 'off' No change. MAIN_RI pin stays inactive (high). 'pulse' Pulse. Pulse width is determined by . BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 21 / 49 LPWA Module Series 'always' Change to active. MAIN_RI behavior can be restored to inactive with AT+QRIR (see document [1] for more information). 'auto' When RING URC is reported to indicate an incoming call, MAIN_RI pin changes to active and remains active. Answering or hanging up the incoming call changes MAIN_RI pin state to inactive. 'wave' When RING URC is reported to indicate an incoming call, MAIN_RI pin outputs a square wave. Both and are used to set the square wave. Answering or hanging up the incoming call changes the MAIN_RI pin to inactive. Integer type. Pulse width. Range: 1–2000. Default: 120. Unit: ms. Parameter is valid only when ='pulse'. Integer type. Active duration of the square wave. Range: 1–10000. Default: 1000. Unit: ms. Parameter is valid only when ='wave'. Integer type. Inactive duration of the square wave. Range: 1–10000. Default: 5000. Unit: ms. Parameter is valid only when ='wave'. String type. Set whether the MAIN_RI pin behavior could be disturbed. Parameter is valid only when ='auto' or 'wave'. For example, when ='wave', if the square wave will not be interrupted by other URCs (including SMS-related URCs), then should be set to 'on'. 'off' MAIN_RI pin behavior can be changed by other URCs when an incoming call is ringing. 'on' MAIN_RI behavior cannot be changed by other URCs when an incoming call is ringing. Integer type. Pulse count. Parameter is valid only when ='pulse'. Range: 1–5. Default: 1. Interval between two pulses is equal to . Integer type. Error code. See Chapter 3 for more information. 2.1.2.2. AT+QCFG='urc/ri/smsincoming' Configure MAIN_RI Behavior in Case of Incoming SMS URCs The command queries and configures the behavior of the MAIN_RI pin when there are incoming SMS URCs. Incoming SMS URCs include +CMTI, +CMT, +CDS, and +CBM (see document [1] for details). AT+QCFG='urc/ri/smsincoming' Configure MAIN_RI Behavior in Case of Incoming SMS URCs Write Command Response AT+QCFG='urc/ri/smsincoming'[,[,[,]]] +QCFG: 'urc/ri/smsincoming',,, OK If any of the optional parameters is specified, configure the MAIN_RI behavior when there are incoming SMS URCs: OK If there is an error related to ME functionality: +CME ERROR: If there is any other error: ERROR 300 ms The command takes effect immediately. The configurations are saved automatically. Parameter String type. MAIN_RI behavior when there are incoming SMS URCs. 'off' No change. MAIN_RI pin stays inactive (high). 'pulse' Pulse. Pulse width is determined by . 'always' Change to active. MAIN_RI behavior can be restored to inactive with AT+QRIR (see document [1] for more information). Integer type. Pulse width. Range: 1–2000. Default: 120. Unit: ms. Parameter is valid only when ='pulse'. Integer type. Pulse count. Parameter is valid only when ='pulse'. Range: 1–5. Default: 1. Interval between two pulses is equal to . Integer type. Error code. See Chapter 3 for more information. 2.1.2.3. AT+QCFG='urc/ri/other' Configure MAIN_RI Behavior in Case of Other URCs The command queries and configures the behavior of the MAIN_RI pin when there are other URCs. AT+QCFG='urc/ri/other' Configure MAIN_RI Behavior in Case of Other URCs Write Command AT+QCFG='urc/ri/other'[,[,[,]]] Response If optional parameters are omitted, query the current settings: +QCFG: 'urc/ri/other',,, BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 23 / 49 LPWA Module Series Maximum Response Time Characteristics OK If any of the optional parameters is specified, configure the MAIN_RI behavior when there are other URCs. OK If there is an error related to ME functionality: +CME ERROR: If there is any other error: ERROR 300 ms The command takes effect immediately. The configurations are saved automatically. Parameter String type. MAIN_RI behavior when there are other URCs. 'off' No change. MAIN_RI pin stays inactive (high). 'pulse' Pulse. Pulse width determined by . Integer type. Pulse width. Range: 1–2000. Default: 120. Unit: ms. Parameter is valid only when = 'pulse'. Integer type. Pulse count. Parameter is valid only when ='pulse'. Range: 1–5. Default: 1. Interval between two pulses is equal to . Integer type. Error code. See Chapter 3 for more information. 2.1.2.4. AT+QCFG='risignaltype' Configure MAIN_RI Signal Output Carrier The command queries and configures the output carrier of the MAIN_RI signal. AT+QCFG='risignaltype' Configure Main_RI Signal Output Carrier Write Command AT+QCFG='risignaltype'[,] Response If the optional parameter is omitted, query the current settings: +QCFG: 'risignaltype', OK If the optional parameter is specified, configure the output carrier of the MAIN_RI signal. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 24 / 49 LPWA Module Series Maximum Response Time Characteristics OK If there is an error related to the ME functionality: +CME ERROR: If there is any other error: ERROR 300 ms The command takes effect immediately. The configuration is saved automatically. Parameter String type. MAIN_RI signal output carrier. 'respective' Causes MAIN_RI behavior on the port where a URC is presented. For example, if a URC is presented on the UART port, it is a physical ring indication signal. AT+QURCCFG='urcport' can get the port on which a URC is presented (see document [1] for more information). 'physical' No matter on which port the URC is presented, it only causes the behavior of physical ring indication signal. Integer type. Error code. See Chapter 3 for more information. 2.1.2.5. AT+QCFG='urc/delay' Configure URC Output Time The command queries and configures URC output time. AT+QCFG='urc/delay' Configure URC Output Time Write Command AT+QCFG='urc/delay'[,] Response If the optional parameter is omitted, query the current settings: +QCFG: 'urc/delay', OK If the optional parameter is specified, configure URC output time: OK If there is an error related to ME functionality: +CME ERROR: BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 25 / 49 LPWA Module Series Maximum Response Time Characteristics If there is any other error: ERROR 300 ms The command takes effect immediately. The configuration is saved automatically. Parameter Integer type. URC output time. 0 Output URC when ring indication pulse starts. 1 Output URC when ring indication pulse ends (effective only when ='pulse'. See AT+QCFG='urc/ri/ring', AT+QCFG='urc/ri/smsincoming' and AT+QCFG='urc/ri/other' for more information). Integer type. Error code. See Chapter 3 for more information. 2.1.2.6. AT+QCFG='gpio' Configure GPIO Status The command queries and configures the GPIO status. AT+QCFG='gpio' Configure GPIO Status Write Command Query the formats of the command AT+QCFG='gpio' Response +QCFG: 'gpio',,[,[,,]/[][,]] Write Command AT+QCFG='gpio',,[,[,,]/[][,]] OK Response If =2, then all optional parameters should be omitted. +QCFG: 'gpio', OK If =1, then should be omitted. OK If =3, then , and should be omitted. OK Maximum Response Time If there is an error related to ME functionality: +CME ERROR: 300 ms BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 26 / 49 LPWA Module Series Characteristics The command takes effect immediately. determines whether the configuration will be saved. When =1, the configurations are saved and remain valid after the module reboots. Parameter Integer type. Command mode. 1 Initialize GPIO status 2 Query GPIO status 3 Configure GPIO status Integer type. GPIO pin number. BG770A module supports the following pin numbers: Pin No. Pin Name 1 GPIO1 8 GPIO2 9 GPIO3 33 GPIO4 40 GPIO5 57 GPIO6 63 GPIO7 BG950A-GL, BG951A-GL and BG955A-GL modules support the following pin numbers: Pin No. Pin Name 25 GPIO1 26 GPIO2 64 GPIO3 65 GPIO4 66 GPIO5 85 GPIO6 86 GPIO7 87 GPIO8 88 GPIO9 Integer type. GPIO pin direction. 0 Input 1 Output Integer type. GPIO pin pull type. 0 No pull 1 Pull the GPIO down 2 Keep the GPIO as it is 3 Pull the GPIO up Integer type. GPIO pin drive strength. 0 2 mA 1 4 mA 3 8 mA BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 27 / 49 LPWA Module Series 5 12 mA Integer type. Value read from or written to a GPIO. 0 Low level 1 High level Integer type. Determines whether to save the configurations. 0 Do not save 1 Save Integer type. Error code. See Chapter 3 for more information. NOTE 1. Command AT+QCFG='gpio' cannot be used on BG772A-GL and BG952A-GL modules. 2. is valid only when is 1 or 3. 3. For the value of , see corresponding hardware design for details. 2.1.2.7. AT+QCFG='airplanecontrol' Enable/Disable Airplane Mode Control via W_DISABLE# The command enables/disables airplane mode control via the W_DISABLE# pin and queries the current settings. If the function is enabled, the module enters the airplane mode when the pin is pulled down, or the normal mode when the pin is pulled up. In addition, the command outputs a related URC before the module enters or exits airplane mode. AT+QCFG='airplanecontrol' W_DISABLE# Enable/Disable Airplane Mode Control via Write Command Response AT+QCFG='airplanecontrol'[,] settings: +QCFG: 'airplanecontrol',, OK Maximum Response Time Characteristics If the optional parameter is specified, configure whether to enable airplane mode control via W_DISABLE# pin: OK Or ERROR 300 ms The command takes effect immediately. The configuration is saved automatically. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 28 / 49 LPWA Module Series Parameter Integer type. Enable/disable airplane mode control via W_DISABLE# pin. 0 Disable 1 Enable Integer type. Current status. 0 In normal mode 1 ln airplane mode NOTE The status of the W_DISABLE# pin may affect the validity of AT+CFUN (see document [1] for more information). When the airplane mode control via W_DISABLE# is enabled and the pin is pulled down, the module enters the airplane mode regardless of the status of AT+CFUN. In addition, the module functionality level cannot be switched with AT+CFUN. Example AT+QCFG='airplanecontrol',1 OK //Pull down W_DISABLE# pin +QIND: 'airplanestatus',1 //Enable airplane mode control via W_DISABLE#. //URC indicating that the module enters airplane mode. AT+QCFG='airplanecontrol' //Query whether airplane mode control via W_DISABLE# is enabled and the current status of the module. +QCFG: 'airplanecontrol',1,1 //Airplane mode control via W_DISABLE# is enabled and the module is currently in airplane mode. OK //Pull up W_DISABLE# pin +QIND: 'airplanestatus',0 //URC indicating that the module exits airplane mode. AT+QCFG='airplanecontrol' +QCFG: 'airplanecontrol',1,0 //Query whether airplane mode control via W_DISABLE# is enabled and the current status of the module. //Airplane mode control via W_DISABLE# is enabled and the module is currently in normal mode. OK BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 29 / 49 LPWA Module Series 2.1.2.8. AT+QCFG='emux/urcport' Configure URC Output Port in EMUX Mode The command queries and configures the URC output port in EMUX mode. AT+QCFG='emux/urcport' Configure URC Output Port in EMUX Mode Write Command AT+QCFG='emux/urcport'[,] Response If the optional parameter is omitted, query the current settings: +QCFG: 'emux/urcport', OK If the optional parameter is specified, configure the URC output port in EMUX mode: 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 The command takes effect immediately. The configuration is saved automatically. Parameter Integer type. URC output port in EMUX mode. 0 All ports 1 Virtual port 1 2 Virtual port 2 3 Virtual port 3 Integer type. Error code. See Chapter 3 for more information. 2.1.2.9. AT+QCFG='apready'* Configure AP_READY* Behavior The command queries and configures the behavior of the AP_READY pin. An external MCU can change AP_READY pin level as needed. When there is a URC to be reported, if the AP_READY pin level is invalid, the URC is buffered first, and the AP_READY pin level will be detected periodically within the configured detection period. The URC will BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 30 / 49 LPWA Module Series be output when the AP_READY pin level becomes valid. The pulse signal generated on the MAIN_RI pin can still be output according to the configured mode, and will not be buffered. AT+QCFG='apready'* Configure AP_READY Behavior Write Command AT+QCFG='apready'[,[,[,]]] Response If the optional parameters are omitted, query the current settings: +QCFG: 'apready',,, OK If any of the optional parameters is specified, configure the AP_READY behavior: 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 The command takes effect immediately. The configurations are saved automatically. Parameter Integer type. Enable/disable the AP_READY pin for AP sleep state detection. 0 Disable 1 Enable Integer type. Valid level of AP_READY pin. Parameter is valid only when the AP_READY detection function is enabled. 0 Low level 1 High level Integer type. Detection interval. Range: 100–3000. Default: 500. Unit: ms. Parameter is valid only when the AP_READY detection function is enabled. Integer type. Error code. See Chapter 3 for more information. NOTE 1. Up to 15 URCs can be buffered. When the number of URCs exceeds 15, the oldest one in the buffer will be cleared to store a new URC. 2. The RING URC is buffered only once for each call process. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 31 / 49 LPWA Module Series 2.1.2.10. AT+QCFG='apn/display' Enable/Disable Showing APN The command enables/disables showing of allocated point name (APN) and queries the current settings. When =1, the APN is shown in the response of AT+CGDCONT? (see document [1] for more information). AT+QCFG='apn/display' Enable/Disable Showing APN Write Command AT+QCFG='apn/display'[,] Response If the optional parameter is omitted, query the current settings: +QCFG: 'apn/display', OK If the optional parameter is specified, set whether to enable showing APN. 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 The command takes effect immediately. The configuration is not saved. Parameter Integer type. Enable/disable showing APN. 0 Disable 1 Enable Integer type. Error code. Refer to Chapter 3 for more information. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 32 / 49 LPWA Module Series 2.1.2.11. AT+QCFG='lwm2m' Enable/Disable LwM2M The command enables/disables LwM2M and queries the current settings. AT+QCFG='lwm2m' Enable/Disable LwM2M Write Command AT+QCFG='lwm2m'[,] Response If the optional parameter is omitted, query the current settings: +QCFG: 'lwm2m', OK If the optional parameter is specified, set whether to enable LwM2M. 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 The command takes effect after the module reboots. The configuration is saved automatically. Parameter Integer type. 0 Disable 1 Enable Integer type. Error code. See Chapter 3 for more information. 2.1.2.12. AT+QCFG='nwoper' Configure Network Operator Mode of the Modem The command queries and configures network operator mode of the modem. This mode setting supports network operator specific requirements defined on top of 3GPP requirements. ='DEFAULT' means default 3GPP compliant behavior of the modem. The list of operators is not limited. Use Test Command (AT+QCFG=?) to retrieve the list of currently supported operators. Any attempt to set unknown operator name will return ERROR. In the 'AUTO' mode, when a new operator is identified, the configurations are set by the modem similar to BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 33 / 49 LPWA Module Series AT+QCFG='nwoper', operation. This means all operator configuration files will be restored to the new selected operator default values. AT+QCFG='nwoper' Configure Network Operator Mode of the Modem Write Command AT+QCFG='nwoper'[,] Response If the optional parameter is omitted, query the current settings: +QCFG: 'nwoper',[,mode] OK If the optional parameter is specified, set network operator mode: 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 The command takes effect immediately. The configuration is saved automatically. Parameter String type. Network operator mode of the modem. 'DEFAULT' Default 3GPP compliant mode 'VZW' Verizon 'ATT' AT&T … String type. Optional parameter, indicates that 'AUTO' mode is currently configured. 'AUTO' Network operator mode is selected in accordance with IMSI value of the currently used (U)SIM Integer type. Error code. See Chapter 3 for more information. 2.1.2.13. AT+QCFG='ps_dev_mob_type' Configure Device Mobility Type Flag The command queries and configures device mobility type flag. It gets configuration from JSON configuration file. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 34 / 49 LPWA Module Series AT+QCFG='ps_dev_mob_type' Configure Device Mobility Type Flag Write Command AT+QCFG='ps_dev_mob_type'[,] Response If the optional parameter is omitted, query the current settings: +QCFG: 'ps_dev_mob_type', OK If the optional parameter is specified, set device mobility type flag: 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 The command takes effect immediately. The configuration is saved automatically. Parameter Integer type. Device mobility type flag. 1 mobile 2 static Integer type. Error code. See Chapter 3 for more information. Example AT+QCFG='ps_dev_mob_type',1 OK //Set the flag to mobile. 2.1.2.14. AT+QCFG='netupd' Enable/Disable Network Override for Specified LTE Parameters The command queries the current settings and enables/disables network override for specified LTE parameters (i.e., by EMM messages). BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 35 / 49 LPWA Module Series AT+QCFG='netupd' Enable/Disable Network Override for Specified LTE Parame ters Write Command Response AT+QCFG='netupd',[, If the optional parameter is omitted, query the current ] settings: +QCFG: 'netupd',, OK If the optional parameter is specified, enable/disable network override for specified LTE parameters: 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 The command takes effect immediately. The configurations are not saved. Parameter String type. 'NWNAME' Sets the behavior of network name supplied by AT+COPS?. Integer type. For 'NWNAME': 0 AT+COPS? show the most updated full network name as required by the 27.007 standard. 1 Prohibit override of network name by EMM message (i.e. shown in AT+COPS?, etc.) even if the EMM information message indicates another full network name. Integer type. Error code. See Chapter 3 for more information. Example AT+QCFG='netupd','nwname',1 OK //Set 'nwname' to mode 1. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 36 / 49 LPWA Module Series 2.1.2.15. AT+QCFG='edrxusimact' Activate/Deactivate (U)SIM in eDRX Mode This command activates/deactivates (U)SIM in eDRX mode regardless of (U)SIM EF_AD settings. AT+QCFG='edrxusimact' Activate/Deactivate (U)SIM in eDRX Mode Write Command AT+QCFG='edrxusimact'[,] Response If the optional parameter is omitted, query the current settings: +QCFG: 'edrxusimact', OK If the optional parameter is specified, activate/deactivate (U)SIM in eDRX mode regardless of (U)SIM EF_AD settings: 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 The command takes effect immediately. The configuration is not saved. Parameter Integer type. (U)SIM activation policy. 0 Apply default (U)SIM activation policy as per (U)SIM EF_AD settings in eDRX mode 1 Activate (U)SIM in eDRX mode regardless of (U)SIM EF_AD settings 2 Deactivate (U)SIM in eDRX mode regardless of (U)SIM EF_AD settings Integer type. Error code. See Chapter 3 for more information. Example AT+QCFG='edrxusimact' +QCFG: 'edrxusimact',0 OK //Query the current (U)SIM activation policy. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 37 / 49 LPWA Module Series 2.1.2.16. AT+QCFG='setcfg' Set Configuration Field to the NV memory This command sets configuration field to the NV memory. AT+QCFG='setcfg' Set Configuration Field to the NV memory Write Command AT+QCFG='setcfg',[,] Response If the optional parameter is omitted, query the current settings: +QCFG: , OK If the optional parameter is specified, activate/deactivate USB interface: OK Maximum Response Time Characteristics If there is any other error: ERROR 300 ms The command takes effect immediately. The configurations are saved automatically. Parameter String type. 'sim_dual_config' Enable the dual SIM feature (between plastic and embedded SIM only) 'sim_init_select_policy' SIM policy options 'data_inactivity_dis' Integer type. For 'sim_dual_config': Enable/Disable inactivity timer 0 SW default 1 Single SIM 2 Dual SIM For 'sim_init_select_policy': 0 N/A, Single SIM 1 SIM1 only 2 Reserved 3 Reserved 4 Reserved 5 iUICC only option (no fallback available) For 'data_inactivity_dis': BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 38 / 49 0 Inactivity timer is enabled 1 inactivity timer is disabled LPWA Module Series Example AT+QCFG='setcfg',' sim_init_select_policy ',5 OK // set to iSIM only 2.1.2.17. AT+QCFG='setsyscfg' Set Value(s) to System Configuration Files This command sets value(s) to system configuration files. AT+QCFG='setsyscfg' Set Value(s) to System Configuration Files Write Command AT+QCFG='setsyscfg',,,,,, Response 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 The command takes effect immediately. The configurations are saved automatically. Parameter String type. 'ant_cfg' Antenna tuning configuration file. Integer type. Antenna characterization stage. Range: 1–56. Integer type. 0 Enable corresponding stage 1 Disable corresponding stage Integer type. Lower frequency of corresponding bandwidth, given in MHz multiplied by 10. Range: 4000–38000. Integer type. Upper frequency of corresponding bandwidth, given in MHz multiplied by 10. Range: 4000–38000. Integer type. Truth table combination of two different states of GRFC1 and GRFC2 pins respectively. Range: 0–3. Integer type. Error code. See Chapter 3 for more information. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 39 / 49 LPWA Module Series Example AT+QCFG='setsyscfg','ant_cfg',1,1,8031,9600,2 OK // 803.1-960MHz NOTE Overlapping between frequency ranges is forbidden. 2.1.2.18. AT+QCFG='uartmapping' Show Port and Function Mapping The command is used to present port (physical and virtual) mapping, i.e., to present the function performed by each port. AT+QCFG='uartmapping' Show Port and Function Mapping Write Command AT+QCFG='uartmapping' Response :, … : OK If there is an error related to ME functionality: +CME ERROR: Maximum Response Time Characteristics If there is any other error: ERROR 500 ms The command takes effect immediately. Parameter String type. DBG MAIN AUX MCU EMUX0 EMUX1 EMUX2 Physical port, DBG UART Physical port, MAIN UART Physical port, AUX UART Internal port, Reserved (BG772A-GL, BG952A-GL) Virtual port 0, EMUX function Virtual port 1, EMUX function Virtual port 2, EMUX function BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 40 / 49 LPWA Module Series EMUX3 Virtual port 3, EMUX function ACM0 Virtual port 0, USB interface ACM1 Virtual port 1, USB interface ACM2 Virtual port 2, USB interface ACM3 Virtual port 3, USB interface String type. AT_PPP AT client 0 / PPP data transfer AT_1 AT client 1 AT_2 AT client 2 GNSS_NMEA GNSS NMEA output SFP_LOGGER FW log messages, Debug mode FW_LOG LTE log messages, Debug mode MAC_VIA_MAP LTE log messages, Debug mode ALTCOM Internal function, Reserved (BG772A-GL, BG952A-GL) None No function is allocated to Integer type. Error code. See Chapter 3 for more information. 2.1.2.19. AT+QCFG='uartmapping/profile' Read/Write Port Profile Mapping Configuration This command reads or writes the value of parameters in port profile mapping configurations. The current mapping configuration of the selected port profile can be queried with AT+QCFG='uartmapping'. AT+QCFG='uartmapping/profile' Read/Write Port Profile Mapping Configuration Write Command AT+QCFG='uartmapping/profile'[,] Response If the optional parameter is omitted, query the current configuration: +QCFG: ' uartmapping/profile', OK If the optional parameter is specified, set the port profile mapping configuration OK If there is an error related to ME functionality: ERROR If there is any other error: Maximum Response Time Characteristics 300 ms The command takes effect immediately. The configurations are saved automatically. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 41 / 49 LPWA Module Series Parameter String type. 0 Default port profile Delta change in relation to Default port profile Mode USB+DEBUG DBG None MAIN AT1 AUX None ACM0 AT/PPP ACM3 GNSS 1 Port profile #1 Mode DBG MAIN AUX ACM0 ACM3 USB+DEBUG GNSS_NMEA AT/PPP AT1 None None 2.1.2.20. AT+QCFG='usb' Activate/Deactivate USB Interface This command activates/deactivates USB Interface. To use USB interface, the module should be connected via USB cable to the host computer. Following the boot process, the module exposes 3 other ports. AT+QCFG='usb' Activate/Deactivate USB Interface Write Command AT+QCFG='usb'[,] Response If the optional parameter is omitted, query the current settings: +QCFG: 'usb', OK If the optional parameter is specified, activate/deactivate USB interface: OK If there is an error related to ME functionality: +CME ERROR: Maximum Response Time Characteristics If there is any other error: ERROR 1500 ms The command takes effect after the module reboots. BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 42 / 49 LPWA Module Series The configuration is saved automatically. Parameter Integer type. Activates/deactivates USB Interface. 0 Deactivate 1 Activate Integer type. Error code. See Chapter 3 for more information. 2.1.2.21. AT+QCFG='usb/urcport' Configure URC Output Port in USB Interface Mode The command queries and configures the URC output port in USB interface mode. AT+QCFG='usb/urcport' Configure URC Output Port in USB Interface Mode Write Command AT+QCFG='usb/urcport'[,] Response If the optional parameter is omitted, query the current settings: +QCFG: 'usb/urcport', OK If the optional parameter is specified, configure the URC output port in USB Interface mode: 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 The command takes effect immediately. The configuration is saved automatically. Parameter Integer type. URC output port in USB Interface mode. 0 All ports 1 Virtual port 1 2 Virtual port 2 3 Virtual port 3 BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 43 / 49 LPWA Module Series Integer type. Error code. See Chapter 3 for more information. 2.1.2.22. AT+QCFG='lte/bandprior' Configure Band Scan Priority under LTE The command queries and configures the band scan priority. AT+QCFG='lte/bandprior' Configure Band Scan Priority under LTE Write Command AT+QCFG='lte/bandprior'[,] Response If the optional parameter is omitted, query the current settings: +QCFG: ' lte/bandprior', OK If the optional parameter is specified, configure the URC output port in USB Interface mode: OK Maximum Response Time Characteristics If there is any other error: ERROR 300 ms The configuration is saved automatically. Parameter < band_value > LTE Cat.M1 band value 01 Band 1 02 Band 2 03 Band 3 04 Band 4 05 Band 5 07 Band 7 08 Band 8 Example AT+QCFG='lte/bandprior' //Configure Band Scan Priority under LTE +QCFG='lte/bandprior',1,5,7……….//Configured Band1, Band5 and Band7. OK //Search priority: 1 -> 5 -> 7 BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 44 / 49 LPWA Module Series 2.1.2.23. AT+QCFG='stored/cell' Delete Stored Cell Acquisition DB The command deletes stored cell acquisition DB AT+QCFG='stored/cell' Delete Stored Cell Acquisition DB Write Command AT+QCFG='stored/cell'[,< value>] Response If the optional parameter is omitted, query the current settings: +QCFG: 'stored/cell', OK Maximum Response Time Characteristics If there is any other error: ERROR 300 ms The configuration is saved automatically. Parameter Integer value. 1 Delete acquisition DB BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 45 / 49 LPWA Module Series 3 Summary of +CME ERROR Codes Final result code +CME ERROR: indicates an error related to mobile equipment or network. The operation is similar to the 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 2: Summary of +CME ERROR Codes Numeric Value 0 1 2 3 4 5 6 7 10 11 12 13 14 15 Verbose Value 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 SIM not inserted SIM PIN required SIM PUK required SIM failure SIM busy SIM wrong BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 46 / 49 LPWA Module Series 16 incorrect password 17 SIM PIN2 required 18 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 BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 47 / 49 LPWA Module Series 4 Appendix References Table 3: Related Document Document Name [1] Quectel_BG77xA-GL&BG95xA-GL_AT_Commands_Manual Table 4: Terms and Abbreviations Abbreviation AP APN CDS CE eDRX EMM EMUX eMTC GPIO GSM IMSI JSON LED LTE LwM2M Description Application Processor Access Point Name Common Data Service Coverage Enhancement Extended Discontinuous Reception EPS Mobility Management Multiplexing Enhanced Machine-Type Communication General-Purpose Input/Output Global System for Mobile Communications International Mobile Subscriber Identity JavaScript Object Notation Light Emitting Diode Long-Term Evolution Lightweight M2M BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 48 / 49 ME NB-IoT PIN PS PSM PUK RAT RRC SMS TA TAU URC (U)SIM Mobile Equipment Narrowband Internet of Things Personal Identification Number Packet Switched Power Saving Mode PIN Unlock Key Radio Access Technology Radio Resource Control Short Message Service Terminal Adapter Tracking Area Update Unsolicited Result Code (Universal) Subscriber Identity Module LPWA Module Series BG77xA-GL&BG95xA-GL_QCFG_AT_Commands_Manual 49 / 49
483.98 KB
L89 R2.0&LC29H&LC79H AGNSS Application Note GNSS Module Series Version: 1.0 Date: 2022-05-19 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_AGNSS_Application_Note 1 / 44 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_AGNSS_Application_Note 2 / 44 GNSS Module Series About the Document Document Information Title L89 R2.0&LC29H&LC79H AGNSS Application Note Subtitle GNSS Module Series Document Type Application Note Document Status Released Revision History Version 1.0 Date 2021-10-14 2022-05-19 Description Creation of the document First official release L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 3 / 44 GNSS Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 6 Figure Index ................................................................................................................................................. 7 1 Introduction .......................................................................................................................................... 8 1.1. Differences Between Host EPO and Flash EPO....................................................................... 8 1.2. AGNSS Requirements............................................................................................................... 9 2 Download EPO Files .......................................................................................................................... 10 2.1. Get EPO Files from Server...................................................................................................... 10 2.2. EPO File Format ...................................................................................................................... 11 2.2.1. EPO File Format – GPS Only ........................................................................................ 12 2.2.2. EPO File Format – BDS/Galileo Only ............................................................................ 13 2.2.3. EPO File Format – GPS + GLONASS ........................................................................... 15 2.3. EPO File Types ........................................................................................................................ 15 2.4. Recommended Download Procedures of EPO Files .............................................................. 16 2.5. EPO File Validity Period .......................................................................................................... 17 3 AGNSS Implementation..................................................................................................................... 19 3.1. AGNSS with Flash EPO .......................................................................................................... 19 3.1.1. Binary Protocol ............................................................................................................... 19 3.1.2. EPO Data Transfer Protocol .......................................................................................... 21 3.1.2.1 Pseudo Code for EPO Data Transfer Protocol........................................................ 21 3.1.3. AGNSS Procedure with Flash EPO ............................................................................... 25 3.2. AGNSS with Host EPO............................................................................................................ 26 3.2.1. Recommended Sequence for Host EPO ....................................................................... 26 3.2.2. Sample Code to Send EPO ........................................................................................... 27 4 AGNSS Related Messages ................................................................................................................ 30 4.1. PAIR001 PAIR_ACK ................................................................................................................ 30 4.2. PAIR010 PAIR_REQUEST_AIDING ....................................................................................... 31 4.3. PAIR470 PAIR_EPO_GET_STATUS ...................................................................................... 32 4.4. PAIR471 PAIR_EPO_SET_DATA ........................................................................................... 33 4.5. PAIR472 PAIR_EPO_ERASE_FLASH_DATA ........................................................................ 34 4.6. PAIR590 PAIR_TIME_SET_REF_UTC ................................................................................... 35 4.7. PAIR600 PAIR_LOC_SET_REF.............................................................................................. 36 5 Download EPO Data with QGNSS .................................................................................................... 38 5.1. Download Flash EPO with QGNSS......................................................................................... 38 5.2. Download Host EPO with QGNSS .......................................................................................... 39 6 AGNSS Implementation Example..................................................................................................... 41 6.1. Flash EPO Implementation...................................................................................................... 41 6.2. Host EPO Implementation ....................................................................................................... 42 L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 4 / 44 GNSS Module Series 7 Appendix References ........................................................................................................................ 44 L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 5 / 44 GNSS Module Series Table Index Table 1: Differences between Flash EPO and Host EPO ............................................................................ 8 Table 2: AGNSS Related Commands .......................................................................................................... 9 Table 3: Download URL of EPO Files ........................................................................................................ 10 Table 4: EPO Data SVID Range .................................................................................................................11 Table 5: EPO File Types............................................................................................................................. 15 Table 6: Description of Binary Protocol Fields ........................................................................................... 20 Table 7: Start of EPO Binary Format .......................................................................................................... 20 Table 8: EPO Data Binary Format.............................................................................................................. 20 Table 9: End of EPO Binary Format ........................................................................................................... 20 Table 10: Terms and Abbreviations ............................................................................................................ 44 L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 6 / 44 GNSS Module Series Figure Index Figure 1: EPO File Format – GPS Only ..................................................................................................... 12 Figure 2: Format of Several Segments of EPO Files................................................................................. 12 Figure 3: EPO File Format – BDS/Galileo Only......................................................................................... 13 Figure 4: Galileo EPO Header ................................................................................................................... 14 Figure 5: BDS EPO Header ....................................................................................................................... 14 Figure 6: EPO File Format – GPS + GLONASS........................................................................................ 15 Figure 7: Recommended Download Procedures of EPO Files ................................................................. 16 Figure 8: Binary Protocol Structure ............................................................................................................ 19 Figure 9: AGNSS Procedure with Flash EPO ............................................................................................ 25 Figure 10: Suggested Sequence for Host EPO ......................................................................................... 27 Figure 11: QGNSS Interface for Setting Flash EPO .................................................................................. 38 Figure 12: Download Flash EPO File......................................................................................................... 39 Figure 13: QGNSS Interface for Setting Host EPO ................................................................................... 40 Figure 14: Download Host EPO File .......................................................................................................... 40 L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 7 / 44 GNSS Module Series 1 Introduction EPO (Extended Prediction Orbit) is an AGNSS feature implemented by the chipset supplier, which improves the sensitivity of the GNSS receiver and therefore shortens its TTFF. This document mainly describes EPO file downloading, AGNSS implementation, EPO related PAIR commands and how to download EPO data through the 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 PAIR 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 3-, 7- or 14-day assistance data, which are sent to the receiver through the 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 3, 7 or 14 day assistance data Binary Host EPO RAM 6-hour assistance data NMEA NOTE The maximum flash memory EPO data retention period is 14 days for GPS-only and GPS + GLONASS EPO files, 7 days for Galileo EPO files and 3 days for BDS EPO files. If 30-day GPS-only or GPS + GLONASS EPO files are sent, only the first 14 days of EPO data will be stored. L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 8 / 44 GNSS Module Series 1.2. 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 must meet the following requirements so that the GNSS receiver can make better use of EPO: ⚫ The Reference Time should be accurate within 3 seconds and must be specified in UTC time. ⚫ The Reference Position should be accurate within 30 km from the receiver’s actual position. 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 not available 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 the following table. See Chapter 4 for a detailed description of these messages. Table 2: AGNSS Related Commands Packet Type $PAIR471 $PAIR590 $PAIR600 Data Content GPS/GLONASS/Galileo/BDS EPO data for a single satellite. Reference UTC Time. Reference Position. L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 9 / 44 GNSS Module Series 2 Download EPO Files Quectel does not provide any Service Level Agreement for EPO files. Download EPO data to your own server and send them to devices to ensure EPO data availability. 2.1. Get EPO Files from Server Table 3: Download URL of EPO Files EPO Type Unified QEPO Unified QEPO Unified QEPO Unified QEPO EPO EPO EPO EPO GNSS Type EPO File URL File Name GPS only GPS + GLONASS BDS only Galileo only GPS only GPS + GLONASS BDS only Galileo only http://wpepodownload.mediatek.co m/QGPS.DAT?vendorinfo http://wpepodownload.mediatek.co m/QG_R.DAT?vendorinfo http://wpepodownload.mediatek.co m/QBD2.DAT?vendorinfo http://wpepodownload.mediatek.co m/QGA.DAT?vendorinfo http://wpepodownload.mediatek.co m/EPO_GPS_3_X.DAT?vendorinfo http://wpepodownload.mediatek.co m/EPO_GR_3_X.DAT?vendorinfo http://wpepodownload.mediatek.co m/EPO_BDS_3.DAT?vendorinfo http://wpepodownload.mediatek.co m/EPO_GAL_X.DAT?vendorinfo Single name: QGPS.DAT Single name: QG_R.DAT Single name: QBD2.DAT Single name: QGA.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 EPO_BDS_3.DAT X = 3 or 7 EPO_GAL_3.DAT or EPO_GAL_7.DAT The following is 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 and BBB in the example) are issued by Quectel. Contact L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 10 / 44 GNSS Module Series 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 by the customer. For example: if CCC = XXX_YYY, the value XXX is provided by Quectel and you can contact Quectel Technical Support to get the value, while YYY can be assigned by yourself and it must be a unique value, such as IMEI. Each device must have a unique ID. NOTE There will be up to 10 files as the GPS-only or GPS + GLONASS EPO files may include a maximum of 30 days of predictions. 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 File Format This part mainly illustrates the format of EPO files. The SVID numbers of EPO files for different constellations are shown below. Table 4: EPO Data SVID Range GNSS Type GPS GLONASS Galileo BDS PRN 1–32 1–24 1–36 1–54, 55–63 EPO Data SVID 1–32 65–88 101–136 201–254, 190–198 L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 11 / 44 2.2.1. EPO File Format – GPS Only GNSS Module Series Day1 Day2 ... Day7 ... 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 SVID Byte offset 0[LSB]~2[MSB] 3 Data ... Byte offset ... ... 4~7 ... 64~67 ... 8~11 CheckSum 68~71 Figure 1: EPO File Format – GPS Only GPS_Secs = GPS_Hour * 3600 GPS_Week Number = GPS_Secs / 604800 GPS TOW = GPS_Secs % 604800 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 of several segments of EPO files. SAT data SAT data 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 of Several Segments of EPO Files L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 12 / 44 GNSS Module Series 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 and thus 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 File Format – BDS/Galileo Only Galileo EPO data consist of the 72-byte header and 3- or 7- day fundamental EPO data. BDS EPO data consist of the 72-byte header and 3-day EPO data only. The EPO format for both has no fixed size. Header 72 bytes Day1 Day2 Day3 ... Day7 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) SV SV ... SV SV EPO Format (1 SV) Data GPS_Hour SVID Byte offset 0[LSB]~2[MSB] 3 Data ... Byte offset ... ... 4~7 ... 64~67 ... 8~11 CheckSum 68~71 Figure 3: EPO File Format – BDS/Galileo Only The 72-byte header contains the SV available bitmask that can be used for calculating the available satellite ID. When the SV available bitmask position is 1, it indicates that the satellite is available, and the number of bits indicates the satellite ID. For example, you can parse the data from Figure 4: Galileo EPO Header as follows. ⚫ SVID is FE for Galileo. ⚫ SV available bitmask: 09 67 94 5D DF. ⚫ Total available SVs: 22. ⚫ Available SVs: 1, 2, 3, 4, 5, 7, 8, 9, 11, 12, 13, 15, 19, 21, 24, 25, 26, 27, 30, 31, 33, 36. L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 13 / 44 GNSS Module Series Data *** Byte offset 0~2 Example SVID 3 SV available bitmask(Lbytes) 4[LSB]~7[MSB] FE DF 5D 94 67 Data SV available bitmask(Hbytes) Byte offset 16[LSB]~19[MSB] Example 09 00 00 00 *** 20~23 *** 8~11 *** 24~27 *** 12~15 *** 18~31 Figure 4: Galileo EPO Header You can parse the data from Figure 5: BDS EPO Header as follows. ⚫ SVID is FF for BDS. ⚫ SV available bitmask: 3F FF BF FC 3F FF. ⚫ Total available SVs: 41. ⚫ Available SVs: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46. Data *** Byte offset 0~2 Example SVID 3 SV available bitmask(Lbytes) 4[LSB]~7[MSB] FF FF 3F FC BF Data SV available bitmask(Hbytes) Byte offset 16[LSB]~19[MSB] Example FF 3F 00 00 *** 20~23 *** 8~11 *** 24~27 Figure 5: BDS EPO Header *** 12~15 *** 18~31 L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 14 / 44 2.2.3. EPO File Format – GPS + GLONASS GNSS Module Series 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 6: EPO File Format – GPS + GLONASS The basic unit of an EPO file is SAT Data, and the size of SAT Data is 72 bytes. In GPS + GLONASS EPO files, one EPO SET contains 56 SAT Data, so the EPO SET data size is 4032 bytes. Each 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. EPO File Types The EPO data can be downloaded in the form of files. You can select the most suitable file type to download based on the availability of a data connection and storage space of your application. See Table 3: Download URL of EPO Files and Table 5: EPO File to decide on the file type to be downloaded. Table 5: EPO File Types EPO Type EPO EPO GNSS Type GPS only Galileo only Description 3–14 days of prediction orbit (ephemeris). Split into 5 files, each containing 3-day information. 3- or 7-day prediction orbit (ephemeris). L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 15 / 44 GNSS Module Series EPO EPO Unified QEPO Unified QEPO Unified QEPO BDS only 3-day prediction orbit (ephemeris). GPS + GLONASS GPS only GPS + GLONASS BDS/Galileo only 3–14 days of prediction orbit (ephemeris). Split into 5 files, each containing 3-day information. 6-hour prediction orbit (ephemeris). Single file containing the latest available GPS EPO data. 6-hour prediction orbit (ephemeris). Single file containing the latest available GPS + GLONASS EPO data. 6-hour prediction orbit (ephemeris). Single file containing the latest available BDS/Galileo EPO data. 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 backup Verify downloaded data2) Do you have valid EPO files?3) Yes No Download unified QEPO files EPO aiding with backup file Verify downloaded data Position fixed Back up prepared EPO files Position fixed Figure 7: Recommended Download Procedures of EPO Files NOTE 1. 1) Users must know the current UTC time to download the valid EPO files. 2. 2) Send $PAIR470 to check if the data are correct. L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 16 / 44 GNSS Module Series 3. 3) If the device is powered-off for a long time, EPO files stored in flash may expire. 2.5. EPO File Validity Period EPO file validity period is related to the current UTC time. The EPO file validity period can be obtained from the last segment of the EPO file. See Figure 1: EPO File Format – GPS Only or the sample of how to calculate EPO file 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. 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--; } L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 17 / 44 GNSS Module Series } 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; } L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 18 / 44 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 PAIR commands, such as $PAIR471. ⚫ Implement AGNSS with Flash EPO The EPO data are downloaded to the flash of GNSS receiver through Binary Protocol. Flash EPO retains data longer than Host EPO. 3.1. AGNSS with Flash EPO Flash EPO can store up to 14 days of EPO assistance data in flash, which enables the receiver to use the available data since boot time. The communication protocol of Flash EPO is Binary Protocol. Thus, you need to download assistance data to the GNSS receiver 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 Frame preamble fixed as 0x04 0x24 2-byte Message ID 2-byte Message Preamble MsgID Length Payload Range for checksum calculation 1-byte Frame tail fixed as Checksum 0xAA 0x44 Checksum Tail Figure 8: Binary Protocol Structure L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 19 / 44 GNSS Module Series Table 6: Description of Binary Protocol Fields Field Preamble MsgID Length Payload Checksum Tail Length (Byte) 2 2 2 Variable 1 2 Description Fixed as 0x2404. Little-endian. Message ID. Payload length. Unit: byte. Default packet size: 72 bytes. Little-endian. 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 0x44AA. Little-endian. The EPO binary format is divided into start message, EPO data message and end message. Table 7: Start of EPO Binary Format Preamble MsgID Length 0x04 0x24 0xB0 0x04 1 2 Bytes 2 Bytes 2 Bytes Payload ‘G’ – GPS ‘R’ – GLONASS ‘E’ – Galileo ‘C’ – BDS 2 Bytes Checksum 0x** 1 Byte Tail 0xAA 0x44 2 Bytes Table 8: EPO Data Binary Format Preamble 0x04 0x24 2 Bytes MsgID 0xB1 0x04 2 Bytes Length 72 2 Bytes Payload EPO Data 72 Bytes Checksum 0x** 1 Byte Tail 0xAA 0x44 2 Bytes Table 9: End of EPO Binary Format Preamble MsgID Length 0x04 0x24 0xB2 0x04 1 Payload ‘G’ – GPS ‘R’ – GLONASS Checksum 0x** Tail 0xAA 0x44 L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 20 / 44 2 Bytes 2 Bytes 2 Bytes ‘E’ – Galileo ‘C’ – BDS 2 Bytes GNSS Module Series 1 Byte 2 Bytes 3.1.2. EPO Data Transfer Protocol When transmitting assistance data, the host first sends the start message packet, then splits the EPO data into data packets and sends them, and finally sends the end message packet. The host should follow the EPO Data Transfer Protocol when transferring EPO data to the GNSS receiver. 3.1.2.1 Pseudo Code for EPO Data Transfer Protocol Pseudo code for the EPO data transfer procedure of GPS + GLONASS, for reference only: #define GNSS_APP_BINARY_BINARY_PREAMBLE1 #define GNSS_APP_BINARY_BINARY_PREAMBLE2 #define GNSS_APP_BINARY_BINARY_ENDWORD1 #define GNSS_APP_BINARY_BINARY_ENDWORD2 (0x04) (0x24) (0xAA) (0x44) #define GNSS_APP_BINARY_BINARY_PREAMBLE_SIZE (2) #define GNSS_APP_BINARY_BINARY_CHECKSUM_SIZE (1) #define GNSS_APP_BINARY_BINARY_ENDWORD_SIZE (2) #define GNSS_APP_BINARY_BINARY_CONTROL_SIZE (GNSS_APP_BINARY_BINARY_PREAMBLE_SIZE + GNSS_APP_BINARY_BINARY_CHECKSUM_SIZE + GNSS_APP_BINARY_BINARY_ENDWORD_SIZE) #define GNSS_APP_BINARY_BINARY_MESSAGE_ID_SIZE (2) #define GNSS_APP_BINARY_BINARY_PAYLOAD_LENGTH_SIZE (2) #define GNSS_APP_BINARY_BINARY_PAYLOAD_HEADER_SIZE (GNSS_APP_BINARY_BINARY_MESSAGE_ID_SIZE + GNSS_APP_BINARY_BINARY_PAYLOAD_LENGTH_SIZE) #define GNSS_APP_BINARY_BINARY_MAX_DATA_SIZE (512) #define GNSS_APP_BINARY_BINARY_MAX_PAYLOAD_DATA_SIZE (GNSS_APP_BINARY_BINARY_MAX_DATA_SIZE - GNSS_APP_BINARY_BINARY_CONTROL_SIZE - GNSS_APP_BINARY_BINARY_PAYLOAD_HEADER_SIZE) typedef enum gnss_app_binary_binary_decode_results { GNSS_APP_BINARY_BINARY_DECODE_SUCCESS = 0, GNSS_APP_BINARY_BINARY_DECODE_WRONG_PARAMETER = -1, L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 21 / 44 GNSS Module Series GNSS_APP_BINARY_BINARY_DECODE_WRONG_PREAMBLE = -2, GNSS_APP_BINARY_BINARY_DECODE_WRONG_CHECKSUM = -3, GNSS_APP_BINARY_BINARY_DECODE_WRONG_ENDWORD = -4, }gnss_app_binary_binary_decode_results_t; typedef struct gnss_app_binary_binary_payload { uint16_t message_id; uint16_t data_size; /* actual size of data in payload data buffer */ uint8_t data[GNSS_APP_BINARY_BINARY_MAX_PAYLOAD_DATA_SIZE]; }gnss_app_binary_binary_payload_t; uint8_t gnss_app_binary_calculate_binary_checksum(const gnss_app_binary_binary_payload_t* const payload) { uint8_t checksum = 0; uint8_t* pheader = NULL; uint8_t* pdata = NULL; uint16_t i; if (NULL == payload) { return 0; } /* The checksum is the 8-bit exclusive OR of all bytes in the payload. */ pheader = (uint8_t*)payload; for (i = 0; i < GNSS_APP_BINARY_BINARY_PAYLOAD_HEADER_SIZE; i++) { checksum ^= *pheader; pheader++; } pdata = (uint8_t*)payload->data; for (i = 0; i < payload->data_size; i++) { checksum ^= *pdata; pdata++; } return checksum; } int16_t gnss_app_binary_encode_binary_packet(uint8_t* const buffer, uint16_t max_buffer_size, const gnss_app_binary_binary_payload_t* const payload) { uint8_t* pbyte; uint16_t required_length; if (NULL == buffer || payload == NULL) { return -1; } required_length = payload->data_size + GNSS_APP_BINARY_BINARY_CONTROL_SIZE + GNSS_APP_BINARY_BINARY_PAYLOAD_HEADER_SIZE; L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 22 / 44 GNSS Module Series if (max_buffer_size < required_length) { return -1; } memset((void*)buffer, 0, max_buffer_size); buffer[0] = GNSS_APP_BINARY_BINARY_PREAMBLE1; buffer[1] = GNSS_APP_BINARY_BINARY_PREAMBLE2; pbyte = &buffer[2]; memcpy(pbyte, payload, GNSS_APP_BINARY_BINARY_PAYLOAD_HEADER_SIZE); pbyte += GNSS_APP_BINARY_BINARY_PAYLOAD_HEADER_SIZE; memcpy(pbyte, payload->data, payload->data_size); pbyte += payload->data_size; *pbyte++ = gnss_app_binary_calculate_binary_checksum(payload); *pbyte++ = GNSS_APP_BINARY_BINARY_ENDWORD1; *pbyte = GNSS_APP_BINARY_BINARY_ENDWORD2; return required_length; } FILE* gnss_epo_file = NULL; #define GNSS_MAX_EPO_NUMBER (37) #define GNSS_MAX_RECORD_SIZE (72) static uint32_t gnss_epo_sv_buf[(GNSS_MAX_EPO_NUMBER * GNSS_MAX_RECORD_SIZE) / sizeof(uint32_t)]; int16_t gnss_epo_encode_binary(uint16_t msg_id, char* buffer, uint16_t buffer_size, char* data_input, int32_t data_length) { gnss_app_binary_binary_payload_t payload; int16_t binary_message_length; memset((void*)&payload, 0, sizeof(gnss_app_binary_binary_payload_t)); payload.message_id = msg_id; payload.data_size = (uint16_t)data_length; memcpy(payload.data, data_input, sizeof(uint8_t) * data_length); binary_message_length = gnss_app_binary_encode_binary_packet(buffer, buffer_size, &payload); return binary_message_length; } void gnss_epo_binary_demo() { gnss_app_binary_data_t data; gnss_app_binary_data_result_t result = { 0 }; uint32_t* epobuf; int32_t i; char buffer[500]; uint16_t length = 0; int32_t buffer_size = 0; uint8_t segment = 0; L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 23 / 44 GNSS Module Series uint8_t curr_sys_type = 'G'; //type is the GPS gnss_epo_file = fopen('EPO_GR_3_1.DAT', 'rb'); length = gnss_epo_encode_binary(1200, buffer, 512, &curr_sys_type, 1); gnss_app_uart_send_data(buffer, length); memset(&gnss_epo_sv_buf, 0, sizeof(gnss_epo_sv_buf)); while (gnss_epo_read_data(&gnss_epo_sv_buf, 32 * GNSS_MAX_RECORD_SIZE, segment * (32 + 24) * GNSS_MAX_RECORD_SIZE)) { segment++; for (i = 0; i < 32; i++) { epobuf = (uint32_t*)(gnss_epo_sv_buf + ((i * GNSS_MAX_RECORD_SIZE) / 4)); length = gnss_epo_encode_binary(1201, buffer, 512, (char*)epobuf, GNSS_MAX_RECORD_SIZE); gnss_app_uart_send_data(buffer, length); } memset(&gnss_epo_sv_buf, 0, sizeof(gnss_epo_sv_buf)); } length = gnss_epo_encode_binary(1202, buffer, 512, &curr_sys_type, 1); gnss_app_uart_send_data(buffer, length); curr_sys_type = 'R'; //type is the GLONASS length = gnss_epo_encode_binary(1200, buffer, 512, &curr_sys_type, 1); gnss_app_uart_send_data(&data, &result); memset(&gnss_epo_sv_buf, 0, sizeof(gnss_epo_sv_buf)); segment = 0; while (gnss_epo_read_data(&gnss_epo_sv_buf, 37 * GNSS_MAX_RECORD_SIZE, (segment * (32 + 24) * GNSS_MAX_RECORD_SIZE) + (32 * GNSS_MAX_RECORD_SIZE))) { segment++; for (i = 0; i < 24; i++) { epobuf = (uint32_t*)(gnss_epo_sv_buf + ((i * GNSS_MAX_RECORD_SIZE) / 4)); length = gnss_epo_encode_binary(1201, buffer, 512, (char*)epobuf, GNSS_MAX_RECORD_SIZE); gnss_app_uart_send_data(buffer, length); } memset(&gnss_epo_sv_buf, 0, sizeof(gnss_epo_sv_buf)); } length = gnss_epo_encode_binary(1202, buffer, 512, &curr_sys_type, 1); gnss_app_uart_send_data(buffer, length); fclose(gnss_epo_file); } L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 24 / 44 3.1.3. AGNSS Procedure with Flash EPO Power on GNSS GNSS Module Series Do you have an EPO file? NO YES Has EPO file expired? YES Erase EPO file NO Send Reference Time Download EPO files with Binary Protocol Verify downloaded data Restart GNSS Send Reference Position Position fixed Figure 9: AGNSS Procedure with Flash EPO 1. Power on the GNSS module. 2. Check if there are EPO data in the GNSS module flash memory with $PAIR470. 3. If the flash memory contains EPO data, go to the next step to check data validity. Otherwise, download EPO data to the GNSS module and verify the downloaded data, then restart the GNSS module and go to Step 5. 4. Check whether the EPO file in the GNSS module flash memory has expired. 5. If the EPO file is still valid, go to Step 6. Otherwise, erase the expired EPO file with $PAIR472 and download a new EPO file. 6. Send reference time to the GNSS module with $PAIR590. 7. Send reference position to GNSS module with $PAIR600. 8. Wait for the GNSS module to fix position. L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 25 / 44 GNSS Module Series 3.2. AGNSS with Host EPO Host EPO allows for a simpler text-based implementation that 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 PAIR sentences and the whole data transfer can be performed in NMEA mode. See Chapter 4 for detailed description of $PAIR471, $PAIR590 and $PAIR600. 3.2.1. Recommended Sequence for Host EPO After the module is powered on, it sends an aiding request to notify the expiration of the stored GNSS assistance data when both assistance data and ephemeris are invalid. Therefore, if the module does not report an aiding request, it is recommended to determine whether the assistance data have expired by sending $PAIR470 after the host receives the system startup message. The host sends the assistance data in the sequence shown in Figure 10: Suggested Sequence for Host EPO. Host EPO procedure: 1. GNSS module starts up; 2. Host sends Reference Time; 3. Host sends Reference Position; 4. Host sends EPO data. The supplied Reference Time, Reference Position and EPO data must comply with the requirements listed in Chapter 1.2. NOTE In the current implementation, the host needs to wait for a $PAIR001 packet to be returned before sending another segment of EPO data. L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 26 / 44 GNSS Receiver Host EPO Sequence GNSS Module Powers Up Start up message Assistance Data (Time) PAIR001 (ACK) Assistance Data (Position) PAIR001 (ACK) Loop [Repeats until all EPO data are sent] EPO Assistance Data Segment 001 PAIR001 (ACK) EPO Assistance Data Segment 002 PAIR001 (ACK) Host needs to wait for ACK packages GNSS Module Series Host Figure 10: Suggested Sequence for Host EPO 3.2.2. Sample Code to Send EPO The following is the reference code to send one segment of EPO data to GNSS chip. It indicates how to construct PAIR messages for GNSS receiver. PAIR messages for Reference Time and Reference Position are not included in this example. #define GNSS_GLONASS_EPO_BASE_ID (64) #define GNSS_GALILEO_EPO_BASE_ID (100) #define GNSS_BDS_EPO_BASE_ID (200) #define MNL_SERVICE_MAX_COMMAND_LEN (352) #define EPO_DEMO_RECORD_SIZE (72) typedef enum{ EPO_DEMO_MODE_GPS, L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 27 / 44 GNSS Module Series EPO_DEMO_MODE_GLONASS, EPO_DEMO_MODE_GALILEO, EPO_DEMO_MODE_BEIDOU }epo_demo_mode_t; int32_t epo_demo_get_sv_prn(int32_t type, uint8_t *data) { int32_t sv_id, sv_prn = 0; sv_id = data[3]; switch(type) { case EPO_DEMO_MODE_GPS: sv_prn = sv_id; break; case EPO_DEMO_MODE_GLONASS: sv_prn = sv_id - GNSS_GLONASS_EPO_BASE_ID; break; case EPO_DEMO_MODE_GALILEO: if(sv_id == 255) { sv_prn = 255; } else { sv_prn = sv_id - GNSS_GALILEO_EPO_BASE_ID; } break; case EPO_DEMO_MODE_BDS: if(sv_id == 255) { sv_prn = 255; } else { sv_prn = sv_id - GNSS_BDS_EPO_BASE_ID; } break; default: sv_prn = 0; } return sv_prn; } void epo_demo_send_data(epo_demo_epo_data_t *data_p, int32_t data_num, int32_t type){ char temp_buffer[MNL_SERVICE_MAX_COMMAND_LEN] = {0}; uint8_t data_buffer[EPO_DEMO_RECORD_SIZE] = {0}; int32_t i; int32_t sv_prn = 0; L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 28 / 44 GNSS Module Series for(i = 0; i < data_num; i++) { unsigned int *epobuf = (unsigned int *)data_buffer; epo_demo_epo_fread(data_p, data_buffer, EPO_DEMO_RECORD_SIZE); sv_prn = epo_demo_get_sv_prn(type, data_buffer); sprintf((char *) temp_buffer, '471,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X', (unsigned int)type, (unsigned int)sv_prn, 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]); gnss_app_send_command_ex(temp_buffer); memset(temp_buffer, 0, MNL_SERVICE_MAX_COMMAND_LEN); } } L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 29 / 44 GNSS Module Series 4 AGNSS Related Messages 4.1. PAIR001 PAIR_ACK Acknowledges a PAIR command. An acknowledgement packet $PAIR001 is returned to inform the sender that the receiver has received the packet. Type: Output Synopsis: $PAIR001,,* Parameter: Field Format Unit Description Numeric - Numeric - Type of command to be acknowledged. 0 = Command has been successfully sent. 1 = Command is being processed. Please wait for the result. 2 = Command sending failed. 3 = is not supported. 4 = Command parameter error. Out of range/some parameters were lost/checksum error. 5 = MNL service is busy. Example: $PAIR001,0,3*38 L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 30 / 44 GNSS Module Series 4.2. PAIR010 PAIR_REQUEST_AIDING Notifies the expiration of GNSS assistance data stored in the module. This message is automatically output when the module powers up. Type: Output Synopsis: $PAIR010,,,,* Parameter: Field Format Unit Numeric - Numeric - Numeric Numeric Week Second Description Type of data to be updated. 0 = EPO data 1 = Time 2 = Position Type of GNSS data needed. 0 = GPS data 1 = GLONASS data 2 = Galileo data 3 = BDS data Week Number (accommodating roll-over). Time of Week. Example: //Send GPS EPO data when this sentence is received: $PAIR010,0,0,2044,369413*33 //Send reference time when this sentence is received: $PAIR010,1,-1*16 //Send reference position when this sentence is received: $PAIR010,2,-1*15 NOTE 1. The GNSS system sends this command automatically. Do not send it to the GNSS system. 2. The L89 R2.0 module does not support reporting the expiration of GLONASS and BDS data. L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 31 / 44 GNSS Module Series 4.3. PAIR470 PAIR_EPO_GET_STATUS Queries the status of EPO data stored on the GNSS chip. Type: Query Synopsis: $PAIR470,* Parameter: Field Format Unit Numeric - Description GNSS system ID. 0 = GPS 1 = GLONASS 2 = Galileo 3 = BDS Result: Returns a $PAIR001 message and the query result. Query result message format: $PAIR470,,,,,,,,,,* Parameters in the result: Field Format Unit Description Numeric - GNSS system ID. 0 = GPS 1 = GLONASS 2 = Galileo 3 = BDS Numeric - Total number of EPO data sets stored in GNSS chip. Numeric - GPS week number of the first set of EPO data stored in flash. Numeric - GPS TOW of the first set of EPO data stored in flash. Numeric - GPS week number of the last set of EPO data stored in flash. L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 32 / 44 GNSS Module Series Numeric Numeric Numeric Numeric Numeric - GPS TOW of the last set of EPO data stored in flash. GPS week number of the first set of EPO data that are currently being used. GPS TOW of the first set of EPO data that are currently being used. GPS week number of the last set of EPO data that are currently being used. GPS TOW of the last set of EPO data that are currently being used. Example: $PAIR470,0*25 $PAIR001,470,0*38 $PAIR470,0,1,2098,194400,2098,216000,2098,194400,2098,216000*38 NOTE The L89 R2.0 module does not support the reporting of GLONASS and BDS data. 4.4. PAIR471 PAIR_EPO_SET_DATA Sends the packet containing EPO data for a single satellite. Type: Input Synopsis: $PAIR471,,,,...,* Parameter: Field Format Numeric Hexadecimal Unit Description GNSS system ID. 0 = GPS - 1 = GLONASS 2 = Galileo 3 = BDS - Satellite PRN number used in EPO data. L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 33 / 44 GNSS Module Series - GPS Range: 1–32. GLONASS Range: 1–24. Galileo Range: 1–30. BDS Range: 1–37. Special 255: BDS IONO data. Special 254: Galileo IONO data. 18 words (LSB-first) of one EPO segment data (total 72 bytes). Result: Returns a $PAIR001 message. Example: $PAIR471,1,16,56056272,F2BC0244,4F19AE34,F95C534D,FAE67014,4F19AF6B,F96749BD,9F341F2 D,6F4EA9F,77DB4710,66ADAC2,9ADF3B01,8CC8B19C,29D2D20C,FC5B2E94,1000001C,11005000,7 48B45F4*0A $PAIR001,471,0*39 NOTE The L89 R2.0 module does not support the reporting of GLONASS and BDS data. 4.5. PAIR472 PAIR_EPO_ERASE_FLASH_DATA Erases the EPO data stored in the flash memory. Type: Command Synopsis: $PAIR472* Parameter: None Result: Returns a $PAIR001 message. L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 34 / 44 Example: $PAIR472*3B $PAIR001,472,0*3A GNSS Module Series 4.6. PAIR590 PAIR_TIME_SET_REF_UTC Sends reference UTC time to GNSS chip for faster TTFF. Local time should be avoided due to time-zone offset. To achieve a faster TTFF, the reference time should be accurate within 3 seconds and must be specified in UTC time. Type: Set Synopsis: $PAIR590,,,,,,* Parameter: Field Format Numeric Numeric Numeric Numeric Numeric Numeric Unit Year Month Day Hour Minute Second Description UTC year. Minimum value: 1980. UTC month. Range: 1–12. UTC day. Range: 1–31. UTC hours. Range: 0–23. UTC minutes. Range: 0–59. UTC seconds. Range: 0–59. Result: Returns a $PAIR001 message. Example: $PAIR590,2019,2,10,9,0,58*0B $PAIR001,590,0*37 L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 35 / 44 GNSS Module Series 4.7. PAIR600 PAIR_LOC_SET_REF Sends reference position to GNSS chip for faster TTFF. Type: Set Synopsis: $PAIR600,,,,,,,* Parameter: Field Format Numeric Numeric Numeric Numeric Numeric Numeric Numeric Unit Degrees Degrees Meter Meter Meter Degrees Meter Description Reference latitude. Range: -90 to 90. Minus: south; plus: north. It is recommended to express this value in floating point with 6 decimal points. Reference longitude. Range: -180 to 180. Minus: west; plus: east. It is recommended to express this value in floating point with 6 decimal points. Reference height. Semi-major RMS accuracy. Semi-minor RMS accuracy. Bearing. Vertical RMS accuracy. Result: Returns a $PAIR001 message. Example: $PAIR600,24.772816,121.022636,175.0,50.0,50.0,0.0,100.0*06 $PAIR001,600,0*3D L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 36 / 44 NOTE This command needs to be sent every time after GNSS module reboots. GNSS Module Series L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 37 / 44 GNSS Module Series 5 Download EPO Data with QGNSS This chapter describes how to download EPO data through QGNSS. Contact Quectel Technical Support for details on QGNSS. 5.1. Download Flash EPO with QGNSS Steps to download 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 11: QGNSS Interface for Setting Flash EPO 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. d) Select Satellites type. L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 38 / 44 e) Click the '…' button to select EPO file. f) Click the 'Download' button to download the EPO file to module. GNSS Module Series Figure 12: Download Flash EPO File 5.2. Download Host EPO with QGNSS Steps to download Host EPO with the QGNSS tool: 1. Run the QGNSS tool. 2. In the main interface, click 'AGNSS' → 'Assistant GNSS Online' as shown below. L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 39 / 44 GNSS Module Series Figure 13: QGNSS Interface for Setting Host EPO 3. Configure parameters: a) Check 'Use Current Position' to use current position. b) Check 'Use Current UTC' to use current time. c) Click 'Transfer' to download host EPO file. Figure 14: Download Host EPO File L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 40 / 44 GNSS Module Series 6 AGNSS Implementation Example This chapter gives examples of how to download EPO files to the module. 6.1. Flash EPO Implementation Blue: Sent data Red: ACK information //Host sends $PAIR472*3B to erase the EPO data stored in the flash memory: $PAIR472*3B //Module returns a $PAIR001 message: $PAIR001,472,0*3A //Host sends EPO start message in hexadecimal format: 04 24 B0 04 01 00 52 E7 AA 44 //Module returns an ACK message: 04 24 E8 03 04 00 B0 04 00 00 5B AA 44 //Host sends EPO data in hexadecimal format: 04 24 B1 04 48 00 BF 96 05 41 6E 3A 74 05 C3 21…….AA 44 //Module returns an ACK message: 04 24 E8 03 04 00 B1 04 00 00 5A AA 44 //Host sends EPO data in hexadecimal format: 04 24 B1 04 48 00 BF 96 05 42 09 3A 74 0C CA 77……. AA 44 //Module returns an ACK message: 04 24 E8 03 04 00 B1 04 00 00 5A AA 44 …… //Host sends EPO end data in hexadecimal format: 04 24 B2 04 01 00 52 E5 AA 44 L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 41 / 44 //Module returns an ACK message: 04 24 E8 03 04 00 B2 04 00 00 59 AA 44 //Host queries the EPO data status stored in the GNSS chip: $PAIR470,0*25 //Module returns $PAIR001 and $PAIR470 messages: $PAIR001,470,0*38 $PAIR470,0,1,2098,194400,2098,216000,2098,194400,2098,216000*38 GNSS Module Series 6.2. Host EPO Implementation Blue: Sent data Red: ACK information //Host sends the power-on GNSS system command $PAIR002: $PAIR002*38 //Module returns a $PAIR001 message: $PAIR001,002,0*39 //Module outputs $PAIR010 messages automatically: $PAIR010,1,-1*16 $PAIR010,2,-1*15 //Host sends reference UTC time command $PAIR590: $PAIR590,2021,10,18,08,59,00*3B //Module returns a $PAIR001 message: $PAIR001,590,0*37 //Host sends reference position information command $PAIR600: $PAIR600,31.822203,117.115219,175.0,50.0,50.0,0.0,100.0*0F //Module returns a $PAIR001 message: $PAIR001,600,0*3D //Host sends EPO data: $PAIR471,0,1,10596C0,A174051A,1B2EDE67,9F0BB6,17C37A4,1B2EDE22,F85B368E,845FB0C9,6F1 8C40,23557111,2A4CBD5,A60348AB,FEF7E24,2F236B88,2439FDC6,1000001C,0,4860BF93*44 //Module returns a $PAIR001 message: L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 42 / 44 GNSS Module Series $PAIR001,471,0*39 //Host sends EPO data: $PAIR471,0,2,20596C0,F0740341,1B2EEE36,5F3FAA,17E07E6,1B2E1100,F8C1048F,84A50985,6F1B D33,29192005,D651ED6,A600506D,256C95F,20430E67,C36C910D,1000001C,0,FAC0DA552A 33 43 0D 0A*3C //Module returns a $PAIR001 message: $PAIR001,471,0*39 …… //Host sends EPO data: $PAIR471,0,7,70596C0,377403C2,1B2E41F1,F757006,C57EB,1B2EBF14,F89F543F,8986E880,6F1E6 93,DC3908E,DA7BB7,A603A757,8FBA37BF,21C8A8F0,A2247EAD,1000001C,22000000,DDACBBB6*0 B //Module returns a $PAIR001 message: $PAIR001,471,0*39 L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 43 / 44 GNSS Module Series 7 Appendix References Table 10: Terms and Abbreviations Abbreviation ACK AGNSS EPO GLONASS GNSS GPS IMEI IONO MNL RAM SV SVID TOW TTFF UART UTC URL Description Acknowledgement Assisted GNSS (Global Navigation Satellite System) Extended Prediction Orbit Global Navigation Satellite System (Russia) Global Navigation Satellite System Global Positioning System International Mobile Equipment Identity Ionospheric MTK Navigation Lib Random Access Memory Space Vehicle Space Vehicle Identification Time of Week Time to First Fix Universal Asynchronous Receiver/Transmitter Coordinated Universal Time Uniform Resource Locator L89_R2.0&LC29H&LC79H_AGNSS_Application_Note 44 / 44
837.31 KB
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