Download Zone
Select the files you need to support your use of Quectel’s products
Loading...
Filter
File Type
Product Categories
Relevant Technologies
Welcome to the Quectel Download Zone!
Please use the search bar and filters to find the files you need to support your use of our products. You can also find these listed on the relevant pages of our Product Selector.
Access to most files will require a user account, so please either log in or register to download the files available to you.
Antenna Brochure
1 Contents 01 Quectel Antenna Services 01 Quectel Advantages 01 Instruments 02 5G Antennas 04 Cellular (4G/3G/2G) Antennas 08 GNSS Antennas 14 Wi-Fi & Bluetooth Antennas 15 Combo Antennas 17 ISM Antennas 17 Cable Assemblies Quectel Antenna Services Consulting & Evaluation ■ Feasibility & Architecture Study ■ Risk Identification ■ Initial Proof of Concept ■ Antenna Component Selection Testing & Certification ■ Antenna OTA Testing ■ Interference Mitigation ■ Support for CE/FCC/PTCRB Radio Approval ■ Pre-certification OTA Testing for 2G/3G/4G/5G Quectel Advantages Solutions for the Entire Wireless RF Front End Complete RF Antenna Testing Services Global One Stop Engineering Support Vertical Integration of Antenna Resources Approved for Use with Quectel Modules Instruments Design ■ Antenna Placement ■ Antenna Layout Design ■ RF Specification Design ■ Antenna System Design & Optimization ■ Gerber File Review Manufacturing ■ Antenna Samples ■ Tooling & Molding ■ Assembly and Production Testing ■ Delivery Antenna Module Engineering Support Keysight CATR2305G Rhode & Schwarz WPTC-XS RayZone2800 ETS-AMS-8923-150 1 Quectel Antennas 5G Antennas Product YE0001BA YE0003AA YE0007AA YE0025AA Frequency Bands (MHz) 600–6000 Technology 5G Cable Length (mm) n/a Connector Type SMA Male (center pin) Mounting Type Terminal Dimensions (mm) 221 × 26.95 × 13.5 Matched Quectel Modules 5G/4G/3G/2G/LPWA 699–5000 5G n/a SMA Male (center pin) Terminal 190 × Φ 16 600–6000 5G n/a SMA Male (center pin) Terminal 152.4 × 21.79 × 14.49 698–960,1710–5000 5G n/a SMA Male (center pin) Terminal 199 × 22 5G Antennas Product YE0027AA YE0028AA YE0037AA YXH001AA YBY00A0KA Frequency Bands (MHz) 699–5000 Technology 5G Cable Length (mm) 3000 Connector Type SMA Male (center pin) Mounting Type Magnetic Dimensions (mm) 221 × Φ 61 Matched Quectel Modules 5G/4G/3G/2G/LPWA 700–2700, 3300–5000 5G 1500 SMA Male (center pin) Magnetic 234 × Φ 60 700–5000 5G 1000 SMA Male (center pin) Magnetic 88 × Φ 30 700–960, 1710–2690, 3300–5000 5G 1000 SMA Male (center pin) Magnetic 285 × 45 700–960, 1710–2690, 3300–5000 5G n/a N-J (Male pin with internal thread) Terminal Φ 20 × 300 The parameters shall be subject to the Specification. 2 Quectel Antennas 5G Antennas Product YF0002AA YF0002BA YF0002CA YF0002DA Frequency Bands (MHz) 700-960, 1710-2700, 3300-5000 Technology 5G 1710-2700, 3300-5000 5G Cable Length (mm) n/a n/a Connector Type Spring contact Spring contact Mounting Type Screw Screw Dimensions (mm) 60.1 × 12.25 × 10.1 Matched Quectel Modules 5G/4G/3G/2G/LPWA 41.25 × 10.1 × 10.1 1710-2700, 3300-5000 5G n/a Spring contact Screw 37.25 × 9.6 × 10.1 700-960, 1710-2700, 3300-5000 5G n/a Spring contact Screw 50.25 × 20.1 × 10.1 5G Antennas Product YF0017AA YF0017BA YF0020AA YC0018AA YC0018AAEVB Frequency Bands (MHz) 1500–6000 Technology 5G Cable Length (mm) 193 ±3 Connector Type IPEX Ⅳ Mounting Type Adhesive Dimensions (mm) 49 × 13 × 0.13 Matched Quectel Modules 5G/4G/3G/2G/LPWA 1100–6000 5G 193 ±3 IPEX Ⅳ Adhesive 49 × 13 × 0.13 600–6000 5G 184 ±3 IPEX Ⅳ Adhesive 90.15 × 15.2 × 0.13 617-6000 5G n/a n/a SMD 42 × 7 × 3 617-6000 5G n/a n/a n/a 140 × 40.4 The parameters shall be subject to the Specification. 3 Quectel Antennas 5G Antennas Product YP0009AA YP0009BA YP0009CA Frequency Bands (MHz) 1500–6000 Technology 5G Cable Length (mm) 193 ±3 Connector Type IPEX Ⅳ Mounting Type Adhesive Dimensions (mm) 49 × 13 × 0.85 Matched Quectel Modules 5G/4G/3G/2G/LPWA 1100–6000 5G 193 ±3 IPEX Ⅳ Adhesive 49 × 13 × 0.85 600–6000 5G 188 ±3 IPEX Ⅳ Adhesive 78.5 × 14.2 × 0.85 Cellular (4G/3G/2G) Antennas Product YC0001AA YC0002AA YC0003AA YC0003AAEVB YC0017BA YC0017BAEVB Frequency Bands 698–960, (MHz) 1710–2690 Technology LTE (4G) Cable Length (mm) n/a Connector Type n/a Mounting Type SMD Dimensions (mm) 35.0 × 8.5 × 3.0 Matched Quectel Modules 4G/3G/2G/LPWA 698–960, 1710–2690 LTE (4G) n/a n/a SMD 42 × 10 × 3 The parameters shall be subject to the Specification. 4 698-2700 LTE (4G) n/a n/a SMD 40 × 7 × 3 698-2700 LTE (4G) n/a n/a n/a 120 × 43 698-3800 LTE (4G) n/a n/a SMD 26 × 8 × 3 698-3800 LTE (4G) n/a n/a n/a 140 × 36 Quectel Antennas Cellular (4G/3G/2G) Antennas Product YF0022AA YF0007BA YPCA004AA Frequency Bands (MHz) 700–2690 Technology LTE (4G) Cable Length (mm) 75 ±3 Connector Type RF1 Mounting Type Adhesive Dimensions (mm) 40 × 15 × 1.6 Matched Quectel Modules 4G/3G/2G/LPWA 600–960, 1427.9–1495.9, 1710–2170, 2300–2700 LTE (4G) 75 ±3 RF1 Adhesive 50 × 25 × 0.85 Cellular (4G/3G/2G) Antennas Product YFCA002AA YF0006DA 700–2690 LTE (4G) 100 ±3 IPEX Ⅰ Adhesive 40 ×10 × 1 YF0028AA Frequency Bands (MHz) 700–2690 Technology LTE (4G) Cable Length (mm) 75 ±3 Connector Type RF1 Mounting Type Adhesive Dimensions (mm) 30 × 20 × 0.13 Matched Quectel Modules 4G/3G/2G/LPWA 690–960, 1710–2170, 2300–2690 LTE (4G) 75±3 IPEX Ⅰ Adhesive 50 × 25 × 0.13 698-3000 LTE (4G) 150 ±2 IPEX Ⅰ Adhesive 96 × 21 × 0.2 The parameters shall be subject to the Specification. 5 Quectel Antennas Cellular (4G/3G/2G) Antennas Product YECT002AA YECT003AA YE0009AA YPR00A0AA YCN001AA Frequency Bands (MHz) 700–960,1710–2690 Technology LTE (4G) Cable Length (mm) n/a Connector Type SMA Male (center pin) Mounting Type Terminal Dimensions (mm) 196.2 × 16 × 13 Matched Quectel Modules 4G/3G/2G/LPWA 698-960, 1710-2700 LTE (4G) n/a SMA Male (center pin) Terminal 113× Φ 10 824–2700 LTE (4G) n/a SMA Male (center pin) Terminal 190 × 16 700–2700 LTE (4G) n/a SMA Male (center pin) Terminal 194.3 ×15.95 700–2700 LTE (4G) n/a SMA Male (center pin) Terminal 144 × Φ 13 Cellular (4G/3G/2G) Antennas Product YE0006AA YE0010AA YB0010AA YB0016AA Frequency Bands (MHz) 700–2700 Technology LTE (4G) Cable Length (mm) 1500 Connector Type SMA Male (center pin) Mounting Type Magnetic Dimensions (mm) 318 × Φ 30 Matched Quectel Modules 4G/3G/2G/LPWA 698–2700 LTE (4G) 1000 ±30 SMA Male (center pin) Adhesive 152 × 18 × 5.9 The parameters shall be subject to the Specification. 6 698–960, 1710–2690 LTE (4G) 2000 ±30 SMA Male Magnetic Φ 81.5 × 16 698–960, 1710–2700 LTE (4G) 3000 ±50 SMA Male (center pin) Screw 54 × 91 Quectel Antennas Cellular (4G/3G/2G) Antennas Product YE0012AA YE0021AA YE0029AA Frequency Bands 824–960, (MHz) 1710–2690 Technology LTE (4G) Cable Length (mm) 250 ±10 Connector Type SMA Male (center pin) Mounting Type Adhesive Dimensions (mm) 116.5 × 21.7 × 5.6 Matched Quectel Modules 4G/3G/2G/LPWA 690–960, 1710–2690 LTE (4G) 1500 ±30 SMA Male (center pin) Magnetic 112 × 29.8 700–2700 LTE (4G) 3000 ±50 SMA Male (center pin) Magnetic 88 × Φ 30 Cellular (4G/3G/2G) Antennas Product YDX001AA YE0002AA YE0013AA YGL001AA Frequency Bands (MHz) 824–2690 Technology LTE (4G) Cable Length (mm) n/a Connector Type SMA Male (center pin) Mounting Type Terminal Dimensions (mm) 208 × Φ 12 Matched Quectel Modules 4G/3G/2G/LPWA 699–2700 LTE (4G) n/a RP-SMA Male (center receptacle) Terminal 174.6 × 19.2 700–2700 LTE (4G) n/a SMA Male (center pin) Terminal 115.4 × 17.5 × Φ 10.2 700–960,1710–2690 LTE (4G) n/a SMA Male (center pin) Terminal 196.2 × 16 × 13 The parameters shall be subject to the Specification. 7 Quectel Antennas Cellular (4G/3G/2G) Antennas Product YE0008AA YE0011AA YKL001CA Frequency Bands (MHz) 824–960, 1710–2170 , 2500–2700 Technology LTE (4G) Cable Length (mm) n/a Connector Type SMA Male (center pin) Mounting Type Terminal Dimensions (mm) 52 × Φ 10 Matched Quectel Modules LPWA/3G/2G module series 824–960, 1710–2170, 2500–2700 LTE (4G) n/a SMA Male (center pin) Terminal 50 × Φ 10 NB: 800–1000, 1700–1900 2G/3G/NB-IoT 310 ±10 SMA Male (center pin) Screw 50 × 48 GNSS Antennas Product YC0013AA YC0013AAEVB YC0008AA YC0008AAEVB Frequency Bands (MHz) 1559-1606 Technology GNSS Cable Length (mm) n/a Connector Type n/a Mounting Type SMD Dimensions (mm) 3.2 × 1.6 × 0.6 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS n/a n/a n/a 90 × 50 The parameters shall be subject to the Specification. 8 1173, 1575 GNSS L1 & L5 (passive) n/a n/a SMD 30 × 5 × 5 GNSS L1/L5 module series 1173, 1575 GNSS L1 & L5 (passive) n/a n/a n/a 80 × 36 Quectel Antennas GNSS Antennas Product YCGA001AA YCGA002AA YG0038AA Frequency Bands (MHz) 1559-1606 Technology GNSS L1 Cable Length (mm) n/a Connector Type n/a Mounting Type Pin Mounting Dimensions (mm) 10 × 10 × 4 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS L1 n/a n/a Pin Mounting 12 × 12 × 4 1559-1606 GNSS L1 n/a n/a Pin Mounting 13 × 13 × 4 GNSS Antennas Product YG0043AA YG0046AA YG0005AA YG0062AA YG0048AA Frequency Bands (MHz) 1559-1606 Technology GNSS L1 Cable Length (mm) n/a Connector Type n/a Mounting Type Pin Mounting Dimensions (mm) 15 × 15 × 4 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS L1 n/a n/a Pin Mounting 18 × 18 × 2 1559-1606 GNSS L1 n/a n/a Pin Mounting 18 × 18 × 4 1559-1606 GNSS L1 n/a n/a Pin Mounting 25 × 25 × 4 1176, 1575 GNSS L1 & L5 n/a n/a Pin mounting 18 × 18 × 4 & 25 × 25 × 4 GNSS L1/L5 module series The parameters shall be subject to the Specification. 9 Quectel Antennas GNSS Antennas Product YCGO004AA YCGO005AA YCGO006AA YCGO007AA YG0034AA YG0021AA Frequency Bands (MHz) 1559-1606 Technology GNSS L1 (passive) 1559-1606 GNSS L1 (passive) Cable Length (mm) 50±2 50±2 Connector Type IPEX Ⅰ IPEX Ⅰ Mounting Type Cable Mounting Cable Mounting Dimensions (mm) 10 × 10 × 6.5 15 × 15 × 6.5 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS L1 (passive) 50±2 IPEX Ⅰ Cable Mounting 18 × 18 × 6.5 1559-1606 GNSS L1 (passive) 50±2 IPEX Ⅰ Cable Mounting 25 × 25 × 6.5 1559–1606 GNSS L1 (active) 35±2 IPEX Ⅰ Cable Mounting 13 ×13 × 6.8 1560–1605 GNSS L1 & B1 & G1 (active) 42 ±3 IPEX Ⅰ Cable Mounting 18.4 × 18.4 × 8.86 GNSS Antennas Product YG0032AA YG0015AA YCGO008AA YCGO009AA YCGO010AA YCGO011AA Frequency Bands (MHz) Technology Beidou: 1561 ±5 ; GPS: 1575 ±5 GNSS L1 & B1 & G1 (active) Cable Length (mm) 55 1559–1606 GNSS L1 (active) 55 ±3 Connector Type IPEX Ⅰ IPEX Ⅰ Mounting Type Cable Mounting Cable Mounting Dimensions (mm) 18 × 18 × 6.6 25 × 25 × 8.25 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS L1 (active) 50±3 IPEX Ⅰ Cable Mounting 10 × 10 × 6.5 1559-1606 GNSS L1 (active) 50±2 IPEX Ⅰ Cable Mounting 15 × 15 × 6.5 1559-1606 GNSS L1 (active) 50±3 IPEX Ⅰ Cable Mounting 18 × 18 × 6.5 1559-1606 GNSS L1 (active) 50±3 IPEX Ⅰ Cable Mounting 25 × 25 × 6.5 The parameters shall be subject to the Specification. 10 Quectel Antennas GNSS Antennas Product YCGS004AA YCGS005AA YCGS006AA Frequency Bands (MHz) 1560–1606 Technology GNSS L1 & G1 Cable Length (mm) n/a Connector Type n/a Mounting Type SMD Dimensions (mm) 9 × 9 × 4 Matched Quectel Modules GNSS L1 module series GNSS Antennas Product YAT001AA 1560–1606 GNSS L1 & G1 n/a n/a SMD 18 × 18 × 4 YAT001BA 1560–1606 GNSS L1 & G1 n/a n/a SMD 25 × 25 × 4 YBS00A1AA Frequency Bands (MHz) 1176, 1575 Technology GNSS L1 & L5 (active) Cable Length (mm) n/a Connector Type n/a Mounting Type Cable Mounting Dimensions (mm) 25 × 25 × 4 & 18 × 18 × 4 Matched Quectel Modules GNSS L1/L5 module series 1176, 1575 GNSS L1 & L5 (active) n/a n/a Cable Mounting 25 × 25 × 2 & 18 × 18 × 2 1176, 1575 GNSS L1 & L5 (active) n/a n/a Cable Mounting 40 × 40 × 4 & 45 × 45 × 6 The parameters shall be subject to the Specification. 11 Quectel Antennas GNSS Antennas Product YAT001CA YG0030AA YCGO014AA Frequency Bands (MHz) 1176, 1575 Technology GNSS L1 & L5 (active) Cable Length (mm) 40 ±2 Connector Type IPEX Ⅰ Mounting Type Cable Mounting Dimensions (mm) 25 × 25 × 2 & 18 × 18 × 4 Matched Quectel Modules GNSS L1/L5 module series 1176, 1575 GNSS L1 & L5 (passive) 100 ±2 IPEX Ⅰ Cable Mounting 52 × 52 × 9.9 L5: 1166–1186 L1: 1559–1606 GNSS L1 & L5 (passive) 142 IPEX Ⅰ Cable Mounting 50 × 50 × 19.0 GNSS Antennas Product YFGA001AA YFGA002AA YFGA003AA YFGA004AA Frequency Bands 1160–1270, (MHz) 1560–1605 Technology GNSS L1 & 2 & L5 & L6 Cable Length (mm) 100 Connector Type IPEX Ⅰ Mounting Type Adhesive Dimensions (mm) 74.56 × 24.5 × 0.25 Matched Quectel Modules GNSS L1/L5 module series 1559–1609 GNSS L1 100 IPEX Ⅰ Adhesive 61.15 × 11.24 GNSS L1 module series The parameters shall be subject to the Specification. 12 1559–1609 GNSS L1 100 IPEX Ⅰ Adhesive 39.45 x 13.25 1160–1270, 1560–1605 GNSS L1 & 2 & L5 & L6 100 IPEX Ⅰ Adhesive 43 × 24 × 0.12 GNSS L1/L5 modules Quectel Antennas GNSS Antennas Product YG0035AA YLY001CA YB0017AA YG0028AA Frequency Bands (MHz) 1561, 1575 Technology GNSS L1 & B1 & G1 (active) Cable Length (mm) 3000 ±20 Connector Type SMA Male (center pin) Mounting Type Magnetic Dimensions (mm) 50.3 × 38.4 × 17.1 Matched Quectel Modules GNSS L1 module series 1568 ±10 GNSS L1 & B1 & G1 (active) 2000 SMA Male (center pin) Magnetic 45.5 × 38 × 13.5 GPS L1/L5, BD B1/B2, GLONASS L1 1561–1602, 1166–1186 GNSS L1 & L5 (active) GNSS L1 & L5 (active) L = 3000 SMA Male (center pin) Magnetic 3000 SMA Male (center pin) Magnetic 61.5 × 56.5 × 23 Φ 54 × 38 GNSS L1/L5 module series GNSS Antennas Product YG0065AA YEGT001AA YEGT002AA YG0063AA Frequency Bands (MHz) 1575–1602 Technology GNSS L1 (active) Cable Length (mm) 3000 Connector Type FAKRA Female (Code C) Mounting Type Magnetic Dimensions (mm) 34.5 × 37.5 × 12.5 Matched Quectel Modules GNSS L1 modules 1559-1606 GNSS L1 n/a SMA Male (center pin) Terminal 50 × Ø10 All GNSS L1 modules 1559–1606 GNSS L1 n/a SMA Male (center pin) Terminal 52 × Ø10 GPS L1/L2/L5; BDS B1/B2/B3; GLONASS L1/L2; Galileo E1/E5a/E5b/E6; L-band All GNSS bands + L-band Corrections n/a TNC Female Screw Φ 165 × 68 All GNSS L1/L2/L5 modules The parameters shall be subject to the Specification. 13 Quectel Antennas Wi-Fi & Bluetooth Antennas Product YC0009AA YC0010AA YEWM001AA Frequency Bands (MHz) 2400–2500 Technology Wi-Fi (Bluetooth) Cable Length (mm) n/a Connector Type n/a Mounting Type SMD Dimensions (mm) 3.2 × 1.6 × 0.5 Matched Quectel Modules FC30R 2400–2500 Wi-Fi (Bluetooth) n/a n/a SMD 5.2 × 2.0 × 1.2 2400–2500 Wi-Fi (Bluetooth) 1500 SMA Male (center pin) Magnetic Φ 30 ×77.4 Wi-Fi & Bluetooth Antennas Product YF0011AA YF0026AA YF0027AA YF0029AA YF0023AA YF0023CA Frequency Bands 2400–2500, (MHz) 5150–5850 2400–2500, 4900–5850, 5925-7125 2400–2500, 4900–5850, 5925-7125 2410–2490 , 4920–5925 2400–2500, 5150–5850, 5925-7125 2400–2500, 5150–5850, 5925-7125 Technology Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Cable Length (mm) 44 ±13 100 ±2 100 ±2 100 ±2 100±2 Connector Type IPEX Ⅰ (U.FL Generation Ⅰ) IPEX Ⅰ (U.FL Generation Ⅰ) IPEX Ⅰ (U.FL Generation Ⅰ) IPEX Ⅰ (U.FL Generation Ⅰ) RF I Generation Mounting Type Adhesive Adhesive Adhesive Adhesive Adhesive 100±2 RF I Generation Adhesive Dimensions (mm) Matched Quectel Modules 38.9 × 9 × 0.12 All Wi-Fi/BT modules (Except Wi-Fi 6E) 28.9 × 11 × 0.2 All Wi-Fi/BT modules 42 × 7 × 0.2 30 × 30 × 0.25 All Wi-Fi/BT modules (Except Wi-Fi 6E) 22.90 × 11.70 All Wi-Fi/BT modules 37.80 × 7.50 The parameters shall be subject to the Specification. 14 Quectel Antennas Wi-Fi & Bluetooth Antennas Product YE0031AA YE0032AA YE0038AA YEWT004AA YEWN001AA Frequency Bands 2.4–2.5 GHz, (MHz) 5.15–5.85 GHz Technology Wi-Fi (Bluetooth) 2.4–2.5 GHz, 5.15–5.85 GHz Wi-Fi (Bluetooth) Cable Length (mm) n/a n/a Connector Type SMA Male (center pin) SMA Male (center pin) Mounting Type Terminal Terminal Dimensions (mm) 52 ±2 50 ±2 Matched Quectel Modules All Wi-Fi/BT modules (Except Wi-Fi 6E) 2400–2500, 5150–5850 Wi-Fi (Bluetooth) n/a SMA Male (center pin) Terminal 195 × 13 2400–2500, 5150–7150 Wi-Fi 6E (Bluetooth) n/a SMA Male (center pin) Terminal 109 × Φ 10 All Wi-Fi/BT modules 2400–2500, 5150–5850 Wi-Fi (Bluetooth) n/a RP-SMA Male (Center Receptacle) Terminal 200 × 13 All Wi-Fi/BT modules (Except Wi-Fi 6E) Combo Antennas Product YB0007AA YB0008AA YB0009AA YB0014AA Frequency Bands (MHz) Technology 700–960, 1710–2690 , 3300–5000 5G Cable Length (mm) 500 Connector Type SMA Male (center pin) Mounting Type Screw Dimensions (mm) Matched Quectel Modules Φ 120 × 43 All 5G modules (RM50xQ Series, RG50xQ Series) & All 4G/3G/2G modules & GNSS L1 modules 4G MAIN: 698–960, 1710–2690; GNSS: 1575.42 ±5, 1561.098 ±5; 4G DIV: 1710–2690 Main LTE & DIV LTE & GNSS 300 SMA Male (center pin) Adhesive Φ 84 × 17.5 4G: 824–960, 1710–2690; GPS, BD: 1575.42 ±10, 1561 ±10 LTE & GNSS 310 SMA Male (center pin) Screw 33 × 48 All 4G/3G/2G modules & GNSS L1 modules LTE Main & Div: 698–960, 1700–2700; GNSS: 1561–1571; 1602–1606 Main LTE & DIV LTE & GNSS 3000 SMA Male (center pin) Screw 81 × 27.5 The parameters shall be subject to the Specification. 15 Quectel Antennas Combo Antennas Product YB0015AA YKL001AA YB0032AA YB0033AA YB0022AA Frequency Bands (MHz) Technology LTE: 698–960, 1700–2700; Wi-Fi, Bluetooth: 2400– 2500; GNSS: 1561 ±5, 1575 ±5 LTE/GPS & BD/Wi-Fi Bluetooth: 2400–2500; 4G: 824–960; 1710–2690; GPS, BD: 1575.42 ±10, 1561 ±10 700–960, 1700–2700 LTE/GPS & BD/Wi-Fi Main LTE & DIV LTE Cable Length (mm) 300 310 2000 Connector Type SMA Male (center pin) SMA Male (center pin) SMA Male (Center Pin) Mounting Type Screw Screw Screw Dimensions (mm) 54 × 91 33 × 48 Φ 120 × 43 Matched Quectel Modules 4G/3G/2G modules & GNSS L1 modules & Wi-Fi modules All 4G/3G/2G modules LTE Main & Div: 700–960, 1700–2700 ; GNSS: 1559– 1610 (active) Main LTE & DIV LTE & GNSS 2000 LTE Main & Div: 700–2700; Wi-Fi: 2400–5850 ; GNSS: 1561/1575.42/1602 Main LTE & DIV LTE & GNSS & Wi-Fi1 & Wi-Fi2 1000 SMA Male (Center Pin) FME Female Connector Screw Screw Φ 120 × 43 All 4G/3G/2G modules & GNSS L1 modules Φ 120 × 43 4G/3G/2G modules & GNSS L1 modules & Wi-Fi, Bluetooth modules Combo Antennas Product YB0031AA YEMA003AA YEMA004AA YWL00A0AA YB0026AA YEWN004AA Frequency Bands (MHz) LTE: 698–960; 1710–2690; GNSS: 1575.42 ±5, 1561.098 ±5 LTE: 700–2700 1561/1575.42/1602 Technology LTE & GNSS LTE & GNSS Cable Length (mm) 300 3000 Connector Type SMA Male (center pin) 4G: FAKRA D GNSS: FAKRA C Mounting Type Dimensions (mm) Adhesive Φ 84 ×17.5 Adhesive Φ 84 × 17.5 Matched Quectel Modules All 4G/3G/2G modules & GNSS L1 modules 4G: 698–960 , 1710–2690 Wi-Fi & Bluetooth: 2400–2500 698–960, 1710–2690 LTE: 700–2700 ; Wi-Fi: 2400–5850; GNSS: 1561/1575.42/1602 2400–2500, 5150–5850 LTE & Wi-Fi Main LTE & DIV LTE LTE & GNSS & Wi-Fi1 & Wi-Fi2 Wi-Fi MIMO 900 1500 1000 300 GNSS: FAKRA_C, LTE: SMA Male (Center Pin) SMA Male (Center Pin) FAKRA_D, Wi-Fi 1: FAKRA_ SMA Male (Center Pin) I, Wi-Fi 2: FAKRA_I Screw Screw Screw Screw Φ 81 ×14.5 Φ 81 × 27.5 Φ 120 ×43 Φ 46 ×15 All 4G/3G/2G modules & Wi-Fi modules All 4G/3G/2G modules All 4G/3G/2G modules & GNSS L1 modules & Wi-Fi, Bluetooth modules Wi-Fi modules The parameters shall be subject to the Specification. 16 Quectel Antennas ISM Antennas Product YE0019AA YE0039BA YEIM001AA Frequency Bands (MHz) Technology Cable Length (mm) Connector Type Mounting Type Dimensions (mm) 450–470 ISM SMA Male (center pin) Terminal 109 × 10 430-470, 790-960 ISM 75 SMA Male (center pin) Adhesive 117 × 21.81 × 5.47 Cable Assemblies Product YM0003AA YM0015AA YM0003CA 465–475 ISM 2000 SMA Male (center pin) Magnetic Φ 30 × 131 YM0003AB YM0013AA Frequency Bands (MHz) Technology Cable Length (mm) Connector Type Mounting Type Dimensions (mm) Matched Quectel Modules 0–6000 0–6000 Cable Cable 100 150 SMA-female to IPEX Ⅰ SMA-female to IPEX Ⅰ Screw Screw 100 150 All modules (5G excluded) 0–6000 Cable 200 SMA-female to IPEX Ⅰ Screw 200 0–6000 Cable 200 RP-SMA-female to IPEX Ⅰ Screw 200 0–6000 Cable 300 SMA-female to IPEX Ⅰ Screw 300 Product YM0004AA YM0005AA YSAN001AA YBY00A0HA YBY00A0JA YBY00A0IA Frequency Bands (MHz) Technology Cable Length (mm) Connector Type Mounting Type Dimensions (mm) Matched Quectel Modules 0–6000 0–6000 0–6000 Cable Cable Cable 100 150 300 SMA-female to IPEX Ⅳ SMA-female to RF Ⅳ SMA-female to RF Ⅳ Screw Screw Screw 100 150 300 All 5G modules (RM50xQ Series, RG50xQ Series) 0–6000 Cable 200 0–6000 Cable 250 N-K-female to IPEX Ⅰ N-female to IPEX Ⅰ Screw Screw 200 250 All modules (5G excluded) Bracket - - All modules The parameters shall be subject to the Specification. 17 V1.7.4 2022.04
6.53 MB
Application Note
EC2x&EG2x&EG9x&EM05 Series MQTT Application Note LTE Standard Module Series Version: 1.3 Date: 2023-11-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 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. EC2x&EG2x&EG9x&EM05_Series_MQTT_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. EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 2 / 37 LTE Standard Module Series About the Document Revision History Version 1.0 1.1 1.2 1.3 Date Author Description 2018-08-21 2018-12-12 2020-04-22 2023-11-16 Chavis CHEN Creation of the document Slark WANG Chavis CHEN/ Domingo DENG/ Larson LI Mario CHEN/ Chavis CHEN/ Domingo DENG/ Larson LI Added Write Command AT+QMTCFG='qmtping' and its related information. 1. Added applicable modules in Chapter 1. 2. Updated MQTT data interaction diagram in Chapter 2. 3. Updated description of Test Command AT+QMTCFG=? and added Write Command AT+QMTCFG='willex' in Chapter 3.2.1. 4. Added configuration in the parameter table in Chapter 3.2.4, 3.2.6, 3.2.7 and 3.2.8. 5. Updated error codes of the URC in Table 4. 1. Added the applicable modules: EG21-GL and EG25-GL and updated EC20 R2.1 to EC20-CE. (Chapter 1). 2. Updated the response to AT+QMTCFG=? And the parameter name of AT+QMTCFG='aliauth',[,,,] (Chapter 3.2.1). 3. Added the following sub-commands in AT+QMTCFG (Chapter 3.2.1): ⚫ AT+QMTCFG='send/mode',[,] ⚫ AT+QMTCFG='hwauth',[,,] ⚫ AT+QMTCFG='hwprodid',[,,,] EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 3 / 37 LTE Standard Module Series ⚫ AT+QMTCFG='protocol/check',[, ] 4. Added the characteristics of the following commands (Chapter 3.2): ⚫ AT+QMTOPEN ⚫ AT+QMTCLOSE ⚫ AT+QMTCONN ⚫ AT+QMTDISC ⚫ AT+QMTSUB ⚫ AT+QMTUNS ⚫ AT+QMTPUBEX ⚫ AT+QMTRECV 5. Updated the values of in AT+QMTDISC and added a note (Chapter 3.2.5). 6. Added AT+QMTPUB (Chapter 3.2.9). 7. Added the maximum response time of AT+QMTRECV (Chapter 3.2.10). 8. Updated the examples of AT+QMTDISC (Chapter 5). EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 4 / 37 LTE Standard Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 5 Table Index.................................................................................................................................................. 6 1 Introduction ......................................................................................................................................... 7 1.1. Applicable Modules .................................................................................................................... 7 2 MQTT Data Interaction........................................................................................................................ 8 3 MQTT-Related AT Commands ........................................................................................................... 9 3.1. AT Command Syntax ................................................................................................................. 9 3.1.1. Definitions........................................................................................................................ 9 3.1.2. AT Command Syntax ...................................................................................................... 9 3.2. Declaration of AT Command Examples ................................................................................... 10 3.3. Description of MQTT-Related AT Commands.......................................................................... 10 3.3.1. AT+QMTCFG Configure Optional Parameters of MQTT ........................................... 10 3.3.2. AT+QMTOPEN Open a Network for MQTT Client ..................................................... 17 3.3.3. AT+QMTCLOSE Close a Network for MQTT Client .................................................. 18 3.3.4. AT+QMTCONN Connect a Client to MQTT Server.................................................... 19 3.3.5. AT+QMTDISC Disconnect a Client from MQTT Server ............................................. 20 3.3.6. AT+QMTSUB Subscribe to Topics ............................................................................. 21 3.3.7. AT+QMTUNS Unsubscribe from Topics ..................................................................... 23 3.3.8. AT+QMTPUBEX Publish Messages (Data Mode) ..................................................... 24 3.3.9. AT+QMTPUB Publish Messages (Command Mode) ................................................. 25 3.3.10. AT+QMTRECV Read Messages from Buffer ............................................................. 27 4 MQTT-Related URCs......................................................................................................................... 29 4.1. +QMTSTAT Indicate State Change in MQTT Link Layer ...................................................... 29 4.2. +QMTRECV Notify Host to Read MQTT Packet Data.......................................................... 30 4.3. +QMTPING Indicate PING State of Keep-alive in MQTT ..................................................... 31 5 Examples ........................................................................................................................................... 32 5.1. Example of MQTT Operation without SSL .............................................................................. 32 5.2. Example of MQTT Operation with SSL.................................................................................... 34 6 Appendix References ....................................................................................................................... 37 EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 5 / 37 LTE Standard Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 7 Table 2: Type of AT Commands and Responses ......................................................................................... 9 Table 3: MQTT-Related URCs ................................................................................................................... 29 Table 4: URC Error Codes ......................................................................................................................... 30 Table 5: Related Documents ...................................................................................................................... 37 Table 6: Terms and Abbreviations .............................................................................................................. 37 EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 6 / 37 LTE Standard Module Series 1 Introduction MQTT is a broker-based publish/subscribe messaging protocol designed to be open, simple, lightweight and easy to implement. It is designed for connections with remote locations where a 'small code footprint' is required or the network bandwidth is limited. This document explains how to use the MQTT function of Quectel EC2x family, EG2x family, EG9x family and EM05 series modules through AT commands. 1.1. 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_MQTT_Application_Note 7 / 37 LTE Standard Module Series 2 MQTT Data Interaction This chapter illustrates the data interaction mechanism of MQTT function. MCU Modem Link layer MQTT Server AT+QMTCFG='will',, AT+QMTCFG='timeout',, AT+QMTOPEN=,'', OK TCP-REQ +QMTOPEN: , AT+QMTCONN AT+QMTCONN=,'', OK +QMTCONN: ,[,] TCP established CONN-REQ Start timer T1, T2 CONN ACK-IND Stop T1 or handle Excep1 TCP SYN TCP SYN+ACK TCP ACK Send connect packet Receive connect ACK packet AT+QMTSUB AT+QMTSUB=,,... OK +QMTSUB:,,[,] SUB-REQ () Start timer T1 SUB ACK-IND () Stop T1 or handle Excep2 Send subscribe packet Receive subscribe ACK packet AT+QMTUNS AT+QMTUNS=,,... OK UNS-REQ () Start timer T1 +QMTUNS: ,,[,] AT+QMTPUBEX=,,=0,,'', OK UNS ACK-IND () Stop T1 or handle Excep2 PUB-REQ AT+QMTPUBEX (=1) OK AT+QMTPUBEX=,,=1,,'', PUB-REQ () Start timer T1 PUB ACK-IND () +QMTPUBEX: ,,[,] Stop T1 or handle Excep2 Send unsubscribe packet Receive unsubscribe ACK packet Send publish packet Send publish packet Receive publish ACK packet AT+QMTPUBEX (=2) OK AT+QMTPUBEX=,,=2,,'', PUB-REQ () Start timer T1 PUB REC-IND () Stop T1 or handle Excep2 PUB REL-REQ () Start timer T1 PUB COMP-IND () +QMTPUBEX: ,,[,] Stop T1 or handle Excep2 Send publish packet Receive publish receive packet Send publish release packet Receive publish complete packet T1 is packet transmission timeout. T2 is keep-alive timer. In the absence of a data-related message during the T2 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 URC. PUB-IND () +QMTRECV: ,,'','' PUB ACK/REC-REQ () Reply accor.d..ing 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, please refer to the description of corresponding AT command in Chapter 3.2.1. Figure 1: MQTT Data Interaction Diagram EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 8 / 37 LTE Standard Module Series 3 MQTT-Related AT Commands This chapter presents the AT commands for using the MQTT function. 3.1. AT Command Syntax 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 omitted, the new value equals its previous value or its default setting, unless otherwise specified. ⚫ Underline Default setting of a parameter. 3.1.2. AT Command Syntax The AT or at prefix must be added at the beginning of each command line. Entering will terminate a command line. Commands are usually followed by a response that includes . Throughout this document, only the response will be presented, are omitted intentionally. Table 2: Type of AT Commands and Responses 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_MQTT_Application_Note 9 / 37 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 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 supported s),(list of supported s) +QMTCFG: 'send/mode',(range of supported EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 10 / 37 LTE Standard Module Series s),(list of supported s) +QMTCFG: 'aliauth',(range of supported s),'pr oduct key','device name','device secret' +QMTCFG: 'hwauth',(range of supported s),'d evice id','device secret' +QMTCFG: 'hwprodid',(range of supported s),'product id','product secret','nodeid' +QMTCFG: 'qmtping',(range of supported s),(range of supported s) +QMTCFG: 'protocol/check',(range of supported s),(list of supported s) OK Write Command Response Query/set the MQTT protocol version If is omitted, query the MQTT protocol version: AT+QMTCFG='version',<client_id +QMTCFG: 'version', x>[,] OK Write Command Query/set the PDP to be used by the MQTT client AT+QMTCFG='pdpcid',[,] If is specified and the MQTT connection is not established, set the MQTT protocol version: OK Or ERROR Response If is omitted, query the PDP to be used by the MQTT client: +QMTCFG: 'pdpcid', OK Write Command Query/set Will information AT+QMTCFG='will',[, [,, ,,]] If is specified and the MQTT connection is not established, set the PDP to be used by the MQTT client: OK Or ERROR Response: If , , , and are omitted, query the Will information: +QMTCFG: 'will',[,,,,] OK EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 11 / 37 LTE Standard Module Series Write Command Query/set Will information AT+QMTCFG='willex',[,[,,,,]] If , , , and are specified and the MQTT connection is not established, set the Will information: OK Or ERROR Response If , , , , are omitted, query the current configuration: +QMTCFG: 'willex',,[,,,] OK Write Command Query/set message delivery timeout AT+QMTCFG='timeout',[,,,< timeout_notice>] If , , , , are specified, set the Will information: > Input the Will message. When the actual size of data is greater than , the first byte(s) data will be sent out. OK Or ERROR Response If , and are omitted, query message delivery timeout: +QMTCFG: 'timeout',,, OK Write Command Query/set session type AT+QMTCFG='session',[,] If , and are specified and the MQTT connection is not established, set message delivery timeout: OK Or ERROR Response If is omitted, query session type: +QMTCFG: 'session', OK If is specified and the MQTT connection is not established, set the session type: EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 12 / 37 LTE Standard Module Series Write Command Query/set keep-alive time AT+QMTCFG='keepalive',[,] OK Or ERROR Response If is omitted, query the keep-alive time: +QMTCFG: 'keepalive', OK Write Command Query/set the MQTT SSL mode and SSL context index AT+QMTCFG='ssl',[,< SSL_enable>,] If is specified and the MQTT connection is not established, set the keep-alive time: OK Or ERROR Response If and are omitted, query the MQTT SSL mode and SSL context index: +QMTCFG: 'ssl',[,] OK Write Command Query/set receiving mode when data is received from server AT+QMTCFG='recv/mode',[,[,]] If and are specified and the MQTT connection is not established, set the MQTT SSL mode and SSL context index: OK Or ERROR Response If and are omitted, query the MQTT message receiving mode: +QMTCFG: 'recv/mode',, OK Write Command Query/set client data sending mode AT+QMTCFG='send/mode',<clien If and are specified and the MQTT connection is not established, set the receiving mode when data is received from server: OK Or ERROR Response If is omitted, query the MQTT data sending mode: EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 13 / 37 LTE Standard Module Series t_idx>[,] +QMTCFG: 'send/mode', OK Write Command Query/set Alibaba device information for Alibaba Cloud AT+QMTCFG='aliauth',[,,,] If is specified and the MQTT connection is not established, set the client data sending mode: OK Or ERROR Response If , and are omitted, query the device information: +QMTCFG: 'aliauth',,, OK Write Command Query/set device information for HUAWEI Cloud AT+QMTCFG='hwauth',[,,] If , and are specified and the MQTT connection is not established, set Alibaba device information for Alibaba Could: OK Or ERROR Response If and are omitted, query the device information: +QMTCFG: 'hwauth',, OK Write Command Query/set product information for HUAWEI Cloud AT+QMTCFG='hwprodid',[,,,] If and are specified and the MQTT connection is not established, set device information for HUAWEI Could: OK Or ERROR Response If , and are omitted, query the product information: +QMTCFG: 'hwprodid',,, OK EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 14 / 37 LTE Standard Module Series If , and are specified and the MQTT connection is not established, set product information for HUAWEI Could: OK Or ERROR Write Command Response Query/set the maximum retention If is omitted, query the current time of MQTT connection before configuration: disconnection due to heartbeat +QMTCFG: 'qmtping', timeout AT+QMTCFG='qmtping',[,] If is specified, and the MQTT connection is not established, set the maximum retention time of MQTT connection before disconnection due to heartbeat timeout: OK Or ERROR Write Command Response Query/set MQTT protocol check If is omitted, query the current AT+QMTCFG='protocol/check',[,<protocol_check_enab +QMTCFG: 'protocol/check',,] _enable> OK Maximum Response Time Characteristics If is specified, and the MQTT connection is not established, set MQTT protocol check: OK Or ERROR 300 ms These commands take effect immediately. The configurations are not saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. MQTT protocol version. 3 MQTT protocol V3.1 4 MQTT protocol V3.1.1 Integer type. PDP to be used by the MQTT client. Range: 1–16. Default: 1. EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 15 / 37 LTE Standard Module Series Integer type. Configure the Will flag. 0 Ignore the Will flag configuration 1 Require the Will flag configuration Integer type. Quality of service for message delivery. 0 At most once 1 At least once 2 Exactly once Integer type. Will retain flag is only used on PUBLISH messages. 0 When a client sends a PUBLISH message to a server, the server will not hold on to the message after it has been delivered to the current subscribers. 1 When a client sends a PUBLISH message to a server, the server should hold on to the message after it has been delivered to the current subscribers. String type. Will topic string. Maximum size: 256 bytes. String type. Will message defines the content of the message published to the Will topic when the client is unexpectedly disconnected. Maximum size: 256 bytes. Integer type. Will message length. Range: 0–256. Integer type. Package delivery timeout. Range: 1–60. Default: 5. Unit: s. Integer type. Retry times when packet delivery times out. Range: 0–10. Default: 3. Integer type. Whether to report timeout message when transmitting a packet. 0 Do not report 1 Report Integer type. Configure session type. 0 The server must store the client subscriptions after it disconnects. 1 The server must discard any previously maintained information about the client and treat the connection as 'clean'. Integer type. Keep-alive time. Range: 0–3600. Default: 120. Unit: s. It defines the maximum time interval between messages received from a client. If the server does not receive a message from the client within 1.5 times of the keep-alive time period, it disconnects the client as if the client has sent a DISCONNECT message. 0 The client will not be disconnected Integer type. Configure the MQTT SSL mode. 0 Use normal TCP connection for MQTT 1 Use SSL TCP secure connection for MQTT Integer type. SSL context index. Range: 0–5. Integer type. Configure the MQTT message receiving mode. 0 MQTT message received from server will be contained in URC. 1 MQTT message received from server will not be contained in URC. Integer type. Whether length of MQTT message received from server will be contained in URC. 0 Not contained 1 Contained EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 16 / 37 LTE Standard Module Series Integer type. Configure the MQTT message sending mode. 0 MQTT message sent to server will be contained in URC. 1 MQTT message sent to server will not be contained in URC. String type. Product key issued by Alibaba Cloud. String type. Device name issued by Alibaba Cloud. String type. Device secret key issued by Alibaba Cloud. String type. Device name issued by HUAWEI Cloud. String type. Device secret key issued by HUAWEI Cloud. String type. Product name issued by HUAWEI Cloud. String type. Product secret key issued by HUAWEI Cloud. String type. Device identification code of the product issued by HUAWEI Cloud. Integer type. Maximum retention time of MQTT connection before disconnection due to heartbeat timeout. Range: 5–60. Default: 5. Unit: s. Integer type. Whether to enable MQTT protocol checking. 0 Disable 1 Enable NOTE 1. If =1, then , , and must be specified. Otherwise they will be omitted. 2. =0 is only effective when the server supports the operation. 3. If MQTT connection is configured to SSL mode, must be specified. In addition, customers need to use AT+QSSLCFG to configure the SSL version, cipher suite, secure level, CA certificate, client certificate, client key and ignorance of RTC time, which will be used in MQTT SSL handshake procedure. 4. Please ensure that message delivery does not time out while it is still being sent. 5. AT+QMTCFG='aliauth' is only used for Alibaba Cloud. If it is configured, and in AT+QMTCONN can be omitted. 3.3.2. AT+QMTOPEN Open a Network for MQTT Client This command opens a network for MQTT client. AT+QMTOPEN Open a Network for MQTT Client Test Command AT+QMTOPEN=? Response +QMTOPEN: (range of supported s),'host_n ame',(range of supported s) Read Command AT+QMTOPEN? OK Response [+QMTOPEN: ,,] EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 17 / 37 LTE Standard Module Series Write Command AT+QMTOPEN=,, Maximum Response Time Characteristics OK Or ERROR Response OK +QMTOPEN: , Or ERROR 120 s, determined by network This command takes effect immediately. The configurations are not saved. Parameter Integer type. MQTT client identifier. Range: 0–5. String type. Server address. It could be an IP address or a domain name. Maximum size: 100 bytes. Integer type. Server port. Range: 1–65535. Integer type. Command execution result. -1 Failed to open network 0 Network opened successfully 1 Wrong parameter 2 MQTT identifier is occupied 3 Failed to activate PDP 4 Failed to parse domain name 5 Network connection error 3.3.3. AT+QMTCLOSE Close a Network for MQTT Client This command closes a network for an MQTT client. AT+QMTCLOSE Close a Network for MQTT Client Test Command AT+QMTCLOSE=? Response +QMTCLOSE: (range of supported s) Write Command AT+QMTCLOSE= OK Response OK +QMTCLOSE: , Or EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 18 / 37 LTE Standard Module Series Maximum Response Time Characteristics ERROR 30 s This command takes effect immediately. The configurations are not saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Command execution result. -1 Failed to close network 0 Network closed successfully 3.3.4. AT+QMTCONN Connect a Client to MQTT Server This command connects a client to MQTT server. When a TCP/IP socket connection is established between a client and a server, a protocol level session must be created using a CONNECT flow. AT+QMTCONN Connect a Client to MQTT Server Test Command AT+QMTCONN=? Response +QMTCONN: (range of supported s),'clienti d','username','password' Read Command AT+QMTCONN? OK Response [+QMTCONN: ,] Write Command AT+QMTCONN=,[,,] OK Or ERROR Response OK +QMTCONN: ,[,] Or ERROR Maximum Response Time (default 5 s), determined by network Characteristics This command takes effect immediately. The configurations are not saved. EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 19 / 37 LTE Standard Module Series Parameter Integer type. MQTT client identifier. Range: 0–5. String type. Client identifier string. String type. User name of the client. It can be used for authentication. String type. Password corresponding to the user name of the client. It can be used for authentication. Integer type. Command execution result. 0 Packet sent successfully and ACK received from server 1 Packet retransmission 2 Failed to send packet Integer type. MQTT connection state. 1 MQTT is initializing 2 MQTT is connecting 3 MQTT is connected 4 MQTT is disconnecting Integer type. Connection status return code. 0 Connection Accepted 1 Connection Refused: Unacceptable Protocol Version 2 Connection Refused: Identifier Rejected 3 Connection Refused: Server Unavailable 4 Connection Refused: Bad User Name or Password 5 Connection Refused: Not Authorized Integer type. Package delivery timeout. Range: 1–60. Default: 5. Unit: s. Th e value can be configured by AT+QMTCFG='timeout',[,,,]. NOTE If a client with the same Client ID is already connected to the server, the 'older' client must be disconnected by the server before completing the CONNECT flow of the new client. 3.3.5. AT+QMTDISC Disconnect a Client from MQTT Server This command disconnects a client from MQTT server. A DISCONNECT message is sent from the client to the server to indicate that it is about to close its TCP/IP connection. EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 20 / 37 LTE Standard Module Series AT+QMTDISC Disconnect a Client from MQTT Server Test Command AT+QMTDISC=? Response +QMTDISC: (range of supported s) Write Command AT+QMTDISC= OK Response OK Maximum Response Time Characteristics +QMTDISC: , Or ERROR 30 s This command takes effect immediately. The configurations are not saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Command execution result. 0 Send the request for disconnection successfully 2 Failed to send the request for disconnection NOTE When is 0, it indicates that a DISCONNECT message has been successfully sent to the network, and the MQTT connection is ready to be closed. There are two scenarios: 1. If the server actively disconnects the MQTT connection and the connection is successfully disconnected, report URC +QMTSTAT: ,, and is 5. 2. If the server fails to respond to the disconnection request, execute AT+QMCLOSE to disconnect the MQTT connection. 3.3.6. AT+QMTSUB Subscribe to Topics This command subscribes a client to one or more topics of interest. The client sends a SUBSCRIBE message to the server to register an interest in one or more topics. The server delivers messages published on these topics to the client as PUBLISH messages. EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 21 / 37 LTE Standard Module Series AT+QMTSUB Subscribe to Topics Test Command AT+QMTSUB=? Response +QMTSUB: (range of supported s),,list of ['topic',qos] Write Command AT+QMTSUB=, ,,[,, …] Maximum Response Time Characteristics OK Response OK +QMTSUB: ,,[,] Or ERROR × (default 15 s), determined by network This command takes effect immediately. The configurations are not saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of packet. Range: 1–65535. String type. Topic that the client wants to subscribe to or unsubscribe from. Integer type. The QoS level at which the client wants to publish the messages. 0 At most once 1 At least once 2 Exactly once Integer type. Command execution result. 0 Sent packet successfully and received ACK from server 1 Packet retransmission 2 Failed to send packet Integer type. If is 0, it is a vector of granted QoS levels. If is 1, it is the packet retransmission count. If is 2, it will not be presented. Integer type. Package delivery timeout. Range: 1–60. Default: 5. Unit: second. The value can be configured by AT+QMTCFG='timeout',[,,,]. Integer type. Retry times when packet delivery times out. Range: 0–10. Default: 3. EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 22 / 37 LTE Standard Module Series NOTE The is only present in messages where the QoS bits in the fixed header indicate QoS level 1 or 2. It must be unique amongst the set of 'inflight' messages in a particular direction of communication. It typically increases by 1 from one message to the next, but it is not compulsory in actual practice. 3.3.7. AT+QMTUNS Unsubscribe from Topics This command unsubscribes a client from one or more topics. The client sends an UNSUBSCRIBE message to the server to unsubscribe from the named topics. AT+QMTUNS Unsubscribe from Topics Test Command AT+QMTUNS=? Response +QMTUNS: (range of supported s),,list of ['topic'] Write Command AT+QMTUNS=, ,[,…] Maximum Response Time Characteristics OK Response OK +QMTUNS: ,,[,] Or ERROR × (default 15 s), determined by network This command takes effect immediately. The configurations are not saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of packet. Range: 1–65535. String type. Topic that the client wants to subscribe to or unsubscribe from. Integer type. Command execution result. 0 Sent packet successfully and received ACK from server 1 Packet retransmission 2 Failed to send packet Integer type. If is 0, it is a vector of granted QoS levels. If is 1, it is the packet retransmission count. If is 2, it will not be presented. Integer type. Package delivery timeout. Range: 1–60. Default: 5. Unit: second. The EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 23 / 37 LTE Standard Module Series value can be configured by AT+QMTCFG='timeout',[,,,]. Integer type. Retry times when packet delivery times out. Range: 0–10. Default: 3. 3.3.8. AT+QMTPUBEX Publish Messages (Data Mode) This command publishes fixed length messages by a client to a server for distribution to interested subscribers. Each PUBLISH message is associated with a topic name. If a client subscribes to one or more topics, any message published to those topics will be sent by the server to the client as a PUBLISH message. AT+QMTPUBEX Publish Messages (Data Mode) Test Command AT+QMTPUBEX=? Response +QMTPUBEX: (range of supported s), ,(range of supported s),(list of supported s),'topic','length' Write Command AT+QMTPUBEX=,,,,, OK Response > Input the data to be sent. When the actual size of data exceeds , the first byte(s) data will be sent out. OK Maximum Response Time Characteristics +QMTPUBEX: ,,[,] Or ERROR × (default 15 s), determined by network This command takes effect immediately. The configurations are not saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of packet. Range: 0–65535. It will be 0 only when =0. Integer type. QoS level at which the client wants to publish messages. 0 At most once 1 At least once 2 Exactly once EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 24 / 37 LTE Standard Module Series Integer type. Whether or not the server will retain the message after it has been delivered to the current subscribers. 0 Do not retain 1 Retain String type. Topic that needs to be published. Integer type. Length of message to be published. Integer type. Command execution result. 0 Packet sent successfully and ACK received from server (message published when =0 does not require ACK) 1 Packet retransmission 2 Failed to send packet Integer type. If is 1, it is the packet retransmission count. If is 0 or 2, it will not be presented. Integer type. Package delivery timeout. Range: 1–60. Default: 5. Unit: second. The value can be configured by AT+QMTCFG='timeout',[,,,]. Integer type. Retry times when packet delivery times out. Range: 0–10. Default: 3. NOTE 1. If this command is executed successfully and OK is returned, the client can continue to publish new packet. The maximum quantity of transmitted packets should not exceed inflight window size: 5. Otherwise, ERROR will be returned. 2. After executing this command, the client will be ready to send data as payload. The maximum length of input data is 1500 bytes at a time. 3. PUBLISH messages can be sent either from a publisher to the server, or from the server to a subscriber. When a server publishes messages to a subscriber, the following URC will be returned to notify the host to read the received data that is reported from MQTT server: +QMTRECV: ,,[,],. For more details about the URC description, please refer to Chapter 4.2. 3.3.9. AT+QMTPUB Publish Messages (Command Mode) This command publishes specified messages or messages with any length by a client to a server for distribution to interested subscribers. Each PUBLISH message is associated with a topic name. If a client subscribes to one or more topics, any message published on those topics is sent by the server to the client as a PUBLISH message. EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 25 / 37 LTE Standard Module Series AT+QMTPUB Publish Messages (Command Mode) Test Command AT+QMTPUB=? Response +QMTPUB: (range of supported s), ,(range of supported s),(list of supported s),'topic' Write Command AT+QMTPUB=,, ,,[,] OK Response If is omitted: > Input the data to be sent. OK +QMTPUB: ,,[,] Or ERROR If is specified: OK Maximum Response Time Characteristics +QMTPUB: ,,[,] Or ERROR × (default 15 s), determined by network This command takes effect immediately. The configurations are not saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of a packet. Range: 0–65535. It will be 0 only when =0. Integer type. QoS level at which the client wants to publish messages. 0 At most once 1 At least once 2 Exactly once Integer type. Whether or not the server will retain the message after it has been delivered to the current subscribers. 0 Do not retain 1 Retain String type. Topic that needs to be published. Integer type. Message that needs to be published. Maximum length: 1500 bytes. EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 26 / 37 LTE Standard Module Series Integer type. Command execution result. 0 Packet sent successfully and ACK received from server (message published when =0 does not require ACK) 1 Packet retransmission 2 Failed to send a packet Integer type. If is 1, it is the packet retransmission count. If is 0 or 2, it will not be presented. Integer type. Packet delivery timeout, which can be configured by AT+QMTCFG='timeout',[,,,]. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times after packet delivery failure. Range: 0–10. Default value: 3. NOTE 1. If this command (without ) is executed successfully and OK is returned, the client can continue to publish a new packet. The maximum quantity of transmitting packets should not exceed the inflight window size: 5. Otherwise, ERROR will be returned. 2. After executing this command, the client will be ready to send data, which will be sent as payload. The maximum length of the input data is 1500 bytes at a time. 3. PUBLISH messages can be sent either from a publisher to the server, or from the server to a subscriber. When a server publishes messages to a subscriber, the following URC will be returned to notify the host to read the received data that is reported from MQTT server: +QMTRECV: ,,[,],. For more details about the URC description, please refer to Chapter 4.2. 3.3.10. AT+QMTRECV Read Messages from Buffer This command reads messages from storage buffer where the messages are stored after being reported by the server. AT+QMTRECV Read Messages from Buffer Test Command AT+QMTRECV=? Read Command AT+QMTRECV? Response OK Response +QMTRECV: ,,,,, OK If there is no MQTT connection: OK EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 27 / 37 LTE Standard Module Series Write Command AT+QMTRECV=[,] Response [(List of +QMTRECV: ,,[,],)] OK Maximum Response Time Characteristics If there is no MQTT connection: ERROR 300 ms This command takes effect immediately. The configurations are not saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Indicates if a message stored in the buffer. As maximum 5 messages can be stored in a buffer, the URC can report at most 5 messages simultaneously. 0 No stored messages 1 There are stored messages (up to 5) Integer type. Serial number of a received message. Range: 0–4. Integer type. Message identifier of packet. Range: 0–65535. It will be 0 only when =0. String type. Topic that needs to be published. Integer type. Payload length. String type. Payload relating to topic name. EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 28 / 37 LTE Standard Module Series 4 MQTT-Related URCs This chapter describes the MQTT-related URCs. Table 3: MQTT-Related URCs SN URC Format Description When the state of MQTT link layer changes, the [1] +QMTSTAT: , client will close the MQTT connection and report the URC. +QMTRECV: ,,[,], data from MQTT server. [3] +QMTRECV: , Reported when the message received from MQTT server has been stored in buffer. When the state of MQTT link layer changes, the [4] +QMTPING: , client will close the MQTT connection and report the URC. 4.1. +QMTSTAT Indicate State Change in MQTT Link Layer The URC begins with +QMTSTAT:. It will be reported when there is a change in the state of MQTT link layer. +QMTSTAT Indicate State Change in MQTT Link Layer +QMTSTAT: , When the state of MQTT link layer changes, the client will close the MQTT connection and report the URC. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Error code. Please refer to Table 4 for details. EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 29 / 37 LTE Standard Module Series Table 4: URC Error Codes Description How to Do Execute AT+QMTOPEN and reopen MQTT 1 Connection is closed or reset by peer. connection. Sending PINGREQ packet timed out Deactivate PDP first, and then activate PDP 2 or failed. and reopen MQTT connection. 1. Check whether the inputted user name and password are correct. Sending CONNECT packet timed out 3 2. Make sure the client ID is not used. or failed. 3. Reopen MQTT connection and try to send CONNECT packet to server again. 1. Check whether the inputted user name and password are correct. Receiving CONNACK packet timed out 4 2. Make sure the client ID is not used. or failed. 3. Reopen MQTT connection and try to send CONNECT packet to server again. The client sends DISCONNECT 5 packet to sever and the server closes This is a normal process. MQTT connection. The client closes MQTT connection 1. Make sure the data is correct. 6 due to repetitive packet sending 2. Try to reopen MQTT connection since there failure. may be network congestion or an error. The link is not alive or the server is Make sure the link is alive or the server is 7 unavailable. available. The client closes the MQTT 8 Try to reconnect. connection. 9–255 Reserved for future use. 4.2. +QMTRECV Notify Host to Read MQTT Packet Data The URC begins with +QMTRECV:. It is mainly used to notify the host to read the received MQTT packet data that is reported from MQTT server. +QMTRECV Notify Host to Read MQTT Packet Data +QMTRECV: ,,[,], +QMTRECV: , Notify the host to read the received data reported from MQTT server. Reported when the message received from MQTT server has been stored in buffer. EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 30 / 37 LTE Standard Module Series Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of packet. String type. Topic received from MQTT server. Integer type. Payload length. String type. Payload relating to the topic name. Integer type. Serial number of received message. Range: 0–4. 4.3. +QMTPING Indicate PING State of Keep-alive in MQTT The URC begins with +QMTPING:. It will be reported when server does not receive a message from the client within 1.5 times of the keep-alive time period and it will disconnect the client as if the client has sent a DISCONNECT message. +QMTPING Indicate PING State of Keep-alive in MQTT +QMTPING: , When the state of MQTT link layer changes, the client will close the MQTT connection and report the URC. Parameter . Integer type. MQTT client identifier. Range: 0–5. Integer type. Result of PING state. 1 Failed EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 31 / 37 LTE Standard Module Series 5 Examples This chapter provides examples that explain how to use MQTT-related AT commands. 5.1. Example of MQTT Operation without SSL //Configure receiving mode. AT+QMTCFG='recv/mode',0,0,1 OK //Configure Alibaba device information for Alibaba cloud. AT+QMTCFG='aliauth',0,'oyjtmPl5a5j','MQTT_TEST','wN9Y6pZSIIy7Exa5qVzcmigEGO4kAazZ' OK AT+QMTOPEN=? +QMTOPEN: (0-5),'hostname',(1-65535) OK //Open a network for MQTT client. AT+QMTOPEN=0,'iot-as-mqtt.cn-shanghai.aliyuncs.com',1883 OK +QMTOPEN: 0,0 //Opened the MQTT client network successfully. AT+QMTOPEN? +QMTOPEN: 0,'iot-as-mqtt.cn-shanghai.aliyuncs.com',1883 OK AT+QMTCONN=? +QMTCONN: (0-5),'clientid','username','password' OK //Connect a client to MQTT server. //If Alibaba Cloud is connected, customers can use AT+QMTCFG='aliauth' to configure the device information in advance, and do not need to provide username/password from now on. AT+QMTCONN=0,'clientExample' OK EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 32 / 37 LTE Standard Module Series +QMTCONN: 0,0,0 //Connected the client to MQTT server successfully. AT+QMTSUB=? +QMTSUB: (0-5), ,list of ['topic',qos] OK //Subscribe to topics. AT+QMTSUB=0,1,'topic/example',2 OK +QMTSUB: 0,1,0,2 AT+QMTSUB=0,1,'topic/pub',0 OK +QMTSUB: 0,1,0,0 //If a client subscribes to a topic and other devices publish the same topic to the server, the module will report the following information. +QMTRECV: 0,0,'topic/example',36,'This is the payload related to topic' //Unsubscribe from topics. AT+QMTUNS=0,2,'topic/example' OK +QMTUNS: 0,2,0 AT+QMTPUBEX=? +QMTPUBEX: (0-5),,(0-2),(0,1),'topic','length' OK //Publish messages. After receiving >, input data 'This is test data, hello MQTT.' and then send it. The maximum length of the data is 1500 bytes and the data exceeding 1500 bytes will be omitted. AT+QMTPUBEX=0,0,0,0,'topic/pub',30 >This is test data, hello MQTT. OK +QMTPUBEX: 0,0,0 //If a client subscribes to a topic named 'topic/pub' and other devices publish the same topic to the server, the module will report the following information. +QMTRECV: 0,0,'topic/pub',30,'This is test data, hello MQTT.' //Disconnect a client from MQTT server. EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 33 / 37 LTE Standard Module Series AT+QMTDISC=0 OK +QMTDISC: 0,0 //Send the request for disconnection successfully. //There are two possible scenarios. //The server responds to disconnection request. +QMTSTAT: 0,5 //The server did not respond to the disconnection request, and the module executed the command. AT+QMTCLOSE=0 OK +QMTCLOSE: 0,0 5.2. Example of MQTT Operation with SSL See documents [1] and [2] for AT+QFUPL and commands related to SSL. //Configure receiving mode. AT+QMTCFG='recv/mode',0,0,1 OK //Configure MQTT session into SSL mode. AT+QMTCFG='ssl',0,1,2 OK //If SSL authentication mode is 'server authentication', store CA certificate to RAM. AT+QFUPL='RAM:cacert.pem',1758,100 CONNECT +QFUPL: 1758,384a OK //If SSL authentication mode is 'server authentication', store CC certificate to RAM. AT+QFUPL='RAM:client.pem',1220,100 CONNECT +QFUPL: 1220,2d53 OK EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 34 / 37 LTE Standard Module Series //If SSL authentication mode is 'server authentication', store CK certificate to RAM. AT+QFUPL='RAM:user_key.pem',1679,100 CONNECT +QFUPL: 1679,335f OK //Configure CA certificate. AT+QSSLCFG='cacert',2,'RAM:cacert.pem' OK //Configure CC certificate. AT+QSSLCFG='clientcert',2,'RAM:client.pem' OK //Configure CK certificate. AT+QSSLCFG='clientkey',2,'RAM:user_key.pem' OK //Configure SSL parameters. AT+QSSLCFG='seclevel',2,2 //SSL authentication mode: server authentication OK AT+QSSLCFG='sslversion',2,4 //SSL authentication version OK AT+QSSLCFG='ciphersuite',2,'0xFFFF' //Cipher suite OK AT+QSSLCFG='ignorelocaltime',2,1 //Ignore the time of authentication. OK //Start MQTT SSL connection AT+QMTOPEN=0,'a1zgnxur10j8ux.iot.us-east-1.amazonaws.com',8883 OK +QMTOPEN: 0,0 //Connect to MQTT server AT+QMTCONN=0,'M26_0206' OK +QMTCONN: 0,0,0 //Subscribe to topics. AT+QMTSUB=0,1,'$aws/things/M26_0206/shadow/update/accepted',1 EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 35 / 37 LTE Standard Module Series OK +QMTSUB: 0,1,0,1 //Publish messages. AT+QMTPUBEX=0,1,1,0,'$aws/things/M26_0206/shadow/update/accepted',32 >This is published data from client OK +QMTPUBEX: 0,1,0 //If a client subscribes to a topic named '$aws/things/M26_0206/shadow/update/accepted' and other devices publish the same topic to the server, the module will report the following information. +QMTRECV: 0,1,'$aws/things/M26_0206/shadow/update/accepted',32,'This is published data from client' //Disconnect a client from MQTT server. AT+QMTDISC=0 OK +QMTDISC: 0,0 //There are two possible scenarios. //The server responds to disconnection request. +QMTSTAT: 0,5 //The server did not respond to the disconnection request, and the module executed the command. AT+QMTCLOSE=0 OK +QMTCLOSE: 0,0 EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 36 / 37 LTE Standard Module Series 6 Appendix References Table 5: Related Documents Document Name [1] Quectel_EC2x&EG2x&EG9x&EM05_Series_FILE_Application_Note [2] Quectel_EC2x&EG2x&EG9x&EM05_Series_SSL_Application_Note Table 6: Terms and Abbreviations Abbreviation ACK MQTT QoS RAM SSL TCP URC Description Acknowledgement Message Queuing Telemetry Transport Quality of Service Random Access Memory Secure Sockets Layer Transmission Control Protocol Unsolicited Result Code EC2x&EG2x&EG9x&EM05_Series_MQTT_Application_Note 37 / 37
337.76 KB
RGx00U&RM500U Series RF FTM Application Note 5G Module Series Version: 1.0 Date: 2023-11-09 Status: Released RGx00U&RM500U_Series_RF_FTM_Application_Note 1 / 17 5G 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. RGx00U&RM500U_Series_RF_FTM_Application_Note 1 / 17 5G 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. RGx00U&RM500U_Series_RF_FTM_Application_Note 2 / 17 5G Module Series About the Document Revision History Version Date Author - 2023-10-11 Lenz ZHANG 1.0 2023-11-09 Lenz ZHANG Description Creation of the document First official release RGx00U&RM500U_Series_RF_FTM_Application_Note 3 / 17 5G 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. Description of RF FTM AT Commands ...................................................................................... 8 2.3.1. AT+QRFTEST RF Test in FTM Under WCDMA/LTE/5G ............................................. 8 2.3.2. CMW500 Configuration for RX Test.............................................................................. 14 3 Example ............................................................................................................................................. 15 4 Appendix ............................................................................................................................................ 17 RGx00U&RM500U_Series_RF_FTM_Application_Note 4 / 17 5G Module Series Table Index Table 1: Type of AT Commands and Responses ......................................................................................... 7 Table 2: RX/TX Channel Distribution of 5G Bands .................................................................................... 10 Table 3: RX/TX Channel Distribution of LTE Bands....................................................................................11 Table 4: RX/TX Channel Distribution of WCDMA Bands ........................................................................... 13 Table 5: Terms and Abbreviations .............................................................................................................. 17 RGx00U&RM500U_Series_RF_FTM_Application_Note 5 / 17 5G Module Series 1 Introduction The document describes the AT commands that are used to test the receiving and transmitting performance of Quectel 5G RG200U series, RG500U series and RM500U series modules in FTM (Factory Test Mode), to facilitate RF calibration. RGx00U&RM500U_Series_RF_FTM_Application_Note 6 / 17 5G 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 command line. When an optional parameter is omitted, the new value equals its previous value or its 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 1: Type of AT Commands and Responses 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 + < c m d > = < p 1 > [ , < p 2 > [ , < p 3 > Set user-definable parameter value. [...]]] Execution Command AT+ Return a specific information parameter or perform a specific action. RGx00U&RM500U_Series_RF_FTM_Application_Note 7 / 17 5G Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about how to use the AT commands introduced herein. The examples, however, should not be taken as Quectel’s 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 RF FTM AT Commands 2.3.1. AT+QRFTEST RF Test in FTM Under WCDMA/LTE/5G AT+QRFTEST RF Test in FTM Under WCDMA/LTE/5G Test Command AT+QRFTEST=? Response +QRFTEST: 'rx',,,,,, +QRFTEST: 'tx',,,,,, +QRFTEST: 'mode',(list of supported s) Write Command Query/Set FTM AT+QRFTEST='mode'[,] OK Response If the optional parameter is omitted, query the current setting: +QRFTEST: OK If the optional parameter is specified, set FTM mode: OK Write Command RX test in FTM AT+QRFTEST='rx',,, ,,, Write Command If there is any error: ERROR Response +QRFTEST: rssi[0] = , rssi[1] = , rssi[2] = , rssi[3] = OK If there is any error: ERROR Response RGx00U&RM500U_Series_RF_FTM_Application_Note 8 / 17 5G Module Series TX test in FTM AT+QRFTEST='tx',,, ,,,[,] OK If there is any error: ERROR Maximum Response Time 300 ms Characteristics This command takes effect immediately. The configurations are not saved. Parameter Integer type. RF test mode. 0 Online mode 1 FTM Integer type. WCDMA/LTE/5G configuration. 0 WCDMA 1 LTE 2 5G Integer type. WCDMA/LTE/5G Band. 1 5G n1/LTE B1/WCDMA B1 2 5G n2/LTE B2/WCDMA B2 3 5G n3/LTE B3/WCDMA B3 4 LTE B4/WCDMA B4 5 5G n5/LTE B5/WCDMA B5 6 LTE B6/WCDMA B6 7 5G n7/LTE B7/WCDMA B7 8 5G n8/LTE B8/WCDMA B8 9 LTE B9/WCDMA B9 10 LTE B10/WCDMA B10 11 LTE B11/WCDMA B11 …… 19 LTE B19/WCDMA B19 20 5G n20/LTE B20 28 5G n28/LTE B28 …… Integer type. WCDMA/LTE/5G bandwidth. Unit: MHz. 0 1.4 1 3 2 5 3 10 4 15 5 20 6 40 (Applicable to 5G only) 8 80 (Applicable to 5G only) RGx00U&RM500U_Series_RF_FTM_Application_Note 9 / 17 5G Module Series 10 100 (Applicable to 5G only) Integer type. RX/TX channel. See table 2, table 3 and table 4 for details. Integer type. Receiving antenna index. (Not supported currently) 0 PRX 1 DRX Integer type. Expected value of Rx AGC. The value of this parameter should be set to the signal strength sent on the radio communication tester. Unit: dBm. (Currently not supported) Integer type. RSSI value of antenna. Integer type. Enable/disable TX. 0 Disable 1 Enable Integer type. Transceiver output gain. This parameter has a positive correlation with the actual TX power. Unit: dBm. It is recommended to set it to 23. Integer type. Antenna configuration. This parameter is only configured in the 5G network and is omitted in the LTE and WCDMA networks. 0 Primary antenna 1 Secondary antenna NOTE 1. For network modes and corresponding bands, see table 2, table 3 and table 4. 2. After each RX/TX test of a network mode (5G/LTE/WCDMA), execute AT+QRFTEST='mode',0 to exit FTM, then execute AT+QRFTEST='mode',1 to reenter FTM before RX/TX testing of the next network mode. 3. When performing TX test in FTM, if you need to switch bands, first set to 0 to disable the TX test, and then reconfigure the parameters. 4. The RSSI values returned by different modules correspond to different antenna ports. For the relationship between RSSI values and corresponding antenna ports, please refer to the relevant module's hardware design manual. 5. The demo test data for RX/TX tests can be obtained by contacting Quectel Technical Support. Table 2: RX/TX Channel Distribution of 5G Bands 5G bands n1 RX channel Range Minimum–Maximum 422000–434000 n2 386000–398000 n3 361000–376000 n5 173800–178800 TX channel Range Minimum–Maximum 384000–396000 370000–382000 342000–357000 164800–169800 RGx00U&RM500U_Series_RF_FTM_Application_Note 10 / 17 n7 524000–538000 n8 185000–192000 n20 158200–164200 n28 151600–160600 n38 514000–524000 n41 499200–537999 n50 286400–303400 n51 285400–286400 n66 422000–440000 n70 399000–404000 n71 123400–130400 n74 295000–303600 n75 286400–303400 n76 285400–286400 n77 620000–680000 n78 620000–653333 n79 693334–733333 Table 3: RX/TX Channel Distribution of LTE Bands LTE bands LTE B1 RX channel Range Minimum–Default–Maximum 0–300–599 LTE B2 600–900–1199 LTE B3 1200–1575–1949 LTE B4 1950–2175–2399 LTE B5 2400–2525–2649 5G Module Series 500000–514000 176000–183000 166400–172400 140600–149600 514000–524000 499200–537999 286400–303400 285400–286400 342000–356000 339000–342000 132600–139600 285400–294000 620000–680000 620000–653333 693334–733333 TX channel Range Minimum–Default–Maximum 18000–18300–18599 18600–18900–19199 19200–19575–19949 19950–20175–20339 20400–20525–20649 RGx00U&RM500U_Series_RF_FTM_Application_Note 11 / 17 LTE B6 LTE B7 LTE B8 LTE B9 LTE B10 LTE B11 LTE B12 LTE B13 LTE B14 LTE B17 LTE B18 LTE B19 LTE B20 LTE B21 LTE B22 LTE B23 LTE B24 LTE B25 LTE B26 LTE B27 LTE B28 LTE B29 LTE B30 LTE B31 LTE B32 2650–2700–2749 2750–3100–3449 3450–3625–3799 3800–3975–4149 4150–4450–4749 4750–4850–4949 5000–5095–5179 5180–5230–5279 5280–5330–5379 5730–5790–5849 5850–5925–5999 6000–6075–6149 6150–6300–6449 6450–6525–6599 6600–7000–7399 7500–7600–7699 7700–7870–8039 8040–8365–8689 8690–8865–9039 9040–9125–9209 9210–9435–9659 9660–9715–9769 9770–9820–9869 9870–9895–9919 9920–10140–10359 5G Module Series 20650–20700–20749 20750–21100–21449 21450–21625–21799 21800–21975–22149 22150–22450–22749 22750–22850–22949 23000–23095–23179 23180–23230–23279 23280–23330–23379 23730–23790–23849 23850–23925–23999 24000–24075–24149 24150–24300–24449 24450–24525–24599 24600–25000–25399 25500–25600–25699 25700–25870–26039 26040–26365–26689 26690–26865–27039 27040–27125–27209 27210–27435–27659 27660–27710–27759 27760–27785–27809 25700–25870–26039 - RGx00U&RM500U_Series_RF_FTM_Application_Note 12 / 17 LTE B33 LTE B34 LTE B35 LTE B36 LTE B37 LTE B38 LTE B39 LTE B40 LTE B41 LTE B42 LTE B43 LTE B46 LTE B47 LTE B48 LTE B66 LTE B71 36000–36100–36199 36200–36275–36349 36350–36650–36949 36950–37250–37549 37550–37650–37749 37750–38000–38249 38250–38450–38649 38650–39150–39649 39650–40620–41589 41590–42590–43589 43590–44590–45589 46790–50665–54539 54540–54885–55239 55240–55940–56739 66436–66886–67335 68586–68761–68935 5G Module Series 36000–36100–36199 36200–36275–36349 36350–36650–36949 36950–37250–37549 37550–37650–37749 37750–38000–38249 38250–38450–38649 38650–39150–39649 39650–40620–41589 41590–42590–43589 43590–44590–45589 46790–50665–54539 54540–54885–55239 55240–55940–56739 131972–132322–132671 133122–133297–133471 Table 4: RX/TX Channel Distribution of WCDMA Bands WCDMA bands WCDMA B1 RX channel Range Minimum–Default–Maximum 10562–10700–10838 TX channel Range Minimum–Default–Maximum 9612–9750–9888 WCDMA B2 9662–9800–9938 9262–9400–9538 WCDMA B3 1162–1338–1513 937–1112–1288 WCDMA B4 1537–1638–1738 1312–1412–1513 WCDMA B5 4357–4408–4458 4132–4182–4233 WCDMA B6 4387–4400–4413 4162–4175–4188 RGx00U&RM500U_Series_RF_FTM_Application_Note 13 / 17 WCDMA B7 WCDMA B8 WCDMA B9 WCDMA B10 WCDMA B11 WCDMA B19 2237–2400–2563 2937–3012–3088 9237–9312–9387 3112–3250–3388 3712–3762–3812 712–738–763 5G Module Series 2012–2175–2338 2712–2788–2863 8762–8837–8912 2887–3025–3163 3487–3537–3587 312–338–363 2.3.2. CMW500 Configuration for RX Test Signal sources which emit continuous waves can be used as the downlink CW signals. If you use the CMW500 to test the receiving performance, the following settings can be applied: Figure 1: CMW500 Configuration RGx00U&RM500U_Series_RF_FTM_Application_Note 14 / 17 5G Module Series 3 Example AT+QRFTEST=? +QRFTEST: 'rx',,,,,, +QRFTEST: 'tx',,,,,, +QRFTEST: 'mode',(0,1) OK //RX Test in FTM AT+QRFTEST='mode' +QRFTEST: 0 //Query the RF test mode OK AT+QRFTEST='mode',1 //Enter FTM OK AT+QRFTEST='rx',1,41,3,40620,0,-600 //Perform RX test for LTE B41 +QRFTEST: rssi[0] = -17608, rssi[1] = -8901, rssi[2] = -120, rssi[3] = -120 OK AT+QRFTEST='mode',0 //Exit FTM OK //TX test in FTM AT+QRFTEST='mode' //Query the RF test mode +QRFTEST: 0 OK AT+QRFTEST='mode',1 OK AT+QRFTEST='tx',1,41,3,40620,1,23 OK AT+QRFTEST='tx',1,41,3,40620,0,23 OK //Enter FTM //Perform TX test for LTE B41 //Disable TX test of LTE B41 AT+QRFTEST='tx',1,20,3,24300,1,23 OK AT+QRFTEST='tx',1,20,3,24300,0,23 OK AT+QRFTEST='mode',0 OK AT+QRFTEST='mode' //Perform TX test for LTE B20 //Disable TX test of LTE B20 //Exit FTM //Query the RF test mode RGx00U&RM500U_Series_RF_FTM_Application_Note 15 / 17 +QRFTEST: 0 OK AT+QRFTEST='mode',1 OK AT+QRFTEST='tx',2,41,6,518601,1,23,0 OK AT+QRFTEST='tx',2,41,6,518601,0,23,0 OK AT+QRFTEST='tx',2,41,6,518601,1,23,1 OK AT+QRFTEST='tx',2,41,6,518601,0,23,1 OK AT+QRFTEST='mode',0 OK 5G Module Series //Enter FTM //Perform TX test for 5G n41 primary antenna //Disable TX test of 5G n41 primary antenna //Perform TX test for 5G n41 secondary antenna //Disable TX test of 5G n41 secondary antenna //Exit FTM RGx00U&RM500U_Series_RF_FTM_Application_Note 16 / 17 5G Module Series 4 Appendix Table 5: Terms and Abbreviations Abbreviation AGC CW DRX FTM LTE PRX RF RSSI RX TX WCDMA Description Automatic Gain Control Continuous Wave Discontinuous Reception Factory Test Mode Long Term Evolution Primary Receive Radio Frequency Received Signal Strength Indication Receive Transmit Wideband Code Division Multiple Access RGx00U&RM500U_Series_RF_FTM_Application_Note 17 / 17
363.73 KB
EC200U&EG91xU Series STK Application Note LTE Standard Module Series Version: 1.0 Date: 2023-11-06 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_STK_Application_Note 1 / 34 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_STK_Application_Note 2 / 34 LTE Standard Module Series About the Document Revision History Version 1.0 Date 2023-02-16 2023-11-06 Author Joe TU Joe TU Description Creation of the document First official release EC200U&EG91xU_Series_STK_Application_Note 3 / 34 LTE Standard Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 5 1 Introduction .......................................................................................................................................... 6 1.1. Applicable Modules ..................................................................................................................... 6 1.2. AT Command Introduction .......................................................................................................... 6 1.2.1. Definitions......................................................................................................................... 6 1.2.2. AT Command Syntax ....................................................................................................... 7 1.3. Declaration of AT Commands ..................................................................................................... 7 1.4. Using STK AT Commands .......................................................................................................... 7 1.5. STK States .................................................................................................................................. 8 1.6. Proactive Command Responses ................................................................................................ 8 1.7. STK Character Set ...................................................................................................................... 9 2 Description of STK AT Commands .................................................................................................. 10 2.1. AT+QSTK Enable/Disable STK Functionality ........................................................................ 10 2.2. AT+QSTKPD Get Terminal Profile ......................................................................................... 11 2.3. AT+QSTKSTATE Query STK State........................................................................................ 12 2.4. AT+QSTKGI Get Proactive Command Information ............................................................... 13 2.5. AT+QSTKRSP STK Response .............................................................................................. 13 2.6. Summary of URCs .................................................................................................................... 14 2.6.1. Proactive Command Report........................................................................................... 14 2.6.2. Proactive Command Termination................................................................................... 15 2.6.3. (U)SIM Card Loss .......................................................................................................... 15 2.6.4. Timeout Response ......................................................................................................... 15 2.7. Details of Proactive Command .............................................................................. 15 2.7.1. Play Tone (32) ................................................................................................................ 16 2.7.2. Display Text (33)............................................................................................................. 18 2.7.3. Get Inkey (34)................................................................................................................. 20 2.7.4. Get Input (35) ................................................................................................................. 21 2.7.5. Select Item (36) .............................................................................................................. 23 2.7.6. Set up Menu (37) ........................................................................................................... 25 2.7.7. Set up Idle Mode Text (40) ............................................................................................. 27 2.7.8. Language Notification (53) ............................................................................................. 28 3 Examples of STK AT Commands ..................................................................................................... 30 3.1. Enable STK Function and Set up Menu ................................................................................... 30 3.2. Select Menu .............................................................................................................................. 31 3.3. Terminate STK Session and Timeout Response ...................................................................... 32 3.4. Disable STK Functionality......................................................................................................... 33 4 Appendix References ........................................................................................................................ 34 EC200U&EG91xU_Series_STK_Application_Note 4 / 34 LTE Standard Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 6 Table 2: Types of AT Commands ................................................................................................................. 7 Table 3: Proactive Command Responses.................................................................................................... 8 Table 4: Types of Proactive Commands (Refer to Chapter 13.4 in 3GPP TS 11.14) ................................ 16 Table 5: Related Document........................................................................................................................ 34 Table 6: Terms and Abbreviations .............................................................................................................. 34 EC200U&EG91xU_Series_STK_Application_Note 5 / 34 LTE Standard Module Series 1 Introduction Quectel EC200U series and EG91xU family modules provide AT commands to support (U)SIM Application Toolkit (STK). This document is a reference guide to all (U)SIM Application Toolkit-related AT commands. 1.1. Applicable Modules Table 1: Applicable Modules Module Family EG91xU Module EC200U Series EG912U-GL EG915U Series 1.2. AT Command Introduction 1.2.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. EC200U&EG91xU_Series_STK_Application_Note 6 / 34 LTE Standard Module Series 1.2.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. 1.3. Declaration of AT Commands 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. 1.4. Using STK AT Commands Step 1: Switch on the module, and enable STK functionality with AT+QSTK=1[,], then reboot the module. Step 2: Query proactive command information based on URC with AT+QSTKGI. Respond to the STK proactive command with AT+QSTKRSP. When +QSTKURC: 253 is reported, you can select a menu item with AT+QSTKRSP=253,,. Furthermore, you can use AT+QSTKRSP=254 to terminate the STK session at any time. Step 3: Disable STK functionality with AT+QSTK=0, then reboot the module. EC200U&EG91xU_Series_STK_Application_Note 7 / 34 LTE Standard Module Series 1.5. STK States There are three types of STK states: automatic response state, terminal response state, and waiting state. For more details, see Chapter 2.3. The following figure illustrates the state transitions. Automatic response state AT+QSTK=1[,] and reboot module AT+QSTK=0 and reboot module AT+QSTKRSP=,[ ] Terminal response state +QSTKURC: Waiting state Figure 1: STK State Transitions 1.6. Proactive Command Responses When STK functionality is disabled, the module will automatically respond to a proactive command. However, when STK functionality is enabled, you should respond to the proactive command (Refer to Chapter 2.7). If you do not respond to the proactive command within a specific time frame, a URC indicating a timeout response will be reported, and module will automatically respond to the proactive command. Table 3: Proactive Command Responses Proactive Command PLAY TONE (32) DISPLAY TEXT (33) GET INKEY (34) GET INPUT (35) SELECT ITEM (36) SET UP MENU (37) SET UP IDLE MODE TEXT (40) LANGUAGE NOTIFICATION (53) Automatic Response 48 0 48 48 48 0 0 0 User Response 0, 4, 16, 32, 48 0, 4, 16, 17, 18, 32, 48 0, 4, 16, 17, 18, 19, 32, 48 0, 4, 16, 17, 18, 19, 32, 48 0, 4, 16, 17, 18, 19, 32, 48 0, 4, 32, 48 0, 4, 32, 48 0 EC200U&EG91xU_Series_STK_Application_Note 8 / 34 LTE Standard Module Series 1.7. STK Character Set The STK AT command interface supports the following character sets: ⚫ GSM character set (default) ⚫ UCS-2 character set You can configure the character set with AT+QSTK=[,] (Refer to Chapter 2.1). The configured settings become effective after being set and they will affect both the input parameters and output information of STK AT commands. If UCS-2 characters cannot be converted to GSM characters, they will be converted to 0x20 (space). EC200U&EG91xU_Series_STK_Application_Note 9 / 34 LTE Standard Module Series 2 Description of STK AT Commands 2.1. AT+QSTK Enable/Disable STK Functionality AT+QSTK Enable/Disable STK Functionality Test Command AT+QSTK=? Response +QSTK: (list of supported s),(list of supported < alphabet>s),(range of supported s) Read Command AT+QSTK? OK Response +QSTK: ,, OK Or ERROR If error is related to ME functionality: +CME ERROR: Write Command AT+QSTK=[,[,]] Response OK Or ERROR Maximum Response Time Characteristic If error is related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. EC200U&EG91xU_Series_STK_Application_Note 10 / 34 LTE Standard Module Series Parameter Integer type. Enable or disable the STK functionality. 0 Disable 1 Enable Integer type. Character set encoding. 0 GSM character set 1 UCS-2 character set Integer type. Response timeout. Range: 1–65535. Default value: 300. Unit: second. Integer type. Error code. See document [1] for details. Example AT+QSTK=? +QSTK: (0,1),(0,1),(1-65535) OK AT+QSTK? +QSTK: 0,0,300 OK 2.2. AT+QSTKPD Get Terminal Profile This command gets the terminal profile. For more details, see ETSI TS 102 223. AT+QSTKPD Get Terminal Profile Test Command AT+QSTKPD=? Read Command AT+QSTKPD? Response OK Response +QSTKPD: OK Or ERROR Maximum Response Time Characteristics If error is related to ME functionality: +CME ERROR: 300 ms / EC200U&EG91xU_Series_STK_Application_Note 11 / 34 LTE Standard Module Series Parameter Hex string. STK profile. Integer type. Error code. See document [1] for details. 2.3. AT+QSTKSTATE Query STK State When executing AT+QSTKGI or AT+QSTKRSP, you should refer to the value of . When is 0 or 2, will be ignored. When is 253, it indicates that the STK session has ended. In this STK state, you cannot get STK proactive command information via AT+QSTKGI= and do not need to respond to the proactive command via AT+QSTKRSP. However, you can select a menu item via AT+QSTKRSP=253,, and start an STK session. AT+QSTKSTATE Query STK State Test Command AT+QSTKSTATE=? Response +QSTKSTATE: (range of supported s),(list of supported s) Read Command AT+QSTKSTATE? OK Response +QSTKSTATE: [,] Maximum Response Time Characteristics OK 300 ms / Parameter Integer type. STK state. 0 Automatic response state 1 Terminal response state 2 Waiting state Integer type. Type of command. Range: 32–37, 40, 53, 253. Refer to Table 4 for details. EC200U&EG91xU_Series_STK_Application_Note 12 / 34 LTE Standard Module Series 2.4. AT+QSTKGI Get Proactive Command Information When URC: +QSTKURC: has been reported, you can get STK proactive command information via AT+QSTKGI=. AT+QSTKGI Get Proactive Command Information Test Command AT+QSTKGI=? Response +QSTKGI: (list of supported s) Write Command AT+QSTKGI= Maximum Response Time Characteristics OK Response varies with . See Chapter 2.7 for details. 300 ms / Parameter Integer type. Type of proactive command. Range: 32–37, 40, 53. Refer to Table 4 for details. 2.5. AT+QSTKRSP STK Response After receiving the URC +QSTKURC: , you can get information via AT+QSTKGI= and respond via AT+QSTKRSP. AT+QSTKRSP=253,, is used to select a menu item. It can only be used after receiving +QSTKURC: 253. Terminate STK session via AT+QSTKRSP=254, and then +QSTKURC: 253 will be reported. AT+QSTKRSP STK Response Test Command AT+QSTKRSP=? Response +QSTKRSP: (list of supported s) Write Command Select a menu item AT+QSTKRSP=253,, OK Response OK Or ERROR EC200U&EG91xU_Series_STK_Application_Note 13 / 34 Write Command Terminate the current STK session AT+QSTKRSP=254 Maximum Response Time Characteristics LTE Standard Module Series If error is related to ME functionality: +CME ERROR: Response OK Or ERROR 10 s / Parameter Integer type. Type of command. Range: 32–37, 40, 53, 253, 254. Refer to Table 4 for details. Integer type. Command result. 0 Trigger modem to select menu 19 Help information required by the user Integer type. Menu item ID. Range: 1–255. Integer type. Error code. See document [1] for details. 2.6. Summary of URCs The URCs of STK will be reported to the host in the format +QSTKURC: . They cover various scenarios such as proactive command report, the termination of proactive commands, (U)SIM card loss, and timeout response. 2.6.1. Proactive Command Report During an ongoing STK session, this URC will be reported to prompt you to get the proactive command information via AT+QSTKGI= and respond to the proactive command via AT+QSTKRSP. Proactive Command Report +QSTKURC: Indication of proactive command Parameter Integer type. Type of proactive command. Range: 32–37, 40, 53. Refer to Table 4 for details. EC200U&EG91xU_Series_STK_Application_Note 14 / 34 LTE Standard Module Series 2.6.2. Proactive Command Termination When STK session is finished, the URC +QSTKURC: 253 will be reported. At this time, you cannot get STK proactive command information via AT+QSTKGI= and do not need to respond to the proactive command via AT+QSTKRSP. However, you can select a menu item via AT+QSTKRSP=253,,. Proactive Command Termination +QSTKURC: 253 The termination of proactive command 2.6.3. (U)SIM Card Loss When (U)SIM card is lost, this URC will be reported. For example, the URC is triggered when the (U)SIM card is removed or when AT+CFUN changes the module's functionality from 1 to 0. (U)SIM Card Loss +QSTKURC: 254 Indication of (U)SIM loss 2.6.4. Timeout Response When you do not respond to the proactive command within a specified time frame, this URC will be reported and the module will automatically respond to the proactive command. Timeout Response +QSTKURC: 255, Indication of timeout response Parameter Integer type. Type of proactive command. Range: 32–37, 40, 53. Refer to Table 4 for details. 2.7. Details of Proactive Command You can repeatedly retrieve proactive command information before responding to the proactive command. EC200U&EG91xU_Series_STK_Application_Note 15 / 34 LTE Standard Module Series Table 4: Types of Proactive Commands (Refer to Chapter 13.4 in 3GPP TS 11.14) 32 33 34 35 36 37 40 53 Name Play tone Display text Get inkey Get input Select item Set up menu Set up idle mode text Language notification NOTE Please note that the value of is in hexadecimal in the 3GPP TS 11.14. 2.7.1. Play Tone (32) After receiving the +QSTKURC: 32, you can retrieve information via AT+QSTKGI=32, then respond via AT+QSTKRSP=32,[,]. Play Tone (32) Write Command AT+QSTKGI=32 Response +QSTKGI: 32,,,,,,, OK Or ERROR Write Command AT+QSTKRSP=32,[,] If error is related to ME functionality: +CME ERROR: Response OK Or ERROR EC200U&EG91xU_Series_STK_Application_Note 16 / 34 LTE Standard Module Series If error is related to ME functionality: +CME ERROR: Parameter RFU. String type. Text. Integer type Tone generated by the UE. 01–08 are standard supervisory tones, and 16–18 are UE proprietary tones. 01 Dial tone 02 Called subscriber busy 03 Congestion 04 Radio path acknowledge 05 Radio path not available/call dropped 06 Error/special information 07 Call waiting tone 08 Ringing tone 16 General beep 17 Positive acknowledgement tone 18 Negative acknowledgement or error tone Integer type. Duration unit. 0 Minutes 1 Seconds 2 A tenth of a second Integer type. Duration of tone in units. Range: 1–255. Integer type. Icon qualifier. Bit 1 0 Icon is self-explanatory and can replace text 1 Icon is not self-explanatory and shall be displayed with the text determined value only if associated icon ID is not 0 (an icon exists) Bit 2–8 RFU Integer type. Icon ID. 0 No icon 1–255 Icon ID Integer type. Command result code. 0 Command executed successfully. Indicates that the user has accepted the call request 4 Command executed successfully, but requested icon could not be displayed 16 Proactive (U)SIM session was terminated by user 32 UE is unable to process command currently 48 Command is beyond UE's capabilities Integer type. Optional additional command status. Refer to ETSI TS 102 223 EC200U&EG91xU_Series_STK_Application_Note 17 / 34 LTE Standard Module Series for possible values. Range: 0–255. Integer type. Error code. See document [1] for details. NOTE It indicates that the parameter is invalid under current conditions when '-' or - is returned. See Chapter 3 for details. 2.7.2. Display Text (33) After receiving the +QSTKURC: 33, you can retrieve information via AT+QSTKGI=33, then respond via AT+QSTKRSP=33,[,]. Display Text (33) Write Command AT+QSTKGI=33 Response +QSTKGI: 33,,,,, OK Or ERROR Write Command AT+QSTKRSP=33,[,] If error is related to ME functionality: +CME ERROR: Response OK Or ERROR If error is related to ME functionality: +CME ERROR: Parameter Integer type. Display text command details. Range: 0–255. Bit 1 0 Normal priority 1 High priority Bit 2–7 RFU Bit 8 0 Clear message after a delay 1 Wait for user to clear message String type. Text. Integer type. Immediate response to displayed text. 0 Send terminal response when text is cleared from screen EC200U&EG91xU_Series_STK_Application_Note 18 / 34 LTE Standard Module Series 1 Send terminal response immediately and continue to display the text until one of the following events occurs: ⚫ A subsequent proactive command is received, containing displayed data ⚫ A short delay notified with has expired ⚫ User intervention ⚫ A higher priority event occurs, e.g. a mobile terminated call Integer type. Icon qualifier. Bit 1 0 Icon is self-explanatory and can replace text 1 Icon is not self-explanatory and shall be displayed with the text determined value only if associated icon ID is not 0 (an icon exists) Bit 2–8 RFU Integer type. Icon ID. 0 No icon 1–255 Icon ID Integer type. Command result code. 0 Command executed successfully. Indicates that the user has accepted the call request 4 Command executed successfully, but requested icon could not be displayed 16 Proactive (U)SIM session was terminated by user 17 Backward move in the proactive (U)SIM session is requested by the user 18 No response from user 32 UE is unable to process command currently 48 Command is beyond UE's capabilities Integer type. Optional additional command status. See ETSI TS 102 223 for possible values. Range: 0–255. Integer type. Error code. See document [1] for details. NOTE It indicates that the parameter is invalid under current conditions when '-' or - is returned. See Chapter 3 for details. EC200U&EG91xU_Series_STK_Application_Note 19 / 34 LTE Standard Module Series 2.7.3. Get Inkey (34) After receiving the +QSTKURC: 34, you can retrieve information via AT+QSTKGI=34, then respond via AT+QSTKRSP=34,,[,]. Get Inkey (34) Write Command AT+QSTKGI=34 Response +QSTKGI: 34,,,, OK Or ERROR Write Command AT+QSTKRSP=34,,[,] If error is related to ME functionality: +CME ERROR: Response OK Or ERROR If error is related to ME functionality: +CME ERROR: Parameter Integer type. Get inkey command details. Range: 0–255. Bit 1 0 Digits only 1 Alphabet set Bit 2 0 SMS default alphabet (GSM character set) 1 UCS-2 alphabet Bit 3 0 Character sets defined by bit 1 and bit 2 are enabled 1 Character sets defined by bit 1 and bit 2 are disabled and the 'Yes/No' response is requested Bit 4–7 RFU Bit 8 0 Help information is not available 1 Help information is available String type. Text. Integer type. Icon qualifier. Bit 1 0 Icon is self-explanatory and can replace text 1 Icon is not self-explanatory and shall be displayed with the text determined value only if associated icon ID is not 0 (an icon exists) Bit 2–8 RFU EC200U&EG91xU_Series_STK_Application_Note 20 / 34 LTE Standard Module Series Integer type. Icon ID. 0 No icon 1–255 Icon ID Integer type. Command result code. 0 Command executed successfully. Indicates that the user has accepted the call request 4 Command executed successfully, but requested icon could not be displayed 16 Proactive (U)SIM session is terminated by user 17 Backward move in the proactive (U)SIM session requested by the user 18 No response from user 19 Help information is required by the user 32 UE is unable to process command currently 48 Command is beyond UE's capabilities String type. Input string. Integer type. Optional additional command status. Refer to ETSI TS 102 223 for possible values. Range: 0–255. Integer type. Error code. See document [1] for details. NOTE It indicates that the parameter is invalid under current conditions when '-' or - is returned. See Chapter 3 for details. 2.7.4. Get Input (35) After receiving the +QSTKURC: 35, you can get information via AT+QSTKGI=35, then respond via AT+QSTKRSP=35,,[,]. See Chapter 3.3 for example. Get Input (35) Write Command AT+QSTKGI=35 Response +QSTKGI: 35,,,,,,, OK Or ERROR Write Command AT+QSTKRSP=35,,[,] If error is related to ME functionality: +CME ERROR: Response OK Or EC200U&EG91xU_Series_STK_Application_Note 21 / 34 LTE Standard Module Series ERROR If error is related to ME functionality: +CME ERROR: Parameter Integer type. Get input command details. Range: 0–255. Bit 1 0 Digits only 1 Alphabet set Bit 2 0 SMS default alphabet (GSM character set) 1 UCS-2 alphabet Bit 3 0 ME may echo user input on the display 1 User input shall not be revealed in any way Bit 4 0 User input in unpacked format 1 User input in SMS packed format Bit 5–7 RFU Bit 8 0 No help information available 1 Help information available String type. Text. Integer type. Minimum length of user input. Integer type. Maximum length of user input. String type. Default input text. Integer type. Icon qualifier. Bit 1 0 Icon is self-explanatory and can replace text 1 Icon is not self-explanatory and shall be displayed with the text determined value only if associated icon ID is not 0 (an icon exists) Bit 2–8 RFU Integer type. Icon ID. 0 No icon 1–255 Icon ID Integer type. Command result code. 0 Command executed successfully. Indicates that the user has accepted the call request 4 Command executed successfully, but requested icon could not be displayed 16 Proactive (U)SIM session is terminated by user 17 Backward move in the proactive (U)SIM session requested by the user 18 No response from user 19 Help information is required by the user 32 UE is unable to process command currently 48 Command is beyond UE's capabilities String type. Input string. EC200U&EG91xU_Series_STK_Application_Note 22 / 34 LTE Standard Module Series Integer type. Optional additional command status. Refer to ETSI TS 102 223 for possible values. Range: 0–255. Integer type. Error code. See document [1] for details. NOTE It indicates that the parameter is invalid under current conditions when '-' or - is returned. See Chapter 3 for details. 2.7.5. Select Item (36) After receiving the +QSTKURC: 36, you can get information via AT+QSTKGI=36, then respond via AT+QSTKRSP=36,,[,]. Select Item (36) Write Command AT+QSTKGI=36 Response The response for first line of output: +QSTKGI: 36,,,,< default_itemID>,,,, There are repeated lines for each item with a total number of , and each line lists the following information: +QSTKGI: 36,,,, OK Or ERROR Write Command AT+QSTKRSP=36,, [,] If error is related to ME functionality: +CME ERROR: Response OK Or ERROR If error is related to ME functionality: +CME ERROR: EC200U&EG91xU_Series_STK_Application_Note 23 / 34 LTE Standard Module Series Parameter Integer type. Details of selected item command. Bit 1 0 Presentation type is not specified 1 Presentation type is specified in bit 2 Bit 2 0 Presentation as a choice of data values, if bit 1=1 1 Presentation as a choice of navigation options if bit 1=1 Bit 3 0 No selection preference 1 Using soft key preferred to select Bit 4–7 RFU Bit 8 0 Help information is not available 1 Help information is available Integer type. Number of items in the list. String type. Title. Integer type. Default item ID. 0 No default item is issued 1–255 ID of the default Item Integer type. Presence of item icon. 0 No icon 1 Icon is presented Integer type. Item icon qualifier. Bit 1 0 Icon is self-explanatory and can replace text 1 Icon is not self-explanatory and shall be displayed with the text determined value only if associated icon ID is not 0 (an icon exists) Bit 2–8 RFU Integer type. Title icon qualifier. Bit 1 0 Icon is self-explanatory and can replace text 1 Icon is not self-explanatory and shall be displayed with the text determined value only if associated icon ID is not 0 (an icon exists) Bit 2–8 RFU Integer type. Title icon ID. 0 No icon 1–255 Icon ID Integer type. Item identifier. String type. Item text. Integer type. The next proactive command type to be issued upon execution of the menu item. Integer type. Item icon ID. 0 No icon 1–255 Icon ID Integer type. Command result code. 0 Command executed successfully. Indicates that the user has accepted the call request EC200U&EG91xU_Series_STK_Application_Note 24 / 34 LTE Standard Module Series 4 Command executed successfully, but requested icon could not be displayed 16 Proactive (U)SIM session terminated by user 17 Backward move in the proactive (U)SIM session requested by the user 18 No response from user 19 Help information required by the user 32 UE is unable to process command currently 48 Command beyond UE's capabilities Integer type. Optional additional command status. Refer to ETSI TS 102 223 for possible values. Range: 0–255. Integer type. Error code. See document [1] for details. NOTE It indicates that the parameter is invalid under current conditions when '-' or - is returned. See Chapter 3 for details. 2.7.6. Set up Menu (37) After receiving the +QSTKURC: 37, you can get information via AT+QSTKGI=37, then respond via AT+QSTKRSP=37,[,]. See Chapter 3.1 for example. After this, you can get main menu via AT+QSTKGI=37. Set up Menu (37) Write Command AT+QSTKGI=37 Response The response for first line of output: +QSTKGI: 37,,,,,,, There are repeated lines for each item with a total number of , and and each line lists the following information: +QSTKGI: 37,,,, OK Or ERROR Write Command If error is related to ME functionality: +CME ERROR: Response EC200U&EG91xU_Series_STK_Application_Note 25 / 34 LTE Standard Module Series AT+QSTKRSP=37,[,] OK Or ERROR If error is related to ME functionality: +CME ERROR: Parameter Integer type. Details of set up menu command. Bit 1 0 No selection preference 1 Using soft key preferred to select Bit 2–7 RFU Bit 8 0 Help information is not available 1 Help information is available Integer type. Number of items in the list. String type. Title. Integer type. Presence of item icon. 0 No icon 1 Icon is presented Integer type. Item icon qualifier. Bit 1 0 Icon is self-explanatory and can replace text 1 Icon is not self-explanatory and shall be displayed with the text determined value only if associated icon ID is not 0 (an icon exists) Bit 2-8 RFU Integer type. Icon qualifier. Bit 1 0 Icon is self-explanatory and can replace text 1 Icon is not self-explanatory and shall be displayed with the text determined value only if associated icon ID is not 0 (an icon exists) Bit 2–8 RFU Integer type. Title icon ID. 0 No icon 1–255 Icon ID Integer type. Item identifier. String type. Item text. Integer type. The next proactive command type to be issued upon execution of the menu item. Integer type. Item icon ID. 0 No icon 1–255 Icon ID Integer type. Command result code. 0 Command executed successfully. Indicates that the user has accepted EC200U&EG91xU_Series_STK_Application_Note 26 / 34 LTE Standard Module Series the call request. 4 Command executed successfully, but requested icon could not be displayed 32 UE is unable to process command currently 48 Command is beyond UE's capabilities Integer type. Optional additional command status. Refer to ETSI TS 102 223 for possible values. Range: 0–255. Integer type. Error code. See document [1] for details. NOTE It indicates that the parameter is invalid under current conditions when '-' or - is returned. See Chapter 3 for details. 2.7.7. Set up Idle Mode Text (40) After receiving the +QSTKURC: 40, you can get information via AT+QSTKGI=40, then respond via AT+QSTKRSP=40,[,]. This command provides text, and optionally, an icon will be displayed by the TE when the display is idle. Set up Idle Mode Text (40) Write Command AT+QSTKGI=40 Response The response for first line of output: +QSTKGI: 40,,,, OK Or ERROR Write Command AT+QSTKRSP=40,[,] If error is related to ME functionality: +CME ERROR: Response OK Or ERROR If error is related to ME functionality: +CME ERROR: EC200U&EG91xU_Series_STK_Application_Note 27 / 34 LTE Standard Module Series Parameter RFU. String type. Text to be displayed when TE is in idle mode. Integer type. Icon qualifier. Bit 1 0 Icon is self-explanatory and can replace text 1 Icon is not self-explanatory and shall be displayed with the text determined value only if associated icon ID is not 0 (an icon exists) Bit 2–8 RFU Integer type. Icon ID. 0 No icon 1–255 Icon ID Integer type. Command result code. 0 Command executed successfully. Indicates that the user has accepted the call request 4 Command executed successfully, but requested icon could not be displayed 32 UE is unable to process command currently 48 Command is beyond UE's capabilities Integer type. Optional additional command status. Refer to ETSI TS 102 223 for possible values. Range: 0–255. Integer type. Error code. See document [1] for details. NOTE It indicates that the parameter is invalid under current conditions when '-' or - is returned. See Chapter 3 for details. 2.7.8. Language Notification (53) After receiving the +QSTKURC: 53, you can get information via AT+QSTKGI=53, then respond via AT+QSTKRSP=53,[,]. Language Notification (53) Write Command AT+QSTKGI=53 Response The response for first line of output: +QSTKGI: 53,, OK Or ERROR If error is related to ME functionality: EC200U&EG91xU_Series_STK_Application_Note 28 / 34 LTE Standard Module Series +CME ERROR: Write Command AT+QSTKRSP=53,[,] Response OK Or ERROR If error is related to ME functionality: +CME ERROR: Parameter Integer type. Details of language notification command. Bit 1 0 Non-specific language notification 1 Specific language notification Bit 2–8 RFU String type. Language code string. Provided as a pair of alpha-numeric characters, defined in ISO 639. Each alphanumeric character is coded on one byte using the SMS default 7-bit coded alphabet as defined in 3GPP TS 23.038. Integer type. Command result code. 0 Command executed successfully. Indicates that the user has accepted the call request Integer type. Optional additional command status. Refer to ETSI TS 102 223 for possible values. Range: 0–255. Integer type. Error code. See document [1] for details. NOTE It indicates that the parameter is invalid under current conditions when '-' or - is returned. See Chapter 3 for details. EC200U&EG91xU_Series_STK_Application_Note 29 / 34 LTE Standard Module Series 3 Examples of STK AT Commands 3.1. Enable STK Function and Set up Menu 1. Switch on the module and enable STK functionality. AT+QSTK=1,1 OK //Enable STK functionality. 2. Reset the module and you will receive the URC of the first proactive command, as follows: +QSTKURC: 37 3. Request menu parameter information and respond to the menu setup proactive command. AT+QSTKGI=37 //Get menu setup proactive command information. +QSTKGI: 37,0,9,'005500530049004D53615E947528',-,-,-,- +QSTKGI: 37,25,'7CBE54C163A88350',-,- +QSTKGI: 37,33,'6C83901A884C8BC1',-,- +QSTKGI: 37,54,'624B673A84254E1A5385',-,- +QSTKGI: 37,96,'6C8353C28003',-,- +QSTKGI: 37,98,'727960E0793C5305',-,- +QSTKGI: 37,100,'6C8377E597F3',-,- +QSTKGI: 37,102,'6C8373AF7403',-,- +QSTKGI: 37,104,'6C835A314E50',-,- +QSTKGI: 37,105,'8BA48BC152A9624B',-,- OK AT+QSTKRSP=37,0 OK //Respond to menu setup proactive command. +QSTKURC: 253 //URC indicates that the proactive session has ended. EC200U&EG91xU_Series_STK_Application_Note 30 / 34 LTE Standard Module Series 3.2. Select Menu 1. Select menu item. AT+QSTKRSP=253,0,25 OK //Select menu item, ID is 25. 2. Select item. +QSTKURC: 36 //Select item proactive command notification. AT+QSTKGI=36 //Get the selected item proactive command information. +QSTKGI: 36,0,9,'7CBE54C163A88350',-,-,-,-,- +QSTKGI: 36,1,'53057F574E078C61',-,- +QSTKGI: 36,2,'5E7D9ED851B77B118BDD',-,- +QSTKGI: 36,3,'59296C14988462A5',-,- +QSTKGI: 36,4,'65B095FB805A7126',-,- +QSTKGI: 36,5,'4F53575B5FEB8BAF',-,- +QSTKGI: 36,6,'4EB24EB25B9D8D1D',-,- +QSTKGI: 36,7,'65C56E38653B7565',-,- +QSTKGI: 36,8,'822A73ED67E58BE2',-,- +QSTKGI: 36,255,'4E0B4E009875',-,- OK AT+QSTKRSP=36,0,1 OK //Respond to the selected item proactive command and the item (ID is 1) is selected. +QSTKURC: 36 //Select item proactive command notification. AT+QSTKGI=36 +QSTKGI: 36,0,3,'',-,-,-,-,+QSTKGI: 36,1,'5B9A5236',-,+QSTKGI: 36,2,'53D66D88',-,+QSTKGI: 36,3,'4E1A52A14ECB7ECD',-,- OK AT+QSTKRSP=36,0,3 +QSTKURC: 33 //Respond to the selected item proactive command and the item (ID is 3) is selected. //Display text proactive command notification. AT+QSTKGI=33 +QSTKGI: 33,1,'77ED4FE153D190016210529FFF01',-,-,- OK EC200U&EG91xU_Series_STK_Application_Note 31 / 34 LTE Standard Module Series 3.3. Terminate STK Session and Timeout Response 1. Terminate STK session. AT+QSTKRSP=253,0,25 OK //Select menu item. ID is 25. +QSTKURC: 36 //Select item proactive command notification. AT+QSTKGI=36 //Get the selected item proactive command information. +QSTKGI: 36,0,9,'7CBE54C163A88350',-,-,-,-,- +QSTKGI: 36,1,'53057F574E078C61',-,- +QSTKGI: 36,2,'5E7D9ED851B77B118BDD',-,- +QSTKGI: 36,3,'59296C14988462A5',-,- +QSTKGI: 36,4,'65B095FB805A7126',-,- +QSTKGI: 36,5,'4F53575B5FEB8BAF',-,- +QSTKGI: 36,6,'4EB24EB25B9D8D1D',-,- +QSTKGI: 36,7,'65C56E38653B7565',-,- +QSTKGI: 36,8,'822A73ED67E58BE2',-,- +QSTKGI: 36,255,'4E0B4E009875',-,- OK AT+QSTKRSP=254 OK //Terminate STK session. +QSTKURC: 253 //URC indicates that the proactive session has ended. 2. Timeout response of STK session. AT+QSTKRSP=253,0,25 OK //Select menu item, ID is 25. +QSTKURC: 36 //Select item proactive command notification. AT+QSTKGI=36 //Get the selected item proactive command information. +QSTKGI: 36,0,9,'7CBE54C163A88350',-,-,-,-,- +QSTKGI: 36,1,'53057F574E078C61',-,- +QSTKGI: 36,2,'5E7D9ED851B77B118BDD',-,- +QSTKGI: 36,3,'59296C14988462A5',-,- +QSTKGI: 36,4,'65B095FB805A7126',-,- +QSTKGI: 36,5,'4F53575B5FEB8BAF',-,- +QSTKGI: 36,6,'4EB24EB25B9D8D1D',-,- +QSTKGI: 36,7,'65C56E38653B7565',-,- +QSTKGI: 36,8,'822A73ED67E58BE2',-,- +QSTKGI: 36,255,'4E0B4E009875',-,- EC200U&EG91xU_Series_STK_Application_Note 32 / 34 OK +QSTKURC: 255,36 +QSTKURC: 253 LTE Standard Module Series //Indicate the timeout response of STK session. //URC indicates that the proactive session has ended and entered into main menu (different (U)SIM cards may have different performances). 3.4. Disable STK Functionality After disabling the STK functionality, you should reboot the module. AT+QSTK=0 OK //Disable STK functionality. EC200U&EG91xU_Series_STK_Application_Note 33 / 34 LTE Standard Module Series 4 Appendix References Table 5: Related Document Document Name [1] Quectel_EC200U&EG91xU_Series_AT_Commands_Manual Table 6: Terms and Abbreviations Abbreviation ME TA MS DTE STK URC SMS RFU Description Mobile Equipment Terminal Adapter Mobile Station Data Terminal Equipment (U)SIM Application Toolkit Unsolicited Result Code Short Message Service Reserved for Future Use EC200U&EG91xU_Series_STK_Application_Note 34 / 34
283.24 KB
EC200x&EG800K&EG91xN&EG912Y &EG950A Series TCP/IP Application Note LTE Standard Module Series Version: 1.4 Date: 2023-10-30 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&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 1 / 58 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&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 2 / 58 LTE Standard Module Series About the Document Revision History Version Date 1.0 2020-07-24 1.1 2021-04-20 1.2 2022-03-02 1.3 2023-01-11 1.4 2023-10-30 Author Description Larson LI Larson LI Larson LI Larson LI Fawei ZHOU Initial 1. Added the applicable modules EC200N-CN and EC600N-CN. 2. Updated the valid value range of in AT+ QICSGP from 0 to 3 (Chapter 2.3.1). 3. Added AT Commands ( Chapter 2.3.15): ⚫ AT+QICFG='tcp/retranscfg' ⚫ AT+QICFG='send/buffersize' ⚫ AT+QICFG='send/auto' ⚫ AT+QICFG='recv/ignore' ⚫ AT+QICFG='formatcfg' ⚫ AT+QICFG='qisend/timeout' ⚫ AT+QICFG='close/mode' 1. Added the applicable modules EC200A series and EG915N-EU. 2. Added the AT+QICFG='TCP/SendMode' (Chapter 2.3.1). 1. Updated applicable modules: ⚫ Added EG912N-EN. ⚫ Updated EG915N-EU to EG915N series. ⚫ Deleted EC200T series. 2. Removed the AT+CREG? in the flow chart of using TCP/IP AT commands (Chapter 1.2). 3. Added the following AT commands (Chapter 2.3.1): ⚫ AT+QICFG='sendinfo' ⚫ AT+QICFG='pdp/retry'. 1. Added the following applicable modules: EC200N-LA, EG800K series and EG950A series. 2. Added AT+QICFG='wakeup/data' and URC +QIURC: EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 3 / 58 LTE Standard Module Series 'wakeup/data' (Chapter 2.3.1 & Chapter 2.4.6). 3. Added and in AT+QICFG='send/auto' (Chapter 2.3.1). 4. Added in AT+QICFG='recv/ignore' (Chapter 2.3.1). 5. Added two notes of AT+QICFG (Chapter 2.3.1). 6. Added an example of optional TCP configurations (Chapter 3.10). EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 4 / 58 LTE Standard Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 5 Table Index.................................................................................................................................................. 7 1 Introduction ......................................................................................................................................... 8 1.1. Applicable Modules ..................................................................................................................... 8 1.2. The Process of Using TCP/IP AT Commands ............................................................................ 8 1.3. Description of Data Access Modes........................................................................................... 10 2 TCP/IP AT Commands ...................................................................................................................... 12 2.1. AT Command Introduction ........................................................................................................ 12 2.1.1. Definitions...................................................................................................................... 12 2.1.2. AT Command Syntax .................................................................................................... 12 2.2. Declaration of AT Command Examples .................................................................................... 13 2.3. AT Commands........................................................................................................................... 13 2.3.1. AT+QICFG Configure Optional Parameters............................................................... 13 2.3.2. AT+QICSGP Configure Parameters of a TCP/IP Context ......................................... 22 2.3.3. AT+QIACT Activate a PDP Context ........................................................................... 24 2.3.4. AT+QIDEACT Deactivate a PDP Context .................................................................. 25 2.3.5. AT+QIOPEN Open a Socket Service ......................................................................... 25 2.3.6. AT+QICLOSE Close a Socket Service....................................................................... 27 2.3.7. AT+QISTATE Query Socket Service Status............................................................... 28 2.3.8. AT+QISEND Send Data ............................................................................................. 30 2.3.9. AT+QIRD Read the Received TCP/IP Data ............................................................... 33 2.3.10. AT+QISENDEX Send Hex String Data ...................................................................... 34 2.3.11. AT+QISWTMD Switch Data Access Mode................................................................. 35 2.3.12. AT+QPING Ping a Remote Server............................................................................. 36 2.3.13. AT+QNTP Synchronize Local Time with NTP Server ................................................ 38 2.3.14. AT+QIDNSCFG Configure Address of DNS Server .................................................. 39 2.3.15. AT+QIDNSGIP Get IP Address by Domain Name..................................................... 39 2.3.16. AT+QISDE Control Whether to Echo the Data for AT+QISEND................................ 40 2.3.17. AT+QIGETERROR Query the Error Code of the Last AT Command ........................ 41 2.4. Description of URCs ................................................................................................................. 42 2.4.1. +QIURC: 'closed' URC Indicating Connection Closed.............................................. 42 2.4.2. +QIURC: 'recv' URC Indicating Incoming Data......................................................... 42 2.4.3. +QIURC: 'incoming full' Indicate Incoming Connection Reaches the Limit .............. 43 2.4.4. +QIURC: 'incoming' Indicate Incoming Connection .................................................. 43 2.4.5. +QIURC: 'pdpdeact' Indicate PDP Deactivation ....................................................... 44 2.4.6. +QIURC: 'wakeup/data' Indicate Wake-up Packet Data Receive ............................ 44 3 Examples ........................................................................................................................................... 45 3.1. Configure and Activate a Context ............................................................................................. 45 3.1.1. Configure a Context ...................................................................................................... 45 EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 5 / 58 LTE Standard Module Series 3.1.2. Activate a Context ......................................................................................................... 45 3.1.3. Deactivate a Context..................................................................................................... 45 3.2. TCP Client Works in Buffer Access Mode ................................................................................ 45 3.2.1. Set up a TCP Client Connection and Enter Buffer Access Mode ................................. 45 3.2.2. Send Data in Buffer Access Mode ................................................................................ 46 3.2.3. Retrieve Data from Remote Server in Buffer Access Mode ......................................... 46 3.2.4. Close a Connection....................................................................................................... 47 3.3. TCP Client Works in Transparent Access Mode....................................................................... 47 3.3.1. Set up a TCP Client Connection and Enter Transparent Access Mode ....................... 47 3.3.2. Send Data in Transparent Access Mode ...................................................................... 47 3.3.3. Retrieve Data from Remote Server in Transparent Access Mode ............................... 47 3.3.4. Close a TCP Client........................................................................................................ 48 3.4. TCP Client Works in Direct Push Mode .................................................................................... 48 3.4.1. Set up a TCP Client Connection and Enter Direct Push Mode .................................... 48 3.4.2. Send Data in Direct Push Mode.................................................................................... 48 3.4.3. Retrieve Data from Remote Server in Direct Push Mode............................................. 49 3.4.4. Close a TCP Client........................................................................................................ 49 3.5. TCP Server Works in Buffer Access Mode ............................................................................... 49 3.5.1. Start a TCP Server ........................................................................................................ 49 3.5.2. Accept TCP Incoming Connection ................................................................................ 49 3.5.3. Retrieve Data from Incoming Connection..................................................................... 50 3.5.4. Close a TCP Server ...................................................................................................... 50 3.6. UDP Service.............................................................................................................................. 50 3.6.1. Start a UDP Service ...................................................................................................... 50 3.6.2. Send UDP Data to Remote Client................................................................................. 51 3.6.3. Receive Data from Remote Client ................................................................................ 51 3.6.4. Close a UDP Service .................................................................................................... 51 3.7. PING.......................................................................................................................................... 51 3.8. Synchronize Local Time ............................................................................................................ 52 3.9. Get Last Error Code .................................................................................................................. 52 3.10. Optional Configurations of TCP ................................................................................................ 53 4 Summary of Error Codes ................................................................................................................. 55 5 Appendix References ....................................................................................................................... 57 EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 6 / 58 LTE Standard Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 8 Table 2: Type of AT Commands ................................................................................................................. 12 Table 3: Summary of Error Codes.............................................................................................................. 55 Table 4: Related Document........................................................................................................................ 57 Table 5: Terms and Abbreviations .............................................................................................................. 57 EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 7 / 58 LTE Standard Module Series 1 Introduction Quectel LTE Standard EC200x family, EG800K series, EG91xN family, EG912Y-EU and EG950A series 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 costs. EC200x family, EG800K series, EG91xN family, EG912Y-EU and EG950A series modules provide socket services such as TCP client, UDP client, TCP server and UDP server. 1.1. Applicable Modules Table 1: Applicable Modules Module Family EC200x EG91xN - Module EC200A Series EC200N-LA EC200S Series EG800K Series EG912N-EN EG915N Series EG912Y-EU EG950A Series 1.2. The Process of Using TCP/IP AT Commands Via TCP/IP AT commands, the host can configure a PDP context, activate/deactivate the PDP context, start/close a socket service and send/receive data via the socket service. The following figure illustrates how to use TCP/IP AT commands. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 8 / 58 LTE Standard Module Series Recommended Power on/off: 1. Power off: Send AT+QPOWD command, and then cut off power after 12 s or more. 2. Power on: Keep power key as low for 2 s, 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 20 s. 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 60 s. Configure a PDP Context: 1. Configure APN, user name, password and auth type with AT+QICSGP. 2. Configure QoS settings with 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 status with AT+CPIN? In case of failure to identify (U)SIM card in 20 s, reboot the module. Identify (U)SIM card If it fails in getting the PS registration status, Query PS service in 60 s with 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 with AT+QICSGP/AT+CGQREQ/ AT+CGEQREQ/AT+CGQMIN/ AT+CGEQMIN Activate a PDP Context: 1. Activate the PDP context with AT+QIACT=. 2. Query IP address of the PDP context with 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 150 s. 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 40 s. Reboot the module if there is no response in 40 s. The PDP context is deactivated successfully Activate the PDP context with AT+QIACT= and AT+QIACT? 1. Reboot the module if there is no response in 150 s. 2. If failed to deactivate the PDP context for 3 times continuously, reboot the module. Failed to activate the PDP context Successfully activate PDP context Deactivate the PDP context with AT+QIDEACT= Open connection with AT+QIOPEN Open Connection: 1. If failed to get response of AT+QIOPEN in 150 s, 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. 1. Failed to open connection continuously for 5 times. +QIOPEN: , 2. There is no response in150 s. Send data with AT+QISEND= Get ACK in 90 s TCP Connection Maintenance and Detection: 1. Send data with AT+QISEND =[,]. It is recommended to periodically send a small data packet to the remote end to maintain and detect the TCP connection. 2. Query sending ACK with AT+QISEND=,0. If the package is still not acknowledged after two minutes (query every 5 seconds, 24 times in total), the TCP connection may be abnormal. Execute AT+QICLOSE to close the current connection, and then execute AT+QIOPEN to re-establish the TCP connection. Query sending ACK with AT+QISEND= ,0 Failed to get ACK in 90 s Close connection OK with AT+QICLOSE= Reboot the module if there is no response in 10 s. 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 60 s. 2. Reboot the module if the module has not got response of AT+QIACT in 150 s or response of AT+QICLOSE in 10 s and in 40 s. 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 Using TCP/IP AT Commands EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 9 / 58 LTE Standard Module Series 1.3. Description of Data Access Modes EC200x family, EG800K series, EG91xN family, EG912Y-EU and EG950A series modules support the following three kinds of data access modes: ⚫ Buffer access mode ⚫ Direct push mode ⚫ Transparent transmission mode When opening a socket service via AT+QIOPEN, the data access mode can be specified with . After a socket service is opened, the access mode can be switched with AT+QISWTMD. 1. In buffer access mode, data can be sent via AT+QISEND. If the module has received the data from the Internet, it will buffer them and report the URC: +QIURC: 'recv',. The host can retrieve the buffered data with AT+QIRD. 2. In direct push mode, data can be sent via AT+QISEND. If the module has received the data from the Internet, it will output them to COM port directly through the URC: +QIURC: 'recv',, or +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 exit the 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 s before and after inputting +++. b) Input only +++ within 1 s, and wait until OK is returned. Once OK is retuned, the module switches to buffer access mode. OR 2) Change MAIN_DTR from LOW to HIGH to make the module enter command mode. In this case, set AT&D1 (see document [1]) before the module enters transparent transmission mode. ⚫ Return to transparent access 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. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 10 / 58 LTE Standard Module Series OR 2) Execute ATO. After a connection exits from transparent transmission mode, executing ATO switches the data access mode back to transparent transmission mode. Once transparent transmission mode is entered successfully, CONNECT is returned. If no connection has entered transparent transmission mode, ATO returns NO CARRIER. NOTE 1. In buffer access mode, if the buffer is not empty, and the module receives data again, it does not report any new URC until all the received data have been retrieved with AT+QIRD from the buffer. 2. In transparent transmission mode, AT commands cannot be executed. If the socket connection is closed because of 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. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 11 / 58 LTE Standard Module Series 2 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 2: Type 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. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 12 / 58 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 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: 'dataformat',(list of supported s),(list of supported s) +QICFG: 'viewmode',(list of supported s) +QICFG: 'passiveclosed',(list of supported s) +QICFG: 'udp/readmode',(list of supported s) +QICFG: 'udp/sendmode',(list of supported s) +QICFG: 'tcp/keepalive',(list of supported s),(range of supported s),(range of supported s),(range of supported s) +QICFG: 'recvind',(list of supported s) +QICFG: 'tcp/retranscfg',(range of supported s),(range of supported s) +QICFG: 'tcp/accept',(list of supported s) +QICFG: 'send/buffersize',(range of supported s) +QICFG: 'send/auto',(range of supported s),(range of supported s),(data sent),(<range of supported s),(range of supported s) +QICFG: 'recv/ignore',(range of supported s),(Filtered data),(range of supported s) +QICFG: 'formatcfg',(range of supported s) +QICFG: 'qisend/timeout',(range of supported s) EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 13 / 58 LTE Standard Module Series +QICFG: 'close/mode',(range of supported s) +QICFG: 'sendinfo',(list of supported s) +QICFG: 'TCP/SendMode',(list of supported s) +QICFG: 'pdp/retry',(list of supported s),(list of supported s),(range of supported s),(range of supported s) +QICFG: 'wakeup/data',(range of supported s),< wakeup_data>,(range of supported s) OK Write Command Response Query or set the packet size for If the optional parameter is omitted, query the current setting: transparent transmission mode +QICFG: 'transpktsize', AT+QICFG='transpktsize'[,] OK If the optional parameter is specified, set the packet size for transparent transmission mode: OK Write Command Query or set the waiting time before automatically sending data in transparent transmission mode AT+QICFG='transwaittm'[,] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'transwaittm', OK If the optional parameter is specified, set the waiting time before automatically sending data in transparent transmission mode: OK Write Command Query or set the format of the data to be sent or received (only for nontransparent 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 If there is any error: EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 14 / 58 LTE Standard Module Series ERROR Write Command Query or set the output format of received data (only for nontransparent mode) AT+QICFG='viewmode'[,] 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 If there is any error: ERROR Write Command Response Enable or disable the passive close If the optional parameter is omitted, query the current setting: of TCP connection when the server +QICFG: 'passiveclosed', is closed AT+QICFG='passiveclosed'[,] If the optional parameter is specified, enable or disable the passive close of TCP connection: OK Write Command Query or set the mode when 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 read mode: OK Write Command Query or set the mode when sending UDP data AT+QICFG='udp/sendmode'[,< mode>] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'udp/sendmode', OK If the optional parameter is specified, set the UDP data sending EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 15 / 58 LTE Standard Module Series mode: OK Write Command Query or set whether to send TCP keep-alive information. AT+QICFG='tcp/keepalive'[,[,,,]] If there is any error: ERROR Response If the optional parameters are omitted, query the current configurations +QICFG: 'tcp/keepalive',[,,,] OK If the optional parameters are entered, set whether to send TCP keep-alive information: OK Write Command Enable or disable data length presence in URC reported after data reception in buffer mode AT+QICFG='recvind'[,] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'recvind', OK If the optional parameter is specified, enable or disable data length presence in URC reported: OK Write Command Query or set the number of retransmissions and retransmission interval 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 number of retransmissions and retransmission interval: OK If there is any error: ERROR EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 16 / 58 LTE Standard Module Series Write Command Query/enable or disable the automatic reception of the TCP connection from the client AT+QICFG='tcp/accept'[,] Response If the optional parameter is omitted, query the current setting: +QICFG: 'tcp/accept', OK 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: ERROR Write Command Response Query or set the maximum length of If the optional parameter is omitted, query the current setting: a single transmission data +QICFG: 'send/buffersize', AT+QICFG='send/buffersize'[,< buffer_size>] OK If the optional parameter is specified, set the maximum length of a single transmission data: OK Write Command Query or set to send heartbeat packet data periodically AT+QICFG='send/auto',[,[, ][,][,]] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'send/auto',,,,, OK If the optional parameter is specified, set to send heartbeat packet data periodically: OK Write Command Query or set to filter the specified data AT+QICFG='recv/ignore',[,][,] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'recv/ignore',[,][,] OK EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 17 / 58 LTE Standard Module Series If the optional parameter is specified, set to filter the specified data: OK Write Command Query or set the format of sending AT+QISEND to return > AT+QICFG='formatcfg'[,] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'formatcfg', OK If the optional parameter is specified, set the output format of >: OK Write Command Query or set the maximum response time for sending AT+QISEND 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 If the optional parameter is specified, set the timeout time after output >: OK Write Command Query or set up asynchronous disconnection of TCP connection AT+QICFG='close/mode'[,] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'close/mode', OK If the optional parameter is specified, set up asynchronous disconnection of TCP connection: OK Write Command Enable or disable displaying the return information of AT+QISEND or AT+QISENDEX in URC form If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'sendinfo', EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 18 / 58 LTE Standard Module Series AT+QICFG='sendinfo'[,] OK If the optional parameter is specified, enable or disable displaying the return information of AT+QISEND or AT+QISENDEX in URC form: OK Write Command Set the mode when sending SEND OK AT+QICFG='TCP/SendMode'[,] If there is any error: ERROR Response If the optional parameter is omitted, query the current setting: +QICFG: 'TCP/SendMode', OK If the optional parameter is specified, set the mode when sending SEND OK: OK If there is any error: ERROR Write Command Response Configure retry times and time of If the optional parameter is omitted, query the current setting: PDP activation and deactivation +QICFG: 'pdp/retry',,,,<retry AT+QICFG='pdp/retry', de>,[,,] OK If the optional parameter is specified, configure retry times and time of PDP activation and deactivation: OK Write Command Set wake-up packet data AT+QICFG='wakeup/data',[,[,]] If there is any error: ERROR Response If the optional parameter is omitted, and has not been configured before, query the current setting: +QICFG: 'wakeup/data',,,0 OK If the optional parameter is omitted, and has been configured, query the current setting: +QICFG: 'wakeup/data',,, OK If the optional parameter is specified, set wake-up packet data: OK If there is any error: ERROR 300 ms This command takes effect immediately. The configurations are not saved. Parameter Integer type. In transparent transmission mode, the max length of the data packet to be sent. Range: 1–1460. Default value: 1024. Unit: byte. Integer type. In transparent transmission mode, the waiting time before sending the data automatically, if the length of data to be sent is less than the specified value of . Range: 0–20. Default value: 2. Unit: 100 ms. Integer type. Format of the data to be sent. 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. 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. Enable or disable the passive close of TCP connection when the server is closed. 0 Disable 1 Enable Integer type. Mode when sending UDP data. 0 Disable block mode. 1 Enable stream mode. Integer type. Enable or disable sending of TCP keep-alive information. 0 Disable EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 20 / 58 LTE Standard Module Series 1 Enable Integer type. Indicates the cycle time of triggered keepalive. Range: 1–1800. Unit: s. Integer type. Indicates the interval of sending a packet in cycle time. Range: 25–100. Unit: s. Integer type. Packet transmission count in cycle time. Range: 3–10. Integer type. Enable or disable data length presence in URC reported after data reception in TCP/IP buffer mode. 0 Disable 1 Enable Integer type. Number of reconnections within cycle time. Range: 3–12. Integer type. Reconnect interval within cycle time. Range: 5–1000. Unit: ms. Integer type. 0 Disable auto accepting incoming TCP connection from the client. 1 Enable auto accepting incoming TCP connection from the client. Integer type. Maximum number of bytes sent at one time. Range: 1460–10240. Integer type. Socket service index. Range: 0–11. Integer type. Set the interval for sending heartbeat packets. Range: 20–86400. Unit: s. String type. Send the content of the heartbeat packet. String type. Filter data content. Integer type. Control > output format. 0 0D0A> 1 0D0A>0D0A Integer type. Send data timeout time. Range: 0–120. Unit: s. Integer type. Enable or disable asynchronous disconnection of TCP connection. 0 Disable 1 Enable Integer type. Enable or disable displaying the return information of AT+QISEND or AT+QISENDEX in URC form. 0 Disable 1 Enable Integer type. The return mode of SEND OK. 0 Return SEND OK immediately after sending data 1 Return SEND OK after receiving ACK from server 2 Return ,SEND OK after receiving ACK from server 3 Return +QIURC: SEND OK after receiving ACK from server 4 Return +QIURC: ,SEND OK after receiving ACK from server Integer type. Set the PDP activation or deactivation mode. 0 Deactivation mode 1 Activation mode EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 21 / 58 LTE Standard Module Series Integer type. Set the network type. 0 4G mode 1 2G mode Integer type. Number of retry times. Range: 2–4. Default value: 4. The actual number of activation or deactivation is equal to the value of + 1. Integer type. The maximum time for a single activation and deactivation. Unit: s. String type. Wake-up packet data. Integer type. The type of the input packet data. 0 Hexadecimal ASCII code (automatically converted to hexadecimal string) 1 Hexadecimal string 2 String Integer type. Retry times. Range: 0–10. NOTE 1. If =2, that is, the input data is a string type, the string data cannot contain special characters (such as ASCII special control characters and escape characters), otherwise should be configured to 0 or 1. 2. After the specified data is configured with AT+QICFG='wakeup/data', all other data sent by the server will be discarded, and the MCU will be notified to wake up only when the packet is awakened or the network is abnormal. 2.3.2. AT+QICSGP Configure Parameters of a TCP/IP Context This command configures the , , and other parameters of a TCP/IP context. The QoS settings can be configured with AT+CGQMIN, AT+CGEQMIN, AT+CGQREQ and AT+CGEQREQ. For more information about the AT commands, see document [1]. 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),(list of supp orted s) Write Command Query a specific context configuration AT+QICSGP= OK Response +QICSGP: ,,,, OK EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 22 / 58 LTE Standard Module Series Write Command Configure the context AT+QICSGP=[,,[,,)[,[,]]]] Response OK If there is any error: ERROR Maximum Response Time / Characteristic This command takes effect immediately. The configurations are not saved. 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 Integer type. To configure whether to enable saving of and over CDMA network. 0 Disable 1 Enable Example AT+QICSGP=1 +QICSGP: 1,'','','',0 //Query the configuration of context 1. OK AT+QICSGP=1,1,'UNINET','','',1 OK //Configure context 1. China Unicom APN: 'UNINET'. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 23 / 58 LTE Standard Module Series 2.3.3. AT+QIACT Activate a PDP Context Before activating a PDP context with AT+QIACT, the context should be configured with AT+QICSGP. After activation, the IP address can be queried with AT+QIACT?. Although the range of is 1–15, the module supports maximum three PDP contexts activated simultaneously. Depending on the network, it may take max.150 s to return OK or ERROR after executing AT+QIACT. Other AT commands can be executed only after the response is returned. AT+QIACT Activate a PDP Context Test Command AT+QIACT=? Response +QIACT: (range of supported s) Read command AT+QIACT? OK Response Return the list of the currently activated contexts and their IP addresses: +QIACT: 1,,[,] [..... +QIACT: 15,,[,]] Write Command Activate a specified PDP context AT+QIACT= Maximum Response Time Characteristic OK Response OK If there is any error: ERROR 150 s, determined by the network. / Parameter Integer type. Context ID. Range: 1–15. Integer type. Context state. 0 Deactivated 1 Activated Integer type. Protocol type. 1 IPv4 2 IPv6 EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 24 / 58 LTE Standard Module Series 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 max. 40 s to return OK or ERROR after executing AT+QIDEACT. Other AT commands can be executed only after the response is returned. AT+QIDEACT Deactivate a PDP Context Test Command AT+QIDEACT=? Response +QIDEACT: (range of supported s) Write Command AT+QIDEACT= OK Response OK Maximum Response Time Characteristic If there is any error: ERROR 40 s, determined by the network. / Parameter Integer type. Context ID. Range: 1–15. 2.3.5. AT+QIOPEN Open a Socket Service The 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 URC +QIOPEN indicates if the socket service has been opened successfully. 1. If is 'TCP LISTENER', the module works as TCP server. After accepting a new TCP connection, the module automatically specifies a and reports the URC +QIURC: 'incoming',,,,. The range of is 0–11. The type of this new incoming connection is 'TCP INCOMING' and the of 'TCP INCOMING' is the same as that of 'TCP LISTENER'. 2. If is 'UDP SERVICE', UDP data can be sent to or received from the remote IP via . EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 25 / 58 LTE Standard Module Series ⚫ Send data: execute AT+QISEND=,,,. ⚫ Receive data in direct push mode: the module reports the URC +QIURC: 'recv',,,,. ⚫ Receive data in buffer access mode: the module reports the URC +QIURC: 'recv',, and then the received data can be retrieved with AT+QIRD=. 3. It is suggested to wait for 150 s for +QIOPEN: , to be outputted after executing the Write Command. If the response cannot be received in 150 s, use AT+QICLOSE to close the socket. AT+QIOPEN Open a Socket Service Test Command AT+QIOPEN=? Response +QIOPEN: (range of supported s),(range of supported s),'TCP/UDP/TCP LISTENER/UDP SERVICE','/',(range of supported s),(range of supported s),(range of supported s) OK Write Command AT+QIOPEN=,,,'/',[,[,]] Response If the service is in transparent transmission mode (=2) and the service is opened successfully: CONNECT If there is any error: ERROR Error description can be got via AT+QIGETERROR. If the service is in buffer access mode (=0) or direct push mode (=1): OK Maximum Response Time Characteristic +QIOPEN: , is 0 when the service is opened successfully. In other cases, is not 0. 150 s, determined by the network. / Parameter Integer type. Context ID. Range: 1–15. Integer type. Socket service index. Range: 0–11. String type. Socket service type. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 26 / 58 LTE Standard Module Series '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 incoming TCP connections 'UDP SERVICE' Start a UDP service String type. If is 'TCP' or 'UDP', it indicates the IP address of remote server, such as 220.180.239.212. If is 'TCP LISTENER' or 'UDP SERVICE', enter 127.0.0.1. String type. Domain name address of the remote server. Integer type. Port number of the remote server. Range: 0–65535. If is 'TCP' or 'UDP', this parameter must be specified. Range: 1–65535. If is 'TCP LISTENER' or 'UDP SERVICE', specify this parameter as 0. Integer type. Local port number. Range: 0–65535. If is 'TCP LISTENER' or 'UDP SERVICE', this parameter must be specified. Range: 1–65535. If is 'TCP' or 'UDP', this parameter can be omitted and the default value is 0. The local port is assigned automatically if is 0. Otherwise, the local port is assigned as specified. Integer type. Data access mode of the socket service. 0 Buffer access mode 1 Direct push mode 2 Transparent transmission mode Integer type. Error codes of the operation. See Chapter 4 for more information. 2.3.6. AT+QICLOSE Close a Socket Service This command closes a specified socket service. Depending on the network, it will take max. 10 s (default value, can be modified by ) to return OK or ERROR after executing AT+QICLOSE. Other AT commands can be executed only after the response is returned. AT+QICLOSE Close a Socket Service Test Command AT+QICLOSE=? Response +QICLOSE: (range of supported s),(range of supported s) OK Write Command Response AT+QICLOSE=[,] OK If the command failed to close the socket service: EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 27 / 58 Maximum Response Time Characteristic LTE Standard Module Series ERROR 10 s by default, determined by the setting of . / 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: s. 2.3.7. AT+QISTATE Query Socket Service Status The command queries the socket service status. If the is 0, it returns the statuses of all existing socket services in the specified context. If the is 1, it will return 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 con nection status of a specified context AT+QISTATE=, Response Return the status of all existing connections in a specified context: +QISTATE: ,,,< remote_port>,,,,< serverID>,, […] Write Command If is 1, query the con nection status of a specified socket OK Response +QISTATE: ,,,< remote_port>,,,,< EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 28 / 58 LTE Standard Module Series service AT+QISTATE=, serverID>,, OK Maximum Response Time 300 ms Characteristic / 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 to incoming TCP connections 'TCP INCOMING' Start a TCP connection accepted by a TCP server 'UDP SERVICE' Start a UDP service String type. IP address. If ='TCP' or 'UDP', it is the IP address of 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 'UDP', it is the port of 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 =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 2 'Connected': client/incoming connection has been established 3 'Listening': server is listening 4 'Closing': connection is closing Integer type. Only valid when is 'TCP INCOMING'. represents the ID of the server that accepts the incoming TCP connection, and the value is the same as of the server’s 'TCP LISTENER'. Integer type. Data access mode. 0 Buffer access mode 1 Direct push mode 2 Transparent transmission mode EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 29 / 58 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 LTE Standard Module Series 2.3.8. AT+QISEND Send Data In buffer access mode (=0) or direct push mode (=1), the data can be sent with AT+QISEND. If the data have been sent to the module successfully, SEND OK is returned, otherwise SEND FAIL or ERROR is returned. ⚫ SEND FAIL indicates the sending buffer is full. In this case, resending of the data can be tried. ⚫ ERROR indicates an error in the sending data process. In this case, wait for some time before resending the data. Maximum length of data to be sent: 1460 bytes. ⚫ SEND OK means that the data have been sent to the peer, but it does not mean they have reached the server successfully. You can query whether the data have reached the server with AT+QISEND=,0. AT+QISEND Send Data Test Command AT+QISEND=? Response +QISEND: (range of supported s),(range of supported s) OK Write Command Send variable-length data when is 'TCP', 'UDP' or 'TCP INCOMING' AT+QISEND= Response > After the response >, input the data to be sent. Tap Ctrl + Z to send data, and tap Esc to cancel the operation. (1) If =0: 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, EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 30 / 58 LTE Standard Module Series or any parameter is incorrect: ERROR (2) If =1: If the connection has been established and the data is sent successfully: +QISEND: ,, OK If the connection has not been 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 to . (1) If =0: 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 (2) If =1: If the connection has been established: +QISEND: ,, OK If the connection has not been established, abnormally closed, or any parameter is incorrect: ERROR Write Command Response If is 'UDP SERVICE' Send fixed length data to a specified remote IP address and AT+QISEND=,<send_len remote port. The must be 'UDP SERVICE'. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 31 / 58 LTE Standard Module Series gth>,, > After the response >, input the data until the data length equals If the connection is established and the data are sent successfully: SEND OK If the connection is established but the sending buffer is full: SEND FAIL If the connection is not established, abnormally closed, or any parameter is incorrect: ERROR Write Command When is 0, query the sent data AT+QISEND=,0 Response If the specified connection exists: +QISEND: ,, OK Maximum Response Time Characteristic If the specified does not exist, or there is any other error: ERROR / / Parameter Integer type. Socket service index. Range: 0–11. Integer type. Enable or disable display AT+QISEND command execution information in URC form. 0 Disable 1 Enable Integer type. 0 Send data to the socket buffer successfully 1 The receiving buffer is full, send failed Integer type. Free space in the current buffer. Range: 0–10240. Unit: byte. Integer type. Length of data to be sent. Range: 0–1460. Unit: byte. String type. Remote IP address (must be dot format). Valid only when is 'UDP SERVICE'. Integer type. Remote port. Valid only when is 'UDP SEVERVICE'. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 32 / 58 LTE Standard Module Series 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 Read the Received TCP/IP Data In buffer access mode, after receiving data, the module will buffer it and report +QIURC: 'recv',, and then the data can be read by 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 the received data has been read via AT+QIRD from buffer. AT+QIRD Read the Received TCP/IP Data Test Command AT+QIRD=? Response +QIRD: (range of supported s),(range of supported s) OK Write Command When is 'TCP', 'UDP', 'TCP INCOMING' AT+QIRD=[,] Response If the specified connection has received the data, response: +QIRD: OK If there are no data: +QIRD: 0 OK If the connection does not exist: ERROR Write Command Response When is 'UDP If data exist: SERVICE' +QIRD: ,,<remote_port< AT+QIRD= CR> OK If there are no data: +QIRD: 0 OK EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 33 / 58 LTE Standard Module Series If the connection does not exist: ERROR Write Command When is 0, query the retrieved data length AT+QIRD=,0 Response If the specified connection exists: +QIRD: ,, OK Maximum Response Time Characteristic If there is any error: ERROR / / Parameter Integer type. Socket service index. Range: 0–11. Integer type. Maximum length of data to be read. Range: 0–1500. Unit: byte. Integer type. Length of actually retrieved data. Unit: byte. String type. Retrieved data. Unit: byte. String type. Remote IP address. Valid only when is 'UDP SERVICE'. Integer type. Remote port number. Valid only when is 'UDP SERVICE'. Integer type. Total length of the received data. Unit: byte. Integer type. Length of data that have 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 Response AT+QISENDEX=,< (1) If =0: hex_string> If the hex string is sent successfully: EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 34 / 58 Maximum Response Time Characteristic LTE Standard Module Series SEND OK If the sending buffer is full: SEND FAIL If the connection does not exist: ERROR (2) If =1: If the connection has been established: +QISENDEX: ,, OK If the connection has not been established, abnormally closed, or any parameter is incorrect: ERROR / / Parameter Integer type. Socket service index. Range: 0–11. String type. Hex string data. Max. length: 512 bytes. Integer type. Enable or disable display AT+QISEND command execution information in URC form. 0 Disable 1 Enable Integer type. 0 Send data to the socket buffer successfully 1 The receiving buffer is full, send failed Integer type. Free space in the current buffer. Range: 0–10240. Unit: byte. 2.3.11. AT+QISWTMD Switch Data Access Mode This command switches the data access modes between buffer access mode, direct push mode and transparent transmission mode. When a socket service is started, the data access mode can be specified via the of AT+QIOPEN. After opening a socket, the data access mode can be changed with AT+QISWTMD. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 35 / 58 LTE Standard Module Series AT+QISWTMD Switch Data Access Mode Test Command AT+QISWTMD=? Response +QISWTMD: (range of supported s),(range of supported s) OK Write Command AT+QISWTMD=, Response If data access mode is switched successfully and is 0 or 1: OK If data access mode is switched successfully and is 2, the module enters the intended data mode: CONNECT Maximum Response Time Characteristic If there is any error: ERROR / This command takes effect immediately. The configuration is not saved. 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 2.3.12. AT+QPING Ping a Remote Server This command tests the reachability of a host on an Internet protocol network. Before using the ping utility, the host should activate the context of the corresponding with AT+QIACT. The command returns the result within and the default value of is 4 s. AT+QPING Ping a Remote Server Test Command AT+QPING=? Response +QPING: (range of supported s),,(range of supported s),(range of supported s) EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 36 / 58 LTE Standard Module Series Write Command AT+QPING=,[,[,]] OK Response If a remote host is pinged successfully: OK +QPING: [,,,,] […] +QPING: [,,,,,,] Maximum Response Time Characteristic If there is any error: ERROR / / Parameter Integer type. Context ID. Range: 1–15. String type. Host address in string type. 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: s. Integer type. Maximum number of ping requests. Range: 1–10. Default value: 4. Integer type. Result of each ping request. 0 Received the ping response from the host. In this case, it is followed by ,,,,. Others See Chapter 4 for more information. String type. IP address of the remote server formatted as a dotted decimal IP. Integer type. The length of each sent ping request. Unit: byte. Integer type. The time wait for the response of the ping request. Unit: ms. Integer type. Time to live value of the response packet for the ping request. Integer type. The final result of the command. 0 It is finished normally. It is successful to activate the context and find the host. In this case, it is followed by ,,,,,,. Others Result codes. See Chapter 4 for more information. Integer type. Total number of sent ping requests. Integer type. Total number of the ping requests that have received responses. Integer type. Total number of timed out ping requests. Integer type. Minimum response time. Unit: ms. Integer type. Maximum response time. Unit: ms. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 37 / 58 LTE Standard Module Series Integer type. Average response time. Unit: ms. 2.3.13. 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 with AT+QIACT. Depending on the network, it will take max. 125 s 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: , OK Write command Response AT+QNTP=, If the local time is synchronized with NTP server successfully: [,[,]] OK +QNTP: , Maximum Response Time Characteristic If there is any error: ERROR 125 s, determined by the network. This command takes effect immediately. The configuration is not saved. Parameter Integer type. Context ID. Range: 1–15. String type. NTP server address. Integer type. NTP server port number. Range: 1–65535. Default value: 123. Integer type. Whether to automatically set synchronized time as local time. 0 Not set 1 Set Integer type. Error codes of the operation. See Chapter 4 for more information. String type. Time synchronized with NTP server. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 38 / 58 LTE Standard Module Series The format is 'YYYY/MM/DD,hh:mm:sszz'. Range of zz: -48–+56. 2.3.14. AT+QIDNSCFG Configure Address of DNS Server Before setting the DNS server address, the host must activate the context of corresponding with AT+QIACT. AT+QIDNSCFG Configure Address of DNS Server Test command AT+QIDNSCFG=? Response +QIDNSCFG: (range of supported s),, Write Command AT+QIDNSCFG=[,[,]] OK Response If the optional parameters are omitted, query the current DNS server addresses of a specified PDP context: +QIDNSCFG: ,, OK If any of the optional parameters is specified, configure the primary and secondary DNS server addresses of a specified PDP context: OK Maximum Response Time Characteristic If there is any error: ERROR / This command takes effect immediately. The configurations are not saved. Parameter Integer type. PDP context ID. Range: 1–15. String type. Primary DNS server address. String type. Secondary DNS server address. 2.3.15. 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 the corresponding with AT+QIACT. Depending on the network, it will return a result in max. 60 s. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 39 / 58 LTE Standard Module Series .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 Characteristic The result will be returned as URC. +QIURC: 'dnsgip',,, [..... +QIURC: 'dnsgip',] 60 s, determined by the network. / Parameter Integer type. Context ID. Range: 1–15. String type. Domain name. Integer type. Result code. See Chapter 4 for more information. Integer type. Number of IP addresses corresponding to the . Integer type. Time to live of the DNS. Unit: s. String type. IP address of . 2.3.16. AT+QISDE Control Whether to Echo the Data for AT+QISEND This command controls whether to echo the data for AT+QISEND. AT+QISDE Control Whether to Echo the Data for AT+QISEND Test command AT+QISDE=? Response +QISDE: (list of supported s) Read command AT+QISDE? OK Response +QISDE: OK EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 40 / 58 LTE Standard Module Series Write Command AT+QISDE= Maximum Response Time Characteristic Response OK If there is any error: ERROR 300 ms This command takes effect immediately. The configuration is not saved. Parameter Numeric type. Whether to echo the data for AT+QISEND. 0 Do not echo the data 1 Echo the data 2.3.17. AT+QIGETERROR Query the Error Code of the Last AT Command If ERROR is returned after TCP/IP commands are executed, the detailed information about a result code can be queried with AT+QIGETERROR. Please note that AT+QIGETERROR only returns the result code of the last TCP/IP AT command. AT+QIGETERROR Query the Error Code of the Last AT Command Test command AT+QIGETERROR=? Execution Command AT+QIGETERROR Response OK Response +QIGETERROR: , Maximum Response Time Characteristic OK 300 ms / Parameter Integer type. Error codes of the operation. See Chapter 4 for more information. A string parameter indicates the details of error information. See Chapter 4 for more information. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 41 / 58 LTE Standard Module Series 2.4. Description of URCs +QIURC: is used at the beginning of the URC of TCP/IP AT commands to be reported to the host. The URC contains the reports about incoming data, closed connection and incoming connection and etc. Actually, there is both before and after URC, but is intentionally not presented. 2.4.1. +QIURC: 'closed' URC Indicating Connection Closed When TCP socket service is closed by remote peer or due to a network error, the URC is outputted, and the status of socket service is 'closing' (=4). AT+QICLOSE= can be used to change the to initial. +QIURC: 'closed' URC Indicating Connection Closed +QIURC: 'closed', Socket service connection is closed. Parameter Integer type. Socket service index. Range: 0–11. 2.4.2. +QIURC: 'recv' URC Indicating 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 with AT+QIRD. In direct push mode, the received data are outputted to COM port directly. +QIURC: 'recv' URC Indicating Incoming Data +QIURC: 'recv', Indicates incoming data in buffer access mode. The host can retrieve data via AT+QIRD. +QIURC: 'recv',, is 'TCP', 'UDP' or 'TCP INCOMING'. +QIURC: 'recv',,,,<remote_ is 'UDP SERVICE'. port> EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 42 / 58 LTE Standard Module Series Parameter Integer type. Socket service index. Range: 0–11. Integer type. Length of actually received data. String type. Remote IP address. Integer type. Remote port number. Integer type. Received data. Unit: byte. NOTE If the buffer is not empty, and the module receives data again, it does not report a new URC until all the received data have been retrieved with AT+QIRD from the buffer. 2.4.3. +QIURC: 'incoming full' Indicate Incoming Connection Reaches the Limit If the incoming connection reaches the limit, or no socket system resources can be allocated, then the module reports +QIURC: 'incoming full' for the new incoming connection request. +QIURC: 'incoming full' Indicate Incoming Connection Reaches the Limit +QIURC: 'incoming full' Indicates that the number of incoming connections has reached the limit. 2.4.4. +QIURC: 'incoming' Indicate Incoming Connection If the is 'TCP LISTENER', when a remote client connects to this server, the host will automatically assign a free for the new connection. The range of is 0–11. In such a case, the module will report the URC. The of the new connection will be 'TCP INCOMING', and the will be buffer access mode. +QIURC: 'incoming' Indicate Incoming Connection +QIURC: 'incoming',,,< remoteIP>, When the new incoming connection is accepted by , the allocated , and will be informed by this URC. Parameter Integer type. Assign this socket service for the incoming connection, which is automatically specified by the module. Range: 0–11. Integer type. The incoming accepted by the server whose is 'TCP LISTENER' and listening socket ID is . String type. Remote IP address of the incoming . EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 43 / 58 LTE Standard Module Series Integer type. Remote port of the incoming . 2.4.5. +QIURC: 'pdpdeact' Indicate PDP Deactivation PDP context may be deactivated by the network. The module will report the URC to the host about PDP deactivation. In such a 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. 2.4.6. +QIURC: 'wakeup/data' Indicate Wake-up Packet Data Receive This URC is reported when the module receives the wake-up packet data sent by the server. +QIURC: 'wakeup/data' Indicate Wake-up Packet Data Receive +QIURC: 'wakeup/data', Wake-up data is sent by the server. Parameter Integer type. Context ID. Range: 1–11. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 44 / 58 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. China Unicom APN: 'UNINET'. 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. 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 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 the context with AT+QIACT first. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 45 / 58 LTE Standard Module Series OK +QIOPEN: 0,0 //TCP client connected successfully. It is suggested to wait for 150 s for the URC +QIOPEN: ,. If the URC cannot be received in 150 s, the host could use AT+QICLOSE to close the socket. AT+QISTATE=1,0 //Query the connection status of socket service 1. +QISTATE: 0,'TCP','220.180.239.212',8009,65514,2,1,0,0,'usbmodem' OK 3.2.2. Send Data in Buffer Access Mode AT+QISEND=0 > test1 SEND OK AT+QISEND=0,4 > test SEND OK AT+QISEND=0,0 +QISEND: 9,9,0 //Send variable-length data. //SEND OK does not mean the data has been sent to the server successfully. The host can query whether the data has reached the server via AT+QISEND=0,0. //Send fixed-length data and the data length is 4 bytes. //Query the length of sent 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 AT+QIRD=0,1500 +QIRD: 14 test1 //The received data when =0. //Read data, the maximum length of data to be retrieved is 1500 bytes. //The length of actually received data is 14 bytes. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 46 / 58 OK AT+QIRD=0,1500 +QIRD: 0 OK AT+QIRD=0,0 +QIRD: 14,14,0 OK LTE Standard Module Series //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. 3.3. TCP Client Works in Transparent Access Mode 3.3.1. Set up a TCP Client Connection and Enter Transparent Access 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 connected successfully. It is suggested to wait for 150 s for the URC CONNECT. If the URC cannot be received in 150 s, the host could use AT+QICLOSE to close the socket. 3.3.2. Send Data in Transparent Access Mode 3.3.3. Retrieve Data from Remote Server in Transparent Access Mode Test 1 //All data received from the Internet are outputted directly via COM port. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 47 / 58 3.3.4. Close a TCP Client AT+QICLOSE=0 OK LTE Standard Module Series //After using +++ to exit 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. 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 with 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 of is 0. +QISTATE: 0,'TCP','220.180.239.212',8009,65344,2,1,0,1,'usbmodem' OK 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 //Send variable-length data. //SEND OK does not mean the data have been received by the server successfully. Host can query whether the data have reached the server with AT+QISEND=0,0. //Send fixed length data and the data length is 5 bytes. //Query the lengths of sent, acknowledged and unacknowledged data. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 48 / 58 +QISEND: 10,10,0 OK LTE Standard Module Series //A total of 10 bytes of data have been sent, and all 10 bytes have been acknowledged. 3.4.3. Retrieve 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. 3.5. TCP Server Works in Buffer Access Mode 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. AT+QISTATE=0,1 //Query whether the connection status of is 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 //Accepted a new TCP connection. The is 'TCP incoming', and is 11. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 49 / 58 LTE Standard Module Series 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 TCP server listening. 3.6. UDP Service 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 if the connection status of is 1. +QISTATE: 2,'UDP SERVICE','10.7.157.1',0,3030,2,1,2,0,'usbmodem' EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 50 / 58 LTE Standard Module Series OK 3.6.2. Send UDP Data to Remote Client AT+QISEND=2,10,'10.7.89.10',6969 >1234567890 SEND OK //Send 10-byte long data to a remote client whose IP is 10.7.89.10 and the remote port is 6969. 3.6.3. Receive Data from Remote Client +QIURC: 'recv',2 AT+QIRD=2 +QIRD: 4,'10.7.76.34',7687 AAAA //Receive data from remote client. //Retrieve UDP data. One whole UDP packet will be outputted. There is no need to specify the read length. //The retrieved data length is 4. The remote IP address is 10.7.76.34 and remote port is 7687. OK AT+QIRD=2 +QIRD: 0 //Retrieve data. //No data in buffer. OK AT+QISEND=2,10,'10.7.76.34',7687 >1234567890 SEND OK //Send data to the remote client whose IP is 10.7.76.34 and remote port is 7687. 3.6.4. Close a UDP Service AT+QICLOSE=2 OK //Close the service. 3.7. PING AT+QPING=1,'www.baidu.com' //Ping www.baidu.com in context 1. Before pinging the destination IP address, the host should activate the context with EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 51 / 58 AT+QIACT. 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 LTE Standard Module Series 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 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 EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 52 / 58 LTE Standard Module Series 3.10. Optional Configurations of TCP //Set wake-up packet data. AT+QICFG='wakeup/data',1 +QICFG: 'wakeup/data',1,'',0 //Query the current setting. OK AT+QICFG='wakeup/data',1,'5155454377616b657570' //Set wake-up packet data. OK AT+QICFG='wakeup/data',1 //Query the current wake-up packet data. +QICFG: 'wakeup/data',1,'5155454377616b657570',0 OK AT+QICFG='wakeup/data',1,'' OK AT+QICFG='wakeup/data',1 +QICFG: 'wakeup/data',1,'',0 //Clear and disable wake-up feature. //Query the current setting after the wake-up feature is disabled. OK AT+QICFG='wakeup/data',1,'quec wakeup',2 OK //Configure wake-up packet data to string type //Query or set to send heartbeat packet data periodically. AT+QICFG='send/auto',0,30,'313233343536',0,0 //Configure heartbeat packet data to OK hexadecimal ASCII code AT+QICFG='send/auto',0 //Query the current setting. +QICFG: 'send/auto',0,30,'123456',0,0 OK AT+QICFG='send/auto',0,30,'hi quectel',2,0 OK AT+QICFG='send/auto',0 +QICFG: 'send/auto',0,30,'hi quectel',2,0 //Configure heartbeat packet data to string type. //Query the current setting. OK //Query or set to filter the specified data. AT+QICFG='recv/ignore',0,'313233343536',0 OK AT+QICFG='recv/ignore',0 +QICFG: 'recv/ignore',0,'123456',0 //Configure filtered data to hexadecimal ASCII code. //Query the current setting. OK EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 53 / 58 LTE Standard Module Series AT+QICFG='recv/ignore',0,'313233343536',1 OK AT+QICFG='recv/ignore',0 +QICFG: 'recv/ignore',0,'313233343536',1 OK //Configure filtered data to hexadecimal string. //Query the current setting. EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 54 / 58 LTE Standard Module Series 4 Summary of Error Codes If ERROR is returned after executing TCP/IP AT commands, the detailed information about errors can be queried with AT+QIGETERROR. Please note that AT+QIGETERROR just returns the result code of the last TCP/IP AT command. Table 3: Summary of Error Codes 0 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 Operate successfully Unknown error Operation blocked Invalid parameters Memory allocation failed 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 EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 55 / 58 LTE Standard Module Series 565 DNS parse failed 566 Socket connect failed 567 Connection reset 568 System busy 569 Operation timeout 570 PDP context deactivated 571 Cancel sending 572 Operation not allowed 573 APN not configured 574 Port busy EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 56 / 58 LTE Standard Module Series 5 Appendix References Table 4: Related Document Document Name [1] Quectel_EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_AT_Commands_Manual Table 5: Terms and Abbreviations Abbreviation 3GPP ACK APN ASCII CHAP CS DNS FIN ID IP NTP NV PAP PDP PPP Description 3rd Generation Partnership Project Acknowledgement Access Point Name American Standard Code for Information Interchange Challenge Handshake Authentication Protocol Circuit Switching Domain Name System Finish Mostly refers to Identifier in terms of software Internet Protocol Network Time Protocol Non-Volatile Password Authentication Protocol l Packet Data Protocol Point-to-Point Protocol EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 57 / 58 PS QoS TCP TCP/IP UART UDP URC USB (U)SIM UTC LTE Standard Module Series Packet Switching Quality of Service Transmission Control Protocol Transmission Control Protocol/Internet Protocol Universal Asynchronous Receiver& Transmitter User Datagram Protocol Unsolicited Result Code Universal Serial Bus (Universal) Subscriber Identity Module Coordinated Universal Time EC200x&EG800K&EG91xN&EG912Y&EG950A_Series_TCP/IP_Application_Note 58 / 58
579.26 KB
EC200x&EC600M&EG800K&EG810M& EG91xN&EG912Y&EG950A Series HTTP(S) Application Note LTE Standard Module Series Version: 1.5 Date: 2023-10-26 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&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 1 / 45 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&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 2 / 45 LTE Standard Module Series About the Document Revision History Version Date - 2020-10-30 1.0 2020-11-30 1.1 2021-04-13 Author Luffy LIU Luffy LIU Luffy LIU 1.2 2022-03-02 Larson LI 1.3 2022-08-05 Larson LI 1.4 2023-04-25 Larson LI 1.5 2023-10-26 Fawei ZHOU Description Creation of the document First official release Updated the examples (Chapter 3). 1. Added the applicable modules EC200A series and EG915N-EU. 2. Added AT+QHTTPCFG='reqheader/add' and AT+QHTTPCFG=''reqheader/remove' (Chapter 2.3.1). 3. Updated the description of of AT+QHTTPCFG='closed/ind' (Chapter 2.3.1). 1. Added applicable modules EG915N-LA and EG912N-EN. 2. Deleted applicable module EC200T series. 3. Added data types 'application/json' and 'image/jpeg' for the parameter (Chapter 2.3.1). Added the applicable module EG950A-EL. 1. Updated the applicable modules: ⚫ Added EC200N-LA, EC600M-EU, EG800K series and EG810M-EU. ⚫ Updated EG950A-EL to EG950A series. 2. Added a note that different models support HTTP(S) feature differently due to the flash size of the module (Chapter 1.1). EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 3 / 45 LTE Standard Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index .................................................................................................................................................. 6 1 Introduction ......................................................................................................................................... 7 1.1. Applicable Modules ................................................................................................................ 7 1.2. Using HTTP(S) AT Commands .............................................................................................. 8 1.3. Description of HTTP(S) Header ............................................................................................. 9 1.3.1. Customize HTTP(S) Request Header ............................................................................ 9 1.3.2. Output HTTP(S) Response Header ................................................................................ 9 1.4. Description of Data Mode....................................................................................................... 9 2 Description of HTTP(S) 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 AT Commands ............................................................................................... 12 2.3.1. AT+QHTTPCFG Configure Parameters for HTTP(S) Server .................................... 12 2.3.2. AT+QHTTPURL Set URL of HTTP(S) Server ............................................................ 16 2.3.3. AT+QHTTPGET Send GET Request to HTTP(S) Server .......................................... 17 2.3.4. AT+QHTTPGETEX Send GET Request to HTTP(S) Server to Get Data with Specified Range ............................................................................................................................ 19 2.3.5. AT+QHTTPPOST Send POST Request to HTTP(S) Server via UART/USB ............ 20 2.3.6. AT+QHTTPPOSTFILE Send POST Request to HTTP(S) Server via File................. 22 2.3.7. AT+QHTTPREAD Read Response from HTTP(S) Server via UART/USB ............... 23 2.3.8. AT+QHTTPREADFILE Read Response from HTTP(S) Server via File .................... 24 2.3.9. AT+QHTTPSTOP Cancel HTTP(S) Request ............................................................. 25 3 Examples ........................................................................................................................................... 26 3.1. Access HTTP Server ............................................................................................................ 26 3.1.1. Send HTTP GET Request and Read the Response .................................................... 26 3.1.2. Send HTTP POST Request and Read the Response .................................................. 28 3.1.2.1. HTTP POST Body Obtained from UART/USB ..................................................... 28 3.1.2.2. HTTP POST Body Obtained from File System .................................................... 29 3.2. Access HTTPS Server ......................................................................................................... 30 3.2.1. Send HTTPS GET Request and Read the Response.................................................. 30 3.2.2. Send HTTPS POST Request and Read the Response ............................................... 32 3.2.2.1. HTTPS POST Body Obtained from UART/USB .................................................. 32 3.2.2.2. HTTPS POST Body Obtained from File System.................................................. 35 4 Error Handling ................................................................................................................................... 38 4.1. Executing HTTP(S) AT Command Failure ........................................................................... 38 4.2. PDP Activation Failure.......................................................................................................... 38 EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 4 / 45 LTE Standard Module Series 4.3. DNS Parse Failure................................................................................................................ 39 4.4. Entering Data Mode Failure ................................................................................................. 39 4.5. Sending GET/POST Requests Failure................................................................................. 39 4.6. Reading Response Failure................................................................................................... 40 5 Summary of ERROR Codes ............................................................................................................. 41 6 Summary of HTTP(S) Response Codes ......................................................................................... 43 7 Appendix References ....................................................................................................................... 44 EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 5 / 45 LTE Standard Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 7 Table 2: Type of AT Commands ..................................................................................................................11 Table 3: Summary of Error Codes.............................................................................................................. 41 Table 4: Summary of HTTP(S) Response Codes ...................................................................................... 43 Table 5: Related Documents ...................................................................................................................... 44 Table 6: Terms and Abbreviations .............................................................................................................. 44 EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 6 / 45 LTE Standard Module Series 1 Introduction Quectel EC200x family, EC600M-EU, EG800K series, EG810M-EU, EG91xN family, EG912Y-EU and EG950A series modules support HTTP(S) applications by 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 AT commands defined for HTTP(S). 1.1. Applicable Modules Table 1: Applicable Modules Module Family EC200x EG91xN - Module EC200A Series EC200N-LA EC200S Series EC600M-EU EG800K Series EG810M-EU EG912N-EN EG915N Series EG912Y-EU EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 7 / 45 LTE Standard Module Series - EG950A Series NOTE Limited by the flash size of the module, different models of the modules support HTTP(S) feature differently. For more details, please contact Quectel Technical Support. 1.2. Using HTTP(S) AT Commands With TCP/IP AT commands you can configure a PDP context, activate/deactivate the PDP context, and query the context status. Whereas, with HTTP(S) AT commands you can send HTTP(S) GET/POST requests to the HTTP(S) server and read the HTTP(S) response from the HTTP(S) server. In general, the process is as follows: Step 1: Configure , , and other parameters of a PDP context with AT+QICSGP. See document [1] for more information. Step 2: Activate the PDP context with AT+QIACT. You can query the assigned IP address with AT+QIACT?. See document [1] for more information. Step 3: Configure the PDP context ID and SSL context ID with AT+QHTTPCFG. Step 4: Configure SSL context parameters with AT+QSSLCFG. For more information, see document [2]. Step 5: Set the HTTP(S) URL with AT+QHTTPURL. Step 6: Send an HTTP(S) request. You can use AT+QHTTPGET for sending an HTTP(S) GET request, while AT+QHTTPPOST or AT+QHTTPPOSTFILE can be used for sending an HTTP(S) POST request. Step 7: Read HTTP(S) response with AT+QHTTPREAD or AT+QHTTPREADFILE. Step 8: Deactivate the PDP context with AT+QIDEACT. For more information, see document [1]. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 8 / 45 LTE Standard Module Series 1.3. Description of HTTP(S) Header 1.3.1. Customize HTTP(S) Request Header HTTP(S) request header is filled by the module automatically. It can also be customized by configuring to 1 with AT+QHTTPCFG, and then by inputting the HTTP(S) request header according to the following requirements: ⚫ Apply HTTP(S) request header syntax. ⚫ The value of a URI in HTTP(S) request line and the 'Host:' header must be in line with the URL configured 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 Message=1111&Appleqty=2222&Orangeqty=3333&find=1 1.3.2. Output HTTP(S) Response Header HTTP(S) response header will not be outputted automatically. Outputting of the HTTP(S) response header can be enabled by configuring to 1 via AT+QHTTPCFG. The HTTP(S) response header will be outputted with the HTTP(S) response body after executing AT+QHTTPREAD or AT+QHTTPREADFILE. 1.4. Description of Data Mode The COM port of the above modules have two working modes: AT command mode and data mode. In AT command mode, the data inputted via the COM port are treated as AT commands, while they are treated as data in data mode. ⚫ Exit Data Mode Inputting +++ or pulling up the DTR pin can make the COM port exit data mode. To prevent the +++ from being misinterpreted as data, the following sequence should be followed: EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 9 / 45 LTE Standard Module Series 1) Do not input any character within 1 s before and after inputting +++. 2) Input +++ within 1 s, and do not input other characters during the time. If you are exiting the data mode by pulling the DTR pin up, make sure to set AT&D1 first. ⚫ Enter Data Mode To enter the data mode, execute AT+QHTTPURL, AT+QHTTPPOST and AT+QHTTPREAD. If you input +++ or pull the DTR pin 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. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 10 / 45 LTE Standard Module Series 2 Description of HTTP(S) AT Commands 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 2: Type 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. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 11 / 45 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 AT Commands 2.3.1. AT+QHTTPCFG Configure Parameters for HTTP(S) Server The command configures the parameters for HTTP(S) server, such as configuring a PDP context ID, customizing the HTTP(S) request header, outputting the HTTP(S) response header, and querying SSL settings. If the Write Command only executes one parameter, it will query 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: 'sslctxid',(range of supported s) +QHTTPCFG: 'contenttype',(range of supported s) +QHTTPCFG: 'rspout/auto',(list of supported s) +QHTTPCFG: 'closed/ind',(list of supported s) +QHTTPCFG: 'reqheader/add',, +QHTTPCFG: 'reqheader/remove', Read Command AT+QHTTPCFG? OK Response +QHTTPCFG: 'contextid', +QHTTPCFG: 'requestheader', +QHTTPCFG: 'responseheader', +QHTTPCFG: 'sslctxid', +QHTTPCFG: 'contenttype', +QHTTPCFG: 'rspout/auto', EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 12 / 45 LTE Standard Module Series +QHTTPCFG: 'closed/ind', +QHTTPCFG: 'reqheader/add',[,:,...] +QHTTPCFG: 'reqheader/remove',[,,...] Write Command AT+QHTTPCFG='contextid'[,] OK Response If the optional parameter is omitted, query the current settings: +QHTTPCFG: 'contextid', OK Write Command AT+QHTTPCFG='requestheader'[,< request_header>] If the optional parameter is specified, configure the PDP context ID: OK Or +CME ERROR: Response If the optional parameter is omitted, query the current settings: +QHTTPCFG: 'requestheader', OK Write Command AT+QHTTPCFG='responseheader'[ ,] If the optional parameter is specified, configure whether to enable customization of HTTP(S) request header: OK Or +CME ERROR: Response If the optional parameter is omitted, query the current settings: +QHTTPCFG: 'responseheader', OK Write Command AT+QHTTPCFG='sslctxid'[,] If the optional parameter is specified, configure whether to enable the outputting of the HTTP(S) response header: OK Or +CME ERROR: Response If the optional parameter is omitted, query the current settings: +QHTTPCFG: 'sslctxid', EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 13 / 45 LTE Standard Module Series OK Write Command AT+QHTTPCFG='contenttype'[,] If the optional parameter is specified, configure the SSL context ID used for HTTP(S): OK Or +CME ERROR: Response If the optional parameter is omitted, query the current settings: +QHTTPCFG: 'contenttype', OK Write Command AT+QHTTPCFG='rspout/auto'[,] If the optional parameter is specified, configure the data type of HTTP(S) body: OK Or +CME ERROR: Response If the optional parameter is omitted, query the current settings: +QHTTPCFG: 'rspout/auto', OK Write Command AT+QHTTPCFG='closed/ind'[,] If the optional parameter is specified, configure whether to enable auto output of HTTP(S) response: OK Or +CME ERROR: Response If the optional parameter is omitted, query the current settings: +QHTTPCFG: 'closed/ind', OK Write Command AT+QHTTPCFG='reqheader/add'[, [,]] If the optional parameter is specified, enable/disable the report of HTTP(S) session closing URC +QHTTPURC: 'closed': OK Or +CME ERROR: Response If all optional parameters are omitted, query the customized header(s) added: +QHTTPCFG: 'reqheader/add',[,:,...] OK If the optional parameter is omitted, query the attributes of : +QHTTPCFG: 'reqheader/add',: OK Or +CME ERROR: Write Command AT+QHTTPCFG='reqheader/remov e', Maximum Response Time Characteristics If the optional parameters are specified, set the customized header: OK Or +CME ERROR: Response OK Or +CME ERROR: 300 ms This command takes effect immediately. The configurations are not saved. Parameter Integer type. PDP context ID. Range: 1–15. Default value: 1. Integer type. Disable or enable customization of HTTP(S) request header. 0 Disable 1 Enable Integer type. Disable or enable output of HTTP(S) response header. 0 Disable 1 Enable Integer type. SSL context ID used for HTTP(S). Range: 0–5. Default value: 1. SSL parameters can be configured with AT+QSSLCFG. For more information, see document [2]. 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' EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 15 / 45 LTE Standard Module Series 4 'application/json' 5 'image/jpeg' Integer type. Disable or enable auto output of HTTP(S) response data. If auto outputting of HTTP(S) response data is enabled, then AT+QHTTPREAD and AT+QHTTPREADFILE execution will fail. 0 Disable 1 Enable Integer type. Disable or enable the report of HTTP(S) session closing URC +QHTTPURC: 'closed'. 0 Disable 1 Enable String type. Customized header. String type. Content of customized header. Integer type. Number of added customized headers. Default value: 0. Error code. See Chapter 5 for more information. 2.3.2. AT+QHTTPURL Set URL of HTTP(S) Server This command sets the URL of an HTTP(S) server. The 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: CONNECT TA switches to transparent transmission mode, and then the URL can be inputted. When the total size of the inputted data reaches , TA will return to command mode and report the following code: OK If has been reached, but the received URL length EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 16 / 45 LTE Standard Module Series Maximum Response Time Characteristics is less than , TA will return to command mode and report the following code: +CME ERROR: b) If the parameter format is incorrect or other errors occur: +CME ERROR: Determined by This command takes effect immediately. The configurations are not saved. Parameter Integer type. URL length. Range: 1–2048. Unit: byte. Integer type. Maximum time for inputting URL. Range: 1–65535. Default value: 60. Unit: second. String type. HTTP(S) server URL. Error code. See Chapter 5 for more information. 2.3.3. AT+QHTTPGET Send GET Request to HTTP(S) Server This command sends an HTTP(S) GET request. According to the configured in AT+QHTTPCFG='requestheader'[, ], AT+QHTTPGET has two different formats. If is set to 1, after sending AT+QHTTPGET, CONNECT is outputted within 125 s to indicate successful establishment of the connection. If that is not the case, then +CME ERROR: will be returned. It is recommended to wait for a specific period of time () for +QHTTPGET: [,[,]] to be outputted after OK is returned. In +QHTTPGET: [,[,]], the can only be reported when is 0. If HTTP(S) response header contains CONTENT-LENGTH information, then will be reported. AT+QHTTPGET Send GET Request to HTTP(S) Server Test Command AT+QHTTPGET=? Response +QHTTPGET: (range of supported s),(range of supported s),(range of supported s) Write Command If equals 0 (disable customizing HTTP(S) request header) OK Response a) If the parameter format is correct and no other errors occur: OK EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 17 / 45 LTE Standard Module Series AT+QHTTPGET[=] When the module has received a response from HTTP(S) server, it will report the following URC: +QHTTPGET: [,[,]] Write Command If equals 1 (enable customizing HTTP(S) GET request header) AT+QHTTPGET=,[,] b) If the parameter format is incorrect or other errors occur: +CME ERROR: Response a) If the connection to the HTTP(S) server has been established successfully: CONNECT TA switches to transparent transmission mode, and then the HTTP(S) GET request header can be inputted. When the total size of the inputted data reaches , TA will return to command mode and report the following code: OK When the module has received a response from HTTP(S) server, it will report the following URC: +QHTTPGET: [,[,]] If the has been reached, but the received data length is less than , TA will return to command mode and report the following code: +QHTTPGET: Maximum Response Time Characteristics b) If the parameter format is incorrect or other errors occur: +CME ERROR: Determined by / Parameter Integer type. Timeout value for the HTTP(S) GET response +QHTTPGET: [,[,]] to be outputted after OK is returned. Range: 1–65535. Default value: 60. Unit: second. Integer type. Length of HTTP(S) request, including HTTP(S) request header and HTTP(S) request body. Range: 1–2048. Unit: byte. Integer type. Maximum time for inputting HTTP(S) request including HTTP(S) request header and HTTP(S) request body. Range: 1–65535. Default value: 60. Unit: second. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 18 / 45 LTE Standard Module Series Integer type. HTTP(S) server response code. See Chapter 6 for more information. Integer type. Disable or enable customizing HTTP(S) request header. 0 Disable 1 Enable Integer type. Length of HTTP(S) response body. Unit: byte. Error code. See Chapter 5 for more information. 2.3.4. AT+QHTTPGETEX Send GET Request to HTTP(S) Server to Get Data with Specified Range This command sends an HTTP(S) GET request to the HTTP(S) server to get data within a specified range. MCU can get data from the HTTP(S) server, whose position and length have been specified with AT+QHTTPGETEX, and this command is only executable if AT+QHTTPCFG='requestheader',0. After that, HTTP(S) server will always respond with 206 code to the GET request to get data with specified position and length. AT+QHTTPGETEX Range Test Command AT+QHTTPGETEX=? Send GET Request to HTTP(S) Server to Get Data with Specified Response +QHTTPGET: (range of supported s),(range of supported s,(range of supported s) Write Command AT+QHTTPGETEX=,, OK Response a) If the parameter format is correct and no other errors occur: OK When the module has received response from HTTP(S) server, it will report the following URC: +QHTTPGET: [,[,]] Maximum Response Time Characteristics b) If the parameter format is incorrect or other errors occur: +CME ERROR: Determined by / Parameter Integer type. Timeout value for the HTTP(S) GET response +QHTTPGET: [,[,]] to be outputted after OK is returned. Range: 1–65535. Default value: 60. Unit: second. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 19 / 45 LTE Standard Module Series Integer type. Start position of the data that the HTTP(S) client wants to get. Integer type. Length of the data that the HTTP(S) client wants to get. Integer type. HTTP(S) server response code. See Chapter 6 for more information. Integer type. Length of HTTP(S) response body. Unit: byte. Error code. See Chapter 5 for more information. 2.3.5. AT+QHTTPPOST Send POST Request to HTTP(S) Server via UART/USB The command sends an HTTP(S) POST request. According to the configured in AT+QHTTPCFG='requestheader'[,], AT+QHTTPPOST has two different formats. ⚫ If is set to 0, only HTTP(S) POST body should be inputted via UART/USB port. ⚫ If is set to 1, both the HTTP(S) POST header and body should be inputted via UART/USB port. After sending AT+QHTTPPOST, CONNECT is outputted within 125 s to indicate successful establishment of the connection. If that is not the case, +CME ERROR: will be returned. It is recommended to wait for a specific period of time (refer to the maximum response time below) for +QHTTPPOST: [,[,]] to be outputted after OK is returned. 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) Write Command If equals 0 (disable customizing HTTP(S) request header) AT+QHTTPPOST=[,,] OK Response a) If the parameter format is correct, the connection to HTTP(S) server has been established successfully, and the HTTP(S) request header has been sent: CONNECT TA switches to transparent transmission mode, and then the HTTP(S) POST body can be inputted. When the total size of the inputted data reaches , TA will return to command mode and report the following code: OK When the module has received a response from HTTP(S) server, it will report the following URC: +QHTTPPOST: [,[,]] EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 20 / 45 LTE Standard Module Series If has been reached, but the received data length is less than , TA will return to command mode and report the following code: +QHTTPPOST: Write Command If equals 1 (enable customizing HTTP(S) request header) AT+QHTTPPOST=[,,] b) If the parameter format is incorrect or other errors occur: +CME ERROR: Response a) If the parameter format is correct and the connection to HTTP(S) server has been established successfully: CONNECT TA switches to the transparent transmission mode, and then the HTTP(S) POST header and body can be inputted. When the total size of the inputted data reaches , TA will return to command mode and report the following code: OK When the module has received a response from HTTP(S) server, it will report the following URC: +QHTTPPOST: [,[,]] If the has reached, but the received data length is less than , TA will return to command mode and report the following code: +QHTTPPOST: Maximum Response Time Characteristics b) If the parameter format is incorrect or other errors occur: +CME 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, including HTTP(S) POST request header and body. Range: 1–1024000. Unit: byte. Integer type. Maximum time for inputting HTTP(S) POST body or HTTP(S) POST request. Range: 1–65535. Default value: 60. Unit: second. Integer type. Timeout value for the HTTP(S) POST response +QHTTPPOST: EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 21 / 45 LTE Standard Module Series [,[,]] to be outputted after OK is returned. Range: 1–65535. Default value: 60. Unit: second. Integer type. HTTP(S) server response code. See Chapter 6 for more information. Integer type. Disable or enable customizing HTTP(S) request header. 0 Disable 1 Enable Integer type. Length of HTTP(S) response body. Unit: byte. Error code. See Chapter 5 for more information. 2.3.6. AT+QHTTPPOSTFILE Send POST Request to HTTP(S) Server via File The command sends an HTTP(S) POST request via a file. According to the in AT+QHTTPCFG='requestheader'[,], the file operated with AT+QHTTPPOSTFILE has two different formats. ⚫ If is set to 0, the file in file system will be HTTP(S) POST body only. ⚫ If is set to 1, the file in file system will be HTTP(S) POST header and body. After executing AT+QHTTPPOSTFILE the module will report +QHTTPPOSTFILE: [,[,]] to indicate the execution result. The can only be reported when equals 0. It is recommended to wait for a specific period of time (refer to the maximum response time below) for +QHTTPPOSTFILE: [,[,]] to be outputted after OK is returned. AT+QHTTPPOSTFILE Send POST Request to HTTP(S) Server via File Test Command AT+QHTTPPOSTFILE=? Response +QHTTPPOSTFILE: ,(range of supported s)[,(range of supported s)] Write Command If equals 1, the specified file must contain both HTTP(S) request header and body. AT+QHTTPPOSTFILE=[,< rsptime>,] OK Response a) If parameter format is correct and the connection to HTTP(S) server has been established successfully: OK When the module has received a response from HTTP(S) server, it will report the following URC: +QHTTPPOSTFILE: [,[,]] b) If parameter format is incorrect or other errors occur: EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 22 / 45 Maximum Response Time Characteristics LTE Standard Module Series +CME ERROR: Determined by / Parameter String type. File name. Max. file name length: 80 bytes. Integer type. Timeout value for the HTTP(S) POST response +QHTTPPOSTFILE: [,[,]] to be outputted after OK is returned. Range: 1–65535. Default value: 60. Unit: second. Integer type. HTTP(S) server response code. See Chapter 6 for more information. Integer type. Disable or enable customizing HTTP(S) request header. 0 Disable 1 Enable Integer type. Length of HTTP(S) response body. Unit: byte. String type. HTTP(S) sending files in segments. 0 Send the current file directly 1 Record the file name to be sent (do not send the file for now, wait to send it together with the file configured when =2 2 Send the files configured when =1 and 2 in order (only sending two files together is supported) Error code. See Chapter 5 for more information. 2.3.7. AT+QHTTPREAD Read Response from HTTP(S) Server via UART/USB This command retrieves the HTTP(S) response from an HTTP(S) server via the UART/USB port, after sending HTTP(S) GET/POST requests. AT+QHTTPREAD must be executed after +QHTTPG ET: [,[,]], +QHTTPPOST: [,[,]] or +QHTTPPOSTFILE: [,[,]] is received. AT+QHTTPREAD Read Response from HTTP(S) Server via UART/USB Test Command AT+QHTTPREAD=? Response +QHTTPREAD: (range of s) supported Write Command AT+QHTTPREAD[=] OK Response a) If the parameter format is correct and the HTTP(S) response is read successfully: EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 23 / 45 Maximum Response Time Characteristics LTE Standard Module Series CONNECT OK If is reached or other errors occur, but the HTTP(S) response has not been outputted completely, it will report the following code: +QHTTPREAD: b) If the parameter format is incorrect or other errors occur: +CME ERROR: Determined by / Parameter Integer type. Max interval between receiving two data packets. Range: 1–65535. Default value: 60. Unit: second. Error code. See Chapter 5 for more information. 2.3.8. AT+QHTTPREADFILE Read Response from HTTP(S) Server via File This command retrieves the HTTP(S) response from HTTP(S) server via file after sending HTTP (S) GET/POST requests. AT+QHTTPREADFILE must be executed after +QHTTPGET: [,[,]], +QHTTPPOST: [,[,]] or +Q HTTPPOSTFILE: [,[,]] is received. AT+QHTTPREADFILE Read Response from HTTP(S) Server via File Test Command AT+QHTTPREADFILE=? Response +QHTTPREADFILE: ,(range of supported s) Write Command AT+QHTTPREADFILE=[, ] OK Response a) If the parameter format is correct: OK When response from the HTTP(S) server is read or is reached, it will report: +QHTTPREADFILE: b) If the parameter format is incorrect or other errors occur: EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 24 / 45 Maximum Response Time Characteristics LTE Standard Module Series +CME ERROR: Determined by / Parameter Integer type. Max time between receiving two data packets. Range: 1–65535. Default value: 60. Unit: second. String type. File name. Maximum length of file name: 80 bytes. Error code. See Chapter 5 for more information. 2.3.9. AT+QHTTPSTOP Cancel HTTP(S) Request MCU can cancel HTTP(S) GET/POST request, and disconnect session with HTTP(S) server via this command. AT+QHTTPSTOP Cancel HTTP(S) Request Test Command AT+QHTTPSTOP=? Execution Command AT+QHTTPSTOP Response OK Response a) If the parameter format is correct and no other errors occur: OK Maximum Response Time Characteristics b) If the parameter format is incorrect or other errors occur: +CME ERROR: 10 s / Parameter Error code. See Chapter 5 for more information. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 25 / 45 LTE Standard Module Series 3 Examples 3.1. Access HTTP Server 3.1.1. Send HTTP GET Request and Read the Response The following examples show how to send an HTTP GET request and enable output of HTTP response header, as well as how to read an HTTP GET response. //Example of how to send an HTTP GET request. AT+QHTTPCFG='contextid',1 //Configure the PDP context ID as 1. OK AT+QHTTPCFG='responseheader',1 //Allow the output of HTTP response header. OK AT+QIACT? OK //Query the state of context. //No context activated currently. AT+QICSGP=1,1,'UNINET','','',1 OK //Configure PDP context 1. China Unicom APN: UNINET. (Then set AT+CFUN=1,1 to make the configuration take effect.) AT+QIACT? +QIACT: 1,1,1,'10.7.157.1' //Query the state of context. OK //The first PDP is activated by default. If it is queried inactivated, use AT+QIACT=1 to activate it. AT+QIACT=1 //Activate context 1. OK //Activated successfully. AT+QHTTPURL=23,80 CONNECT HTTP://www.sina.com.cn/ OK AT+QHTTPGET=80 //Set the URL of the HTTP server that will be accessed and timeout value as 80 s. //Input URL whose length is 23 bytes. (This URL is only an example. Input the correct URL in a practical test.) //Send HTTP GET request with the maximum response time of EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 26 / 45 LTE Standard Module Series 80 s. OK +QHTTPGET: 0,200,601710 //If HTTP response header contains CONTENT-LENGTH information, then the (601710) is reported. //Example of how to read an HTTP response. //Solution 1: Read the HTTP response and output it via the UART port. AT+QHTTPREAD=80 //Read HTTP response and output it via UART. The maximum time to wait for an HTTP session to be closed is 80 s. CONNECT HTTP/1.1 200 OK //HTTP response header and body. Server: nginx Date: Tue, 12 Sep 2017 05:57:29 GMT Content-Type: text/html Content-Length: 601710 Connection: close Last-Modified: Tue, 12 Sep 2017 05:54:48 GMT Vary: Accept-Encoding Expires: Tue, 12 Sep 2017 05:58:28 GMT Cache-Control: max-age=60 X-Powered-By: shci_v1.03 Age: 1 …… //Response is omitted here. OK +QHTTPREAD: 0 // HTTP response header and body have been read successfully. //Solution 2: Read HTTP response and store it to a UFS file. AT+QHTTPREADFILE='UFS:1.txt',80 OK //Read HTTP response header and body and store them to UFS:1.txt. The maximum time to wait for HTTP session to be closed is 80 s. +QHTTPREADFILE: 0 //HTTP response header and body have been stored successfully. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 27 / 45 LTE Standard Module Series 3.1.2. Send HTTP POST Request and Read the Response 3.1.2.1. HTTP POST Body Obtained from UART/USB The following examples show how to send an HTTP POST request and retrieve the HTTP POST body via UART port, as well as how to read the HTTP POST response. AT+QHTTPCFG='contextid',1 OK //Configure the PDP context ID as 1. AT+QIACT? //Query the state of context. OK //No context activated currently. AT+QICSGP=1,1,'UNINET','','',1 OK //Configure PDP context 1. China Unicom APN: UNINET. (Then set AT+CFUN=1,1 to make the configuration take effect.) AT+QIACT? +QIACT: 1,1,1,'172.22.86.226' //Query the state of context. OK //The first PDP is activated by default. If it is queried inactivated, use AT+QIACT=1 to activate it. AT+QIACT=1 //Activate context 1. OK //Activated successfully. AT+QHTTPURL=59,80 //Set the URL of the HTTP server that will be accessed and timeout value as 80 s. CONNECT http://api.efxnow.com/DEMOWebServices2.8/Service.asmx/Echo? //Input URL whose length is 59 bytes. (This URL is only an example. Input the correct URL in a practical test.) OK AT+QHTTPPOST=20,80,80 CONNECT Message=HelloQuectel OK //Send HTTP POST request and HTTP POST body is obtained via UART. The maximum input time and the maximum response time are 80 s each. //Input HTTP POST body whose length is 20 bytes. (The POST body is only an example. Input the correct POST body in a practical test.) EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 28 / 45 LTE Standard Module Series +QHTTPPOST: 0,200,177 //If the HTTP response header contains CONTENT-LENGTH information, then the (177) will be reported. AT+QHTTPREAD=80 //Read the HTTP response body and output it via UART. The maximum time to wait for HTTP session to be closed is 80 s. CONNECT Message='HelloQuectel' ASCII:72 101 108 108 111 81 117 101 99 116 101 108 //Output HTTP response body. OK +QHTTPREAD: 0 //HTTP response body has been outputted successfully. 3.1.2.2. HTTP POST Body Obtained from File System The following examples show how to send an HTTP POST request and retrieve the POST body via file system, as well as how to store an HTTP POST response to file system. AT+QHTTPCFG='contextid',1 OK //Configure the PDP context ID as 1. AT+QIACT? OK //Query the state of context. //No context activated currently. AT+QICSGP=1,1,'UNINET','','',1 //Configure PDP context 1. China Unicom APN: UNINET. (Then set AT+CFUN=1,1 to make the configuration take effect.) OK AT+QIACT? +QIACT: 1,1,1,'172.22.86.226' //Query the state of context. OK //The first PDP is activated by default. If it is queried inactivated, use AT+QIACT=1 to activate it. AT+QIACT=1 //Activate context 1. OK //Activated successfully. AT+QHTTPURL=59,80 //Set the URL the HTTP server that will be accessed and timeout value as 80 s. CONNECT http://api.efxnow.com/DEMOWebServices2.8/Service.asmx/Echo? //Input URL whose length is 59 bytes. (This URL is only an example. Input the correct URL in practical test.) OK EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 29 / 45 LTE Standard Module Series //POST the request information from a UFS file, and read HTTP response and store it to a UFS file. AT+QHTTPPOSTFILE='UFS:2.txt',80 OK //Send HTTP(S) POST request. POST body is obtained from UFS:2.txt. The maximum response time is 80 s. +QHTTPPOSTFILE: 0,200,177 //After HTTP POST request is sent successfully, the HTTP response body can be read by executing AT+QHTTPREAD or AT+QHTTPREADFILE. AT+QHTTPREADFILE='UFS:3.txt',80 OK //Read HTTP response body and store it to UFS:3.txt. The maximum time to wait for HTTP session to be closed is 80 s. +QHTTPREADFILE: 0 //HTTP response body has been stored successfully. 3.2. Access HTTPS Server 3.2.1. Send HTTPS GET Request and Read the Response The following examples show how to send an HTTPS GET request and enable output of the HTTPS response header, as well as how to read an HTTPS GET response. //Example of how to send an HTTPS GET request. AT+QHTTPCFG='contextid',1 //Configure the PDP context ID as 1. OK AT+QHTTPCFG='responseheader',1 OK //Allow the output of HTTPS response header. AT+QIACT? OK //Query the state of context. AT+QICSGP=1,1,'UNINET','','',1 OK //Configure PDP context 1. China Unicom APN: UNINET (Then set AT+CFUN=1,1 to make the configuration take effect.) AT+QIACT? +QIACT: 1,1,1,'10.7.157.1' //Query the state of context. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 30 / 45 LTE Standard Module Series OK //The first PDP is activated by default. If it is queried inactivated, use AT+QIACT=1 to activate it. AT+QIACT=1 OK //Activate context 1. //Activated successfully. AT+QHTTPCFG='sslctxid',1 OK //Set SSL context ID as 1. AT+QSSLCFG='sslversion',1,1 OK //Set SSL version as 1, which means TLSV1.0. AT+QSSLCFG='ciphersuite',1,0x0005 OK //Set SSL cipher suite as 0x0005, which means RC4-SHA. AT+QSSLCFG='seclevel',1,0 OK //Set SSL verification level as 0, which means that a CA certificate is not needed. AT+QHTTPURL=22,80 CONNECT https://www.alipay.com OK //Set the URL of the HTTPS server that will be accessed and timeout value as 80 s. //Input a URL whose length is 22 bytes. (This URL is only an example. Input the correct URL in a practical test.) AT+QHTTPGET=80 OK //Send HTTPS GET request with the maximum response time of 80 s. +QHTTPGET: 0,200,21472 //If the HTTPS response header contains CONTENTLENGTH information, the (21472) will be reported. //Example of how to read an HTTPS response. //Solution 1: Read HTTPS response and output it via UART. AT+QHTTPREAD=80 //Read HTTPS response and output it via UART. The maximum time to wait for HTTPS session to be closed is 80 s. CONNECT //HTTPS response header and body. HTTP/1.1 200 OK Server: Tengine/2.1.0 Date: Tue, 12 Sep 2017 05:54:34 GMT EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 31 / 45 LTE Standard Module Series Content-Type: text/html; charset=utf-8 Content-Length: 21451 Connection: keep-alive …… //Response is omitted here. OK +QHTTPREAD: 0 // HTTPS response header and body have been read successfully. //Solution 2: Read HTTPS response and store it to UFS file. AT+QHTTPREADFILE='UFS:4.txt',80 OK //Read HTTPS response header and body and store them to UFS:4.txt. The maximum time to wait for an HTTPS session to be closed is 80 s. +QHTTPREADFILE: 0 //HTTPS response header and body have been stored successfully. 3.2.2. Send HTTPS POST Request and Read the Response 3.2.2.1. HTTPS POST Body Obtained from UART/USB The following examples show how to send an HTTPS POST request and retrieve the POST body via UART port, as well as how to read the HTTPS POST response. AT+QHTTPCFG='contextid',1 OK //Configure the PDP context ID as 1. AT+QIACT? OK //Query the state of context. //No context activated currently. AT+QICSGP=1,1,'UNINET','','',1 OK //Configure PDP context 1. China Unicom APN: UNINET (Then set AT+CFUN=1,1 to make the configuration take effect.) AT+QIACT? +QIACT: 1,1,1,'172.22.86.226' //Query the state of context. OK //The first PDP is activated by default. If it is queried inactivated, use AT+QIACT=1 to activate it. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 32 / 45 LTE Standard Module Series AT+QIACT=1 OK //Activate context 1. //Activated successfully. AT+QHTTPCFG='sslctxid',1 OK //Set SSL context ID as 1. AT+QSSLCFG='sslversion',1,1 OK //Set SSL version as 1, which means TLSV1.0. AT+QSSLCFG='ciphersuite',1,0x0005 OK //Set SSL cipher suite as 0x0005, which means RC4-SHA. AT+QSSLCFG='seclevel',1,2 OK //Set SSL verification level as 2, which means that a CA, certificate, client certificate and client private key should be uploaded with AT+QFUPL. AT+QFUPL='cacert.pem' CONNECT +QFUPL:1216,7648 //Upload the CA certificate to UFS. OK AT+QFUPL='clientcert.pem' CONNECT +QFUPL:1216,5558 //Upload the client certificate to UFS. OK AT+QFUPL='clientkey.pem' CONNECT +QFUPL:1706,538 //Upload the client private key to UFS. OK AT+QSSLCFG='cacert',1,'UFS:cacert.pem' OK Configure the path of CA certificate for SSL context 1. AT+QSSLCFG='clientcert',1,'UFS:clientcert.pem' //Configure the path of client certificate for SSL context 1. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 33 / 45 LTE Standard Module Series OK AT+QSSLCFG='clientkey',1,'UFS:clientkey.pem' OK //Configure the path of client private key for SSL context 1. AT+QHTTPURL=45,80 //Set the URL of the HTTPS server that will be accessed and timeout value as 80 s. CONNECT HTTPs://220.180.239.212:8011/processorder.php //Input the URL whose length is 45 bytes. (This URL is only an example. Input the correct URL in a practical test.) OK AT+QHTTPPOST=48,80,80 //Send HTTPS POST request. The maximum input body time and the maximum response time are 80 s each. CONNECT Message=1111&Appleqty=2222&Orangeqty=3333&find=1 //Input HTTPS POST body whose length is 48 bytes. (This post body is only an example. Input the correct one in a practical test.) OK +QHTTPPOST: 0,200,285 //If the HTTPS response header contains CONTENTLENGTH information, the (285) will be reported. AT+QHTTPREAD=80 //Read HTTPS response body and output it via UART. The maximum time to wait for HTTPS session to be closed is 80 s. CONNECT //HTTPS response body has been read successfully. Quectel's Auto Parts - Order Results Quectel's Auto Parts Order Results Order processed at 02:49, 27th DecemberYour order is as follows: 1111 message2222 apple3333 orange OK EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 34 / 45 +QHTTPREAD: 0 LTE Standard Module Series //HTTPS response body has been outputted successfully. 3.2.2.2. HTTPS POST Body Obtained from File System The following examples show how to send an HTTPS POST request and retrieve the HTTPS POST body from a file system, as well as how to store the HTTPS POST response to a file system. AT+QHTTPCFG='contextid',1 OK //Configure the PDP context ID as 1. AT+QIACT? OK //Query the state of context. //No context activated currently. AT+QICSGP=1,1,'UNINET','','',1 //Configure PDP context 1. China Unicom APN: UNINET. (Then set AT+CFUN=1,1 to make the configuration take effect.) OK AT+QIACT? +QIACT: 1,1,1,'172.22.86.226' //Query the state of context. OK //The first PDP is activated by default. If it is queried inactivated, use AT+QIACT=1 to activate it. AT+QIACT=1 //Activate context 1. OK //Activated successfully. AT+QHTTPCFG='sslctxid',1 OK //Set SSL context ID as 1. AT+QSSLCFG='sslversion',1,1 OK //Set SSL version as 1, which means TLSV1.0. AT+QSSLCFG='ciphersuite',1,0x0005//Set SSL cipher suite as 0x0005, which means RC4-SHA. OK AT+QSSLCFG='seclevel',1,2 OK //Set SSL verification level as 2, which means that a CA certificate, a client certificate and a client private key should be uploaded with AT+QFUPL. AT+QFUPL='cacert.pem' CONNECT +QFUPL:1216,7648 //Upload the CA certificate to UFS. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 35 / 45 LTE Standard Module Series OK AT+QFUPL='clientcert.pem' CONNECT +QFUPL:1216,5558 //Upload the client certificate to UFS. OK AT+QFUPL='clientkey.pem' CONNECT +QFUPL:1706,538 //Upload the client private key to UFS. OK AT+QSSLCFG='cacert',1,'UFS:cacert.pem' OK AT+QSSLCFG='clientcert',1,'UFS:clientcert.pem' OK AT+QSSLCFG='clientkey',1,'UFS:clientkey.pem' OK AT+QHTTPURL=45,80 CONNECT https://220.180.239.212:8011/processorder.php OK //Set the URL of the HTTPS server that will be accessed and timeout value as 80 s. //Input URL whose length is 45 bytes. (This URL is only an example. Input the correct URL in a practical test.) //POST request information from UFS file, and read the HTTPS response and store it to a UFS file. AT+QHTTPPOSTFILE='UFS:5.txt',80 OK //Send HTTPS POST request. HTTPS POST body is obtained from UFS:5.txt. The maximum response time is 80 s. +QHTTPPOSTFILE: 0,200,177 AT+QHTTPREADFILE='UFS:6.txt',80 //After HTTPS POST request is sent successfully, the HTTPS response body can be read via either AT+QHTTPREAD or AT+QHTTPREADFILE. //Read the HTTPS response body and store it to UFS:6.txt. The maximum time to wait for an HTTPS EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 36 / 45 OK +QHTTPREADFILE: 0 LTE Standard Module Series session to be closed is 80 s. //HTTPS response body has been stored successfully. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 37 / 45 LTE Standard Module Series 4 Error Handling 4.1. Executing HTTP(S) AT Command Failure if ERROR response is received from the module after executing HTTP(S) AT commands, check whether the (U)SIM card has been inserted and whether +CPIN: READY is returned after executing AT+CPIN?. 4.2. PDP Activation Failure In case of failure to active a PDP context with AT+QIACT, check the following configurations: 1. Query whether the PS domain is attached or not with AT+CGATT?. If not, execute AT+CGATT=1 to attach the PS domain. 2. Query the PS domain status with AT+CGREG? and make sure the PS domain has been registered. 3. Query the PDP context parameters with AT+QICSGP= and make sure the APN of the specified PDP context has been set. 4. Make sure the specified PDP context ID is neither used by PPP nor activated with AT+CGACT. 5. According to 3GPP specifications, the module supports maximum three PDP contexts activated simultaneously. If all above configurations are correct, but activating the PDP context with AT+QIACT still fails, reboot the module. After rebooting, check the configurations above at least three times in 10-minute intervals to avoid frequent module rebooting. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 38 / 45 LTE Standard Module Series 4.3. DNS Parse Failure If +CME ERROR: 714 (714: HTTP(S) DNS error) is returned after executing AT+QHTTPGET, AT+QHTTPPOST and AT+QHTTPPOSTFILE, check the following: 1. Make sure the domain name of HTTP(S) server is valid. 2. Query the status of the PDP context with AT+QIACT? to make sure the specified PDP context has been activated successfully. 3. Query the address of DNS server with AT+QIDNSCFG to make sure the address is not '0.0.0.0'. If the DNS server address is '0.0.0.0', there are two solutions: 1. Reassign a valid DNS server address with AT+QIDNSCFG. 2. Deactivate the PDP context with AT+QIDEACT, and then re-activate the PDP context with AT+QIACT. 4.4. Entering Data Mode Failure If +CME ERROR: 704 (704: HTTP(S) UART busy) is returned after executing AT+QHTTPURL, AT+QHTTPGET, AT+QHTTPPOST and AT+QHTTPREAD, check if there are other ports in data mode, since the module only supports one port in data mode at a time. If there are, please re-execute these commands after all ports but one have exited data mode. 4.5. Sending GET/POST Requests Failure If a failed result is received after executing AT+QHTTPGET, AT+QHTTPGETEX, AT+QHTTPPOST and AT+QHTTPPOSTFILE, check the following configurations: 1. Make sure the URL inputted via AT+QHTTPURL is valid and can be accessed. 2. Make sure the specified server supports GET/POST requests. 3. Make sure the PDP context has been activated successfully. If all above configurations are correct, but sending GET/POST requests with AT+QHTTPGET, AT+QHTTPPOST and AT+QHTTPPOSTFILE still fails, deactivate the PDP context with AT+QIDEACT and re-activate it with AT+QIACT. If activating the PDP context fails, see Chapter 4.2. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 39 / 45 LTE Standard Module Series 4.6. Reading Response Failure Before reading responses with AT+QHTTPREAD and AT+QHTTPREADFILE, execute AT+QHTTPGET, AT+QHTTPPOST and AT+QHTTPPOSTFILE and wait until the following URC information is reported: +QHTTPGET: [,[,]] +QHTTPPOST: [,[,]] +QHTTPPOSTFILE: [,[,]] In case of errors during the execution of AT+QHTTPREAD and AT+QHTTPREADFILE, such as +CME ERROR: 717 (717: HTTP(S) socket read error), resend HTTP(S) GET/POST requests to HTTP(S) server with AT+QHTTPGET, AT+QHTTPPOST and AT+QHTTPPOSTFILE. If sending GET/POST requests to HTTP(S) server fails, see Chapter 4.5. EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 40 / 45 LTE Standard Module Series 5 Summary of ERROR Codes The error code indicates an error related to mobile equipment or network. The detailed information about is presented in the following table. Table 3: Summary of Error Codes Meaning 0 Operation successful 701 HTTP(S) unknown error 702 HTTP(S) timeout 703 HTTP(S) busy 704 HTTP(S) UART busy 705 HTTP(S) no GET/POST requests 706 HTTP(S) network busy 707 HTTP(S) network open failed 708 HTTP(S) network no configuration 709 HTTP(S) network deactivated 710 HTTP(S) network error 711 HTTP(S) URL error 712 HTTP(S) empty URL 713 HTTP(S) IP address error 714 HTTP(S) DNS error 715 HTTP(S) socket create error 716 HTTP(S) socket connect error 717 HTTP(S) socket read error EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 41 / 45 LTE Standard Module Series 718 HTTP(S) socket write error 719 HTTP(S) socket closed 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 Memory allocation failed 730 Invalid parameter EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 42 / 45 LTE Standard Module Series 6 Summary of HTTP(S) Response Codes indicates the response codes from HTTP(S) server. The meaning of is presented in the following table. Table 4: Summary of HTTP(S) Response Codes 200 403 404 409 411 500 Meaning OK Forbidden Not found Conflict Length required Internal server error EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 43 / 45 LTE Standard Module Series 7 Appendix References Table 5: Related Documents Document Name [1] Quectel_EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_TCP(IP)_ Application_Note [2] Quectel_EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_SSL_ Application_Note [3] Quectel_EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_AT_ Commands_Manual Table 6: Terms and Abbreviations Abbreviation APN CA COM port CR DNS DTR HTTP HTTPS ID IP LF LTE Description Access Point Name Certification Authority Communication Port Carriage Return Domain Name Server Data Terminal Ready Hypertext Transfer Protocol Hypertext Transfer Protocol Secure Identification Internet Protocol Line Feed (a new line) Long-Term Evolution EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 44 / 45 PDP PPP PS SSL TCP TLS UART UFS URC URI URL USB (U)SIM LTE Standard Module Series Packet Data Protocol Point-to-Point Protocol Packet Switch Security Socket Layer Transmission Control Protocol Transport Layer Security Universal Asynchronous Receiver/Transmitter UNIX File System Unsolicited Result Code Uniform Resource Identifier Uniform Resource Locator Universal Serial Bus (Universal) Subscriber Identity Module EC200x&EC600M&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_HTTP(S)_Application_Note 45 / 45
409.95 KB
EC200x&EG800K&EG810M& EG91xN&EG912Y&EG950A Series MQTT Application Note LTE Standard Module Series Version: 1.4 Date: 2023-10-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 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&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 1 / 36 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&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 2 / 36 LTE Standard Module Series About the Document Revision History Version Date - 2020-08-12 1.0 2020-08-12 1.1 2021-04-15 1.2 2022-03-02 1.3 2022-08-05 1.4 2023-10-25 Author Description Luffy LIU/ Larson LI Creation of the document Luffy LIU/ Larson LI First official release Luffy LIU/ Larson LI Added a Writer Command: AT+QMTCFG='edit/timeout',[,,] (Chapter 3.3.1). Luffy LIU/ Added the applicable modules EC200A series and Larson LI EG915N-EU. Luffy LIU/ 1. Added applicable modules EG915N-LA and EG912N-EN. Larson LI 2. Deleted applicable module EC200T series. 1. Added the applicable module: EC200N-LA, EG800K series, EG810M-EU and EG950A series. 2. Added a note that different models support MQTT feature differently due to the flash size of the module (Chapter 1.1). Fawei ZHOU 3. Added a note that the SSL authentication is optional for different models (Chapters 3.3.1 and 5.2) 4. Updated the command and parameter description of AT+QMTCFG='qmtping' and added AT+QMTCFG='protocol/check' (Chapter 3.3.1) EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 3 / 36 LTE Standard Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 1.1. Applicable Modules .................................................................................................................... 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 for MQTT Client ..................................................... 18 3.3.3. AT+QMTCLOSE Close a Network 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 .......................................................................... 24 3.3.9. AT+QMTRECV Read Messages from Buffer ............................................................. 26 4 MQTT URCs ....................................................................................................................................... 28 4.1. +QMTSTAT URC to Indicate State Change in MQTT Link Layer ......................................... 28 4.2. +QMTRECV URC to Inform the Host to Read MQTT Packet Data...................................... 29 4.3. +QMTPING URC to Indicate PING State of Keep-alive 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 ....................................................................................................................... 36 EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 4 / 36 LTE Standard Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 6 Table 2: Types of AT Commands ................................................................................................................. 8 Table 3: MQTT URCs ................................................................................................................................. 28 Table 4: Error Codes of +QMTSTAT: URC................................................................................................. 29 Table 5: Related Document........................................................................................................................ 36 Table 6: Terms and Abbreviations .............................................................................................................. 36 EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 5 / 36 LTE Standard Module Series 1 Introduction Quectel EC200x family, EG800K series, EG810M-EU, EG91xN family, EG912Y-EU and EG950A series modules support MQTT function. Message Queuing Telemetry Transport (MQTT) is a broker-based publish/subscribe messaging protocol designed to be open, simple, lightweight, and easy to implement. It is designed for connections with remote locations where a 'small code footprint' is required or the network bandwidth is limited. This document explains how to use the MQTT function of the following Quectel modules through AT commands. 1.1. Applicable Modules Table 1: Applicable Modules Module Family EC200x EG91xN - Module EC200A Series EC200N-LA EC200S Series EG800K Series EG810M-EU EG912N-EN EG915N Series EG912Y-EU EG950A Series NOTE Limited by the flash size of the module, different models of the modules support PPP feature differently. For more details, please contact Quectel Technical Support. EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 6 / 36 LTE Standard Module Series 2 MQTT Data Interaction This chapter illustrates the data interaction mechanism of the MQTT function. MCU Modem Link layer MQTT Server AT+QMTCFG='will',, AT+QMTCFG='timeout',, AT+QMTOPEN=,'', OK TCP-REQ +QMTOPEN: , AT+QMTCONN AT+QMTCONN=,, OK +QMTCONN: ,[,] TCP established CONN-REQ Start timer T1, T2 CONN ACK-IND Stop T1 or handle Excep1 AT+QMTSUB AT+QMTSUB=,... OK +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 +QMTPUBEX: ,,[,] PUB COMP-IND (msgId) Stop T1 or handle Excep2 TCP SYN TCP SYN+ACK TCP ACK Send connect packet Receive connect ACK packet Send subscribe packet Receive subscribe ACK packet Send unsubscribe packet Receive unsubscribe ACK packet Send publish packet Send publish packet Receive publish ACK packet Send publish packet Receive publish receive packet Send publish release packet Receive publish complete packet T1 is packet transmission timeout. T2 is keep alive timer. In the absence of a data-related message during the T2 time period, the client will send PINGREQ packet. Excep1: Disconnect the TCP connection. Excep2: Resend packets unless maximum retry times is reached. Retry times is set with AT+QMTCFG. Whether the timeout information is reported can be configured with AT+QMTCFG. Receive PUBLISH Receive message in the form of URC. +QMTRECV: ,,, PUB-IND (msgId) PUB ACK/REC-REQ (msgId) Reply accor.d..ing 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, please refer to the description of corresponding AT command in Chapter 3.2. Figure 1: MQTT Data Interaction Diagram EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 7 / 36 LTE Standard Module Series 3 MQTT Related AT Commands 3.1. AT Command Introduction 3.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 3.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 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. EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 8 / 36 LTE Standard Module Series 3.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. 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),(li st of supported s) +QMTCFG: 'pdpcid',(range of supported s),(ra nge 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),(li st of supported s) +QMTCFG: 'timeout',(range of supported s),(r ange 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),(l ist of supported s),'willtopic',(range of support ed s) +QMTCFG: 'recv/mode',(range of supported s),(list of supported s),(list of supported s) +QMTCFG: 'aliauth',(range of supported s),'pr oduct key','device name','device secret' EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 9 / 36 LTE Standard Module Series +QMTCFG: 'qmtping',(range of supported s),(r ange of supported s) +QMTCFG: 'send/mode',(range of supported s),(list of supported s) +QMTCFG: 'onenet',(range of supported s),'pr oduct id','access key' +QMTCFG: 'hwauth',(range of supported s),'p roduct id','device secret' +QMTCFG: 'hwprodid',(range of supported s), 'product id','product secret','nodeid' +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: 'protocol/check',(range of supported s),(list of supported s) Write Command Query/set the MQTT protocol version AT+QMTCFG='version',[,] OK Response If the optional parameter is omitted, query the MQTT protocol version: +QMTCFG: 'version', OK If the optional parameter is specified 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: EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 10 / 36 LTE Standard Module Series OK Write Command Query/set the MQTT SSL mode and SSL context index AT+QMTCFG='ssl',[,< SSL_enable>,] 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 If there is any error: ERROR Write Command Response Query/set timeout of message If the optional parameters are omitted, query the timeout of EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 11 / 36 LTE Standard Module Series delivery AT+QMTCFG='timeout',[,,,< timeout_notice>] message delivery: +QMTCFG: 'timeout',,, OK If the optional parameters are specified and the MQTT connection is not established, set timeout of message delivery: OK Write Command Query/set Will information AT+QMTCFG='will',[, [,, ,,]] If there is any error: ERROR Response If the optional parameters are omitted, query the current configuration: +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 configuration: +QMTCFG: 'willex',[,,,,] If the optional parameters are specified, set the Will information: > Input the Will messages. When the actual size of data is greater than , the first byte(s) data is sent out. OK Write Command Query/set receiving mode when data are received from server AT+QMTCFG='recv/mode',<client If there is any error: ERROR Response If the optional parameters are omitted, query the MQTT message receiving mode: +QMTCFG: 'recv/mode',,[,[,]] ble> OK If the optional parameters are specified and the MQTT connection is not established, set the receiving mode when data are received from server: OK Write Command Query/set Alibaba device information for Alibaba Cloud 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 Alibaba Could: OK If there is any error: ERROR Write Command Response Query/set the maximum interval of If the optional parameter is omitted, query the current reporting +QMTCLOSE when the configuration: heartbeat time expires +QMTCFG: 'qmtping', AT+QMTCFG='qmtping',[,] OK If the optional parameter is specified, and the MQTT connection is not established, set the maximum interval of reporting +QMTCLOSE when the heartbeat time expires: OK If there is any error: ERROR Write Command Response Query/set the MQTT message If the optional parameter is omitted, query the current sending mode configuration: AT+QMTCFG='send/mode',<client +QMTCFG: 'send/mode', EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 13 / 36 LTE Standard Module Series _idx>[,] OK If the optional parameter is specified, and the MQTT connection is not established, configure the MQTT message sending mode: OK Write Command Query/set the MQTT device for China Mobile OneNET IoT platform AT+QMTCFG='onenet',[,,] If there is any error: ERROR Response If the optional parameters are omitted, query the current configuration: +QMTCFG: 'onenet',, OK 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 device for Huawei IoT platform AT+QMTCFG='hwauth',[,,] If there is any error: ERROR Response If the optional parameters are omitted, query the current configuration: +QMTCFG: 'hwauth',,[,] OK If the optional parameters are specified, and the MQTT connection is not established, set the MQTT device for Huawei IoT platform: OK Write Command Query/set the MQTT device for Huawei IoT platform AT+QMTCFG='hwprodid',[,,,] If there is any error: ERROR Response If the optional parameters are omitted, query the current configuration: +QMTCFG: 'hwprodid',,,[,] EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 14 / 36 LTE Standard Module Series OK If the optional parameters are specified, and the MQTT connection is not established, set the MQTT device for Huawei 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 current configuration: +QMTCFG: 'dataformat',, OK If the optional parameters are specified, and the MQTT connection is not established, set the MQTT data format: OK If there is any error: ERROR Write Command Response Query/set the MQTT data view mode If the optional parameter is omitted, query the current in transparent mode configuration: AT+QMTCFG='view/mode',<client +QMTCFG: 'view/mode', _idx>[,] 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 MQTT input data timeout AT+QMTCFG='edit/timeout',[,,] If there is any error: ERROR Response If the optional parameters are omitted, query the current configuration: +QMTCFG: 'edit/timeout',[,] OK If the optional parameters are specified, and the MQTT EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 15 / 36 LTE Standard Module Series connection is not established, set the MQTT input data timeout: OK Write Command Configure MQTT protocol check AT+QMTCFG='protocol/check',[,] If there is any error: ERROR Response If the optional parameter is omitted, query the current configuration: +QMTCFG: 'protocol/check',, OK Maximum Response Time Characteristic If the optional parameter is specified, and the MQTT connection is not established, configure MQTT protocol check: OK Or ERROR 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. MQTT protocol version. 3 MQTT protocol v3.1 4 MQTT protocol v3.1.1 Integer type. PDP to be used by the MQTT client. Range: 1–15. Default value: 1. Integer type. Configure the MQTT SSL mode. 0 Use normal TCP connection for MQTT 1 Use SSL TCP secure connection for MQTT Integer type. SSL context index. Range: 0–5. Integer type. Maximum interval between messages received from a client. If the server does not receive a message (interactive message and keep-alive packet) from the client within 1.5 times the keep-alive time, it disconnects the client as if the client has sent a DISCONNECT message. Range: 0–3600. Default value: 120. Unit: s. 0 Client is not disconnected Integer type. Configure session type. 0 The server must store the subscriptions of the client after it disconnects. 1 The server must discard any previously maintained information about the client and treat the connection as 'clean'. EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 16 / 36 LTE Standard Module Series Integer type. Timeout of packet delivery. Range: 1–60. Default value: 5. Unit: s. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. Integer type. Whether to report timeout message when transmitting packets. 0 Do not report 1 Report Integer type. Configure the Will flag. 0 Ignore the Will flag configuration 1 Require the Will flag configuration Integer type. Quality of service for message delivery. 0 At most once 1 At least once 2 Exactly once Integer type. Will retain flag is only used on PUBLISH messages. 0 When a client sends a PUBLISH message to a server, the server will not hold on to the message after it has been delivered to the current subscribers 1 When a client sends a PUBLISH message to a server, the server should hold on to the message after it has been delivered to the current subscribers String type. Will topic string. Length: 1–256 bytes. String type. Will message defines the content of the message that is published to the will topic when the client is unexpectedly disconnected. Range: 0–256. Integer type. Length of Will message. Range: 0–256. Unit: byte. Integer type. MQTT message receiving mode. 0 MQTT message received from server is contained in URC 1 MQTT message received from server is not contained in URC Integer type. Whether the length of MQTT message received from server is contained in URC. 0 Not contained 1 Contained String type. Product key issued by Alibaba Cloud. String type. Device name issued by Alibaba Cloud. String type. Device secret key issued by Alibaba Cloud/Huawei IoT platform. Integer type. The maximum interval of reporting +QMTCLOSE when the heartbeat time expires. Range: 5–60. Default value: 5. Unit: s. Integer type. Configure MQTT message sending mode. 0 String type 1 Hex type String type. Product ID issued by OneNET/Huawei IoT platform. String type. Product access key issued by OneNET/Huawei IoT platform. Integer type. Enable/disable timestamp check when the device is connected to the Huawei IoT platform. 0 Disable 1 Enable String type. Product verification certificate issued by Huawei IoT platform. EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 17 / 36 LTE Standard Module Series String type. Device identification code, identifying the only device. Integer type. MQTT message receiving mode. 0 String 1 Hex Integer type. MQTT data view mode in transparent mode. 0 Data are not displayed in transparent mode 1 Data can be displayed in transparent mode Integer type. Configure whether to exit when the MQTT input data time out. 0 Disable 1 Enable Integer type. MQTT input data timeout. Range: 1–120. Unit: s. Integer type. Configure whether to enable MQTT protocol checking. 0 Disable 1 Enable NOTE 1. If =1, then , , and must be set. Otherwise, they are omitted. 2. =0 is only effective when the server supports the operation. 3. If MQTT connection is configured to SSL mode, must be specified. In addition, you can use AT+QSSLCFG to configure the SSL version, cipher suite, secure level, CA certificate, client certificate, client key and ignorance of RTC time, which are used in MQTT SSL handshake procedure (SSL authentication is optional for different module models. For more details, please contact Quectel Technical Support). 4. It is crucial to ensure that message delivery does not time out while the message sending is ongoing. 5. AT+QMTCFG='aliauth' is only used for Alibaba Cloud. If it is configured, and in AT+QMTCONN can be omitted. 3.3.2. AT+QMTOPEN Open a Network for MQTT Client This command opens a network for MQTT client. AT+QMTOPEN Open a Network for MQTT Client Test Command AT+QMTOPEN=? Response +QMTOPEN: (range of supported s),'hostna me',(range of supported s) Read Command AT+QMTOPEN? OK Response [+QMTOPEN: ,,] OK EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 18 / 36 LTE Standard Module Series Write Command AT+QMTOPEN=,, If there is any error: ERROR Response OK +QMTOPEN: , Maximum Response Time Characteristic If there is any error: ERROR 120 s, determined by network / Parameter Integer type. MQTT client identifier. Range: 0–5. String type. Server address. It could be an IP address or a domain name. Maximum size: 100 bytes. Integer type. Server port. Range: 1–65535. Integer type. Command execution result. -1 Failed to open network 0 Network opened successfully 1 Wrong parameter 2 MQTT identifier is occupied 3 Failed to activate PDP 4 Failed to parse domain name 5 Network connection error 3.3.3. AT+QMTCLOSE Close a Network for MQTT Client This command closes a network for MQTT client. AT+QMTCLOSE Close a Network for MQTT Client Test Command AT+QMTCLOSE=? Response +QMTCLOSE: (range of supported s) Write Command AT+QMTCLOSE= OK Response OK +QMTCLOSE: , If there is any error: EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 19 / 36 Maximum Response Time Characteristic ERROR 30 s / LTE Standard Module Series Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Command execution result. -1 Failed to close network 0 Network closed successfully 3.3.4. AT+QMTCONN Connect a Client to MQTT Server This command connects a client to MQTT server. When a TCP/IP socket connection is established between a client to a server, a protocol level session must be created using a CONNECT flow. AT+QMTCONN Connect a Client to MQTT Server Test Command AT+QMTCONN=? Response +QMTCONN: (range of supported s),'clienti d','username','password' Read Command AT+QMTCONN? OK Response [+QMTCONN: ,] OK Write Command AT+QMTCONN=,[,,] If there is any error: ERROR Response OK +QMTCONN: ,[,] Maximum Response Time Characteristic If there is any error: ERROR (default 5 s), determined by network / EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 20 / 36 LTE Standard Module Series Parameter Integer type. MQTT client identifier. Range: 0–5. String type. Client identifier string. String type. Client username. It can be used for authentication. String type. Password corresponding to the client username. It can be used for authentication. Integer type. Command execution result. 0 Packet sent successfully and ACK received from server 1 Packet retransmission 2 Failed to send packet Integer type. MQTT connection state. 1 MQTT is initializing 2 MQTT is connecting 3 MQTT is connected 4 MQTT is disconnecting Integer type. Connection status return code. 0 Connection Accepted 1 Connection Refused: Unacceptable Protocol Version 2 Connection Refused: Identifier Rejected 3 Connection Refused: Server Unavailable 4 Connection Refused: Bad Username or Password 5 Connection Refused: Not Authorized Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: second. The value can be configured with AT+QMTCFG='timeout',[,,,]. NOTE If a client with the same client ID is already connected to the server, the 'older' client must be disconnected by the server before completing the CONNECT flow of the new client. 3.3.5. AT+QMTDISC Disconnect a Client from MQTT Server This command requests a disconnection from MQTT server by a client. The client sends a DISCONNECT message to the server to indicate that it is about to close its TCP/IP connection. AT+QMTDISC Disconnect a Client from MQTT Server Test Command AT+QMTDISC=? Response +QMTDISC: (range of supported s) Write Command AT+QMTDISC= OK Response OK EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 21 / 36 LTE Standard Module Series Maximum Response Time Characteristic +QMTDISC: , If there is any error: ERROR 30 s / Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Command execution result. -1 Failed to close connection 0 Connection closed successfully 3.3.6. AT+QMTSUB Subscribe to Topics This command subscribes to one or more topics. A SUBSCRIBE message is sent to the server by a client to register an interest in one or more topics. Messages published to these topics are delivered from the server to the client as PUBLISH messages. AT+QMTSUB Subscribe to Topics Test Command AT+QMTSUB=? Response +QMTSUB: (range of supported s),,list of ['topic',qos] Write Command AT+QMTSUB=, ,,[,, …] OK Response OK +QMTSUB: ,,[,] Maximum Response Time Characteristic If there is any error: ERROR × (default 15 s), determined by network / EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 22 / 36 LTE Standard Module Series Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of packet. Range: 1–65535. String type. Topic that the client wants to subscribe to or unsubscribe from. Integer type. QoS level at which the client wants to publish messages. 0 At most once 1 At least once 2 Exactly once Integer type. Command execution result. 0 Packet sent successfully and ACK received from server 1 Packet retransmission 2 Failed to send packet Integer type. If is 0, it is a vector of granted QoS levels. If is 1, it is the number of times the packet has been retransmitted. If is 2, it is not presented. Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: s. The value can be configured with AT+QMTCFG='timeout',[,,,]. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. NOTE The is only present in messages where the QoS bits in the fixed header indicate QoS levels 1 or 2. It must be unique amongst the set of 'inflight' messages in a particular communication direction. It typically increases by 1 from one message to the next, but it is not compulsory in practical applications. 3.3.7. AT+QMTUNS Unsubscribe from Topics This command unsubscribes from one or more topics. An UNSUBSCRIBE message is sent by the client to the server to unsubscribe from named topics. AT+QMTUNS Unsubscribe from Topics Test Command AT+QMTUNS=? Response +QMTUNS: (range of supported s),,list of ['topic'] Write Command AT+QMTUNS=, ,[,…] OK Response OK +QMTUNS: ,,[,] EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 23 / 36 LTE Standard Module Series Maximum Response Time Characteristic If there is any error: ERROR × (default 15 s), determined by network / Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of packet. Range: 1–65535. String type. Topic that the client wants to subscribe to or unsubscribe from. Integer type. Command execution result. 0 Packet sent successfully and ACK received from server 1 Packet retransmission 2 Failed to send packet Integer type. If is 0, it is a vector of granted QoS levels. If is 1, it the number of times the packet has been retransmitted. If is 2, it is not presented. Integer type. Packet delivery timeout. Range: 1–60. Default value: 5. Unit: s. The value can be configured with AT+QMTCFG='timeout',[,,,]. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. 3.3.8. AT+QMTPUBEX Publish Messages This command publishes fixed-length messages by a client to a server for distribution to interested subscribers. Each PUBLISH message is associated with a topic name. If a client subscribes to one or more topics, any message published on those topics is sent by the server to the client as a PUBLISH message. AT+QMTPUBEX Publish Messages Test Command AT+QMTPUBEX=? Response +QMTPUBEX: (range of supported s),,(range of supported s),(list of supported s),'topic','length' Write Command AT+QMTPUBEX=,,,,, OK Response > After > is reported, input the data to be sent. When the actual EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 24 / 36 Maximum Response Time Characteristic LTE Standard Module Series size of data is greater than , the first byte(s) data is sent out. OK +QMTPUBEX: ,,[,] If there is any error: ERROR × (default 15 s), determined by network / Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of packet. Range: 0–65535. It is 0 only when =0. Integer type. QoS level at which the client wants to publish messages. 0 At most once 1 At least once 2 Exactly once Integer type. Whether or not the server will retain the message after it has been delivered to the current subscribers. 0 Do not retain 1 Retain String type. Topic that needs to be published. Integer type. Length of message to be published. Integer type. Command execution result. 0 Packet sent successfully and ACK received from server (message that is published when =0 does not require ACK) 1 Packet retransmission 2 Failed to send packet Integer type. If is 1, it means the number of times a packet has been retransmitted . If is 0 or 2, it is not presented. Integer type. Packet delivery timeout. Range: 1–60. Default value: 5.Unit: s. AT+QMTCFG='timeout',[,,,]. Integer type, Retry times when packet delivery times out. Range: 0–10. Default value: 3. EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 25 / 36 LTE Standard Module Series NOTE 1. If this command is executed successfully and OK is returned, the client can publish a new packet. The maximum quantity of packets to be transmitted should not be greater than the inflight window size (5); otherwise, ERROR is returned. 2. After executing this command, the client is ready to send data, which are sent as payload. Maximum length of data input at a time: 1500 bytes. 3. PUBLISH messages can be sent either by a publisher to the server, or by the server to a subscriber. When a server publishes messages to a subscriber, the following URC is returned to notify the host to read the received data reported by MQTT server: +QMTRECV: ,,[,],. For more information about the URC, see Chapter 4.2. 3.3.9. AT+QMTRECV Read Messages from Buffer This command reads the messages from the storage buffer where the messages are stored after being reported by the server. AT+QMTRECV Read Messages from Buffer Test Command AT+QMTRECV=? Read Command AT+QMTRECV? Response OK Response +QMTRECV: ,,,,, OK Write Command AT+QMTRECV=[,] If there is no MQTT connection: OK Response [List of (+QMTRECV: ,,[,],)s] OK Maximum Response Time Characteristic If there is no MQTT connection: ERROR / / EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 26 / 36 LTE Standard Module Series Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Indicate if a message is stored in the buffer. Maximum 5 messages can be stored in the buffer. Therefore, URC reports maximally 5 messages simultaneously. 0 No message in the buffer 1 There are stored messages in the buffer Integer type. Serial number of a received message. Range: 0–4. Integer type. Message identifier of packet. Range: 0–65535. It is equal to 0 only when =0. String type. Topic that needs to be published. Integer type. Payload length. Unit: Byte. String type. Payload relating to the topic name. EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 27 / 36 LTE Standard Module Series 4 MQTT URCs This chapter describes MQTT URCs. Table 3: MQTT URCs SN URC Format Description Reported when the state of MQTT link layer has [1] +QMTSTAT: , changed, the client will close the MQTT connection and report the URC. +QMTRECV: ,,[,], data from MQTT server. [3] +QMTRECV: , Reported when the message received from MQTT server has been stored in buffer. Reported when the state of MQTT link layer has [4] +QMTPING: , changed, the client will close the MQTT connection and report the URC. 4.1. +QMTSTAT URC to Indicate State Change in MQTT Link Layer The URC beginning with +QMTSTAT:. is reported when there is a change in the state of MQTT link layer. +QMTSTAT URC to Indicate State Change in MQTT Link Layer +QMTSTAT: , When the state of MQTT link layer has changed, the client will close the MQTT connection and report the URC. Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Error code. Refer to the table below for more information. EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 28 / 36 LTE Standard Module Series Table 4: Error Codes of +QMTSTAT: URC Description Connection is closed or reset by a 1 peer end. Sending PINGREQ packet timed out 2 or failed. Sending CONNECT packet timed out 3 or failed. 4 5 6 7 8 9–255 Receiving CONNACK packet timed out or failed. The client sends DISCONNECT packet to sever and the server starts closing the MQTT connection. The client closes MQTT connection due to packet sending failure all the time. The link is not alive or the server is unavailable. The client closes the MQTT connection. Reserved for future use. Solution Execute AT+QMTOPEN and reopen MQTT connection. First, deactivate and activate the PDP. Then, reopen the MQTT connection. 1. Check whether the inputted username and password are correct. 2. Make sure the client ID is not used. 3. Reopen MQTT connection and try to send CONNECT packet to server again. 1. Check whether the inputted username and password are correct. 2. Make sure the client ID is not used. 3. Reopen MQTT connection and try to send CONNECT packet to server again. This is a normal process. 1. Make sure the data are correct. 2. Try to reopen MQTT connection since there may be a network congestion or an error. Make sure the link is alive or the server is currently available. Try to reconnect. 4.2. +QMTRECV URC to Inform the Host to Read MQTT Packet Data The URC beginning with +QMTRECV:. is mainly used to notify the host to read the received MQTT packet data reported by MQTT server. +QMTRECV URC to Inform the Host to Read MQTT Packet Data +QMTRECV: ,,[,], +QMTRECV: ,[, ] Notify the host to read the received data reported by MQTT server. Reported when the message received from MQTT server has been stored in buffer. EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 29 / 36 LTE Standard Module Series Parameter Integer type. MQTT client identifier. Range: 0–5. Integer type. Message identifier of packet. String type. Topic received from MQTT server. Integer type. Payload length. String type. Payload relating to the topic name. Integer type. Serial number of a received message. Range: 0–4. 4.3. +QMTPING URC to Indicate PING State of Keep-alive in MQTT The URC beginning with +QMTPING:. is reported when server receives no message from the client within 1.5 times the keep-alive interval and it will disconnect the client as if the client has sent a DISCONNECT message. + QMTPING URC to Indicate PING State of Keep-alive in MQTT +QMTPING: , Received when the state of MQTT link layer has changed. The client will close the MQTT connection and report the URC. Parameter . Integer type. MQTT client identifier. Range: 0–5. Integer type. Result of PING state. 1 Failed EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 30 / 36 LTE Standard Module Series 5 Examples This chapter provides some examples to explain how to use MQTT AT commands. 5.1. Example of MQTT Operation Without SSL //Configure receiving mode. AT+QMTCFG='recv/mode',0,0,1 OK //Configure Alibaba device information for Alibaba cloud. AT+QMTCFG='aliauth',0,'oyjtmPl5a5j','MQTT_TEST','wN9Y6pZSIIy7Exa5qVzcmigEGO4kAazZ' OK AT+QMTOPEN=? +QMTOPEN: (0-5),'hostname',(1-65535) OK //Open a network for MQTT client. AT+QMTOPEN=0,'iot-as-mqtt.cn-shanghai.aliyuncs.com',1883 OK +QMTOPEN: 0,0 //Opened the MQTT client network successfully. AT+QMTOPEN? +QMTOPEN: 0,'iot-as-mqtt.cn-shanghai.aliyuncs.com',1883 OK AT+QMTCONN=? +QMTCONN: (0-5),'clientid','username','password' OK //Connect a client to MQTT server. //If Alibaba Cloud is connected, AT+QMTCFG='aliauth' can be used to configure the device information in advance. There is no need to provide username/password from now on. AT+QMTCONN=0,'clientExample' OK EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 31 / 36 LTE Standard Module Series +QMTCONN: 0,0,0 //Connected the client to MQTT server successfully. AT+QMTSUB=? +QMTSUB: (0-5),,list of ['topic',qos] OK //Subscribe to topics. AT+QMTSUB=0,1,'topic/example',2 OK +QMTSUB: 0,1,0,2 AT+QMTSUB=0,1,'topic/pub',0 OK +QMTSUB: 0,1,0,0 //If a client subscribes to a topic and other devices publish the same topic to the server, the module will report the following information. +QMTRECV: 0,0,'topic/example',36,'This is the payload related to topic' //Unsubscribe from topics. AT+QMTUNS=0,2,'topic/example' OK +QMTUNS: 0,2,0 AT+QMTPUBEX=? +QMTPUBEX: (0-5),,(0-2),(0,1),'topic','length' OK //Publish messages. After receiving >, input data 'These are test data, hello MQTT.' and then send it. The maximum length of the data to be sent is 1500 bytes. All data beyond 1500 bytes will be omitted. AT+QMTPUBEX=0,0,0,0,'topic/pub',30 > These are test data, hello MQTT. OK +QMTPUBEX: 0,0,0 //If a client subscribes to a topic named 'topic/pub' and other devices publish the same topic to the server, the module reports the following information. +QMTRECV: 0,0,'topic/pub',30,'These are test data, hello MQTT.' //Disconnect a client from MQTT server. AT+QMTDISC=0 OK EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 32 / 36 +QMTDISC: 0,0 LTE Standard Module Series //Connection closed successfully. 5.2. Example of MQTT Operation with SSL See documents [1] and [2] for more information on AT commands related to SSL. //Configure receiving mode. AT+QMTCFG='recv/mode',0,0,1 OK //Configure MQTT session into SSL mode. AT+QMTCFG='SSL',0,1,2 OK //If SSL authentication mode is 'server authentication', store CA certificate to UFS. AT+QFUPL='UFS:cacert.pem',1758,100 CONNECT +QFUPL: 1758,384a OK //If SSL authentication mode is 'server authentication', store CC certificate to UFS. AT+QFUPL='UFS:client.pem',1220,100 CONNECT +QFUPL: 1220,2d53 OK //If SSL authentication mode is 'server authentication', store CK certificate to UFS. AT+QFUPL='UFS:user_key.pem',1679,100 CONNECT +QFUPL: 1679,335f OK //Configure CA certificate. AT+QSSLCFG='cacert',2,'UFS:cacert.pem' OK EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 33 / 36 LTE Standard Module Series //Configure CC certificate. AT+QSSLCFG='clientcert',2,'UFS:client.pem' OK //Configure CK certificate. AT+QSSLCFG='clientkey',2,'UFS:user_key.pem' OK //Configure the authentication mode for SSL context 2. AT+QSSLCFG='seclevel',2,2 //SSL authentication mode: server and client authentication if requested by the remote server. OK AT+QSSLCFG='sslversion',2,4 //SSL authentication version OK AT+QSSLCFG='ciphersuite',2,'0xFFFF' //Cipher suite OK AT+QSSLCFG='ignorelocaltime',2,1 //Ignore authentication time. OK //Start MQTT SSL connection AT+QMTOPEN=0,'a1zgnxur10j8ux.iot.us-east-1.amazonaws.com',8883 OK +QMTOPEN: 0,0 //Connect to MQTT server. AT+QMTCONN=0,'M26_0206' OK +QMTCONN: 0,0,0 //Subscribe to topics. AT+QMTSUB=0,1,'$aws/things/M26_0206/shadow/update/accepted',1 OK +QMTSUB: 0,1,0,1 //Publish messages. AT+QMTPUBEX=0,1,1,0,'$aws/things/M26_0206/shadow/update/accepted',32 >These are published data from client OK +QMTPUBEX: 0,1,0 //If a client subscribes to a topic named '$aws/things/M26_0206/shadow/update/accepted' and other EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 34 / 36 LTE Standard Module Series devices publish the same topic to the server, the module will report the following information. +QMTRECV: 0,1,'$aws/things/M26_0206/shadow/update/accepted',32,'These are published data from client' //Disconnect a client from MQTT server. AT+QMTDISC=0 OK +QMTDISC: 0,0 NOTE SSL authentication is optional for different module models. For more details, please contact Quectel Technical Support. EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 35 / 36 LTE Standard Module Series 6 Appendix References Table 5: Related Document Document Name [1] Quectel_EC200x&EG800K&EG810M&EG91xN&EG912Y_Series_SSL_Application_Note [2] Quectel_EG950A_Series_SSL_Application_Note Table 6: Terms and Abbreviations Abbreviation ACK CA IP MQTT PDP QoS RTC SSL TCP UFS URC Description Acknowledgement Certificate Authority Internet Protocol Message Queuing Telemetry Transport Packet Data Protocol Quality of Service Real-Time Clock Secure Sockets Layer Transmission Control Protocol User File System Unsolicited Result Code EC200x&EG800K&EG810M&EG91xN&EG912Y&EG950A_Series_MQTT_Application_Note 36 / 36
457.60 KB
EG512R&EM12xR&EM160R Series RF FTM Application Note LTE-A Module Series Version: 1.0 Date: 2023-10-16 Status: Released LTE-A Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 1 / 15 LTE-A Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2023. All rights reserved. EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 2 / 15 LTE-A Module Series About the Document Revision History Version Date Author - 2021-12-15 Kevin LI 1.0 2023-10-16 Kevin LI Description Creation of the document First official release EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 3 / 15 LTE-A Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 1.1. Applicable Modules .................................................................................................................... 6 2 Description of AT Commands ........................................................................................................... 7 1.2. AT Command Introduction ......................................................................................................... 7 Definitions........................................................................................................................ 7 AT Command Syntax ...................................................................................................... 7 1.3. Declaration of AT Command Examples ..................................................................................... 8 1.4. Description of RF FTM AT Commands ...................................................................................... 8 AT+QRFTEST RF Test in FTM..................................................................................... 8 CMW500 Configuration for RX Test.............................................................................. 13 3 Example ............................................................................................................................................. 14 4 Appendix ............................................................................................................................................ 15 EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 4 / 15 LTE-A Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 6 Table 2: Type of AT Commands and Responses ......................................................................................... 7 Table 3: RX/TX Channel Distribution of LTE/WCDMA Bands.................................................................... 10 Table 4: Terms and Abbreviations .............................................................................................................. 15 EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 5 / 15 LTE-A Module Series 1 Introduction The document describes the AT commands that are used to test the receiving and transmitting performance of Quectel LTE-A series modules in FTM (Factory Test Mode), to facilitate RF calibration. 1.1. Applicable Modules Table 1: Applicable Modules Module Family EM12xR - Module EM120R-GL EM121R-GL EM160R-GL EG512R-EA EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 6 / 15 LTE-A Module Series 2 Description of AT Commands 1.2. AT Command Introduction 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 settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 2: Type of AT Commands and Responses 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 + < c m d > = < p 1 > [ , < p 2 > [ , < p 3 > Set user-definable parameter value. [...]]] Execution Command AT+ Return a specific information parameter or perform a specific action. EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 7 / 15 LTE-A Module Series 1.3. 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. 1.4. Description of RF FTM AT Commands AT+QRFTEST RF Test in FTM AT+QRFTEST RF Test in FTM Test Command AT+QRFTEST=? Response +QRFTEST: 'rx',,,,,, +QRFTEST: 'tx',,,,,, +QRFTEST: 'mode',(list of supported s) Write Command Query/Set FTM AT+QRFTEST='mode'[,] OK Response If the optional parameter is omitted, query the current setting: +QRFTEST: OK If the optional parameter is specified, set FTM mode: OK Write Command Receiving Test in FTM AT+QRFTEST='rx',,, ,,, Write Command Transmitting Test in FTM If there is any error: ERROR Response +QRFTEST: 'rx',, OK If there is any error: ERROR Response OK EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 8 / 15 LTE-A Module Series AT+QRFTEST='tx',,, ,,, Or ERROR Maximum Response Time Characteristics 300 ms This command takes effect immediately; The configurations are not saved. Parameter Integer type. RF test mode. 0 Online mode 1 FTM mode Integer type. LTE/WCDMA configuration. 0 WCDMA 1 LTE Integer type. LTE/WCDMA Band. 1 LTE B1/WCDMA B1 2 LTE B2/WCDMA B2 3 LTE B3/WCDMA B3 4 LTE B4/WCDMA B4 5 LTE B5/WCDMA B5 6 LTE B6/WCDMA B6 7 LTE B7/WCDMA B7 8 LTE B8/WCDMA B8 9 LTE B9/WCDMA B9 10 LTE B10/WCDMA B10 11 LTE B11/WCDMA B11 ...... 19 LTE B19/WCDMA B19 20 LTE B20 28 LTE B28 ...... Integer type. LTE/WCDMA bandwidth. 0 1.4 MHz 1 3 MHz 2 5 MHz 3 10 MHz 4 15 MHz 5 20 MHz 6 40 MHz Integer type. RX/TX channel. See table 3 for details. Integer type. Receiving antenna index. EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 9 / 15 LTE-A Module Series 0 PRX 1 DRX Integer type. Expected value of RX AGC. The value of this parameter should be the signal strength sent that set on the radio communication tester in dBm × 10; For example, if the signal strength sent on the radio communication tester is -60 dBm, the is set to -600. Integer type. Tested value of RX AGC. Unit: dBm. Integer type. Tested gain. The value is /10. Unit: dBm. Integer type. Enable/disable TX. 0 Disable 1 Enable Integer type. Transceiver output gain. This parameter has a positive correlation with the actual TX power. The maximum value is 100. Table 3: RX/TX Channel Distribution of LTE/WCDMA Bands LTE/WCDMA bands LTE B1 Range of RX channels Minimum-Median-Maximum 0–300–599 LTE B2 600–900–1199 LTE B3 1200–1575–1949 LTE B4 1950–2175–2399 LTE B5 2400–2525–2649 LTE B6 2650–2700–2749 LTE B7 2750–3100–3449 LTE B8 3450–3625–3799 LTE B9 3800–3975–4149 LTE B10 4150–4450–4749 LTE B11 4750–4850–4949 LTE B12 5010–5095–5179 LTE B13 5180–5230–5279 LTE B14 5280–5330–5379 Range of TX channels Minimum-Median-Maximum 18000–18300–18599 18600–18900–19199 19200–19575–19949 19950–20175–20339 20400–20525–20649 20650–20700–20749 20750–21100–21449 21450–21625–21799 21800–21975–22149 22150–22450–22749 22750–22850–22949 23000–23095–23179 23180–23230–23279 23280–23330–23379 EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 10 / 15 LTE B17 LTE B18 LTE B19 LTE B20 LTE B21 LTE B22 LTE B23 LTE B24 LTE B25 LTE B26 LTE B27 LTE B28 LTE B29 LTE B30 LTE B31 LTE B32 LTE B33 LTE B34 LTE B35 LTE B36 LTE B37 LTE B38 LTE B39 LTE B40 LTE B41 5730–5790–5849 5850–5925–5999 6000–6075–6149 6150–6300–6449 6450–6525–6599 6600–7000–7399 7500–7600–7699 7700–7870–8039 8040–8365–8689 8690–8865–9039 9040–9125–9209 9210–9435–9659 9660–9715–9769 9770–9820–9869 9870–9895–9919 9920–10140–10359 36000–36100–36199 36200–36275–36349 36350–36650–36949 36950–37250–37549 37550–37650–37749 37750–38000–38249 38250–38450–38649 38650–39150–39649 39650–40620–41589 LTE-A Module Series 23730–23790–23849 23850–23925–23999 24000–24075–24149 24150–24300–24449 24450–24525–24599 24600–25000–25399 25500–25600–25699 25700–25870–26039 26040–26365–26689 26690–26865–27039 27040–27125–27209 27210–27435–27659 NA 27660–27710–27759 27760–27785–27809 NA 36000–36100–36199 36200–36275–36349 36350–36650–36949 36950–37250–37549 37550–37650–37749 37750–38000–38249 38250–38450–38649 38650–39150–39649 39650–40620–41589 EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 11 / 15 LTE B42 LTE B43 LTE B46 LTE B47 LTE B48 LTE B66 LTE B71 WCDMA B1 WCDMA B2 WCDMA B3 WCDMA B4 WCDMA B5 WCDMA B6 WCDMA B7 WCDMA B8 WCDMA B9 WCDMA B10 WCDMA B11 WCDMA B19 41590–42590–43589 43590–44590–45589 46790–50665–54539 54540–54885–55239 55240–55940–56739 66436–66886–67335 68586–68761–68935 10562–10700~10838 9662–9800–9938 1162–1338–1513 1537–1638–1738 4357–4408–4458 4387–4400–4413 2237–2400–2563 2937–3012–3088 9237–9312–9387 3112–3250–3388 3712–3762–3812 712–738–763 LTE-A Module Series 41590–42590–43589 43590–44590–45589 46790–50665–54539 54540–54885–55239 55240–55940–56739 131972–132322–132671 133122–133297–133471 9612–9750–9888 9262–9400–9538 937–1112–1288 1312–1412–1513 4132–4182–4233 4162–4175–4188 2012–2175–2338 2712–2788–2863 8762–8837–8912 2887–3025–3163 3487–3537–3587 312–338–363 NOTE 1. After each RF test of a network mode (LTE/WCDMA) is performed, it is necessary to execute AT+QRFTEST='mode',0 to exit FTM mode and reboot the module manually before performing the RF test of the next network mode. 2. The RX/TX test in FTM mode is a non-signaling test, and it is forbidden to insert a SIM card during the test. EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 12 / 15 LTE-A Module Series CMW500 Configuration for RX Test Signal sources which emit continuous waves can be used as the downlink CW signals. If you use the CMW500 to test the receiving performance, the following settings can be applied: Figure 1: CMW500 Configuration EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 13 / 15 LTE-A Module Series 3 Example AT+QRFTEST=? +QRFTEST: 'rx',,,,,, +QRFTEST: 'tx',,,,,, +QRFTEST: 'mode',(0,1) OK //RF Test in FTM for WCDMA AT+QRFTEST='mode',1 OK AT+QRFTEST='rx',0,1,2,10700,0,-600 +QRFTEST: 'rx',-1011,-101 OK AT+QRFTEST='rx',0,1,2,10700,1,-600 +QRFTEST: 'rx',-997,99 OK AT+QRFTEST='mode',0 OK //Reboot the module manually. //RF Test in FTM for LTE AT+QRFTEST='mode',1 OK AT+QRFTEST='rx',1,1,3,300,0,-600 +QRFTEST: 'rx',-867,-86 OK AT+QRFTEST='rx',1,1,3,300,1,-600 +QRFTEST: 'rx',-946,-94 OK AT+QRFTEST='tx',1,1,3,18300,1,50 OK AT+QRFTEST='mode',0 OK EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 14 / 15 LTE-A Module Series 4 Appendix Table 4: Terms and Abbreviations Abbreviation AGC CW DRX FTM LTE PRX RF RX TX WCDMA Description Automatic Gain Control Continuous Wave Discontinuous Reception Factory Test Mode Long Term Evolution Primary Receive Radio Frequency Receive Transmit Wideband Code Division Multiple Access EG512R&EM12xR&EM160R_Series_RF_FTM_Application_Note 15 / 15
339.86 KB
EM12&EG12&EG18 Series RF FTM Application Note LTE-A Module Series Version: 1.0 Date: 2023-10-12 Status: Released EM12&EG12&EG18_Series_RF_FTM_Application_Note 1 / 15 LTE-A Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. EM12&EG12&EG18_Series_RF_FTM_Application_Note 1 / 15 LTE-A Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2023. All rights reserved. EM12&EG12&EG18_Series_RF_FTM_Application_Note 2 / 15 LTE-A Module Series About the Document Revision History Version Date Author - 2023-07-10 Kevin LI 1.0 2023-10-12 Kevin LI Description Creation of the document First official release EM12&EG12&EG18_Series_RF_FTM_Application_Note 3 / 15 LTE-A Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 Description of RF FTM AT Commands ............................................................................................. 7 2.1. AT Command Introduction ......................................................................................................... 7 Definitions........................................................................................................................ 7 AT Command Syntax ...................................................................................................... 7 2.2. Declaration of AT Command Examples ..................................................................................... 8 2.3. Description of AT Commands .................................................................................................... 8 AT+QRFTEST RF Test in FTM for LTE ........................................................................ 8 Example ............................................................................................................................................. 13 Appendix ............................................................................................................................................ 15 EM12&EG12&EG18_Series_RF_FTM_Application_Note 4 / 15 LTE-A Module Series Table Index Table 1: Type of AT Commands and Responses ......................................................................................... 7 Table 2: RX/TX Channel Distribution of LTE Band .................................................................................... 10 Table 3: Terms and Abbreviations .............................................................................................................. 15 EM12&EG12&EG18_Series_RF_FTM_Application_Note 5 / 15 LTE-A Module Series 1 Introduction The document describes the AT commands that are used to test the receiving and transmitting performance of Quectel LTE-A series module in FTM (Factory Test Mode), to facilitate RF calibration. Applicable modules are listed as follows: ⚫ EM12-G ⚫ EG12 Series ⚫ EG18 Series EM12&EG12&EG18_Series_RF_FTM_Application_Note 6 / 15 LTE-A Module Series 2 Description of RF FTM AT Commands 2.1. AT Command Introduction 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. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 1: Type of AT Commands and Responses Command Type Syntax Description Test Command 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 + < c m d > = < p 1 > [ , < p 2 > [ , < p 3 > Set user-definable parameter value. [...]]] Execution Command AT+ Return a specific information parameter or perform a specific action. EM12&EG12&EG18_Series_RF_FTM_Application_Note 7 / 15 LTE-A Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about how to use the AT commands introduced herein. The examples, however, should not be taken as Quectel’s 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 AT+QRFTEST RF RX/TX Test in FTM for LTE AT+QRFTEST RF RX/TX Test in FTM for LTE Test Command AT+QRFTEST=? Response +QRFTEST: 'rx',,,,, +QRFTEST: 'tx',,,,,,,, +QRFTEST: 'mode',(list of supported s) Write Command Query/Set FTM AT+QRFTEST='mode'[,] OK Response If the optional parameter is omitted, query the current setting: +QRFTEST: OK If the optional parameter is specified, set FTM mode: OK Write Command Receiving Test in FTM AT+QRFTEST='rx',,,< channel>,, If there is any error: ERROR Response +QRFTEST: ,,,, OK Write Command If there is any error: ERROR Response EM12&EG12&EG18_Series_RF_FTM_Application_Note 8 / 15 LTE-A Module Series Transmitting Test in FTM AT+QRFTEST='tx',,,< channel>,,[, ,,] OK Or ERROR Maximum Response Time Characteristics 300 ms This command takes effect immediately; The configurations are not saved. Parameter Integer type. RF test mode. 0 Online mode 1 FTM mode Integer type. LTE band. 1 LTE B1 2 LTE B2 … … 42 LTE B42 43 LTE B43 44 LTE B44 48 LTE B48 66 LTE B66 71 LTE B71 Integer type. LTE bandwidth. 0 1.4 MHz 1 3 MHz 2 5 MHz 3 10 MHz 4 15 MHz 5 20 MHz 6 40 MHz Integer type. RX/TX channel. See table 2 for details. Integer type. Receiving antenna index. 0 PRX 1 DRX 2 RX2 3 RX3 Integer type. Expected value of RX AGC. This value should be the signal strengthh sent that set on the radio communication tester in dBm × 10; For example, if thee signal strength sent by the radio communication tester is -60 dBm,e is set to -600. EM12&EG12&EG18_Series_RF_FTM_Application_Note 9 / 15 LTE-A Module Series Integer type. Tested value of RX AGC. Unit: dBm. Integer type. LNA gain state. Range: 0–7. Integer type. Estimated sensitivity. Unit: dBm. Integer type. Carrier-to-noise. Value returned is 10 × carrier-to-noise in dB. Integer type. Peak frequency. Unit: Hz. Integer type. Enable/disable TX. 0 Disable 1 Enable Integer type. TX power. Unit: dBm × 10. Integer type. Start position of LTE RB allocation. The minimum value is 0; the maximum value is 1 less than the number of RB allocation supported by LTE band. Integer type. Number of LTE RB allocation. Minimum value is 1; Maximum value is the difference between the number of RBs allocated by LTE band and . Integer type. TX Waveform. 0 QPSK 1 16 QAM 2 64 QAM 3 256 QAM Table 2: RX/TX Channel Distribution of LTE Band LTE Band LTE B1 RX Channel Minimum–Median–Maximum 0–300–599 LTE B2 600–900–1199 LTE B3 1200–1575–1949 LTE B4 1950–2175–2399 LTE B5 2400–2525–2649 LTE B6 2650–2700–2749 LTE B7 2750–3100–3449 LTE B8 3450–3625–3799 LTE B9 3800–3975–4149 LTE B10 4150–4450–4749 LTE B11 4750–4850–4949 TX Channel Minimum–Median–Maximum 18000–18300–18599 18600–18900–19199 19200–19575–19949 19950–20175–20339 20400–20525–20649 20650–20700–20749 20750–21100–21449 21450–21625–21799 21800–21975–22149 22150–22450–22749 22750–22850–22949 EM12&EG12&EG18_Series_RF_FTM_Application_Note 10 / 15 LTE B12 LTE B13 LTE B14 LTE B17 LTE B18 LTE B19 LTE B20 LTE B21 LTE B22 LTE B23 LTE B24 LTE B25 LTE B26 LTE B27 LTE B28 LTE B30 LTE B31 LTE B33 LTE B34 LTE B35 LTE B36 LTE B37 LTE B38 LTE B39 LTE B40 5000–5095–5179 5180–5230–5279 5280–5330–5379 5730–5790–5849 5850–5925–5999 6000–6075–6149 6150–6300–6449 6450–6525–6599 6600–7000–7399 7500–7600–7699 7700–7870–8039 8040–8365–8689 8690–8865–9039 9040–9125–9209 9210–9435–9659 9770–9820–9869 9870–9895–9919 36000–36100–36199 36200–36275–36349 36350–36650–36949 36950–37250–37549 37550–37650–37749 37750–38000–38249 38250–38450–38649 38650–39150–39649 LTE-A Module Series 23000–23095–23179 23180–23230–23279 23280–23330–23379 23730–23790–23849 23850–23925–23999 24000–24075–24149 24150–24300–24449 24450–24525–24599 24600–25000–25399 25500–25600–25699 25700–25870–26039 26040–26365–26689 26690–26865–27039 27040–27125–27209 27210–27435–27659 27660–27710–27759 27760–27785–27809 36000–36100–36199 36200–36275–36349 36350–36650–36949 36950–37250–37549 37550–37650–37749 37750–38000–38249 38250–38450–38649 38650–39150–39649 EM12&EG12&EG18_Series_RF_FTM_Application_Note 11 / 15 LTE B41 LTE B42 LTE B43 LTE B48 LTE B66 LTE B71 39650–40620–41589 41590–42590–43589 43590–44590–45589 55240–55940–56739 66436–66886–67335 68586–68761–68935 LTE-A Module Series 39650–40620–41589 41590–42590–43589 43590–44590–45589 55240–55940–56739 131972–132322–132671 133122–133297–133471 NOTE 1. Before conducting RX/TX tests, execute AT+QRFTEST='mode',1 to set the module to FTM mode; after the test, execute AT+QRFTEST='mode',0 to exit FTM mode; reboot the module manually after all RX/TX tests are finished. 2. RF test in FTM mode is a non-signaling test, and it is forbidden to insert a SIM card during the test. 3. If you need to perform the RX/TX test of multiple bands or channels, it is recommended to test RX and TX separately, and reboot the module manually before switching between TX and RX tests. 4. For the TX test of a specific band/channel, after setting to 1 to enable the TX function and testing the TX power, set to 0 to disable the TX function for that particular band/channel before performing other tests. EM12&EG12&EG18_Series_RF_FTM_Application_Note 12 / 15 LTE-A Module Series 3 Example AT+QRFTEST=? +QRFTEST: 'rx',,,,, +QRFTEST: 'tx',,,,,,,, +QRFTEST: 'mode',(0,1) OK AT+QRFTEST='mode',1 OK AT+QRFTEST='mode' +QRFTEST: 1 OK AT+QRFTEST='rx',3,3,1575,0,-600 +QRFTEST: -60.5,1,-46.57,-14.42,859708 OK AT+QRFTEST='tx',3,3,19575,1,150 OK AT+QRFTEST='tx',3,3,19575,0,150 OK AT+QRFTEST='rx',42,3,42590,0,-50 +QRFTEST: -61.7,7,-73.83,-12.16,5469340 OK AT+QRFTEST='tx',42,3,42590,1,150 OK //Recommended test procedure: //Enter into FTM mode: AT+QRFTEST='mode',1 OK //Test TX for all required bands (please note that it requires to disable the current band before testing the next band): AT+QRFTEST='tx',2,3,18900,1,150 OK EM12&EG12&EG18_Series_RF_FTM_Application_Note 13 / 15 AT+QRFTEST='tx',2,3,18900,0,150 OK AT+QRFTEST='tx',5,3,20525,1,150 OK AT+QRFTEST='tx',5,3,20525,0,150 OK …… //Exit FTM mode; AT+QRFTEST='mode',0 OK //Reboot the module manually //Enter into FTM mode AT+QRFTEST='mode',1 OK //Test RX for all required bands AT+QRFTEST='rx',2,3,900,0,-600 +QRFTEST: -59.9,1,-98.38,37.38,2002144 OK AT+QRFTEST='rx',5,3,2525,0,-600 +QRFTEST: -62.2,1,-44.85,-16.14,1701260 OK …… //Exit FTM mode AT+QRFTEST='mode',0 OK //Reboot the module manually for next step LTE-A Module Series EM12&EG12&EG18_Series_RF_FTM_Application_Note 14 / 15 4 Appendix Table 3: Terms and Abbreviations Abbreviation AGC DRX FTM LNA LTE PRX QAM QPSK RB RF RX TX Description Automatic Gain Control Discontinuous Reception Factory Test Mode Low Noise Amplifier Long Term Evolution Primary Receive Quadrature Amplitude Modulation Quadrature Phase Shift Keying Resource Block Radio Frequency Receive Transmit LTE-A Module Series EM12&EG12&EG18_Series_RF_FTM_Application_Note 15 / 15
277.29 KB
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
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
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
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
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
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
451.73 KB
L89 R2.0&LC29H Series&LC79H (AL) I2C Application Note GNSS Module Series Version: 1.2 Date: 2023-12-05 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 / 32 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 / 32 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 1.2 2023-12-05 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 4). 1. Added applicable variant LC29H (AI). 2. Updated note on length of data read by the master (Chapter 3.1). 3. Updated data reading flow of master (Figure 8). 4. Added I2C read/write example (Chapter 5). L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 3 / 32 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 I2C Read/Write Operation ...............................................................................................................12 3.1. Master Data Reading Flow .....................................................................................................12 3.2. Master Data Writing Flow .......................................................................................................16 4 I2C Multi-Slave Operation...............................................................................................................19 5 I2C Read/Write Example .................................................................................................................23 6 Sample Code for I2C Reading/Writing Sequence.........................................................................25 7 Appendix References .....................................................................................................................32 L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 4 / 32 GNSS Module Series Table Index Table 1: Applicable Modules ...................................................................................................................... 7 Table 2: Related Documents ................................................................................................................... 32 Table 3: Terms and Abbreviations............................................................................................................ 32 L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 5 / 32 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.............................................................................................. 16 Figure 10: Master Data Writing Flow Step 2 ............................................................................................ 17 Figure 11: Master Data Writing Flow ....................................................................................................... 18 Figure 12: Multi-Slave Operation Sequence on I2C Bus ......................................................................... 19 Figure 13: Multi-Slave Operation on I2C Bus Example 1 ........................................................................ 20 Figure 14: Incorrect Multi-Slave Operation Sequence on I2C Bus .......................................................... 21 Figure 15: Multi-Slave Operation on I2C Bus Example 2 ........................................................................ 22 L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 6 / 32 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. Three device addresses are provided, namely configuration read/write address 0x50, read address 0x54, and write address 0x58. ⚫ 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 flow charts, example 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 (AI) LC29H (BA) LC29H (BS) LC29H (CA) LC29H (DA) LC79H (AL) L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 7 / 32 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 / 32 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. 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 / 32 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 / 32 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 / 32 GNSS Module Series 3 I2C Read/Write Operation The following chapter provides a detailed explanation on how the master reads and writes messages 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. 3.1. Master Data Reading Flow The master reads data as follows: Step 1 Master reads data length from the slave transmit buffer. a) Master sends a configuration read command to the slave. ⚫ 7-bit slave address (0x50) and write bit. ⚫ Two data words: 0xAA510008 and 0x00000004 (little-endian transmission). b) Master reads the data length from the slave transmit buffer. ⚫ 7-bit slave address (0x54) and read bit. ⚫ Master retrieves the data length from the slave transmit buffer. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 12 / 32 GNSS Module Series Data (8 bytes) DEVICE ADDRESS and Write bit 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 and Read bit 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 Master reads data_read_len 1) bytes of data. a) Master sends configuration read command to the slave. ⚫ 7-bit slave address (0x50) and write bit. ⚫ Two data words: 0xAA512000 and data_read_len 1) (little-endian transmission). b) Master reads the data_read_len 1) bytes of data. ⚫ 7-bit slave address (0x54) and read bit. ⚫ Master receives the data_read_len 1) bytes of data. L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 13 / 32 GNSS Module Series Data (8 bytes) DEVICE ADDRESS and Write bit 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 and Read bit 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 read. The value of data_read_len should be less than or equal to the length read in Step 1. If the data length read from the module I2C transmit buffer exceeds data_read_len, you can repeat Step 2 until all data have been read. However, the total length of the data read by the master cannot exceed the data length read in 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 data 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 / 32 GNSS Module Series Master Slave Delay 1) If the data length is 0, read it again. Slave address (0x50) and write bit Sends two words of data: 0xAA510008 and 0x00000004 Delay 1) Slave address (0x54) and read bit Receives the data length Delay 1) Slave address (0x50) and write bit Sends two words of data: 0xAA512000 and data_read_len Delay 1) Slave address (0x54) and read bit 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 / 32 GNSS Module Series 3.2. Master Data Writing Flow The master writes data as follows: Step 1 Master reads the available free length in the slave receive buffer. a) Master sends a configuration read command to the slave. ⚫ 7-bit slave address (0x50) and write bit. ⚫ Two data words: 0xAA510004 and 0x00000004 (little-endian transmission). b) Master reads the free length from the slave receive buffer. ⚫ 7-bit slave address (0x54) and read bit. ⚫ Master receives the free length from the slave receive buffer. Data (8 bytes) DEVICE ADDRESS and Write bit 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 and Read bit S T MASTER A R T (0x54<<1) | 0x01 A SLAVE C K Free Length in slave receive buffer (4 bytes) A A A C C C K K K DATA 1 DATA 2 DATA 3 DATA 4 S NAK T O P Figure 9: Master Data Writing Flow Step 1 L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 16 / 32 GNSS Module Series Step 2 Master writes data_written_len 1) bytes of data. a) Master sends configuration write command to the slave. ⚫ 7-bit slave address (0x50) and write bit. ⚫ Two data words: 0xAA531000 and data_written_len 1) (little-endian transmission). b) Master writes data_written_len 1) bytes of data. ⚫ 7-bit slave address (0x58) and write bit. ⚫ Master writes data_written_len 1) bytes of data. Data (8 bytes) DEVICE ADDRESS and Write bit 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 and Write bit S T MASTER A R T (0x58<<1) & 0xFE DATA 1 Data (data_written_len bytes) 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, you need 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 17 / 32 GNSS Module Series Master Slave Delay 1) Slave address (0x50) and write bit Sends two words of data: 0xAA510004 and 0x00000004 Delay 1) Slave address (0x54) and read bit Receives the free length Delay 1) Slave address (0x50) and write bit Sends two words of data: 0xAA531000 and data_written_len Delay 1) Slave address (0x58) and write bit 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 18 / 32 GNSS Module Series 4 I2C 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 3.2 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 can 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 19 / 32 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 20 / 32 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 21 / 32 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 22 / 32 GNSS Module Series 5 I2C Read/Write Example An example of reading NMEA data and writing data through the I2C interface on the LC29H (BA) module is as follows. //Data Reading Example. //Step 1-a: Master sends a read command to the slave. A0 08 00 51 AA 04 00 00 00 //Step 1-b: Master receives the data length from the slave transmit buffer. If the data length is 0, return to Step 1-a. A9 FC 09 00 00 //Step 2-a: Master sends a read command to the slave. The read length is configured to 0x00000400. A0 00 20 51 AA 00 04 00 00 //Step 2-b: Master reads NMEA data, and the length is 0x00000400. A9 24 50 51 54 4D 56 45 52 2C 4D 4F 44 55 4C 45 5F…… //Step 2-a: Master sends a read command to the slave. The read length is configured to 0x00000400. A0 00 20 51 AA 00 04 00 00 //Step 2-b: Master reads NMEA data, and the length is 0x00000400. A9 43 0D 0A 24 47 4E 56 54 47 2C 2C 54 2C 2C 4D 2C…… //Step 2-a: Master sends a read command to the slave. The read length is configured to 0x000001FC. A0 00 20 51 AA FC 01 00 00 //Step 2-b: Master reads NMEA data, and the length is 0x000001FC. A9 42 47 53 56 2C 31 2C 31 2C 30 30 2C 35 2A 37 32…… //Data Writing Example: 15-byte message $PQTMVERNO*58rn //Step 1-a: Master sends a read command to the slave. A0 04 00 51 AA 04 00 00 00 //Step 1-b: Master receives the free length from the slave receive buffer. As the read free length (0x00000003) is less than the length of message to be sent (0x0000000F), split the message before sending. A9 03 00 00 00 //Step 2-a: Master sends a write command to the slave to configure the write length as 0x00000003. A0 00 10 53 AA 03 00 00 00 //Step 2-b: Master writes data to the slave, starting from '$PQ'. B0 24 50 51 //Step 1-a: Master sends a read command to the slave. A0 04 00 51 AA 04 00 00 00 //Step 1-b: Master receives the free length from the slave receive buffer. A9 FD F0 00 00 L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 23 / 32 GNSS Module Series //Step 2-a: Master sends a write command to the slave to configure the write length as 0x0000000C. A0 00 10 53 AA 0C 00 00 00 //Step 2-b: Master writes data to the slave, i.e., writing 'TMVERNO*58rn' into it. B0 54 4D 56 45 52 4E 4F 2A 35 38 0D 0A L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 24 / 32 GNSS Module Series 6 Sample Code for I2C Reading/Writing Sequence 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; 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) L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 25 / 32 GNSS Module Series { 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; } Dev_Resp_FlagStatus Quectel_Dev_Receive(uint8_t* pData, uint16_t maxLength, uint16_t* pRecLength) { L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 26 / 32 GNSS Module Series 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; } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 27 / 32 GNSS Module Series } } 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) { delay_ms(10); status = I2c_Master_Receive(QUECTEL_I2C_SLAVE_ADDRESS_R << 1, pBuff, *pRxLength); if(status == I2C_ACK) L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 28 / 32 GNSS Module Series { 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; } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { return DEV_REP_ERROR; L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 29 / 32 GNSS Module Series } } //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) { break; } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 30 / 32 GNSS Module Series { } } 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 31 / 32 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 LSB MCU MSB NAK/NACK NMEA SCL SDA Description Acknowledge Global Navigation Satellite System Inter-Integrated Circuit Least Significant Bit Microcontroller Unit Most Significant Bit Negative Acknowledgement NMEA (National Marine Electronics Association) 0183 Interface Standard Serial Clock Serial Data L89_R2.0&LC29H_Series&LC79H(AL)_I2C_Application_Note 32 / 32
511.72 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
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<=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<=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<=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<=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
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
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
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.
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
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
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
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
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
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 pa