Download Zone

Select the files you need to support your use of Quectel’s products

Filter

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.

Results

0 Files in basket

View basket

Antenna Brochure

Select all (max. 100)

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 Identiﬁcation ■ Initial Proof of Concept ■ Antenna Component Selection Testing & Certiﬁcation ■ Antenna OTA Testing ■ Interference Mitigation ■ Support for CE/FCC/PTCRB Radio Approval ■ Pre-certiﬁcation 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 Speciﬁcation 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 Speciﬁcation. 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 Speciﬁcation. 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 Speciﬁcation. 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 Speciﬁcation. 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 Speciﬁcation. 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 Speciﬁcation. 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 Speciﬁcation. 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 Speciﬁcation. 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 Speciﬁcation. 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 Speciﬁcation. 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 Speciﬁcation. 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 Speciﬁcation. 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 Speciﬁcation. 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 Speciﬁcation. 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 Speciﬁcation. 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 Speciﬁcation. 17 V1.7.4 2022.04

Quectel Antenna Brochure 2022

PDF

6.53 MB

Application Note

Select all (max. 100)

EC200U&EG91xU Series SSL Application Note LTE Standard Module Series Version: 1.2 Date: 2023-09-15 Status: Released LTE Standard 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. EC200U&EG91xU_Series_SSL_Application_Note 1 / 37 LTE Standard 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. 2023. All rights reserved. EC200U&EG91xU_Series_SSL_Application_Note 2 / 37 LTE Standard Module Series About the Document Revision History Version 1.0 1.1 1.2 Date 2021-05-19 2021-07-19 2021-08-17 2023-09-15 Author Description Kruskal ZHU Creation of the document Kruskal ZHU First official release Kruskal ZHU Kruskal ZHU Added an applicable module series EG915U. 1. Added an applicable module EG912U-GL. 2. Added the following commands: AT+QSSLCFG='session_cache' (Chapter 2.2.1), AT+QSSLCFG='dtlsversion' (Chapter 2.2.1), AT+QSSLRECV=,0 (Chapter 2.2.4). 3. Deleted a command: AT+QSSLCFG='cacertex'. EC200U&EG91xU_Series_SSL_Application_Note 3 / 37 LTE Standard Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 6 1 Introduction .......................................................................................................................................... 7 1.1. Applicable Modules ..................................................................................................................... 7 1.2. SSL Version and Cipher Suite .................................................................................................... 8 1.3. The Process of Using SSL Function ......................................................................................... 10 1.4. Description of Data Access Modes ........................................................................................... 10 1.5. Validity Period Check of Certificate........................................................................................... 11 1.6. Server Name Indication ............................................................................................................ 11 2 Description of SSL AT Commands .................................................................................................. 12 2.1. AT Command Introduction ........................................................................................................ 12 2.1.1. Definitions....................................................................................................................... 12 2.1.2. AT Command Syntax ..................................................................................................... 12 2.1.3. Declaration of AT Command Examples ......................................................................... 13 2.2. Description of AT Commands ................................................................................................... 13 2.2.1. AT+QSSLCFG Configure Parameters of an SSL Context .......................................... 13 2.2.2. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server ........................ 21 2.2.3. AT+QSSLSEND Send Data via SSL Connection ....................................................... 22 2.2.4. AT+QSSLRECV Receive Data via SSL Connection ................................................... 23 2.2.5. AT+QSSLCLOSE Close an SSL Connection.............................................................. 24 2.2.6. AT+QSSLSTATE Query the State of SSL Connection................................................ 25 2.3. Description of URCs ................................................................................................................. 27 2.3.1. +QSSLURC: 'recv' URC Indicating Incoming Data.................................................... 27 2.3.2. +QSSLURC: 'closed' Notify Abnormal Disconnection ............................................... 27 3 Examples ............................................................................................................................................ 28 3.1. Configure and Activate a PDP Context..................................................................................... 28 3.1.1. Configure a PDP Context............................................................................................... 28 3.1.2. Activate a PDP Context.................................................................................................. 28 3.1.3. Deactivate a PDP Context ............................................................................................. 28 3.2. Configure an SSL Context ........................................................................................................ 28 3.3. SSL Client in Buffer Access Mode ............................................................................................ 29 3.3.1. Set up an SSL Connection and Enter Buffer Access Mode........................................... 29 3.3.2. Send Data in Buffer Access Mode ................................................................................. 29 3.3.2.1. Send Variable-length Data.................................................................................... 29 3.3.2.2. Send Fixed-length Data........................................................................................ 29 3.3.3. Receive Data in Buffer Access Mode ............................................................................ 30 3.3.4. Close an SSL Connection .............................................................................................. 30 3.4. SSL Client in Direct Push Mode................................................................................................ 30 3.4.1. Set up an SSL Connection and Enter Direct Push Mode .............................................. 30 EC200U&EG91xU_Series_SSL_Application_Note 4 / 37 LTE Standard Module Series 3.4.2. Send Data in Direct Push Mode..................................................................................... 30 3.4.3. Receive Data in Direct Push Mode ................................................................................ 31 3.4.4. Close an SSL Connection .............................................................................................. 31 3.5. SSL Client in Transparent Access Mode .................................................................................. 31 3.5.1. Set up an SSL Connection and Send Data in Transparent Access Mode .................... 31 3.5.2. Set up an SSL Connection and Receive Data in Transparent Access Mode................ 31 3.5.3. Close an SSL Connection .............................................................................................. 32 4 Check for Failure in SSL Connection .............................................................................................. 33 5 Error Codes ........................................................................................................................................ 34 6 Appendix References ........................................................................................................................ 36 EC200U&EG91xU_Series_SSL_Application_Note 5 / 37 LTE Standard Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 7 Table 2: SSL Versions .................................................................................................................................. 8 Table 3: Supported SSL Cipher Suites ........................................................................................................ 8 Table 4: Types of AT Command ................................................................................................................. 12 Table 5: Error Codes .................................................................................................................................. 34 Table 6: Related Documents ...................................................................................................................... 36 Table 7: Terms and Abbreviations .............................................................................................................. 36 EC200U&EG91xU_Series_SSL_Application_Note 6 / 37 LTE Standard Module Series 1 Introduction Quectel LTE Standard EC200U series and EG91xU family modules support SSL function. SSL (Secure Sockets Layer) is a networking protocol designed for securing connections between web clients and web servers over an insecure network, such as the internet. The SSL function is to ensure the privacy of communication. In some cases, the communication between the server and the client should be encrypted way to prevent data from being eavesdropped, tampered with or forged during the communication process. 1.1. Applicable Modules Table 1: Applicable Modules Module Family - EG91xU Module EC200U Series EG912U-GL EG915U Series EC200U&EG91xU_Series_SSL_Application_Note 7 / 37 LTE Standard Module Series 1.2. SSL Version and Cipher Suite The following SSL versions are applicable. Table 2: SSL Versions SSL Versions SSL 3.0 TLS 1.2 TLS 1.1 TLS 1.0 The following table shows SSL cipher suites supported by EC200U and EG91xU family modules, and all the SSL cipher suites are supported by default. For detailed description of cipher suites, see RFC 2246-The TLS Protocol Version 1.0. Table 3: Supported SSL Cipher Suites Codes of Cipher Suites Names of Cipher Suites 0X0035 TLS_RSA_WITH_AES_256_CBC_SHA 0X002F TLS_RSA_WITH_AES_128_CBC_SHA 0X0005 TLS_RSA_WITH_RC4_128_SHA 0X0004 TLS_RSA_WITH_RC4_128_MD5 0X000A TLS_RSA_WITH_3DES_EDE_CBC_SHA 0X003D TLS_RSA_WITH_AES_256_CBC_SHA256 0XC002 TLS_ECDH_ECDSA_WITH_RC4_128_SHA 0XC003 TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 0XC004 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 0XC005 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA EC200U&EG91xU_Series_SSL_Application_Note 8 / 37 0XC007 0XC008 0XC009 0XC00A 0XC011 0XC012 0XC013 0XC014 0xC00C 0XC00D 0XC00E 0XC00F 0XC023 0xC024 0xC025 0xC026 0XC027 0XC028 0xC029 0XC02A 0XC02F 0XC030 0XFFFF LTE Standard Module Series TLS_ECDHE_ECDSA_WITH_RC4_128_SHA TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_RC4_128_SHA TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_ECDH_RSA_WITH_RC4_128_SHA TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDH_RSA_WITH_AES_128_CBC_SHA TLS_ECDH_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 Support all cipher suites above EC200U&EG91xU_Series_SSL_Application_Note 9 / 37 LTE Standard Module Series 1.3. The Process of Using SSL Function Step 1: Configure , , and other parameters of a PDP context by AT+QICSGP. See document [1] for details. Step 2: Activate the PDP context by AT+QIACT, then the assigned IP address can be queried by AT+QIACT?. See document [1] for details. Step 3: Configure the SSL version, cipher suite, path of trusted CA certificate authentication mode, the path of the client certificate and private key, etc. for the specified SSL context by AT+QSSLCFG. Step 4: Open an SSL socket to connect a remote server by AT+QSSLOPEN. is used to specify SSL context, and is used to specify data access mode. Step 5: After the SSL connection has been established, data will be sent or received via the connection. For details about how to send and receive data in each access mode, please refer to Chapter 1.4. Step 6: Close an SSL connection by AT+QSSLCLOSE. Step 7: Deactivate the PDP context by AT+QIDEACT. See document [1] for details. 1.4. Description of Data Access Modes The SSL connection supports the following three kinds of data access modes: ⚫ Buffer access mode ⚫ Direct push mode ⚫ Transparent access mode When opening an SSL connection via AT+QSSLOPEN, the data access mode can be specified by the . After the SSL connection has been established, AT+QISWTMD can be used to switch the data access mode. See document [1] for details of AT+QISWTMD. 1. In buffer access mode, data can be sent via AT+QSSLSEND, and if the module has received data from the Internet, it will report a URC as +QSSLURC: 'recv',. In a such case, data can be retrieved via AT+QSSLRECV. 2. In direct push mode, data can be sent via AT+QSSLSEND, and if the module has received data from the Internet, the data will be outputted directly via UART/USB modem/USB AT port in the following format of +QSSLURC: 'recv',,. 3. In transparent access mode, the corresponding port enters exclusive mode. The data received from COM port will be sent to the Internet directly, and the received data from Internet will be outputted to COM port directly. Use +++ or DTR (executing AT&D1 first) to exit transparent access mode. In transparent access mode, if any abnormal SSL disconnection happens, the module will report NO CARRIER. See document [3] for details of AT&D. EC200U&EG91xU_Series_SSL_Application_Note 10 / 37 LTE Standard Module Series ⚫ Exit transparent access mode To exit transparent access mode, +++ or DTR (executing AT&D1 first) can be used. To prevent the +++ from being misinterpreted as data, follow the following sequence: 1) Do not input any other character within 1 s (at least) before inputting +++. 2) Input +++ within 1 s, and no other characters can be inputted during the time. 3) Do not input any other character within 1 s after +++ has been inputted. 4) Use +++ or DTR (executing AT&D1 first) to make the module exit transparent access mode, and wait until OK is returned. ⚫ Return to transparent access mode 1) By AT+QISWTMD. Specify the as 2 when executing this command. If entering transparent access mode successfully, CONNECT will be returned. 2) By ATO. ATO will change the access mode of connection that exits from transparent access mode lately. If entering transparent access mode successfully, CONNECT will be returned. If there is no connection entering transparent access mode before, ATO will return NO CARRIER. See document [3] for details of ATO. 1.5. Validity Period Check of Certificate To check whether a certificate is in the validity period, the certificate must be parsed, and compare the local time with the 'Not before' and 'Not after' of the certificate. If the local time is earlier than the time of 'Not before' or later than the time of 'Not after', the certificate will be considered expired. When validity period check of certificate is required (set as 0 when executing AT+QSSLCFG), in order to avoid failure of certificate validity period check, execute AT+CCLK to configure the module time within the validity period of the certificate. See document [3] for details of AT+CCLK. 1.6. Server Name Indication SNI (Server Name Indication) is desirable for clients to provide Server Host Name information to enhance secure connection with multiple virtual servers based on a single IP address. And this feature is only applicable for TLS protocol. EC200U&EG91xU_Series_SSL_Application_Note 11 / 37 LTE Standard Module Series 2 Description of SSL AT Commands 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals to its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 4: Types of AT Command 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. EC200U&EG91xU_Series_SSL_Application_Note 12 / 37 LTE Standard Module Series 2.1.3. Declaration of AT Command Examples The AT command examples in this document are provided to help you familiarize with AT commands and learn how to use them. 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.2. Description of AT Commands 2.2.1. AT+QSSLCFG Configure Parameters of an SSL Context The command configures the SSL version, cipher suite, path of trusted CA certificate, authentication mode, the path of the client certificate and private key, etc. for the specified SSL context. These parameters will be used in the handshake procedure. is the index of the SSL context. The module supports 6 SSL contexts at most. On the basis of one SSL context, several SSL connections can be established. The settings such as the SSL version and the cipher suite are stored in the SSL context, and they will be applied to the new SSL connections associated with the SSL context. AT+QSSLCFG Configure Parameters of an SSL Context Test Command AT+QSSLCFG=? Response +QSSLCFG: 'sslversion',(range of supported s),(range of supported s) +QSSLCFG: 'dtls',(range of supported s),(li st of supported ) +QSSLCFG: 'ciphersuite',(range of supported s),(list of supported s) +QSSLCFG: 'seclevel',(range of supported s),(range of supported s) +QSSLCFG: 'cacert',(range of supported s), +QSSLCFG: 'clientcert',(range of supported s), +QSSLCFG: 'clientkey',(range of supported s), +QSSLCFG: 'sni',(range of supported s),(list of supported s) +QSSLCFG: 'ignorelocaltime',(range of supported s),(list of supported s) +QSSLCFG: 'negotiatetime',(range of supported s),(range of supported s) +QSSLCFG: 'ignoreinvalidcertsign',(range of supporte d s),(list of supported s) +QSSLCFG: 'ignorecertitem',(range of supported s),(range of supported s) +QSSLCFG: 'ignoremulticertchainverify',(range of supp orted s),(list of supported s) +QSSLCFG: 'session_cache',(range of supported s),(list of supported s) +QSSLCFG: 'dtlsversion',(range of supported s),(list of supported s) OK Write Command Response Configure the SSL version for the If the optional parameter is omitted, query the SSL version for specified SSL context: the specified SSL context: AT+QSSLCFG='sslversion',<SSL_ct +QSSLCFG: 'sslversion',, xID>[,] OK Write Command Configure the DTLS function for the specified SSL context: AT+QSSLCFG='dtls',[,< DTLS_enable>] If the optional parameter is specified, set the SSL version for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the DTLS function is enabled for the specified SSL context: +QSSLCFG: 'dtls',, OK If the optional parameter is specified, enable/disable the DTLS function for the specified SSL context: OK Or ERROR Write Command Response Configure the SSL cipher suites for the If the optional parameter is omitted, query the SSL cipher specified SSL context: suites for the specified SSL context: AT+QSSLCFG='ciphersuite',<SSL_c +QSSLCFG: 'ciphersuite',, txID>[,] EC200U&EG91xU_Series_SSL_Application_Note 14 / 37 LTE Standard Module Series OK Write Command Configure the authentication mode for the specified SSL context: AT+QSSLCFG='seclevel',[,] If the optional parameter is specified, set the SSL cipher suite for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query the authentication mode for the specified SSL context: +QSSLCFG: 'seclevel',, OK If the optional parameter is specified, set the authentication mode for the specified SSL context: OK Or ERROR Write Command Response Configure the path of trusted CA If the optional parameter is omitted, query the path of certificate for the specified SSL context: configured trusted CA certificate for the specified SSL context: AT+QSSLCFG='cacert', +QSSLCFG: 'cacert',, [,] OK Write Command Configure the path of client certificate for the specified SSL context: AT+QSSLCFG='clientcert',[,] If the optional parameter is specified, set the path of trusted CA certificate for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query the path of client certificate for the specified SSL context: +QSSLCFG: 'clientcert',, OK Write Command If the optional parameter is specified, set the path of client certificate for the specified SSL context: OK Or ERROR Response EC200U&EG91xU_Series_SSL_Application_Note 15 / 37 LTE Standard Module Series Configure the path of client private key for the specified SSL context: AT+QSSLCFG='clientkey',[,] If the optional parameter is omitted, query the path of client private key for the specified SSL context: +QSSLCFG: 'clientkey',, OK If the optional parameter is specified, set the path of client private key for the specified SSL context: OK Or ERROR Write Command Response Configure Server Name Indication If the optional parameter is omitted, query whether the Server feature for the specified SSL context: Name Indication feature is enabled for the specified SSL AT+QSSLCFG='sni',[,< context: SNI>] +QSSLCFG: 'sni',, OK Write Command Configure whether to ignore certificate validity period check for the specified SSL context: AT+QSSLCFG='ignorelocaltime',[,] If the optional parameter is specified, disable/enable Server Name Indication feature for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the certificate validity period check is ignored for the specified SSL context: +QSSLCFG: 'ignorelocaltime',, OK If the optional parameter is specified, set whether or not to ignore certificate validity check for the specified SSL context: OK Or ERROR Write Command Response Configure the maximum timeout in SSL If the optional parameter is omitted, query the maximum negotiation stage for the specified SSL timeout in SSL negotiation stage for the specified SSL context: context: AT+QSSLCFG='negotiatetime',<SSL +QSSLCFG: 'negotiatetime',,[,] me> EC200U&EG91xU_Series_SSL_Application_Note 16 / 37 LTE Standard Module Series OK Write Command Configure whether to ignore the invalid certificate signature for the specified SSL context: AT+QSSLCFG='ignoreinvalidcertsig n',[,] If the optional parameter is specified, set the maximum timeout in SSL negotiation stage for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the invalid certificate signature is ignored for the specified SSL context: +QSSLCFG: 'ignoreinvalidcertsign',, OK Write Command Configure whether the client ignores one or more checks specified in the certificate sent by the server for the specified SSL context: AT+QSSLCFG='ignorecertitem',[,] If the optional parameter is specified, set whether or not to ignore the invalid certificate signature for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the client ignores one or more checks specified in the certificate sent by the server for the specified SSL context: +QSSLCFG: 'ignorecertitem',, OK Write Command Configure whether to ignore multiple level certificate chain verification for the specified SSL context: AT+QSSLCFG='ignoremulticertchain verify',[,<ignore_multic If the optional parameter is specified, configure whether the client ignores one or more checks specified in the certificate sent by the server for the specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the multiple level certificate chain verification is ignored for the specified SSL context: +QSSLCFG: 'ignoremulticertchainverify',,< ignore_multicertchain_verify> EC200U&EG91xU_Series_SSL_Application_Note 17 / 37 LTE Standard Module Series ertchain_verify>] OK If the optional parameter is specified, set whether or not to ignore multiple level certificate chain verification for the specified SSL context: OK Or ERROR Write Command Response Enable or disable the specified SSL If the optional parameter is omitted, query whether the context session caching feature: specified SSL context enables SSL session caching: AT+QSSLCFG='session_cache',<SS +QSSLCFG: 'session_cache',,[,] che_enable> OK Write Command Configure the DTLS protocol version that specifies the SSL context: AT+QSSLCFG='dtlsversion',[,] If the optional parameter is specified, enable or disable the specified SSL context session caching feature: OK Or ERROR Response If the optional parameter is omitted, query the DTLS protocol version that specifies the SSL context: +QSSLCFG: 'dtlsversion',, OK Maximum Response Time Characteristics If the optional parameter is specified, configure the DTLS protocol version that specifies the SSL context: OK Or ERROR 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. SSL context ID. Range: 0–5. Integer type. SSL version. 0 SSL 3.0 EC200U&EG91xU_Series_SSL_Application_Note 18 / 37 LTE Standard Module Series 1 TLS 1.0 2 TLS 1.1 3 TLS 1.2 4 All Integer type. Enable/disable the DTLS function. 0 Disable 1 Enable Numeric type in HEX format. SSL cipher suites. 0X0035 TLS_RSA_WITH_AES_256_CBC_SHA 0X002F TLS_RSA_WITH_AES_128_CBC_SHA 0X0005 TLS_RSA_WITH_RC4_128_SHA 0X0004 TLS_RSA_WITH_RC4_128_MD5 0X000A TLS_RSA_WITH_3DES_EDE_CBC_SHA 0X003D TLS_RSA_WITH_AES_256_CBC_SHA256 0XC002 TLS_ECDH_ECDSA_WITH_RC4_128_SHA 0XC003 TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 0XC004 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 0XC005 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 0XC007 TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 0XC008 TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 0XC009 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 0XC00A TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 0XC011 TLS_ECDHE_RSA_WITH_RC4_128_SHA 0XC012 TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 0XC013 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 0XC014 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 0xC00C TLS_ECDH_RSA_WITH_RC4_128_SHA 0XC00D TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 0XC00E TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 0XC00F TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 0XC023 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 0xC024 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 0xC025 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 0xC026 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 0XC027 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 0XC028 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 0xC029 TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 0XC02A TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 0XC02F TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 0xC030 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 0XFFFF Support all cipher suites Integer type. The authentication mode. 0 No authentication 1 Perform server authentication EC200U&EG91xU_Series_SSL_Application_Note 19 / 37 LTE Standard Module Series 2 Perform server and client authentication if requested by the remote server String type. The path of the trusted CA certificate. String type. The path of the client certificate. String type. The path of the client private key. Integer type. Disable/enable Server Name Indication feature. 0 Disable 1 Enable Integer type. Whether or not to ignore validity period check of certificate. 0 Not to ignore 1 Ignore Integer type. Maximum timeout used in SSL negotiation stage. Range: 10–300. Default value: 300. Unit: second. Integer type. Indicates whether or not to ignore the invalid certificate signature. 0 Not to ignore 1 Ignore Integer type. Whether the client ignores one or more checks specified in the certificate sent by the server. The parameter applies an accumulative value if the client ignores more checks. 0 Not to ignore any check item 1 Ignore that the certificate validity has expired 4 Ignore the certificate common name does not match the expected common name 8 Ignore that the certificate is not correctly signed by the trusted CA 256 Ignore other reasons (The reason used to verify the callback) 2048 Ignore that usage does not match the keyUsage extension 4096 Ignore that usage does not match the extendedKeyUsage extension 8192 Ignore that usage does not match the nsCertType extension 32768 Ignore that the certificate signed with unacceptable public key algorithm (such as RSA, ECDSA) 65536 Ignore that the certificate signed with an unacceptable key 1048575 Ignore all check items, that is, not to check the certificate Integer type. Indicates whether or not to ignore the multiple level certificate chains verification. 0 Not to ignore 1 Ignore Integer type. Enable or disable the SSL context session caching feature. 0 Disable 1 Enable Integer type. DTLS version. 0 DTLS 1.0 1 DTLS 1.2 EC200U&EG91xU_Series_SSL_Application_Note 20 / 37 LTE Standard Module Series 2.2.2. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server The command sets up an SSL connection. During the negotiation between the module and the Internet, parameters configured by AT+QSSLCFG will be used in the handshake procedure. After shaking hands with the Internet successfully, the module can send or receive data via this SSL connection. Also, the module can set up several SSL connections based on one SSL context. According to steps mentioned in Chapter 1.3, execute AT+QIACT first to activate the PDP context and then execute AT+QSSLOPEN. It is suggested to wait for a specific period of time (refer to the Maximum Response Time below) for +QSSLOPEN: , URC to be outputted. If the URC response cannot be received during the time, AT+QSSLCLOSE can be used to close the SSL connection. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server Test Command AT+QSSLOPEN=? Response +QSSLOPEN: (range of supported s),(range of supported s),(range of supported s), ,[,(range of supported s)] OK Write Command Response AT+QSSLOPEN=,<SSL If the =2 and the SSL connection is _ctxID>,,,[,] CONNECT If there is any error: ERROR If the =0/1: OK +QSSLOPEN: , is 0 when SSL socket is opened successfully, and is not 0 when opening SSL socket fails. Maximum Response Time Characteristics If there is any error: ERROR Maximum network response time of 150 s, plus configured time of . The command takes effect immediately. The configurations are not saved. EC200U&EG91xU_Series_SSL_Application_Note 21 / 37 LTE Standard Module Series Parameter Integer type. PDP context ID. Range: 1–7. Integer type. SSL context ID. Range: 0–5. Integer type. Socket index. Range: 0–11. String type. The address of remote server. Integer type. The listening port of remote server. Integer type. The data access mode of SSL connection. 0 Buffer access mode 1 Direct push mode 2 Transparent access mode Integer type. The error code of the operation. See Chapter 5. Integer type. Maximum timeout in SSL negotiation stage. Range: 10–300. Default: 300. Unit: second. 2.2.3. AT+QSSLSEND Send Data via SSL Connection After the connection is established, the module can send data through the SSL connection. AT+QSSLSEND Send Data via SSL Connection Test Command AT+QSSLSEND=? Response +QSSLSEND: (range of supported s)[,(range of supported s)] Write Command Send variable-length data AT+QSSLSEND= OK Response > After the above response, input the data to be sent. Tap CTRL+Z to send, and tap ESC to cancel the operation. If the connection has been established and the data have been sent successfully: SEND OK If connection has been established but buffer is full: SEND FAIL Write Command Send fixed-length data AT+QSSLSEND=, If connection cannot be established, abnormally closed, or the parameter is incorrect: ERROR Response > After the above response, input the data until the data length EC200U&EG91xU_Series_SSL_Application_Note 22 / 37 LTE Standard Module Series Maximum Response Time Characteristics equals . If connection has been established and the data have been sent successfully: SEND OK If connection has been established but buffer is full: SEND FAIL If connection cannot be established, abnormally closed, or the parameter is incorrect: ERROR 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. Socket index. Range: 0–11. Integer type. The length of data to be sent. Range: 1–1460. Unit: byte. NOTE The data to be sent includes fixed-length data and variable-length data, and their maximum length is 1460 bytes. 2.2.4. AT+QSSLRECV Receive Data via SSL Connection When the data access mode of an SSL connection is buffer access mode, the module will report URC as +QSSLURC: 'recv', when it receives data from the Internet. You can read the data from buffer by AT+QSSLRECV. AT+QSSLRECV Receive Data via SSL Connection Test Command AT+QSSLRECV=? Response +QSSLRECV: (range of supported s),(range of supported s) Write Command AT+QSSLRECV=, OK Response If the specified connection has received data: +QSSLRECV: EC200U&EG91xU_Series_SSL_Application_Note 23 / 37 LTE Standard Module Series OK If the buffer is empty: +QSSLRECV: 0 OK If connection cannot be established, abnormally closed, or the parameter is incorrect: ERROR Write Command Response When is 0, query the If the specified connection exists: length of the read data: +QSSLRECV: ,<have_read_lengt AT+QSSLRECV=,0 h>, OK Maximum Response Time Characteristics If there is any error: ERROR 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. Socket index. Range: 0–11. Integer type. The length of data to be read. Range: 1–1500. Unit: byte. Integer type. The actual length of data read by AT+QSSLRECV. Unit: byte. The actual data read. Unit: byte. Integer type. The total length of the received data. Unit: byte. Integer type. The length of the read data. Unit: byte. Integer type. The length of the unread data. Unit: byte. 2.2.5. AT+QSSLCLOSE Close an SSL Connection The command closes an SSL connection. If all the SSL connections based on the same SSL context are closed, the module 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) EC200U&EG91xU_Series_SSL_Application_Note 24 / 37 LTE Standard Module Series Write Command AT+QSSLCLOSE=[,] OK Response If the SSL connection is successfully closed: OK Maximum Response Time Characteristics If there is any error: ERROR Determined by The command takes effect immediately. The configurations are not saved. Parameter Integer type. Socket index. Range: 0–11. Integer type. The timeout of executing AT+QSSLCLOSE. Range: 0–65535. Default: 10. Unit: second. 0 means immediate execution of the command. 2.2.6. AT+QSSLSTATE Query the State of SSL Connection The command queries the socket connection status, and can only query the SSL connection status. AT+QSSLSTATE Query the State of SSL Connection Test Command AT+QSSLSTATE=? Write Command AT+QSSLSTATE= Response OK Response +QSSLSTATE: ,'SSLClient',,,,,,,,, Execution Command AT+QSSLSTATE OK Response List of (+QSSLSTATE: ,'SSLClient',,,,,,,,,) Maximum Response Time Characteristics OK 300 ms / EC200U&EG91xU_Series_SSL_Application_Note 25 / 37 LTE Standard Module Series Parameter Integer type. PDP context ID. Range: 1–7. Integer type. Socket index. Range: 0–11. String type. The address of remote server. Integer type. The port of remote server. Range: 0–65535. Integer type. The local port. Range: 0–65535. Integer type. The state of SSL connection. 0 'Initial' Connection has not been established 1 'Opening' Client is connecting 2 'Connected' Client connection has been established 4 'Closing' Connection is closing Integer type. Reserved. Integer type. The access mode of SSL connection. 0 Buffer access mode 1 Direct push mode 2 Transparent access mode String type. COM port. Integer type. SSL context ID. Range: 0–5. EC200U&EG91xU_Series_SSL_Application_Note 26 / 37 LTE Standard Module Series 2.3. Description of URCs 2.3.1. +QSSLURC: 'recv' URC Indicating Incoming Data The URC notifies the host of received data which comes from the server. +QSSLURC: 'recv' URC Indicating Incoming Data +QSSLURC: 'recv', +QSSLURC: 'recv',, The URC of SSL data incoming in buffer access mode. The data can be received by AT+QSSLRECV. The URC of SSL data incoming in direct push mode. Parameter Integer type. Socket index. Range: 0–11. Integer type. The length of actual received data. Unit: byte. The actual data read. Unit: byte. 2.3.2. +QSSLURC: 'closed' Notify Abnormal Disconnection The URC notifies that the connection has been disconnected. Disconnection can be caused by many reasons. For example, the Internet closes the connection or the state of GPRS PDP is deactivated, and the SSL connection state based on the specified socket may be 'closing'. In such case, AT+QSSLCLOSE= must be executed to change the SSL connection state to 'initial'. +QSSLURC: 'closed' Notify Abnormal Disconnection +QSSLURC: 'closed', The SSL connection based on the specified socket is closed. Parameter Integer type. Socket index. Range: 0–11. EC200U&EG91xU_Series_SSL_Application_Note 27 / 37 LTE Standard Module Series 3 Examples 3.1. Configure and Activate a PDP Context 3.1.1. Configure a PDP Context AT+QICSGP=1,1,'UNINET','','',1 OK //Configure PDP context as 1. APN is 'UNINET' for China Unicom. 3.1.2. Activate a PDP Context AT+QIACT=1 OK AT+QIACT? +QIACT: 1,1,1,'10.7.157.1' //Activate PDP context as 1. //Activate successfully. //Query the state of PDP context. OK 3.1.3. Deactivate a PDP Context AT+QIDEACT=1 OK //Deactivate PDP context 1. //Deactivate successfully. 3.2. Configure an SSL Context AT+QSSLCFG='sslversion',1,1 OK AT+QSSLCFG='ciphersuite',1,0X0035 OK AT+QSSLCFG='seclevel',1,1 //Set SSL context ID and SSL version as 1. //Set SSL context ID as 1 and SSL cipher suites as TLS_RSA_WITH_AES_256_CBC_SHA. //Set SSL context ID as 1 and authentication mode as server authentication. EC200U&EG91xU_Series_SSL_Application_Note 28 / 37 LTE Standard Module Series OK AT+QSSLCFG='cacert',1,'UFS:cacert.pem' //Set SSL context ID as 1 and the path of the trusted CA certificate as UFS:cacert.pem. OK 3.3. SSL Client in Buffer Access Mode 3.3.1. Set up an SSL Connection and Enter Buffer Access Mode AT+QSSLOPEN=1,1,4,'220.180.239.212',8010,0 OK +QSSLOPEN: 4,0 //Set up an SSL connection successfully. AT+QSSLSTATE //Query the state of all SSL connections. +QSSLSTATE: 4,'SSLClient','220.180.239.212',8010,65344,2,1,4,0,'usbmodem',1 OK 3.3.2. Send Data in Buffer Access Mode 3.3.2.1. Send Variable-length Data AT+QSSLSEND=4 > Test data from SSL SEND OK //Send variable-length data. 3.3.2.2. Send Fixed-length Data AT+QSSLSEND=4,18 > Test data from SSL SEND OK //Send fixed-length data with the length of 18 bytes. EC200U&EG91xU_Series_SSL_Application_Note 29 / 37 LTE Standard Module Series 3.3.3. Receive Data in Buffer Access Mode +QSSLURC: 'recv',4 //The socket 4 ( = 4) has received data. AT+QSSLRECV=4,1500 +QSSLRECV: 18 Test data from SSL //Read data. The length of data to be read is 1500 bytes. //The length of actual retrieved data is 18 bytes. OK AT+QSSLRECV=4,1500 +QSSLRECV: 0 //No data in buffer. OK 3.3.4. Close an SSL Connection AT+QSSLCLOSE=4 OK //Close an SSL connection ( = 4). Depending on the network, the maximum response time is 10 s. 3.4. SSL Client in Direct Push Mode 3.4.1. Set up an SSL Connection and Enter Direct Push Mode AT+QSSLOPEN=1,1,4,'220.180.239.212',8011,1 OK +QSSLOPEN: 4,0 //Set up SSL connection successfully. AT+QSSLSTATE //Query the state of all SSL connections. +QSSLSTATE: 4,'SSLClient','220.180.239.212',8011,65047,2,1,4,1,'usbmodem',1 OK 3.4.2. Send Data in Direct Push Mode AT+QSSLSEND=4 > Test data from SSL SEND OK //Send variable-length data. EC200U&EG91xU_Series_SSL_Application_Note 30 / 37 AT+QSSLSEND=4,18 > Test data from SSL SEND OK LTE Standard Module Series //Send fixed-length data and the data length is 18 bytes. 3.4.3. Receive Data in Direct Push Mode +QSSLURC: 'recv',4,18 Test data from SSL 3.4.4. Close an SSL Connection AT+QSSLCLOSE=4 OK //Close an SSL connection ( = 4). Depending on the network, the maximum response time is 10 s. 3.5. SSL Client in Transparent Access Mode 3.5.1. Set up an SSL Connection and Send Data in Transparent Access Mode AT+QSSLOPEN= 1,1,4,'220.180.239.212',8011,2 //Set up an SSL connection. CONNECT //Enter transparent access mode. //Client is sending data from COM port to the Internet directly (The data is not visible in the example). OK //Use +++ or DTR (executing AT&D1 first) to exit transparent access mode. The NO CARRIER result code indicates that the server has stopped the SSL connection. 3.5.2. Set up an SSL Connection and Receive Data in Transparent Access Mode AT+QSSLOPEN= 1,1,4,'220.180.239.212',8011,2 //Set up an SSL connection. CONNECT //Enter transparent access mode. //Client is reading the data. OK //Use +++ or DTR (executing AT&D1 first) to exit transparent access mode. The NO CARRIER result code indicates that the server has stopped the SSL connection. EC200U&EG91xU_Series_SSL_Application_Note 31 / 37 LTE Standard Module Series 3.5.3. Close an SSL Connection AT+QSSLCLOSE=4 OK //Close an SSL connection ( = 4). Depending on the network, the maximum response time is 10 s. EC200U&EG91xU_Series_SSL_Application_Note 32 / 37 LTE Standard Module Series 4 Check for Failure in SSL Connection Please find out reasons for the failure in opening an SSL connection as follows: 1. Query the status of the specified PDP context by AT+QIACT? to check whether the specified PDP context has been activated. 2. Since an invalid DNS server address cannot convert domain name to IP address, if the address of remote server is a domain name, please check whether the address of DNS server is valid by AT+QIDNSCFG=. See document [1] for details of AT+QIDNSCFG. 3. Check the SSL configuration by AT+QSSLCFG, especially the SSL version and cipher suite, to make ensure that they are supported on server side. If has been configured as 1 or 2, then the trusted CA certificate has to be uploaded to the module with AT+QFUPL. If the server side has configured 'SSLVerifyClient required', then the client certificate and client private key have to be uploaded to the module with AT+QFUPL. For details about validity period check of certificate, please see Chapter 1.5. See document [2] for details of AT+QFUPL. EC200U&EG91xU_Series_SSL_Application_Note 33 / 37 LTE Standard Module Series 5 Error Codes If an ERROR or URC error code is returned after executing SSL AT commands, the details of error can be queried by AT+QIGETERROR. Please note that AT+QIGETERROR just returns error code of the latest SSL AT command. See document [1] for details of AT+QIGETERROR. Table 5: Error Codes 0 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 Description Operation successful Unknown error Operation blocked Invalid parameter Memory not enough Create socket failed Operation not supported Socket bind failed Socket listen failed Socket write failed Socket read failed Socket accept failed Open PDP context failed Close PDP context failed Socket identity has been used DNS busy EC200U&EG91xU_Series_SSL_Application_Note 34 / 37 LTE Standard Module Series 565 DNS parse failed 566 Socket connection failed 567 Socket has been closed 568 Operation busy 569 Operation timeout 570 PDP context break down 571 Cancel send 572 Operation not allowed 573 APN not configured 574 Port busy 579 SSL handshake fail EC200U&EG91xU_Series_SSL_Application_Note 35 / 37 LTE Standard Module Series 6 Appendix References Table 6: Related Documents Document Name [1] Quectel_EC200U&EG91xU_Series_TCP (IP)_Application_Note [2] Quectel_EC200U&EG91xU_Series_FILE_Application_Note [3] Quectel_EC200U&EG91xU_Series_AT_Commands_Manual Table 7: Terms and Abbreviations Abbreviation APN CA CR CMUX CN DNS DTR DTLS GPRS LF PDP PK PSK Description Access Point Name Certificate Authority Carriage Return Connection Multiplexing Common Name Domain Name Server Data Terminal Ready Datagram Transport Layer Security General Packet Radio Service Line Feed Packet Data Protocol Public Key Pre-Shared Key EC200U&EG91xU_Series_SSL_Application_Note 36 / 37 SNI SSL TCP/IP TLS UART UFS URC USB LTE Standard Module Series Server Name Indication Security Socket Layer Transmission Control Protocol/Internet Protocol Transport Layer Security Universal Asynchronous Receiver/Transmitter Universal Flash Storage Unsolicited Result Code Universal Serial Bus EC200U&EG91xU_Series_SSL_Application_Note 37 / 37

Quectel_EC200U&EG91xU_Series_SSL_Application_Note_V1.2

PDF

258.89 KB

EG800Q&EG91xQ Series SSL Application Note LTE Standard Module Series Version: 1.1 Date: 2023-09-15 Status: Released M10_ATC Confidential / Released 1 / 10 LTE Standard 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. EG800Q&EG91xQ_Series_SSL_Application_Note 1 / 38 LTE Standard 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. 2023. All rights reserved. EG800Q&EG91xQ_Series_SSL_Application_Note 2 / 38 LTE Standard Module Series About the Document Revision History Version 1.0 1.1 Date 2023-04-11 2023-06-13 2023-09-15 Author Greyson DONG Greyson DONG Greyson DONG Description Creation of the document First official release 1. Updated the applicable modules: ⚫ Added EG916Q-GL. ⚫ Updated EG800Q-EU to EG800Q series. 2. Added the command: AT+QSSLCFG='dtlsversion', [,] (Chapter 2.2.1). EG800Q&EG91xQ_Series_SSL_Application_Note 3 / 38 LTE Standard Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 6 1 Introduction .......................................................................................................................................... 7 1.1. SSL Version and Cipher Suite .................................................................................................... 7 1.2. Using SSL Function .................................................................................................................... 9 1.3. Description of Data Access Modes ........................................................................................... 10 1.4. Certificate Validity Check .......................................................................................................... 11 1.5. Server Name Indication ............................................................................................................ 11 2 Description of SSL AT Commands .................................................................................................. 12 2.1. AT Command Description ......................................................................................................... 12 2.1.1. Definitions....................................................................................................................... 12 2.1.2. AT Command Syntax ..................................................................................................... 12 2.1.3. Declaration of AT Command Examples ......................................................................... 13 2.2. Description of AT Commands ................................................................................................... 13 2.2.1. AT+QSSLCFG Configure Parameters of an SSL Context .......................................... 13 2.2.2. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server ........................ 23 2.2.3. AT+QSSLSEND Send Data over SSL Connection ..................................................... 24 2.2.4. AT+QSSLRECV Receive Data over SSL Connection ................................................ 26 2.2.5. AT+QSSLCLOSE Close an SSL Connection.............................................................. 27 2.2.6. AT+QSSLSTATE Query the State of SSL Connection................................................ 27 2.3. Description of URCs ................................................................................................................. 29 2.3.1. +QSSLURC: 'recv' Notify Received Data .................................................................. 29 2.3.2. +QSSLURC: 'closed' Notify Abnormal Disconnection ............................................... 29 3 Examples ............................................................................................................................................ 30 3.1. Configure and Activate a PDP Context..................................................................................... 30 3.1.1. Configure a PDP Context............................................................................................... 30 3.1.2. Activate a PDP Context.................................................................................................. 30 3.1.3. Deactivate a PDP Context ............................................................................................. 30 3.2. Configure an SSL Context ........................................................................................................ 30 3.3. SSL Client in Buffer Access Mode ............................................................................................ 31 3.3.1. Set up an SSL Connection and Enter Buffer Access Mode........................................... 31 3.3.2. Send Data in Buffer Access Mode ................................................................................. 31 3.3.3. Receive Data in Buffer Access Mode ............................................................................ 31 3.3.4. Close an SSL Connection .............................................................................................. 32 3.4. SSL Client in Direct Push Mode................................................................................................ 32 3.4.1. Set up an SSL Connection and Enter Direct Push Mode .............................................. 32 3.4.2. Send Data in Direct Push Mode..................................................................................... 32 3.4.3. Receive Data in Direct Push Mode ................................................................................ 33 3.4.4. Close an SSL Connection .............................................................................................. 33 EG800Q&EG91xQ_Series_SSL_Application_Note 4 / 38 LTE Standard Module Series 3.5. SSL Client in Transparent Transmission Mode ........................................................................ 33 3.5.1. Set up an SSL Connection and Send Data in Transparent Transmission Mode........... 33 3.5.2. Set up an SSL Connection and Receive Data in Transparent Transmission Mode ...... 33 3.5.3. Close an SSL Connection .............................................................................................. 33 4 Check for Failure in SSL Connection .............................................................................................. 34 5 Result Codes ...................................................................................................................................... 35 6 Appendix References ........................................................................................................................ 37 EG800Q&EG91xQ_Series_SSL_Application_Note 5 / 38 LTE Standard Module Series Table Index Table 1: SSL Versions .................................................................................................................................. 7 Table 2: Supported SSL Cipher Suites ........................................................................................................ 8 Table 3: Type of AT Commands ................................................................................................................. 12 Table 4: Result Codes ................................................................................................................................ 35 Table 5: Related Documents ...................................................................................................................... 37 Table 6: Terms and Abbreviations .............................................................................................................. 37 EG800Q&EG91xQ_Series_SSL_Application_Note 6 / 38 LTE Standard Module Series 1 Introduction Quectel EG800Q series and EG91xQ family (EG915Q-NA and EG916Q-GL) modules support SSL function. The SSL function is to ensure the privacy of communication. In some cases, the communication between the server and the client should be encrypted to prevent data from being eavesdropped, tampered with or forged during the communication process. This document introduces how to use the SSL function on Quectel EG800Q series and EG91xQ family modules through AT commands. 1.1. SSL Version and Cipher Suite The following SSL versions are supported. Table 1: SSL Versions SSL Versions SSL 3.0 TLS 1.2 TLS 1.1 TLS 1.0 The following table shows SSL cipher suites supported by Quectel EG800Q series and EG91xQ family modules, and all the SSL cipher suites are supported by default. For detailed description of cipher suites, see RFC 2246-The TLS Protocol Version 1.0. EG800Q&EG91xQ_Series_SSL_Application_Note 7 / 38 LTE Standard Module Series Table 2: Supported SSL Cipher Suites Codes of Cipher Suites Names of Cipher Suites 0X0035 TLS_RSA_WITH_AES_256_CBC_SHA 0X002F 0X0005 0X0004 0X000A TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_RC4_128_SHA TLS_RSA_WITH_RC4_128_MD5 TLS_RSA_WITH_3DES_EDE_CBC_SHA 0X003D TLS_RSA_WITH_AES_256_CBC_SHA256 0XC002 TLS_ECDH_ECDSA_WITH_RC4_128_SHA 0XC003 TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 0XC004 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 0XC005 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 0XC007 TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 0XC008 TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 0XC009 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 0XC00A TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 0XC011 TLS_ECDHE_RSA_WITH_RC4_128_SHA 0XC012 TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 0XC013 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 0XC014 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 0xC00C TLS_ECDH_RSA_WITH_RC4_128_SHA 0XC00D TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 0XC00E TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 0XC00F TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 0XC023 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 EG800Q&EG91xQ_Series_SSL_Application_Note 8 / 38 0xC024 0xC025 0xC026 0XC027 0XC028 0xC029 0XC02A 0XC02F 0XFFFF LTE Standard Module Series TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 Support all the cipher suites listed above 1.2. Using SSL Function Step 1: Configure , , and other parameters of a PDP context by AT+QICSGP. See document [1] for details. Step 2: Activate the PDP context by AT+QIACT, then query the assigned IP address by AT+QIACT?. See document [1] for details. Step 3: Configure the SSL version, cipher suite, path of trusted CA certificate, authentication mode, the path of the client certificate and private key, etc. for a specified SSL context by AT+QSSLCFG. Step 4: Open an SSL socket to connect a remote server by AT+QSSLOPEN. Step 5: After the SSL connection has been established, data will be sent or received over the connection. For details about how to send and receive data in each access mode, see Chapter 1.3. Step 6: Close SSL connection by AT+QSSLCLOSE. Step 7: Deactivate the PDP context by AT+QIDEACT. See document [1] for details. EG800Q&EG91xQ_Series_SSL_Application_Note 9 / 38 LTE Standard Module Series 1.3. Description of Data Access Modes The SSL connection supports the following three data access modes: ⚫ Buffer access mode ⚫ Direct push mode ⚫ Transparent transmission mode When opening an SSL connection over AT+QSSLOPEN, the data access mode can be specified by the . After the SSL connection has been established, AT+QISWTMD can be used to switch the data access mode. For details of AT+QISWTMD, see document [1] for details. 1. In buffer access mode, data can be sent via AT+QSSLSEND, and the module buffers data upon receiving them and reports a URC in the format of +QSSLURC: 'recv', to notify the host of the incoming data. In this case, the host can retrieve the buffered data with AT+QSSLRECV. 2. In direct push mode, data can be sent via AT+QSSLSEND, and the module outputs the received data directly over UART/USB modem/USB AT port in the format of +QSSLURC: 'recv',,. 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 +++. To prevent the +++ from being misinterpreted as data, follow the requirements below: a) Do not input any other character 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 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 [2]) 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 the as 2. Once transparent transmission mode is entered successfully, CONNECT is returned. OR EG800Q&EG91xQ_Series_SSL_Application_Note 10 / 38 LTE Standard Module Series 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. See document [2] for detailed information about ATO. 1.4. Certificate Validity Check To check certificate validity, the certificate must be parsed, and the local time compared with the 'Not before' and 'Not after' of the certificate. If the local time is earlier than the 'Not before' time or later than the 'Not after' time the certificate has expired. When validity check of certificate is required (set as 0 when executing AT+QSSLCFG), to avoid failure of certificate validity check, execute AT+CCLK to configure the module time within the validity time period of the certificate. For details of AT+CCLK, see document [2]. 1.5. Server Name Indication SNI (Server Name Indication) allows the server to safely host multiple TLS Certificates since it provides Server Host Name information as an extension in the client hello message. It thus enhances connection security with multiple virtual servers based on a single IP address. This feature is only applicable to TLS protocol. EG800Q&EG91xQ_Series_SSL_Application_Note 11 / 38 LTE Standard Module Series 2 Description of SSL AT Commands 2.1. AT Command Description 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 to its previous value or the default setting, 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: Type 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. EG800Q&EG91xQ_Series_SSL_Application_Note 12 / 38 LTE Standard Module Series 2.1.3. Declaration of AT Command Examples The AT command examples in this document are provided to help you familiarize with AT commands and learn how to use them. 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.2. Description of AT Commands 2.2.1. AT+QSSLCFG Configure Parameters of an SSL Context This command configures the SSL version, cipher suite, path of trusted CA certificate, authentication mode, the path of the client certificate and private key, etc. for a specified SSL context. These parameters will be used in the handshake procedure. is the index of the SSL context. The module supports 6 SSL contexts at most. On the basis of one SSL context, several SSL connections can be established. The settings such as the SSL version and the cipher suite are stored in the SSL context, and they will be applied to the new SSL connections associated with the SSL context. AT+QSSLCFG Configure Parameters of an SSL Context Test Command AT+QSSLCFG=? Response +QSSLCFG: 'sslversion',(range of supported s),(range of supported s) +QSSLCFG: 'seclevel',(range of supported s),(range of supported s) +QSSLCFG: 'ciphersuite',(range of supported s), +QSSLCFG: 'negotiatetime',(range of supported s),(range of supported s) +QSSLCFG: 'sni',(range of supported s),(li st of supported s) +QSSLCFG: 'cacert',(range of supported s), +QSSLCFG: 'cacertex',(range of supported s),< cacertexpath> +QSSLCFG: 'clientcert',(range of supported s), +QSSLCFG: 'clientkey',(range of supported s),, +QSSLCFG: 'dtls',(range of supported s), EG800Q&EG91xQ_Series_SSL_Application_Note 13 / 38 LTE Standard Module Series (list of supported s) +QSSLCFG: 'dtlsversion',(range of supported s),(range of supported s) +QSSLCFG: 'psk',(range of supported s), , +QSSLCFG: 'ignoremulticertchainverify',(range of sup ported s),(list of supported s) +QSSLCFG: 'ignoreinvalidcertsign',(range of supporte d s),(list of supported s) +QSSLCFG: 'ignorecertitem',(range of supported s),(list of supported s) +QSSLCFG: 'ignorelocaltime',(range of supported s),(list of supported s) +QSSLCFG: 'session_cache',(range of supported s),(list of supported s) +QSSLCFG: 'closetimemode',(range of supported s),(list of supported s) +QSSLCFG: 'renegotiation',(range of supported s),(list of supported s) +QSSLCFG: 'alpn',(range of supported s), Write Command Configure the SSL version for a specified SSL context: AT+QSSLCFG='sslversion',[,] OK Response If the optional parameter is omitted, query the SSL version for a specified SSL context: +QSSLCFG: 'sslversion',, OK Write Command Configure the authentication mode for a specified SSL context: AT+QSSLCFG='seclevel',[,] If the optional parameter is specified, set the SSL version for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query the authentication mode for a specified SSL context: +QSSLCFG: 'seclevel',, OK EG800Q&EG91xQ_Series_SSL_Application_Note 14 / 38 LTE Standard Module Series Write Command Configure the SSL cipher suites for a specified SSL context: AT+QSSLCFG='ciphersuite',[,] If the optional parameter is specified, set the authentication mode for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query the SSL cipher suites for a specified SSL context: +QSSLCFG: 'ciphersuite',, OK If the optional parameter is specified, set the SSL cipher suite for a specified SSL context: OK Or ERROR Write Command Response Configure the maximum timeout in SSL If the optional parameter is omitted, query the maximum negotiation stage for a specified SSL timeout in SSL negotiation stage for a specified SSL context: context: +QSSLCFG: 'negotiatetime',,<negotiate_ti AT+QSSLCFG='negotiatetime', ctxID>[,] OK If the optional parameter is specified, set the maximum timeout in SSL negotiation stage for a specified SSL context: OK Or ERROR Write Command Response Configure Server Name Indication feature If the optional parameter is omitted, query whether the for a specified SSL context: Server Name Indication feature is enabled for a specified AT+QSSLCFG='sni',[,] +QSSLCFG: 'sni',, OK Write Command If the optional parameter is specified, disable/enable Server Name Indication feature for a specified SSL context: OK Or ERROR Response EG800Q&EG91xQ_Series_SSL_Application_Note 15 / 38 LTE Standard Module Series Configure the path of trusted CA certificate for a specified SSL context: AT+QSSLCFG='cacert',[, ] If the optional parameter is omitted, query the path of trusted CA certificate for a specified SSL context: +QSSLCFG: 'cacert',, OK If the optional parameter is specified, set the path of trusted CA certificate for a specified SSL context: OK Or ERROR Write Command Response Configure the path of trusted CA If all optional parameters are omitted, query the path of certificate for a specified : trusted CA certificate chain for all SSL contexts: AT+QSSLCFG='cacertex'[,[,<c +QSSLCFG: 'cacertex',0, acertexpath>]] … +QSSLCFG: 'cacertex',5, OK If only is omitted, query the path of trusted CA certificate for a specified : +QSSLCFG: 'cacertex',, OK Write Command Configure the path of client certificate for a specified SSL context: AT+QSSLCFG='clientcert',[,] If all optional parameters are specified, set the path of trusted CA certificate for a specified : OK Or ERROR Response If the optional parameter is omitted, query the path of client certificate for a specified SSL context: +QSSLCFG: 'clientcert',, OK If the optional parameter is specified, set the path of client certificate for a specified SSL context: OK Or ERROR EG800Q&EG91xQ_Series_SSL_Application_Note 16 / 38 LTE Standard Module Series Write Command Configure the path of client private key for a specified SSL context: AT+QSSLCFG='clientkey',[,[,]] Response If the optional parameters are omitted, query the path of client private key for a specified SSL context: +QSSLCFG: 'clientkey',,, OK Write Command Configure the DTLS function for a specified SSL context: AT+QSSLCFG='dtls',[,] If the optional parameters are specified, set the path of client private key for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the DTLS function is enabled for a specified SSL context: +QSSLCFG: 'dtls',, OK Write Command Configure the DTLS version for a specified SSL context: AT+QSSLCFG='dtlsversion',[,] If the optional parameter is specified, enable/disable the DTLS function for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query the DTLS version supported by a specified SSL context: +QSSLCFG: 'dtlsversion',, OK Write Command Configure the PSK used in handshake for a specified SSL context: AT+QSSLCFG='psk',[,,] If the optional parameter is specified, configure the DTLS version for a specified SSL context: OK Or ERROR Response If the optional parameters are omitted, query the current configuration for a specified SSL context: +QSSLCFG: 'psk',,, OK EG800Q&EG91xQ_Series_SSL_Application_Note 17 / 38 LTE Standard Module Series If the optional parameters are specified, set the PSK used in handshake for a specified SSL context: OK Or ERROR Write Command Response Configure whether to ignore multiple level If the optional parameter is omitted, query whether the certificate chain verification for a specified multiple level certificate chain verification is ignored for a SSL context: specified SSL context: AT+QSSLCFG='ignoremulticertchainv +QSSLCFG: 'ignoremulticertchainverify',, erify',[,<ignore_multicert chain_verify>] OK Write Command Configure whether to ignore the invalid certificate signature for a specified SSL context: AT+QSSLCFG='ignoreinvalidcertsign' ,[,] If the optional parameter is specified, set whether or not to ignore multiple level certificate chain verification for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the invalid certificate signature is ignored for a specified SSL context: +QSSLCFG: 'ignoreinvalidcertsign',, OK Write Command Configure whether to ignore one or more checks specified in the certificate sent by the server for a specified SSL context: AT+QSSLCFG='ignorecertitem',[,] If the optional parameter is specified, set whether or not to ignore the invalid certificate signature for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether one or more checks specified in the certificate sent by the server is ignored for a specified SSL context: +QSSLCFG: 'ignorecertitem',, OK EG800Q&EG91xQ_Series_SSL_Application_Note 18 / 38 LTE Standard Module Series Write Command Configure whether to ignore certificate validity check for a specified SSL context: AT+QSSLCFG='ignorelocaltime',[,] If the optional parameter is specified, set whether or not to ignore one or more checks specified in the certificate sent by the server for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the certificate validity check is ignored for a specified SSL context: +QSSLCFG: 'ignorelocaltime',, OK Write Command Enable/Disable SSL session resumption function for a specified SSL context: AT+QSSLCFG='session_cache',[,] If the optional parameter is specified, set whether or not to ignore certificate validity check for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the SSL session resumption function is enabled for a specified SSL context: +QSSLCFG: 'session_cache',, OK Write Command Enable/disable the delay in closing the SSL connection for a specified SSL context: AT+QSSLCFG='closetimemode',[,] If the optional parameter is specified, enable/disable the SSL session resumption function: OK Or ERROR Response If the optional parameter is omitted, query whether the delay in closing the SSL connection is enabled for a specified SSL context: +QSSLCFG: 'closetimemode',, OK EG800Q&EG91xQ_Series_SSL_Application_Note 19 / 38 LTE Standard Module Series If the optional parameter is specified, enable/disable the delay in closing the SSL connection for a specified SSL context: OK Or ERROR Write Command Response Enable/disable TLS renegotiation If the optional parameter is omitted, query whether the TLS function for a specified SSL context: renegotiation function is enabled for a specified SSL context: AT+QSSLCFG='renegotiation',<SSL_ +QSSLCFG: 'renegotiation',,[,] n_enable> OK If the optional parameter is specified, enabled/disable the TLS renegotiation function for a specified SSL context: OK Or ERROR Write Command Response Configure the ALPN information for a If the optional parameter is omitted, query the ALPN specified SSL context: information for a specified SSL context: AT+QSSLCFG='alpn',[,< +QSSLCFG: 'alpn',, ALPN_name>] OK Maximum Response Time Characteristics If the optional parameter is specified, configure the ALPN information for a specified SSL context: OK Or ERROR 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. SSL context ID. Range: 0–5. Integer type. SSL version. 0 SSL 3.0 1 TLS 1.0 2 TLS 1.1 3 TLS 1.2 EG800Q&EG91xQ_Series_SSL_Application_Note 20 / 38 LTE Standard Module Series 4 All Integer type. The authentication mode. 0 No authentication 1 Perform server authentication 2 Perform server and client authentication if requested by the remote server Numeric type in HEX format. SSL cipher suites. 0X0035 TLS_RSA_WITH_AES_256_CBC_SHA 0X002F TLS_RSA_WITH_AES_128_CBC_SHA 0X0005 TLS_RSA_WITH_RC4_128_SHA 0X0004 TLS_RSA_WITH_RC4_128_MD5 0X000A TLS_RSA_WITH_3DES_EDE_CBC_SHA 0X003D TLS_RSA_WITH_AES_256_CBC_SHA256 0XC002 TLS_ECDH_ECDSA_WITH_RC4_128_SHA 0XC003 TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 0XC004 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 0XC005 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 0XC007 TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 0XC008 TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 0XC009 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 0XC00A TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 0XC011 TLS_ECDHE_RSA_WITH_RC4_128_SHA 0XC012 TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 0XC013 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 0XC014 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 0xC00C TLS_ECDH_RSA_WITH_RC4_128_SHA 0XC00D TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 0XC00E TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 0XC00F TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 0XC023 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 0xC024 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 0xC025 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 0xC026 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 0XC027 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 0XC028 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 0xC029 TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 0XC02A TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 0XC02F TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 0XFFFF Support all cipher suites Integer type. Indicates maximum timeout used in SSL negotiation stage. Range: 10–300. Default value: 300. Unit: second. Integer type. Disables/enables Server Name Indication feature. 0 Disable 1 Enable EG800Q&EG91xQ_Series_SSL_Application_Note 21 / 38 LTE Standard Module Series String type. The path of the trusted CA certificate. Integer type. The certificate index of the CA certificate chain. String type. The path of the trusted CA certificate. String type. The path of the client certificate. String type. The path of the client private key. String type. The password of the client private key. Integer type. Enables/disables the DTLS function. 0 Disable 1 Enable Integer type. Configures DTLS version. 0 DTLS1.0 1 DTLS1.2 2 ALL String type. Identity of PSK. The length is 0–255. String type. Key of PSK. The length is 0–255. Integer type. Indicates whether or not to ignore the multiple level certificate chains verification. 0 Not to ignore 1 Ignore Integer type. Indicates whether or not to ignore the invalid certificate signature. 0 Not to ignore 1 Ignore Integer type. Indicates whether the client ignores one or more checks specified in the certificate sent by the server. The parameter applies an accumulative value if the client ignores more checks. 0 Not ignore any check item in the certificate 1 Ignore that the certificate validity has expired 4 Ignore certificate common name does not match expected CN 8 Ignore that the certificate is not correctly signed by the trusted CA 256 Ignore other reasons (The reason used to verify the callback) 2048 Ignore Usage does not match keyUsage extension 4096 Ignore Usage does not match extendedKeyUsage extension 8192 Ignore Usage does not match nsCertType extension 32768 Ignore that the certificate signed with unacceptable public key algorithm (such as RSA, ECDSA) 65536 Ignore that the certificate signed with an unacceptable key 1048575 Ignore all check items, that is, not to check the certificate Integer type. Indicates whether or not to ignore certificate validity check. 0 Not to ignore 1 Ignore Integer type. Enables/disables the SSL session resumption function. 0 Disable 1 Enable EG800Q&EG91xQ_Series_SSL_Application_Note 22 / 38 LTE Standard Module Series Integer type. Enables/disables the delay in closing the SSL connection. 0 Disable, and the unit of SSL close linger time is second 1 Enable, and the unit of SSL close linger time is millisecond Integer type. Enable/disable the TLS renegotiation function. 0 Disable 1 Enable String type. Configures ALPN protocol name. When the content of this parameter is null (only double quotes are specified), TLS does not contain ALPN extension content. 2.2.2. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server This command sets up an SSL connection, that is, opens an SSL socket to connect a remote server. During the negotiation between the module and the Internet, parameters configured by AT+QSSLCFG will be used in the handshake procedure. After shaking hands with the Server successfully, the module can send or receive data over this SSL connection. Also, the module can set up several SSL connections based on one SSL context. According to steps mentioned in Chapter 1.2, before executing AT+QSSLOPEN, execute AT+QIACT first to activate the PDP context. It is suggested to wait for a specific period of time (refer to the Maximum Response Time below) for +QSSLOPEN: , URC to be outputted. If the URC response cannot be received during the time, AT+QSSLCLOSE can be used to close the SSL connection. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server Test Command AT+QSSLOPEN=? Response +QSSLOPEN: (range of supported s),(range of supported s),(range of supported s),,[,(range of supported s)] Write Command AT+QSSLOPEN=,,,,[,] OK Response If the =2 and the SSL connection is successfully set up: CONNECT If there is any error: ERROR Error description can be got over AT+QIGETERROR. If the =0/1: EG800Q&EG91xQ_Series_SSL_Application_Note 23 / 38 LTE Standard Module Series Maximum Response Time Characteristics OK +QSSLOPEN: , is 0 when SSL socket is opened successfully, and is not 0 when opening SSL socket fails. If there is any error: ERROR Error description can be got over AT+QIGETERROR. Maximum network response time of 150 s, plus configured time of . The command takes effect immediately. The configurations are not saved. Parameter Integer type. PDP context ID. Range: 1–15. Integer type. SSL context ID. Range: 0–5. Integer type. Socket index. Range: 0–11. String type. Remote server address. Integer type. Listening port of remote server. Integer type. The access mode of SSL connection. 0 Buffer access mode 1 Direct push mode 2 Transparent transmission mode Integer type. Result code. See Chapter 5 for details. Integer type. Indicates maximum timeout used in SSL negotiation stage. Range: 10–300. Default value: 300. Unit: second. 2.2.3. AT+QSSLSEND Send Data over SSL Connection After the connection is established, the module can send data through the SSL connection. AT+QSSLSEND Send Data over SSL Connection Test Command AT+QSSLSEND=? Response +QSSLSEND: (range of supported s)[,(range of supported s)] Write Command Send variable-length data AT+QSSLSEND= OK Response > After the above response, input the data to be sent. Tap CTRL+Z to send, and tap ESC to cancel the operation. EG800Q&EG91xQ_Series_SSL_Application_Note 24 / 38 LTE Standard Module Series If the connection has been established and sending is successful: SEND OK If connection has been established but sending buffer is full: SEND FAIL Write Command Send fixed-length data AT+QSSLSEND=, If the connection has not been established, abnormally closed, or any parameter is incorrect: ERROR Response > After the above response, input the data until the data length equals . If connection has been established and sending is successful: SEND OK If connection has been established but sending buffer is full, response: SEND FAIL Maximum Response Time Characteristics If the connection has not been established, abnormally closed, or any parameter is incorrect: ERROR 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. Socket index. Range: 0–11. Integer type. The length of sending data. Range: 1–1460. Unit: byte. NOTE The maximum length of fixed-length data or variable-length data is 1460 bytes. EG800Q&EG91xQ_Series_SSL_Application_Note 25 / 38 LTE Standard Module Series 2.2.4. AT+QSSLRECV Receive Data over SSL Connection When an SSL connection is opened with specified as 0, the module will report URC as +QSSLURC: 'recv', when it receives data from the Internet. You can read the data from buffer by AT+QSSLRECV. AT+QSSLRECV Receive Data over SSL Connection Test Command AT+QSSLRECV=? Response +QSSLRECV: (range of supported s),(range of supported s) Write Command AT+QSSLRECV=, OK Response If the specified socket connection has received data: +QSSLRECV: OK If the buffer is empty: +QSSLRECV: 0 OK Maximum Response Time Characteristics If the connection has not been established, abnormally closed, or any parameter is incorrect: ERROR 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. Socket index. Range: 0–11. Integer type. The length of data to be retrieved. Range: 1–1500. Unit: byte. Integer type. The actual data length obtained by AT+QSSLRECV. Unit: byte. The retrieved data. EG800Q&EG91xQ_Series_SSL_Application_Note 26 / 38 LTE Standard Module Series 2.2.5. AT+QSSLCLOSE Close an SSL Connection This command closes an SSL connection. If all SSL connections based on the same SSL context are closed, the module releases the SSL context. AT+QSSLCLOSE Close an SSL Connection Test Command AT+QSSLCLOSE=? Response +QSSLCLOSE: (range of supported s),(range of supported s) Write Command AT+QSSLCLOSE=[,] OK Response If the SSL connection is successfully closed: OK Maximum Response Time Characteristics If it is failed to close the connection: ERROR Determined by The command takes effect immediately. The configurations are not saved. Parameter Integer type. Socket index. Range: 0–11. Integer type. The timeout of executing AT+QSSLCLOSE. Range: 0–65535. Default value: 10. 0 means closing immediately. The unit of depends on the configuration of AT+QSSLCFG='closetimemode': if =0, the unit is second. If =1, the unit is microsecond. 2.2.6. AT+QSSLSTATE Query the State of SSL Connection This command queries the socket connection status and can only query the SSL connection status. AT+QSSLSTATE Query the State of SSL Connection Test Command AT+QSSLSTATE=? Write Command AT+QSSLSTATE= Response OK Response +QSSLSTATE: ,'SSLClient',,,,,,,,, OK EG800Q&EG91xQ_Series_SSL_Application_Note 27 / 38 Execution Command AT+QSSLSTATE Maximum Response Time Characteristics LTE Standard Module Series Response List of (+QSSLSTATE: ,'SSLClient',,,,,,,,,)s OK 300 ms / Parameter Integer type. Socket index. Range: 0–11. String type. Remote server address. Integer type. Remote server port. Range: 0–65535. Integer type. Local port. Range: 0–65535. Integer type. SSL connection state. 0 'Initial' Connection has not been established 1 'Opening' Client is connecting 2 'Connected' Client connection has been established 4 'Closing' Connection is closing Integer type. PDP context ID. Range: 1–15. Integer type. Reserved. Integer type. The access mode of SSL connection. 0 Buffer access mode 1 Direct push mode 2 Transparent transmission mode String type. The COM port. 'usbat' USB AT port 'uart1' Main UART 'usbmodem' USB Modem port 'uart2' Auxiliary UART Integer type. SSL context ID. Range: 0–5. EG800Q&EG91xQ_Series_SSL_Application_Note 28 / 38 LTE Standard Module Series 2.3. Description of URCs 2.3.1. +QSSLURC: 'recv' Notify Received Data The URC notifies the data received from peer in buffer access mode and direct push mode. +QSSLURC: 'recv' Notify Received Data +QSSLURC: 'recv', +QSSLURC: 'recv',, The URC of SSL data incoming in buffer access mode. SSL data can be received by AT+QSSLRECV. The URC of SSL data incoming in direct push mode. Parameter Integer type. Socket index. Range: 0–11. Integer type. The length of actual received data. Unit: byte. The received data. 2.3.2. +QSSLURC: 'closed' Notify Abnormal Disconnection The URC notifies that the SSL connection has been disconnected. Disconnection can be caused by many reasons. For example, the Internet closes the connection or the state of PDP is deactivated. The SSL connection state based on a specified socket will be 'closing'. In such case, AT+QSSLCLOSE= must be executed to change the SSL connection state to 'initial'. +QSSLURC: 'closed' Notify Abnormal Disconnection +QSSLURC: 'closed', The SSL connection based on the specified socket is closed. Parameter Integer type. Socket index. Range: 0–11. EG800Q&EG91xQ_Series_SSL_Application_Note 29 / 38 LTE Standard Module Series 3 Examples 3.1. Configure and Activate a PDP Context 3.1.1. Configure a PDP Context AT+QICSGP=1,1,'UNINET','','',1 OK //Configure context as 1. APN is 'UNINET' for China Unicom. 3.1.2. Activate a PDP Context AT+QIACT=1 OK AT+QIACT? +QIACT: 1,1,1,'10.7.157.1' //Activate context as 1. //Activated successfully. //Query the state of context. OK 3.1.3. Deactivate a PDP Context AT+QIDEACT=1 OK //Deactivate context 1. //Deactivated successfully. 3.2. Configure an SSL Context AT+QSSLCFG='sslversion',1,1 OK AT+QSSLCFG='ciphersuite',1,0X0035 OK AT+QSSLCFG='seclevel',1,1 OK //Set SSL context ID and SSL version as 1. //Set SSL context ID as 1 and SSL cipher suites as TLS_RSA_WITH_AES_256_CBC_SHA. //Set SSL context ID as 1 and authentication mode as perform server authentication. EG800Q&EG91xQ_Series_SSL_Application_Note 30 / 38 LTE Standard Module Series AT+QSSLCFG='cacert',1,'RAM:cacert.pem' //Set SSL context ID as 1 and the path of the trusted CA certificate as RAM:cacert.pem. OK 3.3. SSL Client in Buffer Access Mode 3.3.1. Set up an SSL Connection and Enter Buffer Access Mode AT+QSSLOPEN=1,1,4,'220.180.239.212',8010,0 OK +QSSLOPEN: 4,0 //Set up an SSL connection successfully. AT+QSSLSTATE //Query the status of all SSL connections. +QSSLSTATE: 4,'SSLClient','220.180.239.212',8010,65344,2,1,4,0,'usbmodem',1 OK 3.3.2. Send Data in Buffer Access Mode 3.3.2.1. Send Variable-Length Data AT+QSSLSEND=4 > Test data from SSL SEND OK //Send variable-length data. 3.3.2.2. Send Fixed-Length Data AT+QSSLSEND=4,18 > Test data from SSL SEND OK //Send fixed-length data with the data length of 18 bytes. 3.3.3. Receive Data in Buffer Access Mode +QSSLURC: 'recv',4 //The socket 4 (=4) has received data. AT+QSSLRECV=4,1500 //Read data. The length of data to be retrieved is 1500 bytes. EG800Q&EG91xQ_Series_SSL_Application_Note 31 / 38 +QSSLRECV: 18 Test data from SSL OK AT+QSSLRECV=4,1500 +QSSLRECV: 0 OK LTE Standard Module Series //The actual received data length is 18 bytes. //No data in buffer. 3.3.4. Close an SSL Connection AT+QSSLCLOSE=4 OK //Close an SSL connection (=4). Depending on the network, the maximum response time is 10 s. 3.4. SSL Client in Direct Push Mode 3.4.1. Set up an SSL Connection and Enter Direct Push Mode AT+QSSLOPEN=1,1,4,'220.180.239.212',8011,1 OK +QSSLOPEN: 4,0 //Set up SSL connection successfully. AT+QSSLSTATE //Query the status of all SSL connections. +QSSLSTATE: 4,'SSLClient','220.180.239.212',8011,65047,2,1,4,1,'usbmodem',1 OK 3.4.2. Send Data in Direct Push Mode AT+QSSLSEND=4 > Test data from SSL SEND OK AT+QSSLSEND=4,18 > Test data from SSL SEND OK //Send variable-length data. //Send fixed-length data and the data length is 18 bytes. EG800Q&EG91xQ_Series_SSL_Application_Note 32 / 38 LTE Standard Module Series 3.4.3. Receive Data in Direct Push Mode +QSSLURC: 'recv',4,18 Test data from SSL 3.4.4. Close an SSL Connection AT+QSSLCLOSE=4 OK //Close a connection (=4). Depending on the network, the maximum response time is 10 s. 3.5. SSL Client in Transparent Transmission Mode 3.5.1. Set up an SSL Connection and Send Data in Transparent Transmission Mode AT+QSSLOPEN=1,1,4,'220.180.239.212',8011,2 //Set up an SSL connection. CONNECT //Enter transparent transmission mode. //Client is sending data from COM port to the Internet directly. (The data is not visible in the example.) OK //Use +++ or DTR (set AT&D1 first) to exit transparent transmission mode. The NO CARRIER result code indicates that the server has stopped the SSL connection. 3.5.2. Set up an SSL Connection and Receive Data in Transparent Transmission Mode AT+QSSLOPEN=1,1,4,'220.180.239.212',8011,2 //Set up an SSL connection. CONNECT //Client is reading the data. OK //Use +++ or DTR (set AT&D1 first) to exit transparent transmission mode. The NO CARRIER result code indicates that the server has stopped the SSL connection. 3.5.3. Close an SSL Connection AT+QSSLCLOSE=4 OK //Close a connection (=4). Depending on the network, the maximum response time is 10 s. EG800Q&EG91xQ_Series_SSL_Application_Note 33 / 38 LTE Standard Module Series 4 Check for Failure in SSL Connection To identify reasons for the failure to open an SSL connection: 1. Query the status of the specified PDP context by AT+QIACT? to check whether the specified PDP context has been activated. 2. Since an invalid DNS server address cannot convert domain name to IP address, if the address of server is a domain name, check whether the DNS server address is valid by AT+QIDNSCFG=. See document [1] for detailed information about AT+QIDNSCFG. 3. Check the SSL configuration by AT+QSSLCFG, especially the SSL version and cipher suite to ensure that they are supported on server side. If has been configured as 1 or 2, then the trusted CA certificate has to be uploaded to the module with AT+QFUPL. If the server side has configured 'SSLVerifyClient required', then the client certificate and client private key have to be uploaded to the module with AT+QFUPL. For details about certificate validity check, see Chapter 1.4. see document [3] for more details of AT+QFUPL. EG800Q&EG91xQ_Series_SSL_Application_Note 34 / 38 LTE Standard Module Series 5 Result Codes If an ERROR or URC error code is returned after executing SSL AT commands, the details of errors can be queried by AT+QIGETERROR. Please note that AT+QIGETERROR just returns result code of the last SSL AT command. See document [1] for details of AT+QIGETERROR. Table 4: Result Codes 0 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 Description Operation successful Unknown error Operation blocked Invalid parameter Memory not enough Create socket failed Operation not supported Socket bind failed Socket listen failed Socket write failed Socket read failed Socket accept failed Open PDP context failed Close PDP context failed Socket identity has been used DNS busy EG800Q&EG91xQ_Series_SSL_Application_Note 35 / 38 LTE Standard Module Series 565 DNS parse failed 566 Socket connection failed 567 Socket has been closed 568 Operation busy 569 Operation timeout 570 PDP context break down 571 Cancel send 572 Operation not allowed 573 APN not configured 574 Port busy EG800Q&EG91xQ_Series_SSL_Application_Note 36 / 38 LTE Standard Module Series 6 Appendix References Table 5: Related Documents Document Name [1] Quectel_EG800Q&EG91xQ_Series_TCP(IP)_Application_Note [2] Quectel_EG800Q&EG91xQ_Series_AT_Commands_Manual [3] Quectel_EG800Q&EG91xQ_Series_FILE_Application_Note Table 6: Terms and Abbreviations Abbreviation ALPN APN CA DNS DTR DTLS PDP SNI SSL TCP/IP TLS UART URC Description Application Layer Protocol Negotiation Access Point Name Certificate Authority Domain Name Server Data Terminal Ready Datagram Transport Layer Security Packet Data Protocol Server Name Indication Security Socket Layer Transmission Control Protocol/Internet Protocol Transport Layer Security Universal Asynchronous Receiver/Transmitter Unsolicited Result Code EG800Q&EG91xQ_Series_SSL_Application_Note 37 / 38 USB Universal Serial Bus LTE Standard Module Series EG800Q&EG91xQ_Series_SSL_Application_Note 38 / 38

Quectel_EG800Q&EG91xQ_Series_SSL_Application_Note_V1.1

PDF

307.69 KB

EC200U&EG91xU Series MMS Application Note LTE Standard Module Series Version: 1.1 Date: 2023-09-12 Status: Released LTE Standard 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. EC200U&EG91xU_Series_MMS_Application_Note 1 / 27 LTE Standard 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. 2023. All rights reserved. EC200U&EG91xU_Series_MMS_Application_Note 2 / 27 LTE Standard Module Series About the Document Revision History Version Date Author - 2021-08-14 Lambert ZHAO 1.0 2021-11-15 Lambert ZHAO 1.1 2023-09-12 Lambert ZHAO Description Creation of the document First official release Added an applicable module EG912U-GL. EC200U&EG91xU_Series_MMS_Application_Note 3 / 27 LTE Standard Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 1.1. Applicable Modules .................................................................................................................... 6 1.2. The Process of Sending MMS Messages ................................................................................. 6 2 Description of MMS 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 MMS AT Commands ........................................................................................... 9 2.3.1. AT+QMMSCFG Configure Parameters of MMS .......................................................... 9 2.3.2. AT+QMMSEDIT Edit MMS Messages ....................................................................... 12 2.3.3. AT+QMMSEND Send MMS Messages...................................................................... 15 3 Examples ........................................................................................................................................... 16 3.1. Add Recipients ......................................................................................................................... 16 3.2. Add CC Recipients or BCC Recipients .................................................................................... 16 3.3. Edit the Title of MMS Messages .............................................................................................. 17 3.4. Add Attachments ...................................................................................................................... 17 3.5. Clear All Contents of MMS Messages ..................................................................................... 19 3.6. Send MMS Messages .............................................................................................................. 19 4 Error Handling ................................................................................................................................... 23 4.1. MMS AT Commands Execution Fails ...................................................................................... 23 4.2. PDP Activation Fails................................................................................................................. 23 4.3. Error Response of AT+QMMSEND.......................................................................................... 23 5 Error Codes ....................................................................................................................................... 24 6 HTTP(S) Response Codes................................................................................................................ 26 7 Appendix References ....................................................................................................................... 27 EC200U&EG91xU_Series_MMS_Application_Note 4 / 27 LTE Standard Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 6 Table 2: Types of AT Commands ................................................................................................................. 8 Table 3: Error Codes .................................................................................................................................. 24 Table 4: HTTP(S) Response Codes........................................................................................................... 26 Table 5: Related Documents ...................................................................................................................... 27 Table 6: Terms and Abbreviations .............................................................................................................. 27 EC200U&EG91xU_Series_MMS_Application_Note 5 / 27 LTE Standard Module Series 1 Introduction Quectel EC200U series and EG91xU family modules provide MMS application interfaces for sending messages including multimedia objects (image, audio, rich text, etc.). This document is a reference guide to all the AT commands defined for MMS. 1.1. Applicable Modules Table 1: Applicable Modules Module Family - EG91xU Module EC200U Series EG912U-GL EG915U Series 1.2. The Process of Sending MMS Messages Step 1: Configure and activate a PDP context. 1) Configure , , and other parameters of a PDP context by AT+QICSGP. See document [1] for more details. If QoS settings need to be updated, configure them by AT+CGQMIN and AT+CGQREQ. See document [2] for more details. 2) Activate the PDP context by AT+QIACT. 3) Configure the PDP context ID for MMS by AT+QMMSCFG='contextid',. Step 2: Configure URL and proxy of MMSC. 1) Configure the URL of MMSC by AT+QMMSCFG='mmsc',. 2) Configure the proxy of MMSC by AT+QMMSCFG='proxy',,. 3) Configure parameters to be used in sending a message by AT+QMMSCFG='sendpar am',,,,,,. EC200U&EG91xU_Series_MMS_Application_Note 6 / 27 LTE Standard Module Series Step 3: Edit an MMS message. 1) Add TO addresses by AT+QMMSEDIT=1,1,. 2) Add CC addresses by AT+QMMSEDIT=2,1,. 3) Add BCC addresses by AT+QMMSEDIT=3,1,. 4) Edit the title by AT+QMMSEDIT=4,1,. The character set of the title should be specified by AT+QMMSCFG='character', first. 5) Add attachments by AT+QMMSEDIT=5,1,. The attachments can be UFS, SFS, EFS, or SD files. And the files can be uploaded to UFS, SFS, EFS, or SD card by AT+QFUPL. See document [3] for details about this command. If the attachment is a text file, the character set should be specified by AT+QMMSCFG='character', first. Step 4: Send an MMS message by AT+QMMSEND=. It may take some time to successfully send an MMS message. Step 5: Clear the content of an MMS message by AT+QMMSEDIT=0 and delete attachments by AT+QFDEL. See document [3] for more details. When sending an MMS message to the same recipient again, step 4 to 5 can be repeated and when sending an MMS message to another recipient, step 2 to 5 can be repeated. NOTE The storage medium (file type) supported may vary in different modules. See document [3] for details. EC200U&EG91xU_Series_MMS_Application_Note 7 / 27 LTE Standard Module Series 2 Description of MMS 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 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. EC200U&EG91xU_Series_MMS_Application_Note 8 / 27 LTE Standard Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you familiarize with AT commands and learn how to use them. 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 MMS AT Commands 2.3.1. AT+QMMSCFG Configure Parameters of MMS This command configures PDP context ID, MMSC, proxy, character type and other MMS parameters. AT+QMMSCFG Configure Parameters of MMS Test Command AT+QMMSCFG=? Response +QMMSCFG: 'contextid',(range of supported s) +QMMSCFG: 'mmsc', +QMMSCFG: 'proxy',,(range of supported s) +QMMSCFG: 'character',(list of supported s) +QMMSCFG: 'sendparam'[,(range of supported s),(range of supported s),(list of supported s),(list of supported s),(range of supported s),(range of supported s)] +QMMSCFG: 'supportfield',(list of supported s) Read Command AT+QMMSCFG? Write Command AT+QMMSCFG='contextid'[,] OK Response OK Response If the optional parameter is omitted, query the current settings: +QMMSCFG: 'contextid', OK If the optional parameter is specified, configure the PDP context ID of MMS: OK EC200U&EG91xU_Series_MMS_Application_Note 9 / 27 LTE Standard Module Series Write Command AT+QMMSCFG='mmsc'[,] Or +CME ERROR: Response If the optional parameter is omitted, query the current settings: +QMMSCFG: 'mmsc', OK If the optional parameter is specified, configure MMSC URL: OK Write Command AT+QMMSCFG='proxy'[,,] Or +CME ERROR: Response If the optional parameters are omitted, query the current settings: +QMMSCFG: 'proxy',, OK If the optional parameters are specified, configure proxy gateway and port: OK Write Command AT+QMMSCFG='character'[,] Or +CME ERROR: Response If the optional parameter is omitted, query the current settings: +QMMSCFG: 'character', OK If the optional parameter is specified, configure the character format: OK Write Command AT+QMMSCFG='sendparam'[,,< Or +CME ERROR: Response If the optional parameters are omitted, query the current EC200U&EG91xU_Series_MMS_Application_Note 10 / 27 LTE Standard Module Series pri>,,,,] +QMMSCFG: 'sendparam',,,,< readrep>,, OK If the optional parameters are specified, configure sendparam properties: OK Write Command AT+QMMSCFG='supportfield'[,] Or +CME ERROR: Response If the optional parameter is omitted, query the current settings: +QMMSCFG: 'supportfield', OK If the optional parameter is specified, configure supportfield properties: OK Maximum Response Time Characteristics Or +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. The PDP context ID. Range: 1–7; default value: 1. String type. The address of MMSC. The maximum length of URL is 248 bytes. String type. The IP address of MMS proxy. The maximum length of gateway is 248 bytes. Integer type. The port of MMS proxy. Range: 1–65535; Default value: 80. String type. The type of character set. 'ASCII' US-ASCII character set 'UTF8' UTF8 character set 'UCS2' ISO-10646-UCS-2 character set. Big-endian order needs to be specified. 'GBK' GBK character set Integer type. The valid period of the MMS message. EC200U&EG91xU_Series_MMS_Application_Note 11 / 27 LTE Standard Module Series 0 1 hour 1 12 hours 2 24 hours 3 2 days 4 1 week 5 No limitation 6 Depend on network configuration Integer type. The priority of the MMS message. 0 Low 1 Normal 2 High 3 Depend on network configuration Integer type. Whether to deliver report. 0 No 1 Yes Integer type. Whether to read report. 0 No 1 Yes Integer type. Whether to hide address. 0 Hide all addresses 1 Show all addresses, including BCC address 2 Depend on network configuration Integer type. The class of the MMS message. 0 Personal 1 Advertisement 2 Informational 3 Automatic 4 Depend on network configuration Integer type. Whether to add the header option of MMS x-up-calling-id. 0 No 1 Yes The error code of operation. See Chapter 5 for details. 2.3.2. AT+QMMSEDIT Edit MMS Messages This command adds the recipient addresses, edit title and add attachments for MMS messages. The character set of title or text file should be specified by AT+QMMSCFG='character',. For example, if the content of a text file is presented as UTF8 character set, AT+QMMSCFG='character','UTF8' must be executed first. EC200U&EG91xU_Series_MMS_Application_Note 12 / 27 LTE Standard Module Series AT+QMMSEDIT Edit MMS Messages Test Command AT+QMMSEDIT=? Response +QMMSEDIT: (range of supported s),(list of supported s), Read Command AT+QMMSEDIT? Write Command AT+QMMSEDIT=[,[,]] OK Response OK Response 1) If the optional parameters are omitted: When is not 0 or 4, query the specified settings of : List of [+QMMSEDIT: ,] OK Or +CME ERROR: When =4, query the specified settings of : List of [+QMMSEDIT: ,,] OK Or +CME ERROR: When =0, delete all content of MMS message: OK Or +CME ERROR: 2) If any of the optional parameters is specified: When =0, needs to be omitted, which means deleting the specified settings of : OK Or +CME ERROR: EC200U&EG91xU_Series_MMS_Application_Note 13 / 27 LTE Standard Module Series Maximum Response Time Characteristics When =1, should be specified, which means setting the specified settings of : OK Or +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. Function operation. 0 Delete all content 1 Add TO address 2 Add CC address 3 Add BCC address 4 Add MMS message title 5 Add file as attachment Integer type. Enable/disable . 0 Delete the specified settings of . 1 Set the specified settings of . String type. The type of character set. 'ASCII' US-ASCII character set 'UTF8' UTF8 character set 'UCS2' ISO-10646-UCS-2 character set. Big-endian order needs to be specified 'GBK' GBK character set String type. If =1, 2 or 3, it is the recipient address. The maximum number of TO, CC and BCC addresses is 6 and the maximum length of the addresses is 128 bytes. If =4, it is the MMS message title. The maximum length of title is 256 bytes. If =5, it is the file name of attachment. If the file name starts with 'UFS', 'SFS', 'EFS', or 'SD', it indicates the file is from 'UFS', 'SFS', 'EFS', or 'SD' card respectively. The maximum length of file name is 128 bytes. The maximum number of attachments is 12, and the maximum size of attachments is restricted by the operator. The error code of operation. See Chapter 5 for details. EC200U&EG91xU_Series_MMS_Application_Note 14 / 27 LTE Standard Module Series NOTE The storage medium (file type) supported may vary in different modules. See document [3] for details. 2.3.3. AT+QMMSEND Send MMS Messages This command sends MMS messages. You should not re-execute AT+QMMSEND until +QMMSEND: ,[,] is returned. When the arrives, if the process of sending MMS messages has not finished yet, MMS sending will be interrupted. AT+QMMSEND Send MMS Messages Test Command AT+QMMSEND=? Response +QMMSEND: (range of supported s) Read Command AT+QMMSEND? Write Command AT+QMMSEND= OK Response OK Response OK Maximum Response Time Characteristics +QMMSEND: ,[,] Or +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. The maximum time to send MMS messages. Range: 1–65535; Unit: second. Integer type. The response code of HTTP(S), for reference only. For example, 200 indicates that HTTP(S) posts data successfully. See Chapter 6 for details. String type. The response string from MMSC when MMS messages sending fails. If MMS messages are sent successfully, is 0. Otherwise, indicates the error code of operation. See Chapter 5 for details. EC200U&EG91xU_Series_MMS_Application_Note 15 / 27 LTE Standard Module Series 3 Examples 3.1. Add Recipients //Add phone number or email address as a TO recipient. The maximum number of recipients is 6. AT+QMMSEDIT=1,1,'13856122546' OK AT+QMMSEDIT=1,1,'recipient .test@quectel.com' OK AT+QMMSEDIT=1 +QMMSEDIT: 1,'13856122546' +QMMSEDIT: 1,'recipient.test@quectel.com' //Add a phone number as a recipient. //Add an email address as a recipient. //Query the recipients’ address. OK //Delete the recipients by executing AT+QMMSEDIT=1,0. AT+QMMSEDIT=1,0 OK AT+QMMSEDIT=1 OK //Delete a recipient. //Query the recipients’ address. 3.2. Add CC Recipients or BCC Recipients //The operation of adding CC recipients differs from that of adding BCC recipients. For CC recipients, the value is 2. For BCC recipients, it is 3. AT+QMMSEDIT=2,1,'13856122546' //Add a phone number as a CC recipient. OK AT+QMMSEDIT=2 //Query the CC recipients’ address. +QMMSEDIT: 2,'13856122546' OK //Delete the CC recipient by executing AT+QMMSEDIT=2,0. AT+QMMSEDIT=2,0 OK AT+QMMSEDIT=2 //Delete the CC recipient. //Query the CC recipients’ address. EC200U&EG91xU_Series_MMS_Application_Note 16 / 27 LTE Standard Module Series OK 3.3. Edit the Title of MMS Messages //The character set of title is set by AT+QMMSCFG='character',. If the is 'ASCII', add the title as follows: AT+QMMSCFG='character','ASCII' //Set the charset as 'ASCII'. OK AT+QMMSEDIT=4,1,'test EC200U mms' //Edit the title of the MMS message. OK AT+QMMSEDIT=4 //Query the title of the MMS message. +QMMSEDIT: 4,'ASCII','test EC200U mms' OK //If the is not ASCII, the input data of should be hex string . AT+QMMSCFG='character', 'UTF8' //Set the charset as 'UTF8'. OK AT+QMMSEDIT=4,1,' 7465737420454332303055206D6D73' //Edit the title of MMS message. '7465737420454332303055206D6D73' is the hex string corresponding to 'test EC200U mms' in UTF8. OK AT+QMMSEDIT=4 //Query the title of the MMS message. +QMMSEDIT: 4,'UTF8','7465737420454332303055206D6D73' OK //Delete the title by executing AT+QMMSEDIT=4,0. AT+QMMSEDIT=4,0 OK AT+QMMSEDIT=4 //Delete the title of the MMS message. //Query the title of the MMS message. OK 3.4. Add Attachments //You can add attachments for an MMS message. The attachments can be UFS, SFS, EFS, and SD files. The storage medium (file type) supported may vary in different modules. See document [3] for details. The maximum number of attachments is 12 and the maximum length of file name is 128 bytes. The total size of attachments may be restricted by the operator. In the following example, the attachment is an UFS text file: EC200U&EG91xU_Series_MMS_Application_Note 17 / 27 LTE Standard Module Series AT+QFUPL='UFS:test_mms.txt',100,200,1 CONNECT +QFUPL: 100,612c //Upload a file to UFS. The file will be saved as test_mms.txt and the maximum size of the file is 100 bytes. 200 indicates timeout value, and 1 indicates enabling ACK mode. See document [3] for more details. OK AT+QFLST='UFS:*' +QFLST: 'UFS:test_mms.txt',100 //Query the file list of UFS. OK AT+QMMSCFG='character','ASCII' OK AT+QMMSEDIT=5,1,'UFS:test_mms.txt' OK AT+QMMSEDIT=5 +QMMSEDIT: 5,'UFS:test_mms.txt' //Set the charset as 'ASCII' for UFS:test_mms.txt. //Add attachments for the MMS message. //Query the attachments. OK //In the following example, the attachment is an UFS JPG file: AT+QFUPL='UFS:test_pic.jpg',200,300,1 //Upload a file to UFS. The file will be saved as test_pic.jpg and the maximum size of file is 200 bytes. 300 indicates timeout value, and 1 indicates enabling ACK mode. See document [3] for more details. CONNECT +QFUPL: 200,0000 OK AT+QFLST='UFS:*' +QFLST: 'UFS:test_mms.txt',100 +QFLST: 'UFS:test_pic.jpg',200 //Query the file list of UFS. OK AT+QMMSEDIT=5,1,'UFS:test_pic.jpg' OK AT+QMMSEDIT=5 +QMMSEDIT: 5,'UFS:test_mms.txt' +QMMSEDIT: 5,'UFS:test_pic.jpg' //UFS:test_pic.jpg is not a text file. There is no need to specify the character set. //Query the attachments. OK //Delete the attachments by AT+QMMSEDIT=5,0. EC200U&EG91xU_Series_MMS_Application_Note 18 / 27 LTE Standard Module Series AT+QMMSEDIT=5,0 //Delete all the attachments of the MMS message. OK AT+QMMSEDIT=5 //Query the attachments. OK //After sending the MMS message successfully, UFS files should be deleted by AT+QFDEL. AT+QFDEL='UFS:test_mms.txt' //Delete the UFS file. OK AT+QFDEL='UFS:test_pic.jpg' //Delete the UFS file. OK AT+QFLST='UFS:*' //Query the file list of UFS. OK 3.5. Clear All Contents of MMS Messages //Delete the content, recipients, CC recipients, BCC recipients, title and attachments of an MMS message by AT+QMMSEDIT=0. AT+QMMSEDIT=0 //Clear all contents of the MMS message. OK AT+QMMSEDIT=1 OK AT+QMMSEDIT=2 OK AT+QMMSEDIT=3 OK AT+QMMSEDIT=4 OK AT+QMMSEDIT=5 OK //Query recipients. //Query CC recipients. //Query BCC recipients. //Query title of the MMS message. //Query attachments. 3.6. Send MMS Messages //Step 1: Configure and activate a PDP context. AT+QICSGP=1,1,'UNIWAP','' ,'',1 OK AT+QIACT=1 OK AT+QIACT? +QIACT: 1,1,1,'10.7.157.1' //Configure PDP context 1. APN is 'UNIWAP' for China Unicom. //Activate PDP context 1. //Successful activation. //Query the state of PDP context. EC200U&EG91xU_Series_MMS_Application_Note 19 / 27 LTE Standard Module Series OK AT+QMMSCFG='contextid',1 OK AT+QMMSCFG='contextid' +QMMSCFG: 'contextid',1 //Set the PDP context ID as 1. The PDP context ID must be activated first. //Query the PDP context ID. OK //Step 2: Configure the URL and proxy of MMSC. AT+QMMSCFG='mmsc','mmsc.myuni.com' OK AT+QMMSCFG='mmsc' +QMMSCFG: 'mmsc','http://mmsc.myuni.com' //Configure the URL of MMSC. 'mmsc.myuni.com' is for China Unicom. //Query the URL of MMSC. OK AT+QMMSCFG='proxy','10.0.0.172',80 OK AT+QMMSCFG='proxy' +QMMSCFG: 'proxy','10.0.0.172',80 //Configure the proxy address and port of MMSC. '10.0.0.172:80' is for China Unicom. //Query the proxy address and port of MMSC. OK //Step 3: Configure the parameters to be used in sending message. AT+QMMSCFG='sendparam',6,2,0,0,2,4 //Configure the parameters. OK AT+QMMSCFG='sendparam' //Query the parameters. +QMMSCFG: 'sendparam',6,2,0,0,2,4 OK //Step 4: Edit the MMS message. AT+QMMSEDIT=1,1,'13856122546' OK AT+QMMSEDIT=2,1,'copy.test@quectel.com' OK AT+QMMSEDIT=3,1,'secret.test@quectel.com' OK AT+QMMSEDIT=1 +QMMSEDIT: 1,'13856122546' //Add a phone number as a TO recipient. //Add an email address as a CC recipient. //Add an email address as a BCC recipient. //Query the recipient address. OK AT+QMMSEDIT=2 +QMMSEDIT: 2,'copy.test@quectel.com' //Query the CC recipient address. EC200U&EG91xU_Series_MMS_Application_Note 20 / 27 LTE Standard Module Series OK AT+QMMSEDIT=3 +QMMSEDIT: 3,'secret.test@quectel.com' //Query the BCC recipient address. OK AT+QMMSCFG='character','ASCII' OK AT+QMMSEDIT=4,1,'test EC200U mms' OK AT+QMMSEDIT=4 +QMMSEDIT: 4,'ASCII','test EC200U mms' //Configure the character type as ASCII for title. //Edit the title of the MMS message. //Query the title of the MMS message. OK //Add attachments. AT+QFUPL='UFS:test.txt',100,300,1 CONNECT +QFUPL: 100,612c //Upload a file to UFS. The file will be saved as test.txt and the maximum size of file is 100 bytes. 300 indicates timeout value, and 1 indicates enabling ACK mode. See document [3] for more details. OK AT+QFLST='UFS:*' +QFLST: 'UFS:test.txt',100 //Query the file list of UFS. OK AT+QMMSCFG='character','ASCII' OK AT+QMMSEDIT=5,1,'UFS:test.txt' OK AT+QMMSEDIT=5 +QMMSEDIT: 5,'UFS:test.txt' //Configure the character type as ASCII for UFS:test.txt. //Add attachments for the MMS message. test.txt is an UFS file. //Query the attachments. OK AT+QFUPL='UFS:test_pic.jpg',200,300,1 CONNECT +QFUPL: 200,0000 //Upload a file to UFS. The file will be saved as test_pic.jpg and the maximum size of file is 200 bytes. 300 indicates timeout value, and 1 indicates enabling ACK mode. See document [3] for more details. EC200U&EG91xU_Series_MMS_Application_Note 21 / 27 LTE Standard Module Series OK AT+QFLST='UFS:*' +QFLST: 'UFS:test.txt',100 +QFLST: 'UFS:test_pic.jpg',200 //Query the file list of UFS. OK AT+QMMSEDIT=5,1,'UFS:test_pic.jpg' OK AT+QMMSEDIT=5 +QMMSEDIT: 5,'UFS:test.txt' +QMMSEDIT: 5,'UFS:test_pic.jpg' //UFS:test_pic.jpg is not a text file and there is no need to specify the character set. //Query the attachments. OK //Step 5: Send the MMS message. AT+QMMSEND=100 OK //Send the MMS message. +QMMSEND: 0,200 //Step 6: Clear content of the MMS message. AT+QMMSEDIT=0 OK AT+QFDEL='UFS:test.txt' OK AT+QFDEL='UFS:test_pic.jpg' OK //Indicate the result of sending the MMS message. //Clear the content of the MMS message. //Delete the UFS file. //Delete the UFS file. EC200U&EG91xU_Series_MMS_Application_Note 22 / 27 LTE Standard Module Series 4 Error Handling 4.1. MMS AT Commands Execution Fails When executing MMS AT commands, if response ERROR is received from the module, please check whether the (U)SIM card is inserted, and whether +CPIN: READY is returned when executing AT+CPIN?. 4.2. PDP Activation Fails If PDP context fails to be activated by AT+QIACT, please check the following configurations: 1. Query whether PS domain is attached or not by AT+CGATT?. If not, please execute AT+CGATT=1 to attach PS domain. 2. Query the PS domain status by AT+CGREG? and make sure the PS domain has been registered. 3. Query the PDP context parameters by AT+QICSGP and make sure the APN of specified PDP context has been set. 4. Make sure the specified PDP context ID is neither used by PPP nor activated by AT+CGACT. 5. Make sure the number of PDP context activated is within the limit. When the module supports one (U)SIM card, it can support the activation of 5 PDP contexts with VoLTE feature enabled and of 7 PDP contexts with VoLTE feature disabled. The number of PDP contexts which can be activated depends on the number of (U)SIM card. If all above configurations are correct, and the PDP context still fails to be activated by AT+QIACT, please reboot the module to resolve this issue. After rebooting the module, please execute the configurations mentioned above for at least three times at an interval of 10 minutes to avoid frequent rebooting. 4.3. Error Response of AT+QMMSEND +QMMSEND: ,[,] will be returned after executing AT+QMMSEND. If is not 0, it indicates that MMS sending fails, and please resend it. If resending fails, please deactivate the PDP context by AT+QIDEACT and re-activate it by AT+QIACT, then send the MMS message again. EC200U&EG91xU_Series_MMS_Application_Note 23 / 27 LTE Standard Module Series 5 Error Codes The error codes indicates errors related to mobile equipment or network. The details about are described in the following table. Table 3: Error Codes 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 Meaning Unknown error URL length error URL error Invalid proxy type Proxy address error Invalid parameter Recipient address full CC recipient address full BCC recipient address full Attachments full File error No recipient File not found MMS busy Server response failed Invalid report of HTTP(S) post Error response of HTTP(S) post EC200U&EG91xU_Series_MMS_Application_Note 24 / 27 768 PDP activation failed 769 PDP deactivated 770 Failed to create socket 771 Failed to connect socket 772 Failed to read socket 773 Failed to write socket 774 Socket closed 775 Timeout 776 Encode data error 777 HTTP(S) decode data error 778 OUT_OF_MEM LTE Standard Module Series EC200U&EG91xU_Series_MMS_Application_Note 25 / 27 LTE Standard Module Series 6 HTTP(S) Response Codes The HTTP(S) protocol response codes indicates response from MMSC. Please see RFC2616 (Hypertext Transfer Protocol--HTTP/1.1) for more details. is described in the following table. Table 4: HTTP(S) Response Codes 200 400 403 404 409 411 500 502 Meaning OK Bad request Forbidden Not found Conflict Length required Internal server error Bad gate way EC200U&EG91xU_Series_MMS_Application_Note 26 / 27 LTE Standard Module Series 7 Appendix References Table 5: Related Documents Document Name [1] Quectel_EC200U&EG91xU_Series_TCP(IP)_Application_Note [2] Quectel_EC200U&EG91xU_Series_AT_Commands_Manual [3] Quectel_EC200U&EG91xU_Series_FILE_Application_Note Table 6: Terms and Abbreviations Abbreviation BCC CC HTTP MMS MMSC PDP QoS SD UFS URL Description Blind Carbon Copy Carbon Copy Hypertext Transfer Protocol Multimedia Messaging Service Multimedia Messaging Service Center Packet Data Protocol Quality of Service Secure Digital User File Storage Uniform Resource Locator EC200U&EG91xU_Series_MMS_Application_Note 27 / 27

Quectel_EC200U&EG91xU_Series_MMS_Application_Note_V1.1

PDF

221.67 KB

L89 R2.0&LC29H (AA,BS)&LC79H (AL) EASY&EPOC Difference Introduction GNSS Module Series Version: 1.0 Date: 2023-08-31 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 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. L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 1 / 25 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 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. 2023. All rights reserved. L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 2 / 25 GNSS Module Series About the Document Document Information Title L89 R2.0&LC29H (AA,BS)&LC79H (AL) EASY&EPOC Difference Introduction Subtitle GNSS Module Series Document Type Difference Introduction Document Status Released Revision History Version 1.0 Date 2023-05-04 2023-08-31 Description Creation of the document First official release L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 3 / 25 GNSS Module Series Contents About the Document ................................................................................................................................3 Contents .................................................................................................................................................... 4 Table Index ...............................................................................................................................................5 Figure Index ..............................................................................................................................................6 1 Introduction .......................................................................................................................................7 1.1 Overview of EASY ....................................................................................................................7 1.2 Overview of EPOC ...................................................................................................................8 2 Differences.......................................................................................................................................10 3 Messages .........................................................................................................................................11 3.1. EASY-Related Messages ....................................................................................................... 11 3.1.1. Packet Type: 490 PAIR_EASY_ENABLE .................................................................... 11 3.1.2. Packet Type: 491 PAIR_EASY_GET_STATUS............................................................12 3.2. EPOC-Related Messages ......................................................................................................13 3.2.1. Packet Type: 496 PAIR_EPOC_ENABLE....................................................................13 3.2.2. Packet Type: 498 PAIR_EPOC_SET_CONFIG ...........................................................13 3.2.3. Packet Type: 507 PAIR_EPOC_CLEAR_DATA ...........................................................14 3.2.4. Packet Type: 508 PAIR_EPOC_GET_STATUS ...........................................................15 3.2.5. Packet Type: 509 PAIR_EPOC_GET_PREDICTION_STATUS ...................................16 3.3. EASY&EPOC-Related Messages ..........................................................................................17 3.3.1. Packet Type: 511 PAIR_NVRAM_SAVE_NAVIGATION_DATA....................................17 3.3.2. Packet Type: 512 PAIR_NVRAM_CLEAR_NAVIGATION_DATA.................................18 3.3.3. Packet Type: 513 PAIR_NVRAM_SAVE_SETTING ....................................................19 4 Applications.....................................................................................................................................20 4.1. EASY Application....................................................................................................................20 4.2. EPOC Application ...................................................................................................................21 5 Appendix A References ..................................................................................................................24 6 Appendix B Special Characters .....................................................................................................25 L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 4 / 25 GNSS Module Series Table Index Table 1: Applicable Modules ...................................................................................................................... 7 Table 2: EASY&EPOC Feature Differences ............................................................................................ 10 Table 3: EASY&EPOC Message Differences .......................................................................................... 10 Table 4: Related Documents ................................................................................................................... 24 Table 5: Terms and Abbreviations............................................................................................................ 24 Table 6: Special Characters .................................................................................................................... 25 L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 5 / 25 GNSS Module Series Figure Index Figure 1: Mechanism of EASY Function.................................................................................................... 8 Figure 2: Mechanism of EPOC Function ................................................................................................... 9 Figure 3: Recommended Process for Using EASY ................................................................................. 20 Figure 4: Recommended Process for Using EPOC................................................................................. 22 L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 6 / 25 GNSS Module Series 1 Introduction Quectel L89 R2.0, LC29H (AA, BS) and LC79H (AL) modules support EASY (Embedded Assist System) or EPOC (Enhanced Prediction Orbit on Chip) function that significantly improves the module’s TTFF. However, owing to technology and constellation updates, the original EASY function has been upgraded to EPOC function. Consequently, EASY will no longer be supported in subsequent firmware versions. This document outlines the differences between EASY and EPOC functions and their respective applications. The supported modules for these functions include: Table 1: Applicable Modules Module Series Model Software Version L89 R2.0 L89 (HA) L89 (HB) L89HANR01A07S and previous versions L89HBNR01A01S LC29H LC29H (AA) LC29H (BS) LC29HAANR11A01S and previous versions LC29HBSNR11A01S and previous versions LC79H LC79H (AL) LC79HALNR11A01S and previous versions Other software versions of the applicable modules Function EASY EPOC 1.1 Overview of EASY EASY is a solution designed to enhance the TTFF performance. It is an internal module application that predicts satellite orbits based on the received ephemeris data decoded from the ephemeris data broadcast by the satellites themselves. This way, the module does not need external network connectivity. Upon receiving the updated broadcast ephemeris data, the EASY function is automatically activated to predict satellite orbits for the following 3 days. EASY enters a standby state upon completion of the 3-day extension of satellite orbit prediction for all available SVs. EASY only supports GPS constellation. The figure below illustrates how the EASY function is activated and utilized by the module for orbit prediction during free time when it is not processing internal tasks. The EASY aiding data supplements the lack of the EPO (Extended Prediction Orbit) aiding data in scenarios L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 7 / 25 GNSS Module Series where the module may not have access to an external network and server derived predictions. Module process time TTFF Day 1 Day 2, Day 3,... GPS & EASY enabled GPS & EASY GPS & EASY enabled & EASY enabled & EASY assist data assist data GPS & EASY enabled & EASY assist data GPS & EASY enabled & EASY assist data TTFF 30 s 5 s ... ... ... ... ... Calculate satellite Receive new Calculate satellite Receive new orbit prediction on ephemeris, which orbit prediction on ephemeris, which free time triggers new prediction free time triggers new prediction Figure 1: Mechanism of EASY Function 1.2 Overview of EPOC EPOC is another internal module application designed to improve the TTFF performance by predicting GNSS constellation orbits using the received broadcast ephemeris data. EPOC aiding data serves as an alternative AGNSS method aimed at speeding up TTFF when the loss of EPO aiding data is caused by unavailability of external network connectivity. The figure below illustrates the operational mechanism of EPOC. On Day 1, TTFF is approximately 30 seconds without EPOC aiding data. Once the broadcast ephemerides are received, EPOC automatically activates the 3-day satellite orbit prediction process. Over the subsequent 72 hours, EPOC accelerates TTFF and ensures precise positioning. After completing the orbit prediction process for all available broadcast ephemerides, EPOC transitions to standby state until new broadcast ephemeris data becomes available. EPOC in contrast to EASY supports three options of constellation configurations: GPS only, GPS + Galileo, and GPS + BDS (MEO and IGSO). In each configuration, the module can receive and process data from L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 8 / 25 GNSS Module Series up to 40 satellites. If a particular constellation search is not turned on while EPOC prediction is enabled, the orbit will not be predicted for that constellation. Module process time TTFF Day 1 Day 2, Day 3,... GNSS & EPOC enabled GNSS & EPOC GNSS & EPOC enabled & EPOC enabled & EPOC assist data assist data GNSS & EPOC enabled & EPOC assist data GNSS & EPOC enabled & EPOC assist data TTFF 30 s 5 s ... ... ... ... ... Calculate satellite Receive new Calculate satellite Receive new orbit prediction on ephemeris, which orbit prediction on ephemeris, which free time triggers new prediction free time triggers new prediction Figure 2: Mechanism of EPOC Function L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 9 / 25 GNSS Module Series 2 Differences Both EPOC and EASY can predict satellite orbits for the upcoming 3 days. However, the main differences between them are: ⚫ EASY only supports GPS, whereas EPOC supports GPS, Galileo, and BDS; ⚫ EASY supports storing 1, 2, or 3 days of prediction data to RTC RAM whereas EPOC supports storing 3 days; ⚫ EPOC uses more commands/messages than EASY. See below for details. Table 2: EASY&EPOC Feature Differences Feature EASY Day(s) of prediction orbit automatically 1, 2 or 3 days stored in RTC RAM Supported satellite constellations GPS EPOC 3 days GPS GPS + Galileo GPS + BDS (MEO and IGSO) Table 3: EASY&EPOC Message Differences Feature Enable or disable EASY/EPOC Configure constellation(s) Clear data from NVM Get status of EASY/EPOC function Get prediction status Save current navigation data from RTC RAM to NVM Clear navigation data in both RTC RAM and NVM Save current configuration from RTC RAM to NVM EASY $PAIR490 $PAIR491 $PAIR491 $PAIR511 $PAIR512 $PAIR513 EPOC $PAIR496 $PAIR498 $PAIR507 $PAIR508 $PAIR509 $PAIR511 $PAIR512 $PAIR513 L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 10 / 25 GNSS Module Series 3 Messages 3.1. EASY-Related Messages 3.1.1. Packet Type: 490 PAIR_EASY_ENABLE Enables/disables EASY function. Type: Set Synopsis: $PAIR490,* Parameter: Field Format Unit Numeric - Description EASY function setting. 0 = Disable 1 = Enable Result: Returns $PAIR001 message. For details about $PAIR001, see documents [1], [2], or [3] protocol specifications. Example: $PAIR490,1*2A $PAIR001,490,0*36 L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 11 / 25 GNSS Module Series 3.1.2. Packet Type: 491 PAIR_EASY_GET_STATUS Gets the status of EASY function and prediction status (EASY data extension status). Type: Get Synopsis: $PAIR491* Parameter: None Result: Returns $PAIR001 message and the query result. For details about $PAIR001, see documents [1], [2], or [3] protocol specifications. Query result message format: $PAIR491,[,]* Parameters included in the result: Field Format Unit Numeric - Numeric - Description EASY function setting. 0 = Disabled 1 = Enabled EASY data extension status. 0 = Not finished 1 = 1-day extension finished 2 = 2-day extension finished 3 = 3-day extension finished Example: $PAIR491*36 $PAIR001,491,0*37 $PAIR491,1,0*37 NOTE If EASY function is disabled, only the value of will be returned after executing this command. L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 12 / 25 GNSS Module Series 3.2. EPOC-Related Messages 3.2.1. Packet Type: 496 PAIR_EPOC_ENABLE Enables/disables EPOC function. Type: Set Synopsis: $PAIR496,* Parameter: Field Format Unit Numeric - Description EPOC function setting. 0 = Disable 1 = Enable Result: Returns $PAIR001 message. For details about $PAIR001, see documents [1], [2], or [3] protocol specifications. Example: $PAIR496,1*2C $PAIR001,496,0*30 3.2.2. Packet Type: 498 PAIR_EPOC_SET_CONFIG Sets EPOC constellation configuration. Type: Set Synopsis: $PAIR498,* L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 13 / 25 GNSS Module Series Parameter: Field Format Unit Numeric - Description EPOC constellation configuration. Default configuration: GPS. Bit 0 = GPS Bit 1 = Galileo Bit 2 = BDS Result: Returns $PAIR001 message. For details about $PAIR001, see documents [1], [2], or [3] protocol specifications. Example: $PAIR498,1*22 $PAIR001,498,0*3E NOTE is a decimal value. Only GPS, GPS + Galileo, and GPS + BDS are available. 3.2.3. Packet Type: 507 PAIR_EPOC_CLEAR_DATA Clears all EPOC data from NVM. Type: Command Synopsis: $PAIR507* Parameter: None Result: Returns $PAIR001 message. For details about $PAIR001, see documents [1], [2], or [3] protocol specifications. L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 14 / 25 Example: $PAIR507*38 $PAIR001,507,0*39 GNSS Module Series 3.2.4. Packet Type: 508 PAIR_EPOC_GET_STATUS Gets the status of EPOC function and constellation configuration. Type: Get Synopsis: $PAIR508* Parameter: None Result: Returns $PAIR001 message and the query result. For details about $PAIR001, see documents [1], [2], or [3] protocol specifications. Query result message format: $PAIR508,,* Parameters included in the result: Field Format Unit Numeric - Numeric - Description EPOC function setting. 0 = Disabled 1 = Enabled EPOC constellation configuration. Bit 0 = GPS Bit 1 = Galileo Bit 2 = BDS Example: $PAIR508*37 $PAIR001,508,0*36 $PAIR508,1,1*37 L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 15 / 25 GNSS Module Series 3.2.5. Packet Type: 509 PAIR_EPOC_GET_PREDICTION_STATUS Gets EPOC prediction status. Type: Get Synopsis: $PAIR509,* Parameter: Field Format Unit Numeric - Description EPOC constellation configuration. Bit 0 = GPS Bit 1 = Galileo Bit 2 = BDS Result: Returns $PAIR001 message and the query result. For details about $PAIR001, see documents [1], [2], or [3] protocol specifications. Query result message format: $PAIR509,,,* Parameters included in the result: Field Format Unit Numeric - Numeric - Hexadecimal - Description Prediction status. 1 = Prediction in progress. 2 = All received ephemeris data have been calculated for prediction. 3 = No valid ephemeris data. EPOC constellation configuration. Bit 0 = GPS Bit 1 = Galileo Bit 2 = BDS Satellite available bitmask. Bit number represents satellite ID and '1' in a specific bit position indicates that the orbit prediction for the corresponding satellite is complete. L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 16 / 25 Example: $PAIR509,1*2B $PAIR001,509,0*37 $PAIR509,2,1,00000000000D2D2C*6A GNSS Module Series NOTE : Satellite number in bitwise format. For example, '00000000000D2D2C' indicates that the 3-day predictions for satellites 3, 4, 6, 9, 11, 12, 14, 17, 19, and 20 have been completed. 3.3. EASY&EPOC-Related Messages 3.3.1. Packet Type: 511 PAIR_NVRAM_SAVE_NAVIGATION_DATA Saves current navigation data from RTC RAM to NVM. Type: Command Synopsis $PAIR511* Parameter: None Result: Returns $PAIR001 message. For details about $PAIR001, see documents [1], [2], or [3] protocol specifications. Example: //If the position fix rate is 1 Hz. $PAIR511*3F $PAIR001,511,0*3E //If the position fix rate exceeds 1 Hz. For L89 R2.0, executing $PAIR382 is not required. $PAIR382,1*2E $PAIR001,382,0*32 $PAIR003*39 $PAIR001,003,0*38 L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 17 / 25 $PAIR511*3F $PAIR001,511,0*3E $PAIR002*38 $PAIR001,002,0*39 GNSS Module Series NOTE 1. If the backup domain cannot be powered after the power supply of the module is cut off, you must send $PAIR511 every time the parameters are modified. 2. If the position fix rate exceeds 1 Hz, power off the GNSS system with $PAIR382,1*2E (not required for L89 R2.0) and $PAIR003*39 in sequence before sending this command. After sending $PAIR511*3F, re-power the module with $PAIR002*38. This limitation does not apply to position fix rates below 1 Hz. 3.3.2. Packet Type: 512 PAIR_NVRAM_CLEAR_NAVIGATION_DATA Clears navigation data in both RTC RAM and NVM. Type: Command Synopsis $PAIR512* Parameter: None Result: Returns $PAIR001 message. For details about $PAIR001, see documents [1], [2], or [3] protocol specifications. Example: $PAIR512*3C $PAIR001,512,0*3D L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 18 / 25 GNSS Module Series 3.3.3. Packet Type: 513 PAIR_NVRAM_SAVE_SETTING Saves current configuration from RTC RAM to NVM. Type: Command Synopsis: $PAIR513* Parameter: None Result: Returns $PAIR001 message. For details about $PAIR001, see documents [1], [2], or [3] protocol specifications. Example: //If the position fix rate is 1 Hz. $PAIR513*3D $PAIR001,513,0*3C //If the position fix rate exceeds 1 Hz. For L89 R2.0, executing $PAIR382 is not required. $PAIR382,1*2E $PAIR001,382,0*32 $PAIR003*39 $PAIR001,003,0*38 $PAIR513*3D $PAIR001,513,0*3C $PAIR002*38 $PAIR001,002,0*39 NOTE 1. If the backup domain cannot be powered after the power supply of the module is cut off, you must send $PAIR513 every time the parameters are modified. 2. If the position fix rate exceeds1 Hz, power off the GNSS system with $PAIR382,1*2E (not required for L89 R2.0) and $PAIR003*39 in sequence before sending this command. After sending $PAIR513*3D, re-power the module with $PAIR002*38. This limitation does not apply to position fix rates below 1 Hz. L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 19 / 25 GNSS Module Series 4 Applications This chapter explains how to use EASY and EPOC functions, which have similar usage steps. 4.1. EASY Application The recommended process for utilizing the EASY function is illustrated below: Start Use EASY function? N Y Enable EASY Get EASY status Disable EASY N Enabled EASY N successfully? Get EASY status N Y Prediction is finished? Disabled EASY successfully? Y End Y Figure 3: Recommended Process for Using EASY L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 20 / 25 Example: //1. Enable EASY function. //Enable EASY: $PAIR490,1*2A $PAIR001,490,0*36 //Get EASY status: $PAIR491*36 $PAIR001,491,0*37 $PAIR491,1,0*37 //2. Disable EASY function. //Disable EASY: $PAIR490,0*2B $PAIR001,490,0*36 //Get EASY status: $PAIR491*36 $PAIR001,491,0*37 $PAIR491,0,0*36 GNSS Module Series NOTE Performing 'Enable EASY' is optional since EASY is enabled by default. 4.2. EPOC Application The recommended process for utilising the EPOC function is illustrated below: L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 21 / 25 Start Use EPOC function? GNSS Module Series Configure constellation? N Y Configure constellation Get EPOC N constellation configuration N Configured successfully? Y Enable EPOC N Get EPOC status Enabled EPOC successfully? Y Get EPOC prediction status N Prediction is complete? Y End Disable EPOC Get EPOC N status Disabled EPOC successfully? Y Figure 4: Recommended Process for Using EPOC L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 22 / 25 Example: //1. Enable EPOC function. //Set EPOC constellation configuration: $PAIR498,1*22 $PAIR001,498,0*3E //Get EPOC constellation configuration: $PAIR508*37 $PAIR001,508,0*36 $PAIR508,0,1*36 //Enable EPOC: $PAIR496,1*2C $PAIR001,496,0*30 //Get EPOC status: $PAIR508*37 $PAIR001,508,0*36 $PAIR508,1,1*37 //Get EPOC prediction status: $PAIR509,1*2B $PAIR001,509,0*37 $PAIR509,2,1,00000000000D2D2C*6A //2. Disable EPOC function. //Disable EPOC: $PAIR496,0*2D $PAIR001,496,0*30 //Get EPOC status: $PAIR508*37 $PAIR001,508,0*36 $PAIR508,0,1*36 GNSS Module Series NOTE Performing 'Enable EPOC' is optional since EPOC is enabled by default. L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 23 / 25 GNSS Module Series 5 Appendix A References Table 4: Related Documents Document Name [1] Quectel_L89_R2.0_GNSS_Protocol_Specification [2] Quectel_LC29H(BS)_GNSS_Protocol_Specification [3] Quectel_LC29H_Series&LC79H(AL)_GNSS_Protocol_Specification Table 5: Terms and Abbreviations Abbreviation EASY EPO EPOC GNSS IGSO MEO NVM SV TTFF Description Embedded Assist System Extended Prediction Orbit Enhanced Prediction Orbit on Chip Global Navigation Satellite System Inclined Geosynchronous Orbit Medium Earth Orbit Non-Volatile Memory Satellites in View Time To First Fix L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 24 / 25 GNSS Module Series 6 Appendix B Special Characters Table 6: Special Characters Special Character […] {…} Underline Description Carriage return character. Line feed character. Parameter name. Angle brackets do not appear in the message. Optional field of a message. Square brackets do not appear in the message. Repeated field of a message. Curly brackets do not appear in the message. Default setting of a parameter. L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction 25 / 25

Quectel_L89_R2.0&LC29H(AA,BS)&LC79H(AL)_EASY&EPOC_Difference_Introduction_V1.0

PDF

323.32 KB

LG69T (AM,AP) DR&RTK Application Note GNSS Module Series Version: 1.0 Date: 2023-08-10 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. LC69T(AM,AP)_DR&RTK_Application_Note 1 / 31 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. 2023. All rights reserved LC69T(AM,AP)_DR&RTK_Application_Note 2 / 31 GNSS Module Series About the Document Document Information Title Subtitle Document Type Document Status LG69T (AM,AP) DR&RTK Application Note GNSS Module Series Application Note Released Revision History Version 1.0.0 Date 2023-06-12 2023-08-10 Description Creation of the document First official release LC69T(AM,AP)_DR&RTK_Application_Note 3 / 31 GNSS Module Series Contents About the Document ................................................................................................................................... 4 Contents ....................................................................................................................................................... 5 Table Index................................................................................................................................................... 6 Figure Index ................................................................................................................................................. 7 1 Introduction .......................................................................................................................................... 8 1.1. Overview on DR .......................................................................................................................... 8 1.2. Overview on RTK ........................................................................................................................ 9 2 Configuration...................................................................................................................................... 10 2.1. DR Configuration....................................................................................................................... 10 2.1.1. Orientation...................................................................................................................... 10 2.1.2. Mounting......................................................................................................................... 11 2.1.3. DR Calibration ................................................................................................................ 12 3 RTK Input ............................................................................................................................................ 14 4 PQTM Messages................................................................................................................................. 15 4.1. PQTMPVT ................................................................................................................................. 15 4.2. PQTMDRPVA............................................................................................................................ 17 4.3. PQTMSENMSG ........................................................................................................................ 19 4.3.1. When = 2 ...................................................................................................... 20 4.4. PQTMVEHMSG ........................................................................................................................ 21 4.4.1. When = 1.................................................................................................... 21 4.5. PQTMCFGCAN......................................................................................................................... 22 4.6. PQTMCFGCANFILTER ............................................................................................................ 23 4.7. PQTMCFGVEHDBC ................................................................................................................. 25 4.8. PQTMCFGVEHRVAL................................................................................................................ 27 4.9. PQTMCFGLA............................................................................................................................ 28 5 Appendix A References..................................................................................................................... 30 6 Appendix B Special Characters ....................................................................................................... 32 LC69T(AM,AP)_DR&RTK_Application_Note 4 / 31 GNSS Module Series Table Index Table 1: Supported RTCM Input Messages ............................................................................................... 14 Table 2: Error Code .................................................................................................................................... 15 Table 3: Related Documents ...................................................................................................................... 30 Table 4: Terms and Abbreviations .............................................................................................................. 30 Table 5: Special Characters ....................................................................................................................... 32 LC69T(AM,AP)_DR&RTK_Application_Note 5 / 31 GNSS Module Series Figure Index Figure 1: Four-Wheel Vehicle....................................................................................................................... 8 Figure 2: RTK Schematic Diagram .............................................................................................................. 9 Figure 3: Reference Frame ........................................................................................................................ 10 Figure 4: IMU Reference Frame .................................................................................................................11 Figure 5: Installation Yaw Angle ..................................................................................................................11 Figure 6: Installation Pitch Angle................................................................................................................ 12 Figure 7: Installation Roll Angle.................................................................................................................. 12 LC69T(AM,AP)_DR&RTK_Application_Note 6 / 31 GNSS Module Series 1 Introduction This document describes the dead reckoning (DR) and real-time kinematic (RTK) features, including orientation, mounting, calibration, and messages related to DR and RTK of Quectel LG69T (AM) and LG69T (AP). The supported features on each module are as follows: ⚫ LG69T (AM) supports RTK only. ⚫ LG69T (AP) supports DR and RTK. The modules are recommended for use in four-wheel vehicle. Figure 1: Four-Wheel Vehicle 1.1. Overview on DR Quectel LG69T (AP) supports the ADR mode, where the module utilizes speed data from the vehicle and the onboard 6-axis sensor to enhance accuracy in environments without GNSS coverage. The module obtains vehicle speed data through CAN interface, supporting receiving data that conforms to ISO11898-1 standard. The vehicle speed requirement includes a minimum injection frequency of 10 Hz, delay below 10 ms, and speed RMS below 0.5 m/s. LC69T(AM,AP)_DR&RTK_Application_Note 7 / 31 GNSS Module Series 1.2. Overview on RTK Quectel offers high-precision RTK positioning products that support multiple GNSS constellations and frequencies, enabling centimeter-level accuracy. RTK (Real Time Kinematic) is a real-time differential GPS (RTDGPS) technology based on carrier phase observations. It consists of three components: a base station (which may be an actual satellite receiver or a virtual reference station (VRS), differential correction data link, and rover. The base station continuously observes GNSS satellites, and transmits its observation data and station information to the rover in real-time through a data transmission network. While receiving GNSS satellite signals, the rover uses the data transmitted by the base station through wireless receiving equipment to calculate its three-dimensional coordinates in real-time relative to the base station, using the principle of relative positioning. Base Station Rover Figure 2: RTK Schematic Diagram LC69T(AM,AP)_DR&RTK_Application_Note 8 / 31 GNSS Module Series 2 Configuration 2.1. DR Configuration 2.1.1. Orientation The LG69T (AP) modules are specifically designed for use in four-wheel vehicles. Module with GNSS and motion sensor ICs must be firmly and securely fixed 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 recommended installation method is to firmly screw the device down to the vehicle frame. Mounting location should allow easy access to power supply and GNSS antenna, while avoiding exposure to excessive heat. The reference frame axes definitions are as follows: ⚫ The X-axis points towards the right side of the vehicle. ⚫ The Y-axis points towards the front of the vehicle. ⚫ The Z-axis points upwards from the vehicle. Z Y Figure 3: Reference Frame LC69T(AM,AP)_DR&RTK_Application_Note 9 / 31 The IMU reference frame of the module is shown below: Z GNSS Module Series Figure 4: IMU Reference Frame 2.1.2. Mounting When mounting the Quectel LG69T (AP) module on the vehicle: 1) Firmly attach LG69T (AP) to the vehicle body, preferably as close to the center of the rear wheel as possible. 2) The default installation of LG69T (AP) should be horizontal, aligning the X/Y axis of the module with the X/Y axis of the vehicle body as closely as possible, and ensuring the misalignment angles (α, β, γ) are less than 10°. 3) Avoid misalignment angles (α, β, γ) greater than 30°. X Y Figure 5: Installation Yaw Angle LC69T(AM,AP)_DR&RTK_Application_Note 10 / 31 GNSS Module Series Y β -β Figure 6: Installation Pitch Angle γ -γ Figure 7: Installation Roll Angle NOTE Firmly affix the module to the vehicle body. Select a structurally sound location that is not prone to flexing. 2.1.3. DR Calibration To ensure accurate functioning of the dead reckoning functionality, the module requires calibration. Follow the steps below for DR calibration: Step 1: Fix the module on the vehicle frame firmly. Any displacement, rotation or tilt of the device relative to the vehicle plane, however small, may cause performance issues and/or void calibration. Step 2: Calibration should be performed under good GNSS signal and clear sky conditions. Step 3: Power up the module, then start the vehicle on a plain surface. LC69T(AM,AP)_DR&RTK_Application_Note 11 / 31 GNSS Module Series Step 4: Drive at a speed of more than 2.5 m/s, and preferably perform at least 1 turning movement. Then, the module will start self-calibration, which will be completed in 2 minutes. Step 5: Once the calibration process is completed, the module immediately outputs the $PQTMDRPVA message. See Chapter 4.2 PQTMDRPVA for details about the message. After the calibration, there is no limit to driving trajectory and driving dynamics, and you can perform verification tests in the following scenarios: 1) Open sky area, urban main road (good satellite signal). 2) Urban tunnels (absence of satellite signal). 3) Urban viaduct (weak satellite signal). 4) Underground vehicle park (absence of satellite signal). 5) Areas surrounded with dense buildings (multi-path in urban canyon). 6) City boulevards (weak satellite signal). 7) High-rise dense area (severe urban canyon multipath). NOTE 1. $PQTMDRPVA is only output when calibration process is completed. 2. The standard NMEA message has a fixed output frequency of 1 Hz, however the GGA, RMC, GST and VTG output frequency will shift to 10 Hz after the DR calibration procedure is completed. The combination of $PQTMCFGFIXRATE and $PQTMCFGMSGRATE can be used to configure the output frequency of standard NMEA message. For more details about these commands, see document [1] protocol specification. LC69T(AM,AP)_DR&RTK_Application_Note 12 / 31 GNSS Module Series 3 RTK Input Quectel LG69T (AM) and LG69T (AP) modules support the RTCM 10403.3 input messages listed in table below. Table 1: Supported RTCM Input Messages Message Type 1005 1006 1074 1077 1094 1097 1114 1117 1124 1127 Description Stationary RTK Reference Station ARP Stationary RTK Reference Station ARP with Antenna Height GPS MSM4 GPS MSM7 Galileo MSM4 Galileo MSM7 QZSS MSM4 QZSS MSM7 BDS MSM4 BDS MSM7 LC69T(AM,AP)_DR&RTK_Application_Note 13 / 31 GNSS Module Series 4 PQTM Messages This chapter outlines the PQTM messages (proprietary NMEA messages defined by Quectel) for DR function, which are supported by LG69T (AP). Table 2: Error Code Field Format Unit Numeric - Description Error code. 1 = Invalid parameters. 2 = Failed execution. 4.1. PQTMPVT Outputs the PVT (GNSS-only) result. Type: Output Synopsis: $PQTMPVT,,,,,,,,,,< Lon>,,,,,,,,,* Parameter: Field Format Numeric Numeric yyyymmdd Unit Description Message version. - 1 = Version 1 (Always 1 for this version.) Millisecond Time of week. UTC date. yyyy: Year mm: Month dd: Day of month LC69T(AM,AP)_DR&RTK_Application_Note 14 / 31 GNSS Module Series Field Format Unit hhmmss.sss - Numeric - Numeric - Numeric Numeric Second Numeric Degree Numeric Degree Numeric Meter Numeric Meter Description UTC time. hh: Hours (00–23) mm: Minutes (00–59) ss: Seconds (00–59) sss: Decimal fraction of seconds GPS quality indicator. 0 = Fix not available or invalid. 1 = GPS SPS mode, fix valid. 2 = Differential GPS, SPS mode, or Satellite Based Augmentation. System (SBAS), fix valid. 3 = GPS PPS mode, fix valid. 4 = Real Time Kinematic (RTK) System used in RTK mode with fixed integers. 5 = Float RTK. Satellite system used in RTK mode, floating integers. 6 = Estimated (DR) mode. Note that this field is the same as in GGA. Fix mode. 0 = No fix. 1 = Reserved. 2 = 2D fix. 3 = 3D fix. Number of satellites in use. Leap seconds. Note that this field is empty in case of an invalid value. Latitude. Note that this field is empty in case of an invalid value. Longitude. Note that this field is empty in case of an invalid value. Altitude above mean-sea-level. Note that this field is empty in case of an invalid value. Geoidal separation (the difference between the WGS84 earth ellipsoid surface and the mean-sea-level surface). Note that this field is empty in case of an invalid value. LC69T(AM,AP)_DR&RTK_Application_Note 15 / 31 GNSS Module Series Field Format Numeric Numeric Numeric Numeric Numeric Numeric Numeric Unit m/s m/s m/s m/s Degree - Description North velocity. Note that this field is empty in case of an invalid value. East velocity. Note that this field is empty in case of an invalid value. Down velocity. Note that this field is empty in case of an invalid value. Ground speed. Note that this field is empty in case of an invalid value. Heading. Note that this field is empty in case of an invalid value. Range: 0.00–360.00 Horizontal dilution of precision. Note that the value is 99.99 in case of an invalid value. Position (3D) dilution of precision. Note that the value is 99.99 in case of an invalid value. Example: //No fix. $PQTMPVT,1,1000,20221225,163355.000,0,0,00,,,,,,,,,,,99.99,99.99*49 //3D fix. $PQTMPVT,1,31075000,20221225,083737.000,4,3,09,18,31.12738291,117.26372910,34.212,5.267,3.2 12,2.928,0.238,4.346,34.12,2.16,4.38*65 4.2. PQTMDRPVA Outputs the DR position, velocity and attitude. Type: Output LC69T(AM,AP)_DR&RTK_Application_Note 16 / 31 GNSS Module Series Synopsis: $PQTMDRPVA,,,,,,,,,,,< VelD>,,,* Parameter: Field Format Numeric Numeric hhmmss.sss Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Unit Millisecond - - Degree Degree Meter Meter m/s m/s m/s m/s Degree Description Message version. 1 = Version 1 (Always 1 for this version.) Milliseconds since module startup. 32-bit unsigned integer. UTC time. hh: Hours (00–23) mm: Minutes (00–59) ss: Seconds (00–59) sss: Decimal fraction of seconds Solution type. 0 = No fix. 1 = GNSS only. 2 = GNSS + DR. 3 = DR only. Latitude. Note that this field is empty in case of an invalid value. Longitude. Note that this field is empty in case of an invalid value. Altitude above mean-sea-level. Note that this field is empty in case of an invalid value. Geoidal separation (the difference between the WGS84 earth ellipsoid surface and the mean-sea-level surface). Note that this field is empty in case of an invalid value. North velocity. Note that this field is empty in case of an invalid value. East velocity. Note that this field is empty in case of an invalid value. Down velocity. Note that this field is empty in case of an invalid value. Ground speed. Note that this field is empty in case of an invalid value. Roll angle. Note that this field is empty in case of an invalid value. Range: -180.000000 to 180.000000 LC69T(AM,AP)_DR&RTK_Application_Note 17 / 31 GNSS Module Series Field Format Numeric Numeric Unit Degree Degree Description Pitch angle. Note that this field is empty in case of an invalid value. Range: -90.000000 to 90.000000 Heading. Note that this field is empty in case of an invalid value. Range: 0.000000–360.000000 Example: //No fix: $PQTMDRPVA,1,1000,163355.000,0,,,,,,,,,,,*7C //GNSS + DR fix: $PQTMDRPVA,1,75000,083737.000,2,31.12738291,117.26372910,34.212,5.267,3.212,2.928,0.238,4.3 46,0.392663,1.300793,0.030088*5E 4.3. PQTMSENMSG Outputs sensor information. Type: Output Synopsis: $PQTMSENMSG,,[,,…,]* Parameter: Field Format Unit Numeric - to Numeric Numeric - Description Message version. 2 = IMU sensor data. See Figure 4: IMU Reference Frame. Timestamp since power-on. 32-bit unsigned integer. Sensor information. See Chapter 4.3.1 When = 2. LC69T(AM,AP)_DR&RTK_Application_Note 18 / 31 GNSS Module Series 4.3.1. When = 2 This message is used to output the IMU raw data, these values are read directly from the IMU without any filtering. Refer to IMU reference frame. Synopsis: $PQTMSENMSG,2,,,,,,< IMU_ACC_X>,,* Parameter: Field Format Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Unit Description Timestamp since power-on. 32-bit unsigned - integer. °C IMU temperature dps IMU X-axis raw gyroscope value dps IMU Y-axis raw gyroscope value dps IMU Z-axis raw gyroscope value g IMU X-axis raw accelerometer value g IMU Y-axis raw accelerometer value g IMU Z-axis raw accelerometer value Example: $PQTMSENMSG,2,2248864,36.70,0.6118,-0.4064,-0.5419,0.0132,-0.0151,1.0045*34 NOTE 1. $PQTMCFGMSGRATE can be used to enable or disable $PQTMSENMSG message output. For more details about this command, see document [1] protocol specification. //Enable $PQTMSENMSG command: $PQTMCFGMSGRATE,W,PQTMSENMSG,100,2*4C $PQTMCFGMSGRATE,OK*29 //Disable $PQTMSENMSG command: $PQTMCFGMSGRATE,W,PQTMSENMSG,0,2*4D $PQTMCFGMSGRATE,OK*29 LC69T(AM,AP)_DR&RTK_Application_Note 19 / 31 GNSS Module Series 4.4. PQTMVEHMSG Outputs vehicle information. Type: Output Synopsis: $PQTMVEHMSG,,[,,…,]* Parameter: Field Format Unit Numeric - Numeric - to Numeric - Description Message type: 1 = Outputs vehicle speed (in m/s) information via UART interface Timestamp since power-on. 32-bit unsigned integer. This field varies with the message type. See Chapter 4.4.1 When = 1. 4.4.1. When = 1 Synopsis: $PQTMVEHMSG,1,,* Parameter: Field Format Numeric Numeric Unit Description Millisecond Timestamp since power-on. 32-bit unsigned integer. m/s Vehicle speed. Range: -100 to 100. Example: $PQTMVEHMSG,1,3748292,3.6*1D LC69T(AM,AP)_DR&RTK_Application_Note 20 / 31 GNSS Module Series NOTE 1. $PQTMCFGMSGRATE can be used to enable or disable $PQTMVEHMSG message output. For more details about this command, see document [1] protocol specification. //Enable $PQTMVEHMSG command: $PQTMCFGMSGRATE,W,PQTMVEHMSG,1,1*4C $PQTMCFGMSGRATE,OK*29 //Disable $PQTMVEHMSG command: $PQTMCFGMSGRATE,W,PQTMVEHMSG,0,1*4D $PQTMCFGMSGRATE,OK*29 4.5. PQTMCFGCAN Configures CAN interface and baud rate. Type: Set/Get Synopsis: //Set: $PQTMCFGCAN,W,,,,,* //Get: $PQTMCFGCAN,R,* Parameter: Field Format Numeric Numeric Numeric Numeric Unit Description CAN interface index. - 0 = CAN Enable/disable CAN interface. - 0 = Disable 1 = Enable Frame format of CAN interface. 0 = Classic CAN 1 = CAN FD without bitrate switching 2 = CAN FD with bitrate switching bps Nominal baud rate of CAN interface. LC69T(AM,AP)_DR&RTK_Application_Note 21 / 31 GNSS Module Series Field Format Numeric Unit Description Data baud rate of CAN interface. Note: This field is only valid in CAN FD frame bps format. It can be set to 0 in classic CAN frame format. Result: ⚫ If successful, the module returns: //Set: $PQTMCFGCAN,OK*74 //Get: $PQTMCFGCAN,OK,,,,,*< CR> ⚫ If failed, the module returns: $PQTMCFGCAN,ERROR,* For details about , see Table 2: Error Code. Example: //Sets the CAN interface $PQTMCFGCAN,W,0,1,0,500000,0*45 $PQTMCFGCAN,OK*3E //Gets the configuration of CAN interface $PQTMCFGCAN,R,0*74 $PQTMCFGCAN,OK,0,1,0,500000,0*16 4.6. PQTMCFGCANFILTER Configures the CAN filter. The module only receives messages that match the filtering rules. Type: Set/Get Synopsis: //Set: $PQTMCFGCANFILTER,W,,,,,,,* LC69T(AM,AP)_DR&RTK_Application_Note 22 / 31 GNSS Module Series //Get: $PQTMCFGCANFILTER,R,,* Parameter: Field Format Unit Numeric - Numeric - Numeric - Numeric - Numeric - Hexadecimal - Hexadecimal - Description CAN interface index. 0 = CAN Filter index. 0 = Filter 0 1 = Filter 1 Enable/disable filter. 0 = Disable 1 = Enable Filter type. 0 = Range filter 1 = Dual ID filter 2 = Mask filter Identifier type. 0 = Standard ID 1 = Extended ID Filter identification 1. Range: 0–0x7FF, if is Standard ID Range: 0–0x1FFFFFFF, if is Extended ID Filter identification 2. Range: 0–0x7FF, if is Standard ID Range: 0–0x1FFFFFFF, if is Extended ID Result: ⚫ If successful, the module returns: //Set: $PQTMCFGCANFILTER,OK*3E //Get: $PQTMCFGCANFILTER,OK,,,,,,,* ⚫ If failed, the module returns: $PQTMCFGCANFILTER,ERROR,* For details about , see Table 2: Error Code. LC69T(AM,AP)_DR&RTK_Application_Note 23 / 31 Example: //Sets the CAN filter 0. $PQTMCFGCANFILTER,W,0,0,1,0,0,3E9,1F5*7D $PQTMCFGCANFILTER,OK*3E //Gets the configuration of CAN filter 0 $PQTMCFGCANFILTER,R,0,0*68 $PQTMCFGCANFILTER,OK,0,0,1,1,0,3E9,1F5*2F GNSS Module Series NOTE If the filter type is mask filter ( = 2): ⚫ is the filter ID, and is the mask. ⚫ If a mask bit is set to 1, the corresponding ID bit will be compared with the value of the filter ID bit; and if it matches then the message will be accepted, otherwise the message will be rejected. 4.7. PQTMCFGVEHDBC Configure the vehicle Database for CAN (DBC). Type: Set/Get Synopsis: //Set: $PQTMCFGVEHDBC,W,,,,,,,,,,* //Get: $PQTMCFGVEHDBC,R,* Parameter: Field Format Numeric Numeric Numeric Unit - Description DBC index. 0 = Vehicle speed DBC 1 = Vehicle gear DBC CAN message ID. Start bit of data. LC69T(AM,AP)_DR&RTK_Application_Note 24 / 31 GNSS Module Series Field Format Numeric Numeric Numeric Numeric Numeric Numeric Numeric Unit - - - Description Bit size of data. Byte order. 0 = Motorola mode (Big endian) 1 = Intel mode (Litter endian) Value type. Not support, always 0 Factor of value. Offset of value. Minimal value. Maximum value. Result: ⚫ If successful, the module returns: //Set: $PQTMCFGVEHDBC,OK*6C //Get: $PQTMCFGVEHDBC,OK,,,,,,,,< Offset>,,* ⚫ If failed, the module returns: $PQTMCFGVEHDBC,ERROR,* For details about , see Table 2: Error Code. Example: //Sets the vehicle speed DBC $PQTMCFGVEHDBC,W,0,3E9,8,16,0,0,0.015625,0,0,300*57 $PQTMCFGVEHDBC,OK*6C //Gets the configuration of vehicle speed DBC $PQTMCFGVEHDBC,R,0*26 $PQTMCFGVEHDBC,OK,0,3E9,8,16,0,0,0.015625,0.000000,0.000000,300.000000*2A LC69T(AM,AP)_DR&RTK_Application_Note 25 / 31 GNSS Module Series 4.8. PQTMCFGVEHRVAL Configures the vehicle reverse gear value based on CAN forward/backward information. Type: Set/Get Synopsis: //Set: $PQTMCFGVEHRVAL,W,* //Get: $PQTMCFGVEHRVAL,R* Parameter: Field Format Numeric Unit Description Vehicle reverse gear value. Range: 0–255 Result: ⚫ If successful, the module returns: //Set: $PQTMCFGVEHRVAL,OK*20 //Get: $PQTMCFGVEHRVAL,OK,* ⚫ If failed, the module returns: $PQTMCFGVEHRVAL,ERROR,* For details about , see Table 2: Error Code. Example: //Set: $PQTMCFGVEHRVAL,W,2*6D $PQTMCFGVEHRVAL,OK*20 //Get: $PQTMCFGVEHRVAL,R*76 $PQTMCFGVEHRVAL,OK,2*3E LC69T(AM,AP)_DR&RTK_Application_Note 26 / 31 GNSS Module Series 4.9. PQTMCFGLA Configures the lever arm. Type: Set/Get Synopsis: //Set: $PQTMCFGLA,W,,,,* //Get: $PQTMCFGLA,R,* Parameter: Field Format Numeric Numeric Numeric Numeric Unit - Meter Meter Meter Description Type of lever arm. 1 = IMU to antenna 1 lever arm. 3 = IMU to user lever arm. Lever arm of X axis. Lever arm of Y axis. Lever arm of Z axis. Result: ⚫ If successful, the module returns: //Set: $PQTMCFGLA,OK* //Get: $PQTMCFGLA,OK,,,,* ⚫ If failed, the module returns: $PQTMCFGLA,ERROR,* For details about , see Table 2: Error Code. Example: $PQTMCFGLA,W,1,0.212,0.514,0.113*31 $PQTMCFGLA,OK*7F LC69T(AM,AP)_DR&RTK_Application_Note 27 / 31 GNSS Module Series NOTE After issuing this command, the module must be restarted for the command to take effect. LC69T(AM,AP)_DR&RTK_Application_Note 28 / 31 GNSS Module Series 5 Appendix A References Table 3: Related Documents Document Name [1] Quectel_LG69T(AM,AP)_GNSS_Protocol_Specification Table 4: Terms and Abbreviations Abbreviation 2D 3D Description 2 Dimension 3 Dimension ADR ARP CAN Automotive Dead Reckoning Antenna Reference Point Controller Area Network CAN FD BDS DBC CAN with Flexible Data rate BeiDou Navigation Satellite System Database for CAN DR GNSS GGA Dead Reckoning Global Navigation Satellite System Global Positioning System Fix Data GPS IMU MSM Global Positioning System Inertial Measurement Unit Multiple Signal Message NMEA NMEA (National Marine Electronics Association) 0183 Interface Standard LC69T(AM,AP)_DR&RTK_Application_Note 29 / 31 Abbreviation PPS PQTM QZSS RMS RTCM RTDGPS RTK SPS UART UTC VRS WGS84 GNSS Module Series Description Pulse Per Second Proprietary Protocol of Quectel Quasi-Zenith Satellite System Root mean square Radio Technical Commission for Maritime Services Real Time Differential Global Positioning System Real-Time Kinematic Standard Positioning Service Universal Asynchronous Receiver/Transmitter Coordinated Universal Time Virtual Reference Station World Geodetic System 1984 LC69T(AM,AP)_DR&RTK_Application_Note 30 / 31 GNSS Module Series 6 Appendix B Special Characters Table 5: Special Characters Special Character […] {…} Underline Description Carriage return character. Line feed character. Parameter name. Angle brackets do not appear in the message. Optional field of a message. Square brackets do not appear in the message. Repeated field of a message. Curly brackets do not appear in the message. Default setting of a parameter. LC69T(AM,AP)_DR&RTK_Application_Note 31 / 31

Quectel_LG69T(AM,AP)_DR&RTK_Application_Note_V1.0

PDF

515.17 KB

LG69T (AM,AP) Moving Base Application Note GNSS Module Series Version: 1.0 Date: 2023-08-02 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. LG69T(AM,AP)_Moving_Base_Application_Note 1 / 26 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. 2023. All rights reserved. LG69T(AM,AP)_Moving_Base_Application_Note 2 / 26 GNSS Module Series Safety Information The following safety precautions must be observed during all phases of operation, such as usage, service, or repair of any terminal or mobile incorporating the module. Manufacturers of the terminal should notify users and operating personnel of the following safety information by incorporating these guidelines into all product manuals. Otherwise, Quectel assumes no liability for customers’ failure to comply with these precautions. Ensure that the product may be used in the country and the required environment, as well as that it conforms to the local safety and environmental regulations. Keep away from explosive and flammable materials. The use of electronic products in extreme power supply conditions and locations with potentially explosive atmospheres may cause fire and explosion accidents. The product must be powered by a stable voltage source, and the wiring shall conform to security precautions and fire prevention regulations. Proper ESD handling procedures must be followed throughout the mounting, handling and operation of any devices and equipment that incorporate the module to avoid ESD damages. LG69T(AM,AP)_Moving_Base_Application_Note 3 / 26 GNSS Module Series About the Document Document Information Title LG69T (AM,AP) Moving Base Application Note Subtitle GNSS Module Series Document Type Application Note Document Status Released Revision History Version Date Description - 2023-04-24 Creation of the document 1.0 2023-08-02 First official release LG69T(AM,AP)_Moving_Base_Application_Note 4 / 26 GNSS Module Series Contents Safety Information....................................................................................................................................... 3 About the Document ................................................................................................................................... 4 Contents ....................................................................................................................................................... 5 Table Index................................................................................................................................................... 6 Figure Index ................................................................................................................................................. 7 1 Introduction .......................................................................................................................................... 8 2 Hardware Design.................................................................................................................................. 9 2.1. Application Interfaces .............................................................................................................. 11 2.1.1. UART Interfaces............................................................................................................. 11 2.1.2. RESET_N....................................................................................................................... 12 2.1.3. SLAVE_RESET_EN....................................................................................................... 13 2.1.4. BOOT ............................................................................................................................. 13 2.1.5. SLAVE_BOOT_EN ........................................................................................................ 14 3 System Construction......................................................................................................................... 15 3.1. Precautions for GNSS Antenna Mounting .............................................................................. 15 3.1.1. Antenna Mounting Method ............................................................................................. 15 3.1.2. Recommended Mounting for GNSS Antennas .............................................................. 16 4 Reference Frame ................................................................................................................................ 17 4.1. Local Cartesian Coordinate System (ENU) ............................................................................ 17 4.2. Vehicle Frame ......................................................................................................................... 18 5 Angle Definition.................................................................................................................................. 19 5.1. Heading ................................................................................................................................... 19 5.2. Pitch......................................................................................................................................... 20 5.3. Roll .......................................................................................................................................... 21 6 Configuration...................................................................................................................................... 22 7 Moving Base Related Message ........................................................................................................ 23 7.1. PQTMTAR Message ............................................................................................................... 23 8 Appendix A References..................................................................................................................... 25 9 Appendix B Special Characters ....................................................................................................... 26 LG69T(AM,AP)_Moving_Base_Application_Note 5 / 26 GNSS Module Series Table Index Table 1: Function Differences for LG69T (AP) Pins in Different Applications ............................................. 9 Table 2: Related Documents...................................................................................................................... 25 Table 3: Terms and Abbreviations ............................................................................................................. 25 Table 4: Special Characters ....................................................................................................................... 26 LG69T(AM,AP)_Moving_Base_Application_Note 6 / 26 GNSS Module Series Figure Index Figure 1: Schematic Diagram of Connection Between Base and Rover................................................... 10 Figure 2: Reference Design of UART1 Interface on Base......................................................................... 11 Figure 3: Reference Design of UART2 Interface on Rover ....................................................................... 12 Figure 4: Reference OC Circuit for Base’s RESET_N............................................................................... 12 Figure 5: Reference OC Circuit for Rover’s RESET_N ............................................................................. 12 Figure 6: Reference Control Circuit for Base’s BOOT ............................................................................... 13 Figure 7: Reference Control Circuit for Rover’s BOOT ............................................................................. 13 Figure 8: Antenna Mounting Top View....................................................................................................... 15 Figure 9: Antenna Mounting (Same Reference Ground Plane) ................................................................ 15 Figure 10: Antenna Mounting – Vehicle..................................................................................................... 16 Figure 11: ENU Coordinate System........................................................................................................... 17 Figure 12: Vehicle Frame ........................................................................................................................... 18 Figure 13: Heading Angle .......................................................................................................................... 19 Figure 14: Pitch Angle ................................................................................................................................ 20 Figure 15: Roll Angle.................................................................................................................................. 21 LG69T(AM,AP)_Moving_Base_Application_Note 7 / 26 GNSS Module Series 1 Introduction This document presents the software and hardware designs of the LG69T (AM) and the LG69T (AP) modules for the use in the Moving Base application. LG69T (AM) supports dual-band precision RTK technology to calculate the heading angle and attitude information and transmit the calculation results to LG69T (AP). LG69T (AP) integrates a 6-axis IMU and supports dual-band precision RTK technology and DR algorithm to output high precision position, heading and attitude information. RTK technology includes the rover and the base. The base sends a continuous differential correction data stream to the rover via a communication link. In standard RTK mode, the base remains static in a known position, while the rover module can move. However, in Moving Base mode, both the base and the rover can move, making it suitable for use in vehicles. To enable the Moving Base function, both the LG69T (AM) and the LG69T (AP) modules must be installed on the same carrier platform. The cm-level accuracy vector between two antennas can be computed via the Moving Base function. This allows for outputting orientation when static on startup and requires no horizontal motion usually required by GNSS to provide Heading. The absolute position accuracy is limited by the positioning mode of the moving base receiver. If the base receiver is in single (autonomous) mode, this will be m-level accuracy. Should cm-level accuracy be required, the moving base also needs to receive RTK corrections from a static base or RTK network. The terms 'base', 'rover,' 'baseline', and 'heading' are used to describe the functionality of the Moving Base. ⚫ Base: Receiver that transmits the different correction data stream. ⚫ Rover: Receiver that receives the different correction data stream. ⚫ Baseline: Vector connecting the base antenna to the rover antenna. The Moving Base function supports baseline lengths varying from 0.3 m to 1.4 m. ⚫ Heading: Angle from true north to baseline measured in a clockwise direction. NOTE LG69T(AM) with firmware version LG69TAMNR01A03S_RQN and LG69T(AP) with firmware version LG69TAPNR01A01S, as well as their later versions, support the Moving Base function. LG69T(AM,AP)_Moving_Base_Application_Note 8 / 26 GNSS Module Series 2 Hardware Design For LG69T (AM) and LG69T (AP) modules, the LG69T (AP) can be used as the base, while the LG69T (AM) can be used as the rover. The base communicates with the MCU via its UART1, while the rover communicates with the base’s UART2 via its UART2. The following schematic diagram illustrates the specific connection configuration: In the Moving Base application, certain pins (pins 16, 17, 28 and 29) function configurations of the LG69T (AP) module are different from those in the general application, as shown in below. Table 1: Function Differences for LG69T (AP) Pins in Different Applications Pin No. General Application Moving Base Application 16 RESERVED SLAVE_BOOT_EN: Controls the BOOT of the rover 17 RESERVED SLAVE_RESET_EN: Controls the RESET_N of the rover 28 RESERVED TXD3: Debugging data 29 RESERVED RXD3: Debugging data LG69T(AM,AP)_Moving_Base_Application_Note 9 / 26 GNSS Module Series External Corrections NMEA + Fused Heading GPIO_X GPIO_X GPIO_X MCU_TXD MCU_RXD RESERVED 54 1PPS 53 RESERVED 52 RESERVED 51 BOOT 50 RESET_N 49 GND 48 RESERVED 47 RESERVED 46 RESERVED 45 RESERVED 44 RXD1 43 TXD1 42 RESERVED 54 1PPS 53 RESERVED 52 RESERVED 51 BOOT 50 RESET_N 49 GND 48 RESERVED 47 RESERVED 46 RESERVED 45 RESERVED 44 RXD1 43 TXD1 42 Antenna Circuit Antenna Status Detection Circuit 1 GND 2 RF_IN 3 GND 4 ANT_DET 5 ANT_OFF 6 ANT_SHORT 7 VDD_RF 8 RESERVED 9 RESERVED 10 RESERVED 11 RESERVED 12 GND 13 RESERVED 14 GND LG69T (AP) (Base) GND 41 RESERVED 40 RESERVED 39 RESERVED 38 GND 37 V_BCKP 36 RESERVED 35 VCC 34 VCC 33 GND 32 RESERVED 31 RESERVED 30 RXD3 29 TXD3 28 V_BCKP VCC_3.3V MCU Antenna Circuit Antenna Status Detection Circuit 1 GND 2 RF_IN 3 GND 4 ANT_DET 5 ANT_OFF 6 ANT_SHORT 7 VDD_RF 8 RESERVED 9 RESERVED 10 RESERVED 11 RESERVED 12 GND 13 RESERVED 14 GND LG69T (AM) (Rover) GND 41 RESERVED 40 RESERVED 39 RESERVED 38 GND 37 V_BCKP 36 RESERVED 35 VCC 34 VCC 33 GND 32 RESERVED 31 RESERVED 30 RESERVED 29 RESERVED 28 15 RESERVED 16 RESERVED 17 RESERVED 18 RESERVED 19 RESERVED 20 RTK_IND 21 RESERVED 22 RESERVED 23 RESERVED 24 RESERVED 25 RESERVED 26 RXD2 27 TXD2 15 RESERVED 16 SLAVE_BOOT_EN 17 SLAVE_RESET_EN 18 RESERVED 19 RESERVED 20 RTK_IND 21 RESERVED 22 WHEEL_TICK 23 FWD 24 CAN_RX 25 CAN_TX 26 RXD2 27 TXD2 GPIO_X GPIO_X GPIO_X V_BCKP VCC_3.3V I/O POWER GND SYSTEM ANT RESERVED Derived Heading Local Corrections Figure 1: Schematic Diagram of Connection Between Base and Rover LG69T(AM,AP)_Moving_Base_Application_Note Direct Connection Indirect Connection 10 / 26 GNSS Module Series ⚫ External Corrections: The external corrections can be from the VRS service provider. The MCU obtains the RTCM corrections from the VRS service and then sends them to the base (LG69T (AP) module) to realize the RTK positioning function. ⚫ Local Corrections: The local corrections are provided by the base and transmitted to the rover (LG69T (AM) module) via UART2 interface to calculate the heading information. ⚫ Derived Heading: The rover (LG69T (AM) module) calculates the heading information and sends it back to the base (LG69T (AP) module), and the base (LG69T (AP) module) reprocesses the heading information, and finally outputs the fused heading information. ⚫ NMEA + Fused Heading: The base (LG69T (AP) module) can pass through the heading information from the rover (LG69T (AM) module), so the MCU only needs to be connected with the base (LG69T (AP) module) to obtain the positioning data (NMEA) and heading information at the same time. NOTE 1. The modules operate at an I/O voltage of 3.3 V. If the I/O voltage of the MCU differs from this value, a level-shifting circuit must be used. 2. It is recommended to use an OC drive circuit for the RESET_N pin. For more information, see Chapter 2.1.2 RESET_N. 3. It is recommended to use a boot control circuit for the BOOT pin. For more information, see Chapter 2.1.4 BOOT. 2.1. Application Interfaces 2.1.1. UART Interfaces The UART1 on the base is connected to MCU, as shown below: MCU MCU_TXD MCU_RXD GND LG69T (AP) (Base) TXD1 RXD1 GND Figure 2: Reference Design of UART1 Interface on Base The UART2 on the rover is connected to the UART2 on the base, as shown below: LG69T(AM,AP)_Moving_Base_Application_Note 11 / 26 LG69T (AP) (Base) TXD2 RXD2 GND GNSS Module Series LG69T (AM) (Rover) TXD2 RXD2 GND Figure 3: Reference Design of UART2 Interface on Rover 2.1.2. RESET_N RESET_N is an input pin. The base can be reset by driving the RESET_N pin low for at least 100 ms and then releasing it. To control the RESET_N pin of the base, it is recommended to connect it to the GPIO of the MCU through an OC driver circuit. The circuit should be designed as shown below. MCU_GPIO Input pulse RESET_N (Base) Figure 4: Reference OC Circuit for Base’s RESET_N The RESET_N pin of the rover is connected with the SLAVE_RESET_EN pin of the base via an OC driver circuit for upgrading, as shown below: SLAVE_RESET_EN Input pulse RESET_N (Rover) Figure 5: Reference OC Circuit for Rover’s RESET_N LG69T(AM,AP)_Moving_Base_Application_Note 12 / 26 GNSS Module Series 2.1.3. SLAVE_RESET_EN The SLAVE_RESET_EN pin of the base, which is active high, is used to control the RESET_N pin of the rover via an OC driver circuit. For more information about the OC driver circuit, see Figure 5: Reference OC Circuit for Rover’s RESET_N. The RESET_N of the base is pulled down via the GPIO of the MCU to complete the base’s upgrading. When upgrading the rover, the SLAVE_RESET_EN is automatically pulled up, which enables the OC driver circuit and drives low the RESET_N pin of the rover, causing the rover to reset and enter upgrade mode. 2.1.4. BOOT BOOT is used to set the base to Boot download mode. It is pulled down internally by default. If the pin is pulled up with a 100 Ω resistor to the VCC for 50 ms during startup, the base enters Boot download mode. During startup, the BOOT pin voltage level is checked to determine the base’s operating mode. The base’s BOOT pin is connected to the GPIO of the MCU. It is recommended to use a boot control circuit to control the BOOT pin. V CC_3.3V 10K M CU_GP IO 47K 100R BOOT (Base) Figure 6: Reference Control Circuit for Base’s BOOT The rover’s BOOT pin is connected to the SLAVE_BOOT_EN pin of the base via a 0 Ω resistor for downloading. The circuit is illustrated in the figure below: S LA VE _B OO T_E N 0R BOOT (Rover) Figure 7: Reference Control Circuit for Rover’s BOOT LG69T(AM,AP)_Moving_Base_Application_Note 13 / 26 GNSS Module Series 2.1.5. SLAVE_BOOT_EN The SLAVE_BOOT_EN pin of the base, which is active high, is used to control the BOOT pin of the rover via a 0 Ω resistor. For more information about the BOOT control circuit, see Figure 6: Reference Control Circuit for Base’s BOOT. When the rover downloads the firmware, the SLAVE_BOOT_EN and SLAVE_RESET_EN are automatically pulled up, which in turn pulls up the BOOT of the rover. Meanwhile, the RESET_N of the rover is released automatically after being pulled down for at least 100 ms, which puts it to Boot download mode, allowing the firmware to be downloaded. LG69T(AM,AP)_Moving_Base_Application_Note 14 / 26 GNSS Module Series 3 System Construction This chapter provides system-level recommendations for using the base and rover to develop high-performance Moving Base solutions. 3.1. Precautions for GNSS Antenna Mounting 3.1.1. Antenna Mounting Method In practical applications, it is important to fix GNSS antennas during mounting, as shown in the following figure. The vector from the base antenna to the rover antenna is called the baseline. Its minimum length is 0.3 m. Base Anetnna Rover Antenna Figure 8: Antenna Mounting Top View If the orientation test is carried out on the same device, ensure to use two identical GNSS antennas and place them on the same reference ground plane (with the same ground plane size, shape, angle of the horizontal plane). However, the use of a helix antenna does not require ground planes. Base Antenna Rover Antenna Figure 9: Antenna Mounting (Same Reference Ground Plane) LG69T(AM,AP)_Moving_Base_Application_Note 15 / 26 GNSS Module Series 3.1.2. Recommended Mounting for GNSS Antennas Pay attention to the mounting positions for GNSS antennas. For a vehicle, apply GNSS antennas in the same plane and unstructured environment. Figure 10: Antenna Mounting – Vehicle NOTE For recommended antenna selection and design, see document [1] GNSS antenna selection guidance or contact Quectel Technical Support (support@quectel.com). LG69T(AM,AP)_Moving_Base_Application_Note 16 / 26 GNSS Module Series 4 Reference Frame 4.1. Local Cartesian Coordinate System (ENU) Local cartesian coordinate system is a right-handed rectangular coordinate system where the coordinate origin is located at the station center. In the Moving Base application, the phase center of the base antenna is considered the station center, and the heading angle is referenced to this coordinate system. Sky (U) R Rover Antenna B Base Antenna Figure 11: ENU Coordinate System East (E) LG69T(AM,AP)_Moving_Base_Application_Note 17 / 26 GNSS Module Series 4.2. Vehicle Frame The vehicle frame is a 3D frame, as shown in the figure below, and the pitch and roll angles are referenced to this coordinate system. ⚫ The X-axis points towards the right of the vehicle. ⚫ The Y-axis points towards the front of the vehicle. ⚫ The Z-axis points towards the top of the vehicle. Z Y Figure 12: Vehicle Frame LG69T(AM,AP)_Moving_Base_Application_Note 18 / 26 GNSS Module Series 5 Angle Definition This chapter provides the definitions of the heading, pitch and roll angles in the LG69T (AM) and LG69T (AP) Moving Base applications. 5.1. Heading The heading angle in the dual antenna setup is referenced to the local cartesian coordinate system (ENU). It is defined as the angle between the projection of the baseline vector (i.e., the vector connecting the base antenna and rover antenna) on the horizontal plane and the true north (i.e., N-axis) with the effective range of [0,360). For details about the heading angle output, see Chapter 7.1 PQTMTAR Message. The heading angle plane diagram (with north and east directions as reference planes) is illustrated below: North (N) Rover Antenna R Base Antenna B Figure 13: Heading Angle East (E) NOTE This heading angle is derived using dual antenna orientation, and it is different from the heading angle output in RMC message. LG69T(AM,AP)_Moving_Base_Application_Note 19 / 26 GNSS Module Series 5.2. Pitch The pitch angle references vehicle frame. It is the angle between the Y-axis of the vehicle and the horizontal plane, with a range of [-90,+90]. Positive values correspond to upward pitch, while negative values correspond to downward pitch. For details about the pitch angle output, see Chapter 7.1 PQTMTAR Message. The pitch angle diagram is illustrated below: Positive Rotation Pitch Figure 14: Pitch Angle LG69T(AM,AP)_Moving_Base_Application_Note 20 / 26 GNSS Module Series 5.3. Roll The roll angle is referenced to vehicle frame, and is measured between the X-axis of the vehicle and the horizontal plane. Its effective range is [-180,+180], where right is positive and left is negative (when viewed from the rear of the vehicle). For details about roll angle output, see Chapter 7.1 PQTMTAR Message. The roll angle diagram is illustrated below: Positive Rotation Roll Figure 15: Roll Angle LG69T(AM,AP)_Moving_Base_Application_Note 21 / 26 GNSS Module Series 6 Configuration The LG69T (AM) and LG69T (AP) do not require any special configuration for Moving Base application. As long as they are properly connected as shown in Figure 1: Schematic Diagram of Connection Between Base and Rover, LG69T (AP) automatically identifies itself as the base, and LG69T (AM) automatically identifies itself as the rover. The attitude information is provided by $PQTMTAR message on the base, which is enabled by default, see Chapter 7.1 PQTMTAR Message for details. $PQTMTAR message can be enabled/disabled by $PQTMCFGMSGRATE, see document [2] protocol specification for details. LG69T(AM,AP)_Moving_Base_Application_Note 22 / 26 GNSS Module Series 7 Moving Base Related Message 7.1. PQTMTAR Message Outputs the UTC and attitude of the module (base). This message can be enabled or disabled by $PQTMCFGMSGRATE command. Type: Output Synopsis: $PQTMTAR,,,,,,,,,,,,* Parameter: Field Format Unit Numeric - hhmmss.sss - Numeric - Numeric Numeric Meter Degree Description Message version. 1 = Version 1 (Always 1 for this message version.) UTC time. hh: Hours (00–23) mm: Minutes (00–59) ss: Seconds (00–59) sss: Decimal fraction of seconds GPS quality indicator: 0 = Fix not available or invalid 1 = GPS SPS mode 2 = Differential GPS, SPS mode 4 = Real Time Kinematic (RTK) mode 5 = Float RTK mode 6 = Estimated (dead reckoning) mode Reserved. Always null. Base line length. Pitch angle. Range: -90.000000 to 90.000000. LG69T(AM,AP)_Moving_Base_Application_Note 23 / 26 GNSS Module Series Field Format Numeric Numeric Numeric Numeric Numeric Numeric Unit Degree Degree Degree Degree Degree - Description Note that this field is empty in case of an invalid value. Roll angle. Range: -180.000000 to 180.000000. Note that this field is empty in case of an invalid value. Heading angle. Range: 0.000000 to 359.999999. Note that this field is empty in case of an invalid value. Vehicle pitch accuracy. Note that this field is empty in case of an invalid value. Vehicle roll accuracy. Note that this field is empty in case of an invalid value. Vehicle heading accuracy. Note that this field is empty in case of an invalid value. Number of satellites used in heading solution. Example: $PQTMTAR,1,165034.000,4,,0.860,1.124780,,50.968541,0.254125,,0.012547,21*59 NOTE This message can be enabled or disabled by $PQTMCFGMSGRATE command, see document [2] protocol specification for details. //Enabled $PQTMTAR message: $PQTMCFGMSGRATE,W,PQTMTAR,1,1*09 $PQTMCFGMSGRATE,OK*29 //Disabled $PQTMTAR message: $PQTMCFGMSGRATE,W,PQTMTAR,0,1*08 $PQTMCFGMSGRATE,OK*29 LG69T(AM,AP)_Moving_Base_Application_Note 24 / 26 GNSS Module Series 8 Appendix A References Table 2: Related Documents Document Name [1] Quectel_GNSS_Antenna_Selection_Guidance [2] Quectel_LG69T(AM,AP)_GNSS_Protocol_Specification Table 3: Terms and Abbreviations Abbreviation DR Description Dead Reckoning ENU GNSS East North Up (navigational coordinate system) Global Navigation Satellite System I/O MCU NMEA Input/Output Microcontroller Unit/Microprogrammed Control Unit National Marine Electronics Association RF RMC RTK Radio Frequency Recommended Minimum Specific GNSS Data Real-Time Kinematic RXD TXD Receive Data (Pin) Transmit Data (Pin) UART UTC Universal Asynchronous Receiver/Transmitter Coordinated Universal Time VRS Virtual Reference Station LG69T(AM,AP)_Moving_Base_Application_Note 25 / 26 GNSS Module Series 9 Appendix B Special Characters Table 4: Special Characters Special Character […] {…} Underline Description Carriage return character. Line feed character. Parameter name. Angle brackets do not appear in the message. Optional field of a message. Square brackets do not appear in the message. Repeated field of a message. Curly brackets do not appear in the message. Default setting of a parameter. LG69T(AM,AP)_Moving_Base_Application_Note 26 / 26

Quectel_LG69T(AM,AP)_Moving_Base_Application_Note_V1.0

PDF

451.73 KB

L89 R2.0&LC29H Series&LC79H (AL) I2C Application Note GNSS Module Series Version: 1.1 Date: 2023-07-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 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. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 1 / 31 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 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. 2023. All rights reserved. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 2 / 31 GNSS Module Series About the Document Document Information Title Subtitle Document Type Document Status L89 R2.0&LC29H Series&LC79H (AL) I2C Application Note GNSS Module Series Application Note Released Revision History Revision Date - 2022-01-25 1.0 2022-10-10 1.1 2023-07-28 Description Creation of the document First official release 1. Updated applicable variant LC79H series to LC79H (AL). 2. Added information on I2C communication protocol (Chapter 2). 3. Added information on multiple slave operation (Chapter 5). L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 3 / 31 GNSS Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 2 I2C Communication Protocol ............................................................................................................ 8 2.1. START and STOP Signals ......................................................................................................... 8 2.2. Data Transfer and Acknowledge Signals ................................................................................... 8 2.3. Communication .......................................................................................................................... 9 2.4. Write Sequence........................................................................................................................ 10 2.5. Read Sequence ....................................................................................................................... 10 3 Data Reading ..................................................................................................................................... 12 3.1. Master Data Reading Flow ...................................................................................................... 12 4 Data Writing ....................................................................................................................................... 16 4.1. Master Data Writing Flow......................................................................................................... 16 5 Multi-Slave Operation ....................................................................................................................... 20 6 Sample Code for I2C Reading/Writing Sequence.......................................................................... 24 6.1. Sample Code ........................................................................................................................... 24 7 Appendix References ....................................................................................................................... 31 L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 4 / 31 GNSS Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 7 Table 2: Related Documents ...................................................................................................................... 31 Table 3: Terms and Abbreviations .............................................................................................................. 31 L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 5 / 31 GNSS Module Series Figure Index Figure 1: START and STOP Signals ............................................................................................................ 8 Figure 2: Acknowledge on I2C Bus.............................................................................................................. 9 Figure 3: Complete I2C Data Transfer ......................................................................................................... 9 Figure 4: Write Sequence .......................................................................................................................... 10 Figure 5: Read Sequence .......................................................................................................................... 10 Figure 6: Master Data Reading Flow Step 1.............................................................................................. 13 Figure 7: Master Data Reading Flow Step 2.............................................................................................. 14 Figure 8: Data Reading Flow of Master ..................................................................................................... 15 Figure 9: Master Data Writing Flow Step 1 ................................................................................................ 17 Figure 10: Master Data Writing Flow Step 2 .............................................................................................. 18 Figure 11: Master Data Writing Flow.......................................................................................................... 19 Figure 12: Multi-Slave Operation Sequence on I2C Bus ........................................................................... 20 Figure 13: Multi-Slave Operation on I2C Bus Example 1 .......................................................................... 21 Figure 14: Incorrect Multi-Slave Operation Sequence on I2C Bus............................................................ 22 Figure 15: Multi-Slave Operation on I2C Bus Example 2 .......................................................................... 23 L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 6 / 31 GNSS Module Series 1 Introduction This document provides an overview of the I2C function and its usage on Quectel’s L89 R2.0, LC29H series, and LC79H (AL) GNSS modules. The modules always operate as slave devices when communicating with the master (client-side MCU). The master can read from and write to the modules via the I2C bus. The features of the module I2C interface: ⚫ Slave mode ⚫ Standard mode (100 kbps) and fast mode (400 kbps) ⚫ 7-bit address format ⚫ Supports sending and receiving variable length messages ⚫ I2C pins: I2C_SDA and I2C_SCL In addition, this document offers a detailed introduction as well as a flow chart and sample code to illustrate how the master reads/writes data via the I2C bus. Table 1: Applicable Modules Module Series L89 R2.0 LC29H LC79H Model L89 (HA) L89 (HB) LC29H (AA) LC29H (BA) LC29H (BS) LC29H (CA) LC29H (DA) LC79H (AL) L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 7 / 31 GNSS Module Series 2 I2C Communication Protocol 2.1. START and STOP Signals The bus transaction begins with the transmission of a START (S) signal. A START signal is initiated by a HIGH to LOW transition on the SDA line while the SCL line is kept HIGH (see figure below). The bus is considered busy until the master generates a STOP signal (P) on the bus, which is defined as a LOW to HIGH transition on the SDA line while SCL is kept HIGH (see figure below). In addition, the bus remains busy if a repeated START (S) is generated instead of a STOP signal. SCL SDA S START Signal Figure 1: START and STOP Signals P STOP Signal 2.2. Data Transfer and Acknowledge Signals I2C data bytes are 8 bits long. Any number of bytes can be transmitted per transfer. Each transferred byte must be followed by an acknowledge signal. The clock for the acknowledge signal is generated by the master, while the receiver generates the acknowledge (ACK) signal by pulling down SDA and keeping it low (or the negative acknowledge (NAK) signal by pulling up SDA and keeping it high) during the HIGH phase of the acknowledge clock pulse. If the slave is busy and unable to transmit or receive another byte of data until the ongoing processing task is performed, it can hold the SCL line LOW. This action forces the master into a wait state, effectively pausing the data transfer. Once the slave completes its task and is ready for another byte of data, it releases the clock line, allowing normal data transfer to resume. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 8 / 31 GNSS Module Series SCL from Master Data output by Transmitter (SDA) 1 2 8 9 clock pulse for acknowledgement Data output by NAK Receiver (SDA) ACK START Signal Figure 2: Acknowledge on I2C Bus 2.3. Communication After initiating the communication with the START signal (S), the master sends a 7-bit slave address followed by an extra 8th bit, known as the read/write bit, to inform the slave if the master intends to write to it or read from it. If the bit is zero it indicates a write operation, whereas 1 indicates a read operation. Data is transferred on the SDA line, starting with the Most Significant bit (MSB). Then, the master releases the SDA line and waits for the acknowledge signal (ACK) from the slave device. After transferring each byte the master releases the SDA line and waits for the acknowledge signal from the slave device. The slave device must return an acknowledge bit for each transferred byte by pulling the SDA line LOW and keeping it LOW during the high period of the SCL line. To terminate data transmission, the master generates a STOP signal (P), thus freeing the communication line. However, the master can generate a repeated START signal (S) to address another slave without first generating a STOP signal (P). It is important to note that all SDA changes should take place when SCL is low, with the exception of START and STOP signals. SCL 1-7 8 9 1 - 8 9 1 - 8 9 SDA ADDRESS R/W ACK DATA ACK DATA S START Signal Figure 3: Complete I2C Data Transfer ACK P STOP Signal L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 9 / 31 GNSS Module Series 2.4. Write Sequence The sequence charts for writing data to the I2C slave are shown below. S W T R A DEVICE I R ADDRESS T T - 0xA0 E SDA M LRA S S/C B BW K DATA n Figure 4: Write Sequence S T O P A C K To write data to the module, the master initiates the process by sending a start signal, followed by the I2C slave address and a write bit. At the 9th clock cycle (when the clock is high), the slave acknowledges the master’s request. Then the master transmits the data onto the bus. After every 8 bits of data transfer, the slave responds with an ACK to indicate successful reception. If it generates an ACK bit, it signifies that it has received the data and is ready to accept another byte. On the other hand, if it generates a NAK bit, it indicates it cannot accept any further data, and the master should terminate the transfer by sending a STOP signal (P). 2.5. Read Sequence The sequence charts for reading data from the I2C slave are shown below. S T R A R T DEVICE ADDRESS - 0xA9 E A D SDA M LR A S S/ C B BW K DATA1 ... A C K DATA n S T O P N A K Figure 5: Read Sequence L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 10 / 31 GNSS Module Series To read the slave data, the master initiates the process by sending a START signal, followed by the I2C slave address. As a result, the slave sends an ACK signal and the requested data. The communication ends with a NAK signal and a stop bit from the master. The above figures illustrate the sequences for reading multiple bytes of data. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 11 / 31 GNSS Module Series 3 Data Reading The following chapter provides a detailed explanation on how the master reads data packets via I2C bus. 3.1. Master Data Reading Flow The master reads data as follows: Step 1 The master reads data length from the slave transmit buffer. a) The master sends a configuration read command to the slave. ⚫ 7-bit slave address is 0x50. ⚫ The sent data consists of two words: 0xAA510008 and 0x00000004 (little-endian transmission). b) The master receives the data length from the slave transmit buffer. ⚫ 7-bit slave address is 0x54. ⚫ The master retrieves the data length from the slave transmit buffer. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 12 / 31 GNSS Module Series Data (8 bytes) DEVICE ADDRESS 0xAA510008 0x00000004 S T MASTER A R T (0x50<<1) & 0xFE 0x08 0x00 0x51 0xAA 0x04 0x00 0x00 S 0x00 T O P SLAVE A A A A A A A A A C C C C C C C C C K K K K K K K K K DEVICE ADDRESS Data Length (4 bytes) S T MASTER A R T (0x54<<1 ) | 0x01 A A A C C C K K K SLAVE A C DATA 1 K DATA 2 DATA 3 DATA 4 S NAK T O P Figure 6: Master Data Reading Flow Step 1 Step 2 The master reads the data_read_len 1) bytes of data. a) The master sends configuration read command to the slave. ⚫ 7-bit slave address is 0x50. ⚫ The sent data is two words: 0xAA512000 and data_read_len 1) (little-endian transmission). b) The master receives the data_read_len 1) bytes of data. ⚫ 7-bit slave address is 0x54. ⚫ The master receives the data_read_len 1) bytes of data. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 13 / 31 GNSS Module Series Data (8 bytes) DEVICE ADDRESS 0xAA512000 data_read_len (e.g. 200 bytes) S T MASTER A R T (0x50<<1) & 0xFE 0x00 0x20 0x51 0xAA 0xC8 0x00 0x00 S 0x00 T O P SLAVE A A A A A A A A A C C C C C C C C C K K K K K K K K K DEVICE ADDRESS Data (data_read_len bytes) S T MASTER A R T (0x54<<1) | 0x01 A A A C C C K K K SLAVE A C DATA 1 K DATA 2 DATA 3 A C K S NAK T O P DATA N Figure 7: Master Data Reading Flow Step 2 NOTE 1. 1) Unsigned int data_read_len represents the data length that the master intends to receive. The value of data_read_len should be less than or equal to the length read in the Step 1. 2. If the master fails to read the data on time, the transmit buffer will become full, causing the I2C transmitter to enter sleep state. Sending any command to the module via I2C port can wake up the I2C transmitter. 3. 1 word = 4 bytes. 4. The module transmits data in little-endian format. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 14 / 31 Master GNSS Module Series Slave Delay 1) Slave address: 0x50 Sends two words of data: 0xAA510008 and 0x00000004 Delay 1) Slave address: 0x54 Receives the data length Delay 1) Slave address: 0x50 Sends two words of data: 0xAA512000 and data_read_len Delay 1) Slave address: 0x54 Receives data (data_read_len bytes) Figure 8: Data Reading Flow of Master NOTE 1) Delay time is about 10 ms. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 15 / 31 GNSS Module Series 4 Data Writing The master can send messages to the slave via I2C bus. See documents [1] and [2] protocol specifications for detailed information on the messages. The interval between two input messages cannot be less than 10 ms because the slave needs 10 ms to process the input data. 4.1. Master Data Writing Flow The master writes data as follows: Step 1 The master reads the available free length in the slave receive buffer. a) The master sends a configuration read command to the slave. ⚫ 7-bit slave address is 0x50. ⚫ Sent data is two words: 0xAA510004 and 0x00000004 (little-endian transmission). b) The master receives the free length from the slave receive buffer. ⚫ 7-bit slave address is 0x54. ⚫ The master receives the free length from the slave receive buffer. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 16 / 31 GNSS Module Series Data (8 bytes) DEVICE ADDRESS 0xAA510004 0x00000004 S MASTER T A R (0x50<<1) & 0xFE T 0x04 0x00 0x51 0xAA 0x04 0x00 0x00 S 0x00 T O P SLAVE A A A A A A A A A C C C C C C C C C K K K K K K K K K DEVICE ADDRESS Free Length in slave receive buffer (4 bytes) S T MASTER A R T (0x54<<1) | 0x01 A A A C C C K K K SLAVE A C DATA 1 K DATA 2 DATA 3 DATA 4 S NAK T O P Figure 9: Master Data Writing Flow Step 1 Step 2 The master writes data_written_len 1) bytes of data. a) The master sends configuration write command to the slave. ⚫ 7-bit slave address is 0x50. ⚫ The sent data is two words: 0xAA531000 and data_written_len 1) (little-endian transmission). b) The master writes data_written_len 1) bytes of data. ⚫ 7-bit slave address is 0x58. ⚫ The master writes data_written_len 1) bytes of data. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 17 / 31 GNSS Module Series Data (8 bytes) DEVICE ADDRESS 0xAA531000 data_written_len (e.g. 30 bytes) S T MASTER A R T (0x50<<1) & 0xFE 0x00 0x10 0x53 0xAA 0x1E 0x00 0x00 S 0x00 T O P SLAVE A A A A A A A A A C C C C C C C C C K K K K K K K K K DEVICE ADDRESS Data (data_written_len bytes) S T MASTER A R T (0x58<<1) & 0xFE DATA 1 DATA 2 DATA 3 SLAVE A A A A C C C C K K K K S DATA N T O P A A C C K K Figure 10: Master Data Writing Flow Step 2 NOTE 1. 1) Unsigned int data_written_len represents the data length that the master intends to write. 2. The free length in the slave receive buffer indicates the maximum length of data the master can write. If the data to be sent exceeds the free length in the slave receive buffer, the user needs to divide the data into multiple parts and send them separately. 3. 1 word = 4 bytes. 4. The module transmits data in little-endian format. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 18 / 31 GNSS Module Series Master Slave Delay 1) Slave address: 0x50 Sends two words of data: 0xAA510004 and 0x00000004 Delay 1) Slave address: 0x54 Receives the free length Delay 1) Slave address: 0x50 Sends two words of data: 0xAA531000 and data_written_len Delay 1) Slave address: 0x58 Writes data (data_written_len bytes) Figure 11: Master Data Writing Flow NOTE 1) Delay time is about 10 ms.. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 19 / 31 GNSS Module Series 5 Multi-Slave Operation If there is more than one slave device on the I2C bus, the master must consider the following: 1. To ensure proper communication on the I2C bus, it is important to follow a specific sequence when reading/writing data to/from the GNSS module and other slave devices. If the master intends to interact with other slave devices before the GNSS module, you should write GNSS module’s 7-bit slave address (0x50) first, then go on the steps outlined in Step 1-a) to Step 2-b) in Chapter 3.1 Master Data Reading Flow (or Step 1-a) to Step 2-b) in Chapter 4.1 Master Data Writing Flow). Otherwise, a NAK may be generated on the I2C bus. MASTER Operate other I2C slave devices Write GNSS module s 7-bit slave address (0x50) without sending data Step 1-a): Send a configuration read command to the slave Step 1-b): Receive the data length from the slave transmit buffer or free length from the slave receive buffer Step 2-a): Send a configuration read/write command to the slave Step 2-b): Receive the data from slave or write the data to slave Right Sequence MASTER Operate other I2C slave devices Step 1-a): Send a configuration read command to the slave Step 1-b): Receive the data length from the slave transmit buffer or free length from the slave receive buffer NAK may be generated when executing Step 1-b) Step 2-a): Send a configuration read/write command to the slave Step 2-b): Receive the data from slave or write the data to slave × Wrong Sequence Figure 12: Multi-Slave Operation Sequence on I2C Bus L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 20 / 31 Correct Sequence Example GNSS Module Series Incorrect Sequence Example Figure 13: Multi-Slave Operation on I2C Bus Example 1 2. Master cannot operate other I2C slave devices simultaneously when performing I2C data transfer with the GNSS module. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 21 / 31 GNSS Module Series MASTER Write GNSS module s 7-bit slave address (0x50) without sending data Operate other I2C device Step 1-a): Send a configuration read command to the slave Operate other I2C device Step 1-b): Receive the data length from the slave transmit buffer or free length from the slave receive buffer Operate other I2C device Step 2-a): Send a configuration read/write command to the slave Operate other I2C device Step 2-b): Receive the data from slave or write the data to slave It is not allowed to operate other I2C devices between Write GNSS module s 7-bit slave address (0x50) and Step2-b). Figure 14: Incorrect Multi-Slave Operation Sequence on I2C Bus L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 22 / 31 GNSS Module Series Correct Sequence Example Incorrect Sequence Example Figure 15: Multi-Slave Operation on I2C Bus Example 2 L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 23 / 31 GNSS Module Series 6 Sample Code for I2C Reading/Writing Sequence 6.1. Sample Code The sample code for reading data from and writing data to the I2C buffer is shown below. #define QUECTEL_I2C_SLAVE_CR_CMD 0xaa51 #define QUECTEL_I2C_SLAVE_CW_CMD 0xaa53 #define QUECTEL_I2C_SLAVE_CMD_LEN #define QUECTEL_I2C_SLAVE_TX_LEN_REG_OFFSET #define QUECTEL_I2C_SLAVE_TX_BUF_REG_OFFSET 8 0x08 0x2000 #define QUECTEL_I2C_SLAVE_RX_LEN_REG_OFFSET #define QUECTEL_I2C_SLAVE_RX_BUF_REG_OFFSET 0x04 0x1000 #define QUECTEL_I2C_SLAVE_ADDRESS_CR_OR_CW #define QUECTEL_I2C_SLAVE_ADDRESS_R #define QUECTEL_I2C_SLAVE_ADDRESS_W 0x50 0x54 0x58 #define MAX_ERROR_NUMBER 20 #define MAX_I2C_BUFFER 1024 typedef enum { I2C_ACK = 0, I2C_NACK = 1 }I2c_Resp_FlagStatus; typedef enum { DEV_REP_SUCCESS = 0, DEV_REP_ERROR = 1 }Dev_Resp_FlagStatus; L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 24 / 31 GNSS Module Series I2c_Resp_FlagStatus I2c_Master_Receive(uint8_t addr, uint8_t *Data, uint16_t Length) { mcu_i2c_start(); mcu_i2c_send_byte(addr|0x01); if(mcu_i2c_wait_ack() != I2C_ACK) { mcu_i2c_stop(); return I2C_NACK; } for(int i = 0; i < Length; i++) { *(Data + i) = mcu_i2c_receive_byte(); if(i != (Length - 1)) { mcu_i2c_ack(); } } mcu_i2c_no_ack(); mcu_i2c_stop(); return I2C_ACK; } I2c_Resp_FlagStatus I2c_Master_Transmit(uint8_t addr, uint8_t *Data, uint8_t Length) { uint8_t i = 0; uint8_t flag=0; mcu_i2c_start(); mcu_i2c_send_byte(addr); if(mcu_i2c_wait_ack() == I2C_NACK) { mcu_i2c_stop(); return I2C_NACK; } for(i = 0; i < Length; i++) { mcu_i2c_send_byte(*(Data+i)); if(mcu_i2c_wait_ack() == I2C_NACK) { mcu_i2c_stop(); return I2C_NACK; } } mcu_i2c_stop(); return I2C_ACK; L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 25 / 31 GNSS Module Series } Dev_Resp_FlagStatus Quectel_Dev_Receive(uint8_t* pData, uint16_t maxLength, uint16_t* pRecLength) { uint32_t request_cmd[2]; uint16_t* pRxLength = pRecLength; uint8_t* pBuff = pData; uint8_t i2c_master_receive_error_counter = 0; I2c_Resp_FlagStatus status; //step 1_a request_cmd[0] = (uint32_t)((uint32_t)(QUECTEL_I2C_SLAVE_CR_CMD << 16) | QUECTEL_I2C_SLAVE_TX_LEN_REG_OFFSET); request_cmd[1] = 4; i2c_master_receive_error_counter = 0; while(1) { delay_ms(10); status = I2c_Master_Transmit(QUECTEL_I2C_SLAVE_ADDRESS_CR_OR_CW << 1, (uint8_t *)request_cmd, QUECTEL_I2C_SLAVE_CMD_LEN); if(status == I2C_ACK) { break; } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { return DEV_REP_ERROR; } } //step 1_b i2c_master_receive_error_counter = 0; while(1) { delay_ms(10); status = I2c_Master_Receive(QUECTEL_I2C_SLAVE_ADDRESS_R << 1, (uint8_t*)pRxLength, 4); if(status == I2C_ACK) { break; L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 26 / 31 GNSS Module Series } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { return DEV_REP_ERROR; } } if(*pRxLength == 0) { return DEV_REP_ERROR; } if(*pRxLength > MAX_I2C_BUFFER) { *pRxLength = MAX_I2C_BUFFER; } //step 2_a request_cmd[0] = (uint32_t)(QUECTEL_I2C_SLAVE_CR_CMD << 16) | QUECTEL_I2C_SLAVE_TX_BUF_REG_OFFSET; request_cmd[1] = *pRxLength; i2c_master_receive_error_counter = 0; while(1) { delay_ms(10); status = I2c_Master_Transmit(QUECTEL_I2C_SLAVE_ADDRESS_CR_OR_CW << 1, (uint8_t *)request_cmd, QUECTEL_I2C_SLAVE_CMD_LEN); if(status == I2C_ACK) { break; } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { *pRxLength = 0; return DEV_REP_ERROR; } } //step 2_b i2c_master_receive_error_counter = 0; while(1) L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 27 / 31 GNSS Module Series { delay_ms(10); status = I2c_Master_Receive(QUECTEL_I2C_SLAVE_ADDRESS_R << 1, pBuff, *pRxLength); if(status == I2C_ACK) { return DEV_REP_SUCCESS; } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { *pRxLength = 0; return DEV_REP_ERROR; } } return DEV_REP_SUCCESS; } Dev_Resp_FlagStatus Quectel_Dev_Transmit(uint8_t *pData, uint16_t dataLength) { uint32_t request_cmd[2]; uint16_t rxBuffLength = 0; uint8_t i2c_master_receive_error_counter = 0; I2c_Resp_FlagStatus status; //step 1_a request_cmd[0] = (uint32_t)((QUECTEL_I2C_SLAVE_CR_CMD << 16) | QUECTEL_I2C_SLAVE_RX_LEN_REG_OFFSET); request_cmd[1] = 4; i2c_master_receive_error_counter = 0; while(1) { delay_ms(10); status = I2c_Master_Transmit(QUECTEL_I2C_SLAVE_ADDRESS_CR_OR_CW << 1, (uint8_t *)request_cmd, QUECTEL_I2C_SLAVE_CMD_LEN); if(status == I2C_ACK) { break; } L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 28 / 31 GNSS Module Series i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { return DEV_REP_ERROR; } } //step 1_b i2c_master_receive_error_counter = 0; while(1) { delay_ms(10); status = I2c_Master_Receive(QUECTEL_I2C_SLAVE_ADDRESS_R << 1, (uint8_t*)&rxBuffLength, 4); if(status == I2C_ACK) { break; } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { return DEV_REP_ERROR; } } if(dataLength > rxBuffLength) { return DEV_REP_ERROR; } //step 2_a request_cmd[0] = (uint32_t)(QUECTEL_I2C_SLAVE_CW_CMD << 16) | QUECTEL_I2C_SLAVE_RX_BUF_REG_OFFSET; request_cmd[1] = dataLength; i2c_master_receive_error_counter = 0; while(1) { delay_ms(10); status = I2c_Master_Transmit(QUECTEL_I2C_SLAVE_ADDRESS_CR_OR_CW << 1, (uint8_t *)request_cmd, QUECTEL_I2C_SLAVE_CMD_LEN); if(status == I2C_ACK) { L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 29 / 31 GNSS Module Series break; } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { return DEV_REP_ERROR; } } //step 2_b i2c_master_receive_error_counter = 0; while(1) { delay_ms(10); status = I2c_Master_Transmit(QUECTEL_I2C_SLAVE_ADDRESS_W << 1, pData, dataLength); if(status == I2C_ACK) { return DEV_REP_SUCCESS; } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { return DEV_REP_ERROR; } } return DEV_REP_SUCCESS; } L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 30 / 31 GNSS Module Series 7 Appendix References Table 2: Related Documents Document Name [1] Quectel_LC29H_Series&LC79H(AL)_GNSS_Protocol_Specification [2] Quectel_L89_R2.0_GNSS_Protocol_Specification Table 3: Terms and Abbreviations Abbreviation ACK GNSS I2C MCU NAK SCL SDA Description Acknowledge Global Navigation Satellite System Inter-Integrated Circuit Microcontroller Unit Negative Acknowledge Serial Clock Serial Data L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 31 / 31

Quectel_L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note_V1.1

PDF

487.04 KB

LC29H (EA) Moving Base Application Note GNSS Module Series Version: 1.0 Date: 2023-07-20 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. LC29H(EA)_Moving_Base_Application_Note 1 / 26 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. 2023. All rights reserved. LC29H(EA)_Moving_Base_Application_Note 2 / 26 GNSS Module Series Safety Information The following safety precautions must be observed during all phases of operation, such as usage, service, or repair of any terminal or mobile incorporating the module. Manufacturers of the terminal should notify users and operating personnel of the following safety information by incorporating these guidelines into all product manuals. Otherwise, Quectel assumes no liability for customers’ failure to comply with these precautions. Ensure that the product may be used in the country and the required environment, as well as that it conforms to the local safety and environmental regulations. Keep away from explosive and flammable materials. The use of electronic products in extreme power supply conditions and locations with potentially explosive atmospheres may cause fire and explosion accidents. The product must be powered by a stable voltage source, and the wiring shall conform to security precautions and fire prevention regulations. Proper ESD handling procedures must be followed throughout the mounting, handling and operation of any devices and equipment that incorporate the module to avoid ESD damages. LC29H(EA)_Moving_Base_Application_Note 3 / 26 GNSS Module Series About the Document Document Information Title LC29H (EA) Moving Base Application Note Subtitle GNSS Module Series Document Type Application Note Document Status Released Revision History Version Date Description - 2023-03-30 Creation of the document 1.0 2023-07-20 First official release LC29H(EA)_Moving_Base_Application_Note 4 / 26 GNSS Module Series Contents Safety Information....................................................................................................................................... 3 About the Document ................................................................................................................................... 4 Contents ....................................................................................................................................................... 5 Table Index................................................................................................................................................... 6 Figure Index ................................................................................................................................................. 7 1 Introduction .......................................................................................................................................... 8 2 Hardware Design.................................................................................................................................. 9 2.1. Application Interfaces .............................................................................................................. 11 2.1.1. UART Interfaces............................................................................................................. 11 2.1.2. WAKEUP........................................................................................................................ 11 2.1.3. RESET_N....................................................................................................................... 12 2.1.4. RESET_CTL................................................................................................................... 13 3 System Construction......................................................................................................................... 14 3.1. Precautions for GNSS Antenna Mounting .............................................................................. 14 3.1.1. Antenna Mounting Method ............................................................................................. 14 3.1.2. Recommended Mounting for GNSS Antennas .............................................................. 15 4 Reference Frame ................................................................................................................................ 17 4.1. Local Cartesian Coordinate System (ENU) ............................................................................ 17 5 Angle Definition.................................................................................................................................. 18 5.1. Heading ................................................................................................................................... 18 5.2. Pitch......................................................................................................................................... 19 6 Configuration...................................................................................................................................... 21 7 Moving Base Related Messages ...................................................................................................... 22 7.1. PQTMCFGMSGRATE Message............................................................................................. 22 7.2. PQTMTAR Message ............................................................................................................... 23 8 Appendix A References..................................................................................................................... 25 9 Appendix B Special Characters ....................................................................................................... 26 LC29H(EA)_Moving_Base_Application_Note 5 / 26 GNSS Module Series Table Index Table 1: Pin Function Differences for LC29H (EA) in Different Applications............................................... 9 Table 2: Error Codes .................................................................................................................................. 23 Table 3: Related Documents...................................................................................................................... 25 Table 4: Terms and Abbreviations ............................................................................................................. 25 Table 5: Special Characters ....................................................................................................................... 26 LC29H(EA)_Moving_Base_Application_Note 6 / 26 GNSS Module Series Figure Index Figure 1: Schematic Diagram of Connection Between Base and Rover................................................... 10 Figure 2: Reference Design of UART1 Interface on Base......................................................................... 11 Figure 3: Reference Design of UART1 Interface on Rover ....................................................................... 11 Figure 4: Enter/Exit Backup Mode Sequence ............................................................................................ 12 Figure 5: Reference OC Circuit for Base Reset......................................................................................... 13 Figure 6: Antenna Mounting Top View....................................................................................................... 14 Figure 7: Antenna Mounting (Same Reference Ground Plane) ................................................................ 14 Figure 8: Antenna Mounting – Drone......................................................................................................... 15 Figure 9: Antenna Mounting – Mower........................................................................................................ 15 Figure 10: Antenna Mounting – Vehicle..................................................................................................... 16 Figure 11: Local Cartesian Coordinate System ......................................................................................... 17 Figure 12: Heading and Pitch Angles ........................................................................................................ 18 Figure 13: Heading Angle .......................................................................................................................... 19 Figure 14: Pitch Angle ................................................................................................................................ 20 LC29H(EA)_Moving_Base_Application_Note 7 / 26 GNSS Module Series 1 Introduction This document presents the software and hardware designs of the two LC29H (EA) modules in the Moving Base application. Quectel LC29H (EA) supports multi-band RTK technology, which can output high precision position, heading and attitude information. RTK technology includes the rover and the base. The base sends a differential correction data stream to the rover via a communication link continuously. In standard RTK mode, the base remains static in a known position, while the rover can move. However, in Moving Base mode, both the base and the rover can move, making it suitable for use in drones, mowers and vehicles. To enable the Moving Base function, both two LC29H (EA) modules must be installed on the same carrier platform. The terms 'base', 'rover', 'baseline' and 'heading' are used to describe the functionality of the Moving Base. ⚫ Base: Receiver that transmits the different correction data stream. ⚫ Rover: Receiver that receives the different correction data stream. ⚫ Baseline: Vector connecting the base antenna to the rover antenna. The LC29H (EA) Moving Base function supports baseline lengths varying from 0.2 m to 5 m. ⚫ Heading: Angle from true north to baseline measured in a clockwise direction. LC29H(EA)_Moving_Base_Application_Note 8 / 26 GNSS Module Series 2 Hardware Design For two LC29H (EA) modules, one can be select as a base and the other as a rover. The base and rover can be distinguished from the connection diagram. The base communicates with the MCU via its UART1, and the rover communicates with the UART2 on base via its UART1. Figure 1: Schematic Diagram of Connection Between Base and Rover illustrates the specific connection configuration. In the Moving Base application, function configurations of pins 5, 6 and 15–19 are different from those in the general application, as shown in below. Table 1: Pin Function Differences for LC29H (EA) in Different Applications Pin No. General Application (Single Module) Pin Function Moving Base Application (Two Modules) 5 D_SEL1: Selects UART1/I2C/SPI 6 D_SEL2: Selects UART1/I2C/SPI 15 TXD2: UART2 transmits data RESERVED RESERVED RESERVED 16 RXD2: UART2 receives data RESERVED 17 WI: Warning indicator RESET_CTL: Controls the RESET_N of the rover 18 I2C_SDA/SPI_CS: I2C serial data/SPI chip-select TXD2: UART2 transmits data 19 I2C_SCL/SPI_CLK: I2C serial clock/SPI clock RXD2: UART2 receives data LC29H(EA)_Moving_Base_Application_Note 9 / 26 GNSS Module Series External Corrections NMEA + Heading (Proprietary Messages) MCU_RXD MCU_TXD GPIO_X GPIO_X GPIO_X MCU Antenna Circuit 1 WAKEUP GND 24 2 RESERVED VCC 23 3 1PPS V_BCKP 22 4 RESERVED RXD1 21 5 RESERVED TXD1 20 6 RESERVED LC29H (EA) 7 VDD_EXT (Base) RXD2 19 TXD2 18 8 RESET_N 9 VDD_RF 10 GND 11 RF_IN 12 GND RESET_CTL 17 RESERVED 16 RESERVED 15 ANT_ON 14 GND 13 VCC_3.3 V_Base V_BCKP_3.3 V_Base Derived Heading Local Corrections GPIO_X GPIO_X 1 WAKEUP GND 24 2 RESERVED VCC 23 3 1PPS V_BCKP 22 4 RESERVED RXD1 21 5 RESERVED TXD1 20 6 RESERVED LC29H (EA) 7 VDD_EXT (Rover) RXD2 19 TXD2 18 VCC_3.3 V_Rover V_BCKP_3.3 V_Rover Antenna Circuit 8 RESET_N 9 VDD_RF 10 GND 11 RF_IN 12 GND RESET_CTL 17 RESERVED 16 RESERVED 15 ANT_ON 14 GND 13 I/O PO WER GND SY STEM ANT RESERVED Direct Connection Not Direct Connection Figure 1: Schematic Diagram of Connection Between Base and Rover ⚫ External Corrections: External corrections can be obtained from the VRS provider. The MCU sends the RTCM corrections from the VRS to the base, enabling it to perform the RTK positioning function. ⚫ Local Corrections: Local corrections are provided by the base and transmitted via its UART2 interface to the rover to calculate heading information. ⚫ Derived Heading: Heading information is calculated by the rover and sent back to the base, and finally output by the base. ⚫ NMEA + Heading (Proprietary Messages): Positioning data (standard NMEA messages) and heading information (proprietary NMEA messages) are sent from the base to the MCU. The connection between the MCU and the base is required. LC29H(EA)_Moving_Base_Application_Note 10 / 26 GNSS Module Series NOTE 1. The modules operate at an I/O voltage of 2.8 V. If the I/O voltage of the MCU differs from this value, a level-shifting circuit must be used. 2. It is recommended to use an OC drive circuit for the RESET_N pin of base. For more information, see Chapter 2.1.3 RESET_N. 2.1. Application Interfaces 2.1.1. UART Interfaces The UART1 on the base is connected to MCU, as shown below: MCU MCU_TXD MCU_RXD GND LC29H (EA) (Base) TXD1 RXD1 GND Figure 2: Reference Design of UART1 Interface on Base The UART1 on the rover is connected to the UART2 on the base, as shown below: LC29H (EA) (Base) TXD2 RXD2 GND LC29H (EA) (Rover) TXD1 RXD1 GND Figure 3: Reference Design of UART1 Interface on Rover 2.1.2. WAKEUP For power-sensitive applications, the module supports a Backup mode to reduce power consumption. Pull the WAKEUP pin high for at least 10 ms to wake up the module from the Backup mode. Keep this pin LC29H(EA)_Moving_Base_Application_Note 11 / 26 GNSS Module Series open or pulled low before entering the Backup mode. The WAKEUP pin is pulled down internally and it belongs to backup domain. If unused, leave the pin N/C. The base can synchronously transmit the commands received from the MCU to the rover via UART interfaces. Thus, the MCU sends commands to the base via UART interfaces to enable the base and the rover enter the Backup mode at the same time. ⚫ Enter the Backup mode: 1. Send $PAIR650 to shut down internal main power supply in sequence. For more information about the relevant software command, see document [1] protocol specification. 2. Cut off the power supply to the VCC pin and keep the V_BCKP pin powered. ⚫ Exit the Backup mode: 1. Restore VCC. 2. Pull the WAKEUP pin high for at least 10 ms. V_BCKP Enter Backup mode Low power consumption Exit Backup mode VCC below 100 mV 1 s WAKEUP 10 ms UART Valid Continuous mode Send command Invalid Valid Backup mode Continuous mode Cut off VCC Restore VCC Pull WAKEUP high Figure 4: Enter/Exit Backup Mode Sequence NOTE The WAKEUP pin is pulled down internally with a 47 kΩ resistor, and the GPIO of MCU connected to the WAKEUP pin needs to support push-pull output. 2.1.3. RESET_N RESET_N is an input pin. The module can be reset by driving the RESET_N pin low for at least 100 ms and then releasing it. For the base, the RESET_N pin is connected to the GPIO control pin of the MCU. An OC driver circuit as shown below is recommended to control the RESET_N pin. LC29H(EA)_Moving_Base_Application_Note 12 / 26 Input pulse RESET_N GNSS Module Series Figure 5: Reference OC Circuit for Base Reset For the rover, the RESET_N pin is connected in series with the RESET_CTL pin of the base through a 0 Ω resistor for upgrading. 2.1.4. RESET_CTL For the base, the RESET_CTL is used to control the RESET_N of the rover for upgrading. The RESET_N pin of the base is pulled down via the GPIO of the MCU to complete the base’s upgrading, and then the RESET_CTL is pulled down automatically so that the RESET_N pin of the rover is also pulled down, allowing the rover’s upgrading to be completed. The default state is 2.8 V high level, active low. For the rover, leave the pin floating. LC29H(EA)_Moving_Base_Application_Note 13 / 26 GNSS Module Series 3 System Construction This chapter provides system-level recommendations for using the base and rover to develop high-performance Moving Base solutions. 3.1. Precautions for GNSS Antenna Mounting 3.1.1. Antenna Mounting Method In practical applications, it is important to fix GNSS antennas during mounting, as shown in the following figure. The vector from the base antenna to the rover antenna is called the baseline. Its minimum length is 0.2 m. Base Antenna Rover Antenna Figure 6: Antenna Mounting Top View If the orientation test is carried out on the same device, ensure to use two identical GNSS antennas and place them on the same reference ground plane (with the same ground plane size, shape, angle of the horizontal plane). However, the use of a helix antenna does not require reference ground plane. Base Antenna Rover Antenna Figure 7: Antenna Mounting (Same Reference Ground Plane) LC29H(EA)_Moving_Base_Application_Note 14 / 26 GNSS Module Series 3.1.2. Recommended Mounting for GNSS Antennas The recommended mounting for GNSS antennas depends on the application. For a drone, place the GNSS antennas on top of the drone to avoid interference from crowded structures and motors, as shown in the figure below: Figure 8: Antenna Mounting – Drone For mowers, apply the GNSS antennas in an open, unstructured environment. Figure 9: Antenna Mounting – Mower LC29H(EA)_Moving_Base_Application_Note 15 / 26 GNSS Module Series For a vehicle, apply GNSS antennas in the same plane and unstructured environment. Figure 10: Antenna Mounting – Vehicle NOTE For recommended antenna selection and design, see document [2] GNSS antenna selection guidance or contact Quectel Technical Support (support@quectel.com). LC29H(EA)_Moving_Base_Application_Note 16 / 26 GNSS Module Series 4 Reference Frame 4.1. Local Cartesian Coordinate System (ENU) Local Cartesian coordinate system is a right-handed rectangular coordinate system where the coordinate origin is located at the station center. In the Moving Base application, the phase center of the base antenna is considered the station center, and the heading and pitch angle outputs of rover are referenced to this coordinate system. Sky (U) R Rover Antenna B Base Antenna East (E) Figure 11: Local Cartesian Coordinate System LC29H(EA)_Moving_Base_Application_Note 17 / 26 GNSS Module Series 5 Angle Definition This chapter provides the definitions of the heading and pitch angles in the LC29H (EA) Moving Base applications. H ead ing Base Antenna B R Pitch Rover Antenna Roll Figure 12: Heading and Pitch Angles NOTE Roll angle is not supported by the LC29H (EA) Moving Base applications. 5.1. Heading The heading angle in the dual antenna setup is referenced to the local Cartesian coordinate system (ENU). It is defined as the angle between the projection of the baseline vector (i.e., the vector connecting the base antenna and rover antenna) on the horizontal plane and the true north (i.e., N-axis) with the effective range of [0,360). For details about the heading angle output, see Chapter 7.2 PQTMTAR Message. The heading angle (with north and east directions as reference planes) is illustrated below: LC29H(EA)_Moving_Base_Application_Note 18 / 26 North (N) Rover Antenna R GNSS Module Series Base Antenna B Figure 13: Heading Angle East (E) NOTE This heading angle is derived using dual antenna orientation, and it is different from the heading angle output in RMC message. 5.2. Pitch The pitch angle references local Cartesian coordinate system (ENU). It is the angle between the baseline vector (base antenna to rover antenna) and the horizontal plane, with a range of [-90,+90]. Positive values correspond to upward pitch, while negative values correspond to downward pitch. For details about the pitch angle output, see Chapter 7.2 PQTMTAR Message. The pitch angle is illustrated below: LC29H(EA)_Moving_Base_Application_Note 19 / 26 Sky (U) GNSS Module Series R Rover Antenna B Base Antenna Horizontal Plane Figure 14: Pitch Angle LC29H(EA)_Moving_Base_Application_Note 20 / 26 GNSS Module Series 6 Configuration As long as the two LC29H (EA) modules are properly connected as shown in Figure 1: Schematic Diagram of Connection Between Base and Rover, the system automatically identifies them as rover or base and no special configuration is required for the Moving Base application. The heading and attitude information are provided by $PQTMTAR message on the rover. Use $PQTMCFGMSGRATE command (see Chapter 7.1 PQTMCFGMSGRATE Message for details) to enable the output of $PQTMTAR message (see Chapter 7.2 PQTMTAR Message for details). Example: //Enable $PQTMTAR message: $PQTMCFGMSGRATE,W,PQTMTAR,1,1*09 $PQTMCFGMSGRATE,OK*29 LC29H(EA)_Moving_Base_Application_Note 21 / 26 GNSS Module Series 7 Moving Base Related Messages 7.1. PQTMCFGMSGRATE Message Configures the message output rate on the current port. Type: Set/Get Synopsis: //Set: $PQTMCFGMSGRATE,W,,,* //Get: $PQTMCFGMSGRATE,R,,* Parameter: Field Format String Numeric Numeric Unit Description - Configuration message name. Message output rate. - 0 = Output disabled. 1 = Output once every position fix. - Message version. Result: ⚫ If successful, the module returns: //Response to Set command: $PQTMCFGMSGRATE,OK* //Response to Get command: $PQTMCFGMSGRATE,OK,,,* LC29H(EA)_Moving_Base_Application_Note 22 / 26 ⚫ If failed, the module returns: $PQTMCFGMSGRATE,ERROR,* For details about , see Table 2: Error Codes. GNSS Module Series Table 2: Error Codes Field Format Unit Numeric - Example: //Enable $PQTMTAR message: $PQTMCFGMSGRATE,W,PQTMTAR,1,1*09 $PQTMCFGMSGRATE,OK*29 Description Error code. 1 = Invaild parameters. 2 = Execution failed. NOTE The set command will take effect after sending $PQTMSAVEPAR*5A (see document [1] protocol specification for details) and resetting the module. 7.2. PQTMTAR Message Outputs the UTC and attitude of the module (rover). This message can be enabled or disabled by $PQTMCFGMSGRATE command. Type: Output Synopsis: $PQTMTAR,,,,,,,,,,< Res3>,,* LC29H(EA)_Moving_Base_Application_Note 23 / 26 GNSS Module Series Parameter: Field Format Unit Numeric - hhmmss.sss - Numeric - - - Description Message version. 1 = Version 1 (Always 1 for this message version.) UTC time. hh: Hours (00–23) mm: Minutes (00–59) ss: Seconds (00–59) sss: Decimal fraction of seconds GNSS quality indicator: 0 = Fix not available or invalid 1 = GPS SPS mode 2 = Differential GPS, SPS mode 4 = Real Time Kinematic (RTK) mode. System used in RTK mode with fixed integers. 5 = Float RTK mode. Satellite system used in RTK mode, floating integers. Reserved. Always null. Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Meter Degree Degree Degree Degree Degree Degree - Baseline length. Pitch angle. Range: -90.000000 to 90.000000. Note that this field is null in case of an invalid value. Reserved. Always null. Heading angle. Range: 0.000000 to 359.999999. Note that this field is null in case of an invalid value. Vehicle pitch accuracy. Note that this field is null in case of an invalid value. Reserved. Always null. Vehicle heading accuracy. Note that this field is null in case of an invalid value. Number of satellites used in heading solution. Example: $PQTMTAR,1,165034.000,4,,0.860,1.124780,,50.968541,0.254125,,0.012547,21*59 LC29H(EA)_Moving_Base_Application_Note 24 / 26 GNSS Module Series 8 Appendix A References Table 3: Related Documents Document Name [1] Quectel_LC29H_Series&LC79H(AL)_GNSS_Proocol_Specification [2] Quectel_GNSS_Antenna_Selection_Guidance Table 4: Terms and Abbreviations Abbreviation ENU GNSS I/O MCU RF RMC RTK RXD TXD UART UTC VRS Description East North Up Global Navigation Satellite System Input/Output Microcontroller Unit/Microprogrammed Control Unit Radio Frequency Recommended Minimum Specific GNSS Data Real-Time Kinematic Receive Data (Pin) Transmit Data (Pin) Universal Asynchronous Receiver/Transmitter Coordinated Universal Time Virtual Reference Station LC29H(EA)_Moving_Base_Application_Note 25 / 26 GNSS Module Series 9 Appendix B Special Characters Table 5: Special Characters Special Character [...] {…} Underline Definition Carriage return character. Line feed character. Parameter name. Angle brackets do not appear in the message. Optional field of a message. Square brackets do not appear in the message. Repeated field of a message. Curly brackets do not appear in the message. Default setting of a parameter. LC29H(EA)_Moving_Base_Application_Note 26 / 26

Quectel_LC29H(EA)_Moving_Base_Application_Note_V1.0

PDF

511.58 KB

BC660K-GL&BC950K-GL CoAP Application Note NB-IoT Module Series Version: 1.0 Date: 2023-07-07 Status: Released 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&BC950K-GL_CoAP_Application_Note 1 / 31 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. 2023. All rights reserved. BC660K-GL&BC950K-GL_CoAP_Application_Note 2 / 31 NB-IoT Module Series About the Document Revision History Version 1.0 Date 2023-04-13 2023-07-07 Author Description Randy LI/ Caden ZHANG Yance YANG/ Randy LI/ Caden ZHANG Creation of the document First official release BC660K-GL&BC950K-GL_CoAP_Application_Note 3 / 31 NB-IoT Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 2 Description of CoAP 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. AT Command Details ................................................................................................................. 8 2.3.1. AT+QCOAPCFG Configure Optional Parameters of CoAP Client .............................. 8 2.3.2. AT+QCOAPOPEN Create a CoAP Context............................................................... 10 2.3.3. AT+QCOAPCLOSE Delete a CoAP Context ............................................................. 11 2.3.4. AT+QCOAPOPTION Configure CoAP Message Options ......................................... 12 2.3.5. AT+QCOAPHEAD Configure CoAP Message ID and Token .................................... 15 2.3.6. AT+QCOAPSEND Send CoAP Message .................................................................. 17 3 Description of CoAP URC ................................................................................................................ 21 4 Example ............................................................................................................................................. 24 4.1. Register to IoT Platform Without DTLS ................................................................................... 24 4.2. Register to IoT Platform with DTLS ......................................................................................... 25 5 Summary of Result Codes ............................................................................................................... 28 6 Summary of Error Codes ................................................................................................................. 29 7 Appendix References ....................................................................................................................... 30 BC660K-GL&BC950K-GL_CoAP_Application_Note 4 / 31 NB-IoT Module Series Table Index Table 1 : Types of AT Commands ............................................................................................................... 7 Table 2 : Description of Codes..................................................................................................... 28 Table 3 : General Errors (27.007) .............................................................................................................. 29 Table 4 : Related Documents..................................................................................................................... 30 Table 5 : Terms and Abbreviations ............................................................................................................ 30 BC660K-GL&BC950K-GL_CoAP_Application_Note 5 / 31 NB-IoT Module Series 1 Introduction This document explains how to use the CoAP feature on Quectel BC660K-GL and BC950K-GL modules through AT commands. BC660K-GL&BC950K-GL_CoAP_Application_Note 6 / 31 NB-IoT Module Series 2 Description of CoAP 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 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. BC660K-GL&BC950K-GL_CoAP_Application_Note 7 / 31 NB-IoT 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. AT Command Details 2.3.1. AT+QCOAPCFG Configure Optional Parameters of CoAP Client This command configures optional parameters of a CoAP client. AT+QCOAPCFG Configure Optional Parameters of CoAP Client Write Command Query/Set the DTLS mode for a specified CoAP client. AT+QCOAPCFG='dtls',[,] Response If the optional parameter is omitted, query the current setting: +QCOAPCFG: 'dtls', OK If the optional parameter is specified, set the DTLS mode for the specified CoAP client: OK Write Command Query/Set the PSK used in handshake for a specified CoAP client. AT+QCOAPCFG='psk',[,,] If there is any error: ERROR Or +CME ERROR: Response If the optional parameters are omitted, query the current setting: +QCOAPCFG: 'psk',, OK If the optional parameters are specified, set the PSK used in handshake for a specified CoAP client: OK BC660K-GL&BC950K-GL_CoAP_Application_Note 8 / 31 NB-IoT Module Series Maximum Response Time Characteristics If there is any error: ERROR Or +CME ERROR: 300 ms This command takes effect immediately; The configurations are not saved. Parameter Integer type. CoAP client identifier. Range: 0–4. Integer type. Whether to enable DTLS mode for CoAP client. 0 Use normal UDP connection for CoAP client 1 Use DTLS connection for CoAP client String type. PSK identity. Length: 0–152. Unit: byte. Hex string type. PSK key. Length: 0–256. Unit: byte. Integer type. Error code. See Chapter 6 for more details. Example AT+QCOAPCFG='dtls',0,1 OK AT+QCOAPCFG='dtls',0 +QCOAPCFG: 'dtls',1 //Use DTLS connection for CoAP client. //Query the current DTLS configuration. OK //Set the handshake PSK for the specified CoAP client. AT+QCOAPCFG='psk',0,'869154040004132','46694a6871617a3062706d68454c6e4c' OK AT+QCOAPCFG='psk',0 //Query the handshake PSK for the specified CoAP client. +QCOAPCFG: 'psk','869154040004132','46694a6871617a3062706d68454c6e4c' OK AT+QCOAPOPEN=0,'220.180.239.212',8032 OK //Create a CoAP context. +QCOAPOPEN: 0,0 BC660K-GL&BC950K-GL_CoAP_Application_Note 9 / 31 NB-IoT Module Series 2.3.2. AT+QCOAPOPEN Create a CoAP Context This command creates a CoAP context. AT+QCOAPOPEN Create a CoAP Context Test Command AT+QCOAPOPEN=? Response +QCOAPOPEN: (range of supported s),,(range of supported s) Read Command AT+QCOAPOPEN? OK Response [+QCOAPOPEN: ,,,] Write Command AT+QCOAPOPEN=,, OK Response OK +QCOAPOPEN: , Maximum Response Time Characteristics If there is any error: ERROR Or +CME ERROR: 300 ms This command takes effect immediately; The configurations are not saved. Parameter Integer type. CoAP client identifier. Range: 0–4. String type. CoAP server address. It can only be an IP address in IPv4 or IPv6. Maximum length: 100 bytes. Integer type. CoAP server port. Range: 1–65535. Integer type. Current status of the specified CoAP client. 0 Idle or disconnected. 1 CoAP client is opening. 2 CoAP client is connecting to the CoAP server. 3 CoAP client is connected to the CoAP server. 4 CoAP client is disconnecting from the CoAP server. Integer type. Command execution result. See Chapter 5 for details. Integer type. Error codes. See Chapter 6 for details. BC660K-GL&BC950K-GL_CoAP_Application_Note 10 / 31 NB-IoT Module Series Example AT+QCOAPOPEN=? //Query the supported parameter value. +QCOAPOPEN: (0-4),,(1-65535) OK AT+QCOAPOPEN=0,'220.180.239.212',8032 OK //Create a CoAP context. +QCOAPOPEN: 0,0 AT+QCOAPOPEN? +QCOAPOPEN: 0,'220.180.239.212',8032,3 //Query the current status of the CoAP client. OK 2.3.3. AT+QCOAPCLOSE Delete a CoAP Context This command deletes a CoAP context. AT+QCOAPCLOSE Delete a CoAP Context Test Command AT+QCOAPCLOSE=? Response +QCOAPCLOSE: (range of supported s) Write Command AT+QCOAPCLOSE= OK Response OK +QCOAPCLOSE: , Maximum Response Time Characteristics If there is any error: ERROR Or +CME ERROR: 300 ms / Parameter Integer type. CoAP client identifier. Range: 0–4. Integer type. Command execution result. See Chapter 5 for details. Integer type. Error codes. See Chapter 6 for details. BC660K-GL&BC950K-GL_CoAP_Application_Note 11 / 31 Example AT+QCOAPCLOSE=? +QCOAPCLOSE: (0-4) OK AT+QCOAPOPEN=0,'220.180.239.212',8032 OK +QCOAPOPEN: 0,0 AT+QCOAPCLOSE=0 OK +QCOAPCLOSE: 0,0 NB-IoT Module Series //Query the supported parameter value. //Create a CoAP context. //Delete a CoAP context. 2.3.4. AT+QCOAPOPTION Configure CoAP Message Options This command configures the options of a CoAP message. AT+QCOAPOPTION Configure CoAP Message Options Test Command AT+QCOAPOPTION=? Response +QCOAPOPTION: (range of supported s),(list of supported s),,(range of supported s),,(list of supported s) Write Command If is not 11 AT+QCOAPOPTION=,,,, Write Command If is 11 AT+QCOAPOPTION=,,,,[,] OK Response OK If there is any error: ERROR Or +CME ERROR: Response If the optional parameter is omitted, use '/' to divide Uri-Path into multiple CoAP options by default: OK If the optional parameter is specified, configure Uri-Path message options: OK If there is any error: BC660K-GL&BC950K-GL_CoAP_Application_Note 12 / 31 NB-IoT Module Series Maximum Response Time Characteristics ERROR Or +CME ERROR: 300 ms This command takes effect immediately; The configurations are not saved. Parameter Integer type. CoAP client identifier. Range: 0–4. Integer type. Index of the CoAP option to be added/deleted. Only 0 is supported currently, indicating not to configure any option index. Integer type. CoAP option name. See RFC 7252 and RFC7959 for details. 1 If-Match 3 Uri-Host 4 ETag 5 If-None-Match 6 Observe 8 Location-Path 11 Uri-Path 12 Content-Format 14 Max-Age 15 Uri-Query 17 Accept 20 Location-Query 23 Block2 27 Block1 28 Size2 35 Proxy-Uri Integer type. Length of . Range: 0–255. Unit: byte. String type. CoAP option values. Maximum length: 255 bytes. See RFC 7252 and RFC7959 for details. If is 23 or 27, use the formula below, which requires inputting the expected values of block_num, block_more and block_size, to calculate the value of : = (block_num << 4) | (block_more&0x8) | log2(block_size/16) If is 12 or 17, the value of is as follows: '0' Text-plain '40' Application/link-format '41' Application/xml '42' Application/octet-stream '47' Application/exi '50' Application/json BC660K-GL&BC950K-GL_CoAP_Application_Note 13 / 31 NB-IoT Module Series Integer type. Indicates whether the CoAP option value is segmented, and only need to be configured when =11 (the option is Uri-path). 0 Use '/' to divide Uri-Path into multiple CoAP options 1 Uri-Path as a whole Integer type. Error codes. See Chapter 6 for details. Example AT+QCOAPOPTION=? +QCOAPOPTION: (0-4),(0),,(0-255),,(0,1) OK //Set the CoAP option to 11 (Uri-path), and specify the CoAP option value as 'rd'. The length of the value is 2 bytes, and Uri-path is divided using '/' as a separator. AT+QCOAPOPTION=0,0,11,2,'rd' OK //Set the CoAP option to 15 (Uri-Query), and specify the CoAP option value as 'ep=86370303'. The length of the value is 11 bytes. AT+QCOAPOPTION=0,0,15,11,'ep=86370303' OK NOTE Please note the option definitions in the table below: 1 (If-Match) String type 3 (Uri-Host) String type 4 (ETag) String type 5 (If-None-Match) NULL 6 (Observe) Integer type 8 (Location-Path) String type 11 (Uri-Path) String type 12 (Content-Format) String type 14 (Max-Age) Integer type 15 (Uri-Query) String type Range: 0–8 Range: 1–255 Range: 1–8 supports 0 only Range: 0–255 Range: 0–255 Range: 0–255 Range: 1–255 Range: 0–255 Range: 0–255 BC660K-GL&BC950K-GL_CoAP_Application_Note 14 / 31 17 (Accept) 20 (Location-Query) 23 (Block2) 27 (Block1) 28 (Size2) 35 (Proxy-Uri) String type String type Integer type Integer type Integer type String type NB-IoT Module Series Range: 1–255 Range: 0–255 Range: 0–255 Range: 0–255 Range: 0–255 Range: 1–255 2.3.5. AT+QCOAPHEAD Configure CoAP Message ID and Token This command sets the CoAP message ID and token. AT+QCOAPHEAD Configure CoAP Message ID and Token Test Command AT+QCOAPHEAD=? Response +QCOAPHEAD: (range of supported s),(range of supported s),(range of supported ),(range of supported s), OK Write Command AT+QCOAPHEAD=,[,[][,,]] If there is any error: ERROR Or +CME ERROR: Response OK If there is any error: ERROR Or +CME ERROR: Maximum Response Time 300 ms Characteristics This command takes effect immediately; The configurations are not saved. Parameter Integer type. CoAP client identifier. Range: 0–4. BC660K-GL&BC950K-GL_CoAP_Application_Note 15 / 31 NB-IoT Module Series Integer type. Message ID and token mode selection. Range: 0–5. 0 Generate message ID and token values randomly. 1 Generate message ID randomly, and set the token value. 2 Generate message ID randomly, token value is omitted. 3 Set message ID only; token value is omitted. 4 Set message ID; generate token values randomly. 5 Configure message ID and token values. Integer type. CoAP message ID, which only needs to be configured when the is 3, 4 or 5. Range: 0–65535. Integer type. Length of token values, which only needs to be configured when the is 1 or 5. Range: 1–8. Unit: byte. String in Hex. Token values, which can be configured when the is 1 or 5. Integer type. Error codes. See Chapter 6 for details. Example AT+QCOAPHEAD=? //Query the supported parameter range. +QCOAPHEAD: (0-4),(0-5),(0-65535),(1-8), OK AT+QCOAPHEAD=0,0 //Generate message ID and token values randomly. OK AT+QCOAPHEAD=0,1,4,'02040608' //Generate message ID randomly, and set the token value to '02040608'. OK AT+QCOAPHEAD=0,2 //Generate message ID randomly, token value is omitted. OK AT+QCOAPHEAD=0,3,13940 //Set the Message ID to 13940; token value is omitted. OK AT+QCOAPHEAD=0,4,13940 //Set the Message ID to 13940, and randomly generate the token value. OK AT+QCOAPHEAD=0,5,13940,4,'02040608' //Set the Message ID to 13940 and the token value to '02040608'. OK NOTE If this command is not used, the module will randomly generate CoAP Message ID and the token value by default. BC660K-GL&BC950K-GL_CoAP_Application_Note 16 / 31 NB-IoT Module Series 2.3.6. AT+QCOAPSEND Send CoAP Message This command sends data to the CoAP server. After the CON data is sent, the result will be automatically provided to the terminal. The CON data state can also be queried by the AT+QCOAPSEND= through the terminal. AT+QCOAPSEND Send CoAP Message Test Command AT+QCOAPSEND=? Response +QCOAPSEND: (range of supported s),(range of supported s),,(list of suppo rted s),(range of supported s), Write Command AT+QCOAPSEND= OK Response +QCOAPSEND: , OK Write Command AT+QCOAPSEND=,,< method/rspcode>, After > is returned, input to be sent. Tap 'Ctrl' + 'Z' to send the data, or tap 'Esc' to cancel the operation. Write Command AT+QCOAPSEND=,,< method/rspcode>,, After > is returned, input to be sent. When the is reached, the data will send automatically. If there is any error: ERROR Or +CME ERROR: Response > input the data to be sent OK If there is any error: ERROR Or +CME ERROR: Response If is 0: OK If is not 0: > input the data to be sent OK If there is any error: ERROR Or BC660K-GL&BC950K-GL_CoAP_Application_Note 17 / 31 NB-IoT Module Series +CME ERROR: Write Command AT+QCOAPSEND=,,< method/rspcode>,,, Response OK If there is any error: ERROR Or +CME ERROR: Maximum Response Time 300 ms Characteristics This command take effect immediately; The configuration is not saved. Parameter Integer type. CoAP client identifier. Range: 0–4. Integer type. CoAP message type. For details, refer to RFC 7252. 0 Confirmable (CON) 1 Non-confirmable (NON) 2 Acknowledgement (ACK) 3 Reset (RST) Integer type. CoAP request method. Refer to the RFC 7252. 1 GET 2 POST 3 PUT 4 DELETE Integer type. CoAP response code. Refer to the RFC 7252. 0 Empty Message 201 2.01, Created 202 2.02, Deleted 203 2.03, Valid 204 2.04, Changed 205 2.05, Content 400 4.00, Bad Request 401 4.01, Unauthorized 402 4.02, Bad Option 403 4.03, Forbidden 404 4.04, Not Found 405 4.05, Method Not Allowed 406 4.06, Not Acceptable 412 4.12, Precondition Failed 413 4.13, Request Entity Too Large 415 4.15, Unsupported Content-Format BC660K-GL&BC950K-GL_CoAP_Application_Note 18 / 31 NB-IoT Module Series 500 5.00, Internal Server Error 501 5.01, Not Implemented 502 5.02, Bad Gateway 503 5.03, Service Unavailable 504 5.04, Gateway Timeout 505 5.05, Proxying Not Supported Integer type. CoAP data packet adding options. Currently only 0 is supported, indicating no option is added to the CoAP packet. Integer type. Length of data to be sent. Range: 0–1024. Unit: byte. String type. Data to be sent. If > is returned, the input data is a text string, otherwise, it is in hexadecimal format. Integer type. Status of sent CON data. 0 Not sent 1 Sent, waiting for response from the CoAP server 2 Failed sending 3 Timeout 4 Sent successfully 5 Get reset message Integer type. Error codes. See Chapter 6 for details. Example AT+QCOAPSEND=? +QCOAPSEND: (0-4),(0-3),,(0),(0-1024), OK AT+QCOAPSEND=0 +QCOAPSEND: 0,0 OK //Send a CON type GET request to the server. AT+QCOAPSEND=0,0,1,0,127,'683836373732353033303536393638390202000000000000010060B8 07B7C89F893C3AE82E2E9527598E16DAB2CDC5D92B65EE24665F21DA270272DF7DC0BEC89D7 DCDFDF33EC4F22C83D927DF1DD6A84D42EE14510951C31967B1EA7CC6E83C00B9CD410E53D A35F8A76D53DD6CBC9CF0D1246F3F481D7FEE6D0B0000E516' OK +QCOAPURC: 0,2,205,26924,133,6,'514CE1000000',12,'0',14,'196607',133,'This is a test server made with libcoap (see https://libcoap.net)Copyright (C) 2010--2021 Olaf Bergmann and others' //Received a response from the server. AT+QCOAPSEND=0 +QCOAPSEND: 0,4 //Data was sent successfully. OK BC660K-GL&BC950K-GL_CoAP_Application_Note 19 / 31 NB-IoT Module Series NOTE 1. It is recommended to retrieve the CON data status through AT+QCOAPSEND= before sending the next CON or NON data. 2. AT+QCOAPSEND= is only used to query the status of previously sent CON data. 3. URC +QCOAPURC: ,,,,[,,][,,[,...]][,,] is reported upon successful transmission and receiving a response from the server. See Chapter 3 for details. BC660K-GL&BC950K-GL_CoAP_Application_Note 20 / 31 NB-IoT Module Series 3 Description of CoAP URC This provides an overview and description of the CoAP-related URC and its functionalities. +QCOAPURC Notify TE to Respond to Requests from CoAP Server +QCOAPURC: ,,,,[,,] [,,[,...]][,,] Notify TE to respond to requests from CoAP server or to handle the response from the CoAP server Parameter Integer type. CoAP client identifier. Integer type. CoAP message type, refer to the RFC 7252. 0 Confirmable (CON) 1 Non-confirmable (NON) 2 Acknowledgement (ACK) 3 Reset (RST) Integer type. CoAP request method, refer to the RFC 7252. 1 GET 2 POST 3 PUT 4 DELETE Integer type. CoAP response code, refer to the RFC 7252. 0 Empty Message 201 2.01, Created 202 2.02, Deleted 203 2.03, Valid 204 2.04, Changed 205 2.05, Content 400 4.00, Bad Request 401 4.01, Unauthorized 402 4.02, Bad Option 403 4.03, Forbidden 404 4.04, Not Found 405 4.05, Method Not Allowed 406 4.06, Not Acceptable BC660K-GL&BC950K-GL_CoAP_Application_Note 21 / 31 NB-IoT Module Series 412 4.12, Precondition Failed 413 4.13, Request Entity Too Large 415 4.15, Unsupported Content-Format 500 5.00, Internal Server Error 501 5.01, Not Implemented 502 5.02, Bad Gateway 503 5.03, Service Unavailable 504 5.04, Gateway Timeout 505 5.05 Proxying Not Supported Integer type. CoAP message ID. Range: 0–65535. Integer type. Indicates the presence of a token, data and option counts. Bit 0 Indicates the presence of data. 1 means there is data; 0 means there is no data. Bit 1-6 Represent the option counts when converted to decimal. Bit 7 Indicates the presence of a token. 1 means there is a token; 0 means there is no token. Example: If is 131, it is converted to binary as 1000 0011, which means that both token and data are present, and the option counts is 1. Integer type. Token length of the CoAP server. Range: 1–8. Unit: byte. String in Hex. Token values. Integer type. CoAP option name. See RFC 7252 and RFC7959 for more details. 1 If-Match 3 Uri-Host 4 ETag 5 If-None-Match 6 Observe 8 Location-Path 11 Uri-Path 12 Content-Format 14 Max-Age 15 Uri-Query 17 Accept 20 Location-Query 23 Block2 27 Block1 28 Size2 35 Proxy-Uri String type. CoAP option values. Maximum length: 255 bytes. If is 23 or 27, calculate the value of according to the following formula: = (block_num << 4) | (block_more&0x8) | log2(block_size/16) If =12 or 17, the value of is as follows: '0' Text-plain '40' Application/link-format BC660K-GL&BC950K-GL_CoAP_Application_Note 22 / 31 NB-IoT Module Series '41' Application/xml '42' Application/octet-stream '47' Application/exi '50' Application/json Integer type. Data length. Unit: byte. String type. Received data. If =12 and =0/41/50, the data is in string format, otherwise, the data is in hexadecimal format. BC660K-GL&BC950K-GL_CoAP_Application_Note 23 / 31 NB-IoT Module Series 4 Example 4.1. Register to IoT Platform Without DTLS AT+CGATT? +CGATT: 1 // Query the service status of the current PS domain. // PS domain is attached. OK AT+QCOAPCFG='dtls',0 +QCOAPCFG: 'dtls',0 // Query DTLS Mode with client ID 0. // DTLS Mode is off with client ID 0. OK AT+QCOAPOPEN=0,'220.180.239.212',7002 OK //Create a CoAP context with client ID 0. +QCOAPOPEN: 0,0 //Configure the CoAP message ID as 12345, the token value as '01020304', and the length as 4 bytes. AT+QCOAPHEAD=0,5,12345,4,'01020304' OK //Configure the CoAP option as 11 (Uri-Path), with the option value 'rd' and the length of 2 bytes. AT+QCOAPOPTION=0,0,11,2,'rd' OK //Configure the CoAP option as 12(Content-Format), with the option value '40'(Application/link-format), and the length of 2 bytes. AT+QCOAPOPTION=0,0,12,2,'40' OK //Configure the CoAP option as 15 (Uri-Query), with the option value 'lwm2m=1.0&ep=867725030012276 &b=U&lt=900', and the length of 39 bytes. Use '&' symbol to connect multiple options. AT+QCOAPOPTION=0,0,15,39,'lwm2m=1.0&ep=867725030012276&b=U&lt=900' OK AT+QCOAPSEND=0 //Query the sending status of CoAP CON data. +QCOAPSEND: 0,0 //Data is not sent. OK AT+QCOAPSEND=0,0,2,0 //Send a CON type POST request to the COAP server. > ;rt='oma.lwm2m';ct=11543,,,,,, BC660K-GL&BC950K-GL_CoAP_Application_Note 24 / 31 NB-IoT Module Series OK //URC below is returned after the request is received from the server, with as 201, as 12345, as 132, as 4 bytes, as '01020304', as 8 and 8 corresponding to ' rd ' and '867725030012276' of respectively. +QCOAPURC: 0,2,201,12345,132,4,'01020304',8,'rd',8,' 867725030012276' //After receiving the request from the server, the following URC is returned with as 0, as 1, as 21152, as 134, as 8 bytes, as 'E8532E3363BE54B9', as 6, as 0, as 11, as 3, as 11, as 0. +QCOAPURC: 0,0,1,21152,134,8,'E8532E3363BE54B9',6,'0',11,'3',11,'0' AT+QCOAPSEND=0 +QCOAPSEND: 0,4 //CON data was sent successfully. OK //According to the last requested URC content, configure CoAP message ID as 21152, token length as 8 bytes, and token value as 'E8532E3363BE54B9'. AT+QCOAPHEAD=0,5,21152,8,'E8532E3363BE54B9' OK // Send a 205 response code and 'AAAA' data to the IoT platform using the ACK type. AT+QCOAPSEND=0,2,205,0 > AAAA OK AT+QCOAPCLOSE=0 OK //Delete the CoAP context. +QCOAPCLOSE: 0,0 //The CoAP context is deleted successfully. 4.2. Register to IoT Platform with DTLS AT+CGATT? +CGATT: 1 //Query the service status of the current PS domain. // PS domain is attached. OK AT+QCOAPCFG='dtls',0,1 //Enable DTLS mode for CoAP client with ID 0. OK //Configure PSK, with '869154040004132', '67514b6c5a45334e31576a6d5733387 a'. BC660K-GL&BC950K-GL_CoAP_Application_Note 25 / 31 NB-IoT Module Series AT+QCOAPCFG='psk',0,'869154040004132','67514b6c5a45334e31576a6d5733387a' OK AT+QCOAPOPEN=0,'220.180.239.212',7002 //Create a CoAP context with a client ID of 0. OK +QCOAPOPEN: 0,0 //Configure the CoAP message ID as 12345, the token value as '01020304', and the length as 4 bytes. AT+QCOAPHEAD=0,5,12345,4,'01020304' OK //Configure the CoAP option as 11 (Uri-Path), with the option value 'rd', and the length of 2 bytes. AT+QCOAPOPTION=0,0,11,2,'rd' OK //Configure the CoAP option as 12(Content-Format), with the option value '40'(Application/link-format), and the length of 2 bytes. AT+QCOAPOPTION=0,0,12,2,'40' OK //Configure the CoAP option as 15 (Uri-Query), with the option value 'lwm2m=1.0&ep=869619050023990&b=U&lt=1600', and the length of 40 bytes. Use '&' symbol to connect multiple options. AT+QCOAPOPTION=0,0,15,40,'lwm2m=1.0&ep=869154040004132&b=U&lt=1600' OK AT+QCOAPSEND=0 //Query the sending status of CoAP CON data +QCOAPSEND: 0,0 //Data is not sent. OK AT+QCOAPSEND=0,0,2,0 //Send a CON type POST request to the COAP server. > ;rt='oma.lwm2m';ct=11543,,,,,, OK //URC below is returned after the request is received from the server, with as 201, as 12345, as 132, as 4 bytes, as '01020304', as 8 and 8 corresponding to ' rd ' and '869154040004132' of respectively. +QCOAPURC: 0,2,201,12345,132,4,'01020304',8,'rd',8,'869154040004132' // After receiving the request from the server, the following URC is received with as 0, as 1, as 41128, as 134, as 8 bytes, as 'E8532D1363BE54B9', as 6, as 0, as 11, as 3, as 11, as 0. +QCOAPURC: 0,0,1,41128,134,8,'E8532D1363BE54B9',6,'0',11,'3',11,'0' AT+QCOAPSEND=0 +QCOAPSEND: 0,4 //CON data was sent successfully. OK BC660K-GL&BC950K-GL_CoAP_Application_Note 26 / 31 NB-IoT Module Series //According to the last requested URC content, configure CoAP message ID as 41128, token length as 8 bytes, and token value as 'E8532D1363BE54B9'. AT+QCOAPHEAD=0,5,41128,8,'E8532D1363BE54B9' OK // Send a 205 response code and 'AAAA' data to the IoT platform using the ACK type. AT+QCOAPSEND=0,2,205,0 > AAAA OK OK AT+QCOAPCLOSE=0 OK //Delete the CoAP context. +QCOAPCLOSE: 0,0 //The CoAP context is deleted successfully. BC660K-GL&BC950K-GL_CoAP_Application_Note 27 / 31 NB-IoT Module Series 5 Summary of Result Codes The following table lists some of the general result codes. Table 2: Description of Codes Code of 0 -1 -2 -3 -4 -5 -6 -7 -8 -9 -10 -11 Meaning Operation successful Invalid parameter Operation in processing Operation not allowed Network failure DNS error Data call activating Socket connection failure Out of memory error DTLS handshaking failure CoAP client identifier occupied Data sending failure BC660K-GL&BC950K-GL_CoAP_Application_Note 28 / 31 NB-IoT Module Series 6 Summary of Error Codes This chapter summarizes the error codes related to BC660K-GL and BC950K-GL modules. The error codes listed in the following two tables are compliant with the 3GPP specifications. Please refer to 3GPP TS 27.007 V13.5.0, sub-clause 9.2 for all possible values. Table 3: General Errors (27.007) Code of 3 4 23 30 50 51 52 159 Description Operation not allowed Operation not supported Memory failure No network service Incorrect parameters Command implemented but currently disabled Command aborted by user Uplink busy/flow control NOTE AT+CMEE= command disables (=0) or enables (=1) the use of final result code '+CME ERROR:'. If =1 or an error occurs, +CME ERROR: will be returned. If =0 or an error occurs, ERROR will be returned, see document [1] for details. BC660K-GL&BC950K-GL_CoAP_Application_Note 29 / 31 NB-IoT Module Series 7 Appendix References Table 4: Related Documents Document Name [1] Quectel_BC660K-GL&BC950K-GL_AT_Commands_Manual Table 5: Terms and Abbreviations Abbreviation 3GPP ACK CoAP DNS DTLS ID loT IP ME OPT PDU PIN PS PUK RST SMS Description 3rd Generation Partnership Project Acknowledgement Constrained Application Protocol Domain Name Server Datagram Transport Layer Security Identification Internet of Things Internet Protocol Mobile Equipment Option Protocol Data Unit Personal Identification Number Packet Switch PIN Unlock Key Reset Short Message Service BC660K-GL&BC950K-GL_CoAP_Application_Note 30 / 31 SMSC TA TE URC USIM NB-IoT Module Series Short Message Service Center Terminal Adapter Terminal Equipment Unsolicited Result Code Universal Subscriber Identity Module BC660K-GL&BC950K-GL_CoAP_Application_Note 31 / 31

Quectel_BC660K-GL&BC950K-GL_CoAP_Application_Note_V1.0

PDF

284.70 KB

EC2x&EG2x&EG9x&EM05 Series QuecLocator Application Note LTE Standard Module Series Version: 2.0 Date: 2023-07-05 Status: Released LTE Standard 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. EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 1 / 22 LTE Standard 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. 2023. All rights reserved. EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 2 / 22 LTE Standard Module Series About the Document Revision History Version Date Author Description 1.0 2018-09-17 Slark WANG First official release 1. Updated the applicable modules: ⚫ Added EG21-G, EG25-G, EG21-GL and EG25-GL. ⚫ Updated EC20 R2.1 to EC20-CE. ⚫ Deleted EC20 R2.0. 2. Deleted QuecLocator overview. Slark WANG/ 3. Deleted AT+QLOCCFG and AT+QCELLLOC. 2.0 2023-07-05 Water WANG 4. Updated the introduction (Chapter 1). 5. Added QuecLocator authorization (Chapter 2). 6. Added AT+QLBSCFG, AT+QLBS and AT+QLBSEX (Chapters 3.3 & 3.4 & 3.5). 7. Updated the example (Chapter 4). 8. Updated summary of error codes (Chapter 6). EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 3 / 22 Contents LTE Standard Module Series Applicable Modules .................................................................................................................... 6 AT Command Introduction ......................................................................................................... 8 3.1.1. Definitions........................................................................................................................ 8 3.1.2. AT Command Syntax ...................................................................................................... 8 Declaration of AT Command Examples ..................................................................................... 9 AT+QLBSCFG Configure Parameters for QuecLocator............................................................ 9 AT+QLBS Get Location Information by QuecLocator ........................................................... 13 AT+QLBSEX Input the Cell Information and Get Location Information by QuecLocator ..... 15 Executing QuecLocator AT Command Fails ............................................................................ 19 PDP Activation Fails................................................................................................................. 19 Error Response of AT+QLBS ................................................................................................... 19 EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 4 / 22 LTE Standard Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 6 Table 2: Types of AT Commands ................................................................................................................. 8 Table 3: Summary of Error Codes.............................................................................................................. 20 Table 4: Related Documents ...................................................................................................................... 21 Table 5: Terms and Abbreviations .............................................................................................................. 21 EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 5 / 22 LTE Standard Module Series Introduction This document is an application note for all AT commands related to QuecLocator® on Quectel LTE Standard EC2x, EG2x, EG9x family and EM05 series 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 of a blocked or intermittent GNSS signal. For more information, visit https://iot.quectel.com/doc_getStart.html#QuecLocator. Applicable Modules Table 1: Applicable Modules Module Family EC2x EG2x EG9x - Module EC20-CE EC21 Series EC25 Series EG21-G EG25-G EG21-GL EG25-GL EG91 Series EG95 Series EM05 Series EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 6 / 22 LTE Standard Module Series QuecLocator® Authentication To use the QuecLocator service, an authorization token is needed for identity authentication. The auth token remains valid after module rebooting or power-off. It is needed to 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 concrete steps are illustrated in the figure below. MCU Module Configure token AT+Q LBS CFG='tok en' Query whether the token has been input. +QLBSCFG: 'token','' Token is empty. The token value can be saved af ter module's power-off. If it is empty, please input one. AT+QLBSCFG='t oken', '1234567890ABXDE F' Input token. AT+Q LBS CFG='tok en' Query whether the token is input. +QLBSCFG: 'token','******** ********' The token value exists If a token exists, there is no need to input it. AT+Q LBS Execute the Execution Command for location. Figure 1: QuecLocator® Auth Token Configuration NOTE Please contact Quectel Technical Support to apply for the token value. EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 7 / 22 LTE Standard Module Series Description of AT Commands 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 to 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 2: 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. EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 8 / 22 LTE Standard Module Series Declaration of AT Command Examples The AT command examples in this document are provided to help you familiarize with AT commands and learn how to use them. 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. AT+QLBSCFG Configure Parameters for QuecLocator 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: 'contextid',(range of supported s) Read Command AT+QLBSCFG? OK Response +QLBSCFG: 'asynch', +QLBSCFG: 'timeout', +QLBSCFG: 'server', +QLBSCFG: 'token', +QLBSCFG: 'timeupdate', +QLBSCFG: 'withtime', +QLBSCFG: 'latorder', +QLBSCFG: 'contextid', Write Command AT+QLBSCFG='asynch'[,] OK Response If the optional parameter is omitted, query the current setting: +QLBSCFG: 'asynch', OK EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 9 / 22 LTE Standard Module Series If the optional parameter is specified, set the execution mode of AT+QLBS: OK If there is an error related to ME functionality: +CME ERROR: Write Command Response AT+QLBSCFG='timeout'[,] +QLBSCFG: 'timeout', OK If the optional parameter is specified, set the maximum response time of AT+QLBS: OK Write Command 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, set the domain name/IP address and port number of the server providing 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, and is set, query the current setting: +QLBSCFG: 'token','*****************' OK If the optional parameter is omitted, and is not set, query the current setting: +QLBSCFG: 'token','' OK EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 10 / 22 LTE Standard Module Series If the optional parameter is specified, configure the token value for server authentication: OK If there is an error related to ME functionality: +CME ERROR: Write Command Response AT+QLBSCFG='timeupdate'[,] +QLBSCFG: 'timeupdate', OK If the optional parameter is specified, set whether to update to the RTC: OK Write Command AT+QLBSCFG='withtime'[,] If there is an error related to ME functionality: +CME ERROR: Response If the optional parameter is omitted, query the current setting: +QLBSCFG: 'withtime', OK If the optional parameter is specified, set whether to output the time when calling 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 If the optional parameter is specified, set the latitude and longitude output order of the location results: OK Write Command AT+QLBSCFG='contextid'[,<context If there is an error related to ME functionality: +CME ERROR: Response If the optional parameter is omitted, query the current setting: EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 11 / 22 LTE Standard Module Series ID>] +QLBSCFG: 'contextid', OK If the optional parameter is specified, set the number of PDP context ID: 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 are not saved except those of and . Parameter Integer type. Execution mode of AT+QLBS. In different modes, the response of the command will be different. 0 Synchronous mode 1 Asynchronous mode Integer type. The maximum response time of AT+QLBS. If there is no response from the server within , the command will be timeout. Range: 10–120. Default: 60. Unit: second. String type. Domain/IP address and server port. Format: 'domain/IP address:port' (e.g., 'www.queclocator.com:80'). Server port range: 1–65535. Default server: 'www.queclocator.com:80'. String type. Authentication token value. Length: 16 bytes. Integer type. Whether to update the system time, which is acquired when accessing the server of QuecLocator, to RTC. 0 Do not update the time to RTC 1 Update the time to RTC Integer type. Whether to output the time when calling AT+QLBS. 0 Do not output the time 1 Output the time Integer type. Configure the latitude and longitude output order of the location results. 0 Longitude output before latitude like this: +QLBS: ,,[,] 1 Latitude output before longitude like this: +QLBS: ,,[,] See Chapter 3.4 for details of the parameters. Integer type. PDP context ID. Range: 1–16. Default value: 1. EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 12 / 22 LTE Standard Module Series AT+QLBS Get Location Information by QuecLocator AT+QLBS Get Location Information by QuecLocator Test Command AT+QLBS=? Response OK Execution Command Response AT+QLBS If the module is in synchronous (=0) mode and the positioning succeeds: +QLBS: ,,[,] or +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: ,,[,] or +QLBS: ,,[,] If the module is in asynchronous mode and the positioning fails: OK +QLBS: Write Command AT+QLBS=, ,,,[,…] If there is an error related to ME functionality: +CME ERROR: Response If the module is in synchronous mode and the positioning succeeds: +QLBS: ,,[,] or +QLBS: ,,[,] EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 13 / 22 LTE Standard Module Series Maximum Response Time Characteristics OK If the module is in synchronous mode and the positioning fails: +QLBS: OK If the module is in asynchronous mode and the positioning succeeds: OK +QLBS: ,,[,] or +QLBS: ,,[,] If the module is in asynchronous mode and the positioning fails: OK +QLBS: If there is an error related to ME functionality: +CME ERROR: Depends on in AT+QLBSCFG='timeo ut',. The command takes effect immediately. The configurations are not saved. Parameter Integer type. The number of inputted Wi-Fi MAC addresses. Range: 2–6. String type. MAC addresses of nearby Wi-Fi hotspots. Integer type. Received signal strength indicator. The value should be less than zero. Float type. The latitude of the location information. This value is accurate to six decimal places. Range: -90.000000–90.000000. Float type. The longitude of the location information. This value is accurate to six decimal places, and the range is from -180.000000 to 180.000000. String type. The date and time obtained from HTTP header. Integer type. Positioning result. 0 Positioning succeeded Other values Positioning failed (See Chapter 6 for more information.) Error code. See Chapter 6 for more information. EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 14 / 22 LTE Standard Module Series AT+QLBSEX Input the Cell Information and Get Location Information by QuecLocator AT+QLBSEX Input the Cell information and Get Location Information by QuecLocator Test Command AT+QLBSEX=? Response OK Write Command Response AT+QLBSEX=,,,,,,,,,,<ua +QLBS: ,,[,] rfcndl>,,,, or ,,[,…] +QLBS: ,,[,] OK If the module is in synchronous mode and the positioning fails: +QLBS: OK If the module is in asynchronous mode and the positioning succeeds: OK +QLBS: ,,[,] or +QLBS: ,,[,] If the module is in asynchronous mode and the positioning fails: OK +QLBS: Maximum Response Time Characteristics If there is an error related to ME functionality: +CME ERROR: Depends on . The command takes effect immediately. The configurations are not saved. EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 15 / 22 LTE Standard Module Series Parameter Integer type. The number of inputted physical cell ID. Range: 1–5. Integer type. Radio access technology. 1 GSM 2 WCDMA 3 LTE Integer type. Mobile country code (the first part of the PLMN code). Integer type. Mobile network code (the second part of the PLMN code). Integer type. Location area identification. Integer type. The physical cell ID that has been locked. Integer type. Signal intensity. Integer type. Broadcast control channel. Integer type. Base station identity code, used for GSM. Range: 0–255. Integer type. UTRA absolute radio frequency channel number, used for WCDMA. Range: 0–65535. Integer type. Primary scrambling code, used for WCDMA. Range: 0–65535. Integer type. Tracking area code, used for LTE. Range: 0–65535. Integer type. The reference signal received quality threshold, used for LTE. Range: 0– 65535. Integer type. Physical cell identifier, used for LTE. Range: 0–65535. Integer type. E-UTRAN absolute radio frequency channel number, used for LTE. Range: 0–65535. EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 16 / 22 LTE Standard Module Series Example //Step 1: Configure and activate the PDP context. AT+QICSGP=1,1,'UNIWAP','','',1 OK AT+QIACT=1 OK AT+QIACT? +QIACT: 1,1,1,'10.7.157.1' //Configure PDP context 1, APN is 'UNIWAP' for China Unicom. //Activate PDP context 1. //Activated successfully. //Query the state of PDP context. OK AT+QLBSCFG='contextid',1 OK AT+QLBSCFG='contextid' + QLBSCFG: 'contextid',1 //Set the PDP context ID as 1. The PDP context must be activated first. //Query the PDP context ID. OK AT+QLBCFG='timeout',10 OK AT+QLBSCFG='timeout' + QLBSCFG: 'timeout',10 //Configure the timeout value. //Query the current timeout value. OK AT+QLBSCFG='token','1234567812345678' OK AT+QLBSCFG='token' +QLBSCFG: 'token','****************' //Configure the token value. //Query the current token state. OK AT+QLBSCFG='server','47.74.213.211:80' OK AT+QLBSCFG='server' + QLBSCFG: 'server','47.74.213.211:80' //Configure the server address and port information. //Query the current server address and port information. OK //Step 2: Get the location information by QuecLocator. AT+QLBS //Get the serving cell location. +QLBS: 0,117.115517,31.821774 OK EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 17 / 22 LTE Standard Module Series AT+QLBS=6,'44:6a:2e:11:d7:d1',-30,'44:6a:2e:11:d7:c2',-39,'44:6a:2e:11:d6:e1',59,'44:6a:2e:11:d6:e2',-76,'44:6a:2e:11:d6:e0',-81,'44:6a:2e:11:d7:d1',-30 +QLBS: 0,117.126633,31.800074 AT+QLBSEX=1,3,460,00,0,0,-95,0,0,0,0,0,0,0,121,1300 +QLBS: 0,117.115486,31.821793 OK EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 18 / 22 LTE Standard Module Series Error Handling Executing QuecLocator AT Command Fails If an '+CME ERROR: ' response is received from the module, after executing QuecLocator AT commands, check the following: ⚫ Ensure that the SIM/USIM card is inserted, ⚫ Verify if '+CPIN: READY' was returned after executing AT+CPIN?. PDP Activation Fails If PDP context activation with AT+QIACT fails, check the following: 1. Query whether the PS domain is attached or not with AT+CGATT?. If not, execute AT+CGATT=1 to attach PS domain. 2. Query the network registration status with AT+CGREG? and make sure the PS domain is registered. 3. Query the PDP context parameters with AT+QICSGP and make sure the APN of the specified PDP context is set correctly. 4. Make sure the specified PDP context ID is neither used by PPP nor activated by AT+CGACT. If all above configurations are correct, but activating PDP context by AT+QIACT still fails, please reboot the module to resolve this issue. After booting the module, please check the configurations mentioned above at least three times and each time at an interval of 10 minutes to avoid frequently rebooting the module. Error Response of AT+QLBS If '+CME ERROR: ' is returned after executing AT+QLBS, retry the command. If it fails again, deactivate the PDP context with AT+QIDEACT command, and then try again. EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 19 / 22 LTE Standard Module Series Summary of Error Codes indicates an error related to mobile equipment or network. The details about are described in the following table. Table 3: Summary of Error Codes Code of 10000 10001 10002 10003 10004 10005 10006 10007 10008 10009 Description of Error Codes Location failed. 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. Token expired. IMEI number is not accepted by the server. Times of positioning using the same token within one day exceeds the limit. Times of positioning using the same token within a cycle exceeds the limit. NOTE If QuecLocator returns any HTTP error code, please refer to document [4] for detailed descriptions of the error codes. EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 20 / 22 LTE Standard Module Series Appendix References Table 4: Related Documents Document Name [1] Quectel_EC2x&EG9x&EG2x-G&EM05_Series_AT_Commands_Manual [2] Quectel_EC2x&EG2x&EG9x&EM05_Series_QCFG_AT_Commands_Manual [3] Quectel_EC2x&EG2x&EG9x&EM05_Series_TCP(IP)_Application_Note [4] Quectel_EC2x&EG2x&EG9x&EM05_Series _HTTP(S)_Application_Note Table 5: Terms and Abbreviations Abbreviation AP APN E-UTRAN GNSS GSM HTTP ID IMEI IP LTE MAC PDP Description Access Point Access Point Name Evolved Universal Terrestrial Radio Access Global Navigation Satellite System Global System for Mobile Communications Hyper Text Transfer Protocol Identification International Mobile Equipment Identity Internet Protocol Long Term Evolution Media Access Control Packet Data Protocol EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 21 / 22 PPP QoS RTC UTRA WCDMA LTE Standard Module Series Point-to-Point Protocol Quality of Service Real-Time Clock Universal Terrestrial Radio Access Wideband Code Division Multiple Access EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note 22 / 22

Quectel_EC2x&EG2x&EG9x&EM05_Series_QuecLocator_Application_Note_V2.0

PDF

421.89 KB

EC2x&EG2x&EG9x Series Secure Boot Application Note LTE Standard Module Series Version: 1.0 Date: 2023-06-30 Status: Released EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 0 / 19 LTE Standard 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. EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 1 / 19 LTE Standard 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. 2023. All rights reserved. EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 2 / 19 LTE Standard Module Series About the Document Revision History Version 1.0 Date 2023-05-16 2023-06-30 Author Eve HU/ Damon LI Eve HU/ Damon LI Description Creation of the document First official release EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 3 / 19 LTE Standard Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 1.1. Applicable Module...................................................................................................................... 7 2 Secure Boot Overview ........................................................................................................................ 8 2.1. Definition .................................................................................................................................... 8 2.2. Flow Chart .................................................................................................................................. 8 3 Secure Boot Enabling Procedures.................................................................................................. 10 3.1. Certificate Chain Generation.................................................................................................... 10 3.1.1. Environment Preparation .............................................................................................. 10 3.1.2. Certificate and Keys Generation ................................................................................... 10 3.1.3. Certificate and Key Replacement ................................................................................. 11 3.2. QFPROM Configurations ......................................................................................................... 11 3.2.1. Parameter Configuration ............................................................................................... 11 3.2.2. sec.dat File Generation ................................................................................................. 12 3.3. Image Signing .......................................................................................................................... 13 3.3.1. Modules with Flash Memory in 128 M .......................................................................... 13 3.3.2. Modules with Flash Memory in 256 M or 512 M ........................................................... 14 3.4. Secure Firmware Downloading................................................................................................ 15 4 FAQs................................................................................................................................................... 17 4.1. Do I Need to Execute Certificate Chain Repeatedly ............................................................... 17 4.2. Do I Need to Generate sec.dat Repeatedly............................................................................. 17 4.3. Can Unsigned Firmware Run on Module ................................................................................ 17 4.4. Can Original Firmware Be Downloaded After Enabling Secure Boot ..................................... 17 4.5. How to Perform Verification After Enabling Secure Boot ........................................................ 17 4.6. Does Secure Boot Still Work After Erasing sec Partition ........................................................ 18 5 Appendix References ....................................................................................................................... 19 EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 4 / 19 LTE Standard Module Series Table Index Table 1: Applicable Module .......................................................................................................................... 7 Table 2: Terms and Abbreviations ............................................................................................................. 19 EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 5 / 19 LTE Standard Module Series Figure Index Figure 1: Secure Boot Flow Chart................................................................................................................ 8 Figure 2: Generate Certificates and Keys.................................................................................................. 10 Figure 3: Certificates and Keys .................................................................................................................. 11 Figure 4: Configure QFPROM Parameter.................................................................................................. 12 Figure 5: sec.dat File.................................................................................................................................. 12 Figure 6: Prepare Images to Be Signed..................................................................................................... 13 Figure 7: Sign Images ................................................................................................................................ 13 Figure 8: Signed Images List ..................................................................................................................... 14 Figure 9: Prepare Images to Be Signed..................................................................................................... 14 Figure 10: Sign Images .............................................................................................................................. 14 Figure 11: Signed Images List ................................................................................................................... 15 Figure 12: Firmware Package with sec.dat File......................................................................................... 15 EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 6 / 19 LTE Standard Module Series 1 Introduction This document explains how to enable Secure Boot on Quectel EC2x family, EG2x family and EG9x family modules. 1.1. Applicable Module Table 1: Applicable Module Module Family EC2x EG2x EG9x Module EC20-CE EC21 Series EC25 Series EG21-G EG25-G EG21-GL EG25-GL EG91 Series EG95 Series 1NOTE This document is applicable to the above modules and their QuecOpen® solutions. EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 7 / 19 LTE Standard Module Series 2 Secure Boot Overview 2.1. Definition Secure Boot refers to the secure bootup sequence that establishes a trusted platform by incorporating signature verification. It ensures that only authorized software is executed during the boot process. Secure Boot system incorporates signature verification to each stage of the module booting process to prevent the execution of any unauthorized or maliciously modified software on the module. 2.2. Flow Chart Figure 1: Secure Boot Flow Chart EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 8 / 19 LTE Standard Module Series 2NOTE According to the image signature format, Secure Boot is divided into two parts: ⚫ Classic Secure Boot mechanism that does not support signing HLOS (Kernel and FS) images. ⚫ Aboot (Bootloader) authentication with the authentication of Kernel (mdm9607-perf-boot.img). The public key certificate used for authentication is stored in the aboot file. EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 9 / 19 LTE Standard Module Series 3 Secure Boot Enabling Procedures 3.1. Certificate Chain Generation 3.1.1. Environment Preparation 1. Software environment: Ubuntu system, Python 2.7, OpenSSL 1.0.2 or later versions. 2. Contact Quectel Technical Support for the corresponding tool installation packages gencerts.zip for generating certificates and keys as well as ql_9207_nork_mro_SecBootTools_Release_v1.2m.tar.gz used for generating signed images. 3.1.2. Certificate and Keys Generation To generate the certificates and keys: Step 1: Open Ubuntu terminal window and unzip gencerts.zip Step 2: Execute ./genCerts.sh to generate certificates and keys. Figure 2: Generate Certificates and Keys EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 10 / 19 LTE Standard Module Series If the command is executed successfully, the generated certificates and keys will be stored under the /certs of gencerts.zip directory. Figure 3: Certificates and Keys 3.1.3. Certificate and Key Replacement To replace the certificates and keys: Step 1: Unzip the ql_9207_nork_mro_SecBootTools_Release_v1.2m.tar.gz tool package. Step 2: Copy the newly generated oem_rootca.key, oem_rootca.cer, oem_attestationca.key and oem_attestationca.cer files to the ql_9207_nork_mro_SecBootTools_Release_v1.2m/cert directory to replace the existing files in the directory with the newly copied files. 3.2. QFPROM Configurations QFPROM, which stores configurations related to chip authentication in Non-Volatile ROM, can achieve the safe environment required by Secure Boot. This chapter provides an overview of the parameter configurations that must be set before signing images. 3.2.1. Parameter Configuration To configure the parameters: Step 1: Open the 9607_fuseblower_USER.xml file in the common/sectools/config/9607 directory of ql_9207_nork_mro_SecBootTools_Release_v1.2m package. EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 11 / 19 LTE Standard Module Series Step 2: Locate the root_cert_hash parameter within the file and replace the existing value with the new value. Note that the other option values typically remain at their default settings. Figure 4: Configure QFPROM Parameter 3NOTE The value of root_cert_hash is obtained by signing oem_rootca.cer file with SHA256 algorithm. To obtain the value, execute sha256sum oem_rootca.cer in Ubuntu terminal window. 3.2.2. sec.dat File Generation Execute genSecdat.sh in Ubuntu terminal window to generate sec.dat. The file will be stored in the output/SecDat of ql_9207_nork_mro_SecBootTools_Release_v1.2m directory. Figure 5: sec.dat File EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 12 / 19 LTE Standard Module Series 3.3. Image Signing 3.3.1. Modules with Flash Memory in 128 M 1. Unzip the latest firmware package, replace all images to be signed in the of ql_9207_nork_mro_SecBootTools_Release_v1.2m/firmwares directory with the signed versions: Figure 6: Prepare Images to Be Signed 2. Copy ql-rootfs.tar.gz file from the secboot folder in the firmware package to the ql_9207_nork_mro_SecBootTools_Release_v1.2m/firmwares directory. 3. Follow the instructions in the README file of ql_9207_nork_mro_SecBootTools_Release_v1.2m to create a Docker environment. Run the signImage.sh script of ql_9207_nork_mro_SecBootTools_Release_v1.2m in the newly created Docker environment to sign the images. Figure 7: Sign Images 4. The signed images will be stored in ql_9207_nork_mro_SecBootTools_Release_v1.2m/output/SignImg. EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 13 / 19 LTE Standard Module Series Figure 8: Signed Images List 1NOTE When you copy the singed images from the SignImg folder to the update directory in the firmware package, you also need to copy the mdm9607-sysfs.ubi in the ql-rootfs folder. 3.3.2. Modules with Flash Memory in 256 M or 512 M 1. Unzip the latest firmware package, and replace all images to be signed in the ql_9207_nork_mro_SecBootTools_Release_v1.2m/firmwares directory with the signed ones: Figure 9: Prepare Images to Be Signed 2. Follow the instructions in the README file of ql_9207_nork_mro_SecBootTools_Release_v1.2m to create a Docker environment. Run the signImage.sh script of ql_9207_nork_mro_SecBootTools_Release_v1.2m in the newly created Docker environment to sign the images. Figure 10: Sign Images EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 14 / 19 LTE Standard Module Series 3. The signed images will be stored in ql_9207_nork_mro_SecBootTools_Release_v1.2m/output/SignImg. Figure 11: Signed Images List 3.4. Secure Firmware Downloading 1. The generated firmware package includes the signed images and sec.dat, as shown below. Among them, the sec.dat, patition.mbn and partion_nand.xml files are used to enable Secure Boot without signed images. Figure 12: Firmware Package with sec.dat File 2. Download the firmware package without sec.dat to verify if the module can be booted normally. EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 15 / 19 LTE Standard Module Series 3. Once the module is booted successfully, download sec.dat separately. Before downloading, you must modify rawprogram_nand_p2K_b128K_update.xml file (for modules with 128 M or 256 M flash memory) or rawprogram_nand_p4K_b256K_update.xml (for modules with 512 M flash memory) in the update/firehouse/ directory of the firmware package to support downloading the sec partition. Contact Quectel Technical Support for the rawprogram_nand_p2K_b128K_update.xml or rawprogram_nand_p4K_b256K_update.xml file. 2NOTE Secure Boot must be enabled during the module production stage. Enabling Secure Boot after upgrading the module to a version that supports Secure Boot is strictly prohibited, as it may result in abnormal functioning and irrecoverable issues. No configuration, such as SIMLock configuration, should be performed before enabling Secure Boot. EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 16 / 19 LTE Standard Module Series 4 FAQs 4.1. Do I Need to Execute Certificate Chain Repeatedly If the keys and certificates remain unchanged, there is no need to execute certificate chain repeatedly. The certificate chain only needs to be generated once. For subsequent firmware upgrades, you only need to re-sign the images (see Chapter 3.3 for details). 4.2. Do I Need to Generate sec.dat Repeatedly If the module model and root certificate remain unchanged, there is no need to re-generate sec.dat. 4.3. Can Unsigned Firmware Run on Module Before enabling Secure Boot, unsigned firmware can run on the module. However, once Secure Boot is enabled, unsigned firmware cannot run on the module. 4.4. Can Original Firmware Be Downloaded After Enabling Secure Boot You can only download the original firmware with fastboot method. 4.5. How to Perform Verification After Enabling Secure Boot Perform verification by downloading the original incorrectly signed firmware. Once Secure Boot is enabled, firmware that is not properly signed cannot be downloaded. EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 17 / 19 LTE Standard Module Series 4.6. Does Secure Boot Still Work After Erasing sec Partition Erasing sec partition does not affect the functionality of Secure Boot. EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 18 / 19 LTE Standard Module Series 5 Appendix References Table 2: Terms and Abbreviations Abbreviation HLOS IoT QFPROM ROM Description High Level Operating System Internet of Things Qualcomm Fuse Programmable Read Only Memory Read Only Memory EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note 19 / 19

Quectel_EC2x&EG2x&EG9x_Series_Secure_Boot_Application_Note_V1.0

PDF

590.85 KB

BC660K-GL&BC950K-GL HTTP(S) Application Note NB-IoT Module Series Version: 1.0 Date: 2023-06-19 Status: Released 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&BC950K-GL_HTTP(S)_Application_Note 1 / 31 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. 2023. All rights reserved. BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 2 / 31 NB-IoT Module Series About the Document Revision History Version - Date 2023-04-13 1.0 2023-06-19 Author Description Randy LI/ Caden ZHANG Yance YANG/ Randy LI/ Caden ZHANG Creation of the document First official release BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 3 / 31 NB-IoT Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 5 1 Introduction .......................................................................................................................................... 6 1.1. Description of HTTP(S) Request Header ................................................................................... 6 1.1.1. Customize HTTP(S) Request Header ............................................................................. 6 1.1.2. Output HTTP(S) Response Header ................................................................................. 7 2 Description of HTTP(S) AT Commands ............................................................................................. 8 2.1. AT Command Syntax .................................................................................................................. 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+QHTTPCFG Configure Parameters for HTTP(S) Server ....................................... 9 2.3.2. AT+QHTTPURL Set URL of HTTP(S) Server ............................................................. 12 2.3.3. AT+QHTTPGET Send GET Request to HTTP(S) Server ........................................... 13 2.3.4. AT+QHTTPGETEX Send GET Request to HTTP(S) Server to Get Data With Specified Range............................................................................................................................ 14 2.3.5. AT+QHTTPPOST Send POST Request to HTTP(S) Server via UART/USB ............. 15 2.3.6. AT+QHTTPREAD Read Response from HTTP(S) Server via UART/USB ................ 17 3 Examples ............................................................................................................................................ 19 3.1. Access to HTTP Server ............................................................................................................ 19 3.1.1. Send HTTP GET Request and Read the Response ..................................................... 19 3.1.2. Send HTTP POST Request and Read the Response ................................................... 20 3.2. Access to HTTPS Server .......................................................................................................... 21 3.2.1. Send HTTPS GET Request and Read the Response................................................... 21 3.2.2. Send HTTPS POST Request and Read the Response ................................................ 23 4 Error Handling .................................................................................................................................... 26 4.1. Executing HTTP(S) AT Commands Fails.................................................................................. 26 4.2. DNS Parse Fails........................................................................................................................ 26 4.3. Entering Data Mode Fails ......................................................................................................... 26 4.4. Sending GET/POST Requests Fails......................................................................................... 27 4.5. Reading Response Fails ........................................................................................................... 27 5 Summary of ERROR Codes .............................................................................................................. 28 6 Summary of HTTP(S) Response Codes .......................................................................................... 30 7 Appendix and References................................................................................................................. 31 BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 4 / 31 NB-IoT Module Series Table Index Table 1: Types of AT Commands ................................................................................................................. 8 Table 2: Summary of Error Codes.............................................................................................................. 28 Table 3: Summary of HTTP Response Codes ........................................................................................... 30 Table 4: Related Documents ...................................................................................................................... 31 Table 5: Terms and Abbreviations .............................................................................................................. 31 BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 5 / 31 NB-IoT Module Series 1 Introduction Quectel BC660K-GL and BC950K-GL modules support HTTP(S) applications through accessing HTTP(S) servers. Hypertext Transfer Protocol (HTTP) is an application layer protocol for distributed, collaborative, hypermedia information systems. Hypertext Transfer Protocol Secure (HTTPS) is a variant of the standard web transfer protocol (HTTP) that adds a layer of security on the data in transit through a secure socket layer (SSL) or transport layer security (TLS) protocol connection. The main purpose of HTTPS development is to provide identity authentication for website servers and protect the privacy and integrity of exchanged data. This document is a reference guide to all the AT commands defined for HTTP(S). 1.1. Description of HTTP(S) Request Header 1.1.1. Customize HTTP(S) Request Header HTTP(S) request header is filled by the module automatically. It can be customized by configuring as 1 via AT+QHTTPCFG (see Chapter 2.3.1), and then by inputting HTTP(S) request header (see Chapter 2.3.5) according to the following requirements: ⚫ Apply HTTP(S) request header syntax. ⚫ The value of URI in HTTP(S) request line and the 'Host:' request header must be in line with the URL set with AT+QHTTPURL. ⚫ The HTTP(S) request header must end with . A valid HTTP(S) POST request header is shown in the following example: POST /processorder.php HTTP/1.1 Host: 220.180.239.212:8011 Accept: */* User-Agent: QUECTEL_MODULE Connection: Keep-Alive Content-Type: application/x-www-form-urlencoded Content-Length: 48 BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 6 / 31 Message=1111&Appleqty=2222&Orangeqty=3333&find=1 NB-IoT Module Series 1.1.2. Output HTTP(S) Response Header HTTP(S) response header is not automatically output. Outputting of the HTTP(S) response header can be enabled by setting to 1 via AT+QHTTPCFG (see Chapter 2.3.1). The HTTP(S) response header will be output with HTTP(S) response body after executing AT+QHTTPREAD (see Chapter 2.3.6). 1.2. Description of Data Mode BC660K-GL and BC950K-GL support two working modes of the COM port: AT command mode and data mode. In the AT command mode, the data input via the COM port are interpreted as AT commands; whereas in data mode, they are interpreted as data. By default, the BC660K-GL and BC950K-GL modules operate in AT command mode. After receiving the > response, the modules switch to data mode within 500 ms. To exit data mode and transmit the data to the COM port, enter 'Ctrl' + 'Z'. Alternatively, entering 'Esc' will make the module exit data mode and cancel the sending process. NOTE 1. After receiving the > response, it is recommended for the MCU to wait for 500 ms before sending the data. 2. In data mode, URCs will be lost. To prevent this, please enter the data to be sent immediately after the > response, and promptly exit data mode. BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 7 / 31 NB-IoT Module Series 2 Description of HTTP(S) AT Commands 2.1. AT Command Syntax 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: . Throughout this document, only the commands and responses are presented, while carriage return and line feed characters 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. BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 8 / 31 NB-IoT 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. AT Command Description 2.3.1. AT+QHTTPCFG Configure Parameters for HTTP(S) Server The command configures the parameters for HTTP(S) server, including configuring a PDP context ID, customizing HTTP(S) request header, outputting HTTP(S) response header and querying SSL settings. If the Write Command only executes one parameter, it queries the current settings. AT+QHTTPCFG Configure Parameters for HTTP(S) Server Test Command AT+QHTTPCFG=? Response +QHTTPCFG: 'contextid',(range of supported s) +QHTTPCFG: 'requestheader',(list of supported s) +QHTTPCFG: 'responseheader',(list of supported s) +QHTTPCFG: 'contenttype',(range of supported s) +QHTTPCFG: 'ssl',(range of supported s),(range of supported s) +QHTTPCFG: 'readformat',(list of supported s) Read Command AT+QHTTPCFG? OK Response +QHTTPCFG: 'contextid', +QHTTPCFG: 'requestheader', +QHTTPCFG: 'responseheader', +QHTTPCFG: 'contenttype', +QHTTPCFG: 'ssl',, +QHTTPCFG: 'readformat', OK BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 9 / 31 NB-IoT Module Series Write Command Set/query the PDP context ID. AT+QHTTPCFG='contextid'[,] Response If the optional parameter is omitted, query the current settings: +QHTTPCFG: 'contextid', OK If the optional parameter is specified, set the context ID: OK Or ERROR Write Command Response Set/query whether to enable If the optional parameter is omitted, query the current setting: customizing HTTP(S) request +QHTTPCFG: 'requestheader', header. AT+QHTTPCFG='requestheader'[ OK ,] If the optional parameter is specified, enable or disable customizing HTTP(S) request header: OK Or ERROR Write Command Response Set/query whether to enable If the optional parameter is omitted, query the current setting: customizing HTTP(S) response +QHTTPCFG: 'responseheader', header. AT+QHTTPCFG='responseheader OK '[,] If the optional parameter is specified, enable or disable customizing HTTP(S) response header: OK Or ERROR Write Command Response Set/query data type of HTTP(S) If the optional parameter is omitted, query the current setting: body. +QHTTPCFG: 'contenttype', AT+QHTTPCFG='contenttype'[,] OK If the optional parameter is specified, set data type of HTTP(S) body: OK Or ERROR BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 10 / 31 NB-IoT Module Series Write Command Set/query SSL context ID and connection ID. AT+QHTTPCFG='ssl'[,,] Response If the optional parameters are omitted, query the current setting: +QHTTPCFG: 'ssl',, OK Write Command AT+QHTTPCFG='readformat'[,] If the optional parameters are specified, set SSL context ID and connection ID: OK Or ERROR Response If the optional parameter is omitted, query the current setting: +QHTTPCFG: 'readformat', OK If the optional parameter is specified, set the display format of the data returned by AT+QHTTPREAD: OK Maximum Response Time Characteristics If there is any error: ERROR Or +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. PDP context ID. Range: 0–10 (currently only 0 is supported). Integer type. Disable or enable customizing HTTP(S) request header. 0 Disable 1 Enable Integer type. Disable or enable outputting HTTP(S) response header. 0 Disable 1 Enable Integer type. Data type of HTTP(S) body. 0 application/x-www-form-urlencoded 1 text/plain 2 application/octet-stream 3 multipart/form-data BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 11 / 31 NB-IoT Module Series Integer type. SSL context ID. Range: 0–10 (currently only 0 is supported). Integer type. SSL connection ID. Range: 0–4 (currently only 0 is supported). String type. Indicates whether a carriage return and line feed should be included in AT+QHTTPREAD response. 0 No 1 Yes Integer type. Result code. See Chapter 5. NOTE 1. SSL/TLS connection configurations must be set by AT+QSSLCFG. For details of the command, see document [1]. 2. Currently only default , and are supported. 3. Due to chip space limitation, currently HTTPS only supports one-way authentication and no authentication. Two-way authentication is not supported. 2.3.2. AT+QHTTPURL Set URL of HTTP(S) Server This command sets URL of HTTP(S) server. URL must begin with 'http://' or 'https://', which indicates that an HTTP or HTTPS server will be accessed. AT+QHTTPURL Set URL of HTTP(S) Server Test Command AT+QHTTPURL=? Response +QHTTPURL: (range of supported s),(range of supported s) Read Command AT+QHTTPURL? OK Response +QHTTPURL: Write Command AT+QHTTPURL=[,] OK Response a) If the parameter format is correct, but HTTP(S) GET/POST requests are not being sent: > After receiving the > response, the module enters data mode, and the URL can be input. When the total size of the input data reaches , the module returns to command mode and responds with: OK If has been reached, but the length of the received URL is less than , the module returns to BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 12 / 31 NB-IoT Module Series Maximum Response Time Characteristics command mode and responds with: ERROR b) If the parameter format is incorrect or other errors occur: ERROR 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. Length of URL. Range: 1–256. Unit: byte. Integer type. Maximum time for inputting a URL. Range: 1–300. Default value: 60. Unit: second. 2.3.3. AT+QHTTPGET Send GET Request to HTTP(S) Server This command sends a GET request to HTTP(S) server. The format of the command depends on the configured in AT+QHTTPCFG='requestheader'[,] (see Chapter 2.3.1). Customizing GET request header is not supported. If is set to 1, executing AT+QHTTPGET will result in an ERROR response. In such cases, you can use AT+QHTTPPOST (see Chapter 2.3.5) to send a custom HTTP(S) GET packet. After AT+QHTTPGET Write Command is sent, it is suggested to wait for a specific period of time (refer to the maximum response time below) for +QHTTPGET: [,[,]] to be output after OK is returned. can only be reported in +QHTTPGET: [,[,]], when is 0. If HTTP(S) response header contains content-length information, it w ill be reported as . AT+QHTTPGET Send GET Request to HTTP(S) Server Test Command AT+QHTTPGET=? Response +QHTTPGET: (range of supported s),(range of supported s) Write Command AT+QHTTPGET[=[,]] OK Response If the parameter format is correct and no other errors occur: OK When the module receives a response from HTTP(S) server, it BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 13 / 31 Maximum Response Time Characteristics NB-IoT Module Series reports the following URC: +QHTTPGET: [,[,]] If there is any error: ERROR Or +CME ERROR: Determined by / Parameter Integer type. Timeout for the HTTP(S) GET response +QHTTPGET: [,[,]] to be output after OK is returned. Range: 1–300. Default value: 60. Unit: second. Integer type. Maximum time for executing AT+QHTTPGET before releasing the HTTP resources. Range: 1–300. Default value: 60. Unit: second. Integer type. Result code. See Chapter 5. Integer type. HTTP(S) response code. See Chapter 6. Integer type. Length of HTTP(S) response body. Unit: byte. 2.3.4. AT+QHTTPGETEX Send GET Request to HTTP(S) Server to Get Data With Specified Range MCU can retrieve data with a specific position and length from HTTP(S) server by using AT+QHTTPGETEX. This command is only executable when AT+QHTTPCFG='requestheader',0 configuration is set. After sending the command, HTTP(S) server will always respond to the GET request for retrieving data with a specified position and length, by returning a 206 response code. AT+QHTTPGETEX Range Test Command AT+QHTTPGETEX=? Send GET Request to HTTP(S) Server to Get Data With Specified Response +QHTTPGETEX: (range of supported s),,,(range of supported s) Write Command AT+QHTTPGETEX=,,[,] Maximum Response Time Characteristics Description NB-IoT Module Series When the module receives a response from HTTP(S) server, it will report the following URC: +QHTTPGETEX: [,,] If there is any error: ERROR Or +CME ERROR: Determined by / Parameter Integer type. Timeout for the HTTP(S) GET response +QHTTPGETEX: ,[,] to be output after OK is returned. Range: 1–300. Default: 60. Unit: second. Integer type. The start position of the data that the HTTP(S) client wants to get. Integer type. The length of the data that the HTTP(S) client wants to get. Integer type. Maximum time for executing AT+QHTTPGETEX before releasing the resources. Range: 1–300. Default value: 60. Unit: second. Integer type. Result code. See Chapter 5. Integer type. HTTP response code. See Chapter 6 for details. Integer type. The length of HTTP(S) response body. Unit: byte. 2.3.5. AT+QHTTPPOST Send POST Request to HTTP(S) Server via UART/USB The command sends a POST request to an HTTP(S) server. Depending on the configuration of in AT+QHTTPCFG='requestheader'[,], AT+QHTTPPOST Write Command can have two different formats (see Chapter 2.3.1): ⚫ If is set to 0, HTTP(S) POST body should be input via UART/USB port. ⚫ If is set to 1, both HTTP(S) POST header and body should be input via UART/USB port. After AT+QHTTPPOST is sent, the module may output > within 50 s to indicate a successful connection. If > is not received within this time, it indicates a socket error and the module responds with +QHTTPPOST: 716. It is recommended to wait for a specific period of time (refer to the maximum response time below) for +QHTTPPOST: [,[,]] to be output after OK is returned. BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 15 / 31 NB-IoT Module Series AT+QHTTPPOST Send POST Request to HTTP(S) Server via UART/USB Test Command AT+QHTTPPOST=? Response +QHTTPPOST: (range of supported s),(range of supported s),(range of supported s),(list of supported s),(range of supported s) Write Command AT+QHTTPPOST=[, ,[,[,< read_timeout>]]] OK Response a) If the parameter format is correct, HTTP(S) server is connected successfully and HTTP(S) request header is sent: > After > is returned, the module switches to data mode, and the HTTP(S) POST body can be input. When the total size of the input data reaches , the module returns to command mode and responds with: OK When the module receives a response from HTTP(S) server, it reports the following URC: +QHTTPPOST: [,[,]] If the has been reached, but the received length of data is less than , the module returns to command mode and responds with: ERROR Maximum Response Time Characteristics b) If the parameter format is incorrect or other errors occur: ERROR Determined by network and / Parameter Integer type. If is 0, it indicates the length of HTTP(S) POST body. If is 1, it indicates the length of HTTP(S) POST request information, including HTTP(S) request header and HTTP(S) request body. Range: 1–2048. Unit: byte. Integer type. Maximum time for inputting HTTP(S) POST body or HTTP(S) POST request information. Range: 1–300. Default value: 60. Unit: second. BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 16 / 31 NB-IoT Module Series Integer type. Timeout for the HTTP(S) POST response +QHTTPPOST: [,[,]] to be output after OK is returned. Range: 1–300. Default value: 60. Unit: second. Integer type. Whether the current packet is the last packet. 0 Packet is the last one 1 Packet is not the last one Integer type. Maximum time for executing AT+QHTTPPOST before releasing the HTTP resources. Range: 1–300. Default value: 60. Unit: second. Integer type. Result code. See Chapter 5. Integer type. HTTP(S) response code. See Chapter 6. Integer type. Length of HTTP(S) response body. Unit: byte. 2.3.6. AT+QHTTPREAD Read Response from HTTP(S) Server via UART/USB This command retrieves the HTTP(S) server response via the UART/USB port, after HTTP(S) GET/POST requests are sent. It must be executed after one of the following URCs is received. ⚫ +QHTTPGET: [,[,]] ⚫ +QHTTPPOST: [,[,]] AT+QHTTPREAD Read Response from HTTP(S) Server via UART/USB Test Command AT+QHTTPREAD=? Response +QHTTPREAD: (range of supported s) Write Command AT+QHTTPREAD= OK Response If the parameter format is correct and the server response is read successfully: +QHTTPREAD: , OK Maximum Response Time Characteristics If the parameter format is incorrect or other errors occur: ERROR Determined by network and / Parameter Integer type. Length of data requested to be read. Range: 1–1024. Default BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 17 / 31 NB-IoT Module Series value: 1024. Unit: byte. Integer type. Actual length of received data. Unit: byte. Integer type. Remaining length of last received data. Unit: byte. BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 18 / 31 NB-IoT Module Series 3 Examples 3.1. Access to HTTP Server 3.1.1. Send HTTP GET Request and Read Response The following examples show how to send HTTP GET request with a custom HTTP request header and how to read HTTP GET response. //Example of how to send HTTP GET request. AT+QSCLK=0 //Disable sleep mode. OK AT+QHTTPCFG='contextid',0 //Set the PDP context ID to 0. OK AT+QHTTPCFG='responseheader',1 //Enable outputting of HTTP response header. OK AT+QHTTPURL=19,80 //Set the URL of HTTP server to be accessed. > http://example.com/ //Input URL whose length is 19 bytes. OK AT+QHTTPGET=80 OK //Send HTTP GET request and set the maximum response time of HTTP GET request to 80 s. +QHTTPGET: 0,200,1256 //If HTTP response header contains CONTENT-LENGTH information, is returned. //Example of how to read HTTP response. //Read HTTP response information via UART port. AT+QHTTPREAD=80 //Read 80 bytes of HTTP response information via UART. +QHTTPREAD: 80,1431 //The actual length of the read data is 80 bytes, and the remaining length of the HTTP response is 1431 bytes. HTTP/1.1 200 OK Age: 430547 Cache-Control: max-age=604800 Content-Type: text/ BC660K-GL&BC950K-GL_HTTP(S)_Application_Note 19 / 31 NB-IoT Module Series OK AT+QSCLK=1 OK //Enable sleep mode. 3.1.2. Send HTTP POST Request and Read Response The following examples show how to send HTTP POST request and retrieve post body via UART port, and how to read HTTP POST response. AT+QSCLK=0 //Disable sleep mode. OK AT+QHTTPCFG='contextid',0 //Set the PDP context ID to 0. OK AT+QHTTPURL=59,80 //Set the URL of HTTP server to be accessed. > http://api.efxnow.com/DEMOWebServices2.8/Service.asmx/Echo? //Input URL whose length is 59 bytes. OK AT+QHTTPPOST=20,80,80 //Send HTTP POST request. POST body is obtained via UART. The maximum time for inputting HTTP POST body is 80 s and the maximum timeout for HTTP POST response is 80 s. > Message=HelloQuectel //Input HTTP POST body whose length is 20 bytes. OK +QHTTPPOST: 0,200,177 //If the HTTP response header contains CONTENT-LENGTH, is returned. //Example of how to read HTTP response. AT+QHTTPREAD=80 //Read 80 bytes of HTTP response body via UART. +HTTPREAD: 80,97 //The actual length of the read data is 80 bytes, and the remaining length of the HTTP response is 97 bytes.

Quectel_BC660K-GL&BC950K-GL_HTTP(S)_Application_Note_V1.0

PDF

238.71 KB

BG96 Security Folder Application Note LPWA Module Series Version: 1.0 Date: 2023-06-12 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_Security_Folder_Application_Note 1 / 16 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. 2023. All rights reserved. BG96_Security_Folder_Application_Note 2 / 16 LPWA Module Series About the Document Revision History Version Date Author Description - 2023-03-03 Glenn SHAO Creation of the document 1.0 2023-06-12 Glenn SHAO First official release BG96_Security_Folder_Application_Note 3 / 16 LPWA Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 5 1 Introduction .......................................................................................................................................... 6 2 Description of Related AT Command ................................................................................................ 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. AT Command Description ........................................................................................................... 8 2.3.1. AT+QFLST List Files ..................................................................................................... 8 2.3.2. AT+QFUPL Upload a File ............................................................................................ 10 2.3.3. AT+QFDEL Delete Files .............................................................................................. 12 3 Summary of Error Codes .................................................................................................................. 14 4 Appendix Reference .......................................................................................................................... 16 BG96_Security_Folder_Application_Note 4 / 16 LPWA Module Series Table Index Table 1: Summary of Error Codes.............................................................................................................. 14 Table 2: Related Document........................................................................................................................ 16 Table 3:Terms and Abbreviations ............................................................................................................... 16 BG96_Security_Folder_Application_Note 5 / 16 LPWA Module Series 1 Introduction File system security is crucial because many important files and data are stored in the file system. To ensure data security, Quectel provides a security folder to protect data. You can store key data, such as certificates, secret keys and other important files in this folder. The security folder is in the UFS directory and the properties of the files in this folder are hidden. Some access restrictions are added to this security folder. To be specific, only AT+QFLIST, AT+QFUPL and AT+QFDEL are supported to list, upload and delete files stored in the security folder respectively. Files in the security folder are not supported to be directly read by AT+QFREAD (For more information on AT+QFREAD, refer to Document [1]), also not allowed to be accessed and operated through PC tool. Therefore, only some application services of the module kernel can access the files in the security folder, but the data of these files will not be reported to the application layer. For example, you can store SSL certificates in the security folder and configure the paths of them for SSL services, then the certificate data are retrieved and read internally when relevant SSL services are running. This document introduces the security folder protection mechanism and how to apply the mechanism. BG96_Security_Folder_Application_Note 6 / 16 LPWA Module Series 2 Description of Related AT Command 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. BG96_Security_Folder_Application_Note 7 / 16 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. AT Command Description 2.3.1. AT+QFLST List Files This command lists the information of a single file or all files in the specified storage medium. AT+QFLST List Files Test Command AT+QFLST=? Write Command AT+QFLST= Response OK Response [+QFLST: , [+QFLST: ,] […]] OK Execution Command AT+QFLST If there is any error: +CME ERROR: Response Return the information of the UFS files: +QFLST: , [+QFLST: , […]] OK Maximum Response Time Characteristics If there is any error: +CME ERROR: 300 ms The command takes effect immediately. The configuration is not saved. BG96_Security_Folder_Application_Note 8 / 16 LPWA Module Series Parameter String type. The file to be listed. '*' All the files in UFS 'UFS:*' All the files in UFS 'EUFS:/ufs/*' All the files in ufs directory of EUFS 'EUFS:/datatx/*' All the files in datatx directory of EUFS 'EUFS:*' All the files in ufs directory of EUFS 'UFS:/security/*' All the files in ufs/security directory of UFS '' A specified file in UFS 'UFS:' A specified file in UFS 'EUFS:' A specified file in EUFS 'EUFS:/ufs/' A specified file in ufs directory of EUFS 'EUFS:/datatx/' A specified file in datatx directory of EUFS 'UFS:/security/' A specified file in ufs/security directory of UFS String type. File name. The maximum length of is 80 bytes. Integer type. File size. Unit: byte. Integer type. Error code. See Chapter 3 for possible values. Example AT+QFLST='*' +QFLST: 'F_M12-1.bmp',56255 +QFLST: 'F_M12-10.bmp',562554 +QFLST: 'F_M12-11.bmp',562554 +QFLST: 'security/',5 //List all the files in UFS. OK AT+QFLST='UFS:/security/*' +QFLST: '/security/1.txt',6883 +QFLST: '/security/2.txt',10 +QFLST: '/security/3.txt',20 //List all the files in ufs/security directory. OK AT+QFLST='UFS:/security/1.txt' +QFLST: '/security/1.txt',6883 //Get the information of the specified file in the security directory. OK NOTE Due to the restrictions on the security directory, when executing AT+QFLST='*', only the number of files in the security directory is listed instead of the specific security files. BG96_Security_Folder_Application_Note 9 / 16 LPWA Module Series 2.3.2. AT+QFUPL Upload a File The command uploads a file to UFS. If any file in UFS has the same name with the file to be uploaded, an error will be reported. After executing the Write Command and CONNECT returns, the module will switch to data mode. When the uploaded data reaches , or there is no any data inputted when reaches, then it will exit from data mode automatically. During data transmission, you can use +++ or DTR to make the module exit from data mode. For more information on data mode, refer to Document [1]. AT+QFUPL Upload a File Test Command AT+QFUPL=? Response +QFUPL: [,(1-)[,(range of supported s)[,(list of supported s)]]] Write Command AT+QFUPL=[,[, [,]]] OK Response CONNECT TA switches to the data mode (transparent access mode), and the binary data of file can be inputted. When the total size of the inputted data reaches (unit: byte), TA will return to command mode and respond with the following: +QFUPL: , OK Maximum Response Time Characteristics If there is any error: +CME ERROR: Determined by the file size / Parameter String type. Name of the file to be uploaded. The maximum length is 80 bytes. '' Upload the file to UFS 'UFS:' Upload the file to UFS 'EUFS:' Upload the file to EUFS 'EUFS:/ufs/' Upload the file to ufs directory of EUFS 'EUFS:/datatx/' Upload the file to datatx directory of EUFS 'UFS:/security/' Upload the file to ufs/security directory of UFS. Integer type. The free space size of . Please refer to BG96_Security_Folder_Application_Note 10 / 16 LPWA Module Series AT+QFLDS command in Document [1] for more details of . Integer type. Size of the file. Unit: byte. Integer type. The time waiting for data to be inputted to USB/UART. Range: 1–65535. Default value: 5. Unit: s. Integer type. Whether to use ACK mode. 0 Turn off the ACK mode 1 Turn on the ACK mode Integer type. The actual size of the uploaded data. Unit: byte. Integer type. The checksum of the uploaded data. Integer type. Error code. See Chapter 3 for possible values. Example AT+QFLST='UFS:/security/*' +QFLST: '/security/1.txt',1 +QFLST: '/security/2.txt',10 OK AT+QFUPL='UFS:/security/3.txt' CONNECT +QFUPL: 10,3938 OK //List all the files in ufs/security directory. //Upload the file to ufs/security directory. NOTE 1. UFS is the user file storage directory on the modem side. It is a special directory in the flash file system; EUFS is the extended user file storage on the application side. For more information on UFS and EUFS, refer to Document [1]. 2. It is strongly recommended to use DOS 8.3 file name format for . 3. is a 16-bit checksum based on bitwise XOR. If the number of the characters is odd, set the last character as the high 8-bit, and the low 8-bit as 0, and then use an XOR operator to calculate the checksum. +++ sequence will cause TA to end the command and switch to command mode. However, the data previously uploaded will be preserved into the file. At this point, the value of is the checksum of the uploaded data. 4. When executing the command, the data must be entered after CONNECT is returned. 5. The ACK mode is provided to avoid the loss of data when uploading large files, in case hardware flow control does not work. The ACK mode works as follows: 1) Run AT+QFUPL=,,,1 command to enable the ACK mode. 2) BG96 outputs CONNECT. 3) MCU sends 1 K bytes data, and then BG96 will respond with an 'A'. 4) MCU receives this 'A' and then sends the next 1 K bytes data; 5) Repeat Step 3) and Step 4) until the transfer is completed. BG96_Security_Folder_Application_Note 11 / 16 LPWA Module Series 2.3.3. AT+QFDEL Delete Files This command deletes a specified file or all the files in the storage medium. AT+QFDEL Delete Files Test Command AT+QFDEL=? Response +QFDEL: Write Command AT+QFDEL= OK Response OK Maximum Response Time Characteristics If there is any error: +CME ERROR: Determined by the file size / Parameter String type. Name of the file to be deleted. The maximum length of is 80 bytes. '*' Delete all the files in UFS (the directory is remained) 'UFS:*' Delete all the files in UFS (the directory is remained) 'UFS:/security/*' Delete all the files in ufs/security directory of UFS (ufs/security directory is remained) 'EUFS:/ufs/*' Delete all the files in ufs directory of EUFS (ufs directory is remained) 'EUFS:/datatx/*' Delete all the files in datatx directory of EUFS (datatx directory is remained) 'EUFS:*' Delete all the files in ufs directory of EUFS (ufs directory is remained) '' Delete a specified file in UFS 'UFS:' Delete a specified file in UFS 'EUFS:' Delete a specified file in ufs directory of EUFS 'EUFS:/ufs/' Delete a specified file in ufs directory of EUFS 'EUFS:/datatx/' Delete a specified file in datatx directory of EUFS 'UFS:/security/' Delete a specified file in ufs/security directory of UFS. Integer type. Error code. See Chapter 3 for possible values. BG96_Security_Folder_Application_Note 12 / 16 LPWA Module Series Example AT+QFLST='UFS:/security/*' +QFLST: '/security/1.txt',1 +QFLST: '/security/2.txt',10 OK AT+QFDEL='UFS:/security/1.txt' OK AT+QFLST='UFS:/security/*' +QFLST: '/security/2.txt',10 OK AT+QFDEL='UFS:/security/*' OK AT+QFLST='UFS:/security/*' OK //List all the file in ufs/security directory. //Delete a file in ufs/security directory. //List all the file in ufs/security directory. //Delete all the file in ufs/security directory. //List all the file in ufs/security directory. BG96_Security_Folder_Application_Note 13 / 16 LPWA Module Series 3 Summary of Error Codes The error code indicates an error related to mobile equipment or network. The details about are described in the following table, and these error codes are only related to 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 420 Meaning Invalid input value Larger than the size of the file Read zero byte Drive full File not found Invalid file name File already existed Fail to write the file Fail to open the file Fail to read the file Reach the max number of files allowed to be opened The file read-only Invalid file descriptor Fail to list the file Fail to delete the file Fail to get disk info No space BG96_Security_Folder_Application_Note 14 / 16 LPWA Module Series 421 Time out 423 File too large 425 Invalid parameter 426 File already opened BG96_Security_Folder_Application_Note 15 / 16 LPWA Module Series 4 Appendix Reference Table 3: Related ocument Document Name [1] Quectel_BG96_FILE_AT_Commands_Manual Table 4:Terms and Abbreviations Abbreviation ACK COM CRC DOS DTR EUFS ME TA UART UFS USB XOR RAM Description Acknowledgement Communication Port Cyclic Redundancy Check Disk Operating System Data Terminal Ready Extended User File Storage Mobile Equipment Terminal Adapter Universal Asynchronous Receiver/Transmitter User File Storage Universal Serial Bus Exclusive OR Random Access Memory BG96_Security_Folder_Application_Note 16 / 16

Quectel_BG96_Security_Folder_Application_Note_V1.0

PDF

212.68 KB

EG800Q-EU&EG915Q-NA SSL Application Note LTE Standard Module Series Version: 1.0 Date: 2023-06-13 Status: Released M10_ATC Confidential / Released 1 / 10 LTE Standard 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. EG800Q-EU&EG915Q-NA_SSL_Application_Note 1 / 38 LTE Standard 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. 2023. All rights reserved. EG800Q-EU&EG915Q-NA_SSL_Application_Note 2 / 38 LTE Standard Module Series About the Document Revision History Version 1.0 Date 2023-04-11 2023-06-13 Author Greyson DONG Greyson DONG Description Creation of the document First official release EG800Q-EU&EG915Q-NA_SSL_Application_Note 3 / 38 LTE Standard Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 6 1 Introduction .......................................................................................................................................... 7 1.1. SSL Version and Cipher Suite .................................................................................................... 7 1.2. Using SSL Function .................................................................................................................... 9 1.3. Description of Data Access Modes ............................................................................................. 9 1.4. Certificate Validity Check .......................................................................................................... 11 1.5. Server Name Indication ............................................................................................................ 11 2 Description of SSL AT Commands .................................................................................................. 12 2.1. AT Command Description ......................................................................................................... 12 2.1.1. Definitions....................................................................................................................... 12 2.1.2. AT Command Syntax ..................................................................................................... 12 2.1.3. Declaration of AT Command Examples ......................................................................... 13 2.2. Description of AT Commands ................................................................................................... 13 2.2.1. AT+QSSLCFG Configure Parameters of an SSL Context .......................................... 13 2.2.2. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server ........................ 22 2.2.3. AT+QSSLSEND Send Data over SSL Connection ..................................................... 24 2.2.4. AT+QSSLRECV Receive Data over SSL Connection ................................................ 25 2.2.5. AT+QSSLCLOSE Close an SSL Connection.............................................................. 26 2.2.6. AT+QSSLSTATE Query the State of SSL Connection................................................ 27 2.3. Description of URCs ................................................................................................................. 28 2.3.1. +QSSLURC: 'recv' Notify Received Data .................................................................. 28 2.3.2. +QSSLURC: 'closed' Notify Abnormal Disconnection ............................................... 28 3 Examples ............................................................................................................................................ 30 3.1. Configure and Activate a PDP Context..................................................................................... 30 3.1.1. Configure a PDP Context............................................................................................... 30 3.1.2. Activate a PDP Context.................................................................................................. 30 3.1.3. Deactivate a PDP Context ............................................................................................. 30 3.2. Configure an SSL Context ........................................................................................................ 30 3.3. SSL Client in Buffer Access Mode ............................................................................................ 31 3.3.1. Set up an SSL Connection and Enter Buffer Access Mode........................................... 31 3.3.2. Send Data in Buffer Access Mode ................................................................................. 31 3.3.3. Receive Data in Buffer Access Mode ............................................................................ 31 3.3.4. Close an SSL Connection .............................................................................................. 32 3.4. SSL Client in Direct Push Mode................................................................................................ 32 3.4.1. Set up an SSL Connection and Enter Direct Push Mode .............................................. 32 3.4.2. Send Data in Direct Push Mode..................................................................................... 32 3.4.3. Receive Data in Direct Push Mode ................................................................................ 33 3.4.4. Close an SSL Connection .............................................................................................. 33 EG800Q-EU&EG915Q-NA_SSL_Application_Note 4 / 38 LTE Standard Module Series 3.5. SSL Client in Transparent Transmission Mode ........................................................................ 33 3.5.1. Set up an SSL Connection and Send Data in Transparent Transmission Mode........... 33 3.5.2. Set up an SSL Connection and Receive Data in Transparent Transmission Mode ...... 33 3.5.3. Close an SSL Connection .............................................................................................. 33 4 Check for Failure in SSL Connection .............................................................................................. 34 5 Result Codes ...................................................................................................................................... 35 6 Appendix References ........................................................................................................................ 37 EG800Q-EU&EG915Q-NA_SSL_Application_Note 5 / 38 LTE Standard Module Series Table Index Table 1: SSL Versions .................................................................................................................................. 7 Table 2: Supported SSL Cipher Suites ........................................................................................................ 7 Table 3: Type of AT Commands ................................................................................................................. 12 Table 4: Result Codes ................................................................................................................................ 35 Table 5: Related Documents ...................................................................................................................... 37 Table 6: Terms and Abbreviations .............................................................................................................. 37 EG800Q-EU&EG915Q-NA_SSL_Application_Note 6 / 38 LTE Standard Module Series 1 Introduction Quectel EG800Q-EU and EG915Q-NA modules support SSL function. The SSL function is to ensure the privacy of communication. In some cases, the communication between the server and the client should be encrypted to prevent data from being eavesdropped, tampered with or forged during the communication process. This document introduces how to use the SSL function on Quectel EG800Q-EU and EG915Q-NA modules through AT commands. 1.1. SSL Version and Cipher Suite The following SSL versions are supported. Table 1: SSL Versions SSL Versions SSL 3.0 TLS 1.2 TLS 1.1 TLS 1.0 The following table shows SSL cipher suites supported by Quectel EG800Q-EU and EG915Q-NA modules, and all the SSL cipher suites are supported by default. For detailed description of cipher suites, see RFC 2246-The TLS Protocol Version 1.0. Table 2: Supported SSL Cipher Suites Codes of Cipher Suites Names of Cipher Suites 0X0035 TLS_RSA_WITH_AES_256_CBC_SHA EG800Q-EU&EG915Q-NA_SSL_Application_Note 7 / 38 0X002F 0X0005 0X0004 0X000A 0X003D 0XC002 0XC003 0XC004 0XC005 0XC007 0XC008 0XC009 0XC00A 0XC011 0XC012 0XC013 0XC014 0xC00C 0XC00D 0XC00E 0XC00F 0XC023 0xC024 0xC025 LTE Standard Module Series TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_RC4_128_SHA TLS_RSA_WITH_RC4_128_MD5 TLS_RSA_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_ECDH_ECDSA_WITH_RC4_128_SHA TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_RC4_128_SHA TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_RC4_128_SHA TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_ECDH_RSA_WITH_RC4_128_SHA TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDH_RSA_WITH_AES_128_CBC_SHA TLS_ECDH_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 EG800Q-EU&EG915Q-NA_SSL_Application_Note 8 / 38 0xC026 0XC027 0XC028 0xC029 0XC02A 0XC02F 0XFFFF LTE Standard Module Series TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 Support all the cipher suites listed above 1.2. Using SSL Function Step 1: Configure , , and other parameters of a PDP context by AT+QICSGP. See document [1] for details. Step 2: Activate the PDP context by AT+QIACT, then query the assigned IP address by AT+QIACT?. See document [1] for details. Step 3: Configure the SSL version, cipher suite, path of trusted CA certificate, authentication mode, the path of the client certificate and private key, etc. for a specified SSL context by AT+QSSLCFG. Step 4: Open an SSL socket to connect a remote server by AT+QSSLOPEN. Step 5: After the SSL connection has been established, data will be sent or received over the connection. For details about how to send and receive data in each access mode, see Chapter 1.3. Step 6: Close SSL connection by AT+QSSLCLOSE. Step 7: Deactivate the PDP context by AT+QIDEACT. See document [1] for details. 1.3. Description of Data Access Modes The SSL connection supports the following three data access modes: ⚫ Buffer access mode ⚫ Direct push mode EG800Q-EU&EG915Q-NA_SSL_Application_Note 9 / 38 LTE Standard Module Series ⚫ Transparent transmission mode When opening an SSL connection over AT+QSSLOPEN, the data access mode can be specified by the . After the SSL connection has been established, AT+QISWTMD can be used to switch the data access mode. For details of AT+QISWTMD, see document [1] for details. 1. In buffer access mode, data can be sent via AT+QSSLSEND, and the module buffers data upon receiving them and reports a URC in the format of +QSSLURC: 'recv', to notify the host of the incoming data. In this case, the host can retrieve the buffered data with AT+QSSLRECV. 2. In direct push mode, data can be sent via AT+QSSLSEND, and the module outputs the received data directly over UART/USB modem/USB AT port in the format of +QSSLURC: 'recv',,. 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 +++. To prevent the +++ from being misinterpreted as data, follow the requirements below: a) Do not input any other character 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 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 [2]) 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 the as 2. Once transparent transmission mode is entered successfully, CONNECT is returned. 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. See document [2] for detailed information about ATO. EG800Q-EU&EG915Q-NA_SSL_Application_Note 10 / 38 LTE Standard Module Series 1.4. Certificate Validity Check To check certificate validity, the certificate must be parsed, and the local time compared with the 'Not before' and 'Not after' of the certificate. If the local time is earlier than the 'Not before' time or later than the 'Not after' time the certificate has expired. When validity check of certificate is required (set as 0 when executing AT+QSSLCFG), to avoid failure of certificate validity check, execute AT+CCLK to configure the module time within the validity time period of the certificate. For details of AT+CCLK, see document [2]. 1.5. Server Name Indication SNI (Server Name Indication) allows the server to safely host multiple TLS Certificates since it provides Server Host Name information as an extension in the client hello message. It thus enhances connection security with multiple virtual servers based on a single IP address. This feature is only applicable to TLS protocol. EG800Q-EU&EG915Q-NA_SSL_Application_Note 11 / 38 LTE Standard Module Series 2 Description of SSL AT Commands 2.1. AT Command Description 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 to its previous value or the default setting, 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: Type 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. EG800Q-EU&EG915Q-NA_SSL_Application_Note 12 / 38 LTE Standard Module Series 2.1.3. Declaration of AT Command Examples The AT command examples in this document are provided to help you familiarize with AT commands and learn how to use them. 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.2. Description of AT Commands 2.2.1. AT+QSSLCFG Configure Parameters of an SSL Context This command configures the SSL version, cipher suite, path of trusted CA certificate, authentication mode, the path of the client certificate and private key, etc. for a specified SSL context. These parameters will be used in the handshake procedure. is the index of the SSL context. The module supports 6 SSL contexts at most. On the basis of one SSL context, several SSL connections can be established. The settings such as the SSL version and the cipher suite are stored in the SSL context, and they will be applied to the new SSL connections associated with the SSL context. AT+QSSLCFG Configure Parameters of an SSL Context Test Command AT+QSSLCFG=? Response +QSSLCFG: 'sslversion',(range of supported s),(range of supported s) +QSSLCFG: 'seclevel',(range of supported s),(range of supported s) +QSSLCFG: 'ciphersuite',(range of supported s), +QSSLCFG: 'negotiatetime',(range of supported s),(range of supported s) +QSSLCFG: 'sni',(range of supported s),(li st of supported s) +QSSLCFG: 'cacert',(range of supported s), +QSSLCFG: 'cacertex',(range of supported s),< cacertexpath> +QSSLCFG: 'clientcert',(range of supported s), +QSSLCFG: 'clientkey',(range of supported s),, +QSSLCFG: 'dtls',(range of supported s), EG800Q-EU&EG915Q-NA_SSL_Application_Note 13 / 38 LTE Standard Module Series (list of supported s) +QSSLCFG: 'psk',(range of supported s), , +QSSLCFG: 'ignoremulticertchainverify',(range of sup ported s),(list of supported s) +QSSLCFG: 'ignoreinvalidcertsign',(range of supporte d s),(list of supported s) +QSSLCFG: 'ignorecertitem',(range of supported s),(list of supported s) +QSSLCFG: 'ignorelocaltime',(range of supported s),(list of supported s) +QSSLCFG: 'session_cache',(range of supported s),(list of supported s) +QSSLCFG: 'closetimemode',(range of supported s),(list of supported s) +QSSLCFG: 'renegotiation',(range of supported s),(list of supported s) +QSSLCFG: 'alpn',(range of supported s), Write Command Configure the SSL version for a specified SSL context: AT+QSSLCFG='sslversion',[,] OK Response If the optional parameter is omitted, query the SSL version for a specified SSL context: +QSSLCFG: 'sslversion',, OK Write Command Configure the authentication mode for a specified SSL context: AT+QSSLCFG='seclevel',[,] If the optional parameter is specified, set the SSL version for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query the authentication mode for a specified SSL context: +QSSLCFG: 'seclevel',, OK If the optional parameter is specified, set the authentication mode for a specified SSL context: EG800Q-EU&EG915Q-NA_SSL_Application_Note 14 / 38 LTE Standard Module Series Write Command Configure the SSL cipher suites for a specified SSL context: AT+QSSLCFG='ciphersuite',[,] OK Or ERROR Response If the optional parameter is omitted, query the SSL cipher suites for a specified SSL context: +QSSLCFG: 'ciphersuite',, OK If the optional parameter is specified, set the SSL cipher suite for a specified SSL context: OK Or ERROR Write Command Response Configure the maximum timeout in SSL If the optional parameter is omitted, query the maximum negotiation stage for a specified SSL timeout in SSL negotiation stage for a specified SSL context: context: +QSSLCFG: 'negotiatetime',,<negotiate_ti AT+QSSLCFG='negotiatetime', ctxID>[,] OK Write Command Configure Server Name Indication feature for a specified SSL context: AT+QSSLCFG='sni',[,] If the optional parameter is specified, set the maximum timeout in SSL negotiation stage for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the Server Name Indication feature is enabled for a specified SSL context: +QSSLCFG: 'sni',, OK If the optional parameter is specified, disable/enable Server Name Indication feature for a specified SSL context: OK Or ERROR Write Command Response Configure the path of trusted CA If the optional parameter is omitted, query the path of trusted certificate for a specified SSL context: CA certificate for a specified SSL context: EG800Q-EU&EG915Q-NA_SSL_Application_Note 15 / 38 LTE Standard Module Series AT+QSSLCFG='cacert',[, ] +QSSLCFG: 'cacert',, OK If the optional parameter is specified, set the path of trusted CA certificate for a specified SSL context: OK Or ERROR Write Command Response Configure the path of trusted CA If all optional parameters are omitted, query the path of certificate for a specified : trusted CA certificate chain for all SSL contexts: AT+QSSLCFG='cacertex'[,[,<c +QSSLCFG: 'cacertex',0, acertexpath>]] … +QSSLCFG: 'cacertex',5, OK If only is omitted, query the path of trusted CA certificate for a specified : +QSSLCFG: 'cacertex',, OK Write Command Configure the path of client certificate for a specified SSL context: AT+QSSLCFG='clientcert',[,] If all optional parameters are specified, set the path of trusted CA certificate for a specified : OK Or ERROR Response If the optional parameter is omitted, query the path of client certificate for a specified SSL context: +QSSLCFG: 'clientcert',, OK Write Command Configure the path of client private key for If the optional parameter is specified, set the path of client certificate for a specified SSL context: OK Or ERROR Response If the optional parameters are omitted, query the path of EG800Q-EU&EG915Q-NA_SSL_Application_Note 16 / 38 LTE Standard Module Series a specified SSL context: client private key for a specified SSL context: AT+QSSLCFG='clientkey',[,[,]] 'clientkey',,, OK Write Command Configure the DTLS function for a specified SSL context: AT+QSSLCFG='dtls',[, If the optional parameters are specified, set the path of client private key for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the DTLS function is enabled for a specified SSL context: +QSSLCFG: 'dtls',, OK Write Command Configure the PSK used in handshake for a specified SSL context: AT+QSSLCFG='psk',[,,] If the optional parameter is specified, enable/disable the DTLS function for a specified SSL context: OK Or ERROR Response If the optional parameters are omitted, query the current configuration for a specified SSL context: +QSSLCFG: 'psk',,, OK Write Command Configure whether to ignore multiple level certificate chain verification for a specified SSL context: AT+QSSLCFG='ignoremulticertchainv erify',[,] If the optional parameters are specified, set the PSK used in handshake for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the multiple level certificate chain verification is ignored for a specified SSL context: +QSSLCFG: 'ignoremulticertchainverify',, OK EG800Q-EU&EG915Q-NA_SSL_Application_Note 17 / 38 LTE Standard Module Series Write Command Configure whether to ignore the invalid certificate signature for a specified SSL context: AT+QSSLCFG='ignoreinvalidcertsign' ,[,] If the optional parameter is specified, set whether or not to ignore multiple level certificate chain verification for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the invalid certificate signature is ignored for a specified SSL context: +QSSLCFG: 'ignoreinvalidcertsign',, OK If the optional parameter is specified, set whether or not to ignore the invalid certificate signature for a specified SSL context: OK Or ERROR Write Command Response Configure whether to ignore one or more If the optional parameter is omitted, query whether one or checks specified in the certificate sent by more checks specified in the certificate sent by the server is the server for a specified SSL context: ignored for a specified SSL context: AT+QSSLCFG='ignorecertitem',<SSL +QSSLCFG: 'ignorecertitem',,[,] eck_item> OK Write Command Configure whether to ignore certificate validity check for a specified SSL context: AT+QSSLCFG='ignorelocaltime',[,] If the optional parameter is specified, set whether or not to ignore one or more checks specified in the certificate sent by the server for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the certificate validity check is ignored for a specified SSL context: +QSSLCFG: 'ignorelocaltime',, OK EG800Q-EU&EG915Q-NA_SSL_Application_Note 18 / 38 LTE Standard Module Series Write Command Enable/Disable SSL session resumption function for a specified SSL context: AT+QSSLCFG='session_cache',[,] If the optional parameter is specified, set whether or not to ignore certificate validity check for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the SSL session resumption function is enabled for a specified SSL context: +QSSLCFG: 'session_cache',, OK Write Command Enable/disable the delay in closing the SSL connection for a specified SSL context: AT+QSSLCFG='closetimemode',[,] If the optional parameter is specified, enable/disable the SSL session resumption function: OK Or ERROR Response If the optional parameter is omitted, query whether the delay in closing the SSL connection is enabled for a specified SSL context: +QSSLCFG: 'closetimemode',, OK Write Command Enable/disable TLS renegotiation function for a specified SSL context: AT+QSSLCFG='renegotiation',[,] If the optional parameter is specified, enable/disable the delay in closing the SSL connection for a specified SSL context: OK Or ERROR Response If the optional parameter is omitted, query whether the TLS renegotiation function is enabled for a specified SSL context: +QSSLCFG: 'renegotiation',, OK If the optional parameter is specified, enabled/disable the EG800Q-EU&EG915Q-NA_SSL_Application_Note 19 / 38 LTE Standard Module Series TLS renegotiation function for a specified SSL context: OK Or ERROR Write Command Response Configure the ALPN information for a If the optional parameter is omitted, query the ALPN specified SSL context: information for a specified SSL context: AT+QSSLCFG='alpn',[,< +QSSLCFG: 'alpn',, ALPN_name>] OK Maximum Response Time Characteristics If the optional parameter is specified, configure the ALPN information for a specified SSL context: OK Or ERROR 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. SSL context ID. Range: 0–5. Integer type. SSL version. 0 SSL 3.0 1 TLS 1.0 2 TLS 1.1 3 TLS 1.2 4 All Integer type. The authentication mode. 0 No authentication 1 Perform server authentication 2 Perform server and client authentication if requested by the remote server Numeric type in HEX format. SSL cipher suites. 0X0035 TLS_RSA_WITH_AES_256_CBC_SHA 0X002F TLS_RSA_WITH_AES_128_CBC_SHA 0X0005 TLS_RSA_WITH_RC4_128_SHA 0X0004 TLS_RSA_WITH_RC4_128_MD5 0X000A TLS_RSA_WITH_3DES_EDE_CBC_SHA 0X003D TLS_RSA_WITH_AES_256_CBC_SHA256 0XC002 TLS_ECDH_ECDSA_WITH_RC4_128_SHA 0XC003 TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA EG800Q-EU&EG915Q-NA_SSL_Application_Note 20 / 38 LTE Standard Module Series 0XC004 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 0XC005 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 0XC007 TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 0XC008 TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 0XC009 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 0XC00A TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 0XC011 TLS_ECDHE_RSA_WITH_RC4_128_SHA 0XC012 TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 0XC013 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 0XC014 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 0xC00C TLS_ECDH_RSA_WITH_RC4_128_SHA 0XC00D TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 0XC00E TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 0XC00F TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 0XC023 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 0xC024 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 0xC025 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 0xC026 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 0XC027 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 0XC028 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 0xC029 TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 0XC02A TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 0XC02F TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 0XFFFF Support all cipher suites Integer type. Indicates maximum timeout used in SSL negotiation stage. Range: 10–300. Default value: 300. Unit: second. Integer type. Disables/enables Server Name Indication feature. 0 Disable 1 Enable String type. The path of the trusted CA certificate. Integer type. The certificate index of the CA certificate chain. String type. The path of the trusted CA certificate. String type. The path of the client certificate. String type. The path of the client private key. String type. The password of the client private key. Integer type. Enables/disables the DTLS function. 0 Disable 1 Enable String type. Identity of PSK. The length is 0–255. String type. Key of PSK. The length is 0–255. Integer type. Indicates whether or not to ignore the multiple level certificate chains verification. 0 Not to ignore 1 Ignore EG800Q-EU&EG915Q-NA_SSL_Application_Note 21 / 38 LTE Standard Module Series Integer type. Indicates whether or not to ignore the invalid certificate signature. 0 Not to ignore 1 Ignore Integer type. Indicates whether the client ignores one or more checks specified in the certificate sent by the server. The parameter applies an accumulative value if the client ignores more checks. 0 Not ignore any check item in the certificate 1 Ignore that the certificate validity has expired 4 Ignore certificate common name does not match expected CN 8 Ignore that the certificate is not correctly signed by the trusted CA 256 Ignore other reasons (The reason used to verify the callback) 2048 Ignore Usage does not match keyUsage extension 4096 Ignore Usage does not match extendedKeyUsage extension 8192 Ignore Usage does not match nsCertType extension 32768 Ignore that the certificate signed with unacceptable public key algorithm (such as RSA, ECDSA) 65536 Ignore that the certificate signed with an unacceptable key 1048575 Ignore all check items, that is, not to check the certificate Integer type. Indicates whether or not to ignore certificate validity check. 0 Not to ignore 1 Ignore Integer type. Enables/disables the SSL session resumption function. 0 Disable 1 Enable Integer type. Enables/disables the delay in closing the SSL connection. 0 Disable, and the unit of SSL close linger time is second 1 Enable, and the unit of SSL close linger time is millisecond Integer type. Enable/disable the TLS renegotiation function. 0 Disable 1 Enable String type. Configures ALPN protocol name. When the content of this parameter is null (only double quotes are specified), TLS does not contain ALPN extension content. 2.2.2. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server This command sets up an SSL connection, that is, opens an SSL socket to connect a remote server. During the negotiation between the module and the Internet, parameters configured by AT+QSSLCFG will be used in the handshake procedure. After shaking hands with the Server successfully, the module can send or receive data over this SSL connection. Also, the module can set up several SSL connections based on one SSL context. EG800Q-EU&EG915Q-NA_SSL_Application_Note 22 / 38 LTE Standard Module Series According to steps mentioned in Chapter 1.2, before executing AT+QSSLOPEN, execute AT+QIACT first to activate the PDP context. It is suggested to wait for a specific period of time (refer to the Maximum Response Time below) for +QSSLOPEN: , URC to be outputted. If the URC response cannot be received during the time, AT+QSSLCLOSE can be used to close the SSL connection. AT+QSSLOPEN Open an SSL Socket to Connect a Remote Server Test Command AT+QSSLOPEN=? Response +QSSLOPEN: (range of supported s),(range of supported s),(range of supported s),,[,(range of supported s)] Write Command AT+QSSLOPEN=,,,,[,] OK Response If the =2 and the SSL connection is successfully set up: CONNECT If there is any error: ERROR Error description can be got over AT+QIGETERROR. If the =0/1: OK +QSSLOPEN: , is 0 when SSL socket is opened successfully, and is not 0 when opening SSL socket fails. Maximum Response Time Characteristics If there is any error: ERROR Error description can be got over AT+QIGETERROR. Maximum network response time of 150 s, plus configured time of . The command takes effect immediately. The configurations are not saved. Parameter Integer type. PDP context ID. Range: 1–15. Integer type. SSL context ID. Range: 0–5. EG800Q-EU&EG915Q-NA_SSL_Application_Note 23 / 38 LTE Standard Module Series Integer type. Socket index. Range: 0–11. String type. Remote server address. Integer type. Listening port of remote server. Integer type. The access mode of SSL connection. 0 Buffer access mode 1 Direct push mode 2 Transparent transmission mode Integer type. Result code. See Chapter 5 for details. Integer type. Indicates maximum timeout used in SSL negotiation stage. Range: 10–300. Default value: 300. Unit: second. 2.2.3. AT+QSSLSEND Send Data over SSL Connection After the connection is established, the module can send data through the SSL connection. AT+QSSLSEND Send Data over SSL Connection Test Command AT+QSSLSEND=? Response +QSSLSEND: (range of supported s)[,(range of supported s)] Write Command Send variable-length data AT+QSSLSEND= OK Response > After the above response, input the data to be sent. Tap CTRL+Z to send, and tap ESC to cancel the operation. If the connection has been established and sending is successful: SEND OK If connection has been established but sending buffer is full: SEND FAIL Write Command Send fixed-length data AT+QSSLSEND=, If the connection has not been established, abnormally closed, or any parameter is incorrect: ERROR Response > After the above response, input the data until the data length equals . If connection has been established and sending is successful: SEND OK EG800Q-EU&EG915Q-NA_SSL_Application_Note 24 / 38 LTE Standard Module Series Maximum Response Time Characteristics If connection has been established but sending buffer is full, response: SEND FAIL If the connection has not been established, abnormally closed, or any parameter is incorrect: ERROR 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. Socket index. Range: 0–11. Integer type. The length of sending data. Range: 1–1460. Unit: byte. NOTE The maximum length of fixed-length data or variable-length data is 1460 bytes. 2.2.4. AT+QSSLRECV Receive Data over SSL Connection When an SSL connection is opened with specified as 0, the module will report URC as +QSSLURC: 'recv', when it receives data from the Internet. You can read the data from buffer by AT+QSSLRECV. AT+QSSLRECV Receive Data over SSL Connection Test Command AT+QSSLRECV=? Response +QSSLRECV: (range of supported s),(range of supported s) Write Command AT+QSSLRECV=, OK Response If the specified socket connection has received data: +QSSLRECV: OK If the buffer is empty: +QSSLRECV: 0 EG800Q-EU&EG915Q-NA_SSL_Application_Note 25 / 38 LTE Standard Module Series Maximum Response Time Characteristics OK If the connection has not been established, abnormally closed, or any parameter is incorrect: ERROR 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. Socket index. Range: 0–11. Integer type. The length of data to be retrieved. Range: 1–1500. Unit: byte. Integer type. The actual data length obtained by AT+QSSLRECV. Unit: byte. The retrieved data. 2.2.5. AT+QSSLCLOSE Close an SSL Connection This command closes an SSL connection. If all SSL connections based on the same SSL context are closed, the module releases the SSL context. AT+QSSLCLOSE Close an SSL Connection Test Command AT+QSSLCLOSE=? Response +QSSLCLOSE: (range of supported s),(range of supported s) Write Command AT+QSSLCLOSE=[,] OK Response If the SSL connection is successfully closed: OK Maximum Response Time Characteristics If it is failed to close the connection: ERROR Determined by The command takes effect immediately. The configurations are not saved. EG800Q-EU&EG915Q-NA_SSL_Application_Note 26 / 38 LTE Standard Module Series Parameter Integer type. Socket index. Range: 0–11. Integer type. The timeout of executing AT+QSSLCLOSE. Range: 0–65535. Default value: 10. 0 means closing immediately. The unit of depends on the configuration of AT+QSSLCFG='closetimemode': if =0, the unit is second. If =1, the unit is microsecond. 2.2.6. AT+QSSLSTATE Query the State of SSL Connection This command queries the socket connection status and can only query the SSL connection status. AT+QSSLSTATE Query the State of SSL Connection Test Command AT+QSSLSTATE=? Write Command AT+QSSLSTATE= Response OK Response +QSSLSTATE: ,'SSLClient',,,,,,,,, Execution Command AT+QSSLSTATE OK Response List of (+QSSLSTATE: ,'SSLClient',,,,,,,,,)s Maximum Response Time Characteristics OK 300 ms / Parameter Integer type. Socket index. Range: 0–11. String type. Remote server address. Integer type. Remote server port. Range: 0–65535. Integer type. Local port. Range: 0–65535. Integer type. SSL connection state. 0 'Initial' Connection has not been established 1 'Opening' Client is connecting 2 'Connected' Client connection has been established 4 'Closing' Connection is closing EG800Q-EU&EG915Q-NA_SSL_Application_Note 27 / 38 LTE Standard Module Series Integer type. PDP context ID. Range: 1–15. Integer type. Reserved. Integer type. The access mode of SSL connection. 0 Buffer access mode 1 Direct push mode 2 Transparent transmission mode String type. The COM port. 'usbat' USB AT port 'uart1' Main UART 'usbmodem' USB Modem port 'uart2' Auxiliary UART Integer type. SSL context ID. Range: 0–5. 2.3. Description of URCs 2.3.1. +QSSLURC: 'recv' Notify Received Data The URC notifies the data received from peer in buffer access mode and direct push mode. +QSSLURC: 'recv' Notify Received Data +QSSLURC: 'recv', +QSSLURC: 'recv',, The URC of SSL data incoming in buffer access mode. SSL data can be received by AT+QSSLRECV. The URC of SSL data incoming in direct push mode. Parameter Integer type. Socket index. Range: 0–11. Integer type. The length of actual received data. Unit: byte. The received data. 2.3.2. +QSSLURC: 'closed' Notify Abnormal Disconnection The URC notifies that the SSL connection has been disconnected. Disconnection can be caused by many reasons. For example, the Internet closes the connection or the state of PDP is deactivated. The SSL connection state based on a specified socket will be 'closing'. In such case, AT+QSSLCLOSE= must be executed to change the SSL connection state to 'initial'. +QSSLURC: 'closed' Notify Abnormal Disconnection +QSSLURC: 'closed', The SSL connection based on the specified socket is closed. EG800Q-EU&EG915Q-NA_SSL_Application_Note 28 / 38 Parameter Integer type. Socket index. Range: 0–11. LTE Standard Module Series EG800Q-EU&EG915Q-NA_SSL_Application_Note 29 / 38 LTE Standard Module Series 3 Examples 3.1. Configure and Activate a PDP Context 3.1.1. Configure a PDP Context AT+QICSGP=1,1,'UNINET','','',1 OK //Configure context as 1. APN is 'UNINET' for China Unicom. 3.1.2. Activate a PDP Context AT+QIACT=1 OK AT+QIACT? +QIACT: 1,1,1,'10.7.157.1' //Activate context as 1. //Activated successfully. //Query the state of context. OK 3.1.3. Deactivate a PDP Context AT+QIDEACT=1 OK //Deactivate context 1. //Deactivated successfully. 3.2. Configure an SSL Context AT+QSSLCFG='sslversion',1,1 OK AT+QSSLCFG='ciphersuite',1,0X0035 OK AT+QSSLCFG='seclevel',1,1 OK //Set SSL context ID and SSL version as 1. //Set SSL context ID as 1 and SSL cipher suites as TLS_RSA_WITH_AES_256_CBC_SHA. //Set SSL context ID as 1 and authentication mode as perform server authentication. EG800Q-EU&EG915Q-NA_SSL_Application_Note 30 / 38 LTE Standard Module Series AT+QSSLCFG='cacert',1,'RAM:cacert.pem' //Set SSL context ID as 1 and the path of the trusted CA certificate as RAM:cacert.pem. OK 3.3. SSL Client in Buffer Access Mode 3.3.1. Set up an SSL Connection and Enter Buffer Access Mode AT+QSSLOPEN=1,1,4,'220.180.239.212',8010,0 OK +QSSLOPEN: 4,0 //Set up an SSL connection successfully. AT+QSSLSTATE //Query the status of all SSL connections. +QSSLSTATE: 4,'SSLClient','220.180.239.212',8010,65344,2,1,4,0,'usbmodem',1 OK 3.3.2. Send Data in Buffer Access Mode 3.3.2.1. Send Variable-Length Data AT+QSSLSEND=4 > Test data from SSL SEND OK //Send variable-length data. 3.3.2.2. Send Fixed-Length Data AT+QSSLSEND=4,18 > Test data from SSL SEND OK //Send fixed-length data with the data length of 18 bytes. 3.3.3. Receive Data in Buffer Access Mode +QSSLURC: 'recv',4 //The socket 4 (=4) has received data. AT+QSSLRECV=4,1500 //Read data. The length of data to be retrieved is 1500 bytes. EG800Q-EU&EG915Q-NA_SSL_Application_Note 31 / 38 +QSSLRECV: 18 Test data from SSL OK AT+QSSLRECV=4,1500 +QSSLRECV: 0 OK LTE Standard Module Series //The actual received data length is 18 bytes. //No data in buffer. 3.3.4. Close an SSL Connection AT+QSSLCLOSE=4 OK //Close an SSL connection (=4). Depending on the network, the maximum response time is 10 s. 3.4. SSL Client in Direct Push Mode 3.4.1. Set up an SSL Connection and Enter Direct Push Mode AT+QSSLOPEN=1,1,4,'220.180.239.212',8011,1 OK +QSSLOPEN: 4,0 //Set up SSL connection successfully. AT+QSSLSTATE //Query the status of all SSL connections. +QSSLSTATE: 4,'SSLClient','220.180.239.212',8011,65047,2,1,4,1,'usbmodem',1 OK 3.4.2. Send Data in Direct Push Mode AT+QSSLSEND=4 > Test data from SSL SEND OK AT+QSSLSEND=4,18 > Test data from SSL SEND OK //Send variable-length data. //Send fixed-length data and the data length is 18 bytes. EG800Q-EU&EG915Q-NA_SSL_Application_Note 32 / 38 LTE Standard Module Series 3.4.3. Receive Data in Direct Push Mode +QSSLURC: 'recv',4,18 Test data from SSL 3.4.4. Close an SSL Connection AT+QSSLCLOSE=4 OK //Close a connection (=4). Depending on the network, the maximum response time is 10 s. 3.5. SSL Client in Transparent Transmission Mode 3.5.1. Set up an SSL Connection and Send Data in Transparent Transmission Mode AT+QSSLOPEN=1,1,4,'220.180.239.212',8011,2 //Set up an SSL connection. CONNECT //Enter transparent transmission mode. //Client is sending data from COM port to the Internet directly. (The data is not visible in the example.) OK //Use +++ or DTR (set AT&D1 first) to exit transparent transmission mode. The NO CARRIER result code indicates that the server has stopped the SSL connection. 3.5.2. Set up an SSL Connection and Receive Data in Transparent Transmission Mode AT+QSSLOPEN=1,1,4,'220.180.239.212',8011,2 //Set up an SSL connection. CONNECT //Client is reading the data. OK //Use +++ or DTR (set AT&D1 first) to exit transparent transmission mode. The NO CARRIER result code indicates that the server has stopped the SSL connection. 3.5.3. Close an SSL Connection AT+QSSLCLOSE=4 OK //Close a connection (=4). Depending on the network, the maximum response time is 10 s. EG800Q-EU&EG915Q-NA_SSL_Application_Note 33 / 38 LTE Standard Module Series 4 Check for Failure in SSL Connection To identify reasons for the failure to open an SSL connection: 1. Query the status of the specified PDP context by AT+QIACT? to check whether the specified PDP context has been activated. 2. Since an invalid DNS server address cannot convert domain name to IP address, if the address of server is a domain name, check whether the DNS server address is valid by AT+QIDNSCFG=. See document [1] for detailed information about AT+QIDNSCFG. 3. Check the SSL configuration by AT+QSSLCFG, especially the SSL version and cipher suite to ensure that they are supported on server side. If has been configured as 1 or 2, then the trusted CA certificate has to be uploaded to the module with AT+QFUPL. If the server side has configured 'SSLVerifyClient required', then the client certificate and client private key have to be uploaded to the module with AT+QFUPL. For details about certificate validity check, see Chapter 1.4. see document [3] for more details of AT+QFUPL. EG800Q-EU&EG915Q-NA_SSL_Application_Note 34 / 38 LTE Standard Module Series 5 Result Codes If an ERROR or URC error code is returned after executing SSL AT commands, the details of errors can be queried by AT+QIGETERROR. Please note that AT+QIGETERROR just returns result code of the last SSL AT command. See document [1] for details of AT+QIGETERROR. Table 4: Result Codes 0 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 Description Operation successful Unknown error Operation blocked Invalid parameter Memory not enough Create socket failed Operation not supported Socket bind failed Socket listen failed Socket write failed Socket read failed Socket accept failed Open PDP context failed Close PDP context failed Socket identity has been used DNS busy EG800Q-EU&EG915Q-NA_SSL_Application_Note 35 / 38 LTE Standard Module Series 565 DNS parse failed 566 Socket connection failed 567 Socket has been closed 568 Operation busy 569 Operation timeout 570 PDP context break down 571 Cancel send 572 Operation not allowed 573 APN not configured 574 Port busy EG800Q-EU&EG915Q-NA_SSL_Application_Note 36 / 38 LTE Standard Module Series 6 Appendix References Table 5: Related Documents Document Name [1] Quectel_EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note [2] Quectel_EG800Q-EU&EG915Q-NA_AT_Commands_Manual [3] Quectel_EG800Q-EU&EG915Q-NA_FILE_Application_Note Table 6: Terms and Abbreviations Abbreviation ALPN APN CA DNS DTR DTLS PDP SNI SSL TCP/IP TLS UART URC Description Application Layer Protocol Negotiation Access Point Name Certificate Authority Domain Name Server Data Terminal Ready Datagram Transport Layer Security Packet Data Protocol Server Name Indication Security Socket Layer Transmission Control Protocol/Internet Protocol Transport Layer Security Universal Asynchronous Receiver/Transmitter Unsolicited Result Code EG800Q-EU&EG915Q-NA_SSL_Application_Note 37 / 38 USB Universal Serial Bus LTE Standard Module Series EG800Q-EU&EG915Q-NA_SSL_Application_Note 38 / 38

Quectel_EG800Q-EU&EG915Q-NA_SSL_Application_Note_V1.0

PDF

297.97 KB

BC660K-GL&BC950K-GL Throughput Test Guide NB-IoT Module Series Version: 1.1 Date: 2023-04-25 Status: Released 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&BC950K-GL_Throughput_Test_Guide 1 / 17 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. 2023. All rights reserved. BC660K-GL&BC950K-GL_Throughput_Test_Guide 2 / 17 NB-IoT Module Series About the Document Revision History Version 1.0 1.1 Date 2022-07-19 2022-09-30 2023-04-25 Author Lewis Liu/ Jacobi Rao Lewis Liu/ Jacobi Rao Yance YANG/ Randy LI Description Creation of the document First official release Added the applicable module BC950K-GL. BC660K-GL&BC950K-GL_Throughput_Test_Guide 3 / 17 NB-IoT Module Series Contents About the Document .................................................................................................................................. 3 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 2 General Overview of Throughput...................................................................................................... 8 3 Throughput Test Preparation ............................................................................................................ 9 4 Throughput Test................................................................................................................................ 10 4.1. Throughput Test with Iperf ....................................................................................................... 10 4.1.1. Uplink Throughput Test................................................................................................. 10 4.1.2. Downlink Throughput Test ............................................................................................ 11 4.1.3. Statistics from AT+QCFG='statisr' ............................................................................... 12 4.2. Throughput Test with TCP/UDP .............................................................................................. 13 4.2.1. Uplink Throughput Test................................................................................................. 13 4.2.2. Downlink Throughput Test ............................................................................................ 15 4.2.3. Statistics from AT+QCFG='statisr' ............................................................................... 15 5 Appendix References ....................................................................................................................... 17 BC660K-GL&BC950K-GL_Throughput_Test_Guide 4 / 17 NB-IoT Module Series Table Index Table 1: Related Documents...................................................................................................................... 17 Table 2: Terms and Abbreviations ............................................................................................................. 17 BC660K-GL&BC950K-GL_Throughput_Test_Guide 5 / 17 NB-IoT Module Series Figure Index Figure 1: QCOM Tool ................................................................................................................................... 9 Figure 2: The Response of AT+QCFG='statisr'........................................................................................ 12 Figure 3: QCOM Setting Interface ............................................................................................................. 14 Figure 4: Search Throughput in AT Logs................................................................................................... 16 BC660K-GL&BC950K-GL_Throughput_Test_Guide 6 / 17 NB-IoT Module Series 1 Introduction Quectel NB-IoT BC660K-GL and BC950K-GL modules do not support dial-up. Therefore, this document introduces how to test the throughput of BC660K-GL and BC950K-GL modules by using AT+QIPERF, AT+QIOPEN, AT+QICLOSE, AT+QISEND and AT+QCFG='statisr' provided by Quectel. BC660K-GL&BC950K-GL_Throughput_Test_Guide 7 / 17 NB-IoT Module Series 2 General Overview of Throughput A server is required for testing peak uplink and downlink throughput. For uplink throughput test, the module can send data to the server over TCP/UDP as a client. For downlink throughput test, the module can receive data from the server as a client or receive data from other clients as a server. If the module is regarded as a server, you should use the UDP NAT service. BC660K-GL&BC950K-GL_Throughput_Test_Guide 8 / 17 NB-IoT Module Series 3 Throughput Test Preparation 1. Prepare a server which supports Iperf with a known IP address and port. 2. Prepare the AT tool QCOM which supports storing the AT command interaction information. The blue box in the following figure is used to save the received data as a file. Figure 1: QCOM Tool ⚫NOTE Before you test the throughput, enable the throughput statistics and configure the reporting interval of statistics with AT+QCFG='statisr'. For example, AT+QCFG='statisr',10, that is, enable statistics URC reporting and set the reporting interval to 10 seconds. BC660K-GL&BC950K-GL_Throughput_Test_Guide 9 / 17 NB-IoT Module Series 4 Throughput Test 4.1. Throughput Test with Iperf 4.1.1. Uplink Throughput Test For uplink throughput test, the module is regarded as a client. Generally, it is recommended to perform peak throughput test in UDP mode. The following commands (with specified parameters) can be used for test: ⚫ AT+QIPERF=1,0,8058,'220.180.239.212',180000,940 ⚫ AT+QIPERF=1,1,8058,'220.180.239.212',180000,940 Below is an example: AT+QIPERF=1,0,8058,'220.180.239.212',180000,940 OK +QIPERF: Client SUCC, pkg sent bytes: 62920, UL through put: 50336 bps +QIPERF: Client END, pkg sent total bytes: 96800, average UL through put: 45552 bps AT+QIPERF=1,1,8058,'220.180.239.212',180000,940 OK +QIPERF: Client SUCC, pkg sent bytes: 42140, UL through put: 33712 bps +QIPERF: Client SUCC, pkg sent bytes: 31360, UL through put: 25088 bps +QIPERF: Client SUCC, pkg sent bytes: 13720, UL through put: 10976 bps +QIPERF: Client END, pkg sent total bytes: 98000, average UL through put: 23757 bps If you want to test uplink throughput in UDP mode, execute the first command while test uplink throughput in TCP mode, execute the second command. BC660K-GL&BC950K-GL_Throughput_Test_Guide 10 / 17 NB-IoT Module Series ⚫NOTE 1. BC660K-GL and BC950K-GL modules do not support modifying the reporting interval from one to another in enabled state. If you want to modify the interval time, disable statistics URC reporting with AT+QCFG='statisr',0 first, and then enable the statistics URC reporting and set the reporting interval to the expected interval timse. See document [1] for details. 2. Note that you need to replace the port number and IP address in the above commands with the server port and address actually used in throughput test, and the rest parameters are fixed. See document [1] for details about AT+QIPERF. 3. If you test the throughput with Qserver, please contact Quectel Technical Supports to start the server. 4.1.2. Downlink Throughput Test For downlink throughput test, the module is regarded as a server. Generally, it is recommended to perform peak throughput test in UDP mode. Since IP addresses of all operator networks are assigned by P-GW, in AT+QIPERF=,,, should be set to 4 (IPERF UDP NAT server). Then push data from the remote server to the module. For example, AT+QIPERF=4,0,8058,'220.180.239.212'. ⚫NOTE Note that you need to replace IP address and port number in the command with the server address and port actually used in throughput test. After testing, please stop the server with AT+QIPERF=5. See document [1] for details. BC660K-GL&BC950K-GL_Throughput_Test_Guide 11 / 17 NB-IoT Module Series 4.1.3. Statistics from AT+QCFG='statisr' If the Iperf server used supports throughput statistics, you can also use the throughput reported by the server. The response of AT+QCFG='statisr' is as follows. See document [1] for details. Figure 2: The Response of AT+QCFG='statisr' BC660K-GL&BC950K-GL_Throughput_Test_Guide 12 / 17 NB-IoT Module Series 4.2. Throughput Test with TCP/UDP 4.2.1. Uplink Throughput Test 1. Open a socket service with the corresponding IP address and port number through the following commands. Make sure the IP address and port number are correct for the server used. Below is an example: AT+QIOPEN=0,0,'UDP','220.180.239.212',8058,0,1 OK //Start a UDP connection as a client +QIOPEN: 0,0 //Connected successfully. It is recommended to wait for 60 seconds for the URC to be reported. AT+QIOPEN=0,0,'TCP','220.180.239.212',8058,0,1 //Start a TCP connection as a client OK +QIOPEN: 0,0 //Connected successfully. It is recommended to wait for 60 seconds for the URC to be reported. If you want to open a socket service in UDP mode, execute the first command while open a socket service in TCP mode, execute the second command. ⚫NOTE 1. BC660K-GL and BC950K-GL modules do not support modifying the reporting interval from one to another in enabled state. If you want to modify the interval time, disable the statistics URC reporting with AT+QCFG='statisr',0 first, and then enable the statistics URC reporting and set the reporting interval to the expected interval time. See document [1] for details. 2. Note that you need to replace the IP address and port number in the above commands according to specific requirements. See document [2] for details about the command. 3. If you test the throughput with Qserver, please contact Quectel Technical Supports to start the server. 2. Send data. Configure AT+QISEND=,,, and then copy the command content configured of AT+QISEND into the command list on the right side of QCOM, and check the checkbox in red part in Figure 3. Here is an example: AT+QISEND=0,1000,123456789012345678901234567890123456789012345678901234567890123456 78901234567890123456789012345678901234567890123456789012345678901234567890123456789 01234567890123456789012345678901234567890123456789012345678901234567890123456789012 34567890123456789012345678901234567890123456789012345678901234567890123456789012345 BC660K-GL&BC950K-GL_Throughput_Test_Guide 13 / 17 NB-IoT Module Series 67890123456789012345678901234567890123456789012345678901234567890123456789012345678 90123456789012345678901234567890123456789012345678901234567890123456789012345678901 23456789012345678901234567890123456789012345678901234567890123456789012345678901234 56789012345678901234567890123456789012345678901234567890123456789012345678901234567 89012345678901234567890123456789012345678901234567890123456789012345678901234567890 12345678901234567890123456789012345678901234567890123456789012345678901234567890123 45678901234567890123456789012345678901234567890123456789012345678901234567890123456 78901234567890123456789012345678901234567890123456789012345678901234567890123456789 012345678901234567890 Set 'Run times' to 1000 and 'Delay time' to 150 milliseconds. Then click the 'Run' button to automatically send the data to the server, as shown in the figure below. Figure 3: QCOM Setting Interface ⚫NOTE Note that has to equal the length of . See document [2] for details about the command. BC660K-GL&BC950K-GL_Throughput_Test_Guide 14 / 17 NB-IoT Module Series 4.2.2. Downlink Throughput Test 1. Open a socket service with the corresponding IP address and port number through the following commands. Make sure the IP address and port are correct for the server used. Here is an example: AT+QIOPEN=0,0,'UDP','220.180.239.212',8043,0,1 OK //Start a UDP connection as a client +QIOPEN: 0,0 //Connected successfully. It is recommended to wait for 60 seconds for the URC to be reported. AT+QIOPEN=0,0,'TCP','220.180.239.212',8043,0,1 //Start a TCP connection as a client OK +QIOPEN: 0,0 //Connected successfully. It is recommended to wait for 60 seconds for the URC to be reported. 2. Send data. For the downlink throughput test, connect the module to the server first by executing AT+QISEND=,,. After sending the data to the server, you can find the module at the server side. Then push data to the module at server side. 3. Close the socket service as follows: AT+QICLOSE=0 OK //Close a connection whose socket ID is 0. CLOSE OK 4.2.3. Statistics from AT+QCFG='statisr' If there are too many AT logs to be found, you can use Notepad to open the file. Use phyUITpt for searching uplink throughput while phyDlTpt for searching downlink throughput. Then search the related throughput as follow. BC660K-GL&BC950K-GL_Throughput_Test_Guide 15 / 17 NB-IoT Module Series Figure 4: Search Throughput in AT Logs BC660K-GL&BC950K-GL_Throughput_Test_Guide 16 / 17 NB-IoT Module Series 5 Appendix References Table 1: Related Documents Document Name [1] Quectel_BC660K-GL&BC950K-GL_AT_Commands_Manual [2] Quectel_BC660K-GL&BC950K-GL_TCP(IP)_Application_Note Table 2: Terms and Abbreviations Abbreviation IoT IP P-GW TCP UDP URC Description Internet of Things Internal Protocol Packet Data Network Gateway Transmission Control Protocol User Datagram Protocol Unsolicited Result Code BC660K-GL&BC950K-GL_Throughput_Test_Guide 17 / 17

Quectel_BC660K-GL&BC950K-GL_Throughput_Test_Guide_V1.1

PDF

311.15 KB

EG06xK&Ex120K&EM060K Series FOTA Application Note LTE-A Module Series Version: 1.0 Date: 2023-05-18 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. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 1 / 19 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. 2023. All rights reserved. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 2 / 19 LTE-A Module Series About the Document Revision History Version 1.0 Date Author 2023-03-21 Monan TIAN 2023-05-18 Monan TIAN Description Creation of the document First official released EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 3 / 19 LTE-A Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 5 1 Introduction .......................................................................................................................................... 6 1.1. Application Modules .................................................................................................................... 6 2 Firmware Upgrade Procedure Over FOTA ........................................................................................ 7 2.1. Get Firmware Package ............................................................................................................... 8 2.2. Put Firmware Package on FTP/HTTP(S) Server........................................................................ 8 2.3. Execute AT Command to Update the Firmware ......................................................................... 8 3 Description of FOTA AT Commands ................................................................................................. 9 3.1. AT Command Introduction .......................................................................................................... 9 3.1.1. Definitions......................................................................................................................... 9 3.1.2. AT Command Syntax ....................................................................................................... 9 3.2. Declaration of AT Command Examples .................................................................................... 10 3.3. AT+QFOTADL Firmware Upgrade via FOTA ......................................................................... 10 3.3.1. AT+QFOTADL= Upgrade Firmware over FTP Server ............................ 10 3.3.2. AT+QFOTADL= Upgrade Firmware over HTTP(S) Server .................. 12 3.3.3. AT+QFOTADL= Upgrade Firmware over Local File System .................. 13 4 Exception Handling and Precautions .............................................................................................. 15 4.1. Exception Handling ................................................................................................................... 15 4.2. Precautions ............................................................................................................................... 15 5 Summary of Error Codes .................................................................................................................. 17 6 Appendix References ........................................................................................................................ 19 EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 4 / 19 LTE-A Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 6 Table 2: Types of AT Commands ................................................................................................................. 9 Table 3: Summary of Codes .................................................................................................... 17 Table 4: Summary of Codes ................................................................................................. 17 Table 5: Summary of Codes ............................................................................................................. 17 Table 6: Related Documents ...................................................................................................................... 19 Table 7: Terms and Abbreviations .............................................................................................................. 19 EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 5 / 19 LTE-A Module Series 1 Introduction Quectel LTE-A EG060K series, EG065K series, EG120K series, EM120K-GL, and EM060K series modules support FOTA (Firmware Upgrade Over-The-Air) function to upgrade the firmware of partitions such as modem, system, boot, sbl, tz and so on. With this function, the firmware can be upgraded to a new version and reverted to the old version. The firmware package only contains the difference between the original firmware version and the target firmware version, with the amount of data transmission greatly reduced and the transmission time greatly shortened. 1.1. Application Modules Table 1: Applicable Modules Module Family EG06xK Ex120K - Module EG060K Series EG065K Series EG120K Series EM120K-GL EM060K Series EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 6 / 19 LTE-A Module Series 2 Firmware Upgrade Procedure Over FOTA The following chart illustrates the firmware upgrade procedure via FOTA when the firmware package is stored on an FTP/HTTP(S) server. 2. Put the package on an FTP/HTTP(S) server. FTP/HTTP(S) server 1. Get a firmware package. LTE/WCDMA (FTP/HTTP(S)) 4. Automatically download the firmware package from the FTP/HTTP(S) server via LTE/WCDMA. Ext. MCU 3. Execute AT+QFOTADL Quectel Module 5. Automatically upgrade the module s firmware. Figure 1: Firmware Upgrade Procedure via FOTA As shown in the above figure, the following steps need to be performed to update the firmware when the firmware package is stored on an FTP/HTTP(S) server: Step 1: Get a firmware package from Quectel. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 7 / 19 LTE-A Module Series Step 2: Put the firmware package on an FTP/HTTP(S) server. Step 3: Execute AT+QFOTADL. Step 4: The module will automatically download the package from the FTP/HTTP(S) server or local file system via LTE/WCDMA. Step 5: The module’s firmware will be automatically upgraded. 2.1. Get Firmware Package Before upgrading, check the original firmware version name with ATI and confirm the target firmware version, and then send the two firmware versions to Quectel or the agent to get a firmware package. 2.2. Put Firmware Package on FTP/HTTP(S) Server Step 1: Please set up an FTP/HTTP(S) server before using FOTA function. (Quectel does not provide such servers.) Step 2: Put the firmware package on the server, and record the storage path. 2.3. Execute AT Command to Update the Firmware After putting the firmware package on the FTP/HTTP(S) server, execute AT+QFOTADL, and then the module will download the firmware package from the FTP/HTTP(S) server over the air and update the firmware automatically. For more details about the AT commands, see Chapter 3. ⚫NOTE In addition to firmware upgrade over the FTP/HTTP(s) server, the module also supports firmware upgrade over the local file system. For more information on upgrade over the local file system, see Chapter 3.3.3. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 8 / 19 LTE-A Module Series 3 Description of FOTA 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 to 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 2: 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. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 9 / 19 LTE-A 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. AT+QFOTADL Firmware Upgrade via FOTA This command enables automatic firmware upgrade via FOTA. After executing the corresponding command, the module will automatically download the firmware package from FTP/HTTP(S) server or local file system. After the package is successfully downloaded, the module will automatically upgrade the firmware and then reboot. AT+QFOTADL Firmware Upgrade via FOTA Test Command AT+QFOTADL=? Response OK Maximum Response Time 300 ms 3.3.1. AT+QFOTADL= Upgrade Firmware over FTP Server If the firmware package is stored on an FTP server, execute AT+QFOTADL= to enable automatic firmware upgrade via FOTA. Then the module will download the package from the FTP server over the air and upgrade the firmware automatically. AT+QFOTADL= Upgrade Firmware over FTP Server Write Command AT+QFOTADL= Response OK +QIND: 'FOTA','FTPSTART' +QIND: 'FOTA','FTPEND', +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ... +QIND: 'FOTA','END', If there is any error: ERROR EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 10 / 19 LTE-A Module Series Maximum Response Time Characteristics 300 ms / Parameter String type. The URL that the firmware package stored on the FTP server. The maximum length is 512 bytes. It should be started with 'ftp://'. For example: 'ftp://:@:/'. String type. The user name for authentication. String type. The password for authentication. String type. The FTP server address. Integer type. The port of the FTP server. Range: 1–65535. Default: 21. String type. The file name on FTP server. Integer type. The FTP error code. 0 Downloaded the firmware package from the FTP server successfully. Others Failed to download the firmware package from the FTP server. See Chapter 5 for details. Integer type. The upgrade progress in percentage. Range: 0–100. Integer type. Error code of upgrading. 0 Upgraded the firmware successfully Others Failed to upgrade the firmware. See Chapter 5 for more details. Example //Upgrade firmware after the firmware package is stored on an FTP server. The FTP server address is 'ftp://test:test@124.74.41.170:21/Jun/update-v12-to-v13.zip'. Execute the following command to enable automatic firmware upgrade via FOTA. The module will start to download the firmware package and upgrade firmware automatically. AT+QFOTADL='ftp://test:test@124.74.41.170:21/Jun/update-v12-to-v13.zip' OK +QIND: 'FOTA','FTPSTART' +QIND: 'FOTA','FTPEND',0 //Finish downloading the firmware package from the FTP server. //The module reboots automatically and the USB port is re-initialized. If the current port is USB port, MCU should close and reopen it. After the module is rebooted, the first URC should be reported within 90 seconds. Otherwise, it means an unknown error occurs. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',20 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //The module automatically restarts to complete the FOTA upgrade. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 11 / 19 LTE-A Module Series 3.3.2. AT+QFOTADL= Upgrade Firmware over HTTP(S) Server If the firmware package is stored on an HTTP(S) server, execute AT+QFOTADL= to enable automatic firmware upgrade via FOTA. Then the module will download the package from the HTTP(S) server over the air and upgrade the firmware automatically. AT+QFOTADL= Upgrade Firmware over HTTP(S) Server Write Command AT+QFOTADL= Response OK +QIND: 'FOTA','HTTPSTART' +QIND: 'FOTA','HTTPEND', +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ... +QIND: 'FOTA','END', Maximum Response Time Characteristics If there is any error: ERROR 300 ms / Parameter String type. The maximum length is 512 bytes. It should be started with 'http(s)://'. For example: 'http(s)://:/'. String type. The IP address or domain name of the HTTP(S) server. Integer type. The port of the HTTP(S) server. Range: 1–65535. Default: 80. String type. The file name on the HTTP(S) server. Integer type. The HTTP/HTTPS error code. 0 Downloaded the firmware package from the HTTP(S) server successfully Others Failed to download the firmware package from the HTTP(S) server. See Chapter 5 for details. Integer type. The upgrade progress in percentage. Range: 0–100. Integer type. Error code of upgrading. 0 Upgraded the firmware successfully Others Failed to upgrade the firmware. See Chapter 5 for more details. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 12 / 19 LTE-A Module Series Example //Upgrade firmware after the firmware package is stored on an HTTP(S) server. The HTTP(S) server address is 'http://www.quectel.com:100/update.zip'. Execute the following command to enable automatic firmware upgrade via FOTA, and then the module starts to download the firmware package and upgrade firmware automatically. AT+QFOTADL='http://www.quectel.com:100/update.zip' OK +QIND: 'FOTA','HTTPSTART' +QIND: 'FOTA','HTTPEND',0 //Finish downloading the firmware package from the HTTP server. //The module reboots automatically and the USB port is re-initialized. If the current port is USB port, MCU should close and reopen it. After the module is rebooted, the first URC should be reported within 90 seconds. Otherwise, it means an unknown error occurs. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',2 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //The module automatically restarts to complete the FOTA upgrade. 3.3.3. AT+QFOTADL= Upgrade Firmware over Local File System If the firmware package has already been stored in the module’s file system, execute AT+QFOTADL= to enable automatic firmware upgrade via FOTA. Then the module will download the firmware package from the local file system and upgrade the firmware automatically. AT+QFOTADL= Upgrade Firmware over Local File System Write Command AT+QFOTADL= Response OK +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ... +QIND: 'FOTA','END', Maximum Response Time Characteristics If there is any error: ERROR 300 ms / EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 13 / 19 LTE-A Module Series Parameter String type. The path where the firmware package stores in the local file system. The maximum length is 90 bytes. It should be started with 'cache/ufs/' in UFS. Integer type. The upgrade progress in percentage. Range: 0–100. Integer type. Error code of upgrading. 0 Upgraded the firmware successfully Others Failed to upgrade the firmware. See Chapter 5 for more details. ⚫NOTE 1. Before using this command, make sure that the firmware package is stored in the module. You can upload the package to the module through AT+QFUPL. For details of AT+QFUPL, see document [1]. 2. The first APN is used for data call during FOTA upgrade by default. If the first APN is occupied by the host for data call, the module cannot use this APN at the same time. Therefore, the module automatically performs data call for FOTA upgrade after the host disconnects the data call with this APN. 3. If Verizon certification uses the first APN to perform data call, it is suggested to use AT command to switch channels for FOTA upgrade. For details, please contact Quectel Technical Support. Example //Upgrade firmware when the firmware package is stored on the local file system. AT+QFOTADL='/cache/ufs/update-v13-to-v12.zip' OK //The module reboots automatically and the USB port is re-initialized. If the current port is USB port, MCU should close and reopen it. After the module is rebooted, the first URC should be reported within 90 seconds. Otherwise, it means an unknown error occurs. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',2 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //The module automatically restart to complete the FOTA upgrade. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 14 / 19 LTE-A Module Series 4 Exception Handling and Precautions 4.1. Exception Handling To improve the upgrade success rate, the module will set the upgrade flag before starting the upgrade. When an error is reported during the upgrade, the module will automatically restart. After the upgrade flag is found, the module will continue to upgrade. If the upgrade fails for five consecutive times, the upgrade is a complete failure, and the module will delete the flag, exit and try to start the module normally. The upgrade interface is as follows: +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',20 +QIND: 'FOTA','END', … //The module restarts automatically … +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',20 +QIND: 'FOTA','UPDATING',30 ... +QIND: 'FOTA','END',0 ⚫NOTE The consecutive upgrade times is only valid when an upgrade error is reported, while there is no limit to the number of upgrades in the event of an abnormal power failure. If an abnormal power failure occurs during module upgrade process, the upgrade can also continue after the module is restarted. After the upgrade is successful, the upgrade mark will also be deleted. 4.2. Precautions 1. After AT+QFOTADL is executed, the host receives URC +QIND: 'FOTA','START' which means that the upgrade begins, and URC +QIND: 'FOTA','END',0 means the upgrade is completed. After the upgrade, the module automatically restarts and enters normal mode. Do not power off the module EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 15 / 19 LTE-A Module Series during the upgrade. 2. If the host does not receive any URC within 4 minutes during the upgrade process, you can restart the module. 3. It is recommended to set up a flag to mark the firmware upgrade task and remove it after the upgrade is completed successfully. ⚫NOTE It is recommended not to power off the module during the FOTA upgrade process. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 16 / 19 LTE-A Module Series 5 Summary of Error Codes This chapter introduces the error codes related to Quectel modules or network. The details about , and are described in the following tables. Table 3: Summary of Codes Numerical 0 601 Character Downloaded the firmware package from the FTP server successfully FTP Unknown error Table 4: Summary of Codes Numerical 0 701 Character Downloaded the firmware package from the HTTP(S) server successfully Failed to download the firmware package from the HTTP(S) server Table 5: Summary of Codes Numerical 0 502 504 505 510 511 Character Upgraded the firmware successfully The upgrade process exits due to some unknown errors or exceptions. The system will retry five times. Incorrect zip format The project or the version of the package does not match The firmware package file does not match the source package file of the module, and needs to be checked if it is wrong. The file system has no enough space for upgrade. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 17 / 19 520–530 540–546 550 LTE-A Module Series Firmware upgrading failed. The module will reboot and retry to upgrade the firmware until the upgrade is successful. The firmware package is too large EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 18 / 19 LTE-A Module Series 6 Appendix References Table 6: Related Documents Document Name [1] Quectel_EG06xK&Ex120K&EM060K_Series_FILE_Application_Note Table 7: Terms and Abbreviations Abbreviation FOTA FTP GPRS GSM HTTP(S) IP LTE MCU TA UFS URC URL USB WCDMA Description Firmware Upgrade Over-The-Air File Transfer Protocol General Packet Radio Service Global System for Mobile Communications Hypertext Transfer Protocol (Secure/over Secure Socket Layer) Internet Protocol (Long-Term Evolution) a 4G mobile communications standard Microcontroller Unit Terminal Adapter User File System Unsolicited Result Code Uniform/Universal Resource Locator Universal Serial Bus Wideband Code Division Multiple Access EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 19 / 19

Quectel_EG06xK&Ex120K&EM060K_Series_FOTA_Application_Note_V1.0

PDF

258.56 KB

EG512R&EM12xR&EM160R Series FOTA Application Note LTE-A Module Series Version: 1.0 Date: 2023-05-18 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. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 1 / 19 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. 2023. All rights reserved. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 2 / 19 LTE-A Module Series About the Document Revision History Version 1.0 Date Author 2023-03-21 Monan TIAN 2023-05-18 Monan TIAN Description Creation of the document First official released EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 3 / 19 LTE-A Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 5 1 Introduction .......................................................................................................................................... 6 1.1. Application Modules .................................................................................................................... 6 2 Firmware Upgrade Procedure Over FOTA ........................................................................................ 7 2.1. Get Firmware Package ............................................................................................................... 8 2.2. Put Firmware Package on FTP/HTTP(S) Server........................................................................ 8 2.3. Execute AT Command to Update the Firmware ......................................................................... 8 3 Description of FOTA AT Commands ................................................................................................. 9 3.1. AT Command Introduction .......................................................................................................... 9 3.1.1. Definitions......................................................................................................................... 9 3.1.2. AT Command Syntax ....................................................................................................... 9 3.2. Declaration of AT Command Examples .................................................................................... 10 3.3. AT+QFOTADL Firmware Upgrade via FOTA ......................................................................... 10 3.3.1. AT+QFOTADL= Upgrade Firmware over FTP Server ............................ 10 3.3.2. AT+QFOTADL= Upgrade Firmware over HTTP(S) Server .................. 12 3.3.3. AT+QFOTADL= Upgrade Firmware over Local File System .................. 13 4 Exception Handling and Precautions .............................................................................................. 15 4.1. Exception Handling ................................................................................................................... 15 4.2. Precautions ............................................................................................................................... 15 5 Summary of Error Codes .................................................................................................................. 17 6 Appendix References ........................................................................................................................ 19 EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 4 / 19 LTE-A Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 6 Table 2: Types of AT Commands ................................................................................................................. 9 Table 3: Summary of Codes .................................................................................................... 17 Table 4: Summary of Codes ................................................................................................. 17 Table 5: Summary of Codes ............................................................................................................. 17 Table 6: Related Documents ...................................................................................................................... 19 Table 7: Terms and Abbreviations .............................................................................................................. 19 EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 5 / 19 LTE-A Module Series 1 Introduction Quectel LTE-A EG512R-EA、EM120R-GL、EM121R-GL and EM160R-GL series modules support FOTA (Firmware Upgrade Over-The-Air) function to upgrade the firmware of partitions such as modem, system, boot, sbl, tz and so on. With this function, the firmware can be upgraded to a new version and reverted to the old version. The firmware package only contains the difference between the original firmware version and the target firmware version, with the amount of data transmission greatly reduced and the transmission time greatly shortened. 1.1. Application Modules Table 1: Applicable Modules Module Family EM12xR - Module EG512R-EA EM120R-GL EM121R-GL EM160R-GL EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 6 / 19 LTE-A Module Series 2 Firmware Upgrade Procedure Over FOTA The following chart illustrates the firmware upgrade procedure via FOTA when the firmware package is stored on an FTP/HTTP(S) server. 2. Put the package on an FTP/HTTP(S) server. FTP/HTTP(S) server 1. Get a firmware package. LTE/WCDMA (FTP/HTTP(S)) 4. Automatically download the firmware package from the FTP/HTTP(S) server via LTE/WCDMA. Ext. MCU 3. Execute AT+QFOTADL Quectel Module 5. Automatically upgrade the module s firmware. Figure 1: Firmware Upgrade Procedure via FOTA As shown in the above figure, the following steps need to be performed to update the firmware when the firmware package is stored on an FTP/HTTP(S) server: EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 7 / 19 LTE-A Module Series Step 1: Get a firmware package from Quectel. Step 2: Put the firmware package on an FTP/HTTP(S) server. Step 3: Execute AT+QFOTADL. Step 4: The module will automatically download the package from the FTP/HTTP(S) server or local file system via LTE/WCDMA. Step 5: The module’s firmware will be automatically upgraded. 2.1. Get Firmware Package Before upgrading, check the original firmware version name with ATI and confirm the target firmware version, and then send the two firmware versions to Quectel or the agent to get a firmware package. 2.2. Put Firmware Package on FTP/HTTP(S) Server Step 1: Please set up an FTP/HTTP(S) server before using FOTA function. (Quectel does not provide such servers.) Step 2: Put the firmware package on the server, and record the storage path. 2.3. Execute AT Command to Update the Firmware After putting the firmware package on the FTP/HTTP(S) server, execute AT+QFOTADL, and then the module will download the firmware package from the FTP/HTTP(S) server over the air and update the firmware automatically. For more details about the AT commands, see Chapter 3. ⚫NOTE In addition to FOTA upgrade over the FTP/HTTP(s) server, the module also supports firmware upgrade over the local file system. For more information on upgrade over the local file system, see Chapter 3.3.3. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 8 / 19 LTE-A Module Series 3 Description of FOTA 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 to 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 2: 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. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 9 / 19 LTE-A 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. AT+QFOTADL Firmware Upgrade via FOTA This command enables automatic firmware upgrade via FOTA. After executing the corresponding command, the module will automatically download the firmware package from FTP/HTTP(S) server or local file system. After the package is successfully downloaded, the module will automatically upgrade the firmware and then reboot. AT+QFOTADL Firmware Upgrade via FOTA Test Command AT+QFOTADL=? Response OK Maximum Response Time 300 ms 3.3.1. AT+QFOTADL= Upgrade Firmware over FTP Server If the firmware package is stored on an FTP server, execute AT+QFOTADL= to enable automatic firmware upgrade via FOTA. Then the module will download the package from the FTP server over the air and upgrade the firmware automatically. AT+QFOTADL= Upgrade Firmware over FTP Server Write Command AT+QFOTADL= Response OK +QIND: 'FOTA','FTPSTART' +QIND: 'FOTA','FTPEND', +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ... +QIND: 'FOTA','END', If there is any error: ERROR EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 10 / 19 LTE-A Module Series Maximum Response Time Characteristics 300 ms / Parameter String type. The URL that the firmware package stored on the FTP server. The maximum length is 512 bytes. It should be started with 'ftp://'. For example: 'ftp://:@:/'. String type. The user name for authentication. String type. The password for authentication. String type. The FTP server address. Integer type. The port of the FTP server. Range: 1–65535. Default: 21. String type. The file name on FTP server. Integer type. The FTP error code. 0 Downloaded the firmware package from the FTP server successfully. Others Failed to download the firmware package from the FTP server. See Chapter 5 for details. Integer type. The upgrade progress in percentage. Range: 0–100. Integer type. Error code of upgrading. 0 Upgraded the firmware successfully Others Failed to upgrade the firmware. See Chapter 5 for more details. Example //Upgrade firmware after the firmware package is stored on an FTP server. The FTP server address is 'ftp://test:test@124.74.41.170:21/Jun/update-v12-to-v13.zip'. Execute the following command to enable automatic firmware upgrade via FOTA. The module will start to download the firmware package and upgrade firmware automatically. AT+QFOTADL='ftp://test:test@124.74.41.170:21/Jun/update-v12-to-v13.zip' OK +QIND: 'FOTA','FTPSTART' +QIND: 'FOTA','FTPEND',0 //Finish downloading the firmware package from the FTP server. //The module reboots automatically and the USB port is re-initialized. If the current port is USB port, MCU should close and reopen it. After the module is rebooted, the first URC should be reported within 90 seconds. Otherwise, it means an unknown error occurs. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',20 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //The module automatically restarts to complete the FOTA upgrade. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 11 / 19 LTE-A Module Series 3.3.2. AT+QFOTADL= Upgrade Firmware over HTTP(S) Server If the firmware package is stored on an HTTP(S) server, execute AT+QFOTADL= to enable automatic firmware upgrade via FOTA. Then the module will download the package from the HTTP(S) server over the air and upgrade the firmware automatically. AT+QFOTADL= Upgrade Firmware over HTTP(S) Server Write Command AT+QFOTADL= Response OK +QIND: 'FOTA','HTTPSTART' +QIND: 'FOTA','HTTPEND', +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ... +QIND: 'FOTA','END', Maximum Response Time Characteristics If there is any error: ERROR 300 ms / Parameter String type. The maximum length is 512 bytes. It should be started with 'http(s)://'. For example: 'http(s)://:/'. String type. The IP address or domain name of the HTTP(S) server. Integer type. The port of the HTTP(S) server. Range: 1–65535. Default: 80. String type. The file name on the HTTP(S) server. Integer type. The HTTP/HTTPS error code. 0 Downloaded the firmware package from the HTTP(S) server successfully Others Failed to download the firmware package from the HTTP(S) server. See Chapter 5 for details. Integer type. The upgrade progress in percentage. Range: 0–100. Integer type. Error code of upgrading. 0 Upgraded the firmware successfully Others Failed to upgrade the firmware. See Chapter 5 for more details. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 12 / 19 LTE-A Module Series Example //Upgrade firmware after the firmware package is stored on an HTTP(S) server. The HTTP(S) server address is 'http://www.quectel.com:100/update.zip'. Execute the following command to enable automatic firmware upgrade via FOTA, and then the module starts to download the firmware package and upgrade firmware automatically. AT+QFOTADL='http://www.quectel.com:100/update.zip' OK +QIND: 'FOTA','HTTPSTART' +QIND: 'FOTA','HTTPEND',0 //Finish downloading the firmware package from the HTTP server. //The module reboots automatically and the USB port is re-initialized. If the current port is USB port, MCU should close and reopen it. After the module is rebooted, the first URC should be reported within 90 seconds. Otherwise, it means an unknown error occurs. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',2 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //The module automatically restarts to complete the FOTA upgrade. 3.3.3. AT+QFOTADL= Upgrade Firmware over Local File System If the firmware package has already been stored in the module’s file system, execute AT+QFOTADL= to enable automatic firmware upgrade via FOTA. Then the module will download the firmware package from the local file system and upgrade the firmware automatically. AT+QFOTADL= Upgrade Firmware over Local File System Write Command AT+QFOTADL= Response OK +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ... +QIND: 'FOTA','END', Maximum Response Time Characteristics If there is any error: ERROR 300 ms / EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 13 / 19 LTE-A Module Series Parameter String type. The path where the firmware package stores in the local file system. The maximum length is 512 bytes. It should be started with 'cache/ufs/' in UFS. Integer type. The upgrade progress in percentage. Range: 0–100. Integer type. Error code of upgrading. 0 Upgraded the firmware successfully Others Failed to upgrade the firmware. See Chapter 5 for more details. ⚫NOTE 1. Before using this command, make sure that the firmware package is stored in the module. You can upload the package to the module through AT+QFUPL. For details of AT+QFUPL, see document [1]. 2. The first APN is used for data call during FOTA upgrade by default. If the first APN is occupied by the host for data call, the module cannot use this APN at the same time. Therefore, the module automatically performs data call for FOTA upgrade after the host disconnects the data call with this APN. 3. If Verizon certification uses the first APN to perform data call, it is suggested to use AT command to switch channels for FOTA upgrade. For details, please contact Quectel Technical Support. Example //Upgrade firmware when the firmware package is stored on the local file system. AT+QFOTADL='/cache/ufs/update-v13-to-v12.zip' OK //The module reboots automatically and the USB port is re-initialized. If the current port is USB port, MCU should close and reopen it. After the module is rebooted, the first URC should be reported within 90 seconds. Otherwise, it means an unknown error occurs. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',2 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //The module automatically restart to complete the FOTA upgrade. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 14 / 19 LTE-A Module Series 4 Exception Handling and Precautions 4.1. Exception Handling To improve the upgrade success rate, the module will set the upgrade flag before starting the upgrade. When an error is reported during the upgrade, the module will automatically restart. After the upgrade flag is found, the module will continue to upgrade. If the upgrade fails for five consecutive times, the upgrade is a complete failure, and the module will delete the flag, exit and try to start the module normally. The upgrade interface is as follows: +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',20 +QIND: 'FOTA','END', … //The module restarts automatically … +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',20 +QIND: 'FOTA','UPDATING',30 ... +QIND: 'FOTA','END',0 ⚫NOTE The consecutive upgrade times is only valid when an upgrade error is reported, while there is no limit to the number of upgrades in the event of an abnormal power failure. If an abnormal power failure occurs during module upgrade process, the upgrade can also continue after the module is restarted. After the upgrade is successful, the upgrade mark will also be deleted. 4.2. Precautions 1. After AT+QFOTADL is executed, the host receives URC +QIND: 'FOTA','START' which means that the upgrade begins, and URC +QIND: 'FOTA','END',0 means the upgrade is completed. After the upgrade, the module automatically restarts and enters normal mode. Do not power off the module EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 15 / 19 LTE-A Module Series during the upgrade. 2. If the host does not receive any URC within 4 minutes during the upgrade process, you can restart the module. 3. It is recommended to set up a flag to mark the firmware upgrade task and remove it after the upgrade is completed successfully. ⚫NOTE It is recommended not to power off the module during the FOTA upgrade process. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 16 / 19 LTE-A Module Series 5 Summary of Error Codes This chapter introduces the error codes related to Quectel modules or network. The details about , and are described in the following tables. Table 3: Summary of Codes Numerical 0 601 Character Downloaded the firmware package from the FTP server successfully FTP Unknown error Table 4: Summary of Codes Numerical 0 701 Character Downloaded the firmware package from the HTTP(S) server successfully Failed to download the firmware package from the HTTP(S) server Table 5: Summary of Codes Numerical 0 502 504 505 510 511 Character Upgraded the firmware successfully The upgrade process exits due to some unknown errors or exceptions. The system will retry five times. Incorrect zip format The project or the version of the package does not match The firmware package file does not match the source package file of the module, and needs to be checked if it is wrong. The file system has no enough space for upgrade. EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 17 / 19 520–530 540–546 550 LTE-A Module Series Firmware upgrading failed. The module will reboot and retry to upgrade the firmware until the upgrade is successful. The firmware package is too large EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 18 / 19 LTE-A Module Series 6 Appendix References Table 6: Related Documents Document Name [1] Quectel_EG512R&EM12xR&EM160R_Series_FILE_Application_Note Table 7: Terms and Abbreviations Abbreviation FOTA FTP GPRS GSM HTTP(S) IP LTE MCU TA UFS URC URL USB WCDMA Description Firmware Upgrade Over-The-Air File Transfer Protocol General Packet Radio Service Global System for Mobile Communications Hypertext Transfer Protocol (Secure/over Secure Socket Layer) Internet Protocol (Long-Term Evolution) a 4G mobile communications standard Microcontroller Unit Terminal Adapter User File System Unsolicited Result Code Uniform/Universal Resource Locator Universal Serial Bus Wideband Code Division Multiple Access EG06xK&Ex120K&EM060K_Series_FOTA_Applicaton_Note 19 / 19

Quectel_EG512R&EM12xR&EM160R_Series_FOTA_Application_Note_V1.0

PDF

258.83 KB

EM12&EG12&EG18 Series FOTA Application Note LTE-A Module Series Version: 1.0 Date: 2023-05-18 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. EM12&EG12&EG18_Series_FOTA_Applicaton_Note 1 / 19 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. 2023. All rights reserved. EM12&EG12&EG18_Series_FOTA_Applicaton_Note 2 / 19 LTE-A Module Series About the Document Revision History Version 1.0 Date Author 2023-03-21 Monan TIAN 2023-05-18 Monan TIAN Description Creation of the document First official released EM12&EG12&EG18_Series_FOTA_Applicaton_Note 3 / 19 LTE-A Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 5 1 Introduction .......................................................................................................................................... 6 2 Firmware Upgrade Procedure Over FOTA ........................................................................................ 7 2.1. Get Firmware Package ............................................................................................................... 8 2.2. Put Firmware Package on FTP/HTTP(S) Server........................................................................ 8 2.3. Execute AT Command to Update the Firmware ......................................................................... 8 3 Description of FOTA AT Commands ................................................................................................. 9 3.1. AT Command Introduction .......................................................................................................... 9 3.1.1. Definitions......................................................................................................................... 9 3.1.2. AT Command Syntax ....................................................................................................... 9 3.2. Declaration of AT Command Examples .................................................................................... 10 3.3. AT+QFOTADL Firmware Upgrade via FOTA ......................................................................... 10 3.3.1. AT+QFOTADL= Upgrade Firmware over FTP Server ............................ 10 3.3.2. AT+QFOTADL= Upgrade Firmware over HTTP(S) Server .................. 12 3.3.3. AT+QFOTADL= Upgrade Firmware over Local File System .................. 13 4 Exception Handling and Precautions .............................................................................................. 15 4.1. Exception Handling ................................................................................................................... 15 4.2. Precautions ............................................................................................................................... 15 5 Summary of Error Codes .................................................................................................................. 17 6 Appendix References ........................................................................................................................ 19 EM12&EG12&EG18_Series_FOTA_Applicaton_Note 4 / 19 LTE-A Module Series Table Index Table 1: Types of AT Commands ................................................................................................................. 9 Table 2: Summary of Codes .................................................................................................... 17 Table 3: Summary of Codes ................................................................................................. 17 Table 4: Summary of Codes ............................................................................................................. 17 Table 5: Related Documents ...................................................................................................................... 19 Table 6: Terms and Abbreviations .............................................................................................................. 19 EM12&EG12&EG18_Series_FOTA_Applicaton_Note 5 / 19 LTE-A Module Series 1 Introduction Quectel LTE-A EM12-G, EG12 and EG18 series modules support FOTA (Firmware Upgrade Over-The-Air) function to upgrade the firmware of partitions such as modem, system and boot. With this function, the firmware can be upgraded to a new version and reverted to the old version. The firmware package only contains the difference between the original firmware version and the target firmware version, with the amount of data transmission greatly reduced and the transmission time greatly shortened. EM12&EG12&EG18_Series_FOTA_Applicaton_Note 6 / 19 LTE-A Module Series 2 Firmware Upgrade Procedure Over FOTA The following chart illustrates the firmware upgrade procedure via FOTA when the firmware package is stored on an FTP/HTTP(S) server. 2. Put the package on an FTP/HTTP(S) server. FTP/HTTP(S) server 1. Get a firmware package. LTE/WCDMA (FTP/HTTP(S)) 4. Automatically download the firmware package from the FTP/HTTP(S) server via LTE/WCDMA. Ext. MCU 3. Execute AT+QFOTADL Quectel Module 5. Automatically upgrade the module s firmware. Figure 1: Firmware Upgrade Procedure via FOTA As shown in the above figure, the following steps need to be performed to update the firmware when the firmware package is stored on an FTP/HTTP(S) server: Step 1: Get a firmware package from Quectel. EM12&EG12&EG18_Series_FOTA_Applicaton_Note 7 / 19 LTE-A Module Series Step 2: Put the firmware package on an FTP/HTTP(S) server. Step 3: Execute AT+QFOTADL. Step 4: The module will automatically download the package from the FTP/HTTP(S) server or local file system via LTE/WCDMA. Step 5: The module’s firmware will be automatically upgraded. 2.1. Get Firmware Package Before upgrading, check the original firmware version name with ATI and confirm the target firmware version, and then send the two firmware versions to Quectel or the agent to get a firmware package. 2.2. Put Firmware Package on FTP/HTTP(S) Server Step 1: Please set up an FTP/HTTP(S) server before using FOTA function. (Quectel does not provide such servers.) Step 2: Put the firmware package on the server, and record the storage path. 2.3. Execute AT Command to Update the Firmware After putting the firmware package on the FTP/HTTP(S) server, execute AT+QFOTADL, and then the module will download the firmware package from the FTP/HTTP(S) server over the air and update the firmware automatically. For more details about the AT commands, see Chapter 3. ⚫NOTE In addition to firmware upgrade over the FTP/HTTP(s) server, the module also supports firmware upgrade over the local file system. For more information on upgrade over the local file system, see Chapter 3.3.3. EM12&EG12&EG18_Series_FOTA_Applicaton_Note 8 / 19 LTE-A Module Series 3 Description of FOTA 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 to 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 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. EM12&EG12&EG18_Series_FOTA_Applicaton_Note 9 / 19 LTE-A 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. AT+QFOTADL Firmware Upgrade via FOTA This command enables automatic firmware upgrade via FOTA. After executing the corresponding command, the module will automatically download the firmware package from FTP/HTTP(S) server or local file system. After the package is successfully downloaded, the module will automatically upgrade the firmware and then reboot. AT+QFOTADL Firmware Upgrade via FOTA Test Command AT+QFOTADL=? Response OK Maximum Response Time 300 ms 3.3.1. AT+QFOTADL= Upgrade Firmware over FTP Server If the firmware package is stored on an FTP server, execute AT+QFOTADL= to enable automatic firmware upgrade via FOTA. Then the module will download the package from the FTP server over the air and upgrade the firmware automatically. AT+QFOTADL= Upgrade Firmware over FTP Server Write Command AT+QFOTADL= Response OK +QIND: 'FOTA','FTPSTART' +QIND: 'FOTA','FTPEND', +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ... +QIND: 'FOTA','END', If there is any error: ERROR EM12&EG12&EG18_Series_FOTA_Applicaton_Note 10 / 19 LTE-A Module Series Maximum Response Time Characteristics 300 ms / Parameter String type. The URL that the firmware package stored on the FTP server. It should be started with 'ftp://'. The maximum length is 512 bytes. For example: 'ftp://:@:/'. String type. The user name for authentication. String type. The password for authentication. String type. The FTP server address. Integer type. The port of the FTP server. Range: 1–65535. Default: 21. String type. The file name on FTP server. Integer type. The FTP error code. 0 Downloaded the firmware package from the FTP server successfully. Others Failed to download the firmware package from the FTP server. See Chapter 5 for details. Integer type. The upgrade progress in percentage. Range: 0–100. Integer type. Error code of upgrading. 0 Upgraded the firmware successfully Others Failed to upgrade the firmware. See Chapter 5 for more details. Example //Upgrade firmware after the firmware package is stored on an FTP server. The FTP server address is 'ftp://test:test@124.74.41.170:21/Jun/update-v12-to-v13.zip'. Execute the following command to enable automatic firmware upgrade via FOTA. The module will start to download the firmware package and upgrade firmware automatically. AT+QFOTADL='ftp://test:test@124.74.41.170:21/Jun/update-v12-to-v13.zip' OK +QIND: 'FOTA','FTPSTART' +QIND: 'FOTA','FTPEND',0 //Finish downloading the firmware package from the FTP server. //The module reboots automatically and the USB port is re-initialized. If the current port is USB port, MCU should close and reopen it. After the module is rebooted, the first URC should be reported within 90 seconds. Otherwise, it means an unknown error occurs. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',20 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //The module automatically restarts to complete the FOTA upgrade. EM12&EG12&EG18_Series_FOTA_Applicaton_Note 11 / 19 LTE-A Module Series 3.3.2. AT+QFOTADL= Upgrade Firmware over HTTP(S) Server If the firmware package is stored on an HTTP(S) server, execute AT+QFOTADL= to enable automatic firmware upgrade via FOTA. Then the module will download the package from the HTTP(S) server over the air and upgrade the firmware automatically. AT+QFOTADL= Upgrade Firmware over HTTP(S) Server Write Command AT+QFOTADL= Response OK +QIND: 'FOTA','HTTPSTART' +QIND: 'FOTA','HTTPEND', +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ... +QIND: 'FOTA','END', Maximum Response Time Characteristics If there is any error: ERROR 300 ms / Parameter String type. The maximum length is 512 bytes. It should be started with 'http(s)://'. For example: 'http(s)://:/'. String type. The IP address or domain name of the HTTP(S) server. Integer type. The port of the HTTP(S) server. Range: 1–65535. Default: 80. String type. The file name on the HTTP(S) server. Integer type. The HTTP(S) error code. 0 Downloaded the firmware package from the HTTP(S) server successfully Others Failed to download the firmware package from the HTTP(S) server. See Chapter 5 for details. Integer type. The upgrade progress in percentage. Range: 0–100. Integer type. Error code of upgrading. 0 Upgraded the firmware successfully Others Failed to upgrade the firmware. See Chapter 5 for more details. EM12&EG12&EG18_Series_FOTA_Applicaton_Note 12 / 19 LTE-A Module Series Example //Upgrade firmware after the firmware package is stored on an HTTP(S) server. The HTTP(S) server address is 'http://www.quectel.com:100/update.zip'. Execute the following command to enable automatic firmware upgrade via FOTA, and then the module starts to download the firmware package and upgrade firmware automatically. AT+QFOTADL='http://www.quectel.com:100/update.zip' OK +QIND: 'FOTA','HTTPSTART' +QIND: 'FOTA','HTTPEND',0 //Finish downloading the firmware package from the HTTP server. //The module reboots automatically and the USB port is re-initialized. If the current port is USB port, MCU should close and reopen it. After the module is rebooted, the first URC should be reported within 90 seconds. Otherwise, it means an unknown error occurs. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',2 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //The module automatically restarts to complete the FOTA upgrade. 3.3.3. AT+QFOTADL= Upgrade Firmware over Local File System If the firmware package has already been stored in the module’s file system, execute AT+QFOTADL= to enable automatic firmware upgrade via FOTA. Then the module will download the firmware package from the local file system and upgrade the firmware automatically. AT+QFOTADL= Upgrade Firmware over Local File System Write Command AT+QFOTADL= Response OK +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ... +QIND: 'FOTA','END', Maximum Response Time Characteristics If there is any error: ERROR 300 ms / EM12&EG12&EG18_Series_FOTA_Applicaton_Note 13 / 19 LTE-A Module Series Parameter String type. The path where the firmware package stores in the local file system. The maximum length is 512 bytes. It should be started with 'cache/ufs/' in UFS. Integer type. The upgrade progress in percentage. Range: 0–100. Integer type. Error code of upgrading. 0 Upgraded the firmware successfully Others Failed to upgrade the firmware. See Chapter 5 for more details. ⚫NOTE 1. Before using this command, make sure that the firmware package is stored in the module. You can upload the package to the module through AT+QFUPL. For details of AT+QFUPL, see document [1]. 2. The first APN is used for data call during FOTA upgrade by default. If the first APN is occupied by the host for data call, the module cannot use this APN at the same time. Therefore, the module automatically performs data call for FOTA upgrade after the host disconnects the data call with this APN. 3. If Verizon certification uses the first APN to perform data call, it is suggested to use AT command to switch channels for FOTA upgrade. For details, please contact Quectel Technical Support. Example //Upgrade firmware when the firmware package is stored on the local file system. AT+QFOTADL='/cache/ufs/update-v13-to-v12.zip' OK //The module reboots automatically and the USB port is re-initialized. If the current port is USB port, MCU should close and reopen it. After the module is rebooted, the first URC should be reported within 90 seconds. Otherwise, it means an unknown error occurs. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',2 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //The module automatically restart to complete the FOTA upgrade. EM12&EG12&EG18_Series_FOTA_Applicaton_Note 14 / 19 LTE-A Module Series 4 Exception Handling and Precautions 4.1. Exception Handling To improve the upgrade success rate, the module will set the upgrade flag before starting the upgrade. When an error is reported during the upgrade, the module will automatically restart. After the upgrade flag is found, the upgrade will continue to upgrade. If the upgrade fails for five consecutive times, the upgrade is a complete failure, and the module will delete the flag, exit and try to start the module normally. The upgrade interface is as follows: +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',20 +QIND: 'FOTA','END', … //The module restarts automatically … +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',20 +QIND: 'FOTA','UPDATING',30 ... +QIND: 'FOTA','END',0 ⚫NOTE The consecutive upgrade times is only valid when an upgrade error is reported, while there is no limit to the number of upgrades in the event of an abnormal power failure. If an abnormal power failure occurs during module upgrade process, the upgrade can also continue after the module is restarted. After the upgrade is successful, the upgrade flag will also be deleted. 4.2. Precautions 1. After AT+QFOTADL is executed, the host receives URC +QIND: 'FOTA','START' which means that the upgrade begins, and URC +QIND: 'FOTA','END',0 means the upgrade is completed. After the upgrade, the module automatically restarts and enters normal mode. Do not power off the module EM12&EG12&EG18_Series_FOTA_Applicaton_Note 15 / 19 LTE-A Module Series during the upgrade. 2. If the host does not receive any URC within 4 minutes during the upgrade process, you can restart the module. 3. It is recommended to set up a flag to mark the firmware upgrade task and remove it after the upgrade is completed successfully. ⚫NOTE It is recommended not to power off the module during the FOTA upgrade process. EM12&EG12&EG18_Series_FOTA_Applicaton_Note 16 / 19 LTE-A Module Series 5 Summary of Error Codes This chapter introduces the error codes related to Quectel modules or network. The details about , and are described in the following tables. Table 2: Summary of Codes Numerical 0 601 Character Downloaded the firmware package from the FTP server successfully FTP Unknown error Table 3: Summary of Codes Numerical 0 701 Character Downloaded the firmware package from the HTTP(S) server successfully Failed to download the firmware package from the HTTP(S) server Table 4: Summary of Codes Numerical 0 502 504 505 510 511 Character Upgraded the firmware successfully The upgrade process exits due to some unknown errors or exceptions. The system will retry five times. Incorrect zip format The project or the version of the package does not match The firmware package file does not match the source package file of the module, and needs to be checked if it is wrong. The file system has no enough space for upgrade. EM12&EG12&EG18_Series_FOTA_Applicaton_Note 17 / 19 520–530 540–546 550 LTE-A Module Series Firmware upgrading failed. The module will reboot and retry to upgrade the firmware until the upgrade is successful. The firmware package is too large EM12&EG12&EG18_Series_FOTA_Applicaton_Note 18 / 19 LTE-A Module Series 6 Appendix References Table 5: Related Documents Document Name [1] Quectel_EM12&EG12&EG18_Series_FILE_Application_Note Table 6: Terms and Abbreviations Abbreviation FOTA FTP GPRS GSM HTTP(S) IP LTE MCU TA UFS URC URL USB WCDMA Description Firmware Upgrade Over-The-Air File Transfer Protocol General Packet Radio Service Global System for Mobile Communications Hypertext Transfer Protocol (Secure/over Secure Socket Layer) Internet Protocol (Long-Term Evolution) a 4G mobile communications standard Microcontroller Unit Terminal Adapter User File System Unsolicited Result Code Uniform/Universal Resource Locator Universal Serial Bus Wideband Code Division Multiple Access EM12&EG12&EG18_Series_FOTA_Applicaton_Note 19 / 19

Quectel_EM12&EG12&EG18_Series_FOTA_Application_Note_V1.0

PDF

256.22 KB

EG06xK&Ex120K&EM060K Series LwM2M Application Note LTE-A Module Series Version: 1.0 Date: 2023-05-23 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. EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 1 / 24 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. 2023. All rights reserved. EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 2 / 24 LTE-A Module Series About the Document Revision History Version Date - 2021-12-16 1.0 2023-05-23 Author Jacque YI Jacque YI/ Noah DENG Description Creation of the document First official release EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 3 / 24 LTE-A Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 1.1. Applicable Modules .................................................................................................................... 6 2 LwM2M 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+QLWCFG Configure Optional Parameters of LwM2M........................................... 8 2.3.2. AT+QLWREG Send a Register Request to the LwM2M Server ................................ 14 2.3.3. AT+QLWUPDATE Send an Update Request to the LwM2M Server ......................... 14 2.3.4. AT+QLWDEREG Send a Deregister Request to the LwM2M Server........................ 15 3 LwM2M Related URCs ...................................................................................................................... 16 3.1. +QLWURC: 'pdp active' PDP Activation Result Indication................................................... 16 3.2. +QLWURC: 'initial' Initialization Result Indication ................................................................ 16 3.3. +QLWURC: 'dtls' DTLS Handshake Result Indication......................................................... 17 3.4. +QLWURC: 'dns' DNS Resolution Result Indication ........................................................... 17 3.5. +QLWURC: 'bootstraping' Bootstrap Working Indication..................................................... 18 3.6. +QLWURC: 'bootstrap' Bootstrap Working Result Indication .............................................. 18 3.7. +QLWURC: 'registering' Registration Start Indication.......................................................... 19 3.8. +QLWURC: 'ready' Registration Result Indication............................................................... 19 3.9. +QLWURC: 'update' Update Result Indication .................................................................... 19 3.10. +QLWURC: 'deregister' Deregistration Result Indication .................................................... 20 4 Examples ........................................................................................................................................... 21 4.1. Login to the Verizon LwM2M Test Server ................................................................................ 21 4.2. Login to the Verizon LwM2M Test Server by Test Mode ......................................................... 22 5 Appendix References ....................................................................................................................... 23 EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 4 / 24 LTE-A Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 6 Table 2: Types of AT Commands ................................................................................................................. 7 Table 3: Related Document........................................................................................................................ 23 Table 4: Terms and Abbreviations .............................................................................................................. 23 EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 5 / 24 LTE-A Module Series 1 Introduction OMA Lightweight M2M (LwM2M) is a device management protocol designed for sensor networks and the demands of a machine-to-machine (M2M) environment. The LwM2M protocol, designed for remote management of M2M devices and related service enablement, features a modern architectural design based on REST, defines an extensible resource and data model and builds on an efficient secure data transfer standard called the Constrained Application Protocol (CoAP). This document mainly introduces how to use the LwM2M feature with Quectel EG06xK, Ex120K and EM060K series modules through AT commands. 1.1. Applicable Modules Table 1: Applicable Modules Module Family EG06xK Ex120K - Module EG065K Series EG060K Series EM120K-GL EG120K Series EM060K Series EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 6 / 24 LTE-A Module Series 2 LwM2M 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 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 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. EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 7 / 24 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 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+QLWCFG Configure Optional Parameters of LwM2M This command configures optional parameters of LwM2M. AT+QLWCFG Configure Optional Parameters of LwM2M Test Command AT+QLWCFG=? Response +QLWCFG: 'security',(range of supported s),(range of supported s),,(list of supported s),(list of supported s),, +QLWCFG: 'server',(range of supported s),(range of supported s),(range of supported s),(range of supported s),(range of supported s),(list of supports s),(list of supported s) +QLWCFG: 'epname/mode',(list of supported s) +QLWCFG: 'urc',(list of supported s) +QLWCFG: 'lwm2m_enable',(range of supported s),(list of supported s) +QLWCFG: 'hostdevice',,,,,,, +QLWCFG: 'reset' +QLWCFG: 'nettype',(range of supported s) +QLWCFG: 'testmode', OK Write Command Response Query/Set the resources of If the optional parameters are omitted, query the current setting: LwM2M security object. +QLWCFG: 'security',,,,<boo AT+QLWCFG='security'[,, erID>[,,,< bootstrap>,[,< OK EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 8 / 24 LTE-A Module Series pskID>,]]] If only is specified and all the other optional parameters are omitted, delete the resources of LwM2M security object of the specified : OK If all optional parameters are specified, set the resources of LwM2M security object: OK If there is any error: ERROR Write Command Response Query/Set the resources of If the optional parameters are omitted, query the current setting: LwM2M server object. +QLWCFG: 'server',,,,<pe AT+QLWCFG='server'[,,,, ID>,[,[, [,[,[,]]]]]] If only is specified and all other optional parameters are omitted, delete the LwM2M server properties of the specified : OK If all optional parameters are specified, set the LwM2M server properties: OK If there is any error: ERROR Write Command Response Query/Set mode of endpoint If the optional parameter is omitted, query the current setting: name. +QLWCFG: 'epname/mode', AT+QLWCFG='epname/mode'[ ,] OK If the optional parameter is specified, set the mode of endpoint name: OK Write Command Query/Set LwM2M URC If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 9 / 24 LTE-A Module Series enablement. AT+QLWCFG='urc'[,] +QLWCFG: 'urc', OK If the optional parameter is specified, set whether to enable URC report: OK If there is any error: ERROR Write Command Response Query/Set the startup mode of If the optional parameters are omitted, query all the operator IDs LwM2M client for one or all that enable LwM2M client to auto-start after the module is booted operators. +QLWCFG: 'lwm2m_enable', AT+QLWCFG='lwm2m_enable' [+QLWCFG: 'lwm2m_enable',] [,[,] […] ] OK If is omitted, query whether the LwM2M client under the specified operator network will auto-start after the module is booted: +QLWCFG: 'lwm2m_enable', OK If the optional parameters are specified, set the startup mode of LwM2M client for one or all operators: OK If there is any error: ERROR Write Command Response Query/Set host device If the network is not Verizon and the optional parameters are information. omitted, query the current host device information: AT+QLWCFG='hostdevice'[,<d +QLWCFG: 'hostdevice',,,[,[,, del>[,[,[,[,]]]]]]]] If the network is Verizon and the optional parameters are omitted, query the current host device information under Verizon network: +QLWCFG: 'hostdevice',,,,,,, EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 10 / 24 LTE-A Module Series OK If the network is not Verizon, , , and are omitted and other optional parameters are specified, set host device information: OK If the network is Verizon and all optional parameters are specified, set host device information: OK If there is any error: ERROR Write Command Response Erase LwM2M client running OK record. Or AT+QLWCFG='reset' ERROR Write Command Response Query/Set the network type of If the optional parameter is omitted, query the current setting: LwM2M client. +QLWCFG: 'nettype', AT+QLWCFG='nettype'[,] OK If the optional parameter is specified, set the network type: OK Write Command Set the test mode. AT+QLWCFG='testmode'[,] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QLWCFG: 'testmode', OK If the optional parameter is specified, set the test mode: OK Maximum Response Time Characteristics If there is any error: ERROR 150 ms The commands take effect immediately. EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 11 / 24 LTE-A Module Series The configurations are saved automatically except . Parameter Integer type. Server type. 0 Bootstrap server 1 DM server 2 Diagnostics server 3 Repository server Integer type. Short server ID. Custom parameter. Range: 1–65534. 100 Bootstrap server under Verizon network 101 Diagnostics server under Verizon network 102 DM server under Verizon network 1000 Repository server under Verizon network Others Other specified servers String type. Server address. The format is 'address:port', for example, 'coaps://boot.lwm2m.vzwdm.com:5684'. Integer type. Whether it is necessary to connect Bootstrap server. 0 No (Only valid when ≠0) 1 Yes (Only valid when =0) Integer type. Encryption method. 0 Pre-shared key mode 3 Unencrypted mode String type. Pre-shared key ID. Only valid when =0. String type in hexadecimal. Pre-shared key. Only valid when =0. Integer type. The lifetime of receiving heartbeat package by server. Range: 1–86400. Default: 60. Unit: second. Integer type. The minimum response period. Range: 1–86400. Default: 1. Unit: second. Integer type. The maximum response period. Range: 1–86400. Default: 60. Unit: second. Integer type. The interval to the next connection after disconnecting from the LwM2M server. Range: 1–86400. Default: 86400. Unit: second. Integer type. Whether to save the server information. 0 Not save 1 Save String type. The binding mode used to connect to the LwM2M server. 'U' UDP 'UQ' UDP with Queue mode 'S' SMS 'SQ' SMS with Queue mode EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 12 / 24 LTE-A Module Series 'US' UDP and SMS 'UQS' UDP and SMS with Queue mode Integer type. The format of endpoint name. 3 The endpoint name format: urn:imei:xxxxx 6 The endpoint name format: urn:imei-msisdn:xxxxx-xxx 7 The endpoint name format: urn:imei-imsi:xxxxx-xxx 8 China Mobile DM endpoint name Integer type. Whether to enable LwM2M URC report. 0 Disable LwM2M URC report 1 Enable LwM2M URC report Integer type. Operator type. 0 all operators 1 other operators or no SIM card is inserted 2 Verizon 3 AT&T 4 CMCC 5 DoCoMo 6 Sprint 7 T-Mobile 8 Rogers 9 Bell 10 Telus 11 SoftBank 12 KDDI 13 Rakuten 14 Telstra 15 Deutsche Telekom 16 SK Telecom 17 Korea Telecom 18 LGU+ Integer type. For the specified operator, whether the LwM2M function will auto-start. 0 LwM2M will not auto-start when the module is booted. 1 LwM2M will auto-start when the module is booted String type. The unique identification code of host device. String type. The manufacturer name of host device. String type. The model of host device. String type. The software version number of host device. String type. The firmware version number of host device. String type. The hardware version number of host device. Integer type. The seconds from January 1,1970 00:00:00 to the last firmware or software update time. If no timestamp is available, 0 is returned. Integer type. The network type. EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 13 / 24 LTE-A Module Series 0 Others 1 Verizon 2 AT&T String type. The bootstrap server URL. If is '0', it indicates to clear all the configured URLs and use the default commercial server URL. 2.3.2. AT+QLWREG Send a Register Request to the LwM2M Server This command sends a register request to the LwM2M Server. AT+QLWREG Send a Register Request to the LwM2M Server Test Command AT+QLWREG=? Execution Command AT+QLWREG Response OK Response OK Or ERROR Maximum Response Time 150 ms Characteristics / 2.3.3. AT+QLWUPDATE Send an Update Request to the LwM2M Server This command sends an update request to the LwM2M Server. AT+QLWUPDATE Send an Update Request to the LwM2M Server Test Command AT+QLWUPDATE=? Write Command AT+QLWUPDATE= Response OK Response OK Or ERROR Maximum Response Time 150 ms Characteristics The command takes effect immediately. The configuration is not saved. EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 14 / 24 Parameter LTE-A Module Series Integer type. Server ID. The Bootstrap server is not included. 0 All servers 101 Diagnostics server under Verizon network 102 DM server under Verizon network 1000 Repository server under Verizon network Others Other specified servers 2.3.4. AT+QLWDEREG Send a Deregister Request to the LwM2M Server This command sends a deregister request to the LwM2M Server. AT+QLWDEREG Send a Deregister Request to the LwM2M Server Test Command AT+QLWDEREG=? Execution Command AT+QLWDEREG Response OK Response OK Or ERROR Maximum Response Time 150 ms Characteristics / EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 15 / 24 LTE-A Module Series 3 LwM2M Related URCs This chapter describes LwM2M-related URCs. 3.1. +QLWURC: 'pdp active' PDP Activation Result Indication This URC reports the PDP activation result. Users should use AT+CGACT to activate PDP first before sending a registration request to the LwM2M server. For more information on AT+CGACT, please refer to document [1]. +QLWURC: 'pdp active' PDP Activation Result Indication +QLWURC: 'pdp active',, This URC reports the PDP activation result. Parameter String type. The PDP activation result. 'successfully' 'failed' String type. APN name. 3.2. +QLWURC: 'initial' Initialization Result Indication This URC reports the initialization result of the connection between client and the LwM2M server. +QLWURC: 'initial' Initialization Result Indication +QLWURC: 'initial',, This URC reports the connection initialization result. Parameter String type. The initialization result. 'successfully' 'failed' EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 16 / 24 LTE-A Module Series Integer type. Server ID. 100 Bootstrap server under Verizon network 101 Diagnostics server under Verizon network 102 DM server under Verizon network 1000 Repository server under Verizon network Others Other specified servers 3.3. +QLWURC: 'dtls' DTLS Handshake Result Indication This URC reports the DTLS handshake result if the encryption method is used. +QLWURC: 'dtls' DTLS Handshake Result Indication +QLWURC: 'dtls',, This URC reports the DTLS handshake result. Parameter String type. DTLS handshake result. 'successfully' 'failed' Integer type. Server ID. 100 Bootstrap server under Verizon network 101 Diagnostics server under Verizon network 102 DM server under Verizon network 1000 Repository server under Verizon network Others Other specified servers 3.4. +QLWURC: 'dns' DNS Resolution Result Indication This URC reports the DNS resolution result. +QLWURC: 'dns' DNS Resolution Result Indication +QLWURC: 'dns',, This URC reports the DNS resolution result. Parameter String type. DNS resolution result. 'successfully' EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 17 / 24 LTE-A Module Series 'failed' Integer type. Server ID. 100 Bootstrap server under Verizon network 101 Diagnostics server under Verizon network 102 DM server under Verizon network 1000 Repository server under Verizon network Others Other specified servers 3.5. +QLWURC: 'bootstraping' Bootstrap Working Indication This URC reports the Bootstrap is working. +QLWURC: 'bootstraping' Bootstrap Working Indication +QLWURC: 'bootstraping' This URC reports the Bootstrap is working. 3.6. +QLWURC: 'bootstrap' Bootstrap Working Result Indication This URC reports the working result of Bootstrap. +QLWURC: 'bootstrap' Bootstrap Working Result Indication +QLWURC: 'bootstrap',, This URC reports the Bootstrap working result. Parameter String type. The working result of Bootstrap. 'successfully' 'failed' Integer type. Server ID. 100 Bootstrap server under Verizon network Others Other specified servers EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 18 / 24 LTE-A Module Series 3.7. +QLWURC: 'registering' Registration Start Indication This URC is reported when the client is registering on the LwM2M server. +QLWURC: 'registering' Start Registration Indication +QLWURC: 'registering' This URC reports the client is registering. 3.8. +QLWURC: 'ready' Registration Result Indication This URC reports the registration result after the registration request is sent to the LwM2M server. +QLWURC: 'ready' Registration Result Indication +QLWURC: 'ready',, This URC reports the registration result. Parameter String type. The registration result. 'successfully' 'failed' Integer type. Server ID. The Bootstrap server is not included. 101 Diagnostics server under Verizon network 102 DM server under Verizon network 1000 Repository server under Verizon network Others Other specified servers 3.9. +QLWURC: 'update' Update Result Indication This URC reports the update result after the update request is sent to the LwM2M server. +QLWURC: 'update' Update Result Indication +QLWURC: 'update',, This URC reports the update result. Parameter String type. Update result. 'successfully' EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 19 / 24 LTE-A Module Series 'failed' Integer type. Server ID. The Bootstrap server is not included. 101 Diagnostics server under Verizon network 102 DM server under Verizon network 1000 Repository server under Verizon network Others Other specified servers 3.10. +QLWURC: 'deregister' Deregistration Result Indication This URC reports the deregistration result after the deregistration request is sent to the LwM2M server. +QLWURC: 'deregister' Deregistration Result Indication +QLWURC: 'deregister', This URC reports the deregistration result. Parameter Integer type. Server ID. The Bootstrap server is not included. 101 Diagnostics server under Verizon network 102 DM server under Verizon network 1000 Repository server under Verizon network Others Other specified servers EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 20 / 24 LTE-A Module Series 4 Examples This chapter gives examples to explain how to use LwM2M related AT commands. Please start the following test after inserting the SIM card and enable it. For some AT commands mentioned but not described in detail in this document, you can see document [1] for more details. 4.1. Login to the Verizon LwM2M Test Server AT+QLWDEREG //Send a deregister request to the LwM2M Server. OK AT+QLWCFG='reset' //Erase LwM2M client running record. OK AT+QLWCFG='security' //Query the resources of LwM2M security object. +QLWCFG: 'security',0,100,'coaps://boot.lwm2m.vzwdm.com:5684',1,0 +QLWCFG: 'security',2,101,'coaps://diag.lwm2m.vzwdm.com:5684',0,0 OK AT+QLWCFG='security',0 //Delete the property data of Bootstrap server. OK AT+QLWCFG='security' //Query the current setting. +QLWCFG: 'security',2,101,'coaps://diag.lwm2m.vzwdm.com:5684',0,0 OK AT+GSN 865814040000216 //Request International Mobile Equipment Identity. OK AT+CNUM //Query the subscribers' number from the (U)SIM. +CNUM: 'Line 1','+15404498889',145 OK AT+QLWCFG='security',0,100,'coaps://xvzwcdpii.xdev.motive.com:5684',1,0,'urn:imei-msisdn:8 65814040000216-5404498889','d6160c2e7c90399ee7d207a22611e3d3a87241b0462976b935341d00 0a91e747' //Set the property data of Bootstrap server. OK AT+QLWCFG='security' //Query the current setting. +QLWCFG: 'security',0,100,'coaps://xvzwcdpii.xdev.motive.com:5684',1,0 EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 21 / 24 LTE-A Module Series +QLWCFG: 'security',2,101,'coaps://diag.lwm2m.vzwdm.com:5684',0,0 OK AT+CFUN=1,1 OK //Set the device to full functionality after it is reset. +QLWURC: 'pdp active','successfully','VZWADMIN' +QLWURC: 'dns','successfully',100 +QLWURC: 'dtls','successfully',100 +QLWURC: 'bootstraping' +QLWURC: 'bootstrap','successfully',100 +QLWURC: 'dns','successfully',102 +QLWURC: 'dns','successfully',101 +QLWURC: 'dtls','successfully',102 +QLWURC: 'ready','successfully',102 +QLWURC: 'pdp active','successfully','VZWINTERNET' +QLWURC: 'dns','successfully',1000 +QLWURC: 'update','successfully',102 +QLWURC: 'dtls','successfully',101 +QLWURC: 'dtls','successfully',1000 +QLWURC: 'ready','successfully',101 +QLWURC: 'ready','successfully',1000 OK 4.2. Login to the Verizon LwM2M Test Server by Test Mode AT+QLWDEREG //Send a deregister request to the LwM2M Server. OK AT+QLWCFG='testmode','0' //Clear the existing configured URLs. OK AT+QLWCFG='testmode','coaps://xvzwcdpii.xdev.motive.com:5684' //Configure Bootstrap server URL which the module will connect to. OK AT+CFUN=1,1 //Set the device to full functionality after it is reset. OK EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 22 / 24 LTE-A Module Series 5 Appendix References Table 3: Related Document Document Name [1] Quectel_EG06xK&Ex120K&EM060K_Series_AT_Commands_Manual Table 4: Terms and Abbreviations Abbreviation APN AT&T CMCC CoAP DM DNS DTLS ID LTE LwM2M PDP PSK REST SKT SMS Description Access Point Name American Telephone & Telegraph China Mobile Communications Corporation Constrained Application Protocol Device Management Domain Name Server Datagram Transport Layer Security Mostly refers to Identifier in terms of software Long Term Evolution Lightweight Machine to Machine Packet Data Protocol Pre-Shared Key Representational State Transfer SK Telecom Short Message Service EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 23 / 24 SSID TA UDP URC URL VZW Service Set Identifier Terminal Adapter User Datagram Protocol Unsolicited Result Code Uniform Resource Locator Verizon Wireless LTE-A Module Series EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note 24 / 24

Quectel_EG06xK&Ex120K&EM060K_Series_LwM2M_Application_Note_V1.0

PDF

247.21 KB

EC200x&EG91xN&EG912Y&EG950A Series PPP Application Note LTE Standard Module Series Version: 1.4 Date: 2023-05-16 Status: Released LTE Standard 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. EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 1 / 28 LTE Standard 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. 2023. All rights reserved. EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 2 / 28 LTE Standard Module Series About the Document Revision History Version Date Author Description 1.0 2020-07-31 Chaim QIAN Initial 1.1 2021-04-02 Chaim QIAN Changed the response of ATO to CONNECT (Chapter 4.1.2.1). 1.2 2022-02-25 Chaim QIAN Added applicable modules EC200A series and EG915N-EU. Updated applicable modules: ⚫ Added EG912N-EN. 1.3 2022-09-22 Chaim QIAN ⚫ Updated EG915N-EU to EG915N series. ⚫ Deleted EC200T series. 1. Added the applicable module EG950A series. 1.4 2023-05-16 Chaim QIAN 2. Updated the module diagram of General Procedures for PPP Link Establishment (Chapter 3.1). EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 3 / 28 LTE Standard Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 1.1. Applicable Modules ..................................................................................................................... 7 2 PPP Application Mode........................................................................................................................ 8 3 PPP Link Establishment..................................................................................................................... 9 3.1. General Procedures for PPP Link Establishment....................................................................... 9 3.2. Recommended Procedures for PPP Link Establishment ......................................................... 10 4 PPP Connection Modes.................................................................................................................... 12 4.1. Data Mode and Command Mode.............................................................................................. 12 4.1.1. Switch from Data Mode to Command Mode................................................................. 12 4.1.1.1. Change DTR Level to Switch from Data Mode to Command Mode ..................... 12 4.1.1.2. Use Sequence +++ to Switch from Data Mode to Command Mode ..................... 12 4.1.2. Switch from Command Mode to Data Mode................................................................. 13 4.1.2.1. Use ATO to Switch from Command Mode to Data Mode...................................... 13 4.2. Handle URC in Data Mode ....................................................................................................... 13 4.3. Data Carrier Detection (DCD) Mode......................................................................................... 13 5 PPP Connection Termination .......................................................................................................... 15 6 PPP Dial-up Operations.................................................................................................................... 16 6.1. Preparation................................................................................................................................ 16 6.2. PPP Dial-up in Windows 10 ...................................................................................................... 16 6.2.1. Modem Configuration.................................................................................................... 16 6.2.1.1. Add New Modem ................................................................................................... 16 6.2.1.2. Configure Modem Driver ....................................................................................... 21 6.2.2. Dial-up Network Configuration ...................................................................................... 22 6.2.2.1. Create a New Connection ..................................................................................... 22 6.2.2.2. Configure the Connection ...................................................................................... 24 6.2.2.3. Configure the Dial-up Tool ..................................................................................... 25 6.2.2.4. Establish the Dial-up Connection .......................................................................... 26 7 Appendix References ....................................................................................................................... 27 EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 4 / 28 LTE Standard Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 7 Table 2: Related Documents ...................................................................................................................... 27 Table 3: Terms and Abbreviations .............................................................................................................. 27 EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 5 / 28 LTE Standard Module Series Figure Index Figure 1: PPP Application Mode .................................................................................................................. 8 Figure 2: General Procedures for PPP Link Establishment......................................................................... 9 Figure 3: Recommended Procedures for PPP Link Establishment ........................................................... 10 Figure 4: Search for 'Phone and Modem' in Control Panel ...................................................................... 17 Figure 5: Add New Modem......................................................................................................................... 18 Figure 6: Select Modem Model .................................................................................................................. 19 Figure 7: Select Port................................................................................................................................... 20 Figure 8: New Modem is Installed Successfully ........................................................................................ 20 Figure 9: Configure Modem Driver............................................................................................................. 21 Figure 10: Create New Connection............................................................................................................ 22 Figure 11: Set up New Connection ............................................................................................................ 23 Figure 12: Configure Connection ............................................................................................................... 24 Figure 13: Configure Dial-up Tool .............................................................................................................. 25 Figure 14: Connecting to Dial-up Connection............................................................................................ 26 Figure 15: Establish Dial-up Connection Successfully .............................................................................. 26 EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 6 / 28 LTE Standard Module Series 1 Introduction This document explains the PPP function of Quectel EC200x family, EG91xN family, EG912Y-EU and EG950A series modules, including PPP application modes, setting procedures, connection modes, termination steps, and dialing examples. 1.1. Applicable Modules Table 1: Applicable Modules Module Family EC200x EG91xN - Module EC200A Series EC200S Series EG912N-EN EG915N Series EG912Y-EU EG950A Series EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 7 / 28 LTE Standard Module Series 2 PPP Application Mode The use of PPP (Point-to-Point Protocol) is illustrated in the following figure. Use UART port or USB port for PPP connection. The module provides a PPP server for application, and the application provides a PPP client for the module. Meanwhile, the application must provide protocols such as TCP/IP, HTTP(S), etc. After the PPP connection is established, the IP packet data stream from the application will be transmitted to the Internet through the module. Most standard operating systems (e.g., Windows, Unix/Linux) include the PPP protocol stack. For operating systems that do not have applications for PPP connection, it is necessary to develop the relevant application software first. Application IP PPP UART TXD RXD CTS RTS DTR DCD RING USB USB_DM USB_DP USB_GN USB_VBUS IP RELAY PPP TXD RXD CTS RTS DTR DCD RING UART USB_DM USB_DP USB_GND USB_VBUS USB Radio Bearer Application Module Figure 1: PPP Application Mode EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 8 / 28 LTE Standard Module Series 3 PPP Link Establishment 3.1. General Procedures for PPP Link Establishment After the module registers on GPRS network, it is necessary to set the APN for PPP with AT+CGDCONT and to start PPP with ATD*99#. After executing ATD*99#, the module will enter the PPP frame interaction process, which is based on standard PPP protocol. The module data packet interaction is described in the figure below. For more information about standard PPP, see RFC 1661. Figure 2: General Procedures for PPP Link Establishment EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 9 / 28 LTE Standard Module Series 3.2. Recommended Procedures for PPP Link Establishment Recommended Power-on/off: For details of the recommended power-on/off methods of each applicable module, see their Hardware Design documents respectively. Power on the module 1. Synchronization between TE and TA. 2. Fix and save baud rate by AT+IPR=xxx&W. If USB modem port is used, this could be ignored. N Query (U)SIM Card Status: AT+CPIN. Reboot the module if it fails to detect (U)SIM card in 20 s with AT+CPIN?. Network: 1. It indicates that the module has registered on network when AT+CREG? returns 1 or 5. 2. Reboot the module if it fails to register on network in 60 s. PS Network: 1. It indicates that the module has registered on PS when AT+CGREG? returns 1 or 5. 2. It is able to go to next step without registering on PS in 60 s. Exit from the PPP dialing if (U)SIM card is not ready in 20 s. AT+CPIN? Y Query (U)SIM card status Exit from the PPP dialing if the module fails to register on network in 60 s (U)SIM card is ready AT+CREG? Query network status Register on network in 60 s AT+CGREG? Query PS network Connect_Count < 5 APN Configuration: 1. APN must be set by AT+CGDCONT. 2. Use AT+CGACT? to check whether the current context has been activated when AT+CGDCONT returns error. 1. Set APN by AT+CGDCONT 2. Start PPP dialing by ATD*99# Connect_Count++ Packet Interaction Packet Interaction: 1. Exit from the procedure of Packet Interaction by '+++'. 2. The module will report NO CARRIER when PPP connection is terminated. LCP Negotiation: 1. If UART is used, ensure the baud rate between MCU and the module is the same. AUTH Negotiation: 1. Ensure the type of AUTH is one of the following two: PAP(0xc023), CHAP(0xc223). IPCP Negotiation: 1. Check whether MCU has got legal IP and DNS address. 2. Check whether the amount of DNS MCU is equal to the amount requested by MCU. 3. Terminate PPP connection if IPCP negotiation between TA and TE is not completed in 90 s, and then retry PPP setup. Start timer when IPCP negotiation begins Exception Handling: 1. Check whether the PPP TerminateRequest packet is right. 2. Reboot the module if the steps above do not work. Return CONNECT LCP negotiation OK AUTH negotiation OK Exception handling N Send Count < 5 IPCP negotiation Y N OK Succeed to negotiate IPCP in 90 s MCU sends PPP N TerminateRequest packet MCU receives Y PPP Terminate- Ack packet in 3 s Send Count++ Y MCU got IP and N DNS Y Data transmission Figure 3: Recommended Procedures for PPP Link Establishment EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 10 / 28 LTE Standard Module Series When the module is powered on, if the main UART is used, set the baud rate by executing AT+IPR=xxx;&W. Before executing ATD*99# to start PPP dialing, you must check the status of the (U)SIM card with AT+CPIN?. When the (U)SIM card is ready, periodically check the network registration status with AT+CREG? and AT+CGREG? until the network is ready. NOTE 1. Ensure that the MCU and the module are synchronized after rebooting the module. MCU sends AT to the module every 100 ms until it receives OK reported by the module. If the main UART is used, the MCU will execute AT+IPR=xxx;&W to set and save the baud rate after synchronizing the baud rate. 2. Before inputting the next AT command, the MCU needs to wait for the response to the AT command (such as response OK, CME error, CMS error) that is being executed. If there is no response within 60 seconds, the module can be restarted. 3. Do NOT power on/off the module frequently. If 3 consecutive dialing attempts fail, you can immediately power on/off (reset) the module for the first time. After resetting, if the dialing attempt fails, you need to wait 10 minutes for the second reset, 30 minutes for the third reset, and one hour for the fourth reset. 4. If the MCU fails to transmit data to network after establishing the PPP connection, check the PPP configuration and network status and restart the module. 5. If the module has registered on CDMA network, use ATD*99# instead of ATD#777 to start PPP dialling. EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 11 / 28 LTE Standard Module Series 4 PPP Connection Modes 4.1. Data Mode and Command Mode The module communicates with an application via a USB or UART port (including AT commands and data). USB and UART ports have two working modes: data mode and command mode. The two ports are in command mode before PPP is set, and the module can execute AT commands in this mode. When PPP negotiation starts, the two ports enter data mode, and remain in the mode once the PPP connection is established. If the PPP connection is not successfully established, the two ports will be in the command mode. In data mode, the module cannot execute AT commands. EC200x family, EG91xN family, EG912Y-EU and EG950A series modules provide convenient methods to switch between the two modes. 4.1.1. Switch from Data Mode to Command Mode 4.1.1.1. Change DTR Level to Switch from Data Mode to Command Mode When the PPP connection has been established and USB/UART port is in data mode, change the DTR pin level from low to high to switch from data mode to command mode (AT&D1 must be set first). After a successful switch, the module will return OK. 4.1.1.2. Use Sequence +++ to Switch from Data Mode to Command Mode After the PPP connection is established, use +++ to switch the USB/UART port from data mode to command mode. To prevent the +++ escape sequence from being misinterpreted as data, the following requirements should be followed: 1) Do not input any character for at least 1 s before inputting +++. 2) Input only +++ within 1 s, USB/UART port will switch from data mode to command mode, and the module will return OK. 3) Do not input any character for within 1 s after inputting +++. EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 12 / 28 LTE Standard Module Series NOTE Perform the above operations after completing the PPP negotiation, otherwise the above operations will terminate the PPP negotiation and the USB/UART port will exit the data mode. After completing the PPP negotiation, when the USB/UART port switches to the command mode, the input data will be treated as AT command, and the module maintains the PPP connection. 4.1.2. Switch from Command Mode to Data Mode 4.1.2.1. Use ATO to Switch from Command Mode to Data Mode Execute ATO to switch USB/UART port from command mode to data mode, once the PPP connection has been established. Example //Once the PPP connection has been established, USB/UART port is in command mode. ATO CONNECT //Indicates that TA has entered data mode, and all data inputted via USB/UART port will be treated as PPP frames. 4.2. Handle URC in Data Mode The URC for incoming calls and short messages in data mode will not be reported to the PPP dial-up port during an ongoing PPP connection. However, the level of module’s RI pin will change from high to low for 120 ms as an indication of URC for incoming calls and short messages. The MCU can switch the port to command mode according to the RI pin status to process incoming calls or short messages. After switching to command mode, the URC will be reported to the PPP dial-up port if there are still incoming calls or text messages. 4.3. Data Carrier Detection (DCD) Mode DCD mode is determined by AT&C. If AT&C0 is executed, the DCD pin will not be used to indicate the data carrier status. If AT&C1 is executed, the DCD pin will be used to indicate the data carrier status. The pin will remain at low level if there is a data carrier or PPP negotiation begins, otherwise it will remain at high level. EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 13 / 28 LTE Standard Module Series NOTE When switching module’s USB/UART port from data mode to command mode (by using +++), the DCD state remains unchanged. EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 14 / 28 LTE Standard Module Series 5 PPP Connection Termination There are two methods to terminate the PPP dial-up connection: 1. Terminating the PPP connection through the LCP Terminate-Request message – recommended method. 2. Terminating the PPP connection by changing the DTR level. Set the DTR function with AT&D2, change the DTR level from low to high, and the data connection will be automatically terminated. Once the PPP connection is terminated, the USB/UART port will enter the command mode. Example //USB/UART port is in command mode before PPP connection is established. AT&D2 OK NOTE 1. PPP connection termination procedures must be performed in data mode. 2. PPP connection termination procedures can be performed at any time during the PPP setting or connecting process. EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 15 / 28 LTE Standard Module Series 6 PPP Dial-up Operations This chapter explains how to establish a PPP dial-up connection in Windows 10. For detailed operations in Linux operating system, see document [1] 6.1. Preparation It is necessary to perform the following steps before establishing a PPP dial-up connection in Windows. 1. Connect the module to a PC and enter the PIN code if the (U)SIM card PIN is locked. 2. Make sure the (U)SIM card can successfully register on GPRS network. 6.2. PPP Dial-up in Windows 10 6.2.1. Modem Configuration 6.2.1.1. Add New Modem If the Standard 19200 bps Modem is not installed, add a new standard modem to the modem section of the control panel. EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 16 / 28 LTE Standard Module Series 1. Search for 'Phone' in the main interface, and then click 'Phone and Modem' option: Figure 4: Search for 'Phone and Modem' in Control Panel EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 17 / 28 LTE Standard Module Series 2. Double-click the 'Phone and Modem', and select 'Modems' → 'Add…' to add a new modem. Figure 5: Add New Modem EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 18 / 28 LTE Standard Module Series 3. Follow the instructions on the screen to install the new modem: select 'Standard 19200 bps Modem' and then the port (such as 'COM10') to be installed; click 'Next' button until the configuration is complete. For details, see the figures below. Figure 6: Select Modem Model EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 19 / 28 LTE Standard Module Series Figure 7: Select Port Figure 8: New Modem is Installed Successfully EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 20 / 28 LTE Standard Module Series 6.2.1.2. Configure Modem Driver Select the installed 'Standard 19200 bps Modem' and click the 'Properties' button. After entering the interface, select the 'Modems' option and modify the 'Maximum Port Speed' to '115200' (default value). Click the 'Advanced' option, configure 'Extra Settings' and input AT+CGDCONT=1,'IP','CMNET'. Figure 9: Configure Modem Driver EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 21 / 28 LTE Standard Module Series NOTE In the example above, AT+CGDCONT=1,'IP','CMNET' predefines a PDP context where CID=1, PDP type=IP and APN=CMNET. CMNET is the APN of the network operator China Mobile and it should be replaced with the value provided by the network operator. 6.2.2. Dial-up Network Configuration 6.2.2.1. Create a New Connection 1. Open 'Control Panel', click 'Network and Internet', 'Network and Sharing Center' and finally 'Set up a new connection or network'. Figure 10: Create New Connection EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 22 / 28 LTE Standard Module Series 2. Select 'Connect to the Internet', click 'Next'. Then click 'Set up a new connection anyway' and 'Dial-up' to connect. Figure 11: Set up New Connection EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 23 / 28 LTE Standard Module Series 6.2.2.2. Configure the Connection Enter characters (such as *99#) in 'Dial-up phone number' box, and then click 'Connect' button. Figure 12: Configure Connection EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 24 / 28 LTE Standard Module Series 6.2.2.3. Configure the Dial-up Tool Enter characters (such as *99#) in 'Dial' window, click 'Properties' button, and configure the 'Standard 19200 bps Modem (COM10)'. Then select '115200' from the drop-down list of 'Maximum speed'. Click 'OK' button to finish the configuration. Figure 13: Configure Dial-up Tool EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 25 / 28 LTE Standard Module Series 6.2.2.4. Establish the Dial-up Connection After the above operations, click the 'Dial' button, the interface will pop up a prompt box 'Verifying username and password', and the pop-up box quickly pops up 'Connected' to indicate a dial-up connection. See the following figures for details. Figure 14: Connecting to Dial-up Connection Figure 15: Establish Dial-up Connection Successfully EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 26 / 28 LTE Standard Module Series 7 Appendix References Table 2: Related Documents Document Name [1] Quectel_LTE_5G_Linux_USB_Driver_User_Guide Table 3: Terms and Abbreviations Abbreviation APN CHAP DCD DNS DTR GPRS GSM IP IPCP LCP MCU MS PAP PDP PIN Description Access Point Name Challenge Handshake Authentication Protocol Data Carrier Detection Domain Name Server Data Terminal Ready General Packet Radio Service Global System of Mobile Communication Internet Protocol IP Control Protocol Link Control Protocol Micro Control Unit Mobile Station Password Authentication Protocol Packet Data Protocol Personal Identification Number EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 27 / 28 PPP RI TA TE UART (U)SIM LTE Standard Module Series Point-to-Point Protocol Ring Indicator Terminal Adapter Terminal Equipment Universal Asynchronous Receiver Transmitter (Universal) Subscriber Identity Module EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note 28 / 28

Quectel_EC200x&EG91xN&EG912Y&EG950A_Series_PPP_Application_Note_V1.4

PDF

776.77 KB

LC76F AGNSS Application Note GNSS Module Series Version: 1.1 Date: 2023-05-17 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 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. LC76F_AGNSS_Application_Note 1 / 28 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 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. 2023. All rights reserved. LC76F_AGNSS_Application_Note 2 / 28 GNSS Module Series About the Document Document Information Title Subtitle Document Type Document Status LC76F AGNSS Application Note GNSS Module Series Application Note Released Revision History Version 1.0 1.1 Date 2021-11-18 2022-01-21 2023-05-17 Description Creation of the document First official release 1. Deleted the PGKC001, PGKC030 and PGKC147 messages (Chapter 2.1.1). 2. Added the PGKC047 message (Chapter 2.1.1.1). 3. Added a response in the PGKC149 message (Chapter 2.1.1.2). 4. Added notes of Reference Time and Reference Position (Chapter 2.1.1.3). LC76F_AGNSS_Application_Note 3 / 28 GNSS Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 2 AGNSS Implementation...................................................................................................................... 8 2.1. Messages for AGNSS Implementation ...................................................................................... 8 2.1.1. NMEA Proprietary Messages.......................................................................................... 9 2.1.1.1. PGKC047: PGKC_CLEAR_GPD_FILE_IN_FLASH............................................ 9 2.1.1.2. PGKC149: PGKC_SET_DATA_MODE ............................................................... 9 2.1.1.3. PGKC639: PGKC_SET_POSITION_AND_TIME .............................................. 10 2.1.2. Binary Messages........................................................................................................... 12 2.1.2.1. SET_DATA_MODE (0x0095) ............................................................................ 13 2.1.2.2. ACK_FOR_CMD (0x0001)................................................................................. 14 2.1.2.3. GPD_DATA (0x0266)......................................................................................... 14 2.1.2.4. ACK_FOR_GPD_MSG (0x0003)....................................................................... 16 2.2. Download GPD File from AGNSS Server................................................................................ 17 2.3. GPD Data Format .................................................................................................................... 18 2.4. Send GPD Data to Module Flash ............................................................................................ 19 3 AGNSS Testing Procedures ............................................................................................................ 20 3.1 Prerequisites ............................................................................................................................ 20 3.2 Procedures ............................................................................................................................... 21 3.2.1. Simplified Procedure of Satellite Data Transfer via QGNSS Tool................................ 25 3.3 Results ..................................................................................................................................... 26 4 Appendix A References.................................................................................................................... 27 5 Appendix B Special Characters ...................................................................................................... 28 LC76F_AGNSS_Application_Note 4 / 28 GNSS Module Series Table Index Table 1: List of Proprietary NMEA Messages .............................................................................................. 8 Table 2: List of Binary Messages ................................................................................................................. 8 Table 3: Structure of Binary Messages...................................................................................................... 12 Table 4: SET_DATA_MODE Payload........................................................................................................ 13 Table 6: ACK_FOR_CMD Payload ............................................................................................................ 14 Table 5: GPD_DATA Payload.................................................................................................................... 15 Table 7: ACK_FOR_GPD_MSG Payload .................................................................................................. 16 Table 8: Related Document ....................................................................................................................... 27 Table 9: Terms and Abbreviations ............................................................................................................. 27 Table 10: Special Characters..................................................................................................................... 28 LC76F_AGNSS_Application_Note 5 / 28 GNSS Module Series Figure Index Figure 1: Structure of Binary Messages..................................................................................................... 12 Figure 2: GPD Data Format ....................................................................................................................... 18 Figure 3: Send GPD Data to Module ......................................................................................................... 19 Figure 4: Transmission Flow ...................................................................................................................... 21 Figure 5: Simplified Testing Procedure via QGNSS Tool .......................................................................... 25 Figure 6: Log of Testing AGNSS Feature via QGNSS Tool ...................................................................... 26 LC76F_AGNSS_Application_Note 6 / 28 GNSS Module Series 1 Introduction The following document provides a detailed explanation on the operation mechanism and the procedures of the AGNSS function, which is used to improve the TTFF duration of the Quectel GNSS LC76F module. To implement the AGNSS function, the module should obtain the AGNSS data from the relevant server (GPD) via a serial port. LC76F_AGNSS_Application_Note 7 / 28 GNSS Module Series 2 AGNSS Implementation This chapter explains the AGNSS implementation on the LC76F GNSS module and the data download procedure. It also includes the messages for AGNSS implementation. 2.1. Messages for AGNSS Implementation The LC76F module supports binary messages and proprietary PGKC messages in NMEA format. Table 1: List of Proprietary NMEA Messages Message PGKC047 PGKC149 PGKC639 Description Clears the GPD file in the Flash. Switches NMEA mode (default) to binary mode. Sets approximate location information and time information. Table 2: List of Binary Messages Message Type 0x0095 0x0001 0x0266 0x0003 Description Switches binary mode to NMEA mode and sets the baud rate. (Corresponds to PGKC149) Responses to a command in binary format. Sends GPD data to module. Responses to GPD data transmission message. LC76F_AGNSS_Application_Note 8 / 28 GNSS Module Series 2.1.1. NMEA Proprietary Messages 2.1.1.1. PGKC047: PGKC_CLEAR_GPD_FILE_IN_FLASH Clears the GPD file in the Flash. GPD file is the AGNSS auxiliary positioning file defined by the chipset supplier. Type: Command Synopsis: $PGKC047* Parameter: None Result: Returns $PGKC001 message. For details about $PGKC001 message, refer to document [1] protocol specification. Example: $PGKC047*2C $PGKC001,47,3*1E 2.1.1.2. PGKC149: PGKC_SET_DATA_MODE Switches NMEA mode (default) to binary mode. must match the module’s current baud rate. Type: Set Synopsis: $PGKC149,,* LC76F_AGNSS_Application_Note 9 / 28 Parameter: Field Format Unit Numeric - Numeric bps Result: Data mode switches to binary mode. Example: $PGKC149,1,9600*1D AA F0 0C 00 01 00 95 00 03 9B 0D 0A Description 1 = Binary mode Baud rate: 9600 14400 19200 38400 57600 115200 230400 460800 921600 GNSS Module Series 2.1.1.3. PGKC639: PGKC_SET_POSITION_AND_TIME Sets approximate location information and time information to speed up positioning. Type: Set Synopsis: $PGKC639,,,,,,,,,*< CR> LC76F_AGNSS_Application_Note 10 / 28 GNSS Module Series Parameter: Field Format Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Unit Degree Degree Meter Year Month Day Hour Minute Second Description Latitude. Longitude. Height. Year. Month. Day. Hour, UTC time. Minute. Second. Result: Returns $PGKC001 message. For details about $PGKC001 message, refer to document [1] protocol specification. Example: $PGKC639,31.822234,117.115230,59,2021,9,17,06,51,0*33 $PGKC001,639,3*21 NOTE 1. The Reference Time should be accurate within 3 seconds and must be specified in UTC time. 2. The Reference Position should be accurate within 30 km from the receiver's actual position. LC76F_AGNSS_Application_Note 11 / 28 GNSS Module Series 2.1.2. Binary Messages The header of the frame, always '0xAA 0xF0' 2 bytes 2 bytes End of the frame, 1 byte always '0x0D 0x0A' Header Length MsgType Payload Checksum Tail The range for checksum calculation Figure 1: Structure of Binary Messages Table 3: Structure of Binary Messages Field Header Length MsgType Payload Checksum Tail Description Header of the frame, fixed at 0xAA 0xF0. Message length, the total length from Header to Tail (including Header and Tail fileds). The length format is a little-endian unsigned 16-bit integer. Message type, 2 bytes in little-endian format. Message contents. Checksum is a byte-by-byte XOR from Length to Payload. End of the frame, fixed at 0x0D 0x0A. Checksum sample code: #define LENGTH 518 unsigned char Get_Checksum (const char* buf, int buf_len) { int i; unsigned char checksum; if (buf_len > LENGTH) { buf_len = LENGTH; } else if (0 == buf_len || buf == NULL) { return 0; } LC76F_AGNSS_Application_Note 12 / 28 checksum = 0; for (i = 0; i < buf_len; i++) { checksum ^= buf[i]; } return checksum; } GNSS Module Series 2.1.2.1. SET_DATA_MODE (0x0095) Switches binary mode to NMEA mode and sets the baud rate. SET_DATA_MODE Header Length 0xAA 0xF0 0x0E 0x00 MsgType 0x95 0x00 Payload Checksum See Table 4: SET_DATA_MODE 0x** Payload Tail 0x0D 0x0A Table 4: SET_DATA_MODE Payload Offset Scaling Name Unit 0 - Mode - 1 - Baud rate bps Example: //Switch to NMEA mode with 115200 bps: AA F0 0E 00 95 00 00 00 C2 01 00 58 0D 0A AA F0 0C 00 01 00 95 00 03 9B 0D 0A Description Fixed at 0x00. Sets the baud rate when switching binary mode to NMEA mode. 4 bytes in little-endian format. LC76F_AGNSS_Application_Note 13 / 28 GNSS Module Series 2.1.2.2. ACK_FOR_CMD (0x0001) Responses to a command in binary format. ACK_FOR_CMD Header Length 0xAA 0xF0 0x0C 0x00 MsgType 0x01 0x00 Payload See Table 5: ACK_FOR_CMD Payload Checksum Tail 0x** 0x0D 0x0A Table 5: ACK_FOR_CMD Payload Offset 0 Scaling Name Unit - MsgType - 2 - ValidInd - Description Acknowledged message type. Input message validity indicator. 0x00 = Invalid. 0x01 = Not supported. 0x02 = Failed. 0x03 = Succeeded. Example: AA F0 0C 00 01 00 95 00 03 9B 0D 0A 2.1.2.3. GPD_DATA (0x0266) Sends the GPD data to module. GPD_DATA Header Length 1) MsgType 0xAA 0xF0 0x** 0x** 0x66 0x02 Payload See Table 6: GPD_DATA Payload Checksum 0x** Tail 0x0D 0x0A LC76F_AGNSS_Application_Note 14 / 28 GNSS Module Series Table 6: GPD_DATA Payload Offset Scaling Name Unit 0 - PkgNum - 2 - GPD_Data - Description Package sequence number of GPD data. 2 bytes in little-endian format starting from 0x0000. GPD data content, 512 bytes. Example: //The first packet of GPD data: AA F0 0B 02 66 02 00 00 D0 80 6E 4E 01 01 FF FF D0 80 6E 4E 00 D2 1F 00 00 00 00 00 00 00 00 00 00 00 00 00 0A 00 00 00 …… AA F0 0C 00 03 00 00 00 01 0E 0D 0A … //The last packet of GPD data: AA F0 0B 02 66 02 06 00 02 55 02 00 65 6E BD 00 A1 8D 0B 00 C7 1E 0D 00 00 B6 67 00 A2 EF FF 00 0A 28 C3 00 26 0D 00 00…… AA F0 0C 00 03 00 06 00 01 08 0D 0A //The end message without GPD data: AA F0 0B 00 66 02 FF FF 6F 0D 0A AA F0 0C 00 03 00 FF FF 01 0E 0D 0A NOTE 1. The GPD file is divided into 512-byte data blocks for each transmission. If the last data block is less than 512 bytes, it must be filled with 0x00. 2. After sending all GPD data, an end message must be sent. In this message, PkgNum should be 0xFFFF without GPD_Data. 3. 1) For GPD data, the length is fixed at 0x0B 0x02. For end message without GPD data, the length is fixed at 0x0B 0x00 LC76F_AGNSS_Application_Note 15 / 28 GNSS Module Series 2.1.2.4. ACK_FOR_GPD_MSG (0x0003) Responses to GPD data transmission message. ACK_FOR_GPD_MSG Header Length 0xAA 0xF0 0x0C 0x00 MsgType 0x03 0x00 Payload Checksum See Table 7: ACK_FOR_GPD_MS 0x** G Payload Tail 0x0D 0x0A Table 7: ACK_FOR_GPD_MSG Payload Offset 0 Scaling Name Unit - PkgNum - 2 - ValidInd - Description The package sequence number of GPD data. Input message validity indicator. 0x00 = Invalid 0x01 = Valid Example: AA F0 0C 00 03 00 00 00 01 0E 0D 0A LC76F_AGNSS_Application_Note 16 / 28 GNSS Module Series 2.2. Download GPD File from AGNSS Server You can download the brdcGPD.dat AGNSS data file through the FTP protocol at ftp://agnss.queclocator.com. Quectel AGNSS server offers the capability to download GPD data with a validity duration of six-hours. NOTE 1. Quectel AGNSS server downloads the satellite data in real time. You must create your own server for downloading and storing the satellite data from the Quectel AGNSS server. It is recommended to update the assistance data at least every 6 hours to ensure that the most up-to-date satellite data are available for your terminal device. 2. To access and use the Quectel AGNSS server, you must have an account. Contact Quectel’s Technical Support Team (support@quectel.com) to apply for the account. LC76F_AGNSS_Application_Note 17 / 28 GNSS Module Series 2.3. GPD Data Format GPD data format is shown in the figure below: Offset 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 00000000 D0 80 6E 4E 01 01 FF FF D0 80 6E 4E 00 D2 1F 00 00 00 00 00 00 00 00 00 00 00 00 00 0A 00 00 00 00000020 B5 67 39 00 9F FF 00 00 64 24 4A 00 CC 02 39 00 21 88 2C 00 0D 31 27 00 05 43 02 00 D5 08 AA 00 00000040 A1 95 05 00 4D 6C 0D 00 00 B5 67 00 22 CC FF 00 D8 D3 47 00 28 22 00 00 BF 60 26 00 24 A1 2A 00 00000060 63 6E 47 00 A0 A5 FF 00 CC 03 00 39 02 01 FF FF E0 80 6E 4E 00 D2 1F 00 00 00 00 00 00 00 00 00 00000080 00 00 00 00 DB 00 00 00 B6 67 3E 00 EE FF 00 00 3C 12 AD 00 B3 03 3E 00 2C EF 32 00 95 75 1E 00 000000A0 0A A0 02 00 9B 85 60 00 A1 03 05 00 37 0E 0E 00 00 B6 67 00 1E 5E FF 00 05 82 C5 00 27 27 FF 00 000000C0 7F F1 46 00 C3 DE 29 00 8A CE 28 00 09 A1 FF 00 38 09 00 3E 03 01 FF FF E0 80 6E 4E 00 D2 1F 00 000000E0 00 00 00 00 00 00 00 00 00 00 00 00 04 00 00 00 B6 67 16 00 8B FF 00 00 3C C0 D9 00 14 F3 16 00 00000100 F3 53 2F 00 27 7A A4 00 01 BA F4 00 72 26 FB 00 A1 A2 0D 00 5C 33 0E 00 00 B6 67 00 4C 07 00 00 00000120 74 20 87 00 27 22 00 00 72 ED 89 00 28 21 21 00 EE 7B 05 00 90 A7 FF 00 6C FD 00 16 04 01 FF FF 00000140 E0 80 6E 4E 02 D2 1F 00 00 00 00 00 00 00 00 00 00 00 00 00 F7 00 00 00 B6 67 34 00 01 00 00 00 00000160 28 39 E5 00 6B FD 34 00 69 52 31 00 48 59 8D 00 00 FA FD 00 F6 DE B6 00 A1 9C 16 00 6B 9A 0D 00 00000180 00 B6 67 00 78 D9 FF 00 A2 67 91 00 27 F9 FF 00 32 3F 29 00 83 9D 15 00 07 19 6D 00 FD A9 FF 00 000001A0 C4 13 00 34 05 01 FF FF E0 80 6E 4E 00 D2 1F 00 00 00 00 00 00 00 00 00 00 00 00 00 E8 00 00 00 000001C0 B6 67 5A 00 F5 FF 00 00 88 D6 F8 00 C4 EF 5A 00 8B D8 31 00 11 D8 B2 00 03 7A F1 00 50 29 1E 00 000001E0 A1 B4 0D 00 52 C1 0C 00 00 B6 67 00 4A 21 00 00 FE F8 F6 00 27 D8 FF 00 B3 E9 01 00 28 6C 1F 00 00000200 04 DB 7C 00 24 A7 FF 00 04 FC 00 5A 06 01 FF FF E0 80 6E 4E 00 D2 1F 00 00 00 00 00 00 00 00 00 00000220 00 00 00 00 08 00 00 00 B6 67 3E 00 41 00 00 00 C0 EF 09 00 16 02 3E 00 2E 8C 2C 00 6C 00 EF 00 00000240 01 08 02 00 2B 54 1C 00 A1 EE 04 00 E9 9B 0C 00 00 B6 67 00 21 16 00 00 F6 BA F1 00 28 BC FF 00 00000260 99 6D 20 00 D6 FF 2A 00 E3 06 C0 00 C5 A6 FF 00 B8 09 00 3E 07 01 FF FF D0 80 6E 4E 00 D2 1F 00 00000280 00 00 00 00 00 00 00 00 00 00 00 00 E8 00 00 00 B5 67 2C 00 3E 00 00 00 70 4C 20 00 FC 02 2C 00 000002A0 08 FF 39 00 5F BD 36 00 07 E2 02 00 7F 6E D0 00 A1 14 0C 00 2B D7 0D 00 00 B5 67 00 A2 E5 FF 00 000002C0 29 0A 22 00 26 4A 00 00 1A D2 C2 00 A2 DA 20 00 D2 91 07 00 A6 A1 FF 00 7C FF 00 2C FF FF FF FF 000002E0 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 00000300 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 00000320 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 00000340 FF FF FF FF 09 01 FF FF E0 80 6E 4E 00 D2 1F 00 00 00 00 00 00 00 00 00 00 00 00 00 02 00 00 00 00000360 B6 67 29 00 FB FF 00 00 34 AD D0 00 30 FD 29 00 8D 23 33 00 13 E9 F0 00 01 97 FD 00 52 A4 1A 00 00000380 A1 C8 16 00 07 B2 0D 00 00 B6 67 00 76 06 00 00 69 0A 76 00 26 09 00 00 78 35 DF 00 49 DA 14 00 000003A0 B2 99 F6 00 56 A9 FF 00 90 12 00 29 0A 01 FF FF E0 80 6E 4E 00 D2 1F 00 00 00 00 00 00 00 00 00 000003C0 00 00 00 00 05 00 00 00 B6 67 49 00 BB FF 00 00 A8 2A E5 00 1A F0 49 00 D1 8E 2E 00 90 80 90 00 000003E0 03 40 F2 00 22 1B 8E 00 A1 DF 0C 00 69 71 0D 00 00 B6 67 00 4C 6D 00 00 23 83 69 00 27 F7 FF 00 00000400 Figure 2: GPD Data Format LC76F_AGNSS_Application_Note 18 / 28 GNSS Module Series 2.4. Send GPD Data to Module Flash Once the master control of the terminal device obtains the GPD file, it communicates with the module through the serial port to complete the injection of GPD file. Start Host downloads GDP data from server N Successful? Y Total GPD data is downloaded Host sends GPD data (in 512-byte data blocks each time) Successful? Y Has the host sent N all GPD data? Y GPD data injection is completed End Figure 3: Send GPD Data to Module LC76F_AGNSS_Application_Note 19 / 28 GNSS Module Series 3 AGNSS Testing Procedures This chapter illustrates how to test the AGNSS feature with Quectel’s QGNSS tool. 3.1 Prerequisites Before testing the AGNSS function make sure to: 1. Connect the LC76F EVB to your computer. 2. Download the QGNSS tool and set the corresponding serial port number, baud rate, and the module’s model. 3. Create the account for Quectel AGNSS server 1), and connect to the AGNSS server via the QGNSS tool. In order to notice the improvement of TTFF duration due to the AGNSS feature, you could first get the fix duration without using AGNSS. After the testing procedure, you can compare the difference between TTFF results. NOTE 1) Contact Quectel’s Technical Support Team (support@quectel.com) for information on how to access Quectel AGNSS server. LC76F_AGNSS_Application_Note 20 / 28 GNSS Module Series 3.2 Procedures After the host obtains the AGNSS data (download it from the AGNSS server), it communicates with the module via a serial port to complete the AGNSS data injection. The data transfer procedure is as follows. Start Send command $PGKC149 No Received the ACK? Yes Send the GPD data to the module Send the command to switch the binary mode to NMEA mode No Received the ACK? Yes Send full cold start command $PGKC030,4,2*2A Send command $PGKC639 No Received the $PGKC001? Yes End Figure 4: Transmission Flow LC76F_AGNSS_Application_Note 21 / 28 GNSS Module Series Example: Blue: Send data Black bold: ACK information Black: NMEA data a) Host sends the $PGKC149 command to the module to switch the NMEA mode to binary mode. $PGKC149,1,9600*1D //ACK: AA F0 0C 00 01 00 95 00 03 9B 0D 0A b) The host sends GPD data to the module in 512-byte data blocks. //Host sends the first data packet (523 bytes) to the module: AA F0 0B 02 66 02 00 00 D0 80 6E 4E 01 01 FF FF D0 80 6E 4E 00 D2 1F 00 00 00 00 00 00 00 00 00 00 00 00 00 0A 00 00 00 …… //ACK AA F0 0C 00 03 00 00 00 01 0E 0D 0A //Host sends the second data packet (523 bytes) to the module: AA F0 0B 02 66 02 01 00 04 DB 7C 00 24 A7 FF 00 04 FC 00 5A 06 01 FF FF E0 80 6E 4E 00 D2 1F 00 00 00 00 00 00 00 00 00 …… //ACK AA F0 0C 00 03 00 01 00 01 0F 0D 0A //Host sends the third data packet (523 bytes) to the module: AA F0 0B 02 66 02 02 00 31 67 88 00 96 E6 20 00 B5 2C AA 00 45 A8 FF 00 EC FB 00 49 0B 01 FF FF E0 80 6E 4E FC D0 1F 00…… //ACK AA F0 0C 00 03 00 02 00 01 0C 0D 0A …… //Host sends the last data packet (523 bytes) to the module: AA F0 0B 02 66 02 06 00 02 55 02 00 65 6E BD 00 A1 8D 0B 00 C7 1E 0D 00 00 B6 67 00 A2 EF FF 00 0A 28 C3 00 26 0D 00 00…… //ACK AA F0 0C 00 03 00 06 00 01 08 0D 0A c) Host sends GPD data transmission end command to the module: AA F0 0B 00 66 02 FF FF 6F 0D 0A LC76F_AGNSS_Application_Note 22 / 28 GNSS Module Series //ACK AA F0 0C 00 03 00 FF FF 01 0E 0D 0A d) Host sends the command to switch the binary mode to NMEA mode (9600 bps): AA F0 0E 00 95 00 00 80 25 00 00 3E 0D 0A //ACK AA F0 0C 00 01 00 95 00 03 9B 0D 0A $GNRMC,032324.000,A,3149.330359,N,11706.912790,E,0.00,0.00,180921,,,A,V*08 $GNVTG,0.00,T,,M,0.00,N,0.00,K,A*23 $GNGGA,032325.000,3149.330359,N,11706.912790,E,1,12,1.02,60.736,M,-0.337,M,,*5C $GNGLL,3149.330359,N,11706.912790,E,032325.000,A,A*47 $GNGSA,A,3,29,195,02,20,05,13,15,,,,,,2.15,1.02,1.90,1*39 $GNGSA,A,3,68,69,82,84,83,,,,,,,,2.15,1.02,1.90,2*03 $GPGSV,3,1,12,02,65,082,43,05,59,308,42,20,59,020,42,195,54,149,41,1*52 $GPGSV,3,2,12,13,52,175,43,50,42,134,38,29,36,310,40,15,29,210,40,1*69 $GPGSV,3,3,12,06,25,108,,30,15,095,,07,09,062,35,03,,,20,1*59 $GLGSV,2,1,05,83,69,110,28,69,62,251,41,68,54,017,38,84,40,336,26,1*70 $GLGSV,2,2,05,82,24,139,37,1*4E e) Host sends full cold start command: $PGKC030,4,2*2A $GNTXT,GK9501*7C $GNTXT,HW:V1901_B05*1F $GNTXT,SW:V2.0_Sep 15 2021*25 $GNTXT,GNSS_Mode:GG*32 $GNTXT,NMEA_Format:V4.10(UBX)*3F $GNGGA,004326.264,,,,,0,00,,,,,,,*65 $GNGLL,,,,,,V,N*7A $GNGSA,A,1,,,,,,,,,,,,,,,,1*1D $GNGSA,A,1,,,,,,,,,,,,,,,,2*1E $GPGSV,1,1,00,1*64 $GLGSV,1,1,00,1*78 $GNRMC,004326.264,V,,,,,0.00,,,,,N,V*34 f) Host sends the $PGKC639 command to the module to set Latitude, Longitude, Height, Year, Month, Day, and UTC time data: $PGKC639,31.822234,117.115230,59,2021,9,17,06,51,0*33 $GNGLL,,,,,,V,N*7A $GNGSA,A,1,,,,,,,,,,,,,,,,1*1D $GNGSA,A,1,69,84,68,,,,,,,,,,,,,2*13 LC76F_AGNSS_Application_Note 23 / 28 GNSS Module Series //Module responds with $PGKC001 $PGKC001,639,3*21 $GNRMC,015429.459,V,,,,,0.00,,,,,N,V*34 $GNVTG,,,,,,,,,N*2E $GNGGA,015429.459,,,,,0,00,,,,,,,*65 $GNGSA,A,1,,,,,,,,,,,,,,,,1*1D $GNGSA,A,1,,,,,,,,,,,,,,,,2*1E $GPGSV,3,1,12,15,75,337,46,13,52,037,44,18,46,316,42,05,45,067,43,1*6C $GPGSV,3,2,12,24,34,174,,29,28,226,40,23,23,299,38,20,22,093,,1*67 $GPGSV,3,3,12,02,16,148,,11,08,141,,30,06,039,,193,,,41,1*62 $GLGSV,2,1,05,75,,,,70,,,,65,,,,85,,,,1*75 $GLGSV,2,2,05,74,,,,1*7E $GNGLL,,,,,,V,N*7A $GNRMC,015431.099,V,,,,,0.10,,,,,N,V*34 $GNVTG,,,,,,,,,N*2E $GNGGA,015431.099,,,,,0,06,,,,,,,*62 $GNGSA,A,1,18,29,23,05,13,15,,,,,,,,,,1*1D $GNGSA,A,1,,,,,,,,,,,,,,,,2*1E $GPGSV,4,1,13,15,75,337,46,13,52,037,44,18,46,316,42,05,45,067,43,1*6A $GPGSV,4,2,13,42,45,140,,24,34,174,,29,28,226,40,23,23,299,38,1*6B $GPGSV,4,3,13,20,22,093,,02,16,148,,11,08,141,,30,06,039,,1*62 $GPGSV,4,4,13,193,,,41,1*58 $GLGSV,2,1,05,75,,,,70,,,,65,,,,85,,,,1*75 $GLGSV,2,2,05,74,,,,1*7E $GNGLL,,,,,,V,N*7A $GNRMC,015432.079,V,,,,,0.09,,,,,N,V*31 $GNVTG,,,,,,,,,N*2E $GNGGA,015432.079,,,,,0,06,,,,,,,*6F $GNGSA,A,1,18,29,23,05,13,15,,,,,,,,,,1*1D $GNGSA,A,1,,,,,,,,,,,,,,,,2*1E $GPGSV,4,1,13,15,75,337,46,13,52,037,44,18,46,316,42,05,45,067,43,1*6A $GPGSV,4,2,13,42,45,140,,24,34,174,,29,28,226,40,23,23,299,38,1*6B $GPGSV,4,3,13,20,22,093,,02,16,148,,11,08,141,,30,06,039,,1*62 $GPGSV,4,4,13,193,,,41,1*58 $GLGSV,2,1,05,75,,,,70,,,,65,,,,85,,,,1*75 $GLGSV,2,2,05,74,,,,1*7E $GNGLL,,,,,,V,N*7A // 1st second //2nd second //3rd second //Module gets a fix in the 4th second $GNRMC,015434.000,A,3149.322264,N,11706.899322,E,0.00,0.00,131121,,,A,V*0A $GNVTG,0.00,T,,M,0.00,N,0.00,K,A*23 $GNGGA,015434.000,3149.322264,N,11706.899322,E,1,06,1.38,60.399,M,-0.338,M,,*5F $GNGSA,A,3,18,29,23,05,13,15,,,,,,,1.67,1.38,0.94,1*06 LC76F_AGNSS_Application_Note 24 / 28 GNSS Module Series $GNGSA,A,3,,,,,,,,,,,,,1.67,1.38,0.94,2*05 $GPGSV,4,1,13,15,75,337,46,13,52,037,44,18,46,316,42,05,45,067,43,1*6A $GPGSV,4,2,13,42,45,140,,24,34,174,,29,28,226,40,23,23,299,38,1*6B $GPGSV,4,3,13,20,22,093,,02,16,148,,11,08,141,,30,06,039,,1*62 $GPGSV,4,4,13,193,,,41,1*58 $GLGSV,2,1,05,75,,,,70,,,,65,,,,85,,,,1*75 $GLGSV,2,2,05,74,,,,1*7E $GNGLL,3149.322264,N,11706.899322,E,015434.000,A,A*46 3.2.1. Simplified Procedure of Satellite Data Transfer via QGNSS Tool The simplified procedure of testing AGNSS feature is illustrated as following: a) Execute the QGNSS tool. b) In the main interface, click 'AGNSS' -> 'Assistant GNSS Offline' to enter the Download window. c) Click the 'Connect' button to connect the FTP server. d) Click the 'Download selected file' button to download the GPD file to your computer. e) Click the '…' button to select the GPD file. f) Click the 'Download' button to download the GPD file to module. g) Enter latitude and longitude manually or check the 'Use Current Position' option to auto-fill the information. h) Check the 'Use Current' to auto-fill the information about UTC. i) Select 'Full cold start' mode, click the 'Transfer' button to send position, time information and restart command to module. Figure 5: Simplified Testing Procedure via QGNSS Tool LC76F_AGNSS_Application_Note 25 / 28 GNSS Module Series Figure 6: Log of Testing AGNSS Feature via QGNSS Tool 3.3 Results When the GNSS engine is started, the module will try to obtain a position fix. After a cold start, if the AGNSS feature is not enabled, the module gets a position fix in about 25–30 s. If the AGNSS feature is enabled, the module gets a position fix in about 6 s or less. LC76F_AGNSS_Application_Note 26 / 28 GNSS Module Series 4 Appendix A References Table 8: Related Document Document Name [1] Quectel_LC76F_GNSS_Protocol_Specification Table 9: Terms and Abbreviations Abbreviation ACK AGNSS EVB FTP GPD GNSS NMEA UTC TTFF Description Acknowledgement Assisted GNSS Evaluation Board File Transfer Protocol Geographic Position Data Global Navigation Satellite System NMEA (National Marine Electronics Association) 0183 Interface Standard Coordinated Universal Time Time to First Fix LC76F_AGNSS_Application_Note 27 / 28 GNSS Module Series 5 Appendix B Special Characters Table 10: Special Characters Special Character Definition Carriage return character. Line feed character. Parameter name. Angle brackets do not appear in the message. [...] Optional field of a message. Square brackets do not appear in the message. {…} Repeated field of a message. Curly brackets do not appear in the message. Underline Default setting of a parameter. LC76F_AGNSS_Application_Note 28 / 28

Quectel_LC76F_AGNSS_Application_Note_V1.1

PDF

378.90 KB

EG800Q&EG91xQ Series Wi-Fi Scan Application Note LTE Standard Module Series Version: 1.1 Date: 2023-08-25 Status: Released LTE Standard 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. EG800Q&EG91xQ_Series_Wi-Fi_Scan_Application_Note 1 / 11 LTE Standard 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. 2023. All rights reserved. EG800Q&EG91xQ_Series_Wi-Fi_Scan_Application_Note 2 / 11 LTE Standard Module Series About the Document Revision History Version 1.0 Date 2023-04-13 2023-05-16 Author Alwyn YE Alwyn YE 1.1 2023-08-25 Alwyn YE Description Creation of the document First official release Updated the applicable modules: ⚫ Added EG916Q-GL. ⚫ Updated EG800Q-EU to EG800Q series. EG800Q&EG91xQ_Series_Wi-Fi_Scan_Application_Note 3 / 11 LTE Standard Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 5 1 Introduction .......................................................................................................................................... 6 2 Related AT Command.......................................................................................................................... 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 Related AT Command ...................................................................................... 8 2.3.1. AT+QWIFISCAN Set Wi-Fi Scan Parameters............................................................... 8 3 Appendix References ........................................................................................................................ 11 EG800Q&EG91xQ_Series_Wi-Fi_Scan_Application_Note 4 / 11 LTE Standard Module Series Table Index Table 1: Types of AT Commands ................................................................................................................. 7 Table 2: Terms and Abbreviations ..............................................................................................................11 EG800Q&EG91xQ_Series_Wi-Fi_Scan_Application_Note 5 / 11 LTE Standard Module Series 1 Introduction This document outlines Wi-Fi Scan-related AT command. It is applicable to Quectel EG800Q series, EG915Q-NA and EG916Q-GL modules. EG800Q&EG91xQ_Series_Wi-Fi_Scan_Application_Note 6 / 11 LTE Standard Module Series 2 Related AT Command 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 Execution 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. AT+ Return a specific information parameter or perform a specific action. EG800Q&EG91xQ_Series_Wi-Fi_Scan_Application_Note 7 / 11 LTE Standard 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 Related AT Command 2.3.1. AT+QWIFISCAN Set Wi-Fi Scan Parameters This command sets Wi-Fi Scan parameters. AT+QWIFISCAN Set Wi-Fi Scan Parameters Test Command AT+QWIFISCAN=? Response +QWIFISCAN: (range of supported s),(range of supported s),(range of supported s),(range of supported s),(list of supported s) Read Command AT+QWIFISCAN? OK Response +QWIFISCAN: ,,,, OK Write Command AT+QWIFISCAN[=[,[,[,[,]]]]] Response If parameters are set successfully, scanning result is reported: OK +QWIFISCAN: (,,,,) OK If there is no Wi-Fi hotspot: OK +QWIFISCAN:TIMEOUT EG800Q&EG91xQ_Series_Wi-Fi_Scan_Application_Note 8 / 11 LTE Standard Module Series Maximum Response Time Characteristics If parameter value(s) exceed(s) the supported range: +CME ERROR: 50 If more than 5 parameters are set: ERROR 13 s This command takes effect immediately. The configurations are not saved. Parameter Integer type. Wi-Fi Scan time. +QWIFISCAN:TIMEOUT will be reported, if there is no scanning result after the time. Range: 4000–255000. Default value: 12000. Unit: millisecond. Integer type. Number of Wi-Fi Scan round(s). Range: 1–3. Default value: 1. Integer type. Expected number of scanned Wi-Fi hotspots. Range: 4–10. Default value: 5. Integer type. RRC polling timeout period of Wi-Fi Scan. Range: 0–255. Default value: 5. Unit: second. Integer type. Wi-Fi Scan prioritization parameter. 0 Data prioritization 1 Wi-Fi Scan prioritization Wi-Fi hotspot encryption mode. Currently this parameter is not supported and the fixed value is '-'. Name of the connected Wi-Fi hotspot. Currently this parameter is not supported and the fixed value is '-'. Integer type. Signal strength of the Wi-Fi hotspot. Unit: dBm. String type. Wi-Fi hotspot MAC address. Integer type. Channel used by the Wi-Fi hotspot. Range: 1–13. NOTE The Parameter specifies the number of reported MAC addresses. For instance: ⚫ Set the number of Wi-Fi Scan rounds to 1 and the expected number of scanned Wi-Fi hotspots to 5. If 5 or more MAC addresses are scanned, only 5 of them will be reported. If 5 MAC addresses or less are scanned, all of them will be reported. ⚫ Set the number of Wi-Fi Scan rounds to 3 and the expected number of scanned Wi-Fi hotspots to 10. If 10 MAC addresses or more are scanned at the first round, then 10 MAC addresses will be reported, and the second and third rounds of scanning will not proceed. If 5 MAC addresses are scanned at the first round, Wi-Fi Scan continues; the scanning proceeds if 3 MAC addresses are scanned at the second round; if 6 MAC addresses are scanned at the third round, then the results EG800Q&EG91xQ_Series_Wi-Fi_Scan_Application_Note 9 / 11 LTE Standard Module Series of the three rounds of scanning (5 + 3 + 6) will be reported. If the total number of MAC addresses at the first and second rounds exceeds 10, the third round of scanning will not proceed. If there are identical MAC addresses, the duplicate data will be subtracted. Example AT+QWIFISCAN OK +QWIFISCAN: (-,-,-30,'1C:20:DB:8D:D7:80',1) +QWIFISCAN: (-,-,-30,'1C:20:DB:8D:D7:81',1) +QWIFISCAN: (-,-,-55,'1C:20:DB:8D:C2:81',1) +QWIFISCAN: (-,-,-61,'44:00:4D:D5:26:01',1) +QWIFISCAN: (-,-,-68,'A4:00:E2:EF:F8:80',1) OK AT+QWIFISCAN=12000,1,6,5,0 OK +QWIFISCAN: (-,-,-35,'1C:20:DB:8D:D7:80',1) +QWIFISCAN: (-,-,-35,'1C:20:DB:8D:D7:81',1) +QWIFISCAN: (-,-,-58,'60:38:E0:C5:A6:49',6) +QWIFISCAN: (-,-,-63,'A4:00:E2:EF:F8:81',1) +QWIFISCAN: (-,-,-66,'44:00:4D:D5:26:00',1) +QWIFISCAN: (-,-,-70,'44:00:4D:D5:23:60',6) OK //Wi-Fi scan without Wi-Fi hotspot. AT+QWIFISCAN OK +QWIFISCAN:TIMEOUT EG800Q&EG91xQ_Series_Wi-Fi_Scan_Application_Note 10 / 11 LTE Standard Module Series 3 Appendix References Table 2: Terms and Abbreviations Abbreviation MAC RRC RSSI Description Medium Access Control Radio Resource Control Received Signal Strength Indicator EG800Q&EG91xQ_Series_Wi-Fi_Scan_Application_Note 11 / 11

Quectel_EG800Q&EG91xQ_Series_Wi-Fi_Scan_Application_Note_V1.1

PDF

135.36 KB

EC200U&EG91xU Series Camera Application Note LTE Standard Module Series Version: 1.2 Date: 2023-05-10 Status: Released LTE Standard 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. EC200U&EG91xU_Series_Camera_Application_Note 1 / 14 LTE Standard 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. 2023. All rights reserved. EC200U&EG91xU_Series_Camera_Application_Note 2 / 14 LTE Standard Module Series About the Document Revision History Version 1.0 1.1 Date 2021-06-03 2021-07-27 2021-08-17 Author Evan MENG Evan MENG Evan MENG 1.2 2023-05-10 Sum LI Description Creation of the document First official release Added an applicable module series EG915U. 1. Added an applicable module EG912U-GL. 2. Added the values of in URC reporting decoding results (Chapter 2.3.2.1). EC200U&EG91xU_Series_Camera_Application_Note 3 / 14 LTE Standard Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 1.1. Applicable Modules .................................................................................................................... 6 2 Camera Related 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. AT Command Details ................................................................................................................. 8 2.3.1. AT+QCAMOPEN Turn on Camera Function ............................................................... 8 2.3.2. AT+QCAMIDFY Start/Stop Decoding .......................................................................... 9 2.3.2.1. URC Reporting Decoding Results ..................................................................... 10 2.3.3. AT+QCAMCLOSE Turn off Camera Function ........................................................... 10 2.3.4. AT+QCAMAPPVER Get Decoding Library Version Information ............................... 11 2.3.5. AT+QAUTHCODE Read and Write Authorization Code of Decoding Library........... 12 3 Error Codes ....................................................................................................................................... 14 EC200U&EG91xU_Series_Camera_Application_Note 4 / 14 LTE Standard Module Series Table Index Table 1: Applicable Modules ........................................................................................................................ 6 Table 2: Types of AT Commands ................................................................................................................ 7 Table 3: Description of +CME ERROR: ........................................................................................... 14 EC200U&EG91xU_Series_Camera_Application_Note 5 / 14 LTE Standard Module Series 1 Introduction This document introduces camera related AT commands of Quectel EC200U and EG91xU family modules. 1.1. Applicable Modules Table 1: Applicable Modules Module Family - EG91xU Module EC200U Series EG912U-GL EG915U Series EC200U&EG91xU_Series_Camera_Application_Note 6 / 14 LTE Standard Module Series 2 Camera Related 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. EC200U&EG91xU_Series_Camera_Application_Note 7 / 14 LTE Standard 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 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 Command Details 2.3.1. AT+QCAMOPEN Turn on Camera Function AT+QCAMOPEN Turn on Camera Function Test Command AT+QCAMOPEN=? Response +QCAMOPEN: (range of supported s),(range of supported s) Write Command AT+QCAMOPEN=, OK Response OK Maximum Response Time Characteristic If there is any error related to ME functionality: +CME ERROR: 500 ms The command takes effect immediately. The configurations will not be saved. Parameter Integer type. The height of the image. Range: 50–480. Unit: pixel. Integer type. The width of the image. Range: 50–640. Unit: pixel. Integer type. Error code. See Chapter 3 for details. EC200U&EG91xU_Series_Camera_Application_Note 8 / 14 LTE Standard Module Series ⚫NOTE 1. When the camera is not recognized, this command returns error code 7300. 2. If all the functions of the module are supported, the space allocated to the camera will be limited. At this time, the range of the will be 50–240, and the range of the will be 50–320. 2.3.2. AT+QCAMIDFY Start/Stop Decoding AT+QCAMIDFY Start/Stop Decoding Test Command AT+QCAMIDFY=? Response +QCAMIDFY: (list of supported s),(range of supported s) Write Command AT+QCAMIDFY= OK Response OK Maximum Response Time Characteristic If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. The configurations will not be saved. Parameter Integer type. Start/stop decoding. 0 Stop decoding. 1 Start decoding. Integer type. Sets the times of decoding. Decoding will stop when the times of decoding reaches the set value. Range: 0–255. The value is 0 by default, which indicates there is no limitation on the times of decoding. Integer type. Error code. See Chapter 3 for details. EC200U&EG91xU_Series_Camera_Application_Note 9 / 14 LTE Standard Module Series 2.3.2.1. URC Reporting Decoding Results URC Reporting Decoding Results +QCAMPRES: ,,, Reporting Decoding Results Parameter Integer type. Decoding Results. 0 Successful decoding. 1 No decoding library. Other value Decoding failure. Integer type. One-dimensional code or two-dimensional code to be decoded. Decoding type output varies with different decoding libraries. 0 CODE39 (Barcode) 1 CODE128 (Barcode) 2 CODE_QR (QR code) 0xff Unknown type Integer type. The length of data to be decoded. Unit: byte. Data to be decoded. The output result is related to the decoding library. Example AT+QCAMOPEN=480,640 OK AT+QCAMIDFY=1 OK +QCAMPRES: 0,1,6,456789 2.3.3. AT+QCAMCLOSE Turn off Camera Function AT+QCAMCLOSE Turn off Camera Function Test Command AT+QCAMCLOSE=? Write Command AT+QCAMCLOSE Response OK Response OK Maximum Response Time 300 ms EC200U&EG91xU_Series_Camera_Application_Note 10 / 14 LTE Standard Module Series Characteristic Example AT+QCAMOPEN=240,320 OK AT+QCAMIDFY=1 OK +QCAMPRES: 0,1,6,456789 AT+QCAMCLOSE OK The command takes effect immediately. The configurations will not be saved. 2.3.4. AT+QCAMAPPVER Get Decoding Library Version Information AT+QCAMAPPVER Get Decoding Library Version Information Test Command AT+QCAMAPPVER=? Write Command AT+QCAMAPPVER Response OK Response +QCAMAPPVER: Maximum Response Time Characteristic OK 300 ms The command takes effect immediately. The configurations will not be saved. Parameter Version information of the decoding library. EC200U&EG91xU_Series_Camera_Application_Note 11 / 14 LTE Standard Module Series 2.3.5. AT+QAUTHCODE Read and Write Authorization Code of Decoding Library This command reads and writes the authorization code of the decoding library. When the decoding library runs, it reads the authorization code for verification. If the verification passes, the complete decoding result will be output. AT+QAUTHCODE Read and Write Authorization Code of Decoding Library Test Command AT+QAUTHCODE=? Response +QAUTHCODE: (list of supported s),(range of supporteds), OK Write Command AT+QAUTHCODE=,[,] Response If =1 and is ommitted, read the authorization code of decoding library: +QAUTHCODE: OK If =2 and is specified, write the authorization code of decoding library: +QAUTHCODE: OK Maximum Response Time Characteristic If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. The configurations will not be saved. Parameter Integer type. 1 Read the authorization code. 2 Write the authorization code. Integer type. The length of the authorization code to be read or written. Range: 0–108. Unit: byte. String type. Authorization code. Integer type. Error code. See Chapter 3 for details. EC200U&EG91xU_Series_Camera_Application_Note 12 / 14 Example AT+QAUTHCODE=2,20,'1234567890asdfghjk#l' +QAUTHCODE: '1234567890asdfghjk#l' OK AT+QAUTHCODE=1,20 +QAUTHCODE: '1234567890asdfghjk#l' OK LTE Standard Module Series EC200U&EG91xU_Series_Camera_Application_Note 13 / 14 LTE Standard Module Series 3 Error Codes Table 3: Description of +CME ERROR: Code of 7100 7200 7300 7400 Description Unknown error Parameter error Initialization error Decoding error EC200U&EG91xU_Series_Camera_Application_Note 14 / 14

Quectel_EC200U&EG91xU_Series_Camera_Application_Note_V1.2

PDF

200.22 KB

EG800Q&EG91xQ Series QuecCell Application Note LTE Standard Module Series Version: 1.1 Date: 2023-08-25 Status: Released LTE Standard 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. EG800Q&EG91xQ_Series_QuecCell_Application_Note 1 / 13 LTE Standard 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. 2023. All rights reserved. EG800Q&EG91xQ_Series_QuecCell_Application_Note 2 / 13 LTE Standard Module Series About the Document Revision History Version Date Author - 2023-04-13 Alwyn YE 1.0 2023-05-06 Alwyn YE 1.1 2023-08-25 Alwyn YE Description Creation of the document First official release Updated the applicable modules: ⚫ Added EG916Q-GL. ⚫ Updated EG800Q-EU to EG800Q series. EG800Q&EG91xQ_Series_QuecCell_Application_Note 3 / 13 LTE Standard Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 2 Description of 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. AT+QENG Get Information of Primary Serving Cell and Neighbour Cells ............................. 8 2.4. AT+QCELL Get Information of Serving Cell and Neighbour Cells ....................................... 11 3 Appendix References ....................................................................................................................... 13 EG800Q&EG91xQ_Series_QuecCell_Application_Note 4 / 13 LTE Standard Module Series Table Index Table 1: Types of AT Commands ................................................................................................................ 7 Table 2: Terms and Abbreviations ............................................................................................................. 13 EG800Q&EG91xQ_Series_QuecCell_Application_Note 5 / 13 LTE Standard Module Series 1 Introduction This document introduces AT commands related to QuecCell on Quectel EG800Q series, EG915Q-NA and EG916Q-GL modules. QuecCell is a featured function embedded in the module. It can be used to scan the detailed information of base stations. EG800Q&EG91xQ_Series_QuecCell_Application_Note 6 / 13 LTE Standard Module Series 2 Description of 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: Types of AT Commands Command Type Syntax Description Test Command AT+=? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Read Command AT+? 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. EG800Q&EG91xQ_Series_QuecCell_Application_Note 7 / 13 LTE Standard Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you familiarize with AT commands and learn how to use them. 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+QENG Get Information of Primary Serving Cell and Neighbour Cells This command gets the information of the primary serving cell and neighbour cells. AT+QENG Get Information of Primary Serving Cell and Neighbour Cells Test Command AT+QENG=? Response +QENG: (list of supported s) Write Command AT+QENG='servingcell' OK Response +QENG: 'servingcell',,'LTE',,,< MNC>,,,,,,,,,,< RSSI>,, Write Command AT+QENG='neighbourcell' OK Response [+QENG: 'neighbourcell intra','LTE',,, ,,-,-,-,-,-,[…]] [+QENG: 'neighbourcell inter','LTE',,, ,,-,-,-,-,-,[…]] Maximum Response Time Characteristics OK 300 ms / EG800Q&EG91xQ_Series_QuecCell_Application_Note 8 / 13 Parameter LTE Standard Module Series String type. Information of different cells. 'servingcell' Information of 4G serving cells 'neighbourcell' Information of 4G neighbour cells String type. UE state. 'SEARCH' UE is searching but could not (yet) find a suitable 4G cell 'LIMSRV' UE is camping on a cell but has not registered on the network 'NOCONN' UE has camped on a cell and registered on the network, and it is in idle state 'CONNECT' UE has camped on a cell and registered on the network, and a call is in progress String type. Communication mode. 'TDD' Time division duplex mode 'FDD' Frequency division duplex mode Integer type. Mobile country code (first part of the PLMN code). Integer type. Mobile network code (second part of the PLMN code). Hexadecimal format. Cell ID. Range: 0–0xFFFFFFF. Integer type. Physical cell identity. Range: 0–503. Integer type. E-UTRA absolute radio frequency channel number. Integer type. E-UTRA frequency band. (See 3GPP 36.101). Integer type. Uplink bandwidth. 0 1.4 MHz 1 3 MHz 2 5 MHz 3 10 MHz 4 15 MHz 5 20 MHz Integer type. Downlink bandwidth. 0 1.4 MHz 1 3 MHz 2 5 MHz 3 10 MHz 4 15 MHz 5 20 MHz Hexadecimal format. Tracking area code. Range: 0–0xFFFFFFFF. (See 3GPP 23.003 subclause 19.4.2.3). Integer type. Reference signal received power. Range: -156 to -44. Unit: dBm. (See 3GPP 36.214 subclause 5.1.1). Integer type. Reference signal received quality. Range: -34 to 2.5. Unit:dB. (See 3GPP 36.214 subclause 5.1.3). Integer type. Received signal strength indication. Range: -120 to -25. Unit: dBm. EG800Q&EG91xQ_Series_QuecCell_Application_Note 9 / 13 LTE Standard Module Series Integer type. Signal to interference plus noise ratio. Range: -20 to 40. Unit: dB. Integer type. Cell selection Rx level value. Unit: dB. (See 3GPP 25.304/3GPP 36.304). NOTE 1. After executing AT+QENG='neighbourcell', if intra-frequency neighbour cell is found, +QENG: 'neighbourcell intra','LTE',,,,,-,-,-,-,-,- is returned; if inter-frequency neighbour cell is found, +QENG: 'neighbourcell inter','LTE',,,,,-,-,-,-,-,- is returned. If intra-frequency neighbour cell is found, the information of intra-frequency neighbour cell is returned first; if intra-frequency neighbour cell is not found, only the information of inter-frequency neighbour cell is returned. 2. It indicates that the parameter is invalid under current conditions when '-' or - is returned. Example AT+QENG='servingcell' +QENG: 'servingcell','SEARCH' OK AT+QENG='servingcell' +QENG:'servingcell','NOCONN','LTE','FDD',460,11,B57DE09,352,100,1,5,5,B504,-85,-8,-70,13, 37 OK AT+QENG='neighbourcell' +QENG: 'neighbourcell intra','LTE',100,353,-20,-106,-,-,-,-,-,+QENG: 'neighbourcell intra','LTE',100,210,-20,-106,-,-,-,-,-,+QENG: 'neighbourcell inter','LTE',1850,63,-19,-88,-,-,-,-,-,+QENG: 'neighbourcell inter','LTE',1850,362,-20,-96,-,-,-,-,-,- OK EG800Q&EG91xQ_Series_QuecCell_Application_Note 10 / 13 LTE Standard Module Series 2.4. AT+QCELL Get Information of Serving Cell and Neighbour Cells This command gets the information of the serving cell and neighbour cells. AT+QCELL Get Information of Serving Cell and Neighbour Cells Test Command AT+QCELL=? Read Command AT+QCELL? Response OK Response +QCELL: 'servingcell','LTE',,,,,, [+QCELL: 'neighbourcell intra','LTE',,,< TAC>,,, […]] [+QCELL: 'neighbourcell inter','LTE',,,< TAC>,,, […]] OK Maximum Response Time 4 s Characteristics / Parameter Integer type. Mobile country code (the first part of the PLMN code). Integer type. Mobile network code (the second part of the PLMN code). Hexadecimal format. Tracking area code. Range: 0–0xffffffff. (See 3GPP 23.003 Section 19.4.2.3). Hexadecimal format. Cell ID. Range: 0–0xfffffff. Integer type. Physical cell identity. Range: 0–503. Integer type. Rx level in the cell. Range: 0–63. Unit: dB. (See 3GPP 25.304). EG800Q&EG91xQ_Series_QuecCell_Application_Note 11 / 13 LTE Standard Module Series NOTE 1. This command can only be executed when the (U)SIM card is not inserted or when the module is in the idle state with the (U)SIM card inserted; it is recommended to use the command when the (U)SIM card is not inserted. 2. After executing AT+QCELL?, if intra-frequency neighbour cell is found, +QCELL: 'neighbourcell intra','LTE',,,,,, is returned; if inter-frequency neighbour cell is found, +QCELL: 'neighbourcell inter','LTE',,,,,, is returned. If intra-frequency neighbour cell is found, the information of intra-frequency neighbour cell is returned first; if intra-frequency neighbour cell is not found, only the information of inter-frequency neighbour cell is returned. Example AT+QCELL? // Get the information of serving cell and neighbour cells. +QCELL: 'servingcell','LTE',460,00,550b,d6b5c0,123,36 +QCELL: 'neighbourcell inter','LTE',460,00,550b,5e05e2a,20,12 +QCELL: 'neighbourcell inter','LTE',460,00,550b,5c4ef29,121,25 OK EG800Q&EG91xQ_Series_QuecCell_Application_Note 12 / 13 LTE Standard Module Series 3 Appendix References Table 2: Terms and Abbreviations Abbreviation 3GPP DL EARFCN E-UTRA FDD LTE MCC MNC PCI PLMN RSRP RSRQ RSSI SINR TA TAC TDD UE UL UTRA Description The 3rd Generation Partnership Project Downlink E-UTRA Absolute Radio Frequency Channel Number Evolved-Universal Terrestrial Radio Access Frequency Division Duplex Long Term Evolution Mobile Country Code Mobile Network Code Physical Cell Identity Public Land Mobile Network Reference Signal Received Power Reference Signal Received Quality Received Signal Strength Indicator Signal to Interference Plus Noise Ratio Terminal Adapter Tracking Area Code Time Division Duplex User Equipment Uplink UMTS Terrestrial Radio Access EG800Q&EG91xQ_Series_QuecCell_Application_Note 13 / 13

Quectel_EG800Q&EG91xQ_Series_QuecCell_Application_Note_V1.1

PDF

214.17 KB

LC26G&LC76G&LC86G Series Low Power Mode Application Note GNSS Module Series Version: 1.0 Date: 2023-04-27 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. LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 1 / 23 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. 2023. All rights reserved. LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 2 / 23 GNSS Module Series About the Document Document Information Title LC26G&LC76G&LC86G Series Low Power Mode Application Note Subtitle GNSS Module Series Document Type Application Note Document Status Released Revision History Version 1.0 Date 2023-02-17 2023-04-27 Description Creation of the document First official release LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 3 / 23 GNSS Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 2 Low Power Modes............................................................................................................................. 11 2.1. Backup Mode ........................................................................................................................... 11 2.1.1. Operation Mechanism ................................................................................................... 11 2.1.2. Testing Procedures ....................................................................................................... 12 2.2. Periodic Mode .......................................................................................................................... 13 2.2.1. Operation Mechanism ................................................................................................... 13 2.2.2. Testing Procedures ....................................................................................................... 15 2.3. ALP Mode ................................................................................................................................ 16 2.3.1. Operation Mechanism ................................................................................................... 16 2.3.2. Testing Procedures ....................................................................................................... 16 2.3.2.1. Entering ALP mode after Power on ................................................................... 17 2.3.2.2. Entering ALP mode at Stable Satellite Search .................................................. 18 2.4. GLP Mode ................................................................................................................................ 19 2.4.1. Operation Mechanism ................................................................................................... 19 2.4.2. Testing Procedures ....................................................................................................... 20 2.5. FLP Mode................................................................................................................................. 20 2.5.1. Operation Mechanism ................................................................................................... 20 2.5.2. Testing Procedures ....................................................................................................... 21 3 Appendix References ....................................................................................................................... 22 LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 4 / 23 GNSS Module Series Table Index Table 1: Related Commands ....................................................................................................................... 7 Table 2: Navigation Modes .......................................................................................................................... 8 Table 3: Low Power Modes and Corresponding Configurations ................................................................. 9 Table 4: System Resources Utilized in Low Power Modes ....................................................................... 11 Table 5: Testing Environment in Backup Mode ......................................................................................... 12 Table 6: Testing Environment in Periodic Mode ........................................................................................ 15 Table 7: Testing Environment in ALP Mode – Entering ALP Mode after Power On ................................. 17 Table 8: Testing Environment in ALP Mode – at Stable Satellite Search ................................................. 18 Table 9: Related Documents...................................................................................................................... 22 Table 10: Terms and Abbreviations ........................................................................................................... 22 LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 5 / 23 GNSS Module Series Figure Index Figure 1: Enter/Exit Backup Mode Timing ................................................................................................. 12 Figure 2: Measured Power Consumption in Backup Mode ....................................................................... 13 Figure 3: Module Operation in Smart Periodic Mode ................................................................................ 14 Figure 4: Module Operation in Strict Periodic Mode .................................................................................. 14 Figure 5: Measured Power Consumption in Periodic Mode ...................................................................... 15 Figure 6: Module Operation in ALP Mode ................................................................................................. 16 Figure 7: Power Consumption Measured in ALP Mode after Power On ................................................... 18 Figure 8: Measured Power Consumption in ALP Mode at Stable Satellite Search .................................. 19 Figure 9: Operation Status in GLP Mode................................................................................................... 19 Figure 10: Operation Status in FLP Mode ................................................................................................. 20 LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 6 / 23 GNSS Module Series 1 Introduction The LC26G (AB), LC76G series and LC86G series modules support different low power modes with enhanced power consumption and outstanding positioning performances. This document describes the operation mechanisms and related testing procedures of Backup, Periodic, Adaptive Low Power (ALP), GPS Low Power (GLP), and Fitness Low Power (FLP) modes. Backup mode is an inactive state where the power consumption is reduced to a fraction of that in the other operating modes. Periodic mode consists of running (active) and sleeping stages, of which the time span can be adjusted to reduce power consumption. FLP mode extends GLP mode by adding more constellation combinations, while ALP mode is a subset of FLP mode that differs in navigation mode. The differences between GLP, FLP and ALP modes are detailed in Table 3: Low Power Modes. The relevant commands of the low power modes are listed below. For details, please refer to document [1] protocol specification. Table 1: Related Commands PAIR Command PAIR050 PAIR051 PAIR066 PAIR067 PAIR080 PAIR081 PAIR650 PAIR680 PAIR681 Description Sets position fix interval. Gets position fix interval. Sets the GNSS search mode. Gets the GNSS search mode. Sets navigation mode. Gets navigation mode. Enables Backup mode. Enables/disables GLP mode. Gets GLP mode setting. LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 7 / 23 PAIR Command PAIR690 PAIR691 PAIR730 PAIR731 PAIR732 PAIR733 GNSS Module Series Description Sets Periodic power saving mode configurations. Gets Periodic power saving mode configurations. Enables/disables FLP mode. Gets FLP mode setting. Enables/disables ALP mode. Gets ALP mode configuration setting. Table 2: Navigation Modes Navigation Mode Normal mode Fitness mode Swimming mode Drone mode Description Used for general purposes. Used for running and walking purposes, making low-speed movement (< 5 m/s) more impactful on position calculation. Used for swimming purposes to smooth the trajectory and improve the accuracy of distance calculation. Used for drone applications with equivalent dynamic range and vertical acceleration at different flight phases (for example, hovering, cruising). LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 8 / 23 GNSS Module Series The corresponding configurations of the low power modes supported by LC26G (AB), LC76G series and LC86G series are as follows: Table 3: Low Power Modes and Corresponding Configurations Type Backup mode Periodic mode Navigation Mode Constellation Option Fix Update Rate Supported Module ⚫ GPS only ⚫ GPS + QZSS ⚫ GPS + GLONASS ⚫ Normal mode ⚫ GPS + GLONASS + QZSS ⚫ GPS + Galileo ⚫ 1 Hz ⚫ Fitness mode ⚫ GPS + Galileo + QZSS ⚫ Swimming mode ⚫ GPS + BDS ⚫ Drone mode ⚫ GPS + BDS + QZSS ⚫ 2 Hz ⚫ 5 Hz ⚫ 10 Hz ⚫ GPS + GLONASS + Galileo + BDS ⚫ GPS + GLONASS + Galileo + BDS + QZSS ⚫ GPS only ⚫ GPS + QZSS ⚫ GPS + GLONASS ⚫ GPS + GLONASS + QZSS ⚫ Normal mode ⚫ GPS + Galileo ⚫ ⚫ Fitness mode ⚫ Swimming mode GPS + Galileo + QZSS ⚫ GPS + BDS ⚫ Drone mode ⚫ GPS + BDS + QZSS ⚫ 1 Hz ⚫ 2 Hz ⚫ 5 Hz ⚫ 10 Hz ⚫ GPS + GLONASS + Galileo + BDS ⚫ GPS + GLONASS + Galileo ⚫ LC26G (AB) ⚫ LC76G (AB, PA, PB) ⚫ LC86G (AA, AB, LA) ⚫ LC26G (AB) ⚫ LC76G (AB, PA, PB) ⚫ LC86G (AA, AB, LA) LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 9 / 23 Type ALP mode GLP mode FLP mode GNSS Module Series Navigation Mode ⚫ Normal mode ⚫ Fitness mode ⚫ Fitness mode Constellation Option + BDS + QZSS Fix Update Rate Supported Module ⚫ GPS + GLONASS ⚫ GPS + GLONASS + QZSS ⚫ GPS + GLONASS + Galileo ⚫ 1 Hz + BDS ⚫ GPS + GLONASS + Galileo + BDS + QZSS ⚫ GPS only ⚫ 1 Hz ⚫ GPS + BDS ⚫ GPS + BDS + QZSS ⚫ GPS + GLONASS ⚫ GPS + GLONASS + QZSS ⚫ 1 Hz ⚫ GPS + GLONASS + Galileo + BDS ⚫ GPS + GLONASS + Galileo + BDS + QZSS ⚫ LC26G (AB) with LC26GABNR12A01S or higher versions. ⚫ LC76G (AB) with LC76GABNR12A01S, LC76G (PA) with LC76GPANR02A02S and LC76G (PB) with LC76GPBNR02A02S or higher versions. ⚫ LC86G (AA, AB), LC86G (LA) with LC86GLANR02A02S or higher versions. ⚫ LC26G (AB) ⚫ LC76G (AB, PA, PB) ⚫ LC86G (AA, AB, LA) ⚫ LC26G (AB) ⚫ LC76G (AB, PA, PB) ⚫ LC86G (AA, AB, LA) NOTE 1. The navigation mode, GNSS satellite configuration and fix update rate are the prerequisites for the operation of the low power modes. If the module is not in tracking mode that matches one of the available navigation profiles, it cannot support low power modes. 2. For LC76G (PA, PB) modules, the fix update rate can only be 1 Hz. LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 10 / 23 GNSS Module Series 2 Low Power Modes To extend battery operation time and meet customer requirements, the module supports several low power modes. Table 4: System Resources Utilized in Low Power Modes System Periodic Periodic Backup ALP GLP FLP Resource (Running Stage) (Sleeping Stage) RTC Macro ● ● ● ● ● ● RTC SRAM ● ● Internal - ● Circuits CPU core - ● ● ● ● ● ● ● ● ● ● ● ● ● SRAM - ● ● ● ● ● TCXO - ● ● ● ● ● GPIO - ● ● ● ● ● RF - ● - ● ● ● 2.1. Backup Mode 2.1.1. Operation Mechanism Backup mode is used to improve power efficiency. It shuts down most system components, such as RF controller, processing engine DSP, CPU core and so on. As a result, while the module is in Backup mode, the module's communication port is unresponsive to any incoming commands and no data is transmitted over it. Before it enters the Backup mode, the module saves navigation data, including ephemeris, almanac, location and time to RTC SRAM for the next navigation cycle to shorten the TTFF. The CPU core can be awoken by either setting the timer or powering on the VCC pin. For details, refer to document [1] protocol specification and documents [2], [3], [4] hardware designs. Once the CPU core exits the Backup mode, the navigation data will be loaded from RTC SRAM. If all the data is valid, a shorter TTFF can be achieved. LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 11 / 23 GNSS Module Series The timing sequence of the Backup mode is as follows: V_BCKP Enter Backup mode Low power consumption Exit Backup mode VCC RESET_N below 100 mv 1 s 100 ms Communication Port Valid Invalid Backup mode Cut off VCC Send command Restore VCC Pull RESET_N low Valid Figure 1: Enter/Exit Backup Mode Timing 2.1.2. Testing Procedures To enter the Backup mode: ⚫ Power up the module and make sure both VCC and V_BCKP are powered. ⚫ Send $PAIR650 and disconnect the VCC power supply to enter the Backup mode. The module returns $PAIR001,650,0*38 when it enters the Backup mode. To exit the Backup mode: ⚫ Restore VCC power. ⚫ Drive the RESET_N low for at least 100 ms. Table 5: Testing Environment in Backup Mode Item Module Voltage RF Signal Strength Equipment Command Execution Time Axis Description LC76G (PA) 3.3 V -130 dBm Keysight 66319B Dual Mobile Comm DC Source w/ Battery Emulation $PAIR650,0*25 After the module gets a fix. Vertical axis: current consumption (μA) Horizontal axis: duration (seconds/minutes) LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 12 / 23 GNSS Module Series Data Log Display Current Drain(μA) 35.01 19.85 4.69 0.00 msec 9.92 sec Current 19.83 sec 29.75 sec 39.66 sec Run Time Average 14.489 μA 49.58 sec -10.47 59.50 sec Marker (Delta) Time: 29.99 Second Figure 2: Measured Power Consumption in Backup Mode 2.2. Periodic Mode 2.2.1. Operation Mechanism In the Periodic mode, power consumption can be reduced by turning off the DSP and periodically putting the CPU core to sleep. The running time and the sleeping time can be defined by users based on their needs. ⚫ During the running time, the DSP and CPU core are active and perform their respective tasks, while the GNSS module generates the position-related information. ⚫ During the sleeping time, the DSP is paused while the CPU core is in the sleeping stage. The time span of the running (active) and sleeping stages can be dynamically changed or strictly limited, i.e., Smart Periodic Mode and Strict Periodic Mode. In Smart Periodic mode, the module observes the current satellite signal status, satellite health status, collected ephemeris status, etc., to determine the time needed to collect ephemeris data. Therefore, when $PAIR690 is implemented, the system will automatically adjust the extension time to collect the required ephemeris data, increasing the likelihood that the position will be available immediately after the module wakes up from sleep. To shorten TTFF after waking up, it is recommended to use Smart Periodic mode to dynamically change the time span of the running stage to obtain more navigation information, such as pseudorange, ephemeris, and almanac. In Strict Periodic mode the duration of every cycle is fixed because the time span of the running stage is limited to a specific value. This fixed time span means that the module may not be able to complete satellite data update, such as ephemeris, within a single cycle, could potentially affect the TTFF. LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 13 / 23 GNSS Module Series Periodic pattern schematic diagram with different colors representing specific stages: ⚫ Blue: module is in running (active) stage and the GNSS signal is good. ⚫ Red: module is in sleeping stage and the GNSS signal is good. ⚫ Yellow: module is in running (active) stage and there is no GNSS signal. ⚫ Green: module is in sleeping stage and there is no GNSS signal. ⚫ Brown: the extension time of running (active) stage. Module operation in Smart Periodic mode is illustrated in the following figure: With signal Without signal $PAIR690,1,,,,* Good GNSS Signal Power Extension time No GNSS Signal Figure 3: Module Operation in Smart Periodic Mode Module operation in Strict Periodic mode is illustrated in the following figure: With signal Without signal $PAIR690,2,,,,* Power Good GNSS Signal No GNSS Signal Figure 4: Module Operation in Strict Periodic Mode LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 14 / 23 GNSS Module Series 2.2.2. Testing Procedures To enter the Periodic mode: ⚫ Power on the module. ⚫ Send $PAIR690 to enter the Periodic mode. The module returns $PAIR001,690,0*34 when it enters the Periodic mode. To exit the Periodic mode: Send $PAIR690,0*29 to exit the Periodic mode. Table 6: Testing Environment in Periodic Mode Item Module Voltage RF Signal Strength Equipment Command Execution Time Axis Description LC76G (PA) 3.3 V -130 dBm Keysight 66319B Dual Mobile Comm DC Source w/ Battery Emulation $PAIR690,2,10,30,30,40*2E After the module gets a fix. Vertical axis: current consumption (mA) Horizontal axis: duration (seconds/minutes) Data Log Display Current Drain(mA) 18.21 11.62 5.02 X1 0.00 mse c 39.00 se c 1.30 min Current 1.95 min Run Time Average 3.785 mA 2.60 min -1.58 3.25 min 3.90 min Marker ( Delta) Time: 3. 33 Minute Figure 5: Measured Power Consumption in Periodic Mode LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 15 / 23 GNSS Module Series 2.3. ALP Mode 2.3.1. Operation Mechanism In the ALP mode, power is saved by using duty cycles, but the position quality is degraded compared to that in normal tracking mode. The receiver outputs positioning solution at every epoch. ALP mode working status per second Calculate positioning information Positioning Stage (PE) Idle Stage Measuring Stage (ME) Receive satellite observations ALP mode working status per second Calculate positioning information Positioning Stage (PE) Idle Stage Measuring Stage (ME) Receive satellite observations Time Figure 6: Module Operation in ALP Mode As shown above, the ALP mode consists of three stages: ⚫ Measuring Stage: ME receives satellite observations. ⚫ Positioning Stage: PE calculates positioning information. ⚫ Idle Stage: the module is in idle stage. In the ALP mode, the module searches for satellites and adjusts the search time according to the actual conditions to achieve better positioning results while minimizing power consumption. This means that the satellite search time can be extended when satellite availability and signal quality are weak and the satellite search time can be shortened when satellite availability and signal quality are good. 2.3.2. Testing Procedures Please refer to Table 3: Low Power Modes before performing the following test. To enter the ALP mode: 1. Power on the module. 2. Send $PAIR066 to switch GNSS satellite configuration. 3. Send $PAIR080 to switch the navigation mode of the module. 4. Send $PAIR732 to enter ALP mode. Once the module returns $PAIR001,732,0*3D, the module enters the ALP mode. To exit the ALP mode: Send $PAIR732,0*20 to exit the ALP mode. LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 16 / 23 GNSS Module Series 2.3.2.1. Entering ALP mode after Power on When the module enters the ALP mode after being powered on, it does not immediately reduce power consumption. The module uses ME and PE at full performance, resulting in the shortest possible TTFF and the highest sensitivity. It searches for all possible satellites until the almanac is completely downloaded. When there is enough ephemeris data and almanac data, the module gradually reduces power consumption When the ephemeris and almanac data are completely downloaded, the power consumption of the module will gradually stabilize. Detailed process is as follows: 1. To achieve a good positioning performance, the module continuously searches for GNSS satellite signals after startup, and its ME engine and PE engine consume most of the time. Power consumption is the highest in this phase. 2. Once the module receives enough GNSS satellite data, it gradually reduces the usage of ME and PE. In this phase, the power consumption of the module gradually decreases. 3. After transmitting the complete almanac (which takes about 12.5 min) the power consumption of the module stabilizes. ME and PE dynamically adjust based on the quality of the received signals in this phase. To reduce the satellite search time and to speed up the module’s entry into the ALP mode, you can send $PAIR511*3F to save the ephemeris and almanac data to flash memory after each satellite search or before the module is turned off, to avoid data loss due to time or power failure. If the V_BCKP power supply is available, the ephemeris and almanac data can also be saved by entering the Backup mode. Table 7: Testing Environment in ALP Mode – Entering ALP Mode after Power On Item Module Voltage RF Signal Strength Equipment Command Execution Time Axis Description LC76G (PA) 3.3 V -130 dBm Keysight 66319B Dual Mobile Comm DC Source w/ Battery Emulation $PAIR732,1*21 Immediately after the module is powered on. Vertical axis: current consumption (mA) Horizontal axis: duration (seconds/minutes) LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 17 / 23 GNSS Module Series Data Log Display Current Drai n(mA) 16.42 9.31 2.21 0.00 msec 5.00 min Current 10.00 min 15.00 min Run Time Average 6.847 mA 20.00 min -4.90 25.00 min 30.00 min Marker (Delt a) Time: 29.98 Minute Figure 7: Power Consumption Measured in ALP Mode after Power On 2.3.2.2. Entering ALP mode at Stable Satellite Search Three conditions should be met before sending $PAIR066, $PAIR080 and $PAIR732 to allow module to quickly reduce power consumption after entering the ALP mode. ⚫ A valid position is obtained. ⚫ The entire almanac has been downloaded. ⚫ The ephemeris for each satellite in view is valid. Table 8: Testing Environment in ALP Mode – at Stable Satellite Search Item Module Voltage RF Signal Strength Equipment Command Execution Time Axis Description LC76G (PA) 3.3 V -130 dBm Keysight 66319B Dual Mobile Comm DC Source w/ Battery Emulation $PAIR732,1*21 15 minutes after the module is powered on. Vertical axis: current value (mA) Horizontal axis: duration (seconds/minutes) LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 18 / 23 GNSS Module Series Data Log Display Current Drai n(mA) 17.82 10.43 3.04 0.00 msec 5.00 min Current 10.00 min 15.00 min Run Time Average 7.537 mA 20.00 min -4.35 25.00 min 30.00 min Marker (Delt a) Time: 29.95 Minute Figure 8: Measured Power Consumption in ALP Mode at Stable Satellite Search 2.4. GLP Mode 2.4.1. Operation Mechanism In GLP mode, power is saved by using duty cycles, but the position quality is degraded compared to that in normal tracking mode. GLP mode working status per second Calculate positioning information Positioning Stage (PE) Idle Stage Measuring Stage (ME) Receive satellite observations GLP mode working status per second Calculate positioning information Positioning Stage (PE) Idle Stage Measuring Stage (ME) Receive satellite.observations Time Figure 9: Operation Status in GLP Mode As shown above, the GLP mode consists of three stages: ⚫ Measuring Stage: ME receives satellite observations. ⚫ Positioning Stage: PE calculates positioning information. ⚫ Idle Stage: the module is in idle stage. LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 19 / 23 GNSS Module Series When the module enters GLP mode, it restricts its satellite search to GPS satellites only, reducing the time it takes to acquire satellites and resolve information, and maintaining low power consumption. 2.4.2. Testing Procedures Please refer to Table 3: Low Power Modes before performing the following test. To enter the GLP mode: 1. Power on the module. 2. Send $PAIR066 to switch GNSS satellite configuration. 3. Send $PAIR080 to switch the navigation mode of the module. 4. Send $PAIR680 to enter the GLP mode. The module returns $PAIR001,680,0*35 when it enters the GLP mode. To exit the GLP mode: Send the $PAIR680 to exit the GLP mode. The module's power consumption in the GLP mode is similar to that in the ALP mode. For the description of power consumption in the GLP mode, please refer to Chapter 2.3.2 Testing Procedure. 2.5. FLP Mode 2.5.1. Operation Mechanism In FLP mode, more power is saved by using duty cycles, but the position quality is degraded compared to that in normal tracking mode. FLP mode working status per second Calculate positioning information Positioning Stage (PE) Idle Stage Measuring Stage (ME) Receive satellite observations FLP mode working status per second Calculate positioning information Positioning Stage (PE) Idle Stage Measuring Stage (ME) Receive satellite observations Time Figure 10: Operation Status in FLP Mode LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 20 / 23 GNSS Module Series As shown above, the FLP mode consists of three stages: ⚫ Measuring Stage: ME receives satellite observations. ⚫ Positioning Stage: PE calculates positioning information. ⚫ Idle Stage: the module is in idle stage. Due to the satellite search limitations in FLP mode, the positioning accuracy is lower compared to that in normal mode. However, because the module limits the number of satellites it searches, the time for satellite search and calculation is reduced, resulting in lower power consumption in this mode. 2.5.2. Testing Procedures Please refer to Table 3: Low Power Modes before performing the following test. To enter the FLP mode: 1. Power on the module. 2. Send $PAIR066 to switch GNSS satellite configuration. 3. Send $PAIR080 to switch the navigation mode of the module. 4. Send $PAIR730 to enter FLP mode. The module returns $PAIR001,730,0*3F when it enters the FLP mode. To exit the FLP mode: Send $PAIR730 to exit the FLP mode. The module's power consumption in FLP mode is similar to that in ALP mode. For the description of power consumption in the FLP mode, please refer to Chapter 2.3.2 Testing Procedure. LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 21 / 23 GNSS Module Series 3 Appendix References Table 9: Related Documents Document Name [1] Quectel_LC26G&LC76G&LC86G_Series_Protocol_Specification [2] Quectel_LC26G(AB)_Hardware_Design [3] Quectel_LC76G_Series_Hardware_Design [4] Quectel_LC86G_Series_Hardware_Design Table 10: Terms and Abbreviations Abbreviation ALP BDS CPU DSP FLP GLP GNSS GPIO GPS ME PE SRAM Description Adaptive Low Power BDS Navigation Satellite System Central Processing Unit Digital Signal Processing Fitness Low Power GPS Low Power Global Navigation Satellite System General-purpose input/output Global Positioning System Measurement Engine Position Engine Static Random-Access Memory LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 22 / 23 Abbreviation TCXO TTFF GNSS Module Series Description Temperature Compensate X'tal (crystal) Oscillator Time to First Fix LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note 23 / 23

Quectel_LC26G&LC76G&LC86G_Series_Low_Power_Mode_Application_Note_V1.0

PDF

391.10 KB

EG800Q&EG91xQ Series FILE Application Note LTE Standard Module Series Version: 1.1 Date: 2023-09-05 Status: Released LTE Standard 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. EG800Q&EG91xQ_Series_FILE_Application_Note 1 / 25 LTE Standard 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. 2023. All rights reserved. EG800Q&EG91xQ_Series_FILE_Application_Note 2 / 25 LTE Standard Module Series About the Document Revision History Version 1.0 Date 2022-10-10 2022-12-01 1.1 2023-09-05 Author Egan LI Egan LI Tomas QIN Description Creation of the document First official release Updated the applicable modules: ⚫ Added EG916Q-GL. ⚫ Updated EG800Q-EU to EG800Q series. EG800Q&EG91xQ_Series_FILE_Application_Note 3 / 25 LTE Standard 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 Description ...................................................................................................... 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 on Storage Medium ................................................ 10 2.3.3. AT+QFDEL Delete File(s) on Storage Medium ...........................................................11 2.3.4. AT+QFUPL Upload File to Storage Medium .............................................................. 12 2.3.5. AT+QFDWL Download File from Storage Medium .................................................... 14 2.3.6. AT+QFOPEN Open a File .......................................................................................... 15 2.3.7. AT+QFREAD Read a File........................................................................................... 16 2.3.8. AT+QFWRITE Write to a File ..................................................................................... 17 2.3.9. AT+QFSEEK Set File Pointer to Specified Position................................................... 18 2.3.10. AT+QFPOSITION Get Offset of File Pointer.............................................................. 19 2.3.11. AT+QFCLOSE Close a File........................................................................................ 20 3 Examples ........................................................................................................................................... 21 3.1. Upload and Download Files ................................................................................................. 21 3.1.1. Upload a File ................................................................................................................. 21 3.1.1.1. Non-ACK Mode..................................................................................................... 21 3.1.1.2. ACK Mode ............................................................................................................ 21 3.1.2. Download a File ............................................................................................................ 22 3.2. Write to and Read Files ........................................................................................................ 22 3.2.1. Write to and Read a UFS File ....................................................................................... 22 4 Summary of Error Codes ................................................................................................................. 23 5 Appendix References ....................................................................................................................... 25 EG800Q&EG91xQ_Series_FILE_Application_Note 4 / 25 LTE Standard Module Series Table Index Table 1: Types of AT Commands ................................................................................................................. 8 Table 2: Summary of Error Codes.............................................................................................................. 23 Table 3: Terms and Abbreviations .............................................................................................................. 25 EG800Q&EG91xQ_Series_FILE_Application_Note 5 / 25 LTE Standard Module Series 1 Introduction Quectel EG800Q series, EG915Q-NA and EG916Q-GL modules support AT commands for working with files on different physical storage mediums. This document is a reference guide to these commands. Quectel EG800Q series, EG915Q-NA and EG916Q-GL modules support only one storage medium – UFS (User File Storage directory) currently. It is a special directory on the flash file system. 1.1. Using FILE AT Commands Follow the steps below to create, read and write to a file in the storage: 1. Upload a file to the storage with AT+QFUPL. If necessary, output/download it through the serial interface with AT+QFDWL. 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 set the file into overwrite mode, read-only mode or other modes with (For more information about , see Chapter 2.3.6). After opening the file, a is assigned to it so that various file operations can be carried out. ⚫ After opening the file, you can write data to the file with AT+QFWRITE and read the data from the current file position with AT+QFREAD. ⚫ Set the file position with AT+QFSEEK or query the current file position with AT+QFPOSITION. ⚫ Close the file with AT+QFCLOSE, after which the will become invalid. Commands for managing files on storage medium: 1. AT+QFLDS: Get storage space information. 2. AT+QFLST: List the file information on the storage medium. 3. AT+QFDEL: Delete the file(s) on the storage medium. ⚫NOTE The file handle obtained after executing AT+QFOPEN must be closed with AT+QFCLOSE after the operation is completed, otherwise the file handle will be leaked. EG800Q&EG91xQ_Series_FILE_Application_Note 6 / 25 LTE Standard Module Series 1.2. Description of Data Mode The COM port of EG800Q series, EG915Q-NA and EG916Q-GL modules has two working modes: AT command mode and data mode. In AT command mode, the data inputted via COM port are treated as AT commands; whereas in data mode, they are treated as data. ⚫ Enter Data Mode Once AT+QFUPL, AT+QFDWL, AT+QFREAD or AT+QFWRITE is executed, the module returns CONNECT and the COM port enters data mode. Or you can enter date mode again by executing ATO. ⚫ Exit Data Mode If you input +++ or pull up the DTR pin (AT&D1 must be executed first) to make the port exit 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 data mode if you execute ATO. To prevent +++ from being misinterpreted as data, the following sequence should be followed: 1 Do not input any data for at least 1 s after inputting +++. 2 Input +++ within 1 s and any other data cannot be inputted. 3 Input +++ and wait until OK is returned. Once OK is returned, the COM port exits the data mode. EG800Q&EG91xQ_Series_FILE_Application_Note 7 / 25 LTE Standard Module Series 2 Description of FILE AT Commands 2.1. AT Command Description 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. EG800Q&EG91xQ_Series_FILE_Application_Note 8 / 25 LTE Standard 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. AT Command Description 2.3.1. AT+QFLDS Get the Space Information of Storage Medium This command gets the space information of the specified storage medium. AT+QFLDS Get the Space Information of Storage Medium Test Command AT+QFLDS=? Write Command AT+QFLDS= Response OK Response +QFLDS: , OK Execution Command AT+QFLDS If there is an error: +CME ERROR: Response Return UFS space information: +QFLDS: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. EG800Q&EG91xQ_Series_FILE_Application_Note 9 / 25 LTE Standard Module Series Parameter String type. Storage medium type. 'UFS' UFS Integer type. Free space size of . Unit: byte. Integer type. Total space 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 details. Example AT+QFLDS='UFS' +QFLDS: 578847,917503 OK //Query the space information of 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 Execution Command AT+QFLST If there is an error: +CME ERROR: Response Return the space information of UFS files: +QFLST: , [+QFLST: , […]] OK If there is an error: +CME ERROR: EG800Q&EG91xQ_Series_FILE_Application_Note 10 / 25 LTE Standard Module Series Maximum Response Time Characteristics 300 ms The command takes effect immediately. The configurations are not saved. Parameter String type. File to be listed. Maximum length: 80 bytes. '*' List all files in UFS 'UFS:' List the specified file in UFS '' List the specified file in UFS String type. File name. Integer type. File size of specified file in UFS. Unit: byte. Integer type. Error code. See Chapter 4 for details. Example AT+QFLST='*' +QFLST: 'UFS:1k.txt',1024 +QFLST: 'UFS:2k.txt',2048 +QFLST: 'UFS:3k.txt',3072 OK //List all files in UFS. ⚫NOTE AT+QFLST queries the actual size of the file currently stored on Flash. Use AT+QFWRITE (see Chapter 2.3.8) to write data. If AT+QFLST cannot query file size, execute AT+QFCLOSE (see Chapter 2.3.11) to close the file and then query the file size. 2.3.3. AT+QFDEL Delete File(s) on Storage Medium This command deletes a single file or all files from a specified storage medium. AT+QFDEL Delete File(s) on Storage Medium Test Command AT+QFDEL=? Response +QFDEL: Write Command AT+QFDEL= OK Response OK If there is an error: EG800Q&EG91xQ_Series_FILE_Application_Note 11 / 25 LTE Standard Module Series Maximum Response Time Characteristics +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. Parameter String type. Name of the file to be deleted. Maximum length: 80 bytes. '*' Delete all files in UFS (do not delete the directory) 'UFS:' Delete the specified file in UFS '' Delete the specified file in UFS String type. File name. Integer type. Error code. See Chapter 4 for details. Example AT+QFDEL='*' OK AT+QFDEL='UFS:1.txt' OK //Delete all files in UFS (do not delete the directory). //Delete the 1.txt file in UFS. 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 has the same name as the file to be uploaded, an error will be reported. 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 TA switches to 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 no data is inputted when is reached, TA will go back to AT command mode and return the following code: +QFUPL: , OK EG800Q&EG91xQ_Series_FILE_Application_Note 12 / 25 LTE Standard Module Series Maximum Response Time Characteristics If there is an error: +CME ERROR: 5 s The command takes effect immediately. The configurations are not saved. Parameter String type. Name of the file to be uploaded. Maximum length: 80 bytes. 'UFS:' Name of the file to be uploaded to UFS '' Name of the file to be uploaded to UFS String type. File name. Integer type. Free space size of . See AT+QFLDS for more details on . Integer type. Waiting time for inputting data to USB/UART. Range: 1–65535. Default value: 5. Unit: second. Integer type. Determines whether to use ACK mode. 0 Turn off ACK mode 1 Turn on ACK mode 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. Checksum of uploaded data. Integer type. Error code. See Chapter 4 for details. 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. If the number of characters is odd, set the last character as the high 8 bit, and the low 8 bit as 0, and then use an XOR operator to calculate the checksum. After switching to command mode, 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. ACK mode is a safeguard against data loss when uploading large files, if hardware flow control does not work. ACK mode works as follows: 1) Execute AT+QFUPL=,,,1 to enable ACK mode. 2) Module outputs CONNECT. 3) MCU sends 1 KB data, to which the module responds with an A. 4) MCU receives the A and then sends the next 1 KB data. 5) Repeat step 3) and 4) until the transfer is completed. For an example of ACK mode use, see Chapter 3.1.1.2. EG800Q&EG91xQ_Series_FILE_Application_Note 13 / 25 LTE Standard Module Series 2.3.5. AT+QFDWL Download File from Storage Medium This command downloads a specified file from the storage medium. AT+QFDWL Download File from Storage Medium Test Command AT+QFDWL=? Response +QFDWL: Write Command AT+QFDWL= OK Response CONNECT TA switches to data mode, so the binary data of the file can be outputted. After the file is downloaded, TA will go back to AT command mode and return the following codes: +QFDWL: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 5 s The command takes effect immediately. The configurations are not saved. Parameter String type. Name of the file to be downloaded. Maximum length: 80 bytes. 'UFS:' Name of the UFS file to be downloaded '' Name of the UFS file to be downloaded String type. File name. Integer type. Size of downloaded data. Unit: byte. Integer type. Checksum of downloaded data. Integer type. Error code. See Chapter 4 for details. NOTE is a 16-bit checksum based on bitwise XOR. EG800Q&EG91xQ_Series_FILE_Application_Note 14 / 25 LTE Standard Module Series 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 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 Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. Parameter String type. Name of the file to be opened. Maximum length: 80 bytes. 'UFS:' Name of the UFS file to be opened '' Name of the UFS file to be opened String type. File name. 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 and cleared. 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. Integer type. File handle to be used. Data type: 4 bytes. Integer type. Error code. See Chapter 4 for details. EG800Q&EG91xQ_Series_FILE_Application_Note 15 / 25 LTE Standard Module Series 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 TA switches to data mode, so the data being read will be outputted. When the total size of the data reaches , TA will go back to AT command mode, display the result and then return the following code: OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 5 s The command takes effect immediately. The configurations are not saved. Parameter Integer type. File handle to be read. Integer type. Length of the file to be read. If this parameter is not inputted, the default length is 10 KB. If this parameter is inputted, the actual length of the file is read. Maximum value of this parameter is determined by of AT+QFUPL. Default value: 10240. Unit: byte. Integer type. Actual read length. Unit: byte. Integer type. Error code. See Chapter 4 for details. EG800Q&EG91xQ_Series_FILE_Application_Note 16 / 25 LTE Standard Module Series 2.3.8. AT+QFWRITE Write to a File This command writes data into a file. The data starts 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: [,[,range of supported s]] Write Command AT+QFWRITE=[, [,]] OK Response CONNECT TA switches to data mode, so the hexadecimal data of the file can be written to. When the total size of the written data reaches or the written time reaches , TA will go back to AT command mode and return the following code: +QFWRITE: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 5 s The command takes effect immediately. The configurations are not saved. Parameter Integer type. File handle to be written to. Integer type. Length of the file to be written to. If this parameter is not inputted, the default length is 10 KB. If this parameter is inputted, the actual length of the file is 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: second. Integer type. Actual written length. Unit: byte. Integer type. Total file length. Unit: byte. Integer type. Error code. See Chapter 4 for details. EG800Q&EG91xQ_Series_FILE_Application_Note 17 / 25 LTE Standard Module Series 2.3.9. AT+QFSEEK Set File Pointer to Specified Position This command sets a file pointer to the specified position. This will decide the starting position of commands, such as AT+QFREAD, AT+QFWRITE and AT+QFPOSITION. AT+QFSEEK Set a File Pointer to Specified Position Test Command AT+QFSEEK=? Response +QFSEEK: ,[,range of supported s] Write Command AT+QFSEEK=,[,< position>] OK Response OK If there is an error: +CME ERROR: Maximum Response Time 300 ms Characteristics The command takes effect immediately. The configurations are not saved. Parameter Integer type. File handle 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 details. NOTE If the set final position of the pointer exceeds the file size, executing this command will return ERROR. EG800Q&EG91xQ_Series_FILE_Application_Note 18 / 25 LTE Standard Module Series 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 the Offset of a File Pointer Test Command AT+QFPOSITION=? Response +QFPOSITION: Write Command AT+QFPOSITION= OK Response +QFPOSITION: OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. File handle 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 details. EG800Q&EG91xQ_Series_FILE_Application_Note 19 / 25 LTE Standard Module Series 2.3.11. 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 Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. File handle to be closed. Integer type. Error code. See Chapter 4 for details. EG800Q&EG91xQ_Series_FILE_Application_Note 20 / 25 LTE Standard 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 //Upload the text file test1.txt to UFS. //Input binary data of the text file in data mode. 3.1.1.2. ACK Mode The ACK mode can make the data transmission more reliable. When transmitting a large file without hardware flow control, the ACK mode is recommended to prevent data loss. For more details on ACK mode, see AT+QFUPL. AT+QFUPL='test.txt',3000,5,1 CONNECT A A +QFUPL: 3000,B34A //Upload the text file test.txt to UFS. //Input 1024 bytes of binary data of the text file in data mode. //After receiving 1024 bytes of binary data of the text file, the module returns an A. //Input next 1024 bytes of binary data of the text file in data mode. //Input the rest of binary data of the text file in data mode. OK EG800Q&EG91xQ_Series_FILE_Application_Note 21 / 25 3.1.2. Download a File AT+QFDWL='test.txt' CONNECT +QFDWL: 10,613e OK LTE Standard Module Series //Download the text file test.txt from UFS. //Output binary data of the text file in data mode. //Return size and checksum value of the downloaded data. 3.2. Write to and Read Files 3.2.1. Write to and Read a UFS File AT+QFOPEN='test.txt',1 +QFOPEN: 1 //Open the file to get the file handle. OK AT+QFWRITE=1,10 CONNECT +QFWRITE: 10,10 //Write 10 bytes to the file. //Write hexadecimal data to the file in data mode. //Return the actual written bytes and the size of the file. OK AT+QFSEEK=1,0,0 OK AT+QFREAD=1,10 CONNECT 10 //Set the file pointer to the beginning of the file. //Read data. //Output data to be read in data mode. OK AT+QFCLOSE=1 OK //Close the file. EG800Q&EG91xQ_Series_FILE_Application_Note 22 / 25 LTE Standard Module Series 4 Summary of Error Codes indicates the error codes related to mobile equipment. See the table below for details. The error codes indicated below are related to the file operation of the modules. Table 2: Summary of Error Codes 400 401 402 403 405 406 407 409 410 411 413 414 416 417 418 419 420 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 Fail to write to the file Fail to open the file Fail to read the file Reach the max. number of files allowed to be opened Read-only file Invalid file descriptor Failed to list the file Failed to delete the file Failed to get disk info No space EG800Q&EG91xQ_Series_FILE_Application_Note 23 / 25 421 Time-out 423 File too large 425 Invalid parameter 426 File already opened LTE Standard Module Series EG800Q&EG91xQ_Series_FILE_Application_Note 24 / 25 LTE Standard Module Series 5 Appendix References Table 3: Terms and Abbreviations Abbreviation ACK COM DOS DTR MCU ME RAM TA UART UFS USB XOR Description Acknowledgement Communication Port Disk Operating System Data Terminal Ready Microprogrammed Control Unit Mobile Equipment Random Access Memory Terminal Adapter Universal Asynchronous Receiver-Transmitter User File Storage Universal Serial Bus Exclusive OR EG800Q&EG91xQ_Series_FILE_Application_Note 25 / 25

Quectel_EG800Q&EG91xQ_Series_FILE_Application_Note_V1.1

PDF

327.37 KB

EG800Q&EG91xQ Series DFOTA Application Note LTE Standard Module Series Version: 1.1 Date: 2023-09-06 Status: Released LTE Standard Module Series Our aim is to provide customers with timely and comprehensive service. For any assistance, please contact our company headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local office. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm Or email to support@quectel.com. 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. EG800Q&EG91xQ_Series_DFOTA_Application_Note 1 / 25 LTE Standard 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. 2023. All rights reserved. EG800Q&EG91xQ_Series_DFOTA_Application_Note 2 / 25 LTE Standard Module Series About the Document Revision History Version 1.0 Date 2022-10-27 2023-03-06 Author Byron ZHOU Byron ZHOU 1.1 2023-09-06 Byron ZHOU Description Creation of the document First official release Updated the applicable modules: ⚫ Added EG916Q-GL. ⚫ Updated EG800Q-EU to EG800Q Series. EG800Q&EG91xQ_Series_DFOTA_Application_Note 3 / 25 LTE Standard Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 5 1 Introduction .......................................................................................................................................... 6 2 Firmware Upgrade via DFOTA ............................................................................................................ 7 2.1. Get Delta Firmware Package .................................................................................................. 8 2.2. Put Delta Firmware Package on FTP/HTTP(S) Server or External MCU .............................. 8 2.3. Execute AT Command to Upgrade the Firmware ................................................................... 8 3 Description of DFOTA AT Commands............................................................................................... 9 3.1. AT Command Introduction....................................................................................................... 9 3.1.1. Definitions......................................................................................................................... 9 3.1.2. AT Command Syntax ....................................................................................................... 9 3.2. Declaration of AT Command Examples ................................................................................ 10 3.3. AT Commands Description.................................................................................................... 10 3.3.1. AT+QFOTADL Upgrade Firmware via DFOTA............................................................ 10 3.3.1.1. AT+QFOTADL= Upgrade Firmware over FTP Server ...................11 3.3.1.2. AT+QFOTADL= Upgrade Firmware over HTTP(S) Server ........ 14 3.3.1.3. AT+QFOTADL='FILE:' Upgrade Firmware over External MCU ......... 17 4 Summary of Result Codes ................................................................................................................ 20 4.1. Summary of Codes ............................................................................................. 20 4.2. Summary of Codes .......................................................................................... 22 4.3. Summary of Codes ............................................................................................... 23 4.4. Summary of Codes........................................................................................ 24 4.5. Summary of Codes ...................................................................................................... 24 5 Appendix References ........................................................................................................................ 25 EG800Q&EG91xQ_Series_DFOTA_Application_Note 4 / 25 LTE Standard Module Series Table Index Table 1: Types of AT Commands ................................................................................................................. 9 Table 2: Summary of Codes .................................................................................................... 20 Table 3: Summary of Codes ................................................................................................. 22 Table 4: Summary of Codes ...................................................................................................... 23 Table 5: Summary of Codes............................................................................................... 24 Table 6: Summary of Codes ............................................................................................................. 24 Table 7: Related Document........................................................................................................................ 25 Table 8: Terms and Abbreviations .............................................................................................................. 25 EG800Q&EG91xQ_Series_DFOTA_Application_Note 5 / 25 LTE Standard Module Series 1 Introduction Quectel LTE Standard EG800Q series, EG915Q-NA and EG916Q-GL modules support DFOTA (Delta Firmware Upgrade Over-The-Air) function to realize the upgrade or degrade of the firmware version of the module. EG800Q&EG91xQ_Series_DFOTA_Application_Note 6 / 25 LTE Standard Module Series 2 Firmware Upgrade via DFOTA The following chart illustrates the procedures of firmware upgrade through DFOTA. 2. Put the delta package on FTP/HTTP (S) server FTP/HTTP(S) Server 1. Get delta firmware package （EG800Q Series, EG915Q-NA, EG916Q-GL) LTE (FTP/HTTP(S)) 4. Automatically download the delta package from FTP/HTTP(S) server via LTE network External MCU 3. Execute AT+QFOTADL Quectel Module 5. Automatically upgrade the module s firmware Figure 1: Firmware Upgrade via DFOTA As shown in the above figure, the following steps need to be performed to update the firmware: Step 1: Get the delta firmware package from Quectel or agent. Step 2: Put the delta firmware package on FTP/HTTP(S) server or external MCU. Step 3: Execute AT+QFOTADL. Step 4: The module will automatically download the delta firmware package from FTP/HTTP(S) server EG800Q&EG91xQ_Series_DFOTA_Application_Note 7 / 25 LTE Standard Module Series via LTE network or gets delta firmware package from external MCU. Step 5: The module’s firmware will be automatically upgraded. NOTE During the upgrading process, please make sure that the module is powered up, otherwise, the DFOTA upgrade may fail and cannot be restored. 2.1. Get Delta Firmware Package Before upgrading, get the original firmware version with ATI command and confirm the target firmware version, and then send the two firmware versions to Quectel or the agent to get a delta firmware package. NOTE There are two types of delta firmware packages, one is a .par file to upgrade only the firmware version; the other is a .bin file to upgrade a tool for upgrading firmware (updater) and the firmware version at the same time. You can choose the delta package as needed. 2.2. Put Delta Firmware Package on FTP/HTTP(S) Server or External MCU When the delta package is stored on the FTP/HTTP(S) server: Step 1: Please set up an FTP/HTTP(S) server before using DFOTA function (Quectel does not provide this server). Step 2: Put the delta firmware package on the server, and record the storage path. User can also store the delta package on external MCU directly after getting it. 2.3. Execute AT Command to Upgrade the Firmware After putting the delta firmware package on the FTP/HTTP(S) server or external MCU, execute AT+QFOTADL, and then the module will download the delta firmware package from the FTP/HTTP(S) server over the air or gets the delta firmware package from external MCU and upgrade the firmware automatically. For more details, see Chapter 3. EG800Q&EG91xQ_Series_DFOTA_Application_Note 8 / 25 LTE Standard Module Series 3 Description of DFOTA 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 command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on 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 Command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. EG800Q&EG91xQ_Series_DFOTA_Application_Note 9 / 25 LTE Standard 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 AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendation 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 exists a correlation among these examples and that they should be executed in a given sequence. 3.3. AT Commands Description 3.3.1. AT+QFOTADL Upgrade Firmware via DFOTA AT+QFOTADL enables automatic firmware upgrade for modules via DFOTA. See Chapter 3.3.1.1 to Chapter 3.3.1.3 for details. If the delta package is stored on the FTP/HTTP(S) server, the module automatically downloads the package from FTP/HTTP(S) server after executing AT+QFOTADL. When the package is downloaded successfully, the module will automatically upgrade the firmware; After the firmware is successfully upgraded, the module automatically reboots. If the delta package is stored on an external MCU, after AT+QFOTADL is executed successfully, the module receives the package from the external MCU through the main serial port or USB AT port, and then automatically upgrades the firmware. AT+QFOTADL Upgrade Firmware via DFOTA Test Command AT+QFOTADL=? Response +QFOTADL: ,(list of s),(list of s),(list of s) Maximum Response Time Characteristics OK 180 s / Parameter String type. The URL of the delta firmware package stored on the FTP/HTTP(S) server or external MCU. Maximum length: 255 bytes. See Chapter 3.3.1.1 to Chapter 3.3.1.3 for details. Integer type. Upgrade mode after successfully downloading the delta firmware package. 0 Upgrade the firmware after manually rebooting the module EG800Q&EG91xQ_Series_DFOTA_Application_Note 10 / 25 LTE Standard Module Series 1 Automatically reboot the module to upgrade the firmware at once. Integer type. URC indicating the download progress. The last URC indicates that the download is completed. For example: if it is set to 50, 50 URCs will be reported to indicate the download progress, of which the 25th URC indicates that the download is half completed, and the 50th URC indicates that the download is completed. 0 Reporting URCs indicating download progress is not allowed 5–100 Maximum number of reported download progress URCs Integer type. URC indicating the upgrade progress. The last URC indicates that the upgrade is completed. For example: if it is set to 50, 50 URCs will be reported to indicate the upgrade progress, of which the 25th URC indicates that the upgrade is half completed, and the 50th URC indicates that the upgrade is completed. 0 Reporting URCs indicating upgrade progress is not allowed 5–100 Maximum number of reported upgrade progress URCs 3.3.1.1. AT+QFOTADL= Upgrade Firmware over FTP Server When the delta package is stored on the FTP server, AT+QFOTADL= enables automatic firmware upgrade for modules via DFOTA. After executing this command, the module will automatically download the package from FTP server and then upgrade the firmware. AT+QFOTADL= Upgrade Firmware over FTP Server Write Command If you only upgrade the firmware version (the delta package is a .par file.): AT+QFOTADL=[,[,[,]]] Response OK +QIND: 'FOTA','FTPSTART' [+QIND: 'FOTA','DOWNLOADING', +QIND: 'FOTA','DOWNLOADING', …] +QIND: 'FOTA','FTPEND', +QIND: 'FOTA','START' [+QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ...] +QIND: 'FOTA','END', Write Command If you upgrade the firmware version and the updater tool at the same time (the delta package is a .bin file): AT+QFOTADL=[,<upgrade If there is any error: ERROR Response OK +QIND: 'FOTA','FTPSTART' [+QIND: 'FOTA','DOWNLOADING', +QIND: 'FOTA','DOWNLOADING', EG800Q&EG91xQ_Series_DFOTA_Application_Note 11 / 25 LTE Standard Module Series _mode>[,[,]]] …] +QIND: 'FOTA','FTPEND', +QIND: 'FOTA','UPDATERSTART' +QIND: 'FOTA','UPDATEREND', +QIND: 'FOTA','START' [+QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ...] +QIND: 'FOTA','END', Maximum Response Time Characteristics If there is any error: ERROR 180 s / Parameter String type. The URL address that the delta firmware package stored on the FTP server. It should be started with 'FTP://'. For example, 'FTP://< user_name>:@:/'。 Maximum length: 255 bytes. String type. User name for authentication. String type. Password for authentication. String type. IP address or domain name of FTP server. Integer type. Port of FTP server. Range: 1–65535. Default: 21. String type. Delta firmware package name on FTP server. Integer type. Upgrade mode after successfully downloading the delta firmware package. 0 Upgrade the firmware after manually rebooting the module. 1 Automatically reboot the module to upgrade the firmware at once. Integer type. URC indicating the download progress. The last URC indicates that the download is completed. For example: if it is set to 50, 50 URCs will be reported to indicate the download progress, of which the 25th URC indicates that the download is half completed, and the 50th URC indicates that the download is completed. 0 Reporting URCs indicating download progress is not allowed 5–100 Maximum number of reported download progress URCs Integer type. URC indicating the upgrade progress. The last URC indicates that the upgrade is completed. For example: if it is set to 50, 50 URCs will be reported to indicate the upgrade progress, of which the 25th URC indicates that the upgrade is half completed, and the 50th URC indicates that the upgrade is completed. EG800Q&EG91xQ_Series_DFOTA_Application_Note 12 / 25 LTE Standard Module Series 0 Reporting URCs indicating upgrade progress is not allowed 5–100 Maximum number of reported upgrade progress URCs Integer type. The FTP result code. 0 means download successfully. See Chapter 4.1 for details. Integer type. The result code of the updater tool upgrading. 0 means updater upgraded successfully. See Chapter 4.4 for details. Integer type. Download or upgrade progress. Integer type. Result code. 0 means upgraded successfully. Any other value means an error. See Chapter 4.5 for details. Example //Upgrade the firmware when delta firmware package is stored on an FTP server. //The FTP server address is 'FTP://test:test@124.74.41.170:21/EG800Q_FOTA_PACKAGE.par'. // Configure the PDP context. In this example, the PDP context ID is 2. For more details, refer to the document [1]. AT+QICSGP=2,1,'cmnet','','',1 //Set the PDP context ID to 2, the APN to 'cmnet' (representing China Mobile), the username and password to be empty, and the authentication type to PAP. OK AT+QIACT=2 //Activate the PDP context. OK //Execute AT+QFOTADL to enable automatic firmware upgrade via DFOTA, and then the module will start to download the delta package and upgrade firmware automatically. AT+QFOTADL='FTP://test:test@124.74.41.170:21/EG800Q_FOTA_PACKAGE.par',1,50 OK +QIND: 'FOTA','FTPSTART' +QIND: 'FOTA','DOWNLOADING',2 +QIND: 'FOTA','DOWNLOADING',4 ... +QIND: 'FOTA','DOWNLOADING',100 +QIND: 'FOTA','HTTPEND',0 //Download the delta firmware package from the FTP server successfully. //After the download completes, the module will reboot automatically and enter the upgrade mode and then upgrade firmware through DFOTA. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',2 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //Upgrade the firmware successfully. EG800Q&EG91xQ_Series_DFOTA_Application_Note 13 / 25 LTE Standard Module Series NOTE 1. The server address and delta package name above are only examples, and you can modify them as needed. 2. If the downloaded delta package is a file suffixed with .bin, after the delta package is downloaded, the updater tool will be upgraded first, and the following URC will be reported: +QIND: 'FOTA','UPDATERSTART' +QIND: 'FOTA','UPDATEREND',0 // Upgrade the updater tool successfully. After the updater tool is successfully upgraded, the module will reboot automatically and enter the upgrade mode and then upgrade firmware through DFOTA. 3.3.1.2. AT+QFOTADL= Upgrade Firmware over HTTP(S) Server When the delta package is stored on the HTTP(S) server, AT+QFOTADL= enables automatic firmware upgrade for modules via DFOTA. After executing this command, the module will automatically download the package from HTTP(S) server and then upgrade the firmware. AT+QFOTADL= Upgrade Firmware over HTTP(S) Server Write Command If you only upgrade the firmware version (the delta package is a .par file.): AT+QFOTADL=[,[,[,< update_URC_max>]]] Response OK +QIND: 'FOTA','HTTPSTART' [+QIND: 'FOTA','DOWNLOADING', +QIND: 'FOTA','DOWNLOADING', …] +QIND: 'FOTA','HTTPEND', +QIND: 'FOTA','START' [+QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ...] +QIND: 'FOTA','END', Write Command If you upgrade the firmware version and the updater tool at the same time (the delta package is a .bin file): AT+QFOTADL=[,[,[,< update_URC_max>]]] If there is any error: ERROR Response OK +QIND: 'FOTA','HTTPSTART' [+QIND: 'FOTA','DOWNLOADING', +QIND: 'FOTA','DOWNLOADING', …] +QIND: 'FOTA','HTTPEND', +QIND: 'FOTA','UPDATERSTART' +QIND: 'FOTA','UPDATEREND', EG800Q&EG91xQ_Series_DFOTA_Application_Note 14 / 25 Maximum Response Time Characteristics LTE Standard Module Series +QIND: 'FOTA','START' [+QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ...] +QIND: 'FOTA','END', If there is any error: ERROR 180 s / Parameter String type. The URL of the delta firmware package stored on the HTTP(S) server. It should be started with 'http://' or 'https://'. For example, 'http://:/'. Maximum length: 255 bytes. String type. The IP address or domain name of the HTTP(S) server. Integer type. HTTP(S) server port. Range: 1–65535. Default value: 80. String type. The filename of the delta firmware package on the HTTP(S) server. Integer type. Upgrade mode after successfully downloading the delta firmware package. 0 Upgrade the firmware after manually rebooting the module. 1 Automatically reboot the module to upgrade the firmware at once. Integer type. URC indicating the download progress. The last URC indicates that the download is completed. For example: if it is set to 50, 50 URCs will be reported to indicate the download progress, of which the 25th URC indicates that the download is half completed, and the 50th URC indicates that the download is completed. 0 Reporting URCs indicating download progress is not allowed 5–100 Maximum number of reported download progress URCs Integer type. URC indicating the upgrade progress. The last URC indicates that the upgrade is completed. For example: if it is set to 50, 50 URCs will be reported to indicate the upgrade progress, of which the 25th URC indicates that the upgrade is half completed, and the 50th URC indicates that the upgrade is completed. 0 Reporting URCs indicating upgrade progress is not allowed 5–100 Maximum number of reported upgrade progress URCs Integer type. The HTTP(S) result code. 0 means download successfully. See Chapter 4.2 for details. Integer type. The result code of the updater tool upgrading. 0 means updater EG800Q&EG91xQ_Series_DFOTA_Application_Note 15 / 25 LTE Standard Module Series upgraded successfully. See Chapter 4.4 for details. Integer type. Download or upgrade progress. Integer type. Result code. 0 means upgraded successfully. Any other value means an error. See Chapter 4.5 for details. Example //Upgrade the firmware when delta firmware package is stored on an HTTP(S) server. //The HTTP(S) server address is 'http://www.quectel.com:100/EG800Q_FOTA_PACKAGE.par'. //Configure the PDP context. In this example, the PDP context ID is 2. For more details, refer to the document [1]. AT+QICSGP=2,1,'cmnet','','',1 //Set the PDP context ID to 2, the APN to 'cmnet' (representing China Mobile), the username and password to be empty, and the authentication type to PAP. OK AT+QIACT=2 //Activate the PDP context. OK //Execute AT+QFOTADL to enable automatic firmware upgrade via DFOTA, and then the module will start to download the delta package and upgrade firmware automatically. AT+QFOTADL='http://www.quectel.com:100/EG800Q_FOTA_PACKAGE.par',1,50 OK +QIND: 'FOTA','HTTPSTART' +QIND: 'FOTA','DOWNLOADING',2 +QIND: 'FOTA','DOWNLOADING',4 ... +QIND: 'FOTA','DOWNLOADING',100 +QIND: 'FOTA','HTTPEND',0 //Download the delta firmware package from the HTTP(S) server successfully. //After the download completes, the module will reboot automatically and enter the upgrade mode and then upgrade firmware through DFOTA. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',2 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //Upgrade the firmware successfully. NOTE 1. The server address and delta package name above are only examples, and you can modify them as needed. 2. If the downloaded delta package is a file suffixed with .bin, after the delta package is downloaded, the EG800Q&EG91xQ_Series_DFOTA_Application_Note 16 / 25 LTE Standard Module Series updater tool will be upgraded first, and the following URC will be reported: +QIND: 'FOTA','UPDATERSTART' +QIND: 'FOTA','UPDATEREND',0 //Upgrade the updater tool successfully. After the updater tool is successfully upgraded, the module will reboot automatically and enter the upgrade mode and then upgrade firmware through DFOTA. 3.3.1.3. AT+QFOTADL='FILE:' Upgrade Firmware over External MCU When the delta package is stored on external MCU, AT+QFOTADL='FILE:' should be executed to start firmware upgrade. After executing this command, the module will receive the firmware package from external MCU through the main UART or USB AT port and then upgrade the firmware automatically. If main UART (or USB AT port) is used, the following steps should be performed to upgrade firmware: Step 1: MCU opens the UART tool and chooses main UART(or USB AT port). Step 2: Select the delta package from external MCU. Step 3: Send AT+QFOTADL='FILE:'[,[,[,]]] Step 4：Send the delta firmware package. AT+QFOTADL='FILE:' Upgrade Firmware over External MCU Write Command AT+QFOTADL='FILE:'[,[,[ ,]]] Response OK +QIND: 'FOTA','FILESTART' [+QIND:'FOTA','DOWNLOADING', +QIND:'FOTA','DOWNLOADING', …] +QIND: 'FOTA','FILEEND', +QIND: 'FOTA','START' [+QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ...] +QIND: 'FOTA','END', Maximum Response Time If there is any error: ERROR 180 s EG800Q&EG91xQ_Series_DFOTA_Application_Note 17 / 25 LTE Standard Module Series Characteristics / Parameter Integer type. Length of delta firmware package. Integer type. File result code. 0 indicates successful downloading. Refer to Chapter 4.3 for details. Integer type. Length of uploaded delta firmware package. Integer type. Total length of delta firmware package. Integer type. Download or upgrade progress. Integer type. Result code. 0 indicates upgraded successfully. Any other value indicates an error. See Chapter 4.5 for details. Integer type. Upgrade mode after successfully downloading the delta firmware package. 0 Upgrade the firmware after manually rebooting the module. 1 Automatically reboot the module to upgrade the firmware at once Integer type. URC indicating the download progress. The last URC indicates that the download is completed. For example: if it is set to 50, 50 URCs will be reported to indicate the download progress, of which the 25th URC indicates that the download is half completed, and the 50th URC indicates that the download is completed. 0 Reporting URCs indicating download progress is not allowed 5–100 Maximum number of reported download progress URCs Integer type. URC indicating the upgrade progress. The last URC indicates that the upgrade is completed. For example: if it is set to 50, 50 URCs will be reported to indicate the upgrade progress, of which the 25th URC indicates that the upgrade is half completed, and the 50th URC indicates that the upgrade is completed. 0 Reporting URCs indicating upgrade progress is not allowed 5–100 Maximum number of reported upgrade progress URCs Example // Upgrade the firmware when delta firmware package is stored on external MCU. AT+QFOTADL='FILE:216014',1,100 //The length of delta firmware package is 216014 bytes. OK +QIND: 'FOTA','FILESTART' //Wait for external MCU to send delta firmware package through UART tool to module. +QIND: 'FOTA','DOWNLOADING',2450,216014,1 +QIND: 'FOTA','DOWNLOADING',4550,216014,2 ... EG800Q&EG91xQ_Series_DFOTA_Application_Note 18 / 25 LTE Standard Module Series +QIND: 'FOTA','DOWNLOADING',216014,216014,100 +QIND: 'FOTA','FILEEND',0 //Upgrade firmware via DFOTA immediately after downloading delta firmware package. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',2 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 // Upgrade the firmware successfully. EG800Q&EG91xQ_Series_DFOTA_Application_Note 19 / 25 LTE Standard Module Series 4 Summary of Result Codes This chapter introduces the result codes related to mobile equipment or network. The details about , , , and are described as follows. 4.1. Summary of Codes Detailed information about is listed as follows. Table 2: Summary of Codes 0 601 602 603 604 605 606 607 608 609 610 611 612 Description FTP download successfully FTP unknown error FTP service blocked FTP service busy DNS parse failed Network error Control connection closed Data connection closed Socket closed by peer Timeout error Invalid parameter Failed to open file File position invalid EG800Q&EG91xQ_Series_DFOTA_Application_Note 20 / 25 LTE Standard Module Series 613 File error 614 Service not available, closing control connection 615 Failed to open data connection 616 Connection closed and transfer aborted 617 Requested file action not taken 618 Requested action aborted: local error in processing 619 Requested action not taken: insufficient system storage 620 Syntax error, command unrecognized 621 Syntax error in parameters or arguments 622 Command not implemented 623 Bad sequence of commands 624 Command parameter not implemented 625 Failed to login FTP 626 Need account for storing files 627 Requested action not taken 628 Requested action aborted: page type unknown 629 Requested file action aborted EG800Q&EG91xQ_Series_DFOTA_Application_Note 21 / 25 LTE Standard Module Series 4.2. Summary of Codes Detailed information about is listed as follows. Table 3: Summary of Codes 0 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 Description HTTP(S) download successfully HTTP(S) unknown error HTTP(S) timeout HTTP(S) busy HTTP(S) UART busy HTTP(S) does not get/post request HTTP(S) network busy HTTP(S) network open failed HTTP(S) network not configured HTTP(S) network deactivated HTTP(S) network error HTTP(S) URL error HTTP(S) URL empty HTTP(S) IP address error HTTP(S) DNS error HTTP(S) socket creation error HTTP(S) socket connection error HTTP(S) socket read error HTTP(S) socket write error HTTP(S) socket closed EG800Q&EG91xQ_Series_DFOTA_Application_Note 22 / 25 LTE Standard Module Series 720 HTTP(S) data encode error 721 HTTP(S) data decode error 722 HTTP(S) read timeout 723 HTTP(S) response failed 724 Incoming call busy 725 Voice call busy 726 Input timeout 727 Wait data timeout 728 Wait HTTP(S) response timeout 729 Allocate memory failed 730 Invalid parameter 4.3. Summary of Codes Detailed information about is listed as follows. Table 4: Summary of Codes 0 500 Description File download successfully File dowmload error EG800Q&EG91xQ_Series_DFOTA_Application_Note 23 / 25 LTE Standard Module Series 4.4. Summary of Codes Detailed information about is listed as follows. Table 5: Summary of Codes 0 -1 -2 -3 -4 -5 -6 Description Updater upgraded successfully Updater package read error Updater package header parsing error The updater package has no ending tail Updater package verification error Memory erase error Error loading updater package 4.5. Summary of Codes Detailed information about is listed as follows. Table 6: Summary of Codes 0 504 505 506 507 552 553 Description DFOTA upgrade successfully DFOTA upgrade failed DFOTA package check error DFOTA firmware MD5 check error DFOTA package version is mismatched DFOTA package project name is mismatched DFOTA package baseline number is mismatched EG800Q&EG91xQ_Series_DFOTA_Application_Note 24 / 25 LTE Standard Module Series 5 Appendix References Table 7: Related Document Document Name [1] Quectel_EG800Q&EG91xQ_Series_TCP(IP)_Application_Note Table 8: Terms and Abbreviations Abbreviation APN DFOTA GSM GPRS HTTP HTTPS IP LTE PAP PDP URC URL WCDMA Description Access Point Name Delta Firmware Over-The-Air Global System for Mobile Communications General Packet Radio Service Hyper Text Transfer Protocol Hyper Text Transfer Protocol Secure Internet Protocol Long Term Evolution Password Authentication Protocol Packet Data Protocol Unsolicited Result Code Uniform Resource Locator Wideband Code Division Multiple Access EG800Q&EG91xQ_Series_DFOTA_Application_Note 25 / 25

Quectel_EG800Q&EG91xQ_Series_DFOTA_Application_Note_V1.1

PDF

444.07 KB

EG800Q-EU&EG915Q-NA TCP(IP) Application Note LTE Standard Module Series Version: 1.0 Date: 2023-02-13 Status: Released EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 1 / 54 LTE Standard 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. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 1 / 54 LTE Standard 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. 2023. All rights reserved. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 2 / 54 LTE Standard Module Series About the Document Revision History Version 1.0 Date 2022-12-06 2023-02-13 Author Orange LI Orange LI Description Creation of the document First official release EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 3 / 54 LTE Standard Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index .................................................................................................................................................. 6 1 Introduction ......................................................................................................................................... 7 1.1. Using TCP/IP AT Commands..................................................................................................... 7 1.2. Description of Data Access Modes............................................................................................ 9 2 Description of TCP/IP AT Commands ............................................................................................. 11 2.1. AT Command Introduction ........................................................................................................11 2.1.1. Definitions.......................................................................................................................11 2.1.2. AT Command Syntax .....................................................................................................11 2.2. Declaration of AT Command Examples ................................................................................... 12 2.3. Description of TCP/IP AT Commands ...................................................................................... 12 2.3.1. AT+QICFG Configure Optional Parameters............................................................... 12 2.3.2. AT+QICSGP Configure Parameters of a TCP/IP Context ......................................... 18 2.3.3. AT+QIACT Activate a PDP Context ........................................................................... 20 2.3.4. AT+QIDEACT Deactivate a PDP Context .................................................................. 21 2.3.5. AT+QIOPEN Open a Socket Service ......................................................................... 21 2.3.6. AT+QICLOSE Close a Socket Service....................................................................... 23 2.3.7. AT+QISTATE Query Socket Service Status............................................................... 24 2.3.8. AT+QISEND Send Data ............................................................................................. 26 2.3.9. AT+QIRD Retrieve Received TCP/IP Data ................................................................ 28 2.3.10. AT+QISENDEX Send Hex String Data ...................................................................... 30 2.3.11. AT+QIACCEPT Manually Accept New TCP Incoming Connection............................ 31 2.3.12. AT+QISWTMD Switch Data Access Mode................................................................. 32 2.3.13. AT+QPING Ping a Remote Host ................................................................................ 33 2.3.14. AT+QNTP Synchronize Local Time with NTP Server ................................................ 34 2.3.15. AT+QIDNSCFG Configure Address of DNS Server................................................... 35 2.3.16. AT+QIDNSGIP Get IP Address by Domain Name ..................................................... 36 2.3.17. AT+QISDE Control Whether to Echo Data for AT+QISEND ...................................... 37 2.3.18. AT+QIGETERROR Query Last Error Code ............................................................... 37 2.4. Description of URCs ................................................................................................................ 38 2.4.1. +QIURC: 'closed' Indicate Closed Connection ......................................................... 38 2.4.2. +QIURC: 'recv' Indicate Incoming Data .................................................................... 39 2.4.3. +QIURC: 'incoming full' Indicate Incoming Connection Reached Limit .................... 39 2.4.4. +QIURC: 'incoming' Indicate Incoming Connection in Automatic Acceptance Mode40 2.4.5. +QIURC: 'accept' Indicate Incoming Connection in Manual Acceptance Mode ....... 40 2.4.6. +QIURC: 'pdpdeact' Indicate PDP Deactivation ....................................................... 41 3 Examples ........................................................................................................................................... 42 3.1. Configure and Activate a Context ............................................................................................ 42 3.1.1. Configure a Context ...................................................................................................... 42 EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 4 / 54 LTE Standard Module Series 3.1.2. Activate a Context ......................................................................................................... 42 3.1.3. Deactivate a Context..................................................................................................... 42 3.2. TCP Client Works in Buffer Access Mode under IPv4 ............................................................. 42 3.2.1. Set up a TCP Client Connection and Enter Buffer Access Mode ................................. 42 3.2.2. Send Data in Buffer Access Mode ................................................................................ 43 3.2.3. Retrieve Data from Remote Server in Buffer Access Mode ......................................... 43 3.2.4. Close a Connection....................................................................................................... 44 3.3. TCP Client Works in Transparent Transmission Mode............................................................ 44 3.3.1. Set up a TCP Client Connection and Enter Transparent Transmission Mode ............. 44 3.3.2. Send Data in Transparent Transmission Mode ............................................................ 45 3.3.3. Retrieve Data from Remote Server in Transparent Transmission Mode...................... 45 3.3.4. Close a TCP Client........................................................................................................ 45 3.4. TCP Client Works in Direct Push Mode ................................................................................... 45 3.4.1. Set up a TCP Client Connection and Enter Direct Push Mode .................................... 45 3.4.2. Send Data in Direct Push Mode.................................................................................... 46 3.4.3. Receive Data from Remote Server in Direct Push Mode ............................................. 46 3.4.4. Close a TCP Client........................................................................................................ 46 3.5. TCP Server Works in Buffer Access Mode under IPv4 ........................................................... 46 3.5.1. Start a TCP Server ........................................................................................................ 46 3.5.2. Accept TCP Incoming Connection ................................................................................ 47 3.5.3. Retrieve Data from Incoming Connection..................................................................... 47 3.5.4. Close a TCP Server ...................................................................................................... 47 3.6. UDP Service under IPv4 .......................................................................................................... 48 3.6.1. Start a UDP Service ...................................................................................................... 48 3.6.2. Send UDP Data to Remote Client................................................................................. 48 3.6.3. Retrieve Data from Remote Client ................................................................................ 48 3.6.4. Close a UDP Service .................................................................................................... 49 3.7. PING under IPv4 ...................................................................................................................... 49 3.8. Synchronize Local Time ........................................................................................................... 49 3.9. Get Last Error Code ................................................................................................................. 50 4 Summary of Error Codes ................................................................................................................. 51 5 Appendix References ....................................................................................................................... 53 EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 5 / 54 LTE Standard Module Series Table Index Table 1: Types of AT Commands ................................................................................................................11 Table 2: Summary of Error Codes.............................................................................................................. 51 Table 3: Terms and Abbreviations .............................................................................................................. 53 EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 6 / 54 LTE Standard Module Series 1 Introduction Quectel EG800Q-EU and EG915Q-NA 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. EG800Q-EU and EG915Q-NA modules provide the following socket services: ⚫ TCP client ⚫ UDP client ⚫ TCP server ⚫ UDP server 1.1. Using TCP/IP AT Commands Through 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. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 7 / 54 LTE Standard Module Series Recommended Power on/off: 1. Power off: Send AT+QPOWD command, and then cut off power after 12s or more. 2. Power on: Keep power key as low for 2s, and then pull it to high. Query (U)SIM Card Status: Execute AT+CPIN. Reboot the module if AT+CPIN? fails to identify (U)SIM card in 20s. PS Service: 1. If of AT+CGREG?/AT+CEREG? equals to 1 or 5, it means that the module has registered on PS domain service in UMTS/LTE network. 2. Go to next step no matter whether it is registered on PS domain service or not in 60s. Configure a PDP Context: 1. Configure APN, user name, password and auth type by AT+QICSGP. 2. Configure QoS settings by AT+CGQMIN/ AT+CGEQMIN/ AT+CGQREQ/ AT+CGEQREQ. Power on the module Send AT command and wait for the module to respond OK Query (U)SIM card status by AT+CPIN? If failed to identify (U)SIM card in 20s, then reboot the module. Identify (U)SIM card If it fails in getting the PS registration status, Query PS service in 60s by AT+CGREG?/ AT+CEREG? configure the PDP context and then execute AT+CFUN=0 and AT+CFUN=1. If this still fails, reboot the module. Configure the PDP context and Qos by AT+QICSGP/AT+CGQREQ/ AT+CGEQREQ/AT+CGQMIN/ AT+CGEQMIN Activate a PDP Context: 1. Activate the PDP context by AT+QIACT=. 2. Query IP address of the PDP context by AT+QIACT?. Notes: a) All above commands should be executed together in sequence. b) Reboot the module if there is no response for AT+QIACT in 150s. c) If failed to deactivate the PDP context for 3 times continuously, then reboot the module. 3. Deactivate the PDP context: reboot the module if there is no response for AT+QIDEACT in 40s. Reboot the module if there is no response in 40s. The PDP context is deactivated successfully Activate the PDP context by AT+QIACT= and AT+QIACT? 1. Reboot the module if there is no response in 150s. 2. If failed to deactivate the PDP context for 3 times continuously, then reboot the module. Failed to activate the PDP context Successfully activate PDP context Deactivate the PDP context by AT+QIDEACT= Open connection by AT+QIOPEN 1. Failed to open connection Open Connection: 1. If failed to get response of AT+QIOPEN in 150s, then close connection. 2. If failed to open connection for 5 times continuously, deactivate the PDP context first, and then re-activate the PDP context and open connection again. continuously for 5 times. +QIOPEN: , 2. There is no response in150s. Send data by AT+QISEND= Get ACK in 90s TCP Connection Maintenance and Detection: 1. Send data by 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 by 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 by AT+QISEND= ,0 Failed to get ACK in 90s Close connection by AT+QICLOSE= OK Reboot the module if there is no response in 10s. Notes: 1. Please note that users 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 60s. 2. Reboot the module if the module has not got response of AT+QIACT in 150s or response of AT+QICLOSE in 10s and in 40s. 3. It is NOT recommended to frequently reboot the module. When the module has been continuously rebooted for 3 times due to failed AT command execution, it can be rebooted immediately for the first time after that. If it still fails, reboot the module after 10 minutes for the second time, and reboot after 30 minutes for the third time, one hour for the fourth time, etc. Figure 1: Flow Chart of TCP/IP AT Command Use EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 8 / 54 LTE Standard Module Series 1.2. Description of Data Access Modes EG800Q-EU and EG915Q-NA 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 switched with AT+QISWTMD. 1. In buffer access mode, data can be sent via AT+QISEND, and if the module receives the data from the Internet, it will buffer them and report a URC +QIURC: 'recv',. Data can be read via AT+QIRD. 2. In direct push mode, data can be sent via AT+QISEND, and if the module receives the data from the Internet, the data will be outputted to COM port directly in the following format: +QIURC: 'recv',,. 3. In transparent transmission mode, the corresponding port (such as UART, USB modem port, etc.) is exclusively used for sending/receiving data directly to the Internet. The data received from COM port will be sent to the Internet directly, and the data received from Internet will be outputted via COM port directly. ⚫ Exit transparent transmission mode To make the module exit transparent transmission mode either: 1) Execute +++. Follow the requirements below to prevent +++ from being misinterpreted as data: a) Do not input any character for at least 1 second before and after inputting +++. b) Input +++ within 1 s, and wait until OK is returned. After OK is returned, the module switches to buffer access mode. OR 2) Change 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 before the module enters transparent transmission mode. ⚫ Return back to transparent transmission mode To return to transparent transmission mode either: EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 9 / 54 LTE Standard Module Series 1) Execute AT+QISWTMD. Before execution specify as 2. Once transparent transmission mode is entered successfully, CONNECT is returned. 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 before, 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 via 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. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 10 / 54 LTE Standard Module Series 2 Description of TCP/IP AT Commands This chapter describes AT commands related to TCP/IP. 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. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 11 / 54 LTE Standard 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+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: 'tcp/retranscfg',(range of supported s),(range of supported s) +QICFG: 'tcp/accept',(list of supported s) +QICFG: 'passiveclosed',(list of supported s) +QICFG: 'dataformat',(list of supported s),(list of supported s) +QICFG: 'viewmode',(list of supported s) +QICFG: 'qisend/timeout',(range of supported s) +QICFG: 'recvind',(list of supported s) +QICFG: 'udp/sendmode',(list of supported s) +QICFG: 'udp/readmode',(list of supported s) +QICFG: 'tcp/keepalive',(list of supported s,(range of supported s),(range of supported s),(range of supported s) +QICFG: 'dns/cache',(list of supported s) +QICFG: 'send/buffersize',(range of supported s) +QICFG: 'window/scale',(list of supported s) OK Write Command Response Query/set the packet size for If the optional parameter is omitted, query the current setting: EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 12 / 54 LTE Standard Module Series transparent transmission mode AT+QICFG='transpktsize'[,] +QICFG: 'transpktsize', OK If the optional parameter is specified, set the packet size for transparent transmission mode: OK If there is any error: ERROR Write Command Response Query/set the waiting time for If the optional parameter is omitted, query the current setting: transparent transmission mode +QICFG: 'transwaittm', AT+QICFG='transwaittm'[,] OK If the optional parameter is specified, set the waiting time for transparent transmission mode: OK Write Command Query/set the maximum interval and the number of TCP retransmissions AT+QICFG='tcp/retranscfg'[,,] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'tcp/retranscfg',, OK If the optional parameter is specified, set the maximum interval and the number of TCP retransmissions: OK If there is any error: ERROR Write Command Response Enable or disable the automatic If the optional parameter is omitted, query the current setting: reception of the TCP connection +QICFG: 'tcp/accept', from the client AT+QICFG='tcp/accept'[,] If the optional parameter is specified, enable or disable the automatic reception of the TCP connection from the client: OK If there is any error: EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 13 / 54 LTE Standard Module Series ERROR Write Command Enable or disable the passive closing of TCP connection when the server is closed AT+QICFG='passiveclosed'[,] Response If the optional parameter is omitted, query the current setting: +QICFG: 'passiveclosed', OK If the parameter is specified, enable or disable the passive closing of TCP connection when the server is closed: OK Write Command Query/set the format of the data to be sent or received (only for buffer access mode and direct push mode) AT+QICFG='dataformat'[,,] If there is any error: ERROR Response If the optional parameters are omitted, query the current setting: +QICFG: 'dataformat',, OK If the optional parameters are specified, set the format of the data to be sent or received: OK Write Command Query/set the output format of received data (only for buffer access mode and direct push mode) AT+QICFG='viewmode'[,] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'viewmode', OK If the optional parameter is specified, set the output format of the received data: OK Write Command Query/set the input data timeout AT+QICFG='qisend/timeout'[,] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'qisend/timeout', OK EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 14 / 54 LTE Standard Module Series If the parameter is specified, set the input data timeout: OK If there is any error: ERROR Write Command Response Query/set whether to display the If the parameter is omitted, query the current setting: data length in the URC format +QICFG: 'recvind', reported by the module after receiving data in buffer access OK mode If the parameter is specified, set whether to display the data length AT+QICFG='recvind'[,] in the URC reported by the module after receiving data in buffer access mode: OK Write Command Query/set the mode for sending UDP data AT+QICFG='udp/sendmode'[,] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'udp/readmode', OK If the optional parameter is specified, set the UDP data sending mode: OK Write Command Query/set the mode for reading UDP data AT+QICFG='udp/readmode'[,] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'udp/readmode', OK If the optional parameter is specified, set the UDP data reading mode: OK Write Command Query/set whether to send TCP If there is any error: ERROR Response If the optional parameters are omitted, query the current setting: EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 15 / 54 LTE Standard Module Series keep-alive information. AT+QICFG='tcp/keepalive',[,,,] +QICFG: 'tcp/keepalive',,,, OK If the optional parameters are specified, set whether to send TCP keep-alive information: OK Write Command Enable or disable the DNS cache AT+QICFG='dns/cache'[,] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'dns/cache', OK If the optional parameter is specified, enable or disable the DNS cache: OK Write Command Set the maximum length of a single transmission data AT+QICFG='send/buffersize'[,] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'send/buffersize', OK If the optional parameter is specified, set the maximum length of a single transmission data: OK Write Command Set the TCP protocol extension option windows scale AT+QICFG='windows/scale',[] If there is any error: ERROR Response If the optional parameters are omitted, query the current setting: +QICFG: 'windows/scale', OK If the parameter is specified, set the TCP protocol extension option windows scale: OK EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 16 / 54 LTE Standard Module Series Maximum Response Time Characteristic If there is any error: ERROR / The command takes effect immediately. The configurations are 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 , data will be sent. Range: 0–20. Default value: 2. Unit: 100 ms. Integer type. Maximum number of TCP retransmissions. Range: 3–20. Default value: 12. Integer type. Maximum interval between TCP retransmissions. Range: 5– 1000. Default value: 600. Unit: 100 ms. Integer type. Acceptance mode for the incoming TCP connection from client. 0 Manually accept the incoming TCP connection from the client 1 Automatically accept the incoming TCP connection from the client Integer type. Enable or disable the passive closing of TCP connection when the server is closed 0 Disable 1 Enable Integer type. Format of the data to be sent. The suffix '0x' is not needed when the mode is set as Hex mode as the module will automatically form two bytes to one ASCII code. 0 Text mode 1 Hex mode Integer type. Format of the data to be received. The suffix '0x' is not needed when the mode is set as Hex mode as the module will automatically form two bytes to one ASCII code. 0 Text mode 1 Hex mode Integer type. Output format of received data. 0 data headerrndata. 1 data header,data. Integer type. Timeout of AT+QISEND. After > is returned, if no data is inputted within the timeout period, AT+QISEND will be executed. Range: 0–3600. Default value: 0. Unit: ms. Integer type. In AT+QICFG='tcp/keepalive', it means whether to send TCP EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 17 / 54 LTE Standard Module Series keepalive. In AT+QICFG='recvind', it means whether to display the data length in the URC format of TCP/IP buffer access mode 0 Disable corresponding function 1 Enable corresponding function Integer type. 0 Block mode 1 Stream mode Integer type. 0 Block mode 1 Stream mode Integer type. Trigger keepalive time cycle. Range: 1–120. Default value: 1. Unit: minute. Integer type. Interval between keepalive probes. If the sender does not receive a response packet, it continues to send probe packets according to this interval. Range: 25–100. Default value: 25. Unit: second. Integer type. Number of keepalive probes. Range: 3–10. Default: 3 Integer type. Enable or disable DNS cache. 0 Disable 1 Enable Integer type. Maximum number of bytes sent at one time. Range: 1460–4096. Default value: 1460. Integer type. Whether to enable the TCP protocol extension option windows scale. 0 Disable 1 Enable NOTE The settings of AT+QICFG='tcp/retranscfg'[,,] and +QICFG: 'tcp/k eepalive',,,, take effect on all TCP sockets and cannot be saved to NV. 2.3.2. AT+QICSGP Configure Parameters of a TCP/IP Context This command configures , , 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 EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 18 / 54 LTE Standard Module Series Write Command Query the configuration of a specified context AT+QICSGP= Response +QICSGP: ,,,, OK Write Command Configure the context AT+QICSGP=[,,[,,)[,]]] Response OK If there is any error: ERROR Maximum Response Time / Characteristics The command takes effect immediately. The configurations are saved automatically. Parameter Integer type. 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: 127 bytes. String type. Password. Maximum length: 127 bytes. Integer type. Authentication methods. 0 None 1 PAP 2 CHAP 3 PAP or CHAP Example AT+QICSGP=1 +QICSGP: 1,'','','',0 //Query the configuration of context 1. OK AT+QICSGP=1,1,'UNINET','','',1 OK //Configure context 1. APN is 'UNINET' for China Unicom. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 19 / 54 LTE Standard Module Series 2.3.3. AT+QIACT Activate a PDP Context Before activating a PDP context via AT+QIACT, the context should be configured with AT+QICSGP. After activation, the IP address can be queried via AT+QIACT?. The range of is 1–15 and the module supports maximum three PDP contexts activated simultaneously under LTE Cat M1. Depending on the network, it may take maximum 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: 15,,[,]] Write Command Activate a specified PDP context AT+QIACT= Maximum Response Time OK Response OK If there is any error: ERROR 150 s, determined by the network. Characteristics / Parameter Integer type. Context ID. Range: 1–15. Integer type. Context state. 0 Deactivated 1 Activated Integer type. Protocol type. 1 IPv4 EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 20 / 54 LTE Standard Module Series 2 IPv6 3 IPv4v6 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/IP connections set up in this context. Depending on the network, it may take maximum 40 seconds 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= OK Response OK Maximum Response Time If there is any error: ERROR 40 s, determined by the network. Characteristics / Parameter Integer type. Context ID. Range: 1–15. 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 whether the socket service has been opened successfully. 1. If is 'TCP LISTENER', the module works as a TCP server, and there are two kinds of , automatic acceptance and manual acceptance. In automatic acceptance mode, after accepting a new TCP connection, the module automatically specifies and report the URC +QIURC: 'incoming',,,,. The range of is 0–11. The type of this new incoming connection is 'TCP INCOMING' and the EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 21 / 54 LTE Standard Module Series of 'TCP INCOMING' is the same as that of 'TCP LISTENER'. In manual acceptance mode, if there is a new incoming connection to be accessed, the module will report the URC +QIURC: 'accept',, and is the ID 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 via 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) OK Write Command AT+QIOPEN=,,,/,[,[,]] Response If the service is in transparent transmission (=2) and is opened successfully: CONNECT mode If there is any error: ERROR Error description can be retrieved via AT+QIGETERROR. If the service is in buffer access mode (=0) or direct push mode (=1): OK +QIOPEN: , Maximum Response Time is 0 when the service is opened successfully. In other cases, is not 0. 150 s, determined by the network. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 22 / 54 LTE Standard Module Series Characteristics / Parameter Integer type. Context ID. Range: 1–15. 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 to TCP connection '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', it can be omitted. 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. If is 'TCP LISTENER' or 'UDP SERVICE', specify this parameter as 0. Local port. Range: 0–65535. If is 'TCP LISTENER' or 'UDP SERVICE', this parameter must be specified. If is 'TCP' or 'UDP' and is 0, the local port will be assigned automatically. 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. Err code. See Chapter 4 for details. 2.3.6. AT+QICLOSE Close a Socket Service This command closes a specified socket service. Depending on the network, it takes maximum 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. AT+QICLOSE Close a Socket Service Test Command AT+QICLOSE=? Response +QICLOSE: (range of supported s),(range of supported s) EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 23 / 54 LTE Standard Module Series OK Write Command AT+QICLOSE=[,] Response If the socket service is closed successfully: OK Maximum Response Time If the command failed to close the socket service: ERROR Determined by Characteristics / 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 This 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=? Read/Execution Command AT+QISTATE? or AT+QISTATE Response OK Response Return the status of all existing connections: +QISTATE: ,,,< remote_port>,,,,< serverID>,, […] OK 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: ,,,< remote_port>,,,,< EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 24 / 54 LTE Standard Module Series serverID>,, […] OK Write Command If is 1, query the connection status of a specified socket service AT+QISTATE=, Response +QISTATE: ,,,< remote_port>,,,,< serverID>,, OK Maximum Response Time / 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–15. 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 connection 'TCP INCOMING' Start a TCP connection accepted by a TCP server 'UDP SERVICE' Start a UDP service 'SSL Client' Start an SSL connection as a client String type. IP address. If ='TCP' or 'SSL Client'' or 'UDP', it is the IP address of a remote server. If ='TCP LISTENER' or 'UDP SERVICE', it is the local IP address. If ='TCP INCOMING', it is the IP address of a remote client. Integer type. Remote port number. If ='TCP' or 'SSL Client' or 'UDP', it is the port of a remote server. If ='TCP LISTENER' or 'UDP SERVICE', the port is invalid. If ='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. Integer type. Socket service status. 0 'Initial': connection has not been established 1 'Opening': client is connecting or server is trying to listen EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 25 / 54 LTE Standard Module Series 2 'Connected': client/incoming connection has been established 3 'Listening': server is listening 4 'Closing': connection is closing Integer type. It is valid only when is 'TCP INCOMING'. represents which server accepts this TCP incoming connection, and the value is the same as when the is '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. 'usbmodem' USB modem port 'usbat' USB AT port 'uart1' UART port1 'cmux1' MUX port 1 'cmux2' MUX port 2 'cmux3' MUX port 3 'cmux4' MUX port 4 2.3.8. AT+QISEND Send Data In buffer access mode (=0) or direct push mode (=1), then the data can be sent via AT+QISEND. If the data is sent to the module successfully, SEND OK is returned. Otherwise, SEND FAIL or ERROR is returned. ⚫ SEND FAIL indicates the sending buffer is full. In this case, the 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. Maximum data length: 1460 bytes. ⚫ SEND OK means that the data have been sent to the peer, but it does not mean they have reached the peer successfully. You can query whether the data have reached the peer by 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' AT+QISEND= 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 EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 26 / 54 LTE Standard Module Series If the connection has been established and the data is sent successfully: SEND OK If the connection has been 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 has been established and the data is sent successfully: SEND OK If the connection has been established but the sending buffer is full: SEND FAIL If the connection has not been established, abnormally closed, or any parameter is incorrect: ERROR Write Command If is 'UDP SERVICE' AT+QISEND=,,, Response Sends fixed length data to a specified remote IP address and remote port. must be 'UDP SERVICE'. > After response >, input the data until the data length equals If the connection has been established and the data is sent successfully: SEND OK If the connection has been established but the sending buffer is full: SEND FAIL If the connection has not been established, abnormally closed, EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 27 / 54 LTE Standard Module Series or any parameter is incorrect: ERROR Write Command When is 0, query the sent data AT+QISEND=,0 Response If the specified connection exists: +QISEND: ,, OK Maximum Response Time Characteristics If the specified connection does not exist, or if there is any error: ERROR / / Parameter Integer type. Socket service index. Range: 0–11. Integer type. Length of data to be sent. Range: 0–1460. Unit: byte. String type. Remote IP address (must be dot format). It is valid only when is 'UDP SERVICE'. Integer type. Remote port. It is only valid 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 Received TCP/IP Data In buffer access mode, after receiving data, the module buffers it and reports URC +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 will not report a new URC until all received data has been retrieved via AT+QIRD from the buffer. AT+QIRD Retrieve Received TCP/IP Data Test Command AT+QIRD=? Response +QIRD: (range of supported s),(range of supported s) EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 28 / 54 LTE Standard Module Series OK Write Command When is 'TCP', 'UDP', 'TCP INCOMING' AT+QIRD=[,] Response If the specified connection has received the data: +QIRD: OK If there is no data: +QIRD: 0 OK If the connection does not exist: ERROR Write Command When is 'UDP SERVICE' AT+QIRD=[,] Response If data exists: +QIRD: ,, OK If there is 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: ,,< unread_length> OK Maximum Response Time Characteristics If there is any error: ERROR / / EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 29 / 54 LTE Standard Module Series Parameter Integer type. Socket service index. Range: 0–11. Integer type. Maximum length of data to be retrieved. Range: 0–1500. Unit: byte. Integer type. Length of actually retrieved data. Unit: byte. String type. Remote IP address. It is valid only when is 'UDP SERVICE'. Integer type. Remote port number. It is valid only when is 'UDP SERVICE'. Integer type. Retrieved data. Integer type. Total length of received data. Unit: byte. Integer type. Length of data that has been retrieved. Unit: byte. Integer type. Length of data that has not been retrieved. Unit: byte. 2.3.10. 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), 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 If the connection does not exist: ERROR / Characteristics / EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 30 / 54 LTE Standard Module Series Parameter Integer type. Socket service index. Range: 0–11. String type. Hex string data. Max length: 512 bytes. 2.3.11. AT+QIACCEPT Manually Accept New TCP Incoming Connection If is set to manually accept a new TCP incoming connection, after URC +QIURC: 'accept', is returned, the new TCP incoming connection can be accepted via AT+QIACCEPT. AT+QIACCEPT Manually Accept New TCP Incoming Connection Test Command AT+QIACCEPT=? Response +QIACCEPT: (range of supported s),(list of supported s),(range of supported < incoming_connectID>s) Write Command AT+QIACCEPT=,[,] OK Response If is 0: OK If is 1: OK +QIACCEPT: ,, Maximum Response Time If there is any error: ERROR / Characteristics / Parameter Integer type. ID of 'TCP LISTENER'. Range: 0–11. Integer type. Accept or refuse the incoming connection. 0 Refuse 1 Accept Integer type. ID of the incoming connection to be accepted. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 31 / 54 LTE Standard Module Series String type. Remote client address. Integer type. Remote client port. Range: 1–65535. 2.3.12. 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 parameter of AT+QIOPEN. After opening a socket, the data access mode can be changed via 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 Response AT+QISWTMD=, is 0 or 1: OK If data access mode is switched successfully and is 2, the module will enter the intended data mode: CONNECT Maximum Response Time If there is any error: ERROR / Characteristics / Parameter 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 EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 32 / 54 LTE Standard Module Series 2.3.13. AT+QPING Ping a Remote Host The 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 via AT+QIACT. The command returns the result within and the default value of is 4 seconds. AT+QPING Ping a Remote Host Test Command AT+QPING=? Response +QPING: (range of supported s),,(range of supported s),(range of supported s) Write Command AT+QPING=,[,[,]] OK Response If a remote server is pinged successfully: OK [+QPING: [,,,,< ttl>]…] […] +QPING: [,,,,,,] Maximum Response Time If there is any error: ERROR / Characteristics / Parameter Integer type. Context ID. Range: 1–15. 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. Range: 1–255. Default value: 4. Unit: second. Integer type. Maximum number of times for sending ping request. 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 ,,,,. Other values Err code. See Chapter 4 for details. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 33 / 54 LTE Standard Module Series String type. IP address of the remote host formatted as a dotted decimal IP. Integer type. Length of each sent ping request. Unit: byte. Integer type. Waiting time for the response to 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 ,,,,,. Other values Err code. See Chapter 4 for details. Integer type. Total number of sent ping requests. Integer type. Total number of the ping requests that 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.14. AT+QNTP Synchronize Local Time with NTP Server This command synchronizes the local time with Universal Time Coordinated (UTC) through the NTP server. Before time synchronization, the host should activate the context corresponding to via AT+QIACT. Depending on the network, it will take maximum 125 seconds to return the result. 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 If there is any error: ERROR 125 seconds, determined by the network. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 34 / 54 LTE Standard Module Series Characteristics / Parameter Integer type. Context ID. Range: 1–15. String type. NTP server address. Integer type. NTP server port. Range:1–65535. Integer type. Whether to automatically set synchronized time as local time. 0 Do not set 1 Set Integer type. Err code. See Chapter 4 for details. String type. Time synchronized from NTP server. Format: 'YYYY/MM/DD,hh:mm:sszz'. Range of zz: -48 to +56. 2.3.15. AT+QIDNSCFG Configure Address of DNS Server This command configures the address of DNS server. Before setting the DNS address, the host must activate the context of corresponding via 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 and are omitted, query the current DNS server addresses of a specified PDP context: +QIDNSCFG: ,, OK If and are specified, configure the primary and secondary DNS server addresses of a specified PDP context: OK Maximum Response Time Characteristics If there is any error: ERROR / / EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 35 / 54 Parameter LTE Standard Module Series Integer type. PDP context ID. Range: 1–15. String type. Primary DNS server address. String type. Secondary DNS server address. 2.3.16. 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 via AT+QIACT. Depending on the network, it will take maximum 60 seconds to return the result. .AT+QIDNSGIP Get IP Address by Domain Name Test Command AT+QIDNSGIP=? Response +QIDNSGIP: (range of supported s), Write Command AT+QIDNSGIP=, OK Response OK If there is any error: ERROR Maximum Response Time Characteristics The result will be returned as URC. +QIURC: 'dnsgip',,, [..... +QIURC: 'dnsgip',] 60 seconds, determined by the network. / Parameter Integer type. PDP context ID. Range: 1–15. String type. Domain name. Integer type. Err code. See Chapter 4 for details. Integer type. Number of IP addresses corresponding to . Integer type. Time to live of the DNS. Unit: second. String type. IP address of . EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 36 / 54 LTE Standard Module Series 2.3.17. AT+QISDE Control Whether to Echo Data for AT+QISEND This command controls whether to echo the data for AT+QISEND. AT+QISDE Control Whether to Echo 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= OK Response OK Maximum Response Time If there is any error: ERROR / Characteristics / Parameter Numeric type. Whether to echo the data for AT+QISEND. 0 Do not echo the data 1 Echo the data 2.3.18. AT+QIGETERROR Query Last Error Code If ERROR is returned after executing TCP/IP commands, the detailed information about an error code can be queried via AT+QIGETERROR. Please note that AT+QIGETERROR just returns the error code of the last TCP/IP AT command. AT+QIGETERROR Query Last Error Code Test command AT+QIGETERROR=? Execution Command AT+QIGETERROR Response OK Response +QIGETERROR: , EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 37 / 54 OK Maximum Response Time / Characteristics / LTE Standard Module Series Parameter Integer type. Error codes of the operation. See Chapter 4 for details. String type. String parameter indicates the details of error information. See Chapter 4 for details. 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 so on. Actually, there is both before and after URC, but is intentionally not presented. 2.4.1. +QIURC: 'closed' Indicate Closed Connection When TCP socket service is closed by remote peer or due to network error, the URC will be outputted, and the status of socket service will be 'closing' (=4). AT+QICLOSE= can be used to change the to initial. +QIURC: 'closed' Indicate Closed Connection +QIURC: 'closed', Socket service connection is closed. Parameter Integer type. Socket service index. Range: 0–11. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 38 / 54 LTE Standard Module Series 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. Then host can retrieve data via AT+QIRD. 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', Indicates incoming data in buffer access mode. The host can retrieve data via AT+QIRD. +QIURC: 'recv',, is 'TCP', 'UDP', 'UPD INCOMING' or 'TCP INCOMING'. +QIURC: 'recv',,,,<remote_ is 'UDP SERVICE'. port> Parameter Integer type. Socket service index. Range: 0–11. Integer type. Length of actually received data. Range: 0-1500. Unit:byte. String type. Remote IP address. Integer type. Remote port number. Received data. Unit: byte. 2.4.3. +QIURC: 'incoming full' Indicate Incoming Connection Reached Limit If the incoming connection reaches the limit, or no socket system resources can be allocated, then the module will report the URC as +QIURC: 'incoming full' for the new incoming connection request. +QIURC: 'incoming full' Indicate Incoming Connection Reached Limit +QIURC: 'incoming full' Indicates the number of incoming connections has reached the limit. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 39 / 54 LTE Standard Module Series 2.4.4. +QIURC: 'incoming' Indicate Incoming Connection in Automatic Acceptance Mode If is 'TCP LISTENER', when a remote client connects to this server, and if is automatic acceptance, the module will automatically assign a free for the new connection. The range of is 0 to 11. In such a case, the module will report the URC. of the new connection will be 'TCP INCOMING', and will be assigned as of 'TCP LISENTER'. +QIURC: 'incoming' Indicate Incoming Connection in Automatic Acceptance Mode +QIURC: 'incoming',<connectI When the new incoming connection is accepted by , the D>,,,<re allocated , and are mote_port> 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. It is valid only when is 'TCP INCOMING'. represents which server accepts this TCP incoming connection, and the value is the same as when the is 'TCP LISTENER'. String type. Remote IP address of the incoming . Integer type. Remote port number of the incoming . 2.4.5. +QIURC: 'accept' Indicate Incoming Connection in Manual Acceptance Mode If the is 'TCP LISTENER', when a remote client connects to this server, and if the is manual acceptance, the module will report the URC. +QIURC: 'accept' Indicate Incoming Connection in Manual Acceptance Mode +QIURC: 'accept', AT+QIACCEPT to accept or refuse the incoming connection. Parameter Integer type. ID of 'TCP LISTENER'. Range: 0–11. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 40 / 54 LTE Standard Module Series 2.4.6. +QIURC: 'pdpdeact' Indicate PDP Deactivation PDP context may be deactivated by the network. The module reports the 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–15. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 41 / 54 LTE Standard Module Series 3 Examples 3.1. Configure and Activate a Context 3.1.1. Configure a Context AT+QICSGP=1,1,'UNINET','','',1 OK //Configure context 1. APN is 'UNINET' for China Unicom. 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. 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 AT+QIOPEN=1,0,'TCP','220.180.239.212',8009,0,0 //Context is 1 and is 0. Before using AT+QIOPEN, the host should activate EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 42 / 54 LTE Standard Module Series the context with AT+QIACT first. 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 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.201',8009,65514,2,1,0,0,'usbmodem' OK 3.2.2. Send Data in Buffer Access Mode AT+QISEND=0 > test1 SEND OK //Send variable-length data. //SEND OK does not mean the data has been sent to the server successfully. The host can query whether the data has reached the server via AT+QISEND=0,0. AT+QISEND=0,4 > test SEND OK AT+QISEND=0,0 +QISEND: 9,9,0 //Send fixed-length data and the data length is 4 bytes. //Query the length of sent data, acknowledged data and unacknowledged data. OK AT+QISENDEX=0,'3132333435' SEND OK AT+QISEND=0,0 +QISEND: 14,14,0 //Send Hex string data. //Query the length of sent data, acknowledged data and unacknowledged data. OK 3.2.3. Retrieve Data from Remote Server in Buffer Access Mode +QIURC: 'recv',0 //The received data when =0. AT+QIRD=0,1500 //Retrieve data, and the maximum length of data to be retrieved is 1500 EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 43 / 54 LTE Standard Module Series bytes. +QIRD: 5 test1 OK AT+QICFG='recvind',1 OK +QIURC: 'recv',0,5 AT+QIRD=0,1500 +QIRD: 5 test1 OK AT+QIRD=0,1500 +QIRD: 0 OK AT+QIRD=0,0 +QIRD: 10,10,0 OK //The length of actually retrieved data is 5 bytes. //Received data is 5 bytes when =0. //Retrieve data, and the length is 1500 bytes. //The length of actual received data is 5 bytes. //No data in buffer. //Query the total length of received data, including read and unread data. 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 Transparent Transmission Mode 3.3.1. Set up a TCP Client Connection and Enter Transparent Transmission Mode AT+QIOPEN=1,0,'TCP','220.180.239.212',8009,0,2 //Context is 1 and is 0. Before using AT+QIOPEN, the host should activate the context with AT+QIACT. CONNECT //TCP client is 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. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 44 / 54 LTE Standard Module Series 3.3.2. Send Data in Transparent Transmission Mode 3.3.3. Retrieve Data from Remote Server in Transparent Transmission Mode Test 1 //All data received from the Internet are outputted via COM port directly. 3.3.4. Close a TCP Client 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. 3.4. TCP Client Works in Direct Push Mode 3.4.1. Set up a TCP Client Connection and Enter Direct Push Mode AT+QIOPEN=1,0, »TCP », »220.180.239.212 »,8009,0,1 //Context is 1 and is 0. Before using AT+QIOPEN, the host should activate the context via AT+QIACT. 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 could use AT+QICLOSE to close the socket. AT+QISTATE=1,0 //Query if the connection state socket service 0. +QISTATE: 0,'TCP','220.180.239.201',8009,65344,2,1,0,1,'usbmodem' OK EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 45 / 54 LTE Standard Module Series 3.4.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 has been sent to the server successfully. Host can query whether the data has reached the server via 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.4.3. Receive Data from Remote Server in Direct Push Mode +QIURC: 'recv',0,4 test //Retrieve data from remote server. 3.4.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.5. TCP Server Works in Buffer Access Mode under IPv4 3.5.1. Start a TCP Server AT+QIOPEN=1,1,'TCP LISTENER','127.0.0.1',0,2020,0 //Context is 1 and is 1. Before using AT+QIOPEN, the host should activate the context with AT+QIACT. OK +QIOPEN: 1,0 //TCP server is opened successfully. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 46 / 54 LTE Standard Module Series AT+QISTATE=0,1 //Query the connection the connection status of context 1. +QISTATE: 1,'TCP LISTENER','10.7.157.1',0,2020,3,1,1,0,'usbmodem' OK 3.5.2. Accept TCP Incoming Connection +QIURC: 'incoming',11,1,'172.31.242.222',54091 //A new TCP connection is accepted. is 'TCP incoming', and is 11. 3.5.3. Retrieve Data from Incoming Connection +QIURC: 'recv',11 AT+QIRD=11,1500 +QIRD: 4 test OK AT+QIRD=11,1500 +QIRD: 0 OK AT+QIRD=11,0 +QIRD: 4,4,0 OK //Received data from remote incoming connection. //Retrieve 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.5.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. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 47 / 54 LTE Standard Module Series 3.6. UDP Service under IPv4 3.6.1. Start a UDP Service AT+QIOPEN=1,2,'UDP SERVICE','127.0.0.1',0,3030,0 //Start a UDP service whose is 2 and is 1. Before using AT+QIOPEN, the host should activate the context with AT+QIACT. OK +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,'usbmodem' OK 3.6.2. Send UDP Data to Remote Client AT+QISEND=2,10,'10.7.89.10',6969 >1234567890 SEND OK //Send 10 bytes data to remote client whose IP is 10.7.89.10 and the remote port is 6969. 3.6.3. Retrieve Data from Remote Client +QIURC: 'recv',2 AT+QIRD=2 +QIRD: 4,'10.7.76.34',7687 AAAA OK AT+QIRD=2 +QIRD: 0 OK AT+QISEND=2,10,'10.7.76.34',7687 >1234567890 //Received data from remote client. //Retrieve UDP data. One whole UDP packet will be outputted. There is no need to specify the read length. //Retrieved data length is 4. The remote IP address is 10.7.76.34 and remote port is 7687. //Retrieve data. //No data in buffer. //Send data to the remote client whose IP is 10.7.76.34 and remote port is 7687. EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 48 / 54 SEND OK 3.6.4. Close a UDP Service AT+QICLOSE=2 OK LTE Standard Module Series //Close the service. 3.7. 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,288 //Ping www.baidu.com in context 1. Before pinging the destination IP address, the host should activate the context via AT+QIACT. 3.8. Synchronize Local Time AT+QNTP=1,'202.112.10.36',123 OK //Synchronize local time with NTP server '202.112.10.36:123'. Before synchronizing the time, the host should activate the context with AT+QIACT. +QNTP: 0,'2019/07/21,06:10:59+00' AT+CCLK? +CCLK: '19/07/21,06:11:05+00' OK EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 49 / 54 LTE Standard Module Series 3.9. Get 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 EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 50 / 54 LTE Standard Module Series 4 Summary of Error Codes If an ERROR is returned after executing TCP/IP AT commands, the detailed information about errors can be queried via AT+QIGETERROR. Please note that AT+QIGETERROR just returns error code of the last TCP/IP AT command. Table 2: Summary of Error Codes 0 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 operate success Unknown error Operation blocked Invalid parameters Memory not enough Socket creation 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 EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 51 / 54 LTE Standard Module Series 565 Dns parse failed 566 Socket connect failed 567 Socket has been closed 568 Operation busy 569 Operation timeout 570 PDP context broken down 571 Cancel sending 572 Operation not allowed 573 APN not configured 574 Port busy EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 52 / 54 LTE Standard Module Series 5 Appendix References Table 3: Terms and Abbreviations Abbreviation 3GPP ACK APN ASCII CHAP CS DNS DTR FIN ID IP IPv4 IPv6 LTE NB-IoT NTP NVM PAP PDP PPP Description 3rd Generation Partnership Project Acknowledge Access Point Name American Standard Code for Information Interchange Challenge Handshake Authentication Protocol Circuit Switching 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 Packet Data Protocol Point-to-Point Protocol EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 53 / 54 PSSACK PS QoS TCP TTL UART UDP URC USB (U)SIM UTC LTE Standard Module Series Packet SwitchingSelective Acknowledgment Packet Switching Quality of Service Transmission Control Protocol Time To Live Universal Asynchronous Receiver& Transmitter User Datagram Protocol Unsolicited Result Code Universal Serial Bus (Universal) Subscriber Identity Module Coordinated Universal Time EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note 54 / 54

Quectel_EG800Q-EU&EG915Q-NA_TCP(IP)_Application_Note_V1.0

PDF

474.03 KB

EG800Q&EG91xQ Series MQTT Application Note LTE Standard Module Series Version: 1.1 Date: 2023-09-05 Status: Released LTE Standard 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. EG800Q&EG91xQ_Series_MQTT_Application_Note 1 / 35 LTE Standard 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. 2023. All rights reserved. EG800Q&EG91xQ_Series_MQTT_Application_Note 2 / 35 LTE Standard Module Series About the Document Revision History Version 1.0 1.1 Date Author Description 2022-11-15 Greyson DONG Creation of the document 2023-01-31 2023-09-05 Greyson DONG Greyson DONG First official release Updated the applicable modules: ⚫ Added EG916Q-GL. ⚫ Updated EG800Q-EU to EG800Q series. EG800Q&EG91xQ_Series_MQTT_Application_Note 3 / 35 LTE Standard Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 2 MQTT Data Interaction........................................................................................................................ 7 3 MQTT-Related 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 Related 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 ................................. 18 3.3.3. AT+QMTCLOSE Close a Network Connection for MQTT Client.................................. 19 3.3.4. AT+QMTCONN Connect a Client to MQTT Server.................................................... 20 3.3.5. AT+QMTDISC Disconnect a Client from MQTT Server ............................................. 21 3.3.6. AT+QMTSUB Subscribe to Topics ............................................................................. 22 3.3.7. AT+QMTUNS Unsubscribe from Topics ..................................................................... 23 3.3.8. AT+QMTPUBEX Publish Messages .......................................................................... 25 3.3.9. AT+QMTRECV Read Messages from Buffer ............................................................. 26 4 MQTT URCs ....................................................................................................................................... 28 4.1. +QMTSTAT URC to Indicate the Reason for State Change in MQTT Link Layer ................ 28 4.2. +QMTRECV URC to Notify Host to Read MQTT Packet Data ............................................. 29 4.3. +QMTPING URC to Indicate Keep-Alive Timeout in MQTT ................................................. 30 5 Examples ........................................................................................................................................... 31 5.1. Example of MQTT Operation Without SSL.............................................................................. 31 5.2. Example of MQTT Operation with SSL.................................................................................... 33 6 Appendix References ....................................................................................................................... 35 EG800Q&EG91xQ_Series_MQTT_Application_Note 4 / 35 LTE Standard Module Series Table Index Table 1: Types of AT Commands ................................................................................................................. 8 Table 2: MQTT URCs ................................................................................................................................. 28 Table 3: Error Codes of the URC ............................................................................................................... 29 Table 4: Related Documents ...................................................................................................................... 35 Table 5: Terms and Abbreviations .............................................................................................................. 35 EG800Q&EG91xQ_Series_MQTT_Application_Note 5 / 35 LTE Standard Module Series 1 Introduction Quectel LTE Standard EG800Q series, EG915Q-NA and EG916Q-GL modules support MQTT. MQTT is a broker-based publish/subscribe messaging protocol designed to be open, simple, light-weight and user-friendly. It is designed for connections with remote locations requiring a 'small code footprint' or limited network bandwidth. This document outlines how to use the MQTT function of EG800Q series, EG915Q-NA and EG916Q-GL modules through AT commands. EG800Q&EG91xQ_Series_MQTT_Application_Note 6 / 35 LTE Standard Module Series 2 MQTT Data Interaction This chapter gives the data interaction mechanism of MQTT function. MCU Modem Link Layer MQTT Server AT+QMTCFG= will client_idx>, AT+QMTCFG= timeout client_idx>, AT+QMTOPEN=<client_idx , port> 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 +QMTSUB:,,[,] SUB-REQ (msgID) Start timer T1 SUB ACK-IND (msgID) Stop T1 or handle Excep2 AT+QMTUNS AT+QMTUNS=,... OK UNS-REQ (msgID) Start timer T1 +QMTUNS: ,,[,] AT+QMTPUBEX=,,=0, ,, OK UNS ACK-IND (msgID) Stop T1 or handle Excep2 PUB-REQ AT+QMTPUBEX AT+QMTPUBEX=,,=1, (=1) ,, OK PUB-REQ (msgID) Start timer T1 PUB ACK-IND (msgID) +QMTPUBEX: ,,[,] Stop T1 or handle Excep2 AT+QMTPUBEX AT+QMTPUBEX=,,=2, (=2) ,, OK PUB-REQ (msgID) Start timer T1 PUB REC-IND (msgID) Stop T1 or handle Excep2 PUB REL-REQ (msgID) Start timer T1 PUB COMP-IND (msgID) +QMTPUBEX: ,,[,] 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 a packet transmission timeout. T2 is a 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 by AT+QMTCFG. Whether the timeout information is reported can be configured by AT+QMTCFG. Receive PUBLISH Receive message in the form of a URC. +QMTRECV: ,,, PUB-IND (msgID) PUB ACK/REC-REQ (msgID) Reply accor.d.i.ng to AT+QMTDISC= OK +QMTDISC: , AT+QMTCLOSE= OK +QMTCLOSE: , DISC-REQ TCP-REQ TCP disconnected Receive publish packet Send publish reply packet Send disconnect packet TCP discon..n. ect request Note: refers to optional parameters. For more details about optional parameters, refer to the description of corresponding AT command in Chapter 3.3. Figure 1: MQTT Data Interaction Diagram EG800Q&EG91xQ_Series_MQTT_Application_Note 7 / 35 LTE Standard Module Series 3 MQTT-Related AT Commands This chapter presents the AT commands for implementing the MQTT function. 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 corresponding Command and return information about the type, value, or range of its parameter. Check the current parameter value of a corresponding Command. AT+=[,[,[...]]] Set user-definable parameter value. EG800Q&EG91xQ_Series_MQTT_Application_Note 8 / 35 Execution Command AT+ LTE Standard 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 Related 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),'willtopic','willmessage' +QMTCFG: 'willex',(range of supported s),(list of supported s),(range of supported s),(list of supported s),'willtopic',(range of supported s) +QMTCFG: 'recv/mode',(range of supported s),(list of EG800Q&EG91xQ_Series_MQTT_Application_Note 9 / 35 LTE Standard Module Series supported s),(list of supported s) +QMTCFG: 'qmtping',(range of supported s),(range of supported s) +QMTCFG: 'send/mode',(range of supported s),(list of supported s) +QMTCFG: 'aliauth',(range of supported s),'product_key','device_name','device_secret' +QMTCFG: 'onenet',(range of supported s),'product_id','access_key' +QMTCFG: 'dataformat',(range of supported s),(list of supported s),(list of supported s) +QMTCFG: 'view/mode',(range of supported s),(list of supported s) +QMTCFG: 'edit/timeout',(range of supported s),(list of supported s),(range of supported s) +QMTCFG: 'hwauth',((range of supported s), 'devic e_id','hw_device_secret',(list of supported ) +QMTCFG: 'hwprodid',((range of supported s), 'hw_product_id','product_secret','node_id' OK Write Command Response Query/set the MQTT protocol If the optional parameter is omitted, query the MQTT protocol version: version +QMTCFG: 'version', AT+QMTCFG='version',[,] OK If the optional parameter is specified and the MQTT connection is not established, 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 and the MQTT connection is not established, set the PDP to be used by the MQTT client: OK EG800Q&EG91xQ_Series_MQTT_Application_Note 10 / 35 LTE Standard Module Series 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 the optional parameters are specified and the MQTT connection is not established, set the MQTT SSL mode and SSL context index: OK Write Command Query/set the keep-alive time AT+QMTCFG='keepalive',[,] If there is any error: ERROR Response If the optional parameter is omitted, query the keep-alive time: +QMTCFG: 'keepalive', OK If the optional parameter is specified and the MQTT connection is not established, 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 and the MQTT connection is not established, set the session type: OK Write Command Query/set message delivery timeout AT+QMTCFG='timeout',<cli If there is any error: ERROR Response If the optional parameters are omitted, query the message delivery timeout: +QMTCFG: 'timeout',,,[,, try_times>, ] OK If the optional parameters are specified and the MQTT connection is not established, set the message delivery timeout: OK Write Command Query/set Will information AT+QMTCFG='will',[,[,,< will_retain>,,]] If there is any error: ERROR Response If the optional parameters are omitted, query the current Will information: +QMTCFG: 'will',[,,,, ] OK If the optional parameters are specified and the MQTT connection is not established, set the Will information: OK Write Command Query/set Will information AT+QMTCFG='willex',[,[, ,,,]] If there is any error: ERROR Response If the optional parameters are omitted, query the current setting: +QMTCFG: 'willex',[,,,,] OK If the optional parameters are specified, set the Will information: > Input Will messages. When the actual size of data is greater than , the data length exceeding will be discarded. OK If there is any error: ERROR Write Command Response Query/set receiving mode If the optional parameters are omitted, query the MQTT message when data is received from receiving mode: server +QMTCFG: 'recv/mode',, AT+QMTCFG='recv/mode',< EG800Q&EG91xQ_Series_MQTT_Application_Note 12 / 35 LTE Standard Module Series client_idx>[,[,]] OK If the optional parameters are specified and the MQTT connection is not established, set the receiving mode when data is received from server: OK Write Command Query/set the MQTT heartbeat interval AT+QMTCFG='qmtping',[,] If there is any error: ERROR Response If the optional parameter is omitted, query the MQTT heartbeat interval: +QMTCFG: 'qmtping', OK If the optional parameter is specified, and the MQTT connection is not established, configure the MQTT heartbeat interval: OK Write Command Query/set the MQTT message sending mode AT+QMTCFG='send/mode', [,] If there is any error: ERROR Response If the optional parameter is omitted, query the MQTT message sending mode: +QMTCFG: 'send/mode', OK If the optional parameter is specified, and the MQTT connection is not established, set the MQTT message sending mode: OK Write Command Query/set Alibaba device information for AliCloud AT+QMTCFG='aliauth',[,,,] 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 and the MQTT connection is not established, set Alibaba device information for AliCould: EG800Q&EG91xQ_Series_MQTT_Application_Note 13 / 35 LTE Standard Module Series OK If there is any error: ERROR Write Command Response Query/set the MQTT device for If the optional parameters are omitted, query the MQTT device: China Mobile OneNET IoT +QMTCFG: 'onenet',, platform AT+QMTCFG='onenet',[,,] If the optional parameters are specified, and the MQTT connection is not established, set the MQTT device for OneNET IoT platform: OK Write Command Query/set the MQTT data format AT+QMTCFG='dataformat', [,, ] If there is any error: ERROR Response If the optional parameters are omitted, query the MQTT data format: +QMTCFG: 'dataformat',, OK If the optional parameters are specified, and the MQTT connection is not established, set the MQTT data format: OK Write Command Query/set the MQTT data view mode in transparent mode AT+QMTCFG='view/mode', [,] If there is any error: ERROR Response If the optional parameter is omitted, query the MQTT data view mode in transparent mode: +QMTCFG: 'view/mode', OK If the optional parameter is specified, and the MQTT connection is not established, set the MQTT data view mode in transparent mode: OK Write Command Query/set the timeout message editing If there is any error: ERROR Response of If the optional parameters

Products

Services

Support

About

Industries

Technologies

Resources

Masterclasses

Interactive Resources

Download Zone

Antenna Brochure

Application Note