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
EG800Q-EU&EG915Q-NA FTP(S) Application Note LTE Standard Module Series Version: 1.0 Date: 2023-02-07 Status: Released LTE Standard Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 1 / 49 LTE Standard Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2023. All rights reserved. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 2 / 49 LTE Standard Module Series About the Document Revision History Version 1.0 Date 2022-12-06 2023-02-07 Author Description Orange LI/ Lawrence LIU Orange LI/ Lawrence LIU Creation of the document First official release EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 3 / 49 LTE Standard Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 6 1 Introduction ......................................................................................................................................... 7 1.1. AT Command Introduction...................................................................................................... 7 1.1.1. Definitions ......................................................................................................................... 7 1.1.2. AT Command Syntax ........................................................................................................ 7 1.2. Declaration of AT Command Examples ................................................................................. 8 1.3. The Process of Using FTP(S) AT Commands ....................................................................... 8 1.4. Description of Data Mode..................................................................................................... 10 2 Description of FTP(S) AT Commands ............................................................................................ 11 2.1. AT+QFTPCFG Configure Parameters for FTP(S) Server..................................................11 2.2. AT+QFTPOPEN Login to FTP(S) Server .......................................................................... 15 2.3. AT+QFTPCWD Configure the Current Directory on FTP(S) Server ................................. 16 2.4. AT+QFTPPWD Get the Current Directory on FTP(S) Server ........................................... 17 2.5. AT+QFTPPUT Upload a File to FTP(S) Server................................................................. 17 2.6. AT+QFTPGET Download a File from FTP(S) Server........................................................ 19 2.7. AT+QFTPSIZE Get the File Size on FTP(S) Server ......................................................... 21 2.8. AT+QFTPDEL Delete a File on FTP(S) Server ................................................................. 22 2.9. AT+QFTPMKDIR Create a Folder on FTP(S) Server ....................................................... 23 2.10. AT+QFTPRMDIR Delete a Folder on FTP(S) Server........................................................ 24 2.11. AT+QFTPLIST List Content of a Directory on FTP(S) Server........................................... 24 2.12. AT+QFTPNLST List File Names of a Directory on FTP(S) Server ................................... 26 2.13. AT+QFTPMLSD List Standardized File and Directory Information ................................... 27 2.14. AT+QFTPMDTM Get the File Modification Time on FTP(S) Server ................................. 28 2.15. AT+QFTPRENAME Rename a File or Folder on FTP(S) Server...................................... 29 2.16. AT+QFTPLEN Get the Length of Transferred Data .......................................................... 30 2.17. AT+QFTPSTAT Get the Status of FTP(S) Server ............................................................. 31 2.18. AT+QFTPCLOSE Log out from FTP(S) Server................................................................. 31 3 Examples ........................................................................................................................................... 33 3.1. Login to FTP Server ............................................................................................................. 33 3.2. Login to FTPS Server ........................................................................................................... 34 3.3. Folder Operation................................................................................................................... 35 3.4. File Operation ....................................................................................................................... 35 3.5. List File Information or File Names ...................................................................................... 36 3.6. Upload a File to FTP(S) Server ............................................................................................ 38 3.7. Download a File from FTP(S) Server ................................................................................... 39 3.8. Log out from FTP(S) Server ................................................................................................. 41 4 Error Handling ................................................................................................................................... 42 EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 4 / 49 LTE Standard Module Series 4.1. Executing FTP(S) AT Command Fails ................................................................................. 42 4.2. PDP Activation Fails ............................................................................................................. 42 4.3. DNS Parse Fails ................................................................................................................... 42 4.4. Error Response of FTP(S) Server........................................................................................ 43 5 Summary of Error Codes ................................................................................................................. 44 6 Summary of FTP(S) Protocol Error Codes..................................................................................... 46 7 Appendix References ....................................................................................................................... 48 EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 5 / 49 LTE Standard Module Series Table Index Table 1: Types of AT Commands ................................................................................................................. 8 Table 2: Summary of Error Codes.............................................................................................................. 44 Table 3: Summary of FTP(S) Protocol Error Codes................................................................................... 46 Table 4: Related Documents ...................................................................................................................... 48 Table 5: Terms and Abbreviations .............................................................................................................. 48 EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 6 / 49 LTE Standard Module Series 1 Introduction Quectel LTE Standard EG800Q-EU and EG915Q-NA modules support FTP and FTPS file transfer protocols (hereinafter referred to as 'FTP(S)'). The FTP (File Transfer Protocol) is a standard network protocol used for transferring computer files between a client and server on a computer network, with high transmission rate. FTPS (also known as FTP over SSL, and FTP Secure) is an extension to the commonly used File Transfer Protocol (FTP) that adds support for the Transport Layer Security (TLS) and, formerly, the Secure Sockets Layer cryptographic protocols. This document explains how to use the FTP(S) function of the following Quectel modules through AT commands. 1.1. AT Command Introduction 1.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 1.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. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 7 / 49 LTE Standard Module Series Table 1: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. 1.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. 1.3. Using FTP(S) AT Commands As EG800Q-EU and EG915Q-NA modules support FTP(S) protocol, file and directory on FTP(S) server can be operated via FTP(S) AT commands. The general process is as follows: Step 1: Configure and activate a PDP context 1. Configure , , and other parameters of a PDP context by AT+QICSGP. See document [1] for details. 2. Activate the PDP context via AT+QIACT. See document [1] for details. 3. Configure the PDP context ID for FTP(S) by AT+QFTPCFG='contextid',. The PDP context should be activated first. Step 2: Configure user account and FTP(S) server 1. Configure account information by AT+QFTPCFG='account',,. 2. Configure file type by AT+QFTPCFG='filetype',. Either binary data or ASCII files can be transferred between FTP(S) server and client. 3. Configure the transfer mode by AT+QFTPCFG='transmode',. The transfer EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 8 / 49 LTE Standard Module Series mode means either the FTP(S) server or client listens on a port for a data connection. Note that AT+QFTPCFG='transmode',1 must be set for FTP(S) operations, because FTP(S) currently does not support active mode. 4. Configure the response timeout value by AT+QFTPCFG='rsptimeout',. 5. If the module is an FTPS client, execute the following commands: 1) Execute AT+QFTPCFG='ssltype',1. 2) Execute AT+QFTPCFG='sslctxid', to select . 3) Execute AT+QSSLCFG to configure the selected . See document [3] for details. Step 3: Login to FTP(S) server Login to FTP(S) server by AT+QFTPOPEN=,. If URC +QFTPOPEN: 0,0 is returned, it indicates that the operation is successful. Port numbers of FTPS and FTP servers are different. FTPS server port number depends on FTPS server provider, and it is usually 990. Step 4: File operation 1. Set the current directory by AT+QFTPCWD. 2. Upload a file to FTP(S) server. 1) Option 1: Upload a file from UFS by AT+QFUPL, then upload the file to FTP(S) server by AT+QFTPPUT. After successfully uploading the file to FTP(S) server, delete the file by AT+QFDEL. See document [4] for details of AT+QFUPL and AT+QFDEL. 2) Option 2: Upload a file to FTP(S) server through COM port by AT+QFTPPUT, then the module will enter data mode. +++ can be inputted to finish the file uploading process. 3. Download a file from FTP(S) server by AT+QFTPGET. The file can be outputted to COM port or saved to UFS. If the file is outputted to COM port, the module will enter data mode. 4. Get the size of the file on FTP(S) server by AT+QFTPSIZE. 5. Get the length of data transferred between FTP(S) server and client by AT+QFTPLEN. 6. Delete a file on FTP(S) server by AT+QFTPDEL. 7. Rename a file on FTP(S) server by AT+QFTPRENAME. 8. Get the file modification time on FTP(S) server by AT+QFTPMDTM. Step 5: Directory operation on FTP(S) server 1. Set the current directory by AT+QFTPCWD. 2. Create a directory by AT+QFTPMKDIR. 3. List the content of a directory by AT+QFTPLIST. 4. List file names of a directory by AT+QFTPNLST. 5. List standardized file and directory information by AT+QFTPMLSD. 6. Rename a directory by AT+QFTPRENAME. 7. Delete a directory by AT+QFTPRMDIR. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 9 / 49 LTE Standard Module Series Step 6: Close connection with FTP(S) server Close the connection with FTP(S) server by AT+QFTPCLOSE. If +QFTPCLOSE: 0,0 URC is reported, it indicates that the operation is successful. Step 3 to Step 6 can be repeated. Step 7: Deactivate PDP context Deactivate the PDP context by AT+QIDEACT=. See document [1] for details. 1.4. Description of Data Mode The COM port of EG800Q-EU and EG915Q-NA modules has two working modes: AT command mode and data mode. In AT command mode, the data inputted via COM port is regarded as AT command, while in data mode, it is regarded as data. ⚫ Exit Data Mode Input +++ or pull up ''MAIN_DTR'' pin to make the module exit data mode. To prevent +++ from being misinterpreted as data, the following sequence should be followed before using COM port: 1. Do not input any character for at least 1 second before and after inputting +++. 2. Input +++ within 1 s, and wait until OK is returned. Once OK is returned, the COM port exits the data mode and switches to AT command mode. If you are exiting the data mode by pulling the ''MAIN_DTR'' pin up, make sure to set AT&D1 firstly. ⚫ Enter Data Mode Once AT+QFTPPUT, AT+QFTPGET, AT+QFTPLIST, AT+QFTPMLSD and AT+QFTPNLST are executed, if the local file path is 'COM:', which means data will be received from or outputted to COM port, the COM port will enter data mode. If you input +++ or pull the ''MAIN_DTR'' pin up to make the port exit data mode, you can re-enter data mode by executing ATO after executing AT+QFTPGET, AT+QFTPLIST, and AT+QFTPNLST, whereas you cannot re-enter data mode via ATO after executing AT+QFTPPUT. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 10 / 49 LTE Standard Module Series 2 Description of FTP(S) AT Commands 2.1. AT+QFTPCFG Configure Parameters for FTP(S) Server This command configures FTP(S) server parameters, including user account, file type, transfer mode and PCD context ID. AT+QFTPCFG Configure Parameters for FTP(S) Server Test Command AT+QFTPCFG=? Response +QFTPCFG: 'account',, +QFTPCFG: 'ssltype',(range of supported s) +QFTPCFG: 'sslctxid',(range of supported s) +QFTPCFG: 'filetype',(list of supported s) +QFTPCFG: 'transmode',(list of supported s) +QFTPCFG: 'contextid',(range of supported s) +QFTPCFG: 'rsptimeout',(range of supported s) +QFTPCFG: 'data_address',(range of supported < data_address_type>s),(range of supported s) Write Command AT+QFTPCFG='account'[,,< password>] OK Response If the optional parameters are omitted, query the current setting: +QFTPCFG: 'account',, OK If the optional parameters are specified, set the username and password for authentication: OK Or EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 11 / 49 LTE Standard Module Series Write Command AT+QFTPCFG='ssltype'[,] +CME ERROR: Response If the optional parameter is omitted, query the current setting: +QFTPCFG: 'ssltype', OK Write Command AT+QFTPCFG='sslctxid'[,] If the optional parameter is specified, set the SSL type: OK Or +CME ERROR: Response If the optional parameter is omitted, query the current setting: +QFTPCFG: 'sslctxid', OK Write Command AT+QFTPCFG='filetype'[,] If the optional parameter is specified, set the SSL context ID: OK Or +CME ERROR: Response If the optional parameter is omitted, query the current setting: +QFTPCFG: 'filetype', OK Write Command AT+QFTPCFG='transmode'[,] If the optional parameter is specified, set the file type: OK Or +CME ERROR: Response If the optional parameter is omitted, query the current setting: +QFTPCFG: 'transmode', OK If the optional parameter is specified, set the transfer EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 12 / 49 LTE Standard Module Series Write Command AT+QFTPCFG='contextid'[,] mode: OK Or +CME ERROR: Response If the optional parameter is omitted, query the current setting: +QFTPCFG: 'contextid', OK Write Command AT+QFTPCFG='rsptimeout'[,] If the optional parameter is specified, set the context ID: OK Or +CME ERROR: Response If the optional parameter is omitted, query the current setting: +QFTPCFG: 'rsptimeout', OK Write Command AT+QFTPCFG='data_address'[,[,]] If the optional parameter is specified, configure the response timeout: OK Or +CME ERROR: Response If the optional parameters are omitted, query the current setting: 1) If is 2: +QFTPCFG: 'data_address',, OK 2) If is not 2: +QFTPCFG: 'data_address', OK If any of the optional parameters is specified, set the data connection address: OK EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 13 / 49 LTE Standard Module Series Maximum Response Time Characteristics Or +CME ERROR: 300 ms This command takes effect immediately. The configurations are not saved. Parameter String type. Username for authentication. Maximum size: 255 bytes. String type. Password for authentication. Maximum size: 255 bytes. Integer type. Determines whether the module works as FTP or FTPS client. 0 FTP client 1 FTPS implicit encryption 2 FTPS explicit encryption Integer type. SSL context ID. Range: 0–5. Default value: 0. Configure the SSL parameters with AT+QSSLCFG. See document [3] for details. Integer type. Type of transmission data. 0 Binary 1 ASCII Integer type. Determines whether the FTP(S) server or client listens on a port for data connection. 0 Active mode, the module will listen for the data connection from the FTP(S) server on the client port (Not supported currently). 1 Passive mode, the module will listen for the data connection from the client on the FTP(S) server port Integer type. PDP context ID. Range: 1–15. Default value: 1. Activate PDP context ID with AT+QIACT before using AT+QFTPOPEN. See document [1] for details. Integer type. Range: 20–180. Default value: 90. Unit: second. Generally, it is the response timeout value for most +QFTPXXX: xx,xx commands before the OK result code is returned, except for AT+QFTPPUT/QFTPGET/QFTPLST/QFTPNLST/QFTPMLSD. Rules for these four commands are shown below: 1) When the command has been sent, but CONNECT has not been outputted yet, this parameter indicates the response timeout value for CONNECT to be outputted after the command has been sent. 2) When the module has entered data mode, this parameter indicates the maximum interval between two packets of received/transferred data. 3) When is not 'COM:', it indicates the maximum interval between two packets of received/transferred data. Integer type. Determines the FTP(S) data connection address selection. 0 Use server dispatched address 1 Use FTP(S) control session address EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 14 / 49 LTE Standard Module Series 2 Use FTP(S) control session address. If the connection fails, an address assigned by server will be used. Integer type. Time required to switch the address assigned by the server when the FTP(S) control session address connection fails. It is valid only when is 2. Range: 15–50. Default value: 25. Unit: second. Integer type. Result code. See Chapter 5 for details. NOTE Since FTP(S) does not currently support active mode, you must set to 1 when using FTP(S). 2.2. AT+QFTPOPEN Login to FTP(S) Server This command logs in to FTP(S) server. The PDP context should be activated with AT+QIACT first. +QFTPOPEN: , indicates the result of AT+QFTPOPEN and it should be outputted within configured with AT+QFTPCFG. AT+QFTPOPEN Login to FTP(S) Server Test Command AT+QFTPOPEN=? Response +QFTPOPEN: , Write Command AT+QFTPOPEN=[, ] OK Response OK +QFTPOPEN: , Or +CME ERROR: Maximum Response Time Determined by configured via AT+QFTPCFG Characteristics This command takes effect immediately. The configurations are not saved. Parameter String type. IP address and domain name of the FTP(S) server. Maximum size: 255 bytes. Integer type. FTP(S) server port number. Range: 1–65535. Default value: 21. Integer type. Result code. See Chapter 5 for details. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 15 / 49 LTE Standard Module Series Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. NOTE 1. Configure the server address according to your use case. 2. Port numbers of FTPS and FTP servers are different. FTPS server port number depends on FTPS server provider, and it is usually 990. 2.3. AT+QFTPCWD Configure the Current Directory on FTP(S) Server The command configures the current directory on FTP(S) server. If OK is returned, +QFTPCWD: , should be outputted within configured with AT+QFTPCFG. All file and directory operations will be performed in the current directory. AT+QFTPCWD Configure the Current Directory on FTP(S) Server Test Command AT+QFTPCWD=? Response +QFTPCWD: Write Command AT+QFTPCWD= OK Response OK Maximum Response Time Characteristics +QFTPCWD: , Or +CME ERROR: Determined by configured via AT+QFTPCFG This command takes effect immediately. The configuration is not saved. Parameter String type. Directory path on FTP(S) server. Maximum size: 255 bytes. FTP(S) server root path: '/'. Integer type. Result code. See Chapter 5 for details. Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 16 / 49 LTE Standard Module Series 2.4. AT+QFTPPWD Get Current Directory on FTP(S) Server This command retrieves the current directory on FTP(S) server. If OK is returned, +QFTPPWD: 0, or +QFTPPWD: , should be outputted within configured with AT+QFTPCFG. AT+QFTPPWD Get Current Directory on FTP(S) Server Test Command AT+QFTPPWD=? Execution Command AT+QFTPPWD Response OK Response OK If the current directory is retrieved successfully: +QFTPPWD: 0, Maximum Response Time Characteristics If the retrieval of current directory fails: +QFTPPWD: , Or +CME ERROR: Determined by configured via AT+QFTPCFG This command takes effect immediately. The configuration is not saved. Parameter String type. Directory path on FTP(S) server. Maximum size: 255 bytes. FTP(S) server root path: '/'. Integer type. Result code. See Chapter 5 for details. Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. 2.5. AT+QFTPPUT Upload a File to FTP(S) Server This command uploads a file to FTP(S) server. If the file data are uploaded via COM port, then the module will enter data mode. Inputting +++ will abort file uploading. A local file can be uploaded to FTP(S) server, but the file must be a UFS file. A file can be uploaded to UFS with AT+QFUPL, and then uploaded to FTP(S) server via AT+QFTPPUT. After the file is uploaded successfully, the local UFS file can be deleted with AT+QFDEL. See document [4] for details. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 17 / 49 LTE Standard Module Series A file can be uploaded from a specified file position by . If is 'COM:', CONNECT should be outputted within configured with AT+QFTPCFG. If is not 'COM:', OK is outputted first, and then +QFTPPUT: 0, or +QFTPPUT: , is outputted after data transfer is completed. If the module has entered data mode or is not 'COM:', configured with AT+QFTPCFG indicates the maximum interval between two packets of received/transferred data. AT+QFTPPUT Upload a File to FTP(S) Server Test Command AT+QFTPPUT=? Response +QFTPPUT: ,,,, Write Command When is 'COM:', i.e., to input data via COM port AT+QFTPPUT=,[,[,, ]] OK Response If the module enters the data mode successfully CONNECT OK If the file data is uploaded successfully: +QFTPPUT: 0, Write Command When is not 'COM:' AT+QFTPPUT=,[,] If the data upload fails: +QFTPPUT: , Or +CME ERROR: Response OK If the file data is uploaded successfully: +QFTPPUT: 0, Maximum Response Time Characteristics If the data upload fails: +QFTPPUT: , Or +CME ERROR: Determined by configured via AT+QFTPCFG This command takes effect immediately. The configurations are not saved. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 18 / 49 LTE Standard Module Series Parameter String type. File name on FTP(S) server. Maximum size: 255 bytes. String type. Local file name. Maximum size: 63 bytes. If it is 'COM:', the file received by COM port will be uploaded to the FTP(S) server. Otherwise, the file specified by will be uploaded to the FTP(S) server from UFS. After successful uploading, delete the local UFS file with AT+QFDEL. See document [4] for details. Integer type. Start position of the file to be uploaded. Range: 0–4294967295. Default value: 0. If and are specified, should be the position where the data continues to be uploaded to the same file. Unit: byte. Integer type. Length of data to be uploaded. It is valid only when is 'COM:'. When the length of data uploaded via COM port reaches , the module exits data mode. Range: 0–4294967295. Unit: byte. Integer type. Determines whether it is the last data packet to be uploaded. It is valid only when is 'COM:'. 0 Not the last data packet. When the data length reaches , the module exits data mode, and +QFTPPUT: 0, is outputted. In this case, do not disconnect data connection, as the remaining data needs to be uploaded to the same file on FTP(S). 1 The last data packet. When the data length reaches , the module exits data mode and data connection can be disconnected. After that +QFTPPUT: 0, is outputted. Integer type. Length of successfully transferred data. Unit: byte. Integer type. Result code. See Chapter 5 for details. Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. NOTE If and are omitted, all data will be uploaded to FTP(S) server. 2.6. AT+QFTPGET Download a File from FTP(S) Server This command downloads a file from FTP(S) server. The file can be outputted via COM port by AT+QFTPGET=,'COM:'. The module enters data mode on receiving data from the server. After the data is transfer is completed, the module exits data mode automatically and outputs +QFTPGET: 0,. The file can be saved to UFS by AT+QFTPGET=,. After the file transfer is complete, the module outputs +QFTPGET: 0,. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 19 / 49 LTE Standard Module Series If is 'COM:', CONNECT should be outputted within configured with AT+QFTPCFG. If is not 'COM:', OK is outputted first, and then +QFTPGET: 0, or +QFTPGET: , is outputted after data transfer is complete. If the module has entered data mode or is not 'COM:', configured with AT+QFTPCFG indicates the maximum interval between two packets of received/transferred data. AT+QFTPGET Download a File from FTP(S) Server Test Command AT+QFTPGET=? Response +QFTPGET: ,,, Write Command When is 'COM:', i.e., to output data via COM port AT+QFTPGET=,[,[, ]] OK Response CONNECT OK If the file data is downloaded successfully: +QFTPGET: 0, Write Command When is not 'COM:' AT+QFTPGET=,[,] If the data download fails: +QFTPGET: , Or +CME ERROR: Response OK If the file data is downloaded successfully: +QFTPGET: 0, Maximum Response Time Characteristics If the data download fails: +QFTPGET: , Or +CME ERROR: Determined by configured via AT+QFTPCFG This command takes effect immediately. The configurations are not saved. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 20 / 49 LTE Standard Module Series Parameter String type. File name on FTP(S) server. Maximum size: 255 bytes. String type. Local file name. Maximum size: 63 bytes. If it is 'COM:', the file data will be outputted via COM port. If it is not 'COM:', the data will be saved to UFS. Then the file can be read by AT+QFREAD. See document [4] for details. Integer type. Start position of the file to be downloaded. Range: 0–4294967295. Default value: 0. Unit: byte. Integer type. Length of data to be downloaded. It is valid only when is 'COM:'. If this parameter is specified, the module outputs bytes to COM port and exits data mode. Data can be downloaded from by the same AT command if there is any data left. Range: 0–4294967295. Unit: byte. Integer type. Length of actually transferred data. If the length is less than , it means the file transfer is completed. Unit: byte. Integer type. Result code. See Chapter 5 for details. Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. NOTE When is 'COM:', if and are omitted, a whole file will be downloaded from FTP(S) server. 2.7. AT+QFTPSIZE Get File Size on FTP(S) Server This command retrieves the file size on FTP(S) server. If OK is returned, +QFTPSIZE: 0, or +QFTPSIZE: , should be outputted within configured with AT+QFTPCFG. Otherwise, the FTP(S) connection should be disconnected, and the network should be deactivated and reactivated. AT+QFTPSIZE Get File Size on FTP(S) Server Test Command AT+QFTPSIZE=? Response +QFTPSIZE: Write Command AT+QFTPSIZE= OK Response OK If the file size is successfully retrieved: +QFTPSIZE: 0, EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 21 / 49 LTE Standard Module Series Maximum Response Time Characteristics If file size retrieval fails: +QFTPSIZE: , Or +CME ERROR: Determined by configured via AT+QFTPCFG This command takes effect immediately. The configuration is not saved. Parameter String type. File name on FTP(S) server. Maximum size: 255 bytes. Integer type. Size of file on FTP(S) server. Unit: byte. Integer type. Result code. See Chapter 5 for details. Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. 2.8. AT+QFTPDEL Delete a File on FTP(S) Server This command deletes a specified file on FTP(S) server. If OK is returned, +QFTPDEL: , should be outputted within configured with AT+QFTPCFG. Otherwise, the FTP(S) connection should be disconnected, and the network should be deactivated and reactivated. AT+QFTPDEL Delete a File on FTP(S) Server Test Command AT+QFTPDEL=? Response +QFTPDEL: Write Command AT+QFTPDEL= OK Response OK Maximum Response Time Characteristics +QFTPDEL: , Or +CME ERROR: Determined by configured via AT+QFTPCFG / EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 22 / 49 LTE Standard Module Series Parameter String type. File name on FTP(S) server. Maximum size: 255 bytes. Integer type. Result code. See Chapter 5 for details. Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. 2.9. AT+QFTPMKDIR Create a Folder on FTP(S) Server This command creates a folder on FTP(S) server. If OK is returned, +QFTPMKDIR: , should be outputted within configured with AT+QFTPCFG. Otherwise, the FTP(S) connection should be disconnected, and the network should be deactivated and reactivated. AT+QFTPMKDIR Create a Folder on FTP(S) Server Test Command AT+QFTPMKDIR=? Response +QFTPMKDIR: Write Command AT+QFTPMKDIR= OK Response OK Maximum Response Time Characteristics +QFTPMKDIR: , Or +CME ERROR: Determined by configured via AT+QFTPCFG / Parameter String type. Folder name on FTP(S) server. Maximum size: 255 bytes. Integer type. Result code. See Chapter 5 for details. Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 23 / 49 LTE Standard Module Series 2.10. AT+QFTPRMDIR Delete a Folder on FTP(S) Server This command deletes a specified folder on FTP(S) server. If OK is returned, +QFTPRMDIR: , should be outputted within configured with AT+QFTPCFG. Otherwise, the FTP(S) connection should be disconnected and the network should be deactivated and reactivated. AT+QFTPRMDIR Delete a Folder on FTP(S) Server Test Command AT+QFTPRMDIR=? Response +QFTPRMDIR: Write Command AT+QFTPRMDIR= OK Response OK Maximum Response Time Characteristics +QFTPRMDIR: , Or +CME ERROR: Determined by configured via AT+QFTPCFG / Parameter String type. Folder name on FTP(S) server. Maximum size: 255 bytes. Integer type. Result code. See Chapter 5 for details. Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. 2.11. AT+QFTPLIST List Content of a Directory on FTP(S) Server This command lists content of a directory on FTP(S) server. If is 'COM:', CONNECT should be outputted within configured with AT+QFTPCFG. If is not 'COM:', OK is returned first, and then +QFTPLIST: 0, or +QFTPLIST: , is outputted after the content transfer is completed. If the module has entered data mode or is not 'COM:', configured with AT+QFTPCFG indicates the maximum interval between two packets of received/transferred data. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 24 / 49 LTE Standard Module Series AT+QFTPLIST List Content of a Directory on FTP(S) Server Test Command AT+QFTPLIST=? Response +QFTPLIST: , Write Command When is 'COM:' AT+QFTPLIST=[,] OK Response CONNECT OK If the directory content is listed successfully: +QFTPLIST: 0, Write Command When is not 'COM:' AT+QFTPLIST=, If directory content listing fails: +QFTPLIST: , Or +CME ERROR: Response OK If the directory content is listed successfully: +QFTPLIST: 0, Maximum Response Time Characteristics If directory content listing fails: +QFTPLIST: , Or +CME ERROR: Determined by configured via AT+QFTPCFG This command takes effect immediately. The configuration will not be saved. Parameter String type. Folder name on FTP(S) server. Maximum size: 255 bytes. If it is '.', the command will list the content of current directory configured with AT+QFTPCWD. String type. Local file name. Maximum size: 63 bytes. Default value: 'COM:'. If it is 'COM:', the data will be outputted from the COM port. If it is not 'COM:', the data will be saved to UFS, and then the file can be read via AT+QFREAD. See document [4] for details. Integer type. Size of data transferred from FTP(S) server. Unit: byte. Integer type. Result code. See Chapter 5 for details. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 25 / 49 LTE Standard Module Series Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. 2.12. AT+QFTPNLST List File Names of a Directory on FTP(S) Server This command lists file names of a directory on FTP(S) server. If is 'COM:', CONNECT should be outputted within configured with AT+QFTPCFG. If is not 'COM:', OK is returned first. And then +QFTPNLST: 0, or +QFTPNLST: , is outputted after file name transfer is complete. If the module has entered data mode or is not 'COM:', configured with AT+QFTPCFG indicates the maximum interval between two packets of received/transferred data. AT+QFTPNLIST List File Names of a Directory on FTP(S) Server Test Command AT+QFTPNLST=? Response +QFTPNLST: , Write Command When is 'COM:' AT+QFTPNLST=[, ] OK Response CONNECT OK If file names are successfully listed: +QFTPNLST: 0, Write Command When is not 'COM:' AT+QFTPNLST=, If the file name listing fails: +QFTPNLST: , Or +CME ERROR: Response OK If the file names of the directory are successfully listed: +QFTPNLST: 0, If the file name listing fails: +QFTPNLST: , If there is any error: +CME ERROR: EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 26 / 49 LTE Standard Module Series Maximum Response Time Characteristics Determined by configured via AT+QFTPCFG This command takes effect immediately. The configurations are not saved. Parameter String type. Folder name on FTP(S) server. Maximum size: 255 bytes. If it is '.', it will list the file names of the current directory configured with AT+QFTPCWD. String type. Local file name. Maximum size: 63 bytes. Default value: 'COM:'. If it is 'COM:', the data will be outputted from the COM port. If it is not 'COM:', the data can be saved to UFS. Then the file can be read via AT+QFREAD. See document [4] for details. Integer type. Size of data transferred from FTP(S) server. Unit: byte. Integer type. Result code. See Chapter 5 for details. Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. 2.13. AT+QFTPMLSD List Standardized File and Directory Information This command lists standardized file and directory information on FTP(S) server. If is 'COM:', CONNECT should be outputted within configured with AT+QFTPCFG. If is not 'COM:', OK will be returned first. And then +QFTPMLSD: 0, or +QFTPMLSD: , will be outputted after the content has been transferred completely. If the module has entered data mode or is not 'COM:', configured with AT+QFTPCFG indicates the maximum interval between two packets of received/transferred data. AT+QFTPMLSD List Standardized File and Directory Information Test Command AT+QFTPMLSD=? Response +QFTPMLSD: , Write Command When is 'COM:' AT+QFTPMLSD=[,] OK Response CONNECT OK If the standardized file and directory information is successfully listed: +QFTPMLSD: 0, EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 27 / 49 LTE Standard Module Series Write Command When is not 'COM:' AT+QFTPMLSD=, If the standardized file and directory information listing fails: +QFTPMLSD: , Or +CME ERROR: Response OK If the standardized file and directory information is successfully listed: +QFTPMLSD: 0, Maximum Response Time Characteristics If the standardized file and directory information listing fails: +QFTPMLSD: , Or +CME ERROR: Determined by configured via AT+QFTPCFG / Parameter String type. Folder name on FTP(S) server. Maximum size: 255 bytes. If it is '.', it will list standardized file and directory information configured with AT+QFTPCWD. String type. Local file name. Maximum size: 63 bytes. Default value: 'COM:'. If it is 'COM:', the data will be outputted from the COM port. If it is not 'COM:', the data will be saved to UFS and then the file can be read via AT+QFREAD. See document [4] for details. Integer type. Size of data transferred from FTP(S) server. Unit: byte. Integer type. Result code. See Chapter 5 for details. Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. 2.14. AT+QFTPMDTM Get File Modification Time on FTP(S) Server This command gets the file modification time on FTP(S) server. If OK is returned, +QFTPMDTM: 0, or +QFTPMDTM: , should be outputted within configured with AT+QFTPCFG. Otherwise, the FTP(S) connection should be disconnected, and the network should be deactivated and reactivated. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 28 / 49 LTE Standard Module Series AT+QFTPMDTM Get File Modification Time on FTP(S) Server Test Command AT+QFTPMDTM=? Response +QFTPMDTM: Write Command AT+QFTPMDTM= OK Response OK If the file modification time is successfully retrieved: +QFTPMDTM: 0, Maximum Response Time Characteristics If the retrieval of file modification time fails: +QFTPMDTM: , Or +CME ERROR: Determined by configured via AT+QFTPCFG / Parameter String type. File name on FTP(S) server. Maximum size: 255 bytes. String type. File modification time on FTP(S) server. Format: 'YYYYMMDDHHMMSS' or 'YYYYMMDDHHMMSS.NNN'. Integer type. Result code. See Chapter 5 for details. Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. 2.15. AT+QFTPRENAME Rename a File or Folder on FTP(S) Server This command renames a file or folder on FTP(S) server. If OK is returned, +QFTPRENAME: , should be outputted within configured with AT+QFTPCFG. Otherwise, the FTP(S) connection should be disconnected, and the network should be deactivated and reactivated. AT+QFTPRENAME Rename a File or Folder on FTP(S) Server Test Command AT+QFTPRENAME=? Response +QFTPRENAME: , OK EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 29 / 49 LTE Standard Module Series Write Command AT+QFTPRENAME=, Maximum Response Time Response OK +QFTPRENAME: , Or +CME ERROR: Determined by configured via AT+QFTPCFG Characteristics / Parameter String type. Old file name or folder name on FTP(S) server. Maximum size: 255 bytes. String type. New file name or folder name on FTP(S) server. Maximum size: 255 bytes. Integer type. Result code. See Chapter 5 for details. Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. 2.16. AT+QFTPLEN Get Length of Transferred Data This command gets the length of data transferred between the FTP(S) server and client, after executing AT+QFTPPUT, AT+QFTPGET, AT+QFTPNLST or AT+QFTPLIST. AT+QFTPLEN Get Length of Transferred Data Test Command AT+QFTPLEN=? Execution Command AT+QFTPLEN Response OK Response OK Maximum Response Time Characteristics +QFTPLEN: 0, Or +CME ERROR: Determined by configured via AT+QFTPCFG / EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 30 / 49 LTE Standard Module Series Parameter Integer type. Length of data transferred between FTP(S) server and the client. Unit: byte. Integer type. Result code. See Chapter 5 for details. 2.17. AT+QFTPSTAT Get Status of FTP(S) Server This command gets the status of FTP(S) server. AT+QFTPSTAT Get Status of FTP(S) Server Test Command AT+QFTPSTAT=? Execution Command AT+QFTPSTAT Response OK Response OK Maximum Response Time Characteristics +QFTPSTAT: 0, Or +CME ERROR: Determined by configured via AT+QFTPCFG / Parameter Integer type. Current status of FTP(S) server 0 Opening an FTP(S) server 1 FTP(S) server is open and idle 2 Transferring data to FTP(S) server 3 Closing the FTP(S) server 4 FTP(S) server is closed Integer type. Result code. See Chapter 5 for details. 2.18. AT+QFTPCLOSE Log Out from FTP(S) Server This command logs out from FTP(S) server. If OK is returned, +QFTPCLOSE: , should be outputted within configured with AT+QFTPCFG. Otherwise, the network should be deactivated and reactivated. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 31 / 49 LTE Standard Module Series AT+QFTPCLOSE Log Out from FTP(S) Server Test Command AT+QFTPCLOSE=? Execution Command AT+QFTPCLOSE Response OK Response OK Maximum Response Time Characteristics +QFTPCLOSE: , Or +CME ERROR: Determined by configured via AT+QFTPCFG This command takes effect immediately. The configuration is not saved. Parameter Integer type. Result code. See Chapter 5 for details. Integer type. For reference only. Indicates the original error code from FTP(S) server defined in FTP(S) protocol. See Chapter 6 for details. If it is 0, it is invalid. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 32 / 49 LTE Standard Module Series 3 Examples 3.1. Login to FTP Server //Step 1: Configure and activate the PDP context. AT+QICSGP=1,1,'UNINET','','',1 //Set PDP context as 1 and China Unicom APN as 'UNINET'. OK AT+QIACT=1 //Activate PDP context 1. OK //Activated successfully. AT+QIACT? //Query the status of PDP context. +QIACT: 1,1,1,'10.7.157.1' OK AT+QFTPCFG='contextid',1 //Set the PDP context ID as 1. The PDP context ID must be activated first. OK //Step 2: Configure user account and transfer settings. AT+QFTPCFG='account','test','test' //Set username and password. OK AT+QFTPCFG='filetype',1 //Set file type as ASCII. OK AT+QFTPCFG='transmode',1 //Set transfer mode as passive mode. OK AT+QFTPCFG='rsptimeout',90 //Set the response timeout value. OK //Step 3: Login to FTP server. AT+QFTPOPEN='quectel.3322.org',21 OK +QFTPOPEN: 0,0 NOTE 1. The server address in the above example is a demo address, configure the server address according to your use case. 2. Port numbers of FTPS and FTP servers are different. FTPS server port number depends on FTPS EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 33 / 49 server provider, and it is usually 990. LTE Standard Module Series 3.2. Login to FTPS Server //Step 1: Configure and activate the PDP context. AT+QICSGP=1,1,'UNINET','','',1 //Set PDP context as 1 and China Unicom APN as 'UNINET'. OK AT+QIACT=1 //Activate PDP context 1. OK //Activated successfully. AT+QIACT? //Query the status of PDP context. +QIACT: 1,1,1,'10.7.157.1' OK AT+QFTPCFG='contextid',1 //Set the PDP context ID as 1. The PDP context ID must be activated first. OK //Step 2: Configure user account and transfer settings. AT+QFTPCFG='account','test','test' //Set username and password. OK AT+QFTPCFG='filetype',1 //Set file type as ASCII. OK AT+QFTPCFG='transmode',1 //Set transfer mode as passive mode. OK AT+QFTPCFG='rsptimeout',90 //Set the response timeout value. OK //Step 3: Configure FTPS. AT+QFTPCFG='ssltype',1 //Set SSL type as 1 (the module works as FTPS client). OK AT+QFTPCFG='sslctxid',1 //Set SSL context as 1. OK AT+QSSLCFG='ciphersuite',1,0xffff //Set SSL cipher suite type as 0xffff, which supports all cipher suite types. OK AT+QSSLCFG='seclevel',1,0 //Set SSL security level as 0, which means the SSL CA certificate is not needed. OK AT+QSSLCFG='sslversion',1,1 //Set SSL version as 1, which means TLS1.0. OK //Step 4: Log into FTPS server. AT+QFTPOPEN='quectel.3322.org',990 OK +QFTPOPEN: 0,0 EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 34 / 49 LTE Standard Module Series NOTE 1. The server address in the above example is a demo address, configure the server address according to your use case. 2. Port numbers of FTPS and FTP servers are different. FTPS server port number depends on FTPS server provider, and it is usually 990. 3.3. Work with Folders AT+QFTPCWD='/' OK +QFTPCWD: 0,0 AT+QFTPPWD OK +QFTPPWD: 0,'/' AT+QFTPMKDIR='TEST' OK +QFTPMKDIR: 0,0 AT+QFTPRENAME='TEST','TEST_NEW' OK +QFTPRENAME: 0,0 AT+QFTPRMDIR='TEST_NEW' OK +QFTPRMDIR: 0,0 //Set current directory. //Query current directory. //Create a folder as TEST on FTP(S) server. //Rename the folder as TEST_NEW. //Delete the folder TEST_NEW. 3.4. Work with Files AT+QFTPCWD='/' OK +QFTPCWD: 0,0 AT+QFTPPWD OK //Set current directory. //Query current directory. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 35 / 49 LTE Standard Module Series +QFTPPWD: 0,'/' AT+QFTPSIZE='test_my1.txt' OK //Query the size of test_my1.txt on FTP(S) server. +QFTPSIZE: 0,1000 AT+QFTPRENAME='test_my1.txt','test_new.txt' //Rename the file as test_new.txt. OK +QFTPRENAME: 0,0 AT+QFTPMDTM='test_new.txt' OK //Get the file modification time of test_new.txt on FTP(S) server. +QFTPMDTM: 0,'20140708110039' AT+QFTPDEL='test_new.txt' OK //Delete test_new.txt on FTP(S) server. +QFTPDEL: 0,0 3.5. List File Information or File Names of a Directory AT+QFTPCWD='/' OK //Set current directory. +QFTPCWD: 0,0 AT+QFTPLIST='.' CONNECT OK //List the content of current directory on the FTP(S) server and the data is outputted via COM port. +QFTPLIST: 0,1000 AT+QFTPLIST='.','UFS:list.txt' OK //List the content of current directory on the FTP(S) server and save it to UFS as UFS:list.txt. +QFTPLIST: 0,1000 AT+QFTPLIST='TEST_2','COM:' CONNECT OK //List the content of TEST_2 on the FTP(S) server and the data is outputted via COM port. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 36 / 49 LTE Standard Module Series +QFTPLIST: 0,1000 AT+QFTPNLST='.','COM:' CONNECT OK //List file names of current directory on the FTP(S) server and the data is outputted via COM port. +QFTPNLST: 0,1000 AT+QFTPNLST='.','UFS:nlst.txt' OK //List file names of current directory on the FTP(S) server and save them to UFS as UFS:nlst.txt. +QFTPNLST: 0,1000 AT+QFTPNLST='TEST_2','COM:' CONNECT OK //List file names of TEST_2 on the FTP(S) server and the data is outputted via COM port. +QFTPNLST: 0,1000 AT+QFTPMLSD='.','COM:' //List standardized file and directory information of current directory on the FTP(S) server and the data is outputted via COM port. CONNECT OK +QFTPMLSD: 0,1000 AT+QFTPMLSD='.','UFS:nlst.txt' OK //List standardized file and directory information of current directory on the FTP(S) server and save it to UFS as UFS:nlst.txt. +QFTPMLSD: 0,1000 AT+QFTPMLSD='TEST_2','COM:' //List standardized directory information of TEST_2 on the FTP(S) server and the data is outputted via COM port. CONNECT OK +QFTPMLSD: 0,1000 EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 37 / 49 LTE Standard Module Series 3.6. Upload a File to FTP(S) Server AT+QFTPCWD='/' OK //Set the current directory. +QFTPCWD: 0,0 AT+QFTPSTAT +QFTPSTAT: 0,1 //Get the current status of FTP(S) server. //FTP(S) server is open and idle. OK //Upload a file via COM port to the FTP(S) server. AT+QFTPPUT='test_my1.txt','COM:',0 CONNECT +++ OK //All data will be saved as test_my1.txt on FTP(S) server. //Exit the data mode. +QFTPPUT: 0,1000 AT+QFTPLEN OK +QFTPLEN: 0,1000 AT+QFTPSIZE='test_my1.txt' OK +QFTPSIZE: 0,1000 //Upload a file via COM port to the FTP(S) server and the start position is 1000. AT+QFTPPUT='test_my1.txt','COM:',1000 //All data will be saved as test_my1.txt on FTP(S) server. CONNECT +++ //Exit the data mode. OK +QFTPPUT: 0,500 AT+QFTPSIZE='test_my1.txt' OK +QFTPSIZE: 0,1500 //Solution 1: Upload a file via COM port to FTP(S) server twice in 1024-byte chunks. AT+QFTPPUT='test_my1.txt','COM:',0,1024,0 //It is not the last 1024-byte chunk of test_my1.txt. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 38 / 49 LTE Standard Module Series CONNECT OK //Data length reaches 1024 bytes. +QFTPPUT: 0,1024 AT+QFTPPUT='test_my1.txt','COM:',1024,1024,1 CONNECT OK //It is the last 1024-byte chunk of test_my1.txt. //Data length reaches 1024 bytes. +QFTPPUT: 0,1024 //Solution 2: Upload a file from UFS to FTP(S) server. AT+QFUPL='UFS:test_ufs.txt',1000,300,1 CONNECT +QFUPL: 1000,707 //Upload a file to UFS, the file will be saved as test_ufs.txt. Maximum file size is 1000 bytes. In this example, 300 indicates timeout value and 1 indicates ACK mode. See document [4] for details. OK AT+QFLST='*' +QFLST: 'UFS:test_ufs.txt',1000 OK AT+QFTPPUT='test_my1.txt','UFS:test_ufs.txt',0 OK //Upload UFS:test_ufs.txt file to FTP(S) server and save it as test_my1.txt on FTP(S) server. +QFTPPUT: 0,1000 AT+QFDEL='UFS:test_ufs.txt' OK //Delete local UFS file. 3.7. Download a File from FTP(S) Server AT+QFTPCWD='/' OK //Set the current directory. +QFTPCWD: 0,0 //Solution 1: Output downloaded data directly via COM port. //Download a file from FTP(S) server and the data is outputted via COM port. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 39 / 49 LTE Standard Module Series AT+QFTPGET='test_my.txt','COM:' CONNECT OK +QFTPGET: 0,1000 //Download a file from FTP(S) server and the data is outputted via COM port twice in 500-byte chunks. AT+QFTPGET='test.txt','COM:',0,500 //The size of test.txt is 1000 bytes. Download the first 500 bytes. CONNECT OK +QFTPGET: 0,500 AT+QFTPGET='test.txt','COM:',500,500 CONNECT OK //Download the remaining 500 bytes. +QFTPGET: 0,500 //Solution 2: Save downloaded data to UFS file. //Download a file from FTP(S) server and save it to UFS. AT+QFTPGET='test_my1.txt','UFS:test.txt' //Download file and save it to UFS as test.txt. OK +QFTPGET: 0,1000 AT+QFLST='*' +QFLST: UFS:test.txt,1000 OK //Download a file from FTP(S) server and save it to UFS. The start position is 450. AT+QFTPGET='test_my1.txt','UFS:test1.txt',450 //Download file and save it to UFS as test1.txt. OK +QFTPGET: 0,550 AT+QFLST='*' +QFLST: UFS:test.txt,1000 +QFLST: UFS:test1.txt,550 //Query the downloaded file and file size in UFS. OK EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 40 / 49 LTE Standard Module Series 3.8. Log out from FTP(S) Server AT+QFTPCLOSE OK +QFTPCLOSE: 0,0 AT+QIDEACT=1 OK //Log out from FTP(S) server. //Deactivate the PDP context, which was activated for FTP(S). EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 41 / 49 LTE Standard Module Series 4 Error Handling 4.1. Executing FTP(S) AT Command Fails If ERROR response is received from the module after executing FTP(S) AT commands, check whether: 1. the USIM card is inserted, and 2. +CPIN: READY is returned after executing AT+CPIN?. 4.2. PDP Activation Failure If the PDP context activation with AT+QIACT fails, check the following configurations: 1. Query the PS domain status by executing AT+CGATT? to make sure that the PS domain is registered. If not, execute AT+CGATT=1 to attach the PS domain. 2. Query the network registration status with AT+CGREG? and make sure the network is registered. 3. Query the PDP context parameters with AT+QICSGP and make sure the APN of the specified PDP context is set. 4. Make sure the specified PDP context ID is neither used by PPP nor activated via AT+CGACT. 5. The module supports maximum 5 simultaneously activated PDP contexts under the VoLTE function, and maximum 7 under the non-VoLTE function. The number of activated PDP contexts depends on the USIM card. If all above configurations are correct, but PDP context activation with AT+QIACT still fails, reboot the module to resolve this issue. After rebooting the module, check the above configurations at least three times at 10-minute interval to avoid frequent module rebooting. 4.3. DNS Parsing Failure If +QFTPOPEN: 604,0 is returned after executing AT+QFTPOPEN, check the following: 1. Make sure the domain name of FTP(S) server is valid. 2. Query the status of the PDP context with AT+QIACT? to make sure the specified PDP context has EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 42 / 49 been activated successfully. LTE Standard Module Series 4.4. Error Response from FTP(S) Server If in +QFTPXX: , is not 0, it indicates an error code returned by FTP(S) server. You can check the issue based on the protocol error code. For example, if is 530 (not logged in), it indicates or may be wrong. If is 550 (requested action not taken: file unavailable), it means the file or directory may not exist. See RFC959 for details. EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 43 / 49 LTE Standard Module Series 5 Summary of Result Codes The result code indicates an result related to mobile equipment or network. The details about are provided in the following table. Table 2: Summary of Result Codes 0 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 Description of Result Codes Operation successful Unknown error FTP(S) server blocked FTP(S) server busy DNS parse failed Network error Control connection closed. Data connection closed Socket closed by peer Timeout error Invalid parameter Failed to open file File position invalid File error Service not available, closing control connection Open data connection failed Connection closed; transfer aborted Requested file action not taken EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 44 / 49 LTE Standard Module Series 618 Requested action aborted: local error in processing 619 Requested action not taken: insufficient system storage 620 Syntax error, command unrecognized 621 Syntax error in parameters or arguments 622 Command not implemented 623 Bad sequence of commands 624 Command parameter not implemented 625 Not logged in 626 Need account for storing files 627 Requested action not taken 628 Requested action aborted: page type unknown 629 Requested file action aborted 631 SSL authentication failed 632 Source IP address for transmission cannot use 633 Send data failed 634 Receive data failed EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 45 / 49 LTE Standard Module Series 6 Summary of FTP(S) Protocol Error Codes The protocol error code indicates an error response from FTP(S) server. See RFC959 for details. The details about are provided in the following table. Table 3: Summary of FTP(S) Protocol Error Codes 421 425 426 450 451 452 500 501 502 503 504 530 532 550 551 552 Meaning Service not available, closing control connection Open data connection failed Connection closed; transfer aborted Requested file action not taken Requested action aborted: local error in processing Requested action not taken: insufficient system storage Syntax error, command unrecognized Syntax error in parameters or arguments Command not implemented Bad sequence of commands Command parameter not implemented Not logged in Need account for storing files Requested action not taken: file unavailable Requested action aborted: page type unknown Requested file action aborted: exceeded storage allocation EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 46 / 49 LTE Standard Module Series 553 Requested action not taken: file name not allowed EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 47 / 49 LTE Standard Module Series 7 Appendix References Table 4: 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_SSL_Application_Note [4] Quectel_EG800Q-EU&EG915Q-NA_FILE_Application_Note Table 5: Terms and Abbreviations Abbreviation ACK APN ASCII DNS DTR FTP FTPS ID IP PDP PPP Description Acknowledgement Access Point Name American Standard Code for Information Interchange Domain Name Server Data Terminal Ready File Transfer Protocol FTP over SSL/FTP Secure Identifier Internet Protocol Packet Data Protocol Point-to-Point Protocol EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 48 / 49 PS QoS SSL TLS UFS URC USIM VoLTE LTE Standard Module Series Packet Switching Quality of Service Secure Sockets Layer Transport Layer Security Universal Flash Storage Unsolicited Result Code Universal Subscriber Identity Module Voice over Long-Term Evolution EG800Q-EU&EG915Q-NA_Series_FTP(S)_Application_Note 49 / 49
521.22 KB
LG69T (AB) Antenna Detection Application Note GNSS Module Series Version: 1.0 Date: 2022-12-15 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(AB)_Antenna_Detection_Application_Note 1 / 13 GNSS Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. LG69T(AB)_Antenna_Detection_Application_Note 2 / 13 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 precautions by incorporating them 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(AB)_Antenna_Detection_Application_Note 3 / 13 GNSS Module Series About the Document Document Information Title LG69T (AB) Antenna Detection Application Note Subtitle GNSS Module Series Document Type Application Note Document Status Released Revision History Version Date Description - 2022-09-17 Creation of the document 1.0 2022-12-15 First official release LG69T(AB)_Antenna_Detection_Application_Note 4 / 13 GNSS Module Series Contents Safety Information....................................................................................................................................... 3 About the Document ................................................................................................................................... 4 Contents ....................................................................................................................................................... 5 Table Index................................................................................................................................................... 6 Figure Index ................................................................................................................................................. 7 1 Introduction .......................................................................................................................................... 8 2 Reference Design................................................................................................................................. 9 2.1. Block Diagram ........................................................................................................................... 9 2.2. Recommended LDO ............................................................................................................... 10 2.3. Reference Design.................................................................................................................... 11 3 Appendix References ........................................................................................................................ 13 LG69T(AB)_Antenna_Detection_Application_Note 5 / 13 GNSS Module Series Table Index ———— Table 1: Voltage Level of ANT_SENSE, ANT_EN, SENSE and ERR Pins in Different Failure Modes.. 11 Table 2: Resistor Requirements................................................................................................................. 12 Table 3: Related Document ....................................................................................................................... 13 Table 4: Terms and Abbreviations ............................................................................................................. 13 LG69T(AB)_Antenna_Detection_Application_Note 6 / 13 GNSS Module Series Figure Index Figure 1: Block Diagram of Module and LDO .............................................................................................. 9 Figure 2: Output Characteristic of TPS7B7701QPWPRQ1 with Current Sensing .................................... 10 Figure 3: Antenna Detection with LDO Reference Design ........................................................................ 11 LG69T(AB)_Antenna_Detection_Application_Note 7 / 13 GNSS Module Series 1 Introduction Antenna detection is an internal function supported by LG69T (AB) GNSS module. It can identify external active antenna status so that the users can take subsequent action in case of an abnormal state and the module can automatically manage the power supply of the antenna. The details of external active antenna status are listed below: ⚫ Normal condition, i.e., the external active antenna is connected and operates in nominal condition. ⚫ Open-circuit condition, i.e., the external active antenna is disconnected and the LG69T (AB) GNSS module is unable to detect the antenna. ⚫ Short-circuit condition, i.e., the external active antenna exhibits short-circuit behavior, which is usually a symptom of a malfunction. The antenna status is reported by a RTCM message. For more information, see document [1] protocol specification. This application note provides instructions for the hardware schematic, which can be used as a reference for designing your antenna detection function. LG69T(AB)_Antenna_Detection_Application_Note 8 / 13 GNSS Module Series 2 Reference Design 2.1. Block Diagram The following is a block diagram of LG69T (AB) module and an active LDO with current sensing function. The LDO is connected to LG69T (AB) module through ANT_SENSE and ANT_EN pins. L1 + L2 or L1 + L5 Active Antenna 12 V Clean Power Supply Active LDO With Current Sense Antenna Power RF_IN LG69T (AB) ANT_EN ANT_SENSE Output Data UART Figure 1: Block Diagram of Module and LDO ANT_SENSE: The pin is a 10-bit ADC pin with a reference voltage of 2.0 V, which is also the maximum voltage that the pin can withstand. It detects antenna status by detecting the LDO output voltage. ANT_EN: The pin is used for controlling the external active LDO that supplies the antenna. NOTE L1 + L2 and L1 + L5 are supported by different software versions. Contact Quectel Technical Support (support@quectel.com) for more details. LG69T(AB)_Antenna_Detection_Application_Note 9 / 13 GNSS Module Series 2.2. Recommended LDO The recommended active LDO is TPS7B7701QPWPRQ1 produced by TI. The LDO can provide a current-sense voltage scale with a specific output current range. Figure 2: Output Characteristic of TPS7B7701QPWPRQ1 with Current Sensing It allows a full diagnostic of each status (i.e., the Failure Mode listed in Table 1: Voltage Level ———— of ANT_SENSE, ANT_EN, SENSE and ERR Pins in Different Failure Modes). Before the LDO enters the current limit mode, the output current-sense voltage is linearly proportional to the actual load current. During short circuit, thermal-shutdown or short-to-battery conditions, the current sense voltage falls in the range of fault voltage level specified by the external LDO. During short-circuit and current-limit conditions, the voltage of SENSE pin is between 2.4 V to 2.65 V, as shown in Table 1: Voltage Level of ———— ANT_SENSE, ANT_EN, SENSE and ERR Pins in Different Failure Modes. In this case, LG69T (AB) has to disable the LDO power supply by driving the ANT_EN pin low, and the LDO does not output. LG69T(AB)_Antenna_Detection_Application_Note 10 / 13 2.3. Reference Design GNSS Module Series 12 V Clean Power Supply VCC_12V ANT_SENSE R101 R102 0R 18.2K ±1% R103 C101 10 μF 22K ±1% 1 μF C102 5.6K ±1% R104 100R ±1% R105 3K ±1% R106 1 μF C503 LDO IN SENSE_EN SENSE LIM VCC NC NC NC NC NC NC OUT FB EN ERR GND GND R107 0R R108 0R TPS7B7701QPWPRQ1 ANT_EN CUSTOM_GPIO Figure 3: Antenna Detection with LDO Reference Design R110 27K ±1% R109 82K ±1% ANT_5V C104 10 μF The output voltage of SENSE pin of LDO is 0–3.3 V, so the divider circuit must be set to limit the maximum voltage of ANT_SENSE pin of the module. R102 and R103 are used to limit the voltage of ANT_SENSE pin within 1.8 V, as shown in Figure above. ———— The LDO provides diagnostics through SENSE and ERR pins. To monitor the load current, the current sense circuit inside the LDO provides a proportional analog output to the sensed load current. The accurate current sense allows detection of open, normal, and short-circuit conditions without the need for further calibration. ———— ERR pin of LDO is connected to the host MCU to monitor the LDO status. The following table shows the ———— voltage level of ANT_SENSE and ANT_EN pins (LG69T (AB) module), SENSE and ERR pins (LDO) in different failure modes. ———— Table 1: Voltage Level of ANT_SENSE, ANT_EN, SENSE and ERR Pins in Different Failure Modes Failure Mode V(ANT_SENSE) V(ANT_EN) V(SENSE) ———— ERR LDO Output Open Load 0 ≤ V(ANT_SENSE) < 0.05 V 3.3 V High Yes Normal 0.05 ≤ V(ANT_SENSE) < 1.29 V 3.3 V High Yes Overcurrent Short-circuit/ Current Limit 1.29 ≤ V(ANT_SENSE) < 1.34 V 3.3 V 1.34 ≤ V(ANT_SENSE) < 1.46 V 0 V High Yes 2.4–2.65 V Low No LG69T(AB)_Antenna_Detection_Application_Note 11 / 13 GNSS Module Series Failure Mode V(ANT_SENSE) V(ANT_EN) Thermal Shutdown 1.46 ≤ V(ANT_SENSE) < 1.64 V 3.3 V Output Short-to-Battery - - Reverse Current 1.64 ≤ V(ANT_SENSE) < 2.0 V 0 V V(SENSE) ———— ERR 2.7–3.0 V Low 3.05–3.3 V Low 3.05–3.3 V Low LDO Output No No No The LDO can be powered by a 12 V clean power supply. 12 V voltage is converted to 5 V antenna supply voltage. According to RLIM (R106), the maximum output current of LDO is limited to 88 mA. R101, R102, R103, R104, R105, R106, R109 and R110 are resistors with 1 % accuracy, as shown in the Figure 3: Antenna Detection with LDO Reference Design. Table 2: Resistor Requirements Component R104 R106 R109 R110 Comment R104 generates a current sense voltage to be sampled by ADC. R106 limits the maximum current to 88 mA. Sets VOUT to 5 V. LG69T(AB)_Antenna_Detection_Application_Note 12 / 13 GNSS Module Series 3 Appendix References Table 3: Related Document Document Name [1] Quectel_LG69T(AB)_Protocol_Specification Table 4: Terms and Abbreviations Abbreviation ADC GPIO LDO LIM MCU RTCM TI Description Analog-to-digital Converter General-purpose Input/Output Low-dropout Regulator Limit Microcontroller Unit/Microprogrammed Control Unit Radio Technical Commission for Maritime Services Texas Instruments LG69T(AB)_Antenna_Detection_Application_Note 13 / 13
413.69 KB
EG800Q-EU&EG915Q-NA FILE Application Note LTE Standard Module Series Version: 1.0 Date: 2022-12-01 Status: Released LTE Standard Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. EG800Q-EU&EG915Q-NA_FILE_Application_Note 1 / 24 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. 2022. All rights reserved. EG800Q-EU&EG915Q-NA_FILE_Application_Note 2 / 24 LTE Standard Module Series About the Document Revision History Version 1.0 Date 2022-10-10 2022-12-01 Author Egan LI Egan LI Description Creation of the document First official release EG800Q-EU&EG915Q-NA_FILE_Application_Note 3 / 24 LTE Standard Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index .................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 1.1. Using FILE AT Commands ..................................................................................................... 6 1.2. Description of Data Mode....................................................................................................... 7 2 Description of FILE AT Commands................................................................................................... 8 2.1. AT Command Description ...................................................................................................... 8 2.1.1. Definitions........................................................................................................................ 8 2.1.2. AT Command Syntax ...................................................................................................... 8 2.2. Declaration of AT Command Examples ................................................................................. 9 2.3. AT Command Description ...................................................................................................... 9 2.3.1. AT+QFLDS Get the Space Information of Storage Medium ........................................ 9 2.3.2. AT+QFLST List File Information on Storage Medium ................................................ 10 2.3.3. AT+QFDEL Delete File(s) on Storage Medium ...........................................................11 2.3.4. AT+QFUPL Upload File to Storage Medium .............................................................. 12 2.3.5. AT+QFDWL Download File from Storage Medium .................................................... 14 2.3.6. AT+QFOPEN Open a File .......................................................................................... 15 2.3.7. AT+QFREAD Read a File........................................................................................... 16 2.3.8. AT+QFWRITE Write to a File ..................................................................................... 16 2.3.9. AT+QFSEEK Set File Pointer to Specified Position................................................... 17 2.3.10. AT+QFPOSITION Get Offset of File Pointer.............................................................. 18 2.3.11. AT+QFCLOSE Close a File........................................................................................ 19 3 Examples ........................................................................................................................................... 20 3.1. Upload and Download Files ................................................................................................. 20 3.1.1. Upload a File ................................................................................................................. 20 3.1.1.1. Non-ACK Mode..................................................................................................... 20 3.1.1.2. ACK Mode ............................................................................................................ 20 3.1.2. Download a File ............................................................................................................ 21 3.2. Write to and Read Files ........................................................................................................ 21 3.2.1. Write to and Read a UFS File ....................................................................................... 21 4 Summary of Error Codes ................................................................................................................. 22 5 Appendix References ....................................................................................................................... 24 EG800Q-EU&EG915Q-NA_FILE_Application_Note 4 / 24 LTE Standard Module Series Table Index Table 1: Types of AT Commands ................................................................................................................. 8 Table 2: Summary of Error Codes.............................................................................................................. 22 Table 3: Terms and Abbreviations .............................................................................................................. 24 EG800Q-EU&EG915Q-NA_FILE_Application_Note 5 / 24 LTE Standard Module Series 1 Introduction Quectel EG800Q-EU and EG915Q-NA modules support AT commands for working with files on different physical storage mediums. This document is a reference guide to these commands. Quectel EG800Q-EU and EG915Q-NA support only one storage medium – UFS (User File Storage directory) currently. It is a special directory on the flash file system. 1.1. Using FILE AT Commands Follow the steps below to create, read and write to a file in the storage: 1. Upload a file to the storage with AT+QFUPL. If necessary, output/download it through the serial interface with AT+QFDWL. 2. Open the file with AT+QFOPEN. When the file is opened, you can write to it or read from it any time and from any location until the file is closed with AT+QFCLOSE. ⚫ When opening a file with AT+QFOPEN, you can set the file into overwrite mode, read-only mode or other modes with (For more information about , see Chapter 2.3.6). After opening the file, a is assigned to it so that various file operations can be carried out. ⚫ After opening the file, you can write data to the file with AT+QFWRITE and read the data from the current file position with AT+QFREAD. ⚫ Set the file position with AT+QFSEEK or query the current file position with AT+QFPOSITION. ⚫ Close the file with AT+QFCLOSE, after which the will become invalid. Commands for managing files on storage medium: 1. AT+QFLDS: Get storage space information. 2. AT+QFLST: List the file information on the storage medium. 3. AT+QFDEL: Delete the file(s) on the storage medium. ⚫NOTE The file handle obtained after executing AT+QFOPEN must be closed with AT+QFCLOSE after the operation is completed, otherwise the file handle will be leaked. EG800Q-EU&EG915Q-NA_FILE_Application_Note 6 / 24 LTE Standard Module Series 1.2. Description of Data Mode The COM port of EG800Q-EU and EG915Q-NA modules has two working modes: AT command mode and data mode. In AT command mode, the data inputted via COM port are treated as AT commands; whereas in data mode, they are treated as data. ⚫ Enter Data Mode Once AT+QFUPL, AT+QFDWL, AT+QFREAD or AT+QFWRITE is executed, the module returns CONNECT and the COM port enters data mode. Or you can enter date mode again by executing ATO. ⚫ Exit Data Mode If you input +++ or pull up the DTR pin (AT&D1 must be executed first) to make the port exit data mode, the execution of these commands will be interrupted before the response is returned. In such a case, the COM port cannot re-enter data mode if you execute ATO. To prevent +++ from being misinterpreted as data, the following sequence should be followed: 1 Do not input any data for at least 1 s after inputting +++. 2 Input +++ within 1 s and any other data cannot be inputted. 3 Input +++ and wait until OK is returned. Once OK is returned, the COM port exits the data mode. EG800Q-EU&EG915Q-NA_FILE_Application_Note 7 / 24 LTE Standard Module Series 2 Description of FILE AT Commands 2.1. AT Command Description 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 1: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. EG800Q-EU&EG915Q-NA_FILE_Application_Note 8 / 24 LTE Standard Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 2.3. AT Command Description 2.3.1. AT+QFLDS Get the Space Information of Storage Medium This command gets the space information of the specified storage medium. AT+QFLDS Get the Space Information of Storage Medium Test Command AT+QFLDS=? Write Command AT+QFLDS= Response OK Response +QFLDS: , OK Execution Command AT+QFLDS If there is an error: +CME ERROR: Response Return UFS space information: +QFLDS: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. Parameter String type. Storage medium type. 'UFS' UFS EG800Q-EU&EG915Q-NA_FILE_Application_Note 9 / 24 LTE Standard Module Series Integer type. Free space size of . Unit: byte. Integer type. Total space size of . Unit: byte. Integer type. Size of all files in UFS. Unit: byte. Integer type. Number of files in UFS. Integer type. Error code. See Chapter 4 for details. Example AT+QFLDS='UFS' +QFLDS: 578847,917503 OK //Query the space information of UFS. 2.3.2. AT+QFLST List File Information on Storage Medium This command lists the information of a single file or all files on a specified storage medium. AT+QFLST List File Information on Storage Medium Test Command AT+QFLST=? Write Command AT+QFLST= Response OK Response +QFLST: , [+QFLST: , […]] OK Execution Command AT+QFLST If there is an error: +CME ERROR: Response Return the space information of UFS files: +QFLST: , [+QFLST: , […]] OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. EG800Q-EU&EG915Q-NA_FILE_Application_Note 10 / 24 LTE Standard Module Series Parameter String type. File to be listed. Maximum length: 80 bytes. '*' List all files in UFS 'UFS:' List the specified file in UFS '' List the specified file in UFS String type. File name. Integer type. File size of specified file in UFS. Unit: byte. Integer type. Error code. See Chapter 4 for details. Example AT+QFLST='*' +QFLST: 'UFS:1k.txt',1024 +QFLST: 'UFS:2k.txt',2048 +QFLST: 'UFS:3k.txt',3072 OK //List all files in UFS. ⚫NOTE AT+QFLST queries the actual size of the file currently stored on Flash. Use AT+QFWRITE (see Chapter 2.3.8) to write data. If AT+QFLST cannot query file size, execute AT+QFCLOSE (see Chapter 2.3.11) to close the file and then query the file size. 2.3.3. AT+QFDEL Delete File(s) on Storage Medium This command deletes a single file or all files from a specified storage medium. AT+QFDEL Delete File(s) on Storage Medium Test Command AT+QFDEL=? Response +QFDEL: Write Command AT+QFDEL= OK Response OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. EG800Q-EU&EG915Q-NA_FILE_Application_Note 11 / 24 LTE Standard Module Series Parameter String type. Name of the file to be deleted. Maximum length: 80 bytes. '*' Delete all files in UFS (do not delete the directory) 'UFS:' Delete the specified file in UFS '' Delete the specified file in UFS String type. File name. Integer type. Error code. See Chapter 4 for details. Example AT+QFDEL='*' OK AT+QFDEL='UFS:1.txt' OK //Delete all files in UFS (do not delete the directory). //Delete the 1.txt file in UFS. 2.3.4. AT+QFUPL Upload File to Storage Medium This command uploads a file to a storage medium. If any file on the storage has the same name as the file to be uploaded, an error will be reported. AT+QFUPL Upload File to Storage Medium Test Command AT+QFUPL=? Response +QFUPL: [,(1-)[,(range of supported s)[,(list of supported s)]]] Write Command AT+QFUPL=[,[, [,]]] OK Response CONNECT TA switches to data mode (transparent transmission mode), so the binary data of the file can be inputted. When the total size of the inputted data reaches or no data is inputted when is reached, TA will go back to AT command mode and return the following code: +QFUPL: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 5 s The command takes effect immediately. The configurations are not saved. EG800Q-EU&EG915Q-NA_FILE_Application_Note 12 / 24 LTE Standard Module Series Parameter String type. Name of the file to be uploaded. Maximum length: 80 bytes. 'UFS:' Name of the file to be uploaded to UFS '' Name of the file to be uploaded to UFS String type. File name. Integer type. Free space size of . See AT+QFLDS for more details on . Integer type. Waiting time for inputting data to USB/UART. Range: 1–65535. Default value: 5. Unit: second. Integer type. Determines whether to use ACK mode. 0 Turn off ACK mode 1 Turn on ACK mode Integer type. File size expected to be uploaded. Default value: 10240. Unit: byte. Maximum length is not greater than . Integer type. Actual size of uploaded data. Unit: byte. Integer type. Checksum of uploaded data. Integer type. Error code. See Chapter 4 for details. NOTE 1. It is strongly recommended to use DOS 8.3 file name format for . 2. is a 16-bit checksum based on bitwise XOR. If the number of characters is odd, set the last character as the high 8 bit, and the low 8 bit as 0, and then use an XOR operator to calculate the checksum. After switching to command mode, the previously uploaded data will be preserved in the file. 3. When executing the command, the data must be entered after CONNECT is returned. 4. ACK mode is a safeguard against data loss when uploading large files, if hardware flow control does not work. ACK mode works as follows: 1) Execute AT+QFUPL=,,,1 to enable ACK mode. 2) Module outputs CONNECT. 3) MCU sends 1 KB data, to which the module responds with an A. 4) MCU receives the A and then sends the next 1 KB data. 5) Repeat step 3) and 4) until the transfer is completed. For an example of ACK mode use, see Chapter 3.1.1.2. EG800Q-EU&EG915Q-NA_FILE_Application_Note 13 / 24 LTE Standard Module Series 2.3.5. AT+QFDWL Download File from Storage Medium This command downloads a specified file from the storage medium. AT+QFDWL Download File from Storage Medium Test Command AT+QFDWL=? Response +QFDWL: Write Command AT+QFDWL= OK Response CONNECT TA switches to data mode, so the binary data of the file can be outputted. After the file is downloaded, TA will go back to AT command mode and return the following codes: +QFDWL: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 5 s The command takes effect immediately. The configurations are not saved. Parameter String type. Name of the file to be downloaded. Maximum length: 80 bytes. 'UFS:' Name of the UFS file to be downloaded '' Name of the UFS file to be downloaded String type. File name. Integer type. Size of downloaded data. Unit: byte. Integer type. Checksum of downloaded data. Integer type. Error code. See Chapter 4 for details. NOTE is a 16-bit checksum based on bitwise XOR. EG800Q-EU&EG915Q-NA_FILE_Application_Note 14 / 24 LTE Standard Module Series 2.3.6. AT+QFOPEN Open a File This command opens a file and gets the file handle to be used in commands such as AT+QFREAD, AT+QFWRITE, AT+QFSEEK, AT+QFPOSITION and AT+QFCLOSE. AT+QFOPEN Open a File Test Command AT+QFOPEN=? Response +QFOPEN: [,(range of supported s)] Read Command AT+QFOPEN? OK Response +QFOPEN: ,, [+QFOPEN: ,, […]] Write Command AT+QFOPEN=[,] OK Response +QFOPEN: OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. Parameter String type. Name of the file to be opened. Maximum length: 80 bytes. 'UFS:' Name of the UFS file to be opened '' Name of the UFS file to be opened String type. File name. Integer type. File opening mode. 0 If the file does not exist, it is created. If the file exists, it is opened directly. In both cases, the file can be read and written to. 1 If the file does not exist, it is created. If the file exists, it is overwritten and cleared. In both cases, the file can be read and written to. 2 If the file exists, it is opened directly as a read-only file. Otherwise, an error is returned. Integer type. File handle to be used. Data type: 4 bytes. Integer type. Error code. See Chapter 4 for details. EG800Q-EU&EG915Q-NA_FILE_Application_Note 15 / 24 LTE Standard Module Series 2.3.7. AT+QFREAD Read a File This command reads the data of a file specified by the file handle. The data start from the current position of the file pointer that belongs to the file handle. AT+QFREAD Read a File Test Command AT+QFREAD=? Response +QFREAD: [,] Write Command AT+QFREAD=[,] OK Response CONNECT TA switches to data mode, so the data being read will be outputted. When the total size of the data reaches , TA will go back to AT command mode, display the result and then return the following code: OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 5 s The command takes effect immediately. The configurations are not saved. Parameter Integer type. File handle to be read. Integer type. Length of the file to be read. If this parameter is not inputted, the default length is 10 KB. If this parameter is inputted, the actual length of the file is read. Maximum value of this parameter is determined by of AT+QFUPL. Default value: 10240. Unit: byte. Integer type. Actual read length. Unit: byte. Integer type. Error code. See Chapter 4 for details. 2.3.8. AT+QFWRITE Write to a File This command writes data into a file. The data starts from the current position of the file pointer that belongs to the file handle. AT+QFWRITE Write to a File Test Command AT+QFWRITE=? Response +QFWRITE: [,[,range of supported EG800Q-EU&EG915Q-NA_FILE_Application_Note 16 / 24 LTE Standard Module Series s]] Write Command AT+QFWRITE=[, [,]] OK Response CONNECT TA switches to data mode, so the hexadecimal data of the file can be written to. When the total size of the written data reaches or the written time reaches , TA will go back to AT command mode and return the following code: +QFWRITE: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 5 s The command takes effect immediately. The configurations are not saved. Parameter Integer type. File handle to be written to. Integer type. Length of the file to be written to. If this parameter is not inputted, the default length is 10 KB. If this parameter is inputted, the actual length of the file is written to. Maximum value of this parameter is determined by of AT+QFUPL. Default value: 10240. Unit: byte. Integer type. Waiting time for inputting data to USB/UART. Range:1–65535. Default value: 5. Unit: second. Integer type. Actual written length. Unit: byte. Integer type. Total file length. Unit: byte. Integer type. Error code. See Chapter 4 for details. 2.3.9. AT+QFSEEK Set File Pointer to Specified Position This command sets a file pointer to the specified position. This will decide the starting position of commands, such as AT+QFREAD, AT+QFWRITE and AT+QFPOSITION. AT+QFSEEK Set a File Pointer to Specified Position Test Command AT+QFSEEK=? Response +QFSEEK: ,[,range of supported s] EG800Q-EU&EG915Q-NA_FILE_Application_Note 17 / 24 LTE Standard Module Series Write Command AT+QFSEEK=,[,< position>] OK Response OK If there is an error: +CME ERROR: Maximum Response Time 300 ms Characteristics The command takes effect immediately. The configurations are not saved. Parameter Integer type. File handle for which a pointer is set. Integer type. Number of bytes of the file pointer movement. Integer type. Pointer movement mode. 0 Move forward from the beginning of the file 1 Move forward from the current position of the pointer 2 Move backward from the end of the file Integer type. Error code. See Chapter 4 for details. NOTE If the set final position of the pointer exceeds the file size, executing this command will return ERROR. 2.3.10. AT+QFPOSITION Get Offset of File Pointer This command gets the offset of a file pointer from the beginning of the file. AT+QFPOSITION Get the Offset of a File Pointer Test Command AT+QFPOSITION=? Response +QFPOSITION: Write Command AT+QFPOSITION= OK Response +QFPOSITION: OK If there is an error: +CME ERROR: EG800Q-EU&EG915Q-NA_FILE_Application_Note 18 / 24 LTE Standard Module Series Maximum Response Time Characteristics 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. File handle for which the offset of file pointer is to be gotten. Integer type. Offset from the beginning of the file. Integer type. Error code. See Chapter 4 for details. 2.3.11. AT+QFCLOSE Close a File This command closes a file and ends all file operations. After that, the file handle is released and should not be used again, unless the file is re-opened with AT+QFOPEN. AT+QFCLOSE Close a File Test Command AT+QFCLOSE=? Response +QFCLOSE: Write Command AT+QFCLOSE= OK Response OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. File handle to be closed. Integer type. Error code. See Chapter 4 for details. EG800Q-EU&EG915Q-NA_FILE_Application_Note 19 / 24 LTE Standard Module Series 3 Examples 3.1. Upload and Download Files 3.1.1. Upload a File 3.1.1.1. Non-ACK Mode AT+QFUPL='test1.txt',10 CONNECT +QFUPL: 10,3938 OK //Upload the text file test1.txt to UFS. //Input binary data of the text file in data mode. 3.1.1.2. ACK Mode The ACK mode can make the data transmission more reliable. When transmitting a large file without hardware flow control, the ACK mode is recommended to prevent data loss. For more details on ACK mode, see AT+QFUPL. AT+QFUPL='test.txt',3000,5,1 CONNECT A A +QFUPL: 3000,B34A //Upload the text file test.txt to UFS. //Input 1024 bytes of binary data of the text file in data mode. //After receiving 1024 bytes of binary data of the text file, the module returns an A. //Input next 1024 bytes of binary data of the text file in data mode. //Input the rest of binary data of the text file in data mode. OK EG800Q-EU&EG915Q-NA_FILE_Application_Note 20 / 24 3.1.2. Download a File AT+QFDWL='test.txt' CONNECT +QFDWL: 10,613e OK LTE Standard Module Series //Download the text file test.txt from UFS. //Output binary data of the text file in data mode. //Return size and checksum value of the downloaded data. 3.2. Write to and Read Files 3.2.1. Write to and Read a UFS File AT+QFOPEN='test.txt',1 +QFOPEN: 1 //Open the file to get the file handle. OK AT+QFWRITE=1,10 CONNECT +QFWRITE: 10,10 //Write 10 bytes to the file. //Write hexadecimal data to the file in data mode. //Return the actual written bytes and the size of the file. OK AT+QFSEEK=1,0,0 OK AT+QFREAD=1,10 CONNECT 10 //Set the file pointer to the beginning of the file. //Read data. //Output data to be read in data mode. OK AT+QFCLOSE=1 OK //Close the file. EG800Q-EU&EG915Q-NA_FILE_Application_Note 21 / 24 LTE Standard Module Series 4 Summary of Error Codes indicates the error codes related to mobile equipment. See the table below for details. The error codes indicated below are related to the file operation of the modules. Table 2: Summary of Error Codes 400 401 402 403 405 406 407 409 410 411 413 414 416 417 418 419 420 Meaning Invalid input value Larger than the size of the file Zero-byte read Drive full File not found Invalid file name File already exists Fail to write to the file Fail to open the file Fail to read the file Reach the max. number of files allowed to be opened Read-only file Invalid file descriptor Failed to list the file Failed to delete the file Failed to get disk info No space EG800Q-EU&EG915Q-NA_FILE_Application_Note 22 / 24 421 Time-out 423 File too large 425 Invalid parameter 426 File already opened LTE Standard Module Series EG800Q-EU&EG915Q-NA_FILE_Application_Note 23 / 24 LTE Standard Module Series 5 Appendix References Table 3: Terms and Abbreviations Abbreviation ACK COM DOS DTR MCU ME RAM TA UART UFS USB XOR Description Acknowledgement Communication Port Disk Operating System Data Terminal Ready Microprogrammed Control Unit Mobile Equipment Random Access Memory Terminal Adapter Universal Asynchronous Receiver-Transmitter User File Storage Universal Serial Bus Exclusive OR EG800Q-EU&EG915Q-NA_FILE_Application_Note 24 / 24
322.06 KB
Quectel KG100S Application Note Wireless Module for Amazon Sidewalk Version: 1.0.0 Date: 2022-11-14 Status: Preliminary Sidewalk 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. Quectel_KG100S_Application_Note 1 / 24 Sidewalk Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. Quectel_KG100S_Application_Note 2 / 24 Sidewalk Module Series Safety Information The following safety precautions must be observed during all phases of operation, such as usage, service or repair of any cellular terminal or mobile incorporating the module. Manufacturers of the cellular terminal shall notify users and operating personnel of the following safety information by incorporating these guidelines into all manuals of the product. Otherwise, Quectel assumes no liability for customers’ failure to comply with these precautions. Full attention must be paid to driving at all times in order to reduce the risk of an accident. Using a mobile while driving (even with a handsfree kit) causes distraction and can lead to an accident. Please comply with laws and regulations restricting the use of wireless devices while driving. Switch off the cellular terminal or mobile before boarding an aircraft. The operation of wireless appliances in an aircraft is forbidden to prevent interference with communication systems. If there is an Airplane Mode, it shall be enabled prior to boarding an aircraft. Please consult the airline staff for more restrictions on the use of wireless devices on an aircraft. Wireless devices may cause interference on sensitive medical equipment, so please be aware of the restrictions on the use of wireless devices when in hospitals, clinics or other healthcare facilities. Cellular terminals or mobiles operating over radio signal and cellular network cannot be guaranteed to connect in certain conditions, such as when the mobile bill is unpaid or the (U)SIM card is invalid. When emergent help is needed in such conditions, use emergency call if the device supports it. In order to make or receive a call, the cellular terminal or mobile must be switched on in a service area with adequate cellular signal strength. In an emergency, the device with emergency call function cannot be used as the only contact method considering network connection cannot be guaranteed under all circumstances. The cellular terminal or mobile contains a transceiver. When it is ON, it receives and transmits radio frequency signals. RF interference can occur if it is used close to TV sets, radios, computers or other electric equipment. In locations with explosive or potentially explosive atmospheres, obey all posted signs and turn off wireless devices such as mobile phone or other cellular terminals. Areas with explosive or potentially explosive atmospheres include fuelling areas, below decks on boats, fuel or chemical transfer or storage facilities, and areas where the air contains chemicals or particles such as grain, dust or metal powders. Quectel_KG100S_Application_Note 3 / 24 Sidewalk Module Series About the Document Revision History Version Date Author - 2022-07-07 Wain ZHAO/ Soni RAO 1.0.0 2022-11-14 Wain ZHAO/ Soni RAO Description Creation of the document Preliminary Quectel_KG100S_Application_Note 4 / 24 Sidewalk Module Series Contents Safety Information...................................................................................................................................... 3 About the Document .................................................................................................................................. 4 Contents ...................................................................................................................................................... 5 1 Introduction ......................................................................................................................................... 7 2 Power Supply Dissipation.................................................................................................................. 8 3 Quectel KG100S TE-B....................................................................................................................... 10 3.1. Quectel KG100S TE-B Schematic ........................................................................................... 10 3.2. Quectel KG100S TE-B Layout_ PCB ...................................................................................... 10 4 JLINK FileWave Download Tool ...................................................................................................... 13 4.1. JLINK FileWave Downloader Connection ............................................................................... 13 4.2. JLINK FileWave Downloader ................................................................................................... 13 5 RF Considerations ............................................................................................................................ 15 6 Test Command .................................................................................................................................. 18 6.1. BLE Test Command................................................................................................................. 18 6.2. FSK Test Command ................................................................................................................ 20 6.3. LoRa Test Command ............................................................................................................... 20 7 Block Diagram ................................................................................................................................... 23 8 Appendix ............................................................................................................................................ 24 8.1. Reference Schematic............................................................................................................... 24 Quectel_KG100S_Application_Note 5 / 24 Sidewalk Module Series Figure Index Figure 1: BLE Spectrum (DC-DC)................................................................................................................ 8 Figure 2: BLE Spectrum (LDO) .................................................................................................................... 9 Figure 3: Quectel KG100S Reference Design Layout-Top Layer (TE-B_PCB) ........................................ 10 Figure 4: Quectel KG100S Reference Design Layout-Layer 2 (TE-B_PCB) ............................................ 11 Figure 5: Quectel KG100S Reference Design Layout-Layer 3 (TE-B_PCB) ............................................ 11 Figure 6: Quectel KG100S Reference Design Layout-Bottom Layer (TE-B_PCB)................................... 12 Figure 7: JLINK FileWave Downloader Connection .................................................................................. 13 Figure 8: JLINK FileWave Downloader Pin Definition and Picture............................................................ 14 Figure 9: BLE BPF Reference Design ....................................................................................................... 15 Figure 10: ANT_LORA & ANT_BLE Antenna Port Distance Reference ................................................... 16 Figure 11: RF Diplexer Reference Design ................................................................................................. 17 Quectel_KG100S_Application_Note 6 / 24 Sidewalk Module Series 1 Introduction The purpose of this application note is to help developers select the best reference design of Quectel KG100S integration with key components and design methods that can attain the best performance of their Sidewalk applications. Please read this application note along with the Quectel KG100S Hardware Design. Quectel_KG100S_Application_Note 7 / 24 Sidewalk Module Series 2 Power Supply Dissipation The Quectel KG100S outputs the best performance when VSYS is supplied the power from 3.0 V to 3.6 V and VMCU is supplied the power from 1.71 V to 3.6 V. Recommended operating condition for power supply and voltage on digital and analog pins of the module are listed in the following table. Table 1: Recommended Operating Conditions Parameter VSYS VMCU Min. 3.0 1.71 Typ. Max. Unit 3.3 3.6 V 1.8/3.3 3.6 V DC-DC converter or LDO can be used for VSYS power supply. Recommends to use LDO to supply power for VMCU. Please note the spurs will be generated and will become the interference signals to affect the BLE Tx signal as shown in the Figure 1 when using DC-DC convertor to supply power for VMCU. There is no spur found when using LDO for VMCU as shown in the Figure 2. Figure 1: BLE Spectrum (DC-DC) Quectel_KG100S_Application_Note 8 / 24 Sidewalk Module Series Figure 2: BLE Spectrum (LDO) Quectel_KG100S_Application_Note 9 / 24 Sidewalk Module Series 3 Quectel KG100S TE-B The Quectel KG100S reference design (TE-B) is designed to enable the module to provide optimal performance while maintaining the Tx power at 21 dBm of current consumption of about 115 mA at 3.3 V power supply for Sub-GHz and the Tx power at 0 dBm of current consumption of about 9.6 mA at 1.8 V power supply for BLE. 3.1. Quectel KG100S TE-B Schematic The reference design schematic of TE-B is shown in Chapter 8.1. 3.2. Quectel KG100S TE-B Layout_ PCB The reference layout of TE-B are shown in the following figures. Figure 3: Quectel KG100S Reference Design Layout-Top Layer (TE-B_PCB) Quectel_KG100S_Application_Note 10 / 24 Sidewalk Module Series Figure 4: Quectel KG100S Reference Design Layout-Layer 2 (TE-B_PCB) Figure 5: Quectel KG100S Reference Design Layout-Layer 3 (TE-B_PCB) Quectel_KG100S_Application_Note 11 / 24 Sidewalk Module Series Figure 6: Quectel KG100S Reference Design Layout-Bottom Layer (TE-B_PCB) Quectel_KG100S_Application_Note 12 / 24 Sidewalk Module Series 4 JLINK FileWave Download Tool 4.1. JLINK FileWave Downloader Connection The JLINK FileWave downloader connection is shown as below. EVK’s JLINK pin Definition 16 GND 14 GND 12 GND 10 GND 8 GND 6 GND 4 GND 2 VCC 15 SW_RST 13 SWO 11 NC 9 SWCLK 7 SWDIO 5 NC 3 NC 1 VCC Figure 7: JLINK FileWave Downloader Connection 4.2. JLINK FileWave Downloader It is recommended that customers to use optional power supply 1.8 V or 3.3 V when connecting JLINK FileWave downloader. The pin definition and picture of JLINK FileWave downloader are shown as below. Quectel_KG100S_Application_Note 13 / 24 Sidewalk Module Series VCC 1 N/U 3 N/U 5 SWDIO 7 SWCLK 9 N/U 11 SWO 13 RESET 15 N/C 17 N/C 19 2 VCC (optional) 4 GND 6 GND 8 GND 10 GND 12 GND 14 GND 16 GND 18 GND 20 GND SWD Figure 8: JLINK FileWave Downloader Pin Definition and Picture Quectel_KG100S_Application_Note 14 / 24 Sidewalk Module Series 5 RF Considerations RF trace layout should be pay attention to the continuity of 50 Ohm impendence control. RF trace width is recommended to align with 0201 component’s pad, U.FL connector’s pad and attention to the clearance, etc. Recommends the insulation capacitance of the peripheral RF matching circuit of the terminal device be the same as that of the Quectel KG100S. Also recommends to reserve a π-type matching circuit for RF performance tuning. For the antenna isolation between antenna ports of ANT_LoRa and ANT_BLE: Option 1: Recommends to design over than 20 dB. Option 2: For user scenario supporting BLE & LoRa co-existence, it requires to add a BLE BPF (RFBPF1107A107A5U) to suppress LoRa Tx band signal interfering BLE Rx sensitivity performance. Figure 9: BLE BPF Reference Design Quectel_KG100S_Application_Note 15 / 24 Sidewalk Module Series Figure 10: ANT_LORA & ANT_BLE Antenna Port Distance Reference For BLE & LoRa dual-band signal antenna design, recommends to add a RF diplexer (DPX202700DT-4062A1) placed outside the KG100S. Quectel_KG100S_Application_Note 16 / 24 Sidewalk Module Series Figure 11: RF Diplexer Reference Design Quectel_KG100S_Application_Note 17 / 24 Sidewalk Module Series 6 Test Command 6.1. BLE Test Command Reset parameters to defaults dtm 0 0 Send 'LE Test Setup' Reset: Extended length = 0, PHY = 1M, standard mod index, no CTE Hex 00 00 Set Upper two bits of data length dtm 1 0 Send 'LE Test Setup' Set Upper 2-bits of data length to 0 Hex 01 00 dtm 1 4 Send 'LE Test Setup' Set Upper 2-bits of data length to 1 (+ 64 length) Hex 01 04 dtm 1 8 Send 'LE Test Setup' Set Upper 2-bits of data length to 2 (+ 128 length) Hex 01 08 dtm 1 12 Send 'LE Test Setup' Set Upper 2-bits of data length to 3 (+ 192 length) Hex 01 0C Note: The lower 6-bits of the length are set in bits 7..2 in the second octet of the 'LE Transmitter Test' and 'LE Receiver Test' commands Set Phy rate dtm 2 4 Send 'LE Test Setup' Set PHY to 1M Hex 02 04 dtm 2 8 Send 'LE Test Setup' Set PHY to 2M Hex 02 08 dtm 2 12 Send 'LE Test Setup' Set PHY to LE Coded, S=8 Hex 02 0C dtm 2 16 Send 'LE Test Setup' Set PHY to LE Coded, S=2 Hex 02 10 These settings will be used in the next tests(s), they can be reset or overwritten with new commands. Set Tx Power dtm 9 5 Send 'LE Test Setup' set transmit power to +5 dBm Hex 09 05 dtm 9 251 Send 'LE Test Setup' set transmit power to -5 dBm Hex 09 FB Note: The return value has a relatively complex coding which includes echoing the set power, Quectel_KG100S_Application_Note 18 / 24 Sidewalk Module Series represented as a signed 7-bit number, shifted left one place! Please read the BT Specification to understand this. Turn on CW dtm 31 0 Send 'LE Test Setup' (proprietary) command, start transmit CW on channel 0 Hex 3F 00 dtm 31 39 Send 'LE Test Setup' (proprietary) command, start transmit CW on channel 39 Hex 3F 27 Send 'LE Test End' to stop CW transmission Receiver test dtm 64 0 Send 'LE Receiver Test', Channel 0 (the rate will be as configured above) Hex 40 00 dtm 84 0 Send 'LE Receiver Test', Channel 20 (the rate will be as configured above) Hex 54 0 dtm 103 0 Send 'LE Receiver Test', Channel 39 (the rate will be as configured above) Hex 67 0 After the 'LE Test End command' is sent the number of packets successfully received will be reported. Transmitter test dtm 128 0 Send 'LE Transmitter Test', Channel 0, 0 byte PRBS9 payload Hex 80 00 dtm 148 0 Send 'LE Transmitter Test', Channel 20, 0 byte PRBS9 payload Hex 54 00 dtm 128 40 Send 'LE Transmitter Test', Channel 0, 10 byte PRBS9 payload Hex 80 28 dtm 128 252 Send 'LE Transmitter Test', Channel 0, 63 byte PRBS9 payload Hex 80 FC dtm 167 252 Send 'LE Transmitter Test', Channel 39, 63 byte PRBS9 payload Hex A7 FC dtm 128 253 Send 'LE Transmitter Test', Channel 0, 63 byte 11110000 payload Hex 80 FD dtm 128 254 Send 'LE Transmitter Test', Channel 0, 63 byte 10101010 payload Hex 80 FE End current Test dtm 192 0 Send 'LE Test End' command (halts any active transmission or reception) Hex C0 00 After a receive test, the number of packets successfully received will the returned; please read comments at the top of the document about the 'EV' flag to understand the coding. Quectel_KG100S_Application_Note 19 / 24 Sidewalk Module Series 6.2. FSK Test Command Tx -J Enter radio frequency mode tm phy modem 0 1 indicates LoRa modulation and 0 indicates FSK modulation gpio pin_test 5 1 1 indicates the Tx and Rx EU bands of the gateway SP3T, and 0 indicates the Rx US band of the Gateway SP3T tm phy fp 0 863500000 22 863500000 indicates the frequency HZ and 22 indicates the transmit power in dBm tm phy mod 0 50000 25000 4 15 50000: 50 kbps rate,25000: the deviation of 25 kHz; 4: modulation shaping 4; 15: bandwidth 15 tm phy pkt 0 240 1 3 0 0 16 2 1 240: PREAMBLE LENGTH [240]; 1: PREAMBLE minimum detect [1]; 3: Sync Word LENGTH [3]; 0: Address compare closed; 0: Header type 0; 16 indicates PL16, 2 indicates CRC Type0, and 1 indicates UV Protection tm mod 1 10 75 1000 10 indicates 10 MS packet interval, 75 indicates -75dB Carrier threshold Sensing, and 1000 indicates 1000 US Sense timing. tm mod 0 0 indicates that the launch is stopped Rx -J tm phy modem 0 gpio pin_test 5 1 tm phy fp 0 863500000 22 tm phy mod 0 50000 25000 4 15 tm phy pkt 0 240 1 3 0 0 16 2 1 tm state 3 Enter receive mode tm state 1 Calculate the received packet tm mod 0 The command station displays the received packets tm reset_rx_counters The last received packet is cleared 6.3. LoRa Test Command Tx -J tm phy modem 1 gpio pin_test 5 1 tm phy fp 1 863500000 22 tm phy mod 1 2 0 1 2: SF7,0: 500KHz,1: CR_4_6 //Spreading Factor //SF5 ->0 //SF6 ->1 Quectel_KG100S_Application_Note 20 / 24 Sidewalk Module Series //SF7 ->2 //SF8 ->3 //SF9 ->4 //SF10 ->5 //SF11 ->6 //SF12 ->7 //Bandwidth Value (kHz) //500 ->0 //250 ->1 //125 ->2 //62 ->3 //41 ->4 //31 ->5 //20 ->6 //15 ->7 //10 ->8 //7 ->9 //Coding Rate Value //CR_4_5 ->0 //CR_4_6 ->1 //CR_4_7 ->2 //CR_4_8 ->3 tm phy pkt 1 250 0 1 0 16 250: PREAMBLE LENGTH 【250】,0: Variable Length,1: CRC On,0: IQ Inverted,16: payload length,PL=16 //Header Type //Variable Length ->0 //Fixed Length ->1 //CRC Mode //CRC Off ->0 //CRC On ->1 //Invert IQ //IQ Normal ->0 //IQ Inverted ->1 tm mod 1 10 75 1000 10: 500ms packet interval ,75: -75 dB carrier threshold sensing,1000: 1000us sense timing. tm mod 0 Rx -J tm phy modem 1 gpio pin_test 5 1 tm phy fp 1 863500000 22 tm phy mod 1 2 0 1 tm phy pkt 1 250 0 1 0 16 Quectel_KG100S_Application_Note 21 / 24 tm state 3 tm state 1 tm mod 0 tm reset_rx_counters Sidewalk Module Series Quectel_KG100S_Application_Note 22 / 24 Sidewalk Module Series 7 Block Diagram VSYS XTAL 32 MHz SPI DIO Semtech SX1262 LoRa FSK Block Diagram Sub-1 GHz: Tx (+22 dBm) Bias MAUI_GPIO_0 Match SX_DIO2 RXP RXN Balun RF Filter RF Switch Match Sub-1 GHz RF_Out Sub-1 GHz: Tx (+22 dBm) SPI DIO VMCU SiLabs EFR32BG21 BLE MCU FLASH SRAM XTAL XTAL 38.4 MHz 32.768 KHz BLE Tx/Rx Match BLE: Tx (+10 dBm) BLE RF_Out UART ×1 12C ×1 SPI ×1 GPIO VMCU +1.8 V VSYS +3.3 V Quectel_KG100S_Application_Note 23 / 24 Sidewalk Module Series 8 Appendix 8.1. Reference Schematic The schematics illustrated in the following pages are provided for reference only. Quectel_KG100S_Application_Note 24 / 24 5 D 4 3 2 Power Supply Design VBUS 1 1 S0102 3 3 5 5 2 2 4 4 SS-12D02-G3 USB_VBUS C0104 1uF +/-10% 10V Power Supply for LoRa Chip R0104 10K +/-5% 1/16W 7 IN1 8 IN2 U0101 1 OUT1 2 OUT2 3 OUT3 4 NC/FB 6 EN 5 GND1 9 GND2 ETA5060V330DBI LDO_FB R0108 200K +/-1% 1/20W R0109 100K +/-1% 1/20W VCC_3V3 C0103 1uF +/-10% 6.3V 1 D Power Supply for MCU Chip C C VBUS 10uF +/-20% 10V 1 GND C0101 VOUT = 0.6 × (1 + R0101 / R0102) = 1.8 V U0102 3 VIN 2 SW 6 OUT L0101 1.0uH +/-20% 0.05ohm 3.1A R0103 DCDC_EN 4 EN 10K +/-5% 1/20W 5 FB MP1603GTF-Z R0101 200K +/-1% 1/20W R0102 100K +/-1% 1/20W VCC_1V8_DCDC C0102 10uF +/-20% 6.3V VCC_3V3 1uF +/-10% 10V C0105 R0110 10K +/-5% 1/16W U0103 7 IN1 1 OUT1 8 IN2 2 OUT2 3 OUT3 4 NC/FB 6 EN 5 GND1 9 GND2 ETA5060V330DBI R0111 200K +/-1% 1/20W R0112 100K +/-1% 1/20W VCC_1V8_LDO C0106 1uF +/-10% 6.3V B R0105 B J0102 VCC_3V3 VCC_1V8 NM R0106 VMCU_1V8 NOTE VCC_1V8_LDO VCC_1V8 VCC_1V8_DCDC 1 1 2 2 3 3 0R IDE_3_2_54 NOTE: The power supply for VCC_1V8 selectable. A 5 Screw Holes HL0103 1 1 npth_cir3_20 HL0104 1 1 npth_cir3_20 HL0102 1 1 npth_cir3_20 HL0101 1 1 npth_cir3_20 4 3 2 A Quectel Wireless Solutions PROJECT KG100S VER 1.0.0 DRAWN BY Wain ZHAO CHECKED BY Soni RAO SIZE A2 DATE Monday, November 14, 2022 1 SHEET 1 OF 3 5 4 3 2 1 Module Interfaces Module Interfaces Design Jumper Caps U0201B D ANT_LORA [2] 41 GND24 52 GND29 J0201 D ANT_BLE [2] 43 GND25 54 GND30 [2] US0_RX 1 2 DBG_RXD [2,3] 44 GND26 55 GND31 [2,3] US0_TX 3 4 DBG_TXD [2,3] 45 GND27 46 GND28 56 GND32 [2] DBG_SWO [2] DBG_SWDIO 5 6 7 8 SWO [2,3] SWDIO [2,3] GND KG100S [2,3] DBG_SWCLK 9 10 SWCLK [2,3] W X1145205260 2 2 1 1 40 GND23 39 ANT_LORA 38 GND22 37 GND21 36 GND20 35 GND19 34 GND18 33 GND17 32 ANT_BLE 31 GND16 [2] DBG_SWCLK [2] DBG_SWDIO [2] DBG_SWO [2] US0_TX [2] US0_RX [2] GPIO0 C 1 GND1 2 DBG_SW CLK 3 DBG_SW DIO 4 DBG_SW O 5 GND2 6 VCOM_TX 7 VCOM_RX 8 GND3 9 GPIO0 10 GND4 U0201A KG100S 30 GND15 29 RESET 28 GND14 27 I2C_SCL 26 I2C_SDA 25 GND13 24 PTI_SYNC 23 PTI_DATA 22 GND12 21 VMCU C0209 RESET [2] PTI_SYNC [2] PTI_DATA [2] C0208 C0207 C0201 R0220 NM R0219 NM J0214 VMCU_1V8 1 1 2 2 IDE_2_2.54 R0204 NM VMCU_1V8 [2] RESET [2] PTI_SYNC [2] PTI_DATA [2] GPIO0 [2] GPIO1 J0202 1 2 3 4 5 6 7 8 9 10 W X1145205260 SW_RST [2,3] PTI_SYNC_1 [2,3] PTI_DATA_1 [2] LED0 [2] LED1 [2] J0213 IDE_2_2.54 C 11 GND5 12 SX_DIO2 13 GPIO1 14 GND6 15 GND7 16 GND8 17 GND9 18 GND10 19 VSYS 20 GND11 10pF +/-5% 50V 33pF +/-5% 50V 100nF +/-10% 10V 10uF +/-20% 6.3V 2 2 1 1 [2] SX_DIO2 [2] GPIO1 VCC_3V3 R0205 NM 2 2 1 1 Current test J0203 IDE_2_2.54 C0206 10pF +/-5% 50V C0205 33pF +/-5% 50V C0204 100nF +/-10% 10V C0202 10uF +/-20% 6.3V + C0203 NM_100uF +/-20% 6.3V J0204 IDE_2_2.54 Current test Mini Header J0210 IDE_2_2.54 1 1 2 2 VMCU [2,3] SW_RST [2,3] DBG_TXD [2,3] SWDIO [2] PTI_SYNC_1 VAEM J0212 1 2 3 4 5 6 7 8 9 10 C127VS20501RK DBG_RXD [2,3] SWO [2,3] SWCLK [2,3] PTI_DATA_1 [2] Mini simplicity connector leads out B B LED Design LoRa Header Reset Button 1 2 12 VCC_3V3 D0203 LTST-C193KRKT-5A RED1 1 2 12 VCC_3V3 D0205 LTST-C193KRKT-5A RED2 R0215 2.2K +/-5% 1/16W VCC_3V3 VCC_3V3 2 2 12 1 D0201 LTST-C193TBKT-5A BLUE1 R0201 2.2K +/-5% 1/16W 1 12 D0202 LTST-C193TBKT-5A BLUE2 R0202 2.2K +/-5% 1/16W VMCU_1V8 VCC_1V8 R0221 10K +/-5% 1/16W J0206 1 3 5 7 9 2 4 6 8 10 R0206 W X1145205260 VCC_3V3 VCCB SX_DIO2 [2] 10K +/-5% 1/16W VCC_3V3 PESDNC2FD5VBH 1 [2,3] SW_RST 2 D0204 3 S0201 1 4 2 W T-1203 R0203 2.2K +/-5% 1/16W VMCU_1V8 DTC043ZEBTL 1 B 3 C Q0203 DTC043ZEBTL [2] LED0 1 B 3 C Q0201 DTC043ZEBTL [2] LED1 1 B 3 C Q0202 E 2 E 2 E 2 A Antenna Design [2] ANT_LORA R0212 0R +/-5% 1/16W R0210 NM R0211 NM J0211 1 2 3 HC1650650 NOTE: 1.The length of the trace from switch to antenna port is less than 10 mm. 2.Trace length from SPDT to ANT_LORA is 3.62 mm in module. There's only 6 mm reserved on the TE-B. R0213 NM U0202 RFBPF1107A107A5U R0214 NM J0215 [2] ANT_BLE R0207 1 Input port 4 Output port R0218 1 0R +/-5% 1/16W R0216 NM 2 GND1 3 GND2 5 GND3 0R +/-5% 1/16W 2 3 HC1650650 A R0217 NM Quectel Wireless Solutions PROJECT KG100S VER 1.0.0 DRAWN BY Wain ZHAO CHECKED BY Soni RAO SIZE A2 DATE Monday, November 14, 2022 SHEET 2 OF 3 5 4 3 2 1 5 4 3 2 USB & JLINK Interfaces USB Interface D R0303 0R +/-5% 1/16W [3] DBG_TXD_3V3 [3] DBG_RXD_3V3 R0304 0R +/-5% 1/16W 29 GND 28 DTR 27 DSR 26 TXD 25 RXD 24 RTS 23 CTS 22 NC11 90OHM_USB_DP 90OHM_USB_DM Increase EMC capability. D0302 ICMEF112P900MFR 1 1 2 2 3 90OHM_USB_DP_CN 3 4 90OHM_USB_DM_CN 4 1 VBUS 90OHM_USB_DM_CN 90OHM_USB_DP_CN D0301 J0301 1 2 VBUS 3 USB_DM 4 USB_DP 5 USB_ID GND1 9 GND5 8 GND4 11 GND7 10 GND6 5 GND1 6 GND2 6 GND2 7 GND3 W X4558105890 PTVSHC2EN7VU 2 R0311 0R +/-5% 1/8W C USB_VBUS 90OHM_USB_DP 90OHM_USB_DM C0303 C0301 C0302 1 DCD 2 RI 3 GND1 4 D+ 5 D- 6 VDD 7 REGIN NM R0301 C0304 4.7K +/-5% 1/16W C0305 U0301 CP2102-GM 21 NC10 20 NC9 19 NC8 18 NC7 17 NC6 16 NC5 15 NC4 R0302 10K +/-5% 1/16W 1 D C 4.7uF +/-10% 10V 100nF +/-10% 10V 4.7uF +/-20% 6.3V 100nF +/-10% 10V 8 VBUS 9 RST 10 NC1 11 SUSPEND1 12 SUSPEND2 13 NC2 14 NC3 C0306 C0307 JLINK Interface 100nF +/-10% 10V 100nF +/-10% 10V U0302 VMCU_1V8 1 VCCA 14 VCCB VCCB [2] DBG_TXD 0R +/-5% 1/16W R0310 2 A1 13 B1 DBG_TXD_3V3 [3] [3] DBG_RXD 0R +/-5% 1/16W R0307 3 A2 12 B2 DBG_RXD_3V3 [2,3] [2] SWCLK 0R +/-5% 1/16W R0315 4 A3 11 B3 SWCLK_3V3 [3] B [2] SWDIO 0R +/-5% 1/16W R0314 5 A4 10 B4 SWDIO_3V3 [3] 6 NC1 9 NC2 7 GND 8 OE 10K +/-5% 1/16W R0308 VCC_1V8 TXS0104EPW R R0309 VMCU_1V8 C0308 R0318 4.7K +/-5% 1/16W VCC_3V3 [3] SWDIO_3V3 [3] SWCLK_3V3 [3] SWO_3V3 [3] SW_RST_3V3 R0316 NM J0302 1 1 3 3 5 5 7 7 9 9 11 11 13 13 15 15 2 2 4 4 6 6 8 8 10 10 12 12 14 14 16 16 IDE_8X2_2.54 1nF +/-10% 25V 1 B 100K +/-5% 1/16W Q0301 PNT523T503E0-2 [2] SWO 0R +/-5% 1/16W R0317 2 E 3 C R0323 R0321 0R +/-5% 1/16W SWO_3V3 [3] 0R +/-5% 1/16W /NM VCC_3V3 NOTE 1 VMCU_1V8 R0320 A 4.7K +/-5% 1/16W 1 B [2] SW_RST_3V3 Q0302 PNT523T503E0-2 0R +/-5% 1/16W R0319 2 E 3 C R0324 0R +/-5% 1/16W R0322 10K +/-5% 1/16W SW_RST [2] NOTE 2 NOTE: 1. The voltage level is determined by the MCU firmware. 2. The SW_RST is not useful signal. 5 4 3 2 B A Quectel Wireless Solutions PROJECT KG100S VER 1.0.0 DRAWN BY Wain ZHAO CHECKED BY Soni RAO SIZE A2 DATE Monday, November 14, 2022 1 SHEET 3 OF 3
1.35 MB
EP06&EG06&EM06 Series FILE Application Note LTE-A Module Series Version: 1.0 Date: 2022-10-10 Status: Released LTE-A Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. EP06&EG06&EM06_Series_File_Application_Note 1 / 26 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. 2022. All rights reserved. EP06&EG06&EM06_Series_File_Application_Note 2 / 26 LTE-A Module Series About the Document Revision History Version 1.0 Date 2022-09-09 2022-10-10 Author Monan TIAN Monan TIAN Description Creation of the document First official release EP06&EG06&EM06_Series_File_Application_Note 3 / 26 LTE-A Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index...................................................................................................................................................5 1 Introduction .......................................................................................................................................... 6 1.1. Process of Using FILE AT Commands .................................................................................... 6 1.2. Description of Data Mode........................................................................................................ 7 2 Description of FILE AT Commands ................................................................................................... 8 2.1. AT Command Introduction....................................................................................................... 8 2.1.1. Definitions.........................................................................................................................8 2.1.2. AT Command Syntax ....................................................................................................... 8 2.2. Declaration of AT Command Examples .................................................................................. 9 2.3. AT Command Description ....................................................................................................... 9 2.3.1. AT+QFLDS Get Space Information of Storage Medium ............................................... 9 2.3.2. AT+QFLST List File Information on Storage Medium ................................................. 10 2.3.3. AT+QFDEL Delete File(s) on Storage Medium ........................................................... 12 2.3.4. AT+QFUPL Upload a File to Storage Medium ............................................................ 12 2.3.5. AT+QFDWL Download a File from Storage Medium .................................................. 14 2.3.6. AT+QFOPEN Open a File ........................................................................................... 15 2.3.7. AT+QFREAD Read a File............................................................................................ 16 2.3.8. AT+QFWRITE Write Data into a File........................................................................... 17 2.3.9. AT+QFSEEK Set a File Pointer to the Specified Position........................................... 18 2.3.10. AT+QFPOSITION Get the Offset of a File Pointer...................................................... 19 2.3.11. AT+QFCLOSE Close a File......................................................................................... 19 3 Examples ............................................................................................................................................ 21 3.1. Upload and Download a File ................................................................................................. 21 3.1.1. Upload a File .................................................................................................................. 21 3.1.1.1. Non-ACK Mode..................................................................................................... 21 3.1.1.2. ACK Mode ............................................................................................................ 21 3.1.2. Download a File ............................................................................................................. 22 3.2. Write into and Read Files ...................................................................................................... 22 3.2.1. Write into and Read a UFS File ..................................................................................... 22 3.2.2. Write into and Read an SD File ..................................................................................... 22 4 Summary of Error Codes .................................................................................................................. 24 5 Appendix References ........................................................................................................................ 26 EP06&EG06&EM06_Series_File_Application_Note 4 / 26 LTE-A Module Series Table Index Table 1: Type of AT Commands ................................................................................................................... 8 Table 2: Summary of Error Codes.............................................................................................................. 24 Table 3: Terms and Abbreviations .............................................................................................................. 26 EP06&EG06&EM06_Series_File_Application_Note 5 / 26 LTE-A Module Series 1 Introduction Quectel LTE-A EP06, EG06, and EM06 series support AT commands to manipulate files on different physical storage mediums. This document is a reference guide to these commands. The modules support the following storage mediums: UFS: User File Storage directory. It is a special directory on the flash file system. SD: SD card directory. NOTE 1. The contains the storage location. When it begins with 'UFS:' or with no prefix, it means that the file is stored in UFS. When it begins with 'SD:', it means that the file is stored in SD card. 2. EM06 and EP06 series modules do not support SD storage medium. 1.1. Process of Using FILE AT Commands The general procedure for uploading/downloading, opening/creating, reading and writing to a file in the storage: 1. Upload a file to the storage with AT+QFUPL, and output/download it through the serial interface with AT+QFDWL. 2. Open the file with AT+QFOPEN. Once the file is opened, you can write to it or read from it any time and from any location until the file is closed with AT+QFCLOSE. When opening a file with AT+QFOPEN, you can set the file to overwrite mode, read-only mode or other mode with (For more information about , see Chapter 2.3.6). After opening the file, is assigned to it so that various file operations can be carried out. After opening the file, write the data to the file with AT+QFWRITE and read the data with AT+QFREAD from the current file pointer position. Set the file pointer position with AT+QFSEEK and query the current file pointer position with AT+QFPOSITION. Close the file with AT+QFCLOSE, after which the turns invalid. Use the following commands to manage files on the storage medium: EP06&EG06&EM06_Series_File_Application_Note 6 / 26 LTE-A Module Series 1. AT+QFLDS Get the space information of the storage medium. 2. AT+QFLST List the file information in the storage medium. 3. AT+QFDEL Delete the file(s) in the storage medium. 4N. OTE The file handle obtained after executing AT+QFOPEN must be closed with AT+QFCLOSE after the operation is completed, otherwise the file handle will be leaked. 1.2. Description of Data Mode The module COM port has two working modes: the AT command mode and the data mode. In the AT command mode, the data inputted via COM port will be treated as AT commands; while in the data mode, they will be treated as data. Enter Data Mode Execute AT+QFUPL, AT+QFDWL, AT+QFREAD, or AT+QFWRITE, the module returns CONNECT, and the COM port enters the data mode. Or re-enter the data mode by executing ATO. Exit Data Mode Input +++ to make the COM port exit the data mode. After +++ is inputted, the execution of data-mode-entering commands will be interrupted before the module responds OK, and at this time, the COM port cannot re-enter the data mode if you execute ATO. To prevent the +++ from being misinterpreted as data, the following requirements should be followed: 1. Do not input any character for at least 1 second before inputting +++. 2. Finish inputting +++ within 1 second, during which no other character shall be inputted. 3. After inputting +++, wait until OK is returned. The response OK indicates that the COM port exits the data mode. EP06&EG06&EM06_Series_File_Application_Note 7 / 26 LTE-A Module Series 2 Description of FILE AT Commands 2.1. AT Command Introduction 2.1.1. Definitions Carriage return character. Line feed character. Parameter name. Angle brackets do not appear on 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 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. EP06&EG06&EM06_Series_File_Application_Note 8 / 26 LTE-A Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 2.3. AT Command Description 2.3.1. AT+QFLDS Get Space Information of Storage Medium This command gets the space information of the specified storage medium. AT+QFLDS Get Space Information of Storage Medium Test Command AT+QFLDS=? Write Command AT+QFLDS= Response OK Response +QFLDS: , OK Execution Command AT+QFLDS If there is an error: +CME ERROR: Response Return the UFS information: +QFLDS: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Storage medium type. 'UFS' UFS EP06&EG06&EM06_Series_File_Application_Note 9 / 26 LTE-A Module Series 'SD' SD card Integer type. Free space size of . Unit: byte. Integer type. Total space size of . Unit: byte. Integer type. Size of all files in UFS. Unit: byte. Integer type. Number of files in UFS. Integer type. Error code. See Chapter 4 for details. Example AT+QFLDS='UFS' +QFLDS: 578847,917503 OK AT+QFLDS='SD' +QFLDS: 251920384,253132800 OK //Query the space information of UFS. //Query the space information of SD card. 2.3.2. AT+QFLST List File Information on Storage Medium This command lists the information of a single file or all files on the specified storage medium. AT+QFLST List File Information on Storage Medium Test Command AT+QFLST=? Write Command AT+QFLST= Response OK Response +QFLST: , [+QFLST: , […]] OK Execution Command AT+QFLST If there is an error: +CME ERROR: Response Return the information of the UFS files: +QFLST: , [+QFLST: , […]] OK If there is an error: EP06&EG06&EM06_Series_File_Application_Note 10 / 26 LTE-A Module Series Maximum Response Time Characteristics +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file(s) to be listed. Maximum length: 80 bytes. '*' All files in UFS '' The specified in UFS 'UFS:*' All files in UFS 'UFS:' The specified in UFS 'SD:*' All files in SD card 'SD:' The specified in SD card String type. Exact file name. Integer type. File size. Unit: byte. Integer type. Error code. See Chapter 4 for details. Example AT+QFLST='*' +QFLST: 'UFS:1k.txt',1024 +QFLST: 'UFS:2k.txt',2048 +QFLST: 'UFS:3k.txt',3072 OK AT+QFLST='SD:*' +QFLST: 'SD:1k.txt',1024 +QFLST: 'SD:10k.txt',10240 +QFLST: 'SD:100k.txt',102400 OK //List all files in UFS. //List all files in SD card. NOTE AT+QFLST queries the actual size of the file currently stored in flash. After the data are written in with AT+QFWRITE, if you fail to query the file size by executing AT+QFLST, please close the file with AT+QFCLOSE before another query. EP06&EG06&EM06_Series_File_Application_Note 11 / 26 LTE-A Module Series 2.3.3. AT+QFDEL Delete File(s) on Storage Medium This command deletes a single file or all the files on the specified storage medium. AT+QFDEL Delete File(s) on Storage Medium Test Command AT+QFDEL=? Response +QFDEL: Write Command AT+QFDEL= OK Response OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file to be deleted. Maximum length: 80 bytes. '*' Delete all files in UFS (do not delete the directory) '' Delete the specified in UFS 'UFS:*' Delete all files in UFS (do not delete the directory) 'UFS:' Delete the specified in UFS 'SD:*' Delete all files in SD card (do not delete the directory) 'SD:' Delete the specified in SD card String type. Exact file name. Integer type. Error code. See Chapter 4 for details. Example AT+QFDEL='*' OK AT+QFDEL='UFS:1.txt' OK AT+QFDEL='SD:*' OK //Delete all files in UFS (do not delete the directory). //Delete the file 1.txt in UFS. //Delete all files in SD card (do not delete the directory). 2.3.4. AT+QFUPL Upload a File to Storage Medium This command uploads a file to a storage medium. If any file on the storage medium has the same name as the file to be uploaded, an error will be reported. EP06&EG06&EM06_Series_File_Application_Note 12 / 26 LTE-A Module Series When the uploaded data reach , or if no data are inputted until is reached, the module will exit the data mode automatically. During data transmission, you can send '+++' to make the module exit the data mode. For more details, see Chapter 1.2. For the Linux example of this command, see quec_upload.zip package. For the example introduction, see the Readme file in quec_upload.zip. Please contact Quectel technical support to obtain the quec_upload.zip package. AT+QFUPL Upload a File to Storage Medium Test Command AT+QFUPL=? Response +QFUPL: ,(1-),(range of supported s),(list of supported s) Write Command AT+QFUPL=[,[, [,]]] OK Response CONNECT TA switches to the data mode (transparent transmission mode), and the binary data of the file can be inputted. When the total size of the inputted data reaches or TA receives +++, TA will return to the AT command mode and respond: +QFUPL: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Free space size of . See Chapter 2.3.1 for more details. String type. Name pattern of the file to be uploaded. Maximum length: 80 bytes. '' The specified to be uploaded to UFS 'UFS:' The specified to be uploaded to UFS 'SD:' The specified to be uploaded to SD card String type. Exact file name. Integer type. File size expected to be uploaded. Default: 10240. Unit: byte. The maximum length is not greater than . Integer type. Actual size of uploaded data. Unit: byte. EP06&EG06&EM06_Series_File_Application_Note 13 / 26 LTE-A Module Series Integer type. Waiting time for inputting data to USB/UART. Range: 1–65535. Default: 5. Unit: s. Integer type. Indicates whether to use ACK mode. 0 Turn off the ACK mode 1 Turn on the ACK mode Integer type. Checksum of uploaded data. Integer type. Error code. See Chapter 4 for details. NOTE 1. It is strongly recommended to use DOS 8.3 file name format for . 2. is a 16-bit checksum based on bitwise Exclusive-OR (XOR). If the number of bytes is odd, the last byte is set as the upper 8 bits, and the lower 8 bits are set as 0. Then an XOR operator is used to calculate the checksum. Inputting +++ will make the TA end the data transmission and switch to the AT command mode. However, the previously uploaded data will be preserved in the file. 3. When executing the command, the data must be inputted after CONNECT is returned. 4. The ACK mode is a safeguard against data loss when uploading large files in case the hardware flow control does not work. The ACK mode works as follows: 1) Run AT+QFUPL=,,,1 to enable the ACK mode. 2) The module outputs CONNECT. 3) MCU sends 1 KB of data, to which the module responds with an A. 4) MCU receives the A and then sends the next 1 KB of data. 5) Repeat the step 3) and 4) until the transfer is completed. For an example of ACK mode use, see Chapter 3.1.1.2. 2.3.5. AT+QFDWL Download a File from Storage Medium This command downloads a specified file from the storage medium. For the Linux example of this command, see the Linux example of AT+QFUPL. AT+QFDWL Download a File from Storage Medium Test Command AT+QFDWL=? Response +QFDWL: Write Command AT+QFDWL= OK Response CONNECT TA switches to the data mode, and the binary data of the file can be outputted. When the content of the file is read or the TA receives +++, the TA will return to the AT command mode and respond: EP06&EG06&EM06_Series_File_Application_Note 14 / 26 LTE-A Module Series Maximum Response Time Characteristics +QFDWL: , OK If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file to be downloaded. Maximum length: 80 bytes. '' The specified UFS to be downloaded 'UFS:' The specified UFS to be downloaded 'SD: ' The specified SD to be downloaded String type. Exact file name. Integer type. Size of the downloaded data. Integer type. Checksum of the downloaded data. Integer type. Error code. See Chapter 4 for details. NOTE 1. +++ will cause the TA to end the data transmission and switch to the AT command mode. 2. is a 16-bit checksum based on bitwise XOR. 2.3.6. AT+QFOPEN Open a File This command opens a file and gets the file handle to be used in commands such as AT+QFREAD, AT+QFWRITE, AT+QFSEEK, AT+QFPOSITION and AT+QFCLOSE. AT+QFOPEN Open a File Test Command AT+QFOPEN=? Response +QFOPEN: ,(range of supported s) Read Command AT+QFOPEN? OK Response +QFOPEN: ,, [+QFOPEN: ,, […]] EP06&EG06&EM06_Series_File_Application_Note 15 / 26 LTE-A Module Series Write Command AT+QFOPEN=[,] OK Response +QFOPEN: OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file to be opened. Maximum length: 80 bytes. '' The specified UFS to be opened 'UFS:' The specified UFS to be opened 'SD: ' The specified SD to be opened String type. Exact file name. Integer type. Handle of the file to be operated. Integer type. File opening mode. 0 If the file does not exist, it will be created. If the file exists, it will be opened directly. In both cases, the file can be read and written to. 1 If the file does not exist, it will be created. If the file exists, it will be cleared and overwritten. In both cases, the file can be read and written to. 2 If the file does not exist, an error will be responded. If the file exists, it will be opened directly and read only. Integer type. Error code. See Chapter 4 for details. 2.3.7. AT+QFREAD Read a File This command reads the data of a file specified by the file handle. The data start from the current position of the file pointer that belongs to the file handle. For the Linux example of this command, see the Linux example of AT+QFUPL. AT+QFREAD Read a File Test Command AT+QFREAD=? Response +QFREAD: , OK EP06&EG06&EM06_Series_File_Application_Note 16 / 26 LTE-A Module Series Write Command AT+QFREAD=[,] Response CONNECT TA switches to the data mode. When the total size of the data reaches or TA receives +++, TA will return to the AT command mode, display the result, and then respond: OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Expected length of file to be read. Default length: 10 KB. If file length is less than 10 KB, the actual length of the file will be read. Unit: byte. Integer type. Actual read length. Unit: byte. Integer type. Error code. See Chapter 4 for details. 2.3.8. AT+QFWRITE Write Data into a File This command writes data into a file. The data start from the current position of the file pointer that belongs to the file handle. For the Linux example of this command, see the Linux example of AT+QFUPL. AT+QFWRITE Write Data into a File Test Command AT+QFWRITE=? Response +QFWRITE: ,, Write Command AT+QFWRITE=[, [,]] OK Response CONNECT TA switches to the data mode. When the total size of the written data reaches , TA receives +++ or the time reaches , TA will return to the AT command mode and respond: +QFWRITE: , OK EP06&EG06&EM06_Series_File_Application_Note 17 / 26 LTE-A Module Series Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Length of the file which data are written into. Default length: 10 KB. Maximum value of this parameter is determined by of AT+QFUPL. Unit: byte. Integer type. Waiting time for inputting data to USB/UART. Default: 5. Unit: s. Integer type. Actual written length. Unit: byte. Integer type. Total length of the file. Unit: byte. Integer type. Error code. See Chapter 4 for details. 2.3.9. AT+QFSEEK Set a File Pointer to the Specified Position This command sets a file pointer to the specified position. This will decide the starting position of the commands AT+QFREAD, AT+QFWRITE and AT+QFPOSITION. AT+QFSEEK Set a File Pointer to the Specified Position Test Command AT+QFSEEK=? Response +QFSEEK: ,, Write Command AT+QFSEEK=,[,< position>] OK Response OK If there is an error: +CME ERROR: Maximum Response Time 300 ms Characteristics The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Number of bytes of file pointer movement. EP06&EG06&EM06_Series_File_Application_Note 18 / 26 LTE-A Module Series Integer type. Pointer movement mode. 0 Move forward from the beginning of the file 1 Move forward from the current position of the pointer 2 Move backward from the end of the file Integer type. Error code. See Chapter 4 for details. NOTE If the set final position of the pointer exceeds the file size, executing this command will return ERROR. 2.3.10. AT+QFPOSITION Get the Offset of a File Pointer This command gets the offset of a file pointer from the beginning of the file. AT+QFPOSITION Get the Offset of a File Pointer Test Command AT+QFPOSITION=? Response +QFPOSITION: Write Command AT+QFPOSITION= OK Response +QFPOSITION: OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Offset from the beginning of file. Integer type. Error code. See Chapter 4 for details. 2.3.11. AT+QFCLOSE Close a File This command closes a file and ends all file operations. After that, the file handle is released and should not be used again, unless the file is re-opened with AT+QFOPEN. EP06&EG06&EM06_Series_File_Application_Note 19 / 26 LTE-A Module Series AT+QFCLOSE Close a File Test Command AT+QFCLOSE=? Write Command AT+QFCLOSE= Maximum Response Time Characteristics Response +QFCLOSE: OK Response OK If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Error code. See Chapter 4 for details. EP06&EG06&EM06_Series_File_Application_Note 20 / 26 LTE-A Module Series 3 Examples 3.1. Upload and Download a File 3.1.1. Upload a File 3.1.1.1. Non-ACK Mode AT+QFUPL='test1.txt',10 CONNECT +QFUPL: 10,3938 OK //Upload the text file test1.txt to UFS. //Input the binary data of the file. 3.1.1.2. ACK Mode The ACK mode makes the data transmission more reliable. When transmitting a large file without hardware flow control, the ACK mode is recommended to prevent data loss. For more details about ACK mode, see AT+QFUPL. AT+QFUPL='test.txt',3000,5,1 CONNECT A A +QFUPL: 3000,B34A //Upload the text file test.txt to UFS. //Input 1024 bytes of the binary data of the file. //After MCU sends 1024 bytes of data, the module will respond an A. Then the next 1024 bytes of data can be inputted. //Input 1024 bytes of the binary data of the file. //Input the rest binary data of the file. OK EP06&EG06&EM06_Series_File_Application_Note 21 / 26 3.1.2. Download a File AT+QFDWL='test.txt' CONNECT +QFDWL: 10,613e OK LTE-A Module Series //Download the text file test.txt from UFS. //Binary data of the file is outputted. //Size and checksum value of the downloaded data are returned. 3.2. Write into and Read Files 3.2.1. Write into and Read a UFS File AT+QFOPEN='test.txt',1 +QFOPEN: 3023 //Open the file to get the file handle. OK AT+QFWRITE=3023,10 CONNECT +QFWRITE: 10,10 OK AT+QFSEEK=3023,0,0 OK AT+QFREAD=3023,10 CONNECT 10 //Write 10 bytes of data into the file. //Write in the file data in the data mode. //The actual written bytes and the size of the file are returned. //Set the file pointer to the beginning of the file. //Read 10 bytes of data from the file. //Read data in the data mode. OK AT+QFCLOSE=3023 OK //Close the file. 3.2.2. Write into and Read an SD File AT+QFOPEN='SD:1.txt',1 +QFOPEN: 3024 //Open the file to get the file handle. OK AT+QFWRITE=3024,1024 CONNECT //Write 1024 bytes of data into the file. //Write in the file data in the data mode. EP06&EG06&EM06_Series_File_Application_Note 22 / 26 +QFWRITE: 1024,1024 OK AT+QFSEEK=3024,0,0 OK AT+QFREAD=3024,1024 CONNECT 1024 OK AT+QFCLOSE=3024 OK LTE-A Module Series //The actual written bytes and the size of the file are returned. //Set the file pointer to the beginning of the file. //Read 1024 bytes of data from the file. //Read data in the data mode. //Close the file. EP06&EG06&EM06_Series_File_Application_Note 23 / 26 LTE-A Module Series 4 Summary of Error Codes The error code indicates an error related to mobile equipment. The details about are presented in the following table. Table 2: Summary of Error Codes 400 401 402 403 405 406 407 409 410 411 413 414 416 417 418 419 420 Meaning Invalid input value Larger than the size of the file Zero-byte read Drive full File not found Invalid file name File already exists Failed to write to the file Failed to open the file Failed to read the file Reached the max. number of files allowed to be opened Read-only file Invalid file descriptor Failed to list the file Failed to delete the file Failed to get disk info No space EP06&EG06&EM06_Series_File_Application_Note 24 / 26 421 Time out 423 File too large 425 Invalid parameter 426 File already opened LTE-A Module Series EP06&EG06&EM06_Series_File_Application_Note 25 / 26 LTE-A Module Series 5 Appendix References Table 3: Terms and Abbreviations Abbreviation ACK COM DOS ME SD TA UART UFS USB XOR Description Acknowledgement Communication Port Disk Operating System Mobile Equipment Secure Digital Terminal Adapter Universal Asynchronous Receiver-Transmitter User File Storage Universal Serial Bus Exclusive OR EP06&EG06&EM06_Series_File_Application_Note 26 / 26
369.05 KB
EM12&EG12&EG18 Series FILE Application Note LTE-A Module Series Version: 1.0 Date: 2022-10-10 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_File_Application_Note 1 / 26 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. 2022. All rights reserved. EM12&EG12&EG18_Series_File_Application_Note 2 / 26 LTE-A Module Series About the Document Revision History Version 1.0 Date 2022-09-09 2022-10-10 Author Monan TIAN Monan TIAN Description Creation of the document First official release EM12&EG12&EG18_Series_File_Application_Note 3 / 26 LTE-A Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index...................................................................................................................................................5 1 Introduction .......................................................................................................................................... 6 1.1. Process of Using FILE AT Commands .................................................................................... 6 1.2. Description of Data Mode........................................................................................................ 7 2 Description of FILE AT Commands ................................................................................................... 8 2.1. AT Command Introduction....................................................................................................... 8 2.1.1. Definitions.........................................................................................................................8 2.1.2. AT Command Syntax ....................................................................................................... 8 2.2. Declaration of AT Command Examples .................................................................................. 9 2.3. AT Command Description ....................................................................................................... 9 2.3.1. AT+QFLDS Get Space Information of Storage Medium ............................................... 9 2.3.2. AT+QFLST List File Information on Storage Medium ................................................. 10 2.3.3. AT+QFDEL Delete File(s) on Storage Medium ........................................................... 12 2.3.4. AT+QFUPL Upload a File to Storage Medium ............................................................ 12 2.3.5. AT+QFDWL Download a File from Storage Medium .................................................. 14 2.3.6. AT+QFOPEN Open a File ........................................................................................... 15 2.3.7. AT+QFREAD Read a File............................................................................................ 16 2.3.8. AT+QFWRITE Write Data into a File........................................................................... 17 2.3.9. AT+QFSEEK Set a File Pointer to the Specified Position........................................... 18 2.3.10. AT+QFPOSITION Get the Offset of a File Pointer...................................................... 19 2.3.11. AT+QFCLOSE Close a File......................................................................................... 19 3 Examples ............................................................................................................................................ 21 3.1. Upload and Download a File ................................................................................................. 21 3.1.1. Upload a File .................................................................................................................. 21 3.1.1.1. Non-ACK Mode..................................................................................................... 21 3.1.1.2. ACK Mode ............................................................................................................ 21 3.1.2. Download a File ............................................................................................................. 22 3.2. Write into and Read Files ...................................................................................................... 22 3.2.1. Write into and Read a UFS File ..................................................................................... 22 3.2.2. Write into and Read an SD File ..................................................................................... 22 4 Summary of Error Codes .................................................................................................................. 24 5 Appendix References ........................................................................................................................ 26 EM12&EG12&EG18_Series_File_Application_Note 4 / 26 LTE-A Module Series Table Index Table 1: Type of AT Commands ................................................................................................................... 8 Table 2: Summary of Error Codes.............................................................................................................. 24 Table 3: Terms and Abbreviations .............................................................................................................. 26 EM12&EG12&EG18_Series_File_Application_Note 5 / 26 LTE-A Module Series 1 Introduction Quectel LTE-A EM12-G, EG12, and EG18 series support AT commands to manipulate files on different physical storage mediums. This document is a reference guide to these commands. The modules support the following storage mediums: UFS: User File Storage directory. It is a special directory on the flash file system. SD: SD card directory. NOTE 1. The contains the storage location. When it begins with 'UFS:' or with no prefix, it means that the file is stored in UFS. When it begins with 'SD:', it means that the file is stored in SD card. 2. The EM12-G module does not support SD storage medium. 1.1. Process of Using FILE AT Commands The general procedure for uploading/downloading, opening/creating, reading and writing to a file in the storage: 1. Upload a file to the storage with AT+QFUPL, and output/download it through the serial interface with AT+QFDWL. 2. Open the file with AT+QFOPEN. Once the file is opened, you can write to it or read from it any time and from any location until the file is closed with AT+QFCLOSE. When opening a file with AT+QFOPEN, you can set the file to overwrite mode, read-only mode or other mode with (For more information about , see Chapter 2.3.6). After opening the file, is assigned to it so that various file operations can be carried out. After opening the file, write the data to the file with AT+QFWRITE and read the data with AT+QFREAD from the current file pointer position. Set the file pointer position with AT+QFSEEK and query the current file pointer position with AT+QFPOSITION. Close the file with AT+QFCLOSE, after which the turns invalid. EM12&EG12&EG18_Series_File_Application_Note 6 / 26 LTE-A Module Series Use the following commands to manage files on the storage medium: 1. AT+QFLDS Get the space information of the storage medium. 2. AT+QFLST List the file information in the storage medium. 3. AT+QFDEL Delete the file(s) in the storage medium. 4N. OTE The file handle obtained after executing AT+QFOPEN must be closed with AT+QFCLOSE after the operation is completed, otherwise the file handle will be leaked. 1.2. Description of Data Mode The module COM port has two working modes: the AT command mode and the data mode. In the AT command mode, the data inputted via COM port will be treated as AT commands; while in the data mode, they will be treated as data. Enter Data Mode Execute AT+QFUPL, AT+QFDWL, AT+QFREAD, or AT+QFWRITE, the module returns CONNECT, and the COM port enters the data mode. Or re-enter the data mode by executing ATO. Exit Data Mode Input +++ to make the COM port exit the data mode. After +++ is inputted, the execution of data-mode-entering commands will be interrupted before the module responds OK, and at this time, the COM port cannot re-enter the data mode if you execute ATO. To prevent the +++ from being misinterpreted as data, the following requirements should be followed: 1. Do not input any character for at least 1 second before inputting +++. 2. Finish inputting +++ within 1 second, during which no other character shall be inputted. 3. After inputting +++, wait until OK is returned. The response OK indicates that the COM port exits the data mode. EM12&EG12&EG18_Series_File_Application_Note 7 / 26 LTE-A Module Series 2 Description of FILE AT Commands 2.1. AT Command Introduction 2.1.1. Definitions Carriage return character. Line feed character. Parameter name. Angle brackets do not appear on 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 Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. EM12&EG12&EG18_Series_File_Application_Note 8 / 26 LTE-A Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 2.3. AT Command Description 2.3.1. AT+QFLDS Get Space Information of Storage Medium This command gets the space information of the specified storage medium. AT+QFLDS Get Space Information of Storage Medium Test Command AT+QFLDS=? Write Command AT+QFLDS= Response OK Response +QFLDS: , OK Execution Command AT+QFLDS If there is an error: +CME ERROR: Response Return the UFS information: +QFLDS: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Storage medium type. 'UFS' UFS EM12&EG12&EG18_Series_File_Application_Note 9 / 26 LTE-A Module Series 'SD' SD card Integer type. Free space size of . Unit: byte. Integer type. Total space size of . Unit: byte. Integer type. Size of all files in UFS. Unit: byte. Integer type. Number of files in UFS. Integer type. Error code. See Chapter 4 for details. Example AT+QFLDS='UFS' +QFLDS: 578847,917503 OK AT+QFLDS='SD' +QFLDS: 251920384,253132800 OK //Query the space information of UFS. //Query the space information of SD card. 2.3.2. AT+QFLST List File Information on Storage Medium This command lists the information of a single file or all files on the specified storage medium. AT+QFLST List File Information on Storage Medium Test Command AT+QFLST=? Write Command AT+QFLST= Response OK Response +QFLST: , [+QFLST: , […]] OK Execution Command AT+QFLST If there is an error: +CME ERROR: Response Return the information of the UFS files: +QFLST: , [+QFLST: , […]] OK If there is an error: EM12&EG12&EG18_Series_File_Application_Note 10 / 26 LTE-A Module Series Maximum Response Time Characteristics +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file(s) to be listed. Maximum length: 80 bytes. '*' All files in UFS '' The specified in UFS 'UFS:*' All files in UFS 'UFS:' The specified in UFS 'SD:*' All files in SD card 'SD:' The specified in SD card String type. Exact file name. Integer type. File size. Unit: byte. Integer type. Error code. See Chapter 4 for details. Example AT+QFLST='*' +QFLST: 'UFS:1k.txt',1024 +QFLST: 'UFS:2k.txt',2048 +QFLST: 'UFS:3k.txt',3072 OK AT+QFLST='SD:*' +QFLST: 'SD:1k.txt',1024 +QFLST: 'SD:10k.txt',10240 +QFLST: 'SD:100k.txt',102400 OK //List all files in UFS. //List all files in SD card. NOTE AT+QFLST queries the actual size of the file currently stored in flash. After the data are written in with AT+QFWRITE, if you fail to query the file size by executing AT+QFLST, please close the file with AT+QFCLOSE before another query. EM12&EG12&EG18_Series_File_Application_Note 11 / 26 LTE-A Module Series 2.3.3. AT+QFDEL Delete File(s) on Storage Medium This command deletes a single file or all the files on the specified storage medium. AT+QFDEL Delete File(s) on Storage Medium Test Command AT+QFDEL=? Response +QFDEL: Write Command AT+QFDEL= OK Response OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file to be deleted. Maximum length: 80 bytes. '*' Delete all files in UFS (do not delete the directory) '' Delete the specified in UFS 'UFS:*' Delete all files in UFS (do not delete the directory) 'UFS:' Delete the specified in UFS 'SD:*' Delete all files in SD card (do not delete the directory) 'SD:' Delete the specified in SD card String type. Exact file name. Integer type. Error code. See Chapter 4 for details. Example AT+QFDEL='*' OK AT+QFDEL='UFS:1.txt' OK AT+QFDEL='SD:*' OK //Delete all files in UFS (do not delete the directory). //Delete the file 1.txt in UFS. //Delete all files in SD card (do not delete the directory). 2.3.4. AT+QFUPL Upload a File to Storage Medium This command uploads a file to a storage medium. If any file on the storage medium has the same name as the file to be uploaded, an error will be reported. EM12&EG12&EG18_Series_File_Application_Note 12 / 26 LTE-A Module Series When the uploaded data reach , or if no data are inputted until is reached, the module will exit the data mode automatically. During data transmission, you can send '+++' to make the module exit the data mode. For more details, see Chapter 1.2. For the Linux example of this command, see quec_upload.zip package. For the example introduction, see the Readme file in quec_upload.zip. Please contact Quectel technical support to obtain the quec_upload.zip package. AT+QFUPL Upload a File to Storage Medium Test Command AT+QFUPL=? Response +QFUPL: ,(1-),(range of supported s),(list of supported s) Write Command AT+QFUPL=[,[, [,]]] OK Response CONNECT TA switches to the data mode (transparent transmission mode), and the binary data of the file can be inputted. When the total size of the inputted data reaches or TA receives +++, TA will return to the AT command mode and respond: +QFUPL: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Free space size of . See Chapter 2.3.1 for more details. String type. Name pattern of the file to be uploaded. Maximum length: 80 bytes. '' The specified to be uploaded to UFS 'UFS:' The specified to be uploaded to UFS 'SD:' The specified to be uploaded to SD card String type. Exact file name. Integer type. File size expected to be uploaded. Default: 10240. Unit: byte. The maximum length is not greater than . Integer type. Actual size of uploaded data. Unit: byte. EM12&EG12&EG18_Series_File_Application_Note 13 / 26 LTE-A Module Series Integer type. Waiting time for inputting data to USB/UART. Range: 1–65535. Default: 5. Unit: s. Integer type. Indicates whether to use ACK mode. 0 Turn off the ACK mode 1 Turn on the ACK mode Integer type. Checksum of uploaded data. Integer type. Error code. See Chapter 4 for details. NOTE 1. It is strongly recommended to use DOS 8.3 file name format for . 2. is a 16-bit checksum based on bitwise Exclusive-OR (XOR). If the number of bytes is odd, the last byte is set as the upper 8 bits, and the lower 8 bits are set as 0. Then an XOR operator is used to calculate the checksum. Inputting +++ will make the TA end the data transmission and switch to the AT command mode. However, the previously uploaded data will be preserved in the file. 3. When executing the command, the data must be inputted after CONNECT is returned. 4. The ACK mode is a safeguard against data loss when uploading large files in case the hardware flow control does not work. The ACK mode works as follows: 1) Run AT+QFUPL=,,,1 to enable the ACK mode. 2) The module outputs CONNECT. 3) MCU sends 1 KB of data, to which the module responds with an A. 4) MCU receives the A and then sends the next 1 KB of data. 5) Repeat the step 3) and 4) until the transfer is completed. For an example of ACK mode use, see Chapter 3.1.1.2. 2.3.5. AT+QFDWL Download a File from Storage Medium This command downloads a specified file from the storage medium. For the Linux example of this command, see the Linux example of AT+QFUPL. AT+QFDWL Download a File from Storage Medium Test Command AT+QFDWL=? Response +QFDWL: Write Command AT+QFDWL= OK Response CONNECT TA switches to the data mode, and the binary data of the file can be outputted. When the content of the file is read or the TA receives +++, the TA will return to the AT command mode and respond: EM12&EG12&EG18_Series_File_Application_Note 14 / 26 LTE-A Module Series Maximum Response Time Characteristics +QFDWL: , OK If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file to be downloaded. Maximum length: 80 bytes. '' The specified UFS to be downloaded 'UFS:' The specified UFS to be downloaded 'SD: ' The specified SD to be downloaded String type. Exact file name. Integer type. Size of the downloaded data. Integer type. Checksum of the downloaded data. Integer type. Error code. See Chapter 4 for details. NOTE 1. +++ will cause the TA to end the data transmission and switch to the AT command mode. 2. is a 16-bit checksum based on bitwise XOR. 2.3.6. AT+QFOPEN Open a File This command opens a file and gets the file handle to be used in commands such as AT+QFREAD, AT+QFWRITE, AT+QFSEEK, AT+QFPOSITION and AT+QFCLOSE. AT+QFOPEN Open a File Test Command AT+QFOPEN=? Response +QFOPEN: ,(range of supported s) Read Command AT+QFOPEN? OK Response +QFOPEN: ,, [+QFOPEN: ,, […]] EM12&EG12&EG18_Series_File_Application_Note 15 / 26 LTE-A Module Series Write Command AT+QFOPEN=[,] OK Response +QFOPEN: OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file to be opened. Maximum length: 80 bytes. '' The specified UFS to be opened 'UFS:' The specified UFS to be opened 'SD: ' The specified SD to be opened String type. Exact file name. Integer type. Handle of the file to be operated. Integer type. File opening mode. 0 If the file does not exist, it will be created. If the file exists, it will be opened directly. In both cases, the file can be read and written to. 1 If the file does not exist, it will be created. If the file exists, it will be cleared and overwritten. In both cases, the file can be read and written to. 2 If the file does not exist, an error will be responded. If the file exists, it will be opened directly and read only. Integer type. Error code. See Chapter 4 for details. 2.3.7. AT+QFREAD Read a File This command reads the data of a file specified by the file handle. The data start from the current position of the file pointer that belongs to the file handle. For the Linux example of this command, see the Linux example of AT+QFUPL. AT+QFREAD Read a File Test Command AT+QFREAD=? Response +QFREAD: , OK EM12&EG12&EG18_Series_File_Application_Note 16 / 26 LTE-A Module Series Write Command AT+QFREAD=[,] Response CONNECT TA switches to the data mode. When the total size of the data reaches or TA receives +++, TA will return to the AT command mode, display the result, and then respond: OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Expected length of file to be read. Default length: 10 KB. If file length is less than 10 KB, the actual length of the file will be read. Unit: byte. Integer type. Actual read length. Unit: byte. Integer type. Error code. See Chapter 4 for details. 2.3.8. AT+QFWRITE Write Data into a File This command writes data into a file. The data start from the current position of the file pointer that belongs to the file handle. For the Linux example of this command, see the Linux example of AT+QFUPL. AT+QFWRITE Write Data into a File Test Command AT+QFWRITE=? Response +QFWRITE: ,, Write Command AT+QFWRITE=[, [,]] OK Response CONNECT TA switches to the data mode. When the total size of the written data reaches , TA receives +++ or the time reaches , TA will return to the AT command mode and respond: +QFWRITE: , OK EM12&EG12&EG18_Series_File_Application_Note 17 / 26 LTE-A Module Series Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Length of the file which data are written into. Default length: 10 KB. Maximum value of this parameter is determined by of AT+QFUPL. Unit: byte. Integer type. Waiting time for inputting data to USB/UART. Default: 5. Unit: s. Integer type. Actual written length. Unit: byte. Integer type. Total length of the file. Unit: byte. Integer type. Error code. See Chapter 4 for details. 2.3.9. AT+QFSEEK Set a File Pointer to the Specified Position This command sets a file pointer to the specified position. This will decide the starting position of the commands AT+QFREAD, AT+QFWRITE and AT+QFPOSITION. AT+QFSEEK Set a File Pointer to the Specified Position Test Command AT+QFSEEK=? Response +QFSEEK: ,, Write Command AT+QFSEEK=,[,< position>] OK Response OK If there is an error: +CME ERROR: Maximum Response Time 300 ms Characteristics The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Number of bytes of file pointer movement. EM12&EG12&EG18_Series_File_Application_Note 18 / 26 LTE-A Module Series Integer type. Pointer movement mode. 0 Move forward from the beginning of the file 1 Move forward from the current position of the pointer 2 Move backward from the end of the file Integer type. Error code. See Chapter 4 for details. NOTE If the set final position of the pointer exceeds the file size, executing this command will return ERROR. 2.3.10. AT+QFPOSITION Get the Offset of a File Pointer This command gets the offset of a file pointer from the beginning of the file. AT+QFPOSITION Get the Offset of a File Pointer Test Command AT+QFPOSITION=? Response +QFPOSITION: Write Command AT+QFPOSITION= OK Response +QFPOSITION: OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Offset from the beginning of file. Integer type. Error code. See Chapter 4 for details. 2.3.11. AT+QFCLOSE Close a File This command closes a file and ends all file operations. After that, the file handle is released and should not be used again, unless the file is re-opened with AT+QFOPEN. EM12&EG12&EG18_Series_File_Application_Note 19 / 26 LTE-A Module Series AT+QFCLOSE Close a File Test Command AT+QFCLOSE=? Write Command AT+QFCLOSE= Maximum Response Time Characteristics Response +QFCLOSE: OK Response OK If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Error code. See Chapter 4 for details. EM12&EG12&EG18_Series_File_Application_Note 20 / 26 LTE-A Module Series 3 Examples 3.1. Upload and Download a File 3.1.1. Upload a File 3.1.1.1. Non-ACK Mode AT+QFUPL='test1.txt',10 CONNECT +QFUPL: 10,3938 OK //Upload the text file test1.txt to UFS. //Input the binary data of the file. 3.1.1.2. ACK Mode The ACK mode makes the data transmission more reliable. When transmitting a large file without hardware flow control, the ACK mode is recommended to prevent data loss. For more details about ACK mode, see AT+QFUPL. AT+QFUPL='test.txt',3000,5,1 CONNECT A A +QFUPL: 3000,B34A //Upload the text file test.txt to UFS. //Input 1024 bytes of the binary data of the file. //After MCU sends 1024 bytes of data, the module will respond an A. Then the next 1024 bytes of data can be inputted. //Input 1024 bytes of the binary data of the file. //Input the rest binary data of the file. OK EM12&EG12&EG18_Series_File_Application_Note 21 / 26 3.1.2. Download a File AT+QFDWL='test.txt' CONNECT +QFDWL: 10,613e OK LTE-A Module Series //Download the text file test.txt from UFS. //Binary data of the file is outputted. //Size and checksum value of the downloaded data are returned. 3.2. Write into and Read Files 3.2.1. Write into and Read a UFS File AT+QFOPEN='test.txt',1 +QFOPEN: 3023 //Open the file to get the file handle. OK AT+QFWRITE=3023,10 CONNECT +QFWRITE: 10,10 OK AT+QFSEEK=3023,0,0 OK AT+QFREAD=3023,10 CONNECT 10 //Write 10 bytes of data into the file. //Write in the file data in the data mode. //The actual written bytes and the size of the file are returned. //Set the file pointer to the beginning of the file. //Read 10 bytes of data from the file. //Read data in the data mode. OK AT+QFCLOSE=3023 OK //Close the file. 3.2.2. Write into and Read an SD File AT+QFOPEN='SD:1.txt',1 +QFOPEN: 3024 //Open the file to get the file handle. OK AT+QFWRITE=3024,1024 CONNECT //Write 1024 bytes of data into the file. //Write in the file data in the data mode. EM12&EG12&EG18_Series_File_Application_Note 22 / 26 +QFWRITE: 1024,1024 OK AT+QFSEEK=3024,0,0 OK AT+QFREAD=3024,1024 CONNECT 1024 OK AT+QFCLOSE=3024 OK LTE-A Module Series //The actual written bytes and the size of the file are returned. //Set the file pointer to the beginning of the file. //Read 1024 bytes of data from the file. //Read data in the data mode. //Close the file. EM12&EG12&EG18_Series_File_Application_Note 23 / 26 LTE-A Module Series 4 Summary of Error Codes The error code indicates an error related to mobile equipment. The details about are presented in the following table. Table 2: Summary of Error Codes 400 401 402 403 405 406 407 409 410 411 413 414 416 417 418 419 420 Meaning Invalid input value Larger than the size of the file Zero-byte read Drive full File not found Invalid file name File already exists Failed to write to the file Failed to open the file Failed to read the file Reached the max. number of files allowed to be opened Read-only file Invalid file descriptor Failed to list the file Failed to delete the file Failed to get disk info No space EM12&EG12&EG18_Series_File_Application_Note 24 / 26 421 Time out 423 File too large 425 Invalid parameter 426 File already opened LTE-A Module Series EM12&EG12&EG18_Series_File_Application_Note 25 / 26 LTE-A Module Series 5 Appendix References Table 3: Terms and Abbreviations Abbreviation ACK COM DOS ME SD TA UART UFS USB XOR Description Acknowledgement Communication Port Disk Operating System Mobile Equipment Secure Digital Terminal Adapter Universal Asynchronous Receiver-Transmitter User File Storage Universal Serial Bus Exclusive OR EM12&EG12&EG18_Series_File_Application_Note 26 / 26
367.93 KB
EG512R&EM12xR&EM160R Series FILE Application Note LTE-A Module Series Version: 1.0 Date: 2022-10-10 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. EG512R&EM12xR&EM160R_Series_File_Application_Note 1 / 27 LTE-A Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. EG512R&EM12xR&EM160R_Series_File_Application_Note 2 / 27 LTE-A Module Series About the Document Revision History Version 1.0 Date 2022-09-09 2022-10-10 Author Monan TIAN Monan TIAN Description Creation of the document First official release EG512R&EM12xR&EM160R_Series_File_Application_Note 3 / 27 LTE-A Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index...................................................................................................................................................5 1 Introduction .......................................................................................................................................... 6 1.1. Applicable Modules ................................................................................................................. 6 1.2. Process of Using FILE AT Commands .................................................................................... 7 1.3. Description of Data Mode........................................................................................................ 7 2 Description of FILE AT Commands ................................................................................................... 9 2.1. AT Command Introduction....................................................................................................... 9 2.1.1. Definitions.........................................................................................................................9 2.1.2. AT Command Syntax ....................................................................................................... 9 2.2. Declaration of AT Command Examples ................................................................................ 10 2.3. AT Command Description ..................................................................................................... 10 2.3.1. AT+QFLDS Get Space Information of Storage Medium ............................................. 10 2.3.2. AT+QFLST List File Information on Storage Medium ................................................. 11 2.3.3. AT+QFDEL Delete File(s) on Storage Medium ........................................................... 13 2.3.4. AT+QFUPL Upload a File to Storage Medium ............................................................ 13 2.3.5. AT+QFDWL Download a File from Storage Medium .................................................. 15 2.3.6. AT+QFOPEN Open a File ........................................................................................... 16 2.3.7. AT+QFREAD Read a File............................................................................................ 17 2.3.8. AT+QFWRITE Write Data into a File........................................................................... 18 2.3.9. AT+QFSEEK Set a File Pointer to the Specified Position........................................... 19 2.3.10. AT+QFPOSITION Get the Offset of a File Pointer...................................................... 20 2.3.11. AT+QFCLOSE Close a File......................................................................................... 20 3 Examples ............................................................................................................................................ 22 3.1. Upload and Download a File ................................................................................................. 22 3.1.1. Upload a File .................................................................................................................. 22 3.1.1.1. Non-ACK Mode..................................................................................................... 22 3.1.1.2. ACK Mode ............................................................................................................ 22 3.1.2. Download a File ............................................................................................................. 23 3.2. Write into and Read Files ...................................................................................................... 23 3.2.1. Write into and Read a UFS File ..................................................................................... 23 3.2.2. Write into and Read an SD File ..................................................................................... 23 4 Summary of Error Codes .................................................................................................................. 25 5 Appendix References ........................................................................................................................ 27 EG512R&EM12xR&EM160R_Series_File_Application_Note 4 / 27 LTE-A Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 6 Table 2: Type of AT Commands ................................................................................................................... 9 Table 3: Summary of Error Codes.............................................................................................................. 25 Table 4: Terms and Abbreviations .............................................................................................................. 27 EG512R&EM12xR&EM160R_Series_File_Application_Note 5 / 27 LTE-A Module Series 1 Introduction Quectel LTE-A EG512R-EA, EM120R-GL, EM121R-GL, and EM160R-GL support AT commands to manipulate files on different physical storage mediums. This document is a reference guide to these commands. The modules support the following storage mediums: UFS: User File Storage directory. It is a special directory on the flash file system. SD: SD card directory. NOTE 1. The contains the storage location. When it begins with 'UFS:' or with no prefix, it means that the file is stored in UFS. When it begins with 'SD:', it means that the file is stored in SD card. 2. EM120R-GL, EM121R-GL, and EM160R-GL modules do not support SD storage medium. 1.1. Applicable Modules Table 1: Applicable Modules Applicable Modules EG512R EG512R-EA EM12xR EM120R-GL EM121R-GL EM160R EM160R-GL EG512R&EM12xR&EM160R_Series_File_Application_Note 6 / 27 LTE-A Module Series 1.2. Process of Using FILE AT Commands The general procedure for uploading/downloading, opening/creating, reading and writing to a file in the storage: 1. Upload a file to the storage with AT+QFUPL, and output/download it through the serial interface with AT+QFDWL. 2. Open the file with AT+QFOPEN. Once the file is opened, you can write to it or read from it any time and from any location until the file is closed with AT+QFCLOSE. When opening a file with AT+QFOPEN, you can set the file to overwrite mode, read-only mode or other mode with (For more information about , see Chapter 2.3.6). After opening the file, is assigned to it so that various file operations can be carried out. After opening the file, write the data to the file with AT+QFWRITE and read the data with AT+QFREAD from the current file pointer position. Set the file pointer position with AT+QFSEEK and query the current file pointer position with AT+QFPOSITION. Close the file with AT+QFCLOSE, after which the turns invalid. Use the following commands to manage files on the storage medium: 1. AT+QFLDS Get the space information of the storage medium. 2. AT+QFLST List the file information in the storage medium. 3. AT+QFDEL Delete the file(s) in the storage medium. 4N. OTE The file handle obtained after executing AT+QFOPEN must be closed with AT+QFCLOSE after the operation is completed, otherwise the file handle will be leaked. 1.3. Description of Data Mode The module COM port has two working modes: the AT command mode and the data mode. In the AT command mode, the data inputted via COM port will be treated as AT commands; while in the data mode, they will be treated as data. Enter Data Mode Execute AT+QFUPL, AT+QFDWL, AT+QFREAD, or AT+QFWRITE, the module returns CONNECT, and the COM port enters the data mode. Or re-enter the data mode by executing ATO. EG512R&EM12xR&EM160R_Series_File_Application_Note 7 / 27 LTE-A Module Series Exit Data Mode Input +++ to make the COM port exit the data mode. After +++ is inputted, the execution of data-mode-entering commands will be interrupted before the module responds OK, and at this time, the COM port cannot re-enter the data mode if you execute ATO. To prevent the +++ from being misinterpreted as data, the following requirements should be followed: 1. Do not input any character for at least 1 second before inputting +++. 2. Finish inputting +++ within 1 second, during which no other character shall be inputted. 3. After inputting +++, wait until OK is returned. The response OK indicates that the COM port exits the data mode. EG512R&EM12xR&EM160R_Series_File_Application_Note 8 / 27 LTE-A Module Series 2 Description of FILE AT Commands 2.1. AT Command Introduction 2.1.1. Definitions Carriage return character. Line feed character. Parameter name. Angle brackets do not appear on 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 2: 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. EG512R&EM12xR&EM160R_Series_File_Application_Note 9 / 27 LTE-A Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 2.3. AT Command Description 2.3.1. AT+QFLDS Get Space Information of Storage Medium This command gets the space information of the specified storage medium. AT+QFLDS Get Space Information of Storage Medium Test Command AT+QFLDS=? Write Command AT+QFLDS= Response OK Response +QFLDS: , OK Execution Command AT+QFLDS If there is an error: +CME ERROR: Response Return the UFS information: +QFLDS: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Storage medium type. 'UFS' UFS EG512R&EM12xR&EM160R_Series_File_Application_Note 10 / 27 LTE-A Module Series 'SD' SD card Integer type. Free space size of . Unit: byte. Integer type. Total space size of . Unit: byte. Integer type. Size of all files in UFS. Unit: byte. Integer type. Number of files in UFS. Integer type. Error code. See Chapter 4 for details. Example AT+QFLDS='UFS' +QFLDS: 578847,917503 OK AT+QFLDS='SD' +QFLDS: 251920384,253132800 OK //Query the space information of UFS. //Query the space information of SD card. 2.3.2. AT+QFLST List File Information on Storage Medium This command lists the information of a single file or all files on the specified storage medium. AT+QFLST List File Information on Storage Medium Test Command AT+QFLST=? Write Command AT+QFLST= Response OK Response +QFLST: , [+QFLST: , […]] OK Execution Command AT+QFLST If there is an error: +CME ERROR: Response Return the information of the UFS files: +QFLST: , [+QFLST: , […]] OK If there is an error: EG512R&EM12xR&EM160R_Series_File_Application_Note 11 / 27 LTE-A Module Series Maximum Response Time Characteristics +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file(s) to be listed. Maximum length: 80 bytes. '*' All files in UFS '' The specified in UFS 'UFS:*' All files in UFS 'UFS:' The specified in UFS 'SD:*' All files in SD card 'SD:' The specified in SD card String type. Exact file name. Integer type. File size. Unit: byte. Integer type. Error code. See Chapter 4 for details. Example AT+QFLST='*' +QFLST: 'UFS:1k.txt',1024 +QFLST: 'UFS:2k.txt',2048 +QFLST: 'UFS:3k.txt',3072 OK AT+QFLST='SD:*' +QFLST: 'SD:1k.txt',1024 +QFLST: 'SD:10k.txt',10240 +QFLST: 'SD:100k.txt',102400 OK //List all files in UFS. //List all files in SD card. NOTE AT+QFLST queries the actual size of the file currently stored in flash. After the data are written in with AT+QFWRITE, if you fail to query the file size by executing AT+QFLST, please close the file with AT+QFCLOSE before another query. EG512R&EM12xR&EM160R_Series_File_Application_Note 12 / 27 LTE-A Module Series 2.3.3. AT+QFDEL Delete File(s) on Storage Medium This command deletes a single file or all the files on the specified storage medium. AT+QFDEL Delete File(s) on Storage Medium Test Command AT+QFDEL=? Response +QFDEL: Write Command AT+QFDEL= OK Response OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file to be deleted. Maximum length: 80 bytes. '*' Delete all files in UFS (do not delete the directory) '' Delete the specified in UFS 'UFS:*' Delete all files in UFS (do not delete the directory) 'UFS:' Delete the specified in UFS 'SD:*' Delete all files in SD card (do not delete the directory) 'SD:' Delete the specified in SD card String type. Exact file name. Integer type. Error code. See Chapter 4 for details. Example AT+QFDEL='*' OK AT+QFDEL='UFS:1.txt' OK AT+QFDEL='SD:*' OK //Delete all files in UFS (do not delete the directory). //Delete the file 1.txt in UFS. //Delete all files in SD card (do not delete the directory). 2.3.4. AT+QFUPL Upload a File to Storage Medium This command uploads a file to a storage medium. If any file on the storage medium has the same name as the file to be uploaded, an error will be reported. EG512R&EM12xR&EM160R_Series_File_Application_Note 13 / 27 LTE-A Module Series When the uploaded data reach , or if no data are inputted until is reached, the module will exit the data mode automatically. During data transmission, you can send '+++' to make the module exit the data mode. For more details, see Chapter 1.3. For the Linux example of this command, see quec_upload.zip package. For the example introduction, see the Readme file in quec_upload.zip. Please contact Quectel technical support to obtain the quec_upload.zip package. AT+QFUPL Upload a File to Storage Medium Test Command AT+QFUPL=? Response +QFUPL: ,(1-),(range of supported s),(list of supported s) Write Command AT+QFUPL=[,[, [,]]] OK Response CONNECT TA switches to the data mode (transparent transmission mode), and the binary data of the file can be inputted. When the total size of the inputted data reaches or TA receives +++, TA will return to the AT command mode and respond: +QFUPL: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Free space size of . See Chapter 2.3.1 for more details. String type. Name pattern of the file to be uploaded. Maximum length: 80 bytes. '' The specified to be uploaded to UFS 'UFS:' The specified to be uploaded to UFS 'SD:' The specified to be uploaded to SD card String type. Exact file name. Integer type. File size expected to be uploaded. Default: 10240. Unit: byte. The maximum length is not greater than . Integer type. Actual size of uploaded data. Unit: byte. Integer type. Waiting time for inputting data to USB/UART. Range: 1–65535. EG512R&EM12xR&EM160R_Series_File_Application_Note 14 / 27 Default: 5. Unit: s. Integer type. Indicates whether to use ACK mode. 0 Turn off the ACK mode 1 Turn on the ACK mode Integer type. Checksum of uploaded data. Integer type. Error code. See Chapter 4 for details. LTE-A Module Series NOTE 1. It is strongly recommended to use DOS 8.3 file name format for . 2. is a 16-bit checksum based on bitwise Exclusive-OR (XOR). If the number of bytes is odd, the last byte is set as the upper 8 bits, and the lower 8 bits are set as 0. Then an XOR operator is used to calculate the checksum. Inputting +++ will make the TA end the data transmission and switch to the AT command mode. However, the previously uploaded data will be preserved in the file. 3. When executing the command, the data must be inputted after CONNECT is returned. 4. The ACK mode is a safeguard against data loss when uploading large files in case the hardware flow control does not work. The ACK mode works as follows: 1) Run AT+QFUPL=,,,1 to enable the ACK mode. 2) The module outputs CONNECT. 3) MCU sends 1 KB of data, to which the module responds with an A. 4) MCU receives the A and then sends the next 1 KB of data. 5) Repeat the step 3) and 4) until the transfer is completed. For an example of ACK mode use, see Chapter 3.1.1.2. 2.3.5. AT+QFDWL Download a File from Storage Medium This command downloads a specified file from the storage medium. For the Linux example of this command, see the Linux example of AT+QFUPL. AT+QFDWL Download a File from Storage Medium Test Command AT+QFDWL=? Response +QFDWL: Write Command AT+QFDWL= OK Response CONNECT TA switches to the data mode, and the binary data of the file can be outputted. When the content of the file is read or the TA receives +++, the TA will return to the AT command mode and respond: +QFDWL: , EG512R&EM12xR&EM160R_Series_File_Application_Note 15 / 27 LTE-A Module Series Maximum Response Time Characteristics OK If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file to be downloaded. Maximum length: 80 bytes. '' The specified UFS to be downloaded 'UFS:' The specified UFS to be downloaded 'SD: ' The specified SD to be downloaded String type. Exact file name. Integer type. Size of the downloaded data. Integer type. Checksum of the downloaded data. Integer type. Error code. See Chapter 4 for details. NOTE 1. +++ will cause the TA to end the data transmission and switch to the AT command mode. 2. is a 16-bit checksum based on bitwise XOR. 2.3.6. AT+QFOPEN Open a File This command opens a file and gets the file handle to be used in commands such as AT+QFREAD, AT+QFWRITE, AT+QFSEEK, AT+QFPOSITION and AT+QFCLOSE. AT+QFOPEN Open a File Test Command AT+QFOPEN=? Response +QFOPEN: ,(range of supported s) Read Command AT+QFOPEN? OK Response +QFOPEN: ,, [+QFOPEN: ,, […]] OK EG512R&EM12xR&EM160R_Series_File_Application_Note 16 / 27 LTE-A Module Series Write Command AT+QFOPEN=[,] Response +QFOPEN: OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file to be opened. Maximum length: 80 bytes. '' The specified UFS to be opened 'UFS:' The specified UFS to be opened 'SD: ' The specified SD to be opened String type. Exact file name. Integer type. Handle of the file to be operated. Integer type. File opening mode. 0 If the file does not exist, it will be created. If the file exists, it will be opened directly. In both cases, the file can be read and written to. 1 If the file does not exist, it will be created. If the file exists, it will be cleared and overwritten. In both cases, the file can be read and written to. 2 If the file does not exist, an error will be responded. If the file exists, it will be opened directly and read only. Integer type. Error code. See Chapter 4 for details. 2.3.7. AT+QFREAD Read a File This command reads the data of a file specified by the file handle. The data start from the current position of the file pointer that belongs to the file handle. For the Linux example of this command, see the Linux example of AT+QFUPL. AT+QFREAD Read a File Test Command AT+QFREAD=? Response +QFREAD: , Write Command AT+QFREAD=[,] OK Response CONNECT EG512R&EM12xR&EM160R_Series_File_Application_Note 17 / 27 LTE-A Module Series Maximum Response Time Characteristics TA switches to the data mode. When the total size of the data reaches or TA receives +++, TA will return to the AT command mode, display the result, and then respond: OK If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Expected length of file to be read. Default length: 10 KB. If file length is less than 10 KB, the actual length of the file will be read. Unit: byte. Integer type. Actual read length. Unit: byte. Integer type. Error code. See Chapter 4 for details. 2.3.8. AT+QFWRITE Write Data into a File This command writes data into a file. The data start from the current position of the file pointer that belongs to the file handle. For the Linux example of this command, see the Linux example of AT+QFUPL. AT+QFWRITE Write Data into a File Test Command AT+QFWRITE=? Response +QFWRITE: ,, Write Command AT+QFWRITE=[, [,]] OK Response CONNECT TA switches to the data mode. When the total size of the written data reaches , TA receives +++ or the time reaches , TA will return to the AT command mode and respond: +QFWRITE: , OK If there is an error: EG512R&EM12xR&EM160R_Series_File_Application_Note 18 / 27 LTE-A Module Series Maximum Response Time Characteristics +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Length of the file which data are written into. Default length: 10 KB. Maximum value of this parameter is determined by of AT+QFUPL. Unit: byte. Integer type. Waiting time for inputting data to USB/UART. Default: 5. Unit: s. Integer type. Actual written length. Unit: byte. Integer type. Total length of the file. Unit: byte. Integer type. Error code. See Chapter 4 for details. 2.3.9. AT+QFSEEK Set a File Pointer to the Specified Position This command sets a file pointer to the specified position. This will decide the starting position of the commands AT+QFREAD, AT+QFWRITE and AT+QFPOSITION. AT+QFSEEK Set a File Pointer to the Specified Position Test Command AT+QFSEEK=? Response +QFSEEK: ,, Write Command AT+QFSEEK=,[,< position>] OK Response OK If there is an error: +CME ERROR: Maximum Response Time 300 ms Characteristics The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Number of bytes of file pointer movement. Integer type. Pointer movement mode. 0 Move forward from the beginning of the file EG512R&EM12xR&EM160R_Series_File_Application_Note 19 / 27 LTE-A Module Series 1 Move forward from the current position of the pointer 2 Move backward from the end of the file Integer type. Error code. See Chapter 4 for details. NOTE If the set final position of the pointer exceeds the file size, executing this command will return ERROR. 2.3.10. AT+QFPOSITION Get the Offset of a File Pointer This command gets the offset of a file pointer from the beginning of the file. AT+QFPOSITION Get the Offset of a File Pointer Test Command AT+QFPOSITION=? Response +QFPOSITION: Write Command AT+QFPOSITION= OK Response +QFPOSITION: OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Offset from the beginning of file. Integer type. Error code. See Chapter 4 for details. 2.3.11. AT+QFCLOSE Close a File This command closes a file and ends all file operations. After that, the file handle is released and should not be used again, unless the file is re-opened with AT+QFOPEN. EG512R&EM12xR&EM160R_Series_File_Application_Note 20 / 27 LTE-A Module Series AT+QFCLOSE Close a File Test Command AT+QFCLOSE=? Write Command AT+QFCLOSE= Maximum Response Time Characteristics Response +QFCLOSE: OK Response OK If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Error code. See Chapter 4 for details. EG512R&EM12xR&EM160R_Series_File_Application_Note 21 / 27 LTE-A Module Series 3 Examples 3.1. Upload and Download a File 3.1.1. Upload a File 3.1.1.1. Non-ACK Mode AT+QFUPL='test1.txt',10 CONNECT +QFUPL: 10,3938 OK //Upload the text file test1.txt to UFS. //Input the binary data of the file. 3.1.1.2. ACK Mode The ACK mode makes the data transmission more reliable. When transmitting a large file without hardware flow control, the ACK mode is recommended to prevent data loss. For more details about ACK mode, see AT+QFUPL. AT+QFUPL='test.txt',3000,5,1 CONNECT A A +QFUPL: 3000,B34A //Upload the text file test.txt to UFS. //Input 1024 bytes of the binary data of the file. //After MCU sends 1024 bytes of data, the module will respond an A. Then the next 1024 bytes of data can be inputted. //Input 1024 bytes of the binary data of the file. //Input the rest binary data of the file. OK EG512R&EM12xR&EM160R_Series_File_Application_Note 22 / 27 3.1.2. Download a File AT+QFDWL='test.txt' CONNECT +QFDWL: 10,613e OK LTE-A Module Series //Download the text file test.txt from UFS. //Binary data of the file is outputted. //Size and checksum value of the downloaded data are returned. 3.2. Write into and Read Files 3.2.1. Write into and Read a UFS File AT+QFOPEN='test.txt',1 +QFOPEN: 3023 //Open the file to get the file handle. OK AT+QFWRITE=3023,10 CONNECT +QFWRITE: 10,10 OK AT+QFSEEK=3023,0,0 OK AT+QFREAD=3023,10 CONNECT 10 //Write 10 bytes of data into the file. //Write in the file data in the data mode. //The actual written bytes and the size of the file are returned. //Set the file pointer to the beginning of the file. //Read 10 bytes of data from the file. //Read data in the data mode. OK AT+QFCLOSE=3023 OK //Close the file. 3.2.2. Write into and Read an SD File AT+QFOPEN='SD:1.txt',1 +QFOPEN: 3024 //Open the file to get the file handle. OK AT+QFWRITE=3024,1024 CONNECT //Write 1024 bytes of data into the file. //Write in the file data in the data mode. EG512R&EM12xR&EM160R_Series_File_Application_Note 23 / 27 +QFWRITE: 1024,1024 OK AT+QFSEEK=3024,0,0 OK AT+QFREAD=3024,1024 CONNECT 1024 OK AT+QFCLOSE=3024 OK LTE-A Module Series //The actual written bytes and the size of the file are returned. //Set the file pointer to the beginning of the file. //Read 1024 bytes of data from the file. //Read data in the data mode. //Close the file. EG512R&EM12xR&EM160R_Series_File_Application_Note 24 / 27 LTE-A Module Series 4 Summary of Error Codes The error code indicates an error related to mobile equipment. The details about are presented in the following table. Table 3: Summary of Error Codes 400 401 402 403 405 406 407 409 410 411 413 414 416 417 418 419 420 Meaning Invalid input value Larger than the size of the file Zero-byte read Drive full File not found Invalid file name File already exists Failed to write to the file Failed to open the file Failed to read the file Reached the max. number of files allowed to be opened Read-only file Invalid file descriptor Failed to list the file Failed to delete the file Failed to get disk info No space EG512R&EM12xR&EM160R_Series_File_Application_Note 25 / 27 421 Time out 423 File too large 425 Invalid parameter 426 File already opened LTE-A Module Series EG512R&EM12xR&EM160R_Series_File_Application_Note 26 / 27 LTE-A Module Series 5 Appendix References Table 4: Terms and Abbreviations Abbreviation ACK COM DOS ME SD TA UART UFS USB XOR Description Acknowledgement Communication Port Disk Operating System Mobile Equipment Secure Digital Terminal Adapter Universal Asynchronous Receiver-Transmitter User File Storage Universal Serial Bus Exclusive OR EG512R&EM12xR&EM160R_Series_File_Application_Note 27 / 27
370.02 KB
EG06xK&Ex120K&EM060K Series FILE Application Note LTE-A Module Series Version: 1.0 Date: 2022-10-10 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_File_Application_Note 1 / 27 LTE-A Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. EG06xK&Ex120K&EM060K_Series_File_Application_Note 2 / 27 LTE-A Module Series About the Document Revision History Version 1.0 Date 2022-09-09 2022-10-10 Author Monan TIAN Monan TIAN Description Creation of the document First official release EG06xK&Ex120K&EM060K_Series_File_Application_Note 3 / 27 LTE-A Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index...................................................................................................................................................5 1 Introduction .......................................................................................................................................... 6 1.1. Applicable Modules ................................................................................................................. 6 1.2. Process of Using FILE AT Commands .................................................................................... 7 1.3. Description of Data Mode........................................................................................................ 7 2 Description of FILE AT Commands ................................................................................................... 9 2.1. AT Command Introduction....................................................................................................... 9 2.1.1. Definitions.........................................................................................................................9 2.1.2. AT Command Syntax ....................................................................................................... 9 2.2. Declaration of AT Command Examples ................................................................................ 10 2.3. AT Command Description ..................................................................................................... 10 2.3.1. AT+QFLDS Get Space Information of Storage Medium ............................................. 10 2.3.2. AT+QFLST List File Information on Storage Medium ................................................. 11 2.3.3. AT+QFDEL Delete File(s) on Storage Medium ........................................................... 13 2.3.4. AT+QFUPL Upload a File to Storage Medium ............................................................ 13 2.3.5. AT+QFDWL Download a File from Storage Medium .................................................. 15 2.3.6. AT+QFOPEN Open a File ........................................................................................... 16 2.3.7. AT+QFREAD Read a File............................................................................................ 17 2.3.8. AT+QFWRITE Write Data into a File........................................................................... 18 2.3.9. AT+QFSEEK Set a File Pointer to the Specified Position........................................... 19 2.3.10. AT+QFPOSITION Get the Offset of a File Pointer...................................................... 20 2.3.11. AT+QFCLOSE Close a File......................................................................................... 20 3 Examples ............................................................................................................................................ 22 3.1. Upload and Download a File ................................................................................................. 22 3.1.1. Upload a File .................................................................................................................. 22 3.1.1.1. Non-ACK Mode..................................................................................................... 22 3.1.1.2. ACK Mode ............................................................................................................ 22 3.1.2. Download a File ............................................................................................................. 23 3.2. Write into and Read Files ...................................................................................................... 23 3.2.1. Write into and Read a UFS File ..................................................................................... 23 3.2.2. Write into and Read an SD File ..................................................................................... 23 4 Summary of Error Codes .................................................................................................................. 25 5 Appendix References ........................................................................................................................ 27 EG06xK&Ex120K&EM060K_Series_File_Application_Note 4 / 27 LTE-A Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 6 Table 2: Type of AT Commands ................................................................................................................... 9 Table 3: Summary of Error Codes.............................................................................................................. 25 Table 4: Terms and Abbreviations .............................................................................................................. 27 EG06xK&Ex120K&EM060K_Series_File_Application_Note 5 / 27 LTE-A Module Series 1 Introduction Quectel LTE-A EG060K series, EG065K series, EG120K series, EM120K-GL, and EM060K series modules support AT commands to manipulate files on different physical storage mediums. This document is a reference guide to these commands. The modules support the following storage mediums: UFS: User File Storage directory. It is a special directory on the flash file system. SD: SD card directory. NOTE 1. The contains the storage location. When it begins with 'UFS:' or with no prefix, it means that the file is stored in UFS. When it begins with 'SD:', it means that the file is stored in SD card. 2. EM120K-GL and EM060K series modules do not support SD storage medium. 1.1. Applicable Modules Table 1: Applicable Modules Applicable Modules EG06xK EG060K Series EG065K Series Ex120K EG120K Series EM120K-GL EM060K EM060K Series EG06xK&Ex120K&EM060K_Series_File_Application_Note 6 / 27 LTE-A Module Series 1.2. Process of Using FILE AT Commands The general procedure for uploading/downloading, opening/creating, reading and writing to a file in the storage: 1. Upload a file to the storage with AT+QFUPL, and output/download it through the serial interface with AT+QFDWL. 2. Open the file with AT+QFOPEN. Once the file is opened, you can write to it or read from it any time and from any location until the file is closed with AT+QFCLOSE. When opening a file with AT+QFOPEN, you can set the file to overwrite mode, read-only mode or other mode with (For more information about , see Chapter 2.3.6). After opening the file, is assigned to it so that various file operations can be carried out. After opening the file, write the data to the file with AT+QFWRITE and read the data with AT+QFREAD from the current file pointer position. Set the file pointer position with AT+QFSEEK and query the current file pointer position with AT+QFPOSITION. Close the file with AT+QFCLOSE, after which the turns invalid. Use the following commands to manage files on the storage medium: 1. AT+QFLDS Get the space information of the storage medium. 2. AT+QFLST List the file information in the storage medium. 3. AT+QFDEL Delete the file(s) in the storage medium. 4N. OTE The file handle obtained after executing AT+QFOPEN must be closed with AT+QFCLOSE after the operation is completed, otherwise the file handle will be leaked. 1.3. Description of Data Mode The module COM port has two working modes: the AT command mode and the data mode. In the AT command mode, the data inputted via COM port will be treated as AT commands; while in the data mode, they will be treated as data. Enter Data Mode Execute AT+QFUPL, AT+QFDWL, AT+QFREAD, or AT+QFWRITE, the module returns CONNECT, and the COM port enters the data mode. Or re-enter the data mode by executing ATO. EG06xK&Ex120K&EM060K_Series_File_Application_Note 7 / 27 LTE-A Module Series Exit Data Mode Input +++ to make the COM port exit the data mode. After +++ is inputted, the execution of data-mode-entering commands will be interrupted before the module responds OK, and at this time, the COM port cannot re-enter the data mode if you execute ATO. To prevent the +++ from being misinterpreted as data, the following requirements should be followed: 1. Do not input any character for at least 1 second before inputting +++. 2. Finish inputting +++ within 1 second, during which no other character shall be inputted. 3. After inputting +++, wait until OK is returned. The response OK indicates that the COM port exits the data mode. EG06xK&Ex120K&EM060K_Series_File_Application_Note 8 / 27 LTE-A Module Series 2 Description of FILE AT Commands 2.1. AT Command Introduction 2.1.1. Definitions Carriage return character. Line feed character. Parameter name. Angle brackets do not appear on 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 2: 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. EG06xK&Ex120K&EM060K_Series_File_Application_Note 9 / 27 LTE-A Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 2.3. AT Command Description 2.3.1. AT+QFLDS Get Space Information of Storage Medium This command gets the space information of the specified storage medium. AT+QFLDS Get Space Information of Storage Medium Test Command AT+QFLDS=? Write Command AT+QFLDS= Response OK Response +QFLDS: , OK Execution Command AT+QFLDS If there is an error: +CME ERROR: Response Return the UFS information: +QFLDS: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Storage medium type. 'UFS' UFS EG06xK&Ex120K&EM060K_Series_File_Application_Note 10 / 27 LTE-A Module Series 'SD' SD card Integer type. Free space size of . Unit: byte. Integer type. Total space size of . Unit: byte. Integer type. Size of all files in UFS. Unit: byte. Integer type. Number of files in UFS. Integer type. Error code. See Chapter 4 for details. Example AT+QFLDS='UFS' +QFLDS: 578847,917503 OK AT+QFLDS='SD' +QFLDS: 251920384,253132800 OK //Query the space information of UFS. //Query the space information of SD card. 2.3.2. AT+QFLST List File Information on Storage Medium This command lists the information of a single file or all files on the specified storage medium. AT+QFLST List File Information on Storage Medium Test Command AT+QFLST=? Write Command AT+QFLST= Response OK Response +QFLST: , [+QFLST: , […]] OK Execution Command AT+QFLST If there is an error: +CME ERROR: Response Return the information of the UFS files: +QFLST: , [+QFLST: , […]] OK If there is an error: EG06xK&Ex120K&EM060K_Series_File_Application_Note 11 / 27 LTE-A Module Series Maximum Response Time Characteristics +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file(s) to be listed. Maximum length: 80 bytes. '*' All files in UFS '' The specified in UFS 'UFS:*' All files in UFS 'UFS:' The specified in UFS 'SD:*' All files in SD card 'SD:' The specified in SD card String type. Exact file name. Integer type. File size. Unit: byte. Integer type. Error code. See Chapter 4 for details. Example AT+QFLST='*' +QFLST: 'UFS:1k.txt',1024 +QFLST: 'UFS:2k.txt',2048 +QFLST: 'UFS:3k.txt',3072 OK AT+QFLST='SD:*' +QFLST: 'SD:1k.txt',1024 +QFLST: 'SD:10k.txt',10240 +QFLST: 'SD:100k.txt',102400 OK //List all files in UFS. //List all files in SD card. NOTE AT+QFLST queries the actual size of the file currently stored in flash. After the data are written in with AT+QFWRITE, if you fail to query the file size by executing AT+QFLST, please close the file with AT+QFCLOSE before another query. EG06xK&Ex120K&EM060K_Series_File_Application_Note 12 / 27 LTE-A Module Series 2.3.3. AT+QFDEL Delete File(s) on Storage Medium This command deletes a single file or all the files on the specified storage medium. AT+QFDEL Delete File(s) on Storage Medium Test Command AT+QFDEL=? Response +QFDEL: Write Command AT+QFDEL= OK Response OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file to be deleted. Maximum length: 80 bytes. '*' Delete all files in UFS (do not delete the directory) '' Delete the specified in UFS 'UFS:*' Delete all files in UFS (do not delete the directory) 'UFS:' Delete the specified in UFS 'SD:*' Delete all files in SD card (do not delete the directory) 'SD:' Delete the specified in SD card String type. Exact file name. Integer type. Error code. See Chapter 4 for details. Example AT+QFDEL='*' OK AT+QFDEL='UFS:1.txt' OK AT+QFDEL='SD:*' OK //Delete all files in UFS (do not delete the directory). //Delete the file 1.txt in UFS. //Delete all files in SD card (do not delete the directory). 2.3.4. AT+QFUPL Upload a File to Storage Medium This command uploads a file to a storage medium. If any file on the storage medium has the same name as the file to be uploaded, an error will be reported. EG06xK&Ex120K&EM060K_Series_File_Application_Note 13 / 27 LTE-A Module Series When the uploaded data reach , or if no data are inputted until is reached, the module will exit the data mode automatically. During data transmission, you can send '+++' to make the module exit the data mode. For more details, see Chapter 1.3. For the Linux example of this command, see quec_upload.zip package. For the example introduction, see the Readme file in quec_upload.zip. Please contact Quectel technical support to obtain the quec_upload.zip package. AT+QFUPL Upload a File to Storage Medium Test Command AT+QFUPL=? Response +QFUPL: ,(1-),(range of supported s),(list of supported s) Write Command AT+QFUPL=[,[, [,]]] OK Response CONNECT TA switches to the data mode (transparent transmission mode), and the binary data of the file can be inputted. When the total size of the inputted data reaches or TA receives +++, TA will return to the AT command mode and respond: +QFUPL: , OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Free space size of . See Chapter 2.3.1 for more details. String type. Name pattern of the file to be uploaded. Maximum length: 80 bytes. '' The specified to be uploaded to UFS 'UFS:' The specified to be uploaded to UFS 'SD:' The specified to be uploaded to SD card String type. Exact file name. Integer type. File size expected to be uploaded. Default: 10240. Unit: byte. The maximum length is not greater than . Integer type. Actual size of uploaded data. Unit: byte. Integer type. Waiting time for inputting data to USB/UART. Range: 1–65535. EG06xK&Ex120K&EM060K_Series_File_Application_Note 14 / 27 Default: 5. Unit: s. Integer type. Indicates whether to use ACK mode. 0 Turn off the ACK mode 1 Turn on the ACK mode Integer type. Checksum of uploaded data. Integer type. Error code. See Chapter 4 for details. LTE-A Module Series NOTE 1. It is strongly recommended to use DOS 8.3 file name format for . 2. is a 16-bit checksum based on bitwise Exclusive-OR (XOR). If the number of bytes is odd, the last byte is set as the upper 8 bits, and the lower 8 bits are set as 0. Then an XOR operator is used to calculate the checksum. Inputting +++ will make the TA end the data transmission and switch to the AT command mode. However, the previously uploaded data will be preserved in the file. 3. When executing the command, the data must be inputted after CONNECT is returned. 4. The ACK mode is a safeguard against data loss when uploading large files in case the hardware flow control does not work. The ACK mode works as follows: 1) Run AT+QFUPL=,,,1 to enable the ACK mode. 2) The module outputs CONNECT. 3) MCU sends 1 KB of data, to which the module responds with an A. 4) MCU receives the A and then sends the next 1 KB of data. 5) Repeat the step 3) and 4) until the transfer is completed. For an example of ACK mode use, see Chapter 3.1.1.2. 2.3.5. AT+QFDWL Download a File from Storage Medium This command downloads a specified file from the storage medium. For the Linux example of this command, see the Linux example of AT+QFUPL. AT+QFDWL Download a File from Storage Medium Test Command AT+QFDWL=? Response +QFDWL: Write Command AT+QFDWL= OK Response CONNECT TA switches to the data mode, and the binary data of the file can be outputted. When the content of the file is read or the TA receives +++, the TA will return to the AT command mode and respond: +QFDWL: , EG06xK&Ex120K&EM060K_Series_File_Application_Note 15 / 27 LTE-A Module Series Maximum Response Time Characteristics OK If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file to be downloaded. Maximum length: 80 bytes. '' The specified UFS to be downloaded 'UFS:' The specified UFS to be downloaded 'SD: ' The specified SD to be downloaded String type. Exact file name. Integer type. Size of the downloaded data. Integer type. Checksum of the downloaded data. Integer type. Error code. See Chapter 4 for details. NOTE 1. +++ will cause the TA to end the data transmission and switch to the AT command mode. 2. is a 16-bit checksum based on bitwise XOR. 2.3.6. AT+QFOPEN Open a File This command opens a file and gets the file handle to be used in commands such as AT+QFREAD, AT+QFWRITE, AT+QFSEEK, AT+QFPOSITION and AT+QFCLOSE. AT+QFOPEN Open a File Test Command AT+QFOPEN=? Response +QFOPEN: ,(range of supported s) Read Command AT+QFOPEN? OK Response +QFOPEN: ,, [+QFOPEN: ,, […]] OK EG06xK&Ex120K&EM060K_Series_File_Application_Note 16 / 27 LTE-A Module Series Write Command AT+QFOPEN=[,] Response +QFOPEN: OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter String type. Name pattern of the file to be opened. Maximum length: 80 bytes. '' The specified UFS to be opened 'UFS:' The specified UFS to be opened 'SD: ' The specified SD to be opened String type. Exact file name. Integer type. Handle of the file to be operated. Integer type. File opening mode. 0 If the file does not exist, it will be created. If the file exists, it will be opened directly. In both cases, the file can be read and written to. 1 If the file does not exist, it will be created. If the file exists, it will be cleared and overwritten. In both cases, the file can be read and written to. 2 If the file does not exist, an error will be responded. If the file exists, it will be opened directly and read only. Integer type. Error code. See Chapter 4 for details. 2.3.7. AT+QFREAD Read a File This command reads the data of a file specified by the file handle. The data start from the current position of the file pointer that belongs to the file handle. For the Linux example of this command, see the Linux example of AT+QFUPL. AT+QFREAD Read a File Test Command AT+QFREAD=? Response +QFREAD: , Write Command AT+QFREAD=[,] OK Response CONNECT EG06xK&Ex120K&EM060K_Series_File_Application_Note 17 / 27 LTE-A Module Series Maximum Response Time Characteristics TA switches to the data mode. When the total size of the data reaches or TA receives +++, TA will return to the AT command mode, display the result, and then respond: OK If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Expected length of file to be read. Default length: 10 KB. If file length is less than 10 KB, the actual length of the file will be read. Unit: byte. Integer type. Actual read length. Unit: byte. Integer type. Error code. See Chapter 4 for details. 2.3.8. AT+QFWRITE Write Data into a File This command writes data into a file. The data start from the current position of the file pointer that belongs to the file handle. For the Linux example of this command, see the Linux example of AT+QFUPL. AT+QFWRITE Write Data into a File Test Command AT+QFWRITE=? Response +QFWRITE: ,, Write Command AT+QFWRITE=[, [,]] OK Response CONNECT TA switches to the data mode. When the total size of the written data reaches , TA receives +++ or the time reaches , TA will return to the AT command mode and respond: +QFWRITE: , OK If there is an error: EG06xK&Ex120K&EM060K_Series_File_Application_Note 18 / 27 LTE-A Module Series Maximum Response Time Characteristics +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Length of the file which data are written into. Default length: 10 KB. Maximum value of this parameter is determined by of AT+QFUPL. Unit: byte. Integer type. Waiting time for inputting data to USB/UART. Default: 5. Unit: s. Integer type. Actual written length. Unit: byte. Integer type. Total length of the file. Unit: byte. Integer type. Error code. See Chapter 4 for details. 2.3.9. AT+QFSEEK Set a File Pointer to the Specified Position This command sets a file pointer to the specified position. This will decide the starting position of the commands AT+QFREAD, AT+QFWRITE and AT+QFPOSITION. AT+QFSEEK Set a File Pointer to the Specified Position Test Command AT+QFSEEK=? Response +QFSEEK: ,, Write Command AT+QFSEEK=,[,< position>] OK Response OK If there is an error: +CME ERROR: Maximum Response Time 300 ms Characteristics The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Number of bytes of file pointer movement. Integer type. Pointer movement mode. 0 Move forward from the beginning of the file EG06xK&Ex120K&EM060K_Series_File_Application_Note 19 / 27 LTE-A Module Series 1 Move forward from the current position of the pointer 2 Move backward from the end of the file Integer type. Error code. See Chapter 4 for details. NOTE If the set final position of the pointer exceeds the file size, executing this command will return ERROR. 2.3.10. AT+QFPOSITION Get the Offset of a File Pointer This command gets the offset of a file pointer from the beginning of the file. AT+QFPOSITION Get the Offset of a File Pointer Test Command AT+QFPOSITION=? Response +QFPOSITION: Write Command AT+QFPOSITION= OK Response +QFPOSITION: OK Maximum Response Time Characteristics If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Offset from the beginning of file. Integer type. Error code. See Chapter 4 for details. 2.3.11. AT+QFCLOSE Close a File This command closes a file and ends all file operations. After that, the file handle is released and should not be used again, unless the file is re-opened with AT+QFOPEN. EG06xK&Ex120K&EM060K_Series_File_Application_Note 20 / 27 LTE-A Module Series AT+QFCLOSE Close a File Test Command AT+QFCLOSE=? Write Command AT+QFCLOSE= Maximum Response Time Characteristics Response +QFCLOSE: OK Response OK If there is an error: +CME ERROR: 300 ms The command takes effect immediately; The configurations will not be saved. Parameter Integer type. Handle of the file to be operated. Integer type. Error code. See Chapter 4 for details. EG06xK&Ex120K&EM060K_Series_File_Application_Note 21 / 27 LTE-A Module Series 3 Examples 3.1. Upload and Download a File 3.1.1. Upload a File 3.1.1.1. Non-ACK Mode AT+QFUPL='test1.txt',10 CONNECT +QFUPL: 10,3938 OK //Upload the text file test1.txt to UFS. //Input the binary data of the file. 3.1.1.2. ACK Mode The ACK mode makes the data transmission more reliable. When transmitting a large file without hardware flow control, the ACK mode is recommended to prevent data loss. For more details about ACK mode, see AT+QFUPL. AT+QFUPL='test.txt',3000,5,1 CONNECT A A +QFUPL: 3000,B34A //Upload the text file test.txt to UFS. //Input 1024 bytes of the binary data of the file. //After MCU sends 1024 bytes of data, the module will respond an A. Then the next 1024 bytes of data can be inputted. //Input 1024 bytes of the binary data of the file. //Input the rest binary data of the file. OK EG06xK&Ex120K&EM060K_Series_File_Application_Note 22 / 27 3.1.2. Download a File AT+QFDWL='test.txt' CONNECT +QFDWL: 10,613e OK LTE-A Module Series //Download the text file test.txt from UFS. //Binary data of the file is outputted. //Size and checksum value of the downloaded data are returned. 3.2. Write into and Read Files 3.2.1. Write into and Read a UFS File AT+QFOPEN='test.txt',1 +QFOPEN: 3023 //Open the file to get the file handle. OK AT+QFWRITE=3023,10 CONNECT +QFWRITE: 10,10 OK AT+QFSEEK=3023,0,0 OK AT+QFREAD=3023,10 CONNECT 10 //Write 10 bytes of data into the file. //Write in the file data in the data mode. //The actual written bytes and the size of the file are returned. //Set the file pointer to the beginning of the file. //Read 10 bytes of data from the file. //Read data in the data mode. OK AT+QFCLOSE=3023 OK //Close the file. 3.2.2. Write into and Read an SD File AT+QFOPEN='SD:1.txt',1 +QFOPEN: 3024 //Open the file to get the file handle. OK AT+QFWRITE=3024,1024 CONNECT //Write 1024 bytes of data into the file. //Write in the file data in the data mode. EG06xK&Ex120K&EM060K_Series_File_Application_Note 23 / 27 +QFWRITE: 1024,1024 OK AT+QFSEEK=3024,0,0 OK AT+QFREAD=3024,1024 CONNECT 1024 OK AT+QFCLOSE=3024 OK LTE-A Module Series //The actual written bytes and the size of the file are returned. //Set the file pointer to the beginning of the file. //Read 1024 bytes of data from the file. //Read data in the data mode. //Close the file. EG06xK&Ex120K&EM060K_Series_File_Application_Note 24 / 27 LTE-A Module Series 4 Summary of Error Codes The error code indicates an error related to mobile equipment. The details about are presented in the following table. Table 3: Summary of Error Codes 400 401 402 403 405 406 407 409 410 411 413 414 416 417 418 419 420 Meaning Invalid input value Larger than the size of the file Zero-byte read Drive full File not found Invalid file name File already exists Failed to write to the file Failed to open the file Failed to read the file Reached the max. number of files allowed to be opened Read-only file Invalid file descriptor Failed to list the file Failed to delete the file Failed to get disk info No space EG06xK&Ex120K&EM060K_Series_File_Application_Note 25 / 27 421 Time out 423 File too large 425 Invalid parameter 426 File already opened LTE-A Module Series EG06xK&Ex120K&EM060K_Series_File_Application_Note 26 / 27 LTE-A Module Series 5 Appendix References Table 4: Terms and Abbreviations Abbreviation ACK COM DOS ME SD TA UART UFS USB XOR Description Acknowledgement Communication Port Disk Operating System Mobile Equipment Secure Digital Terminal Adapter Universal Asynchronous Receiver-Transmitter User File Storage Universal Serial Bus Exclusive OR EG06xK&Ex120K&EM060K_Series_File_Application_Note 27 / 27
370.23 KB
BG95&BG77&BG600L Series Voice Application Note LPWA Module Series Version: 1.0 Date: 2022-09-30 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG95&BG77&BG600L_Series_Voice_Application_Note 1 / 43 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG95&BG77&BG600L_Series_Voice_Application_Note 2 / 43 LPWA Module Series About the Document Revision History Version 1.0 Date 2022-06-01 2022-09-30 Author Nora HE Nora HE Description Creation of the document First official release BG95&BG77&BG600L_Series_Voice_Application_Note 3 / 43 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 6 Figure Index ................................................................................................................................................ 7 1 Introduction ......................................................................................................................................... 8 1.1. Applicable Modules and Supported Voice Feature ................................................................... 8 2 General Overview of IMS and VoLTE................................................................................................ 9 2.1. Introduction to IMS Features...................................................................................................... 9 2.1.1. Supported Features ........................................................................................................ 9 2.1.2. Features Not Supported.................................................................................................. 9 2.2. Introduction to VoLTE Call Flow............................................................................................... 10 2.2.1. Prerequisite for VoLTE Call ........................................................................................... 10 2.2.2. Process of VoLTE Call .................................................................................................. 10 3 AT Command Introduction .............................................................................................................. 12 3.1. AT Command Introduction ....................................................................................................... 12 3.1.1. Definitions...................................................................................................................... 12 3.1.2. AT Command Syntax .................................................................................................... 12 3.1.3. Declaration of AT Command Examples ........................................................................ 13 4 AT Command Description................................................................................................................ 14 4.1. AT+QCFG='ims' Query IMS Registration State ................................................................... 14 4.2. ATD Originate a Call.............................................................................................................. 15 4.3. ATA Answer an Incoming Call ............................................................................................... 17 4.4. ATH Disconnect Existing Connection.................................................................................... 18 4.5. AT+CVHU Voice Call Hang Up Control................................................................................. 19 4.6. AT+CLCC List Current Calls of ME ....................................................................................... 20 4.7. AT+CHUP Hang up a Call ..................................................................................................... 21 4.8. AT+QIIC Read/ Write Codec Through IIC ............................................................................. 22 4.9. AT+QDAI Configure Digital Audio Interface .......................................................................... 23 4.10. AT+CLVL Configure Loudspeaker Volume............................................................................ 24 4.11. AT+CMUT Muting Control ..................................................................................................... 25 4.12. AT+QPCMCFG Configure PCM Interface............................................................................. 26 4.13. AT+QLDTMF Play Local DTMF ............................................................................................ 28 4.14. AT+VTS DTMF and Tone Generation ................................................................................... 29 4.15. AT+QTONEDET Enable/Disable DTMF Detection ............................................................... 30 4.16. AT+QAUDLOOP Enable/Disable Audio Loop Test ............................................................... 31 4.17. AT+QINDCFG Configure URC Indication ............................................................................. 32 5 Description of URCs ......................................................................................................................... 35 5.1. RING URC ............................................................................................................................... 35 5.2. Alert URC ................................................................................................................................. 35 BG95&BG77&BG600L_Series_Voice_Application_Note 4 / 43 LPWA Module Series 6 Issue Analysis ................................................................................................................................... 36 6.1. Direction-Related Problem Analysis ........................................................................................ 37 6.2. Protocol-Related Problem Analysis ......................................................................................... 37 6.2.1. VoLTE Issue Analysis .................................................................................................... 38 6.2.2. CS-Voice over GSM Issue Analysis .............................................................................. 38 7 Appendix A References.................................................................................................................... 40 8 Appendix B Summary of CME ERROR Codes............................................................................... 42 BG95&BG77&BG600L_Series_Voice_Application_Note 5 / 43 LPWA Module Series Table Index Table 1: Applicable Modules and Supported Voice Feature ....................................................................... 8 Table 2: Types of AT Commands .............................................................................................................. 12 Table 3: Related Document........................................................................................................................ 40 Table 4: Terms and Abbreviations .............................................................................................................. 40 Table 5: Different Coding Schemes of +CME ERROR: ................................................................... 42 BG95&BG77&BG600L_Series_Voice_Application_Note 6 / 43 LPWA Module Series Figure Index Figure 1: VoLTE Call Flow...........................................................................................................................11 Figure 2: Data Path of AFE Loopback ....................................................................................................... 31 Figure 3: Voice Flow................................................................................................................................... 36 Figure 4: Poor Network Condition in VoLTE .............................................................................................. 38 Figure 5: Poor Channel Condition in CS-Voice (1) .................................................................................... 39 Figure 6: Poor Channel Condition in CS-Voice (2) .................................................................................... 39 BG95&BG77&BG600L_Series_Voice_Application_Note 7 / 43 LPWA Module Series 1 Introduction This document introduces the application of VoLTE and describes the related AT commands of VoLTE, CS voice over GSM (2G) and audio services on Quectel BG95 series, BG77 and BG600L-M3 modules. 1.1. Applicable Modules and Supported Voice Feature Table 1: Applicable Modules and Supported Voice Feature Module Series Module BG95-M1 Supported Network Cat M1 only Supported Voice Feature VoLTE BG95-M2 Cat M1/Cat NB2 VoLTE BG95 BG95-M3 Cat M1/Cat NB2/EGPRS VoLTE/CS voice BG95-M5 Cat M1/Cat NB2/EGPRS, Power Class 3 VoLTE/CS voice BG95-M6 Cat M1/Cat NB2, Power Class 3 VoLTE BG77 BG77 Cat M1/Cat NB2 VoLTE BG600L BG600L-M3 Cat M1/Cat NB2/EGPRS VoLTE/CS voice BG95&BG77&BG600L_Series_Voice_Application_Note 8 / 43 LPWA Module Series 2 General Overview of IMS and VoLTE 2.1. Introduction to IMS Features The IP Multimedia Subsystem (IMS) is an architectural framework for delivering IP multimedia services. 2.1.1. Supported Features The following features are supported in IMS: ⚫ LTE RAT ⚫ Power-saving mode ⚫ IMS registration with or without IPsec ⚫ Single VoLTE call ⚫ SIP forking (up to seven dialogs) ⚫ Audio codecs: AMR-NB, DTMF ⚫ QoS and preconditions ⚫ SMS over IMS in 3GPP format only 2.1.2. Features Not Supported The following features are currently not supported in IMS: ⚫ Emergency call ⚫ Multi-call, such as conference call, call transfer and call pulling ⚫ SRVCC and CSFB ⚫ Audio codecs: EVS, AMR-WB, and G.711 ⚫ VoLTE for internet-connected endpoint (VICE) ⚫ DAN ⚫ Video call, RTT, and TTY ⚫ MWI ⚫ IWLAN ⚫ RCS or Presence BG95&BG77&BG600L_Series_Voice_Application_Note 9 / 43 LPWA Module Series 2.2. Introduction to VoLTE Call Flow VoLTE (Voice over Long-Term Evolution) is based on the IP Multimedia Subsystem (IMS) network, and uses special configuration files for the control and media planes. This enables voice services (at the control and media levels) to be transmitted as data streams over LTE data bearer networks. VoLTE initialization procedures are required before a VoLTE session is established. 2.2.1. Prerequisite for VoLTE Call 1. Attach to LTE network and select domain (all call flows assume voice over IMS). 2. Establish IMS PDN connection and SIP QoS flow. QCI = 5 is used for SIP signaling on IMS default bearer. 3. Complete IMS registration and subscription with IMS CN. IMS feature tags for available services are MMTel IMS Communication Services Identifier (ICSI). 2.2.2. Process of VoLTE Call The steps to establish a VoLTE session with a remote party are as follows. 1. Attach to LTE network and select domain. 2. Establish IMS PDN connection and SIP QoS flow. 3. Complete IMS registration and subscription. 4. Establish IMS session. ⚫ Transmit information by SIP signaling. ⚫ Negotiate codec with SDP. 5. Establish VoLTE QoS call flow. ⚫ Implement network-initiated QoS procedure. 6. Propose ROHC negotiation. 7. Transmit full-duplex VoLTE data between UE and E-UTRA(N). ⚫ This data is routed from the E-UTRA(N) by the packet data core network to the remote party involved in the call. ⚫ Each voice frame is generated by the vocoder and carried as the payload in RTP. ⚫ RTP packets are encapsulated in UDP packets and carried over IP. 8. Terminate IMS session. ⚫ Transmit information by SIP signaling. ⚫ Release and clean up existing VoLTE call(s). 9. Release VoLTE QoS flow. ⚫ Release network-dependent QoS procedure. 10. Terminate VoLTE feature. BG95&BG77&BG600L_Series_Voice_Application_Note 10 / 43 UE E-UTRA(N)/ PDN LTE attachment + domain selection IMS PDN connection + SIP Qos flow IMS registration and subscription {Call setup IMS session establishment VoLTE Qos flow establishment ROHC negotiation VoLTE data IMS session termination VoLTE QoS flow release IMS de-registration LPWA Module Series IM/ CN VoLTE feature initialization procedures VoLTE session procedures } May be simultaneous VoLTE feature termination procedure Figure 1: VoLTE Call Flow BG95&BG77&BG600L_Series_Voice_Application_Note 11 / 43 LPWA Module Series 3 AT Command Introduction 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. BG95&BG77&BG600L_Series_Voice_Application_Note 12 / 43 LPWA Module Series 3.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. BG95&BG77&BG600L_Series_Voice_Application_Note 13 / 43 LPWA Module Series 4 AT Command Description This chapter introduces the voice and audio related AT commands supported by the modules, including the functions, usages and the scope of AT commands. For some AT commands or URCs mentioned but not described in detail in this chapter, unless otherwise specified, see document [1] for more information and usage. 4.1. AT+QCFG='ims' Query IMS Registration State This command queries the module's IMS registration state. VoLTE state indicates IMS registration state, that is, VoLTE is ready indicates IMS feature is enabled. AT+QCFG='ims' Query IMS Registration State Write Command AT+QCFG='ims' Response +QCFG: 'ims', OK Or ERROR Maximum Response Time Characteristics If there is an error related to ME functionality: +CME ERROR: 300 ms - Parameter Integer type. VoLTE state. 0 VoLTE is not ready 1 VoLTE is ready Error code. See Chapter 8 for details. Example AT+QCFG='ims' +QCFG: 'ims',1 BG95&BG77&BG600L_Series_Voice_Application_Note 14 / 43 OK NOTE This command is valid only on the firmware version supporting VoLTE. LPWA Module Series 4.2. ATD Originate a Call This command sets up outgoing voice or data call. ATD Originate a Call Execution Command ATD[][;] Response If no dial tone and ATX2 or ATX4 is set: NO DIAL TONE If busy and ATX3 or ATX4 is set: BUSY If a call connection cannot be established: NO CARRIER If a call connection is established successfully and a non-voice call is to be set up: CONNECT TA switches to data mode. is output only when is greater than 0 in ATX parameter setting. When TA returns to command mode after call release: OK Maximum Response Time Characteristics If a call connection is established successfully and a voice call is set up: OK Or ERROR 5 s, determined by the network (AT+COLP=0). - BG95&BG77&BG600L_Series_Voice_Application_Note 15 / 43 LPWA Module Series Reference V.25ter Parameter String of dialing strings and optional V.25ter modifiers. Dialing strings: 0-9, *, #, +, A, B, C Following V.25ter, optional modifiers ,(comma), T, P, !, W, @ are ignored. String of GSM modifiers: I Activates CLIR (Disable presentation of calling number to called party). i Deactivates CLIR (Enable presentation of calling number to called party). G Activates closed user group invocation for this call only. g Deactivates closed user group invocation for this call only. It is required when setting up a voice call. After the call, TA will return to command state. Example ATD10086; OK //Dial a number. NOTE 1. This command may be aborted generally by receiving an ATH command or a character during execution. It cannot be aborted during some connection establishments such as handshaking. 2. Parameters I and i can be omitted only when there is no * or # code in the dial string. 3. See ATX for details about setting result codes and call monitoring parameters. 4. For voice calls, if dialing with ATD, TA returns OK immediately either after the dialing is completed or the call is established. Otherwise, TA returns BUSY, NO DIAL TONE, or NO CARRIER. 5. Use ATD during an active voice call: ⚫ When a user originates a second voice call while there is already an active voice call, the first call will be automatically put on hold. ⚫ The current states of all calls can be easily checked at any time by AT+CLCC. See Chapter 4.6 for details. 6. Currently, supplementary services, such as COLP, CLIR or closed user group, are not supported. BG95&BG77&BG600L_Series_Voice_Application_Note 16 / 43 LPWA Module Series 4.3. ATA Answer a Call This command connects the module to an incoming voice or data call indicated by a RING URC. ATA Answer a Call Execution Command ATA Response TA sends off-hook to the remote station. In case of data call, if successfully connected: CONNECT And TA switches to data mode. Note: is output only when is greater than 0 in ATX parameter setting. When TA returns to command mode after call release: OK In case of voice call, if successfully connected: OK If no connection: NO CARRIER Or ERROR Maximum Response Time Characteristics Reference V.25ter If there is any error related to ME functionality: +CME ERROR: 90 s, determined by the network. - Parameter Error code. See Chapter 8 for details. Example RING OK ATA OK //Ring tone. //Answer the call. BG95&BG77&BG600L_Series_Voice_Application_Note 17 / 43 LPWA Module Series NOTE 1. Any additional commands on the same command line are ignored. 2. This command may be aborted generally by receiving a character during execution. It cannot be aborted during some connection establishments such as handshaking. 3. See also ATX. 4.4. ATH Disconnect Existing Connection This command disconnects and terminates existing data call or voice call. AT+CHUP is also used to disconnect voice call. See Chapter 4.7 for details. ATH Disconnect Existing Connection Execution Command ATH[] Response OK Or ERROR Maximum Response Time Characteristics Reference V.25ter If there is any error related to ME functionality: +CME ERROR: 90 s, determined by the network. - Parameter Integer type. 0 Disconnect and terminate existing call from command line. Error code. See Chapter 8 for details. Example RING OK ATH OK //Ring tone. //When AT+CVHU=0, hang up the call. BG95&BG77&BG600L_Series_Voice_Application_Note 18 / 43 LPWA Module Series 4.5. AT+CVHU Voice Call Hang Up Control This command controls whether ATH can be used to disconnect the voice call. AT+CVHU Voice Call Hang Up Control Test Command AT+CVHU=? Response +CVHU: (list of supported s) Read Command AT+CVHU? OK Response +CVHU: Write Command AT+CVHU= OK Response OK Or ERROR Maximum Response Time Characteristics Reference 3GPP TS 27.007 If there is an error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. The configuration is not saved. Parameter Integer type. 0 ATH can be used to disconnect the voice call. 1 ATH is ignored with the response OK returned only. Error code. See Chapter 8 for details. BG95&BG77&BG600L_Series_Voice_Application_Note 19 / 43 LPWA Module Series 4.6. AT+CLCC List Current Calls of ME The Execution Command returns the list of all voice calls of ME. If the command is executed successfully, but no call exists, then only OK is sent to TE. AT+CLCC List Current Calls of ME Test Command AT+CLCC=? Execution Command AT+CLCC Response OK Response TA returns the list of all current calls of ME. If the command is executed successfully, but no calls exists, then only OK is sent to TE. [+CLCC: ,,,,[,,[,< alpha>]]] [+CLCC: ,,,,[,,[,< alpha>]]] [...] OK Or ERROR Maximum Response Time Characteristics If there is an error related to ME functionality: +CME ERROR: 300 ms - Parameter Integer type. Call identification number (starting with 1). See 3GPP TS 22.030 subclause 6.5.5.1 for details. Integer type. 0 Mobile originated (MO) call 1 Mobile terminated (MT) call Integer type. Call state. 0 Active 1 Held 2 Dialing (MO call) 3 Alerting (MO call) 4 Incoming (MT call) 5 Waiting (MT call) Integer type. Bearer/teleservice. 0 Voice BG95&BG77&BG600L_Series_Voice_Application_Note 20 / 43 LPWA Module Series 1 Data 2 Fax Integer type. 0 Call is not one of the multiparty (conference) call parties 1 Call is one of the multiparty (conference) call parties String type. Phone number in format specified by . Integer type. Address type in octet format (See 3GPP TS 24.008 subclause 10.5.4.7 for details). Usually, it has three values: 129 Unknown type 145 International type (contains character '+') 161 National type Alphanumeric representation of corresponding to the entry found in phonebook. Error code. See Chapter 8 for details. Example ATD10086; //Dial a number. OK AT+CLCC +CLCC: 2,0,0,0,0,'10086',129 //Dial a number, and the call has been answered. OK 4.7. AT+CHUP Hang up a Call This command cancels any voice call in the state of Active, Waiting or Held. To cancel data call, use ATH. See Chapter 4.4 for details. AT+CHUP Hang up a Call Test Command AT+CHUP=? Execution Command AT+CHUP Response OK Response OK Or ERROR Maximum Response Time Characteristics If there is an error related to ME functionality: +CME ERROR: 90 s, determined by the network. - BG95&BG77&BG600L_Series_Voice_Application_Note 21 / 43 Reference 3GPP 27.007 Parameter Error code. See Chapter 8 for details. Example RING AT+CHUP OK //Ring tone. //Hang up the call. LPWA Module Series 4.8. AT+QIIC Read/ Write Codec Through IIC This command reads and writes the codec through the IIC interface. AT+QIIC Read/ Write Codec Through IIC Test Command AT+QIIC=? Response +QIIC: (list of supported s),(range of supported s),(range of supported s),(list of supported s),(range of supported s) Write Command AT+QIIC=,,,[,] OK Response If =0, all configuration parameters are specified: OK If =1, is omitted: +QIIC: Maximum Response Time Characteristics OK Or ERROR 300 ms The command takes effect immediately. The configurations are not saved. BG95&BG77&BG600L_Series_Voice_Application_Note 22 / 43 LPWA Module Series Parameter Integer type. 0 Write codec through IIC 1 Read codec through IIC Hexadecimal integer type with prefix '0x'. 7-bit slave device address (address of ALC5616: 0x1B; address of NAU8814, NAU88C10: 0x1A, TLV320AIC3104: 0x18 and MAX9860: 0x10). Range: 0–0xFF. Hexadecimal integer type with prefix '0x'. Register address. Range: 0–0xFF. Integer type. Length of the read or write byte(s). Value: 1, 2. Hexadecimal integer type with prefix '0x'. Data value. Range: 0–0xFFFF. Example AT+QIIC=1,0x1B,0x00,2 +QIIC: 0x0021 //Read register value; slave device address: 0x1B; register address: 0x00; read two bytes. OK AT+QIIC=0,0x1B,0x00,2,0x0000 OK //Write register value; slave device address: 0x1B; register address: 0x00; write two bytes; data value: 0x0000. NOTE is 7-bit slave device address (read or write bit not included), which can be found in the device datasheet. 4.9. AT+QDAI Configure Digital Audio Interface This command configures the digital audio interface. AT+QDAI Configure Digital Audio Interface Test Command AT+QDAI=? Response +QDAI: (list of supported s) Read Command AT+QDAI? OK Response +QDAI: OK BG95&BG77&BG600L_Series_Voice_Application_Note 23 / 43 LPWA Module Series Write Command AT+QDAI= Maximum Response Time Characteristics Response OK Or ERROR 300 ms The command takes effect immediately. The configuration is saved automatically. Parameter Integer type. 0 Analog input and output (for audio codec NAU88C10) 1 Analog input and output (for audio codec NAU8814) 2 Analog input and output (for audio codec ALC5616) 3 Analog input and output (for audio codec TLV320AIC3104) 4 Analog input and output (for audio codec MAX9860) 99 Close all external codecs. Example AT+QDAI=? +QDAI: (0-4,99) OK AT+QDAI? +QDAI: 1 OK AT+QDAI=2 OK //Query the current interface configuration. //Set the analog output to ALC5616. 4.10. AT+CLVL Configure Loudspeaker Volume This command configures the volume of the internal loudspeaker of the MT. AT+CLVL Configure Loudspeaker Volume Test Command AT+CLVL=? Response +CLVL: (range of supported s) Read Command OK Response BG95&BG77&BG600L_Series_Voice_Application_Note 24 / 43 LPWA Module Series AT+CLVL? Write Command AT+CLVL= Maximum Response Time Characteristics +CLVL: OK Response OK Or ERROR 300 ms The command takes effect immediately. The configurations are saved automatically. Parameter Integer type. Volume level with manufacturer specific range (Smallest value represents the lowest sound level). Range: 0–5. Default value: 3. Example AT+CLVL=? +CLVL: (0-5) OK AT+CLVL? +CLVL: 3 OK AT+CLVL=2 OK //Query the current volume level. //Set the volume level to 2. 4.11. AT+CMUT Muting Control This command enables or disables muting in the Tx/Rx direction during a voice call. AT+CMUT Muting Control Test Command AT+CMUT=? Response +CMUT: (list of supported s),(list of supported s) Write Command OK Response BG95&BG77&BG600L_Series_Voice_Application_Note 25 / 43 LPWA Module Series AT+CMUT=, Maximum Response Time Characteristics OK Or ERROR 300 ms The command takes effect immediately. The configurations are not saved and must be set during the call. Parameter Integer type. 0 Tx direction 1 Rx direction Integer type 0 Mute off 1 Mute on Example AT+CMUT=? +CMUT: (0,1),(0,1) OK AT+CMUT=1,1 OK //Mute on in Rx direction. 4.12. AT+QPCMCFG Configure PCM Interface This command configures the PCM interface. AT+QPCMCFG Configure PCM Interface Test Command AT+QPCMCFG=? Response +QPCMCFG: (list of supported s),(range of supported s),(range of supported s),(list of supported s) Read Command AT+QPCMCFG? OK Response +QPCMCFG: ,,, BG95&BG77&BG600L_Series_Voice_Application_Note 26 / 43 LPWA Module Series OK Write Command AT+QPCMCFG=,,, Response OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect after re-running voice call. The configurations are saved automatically. Parameter Integer type. 0 Short frame sync 1 Long frame sync Integer type. Bits width per frame. 0 8 bits (not supported currently) 1 16 bits (not supported currently) 2 32 bits 3 64 bits 4 128 bits 5 256 bits Integer type. Quant type in PCM format. 0 A-law no padding 1 Mu-law no padding 2 linear no padding (supported only) 3 A-law padding 4 Mu-law padding 5 linear padding Integer type. 1 16-bit PCM (supported only) 2 24-bit PCM 4 32-bit PCM Example AT+QPCMCFG=? +QLDTMF: (0,1),(0-5),(0-5),(1,2,4) OK AT+QPCMCFG=1,5,2,1 OK //Configure the PCM interface. BG95&BG77&BG600L_Series_Voice_Application_Note 27 / 43 LPWA Module Series NOTE Default: 2.048 MHz BCLK, 8 KHz (supported only) sampling rate, audio PCM only in master mode. 4.13. AT+QLDTMF Play Local DTMF This command plays a local DTMF tone. AT+QLDTMF Play Local DTMF Test Command AT+QLDTMF=? Response +QLDTMF: (list of supported s),(range of supported s),(range of supported s) Write Command AT+QLDTMF=, , OK Response OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. The configurations are not saved. Parameter String type. DTMF character. Range: 0–9, A–D, *, #. Integer type. DTMF tone play time duration. Range: 0–65535. Integer type. DTMF tone play volume gain. Range: 0–65535. Example AT+QLDTMF=? +QLDTMF: (0-9,A-D,*,#),(0-65535),(0-65535) OK AT+QLDTMF=2,200,200 OK //Play '2' DTMF tone whose volume gain is 200 for 200 ms. BG95&BG77&BG600L_Series_Voice_Application_Note 28 / 43 LPWA Module Series 4.14. AT+VTS DTMF and Tone Generation This command sends ASCII characters which cause MSC to transmit DTMF tones to a remote subscriber. This command can only be executed in a voice call. AT+VTS DTMF and Tone Generation Test Command AT+VTS=? Response +VTS: (list of supported s) Execution Command AT+VTS= OK Response OK Or ERROR Maximum Response Time Characteristics Reference 3GPP 27.007 If there is an error related to ME functionality: +CME ERROR: 300 ms - Parameter String type. DTMF character. Range: 0–9, A–D. *, #. Error code. See Chapter 8 for details. Example ATD12345678900; OK //Call connects. AT+VTS=1 OK //Dial. //The remote caller can hear the DTMF tone. NOTE This command cannot send multiple tones at one time. BG95&BG77&BG600L_Series_Voice_Application_Note 29 / 43 LPWA Module Series 4.15. AT+QTONEDET Enable/Disable DTMF Detection This command enables or disables DTMF detection during CS voice or VoLTE call. If this function is enabled, DTMF tones sent by the other side are detected and reported on the assigned serial port. AT+QTONEDET Enable/Disable DTMF Detection Test Command AT+QTONEDET=? Response +QTONEDET: (list of supported s) Read Command AT+QTONEDET? OK Response +QTONEDET: Write Command AT+QTONEDET= Maximum Response Time Characteristics OK Response OK Or ERROR 300 ms The command takes effect immediately. The configuration is not saved. Parameter Integer type. Enable or disable DTMF detection. 0 Disable 1 Enable Example AT+QTONEDET=? +QTONEDET: (0,1) OK AT+QTONEDET=1 OK //Enable DTMF detection. BG95&BG77&BG600L_Series_Voice_Application_Note 30 / 43 NOTE DTMF characters - ASCII DTMF 0 1 2 3 4 5 6 7 ASCII 48 49 50 51 52 53 54 55 DTMF 8 9 A B C D * # LPWA Module Series ASCII 56 57 65 66 67 68 42 35 4.16. AT+QAUDLOOP Enable/Disable Audio Loop Test This command enables or disables the audio loop test. AFE loopback is supported to verify the audio hardware connection, as shown in the following figure. TX AFE RX Codec Microphone Speaker Figure 2: Data Path of AFE Loopback AT+QAUDLOOP Enable/Disable Audio Loop Test Test Command AT+QAUDLOOP=? Response +QAUDLOOP: (list of supporteds) OK BG95&BG77&BG600L_Series_Voice_Application_Note 31 / 43 LPWA Module Series Write Command AT+QAUDLOOP= Maximum Response Time Characteristics Response OK Or ERROR 300 ms The command takes effect immediately. The configuration is not saved. Parameter Integer type. Enable or disable audio loop test. 0 Disable audio loop test 1 Enable audio loop test Example AT+QAUDLOOP=1 //Enable audio loop test, talk into the microphone, and the earphones can hear you. OK 4.17. AT+QINDCFG Configure URC Indication This command configures the URC indication. AT+QINDCFG Configure URC Indication Test command AT+QINDCFG=? Response +QINDCFG: 'all',(list of supported s),(list of supported s) +QINDCFG: 'csq',(list of supported s),(list of supported s) +QINDCFG: 'smsfull',(list of supported s),(list of supported s) +QINDCFG: 'ring',(list of supported s),(list of supported s) +QINDCFG: 'smsincoming',(list of supported s),(list of supported s) +QINDCFG: 'ccinfo',(list of supported s),(list of supported s) Write command OK Response BG95&BG77&BG600L_Series_Voice_Application_Note 32 / 43 LPWA Module Series AT+QINDCFG=[,[,]] If the optional parameters are omitted, query the current configuration: +QINDCFG: , OK If the optional parameters are specified, configure the URC indication: OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. determines whether the configuration is saved. Parameter String type. URC type. 'all' Main switch of all URCs. default value is 1 (ON). 'csq' Indication of signal strength and signal channel bit error rate change. default value is 0 (OFF). If it is 1, +QIND: 'csq',, is reported. 'smsfull' Indication of full SMS storage. default value is 0. If it is 0, +QIND: 'smsfull', is reported. 'ring' Indication of 'RING'. default value is 1. 'smsincoming' Indication of Incoming message. default value is 1. Related URCs include +CMTI, +CMT, +CDS. 'ccinfo' Indication of voice call state change. default value is 0. If it is 1, the URC indication is enabled and +QIND: 'ccinfo',,,,,, ,[,] is reported (see Chapter 4.6 for details about the parameters). Integer type. URC indication is ON or OFF. 0 OFF 1 ON Integer type. Whether to save the configuration into NVRAM. 0 Not save 1 Save BG95&BG77&BG600L_Series_Voice_Application_Note 33 / 43 Example AT+QINDCFG=? +QINDCFG: 'all',(0,1),(0,1) +QINDCFG: 'csq',(0,1),(0,1) +QINDCFG: 'smsfull',(0,1),(0,1) +QINDCFG: 'ring',(0,1),(0,1) +QINDCFG: 'smsincoming',(0,1),(0,1) +QINDCFG: 'ccinfo',(0,1),(0,1) OK AT+QINDCFG='ring',0 OK AT+QINDCFG='ccinfo',1 OK //Disable RING URC report. //Enable ccinfo URC report. LPWA Module Series BG95&BG77&BG600L_Series_Voice_Application_Note 34 / 43 LPWA Module Series 5 Description of URCs 5.1. RING URC The RING URC indicates an incoming call signal from network. RING URC RING An incoming call. 5.2. Alert URC When you make a call by executing ATD, there will be a RING URC in the remote terminal. In the local terminal, we can get an Alert URC returned instead of RBT (RING BACK TONE). Alert URC +ALERTING: ,, Peer side is ringing. Parameter Integer type. Call ID. Call identification number as described in 3GPP TS 22.030. String type. Phone number. Integer type. Type of phone number. 129 Unknown type 145 International type (contains character '+') 161 National type Example ATD505010000000045; //Dial a number. OK //Alert URC +ALERTING: 3,505010000000045,129 //Peer side is ringing. ATH OK BG95&BG77&BG600L_Series_Voice_Application_Note 35 / 43 LPWA Module Series 6 Issue Analysis If an outgoing call fails, check whether the wrong number is dialed first, and then check whether IMS is registered successfully. If the two mentioned preconditions are correct, further analyze the phonetic problems. Before analyzing, make certain the direction that whether it is an uplink problem or a downlink problem. After identifying the direction, pinpoint the type of the problem, such as intermittence, noise, silence, howling, etc. TX VOC Uplink Path ADC Microphone Downlink Path DAC Codec (Control Volume, Audio Stream Path) Module ADSP (Control Volume, Echo Cancellation, Noise Suppression, Mixer by acdb File) Speaker RX VOC Network Figure 3: Voice Flow Factors Affecting Voice Quality: ⚫ Network condition: if the test is conducted in a weak-signal area. ⚫ Channel condition: if the test is conducted in a fading/poor channel or if the channel condition results in CRC errors. ⚫ ADSP processing: if ADSP parameters are set wrongly. ⚫ Packet loss/miss: if the packet is lost in the network or the packet is missed in the system. ⚫ Codec: if an incorrect codec type is selected or a wrong registration parameter (see AT+QDAI, AT+QIIC and 3GPP TS 26.103) is configured. ⚫ PCM interface: if unsuitable parameters (see AT+QPCMCFG) with a selected codec are configured. NOTE BG95 series, BG77 and BG600L-M3 modules do not support adjusting ADSP parameters in real time BG95&BG77&BG600L_Series_Voice_Application_Note 36 / 43 by AT command. LPWA Module Series 6.1. Direction-Related Problem Analysis Making it clear whether the problem occurred on the uplink or downlink side, on the home side or peer side, is the key step to solving the problem. Uplink: If the TX VOC itself has any problem, there is no need to analyze the problem from the perspective of the protocol. If the TX VOC sounds good but the downlink sounds bad on the other end, it is necessary to capture the logs on both sides of the calling and called parties. This scenario can be regarded as the most complex one because there may be a problem with the callee on the remote party, or may be a problem with the local caller. Therefore, we need to compare the logs of both sides and analyze the logs together. Downlink: If the RX VOC itself sounds good but the subsequent PCM sounds bad, there is no need to analyze the problem from the perspective of the protocol. You only need to check whether the Codec and PCM are configured correctly. The RX VOC problem is the most common voice problem. Generally, it is necessary to start from the access layer and make a comprehensive analysis based on the current network coverage, wireless environment, signal-to-noise ratio, bit error rate and other factors. In fact, the vast majority of such problems are caused by poor network coverage. NOTE Be careful when capturing logs. First, select a dedicated audio log mask to capture the log before calling. Then, keep talking for about a minute. Last, hang up. 6.2. Protocol-Related Problem Analysis Voice analysis of common protocols is point-to-point analysis. That is, the time point at which the voice is faulty must be determined in the voice file generated by playback. By observing SNR and RSRP methods to measure the wireless environment at that time. When RSRP is lower than -95 dBm, the wireless environment is considered to be average, and when RSRP is lower than -105 dBm, the wireless environment is considered to be very poor. RxQual represents a bit error rate level, which is a very valid statistic for SNR. Generally, if RxQual is greater than 4 or CRC is 'Fail', or SNR is less than 0, it is difficult to ensure the voice quality. BG95&BG77&BG600L_Series_Voice_Application_Note 37 / 43 LPWA Module Series 6.2.1. VoLTE Issue Analysis From the image below, we can see that the current network condition is very poor because RSRP is less than -105 dBm, which may affect voice quality. Generally, it is not ideal for users to dial in the circumstance. Figure 4: Poor Network Condition in VoLTE 6.2.2. CS-Voice over GSM Issue Analysis From the images below, we can see that RxQual is 7 (greater than 4) in Figure 5 and CRC is 'Fail' in Figure 6. All these data represent the poor channel condition under GSM network, under which circumstances users may hear discontinuous sounds when making a call. BG95&BG77&BG600L_Series_Voice_Application_Note 38 / 43 LPWA Module Series Figure 5: Poor Channel Condition in CS-Voice (1) Figure 6: Poor Channel Condition in CS-Voice (2) BG95&BG77&BG600L_Series_Voice_Application_Note 39 / 43 LPWA Module Series 7 Appendix A References Table 3: Related Document Document Name [1] Quectel_BG95&BG77&BG600L_Series_AT_Commands_Manual Table 4: Terms and Abbreviations Abbreviation ADSP AMR-NB AMR-WB CLIR COLP CRC CSFB DAN DTMF EVS E-UTRA(N) G.711 IMS IPsec IWLAN Description Audio Digital Signal Processor Adaptive Multi-rate Narrow Band Adaptive Multi-rate Wide Band Calling Line Identification Restriction Connected Line Identification Presentation Cyclic Redundancy Check Circuit Switched Fallback Domain Availability Notification Dual-tone multi-frequency Enhance Voice Services Evolved Universal Terrestrial Radio Access (Network) ITU-T Standard Pulse Code Modulation (PCM) of Voice Frequencies IP Multimedia Subsystem Internet Protocol Security Industrial Wireless LAN BG95&BG77&BG600L_Series_Voice_Application_Note 40 / 43 MO MSC MT MWI PDN PCM QCI QoS RAT RCS ROHC RTP RTT SDP SMS SIP SRVCC TTY UDP VICE VoLTE LPWA Module Series Mobile Originated Mobile-services Switching Centre Mobile Terminated Message Waiting Indicator Packet Data Network Pulse Code Modulation QoS Class Identifier Quality of Service Radio Access Technology Rich Communication Suite Robust Header Compression Real-time Transport Protocol Real-Time Text Session Description Protocol Short Message Service Session Initiation Protocol Single Radio Voice Call Continuity Teletypewriter User Datagram Protocol VoLTE for Internet-connected Endpoint Voice over LTE BG95&BG77&BG600L_Series_Voice_Application_Note 41 / 43 LPWA Module Series 8 Appendix B Summary of CME ERROR Codes Final result code +CME ERROR: indicates an error related to mobile equipment or network. The operation of +CME ERROR: final result code is similar to the regular ERROR result code: if +CME ERROR: is the result code for any of the commands in a command line, none of the following commands in the same command line is executed (neither ERROR nor OK result code shall be returned as a result of a completed command line execution). The format of can be either numeric or verbose. This is set with AT+CMEE. The following table lists most of general and GRPS related ERROR codes. For some GSM protocol failure cause described in GSM specifications, the corresponding ERROR codes are not included. Table 5: Different Coding Schemes of +CME ERROR: Code of 0 1 2 3 4 5 6 7 10 11 12 Meaning Phone failure No connection to phone Phone-adaptor link reserved Operation not allowed Operation not supported PH-SIM PIN required PH-FSIM PIN required PH-FSIM PUK required (U)SIM not inserted (U)SIM PIN required (U)SIM PUK required BG95&BG77&BG600L_Series_Voice_Application_Note 42 / 43 LPWA Module Series 13 (U)SIM failure 14 (U)SIM busy 15 (U)SIM wrong 16 Incorrect password 17 (U)SIM PIN2 required 18 (U)SIM PUK2 required 20 Memory full 21 Invalid index 22 Not found 23 Memory failure 24 Text string too long 25 Invalid characters in text string 26 Dial string too long 27 Invalid characters in dial string 30 No network service 31 Network timeout 32 Network not allowed - emergency calls only 40 Network personalization PIN required 41 Network personalization PUK required 42 Network subset personalization PIN required 43 Network subset personalization PUK required 44 Service provider personalization PIN required 45 Service provider personalization PUK required 46 Corporate personalization PIN required 47 Corporate personalization PUK required BG95&BG77&BG600L_Series_Voice_Application_Note 43 / 43
602.39 KB
BG95&BG77&BG600L Series MQTT-SN Application Note LPWA Module Series Version: 1.0 Date: 2022-11-17 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 1 / 28 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 2 / 28 LPWA Module Series About the Document Revision History Version Date Author Description - 2021-10-13 Terrence YANG Creation of the document 1.0 2022-11-17 Terrence YANG First official release BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 3 / 28 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 2 MQTT-SN Data Interaction ................................................................................................................. 7 3 MQTT-SN Related AT Commands ..................................................................................................... 8 3.1. AT Command Syntax ................................................................................................................. 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-SN Related AT Commands ..................................................................... 9 3.3.1. AT+QMTSNCFG Configure Optional Parameters of MQTT-SN.................................. 9 3.3.2. AT+QMTSNOPEN Open a Network for MQTT-SN Client.......................................... 13 3.3.3. AT+QMTSNCLOSE Close a Network for MQTT-SN Client ....................................... 14 3.3.4. AT+QMTSNSUB Subscribe to Topics ........................................................................ 14 3.3.5. AT+QMTSNUNS Unsubscribe from Topics................................................................ 16 3.3.6. AT+QMTSNREG Request Topic ID............................................................................ 17 3.3.7. AT+QMTSNPUB Publish Messages .......................................................................... 18 3.3.8. AT+QMTSNWILLUPD Update Will Topic or Will Message ........................................ 20 3.3.9. AT+QMTSNSLEEP Configure the Current State of the Module ................................ 21 4 MQTT-SN Related URCs................................................................................................................... 23 4.1. +QMTSNSTAT URC to Indicate State Change in MQTT-SN Link Layer.............................. 23 4.2. +QMTSNRECV URC to Inform the Host to Read MQTT-SN Packet Data .......................... 25 5 Example ............................................................................................................................................. 26 5.1. Example of MQTT-SN Operation............................................................................................. 26 6 Appendix A References.................................................................................................................... 28 BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 4 / 28 LPWA Module Series Table Index Table 1: Types of At Commands .......................................................................................................................... 8 Table 2: MQTT-SN Related URCs ..................................................................................................................... 23 Table 3: Error Codes of the URC ....................................................................................................................... 24 Table 4: Terms and Abbreviations...................................................................................................................... 28 BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 5 / 28 LPWA Module Series 1 Introduction MQTT-SN is a publish/subscribe messaging protocol for wireless sensor networks (WSNs), with the aim of extending the MQTT protocol beyond the reach of TCP/IP infrastructure for sensor and actuator solutions. This document mainly introduces how to use the MQTT-SN function of Quectel BG95 series, BG77 and BG600L-M3 modules through AT commands. BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 6 / 28 LPWA Module Series 2 MQTT-SN Data Interaction This chapter gives the data interaction mechanism of MQTT-SN function. MCU Modem Link layer MQTT-SN Gateway AT+QMTSNCFG='will',,[…] AT+QMTSNCFG='timeout',,[…] AT+QMTSNOPEN AT+QMTSNOPEN=,,, OK +QMTSNOPEN: , AT+QMTSNREG AT+QMTSNREG=,, OK +QMTSNREG: ,, CONN-REQ Start timer T1, T2 Will flag=1 CONN ACK-IND Stop T1 or handle Excep1 Send connect packet Receive willtopic request packet Send willtopic packet Receive willmessage request packet Send willmessage packet Receive connect ACK packet REG-REQ (msgID) Start timer T1 REG ACK-IND (msgID) Stop T1 or handle Excep2 +QMTSNREG: tcpidx,1,msgId Send resister packet Receive register ACK packet AT+QMTSNSUB AT+QMTSNSUB=,,, SUB-REQ (msgID) OK Start timer T1 +QMTSNSUB: ,,[,] SUB ACK-IND (msgID) Stop T1 or handle Excep2 +QMTSNSUB: idx,1,msgId Send subscribe packet Receive subscribe ACK packet AT+QMTSNUNS AT+QMTSNUNS=,, OK +QMTSNUNS: ,, AT+QMTSNPUB=,,=0,< retain>, OK AT+QMTSNPUB AT+QMTSNPUB=,,=1,< (=1) retain>, OK +QMTSNPUB: ,,[,] UNS-REQ (msgID) Start timer T1 UNS ACK-IND (msgID) Stop T1 or handle Excep2 +QMTSNUNS: idx,1,msgId Send unsubscribe packet Receive unsubscribe ACK packet PUB-REQ Send publish packet PUB-REQ (msgID) Start timer T1 PUB ACK-IND (msgID) Stop T1 or handle Excep2 +QMTPUB: idx,1,msgId Send publish packet Receive publish ACK packet AT+QMTSNPUB AT+QMTSNPUB=,,=2,< (=2) retain>, OK +QMTSNPUB: ,,[,] PUB-REQ (msgID) Start timer T1 +QMTSNPUB: idx,1,msgId Send publish packet PUB REC-IND (msgID) Receive publish receive packet Stop T1 or handle Excep2 PUB REL-REQ (msgID) Start timer T1 PUB COMP-IND (msgID) +QMTSNPUBREL: idx,1,msgId Send publish release packet Receive publish complete packet Stop T1 or handle Excep2 Receive Receive PUBLISH message in the form of URC. +QMTSNRECV: ,,, AT+QMTSNCLOSE AT+QMTSNCLOSE= OK +QMTSNCLOSE: , PUB-IND (msgID) PUB ACK/REC-REQ (msgID) Reply accor.d..ing to DISC-REQ Disconnect Receive publish packet Send publish reply packet Send disconnect request Disconnect 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: Close UDP connection. Excep2: Resend packets unless the maximum retry times is reached. Retry times is set by AT+QMTSNCFG. Whether the timeout information is reported can be configured by AT+QMTSNCFG. Figure 1: MQTT-SN Data Interaction Diagram BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 7 / 28 LPWA Module Series 3 MQTT-SN Related AT Commands This chapter presents the AT commands for operating MQTT-SN function. 3.1. AT Command Syntax 3.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 3.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 1: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 8 / 28 LPWA Module Series 3.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 3.3. Description of MQTT-SN Related AT Commands 3.3.1. AT+QMTSNCFG Configure Optional Parameters of MQTT-SN This command configures optional parameters of MQTT-SN. AT+QMTSNCFG Configure Optional Parameters of MQTT-SN Test Command AT+QMTSNCFG=? Response +QMTSNCFG: 'pdpcid',(range of supported s), (range of supported s) +QMTSNCFG: 'keepalive',(range of supported s),(range of supported s) +QMTSNCFG: 'session',(range of supported s),(list of supported s) +QMTSNCFG: 'timeout',(range of supported s),(range of supported s),(range of supported s),(list of supported s) +QMTSNCFG: 'dtls',(range of supported s),(list of supported s),(range of supported s) +QMTSNCFG: 'will',(range of supported s),(list of supporteds),(range of supporteds),(list of supported s),, Write Command Query/set the PDP to be used by the MQTT-SN client AT+QMTSNCFG='pdpcid',[,] OK Response If the optional parameter is omitted, query the PDP used by the MQTT-SN client: +QMTSNCFG: 'pdpcid', OK BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 9 / 28 LPWA Module Series If the optional parameter is specified, set the PDP to be used by the MQTT-SN client: OK Write Command Query/set the keep-alive time AT+QMTSNCFG='keepalive',[,] If there is any error: ERROR Response If the optional parameter is omitted, query the keep-alive time: +QMTSNCFG: 'keepalive', OK If the optional parameter is specified, set the keep-alive time: OK Write Command Query/set the session type AT+QMTSNCFG='session',[,] If there is any error: ERROR Response If the optional parameter is omitted, query the session type: +QMTSNCFG: 'session', OK If the optional parameter is specified, set the session type: OK Write Command Query/set timeout of message delivery AT+QMTSNCFG='timeout',[,[,][,]] If there is any error: ERROR Response If the optional parameters are omitted, query the timeout of message delivery: +QMTSNCFG: 'timeout',,, OK If any of the optional parameters is specified, set the timeout of message delivery: OK Write Command Query/set DTLS security mode of If there is any error: ERROR Response If the optional parameters are omitted, query DTLS security BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 10 / 28 LPWA Module Series MQTT-SN client: AT+QMTSNCFG='dtls',[,,] mode of MQTT-SN client: +QMTSNCFG: 'dtls',, OK If the optional parameters are specified, set DTLS security mode for MQTT-SN client: OK Write Command Query/set Will information AT+QMTSNCFG='will',[,[,,,,]] If there is any error: ERROR Response If the optional parameters are omitted, query the Will information: +QMTSNCFG: 'will',[,,,,] OK If any of the optional parameters is specified, set the Will information: OK Maximum Response Time Characteristics If there is any error: ERROR 300 ms The command takes effect immediately. The configurations will not be saved. Parameter Integer type. MQTT-SN socket identifier. Range: 0–5. Integer type. The PDP to be used by the MQTT-SN client. Range: 1–16. Default value: 1. Integer type. Keep-alive time. Range: 0–3600. Default value: 120. Unit: second. It defines the maximum interval time for messages received from a client. If the server does not receive a message from the client within 1.5 times of the keepalive time period, it disconnects the client as if the client has sent a DISCONNECT message. Integer type. Session type. 0 The server must store the subscriptions of the client after it is disconnected 1 The server must discard any previously maintained information about the client and treat the connection as 'clean' BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 11 / 28 LPWA Module Series Integer type. Timeout of the packet delivery. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. Integer type. Whether to report timeout message when transmitting packet. 0 Not report 1 Report Integer type. MQTT-SN SSL mode. 0 Use normal UDP connection for MQTT-SN client 1 Use DTLS security connection for MQTT-SN client Integer type. DTLS context identifier. Range: 0–5. Integer type. Will flag configuration. 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 only used on PUBLISH messages. 0 When a client sends a PUBLISH message to a server, the server will not retain the message after it has been delivered to the current subscribers 1 When a client sends a PUBLISH message to a server, the server will retain the message after it has been delivered to the current subscribers String type. Will topic. The maximum length is 255 bytes. String type. Define the content of the message that is published to the will topic if the client is unexpectedly disconnected. It can be zero-length message. The maximum length is 255 bytes. 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. It is crucial to ensure the message delivery does not time out while the message is still being sent. BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 12 / 28 LPWA Module Series 3.3.2. AT+QMTSNOPEN Open a Network for MQTT-SN Client This command opens a network and sends CONNECT message for MQTT-SN client. AT+QMTSNOPEN Open a Network for MQTT-SN Client Test Command AT+QMTSNOPEN=? Response +QMTSNOPEN: (range of supported s),,(range of supported s), Read Command AT+QMTSNOPEN? OK Response [+QMTSNOPEN: ,,,] Write Command AT+QMTSNOPEN=,,, OK Response OK +QMTSNOPEN: , Maximum Response Time Characteristics If there is any error: ERROR (5 s by default), determined by network - Parameter Integer type. MQTT-SN socket identifier. Range: 0–5. String type. The address of the MQTT-SN gateway. It could be an IP address or a domain name. The maximum size is 255 bytes. Integer type. The port of the MQTT-SN gateway. Range: 0–65535. String type. The client identifier. The maximum size is 255 bytes. Integer type. Current state of the specified MQTT-SN client. 0 Idle state 1 MQTT-SN client is connecting 2 MQTT-SN client is connected 3 MQTT-SN client is disconnecting Integer type. Result of the command execution. -1 Failed to open network 0 Network opened successfully 1 Wrong parameter 2 MQTT-SN client identifier is occupied BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 13 / 28 LPWA Module Series 3 Failed to activate PDP 4 Failed to parse domain name 5 Network connection error Integer type. Timeout of the packet delivery. Range: 1–60. Default value: 5. Unit: second. 3.3.3. AT+QMTSNCLOSE Close a Network for MQTT-SN Client This command closes a network and sends DISCONNECT message for MQTT-SN client. AT+QMTSNCLOSE Close a Network for MQTT-SN Client Test Command AT+QMTSNCLOSE=? Response +QMTSNCLOSE: (range of supported s) Write Command AT+QMTSNCLOSE= OK Response OK +QMTSNCLOSE: , Maximum Response Time Characteristics If there is any error: ERROR (5 s by default), determined by network - Parameter Integer type. MQTT-SN socket identifier. Range: 0–5. Integer type. Result of the command execution. -1 Failed to close network 0 Network closed successfully 2 Failed to send DISCONNECT packet Integer type. Timeout of the packet delivery. Range: 1–60. Default value: 5. Unit: second. 3.3.4. AT+QMTSNSUB Subscribe to Topics This command subscribes to a certain topic. A SUBSCRIBE message is sent by a client to register an interest in a topic with the server. Messages published to the topic are delivered from the server to the client as PUBLISH messages. BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 14 / 28 LPWA Module Series AT+QMTSNSUB Subscribe to Topics Test Command AT+QMTSNSUB=? Response +QMTSNSUB: (range of supported s),(range of supported s),,(range of supported s) Write Command AT+QMTSNSUB=,,, OK Response OK +QMTSNSUB: ,, Maximum Response Time Characteristics If there is any error: ERROR × (15 s by default), determined by network - Parameter Integer type. MQTT-SN socket identifier. Range: 0–5. Integer type. Message identifier of packet. Range: 1–65535. String type. The topic that the client wants to subscribe to. The maximum size is 255 bytes. 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. Result of the command execution. 0 Sent packet successfully and received ACK from server 1 Packet retransmission 2 Failed to send packet Integer type. Timeout of the packet delivery. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. NOTE The is only present in messages where the QoS bits in the fixed header indicate QoS level 1 or 2. It must be unique amongst the set of 'inflight' messages in a particular direction of communication. It typically increases by exactly one from one message to the next, but is not required BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 15 / 28 to do so. LPWA Module Series 3.3.5. AT+QMTSNUNS Unsubscribe from Topics This command unsubscribes from a named topic. An UNSUBSCRIBE message is sent by the client to the gateway to unsubscribe from a named topic. AT+QMTSNUNS Unsubscribe from Topics Test Command AT+QMTSNUNS=? Response +QMTSNUNS: (range of supported s),(range of supported s), Write Command AT+QMTSNUNS=,, OK Response OK +QMTSNUNS: ,, Maximum Response Time Characteristics If there is any error: ERROR × (15 s by default), determined by network - Parameter Integer type. MQTT-SN socket identifier. Range: 0–5. Integer type. Message identifier of packet. Range: 1–65535. String type. The topic that the client wants to unsubscribe from. The maximum size is 255 bytes. Integer type. Result of the command execution. 0 Sent packet successfully and received ACK from server 1 Packet retransmission 2 Failed to send packet Integer type. Timeout of the packet delivery. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 16 / 28 LPWA Module Series 3.3.6. AT+QMTSNREG Request Topic ID This command requests a topic ID from the MQTT-SN gateway when sending a topic name. AT+QMTSNREG Request Topic ID Test Command AT+QMTSNREG=? Response +QMTSNREG: (range of supported s),(range of supported s), Read Command AT+QMTSNREG? OK Response [+QMTSNREG: ,, [...]] Write Command AT+QMTSNREG=,, OK Response OK +QMTSNREG: ,, Maximum Response Time Characteristics If there is any error: ERROR (5 s by default), determined by network - Parameter Integer type. MQTT-SN socket identifier. Range: 0–5. Integer type. Message identifier of packet. Range: 0–65535. String type. The topic that the client subscribed to. The maximum size is 255 bytes Integer type. The value of topic ID that shall be used in the PUBLISH message. Range: 0–65535. Integer type. Result of the command execution. 0 Sent packet successfully and received ACK from server 1 Packet retransmission 2 Failed to send packet Integer type. Timeout of the packet delivery. Range: 1–60. Default value: 5. Unit: second. BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 17 / 28 LPWA Module Series 3.3.7. AT+QMTSNPUB Publish Messages This command publishes messages by a client to a server for distribution to interested subscribers. Each PUBLISH message is associated with a topic name. AT+QMTSNREG or AT+QMTSNSUB should be executed with associated topic name before the message can be published. AT+QMTSNPUB Publish Messages Test Command AT+QMTSNPUB=? Response +QMTSNPUB: (range of supported s),(range of supported s),(range of supported s),(list of supported s),,(range of supported s) Write Command AT+QMTSNPUB=,,,, OK Response > After '>' is responded, input the data to be sent. Tap 'CTRL + Z' to send, and tap 'ESC' to cancel the operation. OK +QMTSNPUB: ,,[,] Write Command AT+QMTSNPUB=,,,,, If there is any error: ERROR Response > After '>' is responded, input the data to be sent. The number of bytes of inputted data must be equal to . OK +QMTSNPUB: ,,[,] Maximum Response Time Characteristics If there is any error: ERROR × (15 s by default), determined by network - Parameter Integer type. MQTT-SN socket identifier. Range: 0–5. Integer type. Message identifier of packet. Range: 0–65535. It will be 0 only when =0. BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 18 / 28 LPWA Module Series 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. Whether or not the server will retain the message after it has been delivered to the current subscribers. 0 Not retain 1 Retain String type. Topic that needs to be published. The maximum size is 255 bytes. Integer type. Length of message to be published. Range: 1–1024. Unit: byte. Integer type. Result of the command execution. 0 Sent packet successfully and received ACK from server (message that published when =0 does not require ACK) 1 Packet retransmission 2 Failed to send packet If is 1, it means the times of packet retransmission. If is 0 or 2, it will not be presented. Integer type. Timeout of the packet delivery. Range: 1–60. Default value: 5. Unit: second. Integer type. Retry times when packet delivery times out. Range: 0–10. Default value: 3. NOTES 1. After executing this command, the client is ready to send data, which will be sent as payload. The maximum length of the input data is 1024 bytes at a time and tap Ctrl + Z to send the data. 2. 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-SN gateway: +QMTSNRECV: ,,,. For more details about the URC description, please refer to Chapter 4.2. BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 19 / 28 LPWA Module Series 3.3.8. AT+QMTSNWILLUPD Update Will Topic or Will Message This command updates Will topic or Will message stored in gateway/server. If is 2, Will topic and Will message stored in gateway/server will be deleted. AT+QMTSNWILLUPD Update Will Topic or Will Message Test Command AT+QMTSNWILLUPD=? Response +QMTSNWILLUPD: (range of supported s), (range of supported s),(range of supported s),(list of supported s),/ Write Command AT+QMTSNWILLUPD=,< mode>,[,,/] OK Response OK +QMTSNWILLUPD: , Maximum Response Time Characteristics If there is an error: ERROR (5 s by default), determined by network - Parameter Integer type. MQTT-SN socket identifier. Range: 0–5. Integer type. Update or delete Will topic or/and Will message. 0 Update Will topic 1 Update Will message 2 Delete Will topic and Will message Integer type. Quality of service for message delivery. 0 At most once 1 At least once 2 Exactly once Integer type. The 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. The maximum length is 255 bytes. String type. The Will message defines the content of the message that is published to the will topic if the client is unexpectedly disconnected. It can be a BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 20 / 28 LPWA Module Series zero-length message. The maximum length is 255 bytes. Integer type. Result of the command execution. 0 Sent packet successfully and received ACK from server 1 Packet retransmission 2 Failed to send packet 3 Request rejected from server Integer type. Timeout of the packet delivery. Range: 1–60. Default value: 5. Unit: second. 3.3.9. AT+QMTSNSLEEP Configure the Current State of the Module This command configures the current state of the module and notifies the gateway that the client enters asleep, awake, or active state. AT+QMTSNSLEEP Configure the Current Status of the Module Test Command AT+QMTSNSLEEP=? Response +QMTSNSLEEP: (range of supported s),(range of supported s),(range of supported s) Write Command AT+QMTSNSLEEP=,[,] OK Response OK +QMTSNSLEEP: , Maximum Response Time Characteristics If there is an error: ERROR (5 s by default), determined by network - Parameter Integer type. MQTT-SN socket identifier. Range: 0–5. Integer type. The current state of the module. 0 Asleep state 1 Awake state 2 Active state Integer type. Sleep duration. It is only valid when is 0. Range: 900–64800. Unit: second. Integer type. Result of the command execution. 0 Sent packet successfully and received ACK from server BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 21 / 28 LPWA Module Series 1 Packet retransmission 2 Failed to send packet Integer type. Timeout of the packet delivery. Range: 1–60. Default value: 5. Unit: second. BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 22 / 28 LPWA Module Series 4 MQTT-SN Related URCs This chapter gives MQTT-SN related URCs and their descriptions. Table 2: MQTT-SN Related URCs SN URC Format Description When the state of MQTT-SN link layer is [1] +QMTSNSTAT: , changed, the client will close the MQTT-SN connection and report the URC. +QMTSNRECV: ,,, packet data from MQTT-SN gateway. 4.1. +QMTSNSTAT URC to Indicate State Change in MQTT-SN Link Layer The URC begins with +QMTSNSTAT:. It will be reported when there is a change in the state of MQTT-SN link layer. +QMTSNSTAT URC to Indicate State Change in MQTT-SN Link Layer +QMTSNSTAT: , will close the MQTT-SN connection and report the URC. Parameter Integer type. MQTT-SN socket identifier. Range: 0–5. Error codes. Please refer to the table below for details. BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 23 / 28 LPWA Module Series Table 3: Error Codes of the URC 1 2 3 4 5 6 7 8-255 Description How to do The connection is closed or reset by a peer. Sending PINGREQ packet timed out or failed. Sending CONNECT packet timed out or failed. Receiving CONNACK packet timed out or failed. The client sends DISCONNECT packet to sever and the server is initiative to close MQTT-SN connection. The client is initiative to close MQTT-SN connection due to packet sending failure all the time. The link is not alive or the server is unavailable. Execute AT+QMTSNOPEN and reopen MQTT-SN connection. Deactivate PDP first, and then active PDP and reopen MQTT-SN connection. 1. Check whether the inputted user name and password are correct. 2. Make sure the client ID is not used. 3. Reopen MQTT-SN connection and try to send CONNECT packet to server again. 1. Check whether the inputted user name and password are correct. 2. Make sure the client ID is not used. 3. Reopen MQTT-SN connection and try to send CONNECT packet to server again. This is a normal process. 1. Make sure the data is correct. 2. Try to reopen MQTT-SN connection since there may be network congestion or an error. Make sure the link is alive or the server is available currently. Reserved for future use. - BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 24 / 28 LPWA Module Series 4.2. +QMTSNRECV URC to Inform the Host to Read MQTT-SN Packet Data The URC begins with +QMTSNRECV:. It is mainly used to inform the host to read the received MQTT-SN packet data that is reported from MQTT-SN gateway. +QMTSNRECV URC to Inform the Host to Read MQTT-SN Packet Data +QMTSNRECV: ,,, MQTT-SN gateway. Parameter Integer type. MQTT-SN socket identifier. Range: 0–5. Integer type. The message identifier of packet. Range: 0–65535. String type. The topic that received from MQTT-SN gateway. The maximum size is 255 bytes. String type. The payload that relates to the topic name. BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 25 / 28 LPWA Module Series 5 Example This chapter gives the examples to explain how to use MQTT-SN related AT commands. 5.1. Example of MQTT-SN Operation //Open a network for MQTT-SN client. AT+QMTSNOPEN=0,'220.180.239.212',8027,'clientid' OK +QMTSNOPEN: 0,0 //Opened the MQTT-SN client network successfully. AT+QMTSNOPEN? +QMTSNOPEN: 0,'220.180.239.212',8027,2 OK AT+QMTSNREG=0,1,'topic/example' OK +QMTSNREG: 0,1,0 AT+QMTSNREG=0,1,'topic/pub' OK +QMTSNREG: 0,1,0 AT+QMTSNSUB=? +QMTSNSUB: (0-5),(1-65535),,(0-2) OK //Subscribe to topics. AT+QMTSNSUB=0,1,'topic/example',2 OK +QMTSNSUB: 0,1,0 AT+QMTSNSUB=0,1,'topic/pub',0 OK +QMTSNSUB: 0,1,0 BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 26 / 28 LPWA Module Series //If a client subscribes to a topic and other devices publish message related to the same topic to the server, the module reports the following information. +QMTSNRECV: 0,0,'topic/example','This is the payload related to topic' //Unsubscribe from topics. AT+QMTSNUNS=0,2,'topic/example' OK +QMTSNUNS: 0,2,0 AT+QMTSNPUB=? +QMTSNPUB: (0-5),(0-65535),(0-2),(0,1),,(1-1024) OK //Publish messages. AT+QMTSNPUB=0,0,0,0,'topic/pub' >This is test data, hello MQTT-SN. //After receiving >, input data This is test data, hello MQTT-SN. and then send it. The maximum length of the data is 1024 bytes and the data that beyond 1024 bytes will be omitted. After inputting data, tap Ctrl + Z to send. OK +QMTSNPUB: 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. +QMTSNRECV: 0,0,'topic/pub','This is test data, hello MQTT-SN.' //Disconnect a client from MQTT-SN gateway. AT+QMTSNCLOSE=0 OK +QMTSNCLOSE: 0,0 //Connection closed successfully. BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 27 / 28 LPWA Module Series 6 Appendix A References Table 4: Terms and Abbreviations Abbreviation ACK DTLS IP LPWA MQTT MQTT-SN PDP QoS RAM SSL TCP UDP URC WSN Description Acknowledgement Datagram Transport Layer Security Internet Protocol Low Power Wide Area Message Queuing Telemetry Transport MQTT For Sensor Networks Packet Data Protocol Quality of Service Random Access Memory Security Socket Layer Transmission Control Protocol User Datagram Protocol Unsolicited Result Code Wireless Sensor Networks BG95&BG77&BG600L_Series_MQTT-SN_Application_Note 28 / 28
349.31 KB
BG95&BG77&BG600L Series Voice Application Note LPWA Module Series Version: 1.0 Date: 2022-09-30 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG95&BG77&BG600L_Series_Voice_Application_Note 1 / 43 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG95&BG77&BG600L_Series_Voice_Application_Note 2 / 43 LPWA Module Series About the Document Revision History Version 1.0 Date 2022-06-01 2022-09-30 Author Nora HE Nora HE Description Creation of the document First official release BG95&BG77&BG600L_Series_Voice_Application_Note 3 / 43 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 6 Figure Index ................................................................................................................................................ 7 1 Introduction ......................................................................................................................................... 8 1.1. Applicable Modules and Supported Voice Feature ................................................................... 8 2 General Overview of IMS and VoLTE................................................................................................ 9 2.1. Introduction to IMS Features...................................................................................................... 9 2.1.1. Supported Features ........................................................................................................ 9 2.1.2. Features Not Supported.................................................................................................. 9 2.2. Introduction to VoLTE Call Flow............................................................................................... 10 2.2.1. Prerequisite for VoLTE Call ........................................................................................... 10 2.2.2. Process of VoLTE Call .................................................................................................. 10 3 AT Command Introduction .............................................................................................................. 12 3.1. AT Command Introduction ....................................................................................................... 12 3.1.1. Definitions...................................................................................................................... 12 3.1.2. AT Command Syntax .................................................................................................... 12 3.1.3. Declaration of AT Command Examples ........................................................................ 13 4 AT Command Description................................................................................................................ 14 4.1. AT+QCFG='ims' Query IMS Registration State ................................................................... 14 4.2. ATD Originate a Call.............................................................................................................. 15 4.3. ATA Answer an Incoming Call ............................................................................................... 17 4.4. ATH Disconnect Existing Connection.................................................................................... 18 4.5. AT+CVHU Voice Call Hang Up Control................................................................................. 19 4.6. AT+CLCC List Current Calls of ME ....................................................................................... 20 4.7. AT+CHUP Hang up a Call ..................................................................................................... 21 4.8. AT+QIIC Read/ Write Codec Through IIC ............................................................................. 22 4.9. AT+QDAI Configure Digital Audio Interface .......................................................................... 23 4.10. AT+CLVL Configure Loudspeaker Volume............................................................................ 24 4.11. AT+CMUT Muting Control ..................................................................................................... 25 4.12. AT+QPCMCFG Configure PCM Interface............................................................................. 26 4.13. AT+QLDTMF Play Local DTMF ............................................................................................ 28 4.14. AT+VTS DTMF and Tone Generation ................................................................................... 29 4.15. AT+QTONEDET Enable/Disable DTMF Detection ............................................................... 30 4.16. AT+QAUDLOOP Enable/Disable Audio Loop Test ............................................................... 31 4.17. AT+QINDCFG Configure URC Indication ............................................................................. 32 5 Description of URCs ......................................................................................................................... 35 5.1. RING URC ............................................................................................................................... 35 5.2. Alert URC ................................................................................................................................. 35 BG95&BG77&BG600L_Series_Voice_Application_Note 4 / 43 LPWA Module Series 6 Issue Analysis ................................................................................................................................... 36 6.1. Direction-Related Problem Analysis ........................................................................................ 37 6.2. Protocol-Related Problem Analysis ......................................................................................... 37 6.2.1. VoLTE Issue Analysis .................................................................................................... 38 6.2.2. CS-Voice over GSM Issue Analysis .............................................................................. 38 7 Appendix A References.................................................................................................................... 40 8 Appendix B Summary of CME ERROR Codes............................................................................... 42 BG95&BG77&BG600L_Series_Voice_Application_Note 5 / 43 LPWA Module Series Table Index Table 1: Applicable Modules and Supported Voice Feature ....................................................................... 8 Table 2: Types of AT Commands .............................................................................................................. 12 Table 3: Related Document........................................................................................................................ 40 Table 4: Terms and Abbreviations .............................................................................................................. 40 Table 5: Different Coding Schemes of +CME ERROR: ................................................................... 42 BG95&BG77&BG600L_Series_Voice_Application_Note 6 / 43 LPWA Module Series Figure Index Figure 1: VoLTE Call Flow...........................................................................................................................11 Figure 2: Data Path of AFE Loopback ....................................................................................................... 31 Figure 3: Voice Flow................................................................................................................................... 36 Figure 4: Poor Network Condition in VoLTE .............................................................................................. 38 Figure 5: Poor Channel Condition in CS-Voice (1) .................................................................................... 39 Figure 6: Poor Channel Condition in CS-Voice (2) .................................................................................... 39 BG95&BG77&BG600L_Series_Voice_Application_Note 7 / 43 LPWA Module Series 1 Introduction This document introduces the application of VoLTE and describes the related AT commands of VoLTE, CS voice over GSM (2G) and audio services on Quectel BG95 series, BG77 and BG600L-M3 modules. 1.1. Applicable Modules and Supported Voice Feature Table 1: Applicable Modules and Supported Voice Feature Module Series Module BG95-M1 Supported Network Cat M1 only Supported Voice Feature VoLTE BG95-M2 Cat M1/Cat NB2 VoLTE BG95 BG95-M3 Cat M1/Cat NB2/EGPRS VoLTE/CS voice BG95-M5 Cat M1/Cat NB2/EGPRS, Power Class 3 VoLTE/CS voice BG95-M6 Cat M1/Cat NB2, Power Class 3 VoLTE BG77 BG77 Cat M1/Cat NB2 VoLTE BG600L BG600L-M3 Cat M1/Cat NB2/EGPRS VoLTE/CS voice BG95&BG77&BG600L_Series_Voice_Application_Note 8 / 43 LPWA Module Series 2 General Overview of IMS and VoLTE 2.1. Introduction to IMS Features The IP Multimedia Subsystem (IMS) is an architectural framework for delivering IP multimedia services. 2.1.1. Supported Features The following features are supported in IMS: ⚫ LTE RAT ⚫ Power-saving mode ⚫ IMS registration with or without IPsec ⚫ Single VoLTE call ⚫ SIP forking (up to seven dialogs) ⚫ Audio codecs: AMR-NB, DTMF ⚫ QoS and preconditions ⚫ SMS over IMS in 3GPP format only 2.1.2. Features Not Supported The following features are currently not supported in IMS: ⚫ Emergency call ⚫ Multi-call, such as conference call, call transfer and call pulling ⚫ SRVCC and CSFB ⚫ Audio codecs: EVS, AMR-WB, and G.711 ⚫ VoLTE for internet-connected endpoint (VICE) ⚫ DAN ⚫ Video call, RTT, and TTY ⚫ MWI ⚫ IWLAN ⚫ RCS or Presence BG95&BG77&BG600L_Series_Voice_Application_Note 9 / 43 LPWA Module Series 2.2. Introduction to VoLTE Call Flow VoLTE (Voice over Long-Term Evolution) is based on the IP Multimedia Subsystem (IMS) network, and uses special configuration files for the control and media planes. This enables voice services (at the control and media levels) to be transmitted as data streams over LTE data bearer networks. VoLTE initialization procedures are required before a VoLTE session is established. 2.2.1. Prerequisite for VoLTE Call 1. Attach to LTE network and select domain (all call flows assume voice over IMS). 2. Establish IMS PDN connection and SIP QoS flow. QCI = 5 is used for SIP signaling on IMS default bearer. 3. Complete IMS registration and subscription with IMS CN. IMS feature tags for available services are MMTel IMS Communication Services Identifier (ICSI). 2.2.2. Process of VoLTE Call The steps to establish a VoLTE session with a remote party are as follows. 1. Attach to LTE network and select domain. 2. Establish IMS PDN connection and SIP QoS flow. 3. Complete IMS registration and subscription. 4. Establish IMS session. ⚫ Transmit information by SIP signaling. ⚫ Negotiate codec with SDP. 5. Establish VoLTE QoS call flow. ⚫ Implement network-initiated QoS procedure. 6. Propose ROHC negotiation. 7. Transmit full-duplex VoLTE data between UE and E-UTRA(N). ⚫ This data is routed from the E-UTRA(N) by the packet data core network to the remote party involved in the call. ⚫ Each voice frame is generated by the vocoder and carried as the payload in RTP. ⚫ RTP packets are encapsulated in UDP packets and carried over IP. 8. Terminate IMS session. ⚫ Transmit information by SIP signaling. ⚫ Release and clean up existing VoLTE call(s). 9. Release VoLTE QoS flow. ⚫ Release network-dependent QoS procedure. 10. Terminate VoLTE feature. BG95&BG77&BG600L_Series_Voice_Application_Note 10 / 43 UE E-UTRA(N)/ PDN LTE attachment + domain selection IMS PDN connection + SIP Qos flow IMS registration and subscription {Call setup IMS session establishment VoLTE Qos flow establishment ROHC negotiation VoLTE data IMS session termination VoLTE QoS flow release IMS de-registration LPWA Module Series IM/ CN VoLTE feature initialization procedures VoLTE session procedures } May be simultaneous VoLTE feature termination procedure Figure 1: VoLTE Call Flow BG95&BG77&BG600L_Series_Voice_Application_Note 11 / 43 LPWA Module Series 3 AT Command Introduction 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. BG95&BG77&BG600L_Series_Voice_Application_Note 12 / 43 LPWA Module Series 3.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. BG95&BG77&BG600L_Series_Voice_Application_Note 13 / 43 LPWA Module Series 4 AT Command Description This chapter introduces the voice and audio related AT commands supported by the modules, including the functions, usages and the scope of AT commands. For some AT commands or URCs mentioned but not described in detail in this chapter, unless otherwise specified, see document [1] for more information and usage. 4.1. AT+QCFG='ims' Query IMS Registration State This command queries the module's IMS registration state. VoLTE state indicates IMS registration state, that is, VoLTE is ready indicates IMS feature is enabled. AT+QCFG='ims' Query IMS Registration State Write Command AT+QCFG='ims' Response +QCFG: 'ims', OK Or ERROR Maximum Response Time Characteristics If there is an error related to ME functionality: +CME ERROR: 300 ms - Parameter Integer type. VoLTE state. 0 VoLTE is not ready 1 VoLTE is ready Error code. See Chapter 8 for details. Example AT+QCFG='ims' +QCFG: 'ims',1 BG95&BG77&BG600L_Series_Voice_Application_Note 14 / 43 OK NOTE This command is valid only on the firmware version supporting VoLTE. LPWA Module Series 4.2. ATD Originate a Call This command sets up outgoing voice or data call. ATD Originate a Call Execution Command ATD[][;] Response If no dial tone and ATX2 or ATX4 is set: NO DIAL TONE If busy and ATX3 or ATX4 is set: BUSY If a call connection cannot be established: NO CARRIER If a call connection is established successfully and a non-voice call is to be set up: CONNECT TA switches to data mode. is output only when is greater than 0 in ATX parameter setting. When TA returns to command mode after call release: OK Maximum Response Time Characteristics If a call connection is established successfully and a voice call is set up: OK Or ERROR 5 s, determined by the network (AT+COLP=0). - BG95&BG77&BG600L_Series_Voice_Application_Note 15 / 43 LPWA Module Series Reference V.25ter Parameter String of dialing strings and optional V.25ter modifiers. Dialing strings: 0-9, *, #, +, A, B, C Following V.25ter, optional modifiers ,(comma), T, P, !, W, @ are ignored. String of GSM modifiers: I Activates CLIR (Disable presentation of calling number to called party). i Deactivates CLIR (Enable presentation of calling number to called party). G Activates closed user group invocation for this call only. g Deactivates closed user group invocation for this call only. It is required when setting up a voice call. After the call, TA will return to command state. Example ATD10086; OK //Dial a number. NOTE 1. This command may be aborted generally by receiving an ATH command or a character during execution. It cannot be aborted during some connection establishments such as handshaking. 2. Parameters I and i can be omitted only when there is no * or # code in the dial string. 3. See ATX for details about setting result codes and call monitoring parameters. 4. For voice calls, if dialing with ATD, TA returns OK immediately either after the dialing is completed or the call is established. Otherwise, TA returns BUSY, NO DIAL TONE, or NO CARRIER. 5. Use ATD during an active voice call: ⚫ When a user originates a second voice call while there is already an active voice call, the first call will be automatically put on hold. ⚫ The current states of all calls can be easily checked at any time by AT+CLCC. See Chapter 4.6 for details. 6. Currently, supplementary services, such as COLP, CLIR or closed user group, are not supported. BG95&BG77&BG600L_Series_Voice_Application_Note 16 / 43 LPWA Module Series 4.3. ATA Answer a Call This command connects the module to an incoming voice or data call indicated by a RING URC. ATA Answer a Call Execution Command ATA Response TA sends off-hook to the remote station. In case of data call, if successfully connected: CONNECT And TA switches to data mode. Note: is output only when is greater than 0 in ATX parameter setting. When TA returns to command mode after call release: OK In case of voice call, if successfully connected: OK If no connection: NO CARRIER Or ERROR Maximum Response Time Characteristics Reference V.25ter If there is any error related to ME functionality: +CME ERROR: 90 s, determined by the network. - Parameter Error code. See Chapter 8 for details. Example RING OK ATA OK //Ring tone. //Answer the call. BG95&BG77&BG600L_Series_Voice_Application_Note 17 / 43 LPWA Module Series NOTE 1. Any additional commands on the same command line are ignored. 2. This command may be aborted generally by receiving a character during execution. It cannot be aborted during some connection establishments such as handshaking. 3. See also ATX. 4.4. ATH Disconnect Existing Connection This command disconnects and terminates existing data call or voice call. AT+CHUP is also used to disconnect voice call. See Chapter 4.7 for details. ATH Disconnect Existing Connection Execution Command ATH[] Response OK Or ERROR Maximum Response Time Characteristics Reference V.25ter If there is any error related to ME functionality: +CME ERROR: 90 s, determined by the network. - Parameter Integer type. 0 Disconnect and terminate existing call from command line. Error code. See Chapter 8 for details. Example RING OK ATH OK //Ring tone. //When AT+CVHU=0, hang up the call. BG95&BG77&BG600L_Series_Voice_Application_Note 18 / 43 LPWA Module Series 4.5. AT+CVHU Voice Call Hang Up Control This command controls whether ATH can be used to disconnect the voice call. AT+CVHU Voice Call Hang Up Control Test Command AT+CVHU=? Response +CVHU: (list of supported s) Read Command AT+CVHU? OK Response +CVHU: Write Command AT+CVHU= OK Response OK Or ERROR Maximum Response Time Characteristics Reference 3GPP TS 27.007 If there is an error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. The configuration is not saved. Parameter Integer type. 0 ATH can be used to disconnect the voice call. 1 ATH is ignored with the response OK returned only. Error code. See Chapter 8 for details. BG95&BG77&BG600L_Series_Voice_Application_Note 19 / 43 LPWA Module Series 4.6. AT+CLCC List Current Calls of ME The Execution Command returns the list of all voice calls of ME. If the command is executed successfully, but no call exists, then only OK is sent to TE. AT+CLCC List Current Calls of ME Test Command AT+CLCC=? Execution Command AT+CLCC Response OK Response TA returns the list of all current calls of ME. If the command is executed successfully, but no calls exists, then only OK is sent to TE. [+CLCC: ,,,,[,,[,< alpha>]]] [+CLCC: ,,,,[,,[,< alpha>]]] [...] OK Or ERROR Maximum Response Time Characteristics If there is an error related to ME functionality: +CME ERROR: 300 ms - Parameter Integer type. Call identification number (starting with 1). See 3GPP TS 22.030 subclause 6.5.5.1 for details. Integer type. 0 Mobile originated (MO) call 1 Mobile terminated (MT) call Integer type. Call state. 0 Active 1 Held 2 Dialing (MO call) 3 Alerting (MO call) 4 Incoming (MT call) 5 Waiting (MT call) Integer type. Bearer/teleservice. 0 Voice BG95&BG77&BG600L_Series_Voice_Application_Note 20 / 43 LPWA Module Series 1 Data 2 Fax Integer type. 0 Call is not one of the multiparty (conference) call parties 1 Call is one of the multiparty (conference) call parties String type. Phone number in format specified by . Integer type. Address type in octet format (See 3GPP TS 24.008 subclause 10.5.4.7 for details). Usually, it has three values: 129 Unknown type 145 International type (contains character '+') 161 National type Alphanumeric representation of corresponding to the entry found in phonebook. Error code. See Chapter 8 for details. Example ATD10086; //Dial a number. OK AT+CLCC +CLCC: 2,0,0,0,0,'10086',129 //Dial a number, and the call has been answered. OK 4.7. AT+CHUP Hang up a Call This command cancels any voice call in the state of Active, Waiting or Held. To cancel data call, use ATH. See Chapter 4.4 for details. AT+CHUP Hang up a Call Test Command AT+CHUP=? Execution Command AT+CHUP Response OK Response OK Or ERROR Maximum Response Time Characteristics If there is an error related to ME functionality: +CME ERROR: 90 s, determined by the network. - BG95&BG77&BG600L_Series_Voice_Application_Note 21 / 43 Reference 3GPP 27.007 Parameter Error code. See Chapter 8 for details. Example RING AT+CHUP OK //Ring tone. //Hang up the call. LPWA Module Series 4.8. AT+QIIC Read/ Write Codec Through IIC This command reads and writes the codec through the IIC interface. AT+QIIC Read/ Write Codec Through IIC Test Command AT+QIIC=? Response +QIIC: (list of supported s),(range of supported s),(range of supported s),(list of supported s),(range of supported s) Write Command AT+QIIC=,,,[,] OK Response If =0, all configuration parameters are specified: OK If =1, is omitted: +QIIC: Maximum Response Time Characteristics OK Or ERROR 300 ms The command takes effect immediately. The configurations are not saved. BG95&BG77&BG600L_Series_Voice_Application_Note 22 / 43 LPWA Module Series Parameter Integer type. 0 Write codec through IIC 1 Read codec through IIC Hexadecimal integer type with prefix '0x'. 7-bit slave device address (address of ALC5616: 0x1B; address of NAU8814, NAU88C10: 0x1A, TLV320AIC3104: 0x18 and MAX9860: 0x10). Range: 0–0xFF. Hexadecimal integer type with prefix '0x'. Register address. Range: 0–0xFF. Integer type. Length of the read or write byte(s). Value: 1, 2. Hexadecimal integer type with prefix '0x'. Data value. Range: 0–0xFFFF. Example AT+QIIC=1,0x1B,0x00,2 +QIIC: 0x0021 //Read register value; slave device address: 0x1B; register address: 0x00; read two bytes. OK AT+QIIC=0,0x1B,0x00,2,0x0000 OK //Write register value; slave device address: 0x1B; register address: 0x00; write two bytes; data value: 0x0000. NOTE is 7-bit slave device address (read or write bit not included), which can be found in the device datasheet. 4.9. AT+QDAI Configure Digital Audio Interface This command configures the digital audio interface. AT+QDAI Configure Digital Audio Interface Test Command AT+QDAI=? Response +QDAI: (list of supported s) Read Command AT+QDAI? OK Response +QDAI: OK BG95&BG77&BG600L_Series_Voice_Application_Note 23 / 43 LPWA Module Series Write Command AT+QDAI= Maximum Response Time Characteristics Response OK Or ERROR 300 ms The command takes effect immediately. The configuration is saved automatically. Parameter Integer type. 0 Analog input and output (for audio codec NAU88C10) 1 Analog input and output (for audio codec NAU8814) 2 Analog input and output (for audio codec ALC5616) 3 Analog input and output (for audio codec TLV320AIC3104) 4 Analog input and output (for audio codec MAX9860) 99 Close all external codecs. Example AT+QDAI=? +QDAI: (0-4,99) OK AT+QDAI? +QDAI: 1 OK AT+QDAI=2 OK //Query the current interface configuration. //Set the analog output to ALC5616. 4.10. AT+CLVL Configure Loudspeaker Volume This command configures the volume of the internal loudspeaker of the MT. AT+CLVL Configure Loudspeaker Volume Test Command AT+CLVL=? Response +CLVL: (range of supported s) Read Command OK Response BG95&BG77&BG600L_Series_Voice_Application_Note 24 / 43 LPWA Module Series AT+CLVL? Write Command AT+CLVL= Maximum Response Time Characteristics +CLVL: OK Response OK Or ERROR 300 ms The command takes effect immediately. The configurations are saved automatically. Parameter Integer type. Volume level with manufacturer specific range (Smallest value represents the lowest sound level). Range: 0–5. Default value: 3. Example AT+CLVL=? +CLVL: (0-5) OK AT+CLVL? +CLVL: 3 OK AT+CLVL=2 OK //Query the current volume level. //Set the volume level to 2. 4.11. AT+CMUT Muting Control This command enables or disables muting in the Tx/Rx direction during a voice call. AT+CMUT Muting Control Test Command AT+CMUT=? Response +CMUT: (list of supported s),(list of supported s) Write Command OK Response BG95&BG77&BG600L_Series_Voice_Application_Note 25 / 43 LPWA Module Series AT+CMUT=, Maximum Response Time Characteristics OK Or ERROR 300 ms The command takes effect immediately. The configurations are not saved and must be set during the call. Parameter Integer type. 0 Tx direction 1 Rx direction Integer type 0 Mute off 1 Mute on Example AT+CMUT=? +CMUT: (0,1),(0,1) OK AT+CMUT=1,1 OK //Mute on in Rx direction. 4.12. AT+QPCMCFG Configure PCM Interface This command configures the PCM interface. AT+QPCMCFG Configure PCM Interface Test Command AT+QPCMCFG=? Response +QPCMCFG: (list of supported s),(range of supported s),(range of supported s),(list of supported s) Read Command AT+QPCMCFG? OK Response +QPCMCFG: ,,, BG95&BG77&BG600L_Series_Voice_Application_Note 26 / 43 LPWA Module Series OK Write Command AT+QPCMCFG=,,, Response OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect after re-running voice call. The configurations are saved automatically. Parameter Integer type. 0 Short frame sync 1 Long frame sync Integer type. Bits width per frame. 0 8 bits (not supported currently) 1 16 bits (not supported currently) 2 32 bits 3 64 bits 4 128 bits 5 256 bits Integer type. Quant type in PCM format. 0 A-law no padding 1 Mu-law no padding 2 linear no padding (supported only) 3 A-law padding 4 Mu-law padding 5 linear padding Integer type. 1 16-bit PCM (supported only) 2 24-bit PCM 4 32-bit PCM Example AT+QPCMCFG=? +QLDTMF: (0,1),(0-5),(0-5),(1,2,4) OK AT+QPCMCFG=1,5,2,1 OK //Configure the PCM interface. BG95&BG77&BG600L_Series_Voice_Application_Note 27 / 43 LPWA Module Series NOTE Default: 2.048 MHz BCLK, 8 KHz (supported only) sampling rate, audio PCM only in master mode. 4.13. AT+QLDTMF Play Local DTMF This command plays a local DTMF tone. AT+QLDTMF Play Local DTMF Test Command AT+QLDTMF=? Response +QLDTMF: (list of supported s),(range of supported s),(range of supported s) Write Command AT+QLDTMF=, , OK Response OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. The configurations are not saved. Parameter String type. DTMF character. Range: 0–9, A–D, *, #. Integer type. DTMF tone play time duration. Range: 0–65535. Integer type. DTMF tone play volume gain. Range: 0–65535. Example AT+QLDTMF=? +QLDTMF: (0-9,A-D,*,#),(0-65535),(0-65535) OK AT+QLDTMF=2,200,200 OK //Play '2' DTMF tone whose volume gain is 200 for 200 ms. BG95&BG77&BG600L_Series_Voice_Application_Note 28 / 43 LPWA Module Series 4.14. AT+VTS DTMF and Tone Generation This command sends ASCII characters which cause MSC to transmit DTMF tones to a remote subscriber. This command can only be executed in a voice call. AT+VTS DTMF and Tone Generation Test Command AT+VTS=? Response +VTS: (list of supported s) Execution Command AT+VTS= OK Response OK Or ERROR Maximum Response Time Characteristics Reference 3GPP 27.007 If there is an error related to ME functionality: +CME ERROR: 300 ms - Parameter String type. DTMF character. Range: 0–9, A–D. *, #. Error code. See Chapter 8 for details. Example ATD12345678900; OK //Call connects. AT+VTS=1 OK //Dial. //The remote caller can hear the DTMF tone. NOTE This command cannot send multiple tones at one time. BG95&BG77&BG600L_Series_Voice_Application_Note 29 / 43 LPWA Module Series 4.15. AT+QTONEDET Enable/Disable DTMF Detection This command enables or disables DTMF detection during CS voice or VoLTE call. If this function is enabled, DTMF tones sent by the other side are detected and reported on the assigned serial port. AT+QTONEDET Enable/Disable DTMF Detection Test Command AT+QTONEDET=? Response +QTONEDET: (list of supported s) Read Command AT+QTONEDET? OK Response +QTONEDET: Write Command AT+QTONEDET= Maximum Response Time Characteristics OK Response OK Or ERROR 300 ms The command takes effect immediately. The configuration is not saved. Parameter Integer type. Enable or disable DTMF detection. 0 Disable 1 Enable Example AT+QTONEDET=? +QTONEDET: (0,1) OK AT+QTONEDET=1 OK //Enable DTMF detection. BG95&BG77&BG600L_Series_Voice_Application_Note 30 / 43 NOTE DTMF characters - ASCII DTMF 0 1 2 3 4 5 6 7 ASCII 48 49 50 51 52 53 54 55 DTMF 8 9 A B C D * # LPWA Module Series ASCII 56 57 65 66 67 68 42 35 4.16. AT+QAUDLOOP Enable/Disable Audio Loop Test This command enables or disables the audio loop test. AFE loopback is supported to verify the audio hardware connection, as shown in the following figure. TX AFE RX Codec Microphone Speaker Figure 2: Data Path of AFE Loopback AT+QAUDLOOP Enable/Disable Audio Loop Test Test Command AT+QAUDLOOP=? Response +QAUDLOOP: (list of supporteds) OK BG95&BG77&BG600L_Series_Voice_Application_Note 31 / 43 LPWA Module Series Write Command AT+QAUDLOOP= Maximum Response Time Characteristics Response OK Or ERROR 300 ms The command takes effect immediately. The configuration is not saved. Parameter Integer type. Enable or disable audio loop test. 0 Disable audio loop test 1 Enable audio loop test Example AT+QAUDLOOP=1 //Enable audio loop test, talk into the microphone, and the earphones can hear you. OK 4.17. AT+QINDCFG Configure URC Indication This command configures the URC indication. AT+QINDCFG Configure URC Indication Test command AT+QINDCFG=? Response +QINDCFG: 'all',(list of supported s),(list of supported s) +QINDCFG: 'csq',(list of supported s),(list of supported s) +QINDCFG: 'smsfull',(list of supported s),(list of supported s) +QINDCFG: 'ring',(list of supported s),(list of supported s) +QINDCFG: 'smsincoming',(list of supported s),(list of supported s) +QINDCFG: 'ccinfo',(list of supported s),(list of supported s) Write command OK Response BG95&BG77&BG600L_Series_Voice_Application_Note 32 / 43 LPWA Module Series AT+QINDCFG=[,[,]] If the optional parameters are omitted, query the current configuration: +QINDCFG: , OK If the optional parameters are specified, configure the URC indication: OK Or ERROR Maximum Response Time Characteristics If there is any error related to ME functionality: +CME ERROR: 300 ms The command takes effect immediately. determines whether the configuration is saved. Parameter String type. URC type. 'all' Main switch of all URCs. default value is 1 (ON). 'csq' Indication of signal strength and signal channel bit error rate change. default value is 0 (OFF). If it is 1, +QIND: 'csq',, is reported. 'smsfull' Indication of full SMS storage. default value is 0. If it is 0, +QIND: 'smsfull', is reported. 'ring' Indication of 'RING'. default value is 1. 'smsincoming' Indication of Incoming message. default value is 1. Related URCs include +CMTI, +CMT, +CDS. 'ccinfo' Indication of voice call state change. default value is 0. If it is 1, the URC indication is enabled and +QIND: 'ccinfo',,,,,, ,[,] is reported (see Chapter 4.6 for details about the parameters). Integer type. URC indication is ON or OFF. 0 OFF 1 ON Integer type. Whether to save the configuration into NVRAM. 0 Not save 1 Save BG95&BG77&BG600L_Series_Voice_Application_Note 33 / 43 Example AT+QINDCFG=? +QINDCFG: 'all',(0,1),(0,1) +QINDCFG: 'csq',(0,1),(0,1) +QINDCFG: 'smsfull',(0,1),(0,1) +QINDCFG: 'ring',(0,1),(0,1) +QINDCFG: 'smsincoming',(0,1),(0,1) +QINDCFG: 'ccinfo',(0,1),(0,1) OK AT+QINDCFG='ring',0 OK AT+QINDCFG='ccinfo',1 OK //Disable RING URC report. //Enable ccinfo URC report. LPWA Module Series BG95&BG77&BG600L_Series_Voice_Application_Note 34 / 43 LPWA Module Series 5 Description of URCs 5.1. RING URC The RING URC indicates an incoming call signal from network. RING URC RING An incoming call. 5.2. Alert URC When you make a call by executing ATD, there will be a RING URC in the remote terminal. In the local terminal, we can get an Alert URC returned instead of RBT (RING BACK TONE). Alert URC +ALERTING: ,, Peer side is ringing. Parameter Integer type. Call ID. Call identification number as described in 3GPP TS 22.030. String type. Phone number. Integer type. Type of phone number. 129 Unknown type 145 International type (contains character '+') 161 National type Example ATD505010000000045; //Dial a number. OK //Alert URC +ALERTING: 3,505010000000045,129 //Peer side is ringing. ATH OK BG95&BG77&BG600L_Series_Voice_Application_Note 35 / 43 LPWA Module Series 6 Issue Analysis If an outgoing call fails, check whether the wrong number is dialed first, and then check whether IMS is registered successfully. If the two mentioned preconditions are correct, further analyze the phonetic problems. Before analyzing, make certain the direction that whether it is an uplink problem or a downlink problem. After identifying the direction, pinpoint the type of the problem, such as intermittence, noise, silence, howling, etc. TX VOC Uplink Path ADC Microphone Downlink Path DAC Codec (Control Volume, Audio Stream Path) Module ADSP (Control Volume, Echo Cancellation, Noise Suppression, Mixer by acdb File) Speaker RX VOC Network Figure 3: Voice Flow Factors Affecting Voice Quality: ⚫ Network condition: if the test is conducted in a weak-signal area. ⚫ Channel condition: if the test is conducted in a fading/poor channel or if the channel condition results in CRC errors. ⚫ ADSP processing: if ADSP parameters are set wrongly. ⚫ Packet loss/miss: if the packet is lost in the network or the packet is missed in the system. ⚫ Codec: if an incorrect codec type is selected or a wrong registration parameter (see AT+QDAI, AT+QIIC and 3GPP TS 26.103) is configured. ⚫ PCM interface: if unsuitable parameters (see AT+QPCMCFG) with a selected codec are configured. NOTE BG95 series, BG77 and BG600L-M3 modules do not support adjusting ADSP parameters in real time BG95&BG77&BG600L_Series_Voice_Application_Note 36 / 43 by AT command. LPWA Module Series 6.1. Direction-Related Problem Analysis Making it clear whether the problem occurred on the uplink or downlink side, on the home side or peer side, is the key step to solving the problem. Uplink: If the TX VOC itself has any problem, there is no need to analyze the problem from the perspective of the protocol. If the TX VOC sounds good but the downlink sounds bad on the other end, it is necessary to capture the logs on both sides of the calling and called parties. This scenario can be regarded as the most complex one because there may be a problem with the callee on the remote party, or may be a problem with the local caller. Therefore, we need to compare the logs of both sides and analyze the logs together. Downlink: If the RX VOC itself sounds good but the subsequent PCM sounds bad, there is no need to analyze the problem from the perspective of the protocol. You only need to check whether the Codec and PCM are configured correctly. The RX VOC problem is the most common voice problem. Generally, it is necessary to start from the access layer and make a comprehensive analysis based on the current network coverage, wireless environment, signal-to-noise ratio, bit error rate and other factors. In fact, the vast majority of such problems are caused by poor network coverage. NOTE Be careful when capturing logs. First, select a dedicated audio log mask to capture the log before calling. Then, keep talking for about a minute. Last, hang up. 6.2. Protocol-Related Problem Analysis Voice analysis of common protocols is point-to-point analysis. That is, the time point at which the voice is faulty must be determined in the voice file generated by playback. By observing SNR and RSRP methods to measure the wireless environment at that time. When RSRP is lower than -95 dBm, the wireless environment is considered to be average, and when RSRP is lower than -105 dBm, the wireless environment is considered to be very poor. RxQual represents a bit error rate level, which is a very valid statistic for SNR. Generally, if RxQual is greater than 4 or CRC is 'Fail', or SNR is less than 0, it is difficult to ensure the voice quality. BG95&BG77&BG600L_Series_Voice_Application_Note 37 / 43 LPWA Module Series 6.2.1. VoLTE Issue Analysis From the image below, we can see that the current network condition is very poor because RSRP is less than -105 dBm, which may affect voice quality. Generally, it is not ideal for users to dial in the circumstance. Figure 4: Poor Network Condition in VoLTE 6.2.2. CS-Voice over GSM Issue Analysis From the images below, we can see that RxQual is 7 (greater than 4) in Figure 5 and CRC is 'Fail' in Figure 6. All these data represent the poor channel condition under GSM network, under which circumstances users may hear discontinuous sounds when making a call. BG95&BG77&BG600L_Series_Voice_Application_Note 38 / 43 LPWA Module Series Figure 5: Poor Channel Condition in CS-Voice (1) Figure 6: Poor Channel Condition in CS-Voice (2) BG95&BG77&BG600L_Series_Voice_Application_Note 39 / 43 LPWA Module Series 7 Appendix A References Table 3: Related Document Document Name [1] Quectel_BG95&BG77&BG600L_Series_AT_Commands_Manual Table 4: Terms and Abbreviations Abbreviation ADSP AMR-NB AMR-WB CLIR COLP CRC CSFB DAN DTMF EVS E-UTRA(N) G.711 IMS IPsec IWLAN Description Audio Digital Signal Processor Adaptive Multi-rate Narrow Band Adaptive Multi-rate Wide Band Calling Line Identification Restriction Connected Line Identification Presentation Cyclic Redundancy Check Circuit Switched Fallback Domain Availability Notification Dual-tone multi-frequency Enhance Voice Services Evolved Universal Terrestrial Radio Access (Network) ITU-T Standard Pulse Code Modulation (PCM) of Voice Frequencies IP Multimedia Subsystem Internet Protocol Security Industrial Wireless LAN BG95&BG77&BG600L_Series_Voice_Application_Note 40 / 43 MO MSC MT MWI PDN PCM QCI QoS RAT RCS ROHC RTP RTT SDP SMS SIP SRVCC TTY UDP VICE VoLTE LPWA Module Series Mobile Originated Mobile-services Switching Centre Mobile Terminated Message Waiting Indicator Packet Data Network Pulse Code Modulation QoS Class Identifier Quality of Service Radio Access Technology Rich Communication Suite Robust Header Compression Real-time Transport Protocol Real-Time Text Session Description Protocol Short Message Service Session Initiation Protocol Single Radio Voice Call Continuity Teletypewriter User Datagram Protocol VoLTE for Internet-connected Endpoint Voice over LTE BG95&BG77&BG600L_Series_Voice_Application_Note 41 / 43 LPWA Module Series 8 Appendix B Summary of CME ERROR Codes Final result code +CME ERROR: indicates an error related to mobile equipment or network. The operation of +CME ERROR: final result code is similar to the regular ERROR result code: if +CME ERROR: is the result code for any of the commands in a command line, none of the following commands in the same command line is executed (neither ERROR nor OK result code shall be returned as a result of a completed command line execution). The format of can be either numeric or verbose. This is set with AT+CMEE. The following table lists most of general and GRPS related ERROR codes. For some GSM protocol failure cause described in GSM specifications, the corresponding ERROR codes are not included. Table 5: Different Coding Schemes of +CME ERROR: Code of 0 1 2 3 4 5 6 7 10 11 12 Meaning Phone failure No connection to phone Phone-adaptor link reserved Operation not allowed Operation not supported PH-SIM PIN required PH-FSIM PIN required PH-FSIM PUK required (U)SIM not inserted (U)SIM PIN required (U)SIM PUK required BG95&BG77&BG600L_Series_Voice_Application_Note 42 / 43 LPWA Module Series 13 (U)SIM failure 14 (U)SIM busy 15 (U)SIM wrong 16 Incorrect password 17 (U)SIM PIN2 required 18 (U)SIM PUK2 required 20 Memory full 21 Invalid index 22 Not found 23 Memory failure 24 Text string too long 25 Invalid characters in text string 26 Dial string too long 27 Invalid characters in dial string 30 No network service 31 Network timeout 32 Network not allowed - emergency calls only 40 Network personalization PIN required 41 Network personalization PUK required 42 Network subset personalization PIN required 43 Network subset personalization PUK required 44 Service provider personalization PIN required 45 Service provider personalization PUK required 46 Corporate personalization PIN required 47 Corporate personalization PUK required BG95&BG77&BG600L_Series_Voice_Application_Note 43 / 43
602.39 KB
BG77xA-GL&BG95xA-GL LwM2M Application Note LPWA Module Series Version: 1.0 Date: 2022-09-09 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 1 / 45 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 2 / 45 LPWA Module Series About the Document Revision History Version Date Author - 2020-11-05 Vladan RAKIC 1.0 2022-09-09 Vladan RAKIC Description Creation of the document First official release BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 3 / 45 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 1.1. Applicable Modules .................................................................................................................... 7 1.2. Special Mark .............................................................................................................................. 8 2 General Overview of LwM2M ............................................................................................................. 9 2.1. LwM2M Interfaces...................................................................................................................... 9 2.1.1. Bootstrap Interface .......................................................................................................... 9 2.1.2. Client Registration Interface.......................................................................................... 10 2.1.3. Device Management and Service Enablement Interface ............................................. 11 2.1.4. Information Reporting Interface..................................................................................... 12 2.2. LwM2M Objects ....................................................................................................................... 13 2.3. IPv6 to IPv4 Fallback Mechanism............................................................................................ 14 2.4. LwM2M and PSM..................................................................................................................... 14 2.5. File Provisioning and Configuration ......................................................................................... 15 2.5.1. Configuration and Script Files* ..................................................................................... 15 2.5.2. Security Mode (DTLS)................................................................................................... 22 3 LwM2M AT Commands..................................................................................................................... 24 3.1. AT Command Introduction ....................................................................................................... 24 3.1.1. Definitions...................................................................................................................... 24 3.1.2. AT Command Syntax .................................................................................................... 24 3.2. Declaration of AT Command Examples................................................................................... 25 3.3. Description of LwM2M AT Commands .................................................................................... 25 3.3.1. AT+QLWCFG Configure LwM2M Client .................................................................... 25 3.3.2. AT+QLWSVC Manage LwM2M Session ................................................................... 33 3.4. Description of LwM2M URCs................................................................................................... 36 3.4.1. +QLWURC: 'event' LwM2M Client State Change Notification.................................. 36 3.4.2. +QLWURC: 'observe' Observe Request Indication .................................................. 37 3.4.3. +QLWURC: 'uldata' Application Data Delivery Result Notification ........................... 38 3.4.4. +QLWURC: 'recv' Incoming Data Indication ............................................................. 39 4 Examples ........................................................................................................................................... 40 4.1. Configure LwM2M Client with Provisioning Profiles*............................................................... 40 4.2. Configure LwM2M Client with AT Command........................................................................... 41 4.2.1. Configure in Client-Initiated Bootstrap Mode ................................................................ 41 4.2.2. Configure in Factory Bootstrap Mode ........................................................................... 42 5 Appendix References ....................................................................................................................... 44 BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 4 / 45 LPWA Module Series Table Index Table 1: Applicable Modules ........................................................................................................................ 7 Table 2: Special Mark................................................................................................................................... 8 Table 3: Configuration and Script Files of LwM2M Client.......................................................................... 15 Table 4: bootstrap.ini Format ..................................................................................................................... 15 Table 5: carrier_apn_cfg Items .................................................................................................................. 18 Table 6: lwm2m_cfg Items ......................................................................................................................... 19 Table 7: Types of AT Commands .............................................................................................................. 24 Table 8: Arguments ................................................................................................................... 32 Table 9: and Arguments ........................................................................... 32 Table 10: and Arguments............................................................................ 36 Table 11: Terms and Abbreviations ........................................................................................................... 44 BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 5 / 45 LPWA Module Series Figure Index Figure 1: Operation Model for Client-Initiated Bootstrap Interface ............................................................ 10 Figure 2: Example Flow for Client Registration Interface .......................................................................... 11 Figure 3: Example Flow of Device Management and Service Enablement Interface ............................... 12 Figure 4: Example Flow of Information Reporting Interface ...................................................................... 13 BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 6 / 45 LPWA Module Series 1 Introduction With the rise of the Internet of Things, more and more terminal devices are being connected to the Internet, making the device management and upgrade requirements increasingly urgent. This industry challenge has been addressed with Open Mobile Alliance (OMA) Lightweight M2M (LwM2M) protocol. LwM2M supports some features that help vendors manage their devices, update firmware, and control devices remotely, etc. Since IoT devices for embedded terminals are often very resource-constrained, without UI, and come with limited computing and network communication capabilities, the main motivation for LwM2M was to define a set of lightweight protocols for a variety of IoT devices. In addition, due to the huge number of IoT terminals, saving network resources has become increasingly important. This document explains OMA LwM2M protocol, the architecture of LwM2M feature and how to use it on Quectel BG77xA-GL and BG95xA-GL modules. 1.1. Applicable Modules Table 1: Applicable Modules Module Family BG77xA-GL BG95xA-GL Model BG770A-GL BG773A-GL BG950A-GL BG951A-GL BG953A-GL BG955A-GL BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 7 / 45 1.2. Special Mark LPWA Module Series Table 2: Special Mark Mark * Definition Unless otherwise specified, an asterisk (*) after a function, feature, interface, pin name, AT command, or argument, indicates that the function, feature, interface, pin, AT command, or argument is under development and currently not supported; and the asterisk (*) after a model indicates that the sample of such model is currently unavailable. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 8 / 45 LPWA Module Series 2 General Overview of LwM2M OMA LwM2M is the application layer communication protocol between an LwM2M Server and an LwM2M Client, located in an LwM2M device. The OMA LwM2M enabler includes device management and service enablement for LwM2M devices. The modules provide the LwM2M Client on APPS. The LwM2M Client is compliant with OMA specifications and supports the following interfaces: ⚫ Bootstrap ⚫ Client Registration ⚫ Device Management and Service Enablement ⚫ Information Reporting . 2.1. LwM2M Interfaces 2.1.1. Bootstrap Interface Bootstrap Interface is used to provision LwM2M Client with essential information to enable it to perform the 'Register' operation with one or more LwM2M Servers. ⚫ Bootstrap Modes LwM2M enabler supports four bootstrap modes: Factory Bootstrap, Bootstrap from Smartcard, ClientInitiated Bootstrap and Server-Initiated Bootstrap. The LwM2M Client must support at least one bootstrap mode specified in the Bootstrap Interface. The modules support two bootstrap modes: Factory Bootstrap and Client-Initiated Bootstrap. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 9 / 45 LPWA Module Series LwM2M Client Bootstrap Request LwM2M Bootstrap Server Write/Read/Discover/Delete Bootstrap Finish Figure 1: Operation Model for Client-Initiated Bootstrap Interface ⚫ Server and Access Control Configurations Information about LwM2M bootstrap server or other standard servers, and the access right for performing an operation for these LwM2M Servers. 2.1.2. Client Registration Interface Client Registration Interface is used by an LwM2M Client to register on one or more LwM2M Servers, maintain each registration, and de-register from an LwM2M Server. ⚫ Registration When registering, the LwM2M Client performs the 'Register' operation and provides the properties the LwM2M Server requires to contact the LwM2M Client (e.g., End Point Name); maintain the registration and session (e.g., lifetime, Queue Mode) between the LwM2M Client and LwM2M Server, as well as the knowledge of the Objects supported by LwM2M Client and existing Object Instances in the LwM2M Client. The registration is in soft state, with the lifetime indicated by the Lifetime Resource of LwM2M Server Object Instance. ⚫ Update The LwM2M Client periodically updates its registration information with the registered LwM2M Server(s) by performing the 'Update' operation. If the lifetime of a registration with an LwM2M Server expires without an update from the LwM2M Client, the LwM2M Server removes the registration of that Client. The LwM2M Client performs the 'Update' operation at an interval equal to the registration lifetime (as per Resource /1/x/1 value). BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 10 / 45 LPWA Module Series ⚫ De-registration When shutting down or discontinuing the use of a LwM2M Server, the LwM2M Client performs a 'Deregister' operation. The Binding Resource of the LwM2M Server Object informs the LwM2M Client of the transport protocol preferences of the LwM2M Server for the communication session between the LwM2M Client and LwM2M Server. The LwM2M Client should perform the operations in the modes indicated by the Binding Resource of the LwM2M Server Object Instance. LwM2M Client Register ep=node1 ,, 2.01 Created LwM2M Server Update 2.04 Changed De-register 2.02 Deleted Figure 2: Example Flow for Client Registration Interface 2.1.3. Device Management and Service Enablement Interface Device Management and Service Enablement is a very important interface in LwM2M. ⚫ The interface is used by the LwM2M Server to access Object Instances and Resources available from a registered LwM2M Client. ⚫ The interface provides this access through 'Create', 'Read', 'Write', 'Delete', 'Execute', 'Write Attributes', or 'Discover' operations. ⚫ The operations supported by Resource are defined in the Object definition using the Object Template. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 11 / 45 LPWA Module Series Example flow of Device Management and Service Enablement Interface is presented below: LwM2M Client LwM2M Server Read /3/0/0 Success Open Mobile Alliance Write /3/0/1 Lightweight M2M Client Success Execute /3/0/4 Success LwM2M Client LwM2M Server Create /2 Success-Location: /2/3 Write /2 Success-Location: /2/4 Delete /2/3 Success Figure 3: Example Flow of Device Management and Service Enablement Interface 2.1.4. Information Reporting Interface The Information Reporting Interface is used by an LwM2M Server to observe any changes in a Resource on a registered LwM2M Client, and to receive notifications when new values are available. ⚫ This observation relationship is initiated by sending an 'Observe' operation to the LwM2M Client for an Object, an Object Instance, or a Resource. ⚫ An observation ends when a 'Cancel Observation' operation is performed. LwM2M Client supports observation and notification of objects, object instances and resources. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 12 / 45 LPWA Module Series LwM2M Client Get /4/0/2 Observe 2.05 Content Observe …3.0.. Notify 28 Notify 31 Cancel Observation LwM2M Server Figure 4: Example Flow of Information Reporting Interface 2.2. LwM2M Objects The LwM2M Client of the modules implements the following objects and handles the server requests for them: ⚫ Security object ⚫ Server object ⚫ Access control object ⚫ Device object ⚫ Connectivity monitoring object ⚫ Location object ⚫ Connectivity statistics object ⚫ APN connection profile ⚫ Cellular connectivity ⚫ Firmware update object ⚫ Software management object* ⚫ Device capability management object The information received for these objects is sent to other registered applications, such as firmware overthe-air (FOTA), which implements these objects and monitors them with LwM2M API. For example, the LwM2M Client receives a request for an 'execute update' on a firmware update object. The LwM2M Client passes the request to the FOTA application registered to receive events. When the FOTA application receives the 'execute update' message, it processes and applies the image and sends the result to the LwM2M Client to forward it to the LwM2M Server. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 13 / 45 LPWA Module Series 2.3. IPv6 to IPv4 Fallback Mechanism If IPv4v6 is selected as the IP family: ⚫ An IPv6 call is brought up first. ⚫ If the IPv6 call is not brought up even after all data call retries, then the LwM2M Client only attempts to bring up an IPv4 call. If the module is given both IPv4 and IPv6 addresses: ⚫ The module first uses the IPv6 address to connect to the LwM2M Server. ⚫ If the LwM2M Server is unreachable with the IPv6 address, the module falls back to the IPv4 address and tries to connect to the LwM2M Server. 2.4. LwM2M and PSM ⚫ LwM2M Client Behavior The LwM2M Client must send a 'registration update' to the LwM2M Server before the lifetime registration expires per the OMA specification. With the PSM enabled, the modules periodically enter deep sleep and wake up only after the PSM timer expires. During deep sleep, the LwM2M Client is shut down and cannot send the 'registration update' to the server, resulting in the loss of LwM2M Client’s registration with the server. ⚫ How to Keep LwM2M Client Registered?* Enable the REG_UPDATE_ON_RECONNECT option (see Chapter 0) for the LwM2M Client to send a 'registration update' to the server every time the module wakes up from PSM. Enabling this feature ensures that the LwM2M Client does not lose its registration with the server. NOTE Currently the modules only support enabling LwM2M PSM feature by provisioning profiles (see Chapter 2.5). BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 14 / 45 LPWA Module Series 2.5. File Provisioning and Configuration 2.5.1. Configuration and Script Files* The LwM2M Client has three configuration files that can be used to control its behavior, and one script for auto starting the LwM2M Client. The four files are listed in the table below. Table 3: Configuration and Script Files of LwM2M Client Filename bootstrap.ini carrier_apn_cfg lwm2m_app_autostart lwm2m_cfg Description • Used as factory bootstrap to discover the bootstrap server or other servers. • Bootstrap server details for client-initiated bootstrap. • Can be used to instantiate multiple instances of objects (Security, Server, ACL). Contains APN information for connecting to servers. An empty file; the presence of this file indicates that the LwM2M Client can start automatically. Contains LwM2M options to control features such as registration retry. NOTE If the above configuration files are preloaded to the /datatx directory of the modules, the LwM2M Client starts up automatically after module reboots. 2.5.1.1. bootstrap.ini bootstrap.ini contains the object information required for bootstrapping. The object information is in JSON format defined in the OMA specification. Table 4: bootstrap.ini Format Attributes JSON Variable Base Name bn Base Time bt Mandatory Description Base name string prepended to the Name value of No the entry for forming a unique identifier for resource. No Base time which the Time values are relative to. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 15 / 45 LPWA Module Series Resource Array e Array Parameters Name n Time t Float v Value Boolean bv Value ObjectLink ov Value String sv Value Yes No No One value field is mandatory Resource list as JSON value array according to [SenML] with Array parameter extension (Object Link). Name value is prepended by the Base Name value to form the resource instance name. The resulting name uniquely identifies the Resource Instance. Example: • If Base Name is '/', the Array entry Name of the Resource is {Object}/{Object Instance}/{Resource}/{Resource Instance} • When Base Name is not present, the Array entry Name is the full URI of the requested Resource Instance Representation time relative to the Base Time in seconds for a notification. Required only for historical representations. Value as a JSON float if the Resource data type is Integer, Float, or Time. Value as a JSON Boolean if the Resource data type is Boolean. Value as a JSON string if the Resource data type is ObjectLink Format (e.g., '10:03'). Value as a JSON string for all other Resource data types. If the Resource data type is opaque the string value holds the Base64 encoded representation of the Resource. The following is an example of a bootstrap.ini file containing security, server, and access control objects, specific to OMA 1.0 servers: {'bn':'/0/0/', 'e':[ {'n':'0','sv':'coaps://10.230.20.192:1111'}, {'n':'1','bv':true}, {'n':'2','v':0}, {'n':'10','v':100 }]} {'bn':'/0/1/', 'e':[ {'n':'1','bv':false}, {'n':'2','v':3}, {'n':'10','v':102 }]} BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 16 / 45 LPWA Module Series {'bn':'/1/1/', 'e':[ {'n':'0','v':102}, {'n':'1','v':50000}, {'n':'2','v':1}, {'n':'3','v':60}, {'n':'5','v':86400}, {'n':'6','bv':true}, {'n':'7','sv':'UQS' }]} {'bn':'/2/0', 'e':[ {'n':'0','v':1}, {'n':'1','v':2}, {'n':'2/102','v':15}, {'n':'3','v':102 }]} The following is an example of a bootstrap.ini file containing security, server, and access control objects, specific to OMA 1.1 servers: {'bn':'/0/0/', 'e':[ {'n':'0','sv':'coap://2002:c023:9c17:c007:5443:ff62:a1f5:2c:5683'}, {'n':'1','bv':true}, {'n':'2','v':0}, {'n':'10','v':100 }]} {'bn':'/0/1/', 'e':[ {'n':'1','bv':false}, {'n':'2','v':3}, {'n':'10','v':102 }]} {'bn':'/1/1/', 'e':[ {'n':'0','v':102}, {'n':'1','v':50000}, {'n':'2','v':1}, {'n':'3','v':60}, {'n':'5','v':86400}, {'n':'6','bv':true}, {'n':'7','sv':'UN'}, {'n':'10','ov':'11:65533'}, {'n':'22','sv':'U' BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 17 / 45 }]} {'bn':'/2/0', 'e':[ {'n':'0','v':1}, {'n':'1','v':2}, {'n':'2/102','v':15}, {'n':'3','v':102 }]} LPWA Module Series 2.5.1.2. carrier_apn_cfg carrier_apn_cfg includes details about the carrier-specific APN used for each server. Table 5: carrier_apn_cfg Items Parameter Default Value APN_NAME - APN_CLASS 2 SHORT_SERVER_ID1 102 BS_IF_REG_FAILS 0 IP_FAMILY BINDINGS v4 ip_nonip Description APN to be used for the server with SHORT_SERVER_ID1. APN class associated with the APN. Short server ID associated with the APN. If set to 0, LwM2M Client will not perform bootstrapping on registration failure for this SSID. If set to 1, LwM2M Client will perform bootstrapping on registration failure for this SSID. Supported values: v4, v6 and v4v6. This is the IP family chosen to connect to the server. Supported values: ip, nonip and ip_nonip. This is the binding type to be chosen to specify whether the LwM2M Client can communicate over IP or non-IP. To successfully register to the network and activate the PDN connection, the corresponding APN should be configured according to the current network. Add a semicolon after the existing APN configuration, and then add the new APN configuration in the next line, as shown below: APN_NAME=carrier_apn1 APN_CLASS=2 BS_IF_REG_FAILS=1 IP_FAMILY=v4 BINDINGS=ip_nonip SHORT_SERVER_ID1=102 ; BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 18 / 45 APN_NAME=carrier_apn2 APN_CLASS=3 BS_IF_REG_FAILS=0 IP_FAMILY=v4 BINDINGS=ip_nonip SHORT_SERVER_ID1=103 ; LPWA Module Series 2.5.1.3. lwm2m_cfg lwm2m_cfg is a LwM2M Client configuration file containing the following configuration information: Table 6: lwm2m_cfg Items Parameter APN IP_FAMILY BINDINGS RETRY_TIMEOUT RETRY_EXPONENT_VAL MAX_RETRY_TIMEOUT MAX_NO_RETRIES ACK_TIMEOUT REG_RETRY_TIMEOUT REG_RETRY_EXPONENT Default Value Description v4 ip_nonip 30 2 640 5 60 60 2 Default APN to be used if carrier_apn_cfg is not available. Supported values: v4, v6, and v4v6. This is the default IP family chosen to connect to the server if the IP family is not mentioned in carrier_apn_cfg. Supported values: ip, nonip and ip_nonip. This is the binding type to be chosen to specify whether the LwM2M Client can communicate over IP or non-IP. Initial timeout (in seconds) to retry a data call in case of data call failure. Value by which the data-call retry timeout must be increased exponentially. Maximum amount of time (in seconds) for a data call retry. Maximum number of retry attempts in case of data call failure. Sleep-ACK timeout (in seconds). If there is no activity during the period, the module goes to sleep. Initial timeout (in seconds) for registration retry in case of registration failure. Value by which the registration retry timeout must be increased exponentially. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 19 / 45 REG_RETRY_MAXTIMEOUT 480 REG_UPDATE_ON_RECONNECT 0 ROAMING_FEAT 1 PER_REGSTATUS_FEAT 0 PER_BOOTSTRAP_FEAT 1 BATTERY_LEVEL_THRESHOLD 20 CARRIER_TYPE 0 REG_EP_NAME 4 BOOTSTRAP_EP_NAME 7 LPWA Module Series Maximum amount of time (in seconds) for a registration retry in case of registration failure. Determines whether a registration update must be sent on reconnection, such as during reboot with persistence-enabled or when IP address changes: • When set to 1, registration update is sent on reconnection. • When set to 0, registration update is not sent on reconnection. Determines LwM2M functionality enablement in roaming: • When set to 1, LwM2M functionality is disabled in roaming. • When set to 0, LwM2M functionality is enabled in roaming. Determines registration persistence across LwM2M Client reboots: • When set to 1, registration persistence is enabled across LwM2M Client reboots. • When set to 0, registration persistence is disabled across LwM2M Client reboots. Determines bootstrap persistence across LwM2M Client reboots. • When set to 1, bootstrap persistence is enabled across LwM2M Client reboots. • When set to 0, bootstrap persistence is disabled across reboots in the LwM2M Client. Battery level less than the threshold mentioned in this configuration value would be considered low battery by the client. Enables carrier-specific functionality in the client: 0 Default 1 Verizon EP name to be used during registration. See OMA specification Section 6.3.1 Endpoint Client Name for more details. Supported values: 4 IMEI URN 7 IMEI MSISDN URN EP name to be used during bootstrap. See OMA specification Section 6.3.1 Endpoint Client Name for more details. Supported values: BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 20 / 45 BOOT_UP_SLEEP_TIME 5 GPS_MIN_INTERVAL 3000 GPS_MIN_DISTANCE MAX_NO_OF_ FACTORY_RESET_ PER_HOUR_BY_SMS MAX_NO_OF_ REG_UPDATE_ PER_HOUR_BY_SMS WAIT_TIME_TO_ TRIGGER_NEXT_ REG_CYCLE 1 1 1 86400 MAX_BOOTSTRAP_WAIT_TIME 0 ROOTCA_SUPPORT_MODE 0 SESSION_TIMEOUT 60 ENABLE_PSM 1 AWAKE_AFTER_PMIN 0 STARTUP_MODE 0 LPWA Module Series 4 IMEI URN 7 IMEI MSISDN URN Sleep time before an LwM2M Client operation starts. Interval (in milliseconds) after which GNSS information is fetched periodically. Change in distance (in meters) after which GNSS information is fetched. Number of factory-reset operations per hour allowed by SMS transport. Number of registration update operations per hour allowed by SMS transport. Hold-off time (in seconds) to trigger the next registration on failure of all registration attempts. Hold-off time (in seconds) during which bootstrap procedure is kept on hold, meanwhile extended applications can register objects. Determines whether to use Root CA or domainissued certificate to validate peer certificate (bootstrap server and standard server) 0 Use domain certificate 3 Use Root CA Inactivity period (in seconds) after which resumption should be triggered for the uplink operation. OEMs should configure the value to be the same as network address translation (NAT) timeout. Determines whether LwM2M enables PSM use. 0 Disable 1 Enable Determines whether the device must go to PSM for every Pmin cycle. 0 By default, the module wakes from Pmin till Pmax. 1 Module goes to PSM for every Pmin cycle until Pmax limit. Determines whether the LwM2M is initialized with OEM application. 0 By default, LwM2M initialization is preloaded. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 21 / 45 LPWA Module Series VERSION 1 LwM2M is initialized with AT commands or DAM application. Specifies the OMA specification version on which 1.0 the LwM2M Client is running. The following example provides an overview of the lwm2m_cfg file with the options explained in the table above: { APN=carrier_apn; RETRY_TIMEOUT=30; RETRY_EXPONENT_VAL=2; MAX_RETRY_TIMEOUT=640; MAX_NO_RETRIES=5; ACK_TIMEOUT=30; REG_RETRY_TIMEOUT=60; REG_RETRY_EXPONENT=2; REG_RETRY_MAXTIMEOUT=480; ROAMING_FEAT=1; PER_REGSTATUS_FEAT=0; BATTERY_LEVEL_THRESHOLD=20; CARRIER_TYPE=0; REG_EP_NAME=4; BOOTSTRAP_EP_NAME=7; BOOT_UP_SLEEP_TIME=10; STARTUP_MODE=0; VERSION=1.0; } 2.5.2. Security Mode (DTLS) Validate the following checkpoints when using Pre-Shared Key security mode: ⚫ PSK files corresponding to bootstrap server or standard server must be present in /datatx/ssl. ⚫ Files should be in _server.psk format (e.g., 100_server.psk for bootstrap server). ⚫ Resource 0/x/2 decides the security mode. See Appendix E.1 of OMA specification for potential values. A typical PSK file used by the modules contains the following: ⚫ PSK Identity used in transactions with the LwM2M Server. ⚫ PSK Key used in transactions with the LwM2M Server. An example of credentials required for transactions with the Nokia Motive Bootstrap Server is presented BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 22 / 45 LPWA Module Series below. Bootstrap PSK Identity structure is exactly as shown below: urn:imei-msisdn:- Example: urn:imei-msisdn:004402460030392-2234235569 The PSK Key used with the bootstrap server is defined as SHA2-256 Digest of the com.vzwm2m.com string. PSK Key = SHA2(com.vzwm2m.com) = d6160c2e7c90399ee7d207a22611e3d3a87241b0462976b935341d000a91e747 Therefore, the content of 100_server.psk PSK file for Nokia Motive Bootstrap Server is as follows: |urn:imei-msisdn:004402460030392-2234235569|: d6160c2e7c90399ee7d207a22611e3d3a87241b0462976b935341d000a91e747 NOTE The LwM2M Client accepts any string value as PSK Identity used in a transaction. However, it only accepts hexadecimal value as PSK Key. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 23 / 45 LPWA Module Series 3 LwM2M 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 7: Types of AT Commands Command Type Syntax Description Test Command AT+=? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Read Command AT+? Check the current parameter value of the corresponding command. Write Command AT+=[,[, Set user-definable parameter value. [...]]] Execution Command AT+ Return a specific information parameter or perform a specific action. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 24 / 45 LPWA Module Series 3.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 3.3. Description of LwM2M AT Commands AT commands for configuring and operating an LwM2M Client are introduced in this chapter, whereas a solution for configuring the LwM2M Client with provisioning profiles is provided in Chapter 2.5. 3.3.1. AT+QLWCFG Configure LwM2M Client The command configures the parameters of LwM2M Client before connecting to the LwM2M Server. AT+QLWCFG Configure LwM2M Client Test Command AT+QLWCFG=? Response +QLWCFG: 'autostart',(list of supported s) +QLWCFG: 'pdpcid',(range of supported s),(range of supported s),(list of supported s) +QLWCFG: 'security',(range of supported s),(range of supported s),,(list of supported s),(list of supported s),, +QLWCFG: 'server',(range of supported s),(range of supported s),(range of supported s),(range of supported s),(range of supported s),(list of supported s), +QLWCFG: 'epns',(list of supported s),, +QLWCFG: 'transcfg',(range of supported s),(range of supported s),(range of supported s) +QLWCFG: 'version',(list of supported s) +QLWCFG: 'select',(range of supported BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 25 / 45 LPWA Module Series s),(list of supported s) +QLWCFG: 'host',(list of supported s),(range of supported s), +QLWCFG: 'device',,,,,, +QLWCFG: 'session',(range of supported s), (range of supported s) +QLWCFG: 'mbsps',,,,,, OK Write Command Response Query/set the startup mode of LwM2M If the optional parameter is omitted, query the current setting. Client. +QLWCFG: 'autostart', AT+QLWCFG='autostart'[,] OK Write Command Query/set the APN profile for LwM2M data connection. AT+QLWCFG='pdpcid'[,,[,]] If the optional parameter is specified, set the startup mode of LwM2M Client. OK Or ERROR Response If the optional parameters are omitted, query the current setting. +QLWCFG: 'pdpcid',,, OK If any of the optional parameters is specified, set the APN profile for LwM2M data connection. OK Or ERROR Write Command Response Query/set the resources of LwM2M If the optional parameters are omitted, query the current setting. security object. +QLWCFG: 'security',,,<server_a AT+QLWCFG='security'[,,, dex>[,,,,[,,]]] If only is specified and all other optional parameters are omitted, delete the property data of the specified . BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 26 / 45 LPWA Module Series OK Write Command Query/set the resources of LwM2M Server object. AT+QLWCFG='server'[,[,,,,,,]] If is specified and any of the other optional parameters is specified, set the specified server property. OK Or ERROR Response If the optional parameters are omitted, query the current setting. +QLWCFG: 'server',,,,,,, OK If only is specified and all other optional parameters are omitted, delete the LwM2M Server attributes of the specified . OK If is specified and any of the other optional parameters is specified, set the LwM2M Server attributes. OK Or ERROR Write Command Response Query/set the endpoint name that If the optional parameters are omitted, query the current setting. identifies the LwM2M Client on one +QLWCFG: 'epns',,, LwM2M Server. AT+QLWCFG='epns'[,,,] If the optional parameters are specified, set the endpoint name. OK Or ERROR Write Command Response Query/set the parameters for bootstrap If the optional parameters are omitted, query the current setting. or registration retry mechanism. +QLWCFG: 'transcfg',,, AT+QLWCFG='transcfg'[,<retry_ti meout>,,] OK If the optional parameters are specified, set the parameters for bootstrap and registration retry mechanism. OK BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 27 / 45 LPWA Module Series Or ERROR Write Command Response Query/set the version of LwM2M If the optional parameter is omitted, query the current setting. Client. +QLWCFG: 'version', AT+QLWCFG='version'[,] OK Write Command Query/set the built-in LwM2M Server information, depending on the specified server type. AT+QLWCFG='select'[,[,]] Write Command Query/set the resource of portfolio object. AT+QLWCFG='host', [,[,]] If the optional parameter is specified, set the version of LwM2M Client. OK Or ERROR Response If the optional parameters are omitted, query the current setting. +QLWCFG: 'select',, OK If any of the optional parameters is specified, set the built-in LwM2M Server information. OK Or ERROR Response If the optional parameters are omitted, query the current setting of the specified . If only is omitted, query the current setting of specified and . [+QLWCFG: 'host',,, [+QLWCFG: 'host',,, [...]]] OK Write Command Query/set the resource of device object. AT+QLWCFG='device'[,<manufact If the optional parameters are specified, set the resource of portfolio object. OK Or ERROR Response If the optional parameters are omitted, query the current setting. +QLWCFG: 'device',,,,,, BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 28 / 45 LPWA Module Series urer>,,,< sw_version>,,] Write Command Query/set the session lifetime. AT+QLWCFG='session'[, ,] OK If the optional parameters are specified, set the resource of device object. OK Or ERROR Response If the optional parameters are omitted, query the current setting. +QLWCFG: 'session',, OK Write Command Query/set the value of parameters required for LG U+ LwM2M Server authentication. AT+QLWCFG='mbsps'[,,,,,< model>,] If the optional parameters are specified, set the session lifetime. OK Or ERROR Response If the optional parameters are omitted, query the current setting. +QLWCFG: 'mbsps',,,,,, OK If the optional parameters are specified, set the value of parameters required for LG U+ LwM2M Server authentication. OK Or ERROR Maximum Response Time 300 ms Characteristics The command takes effect immediately. The configurations are saved automatically. Parameter Integer type. Enable or disable starting LwM2M automatically when the module powers on. 0 Disable 1 Enable Integer type. LwM2M Client identifier. Range: 0–5. Integer type. PDP context ID of LwM2M Client. Range: 1–5. Default value: 1 Integer type. APN class associated with APN. Supported APN classes: 0, 2, 3, 6, BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 29 / 45 LPWA Module Series 7, 10, 11. Default value: 3. Integer type. Unique identifier of LwM2M Server configured for LwM2M Client. Range: 1–65534. String type. LwM2M Server URI. Maximum length: 255 bytes. Integer type. LwM2M Bootstrap Server flag. 0 Standard LwM2M Server 1 LwM2M Bootstrap Server Integer type. Encryption method for UDP payload. 0 Pre-Shared Key mode 2 Certificate mode 3 Non-Secure mode String type. PSK identifier. Only valid when =0. String type. PSK secret key. Only valid when =0. Integer type. Registration lifetime. Range: 0–2147483647. Default value: 0. Unit: second. Integer type. Minimum period of an observation. Range: 0–2147483647. Default value: 0. Unit: second. Integer type. Maximum period of an observation. Range: 0–2147483647. Default value: 0. Unit: second. Integer type. Interval for the next connection after disconnecting from LwM2M Server. Range: 60–2147483647. Default value: 86400. Unit: second. Integer type. LwM2M Client stores 'Notify' operations to LwM2M Server or discards them when LwM2M Server account is disabled or LwM2M Client is offline. 0 LwM2M Client stores 'Notify' operations 1 LwM2M Client discards 'Notify' operations String type. Transport binding mode configured for LwM2M Client. See Table 8. Integer type. Format of endpoint client name. 0 String type - Specify endpoint client name with string format. 1 Integer type - Value of and should be as in Table 9. Endpoint client name for identifying bootstrap server. Format: determined by . See Table 9. Endpoint client name for identifying standard server. Format: determined by . See Table 9. Integer type. Initial timeout value for bootstrap or registration retry upon failure. Range: 0–2147483647. Default value: 60. Unit: second. Integer type. Value by which the timeout for bootstrap or registration retries must be increased exponentially. Range: 0–2147483647. Default value: 2. Integer type. Maximum timeout for all bootstrap or registration retries upon failure. Range: 0–2147483647. Default value: 480. Unit: second. Integer type. LwM2M protocol version. 0 LwM2M protocol version 1.0 1 LwM2M protocol version 1.1 BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 30 / 45 LPWA Module Series Integer type. Built-in LwM2M Server details for network carrier. 0 Factory mode, used to reset all settings of current LwM2M Client 1 Verizon built-in LwM2M Server information 2 AT&T built-in LwM2M Server information 3 T-Mobile built-in LwM2M Server information 4 Telstra built-in LwM2M Server information 5 LG U+ built-in LwM2M Server information 6 NTT DOCOMO built-in LwM2M Server information Integer type. Whether preloaded LwM2M Server details are for commercial use. 0 Staging Server 1 Production Server Integer type. Instance ID of host device. Supported values: 0 and 1. Integer type. Resource ID associated with host device instance. 0 Host device ID 1 Host device manufacturer 2 Host device model number 3 Host device software version String type. Host device information. String type. Device manufacturer. String type. Device model number. String type. Device hardware version. String type. Device software version. String type. Device firmware version. String type. Device type name. Integer type. DTLS session timeout. Range: 0–2147483647. Default value: 0. Unit: second. Integer type. DTLS session resumption timeout. Range: 0–86400. Default value: 86400. Unit: second. String type. Service code. String type. Device IMEI number. String type. MSISDN number. String type. ICCID number. String type. Device model name. String type. Device MAC address. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 31 / 45 LPWA Module Series Table 8: Arguments 'U' 'UQ' 'S' 'SQ' 'US' 'UQS' 'N' Description UDP. LwM2M Server expects LwM2M Client to be accessible via UDP binding at any time. UDP with Queue Mode. LwM2M Server MUST queue all requests to LwM2M Client, and send requests via UDP when the LwM2M Client is on-line. SMS. LwM2M Server expects LwM2M Client to be accessible via SMS binding at any time. SMS with Queue Mode. LwM2M Server MUST queue all requests to LwM2M Client, and send requests via SMS when the LwM2M Client is on-line. UDP and SMS. LwM2M Server expects LwM2M Client to be accessible via UDP binding and SMS binding at any time. UDP with Queue Mode and SMS. LwM2M Server MUST queue all requests to LwM2M Client, and send requests via UDP when the LwM2M Client is on-line. The LwM2M Server expects the LwM2M Client to be accessible via SMS binding at any time. Non-IP. LwM2M Server MUST send requests to LwM2M Client using Non-IP binding. The LwM2M Client MUST send the response to such requests over the Non-IP binding. If =1, the valid values of and are listed in the table below. Table 9: and Arguments / 4 5 6 7 8 9 Description Identify a module using an International Mobile Equipment Identity (see 3GPP TS 23.003). The IMEI URN specifies a valid, 15-digit IMEI. URN format: 'urn:imei:'. Identify a module using an Electronic Serial Number. ESN URN specifies a valid, 8-digit ESN. URN format: 'urn:esn:'. Identify a module using a Mobile Equipment Identifier. MEID URN specifies a valid, 14-digit MEID. URN format: 'urn:meid:'. Identify a module using a combination of International Mobile Equipment Identity (see 3GPP TS 23.003), and MSISDN. Both IMEI and MSISDN are 15 digit numbers. URN format: 'urn:imei-msisdn:-'. Identify a module using a combination of International Mobile Equipment Identity (see 3GPP TS 23.003), and IMSI. Both IMEI and IMSI are 15 digit numbers. URN format: 'urn:imei-imsi:-'. Identify a module using a combination of International Mobile Equipment Identity (see 3GPP TS 23.003), and IMSI. Both IMEI and IMSI are 15 digit numbers. URN BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 32 / 45 format: 'imei-imsi:-'. LPWA Module Series NOTE 1. LwM2M security and server objects must be initialized before starting up LwM2M Client. AT+QLWCFG='security' must be executed before you configure the resource values of LwM2M Server object and parameters of LwM2M data session. 2. Transport binding mode 'N' is only supported under LwM2M protocol version 1.1. 3.3.2. AT+QLWSVC Manage LwM2M Session The command operates a LwM2M Client and manages the flow of LwM2M session. AT+QLWSVC Manage LwM2M Session Test Command AT+QLWSVC=? Response +QLWSVC: 'reg',(list of supported s) +QLWSVC: 'dereg',(list of supported s) +QLWSVC: 'lifetime',(range of supported s),(range of supported s) +QLWSVC: 'update',(range of supported s),(list of supported s) +QLWSVC: 'state',(range of supported s) +QLWSVC: 'uldata',(range of supported s),,(range of supported s),,(list of supported s),(list of supported s) Write Command Initiate registration with LwM2M Server. AT+QLWSVC='reg'[,] OK Response OK +QLWREG: Write Command Deregister a LwM2M Client from the LwM2M Server. AT+QLWSVC='dereg'[,] If there is an error: +CME ERROR: Response OK +QLWDEREG: If there is an error: ERROR BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 33 / 45 LPWA Module Series Write Command Query/update the lifetime of a specific LwM2M Server. AT+QLWSVC='lifetime', [,] Response If the optional parameter is omitted, query the lifetime value of a specific LwM2M Server. +QLWSVC: 'lifetime',, OK If the optional parameter is specified, update the lifetime of a specific LwM2M Server. OK Or ERROR Write Command Response Send a registration update to a If the registration update message is sent successfully: specific LwM2M Server. OK AT+QLWSVC='update', [,] If there is any error: ERROR Write Command Response Query LwM2M Client registration +QLWSVC: 'state',,,,, AT+QLWSVC='state'[,] OK Write Command Response Send application data over LwM2M OK session. AT+QLWSVC='uldata',, If there is any error: ,,[,[,]] Maximum Response Time 300 ms Characteristics / Parameter Integer type. Registration mode. 0 LwM2M Client initiates 'registration' after the module reboots. 1 LwM2M Client initiates 'registration update' after the module reboots. Integer type. Deregistration method. 0 Deregistration 1 Factory reset Integer type. Unique identifier of LwM2M Server configured for LwM2M Client. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 34 / 45 LPWA Module Series Range: 1–65534. Integer type. Registration lifetime. Range: 0–2147483647. Unit: second. Integer type. Whether the current registration update message contains an object list. 0 Send the registration update message with NULL payload. 1 Send the registration update message with object list. Integer type. LwM2M Client identifier. Range: 0–5. String type. LwM2M Server URI. Integer type. LwM2M Bootstrap Server flag. 0 Standard LwM2M Server 1 LwM2M Bootstrap Server Integer type. Registration state code of LwM2M Client. See in Chapter 3.4.1. String type. URI format: ///. Integer type. Application data length. Range: 1–1460. Unit: byte. String type or hexadecimal type. Application data to be sent. Integer type. Application data type. 0 String type. Send application data in string format. 1 Hexadecimal type. Send application data in hexadecimal format. Integer type. Message type of application data to be sent. 0 Confirmable 1 Non-confirmable Integer type. 0 indicates a successful operation. Other values indicate failure. 0 Operation success 1 Operation failure 2 Invalid parameter 3 No memory 4 Failure as another parallel operation started 5 Operation is not allowed Integer type. Error code of AT command operation. 701 Unknown error 702 Command has been executed 703 Invalid parameter 704 LwM2M task is not initiated yet 705 Operation is not allowed 706 No memory NOTE If AT+QLWSVC='lifetime' is executed, a 'registration update' CoAP message containing lifetime value is sent to LwM2M Server. If the module fails to send this CoAP message or receives any response from LwM2M Server, the corresponding event notification in the below format is reported: +QLWURC: 'event',,, BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 35 / 45 See Chapter 3.4.1 for URC details. LPWA Module Series 3.4. Description of LwM2M URCs URCs of LwM2M AT commands are reported to the host when any internal event happens on LwM2M Client, including bootstrapping, registration, observation, and incoming application data. 3.4.1. +QLWURC: 'event' LwM2M Client State Change Notification This URC is reported when the LwM2M Client state changes during bootstrapping or registration; for instance, when the lifetime of a specific LwM2M Server is updated, or when you send a registration update to a specific LwM2M Server. +QLWURC: 'event' LwM2M Client State Change Notification +QLWURC: 'event',,, Parameter Integer type. Unique identifier of the LwM2M Server configured for the LwM2M Client. Range: 0–65534. The value 0 is only used for reporting 'GENERIC_FAILED' and 'FACTORY_RESET' related notifications. Integer type. Current state code of LwM2M Client. See Table 10. String type. Readable string associated with LwM2M Client current state code. See Table 10. Table 10: and Arguments 0 1 2 3 4 Description INITIAL LwM2M Client not registered or bootstrap not started. REG_PENDING Registration pending. REG_READY Registered on LwM2M Server successfully. REG_FAILED UPDATE_PENDING Last registration failed. Registration update pending due to LwM2M Client in sleep state. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 36 / 45 LPWA Module Series LwM2M Client in bootstrap mode due to running hold-off 5 FACTORY_RESET timer. 6 BS_START LwM2M Client initiates a bootstrap request. 7 BS_PENDING Bootstrap ongoing. LwM2M Client is waiting for the pass-through object 8 BS_HOLDOFF initialization to complete and the 'bootstrap request' message has not yet been sent. 9 BS_FINISH Bootstrap finished. 10 BS_FAILED Bootstrap failed. Data call connection retry on failure during registration 11 REG_CONN_RETRY phase. 12 REG_RETRY Registration retry on failure. Data call connection retry on failure during bootstrapping 13 BS_CONN_RETRY phase. 14 BS_RETRY Bootstrap retry on failure. Generic error usually caused by invalid parameters, 15 GENERIC_FAILED populated endpoint name for bootstrap, or failed registration and failed data call start. 16 REG_UPDATE Registration update sent successfully. 17 UPDATE_FAILED Registration update sending failed. 18 DEREG_START Trigger deregistration from LwM2M Server. 19 DEREG_FINISH Deregistered from LwM2M Server successfully. 3.4.2. +QLWURC: 'observe' Observe Request Indication When specific resources are observed by LwM2M Server, this URC is reported. +QLWURC: 'observe' Observe Request Indication +QLWURC: 'observe',,,, BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 37 / 45 LPWA Module Series Parameter Integer type. Unique identifier of the LwM2M Server configured for the LwM2M Client. Range: 1–65534. String type. URI path of Observe operation. URI format: ///. Integer type. Message ID of Observer CoAP message. Integer type. Token ID of Observe CoAP message. Integer type. Observe flag. 0 Observe 1 Cancel Observe 3.4.3. +QLWURC: 'uldata' Application Data Delivery Result Notification When the application data are sent in confirmable message type, this URC is reported after receiving any response from the LwM2M Server. +QLWURC: 'uldata' Application Data Delivery Result Notification +QLWURC: 'uldata',,,,, Parameter Integer type. Unique identifier of the LwM2M Server configured for the LwM2M Client. Range: 1–65534. String type. URI format: ///. Integer type. Message ID of CoAP message. Integer type. Token ID of CoAP message. Integer type. Response code used to indicate the result of application data delivery. 0 Application data with confirmable message type sent successfully -1 Received error response code from server -2 Received NULL response from server -3 Received unsupported or invalid response message from server BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 38 / 45 LPWA Module Series 3.4.4. +QLWURC: 'recv' Incoming Data Indication When the LwM2M Client has received downlink data from the server, this URC is reported. +QLWURC: 'recv' Incoming Data Indication +QLWURC: 'recv',,,, Parameter String type. URI format: ///. Integer type. Content type of incoming downlink data. 4 Resource value type is string. 5 Resource value type is opaque. Integer type. Length of incoming downlink data. Unit: byte. Maximum number of bytes that can be received at a time: 1024. Unit: byte Incoming downlink data. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 39 / 45 LPWA Module Series 4 Examples 4.1. Configure LwM2M Client with Provisioning Profiles* 1) Use bootstrap.ini file to configure LwM2M security object and server object information for Leshan Server. ⚫ Factory Bootstrap (in Non-Secure mode) {'bn':'/0/1/', 'e':[ {'n':'0','sv':'coap://leshan.eclipseprojects.io:5683'}, {'n':'1','bv':false}, {'n':'2','v':3}, {'n':'10','v':102 }]} {'bn':'/1/1/', 'e':[ {'n':'0','v':102}, {'n':'1','v':50000}, {'n':'2','v':1}, {'n':'3','v':60}, {'n':'5','v':86400}, {'n':'6','bv':true}, {'n':'7','sv':'UQS' }]} ⚫ Factory Bootstrap (in Pre-Shared Key mode) {'bn':'/0/1/', 'e':[ {'n':'0','sv':'coaps://leshan.eclipseprojects.io:5684'}, {'n':'1','bv':false}, {'n':'2','v':0}, {'n':'10','v':102 }]} {'bn':'/1/1/', 'e':[ BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 40 / 45 LPWA Module Series {'n':'0','v':102}, {'n':'1','v':50000}, {'n':'2','v':1}, {'n':'3','v':60}, {'n':'5','v':86400}, {'n':'6','bv':true}, {'n':'7','sv':'UQS' }]} An additional PSK key file must be loaded into /datatx/ssl folder in case of Pre-Shared Key mode. 2) Confirm with network carrier and configure proper APN and APN class in carrier_apn_cfg and lwm2m_cfg files. For details, see Chapter 0 and Chapter 0. 3) Put lwm2m_app_autostart auto startup script into /datatx and reboot the module. When the module registers on Leshan Server successfully, the URCs listed below will be reported. +QLWURC: 'event',102,0,'INITIAL' +QLWURC: 'event',102,2,'REG_READY' 4.2. Configure LwM2M Client with AT Command 4.2.1. Configure in Client-Initiated Bootstrap Mode //Configure LwM2M security object in Pre-Shared Key mode. AT+QLWCFG='security',0,111,'coaps://leshan.eclipseprojects.io:5784',1,0,'urn:imei:864475040 090705','313233343536373839' OK //Query the current resource value of LwM2M security object. AT+QLWCFG='security' +QLWCFG: 'security',0,111,'coaps://leshan.eclipseprojects.io:5784',1,0 OK AT+QLWCFG='server',0,60,0,50,60,1,'UQS' OK AT+QLWCFG='server' +QLWCFG: 'server',0,60,0,50,60,1,'UQS' //Configure the LwM2M Server object. OK AT+QLWSVC='reg' //Initiate a bootstrap request to the server. BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 41 / 45 LPWA Module Series OK +QLWREG: 0 +QLWURC: 'event',111,6,'BS_START' +QLWURC: 'event',111,9,'BS_FINISH' +QLWURC: 'event',123,0,'INITIAL' +QLWURC: 'event',123,2,'REG_READY' //The LwM2M Client can execute the following commands only after registering on the server. AT+QLWSVC='lifetime',123,60 //Update registration lifetime to 60 s. OK +QLWURC: 'event',123,16,'REG_UPDATE' AT+QLWSVC='update',123,0 OK //Send 'registration update' message to LwM2M Server. If the module is sleeping, execute this command to wake up the module. +QLWURC: 'event',123,16,'REG_UPDATE' //Modify 'Device Object' information for the host. AT+QLWCFG: 'device','Quectel','BG770A','R1.1','33','BG770AGLAAR01A03','MODEM' OK AT+QLWSVC='dereg' //LwM2M Client is deregistering from LwM2M Server. OK +QLWURC: 'event',123,19,'DEREG_FINISH' //LwM2M Client deregistered from server successfully. +QLWDEREG: 0 4.2.2. Configure in Factory Bootstrap Mode //Configure LwM2M security object in Non-Secure mode. AT+QLWCFG='security',0,100,'coap://leshan.eclipseprojects.io:5683',0,3 OK AT+QLWCFG='server',0,60,0,50,60,1,'UQS' //Configure LwM2M Server object. OK AT+QLWSVC='reg' //Initiate a registration request to the server. OK BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 42 / 45 LPWA Module Series +QLWREG: 0 +QLWURC: 'event',100,0,'INITIAL' +QLWURC: 'event',100,2,'REG_READY' //The LwM2M Client can execute the following commands only after registering on the server. AT+QLWSVC='lifetime',100,60 //Update registration lifetime to 60 s. OK +QLWURC: 'event',100,16,'REG_UPDATE' AT+QLWSVC='update',100,0 OK //Send 'registration update' message to LwM2M Server, If the module is sleeping, execute this command to wake up the module. +QLWURC: 'event',100,16,'REG_UPDATE' AT+QLWSVC='dereg',1 OK //Factory reset. +QLWURC: 'event',0,5,'FACTORY_RESET' +QLWURC: 'event',100,18,'DEREG_START' +QLWURC: 'event',100,19,'DEREG_FINISH' +QLWDEREG: 0 BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 43 / 45 LPWA Module Series 5 Appendix References Table 11: Terms and Abbreviations Abbreviation ACK ACL APN APPS CoAP DAM DTLS EP FOTA GNSS ICCID IMEI IoT IPv4 IPv6 JSON LwM2M MAC Description Acknowledgement Access Control List Access Point Name Application Subsystem Constrained Application Protocol Downloadable Application Module Datagram Transport Layer Security Endpoint Firmware Over-The-Air Global Navigation Satellite System Integrated Circuit Card Identifier International Mobile Equipment Identity Internet of Things Internet Protocol version 4 Internet Protocol version 6 JavaScript Object Notation Lightweight Machine to Machine Medium Access Control BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 44 / 45 MSISDN NAT OEM OMA PDN PDP Pmax Pmin PSK PSM SenML SMS SSID SSL UDP UI URC URI URN LPWA Module Series Mobile Subscriber Integrated Services Digital Network Network Address Translation Original Equipment Manufacturer Open Mobile Alliance Public Data Network Packet Data Protocol Maximum Period Minimum Period Pre-Shared Key Power Saving Mode Sensor Measurement Lists Short Message Service Service Set Identifier Secure Sockets Layer User Datagram Protocol User Interface Unsolicited Result Code Uniform Resource Identifier Uniform Resource Name BG77xA-GL&BG95xA-GL_LwM2M_Application_Note 45 / 45
400.90 KB
BG77xA-GL&BG95xA-GL CoAP Application Note LPWA Module Series Version: 1.0 Date: 2022-09-09 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG77xA-GL&BG95xA-GL_CoAP_Application_Note 1 / 25 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG77xA-GL&BG95xA-GL_CoAP_Application_Note 2 / 25 LPWA Module Series About the Document Revision History Version Date Author Description - 2020-01-10 Nikola BLAZIC Creation of the document 1.0 2022-09-09 Nikola BLAZIC First official release BG77xA-GL&BG95xA-GL_CoAP_Application_Note 3 / 25 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 1.1. Applicable Modules .................................................................................................................... 6 2 General Overview of CoAP ................................................................................................................ 7 3 Description of CoAP 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 CoAP AT Commands ......................................................................................... 9 3.3.1. AT+QCOAPCFG Configure Optional Parameters of CoAP Client .............................. 9 3.3.2. AT+QCOAPOPEN Create a CoAP Session .............................................................. 11 3.3.3. AT+QCOAPCLOSE Disconnect from CoAP Server .................................................. 12 3.3.4. AT+QCOAPHEADER Configure CoAP Message Header......................................... 12 3.3.5. AT+QCOAPOPTION Configure CoAP Message Options ......................................... 13 3.3.6. AT+QCOAPSEND Send CoAP Message .................................................................. 15 3.4. Description of CoAP URCs ...................................................................................................... 18 3.4.1. +QCOAPRECV Incoming CoAP Message Indication ................................................ 18 3.4.2. +QCOAPACK Delivery Result of CoAP Message Indication..................................... 19 3.4.3. +QCOAPIND Retransmission Result Notification ...................................................... 19 4 Summary of Result Codes ............................................................................................................... 21 5 Examples ........................................................................................................................................... 22 5.1. CoAP Client Operation without DTLS ...................................................................................... 22 5.2. CoAP Client Operation with DTLS ........................................................................................... 23 6 Appendix References ....................................................................................................................... 25 BG77xA-GL&BG95xA-GL_CoAP_Application_Note 4 / 25 LPWA Module Series Table Index Table 1: Applicable Modules ........................................................................................................................ 6 Table 2: Types of AT Commands ................................................................................................................ 8 Table 3: Option Definitions ......................................................................................................................... 14 Table 4: and Definitions ........................................................................................ 16 Table 5: Description of Codes...................................................................................................... 21 Table 6: Related Document ....................................................................................................................... 25 Table 7: Terms and Abbreviations ............................................................................................................. 25 BG77xA-GL&BG95xA-GL_CoAP_Application_Note 5 / 25 LPWA Module Series 1 Introduction This document explains how to use the CoAP feature on Quectel BG77xA-GL and BG95xA-GL modules through AT commands. 1.1. Applicable Modules Table 1: Applicable Modules Module Family BG77xA-GL BG95xA-GL Model BG770A-GL BG773A-GL BG950A-GL BG951A-GL BG953A-GL BG955A-GL BG77xA-GL&BG95xA-GL_CoAP_Application_Note 6 / 25 LPWA Module Series 2 General Overview of CoAP The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The protocol is designed for machine-to-machine (M2M) applications such as smart energy and building automation. CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key Web concepts such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments. The data interaction mechanism of CoAP feature is explained below. MCU Modem Configure CoAP Context AT+QCOAPCFG='pdpcid',, AT+QCOAPCFG='dtls',,[,] AT+QCOAPCFG='trans',,, Create CoAP Session AT+QCOAPOPEN=,, DTLS Handshake +QCOAPOPEN: , CoAP Server UDP connection Client Hello Finished Configure CoAP Message (header and options) AT+QCOAPHEADER=,,[,,] AT+QCOAPOPTION=,,[,] Send Specific CoAP Message AT+QCOAPSEND=,,,[,] CoAP non-confirmable message +QCOAPACK: ,,, CoAP confirmable message CoAP ACK AT+QCOAPSEND=,,,,[,] CoAP confirmable message +QCOAPIND: ,,,1, CoAP Retransmission 1(No ACK) CoAP Retransmission N +QCOAPIND: ,,,N, CoAP ACK Receive CoAP Message from Server Close CoAP Session +QCOAPRECV: ,,,,,[,,...],rn[] AT+QCOAPCLOSE= +QCOAPCLOSE:, Downlink CoAP Message UDP or DTLS Disconnection CoAP Retransmission Figure 1: CoAP Data Interaction Diagram BG77xA-GL&BG95xA-GL_CoAP_Application_Note 7 / 25 LPWA Module Series 3 Description of CoAP 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+=? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Read Command AT+? Check the current parameter value of the corresponding command. Write Command AT+=[,[, Set user-definable parameter value. [...]]] Execution Command AT+ Return a specific information parameter or perform a specific action. BG77xA-GL&BG95xA-GL_CoAP_Application_Note 8 / 25 LPWA Module Series 3.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 3.3. Description of CoAP AT Commands 3.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 Test Command AT+QCOAPCFG=? Response +QCOAPCFG: 'pdpcid',(range of supported s),(range of supported s) +QCOAPCFG: 'dtls',(range of supported s),(list of supported s),(range of supported s) +QCOAPCFG: 'trans',(range of supported s),(range of supported s),(range of supported s) Write Command Query/set the PDP context for a specified CoAP client. AT+QCOAPCFG='pdpcid',[,] OK Response If the optional parameter is omitted, query the current setting. +QCOAPCFG: 'pdpcid', OK If the optional parameter is specified, set the PDP context of the specified CoAP client. OK Write Command Query/set the DTLS mode for a specified CoAP client. AT+QCOAPCFG='dtls',<clientID If there is any error: ERROR Response If the optional parameters are omitted, query the current setting. +QCOAPCFG: 'dtls',[,] BG77xA-GL&BG95xA-GL_CoAP_Application_Note 9 / 25 LPWA Module Series >[,[,]] OK If the optional parameters are specified, set the DTLS mode for the specified CoAP client. OK Write Command Query/set retransmission settings for a specified CoAP client. AT+QCOAPCFG='trans',[,,] If there is any error: ERROR Response If the optional parameters are omitted, query the current setting. +QCOAPCFG: 'trans',, OK If the optional parameters are specified, set the retransmission settings for the specified CoAP client. OK Maximum Response Time Characteristics If there is any error: ERROR 300 ms The commands take effect immediately. The configurations are not saved. Parameter Integer type. CoAP client identifier. Range: 0–5. Integer type. PDP context ID used by CoAP client. Range: 1–5. Default value: 1. 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 Integer type. DTLS context identifier. Range: 0–5. Integer type. Acknowledgement timeout of CoAP confirmable message delivery. Range: 2–60. Default value: 2. Unit: second. Integer type. Maximum retransmission counts of CoAP confirmable message delivery. Range: 4–8. Default value: 5. NOTE If DTLS mode is enabled for a CoAP session, the PSK file named _server.psk should be uploaded to UFS or EUFS with AT+QFUPL (see document [1] for more information), and the content of the file should be in the format of '&'. CoAP client uses this PSK file for BG77xA-GL&BG95xA-GL_CoAP_Application_Note 10 / 25 establishing a DTLS session. LPWA Module Series 3.3.2. AT+QCOAPOPEN Create a CoAP Session This command creates a CoAP session. AT+QCOAPOPEN Create a CoAP Session Test Command AT+QCOAPOPEN=? Response +QCOAPOPEN: (range of supported s),,(range of supported s) Read Command AT+QCOAPOPEN? OK Response [+QCOAPOPEN: ,,,] Write Command Configure and connect to a specified CoAP server: AT+QCOAPOPEN=,, OK Response OK +QCOAPOPEN: , If there is any error: ERROR Maximum Response Time 75 s, determined by network Characteristics / Parameter Integer type. CoAP client identifier. Range: 0–5. String type. CoAP server address. It can be an IP address or a domain name. Maximum size: 255 bytes. Integer type. CoAP server port. Range: 1–65535. Integer type. Current status of the specified CoAP client. 0 Idle state or connection disconnected. 1 CoAP client is opening. 2 CoAP client is connecting to the CoAP server. 3 CoAP client is connected. 4 CoAP connection is disconnecting. Integer type. Command execution result. See Chapter 4 for details. BG77xA-GL&BG95xA-GL_CoAP_Application_Note 11 / 25 LPWA Module Series 3.3.3. AT+QCOAPCLOSE Disconnect from CoAP Server This command disconnects a client from the CoAP server. AT+QCOAPCLOSE Disconnect from CoAP Server 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 75 s, determined by network / Parameter Integer type. CoAP client identifier. Range: 0–5. Integer type. Command execution result. See Chapter 4 for details. 3.3.4. AT+QCOAPHEADER Configure CoAP Message Header This command configures a CoAP message header. AT+QCOAPHEADER Configure CoAP Message Header Test Command AT+QCOAPHEADER=? Response +QCOAPHEADER: (range of supported s),(range of supported s),(list of supported s),(range of supported s), Write Command AT+QCOAPHEADER=,,[,,] Maximum Response Time OK Response OK If there is any error: ERROR 300 ms BG77xA-GL&BG95xA-GL_CoAP_Application_Note 12 / 25 LPWA Module Series Characteristics / Parameter Integer type. CoAP client identifier. Range: 0–5. 16-bit unsigned integer in network byte order. Message ID. Used to detect message duplication and to match Acknowledgement/Reset type messages to Confirmable/Non-confirmable type messages. Range: 0–65535. Integer type. Whether to generate token value automatically. 0 Do not generate token value automatically. 1 Generate token value automatically. 4-bit unsigned integer. Length of the variable-length field. Range: 0–8. Unit: bytes. Only valid when =0. Hex string type. CoAP message token value. Only valid when =0. 3.3.5. 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),, Write Command AT+QCOAPOPTION=,,< opt_index>[,,] OK Response OK If there is any error: ERROR Maximum Response Time 300 ms Characteristics / Parameter Integer type. CoAP client identifier. Range: 0–5. Integer type. Command operation mode. 0 Add a new option to CoAP message 1 Remove an existing option from CoAP message BG77xA-GL&BG95xA-GL_CoAP_Application_Note 13 / 25 LPWA Module Series Integer type. Index of the option to be added/deleted. Range: 0–7. Integer type. Option number. Only valid when =0. Individual CoAP options are summarized and explained in RFC 7252 section 5.10. Option Number Option Name 1 If-Match 3 Uri-Host 4 ETag 5 If-None-Match 7 Uri-Port 8 Location-Path 11 Uri-Path 12 Content-Format 14 Max-Age 15 Uri-Query 17 Accept 20 Location-Query 23 Block2 27 Block1 35 Proxy-Uri 39 Proxy-Scheme 60 Size1 Option value corresponding to each option number. Only valid when =0. See Table 3 for details such as format and length of this parameter. Table 3: Option Definitions Option Number Option Name Option Value Format Option Value Length (Bytes) 1 If-Match opaque 0–8 3 Uri-Host string 1–255 4 ETag opaque 1–8 5 If-None-Match empty 0 7 Uri-Port unsigned integer 0–2 8 Location-Path string 0–255 11 Uri-Path string 0–255 12 Content-Format unsigned integer 0–2 14 Max-Age unsigned integer 0–4 BG77xA-GL&BG95xA-GL_CoAP_Application_Note 14 / 25 LPWA Module Series 15 Uri-Query string 0–255 17 Accept unsigned integer 0–2 20 Location-Query string 0–255 (0–1048575),(0–1),(16–2048),(0–104 23 Block2 num,more,sz,offset 8575) (0–1048575),(0–1),(16–2048),(0–104 27 Block1 num,more,sz,offset 8575) 28 Size unsigned integer 0-4 35 Proxy-Uri string 1–1034 39 Proxy-Scheme string 1–255 60 Size1 unsigned integer 0–4 3.3.6. AT+QCOAPSEND Send CoAP Message This command sends a CoAP message. After you input the payload of a specified length, the command first serializes the input data to a CoAP packet and then sends it to the CoAP server. AT+QCOAPSEND Send CoAP Message Test Command AT+QCOAPSEND=? Response +QCOAPSEND: (range of supported s),(range of supported s),,,(range of supported s) Write Command AT+QCOAPSEND=,,< code_value>,[,] OK Response > After > is returned, input the data to be sent. Tap Ctrl + Z to send the data, or tap Esc to cancel the operation. OK +QCOAPACK: ,,, Maximum Response Time Characteristics If there is any error: ERROR 300 ms / BG77xA-GL&BG95xA-GL_CoAP_Application_Note 15 / 25 LPWA Module Series Parameter Integer type. CoAP client identifier. Range: 0–5. Integer type. CoAP message type. 0 Confirmable (CON) 1 Non-confirmable (NON) 2 Acknowledgement 3 Reset Integer type. Request or response code value. See Table 4 for details. Integer type. Current options can be preset in CoAP client with AT+QCOAPOPTION. If any bit in the bitmask of this parameter is set to 1, the corresponding option will be added to a CoAP packet. Value Bitmask Description 0 00000000 No option is added to the CoAP packet 1 00000001 Add the option with index 0 to the CoAP packet 2 00000010 Add the option with index 1 to the CoAP packet 3 00000011 Add options with indexes 0 and 1 to the CoAP packet 4 00000100 Add the option with index 3 to the CoAP packet 5 00000101 Add options with indexes 0 and 3 to the CoAP packet … 253 11111101 Add options with indexes 0 and 2–7 to the CoAP packet 254 11111110 Add options with indexes 1–7 to the CoAP packet 255 11111111 Add options with indexes 0–7 to the CoAP packet Integer type. Length of data to be sent. Maximum length: 1024 bytes. If this parameter is omitted, data of any length not exceeding 1024 bytes can be input. 16-bit unsigned integer in network byte order. Message ID. Used to detect message duplication and to match Acknowledgement/Reset type messages to Confirmable/Non-confirmable type messages. Range: 0–65535. Integer type. Command execution result. See Chapter 4 for details. Table 4: and Definitions Description 0 0.00 Empty message. GET. The GET method retrieves a representation for the information that 1 0.01 currently corresponds to the resource identified by the request URI. POST. The POST method requests that the representation enclosed in 2 0.02 the request be processed. PUT. The PUT method requests that the resource identified by the 3 0.03 request URI be updated or created with the enclosed representation. 4 0.04 DELETE. The DELETE method requests that the resource identified by BG77xA-GL&BG95xA-GL_CoAP_Application_Note 16 / 25 LPWA Module Series the request URI be deleted. Created. Like HTTP 201 'Created', but only used in response to POST 65 2.01 and PUT requests. The payload returned with the response, if any, is a representation of the action result. Deleted. This Response Code is like HTTP 204 'No Content' but only used in response to requests that cause the resource to cease being 66 2.02 available, such as DELETE and, in certain circumstances, POST. The payload returned with the response, if any, is a representation of the action result. Valid. This Response Code is related to HTTP 304 'Not Modified' but only 67 2.03 used to indicate that the response identified by the entity-tag identified by the included ETag Option is valid. Changed. This Response Code is like HTTP 204 'No Content' but only 68 2.04 used in response to POST and PUT requests. The payload returned with the response, if any, is a representation of the action result. Content. This Response Code is like HTTP 200 'OK' but only used in 69 2.05 response to GET requests. 128 4.00 Bad request. Unauthorized. The client is not authorized to perform the requested 129 4.01 action. Bad option. The request could not be understood by the server due to one 130 4.02 or more unrecognized or malformed options. 131 4.03 Forbidden. 132 4.04 Not found. 133 4.05 Method not allowed. 134 4.06 Not acceptable. 140 4.12 Precondition failed. 141 4.13 Request entity too large. 143 4.15 Unsupported Content-Format. 160 5.00 Internal server error. 161 5.01 Not implemented. 162 5.02 Bad gateway. 163 5.03 Service unavailable. BG77xA-GL&BG95xA-GL_CoAP_Application_Note 17 / 25 LPWA Module Series 164 5.04 Gateway timeout. Proxying not supported. The server is unable or unwilling to act as a 165 5.05 forward-proxy for the URI specified in the Proxy-Uri Option or using Proxy-Scheme. NOTE 1. is an 8-bit unsigned integer, split into a 3-bit class (most significant bits) and a 5-bit detail (least significant bits), documented as 'c.dd'. 'c' is a digit from 0 to 7 for the 3-bit subfield and 'dd' are two digits from 00 to 31 for the 5-bit subfield. The class can indicate a request (0), a success response (2), a client error response (4), or a server error response (5). (All other class values are reserved.) As a special case, Code 0.00 indicates an Empty message. 2. When is c.dd, = c × 32 + dd. 3.4. Description of CoAP URCs CoAP URCs are reported to the host when a CoAP Client is in registration, observation, or application data transmission procedure. 3.4.1. +QCOAPRECV Incoming CoAP Message Indication This URC is reported when CoAP client receives a downlink CoAP message from the remote CoAP server. +QCOAPRECV Incoming CoAP Message Indication +QCOAPRECV: ,,,,,[,,…], This URC is reported when a new CoAP message is received from CoAP server. Parameter Integer type. CoAP client identifier. 16-bit unsigned integer in network byte order. Message ID. Response code of incoming message. Format: 'c.dd'. See Table 4 for details. Integer type. Length of a variable-length token field. Token value of a CoAP message. Number of options included in the CoAP message. Option number. BG77xA-GL&BG95xA-GL_CoAP_Application_Note 18 / 25 LPWA Module Series Option value that corresponds to the option number. Payload length of incoming CoAP message. Payload data. 3.4.2. +QCOAPACK Delivery Result of CoAP Message Indication If a CoAP message is sent, the client needs an acknowledgement message from the server. ⚫ If a confirmable message is delivered, this URC indicates if the message has been acknowledged by the server. ⚫ If a non-confirmable, acknowledgement or reset message is delivered, this URC indicates if the message has been sent. +QCOAPACK Delivery Result of CoAP Message Indication +QCOAPACK: ,,, been sent or acknowledged by the server. Parameter Integer type. CoAP client identifier. Range: 0–5. Integer type. CoAP message type. 0 Confirmable 1 Non-confirmable 2 Acknowledgement 3 Reset 16-bit unsigned integer in network byte order. Message ID. Integer type. CoAP message delivery result. See Chapter 4 for details. 3.4.3. +QCOAPIND Retransmission Result Notification This URC is reported to notify the retransmission result when a client retransmits a confirmable message that is not acknowledged by the server. +QCOAPIND Retransmission Result Notification +QCOAPIND: ,,,, CoAP confirmable message. Parameter Integer type. CoAP client identifier. Range: 0–5. Integer type. CoAP message type. BG77xA-GL&BG95xA-GL_CoAP_Application_Note 19 / 25 LPWA Module Series 0 Confirmable 16-bit unsigned integer in network byte order. Message ID. Integer type. Retransmission count after sending a confirmable message. Maximum retransmission count is configured with AT+QCOAPCFG='trans'. Integer type. Retransmission result. See Chapter 4 for details. BG77xA-GL&BG95xA-GL_CoAP_Application_Note 20 / 25 LPWA Module Series 4 Summary of Result Codes The following table lists some of the general result codes. Table 5: Description of Codes 0 -1 -2 -3 -4 -5 -6 -7 -8 -9 -10 -11 Description 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 BG77xA-GL&BG95xA-GL_CoAP_Application_Note 21 / 25 LPWA Module Series 5 Examples 5.1. CoAP Client Operation without DTLS AT+QCOAPCFG='pdpcid',0,1 //Set the PDP context ID as 1 for CoAP client 0. OK AT+QCOAPCFG='trans',0,4,5 //Configure retransmission settings for CoAP client 0. (ACK timeout is 4 seconds and the maximum retransmission count is 5.) OK AT+QCOAPOPEN=0,'220.180.239.212',8028 //Create a CoAP session and connect to the CoAP server. OK +QCOAPOPEN: 0,0 // CoAP session created successfully. AT+QCOAPOPEN? //Query the current status of the CoAP session. +QCOAPOPEN: 0,'220.180.239.212',8028,3 OK //Set CoAP message header. AT+QCOAPHEADER=0,1234,1 OK //Set CoAP message ID to 1234 and generate token automatically. //Add CoAP options. AT+QCOAPOPTION=0,0,0,11,'19'//Add an option (option number: 11, corresponding to option name of Uri-Path; option value: '19') to option index 0. OK AT+QCOAPOPTION=0,0,1,12,40 //Add an option (option number: 12, corresponding to option name: Content-Format; option value: 40, corresponding to media type: of application/link-format) to option index 1. OK AT+QCOAPSEND=0,1,2,1,20 >Hello, CoAP Message! OK //Send 20-byte CoAP non-confirmable message to the server. +COAPACK: 0,1,1234,0 //Receive downlink error message from server. BG77xA-GL&BG95xA-GL_CoAP_Application_Note 22 / 25 +QCOAPRECV: 0,1234,4.04,6,D204D52E814B,0,9 Not Found AT+QCOAPCLOSE=0 OK //Close the CoAP session. +QCOAPCLOSE: 0,0 // CoAP session closed successfully. LPWA Module Series 5.2. CoAP Client Operation with DTLS AT+QCOAPCFG='pdpcid',0,1 //Set the PDP context ID as 1 for CoAP client 0. OK AT+QCOAPCFG='trans',0,4,5 //Configure retransmission settings for CoAP client 0. (ACK timeout is 4 s. Maximum retransmission count is 5.) OK AT+QCOAPCFG='dtls',0,1,0 //Enable DTLS mode for CoAP client 0. OK AT+QSSLCFG='dtls',0,1 //Set DTLS mode (enable DTLS feature). OK AT+QSSLCFG='dtlsversion',0,1 //Configure DTLS1.2 for CoAP session OK AT+QFUPL='UFS:0_server.psk',34 //Upload the PSK file for DTLS session to UFS. CONNECT 864508030012428&313233343446473839 //Input PSK file content. +QFUPL: 34,2802 OK AT+QCOAPOPEN=0,'leshan.eclipseprojects.io',5684 //Create a CoAP session and connect to the CoAP server. OK +QCOAPOPEN: 0,0 // CoAP session created successfully. //Set CoAP message header. AT+QCOAPHEADER=0,1234,1 OK //Set CoAP message ID to 1234 and generate token automatically. //Add CoAP options. AT+QCOAPOPTION=0,0,0,11,'19'//Add an option (option number: 11, corresponding to option name: Uri-Path; option value: '19') to option index 0. OK AT+QCOAPOPTION=0,0,1,12,40 //Add an option (option number: 12, corresponding to option name: Content-Format; option value: 40, corresponding to media type: application/link-format) to option index 1. BG77xA-GL&BG95xA-GL_CoAP_Application_Note 23 / 25 LPWA Module Series OK AT+QCOAPSEND=0,1,2,1,20 >Hello, CoAP Message! OK //Send a 20-byte CoAP non-confirmable message to the server. +COAPACK: 0,1,1234,0 //Receive downlink error message from server-side. +QCOAPRECV: 0,1234,4.04,6,D204D52E814B,0,9 Not Found AT+QCOAPCLOSE=0 //Close the CoAP session. OK +QCOAPCLOSE: 0,0 // CoAP session closed successfully. BG77xA-GL&BG95xA-GL_CoAP_Application_Note 24 / 25 LPWA Module Series 6 Appendix References Table 6: Related Document Document Name [1] Quectel_BG77xA-GL&BG95xA-GL_FILE_Application_Note Table 7: Terms and Abbreviations Abbreviation ACK CoAP DTLS EGPRS HTTP(S) ID LPWA M2M MCU PDP PSK UDP UFS URC URI TA Description Acknowledgement Constrained Application Protocol Datagram Transport Layer Security Enhanced General Packet Radio Service Hypertext Transfer Protocol (Secure) Identifier Low-Power Wide-Area Machine to Machine Microcontroller Unit Packet Data Protocol Pre-Shared Key User Datagram Protocol User File System Unsolicited Result Code Uniform Resource Identifier Terminal Adapter BG77xA-GL&BG95xA-GL_CoAP_Application_Note 25 / 25
315.03 KB
EP06&EG06&EM06 Series Data Call Application Note LTE-A Module Series Version: 1.0 Date: 2022-09-17 Status: Released LTE-A Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. EP06&EG06&EM06_Series_Data_Call_Application_Note 1 / 18 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. 2022. All rights reserved. EP06&EG06&EM06_Series_Data_Call_Application_Note 2 / 18 LTE-A Module Series About the Document Revision History Version 1.0 Date 2022-05-13 2022-09-17 Author Ozzy ANG Ozzy ANG Description Creation of the document First official release EP06&EG06&EM06_Series_Data_Call_Application_Note 3 / 18 LTE-A Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 2 Data Call Methods ............................................................................................................................... 8 2.1. Classification of Data Call Scenarios......................................................................................... 8 2.2. List of Data Call Methods........................................................................................................... 8 3 Data Call Steps .................................................................................................................................. 10 3.1. NDIS Data Call (USB + TE + Windows + QMI) ....................................................................... 10 3.2. QMI_WWAN Data Call (USB + TE + Linux + QMI) ................................................................. 11 3.3. GobiNet Data Call (USB + TE + Linux + QMI) ........................................................................ 12 3.4. MBIM Data Call (USB + TE + Linux + MBIM).......................................................................... 13 3.5. MBIM Data Call (USB + TE + Windows + MBIM).................................................................... 14 3.6. ECM Data Call (USB + AP + Linux)......................................................................................... 15 3.7. ECM Data Call (USB + AP + Windows)................................................................................... 16 4 Appendix References ....................................................................................................................... 17 EP06&EG06&EM06_Series_Data_Call_Application_Note 4 / 18 LTE-A Module Series Table Index Table 1: Data Call Scenarios and Corresponding Data Call Methods ........................................................ 8 Table 2: Related Documents...................................................................................................................... 17 Table 3: Terms and Abbreviations ............................................................................................................. 17 EP06&EG06&EM06_Series_Data_Call_Application_Note 5 / 18 LTE-A Module Series Figure Index Figure 1: Confirm Driver Installation .......................................................................................................... 10 Figure 2: NDIS Data Call (USB + TE + Windows + QMI) .......................................................................... 10 Figure 3: MBIM Data Call (USB + TE + Windows + MBIM) ...................................................................... 15 Figure 4: ECM Data Call (USB + AP + Windows) ..................................................................................... 16 EP06&EG06&EM06_Series_Data_Call_Application_Note 6 / 18 LTE-A Module Series 1 Introduction Quectel LTE-A module EP06 series, EG06 series and EM06 series support data call. This document introduces the supported data call methods, as well as the corresponding steps and notes. EP06&EG06&EM06_Series_Data_Call_Application_Note 7 / 18 LTE-A Module Series 2 Data Call Methods 2.1. Classification of Data Call Scenarios 1. By Communication Method between the host and the module in the data call: 1) QMI (Application layer communication protocol) 2) MBIM (Application layer communication protocol) 3) None (Bottom layer communication protocol of standard interface, such as Ethernet and Wi-Fi) 2. By Interface Type used by the data call: USB 3. By Initiator of the data call: 1) TE: The host initiates the data call. 2) AP: The module initiates the data call. 4. By Operate System of the Host in the data call: 1) Windows 2) Linux (Android) 2.2. List of Data Call Methods According to the data call scenarios mentioned in Chapter 2.1, the corresponding data call methods supported by the module are listed in the table below. Table 1: Data Call Scenarios and Corresponding Data Call Methods Interface Type USB Communication Initiator Operate System of the Host Data Call Method Method TE Windows QMI NDIS USB TE Linux QMI QMI_WWAN/GobiNet EP06&EG06&EM06_Series_Data_Call_Application_Note 8 / 18 USB USB USB TE Windows/Linux AP Windows AP Linux MBIM - LTE-A Module Series MBIM (USB) ECM ECM NOTE 1. The corresponding data call methods are named with the driver’s name. 2. For detailed steps of each data call method, see Chapter 3. Refer to document [1] for details of the related AT commands, if any of these AT commands is not included, please contact Quectel Technical Support. EP06&EG06&EM06_Series_Data_Call_Application_Note 9 / 18 LTE-A Module Series 3 Data Call Steps 3.1. NDIS Data Call (USB + TE + Windows + QMI) 1. Install NDIS driver Quectel_Windows_USB_Driver(Q)_For_NDIS provided by Quectel on the host. 2. Connect the module to the host through USB cable. 3. Check whether the driver 'Quectel Wireless Ethernet Adapter' is loaded under 'Network adapters' on the host as shown in the figure below: Figure 1: Confirm Driver Installation 4. Click the network icon in the lower right corner of the host desktop to start a data call. Figure 2: NDIS Data Call (USB + TE + Windows + QMI) EP06&EG06&EM06_Series_Data_Call_Application_Note 10 / 18 LTE-A Module Series 3.2. QMI_WWAN Data Call (USB + TE + Linux + QMI) 1. Contact Quectel Technical Supports for installation packages of the following drivers and tool: 1) Quectel_Linux_USB_Serial_Option_Driver (Driver for TTY port, such as AT and DM.) 2) Quectel_Linux&Android_QMI_WWAN_Driver (Driver for usbnet data port) 3) QConnectManager_Linux (Data call tool) 2. Integrate/compile the drivers and tool on the host. To install the drivers: 1) Execute make install in the driver file. 2) If you want to perform multiple data call with the driver, add the parameter qmap_mode= in the command line when you execute command to load the driver. The maximum number of data call channels is 4. Here is an example: insmod qmi_wwan_q.ko qmap_mode=4 q map_mode=0 indicates single data call without UL AGG. qmap_mode=1 indicates single data with UL AGG. qmap_mode=2/3/4 indicates multiple data call with UL AGG. 3) If you want to perform data call in bridge mode (that is bridging the data call connection to other devices on the host to provide network access for these devices) with the driver, refer to the following examples in log/ directory of quectel-CM source code package. log/how_to_use_bridge.txt Bridge mode for single data call log/how_to_use_bridge_and_QMAP.txt Bridge mode for multiple data call 4) Please do NOT use Linux original drivers (qmi_wwan.ko and qcserial.ko) when using Quectel modules. You can check whether the Linux original drivers are installed by running lsmod. If the Linux original drivers are installed, you should run rmmod to uninstall the drivers. Before you connect Quectel module to the host, please make sure that qmi_wwan_q.ko and option.ko provided by Quectel are installed. 3. Connect the module to the host through USB. 4. Start a data call with quectel-CM. 1) Execute quectel-CM -h to check help information of quectel-CM. 2) Refer to the following examples in log/ directory of quectel-CM source code package. qmi_wwan_q.txt qmi_wwan_q_bridge.txt Single data call in local without using QMAP Single data call in bridge mode without using QMAP EP06&EG06&EM06_Series_Data_Call_Application_Note 11 / 18 qmi_wwan_q_qmap=1.txt qmi_wwan_q_qmap=1_bridge.txt qmi_wwan_q_qmap=4.txt qmi_wwan_q_qmap=4_bridge.txt LTE-A Module Series Single data call in local with QMAP Single data call in bridge mode with QMAP QMAP multiple data call in local QMAP multiple data call in bridge mode NOTE 1. If you want to perform multiple data call, QMAP feature of the module must be enabled. 2. QMAP feature of the module is enabled by default, that is even if qmap_mode is not configured when you load the driver, qmap_mode=1 is set automatically when you run the driver. Therefore, the examples of qmi_wwan_q.txt and qmi_wwan_q_bridge.txt are same with qmi_wwan_q_qmap=1.txt and qmi_wwan_q_qmap=1_bridge.txt in actual practice. 3.3. GobiNet Data Call (USB + TE + Linux + QMI) 1. Contact Quectel Technical Supports for installation package of the following drivers and tool: 1) Quectel_Linux_USB_Serial_Option_Driver (Driver for TTY port, such as AT and DM.) 2) Quectel_Linux&Android_GobiNet_Driver (Driver for usbnet data port) 3) QConnectManager_Linux (Data call tool) 2. Integrate/compile the drivers and tool on the host. To install the drivers: 1) Execute make install in the driver file. 2) If you want to perform multiple data call with the driver, add the parameter qmap_mode= in the command line when you execute command to load the driver. The maximum number of data call channels is 4. Here is an example: insmod GobiNet.ko qmap_mode=4 q map_mode=0 indicates single data call without UL AGG. qmap_mode=1 indicates single data with UL AGG. qmap_mode=2/3/4 indicates multiple data call with UL AGG. 3) The Quectel drivers will replace the Linux original GobiNet drivers after a successful installation. Please do NOT use Linux original driver (qcserial.ko) when using Quectel modules. You can check whether the Linux original driver (GobiNet + qcserial.ko) is installed by running lsmod. If the Linux original driver is installed, you should run rmmod to uninstall the driver. Before you connect Quectel module to the host, please make sure that GobiNet.ko and option.ko provided by Quectel are installed. EP06&EG06&EM06_Series_Data_Call_Application_Note 12 / 18 LTE-A Module Series 3. Connect the module to the host through USB. 4. Start a data call with quectel-CM. 1) Execute quectel-CM -h to check help information of quectel-CM. 2) Refer to the following examples in log/ directory of quectel-CM source code package. gobinet.txt gobinet_bridge.txt gobinet_qmap=1.txt gobinet_qmap=1_bridge.txt gobinet_qmap=4.txt gobinet_qmap=4_bridge.txt Single data call in local without using QMAP Single data call in bridge mode without using QMAP QMAP single data call in local QMAP single data call in bridge mode QMAP multiple data call in local QMAP multiple data call in bridge mode NOTE 1. If you want to perform multiple data call, QMAP feature of the module must be enabled. 2. QMAP feature of the module is enabled by default, that is even qmap_mode is not configured when you load the driver, qmap_mode=1 is set automatically when you run the driver. Therefore, the examples of gobinet.txt and gobinet_bridge.txt are same with gobinet_qmap=1.txt and gobinet_qmap=1_bridge.txt in actual practice. 3.4. MBIM Data Call (USB + TE + Linux + MBIM) 1. Contact Quectel Technical Supports for installation package of the following drivers and tool: 1) Quectel_Linux_USB_Serial_Option_Driver (Driver for TTY port, such as AT and DM.) 2) cdc_mbim_drv_Linux (Driver for usbnet data port) 3) QConnectManager_Linux (Data call tool) 2. Integrate/compile the drivers and tool on the host. To install the drivers: 1) Execute make install in the driver file. 2) If you want to perform multiple data call with the driver, add the parameter mbim_qmap_mode= in the command line when you execute command to load the driver. The maximum number of data call channels is 16. Here is an example: insmod quec_cdc_mbim.ko mbim_qmap_mode=4 3) Please do NOT use Linux original driver (qcserial.ko) when using Quectel modules. You can EP06&EG06&EM06_Series_Data_Call_Application_Note 13 / 18 LTE-A Module Series check whether the Linux original driver is installed by running lsmod. If the Linux original driver is installed, you should run rmmod to uninstall the driver. Before you connect Quectel module to the host, please make sure that driver quec_cdc_mbim.ko provided by Quectel is installed. 3. Connect the module to the host through USB. 4. Set the NIC data call method of the module to MBIM with AT+QCFG='usbnet',2. 5. Start a data call with quectel-CM. 1) Execute quectel-CM -h to check help information of quectel-CM. 2) Refer to the following examples in log/ directory of quectel-CM source code package. cdc_mbim.txt cdc_mbim_vlan.txt QMAP single data call in local QMAP multiple data call in local NOTE 1. If you want to perform multiple data call, QMAP feature of the module must be enabled. 2. QMAP feature of the module is enabled by default, that is even mbim_qmap_mode is not configured when you load the driver, mbim_qmap_mode=1 is set automatically when you run the driver. 3.5. MBIM Data Call (USB + TE + Windows + MBIM) 1. Connect the module to the host through USB. 2. Set the NIC data call method of the module to MBIM with AT+QCFG='usbnet',2. 3. Make sure that the driver loaded for the device in Windows system is the default MBIM driver. 4. Click the network icon in the lower right corner of the host desktop to start a data call. EP06&EG06&EM06_Series_Data_Call_Application_Note 14 / 18 LTE-A Module Series Figure 3: MBIM Data Call (USB + TE + Windows + MBIM) 3.6. ECM Data Call (USB + AP + Linux) 1. Contact Quectel Technical Supports for installation package of the following driver: Quectel_Linux_USB_Serial_Option_Driver (Driver for TTY port, such as AT and DM.) 2. Integrate/compile the driver on the host. To install the driver: 1) Execute make install in the driver file. 2) Please do NOT use Linux original driver (qcserial.ko) when using Quectel modules. You can check whether the Linux original driver is installed by running lsmod. If the Linux original driver is installed, you should run rmmod to uninstall the driver. Before you connect Quectel module to the host, please make sure that driver option.ko provided by Quectel is installed. 3. Connect the module to the host through USB. 4. Set the NIC data call method of the module to ECM with AT+QCFG='usbnet',1 through AT port /dev/ttyUSB2 (the third TTY port of the module) when you start the module for the first time. 5. Reboot the module. 6. After the module is rebooted, the host matches the Linux original ECM driver automatically and generates a virtual Ethernet interface usb0 based on USB. At this time, the module performs data call internally and provides network access to the host through NAT. The host only needs to send DHCP to ECM NIC to request IP address. EP06&EG06&EM06_Series_Data_Call_Application_Note 15 / 18 LTE-A Module Series 3.7. ECM Data Call (USB + AP + Windows) 1. Contact Quectel Technical Supports for installation package of the ECM driver Quectel_LTE_Windows_USB_Driver_For_ECM and then install the driver. 2. Connect the module to the host through USB. 3. Set the NIC data call method of the module to ECM with AT+QCFG='usbnet',1 through AT port when you start the module for the first time. 4. Reboot the module. 5. Make sure that ECM provided by Quectel is installed and loaded for the device. Then the host generates a virtual Ethernet interface based on USB and obtains IP address through DHCP automatically. Figure 4: ECM Data Call (USB + AP + Windows) EP06&EG06&EM06_Series_Data_Call_Application_Note 16 / 18 LTE-A Module Series 4 Appendix References Table 2: Related Documents Document Name [1] Quectel_EP06&EG06&EM06_AT_Commands_Manual Table 3: Terms and Abbreviations Abbreviation AP DHCP ECM ETH IP MBIM MHI NAT NDIS NIC QMI TE UL AGG USB Description Application Processor Dynamic Host Configuration Protocol Ethernet Control Model Ethernet Internet Protocol Mobile Broadband Interface Model Modem Host Interface Network Address Translation Network Driver Interface Specification Network Interface Controller Qualcomm Message Interface Terminal Equipment Uplink Aggregation Universal Serial Bus EP06&EG06&EM06_Series_Data_Call_Application_Note 17 / 18 WLAN WWAN Wireless Local Area Network Wireless Wide Area Network LTE-A Module Series EP06&EG06&EM06_Series_Data_Call_Application_Note 18 / 18
206.05 KB
EM12&EG12&EG18 Series Data Call Application Note LTE-A Module Series Version: 1.0 Date: 2022-09-17 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_Data_Call_Application_Note 1 / 18 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. 2022. All rights reserved. EM12&EG12&EG18_Series_Data_Call_Application_Note 2 / 18 LTE-A Module Series About the Document Revision History Version 1.0 Date 2022-05-13 2022-09-17 Author Ozzy ANG Ozzy ANG Description Creation of the document First official release EM12&EG12&EG18_Series_Data_Call_Application_Note 3 / 18 LTE-A Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 2 Data Call Methods ............................................................................................................................... 8 2.1. Classification of Data Call Scenarios......................................................................................... 8 2.2. List of Data Call Methods........................................................................................................... 9 3 Data Call Steps .................................................................................................................................. 10 3.1. NDIS Data Call (USB + TE + Windows + QMI) ....................................................................... 10 3.2. QMI_WWAN Data Call (USB + TE + Linux + QMI) ................................................................. 11 3.3. GobiNet Data Call (USB + TE + Linux + QMI) ........................................................................ 12 3.4. MBIM Data Call (USB + TE + Linux + MBIM).......................................................................... 13 3.5. MBIM Data Call (USB + TE + Windows + MBIM).................................................................... 14 3.6. ECM Data Call (USB + AP + Linux)......................................................................................... 15 3.7. ECM Data Call (USB + AP + Windows)................................................................................... 16 4 Appendix References ....................................................................................................................... 17 EM12&EG12&EG18_Series_Data_Call_Application_Note 4 / 18 LTE-A Module Series Table Index Table 1: Data Call Scenarios and Corresponding Data Call Methods ........................................................ 9 Table 2: Related Documents...................................................................................................................... 17 Table 3: Terms and Abbreviations ............................................................................................................. 17 EM12&EG12&EG18_Series_Data_Call_Application_Note 5 / 18 LTE-A Module Series Figure Index Figure 1: Confirm Driver Installation .......................................................................................................... 10 Figure 2: NDIS Data Call (USB + TE + Windows + QMI) .......................................................................... 10 Figure 3: MBIM Data Call (USB + TE + Windows + MBIM) ...................................................................... 15 Figure 4: ECM Data Call (USB + AP + Windows) ..................................................................................... 16 EM12&EG12&EG18_Series_Data_Call_Application_Note 6 / 18 LTE-A Module Series 1 Introduction Quectel LTE-A module EG12 series, EG18 series and EM12-G support data call. This document introduces the supported data call methods and the corresponding steps and notes. EM12&EG12&EG18_Series_Data_Call_Application_Note 7 / 18 LTE-A Module Series 2 Data Call Methods 2.1. Classification of Data Call Scenarios 1. By Communication Method between the host and the module in the data call: 1) QMI (Application layer communication protocol) 2) MBIM (Application layer communication protocol) 3) None (Bottom layer communication protocol of standard interface, such as Ethernet and Wi-Fi) 2. By Interface Type used by the data call: USB 3. By Initiator of the data call: 1) TE: The host initiates the data call. 2) AP: The module initiates the data call. 4. By Operate System of the Host in the data call: 1) Windows 2) Linux (Android) EM12&EG12&EG18_Series_Data_Call_Application_Note 8 / 18 LTE-A Module Series 2.2. List of Data Call Methods According to the classification of data call scenarios mentioned in Chapter 2.1, the data call scenarios supported by the module and the corresponding data call methods are listed in the table below. Table 1: Data Call Scenarios and Corresponding Data Call Methods Interface Type USB Communication Initiator Operate System of the Host Data Call Method Method TE Windows QMI NDIS USB TE Linux QMI QMI_WWAN/GobiNet USB TE Windows/Linux MBIM MBIM (USB) USB AP Windows - ECM USB AP Linux - ECM NOTE 1. The corresponding data call methods are named with the driver’s name. 2. For detailed steps of each data call method, see Chapter 3. Refer to document [1] for details of the related AT commands, if any of these AT commands is not included, please contact Quectel Technical Support. EM12&EG12&EG18_Series_Data_Call_Application_Note 9 / 18 LTE-A Module Series 3 Data Call Steps 3.1. NDIS Data Call (USB + TE + Windows + QMI) 1. Install NDIS driver Quectel_Windows_USB_Driver(Q)_For_NDIS provided by Quectel on the host. 2. Connect the module to the host through USB cable. 3. Check whether the driver 'Quectel Wireless Ethernet Adapter' is loaded under 'Network adapters' on the host as shown in the figure below: Figure 1: Confirm Driver Installation 4. Click the network icon in the lower right corner of the host desktop to start a data call. Figure 2: NDIS Data Call (USB + TE + Windows + QMI) EM12&EG12&EG18_Series_Data_Call_Application_Note 10 / 18 LTE-A Module Series 3.2. QMI_WWAN Data Call (USB + TE + Linux + QMI) 1. Contact Quectel Technical Support for installation packages of the following drivers and tool: 1) Quectel_Linux_USB_Serial_Option_Driver (Driver for TTY port, such as AT and DM.) 2) Quectel_Linux&Android_QMI_WWAN_Driver (Driver for usbnet data port) 3) QConnectManager_Linux (Data call tool) 2. Integrate/compile the above drivers and tool on the host. To install the drivers: 1) Execute make install in the driver file. 2) If you want to perform multiple data call with the driver, add the parameter qmap_mode= in the command line when you execute command to load the driver. The maximum number of data call channels is 4. Here is an example: insmod qmi_wwan_q.ko qmap_mode=4 qmap_mode=0 indicates single data call without UL AGG. qmap_mode=1 indicates single data with UL AGG. qmap_mode=2/3/4 indicates multiple data call with UL AGG. 3) If you want to perform data call in bridge mode (that is bridging the data call connection to other devices on the host to provide network access for these devices) with the driver, refer to the following examples in log/ directory of quectel-CM source code package. log/how_to_use_bridge.txt Bridge mode for single data call log/how_to_use_bridge_and_QMAP.txt Bridge mode for multiple data call 4) Please do NOT use Linux original drivers (qmi_wwan.ko and qcserial.ko) when you use Quectel modules. You can check whether the Linux original drivers are installed by running lsmod. If the Linux original drivers are installed, you should run rmmod to uninstall those. Before you connect Quectel module to the host, please make sure that qmi_wwan_q.ko and option.ko provided by Quectel are installed. 3. Connect the module to the host through USB. 4. Start a data call with quectel-CM. 1) Execute quectel-CM -h to check help information of quectel-CM. 2) Refer to the following examples in log/ directory of quectel-CM source code package. qmi_wwan_q.txt Single data call in local without using QMAP EM12&EG12&EG18_Series_Data_Call_Application_Note 11 / 18 qmi_wwan_q_bridge.txt qmi_wwan_q_qmap=1.txt qmi_wwan_q_qmap=1_bridge.txt qmi_wwan_q_qmap=4.txt qmi_wwan_q_qmap=4_bridge.txt LTE-A Module Series Single data call in bridge mode without using QMAP Single data call in local with QMAP Single data call in bridge mode with QMAP QMAP multiple data call in local QMAP multiple data call in bridge mode NOTE 1. If you want to perform multiple data call, QMAP feature of the module must be enabled. 2. QMAP feature of the module is enabled by default, that is even if qmap_mode is not configured when you load the driver, qmap_mode=1 is set automatically when you run the driver. Therefore, the examples of qmi_wwan_q.txt and qmi_wwan_q_bridge.txt are same with qmi_wwan_q_qmap=1.txt and qmi_wwan_q_qmap=1_bridge.txt in actual practice. 3.3. GobiNet Data Call (USB + TE + Linux + QMI) 1. Contact Quectel Technical Support for installation package of the following drivers and tool: 1) Quectel_Linux_USB_Serial_Option_Driver (Driver for TTY port, such as AT and DM.) 2) Quectel_Linux&Android_GobiNet_Driver (Driver for usbnet data port) 3) QConnectManager_Linux (Data call tool) 2. Integrate/compile the above drivers and tool on the host. To install the drivers: 1) Execute make install in the driver file. 2) If you want to perform multiple data call with the driver, add the parameter qmap_mode= in the command line when you execute command to load the driver. The maximum number of data call channels is 4. Here is an example: insmod GobiNet.ko qmap_mode=4 qmap_mode=0 indicates single data call without UL AGG. qmap_mode=1 indicates single data with UL AGG. qmap_mode=2/3/4 indicates multiple data call with UL AGG. 3) The Quectel drivers will replace the Linux original GobiNet drivers after a successful installation. Please do NOT use Linux original driver (qcserial.ko) when using Quectel modules. You can check whether the Linux original driver (GobiNet + qcserial.ko) is installed by running lsmod. If the Linux original driver is installed, you should run rmmod to uninstall the driver. Before you connect Quectel module to the host, please make sure that GobiNet.ko and option.ko provided EM12&EG12&EG18_Series_Data_Call_Application_Note 12 / 18 LTE-A Module Series by Quectel are installed. 3. Connect the module to the host through USB. 4. Start a data call with quectel-CM. 1) Execute quectel-CM -h to check help information of quectel-CM. 2) Refer to the following examples in log/ directory of quectel-CM source code package. gobinet.txt gobinet_bridge.txt gobinet_qmap=1.txt gobinet_qmap=1_bridge.txt gobinet_qmap=4.txt gobinet_qmap=4_bridge.txt Single data call in local without using QMAP Single data call in bridge mode without using QMAP QMAP single data call in local QMAP single data call in bridge mode QMAP multiple data call in local QMAP multiple data call in bridge mode NOTE 1. If you want to perform multiple data call, QMAP feature of the module must be enabled. 2. QMAP feature of the module is enabled by default, that is even qmap_mode is not configured when you load the driver, qmap_mode=1 is set automatically when you run the driver. Therefore, the examples of gobinet.txt and gobinet_bridge.txt are same with gobinet_qmap=1.txt and gobinet_qmap=1_bridge.txt in actual practice. 3.4. MBIM Data Call (USB + TE + Linux + MBIM) 1. Contact Quectel Technical Support for installation package of the following drivers and tool: 1) Quectel_Linux_USB_Serial_Option_Driver (Driver for TTY port, such as AT and DM.) 2) cdc_mbim_drv_Linux (Driver for usbnet data port) 3) QConnectManager_Linux (Data call tool) 2. Integrate/compile the drivers and tool on the host. To install the drivers: 1) Execute make install in the driver file. 2) If you want to perform multiple data call with the driver, add the parameter mbim_qmap_mode= in the command line when you execute command to load the driver. The maximum number of data call channels is 16. Here is an example: EM12&EG12&EG18_Series_Data_Call_Application_Note 13 / 18 LTE-A Module Series insmod quec_cdc_mbim.ko mbim_qmap_mode=4 3) Please do NOT use Linux original driver (qcserial.ko) when using Quectel modules. You can check whether the Linux original driver is installed by running lsmod. If the Linux original driver is installed, you should run rmmod to uninstall the driver. Before you connect Quectel module to the host, please make sure that driver quec_cdc_mbim.ko provided by Quectel is installed. 3. Connect the module to the host through USB. 4. Set the NIC data call method of the module to MBIM with AT+QCFG='usbnet',2. 5. Start a data call with quectel-CM. 1) Execute quectel-CM -h to check help information of quectel-CM. 2) Refer to the following examples in log/ directory of quectel-CM source code package. cdc_mbim.txt cdc_mbim_vlan.txt QMAP single data call in local QMAP multiple data call in local NOTE 1. If you want to perform multiple data call, QMAP feature of the module must be enabled. 2. QMAP feature of the module is enabled by default, that is even mbim_qmap_mode is not configured when you load the driver, mbim_qmap_mode=1 is set automatically when you run the driver. 3.5. MBIM Data Call (USB + TE + Windows + MBIM) 1. Connect the module to the host through USB. 2. Set the NIC data call method of the module to MBIM with AT+QCFG='usbnet',2. 3. Make sure that the driver loaded for the device in Windows system is the default MBIM driver. 4. Click the network icon in the lower right corner of the host desktop to start a data call. EM12&EG12&EG18_Series_Data_Call_Application_Note 14 / 18 LTE-A Module Series Figure 3: MBIM Data Call (USB + TE + Windows + MBIM) 3.6. ECM Data Call (USB + AP + Linux) 1. Contact Quectel Technical Support for installation package of the following driver: Quectel_Linux_USB_Serial_Option_Driver (Driver for TTY port, such as AT and DM.) 2. Integrate/compile the driver on the host. To install the driver: 1) Execute make install in the driver file. 2) Please do NOT use Linux original driver (qcserial.ko) when using Quectel modules. You can check whether the Linux original driver is installed by running lsmod. If the Linux original driver is installed, you should run rmmod to uninstall the driver. Before you connect Quectel module to the host, please make sure that driver option.ko provided by Quectel is installed. 3. Connect the module to the host through USB. 4. Set the NIC data call method of the module to ECM with AT+QCFG='usbnet',1 through AT port /dev/ttyUSB2 (the third TTY port of the module) when you start the module for the first time. 5. Reboot the module. 6. After the module is rebooted, the host matches the Linux original ECM driver automatically and generates a virtual Ethernet interface usb0 based on USB. At this time, the module performs data call internally and provides network access to the host through NAT. The host only needs to send DHCP to ECM NIC to request IP address. EM12&EG12&EG18_Series_Data_Call_Application_Note 15 / 18 LTE-A Module Series 3.7. ECM Data Call (USB + AP + Windows) 1. Contact Quectel Technical Support for installation package of the ECM driver Quectel_LTE_Windows_USB_Driver_For_ECM and then install the driver. 2. Connect the module to the host through USB. 3. Set the NIC data call method of the module to ECM with AT+QCFG='usbnet',1 through AT port when you start the module for the first time. 4. Reboot the module. 5. Make sure that ECM provided by Quectel is installed and loaded for the device. Then the host generates a virtual Ethernet interface based on USB and obtains IP address through DHCP automatically. Figure 4: ECM Data Call (USB + AP + Windows) EM12&EG12&EG18_Series_Data_Call_Application_Note 16 / 18 LTE-A Module Series 4 Appendix References Table 2: Related Documents Document Name [1] Quectel_EM12&EG12&EG18_AT_Commands_Manual Table 3: Terms and Abbreviations Abbreviation AP DHCP ECM ETH IP MBIM MHI NAT NDIS NIC QMI TE UL AGG USB Description Application Processor Dynamic Host Configuration Protocol Ethernet Control Model Ethernet Internet Protocol Mobile Broadband Interface Model Modem Host Interface Network Address Translation Network Driver Interface Specification Network Interface Controller Qualcomm Message Interface Terminal Equipment Uplink Aggregation Universal Serial Bus EM12&EG12&EG18_Series_Data_Call_Application_Note 17 / 18 WLAN WWAN Wireless Local Area Network Wireless Wide Area Network LTE-A Module Series EM12&EG12&EG18_Series_Data_Call_Application_Note 18 / 18
208.90 KB
EG512R&EM12xR&EM160R Series Data Call Application Note LTE-A Module Series Version: 1.0 Date: 2022-09-17 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. EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 1 / 21 LTE-A Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 2 / 21 LTE-A Module Series About the Document Revision History Version 1.0 Date 2022-05-13 2022-09-17 Author Ozzy ANG Ozzy ANG Description Creation of the document First official release EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 3 / 21 LTE-A Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 1.1. Applicable Modules .................................................................................................................... 7 2 Data Call Methods ............................................................................................................................... 8 2.1. Classification of Data Call Scenarios......................................................................................... 8 2.2. List of Data Call Methods........................................................................................................... 9 3 Data Call Steps .................................................................................................................................. 10 3.1. NDIS Data Call (USB + TE + Windows + QMI) ....................................................................... 10 3.2. QMI_WWAN Data Call (USB + TE + Linux + QMI) ................................................................. 11 3.3. GobiNet Data Call (USB + TE + Linux + QMI) ........................................................................ 12 3.4. PCIe_MHI_Rmnet Data Call (PCIe + TE + Linux + QMI)........................................................ 13 3.5. MBIM Data Call (USB + TE + Linux + MBIM).......................................................................... 14 3.6. MBIM Data Call (USB + TE + Windows + MBIM).................................................................... 15 3.7. MBIM Data Call (PCIe + TE + Windows + MBIM) ................................................................... 16 3.8. MBIM Data Call (PCIe + TE + Linux + MBIM) ......................................................................... 16 3.9. ECM Data Call (USB + AP + Linux)......................................................................................... 17 3.10. ECM Data Call (USB + AP + Windows)................................................................................... 18 3.11. QMAP Data Call (RGMII + AP) ................................................................................................ 19 4 Appendix References ....................................................................................................................... 20 EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 4 / 21 LTE-A Module Series Table Index Table 1: Applicable Modules ........................................................................................................................ 7 Table 2: Data Call Scenarios and Corresponding Data Call Methods ........................................................ 9 Table 3: Related Documents...................................................................................................................... 20 Table 4: Terms and Abbreviations ............................................................................................................. 20 EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 5 / 21 LTE-A Module Series Figure Index Figure 1: Confirm Driver Installation .......................................................................................................... 10 Figure 2: NDIS Data Call (USB + TE + Windows + QMI) .......................................................................... 10 Figure 3: MBIM Data Call (USB + TE + Windows + MBIM) ...................................................................... 15 Figure 4: MBIM Data Call (PCIe + TE + Windows + MBIM) ...................................................................... 16 Figure 5: ECM Data Call (USB + AP + Windows) ..................................................................................... 18 EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 6 / 21 LTE-A Module Series 1 Introduction Quectel LTE-A module EG512R-EA, EM120R-GL, EM121R-GL, and EM160R-GL support data call. This document introduces the supported data call methods and the corresponding steps and notes. 1.1. Applicable Modules Table 1: Applicable Modules Applicable Modules EG512R EG512R-EA EM12xR EM120R-GL EM121R-GL EM160R EM160R-GL EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 7 / 21 LTE-A Module Series 2 Data Call Methods 2.1. Classification of Data Call Scenarios 1. By Communication Method between the host and the module in the data call: 1) QMI (Application layer communication protocol) 2) MBIM (Application layer communication protocol) 3) None (Bottom layer communication protocol of standard interface, such as Ethernet and Wi-Fi ) 2. By Interface Type used by the data call: 1) USB 2) PCIe EP (The module works as an EP device) 3) RGMII 3. By Initiator of the data call: 1) TE: The host initiates the data call. 2) AP: The module initiates the data call. 4. By Operate System of the Host in the data call: 1) Windows 2) Linux (Android) EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 8 / 21 LTE-A Module Series 2.2. List of Data Call Methods According to the classification of data call scenarios mentioned in Chapter 2.1, the data call scenarios supported by the module and the corresponding data call methods are listed in the table below. Table 2: Data Call Scenarios and Corresponding Data Call Methods Communication Interface Type Initiator Operate System of the Host Data Call Method Method USB TE Windows QMI NDIS USB TE Linux QMI QMI_WWAN/GobiNet USB TE Windows/Linux MBIM MBIM(USB) PCIe EP TE Linux QMI PCIe_MHI_Rmnet PCIe EP TE Windows/Linux MBIM PCIe_MHI_MBIM USB AP Windows - ECM USB AP Linux - ECM RGMII AP - - QMAP NOTE 1. The corresponding data call methods are named with the driver’s name. 2. Except EG512R-EA, the applicable modules support PCIe EP but do not support RGMII. EG512R-EA supports RGMII but does not support PCIe EP. 3. For detailed steps of each data call method, see Chapter 3. Refer to document [1] for details of the related AT commands, if any of these AT commands is not included, please contact Quectel Technical Support. EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 9 / 21 LTE-A Module Series 3 Data Call Steps 3.1. NDIS Data Call (USB + TE + Windows + QMI) 1. Install NDIS driver Quectel_Windows_USB_Driver(Q)_For_NDIS provided by Quectel on the host. 2. Connect the module to the host through USB cable. 3. Check whether the driver 'Quectel Wireless Ethernet Adapter' is loaded under 'Network adapters' on the host as shown in the figure below: Figure 1: Confirm Driver Installation 4. Click the network icon in the lower right corner of the host desktop to start a data call. Figure 2: NDIS Data Call (USB + TE + Windows + QMI) EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 10 / 21 LTE-A Module Series 3.2. QMI_WWAN Data Call (USB + TE + Linux + QMI) 1. Contact Quectel Technical Supports for installation packages of the following drivers and tool: 1) Quectel_Linux_USB_Serial_Option_Driver (the driver for TTY port, such as AT and DM) 2) Quectel_Linux&Android_QMI_WWAN_Driver (the driver for usbnet data port) 3) QConnectManager_Linux (the tool for data call) 2. Integrate/compile the drivers and tool on the host. To install the drivers: 1) Execute make install in the driver file. 2) If you want to perform multiple data call with the driver, add the parameter qmap_mode= in the command line when you execute command to load the driver. The maximum number of data call channels is 4. Here is an example: insmod qmi_wwan_q.ko qmap_mode=4 qmap_mode=0 indicates single data call without UL AGG. qmap_mode=1 indicates single data with UL AGG. qmap_mode=2/3/4 indicates multiple data call with UL AGG. 3) If you want to perform data call in bridge mode (that is, bridging the data call connection to other devices on the host to provide network access for these devices) with the driver, refer to the following examples in the directory log/ of quectel-CM source code package. log/how_to_use_bridge.txt Bridge mode for single data call log/how_to_use_bridge_and_QMAP.txt Bridge mode for multiple data call 4) Please do NOT use Linux original drivers (qmi_wwan.ko and qcserial.ko) when using Quectel modules. You can check whether the Linux original drivers are installed by running lsmod. If the Linux original drivers are installed, you should run rmmod to uninstall them. Before you connect Quectel module to the host, please make sure that qmi_wwan_q.ko and option.ko provided by Quectel are installed. 3. Connect the module to the host through USB. 4. Start a data call with quectel-CM. 1) Execute quectel-CM -h to check help information of quectel-CM. 2) Refer to the following examples in the directory log/ of quectel-CM source code package. qmi_wwan_q.txt qmi_wwan_q_bridge.txt qmi_wwan_q_qmap=1.txt qmi_wwan_q_qmap=1_bridge.txt Single data call in local without using QMAP Single data call in bridge mode without using QMAP Single data call in local with QMAP Single data call in bridge mode with QMAP EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 11 / 21 qmi_wwan_q_qmap=4.txt qmi_wwan_q_qmap=4_bridge.txt LTE-A Module Series QMAP multiple data call in local QMAP multiple data call in bridge mode NOTE 1. If you want to perform multiple data call, QMAP feature of the module must be enabled. 2. QMAP feature of the module is enabled by default, that is, even if qmap_mode is not configured when you load the driver, qmap_mode=1 is set automatically when you run the driver. Therefore, the examples of qmi_wwan_q.txt and qmi_wwan_q_bridge.txt are the same as qmi_wwan_q_qmap=1.txt and qmi_wwan_q_qmap=1_bridge.txt in the actual practice. 3.3. GobiNet Data Call (USB + TE + Linux + QMI) 1. Contact Quectel Technical Supports for installation package of the following drivers and tool: 1) Quectel_Linux_USB_Serial_Option_Driver (the driver for TTY port, such as AT and DM) 2) Quectel_Linux&Android_GobiNet_Driver (the driver for usbnet data port) 3) QConnectManager_Linux (the tool for data call) 2. Integrate/compile the drivers and tool on the host. To install the drivers: 1) Execute make install in the driver file. 2) If you want to perform multiple data call with the driver, add the parameter qmap_mode= in the command line when you execute command to load the driver. The maximum number of data call channels is 4. Here is an example: insmod GobiNet.ko qmap_mode=4 qmap_mode=0 indicates single data call without UL AGG. qmap_mode=1 indicates single data with UL AGG. qmap_mode=2/3/4 indicates multiple data call with UL AGG. 3) The Quectel drivers will replace the Linux original GobiNet drivers after a successful installation. Please do NOT use Linux original driver (qcserial.ko) when using Quectel modules. You can check whether the Linux original driver is installed by running lsmod. If the Linux original driver is installed, you should run rmmod to uninstall it. Before you connect Quectel module to the host, please make sure that GobiNet.ko and option.ko provided by Quectel are installed. 3. Connect the module to the host through USB. EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 12 / 21 LTE-A Module Series 4. Start a data call with quectel-CM. 1) Execute quectel-CM -h to check help information of quectel-CM. 2) Refer to the following examples in the directory log/ of quectel-CM source code package. gobinet.txt gobinet_bridge.txt gobinet_qmap=1.txt gobinet_qmap=1_bridge.txt gobinet_qmap=4.txt gobinet_qmap=4_bridge.txt Single data call in local without using QMAP Single data call in bridge mode without using QMAP QMAP single data call in local QMAP single data call in bridge mode QMAP multiple data call in local QMAP multiple data call in bridge mode NOTE 1. If you want to perform multiple data call, QMAP feature of the module must be enabled. 2. QMAP feature of the module is enabled by default, that is, even qmap_mode is not configured when you load the driver, qmap_mode=1 is set automatically when you run the driver. Therefore, the examples of gobinet.txt and gobinet_bridge.txt are the same as gobinet_qmap=1.txt and gobinet_qmap=1_bridge.txt in the actual practice. 3.4. PCIe_MHI_Rmnet Data Call (PCIe + TE + Linux + QMI) This method uses PCIe interface to start a data call. The host works as a PCIe RC and the module works as a PCIe EP. The data call steps are listed as below: 1. Contact Quectel Technical Supports for installation packages of the following driver and tool: 1) Quectel_Linux_PCIE_MHI_Driver (the driver for MHI data port) 2) QConnectManager_Linux (the tool for data call) 2. Integrate/compile the driver and tool on the host. To install the driver: 1) Execute make install in the driver file. 2) If you want to perform multiple data call with the driver, add the parameter qmap_mode= in the command line when you execute command to load the driver. The maximum number of data call channels is 4. Here is an example: insmod pcie_mhi.ko qmap_mode=4 qmap_mode=0 indicates single data call without UL AGG. qmap_mode=1 indicates single data with UL AGG. qmap_mode=2/3/4 indicates multiple data call with UL AGG. EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 13 / 21 LTE-A Module Series 3) View device port loaded by the host, /dev/mhi_DUN is AT port. 4) Before you connect the module to the host, please make sure that driver pcie_mhi.ko provided by Quectel is installed. 3. Connect the module to the host through PCIe. 4. Start a data call with quectel-CM. 1) Execute quectel-CM -h to check help information of quectel-CM. 2) Refer to the following examples in the directory log/ of quectel-CM source code package. pcie_mhi_qmap=1.txt pcie_mhi_qmap=1_bridge.txt pcie_mhi_qmap=4.txt pcie_mhi_qmap=4_bridge.txt QMAP single data call in local QMAP single data call in bridge mode QMAP multiple data call in local QMAP multiple data call in bridge mode NOTE 1. If you want to perform multiple data call, QMAP feature of the module must be enabled. 2. QMAP feature of the module is enabled by default, that is, even qmap_mode is not configured when you load the driver, qmap_mode=1 is set automatically when you run the driver. 3.5. MBIM Data Call (USB + TE + Linux + MBIM) 1. Contact Quectel Technical Supports for installation packages of the following drivers and tool: 1) Quectel_Linux_USB_Serial_Option_Driver (the driver for TTY port, such as AT and DM) 2) cdc_mbim_drv_Linux (the driver for usbnet data port) 3) QConnectManager_Linux (the tool for data call) 2. Integrate/compile the drivers and tool on the host. To install the drivers: 1) Execute make install in the driver file. 2) If you want to perform multiple data call with the driver, add the parameter mbim_qmap_mode= in the command line when you execute command to load the driver. The maximum number of data call channels is 16. Here is an example: insmod quec_cdc_mbim.ko mbim_qmap_mode=4 3) Please do NOT use Linux original driver (qcserial.ko) when using Quectel modules. You can check whether the Linux original driver is installed by running lsmod. If the Linux original driver is EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 14 / 21 LTE-A Module Series installed, you should run rmmod to uninstall it. Before you connect Quectel module to the host, please make sure that driver quec_cdc_mbim.ko provided by Quectel is installed. 3. Connect the module to the host through USB. 4. Set the NIC data call method of the module to MBIM with AT+QCFG='usbnet',2. 5. Start a data call with quectel-CM. 1) Execute quectel-CM -h to check help information of quectel-CM. 2) Refer to the following examples in the directory log/ of quectel-CM source code package. cdc_mbim.txt cdc_mbim_vlan.txt QMAP single data call in local QMAP multiple data call in local NOTE 1. If you want to perform multiple data call, QMAP feature of the module must be enabled. 2. QMAP feature of the module is enabled by default, that is, even mbim_qmap_mode is not configured when you load the driver, mbim_qmap_mode=1 is set automatically when you run the driver. 3.6. MBIM Data Call (USB + TE + Windows + MBIM) 1. Connect the module to the host through USB. 2. Set the NIC data call method of the module to MBIM with AT+QCFG='usbnet',2. 3. Make sure that the driver loaded for the device in Windows system is the default MBIM driver. 4. Click the network icon in the lower right corner of the host desktop to start a data call. Figure 3: MBIM Data Call (USB + TE + Windows + MBIM) EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 15 / 21 LTE-A Module Series 3.7. MBIM Data Call (PCIe + TE + Windows + MBIM) 1. Contact Quectel Technical Supports for the installation package of the driver Quectel_sdx55-windows-pcie-driver and then install it. 2. Connect the module to the host through PCIe. 3. Set the NIC data call method of the module to MBIM with AT+QCFG='pcie_mbim',1. 4. Make sure that the driver loaded for the device in Windows system is the one provided by Quectel. 5. Click the network icon in the lower right corner of the host desktop to start a data call. Figure 4: MBIM Data Call (PCIe + TE + Windows + MBIM) 3.8. MBIM Data Call (PCIe + TE + Linux + MBIM) This data call method uses PCIe interface to start a data call. The host works as a PCIe RC and the module works as a PCIe EP. The data call steps are listed as below: 1. Contact Quectel Technical Supports for installation packages of the following driver and tool: 1) Quectel_Linux_PCIE_MHI_Driver (the driver for MHI data port) 2) QConnectManager_Linux (the tool for data call) 2. Integrate/compile the driver and tool in the host. To install the driver: 1) Execute make install in the driver file. 2) The parameter mhi_mbim_enabled configures MBIM mode. To set the driver works in MBIM mode, add mhi_mbim_enabled=1 in the command line when you execute command to load the driver. You can also add the parameter qmap_mode= in the EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 16 / 21 LTE-A Module Series command line if you want to perform multiple data call with the driver. The maximum number of data call channels is 4. Here is an example: insmod pcie_mhi.ko mhi_mbim_enabled=1 qmap_mode=4 qmap_mode=0 indicates single data call without UL AGG. qmap_mode=1 indicates single data with UL AGG. qmap_mode=2/3/4 indicates multiple data call with UL AGG. 3) View device port loaded by the host, /dev/mhi_DUN is AT port. 4) Before you connect the module to the host, please make sure that driver pcie_mhi.ko provided by Quectel is installed. 3. Connect the module to the host through PCIe. 4. Set the NIC data call method of the module to MBIM with AT+QCFG='pcie_mbim',1. 5. Start a data call with quectel-CM. 1) Execute quectel-CM -h to check help information of quectel-CM. 2) Refer to the following examples in the directory log/ of quectel-CM source code package. pcie_mhi_mbim.txt pcie_mhi_mbim_qmap=4.txt QMAP single data call in local QMAP multiple data call in local NOTE 1. If you want to perform multiple data call, QMAP feature of the module must be enabled. 2. QMAP feature of the module is enabled by default, that is, even qmap_mode is not configured when you load the driver, qmap_mode=1 is set automatically when you run the driver. 3.9. ECM Data Call (USB + AP + Linux) 1. Contact Quectel Technical Supports for the installation package of the following driver: Quectel_Linux_USB_Serial_Option_Driver (the driver for TTY port, such as AT and DM) 2. Integrate/compile the driver on the host. To install the driver: 1) Execute make install in the driver file. 2) Please do NOT use Linux original driver (qcserial.ko) when using Quectel modules. You can check whether the Linux original driver is installed by running lsmod. If the Linux original driver is EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 17 / 21 LTE-A Module Series installed, you should run rmmod to uninstall it. Before you connect Quectel module to the host, please make sure that driver option.ko provided by Quectel is installed. 3. Connect the module to the host through USB. 4. Set the NIC data call method of the module to ECM with AT+QCFG='usbnet',1 through AT port /dev/ttyUSB2 (the third TTY port of the module) when you start the module for the first time. 5. Reboot the module. 6. After the module is rebooted, the host matches the Linux original ECM driver automatically and generates a virtual Ethernet interface usb0 based on USB. At this time, the module performs data call internally and provides network access to the host through NAT. The host only needs to send DHCP to ECM NIC to request IP address. 3.10. ECM Data Call (USB + AP + Windows) 1. Contact Quectel Technical Supports for the installation package of the ECM driver Quectel_LTE_Windows_USB_Driver_For_ECM and then install it. 2. Connect the module to the host through USB. 3. Set the NIC data call method of the module to ECM with AT+QCFG='usbnet',1 through AT port when you start the module for the first time. 4. Reboot the module. 5. Make sure that the ECM driver provided by Quectel is installed and ECM is loaded for the device. Then the host generates a virtual Ethernet interface based on USB and obtains IP address through DHCP automatically. Figure 5: ECM Data Call (USB + AP + Windows) EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 18 / 21 LTE-A Module Series 3.11. QMAP Data Call (RGMII + AP) 1. Contact Quectel Technical Supports for the installation package of the following driver: Quectel_Linux_USB_Serial_Option_Driver (the driver for TTY port, such as AT and DM) 2. Integrate/compile the driver on the host. To install the driver: 1) Execute make install in the driver file. 2) Please do NOT use Linux original driver (qcserial.ko) when using Quectel modules. You can check whether the Linux original driver is installed by running lsmod. If the Linux original driver is installed, you should run rmmod to uninstall it. Before you connect Quectel module to the host, please make sure that driver option.ko provided by Quectel is installed. 3. Reboot the module and configure target interface. 1) Enable RGMII NIC with AT+QETH='rgmii'. 2) Enable data call with AT+QMAP. You can also enable IP Passthrough as needed with AT+QMAP. NOTE RGMII is supported by EG512R-EA only. EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 19 / 21 LTE-A Module Series 4 Appendix References Table 3: Related Documents Document Name [1] Quectel_EG512R&EM1x0R_Series_AT_Commands_Manual Table 4: Terms and Abbreviations Abbreviation AP DHCP ECM ETH IP MBIM MHI NAT NDIS PCIe EP PCIe RC QMI RGMII TE Description Application Processor Dynamic Host Configuration Protocol Ethernet Control Model Ethernet Internet Protocol Mobile Broadband Interface Model Modem Host Interface Network Address Translation Network Driver Interface Specification PCI Express Endpoint Device PCI Express Root Complex Qualcomm Message Interface Reduced Gigabit Media Independent Interface Terminal Equipment EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 20 / 21 UL AGG USB WLAN WWAN Uplink Aggregation Universal Serial Bus Wireless Local Area Network Wireless Wide Area Network LTE-A Module Series EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note 21 / 21
253.49 KB
EG06xK&Ex120K&EM060K Series Data Call Application Note LTE-A Module Series Version: 1.0 Date: 2022-09-17 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_Data_Call_Application_Note 1 / 18 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. 2022. All rights reserved. EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 2 / 18 LTE-A Module Series About the Document Revision History Version 1.0 Date 2022-05-13 2022-09-17 Author Ozzy ANG Ozzy ANG Description Creation of the document First official release EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 3 / 18 LTE-A Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 1.1. Applicable Modules .................................................................................................................... 7 2 Data Call Methods ............................................................................................................................... 8 2.1. Classification of Data Call Scenarios......................................................................................... 8 2.2. List of Data Call Methods........................................................................................................... 9 3 Data Call Steps .................................................................................................................................. 10 3.1. NDIS Data Call (USB + TE + Windows + QMI) ....................................................................... 10 3.2. QMI_WWAN Data Call (USB + TE + Linux + QMI) ................................................................. 11 3.3. GobiNet Data Call (USB + TE + Linux + QMI) ........................................................................ 12 3.4. MBIM Data Call (USB + TE + Linux + MBIM).......................................................................... 13 3.5. MBIM Data Call (USB + TE + Windows + MBIM).................................................................... 14 3.6. ECM Data Call (USB + AP + Linux)......................................................................................... 15 3.7. ECM Data Call (USB + AP + Windows)................................................................................... 15 3.8. QMAP Data Call (PCIe RC + AP) ............................................................................................ 16 4 Appendix References ....................................................................................................................... 17 EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 4 / 18 LTE-A Module Series Table Index Table 1: Applicable Modules ........................................................................................................................ 7 Table 2: Data Call Scenarios and Corresponding Data Call Methods ........................................................ 9 Table 3: Related Documents...................................................................................................................... 17 Table 4: Terms and Abbreviations ............................................................................................................. 17 EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 5 / 18 LTE-A Module Series Figure Index Figure 1: Confirm Driver Installation .......................................................................................................... 10 Figure 2: NDIS Data Call (USB + TE + Windows + QMI) .......................................................................... 10 Figure 3: MBIM Data Call (USB + TE + Windows + MBIM) ...................................................................... 14 Figure 4: ECM Data Call (USB + AP + Windows) ..................................................................................... 16 EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 6 / 18 LTE-A Module Series 1 Introduction Quectel LTE-A EG060K series, EG065K series, EG120K series, EM120K-GL, and EM060K series support data call. This document introduces the supported data call methods and the corresponding steps and notes. 1.1. Applicable Modules Table 1: Applicable Modules Applicable Modules EG06xK EG060K Series EG065K Series Ex120K EG120K Series EM120K-GL EM060K EM060K Series EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 7 / 18 LTE-A Module Series 2 Data Call Methods 2.1. Classification of Data Call Scenarios 1. By Communication Method between the host and the module in the data call: 1) QMI (Application layer communication protocol) 2) MBIM (Application layer communication protocol) 3) None (Bottom layer communication protocol of standard interface, such as Ethernet and Wi-Fi) 2. By Interface Type used by the data call: 1) USB 2) PCIe RC (The module works as a RC device) a) ETH b) WLAN (Wi-Fi) 3. By Initiator of the data call: 1) TE: The host initiates the data call. 2) AP: The module initiates the data call. 4. By Operate System of the Host in the data call: 1) Windows 2) Linux (Android) EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 8 / 18 LTE-A Module Series 2.2. List of Data Call Methods According to the classification of data call scenarios mentioned in Chapter 2.1, the data call scenarios supported by the module and the corresponding data call methods are listed in the table below. Table 2: Data Call Scenarios and Corresponding Data Call Methods Interface Type USB Communication Initiator Operate System of the Host Data Call Method Method TE Windows QMI NDIS USB TE Linux QMI QMI_WWAN/GobiNet USB TE Windows/Linux MBIM MBIM(USB) USB AP Windows - ECM USB AP Linux - ECM PCIe RC AP - - QMAP NOTE 1. The corresponding data call methods are named with the driver’s name. 2. For detailed steps of each data call method, see Chapter 3. Refer to document [1] for details of the related AT commands, if any of these AT commands is not included, please contact Quectel Technical Support. EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 9 / 18 LTE-A Module Series 3 Data Call Steps 3.1. NDIS Data Call (USB + TE + Windows + QMI) 1. Install NDIS driver Quectel_Windows_USB_Driver(Q)_For_NDIS provided by Quectel on the host. 2. Connect the module to the host through USB cable. 3. Check whether the driver 'Quectel Wireless Ethernet Adapter' is loaded under 'Network adapters' on the host as shown in the figure below: Figure 1: Confirm Driver Installation 4. Click the network icon in the lower right corner of the host desktop to start a data call. Figure 2: NDIS Data Call (USB + TE + Windows + QMI) EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 10 / 18 LTE-A Module Series 3.2. QMI_WWAN Data Call (USB + TE + Linux + QMI) 1. Contact Quectel Technical Supports for installation packages of the following drivers and tool: 1) Quectel_Linux_USB_Serial_Option_Driver (the driver for TTY port, such as AT and DM) 2) Quectel_Linux&Android_QMI_WWAN_Driver (the driver for usbnet data port) 3) QConnectManager_Linux (the tool for data call) 2. Integrate/compile the drivers and tool on the host. To install the drivers: 1) Execute make install in the driver file. 2) If you want to perform multiple data call with the driver, add the parameter qmap_mode= in the command line when you execute command to load the driver. The maximum number of data call channels is 4. Here is an example: insmod qmi_wwan_q.ko qmap_mode=4 qmap_mode=0 indicates single data call without UL AGG. qmap_mode=1 indicates single data with UL AGG. qmap_mode=2/3/4 indicates multiple data call with UL AGG. 3) If you want to perform data call in bridge mode (that is, bridging the data call connection to other devices on the host to provide network access for these devices) with the driver, refer to the following examples in the directory log/ of quectel-CM source code package. log/how_to_use_bridge.txt Bridge mode for single data call log/how_to_use_bridge_and_QMAP.txt Bridge mode for multiple data call 4) Please do NOT use Linux original drivers (qmi_wwan.ko and qcserial.ko) when using Quectel modules. You can check whether the Linux original drivers are installed by running lsmod. If Linux original drivers are installed, you should run rmmod to uninstall them. Before you connect Quectel module to the host, please make sure that qmi_wwan_q.ko and option.ko provided by Quectel are installed. 3. Connect the module to the host through USB. 4. Start a data call with quectel-CM. 1) Execute quectel-CM -h to check help information of quectel-CM. 2) Refer to the following examples in the directory log/ of quectel-CM source code package. qmi_wwan_q.txt qmi_wwan_q_bridge.txt qmi_wwan_q_qmap=1.txt qmi_wwan_q_qmap=1_bridge.txt Single data call in local without using QMAP Single data call in bridge mode without using QMAP Single data call in local with QMAP Single data call in bridge mode with QMAP EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 11 / 18 qmi_wwan_q_qmap=4.txt qmi_wwan_q_qmap=4_bridge.txt LTE-A Module Series QMAP multiple data call in local QMAP multiple data call in bridge mode NOTE 1. If you want to perform multiple data call, QMAP feature of the module must be enabled. 2. QMAP feature of the module is enabled by default, that is, even if qmap_mode is not configured when you load the driver, qmap_mode=1 is set automatically when you run the driver. Therefore, the examples of qmi_wwan_q.txt and qmi_wwan_q_bridge.txt are the same as qmi_wwan_q_qmap=1.txt and qmi_wwan_q_qmap=1_bridge.txt in the actual practice. 3.3. GobiNet Data Call (USB + TE + Linux + QMI) 1. Contact Quectel Technical Supports for installation packages of the following drivers and tool: 1) Quectel_Linux_USB_Serial_Option_Driver (the driver for TTY port, such as AT and DM) 2) Quectel_Linux&Android_GobiNet_Driver (the driver for usbnet data port) 3) QConnectManager_Linux (the tool for data call) 2. Integrate/compile the drivers and tool on the host. To install the drivers: 1) Execute make install in the driver file. 2) If you want to perform multiple data call with the driver, add the parameter qmap_mode= in the command line when you execute command to load the driver. The maximum number of data call channels is 4. Here is an example: insmod GobiNet.ko qmap_mode=4 qmap_mode=0 indicates single data call without UL AGG. qmap_mode=1 indicates single data with UL AGG. qmap_mode=2/3/4 indicates multiple data call with UL AGG. 3) The Quectel drivers will replace the Linux original GobiNet drivers after a successful installation. Please do NOT use Linux original driver (qcserial.ko) when using Quectel modules. You can check whether the Linux original driver is installed by running lsmod. If the Linux original driver is installed, you should run rmmod to uninstall it. Before you connect Quectel module to the host, please make sure that GobiNet.ko and option.ko provided by Quectel are installed. 3. Connect the module to the host through USB. EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 12 / 18 LTE-A Module Series 4. Start a data call with quectel-CM. 1) Execute quectel-CM -h to check help information of quectel-CM. 2) Refer to the following examples in the directory log/ of quectel-CM source code package. gobinet.txt gobinet_bridge.txt gobinet_qmap=1.txt gobinet_qmap=1_bridge.txt gobinet_qmap=4.txt gobinet_qmap=4_bridge.txt Single data call in local without using QMAP Single data call in bridge mode without using QMAP QMAP single data call in local QMAP single data call in bridge mode QMAP multiple data call in local QMAP multiple data call in bridge mode NOTE 1. If you want to perform multiple data call, QMAP feature of the module must be enabled. 2. QMAP feature of the module is enabled by default, that is, even qmap_mode is not configured when you load the driver, qmap_mode=1 is set automatically when you run the driver. Therefore, the examples of gobinet.txt and gobinet_bridge.txt are the same as gobinet_qmap=1.txt and gobinet_qmap=1_bridge.txt in the actual practice. 3.4. MBIM Data Call (USB + TE + Linux + MBIM) 1. Contact Quectel Technical Supports for installation packages of the following drivers and tool: 1) Quectel_Linux_USB_Serial_Option_Driver (the driver for TTY port, such as AT and DM) 2) cdc_mbim_drv_Linux (the driver for usbnet data port) 3) QConnectManager_Linux (the tool for data call) 2. Integrate/compile the drivers and tool on the host. To install the drivers: 1) Execute make install in the driver file. 2) If you want to perform multiple data call with the driver, add the parameter mbim_qmap_mode= in the command line when you execute command to load the driver. The maximum number of data call channels is 16. Here is an example: insmod quec_cdc_mbim.ko mbim_qmap_mode=4 3) Please do NOT use Linux original driver (qcserial.ko) when using Quectel modules. You can check whether the Linux original driver is installed by running lsmod. If the Linux original driver is installed, you should run rmmod to uninstall it. Before you connect Quectel module to the host, please make sure that driver quec_cdc_mbim.ko provided by Quectel is installed. EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 13 / 18 LTE-A Module Series 3. Connect the module to the host through USB. 4. Set the NIC data call method of the module to MBIM with AT+QCFG='usbnet',2. 5. Start a data call with quectel-CM. 1) Execute quectel-CM -h to check help information of quectel-CM. 2) Refer to the following examples in the directory log/ of quectel-CM source code package. cdc_mbim.txt cdc_mbim_vlan.txt QMAP single data call in local QMAP multiple data call in local NOTE 1. If you want to perform multiple data call, QMAP feature of the module must be enabled. 2. QMAP feature of the module is enabled by default, that is, even mbim_qmap_mode is not configured when you load the driver, mbim_qmap_mode=1 is set automatically when you run the driver. 3.5. MBIM Data Call (USB + TE + Windows + MBIM) 1. Connect the module to the host through USB. 2. Set the NIC data call method of the module to MBIM with AT+QCFG='usbnet',2. 3. Make sure that the driver loaded for the device in Windows system is the default MBIM driver. 4. Click the network icon in the lower right corner of the host desktop to start a data call. Figure 3: MBIM Data Call (USB + TE + Windows + MBIM) EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 14 / 18 LTE-A Module Series 3.6. ECM Data Call (USB + AP + Linux) 1. Contact Quectel Technical Supports for the installation package of the following driver: Quectel_Linux_USB_Serial_Option_Driver (the driver for TTY port, such as AT and DM) 2. Integrate/compile the driver on the host. To install the driver: 1) Execute make install in the driver file. 2) Please do NOT use Linux original driver (qcserial.ko) when using Quectel modules. You can check whether the Linux original driver is installed by running lsmod. If the Linux original driver is installed, you should run rmmod to uninstall it. Before you connect Quectel module to the host, please make sure that driver option.ko provided by Quectel is installed. 3. Connect the module to the host through USB. 4. Set the NIC data call method of the module to ECM with AT+QCFG='usbnet',1 through AT port /dev/ttyUSB2 (the third TTY port of the module) when you start the module for the first time. 5. Reboot the module. 6. After the module is rebooted, the host matches the Linux original ECM driver automatically and generates a virtual Ethernet interface usb0 based on USB. At this time, the module performs data call internally and provides network access to the host through NAT. The host only needs to send DHCP to ECM NIC to request IP address. 3.7. ECM Data Call (USB + AP + Windows) 1. Contact Quectel Technical Supports for the installation package of the ECM driver Quectel_LTE_Windows_USB_Driver_For_ECM and then install it. 2. Connect the module to the host through USB. 3. Set the NIC data call method of the module to ECM with AT+QCFG='usbnet',1 through AT port when you start the module for the first time. 4. Reboot the module. 5. Make sure that the ECM driver provided by Quectel is installed and ECM is loaded for the device. Then the host generates a virtual Ethernet interface based on USB and obtains IP address through DHCP automatically. EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 15 / 18 LTE-A Module Series Figure 4: ECM Data Call (USB + AP + Windows) 3.8. QMAP Data Call (PCIe RC + AP) 1. Contact Quectel Technical Supports for the installation package of the following driver: Quectel_Linux_USB_Serial_Option_Driver (the driver for TTY port, such as AT and DM) 2. Integrate/compile the driver on the host. To install the driver: 1) Execute make install in the driver file. 2) Please do NOT use Linux original driver (qcserial.ko) when using Quectel modules. You can check whether the Linux original driver is installed by running lsmod. If the Linux original driver is installed, you should run rmmod to uninstall it. Before you connect Quectel module to the host, please make sure that driver option.ko provided by Quectel is installed. 3. Reboot the module and configure the target interface. 1) Enable the corresponding PHY driver with AT+QETH='eth_driver'. 2) Enable data call with AT+QMAP. You can also enable IP Passthrough as needed with AT+QMAP. EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 16 / 18 LTE-A Module Series 4 Appendix References Table 3: Related Documents Document Name [1] Quectel_EG06xK&Ex120K&EM060K_Series_AT_Commands_Manual Table 4: Terms and Abbreviations Abbreviation AP DHCP ECM ETH IP MBIM MHI NAT NDIS PCIe EP PCIe RC QMI TE UL AGG Description Application Processor Dynamic Host Configuration Protocol Ethernet Control Model Ethernet Internet Protocol Mobile Broadband Interface Model Modem Host Interface Network Address Translation Network Driver Interface Specification PCI Express Endpoint Device PCI Express Root Complex Qualcomm Message Interface Terminal Equipment Uplink Aggregation EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 17 / 18 USB WLAN WWAN Universal Serial Bus Wireless Local Area Network Wireless Wide Area Network LTE-A Module Series EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note 18 / 18
226.81 KB
EG060V-EA RF FTM Application Note LTE-A Module Series Version: 1.0 Date: 2022-08-22 Status: Released LTE-A Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. EG060V-EA_RF_FTM_Application_Note 1 / 14 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. 2022. All rights reserved. EG060V-EA_RF_FTM_Application_Note 2 / 14 LTE-A Module Series About the Document Revision History Revision Date - 2022-04-09 1.0 2022-08-22 Author Description Martin WANG/ Creation of the document Paddy LI Paddy LI First official release EG060V-EA_RF_FTM_Application_Note 3 / 14 LTE-A 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. RF FTM-Related AT Commands................................................................................................ 8 2.3.1. AT+QRFTESTMODE Enter/Exit FTM .......................................................................... 8 2.3.2. AT+QRXFTM Force to Receive in FTM ....................................................................... 9 2.3.3. AT+QRFTEST Force to Transmit in FTM................................................................... 10 3 Example ............................................................................................................................................. 12 3.1. Force to Receive in FTM.......................................................................................................... 12 3.2. Force to Transmit in FTM......................................................................................................... 12 4 Summary of CME ERROR Codes .................................................................................................... 13 5 Appendix Reference ......................................................................................................................... 14 EG060V-EA_RF_FTM_Application_Note 4 / 14 LTE-A Module Series Table Index Table 1: Types of AT Commands ................................................................................................................. 7 Table 2: LTE Force-to-Receive Channel Distribution................................................................................. 10 Table 3: LTE Force-to-Transmit Channel Distribution .................................................................................11 Table 4: CME ERROR Codes .................................................................................................................... 13 Table 5: Terms and Abbreviations .............................................................................................................. 14 EG060V-EA_RF_FTM_Application_Note 5 / 14 LTE-A Module Series 1 Introduction This document describes how to test the force-to receive and force-to-transmit performances of Quectel EG060V-EA module in Factory Test Mode (FTM) through AT commands. EG060V-EA_RF_FTM_Application_Note 6 / 14 LTE-A 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 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 1: Types of AT Commands Command Type Syntax Description Test Command AT+=? Test the existence of corresponding command and return information about the type, value, or range of its parameter. Read Command AT+? Check the current parameter value of a corresponding Write 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. EG060V-EA_RF_FTM_Application_Note 7 / 14 LTE-A 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. RF FTM-Related AT Commands 2.3.1. AT+QRFTESTMODE Enter/Exit FTM This command controls the module to enter/exit FTM. AT+QRFTESTMODE Enter/Exit FTM Test Command AT+QRFTESTMODE=? Response +QRFTESTMODE: (list of supported s) Read Command AT+QRFTESTMODE? OK Response +QRFTESTMODE: Write Command AT+QRFTESTMODE= OK Response OK If there is any error: ERROR Maximum Response Time Characteristics If the error is related to ME functionality: +CME ERROR: 300 ms This command takes effect immediately. The configuration is not saved. Parameter Integer type 0 Exit FTM 1 Enter FTM EG060V-EA_RF_FTM_Application_Note 8 / 14 LTE-A Module Series Integer type. Error codes. See Chapter 4 for details. 2.3.2. AT+QRXFTM Force to Receive in FTM This command forces the module to receive signals in FTM. AT+QRXFTM Force to Receive in FTM Test Command AT+QRXFTM=? Write Command AT+QRXFTM=,,,[,] Response OK Response +QRXFTM: , OK If there is any error: ERROR Maximum Response Time Characteristics If the error is related to ME functionality: +CME ERROR: 300 ms This command takes effect immediately. The configuration is not saved. Parameter String type. LTE bands supported by the module. See Table 2 for details. Integer type. LTE force-to-receive channel numbers supported by the module. See Table 2 for details. String type. Enable/disable force-to-receive function in FTM. 'on' Enable 'off' Disable Integer type. The state of LNA AGC, which is relevant to the signal strength absolute value set on instrument. 0 When signal strength to be measured is set within -35 dBm to -65 dBm on instrument 1 When signal strength to be measured is set within -45 dBm to -75 dBm on instrument Integer type. LTE bandwidth. The default value is 0. Currently only 0 is supported. 0 1.4 MHz Integer type. Primary RX RSSI, only applicable for LTE. Unit: dBm. Integer type. Diversity RX RSSI, only applicable for LTE. Unit: dBm. EG060V-EA_RF_FTM_Application_Note 9 / 14 LTE-A Module Series Integer type. Error codes. See Chapter 4 for details. Table 2: LTE Force-to-Receive Channel Distribution LTE Bands 'LTE BAND1' 'LTE BAND3' 'LTE BAND5' 'LTE BAND7' 'LTE BAND8' 'LTE BAND20' 'LTE BAND28' 'LTE BAND38' 'LTE BAND40' 'LTE BAND41' Force-to-Receive Channel Numbers 300 1575 2525 3100 3625 6300 9435 38000 39150 40620 2.3.3. AT+QRFTEST Force to Transmit in FTM This command forces the module to transmit signals in FTM. AT+QRFTEST Force to Transmit in FTM Test Command AT+QRFTEST=? Write Command AT+QRFTEST=,,, Response OK Response OK If there is any error: ERROR Maximum Response Time Characteristics If the error is related to ME functionality: +CME ERROR: 300 ms This command takes effect immediately. EG060V-EA_RF_FTM_Application_Note 10 / 14 LTE-A Module Series The configuration is not saved. Parameter String type. LTE bands supported by the module. See Table 3 for details. Integer type. LTE force-to-transmit channel numbers supported by the module. See Table 3 for details. String type. Enable/disable force-to-transmit function in FTM. 'on' Enable 'off' Disable Integer type. LTE transmit power gain index. Range: 0–2047. 1900 is recommended. Integer type. Error codes. See Chapter 4 for details. Table 3: LTE Force-to-Transmit Channel Distribution LTE Bands 'LTE BAND1' 'LTE BAND3' 'LTE BAND5' 'LTE BAND7' 'LTE BAND8' 'LTE BAND20' 'LTE BAND28' 'LTE BAND38' 'LTE BAND40' 'LTE BAND41' Force-to-Transmit Channel Numbers 18300 19575 20525 21100 21625 24300 27435 38000 39150 40620 EG060V-EA_RF_FTM_Application_Note 11 / 14 LTE-A Module Series 3 Example 3.1. Force to Receive in FTM AT+QRFTESTMODE? +QRFTESTMODE: 0 OK AT+QRFTESTMODE=1 OK AT+QRXFTM='LTE BAND1',300,'on',1 +QRXFTM: -75,-80 OK AT+QRXFTM='LTE BAND1',300,'off',1 OK AT+QRFTESTMODE=0 OK //Query whether the module is currently in FTM. //Enter FTM. //Test downlink channel number 300 for LTE BAND1. //Disable force-to-receive test function of LTE BAND1 //Exit FTM. 3.2. Force to Transmit in FTM AT+QRFTESTMODE? +QRFTESTMODE: 0 //Query whether the module is currently in FTM. OK AT+QRFTESTMODE=1 OK AT+QRFTEST='LTE BAND1',18300,'on',2000 OK AT+QRFTEST='LTE BAND1',18300,'off',2000 OK AT+QRFTESTMODE=0 OK //Enter FTM. //Test uplink channel number 18300 for LTE BAND1. //Disable force-to-transmit test function of LTE //Exit FTM. EG060V-EA_RF_FTM_Application_Note 12 / 14 LTE-A Module Series 4 Summary of CME ERROR Codes The error code indicates an error related to mobile equipment. The details about are described in the following table. Table 4: CME ERROR Codes Code of 3 4 16 20 21 22 23 Meaning Operation not allowed Operation not supported Incorrect password Memory full Invalid index Not found Memory failure EG060V-EA_RF_FTM_Application_Note 13 / 14 LTE-A Module Series 5 Appendix Reference Table 5: Terms and Abbreviations Abbreviation AGC DRX FTM LNA LTE PRX RF RSSI RX TX Description Automatic Gain Control Diversity Receive Factory Test Mode Low Noise Amplifier Long Term Evolution Primary Receive Radio Frequency Received Signal Strength Indicator Receive Transmit EG060V-EA_RF_FTM_Application_Note 14 / 14
170.58 KB
BG95&BG77&BG600L Series GTP Application Note LPWA Module Series Version: 1.0 Date: 2022-07-28 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG95&BG77&BG600L_Series_GTP_Application_Note 1 / 19 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG95&BG77&BG600L_Series_GTP_Application_Note 2 / 19 LPWA Module Series About the Document Revision History Version Date Author Description - 2022-04-27 Matt YE Creation of the document 1.0 2022-07-28 Matt YE First official release BG95&BG77&BG600L_Series_GTP_Application_Note 3 / 19 LPWA Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 5 Figure Index ................................................................................................................................................. 6 1 Introduction .......................................................................................................................................... 7 1.1. GTP Architecture ......................................................................................................................... 7 1.2. Supported GTP Versions ............................................................................................................ 7 1.3. GTP Operation ............................................................................................................................ 8 1.3.1. GTP Operation Flow ........................................................................................................ 8 1.3.2. GNSS Operation Flow with GTP and XTRA .................................................................... 9 2 Description of GNSS 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. AT Commands Description .................................................................................................... 12 2.3.1. AT+QGPSCFG='gtp_fun' Enable/Disable GTP Feature ............................................ 12 2.3.2. AT+QGPSONE Attempt a Single Position Fix ............................................................ 13 3 Examples ............................................................................................................................................ 16 3.1. GTP Operation .......................................................................................................................... 16 3.2. GNSS Operation with GTP and XTRA ..................................................................................... 16 4 Summary of Error Codes .................................................................................................................. 17 5 Appendix References ........................................................................................................................ 19 BG95&BG77&BG600L_Series_GTP_Application_Note 4 / 19 LPWA Module Series Table Index Table 1: Types of AT Commands ...............................................................................................................11 Table 2: Summary of Error Codes ............................................................................................................. 17 Table 3: Related Document ....................................................................................................................... 19 Table 4: Terms and Abbreviations ............................................................................................................. 19 BG95&BG77&BG600L_Series_GTP_Application_Note 5 / 19 LPWA Module Series Figure Index Figure 1: GTP Architecture........................................................................................................................... 7 Figure 2: GTP Operation Flow (XTRA Disabled) ......................................................................................... 8 Figure 3: GNSS Operation Flow with GTP and XTRA................................................................................. 9 BG95&BG77&BG600L_Series_GTP_Application_Note 6 / 19 LPWA Module Series 1 Introduction Quectel BG95 series, BG77 and BG600L-M3 modules integrate GTP feature with the GNSS engine to ensure better positioning performance. The modules support both GTP 1.0 and GTP 2.0 versions. GTP feature is a cellular positioning technology that is disabled by default. If you want to use it, please confirm whether it is supported in the current area by GTP service provider. NOTE GTP feature is supported only on specified firmware versions of the modules. Please contact Quectel Technical Support (support@quectel.com) for more detailed information. 1.1. GTP Architecture Module GTP request with cell observations Network GTP response with location of cell towers GTP server Figure 1: GTP Architecture 1.2. Supported GTP Versions GTP 1.0 ⚫ Supported RATs: GSM, LTE-M and NB-IoT ⚫ Serving-cell only (a single registered cell ID) ⚫ Performance varies across RATs and operators BG95&BG77&BG600L_Series_GTP_Application_Note 7 / 19 LPWA Module Series GTP 2.0 ⚫ Supported RATs: GSM, LTE-M and NB-IoT ⚫ Multi-cell scan (across RATs and bands) ⚫ Improved accuracy compared to GTP 1.0; uniform performance across RATs and operators 1.3. GTP Operation GTP can be used alone or together with XTRA. XTRA provides predicted orbit data (GNSS assistance data) but does not provide reference position. GTP can provide an initial reference position for improved GNSS TTFF performance (similar to AGPS) compared to TTFF achieved using XTRA only. This improvement is prominent in challenging signal conditions, whereas it may be limited in a strong signal environment. 1.3.1. GTP Operation Flow The following flow is triggered by AT+QGPSONE=1, with XTRA disabled. Module GTP Server Establish a TLS connection A HTTP POST (GTPA Request) B HTTP RESPONSE (GTPA Response) C Close the TLS connection D Figure 2: GTP Operation Flow (XTRA Disabled) A: The module will establish a TLS connection to the GTP server, if the currently observed cell information is not the one that is cached by the module in the last positioning. B: The module initiates a GTPA Request to upload the currently observed cell information, module status, etc. to the GTP server. C: The GTP server responds with a GTPA Response message with location information. D: The module closes the TLS connection. BG95&BG77&BG600L_Series_GTP_Application_Note 8 / 19 LPWA Module Series 1.3.2. GNSS Operation Flow with GTP and XTRA The following flow is triggered by AT+QGPS=1 (see document [1] for details) or AT+QGPSONE=0. Module GTP Server Establish a TLS connection A HTTP POST (GTPA Request) B HTTP RESPONSE (GTPA Response) C Close the TLS connection D HTTP REQUEST E HTTP RESPONSE (XTRA File) F G Inject reference position H Inject XTRA data I GNSS starts positioning XTRA Server Figure 3: GNSS Operation Flow with GTP and XTRA A: The module will establish a TLS connection to the GTP server, if the currently observed cell information is not the one that is cached by the module in the last positioning. B: The module initiates a GTPA Request to upload the currently observed cell information, module status, etc. to the GTP server. C: The GTP server responds with a GTPA Response message with location information. D: The module closes the TLS connection. E: The module requests an XTRA file download. F: The XTRA server responds with XTRA file which includes the current GNSS assistance data. G: The module injects reference position to the GNSS engine. H: The module inject XTRA data to the GNSS engine. I: GNSS starts positioning. BG95&BG77&BG600L_Series_GTP_Application_Note 9 / 19 LPWA Module Series NOTE Make sure that XTRA time is synchronized from network or injected manually before executing AT+QGPS=1 or AT+QGPSONE=0. See document [1] for more detailed information. BG95&BG77&BG600L_Series_GTP_Application_Note 10 / 19 LPWA Module Series 2 Description of GNSS AT Commands 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings , unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 1: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. BG95&BG77&BG600L_Series_GTP_Application_Note 11 / 19 LPWA Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about how to use the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendation or suggestions about how 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 and that they should be executed in a given sequence. 2.3. AT Commands Description 2.3.1. AT+QGPSCFG='gtp_fun' Enable/Disable GTP Feature This command enables or disables GTP feature. AT+QGPSCFG='gtp_fun' Enable/Disable GTP Feature Test Command AT+QGPSCFG=? Response … +QGPSCFG: 'gtp_fun',(list of supported s) ... Write Command AT+QGPSCFG='gtp_fun'[,] OK Response If the optional parameter is omitted, query the current setting: +QGPSCFG: 'gtp_fun', OK If the optional parameter is specified, enable/disable GTP feature: OK Maximum Response Time Characteristics If there is any error: +CME ERROR: 300 ms The command takes effect after the module is rebooted. The configurations are saved automatically. Parameter Integer type. Enable/Disable GTP feature. 0 Disable 1 Enable BG95&BG77&BG600L_Series_GTP_Application_Note 12 / 19 Integer type. Error code. See Chapter 3 for details. LPWA Module Series 2.3.2. AT+QGPSONE Attempt a Single Position Fix This command attempts a single position fix and obtains a single location information. Before executing the command, deactivate GNSS, if it is active. AT+QGPSONE Attempt a Single Position Fix Test Command AT+QGPSONE=? Response +QGPSONE: (list of supporteds),(range of supported s),(range of supported s) Write Command AT+QGPSONE=,[,] OK Response OK If the location information is not successfully obtained: +QGPSURC: 'single_shot',,,,, If the location information is successfully obtained: +QGPSURC: 'single_shot',,,,, Maximum Response Time Characteristics If there is any error: +CME ERROR: 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. Requested location mode. URC will be reported once the location information is successfully obtained, or after . 0 Use GNSS for positioning 1 Use GTP for positioning Integer type. Desired accuracy level acceptable for fix computation. URC +QGPSURC: 'single_shot',,,,, will be output when the accuracy of the acquired position is greater than the set threshold or the timeout for single position fix exceeds the value of . When =0: 0 No accuracy threshold BG95&BG77&BG600L_Series_GTP_Application_Note 13 / 19 LPWA Module Series 1 Low accuracy threshold: 1000 m 2 Medium accuracy threshold: 500 m 3 High accuracy threshold: 100 m When =1: 0 No accuracy threshold (GTP 2.0) 1 Low accuracy threshold (GTP 1.0): 1000 m 2 Medium accuracy threshold (GTP 2.0): 500 m 3 High accuracy threshold (GTP 2.0): 100 m Integer type. Timeout of single position fix. Range: 20–600. Default value: 60. Unit: second. String type. Current UTC time. Format: yyyy/mm/dd hh:mm:ss. Float type. Latitude. Format: ±dd.dddddd. Range: -90.000000 – 90.000000 Float type. Longitude. Format: ±ddd.dddddd. Range: -180.000000 – 180.000000 Float type. Height above sea level, correct to one decimal place. Unit: meter. Float type. Positioning accuracy. Unit: meter. Error code. See Chapter 3 for details. NOTE 1. AT+QGPSONE=0, also triggers XTRA file downloading. To use XTRA, make sure that XTRA time is injected first. See document [1] for more information of XTRA. 2. To get location information via GTP, enable GTP feature with AT+QGPSCFG='gtp_fun',1 first. 3. To get location information via GNSS ONLY, disable GTP feature with AT+QGPSCFG='gtp_fun',0. 4. One module only can access to the GTP server up to 255 times per day. 5. If the currently observed cell information is the same one with that cached by the module in the last positioning, the module starts positioning with the cached location information directly, without accessing to GTP server. Deleting the cached information with AT+QGPSDEL=0 can make the module access GTP server, but this will cause GTP failure. In this case, execute AT+CFUN=0 and then AT+CFUN=1 to avoid GTP failure issue. This is usually used for testing. Example AT+QGPSCFG='gtp_fun',1 OK AT+QGPSONE=1,0,60 OK //Enable GTP feature. The command takes effect after the module is rebooted. //Use GTP 2.0 for positioning and no accuracy threshold, and set to 60 seconds. +QGPSURC: 'single_shot',,49.183300,-123.104631,0.0,434.7 AT+QGPSONE=0,3 //Use GNSS for positioning and high accuracy threshold, and default BG95&BG77&BG600L_Series_GTP_Application_Note 14 / 19 LPWA Module Series is 60 seconds. OK +QGPSURC: 'single_shot',2022/02/24 05:50:49,49.187322,-123.108171,1.5,8.0 BG95&BG77&BG600L_Series_GTP_Application_Note 15 / 19 LPWA Module Series 3 Examples 3.1. GTP Operation AT+QGPSCFG='gtp_fun',1 OK AT+QGPSONE=1,1,60 OK //Enable GTP feature. The command takes effect after the module is rebooted. //Use GTP 1.0 for positioning, set a low accuracy threshold of 1000 meters, and set to 60 seconds. +QGPSURC: 'single_shot',,25.076315,121.574840,170.0,513.2 3.2. GNSS Operation with GTP and XTRA AT+QGPSCFG='gtp_fun',1 OK AT+QGPSXTRA=1 OK //Enable GTP feature. The command takes effect after the module is rebooted. //Enable XTRA feature. The command takes effect after the module is rebooted. //Reboot the module. AT+QGPSXTRATIME? +QGPSXTRATIME: '2022/07/22,08:07:59' //If XTRA time is not returned, inject the time manually. OK AT+QGPSONE=0,3,60 OK //Use GNSS for positioning, set a high accuracy threshold of 100 meters, and set to 60 seconds. +QGPSURC: 'XTRA_DL',0 //The XTRA file is downloaded successfully. +QGPSURC: 'single_shot',2022/07/22 08:07:12,25.075385,121.575904,13.8,26.9 BG95&BG77&BG600L_Series_GTP_Application_Note 16 / 19 LPWA Module Series 4 Summary of Error Codes The indicates an error related to the GNSS operation. The details about are presented in the following table. Table 2: Summary of Error Codes 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 Description Invalid parameter Operation is not supported GNSS subsystem is busy Session is ongoing Session is inactive Operation timeout Functionality is disabled Time information error XTRA is disabled XTRA file open failed Bad CRC for XTRA data file Validity time is out of range Internal resource error GNSS locked End by E911 Not fixed now Geo-fence ID does not exist BG95&BG77&BG600L_Series_GTP_Application_Note 17 / 19 LPWA Module Series 518 Sync time failed 519 XTRA file does not exist 520 XTRA file is being downloaded 521 XTRA file is valid 522 GNSS is working 523 Time injection error 524 XTRA file is invalid 525 GTP is disabled 549 Unknown error BG95&BG77&BG600L_Series_GTP_Application_Note 18 / 19 LPWA Module Series 5 Appendix References Table 3: Related Document Document Name [1] Quectel_BG95&BG77&BG600L_Series_GNSS_Application_Note Table 4: Terms and Abbreviations Abbreviation AGPS CRC GNSS GSM GTP GTPA HTTP IoT NB-IoT RAT TLS TTFF URC UTC XTRA Description Assisted Global Positioning System Cyclic Redundancy Check Global Navigation Satellite System Global System for Mobile Communications Global Terrestrial Positioning GTP Assistance Hyper Text Transfer Protocol Internet of Things Narrowband IoT (Internet of Things) Radio Access Technology Transport Layer Security Time to First Fix Unsolicited Result Code Universal Time Coordinated Auxiliary Positioning Technology Provided by Qualcomm BG95&BG77&BG600L_Series_GTP_Application_Note 19 / 19
232.75 KB
BG77xA-GL&BG95xA-GL NIDD Application Note LPWA Module Series Version: 1.0 Date: 2022-08-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 nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG77xA-GL&BG95xA-GL_NIDD_Application_Note 1 / 15 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG77xA-GL&BG95xA-GL_NIDD_Application_Note 2 / 15 LPWA Module Series About the Document Revision History Version Date Author Description - 2021-01-15 Nikola BLAZIC Creation of the document 1.0 2022-08-12 Nikola BLAZIC First official release BG77xA-GL&BG95xA-GL_NIDD_Application_Note 3 / 15 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 Applicable Modules .................................................................................................................... 6 2 NIDD 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 NIDD-Related AT Commands............................................................................. 8 2.3.1. AT+QCFGEXT='nipdcfg' Configure NIDD Connection ............................................... 8 2.3.2. AT+QCFGEXT='nipd' Open/Close NIDD Connection................................................. 9 2.3.3. AT+QCFGEXT='nipds' Send MO Non-IP Data ......................................................... 10 2.3.4. AT+QCFGEXT='nipdr' Retrieve MT Non-IP Data ..................................................... 10 2.4. Description of NIDD Related URCs ......................................................................................... 12 2.4.1. +QIND: 'nipd','recv' Indicate Incoming Non-IP Data ................................................ 12 2.4.2. +QIND: 'nipd','close' Indicate the Connection is Closed .......................................... 12 2.5. Example ................................................................................................................................... 12 3 Summary of ..................................................................................................................... 14 4 Appendix References ....................................................................................................................... 15 BG77xA-GL&BG95xA-GL_NIDD_Application_Note 4 / 15 LPWA Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 6 Table 2: Types of AT Commands ................................................................................................................. 7 Table 3: Summary of ................................................................................................................. 14 Table 4: Related Documents ...................................................................................................................... 15 Table 5: Terms and Abbreviations .............................................................................................................. 15 BG77xA-GL&BG95xA-GL_NIDD_Application_Note 5 / 15 LPWA Module Series 1 Introduction The support for NIDD (Non-IP Data Delivery) is introduced as of 3GPP Release 13 and later releases. Functions for NIDD may be used to handle MO and MT communication with UE, where the data used for the communication are considered unstructured from the EPS standpoint (which is referred to as Non-IP). Quectel BG77xA-GL and BG95xA-GL modules support NIDD in NB-IoT RAT, and support both tethered and embedded Non-IP data calls. This document explains how to use the NIDD function of the modules through AT commands. Applicable Modules Table 1: Applicable Modules Module Family BG77xA-GL BG95xA-GL Model BG770A-GL BG773A-GL BG950A-GL BG951A-GL BG953A-GL BG955A-GL BG77xA-GL&BG95xA-GL_NIDD_Application_Note 6 / 15 LPWA Module Series 2 NIDD AT Commands 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 2: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. BG77xA-GL&BG95xA-GL_NIDD_Application_Note 7 / 15 LPWA Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 2.3. Description of NIDD-Related AT Commands 2.3.1. AT+QCFGEXT='nipdcfg' Configure NIDD Connection This command configures an NIDD connection. AT+QCFGEXT='nipdcfg' Configure NIDD Connection Write Command AT+QCFGEXT='nipdcfg'[,[,[,,]]] Response If the optional parameters are omitted, query the current setting. +QCFGEXT: 'nipdcfg',, OK If any of the optional parameters is specified, configure the NIDD connection. 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. Non-IP outgoing data type. 0 MO Non-IP data type 1 MO Exception Non-IP data type String type. Access point name. String type. Selected APN username. BG77xA-GL&BG95xA-GL_NIDD_Application_Note 8 / 15 String type. Selected APN password. LPWA Module Series NOTE Before using the selected APN for starting up a Non-IP data call, set the APN PDP type into 'Non-IP' with AT+CGDCONT. See document [2] for detailed information about AT+CGDCONT. 2.3.2. AT+QCFGEXT='nipd' Open/Close NIDD Connection This command opens or closes an NIDD connection. AT+QCFGEXT='nipd' Open/Close NIDD Connection Write Command AT+QCFGEXT='nipd',[,] Response If =0, close the NIDD connection. OK If =1, open an NIDD connection. OK +QIND: 'nipd','open', If there is an error related to ME functionality: +CME ERROR: Maximum Response Time Characteristics If there is any other error: ERROR 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. Close or open an NIDD connection. 0 Close an NIDD connection. 1 Open an NIDD connection. Integer type. Timeout for opening the NIDD connection. Parameter is valid only when =1. Range: 30–90. Default value: 30. Unit: second. Integer type. Error code. See Chapter 3 for detailed information. BG77xA-GL&BG95xA-GL_NIDD_Application_Note 9 / 15 LPWA Module Series NOTE 1. Non-IP data calls are supported for AP embedded and tethered RmNet calls only. 2. Non-IP data calls are not supported for modem embedded calls. 2.3.3. AT+QCFGEXT='nipds' Send MO Non-IP Data This command sends MO Non-IP data to a server. AT+QCFGEXT='nipds' Send MO Non-IP Data Write Command AT+QCFGEXT='nipds',,[,[,]] Response OK If there is an error related to ME functionality: +CME ERROR: Maximum Response Time Characteristics If there is any other error: ERROR 300 ms The command takes effect immediately. The configurations are not saved. Parameter Integer type. Data format. 0 ASCII format string. 1 HEX format string. String type. Data to be sent. Integer type. Length of data to be sent. If this parameter is omitted, can be specified at any length within 1358 bytes of ASCII format. Range: 1–1358. can be specified at any length within 679 bytes of HEX format. Range: 1–679. Unit: byte. Integer type. Whether to enable RAI flag when sending data to network side. 0 Disable 1 Enable String type. Error code. See Chapter 3 for detailed information. 2.3.4. AT+QCFGEXT='nipdr' Retrieve MT Non-IP Data This command retrieves the data reported by the URC +QIND: 'nipd','recv'. BG77xA-GL&BG95xA-GL_NIDD_Application_Note 10 / 15 LPWA Module Series AT+QCFGEXT='nipdr' Retrieve MT Non-IP Data Write Command AT+QCFGEXT='nipdr'[,[ ,]] Response +QCFGEXT: 'nipdr',, OK If there are no data that can be retrieved: +QCFGEXT: 'nipdr',0 OK If there is an error related to ME functionality: +CME ERROR: If there is any other error: ERROR Write Command When is 0, query the read status of the retrieved data: AT+QCFGEXT='nipdr',0 Response If the connection has existed: +QCFGEXT: 'nipdr',,, OK If there is an error related to ME functionality: +CME ERROR: Maximum Response Time Characteristics If there is any other error: ERROR 300 ms / Parameter Integer type. Length of data to be retrieved. Retrieve all available data if this parameter is omitted. Unit: byte. Integer type. Data format. This parameter is valid only when is not 0. 0 String type 1 Hex type Integer type. Actual length of retrieved data. Unit: byte. String type. Retrieved data. BG77xA-GL&BG95xA-GL_NIDD_Application_Note 11 / 15 LPWA Module Series Integer type. Total length of received data. Unit: byte. Integer type. Length of retrieved data. Unit: byte. Integer type. Length of unread data. Unit: byte. Integer type. Error code. See Chapter 3 for detailed information. 2.4. Description of NIDD Related URCs 2.4.1. +QIND: 'nipd','recv' Indicate Incoming Non-IP Data After receiving the non-IP data from the MT, the module reports the URC +QIND: 'nipd','recv' to notify the host about incoming data. Then host can retrieve data via AT+QCFGEXT='nipdr'. if the buffer is not empty, and the module receives data again, it will not report a new URC until all the received data have been retrieved via AT+QCFGEXT='nipdr' from the buffer. Buffer size: 2048 bytes. If the data received exceed the buffer size, subsequent data will be discarded. +QIND: 'nipd','recv' Indicate the Incoming Data +QIND: 'nipd','recv' The URC notifies the host about incoming data from the network. Then the host can retrieve the data via AT+QCFGEXT='nipdr'. 2.4.2. +QIND: 'nipd','close' Indicate the Connection is Closed In case of bad signal or the network goes down, the module reports the URC +QIND: 'nipd','close' to notify the host that the connection is closed. +QIND: 'nipd','close' Indicate the Connection is Closed +QIND: 'nipd','close' The URC notifies the host that the connection has been closed accidentally. If the connection closed normally via AT+QCFGEXT='nipd',0, this URC will not be reported. 2.5. Example AT+CGDCONT=1,'Non-IP','cmcc' OK AT+CEREG? +CEREG: 0,1 OK AT+QCFGEXT='nipdcfg',0,'cmcc' OK //Set the PDP type of selected APN into 'Non-IP'. //Set the Non-IP data type and APN. BG77xA-GL&BG95xA-GL_NIDD_Application_Note 12 / 15 LPWA Module Series AT+QCFGEXT='nipdcfg' +QCFGEXT: 'nipdcfg',0,'cmcc' OK AT+QCFGEXT='nipd',1,30 OK //Open an NIDD connection. +QIND: 'nipd','open',0 AT+QCFGEXT='nipds',0,'quectel',7 OK AT+QCFGEXT='nipds',1,'6162636465',10 OK //Send 'quectel' in ASCII format via NIDD connection. //Send 'abcde' in hex format via NIDD connection. //When there are any incoming data from the network, the following URC is reported. +QIND: 'nipd','recv' AT+QCFGEXT='nipdr',0 //Query the retrieved data length. +QCFGEXT: 'nipdr',10,0,10 //There are 10 bytes of data to be retrieved. OK AT+QCFGEXT='nipdr',10 +QCFGEXT: 'nipdr',10,0123456789 //Read 10 bytes of incoming data. OK AT+QCFGEXT='nipdr',0 +QCFGEXT: 'nipdr',10,10,0 //Query the retrieved data length. //All incoming data have been retrieved. OK AT+QCFGEXT='nipd',0 OK //Close the NIDD connection. BG77xA-GL&BG95xA-GL_NIDD_Application_Note 13 / 15 LPWA Module Series 3 Summary of The error code indicates an error related to mobile equipment or network operation. The definition of is provided in the table below. Table 3: Summary of 0 651 652 653 654 655 656 657 658 Definition Operation successful Invalid input value Send error Network error NIDD busy Timeout error Connection not opened Connection already opened Connection accidentally closed BG77xA-GL&BG95xA-GL_NIDD_Application_Note 14 / 15 LPWA Module Series 4 Appendix References Table 4: Related Documents Document Name [1] Quectel_BG77xA-GL&BG95xA-GL_QCFGEXT_AT_Commands_Manual [2] Quectel_BG77xA-GL&BG95xA-GL_AT_Commands_Manual Table 5: Terms and Abbreviations Abbreviation 3GPP AP APN ASCII EPS HEX IP ME MO MT NIDD PDP UE URC Description 3rd Generation Partnership Project Application Processor Access Point Name American Standard Code for Information Interchange Evolved Packet System Hexadecimal Internet Protocol Mobile Equipment Mobile Originated Mobile Terminated Non-IP Data Delivery Packet Data Protocol User Equipment Unsolicited Result Code BG77xA-GL&BG95xA-GL_NIDD_Application_Note 15 / 15
266.59 KB
BG77xA-GL&BG95xA-GL EMUX Application Note LPWA Module Series Version: 1.0 Date: 2022-08-26 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG77xA-GL&BG95xA-GL_EMUX_Application_Note 1 / 18 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG77xA-GL&BG95xA-GL_EMUX_Application_Note 2 / 18 LPWA Module Series About the Document Revision History Version Date Author Description - 2021-04-25 Damir KLICKOVIC Creation of the document Damir KLICKOVIC/ 1.0 2022-08-26 First official release Darko SAVIC BG77xA-GL&BG95xA-GL_EMUX_Application_Note 3 / 18 LPWA Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 1.1. Applicable Modules .................................................................................................................... 7 2 Overview of Quectel Multiplexing System ....................................................................................... 8 3 EMUX 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+EMUX Multiplexing Mode ............................................................................................... 10 4 Multiplexer Protocol ......................................................................................................................... 12 4.1. Frame Structure ....................................................................................................................... 12 4.1.1. Flag Sequence Field ..................................................................................................... 12 4.1.2. Address Field ................................................................................................................ 12 4.1.2.1. DLCI ................................................................................................................... 13 4.1.2.2. C/R ..................................................................................................................... 13 4.1.2.3. EA....................................................................................................................... 13 4.1.3. Control Field .................................................................................................................. 13 4.1.4. Length Field................................................................................................................... 14 4.1.5. Information Field ........................................................................................................... 14 4.1.6. FCS Field ...................................................................................................................... 15 4.2. Information Transfer................................................................................................................. 15 4.2.1. Information Data............................................................................................................ 15 5 Environment Setup ........................................................................................................................... 16 5.1. Windows Host .......................................................................................................................... 16 5.2. Linux Host ................................................................................................................................ 16 5.3. Opening Virtual Channels ........................................................................................................ 17 6 Appendix References ....................................................................................................................... 18 BG77xA-GL&BG95xA-GL_EMUX_Application_Note 4 / 18 LPWA Module Series Table Index Table 1: List of Virtual Port Channels and Their Mapped Functions ........................................................... 6 Table 2: Applicable Modules ........................................................................................................................ 7 Table 3: Types of AT Commands ................................................................................................................ 9 Table 4: EMUX Frame Structure................................................................................................................ 12 Table 5: Address Field Format................................................................................................................... 12 Table 6: C/R Bit Usage .............................................................................................................................. 13 Table 7: Control Field Coding .................................................................................................................... 14 Table 8: Length Field Structure.................................................................................................................. 14 Table 9: Related Document ....................................................................................................................... 18 Table 10: Terms and Abbreviations ........................................................................................................... 18 BG77xA-GL&BG95xA-GL_EMUX_Application_Note 5 / 18 LPWA Module Series 1 Introduction The document defines the Quectel MUX (multiplexer) protocol between UE and TE, and provides examples of how to use the MUX function on Quectel BG77xA-GL and BG95xA-GL modules. This specific implementation of multiplexer protocol is called EMUX and its purpose is to enable the multiplexer control channel similar to the one in the basic option defined in 3GPP TS 27.010. The EMUX feature allows maintaining four simultaneous sessions via one physical serial port. Table 1: List of Virtual Port Channels and Their Mapped Functions EMUX Virtual Port ID 1 2 3 4 Windows Host BGXX_AT1 BGXX_AT2 BGXX_AT3 BGXX_NMEA Linux Host /dev/ttyMUX0 /dev/ttyMUX1 /dev/ttyMUX2 /dev/ttyMUX3 Function AT/PPP AT AT NMEA Output Even though EMUX is based on 3GPP TS 27.010 and uses the same header format, it does not support all its features. The main differences between EMUX and 3GPP-defined CMUX: ⚫ Unlike the standard CMUX, the EMUX configuration is static. After EMUX is enabled, the module will automatically reset and activate the virtual channels. ⚫ EMUX does not support control messages. ⚫ Virtual channel flow control is not supported. ⚫ Virtual channel baud rate selection is automatically handled by EMUX host-side driver. BG77xA-GL&BG95xA-GL_EMUX_Application_Note 6 / 18 1.1. Applicable Modules Table 2: Applicable Modules Module Family BG77xA-GL BG95xA-GL Model BG770A-GL BG772A-GL BG773A-GL BG950A-GL BG951A-GL BG952A-GL BG953A-GL BG955A-GL LPWA Module Series BG77xA-GL&BG95xA-GL_EMUX_Application_Note 7 / 18 LPWA Module Series 2 Overview of Quectel Multiplexing System The multiplexer provides mechanisms for conveying data streams between TE and UE over a single physical port. Quectel multiplexing system creates 4 virtual channels on one physical port to transmit multiple streams of data simultaneously. It enables the physical port to act like four real physical channels for the user application-side. Each virtual channel, except port 4 that is reserved for NMEA output, supports SMS, PPP dialing, etc. All data from the user application-side are packed into different frames, and the frames consist of the data and protocol fields that clearly indicate channel number, information length, FCS, etc. The frames are transmitted as one stream via the serial port. After arriving at the other peer, the data are unpacked as four streams by the multiplexer protocol stack and transmitted to the user application-side. Each channel between TE and UE is called a DLC (Data Link Connection) and it is established separately and sequentially during the boot up process. TE User Application-Side UE App Task DLC1 DLC2 DLC3 DLC4 DLC1 DLC2 DLC3 DLC4 EMMUUXXDDrriviveerr EMMUUXXDTriavsekr Physical Layer Multi DATA Physical Layer Figure 1: EMUX Architecture BG77xA-GL&BG95xA-GL_EMUX_Application_Note 8 / 18 LPWA Module Series 3 EMUX 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 3: Types of AT Commands Command Type Test Command Read Command Write Command Syntax Description AT+=? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. AT+? Check the current parameter value of the corresponding command. AT+=[,[, Set user-definable parameter value. [...]]] BG77xA-GL&BG95xA-GL_EMUX_Application_Note 9 / 18 Execution Command AT+ LPWA Module Series Return a specific information parameter or perform a specific action. 3.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 3.3. AT+EMUX Multiplexing Mode This command enables/disables the multiplexer channel over the main UART port and sets the channel parameters. After enabling the EMUX feature the user will have four virtual channels at disposal. During the EMUX operation, all URCs will be forwarded to ‘BGXX_AT2’ (Windows) or ‘/dev/ttyMUX1’ (Linux). This configuration can be changed with AT+QCFG='emux/urcport'. AT+EMUX Multiplexing Mode Test Command AT+EMUX=? Response +EMUX: (list of supported s),(list of supported s),(list of supported s) Read Command AT+EMUX? OK Response +EMUX: ,, Write Command AT+EMUX=[,][,] Maximum Response Time Characteristics OK Response OK If there is an error: ERROR 3000 ms The command takes effect after the module reboots. The configuration is saved. BG77xA-GL&BG95xA-GL_EMUX_Application_Note 10 / 18 LPWA Module Series Parameter Integer type. Multiplexing mode. 0 Disable 1 Enabled Integer type. Baud rate of main UART port. Unit: bps. 115200 460800 921600 3000000 Integer type. Specifies if the flow control for EMUX (main UART) port is enabled/disabled. 0 Disable 1 Enable hardware flow control (RTS/CTS) Example AT+EMUX=1 OK //The module automatically reboots. AT+EMUX? +EMUX: 1,460800,0 OK NOTE On Quectel’s UMTS<E EVB, the maximum value of must not exceed 460800 bps. BG77xA-GL&BG95xA-GL_EMUX_Application_Note 11 / 18 LPWA Module Series 4 Multiplexer Protocol This chapter explains the technical details of the multiplexer protocol, including the frame structure and information transfer. 4.1. Frame Structure All information transmitted between the TE and UE is conveyed in frames. Table 4: EMUX Frame Structure Opening Flag 1 octet Address 1 octet Control Length Information FCS Closing Flag 1 octet 1–2 octets Multiple octets 1 octet 1 octet 4.1.1. Flag Sequence Field Each frame begins and ends with a flag sequence octet (0xF9). 4.1.2. Address Field The address field consists of a single octet. It contains the Data Link Connection Identifier (DLCI), the C/R bit and the address field extension bit as shown in the table below. Table 5: Address Field Format Bit 1 EA Bit 2 C/R Bit 3 Bit 4 D Bit 5 L Bit 6 C Bit 7 I Bit 8 BG77xA-GL&BG95xA-GL_EMUX_Application_Note 12 / 18 LPWA Module Series 4.1.2.1. DLCI The DLCI identifies the virtual channel between TE and UE. Multiple DLCIs can be supported, but the number is implementation-specific. DLCIs are dynamically assigned. 4.1.2.2. C/R The C/R (command/response) bit identifies the frame as either a command or a response. TE sends a command to the UE with the C/R bit set to 1, and the UE responds with the C/R bit set to 1. The UE sends a command with the C/R bit set to 0, and the TE responds with the C/R bit set to 0. Table 6: C/R Bit Usage Command/Response Command Response Direction TE → UE UE → TE UE → TE TE → UE C/R Value 1 0 1 0 4.1.2.3. EA The EA bit extends the range of the address field. When the EA bit is set to 1 in an octet, it signifies that this octet is the last octet of the length field. When the EA bit is set to 0, it signifies that it is followed by another octet of the address field. NOTE Currently, only EA=1 is supported by the modules. 4.1.3. Control Field The content of control filed defines the frame type. On the modules, only UIH frame is supported. Therefore, the control field is always set to 0. BG77xA-GL&BG95xA-GL_EMUX_Application_Note 13 / 18 LPWA Module Series Table 7: Control Field Coding Frame Type HEX (P/F=0) 1 2 3 4 5 6 7 8 UIH (Unnumbered Information with Header 0xEF check) 1 1 1 1 P/F 1 1 1 P/F is the Poll/Final bit. The poll (P) bit set to 1 is used by one station to solicit (poll) a response or a sequence of responses from the other station. The final (F) bit set to 1 is used by a station to indicate the response frame transmitted as the result of a soliciting (poll) command. The poll/final (P/F) bit has a function in both command frames and response frames. (In command frames, the P/F bit is referred to as the P bit. In response frames, it is referred to as the F bit.) NOTE EMUX only supports data frames (i.e. UIH frames), so the control field is always set to 0. 4.1.4. Length Field Table 8: Length Field Structure Bit 1 E/A Bit 2 L1 Bit 3 L2 Bit 4 L3 Bit 5 L4 Bit 6 L5 Bit 7 L6 Bit 8 L7 The L1 to L7 bits indicate the length of the following data field (i.e., the information field) that contains fewer than 128 bytes. The range of the length field may be extended by use of the EA bit. When the EA bit is set to 1 in an octet, it signifies that this octet is the last octet of the length field. When the EA bit is set to 0, it signifies that a second octet of the length field follows. The total length of the length field is 15 bits in that case. 4.1.5. Information Field The information field is the payload of the frame and carries the user data and any convergence layer information. The field is octet structured and only presents in UIH frames. BG77xA-GL&BG95xA-GL_EMUX_Application_Note 14 / 18 LPWA Module Series 4.1.6. FCS Field In the case of the UIH frame, the contents of the information field are not included in the FCS calculation. FCS is calculated on the contents of the address, control, and length fields only. This means that only the delivery to the correct DLCI is protected, but not the information. 4.2. Information Transfer 4.2.1. Information Data In Quectel multiplexing system, information is conveyed using UIH frames. UIH frames may also be used for data in situations where the delays inherent in error-recovery procedures are unacceptable, such as transmission of voice data. The transmitter takes information from the convergence layer for a particular DLC and places it in the information field of the transmitted frame. Once a UIH frame has been correctly received, the contents of its information field are passed to the convergence layer. The frames sent by the initiating station have the C/R bit set to 1 and those sent by the responding station have the C/R bit set to 0. Both stations set the P-bit to 0. See Chapter 4.1.2.2 for more information about the C/R bit. BG77xA-GL&BG95xA-GL_EMUX_Application_Note 15 / 18 LPWA Module Series 5 Environment Setup This chapter describes how to access and use the EMUX virtual channels. Prior to this, EMUX needs to be activated through the main UART port, as described in Chapter 3.3. Windows and Linux are supported host platforms from which the EMUX can be used. A dedicated application that performs virtualization of serial ports on the host side and acts as a proxy between a user and the modem is provided for each platform. After the application is run, virtual channels can be accessed. 5.1. Windows Host To use the EMUX on Windows OS, the ‘com0com’ (null-modem emulator) application must be installed on the host computer. After the installation of ‘com0com’ application, execute the ‘eMuxLauncher’ application to proceed with the EMUX driver setup. After creating virtual channel bindings, there is no need to repeat this action until their removal. You should enable EMUX on the module with AT+EMUX before starting the host application. > eMuxLauncher.bat –help NOTE Consult Quectel Technical Support (support@quectel.com) for the EMUX driver setup package. 5.2. Linux Host If there is no binary, the host application needs to be built first using the make command. $ make The host application must be run with root privileges, with the following three arguments: $ sudo ./mux /dev/ttyUSB0 /dev/ttyMUX 460800 BG77xA-GL&BG95xA-GL_EMUX_Application_Note 16 / 18 ⚫ Physical serial port name (e.g., /dev/ttyUSB0) ⚫ Virtual serial channel prefix (e.g., /dev/ttyMUX) ⚫ Baud rate (e.g., 460800) LPWA Module Series 5.3. Opening Virtual Channels Enable EMUX on the module with AT+EMUX before starting the host application. After the host application is started and EMUX is activated, virtual channels can be opened with the preferred application, just like any other serial port, using the preferred terminal application. Example (Linux Host) $ minicom -D /dev/ttyMUX0 -b 115200 $ minicom -D /dev/ttyMUX1 -b 115200 $ minicom -D /dev/ttyMUX2 -b 115200 $ minicom -D /dev/ttyMUX3 -b 115200 BG77xA-GL&BG95xA-GL_EMUX_Application_Note 17 / 18 LPWA Module Series 6 Appendix References Table 9: Related Document Document Name [1] Quectel_BG77xA-GL&BG95xA-GL_AT_Commands_Manual Table 10: Terms and Abbreviations Abbreviation ABM C/R DISC DLC DLCI DM FC FCS SABM TE UA UE UI UIH Description Asynchronous Balanced Mode Command/Response Disconnect Data Link Connection Data Link Connection Identifier Disconnected Mode Flow Control Frame Check Sequence Set Asynchronous Balanced Mode Terminal Equipment Unnumbered Acknowledgement User Equipment Unnumbered Information Unnumbered Information with Header Check BG77xA-GL&BG95xA-GL_EMUX_Application_Note 18 / 18
197.73 KB
BG77xA-GL&BG95xA-GL SSL Application Note LPWA Module Series Version: 1.0 Date: 2022-06-24 Status: Released LPWA Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. BG77xA-GL&BG95xA-GL_SSL_Application_Note 1 / 38 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BG77xA-GL&BG95xA-GL_SSL_Application_Note 2 / 38 LPWA Module Series About the Document Revision History Version Date Author - 2021-01-29 Terrence YANG 1.0 2022-06-24 Nikola BLAZIC Description Creation of the document First official release BG77xA-GL&BG95xA-GL_SSL_Application_Note 3 / 38 LPWA Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 6 1 Introduction .......................................................................................................................................... 7 1.1. Applicable Modules ..................................................................................................................... 7 1.2. SSL Versions and Cipher Suites................................................................................................. 7 1.3. Using SSL Function .................................................................................................................... 9 1.4. Description of Data Access Modes ........................................................................................... 10 1.5. Certificate Validity Check .......................................................................................................... 11 1.6. Server Name Indication ............................................................................................................ 12 2 Description of SSL AT Commands .................................................................................................. 13 2.1. AT Command Introduction ........................................................................................................ 13 2.1.1. Definitions....................................................................................................................... 13 2.1.2. AT Command Syntax ..................................................................................................... 13 2.2. Declaration of AT Command Examples .................................................................................... 14 2.3. Description of SSL AT Commands............................................................................................ 14 2.3.1. AT+QSSLCFG Configure Parameters of an SSL Context .......................................... 14 2.3.2. AT+QSSLOPEN Open an SSL Socket to Connect to a Remote Server .................... 21 2.3.3. AT+QSSLSEND Send Data via SSL Connection........................................................ 22 2.3.4. AT+QSSLRECV Retrieve Data via SSL Connection .................................................. 23 2.3.5. AT+QSSLCLOSE Close an SSL Connection.............................................................. 25 2.3.6. AT+QSSLSTATE Query the State of SSL Connections .............................................. 25 2.3.7. AT+QSSLCRYPT Encrypt/Decrypt Data with a Specified Algorithm .......................... 26 2.4. Description of URCs ................................................................................................................. 28 2.4.1. +QSSLURC: 'recv' Notify Received Data .................................................................. 28 2.4.2. +QSSLURC: 'closed' Notify Abnormal Disconnection ............................................... 28 3 Examples ............................................................................................................................................ 29 3.1. Configure and Activate a PDP Context..................................................................................... 29 3.1.1. Configure a PDP Context............................................................................................... 29 3.1.2. Activate a PDP Context.................................................................................................. 29 3.1.3. Deactivate a PDP Context ............................................................................................. 29 3.2. Configure an SSL Context ........................................................................................................ 29 3.3. SSL Client in Buffer Access Mode ............................................................................................ 30 3.3.1. Set up an SSL Connection and Enter Buffer Access Mode........................................... 30 3.3.2. Send Data in Buffer Access Mode ................................................................................. 30 3.3.3. Retrieve Data in Buffer Access Mode ............................................................................ 30 3.3.4. Close an SSL Connection .............................................................................................. 31 3.4. SSL Client in Direct Push Mode................................................................................................ 31 3.4.1. Set up an SSL Connection and Enter Direct Push Mode .............................................. 31 3.4.2. Send Data in Direct Push Mode..................................................................................... 31 BG77xA-GL&BG95xA-GL_SSL_Application_Note 4 / 38 LPWA Module Series 3.4.3. Retrieve Data in Direct Push Mode................................................................................ 31 3.4.4. Close an SSL Connection .............................................................................................. 32 3.5. SSL Client in Transparent Transmission Mode......................................................................... 32 3.5.1. Set up an SSL Connection and Send Data in Transparent Transmission Mode........... 32 3.5.2. Set up an SSL Connection and Retrieve Data in Transparent Transmission Mode...... 32 3.5.3. Close an SSL Connection .............................................................................................. 32 3.6. DTLS Connection Based on PSK Encryption ........................................................................... 32 3.6.1. Set up a DTLS Connection ............................................................................................ 32 3.6.2. Close an SSL Connection .............................................................................................. 33 4 Check for Failure in SSL Connection .............................................................................................. 34 5 Summary of Result Codes ................................................................................................................ 35 6 Appendix References ........................................................................................................................ 37 BG77xA-GL&BG95xA-GL_SSL_Application_Note 5 / 38 LPWA Module Series Table Index Table 1: Applicable Modules......................................................................................................................... 7 Table 2: Supported SSL Versions ................................................................................................................ 8 Table 3: Supported SSL Cipher Suites ........................................................................................................ 8 Table 4: Types of AT Commands ............................................................................................................... 13 Table 5: Result Codes ................................................................................................................................ 35 Table 6: Related Documents ...................................................................................................................... 37 Table 7: Terms and Abbreviations .............................................................................................................. 37 BG77xA-GL&BG95xA-GL_SSL_Application_Note 6 / 38 LPWA Module Series 1 Introduction Quectel BG77xA-GL and BG95xA-GL modules support SSL function. SSL (Secure Sockets Layer) is a networking protocol designed for securing connections between web clients and web servers over an insecure network, such as the internet. The SSL function is to ensure the privacy of communication. In some cases, the communication between the server and the client should be encrypted to prevent tampering, eavesdropping attacks, or data forging. 1.1. Applicable Modules Table 1: Applicable Modules Module Series BG77xA-GL BG95xA-GL Model BG770A-GL BG773A-GL BG950A-GL BG951A-GL BG953A-GL BG955A-GL 1.2. SSL Versions and Cipher Suites The following SSL versions are supported by BG770A-GL, BG950A-GL and BG951A-GL. BG77xA-GL&BG95xA-GL_SSL_Application_Note 7 / 38 LPWA Module Series Table 2: Supported SSL Versions SSL Version SSL3.0 TLS1.0 TLS1.1 TLS1.2 SSL cipher suites supported by the modules are presented in the table below. For a detailed description of cipher suites, see document [1]. Table 3: Supported SSL Cipher Suites Cipher Suite Code 0X0035 0X002F 0X0005 0X0004 0X000A 0X003D 0XC002 0XC003 0XC004 0XC005 0XC007 0XC008 0XC009 0XC00A 0XC011 Cipher Suite Name TLS_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_RC4_128_SHA TLS_RSA_WITH_RC4_128_MD5 TLS_RSA_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_ECDH_ECDSA_WITH_RC4_128_SHA TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 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 BG77xA-GL&BG95xA-GL_SSL_Application_Note 8 / 38 0XC012 0XC013 0XC014 0XC00C 0XC00D 0XC00E 0XC00F 0XC023 0XC024 0XC025 0XC026 0XC027 0XC028 0XC029 0XC02A 0XC02B 0XC02F 0XC0A8 0X00AE 0XFFFF LPWA Module Series TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_ECDH_RSA_WITH_RC4_128_SHA TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDH_RSA_WITH_AES_128_CBC_SHA TLS_ECDH_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 TLS-ECDHE-ECDSA-WITH-AES-128-GCM-SHA256 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_PSK_WITH_AES_128_CCM_8 TLS_PSK_WITH_AES_128_CBC_SHA256 Support all cipher suites above 1.3. Using SSL Function Step 1: Configure , , and other parameters of a PDP context with AT+QICSGP. See document [2] for detailed information. Step 2: Activate the PDP context with AT+QIACT, then the assigned IP address can be queried with AT+QIACT?. See document [2] for detailed information. BG77xA-GL&BG95xA-GL_SSL_Application_Note 9 / 38 LPWA Module Series Step 3: Configure the SSL version, cipher suite, trusted CA certificate path and the security level for a specified SSL context with AT+QSSLCFG. Step 4: Open an SSL socket to connect to a remote server with AT+QSSLOPEN. is used to specify SSL context, and is used to specify data access mode. Step 5: After the SSL connection has been established, data will be sent or received via the connection. For detailed information about how to send and receive data in each data access mode, see Chapter 1.4. Step 6: Close SSL connection with AT+QSSLCLOSE. Step 7: Deactivate the PDP context with AT+QIDEACT. See document [2] for detailed information. 1.4. Description of Data Access Modes The SSL connection supports three data access modes: ⚫ Buffer access mode ⚫ Direct push mode ⚫ Transparent transmission mode When opening an SSL connection via AT+QSSLOPEN, you can specify the data access mode with . After the SSL connection is established, the data access mode can be switched with AT+QISWTMD (see document [2]). 1. In buffer access mode, the module buffers data upon receiving them and reports a URC in the format of +QSSLURC: 'recv', to notify the host of the incoming data. In this case, the host can retrieve the buffered data with AT+QSSLRECV. 2. In direct push mode, the module outputs the received data directly through a URC 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 +++. Follow the requirements below to prevent the +++ from being misinterpreted as data: a) Do not input any character for at least 1 second before and after inputting +++. BG77xA-GL&BG95xA-GL_SSL_Application_Note 10 / 38 LPWA Module Series b) Input +++ within 1 second, and wait until OK is returned. After OK is returned, the module switches to buffer access mode. OR 2) Change MAIN_DTR from LOW to HIGH to make the module enter command mode (the COM port can now be used for running AT commands, as well as for sending/retrieving data). In this case, set AT&D1 (see document [3]) before the module enters transparent transmission mode. ⚫ Return to transparent transmission mode To return to transparent transmission mode either: 1) Execute AT+QISWTMD. Before execution specify as 2. Once transparent transmission mode is entered successfully, CONNECT is returned. OR 2) Execute ATO. After a connection exits transparent transmission mode, executing ATO switches the data access mode back to transparent transmission mode. Once transparent transmission mode is entered successfully, CONNECT is returned. If no connection has entered transparent transmission mode, ATO returns NO CARRIER. NOTE 1. In buffer access mode, if the buffer is not empty and the module receives data again, it does not report a new URC until all the received data have been retrieved with AT+QSSLRECV from the buffer. 2. In transparent transmission mode, AT commands cannot be executed. If the socket connection is closed because of a network error or other errors, the module reports NO CARRIER and exits the transparent transmission mode. In this case, execute AT+QSSLCLOSE to close the socket service. 1.5. Certificate Validity Check To check certificate validity, compare your local time against certificate validity range ('Not before' and 'Not after'). If the local time is earlier than the 'Not before' time or later than the 'Not after' time the certificate has expired. When certificate validity check is required (set as 0 when executing AT+QSSLCFG), to avoid validity period check failure, execute AT+CCLK to configure the module time within the certificate validity period. See document [3] for detailed information about AT+CCLK. BG77xA-GL&BG95xA-GL_SSL_Application_Note 11 / 38 LPWA Module Series 1.6. Server Name Indication SNI (Server Name Indication) allows the server to safely host multiple TLS Certificates since it provides Server Host Name information as an extension in the client hello message. It thus enhances connection security with multiple virtual servers based on a single IP address. This feature is only applicable to TLS protocol. BG77xA-GL&BG95xA-GL_SSL_Application_Note 12 / 38 LPWA Module Series 2 Description of SSL AT Commands 2.1. AT Command Introduction 2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 4: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. Write Command AT+=[,[,[...]]] Set user-definable parameter value. Execution Command AT+ Return a specific information parameter or perform a specific action. BG77xA-GL&BG95xA-GL_SSL_Application_Note 13 / 38 LPWA Module Series 2.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 2.3. Description of SSL AT Commands 2.3.1. AT+QSSLCFG Configure Parameters of an SSL Context This command configures the SSL version, cipher suite, security level, CA certificate, client certificate and client key. These parameters will be used in the handshake procedure. is the index of the SSL context. The module supports 6 SSL contexts at most. Several SSL connections can be established based on one SSL context. The settings such as the SSL version and the cipher suite are stored in the SSL context, and they will be applied to the new SSL connections associated with the SSL context. AT+QSSLCFG Configure Parameters of an SSL Context Test Command AT+QSSLCFG=? Response +QSSLCFG: 'sslversion',(range of supported s),(range of supported s) +QSSLCFG: 'ciphersuite',(range of supported s),(list of supported s) +QSSLCFG: 'cacert',(range of supported s), +QSSLCFG: 'clientcert',(range of supported s), +QSSLCFG: 'clientkey',(range of supported s), +QSSLCFG: 'seclevel',(range of supported s),(range of supported s) +QSSLCFG: 'session',(range of supported s),(list of supported s) +QSSLCFG: 'sni',(range of supported s),(list of supported s) +QSSLCFG: 'checkhost',(range of supported s),(list of supported s) +QSSLCFG: 'ignorelocaltime',(range of supported BG77xA-GL&BG95xA-GL_SSL_Application_Note 14 / 38 LPWA Module Series s),(list of supported s) +QSSLCFG: 'negotiatetime',(range of supported s),(range of supported s) +QSSLCFG: 'renegotiation',(range of supported s),(list of supported s) +QSSLCFG: 'dtls',(range of supported s),(list of supported s) +QSSLCFG: 'dtlsversion',(range of supported s),(range of supported s) OK Write Command Response Query/configure the SSL version for a If the optional parameter is omitted, query the current specified SSL context: setting. AT+QSSLCFG='sslversion', +QSSLCFG: 'sslversion',,<SSL_versio [,] n> OK Write Command Query/configure the SSL cipher suites for a specified SSL context: AT+QSSLCFG='ciphersuite',[,] If the optional parameter is specified, set the SSL version for the specified SSL context. OK Or ERROR Response If the optional parameter is omitted, query the current setting. +QSSLCFG: 'ciphersuite',, OK If the optional parameter is specified, set the SSL cipher suite for the specified SSL context. OK Or ERROR Write Command Response Query/configure the path of trusted CA If the optional parameter is omitted, query the current certificate for a specified SSL context: setting. AT+QSSLCFG='cacert',[,<c +QSSLCFG: 'cacert',, acertpath>] OK BG77xA-GL&BG95xA-GL_SSL_Application_Note 15 / 38 LPWA Module Series Write Command Query/configure the path of client certificate for a 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 current setting. +QSSLCFG: 'clientcert',, OK Write Command Query/configure the path of client private key for a specified SSL context: AT+QSSLCFG='clientkey',[, ] If the optional parameter is specified, set the path of client certificate for the specified SSL context. OK Or ERROR Response If the optional parameter is omitted, query the current setting. +QSSLCFG: 'clientkey',, OK Write Command Query/configure the authentication mode for a specified SSL context: AT+QSSLCFG='seclevel',[,< seclevel>] If the optional parameter is specified, set the path of client private key for the specified SSL context. OK Or ERROR Response If the optional parameter is omitted, query the current setting. +QSSLCFG: 'seclevel',, OK If the optional parameter is specified, set the authentication mode for the specified SSL context. OK Or ERROR BG77xA-GL&BG95xA-GL_SSL_Application_Note 16 / 38 LPWA Module Series Write Command Query/configure SSL Resumption feature for a specified SSL context: AT+QSSLCFG='session',[,< session>] Response If the optional parameter is omitted, query the current setting. +QSSLCFG: 'session',, OK If the optional parameter is specified, enable/disable SSL Resumption feature for the specified SSL context. OK Or ERROR Write Command Response Query/configure Server Name Indication If the optional parameter is omitted, query the current feature for a specified SSL context: setting. AT+QSSLCFG='sni',[,] +QSSLCFG: 'sni',, OK Write Command Query/configure hostname validation feature for a specified SSL context: AT+QSSLCFG='checkhost', [,] If the optional parameter is specified, enable/disable Server Name Indication feature for the specified SSL context. OK Or ERROR Response If the optional parameter is omitted, query the current setting. +QSSLCFG: 'checkhost',, OK If the optional parameter is specified, enable/disable hostname validation feature for the specified SSL context. OK Or ERROR Write Command Response Query/configure whether to ignore certificate If the optional parameter is omitted, query the current validity check for a specified SSL context: setting. AT+QSSLCFG='ignorelocaltime',<SSL_c +QSSLCFG: 'ignorelocaltime',,[,] _localtime> BG77xA-GL&BG95xA-GL_SSL_Application_Note 17 / 38 LPWA Module Series OK Write Command Query/configure the maximum timeout of SSL negotiation for a specified SSL context: AT+QSSLCFG='negotiatetime',[,] If the optional parameter is specified, set whether or not to ignore certificate validity check for the specified SSL context. OK Or ERROR Response If the optional parameter is omitted, query the current setting. +QSSLCFG: 'negotiatetime',, OK Write Command Query/configure whether support for TLS renegotiation is enabled for a specified SSL context: AT+QSSLCFG='renegotiation',[,] If the optional parameter is specified, set the maximum timeout of SSL negotiation for the specified SSL context. OK Or ERROR Response If the optional parameter is omitted, query the current setting. +QSSLCFG: 'renegotiation',, OK Write Command Query the current setting or configure whether to enable DTLS feature for a specified SSL context: AT+QSSLCFG='dtls',[,] If the optional parameter is specified, set whether to enable support for TLS renegotiation for the specified SSL context. OK Or ERROR Response If the optional parameter is omitted, query the current setting. +QSSLCFG: 'dtls',, OK If the optional parameter is specified, set whether to BG77xA-GL&BG95xA-GL_SSL_Application_Note 18 / 38 LPWA Module Series enable DTLS feature for the specified SSL context. OK Or ERROR Write Command Response Query/configure the DTLS version of a If the optional parameter is omitted, query the current specified SSL context: setting. AT+QSSLCFG='dtlsversion',<SSL_ctxID +QSSLCFG: 'dtlsversion',,[,] ion> OK Maximum Response Time Characteristics If the optional parameter is specified, set the DTLS version of the specified SSL context. OK Or ERROR 300 ms The command takes effect immediately. The configurations will not be saved. Parameter Integer type. SSL context ID. Range: 0–5. Integer type. SSL Version. 0 SSL3.0 1 TLS1.0 2 TLS1.1 3 TLS1.2 4 All Numeric type in HEX format. SSL cipher suites. 0X0035 TLS_RSA_WITH_AES_256_CBC_SHA 0X002F TLS_RSA_WITH_AES_128_CBC_SHA 0X0005 TLS_RSA_WITH_RC4_128_SHA 0X0004 TLS_RSA_WITH_RC4_128_MD5 0X000A TLS_RSA_WITH_3DES_EDE_CBC_SHA 0X003D TLS_RSA_WITH_AES_256_CBC_SHA256 0XC002 TLS_ECDH_ECDSA_WITH_RC4_128_SHA 0XC003 TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 0XC004 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 0XC005 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 0XC007 TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 0XC008 TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA BG77xA-GL&BG95xA-GL_SSL_Application_Note 19 / 38 LPWA Module Series 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 0XC02B TLS-ECDHE-ECDSA-WITH-AES-128-GCM-SHA256 0XC02F TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 0XC0A8 TLS_PSK_WITH_AES_128_CCM_8 0X00AE TLS_PSK_WITH_AES_128_CBC_SHA256 0XFFFF Support all cipher suites String type. The path of the trusted CA certificate. String type. The path of the client certificate. String type. The path of the client private key. Integer type. Authentication mode. 0 No authentication 1 Perform server authentication 2 Perform server and client authentication if requested by the remote server Integer type. Enable or disable SSL Resumption feature. 0 Disable 1 Enable Integer type. Enable or disable Server Name Indication feature. DNS hostnames are currently the only supported server names. 0 Disable 1 Enable Integer type. Enable or disable hostname validation feature (Subject Common Name (CN) matches the specified host name). 0 Disable 1 Enable Integer type. Whether or not to ignore certificate validity check. 0 Not to ignore 1 Ignore BG77xA-GL&BG95xA-GL_SSL_Application_Note 20 / 38 LPWA Module Series Integer type. The maximum timeout of SSL negotiation. Range: 10–300. Default value: 300. Unit: second. Integer type. Enable or disable support for TLS renegotiation. 0 Disable 1 Enable Integer type. Enable or disable DTLS feature. 0 Disable 1 Enable Integer type. DTLS version. 0 DTLS1.0 1 DTLS1.2 2 Both 2.3.2. AT+QSSLOPEN Open an SSL Socket to Connect to a Remote Server This command sets up an SSL connection. During the negotiation between the module and the Internet, parameters configured with AT+QSSLCFG will be used in the handshake procedure. After successful handshake with the Internet, the module can send or receive data via this SSL connection. In addition, the module can set up several SSL connections based on one SSL context. According to steps mentioned in Chapter 1.3, execute AT+QIACT first to activate the PDP context and then execute AT+QSSLOPEN. It is suggested to wait for a specific period of time (refer to the Maximum Response Time below) for +QSSLOPEN: , URC to be outputted. If the URC is not received during that time, use AT+QSSLCLOSE to close the SSL connection. AT+QSSLOPEN Open an SSL Socket to Connect to 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 (transparent transmission mode) ctxID>,,,[,] CONNECT If the =0/1(buffer access mode or direct push mode): OK +QSSLOPEN: , BG77xA-GL&BG95xA-GL_SSL_Application_Note 21 / 38 LPWA Module Series 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 will not be saved. Parameter Integer type. PDP context ID. Range: 1–5. 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. Range: 0-65535. Integer type. SSL connection data access mode. 0 Buffer access mode 1 Direct push mode 2 Transparent transmission mode Integer type. Result code. See Chapter 5. Integer type. Maximum timeout of SSL negotiation. Range: 10–300. Default value: 300. Unit: second. NOTE Error description can be got via AT+QIGETERROR. For more details, refer to document [2]. 2.3.3. AT+QSSLSEND Send Data via SSL Connection After the connection is established, the module can send data through the SSL connection. AT+QSSLSEND Send Data via SSL Connection Test Command AT+QSSLSEND=? Response +QSSLSEND: (range of supported s),(range of supported s) Write Command Send variable-length data AT+QSSLSEND= OK Response > After the above response, input the data to be sent. Tap CTRL+Z to send, or tap ESC to cancel the operation. BG77xA-GL&BG95xA-GL_SSL_Application_Note 22 / 38 LPWA Module Series If the connection has been established and sending is successful: SEND OK If the connection has been established but sending buffer is full: SEND FAIL If the connection has not been established, abnormally closed, or any parameter is incorrect: ERROR Write Command Response Send fixed-length data > AT+QSSLSEND=, equals . If the connection has been established and sending is successful: SEND OK If the connection has been established but sending buffer is full: SEND FAIL Maximum Response Time Characteristics If the connection has not been established, abnormally closed, or the parameter is incorrect: ERROR 300 ms / Parameter Integer type. Socket index. Range: 0–11. Integer type. Length of data to be sent. Range: 1–1460. Unit: byte. 2.3.4. AT+QSSLRECV Retrieve Data via SSL Connection When an SSL connection is opened with specified as 0 (buffer access mode), the module reports URC +QSSLURC: 'recv', when it receives data from the Internet. You can read the data from buffer with AT+QSSLRECV. BG77xA-GL&BG95xA-GL_SSL_Application_Note 23 / 38 LPWA Module Series AT+QSSLRECV Retrieve Data via SSL Connection Test Command AT+QSSLRECV=? Response +QSSLRECV: (range of supported s),(range of supported s) OK Write Command Response When is not 0, retrieve the If the specified connection has received data: data in specified length +QSSLRECV: AT+QSSLRECV=[,] OK When 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: retrieved data length +QSSLRECV: ,<have_read_lengt AT+QSSLRECV=,0 h>, OK Maximum Response Time Characteristics If there is any error: ERROR 300 ms / Parameter Integer type. Socket index. Range: 0–11. Integer type. Length of data to be retrieved. Range: 1–1500. Default value: 1500. Unit: byte. Integer type. Length of the data that have been actually retrieved. Unit: byte. String type. Retrieved data. Integer type. Total length of received data. Unit: byte. Integer type. The actual data length read with AT+QSSLRECV. Unit: byte. BG77xA-GL&BG95xA-GL_SSL_Application_Note 24 / 38 LPWA Module Series Integer type. Length of the data that have not been retrieved. Unit: byte. 2.3.5. AT+QSSLCLOSE Close an SSL Connection This command closes an SSL connection. If all the SSL connections based on the same SSL context are closed, the module releases the SSL context. AT+QSSLCLOSE Close an SSL Connection Test Command AT+QSSLCLOSE=? Response +QSSLCLOSE: (range of supported s),(range of supported s) Write Command AT+QSSLCLOSE=[,] OK Response If the SSL connection is successfully closed: OK Maximum Response Time Characteristics If there is any error: ERROR 10 s by default, determined by parameter The command takes effect immediately. The configuration will not be saved. Parameter Integer type. Socket index. Range: 0–11. Integer type. Timeout value of AT+QSSLCLOSE. Range: 0–65535. Default value: 10. Unit: second. 0 means closing immediately. 2.3.6. AT+QSSLSTATE Query the State of SSL Connections This command queries the state of SSL connections. AT+QSSLSTATE Query the State of SSL Connections Test Command AT+QSSLSTATE=? Write Command AT+QSSLSTATE= Response OK Response +QSSLSTATE: ,'SSLClient',,,,,,,,, BG77xA-GL&BG95xA-GL_SSL_Application_Note 25 / 38 Execution Command AT+QSSLSTATE Maximum Response Time Characteristics LPWA Module Series OK 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' Connection has been established 4 'Closing' Connection is closing Integer type. PDP context ID. Range: 1–16. Integer type. Reserved. Integer type. SSL connection data access mode. 0 Buffer access mode 1 Direct push mode 2 Transparent transmission mode String type. COM port of socket service. 'main' Main UART port 'aux' AUX UART port on BG770A-GL and Debug UART on BG95xA-GL 'emux0' EMUX0 'emux1' EMUX1 'emux2' EMUX2 'emux3' EMUX3 Integer type. SSL context ID. Range: 0–5. 2.3.7. AT+QSSLCRYPT Encrypt/Decrypt Data with a Specified Algorithm This command encrypts/decrypts data with a specified algorithm. It supports AES-128-CBC encryption/decryption and MD5 encryption. BG77xA-GL&BG95xA-GL_SSL_Application_Note 26 / 38 LPWA Module Series AT+ QSSLCRYPT Encrypt/Decrypt Data with a Specified Algorithm Test Command AT+QSSLCRYPT=? Response +QSSLCRYPT: ('AES','MD5'),,(list of supported s),(list of supported s), OK Write Command Response AT+QSSLCRYPT='AES', +QSSLCRYPT: 'AES', ,, OK Write Command AT+QSSLCRYPT='MD5', If there is any error: ERROR Response +QSSLCRYPT: 'MD5', OK Maximum Response Time Characteristic If there is any error: ERROR 300 ms / Parameter In AES-128-CBC mode: The data to be encrypted or decrypted. The data format is specified by . The maximum length of is 256 bytes. The length of data to be encrypted/decrypted with AES-128-CBC should be a multiple of 16 bytes. In MD5 mode: String type. The data to be encrypted. The maximum length of is 256 bytes. Integer type. The format of input data. 0 String format 1 Hex format Integer type. AES-128-CBC mode. 0 AES-128-CBC decryption 1 AES-128-CBC encryption String type. The encryption/decryption key of AES-128-CBC. The length must be 16 bytes. Hex String type. The encrypted data or decrypted data. BG77xA-GL&BG95xA-GL_SSL_Application_Note 27 / 38 LPWA Module Series 2.4. Description of URCs 2.4.1. +QSSLURC: 'recv' Notify Received Data The URC notifies the data received from peer in buffer access mode and direct push mode. +QSSLURC: 'recv' Notify Received Data +QSSLURC: 'recv', +QSSLURC: 'recv',, The URC of SSL data incoming in buffer access mode. SSL data can be retrieved with AT+QSSLRECV. The URC of SSL data incoming in direct push mode. Parameter Integer type. Socket index. Range: 0–11. Integer type. Length of actual received data. Unit: byte. The actual received data. 2.4.2. +QSSLURC: 'closed' Notify Abnormal Disconnection The URC notifies that the SSL connection has been disconnected. Disconnection can be caused by many reasons. For example, the Internet closes the connection or the state of GPRS PDP is deactivated, and the SSL connection state based on the specified socket may be 'closing'. In such case, AT+QSSLCLOSE= must be executed to change the SSL connection state to 'initial'. +QSSLURC: 'closed' Notify Abnormal Disconnection +QSSLURC: 'closed', The SSL connection based on the specified socket is closed. Parameter Integer type. Socket index. Range: 0–11. BG77xA-GL&BG95xA-GL_SSL_Application_Note 28 / 38 LPWA Module Series 3 Examples 3.1. Configure and Activate a PDP Context 3.1.1. Configure a PDP Context AT+QICSGP=1,1,'CMNBIOT','','',1 OK //Configure PDP context as 1. China Mobile NB-IoT network APN: CMNBIOT. 3.1.2. Activate a PDP Context AT+QIACT=1 OK AT+QIACT? +QIACT: 1,1,1,'100.142.162.0' OK //Activate PDP context 1. //Activated successfully. //Query the context state, protocol type and IP address of PDP context 1. 3.1.3. Deactivate a PDP Context AT+QIDEACT=1 OK //Deactivate PDP context 1. //Deactivated successfully. 3.2. Configure an SSL Context AT+QSSLCFG='sslversion',1,1 OK AT+QSSLCFG='ciphersuite',1,0X0035 OK AT+QSSLCFG='seclevel',1,1 //Set SSL context ID as 1 and SSL version as TLS1.0. //Set SSL cipher suites of SSL context ID 1 as TLS_RSA_WITH_AES_256_CBC_SHA. //Set authentication mode of SSL context ID 1 as server authentication. BG77xA-GL&BG95xA-GL_SSL_Application_Note 29 / 38 LPWA Module Series OK AT+QSSLCFG='cacert',1,'cacert.pem' OK //Set path of the trusted CA certificate of SSL context ID 1 3.3. SSL Client in Buffer Access Mode 3.3.1. Set up an SSL Connection and Enter Buffer Access Mode AT+QSSLOPEN=1,1,0,'220.180.239.212',8010,0 //Set up an SSL connection. OK +QSSLOPEN: 0,0 //SSL connection has been set up successfully. AT+QSSLSTATE //Query the state of all SSL connections. +QSSLSTATE: 0,'SSLClient','220.180.239.212',8010,65344,2,1,4,0,'main',1 OK 3.3.2. Send Data in Buffer Access Mode AT+QSSLSEND=0 > Test data from SSL SEND OK AT+QSSLSEND=0,18 > Test data from SSL SEND OK //Send variable-length data. //Send fixed-length data with the data length of 18 bytes. 3.3.3. Retrieve Data in Buffer Access Mode +QSSLURC: 'recv',0 //The Socket 0 (=0) has received data. AT+QSSLRECV=0,1500 +QSSLRECV: 18 Test data from SSL //Retrieved data. Length of data to be retrieved:1500 bytes. //Length of retrieved data: 18 bytes. OK AT+QSSLRECV=0,1500 +QSSLRECV: 0 //The buffer is empty. BG77xA-GL&BG95xA-GL_SSL_Application_Note 30 / 38 LPWA Module Series OK 3.3.4. Close an SSL Connection AT+QSSLCLOSE=0 OK //Close the connection (=0). Depending on the network, the maximum response time is 10 s by default. 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,0,'220.180.239.212',8011,1 //Set up an SSL connection. OK +QSSLOPEN: 0,0 //SSL connection has been set up successfully. AT+QSSLSTATE //Query the state of all SSL connections. +QSSLSTATE: 0,'SSLClient','220.180.239.212',8011,65047,2,1,4,1,'main',1 OK 3.4.2. Send Data in Direct Push Mode AT+QSSLSEND=0 > Test data from SSL SEND OK AT+QSSLSEND=0,18 > Test data from SSL SEND OK //Send variable-length data. //Send fixed-length data. Data length is 18 bytes. 3.4.3. Retrieve Data in Direct Push Mode +QSSLURC: 'recv',0,18 Test data from SSL BG77xA-GL&BG95xA-GL_SSL_Application_Note 31 / 38 LPWA Module Series 3.4.4. Close an SSL Connection AT+QSSLCLOSE=0 OK //Close the connection (=0). Depending on the network, the maximum response time is 10 s by default. 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,0,'220.180.239.212',8011,2 //Set up an SSL connection. CONNECT //Enter transparent transmission mode. //The client is sending data from COM port to the Internet directly. (The data are not visible in the example.) OK //Use +++ or MAIN_DTR (set AT&D1 first) to exit transparent transmission mode. The NO CARRIER result code indicates that the server has stopped the SSL connection. 3.5.2. Set up an SSL Connection and Retrieve Data in Transparent Transmission Mode AT+QSSLOPEN=1,1,0,'220.180.239.212',8011,2 //Set up an SSL connection. CONNECT //Enter transparent transmission mode. //The client is reading the data. OK //Use +++ or MAIN_DTR (execute 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=0 OK //Close the connection (=0). Depending on the network, the maximum response time is 10 s by default. 3.6. DTLS Connection Based on PSK Encryption 3.6.1. Set up a DTLS Connection AT+QFUPL='0_server.psk' //Upload PSK file first. The PSK file should be named as SSL_ctxID_server.psk (0_server.psk for instance) and the BG77xA-GL&BG95xA-GL_SSL_Application_Note 32 / 38 LPWA Module Series CONNECT +QFUPL: 24,553 content of the file should be in the format of & (e.g., DTLS_Client&1a2b3c4d). OK AT+QSSLCFG='dtls',0,1 //Enable DTLS feature for SSL context 0. OK AT+QSSLCFG='dtlsversion',0,0 //Configure DTLS version to DTLS1.0 for SSL context 0. OK AT+QSSLCFG='ciphersuite',0,0X00AE //Configure cipher suite for SSL context 0. OK AT+QSSLOPEN=1,0,0,'220.180.239.201',8010,0 OK +QSSLOPEN: 0,0 //SSL connection has been set up successfully. AT+QSSLSTATE //Query the state of SSL connections. +QSSLSTATE: 0,'SSLClient','220.180.239.201',8010,65344,2,1,4,0,'main',1 OK 3.6.2. Close an SSL Connection AT+QSSLCLOSE=0 OK //Close the connection (=0). Depending on the network, the maximum response time is 10 s by default. BG77xA-GL&BG95xA-GL_SSL_Application_Note 33 / 38 LPWA 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 with AT+QIACT? to check whether the specified PDP context has been activated. 2. If the address of server is a domain name, check if the DNS server address is valid with AT+QIDNSCFG=. Because an invalid DNS server address cannot convert domain name to IP address. 3. Check the SSL configuration with AT+QSSLCFG, especially the SSL version and cipher suite, to make sure that they are supported on server side. If has been configured as 1 or 2, then the trusted CA certificate has to be uploaded to the module with AT+QFUPL. If the server has configured 'SSLVerifyClient required', the client certificate and client private key have to be uploaded to the module with AT+QFUPL. For detailed information about certificate validity check, see Chapter 1.5. And for more information about related FILE AT commands, see document [4]. BG77xA-GL&BG95xA-GL_SSL_Application_Note 34 / 38 LPWA Module Series 5 Summary of Result Codes The result code indicates an error related to mobile equipment or network. The meaning of is described in the following table. Table 5: Result Codes 0 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 Meaning Operation successful Unknown error Operation blocked Invalid parameter Memory not enough Create socket failed Operation not supported Socket bind failed Socket listen failed Socket write failed Socket read failed Socket accept failed Open PDP context failed Close PDP context failed Socket identity has been used DNS busy DNS parse failed BG77xA-GL&BG95xA-GL_SSL_Application_Note 35 / 38 566 Socket connection failed 567 Socket has been closed 568 Operation busy 569 Operation timeout 570 PDP context break down 571 Cancel send 572 Operation not allowed 573 APN not configured 574 Port busy LPWA Module Series BG77xA-GL&BG95xA-GL_SSL_Application_Note 36 / 38 LPWA Module Series 6 Appendix References Table 6: Related Documents Document Name [1] RFC 2246 – The TLS Protocol Version 1.0 [2] Quectel_BG77xA-GL&BG95xA-GL_TCP(IP)_Application_Note [3] Quectel_BG77xA-GL&BG95xA-GL_AT_Commands_Manual [4] Quectel_BG77xA-GL&BG95xA-GL_FILE_Application_Note Table 7: Terms and Abbreviations Abbreviation APN CA CR DNS DTR DTLS GPRS ID IP LF PDP SNI Description Access Point Name Certificate Authority Carriage Return Domain Name Server Data Terminal Ready Datagram Transport Layer Security General Packet Radio Service Identifier Internet Protocol Line Feed Packet Data Protocol Server Name Indication BG77xA-GL&BG95xA-GL_SSL_Application_Note 37 / 38 SSL TCP/IP TLS UART URC USB LPWA Module Series Secure Sockets Layer Transmission Control Protocol/Internet Protocol Transport Layer Security Universal Asynchronous Receiver/Transmitter Unsolicited Result Code Universal Serial Bus BG77xA-GL&BG95xA-GL_SSL_Application_Note 38 / 38
336.42 KB
BC65&BC92 HTTP(S) Application Note NB-IoT Module Series Version: 1.0 Date: 2022-08-15 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 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. BC65&BC92_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 thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BC65&BC92_HTTP(S)_Application_Note 2 / 31 NB-IoT Module Series About the Document Revision History Version 1.0 Date 2022-05-17 2022-08-15 Author Arno DONG Arno DONG Description Creation of the document First official release BC65&BC92_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.1. 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 ...................................................................................................... 20 3.2.1. Send HTTPS GET Request and Read the Response................................................... 20 3.2.2. Send HTTPS POST Request and Read the Response ................................................ 23 4 Error Handling .................................................................................................................................... 25 4.1. HTTP(S) AT Command Executing Failure ............................................................................ 25 4.2. DNS Parse Failure................................................................................................................. 25 4.3. Data Mode Entering Failure .................................................................................................. 25 4.4. GET/POST Request Sending Failure ................................................................................... 26 4.5. Response Reading Failure.................................................................................................... 26 5 Summary of ERROR Codes .............................................................................................................. 27 6 Summary of HTTP(S) Response Codes .......................................................................................... 29 7 Appendix References ........................................................................................................................ 30 BC65&BC92_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.............................................................................................................. 27 Table 3: Summary of HTTP Response Codes ........................................................................................... 29 Table 4: Related Documents ...................................................................................................................... 30 Table 5: Terms and Abbreviations .............................................................................................................. 30 BC65&BC92_HTTP(S)_Application_Note 5 / 31 NB-IoT Module Series 1 Introduction Quectel BC65 and BC92 modules support HTTP(S) applications by accessing HTTP(S) server. 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 By default, an HTTP(S) request header is filled by the module automatically. It can also be customized by configuring to 1 via AT+QHTTPCFG (see Chapter 2.3.1) first, and then by inputting HTTP(S) request header according to the following requirements: ⚫ Follow the HTTP(S) request header syntax. ⚫ The value of URI in the HTTP(S) request line and the 'Host:' request header must be in line with the URL configured by 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 BC65&BC92_HTTP(S)_Application_Note 6 / 31 NB-IoT Module Series 1.1.2. Output HTTP(S) Response Header HTTP(S) response header is not outputted automatically. Outputting of the HTTP(S) response header can be enabled by configuring to 1 via AT+QHTTPCFG (see Chapter 2.3.1). The HTTP(S) response header is outputted together with HTTP(S) response body after executing AT+QHTTPREAD (see Chapter 2.3.6). BC65&BC92_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.1. 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. BC65&BC92_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 BC65&BC92_HTTP(S)_Application_Note 9 / 31 NB-IoT Module Series Write Command Configure/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, configure the PDP context ID: OK Or ERROR Write Command Response Configure/query whether to enable If the optional parameter is omitted, query the current settings: 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 Configure/query whether to enable If the optional parameter is omitted, query the current settings: outputting HTTP(S) response +QHTTPCFG: 'responseheader', header. AT+QHTTPCFG='responseheader OK '[,] If the optional parameter is specified, enable or disable outputting HTTP(S) response header: OK Or ERROR Write Command Response Configure/query data type of If the optional parameter is omitted, query the current settings: HTTP(S) body. +QHTTPCFG: 'contenttype', AT+QHTTPCFG='contenttype'[,] OK If the optional parameter is specified, configure data type of HTTP(S) body: OK Or ERROR BC65&BC92_HTTP(S)_Application_Note 10 / 31 NB-IoT Module Series Write Command Configure/query SSL context ID and connection ID used for HTTP(S). AT+QHTTPCFG='ssl'[,,] Response If the optional parameters are omitted, query the current settings: +QHTTPCFG: 'ssl',, OK Write Command Configure/query the display format of data returned by AT+QHTTPREAD. AT+QHTTPCFG='readformat'[,] If the optional parameters are specified, configure SSL context ID and connection ID used for HTTP(S): OK Or ERROR Response If the optional parameter is omitted, query the current settings: +QHTTPCFG: 'readformat', OK If the optional parameter is specified, configure the display format of the data returned by AT+QHTTPREAD: OK Maximum Response Time Characteristics If there is any error: ERROR 300 ms The command takes effect immediately. The configurations is not saved. Parameter Integer type. PDP context ID. Range: 1–3. Default value: 1 (only 1 is supported currently). 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 BC65&BC92_HTTP(S)_Application_Note 11 / 31 NB-IoT Module Series Integer type. SSL context ID. Range: 1–3. Default value: 1. Integer type. SSL connection ID. Range: 0–5. Default value: 0. String type. Display format of the data returned by AT+QHTTPREAD, that is whether carriage return and line feed are followed after +QHTTPREAD:. 0 No 1 Yes Integer type. Error code of the operation. See Chapter 5. NOTE The SSL/TLS connection configurations must be set by AT+QSSLCFG. For details of the command, see document [3]. 2.3.2. AT+QHTTPURL Set URL of HTTP(S) Server This command sets URL of an HTTP(S) server. URL must begin with 'http://' or 'https://', which indicates that an HTTP or HTTPS server to 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 Or ERROR Response a) If the parameter format is correct, and HTTP(S) GET/POST requests are not sent: > After response >, the module enters data mode, and then type the URL. When the total size of the inputted data reaches , the module returns to command mode and reports the following code: OK If has been reached, but the received URL length is less than , the module returns to command mode and reports the following code: BC65&BC92_HTTP(S)_Application_Note 12 / 31 NB-IoT Module Series Maximum Response Time Characteristics ERROR b) If the parameter format is incorrect or other errors occur: ERROR 300 ms The command takes effect immediately. The configurations is not saved. Parameter Integer type. Length of HTTP(S) server URL. Range: 1–700. 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 an HTTP(S) GET request. It is not supported to customize GET request header. If is set to 1, executing AT+QHTTPGET responses ERROR. But you can use AT+QHTTPPOST to send a custom HTTP(S) GET packet. After the 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 outputted after OK is returned. In +QHTTPGET: [,[,]], the can only be reported when is 0. 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 a) If the parameter format is correct and no other errors occur: OK When the module has received a response from HTTP(S) server, it reports the following URC: +QHTTPGET: [,[,]] b) If there is any error: BC65&BC92_HTTP(S)_Application_Note 13 / 31 Maximum Response Time Characteristics ERROR Determined by / NB-IoT Module Series Parameter Integer type. Timeout value for the HTTP(S) GET response +QHTTPGET: [,[,]] to be outputted after OK is returned. Range: 1–300. Default value: 60. Unit: second. Integer type. HTTP(S) response code. See Chapter 6. Integer type. Length of HTTP(S) response body. Unit: byte. This parameter is returned only if HTTP(S) response header contains CONTENT-LENGTH. Integer type. Maximum time for executing AT+QHTTPGET before releasing the HTTP resources. Range: 1–300. Default value: 60. Unit: second. Integer type. Error code of the operation. See Chapter 5. 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 HTTP(S) server, whose position and length have been specified with AT+QHTTPGETEX, and this command is only executable when 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 Send GET Request to HTTP(S) Server to Get Data With Specified Range Test Command Response AT+QHTTPGETEX=? +QHTTPGETEX: (range of supported s),(range of supported s),(range of supported s),(range of supported s) Write Command AT+QHTTPGETEX=,,[,] OK Response If the parameter format is correct and no other errors occur: OK When the module has received a response from HTTP(S) server, it reports the following URC: +QHTTPGETEX: [,,] BC65&BC92_HTTP(S)_Application_Note 14 / 31 NB-IoT Module Series Maximum Response Time Characteristics Description If there is any error: ERROR Determined by / Parameter Integer type. Timeout value for the HTTP(S) GET response +QHTTPGETEX: ,[,] to be outputted after OK is returned. Range: 1–300. Default value: 60. Unit: second. Integer type. Start position of the data that the HTTP(S) client wants to get. Range: 0–102400. Unit: byte. Integer type. Length of the data that the HTTP(S) client wants to get. Range: 0–102400. Unit: byte. Integer type. HTTP(S) server response code. See Chapter 6 for details. Integer type. Length of HTTP(S) response body. Unit: byte. This parameter is returned only if HTTP(S) response header contains CONTENT-LENGTH. Integer type. Maximum time for executing AT+QHTTPGETEX before releasing the resources. Range: 1–300. Default value: 60. Unit: second. Integer type. Error code of the operation. See Chapter 5. 2.3.5. AT+QHTTPPOST Send POST Request to HTTP(S) Server via UART/USB This command sends an HTTP(S) POST request. According to the configured in AT+QHTTPCFG='requestheader'[,] (see Chapter 2.3.1), 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 HTTP(S) POST header and body should be inputted via UART/USB port. After sending AT+QHTTPPOST, > is outputted within 50 s to indicate successful establishment of the connection. If that is not the case, +QHTTPPOST: 716 is 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 BC65&BC92_HTTP(S)_Application_Note 15 / 31 NB-IoT Module Series supported s),(range of supported s),(list of supported s),(range of supported s) Write Command If equals 0 (disable customizing HTTP(S) request header) AT+QHTTPPOST=[, ,[,[,< read_time>]]] 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: > After response >, the module switches to data mode, and the HTTP(S) POST body can be inputted. When the total size of the inputted data reaches , the module returns to command mode and reports the following code: OK When the module has received a response from HTTP(S) server, it reports the following URC: +QHTTPPOST: [,[,]] If the has reached, but the inputted length of data is less than , the module returns to command mode and reports the following code: ERROR Write Command If equals 1 (enable customizing HTTP(S) request header) AT+QHTTPPOST=[, ,[,[,< read_time>]]] b) If the parameter format is incorrect or other errors occur: ERROR Response a) If the parameter format is correct, the connection to HTTP(S) server has been established successfully: > After response >, the module switches to data mode, and the HTTP(S) POST header and body can be inputted. When the total size of the inputted data reaches , the module returns to command mode and reports the following code: OK When the module has received a response from HTTP(S) server, it reports the following URC: +QHTTPPOST: [,[,]] If the has reached, but the inputted length of data is less than , the module returns to command BC65&BC92_HTTP(S)_Application_Note 16 / 31 Maximum Response Time Characteristics NB-IoT Module Series mode and reports the following code: ERROR 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, including HTTP(S) request header and body. Range: 1–2048. Unit: byte. Integer type. Maximum time for inputting HTTP(S) POST body or HTTP(S) POST request. Range: 1–300. Default value: 60. Unit: second. Integer type. Timeout value for the HTTP(S) POST response +QHTTPPOST: [,[,]] to be outputted after OK is returned. Range: 1–300. Default value: 60. Unit: second. Integer type. Whether the current packet is the last packet. 0 The packet is the last one. 1 The packet is not the last one. Integer type. HTTP(S) response code. See Chapter 6. Integer type. Length of HTTP(S) response body. Unit: byte. Integer type. Maximum time for executing AT+QHTTPPOST before releasing the HTTP resources. Range: 1–300. Default value: 60. Unit: second. Integer type. Error code of the operation. See Chapter 5. 2.3.6. AT+QHTTPREAD Read Response from HTTP(S) Server via UART/USB This command reads the HTTP(S) response from an HTTP(S) server via the UART/USB port. After sending HTTP(S) GET/POST requests. It must be executed after +QHTTPGET: [,[,]], or +QHTTPGETEX: [,[,]], or +QHTTPPOST: [,[,]] is received. AT+QHTTPREAD Read Response from HTTP(S) Server via UART/USB Test Command AT+QHTTPREAD=? Response +QHTTPREAD: (range of supported s) OK BC65&BC92_HTTP(S)_Application_Note 17 / 31 NB-IoT Module Series Write Command AT+QHTTPREAD= Response a) If the parameter format is correct, of AT+QHTTPCFG='readformat' is specified to 0, and the HTTP(S) response is read successfully: +QHTTPREAD: , OK b) If the parameter format is correct, of AT+QHTTPCFG='readformat' is specified to 1, and the HTTP(S) response is read successfully: +QHTTPREAD: , OK Maximum Response Time Characteristics c) If the parameter format is incorrect or other errors occur: ERROR Determined by network. / Parameter Integer type. Length of data requested to be read. Range: 1–1024. Unit: byte. Integer type. Actual length of the received data. Unit: byte. Integer type. Remaining length of last received data. Unit: byte. Integer type. Error code of the operation. See Chapter 5. BC65&BC92_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 the Response The following examples show how to send HTTP GET request and how to read HTTP GET response. //Example of how to send an HTTP GET request. AT+QSCLK=0 //Disable the module to enter sleep mode. OK AT+QHTTPCFG='contextid',1 //Configure the PDP context ID to 1. OK AT+QHTTPCFG='responseheader',1 //Allow the output of HTTP response header. OK AT+QHTTPURL=19,80 //Set the URL of HTTP server to be accessed and timeout value to 80 s. > http://example.com/ //Input URL whose length is 19 bytes. (This URL is only an example. Input the correct URL in a practical test. OK AT+QHTTPGET=80 //Send HTTP GET request and set the maximum response time of HTTP GET request to 80 s. OK +QHTTPGET: 0,200,1256 //If HTTP response header contains CONTENT-LENGTH, the is reported. //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/ BC65&BC92_HTTP(S)_Application_Note 19 / 31 OK AT+QSCLK=1 OK NB-IoT Module Series //Enable the module to enter sleep mode. 3.1.2. Send HTTP POST Request and Read the Response The following examples show how to send HTTP POST request and retrieve the HTTP POST body via UART port, as well as how to read HTTP POST response. AT+QSCLK=0 //Disable the module to enter sleep mode. OK AT+QHTTPCFG='contextid',1 //Configure the PDP context ID to 1. OK AT+QHTTPURL=59,80 //Set the URL of HTTP server to be accessed and timeout value as 80 s. >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 //Send HTTP POST request. POST body is obtained via UART. The >Message=HelloQuectel maximum input time and the maximum response time are 80 s each. Input HTTP POST body whose length is 20 bytes after > is returned. OK +QHTTPPOST: 0,200,177 //If the HTTP response header contains CONTENT-LENGTH, the is reported. //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.
237.76 KB
BC65&BC92 CoAP Application Note NB-IoT Module Series Version: 1.0 Date: 2022-08-10 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. BC65&BC92_CoAP_Application_Note 1 / 30 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. 2022. All rights reserved. BC65&BC92_CoAP_Application_Note 2 / 30 NB-IoT Module Series About the Document Revision History Version 1.0 Date 2022-06-01 2022-08-10 Author Howie DONG Howie DONG Description Creation of the document First official release BC65&BC92_CoAP_Application_Note 3 / 30 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 .................................................................. 16 3 Description of CoAP URC ................................................................................................................ 21 4 Example ............................................................................................................................................. 24 4.1. Register to the IoT Platform Without DTLS ............................................................................. 24 4.2. Register to the IoT Platform With DTLS .................................................................................. 25 5 Summary of Result Codes ............................................................................................................... 28 6 Appendix References ....................................................................................................................... 29 BC65&BC92_CoAP_Application_Note 4 / 30 NB-IoT Module Series Table Index Table 1: Types of AT Commands ................................................................................................................ 7 Table 2: Description of Codes...................................................................................................... 28 Table 3: Related Documents...................................................................................................................... 29 Table 4: Terms and Abbreviations ............................................................................................................. 29 BC65&BC92_CoAP_Application_Note 5 / 30 NB-IoT Module Series 1 Introduction This document introduces how to use the CoAP feature on Quectel BC65 and BC92 module through AT commands. BC65&BC92_CoAP_Application_Note 6 / 30 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 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 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. BC65&BC92_CoAP_Application_Note 7 / 30 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 how to use the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendation or suggestions about how you should design a program flow or what status you should set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there exists a correlation among these examples, 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 which used in handshake for a specified CoAP client. AT+QCOAPCFG='psk',[,,] If there is any error: ERROR Response If the optional parameters are omitted, query the current setting: +QCOAPCFG: 'psk',, OK If the optional parameters are specified, set the PSK which used in handshake for a specified CoAP client: OK If there is any error: BC65&BC92_CoAP_Application_Note 8 / 30 NB-IoT Module Series Maximum Response Time Characteristics ERROR 300 ms This command takes effect immediately; Remain valid after wakeup from deep-sleep. The configuration will not be saved to NVRAM. Parameter Integer type. CoAP client identifier. Only 0 is supported currently. 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 (decimal number only). Identity of PSK. Length: 0–152 byte. Hex String type. Key of PSK. Length: 0–256 byte. 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 BC65&BC92_CoAP_Application_Note 9 / 30 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: (list 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 300 ms This command takes effect immediately; Remain valid after wakeup from deep-sleep. The configuration will not be saved to NVRAM. Parameter Integer type. CoAP client identifier. Only 0 is supported currently. String type. Address of CoAP server. It can only be an IP address in IPv4 or IPv6, domain name is not supported currently. The maximum length is 39 bytes. Integer type. Port of CoAP server. Range: 1–65535. Integer type. Current status of the CoAP client. 0 Idle or disconnected. 1 CoAP client is opening. 2 CoAP client is connecting to the CoAP server. 3 The CoAP client has connected to the CoAP server. 4 The CoAP client is disconnecting from the CoAP server. Integer type. Command execution results. See Chapter 5 for details. BC65&BC92_CoAP_Application_Note 10 / 30 NB-IoT Module Series Example AT+QCOAPOPEN=? +QCOAPOPEN: (0),,(1-65535) OK AT+QCOAPOPEN=0,'220.180.239.212',8032 OK +QCOAPOPEN: 0,0 AT+QCOAPOPEN? +QCOAPOPEN: 0,'220.180.239.212',8032,1 OK //Query the supported parameters value. //Create a CoAP context. //Query the current status of the CoAP client. 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: (list of supported s) Write Command AT+QCOAPCLOSE= OK Response OK +QCOAPCLOSE: , Maximum Response Time Characteristics If there is any error: ERROR 300 ms This command takes effect immediately. Parameter Integer type. CoAP client identifier. Only 0 is supported currently. Integer type. Result of the command execution. See Chapter 5 for details. BC65&BC92_CoAP_Application_Note 11 / 30 Example AT+QCOAPCLOSE=? +QCOAPCLOSE: (0) 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 parameters 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: (list of supported s),(list of supported s),,(range of supported s),,(list of supported s) Write Command If is not equal to 11 AT+QCOAPOPTION=,,,, Write Command If is equal to 11 AT+QCOAPOPTION=,,,,[,] OK Response OK If there is any error: 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 Maximum Response Time If there is any error: ERROR 300 ms BC65&BC92_CoAP_Application_Note 12 / 30 NB-IoT Module Series Characteristics This command takes effect immediately. Invalid after wakeup from deep sleep mode. Parameter Integer type. CoAP client identifier. Only 0 is supported currently. 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. The length of . Range: 0–255. Unit: byte. String type. CoAP option value. The maximum length is 255 bytes. See RFC 7252 and RFC7959 for details. If is 23 or 27, follow below formula to calculate the value of . The formula needs to input the expected values of block_num、 block_more and block_size to calculate : = (block_num << 4) | (block_more&0x8) | log2(block_size/16) If is 12 or 17, then 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 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 BC65&BC92_CoAP_Application_Note 13 / 30 NB-IoT Module Series Example AT+QCOAPOPTION=? +QCOAPOPTION: (0),(0),,(0-255),,(0,1) OK //Configure the CoAP option to 11 (Uri-path), the CoAP option value is '/quectel/time', the length is 13 bytes, and the '/' is used to divide Uri-path into multiple CoAP options. AT+QCOAPOPTION=0,0,11,13,'/quectel/time' OK //Configure the CoAP option as 15 (Uri-Query), the CoAP option value is 'ep=86370303', and the length is 11 bytes. AT+QCOAPOPTION=0,0,15,11,'ep=86370303' OK NOTE Pay attention to the options 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 14 (Max-Age) Integer type 15 (Uri-Query) String type 20 (Location-Query) String type 23 (Block2) Integer type 27 (Block1) Integer type 28 (Size2) Integer type 35 (Proxy-Uri) String type Length range: 0–8 Length range: 1–255 Length range: 1–8 supports 0 only Length range: 0–255 Length range: 0–255 Length range: 0–255 Length range: 0–255 Length range: 0–255 Length range: 0–255 Length range: 0–255 Length range: 0–255 Length range: 0–255 Length range: 1–255 BC65&BC92_CoAP_Application_Note 14 / 30 NB-IoT Module Series 2.3.5. AT+QCOAPHEAD Configure CoAP Message ID and Token This command configures the Message ID and Token of CoAP. AT+QCOAPHEAD Configure CoAP Message ID and Token Test Command AT+QCOAPHEAD=? Response +QCOAPHEAD: (list 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 Response OK If there is any error: ERROR Maximum Response Time 300 ms Characteristics This command takes effect immediately. Invalid after wakeup from deep sleep mode. Parameter Integer type. CoAP client identifier. Only 0 is supported currently. Integer type. The message ID and token mode selection. Range: 1–5. 1 Generate message ID and token value randomly. 2 Generate message ID randomly; token value is not included. 3 Configure message ID only; token value is not included. 4 Configure message ID; generate token value randomly. 5 Configure message ID and token value. Integer type. CoAP message ID, which only needs to be configured when the is 3, 4 or 5. Range: 0–65535. Integer type. The length of token value, which only needs to be configured when the is 5. Range: 1–8. Unit: byte. Hexadecimal string. The token value. Only needs to be configured when the is 5. BC65&BC92_CoAP_Application_Note 15 / 30 NB-IoT Module Series Example AT+QCOAPHEAD=? //Query the supported parameter range. +QCOAPHEAD: (0),(1-5),(0-65535),(1-8), OK AT+QCOAPHEAD=0,1 OK AT+QCOAPHEAD=0,2 OK AT+QCOAPHEAD=0,3,13940 OK AT+QCOAPHEAD=0,4,13940 OK AT+QCOAPHEAD=0,5,13940,4,'02040608' OK //Generate message ID and token value randomly. //Generate message ID randomly; token value is not included. //Only configure the Message ID to 13940; token value is not included. //Configure the Message ID to 13940, and randomly generate the token value. //Configure the Message ID to 13940 and the token value to '02040608'. NOTE If this command is not used, the module will randomly generate CoAP Message ID and the token value by default. 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 aut omatically informed to the terminal. The CON data state can also be queried through AT+QCOAP SEND= by the terminal. AT+QCOAPSEND Send CoAP Message Test Command AT+QCOAPSEND=? Response +QCOAPSEND: (list of supported s),(range of supported s),,(list of supporte d s),(range of supported s), Write Command AT+QCOAPSEND= OK Response +QCOAPSEND: , OK BC65&BC92_CoAP_Application_Note 16 / 30 NB-IoT Module Series Write Command AT+QCOAPSEND=,,< method/rspcode>, After > is returned, input the to be sent. Tap Ctrl + Z to send the data, or tap Esc to cancel the operation. If there is any error: ERROR Response > input the data to be sent OK If there is any error: ERROR Write Command AT+QCOAPSEND=,,< method/rspcode>,, After > is returned, input the to be sent. When the reaches, the data will send automatically. Response If is 0: OK If is not 0: > input the data to be sent OK Write Command AT+QCOAPSEND=,,< method/rspcode>,, , If there is any error: ERROR Response OK If there is any error: ERROR Maximum Response Time 300 ms Characteristics This command takes effect immediately. Parameter Integer type. CoAP client identifier. Only 0 is supported currently. Integer type. Type of the CoAP message. For details, refer to RFC 7252. 0 Confirmable (CON) 1 Non-confirmable (NON) 2 Acknowledgement (ACK) 3 Reset (RST) The request method of CoAP. Refer to the RFC 7252. 1 GET 2 POST 3 PUT 4 DELETE The response code of CoAP. Refer to the RFC 7252. BC65&BC92_CoAP_Application_Note 17 / 30 NB-IoT Module Series 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 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 packets adding options. Only 0 is supported currently, indicating no option is added to the CoAP packet. Integer type. The length of the data to be sent. Range: 0–1024. Unit: byte. String type. Data to be sent. Input data after > is returned, and the input data is a text string, otherwise, it is in hexadecimal format. Integer type. The status of CON data. 0 Not Sent 1 Sent, waiting for the response from the CoAP server 2 Failed to send 3 Timeout 4 Sent successfully 5 Get reset message BC65&BC92_CoAP_Application_Note 18 / 30 NB-IoT Module Series Example AT+QCOAPSEND=? +QCOAPSEND: (0),(0-3),,(0),(0-1024), OK AT+QCOAPSEND=0 +QCOAPSEND: 0,0 OK AT+QCOAPSEND=0,0,2,0 //Send a CON type POST request to the server. > ;rt='oma.lwm2m',,,,,, //Input the data to be sent after > is OK returned, press Ctrl+Z to send the data. AT+QCOAPSEND=0 +QCOAPSEND: 0,1 //Data has been sent, waiting for the response from the CoAP server. OK +QCOAPURC: 0,2,201,26923,132,2,'3132',8,'rd',8,'869619050024212' //Received a response from the server. AT+QCOAPSEND=0 +QCOAPSEND: 0,4 //Data is sent successfully. OK 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 is sent successfully. OK BC65&BC92_CoAP_Application_Note 19 / 30 NB-IoT Module Series NOTE 1. If () is specified to send data, the part exceeding 1024 bytes will be discarded and only 1024 bytes of the data will be sent. if () is not specified to send data, all will be discarded when the data exceeds 1024 bytes, and the transmission will be failed. 2. If CON data is required to be sent, it is recommended that to obtain the CON data status through AT+QCOAPSEND= before sending the next CON or NON data. 3. AT+QCOAPSEND= is only used to query the status of CON data that has been sent. 4. URC +QCOAPURC: ,,,,[,,][,,[,...]][,,] will be reported when data is sent successfully and the response is received from the server. See details in Chapter 3. BC65&BC92_CoAP_Application_Note 20 / 30 NB-IoT Module Series 3 Description of CoAP URC This chapter introduces the CoAP-related URCs and their descriptions. +QCOAPURC Notify TE to Respond to Requests from CoAP Server Successfully +QCOAPURC: ,,,,[,,] [,,[,...]][,,] Notify TE to respond to requests from CoAP server successfully. Parameter Integer type. CoAP client identifier. Only 0 is supported currently. Integer type. The message type of CoAP, refer to the RFC 7252. 0 Confirmable (CON) 1 Non-confirmable (NON) 2 Acknowledgement (ACK) 3 Reset (RST) Integer type. The request method of CoAP, refer to the RFC 7252. 1 GET 2 POST 3 PUT 4 DELETE Integer type. The response code of CoAP, 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 BC65&BC92_CoAP_Application_Note 21 / 30 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. Range: 1–255. Indicates whether there is data, the number of CoAP options, and whether there is a token. Bit 0 1 means there is data; 0 means there is no data. Bit 1-6 The number obtained after converting it to decimal represents the number of CoAP options. Bit 7 1 means there is a token; 0 means there is no token. Example: 131 is converted to binary as 1000 0011, which means that there are token and data, and option counts is 1. Integer type. The token length of the CoAP server. Range: 1–8. Unit: byte. String in Hex. Value of the token. 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 value. The maximum length is 255 bytes. If is 23 or 27, follow the formula below to calculate the value of : = (block_num << 4) | (block_more&0x8) | log2(block_size/16) If =12 or 17, the value of are as follows: '0' Text-plain '40' Application/link-format BC65&BC92_CoAP_Application_Note 22 / 30 NB-IoT Module Series '41' Application/xml '42' Application/octet-stream '47' Application/exi '50' Application/json Integer type. The length of data. Unit: byte. String type. The data received. If =12 and =0 ('Text-plain'), 41('Application/xml') or 50('Application/json'), the data is in text string format, otherwise, the data is in hexadecimal format. BC65&BC92_CoAP_Application_Note 23 / 30 NB-IoT Module Series 4 Example 4.1. Register to the IoT Platform Without DTLS AT+CGATT? +CGATT: 1 //Query the service status of the current PS domain. //The 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 a client ID of 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), the option value is 'rd' and the length is 2 bytes. AT+QCOAPOPTION=0,0,11,2,'rd' OK //Configure the CoAP option as 12(Content-Format), the option value is '40'(Application/link-format),the length is 2 bytes. AT+QCOAPOPTION=0,0,12,2,'40' OK //Configure the CoAP option as 15 (Uri-Query), the option value is 'lwm2m=1.0&ep=867725030012276 &b=U<=900', the length is 40 bytes. Use & connect between multiple options. AT+QCOAPOPTION=0,0,15,40,'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,,,,,, OK BC65&BC92_CoAP_Application_Note 24 / 30 NB-IoT Module Series //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, return the URC, with as 0, as 1, as 41128, 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 is sent successfully. OK //According to the last requested URC content, Configure CoAP message Message ID as 21152, Token length as 8 bytes, 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 the IoT Platform With DTLS AT+CGATT? +CGATT: 1 //Query the service status of the current PS domain. //The PS domain is attached. OK AT+QCOAPCFG='dtls',0,1 //Enable DTLS mode for CoAP client with ID 0. OK //Configure PSK, with as '869154040004132', as '67514b6c5a45334e31576a6d 5733387a'. AT+QCOAPCFG='psk',0,'869154040004132','67514b6c5a45334e31576a6d5733387a' OK BC65&BC92_CoAP_Application_Note 25 / 30 NB-IoT Module Series 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), the option value is 'rd' and the length is 2 bytes. AT+QCOAPOPTION=0,0,11,2,'rd' OK //Configure the CoAP option as 12(Content-Format), the option value is '40'(Application/link-format),the length is 2 bytes. AT+QCOAPOPTION=0,0,12,2,'40' OK //Configure the CoAP option as 15 (Uri-Query), the option value is'lwm2m=1.0&ep=869619050023990&b=U<=1600', the length is 40 bytes. Use & connect between 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, return the URC, 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 is sent successfully. OK //According to the last requested URC content, Configure CoAP message Message ID as 41128, Token length as 8 bytes, Token value as 'E8532D1363BE54B9'. AT+QCOAPHEAD=0,5,41128,8,'E8532D1363BE54B9' BC65&BC92_CoAP_Application_Note 26 / 30 NB-IoT Module Series 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. BC65&BC92_CoAP_Application_Note 27 / 30 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 BC65&BC92_CoAP_Application_Note 28 / 30 NB-IoT Module Series 6 Appendix References Table 3: Related Documents Document Name [1] Quectel_BC65_AT_Commands_Manual [2] Quectel_BC92_AT_Commands_Manual Table 4: Terms and Abbreviations Abbreviation 3GPP ACK CoAP CON DNS DTLS ID loT IP ME OPT PIN PS Description 3rd Generation Partnership Project Acknowledgement Constrained Application Protocol Confirmable Domain Name Server Datagram Transport Layer Security Identification Internet of Things Internet Protocol Mobile Equipment Option Personal Identification Number Packet Switch BC65&BC92_CoAP_Application_Note 29 / 30 RST TA TE URC Reset Terminal Adapter Terminal Equipment Unsolicited Result Code NB-IoT Module Series BC65&BC92_CoAP_Application_Note 30 / 30
275.17 KB
BC68-GV&BC95-GV CoAP Application Note NB-IoT Module Series Version: 1.0 Date: 2022-06-24 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. BC68-GV&BC95-GV_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. 2022. All rights reserved. BC68-GV&BC95-GV_CoAP_Application_Note 2 / 31 NB-IoT Module Series About the Document Revision History Version 1.0 Date 2021-11-18 2022-06-24 Author Howie DONG Howie DONG Description Creation of the document First official release BC68-GV&BC95-GV_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 .................................................................16 3 Description of CoAP URC...............................................................................................................21 4 Example ...........................................................................................................................................24 4.1. Register to the IoT Platform without DTLS .............................................................................24 4.2. Register to the IoT Platform with DTLS ..................................................................................25 5 Summary of Result Codes..............................................................................................................28 6 Summary of Error Codes................................................................................................................29 7 Appendix References .....................................................................................................................30 BC68-GV&BC95-GV_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 BC68-GV&BC95-GV_CoAP_Application_Note 5 / 31 NB-IoT Module Series 1 Introduction This document introduces how to use the CoAP feature on Quectel BC68-GV and BC95-GV module through AT commands. BC68-GV&BC95-GV_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. BC68-GV&BC95-GV_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 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 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 which 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 which used in handshake for a specified CoAP client: OK BC68-GV&BC95-GV_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 parameter configuration will not be saved. Parameter Integer type. CoAP client identifier. Currently only 0 is supported. 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 (Decimal number only). Identity of PSK. The maximum length is 152 bytes. Hex String type. Key of PSK. The maximum length is 256 bytes. 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 BC68-GV&BC95-GV_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: (list 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 parameter configuration will not be saved. Parameter Integer type. CoAP client identifier. Only 0 is supported currently. String type. Address of CoAP server. It can only be an IP address in IPv4 or IPv6. The maximum length is 45 bytes. Integer type. Port of CoAP server. Range: 1–65535. Integer type. Current status of the CoAP client. 0 Idle or disconnected. 1 CoAP client is opening. 2 CoAP client is connecting to the CoAP server. 3 The CoAP client has connected to the CoAP server. 4 The CoAP client is disconnecting from the CoAP server. Integer type. Result of the command execution. See Chapter 5 for details. Integer type. Error codes. See Chapter 6 for details. BC68-GV&BC95-GV_CoAP_Application_Note 10 / 31 NB-IoT Module Series Example AT+QCOAPOPEN=? +QCOAPOPEN: (0),,(1-65535) OK AT+QCOAPOPEN=0,'220.180.239.212',8032 OK +QCOAPOPEN: 0,0 AT+QCOAPOPEN? +QCOAPOPEN: 0,'220.180.239.212',8032,1 OK //Query the supported parameters value. //Create a CoAP context. //Query the current status of the CoAP client. 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: (list 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 This command takes effect immediately; The parameter configuration will not be saved. Parameter Integer type. CoAP client identifier. Only 0 is supported currently. Integer type. Result of the command execution. See Chapter 5 for details. Integer type. Error codes. See Chapter 6 for details. BC68-GV&BC95-GV_CoAP_Application_Note 11 / 31 Example AT+QCOAPCLOSE=? +QCOAPCLOSE: (0) 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 parameters 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: (list of supported s),(list of supported s),,(range of supported s),,(list of supported s) Write Command If is not equal to 11 AT+QCOAPOPTION=,,,, Write Command If is equal to 11 AT+QCOAPOPTION=,,,,[,] OK Response OK 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 parameter configuration will not be saved. BC68-GV&BC95-GV_CoAP_Application_Note 12 / 31 NB-IoT Module Series Parameter Integer type. CoAP client identifier. Only 0 is supported currently. Integer type. Index number 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. The length of . Unit: byte. CoAP option values. The maximum length is 255 bytes. See RFC 7252 and RFC7959 for details. If is 23 or 27, follow the formula below to calculate the value of : = (block_num << 4) | (block_more&0x8) | log2(block_size/16) If is 12 or 17, then the value of will be as follows: '0' Text-plain '40' Application/link-format '41' Application/xml '42' Application/octet-stream '47' Application/exi '50' Application/json Integer type. It applies only when is 11. If it is omitted, the default value will be 0. 0 Use '/' to divide Uri-Path into multiple CoAP options: 1 Uri-Path as a whole Error codes. See Chapter 6 for details. BC68-GV&BC95-GV_CoAP_Application_Note 13 / 31 NB-IoT Module Series Example AT+QCOAPOPTION=? +QCOAPOPTION: (0),(0),,(0-255),,(0,1) OK //Configure the CoAP option to 11 (Uri-path), the CoAP option value is 'rd', the length is 2 bytes, and the '/' is used to divide Uri-path into multiple CoAP options. AT+QCOAPOPTION=0,0,11,2,'rd' OK //Configure the CoAP option as 15 (Uri-Query), the CoAP option value is 'ep=86370303', and the length is 11 bytes. AT+QCOAPOPTION=0,0,15,11,'ep=86370303' OK Pay attention to the options in the table below: 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 (Content-Format) 20 (Location-Query) 23 (Block2) 27 (Block1) 28 (Size2) String type String type String type NULL Integer type String type String type Integer type Integer type String type Integer type String type Integer type Integer type Integer type Length range: 0–8 Length range: 1–255 Length range: 1–8 Supports 0 only Length range: 0–255 Length range: 0–255 Length range: 0–255 Length range: 0–2 Length range: 0–255 Length range: 0–255 Length range: 0–2 Length range: 0–255 Length range: 0–255 Length range: 0–255 Length range: 0–255 BC68-GV&BC95-GV_CoAP_Application_Note 14 / 31 NB-IoT Module Series 35 (Proxy-Uri) String type Length range: 1–255 NOTE When is 0, the default value of is 0 if the parameter is integer type while the default value is NULL if the is string type. 2.3.5. AT+QCOAPHEAD Configure CoAP Message ID and Token This command configures the Message ID and Token of CoAP. AT+QCOAPHEAD Configure CoAP Message ID and Token Test Command AT+QCOAPHEAD=? Response +QCOAPHEAD: (list of supported s),(range of supported s),(range of supported ),(range of supported s), OK If there is any error: ERROR Or +CME ERROR: Write Command Response AT+QCOAPHEAD=,[,[][,,]] If there is any error: ERROR Or +CME ERROR: Maximum Response Time 300 ms Characteristics This command takes effect immediately; The parameter configuration will not be saved. Parameter Integer type. CoAP client identifier. Only 0 is supported currently. Integer type. The message ID and token mode selection. Range: 1–5. 1 Generate message ID and token values randomly. 2 Generate message ID randomly; token value is not included. 3 Configure message ID only; token value is not included. BC68-GV&BC95-GV_CoAP_Application_Note 15 / 31 NB-IoT Module Series 4 Configure 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. The length of token values, which only needs to be configured when the is 5. Range: 1–8. Unit: byte. String in Hex. Token value, which only needs to be configured when the is 5. Error codes. See Chapter 6 for details. Example AT+QCOAPHEAD=? //Query the supported parameter range. +QCOAPHEAD: (0),(1-5),(0-65535),(1-8), OK AT+QCOAPHEAD=0,1 //Generate message ID and token values randomly. OK AT+QCOAPHEAD=0,2 //Generate message ID randomly; token value is not included. OK AT+QCOAPHEAD=0,3,13940 //Only configure the Message ID to 13940; token value is not included. OK AT+QCOAPHEAD=0,4,13940 //Configure the Message ID to 13940, and randomly generate the token value. OK AT+QCOAPHEAD=0,5,13940,4,'02040608' //Configure 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. 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 informed to the terminal. The CON data state can also be queried by the AT+QCOAPSEND= through the terminal. BC68-GV&BC95-GV_CoAP_Application_Note 16 / 31 NB-IoT Module Series AT+QCOAPSEND Send CoAP Message Test Command AT+QCOAPSEND=? Response +QCOAPSEND: (list of supported s),(range of supported s),,(list of supporte d s),(range of supported s), Write Command AT+QCOAPSEND= OK Response +QCOAPSEND: , OK Write Command AT+QCOAPSEND=,,< method/rspcode>, After > is returned, input the 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 the to be sent. When the reaches, the data will be sent automatically. If there is any error: ERROR Or +CME ERROR: Response > OK If there is any error: ERROR Or +CME ERROR: Response If is 0: OK If is not 0: > OK Write Command AT+QCOAPSEND=,,< method/rspcode>,,, If there is any error: ERROR Or +CME ERROR: Response OK If there is any error: BC68-GV&BC95-GV_CoAP_Application_Note 17 / 31 NB-IoT Module Series Maximum Response Time Characteristics ERROR Or +CME ERROR: 300 ms This command takes effect immediately; The parameter configuration will not be saved. Parameter Integer type. CoAP client identifier. Currently only 0 is supported. Integer type. The CoAP message type. For details, refer to RFC 7252. 0 Confirmable (CON) 1 Non-Confirmable (NON) 2 Acknowledgement (ACK) 3 Reset (RST) Integer type. The request method of CoAP. Refer to the RFC 7252. 1 GET 2 POST 3 PUT 4 DELETE Integer type. The response code of CoAP. 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 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 BC68-GV&BC95-GV_CoAP_Application_Note 18 / 31 NB-IoT Module Series Integer type. CoAP data packets adding options. Currently only 0 is supported, indicating no option is added to the CoAP packet. Integer type. The length of the data to be sent. Range: 0–1024. Unit: byte. String type. Data to be sent. After > is returned, the input data is a text string, otherwise, it is in hexadecimal format. Integer type. The status of CON data sent. 0 Not Sent 1 Sent, waiting for the response from the CoAP server 2 Failed to send 3 Timeout 4 Sent successfully 5 Get reset message Integer type. Error codes. See Chapter 6 for details. Example AT+QCOAPSEND=? +QCOAPSEND: (0),(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 is sent successfully. OK NOTE 1. The maximum length of is 1024 bytes, and the exceeding part will be ignored. 2. If CON data is required to be sent, it is recommended to obtain the CON data status through BC68-GV&BC95-GV_CoAP_Application_Note 19 / 31 NB-IoT Module Series AT+QCOAPSEND= before sending the next CON or NON data. 3. AT+QCOAPSEND= is only used to query the status of CON data that has been sent. 4. URC +QCOAPURC: ,,,,[,,][,,[,...]][,,] will be reported when data is sent successfully and the response is received from the server. See Chapter 3 for details. BC68-GV&BC95-GV_CoAP_Application_Note 20 / 31 NB-IoT Module Series 3 Description of CoAP URC This chapter introduces CoAP-related URC and its description. +QCOAPURC Notify TE to Respond to Requests from CoAP Server or Notify the Response from the CoAP Server +QCOAPURC: ,,,,[,,] [,,[,...]][,,] Notify TE to respond to requests from CoAP server or notify the response from the CoAP server Parameter Integer type. CoAP client identifier. Currently only 0 is supported. Integer type. The CoAP message type, refer to the RFC 7252. 0 Confirmable (CON) 1 Non-confirmable (NON) 2 Acknowledgement (ACK) 3 Reset (RST) Integer type. The CoAP of method, refer to the RFC 7252. 1 GET 2 POST 3 PUT 4 DELETE Integer type. The CoAP of 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 BC68-GV&BC95-GV_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 whether there is the data, option counts and Token. Bit 0 1 means there is data; 0 means there is no data. Bit 1-6 Converting it to decimal means option counts. Bit 7 1 means there is a token; 0 means there is no token. Example: 131 is converted to binary as 1000 0011, which means that there are token and data, and option counts is 1. Integer type. The token length of the CoAP server. Range: 1–8. Unit: byte. String in Hex. The 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. The maximum length is 255 bytes. If is 23 or 27, follow the formula below to calculate the value of : = (block_num << 4) | (block_more&0x8) | log2(block_size/16) If =12 or 17, the values of are as follows: '0' Text-plain '40' Application/link-format '41' Application/xml '42' Application/octet-stream BC68-GV&BC95-GV_CoAP_Application_Note 22 / 31 NB-IoT Module Series '47' Application/exi '50' Application/json Integer type. The length of data. Unit: byte. String type. The data received. If =12 and =0 (text-plain)/ 41(application/xml)/ 50(application/json), the data is in string format, otherwise, the data is in hexadecimal format. BC68-GV&BC95-GV_CoAP_Application_Note 23 / 31 NB-IoT Module Series 4 Example 4.1. Register to the IoT Platform without DTLS AT+CGATT? +CGATT: 1 //Query the current PS domain service status. //The PS domain is attached. OK AT+QCOAPCFG='dtls',0 +QCOAPCFG: 'dtls',0 //Query DTLS mode of client ID 0. //DTLS mode of client ID 0 is off. OK AT+QCOAPOPEN=0,'220.180.239.212',7002 OK //Create a CoAP context with a client ID of 0. +QCOAPOPEN: 0,0 AT+QCOAPHEAD=0,5,12345,4,'01020304' //Configure the CoAP message ID as 12345, the token value as '01020304', and the length as 4 bytes. OK AT+QCOAPOPTION=0,0,11,2,'rd' //Configure the CoAP option as 11 (Uri-Path), the option value as 'rd' and the length as 2 bytes. OK AT+QCOAPOPTION=0,0,12,2,'40' //Configure the CoAP option as 12 (Content-Format), the option value as '40' (Application/link-format), the length is 2 bytes. OK AT+QCOAPOPTION=0,0,15,40,'lwm2m=1.0&ep=867725030012276&b=U<=900' //Configure the CoAP option as 15 (Uri-Query), the option value is 'lwm2m=1.0&ep=867725030012276 &b=U<=900', the length is 40 bytes. (Use & to connect between multiple options.) 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 of POST request to the IoT platform. > ;rt='oma.lwm2m';ct=11543,,,,,, OK BC68-GV&BC95-GV_CoAP_Application_Note 24 / 31 NB-IoT Module Series //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' //URC below is returned after the request is received from the server, with as 0, as 1, as 21152, as 134, as 8 bytes, as 'E8532E3363BE54B9', as 6, as '0', as 11 corresponding to as '3', as 11 corresponding to as '0'. +QCOAPURC: 0,0,1,21152,134,8,'E8532E3363BE54B9',6,'0',11,'3',11,'0' AT+QCOAPSEND=0 //Query the sending status of CON data. +QCOAPSEND: 0,4 //CON data is sent successfully. OK AT+QCOAPHEAD=0,5,21152,8,'E8532E3363BE54B9' //According to the last requested URC, Configure CoAP message ID as 21152, Token length as 8 bytes, Token value as 'E8532E3363BE54B9'. OK AT+QCOAPSEND=0,2,205,0 //Send a 205 response code and 'AAAA' data using the ACK type to the IoT platform. > AAAA OK AT+QCOAPCLOSE=0 //Delete the CoAP context. OK +QCOAPCLOSE: 0,0 //The CoAP context is deleted successfully. 4.2. Register to the IoT Platform with DTLS AT+CGATT? +CGATT: 1 //Query the current PS domain service status. //The PS domain is attached. OK AT+QCOAPCFG='dtls',0,1 //Enable DTLS mode for CoAP client with ID 0. OK AT+QCOAPCFG='psk',0,'869154040004132','67514b6c5a45334e31576a6d5733387a' //Configure PSK, with as '869154040004132', as '67514b6c5a45334e31576a6d5 733387a'. OK AT+QCOAPOPEN=0,'220.180.239.212',7002 //Create a CoAP context with a client ID of 0. OK BC68-GV&BC95-GV_CoAP_Application_Note 25 / 31 NB-IoT Module Series +QCOAPOPEN: 0,0 AT+QCOAPHEAD=0,5,12345,4,'01020304' //Configure the CoAP message ID as 12345, the token value as '01020304', and the length as 4 bytes. OK AT+QCOAPOPTION=0,0,11,2,'rd' //Configure the CoAP option as 11 (Uri-Path), the option value is 'rd' and the length is 2 bytes. OK AT+QCOAPOPTION=0,0,12,2,'40' //Configure the CoAP option as 12 (Content-Format), the option value is '40' (Application/link-format), the length is 2 bytes. OK AT+QCOAPOPTION=0,0,15,40,'lwm2m=1.0&ep=869154040004132&b=U<=1600' //Configure the CoAP option as 15 (Uri-Query), the option value is 'lwm2m=1.0&ep=869619050023990&b=U<=1600', and the length is 40 bytes. (Use & to connect between multiple options.) 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 of POST request to the IoT platform. > ;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' //URC below is returned after the request is received from the server, with as 0, as 1, as 41128, as 134, as 8 bytes, as 'E8532D1363BE54B9', as 6, as 0, as 11 corresponding to as '3', as 11 corresponding to as '0'. +QCOAPURC: 0,0,1,41128,134,8,'E8532D1363BE54B9',6,'0',11,'3',11,'0' AT+QCOAPSEND=0 +QCOAPSEND: 0,4 //Query the sending status of CON data. //CON data is sent successfully. OK AT+QCOAPHEAD=0,5,41128,8,'E8532D1363BE54B9' //According to the last requested URC content, Configure CoAP message ID as 41128, Token length as 8 bytes, Token value as 'E8532D1363BE54B9'. OK AT+QCOAPSEND=0,2,205,0 //Send a 205 response code and 'AAAA' data using the ACK type to the IoT platform. BC68-GV&BC95-GV_CoAP_Application_Note 26 / 31 > AAAA OK AT+QCOAPCLOSE=0 OK +QCOAPCLOSE: 0,0 NB-IoT Module Series //Delete the CoAP context. //The CoAP context is deleted successfully. BC68-GV&BC95-GV_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 BC68-GV&BC95-GV_CoAP_Application_Note 28 / 31 NB-IoT Module Series 6 Summary of Error Codes This chapter summarizes the error codes related to BC68-GV and BC95-GV 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:'. When =1 or an error occurs, +CME ERROR: will be returned. When =0 or an error occurs, ERROR will be returned, see document [1] for details. BC68-GV&BC95-GV_CoAP_Application_Note 29 / 31 NB-IoT Module Series 7 Appendix References Table 4: Related Documents Document Name [1] Quectel_BC68-GV&BC95-GV_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 Identifier Internet of Things Internet Protocol Mobile Equipment Option Protocol Data Unit Personal Identification Number Packet Switch PIN Unlock Key Reset Short Message Service BC68-GV&BC95-GV_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 BC68-GV&BC95-GV_CoAP_Application_Note 31 / 31
257.69 KB
EM12xR-GL&EM160R-GL Secure Boot Application Note LTE-A Module Series Version: 1.0 Date: 2022-06-28 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. EM12xR-GL&EM160R-GL_Secure_Boot_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 third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note 2 / 15 LTE-A Module Series About the Document Revision History Version 1.0 Date 2022-04-21 2022-06-28 Author Shaun DUAN Shaun DUAN Description Creation of the document First official release EM12xR-GL&EM160R-GL_Secure_Boot_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 Secure Boot Overview ......................................................................................................................7 2.1. Definition ..................................................................................................................................7 2.2. Secure Boot Enabling...............................................................................................................7 2.3. Certificate Chain .......................................................................................................................8 2.4. Image Signing ..........................................................................................................................8 2.5. QFPROM Configuration ...........................................................................................................9 3 Secure Boot Related AT Commands .............................................................................................10 3.1. AT Command Syntax .............................................................................................................10 3.1.1. Definitions ....................................................................................................................10 3.1.2. AT Command Syntax...................................................................................................10 3.2. Declaration of AT Command Examples..................................................................................11 3.3. AT Commands Description.....................................................................................................11 3.3.1. AT+QSECBOOT Enable or Query Secure Boot .......................................................11 3.3.1.1. AT+QSECBOOT='status' Query Enabling Status of Secure Boot .................11 3.3.1.2. AT+QSECBOOT='serialnum' Query Unique Serial Number of Module.........12 3.3.1.3. AT+QSECBOOT='progsec' Enable Secure Boot ..........................................12 4 Development Considerations.........................................................................................................14 5 Appendix Terms and Abbreviations ..............................................................................................15 EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note 4 / 15 LTE-A Module Series Table Index Table 1: Applicable Modules ..................................................................................................................... 6 Table 2: Types of AT Commands............................................................................................................ 10 Table 3: Terms and Abbreviations........................................................................................................... 15 EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note 5 / 15 LTE-A Module Series 1 Introduction Quectel LTE-A EM12xR-GL and EM160R-GL modules support the Secure Boot function. This document describes how to use AT commands to enable the Secure Boot function on EM12xR-GL and EM160R-GL modules, including an overview of Secure Boot, detailed explanations of AT commands, and precautions. 1.1. Applicable Modules Table 1: Applicable Modules Module Series EM12xR EM160R Model EM120R-GL EM121R-GL EM160R-GL EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note 6 / 15 LTE-A Module Series 2 Secure Boot Overview 2.1. Definition Secure Boot is defined as a boot sequence in which each firmware image to be loaded and executed is authorized using the previously authorized firmware. At each stage of the Secure Boot process, signature verification is performed to prevent any software without valid signature or maliciously modified software from running on the module. A root trusted entity is needed during the boot process. The Primary Boot Loader (PBL), embedded in the module as a firmware, is unmodifiable, and therefore can serve as the root trusted entity. 2.2. Secure Boot Enabling Secure Boot can only be enabled with the fuse on the hardware and cannot be disabled after being enabled. The Secure Boot process comprises multiple stages, and the image in each stage performs a specific function. After the Secure Boot is enabled, the image to be executed in each stage needs to be verified by the previously verified image. If the verification fails, the entire boot process stops, and the module cannot boot up. As the root of trust (RoT), the PBL is the firmware embedded in chips and therefore cannot be modified. Therefore, it is considered as the most trusted entity in the booting process, and authenticates the image to be executed in the next boot stage. The SBL is usually verified in the second boot stage. After it is successfully authenticated by the PBL, it can be executed and used to authenticate the image in the next stage. Since the SBL has been trusted, it can be used to authenticate the image in the next stage. EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note 7 / 15 LTE-A Module Series 2.3. Certificate Chain Secure Boot supports 2048-bit or 4096-bit RSA private keys for signatures of the certificate and images. The format of the certificate signatures meets the PKCS #1 v1.2 standard and the SHA256 or SHA384 algorithm. The certificate chain of the module supports two-level certificate and three-level certificates. The three-level certificate is adopted by default and consists of three certificates: self-signed root certificate, attestation CA certificate and attestation certificate. 2.4. Image Signing The standard format of images is ELF. During Secure Boot, the images to be executed in each boot stage must be signed first. A binary file in the standard ELF format includes several segments indicating different types of information separately, wherein the hash table segment stores signature related information. The hash table segment also includes the hash values of each segment and information about certificate trust chain. The images that must be signed in the Secure Boot process for the module are as follows: ⚫ abl.elf ⚫ aop.mbn ⚫ devcfg.mbn ⚫ hyp.mbn ⚫ multi_image.mbn ⚫ prog_firehose_sdx24.mbn ⚫ sbl1.mbn ⚫ tz.mbn ⚫ uefi.elf ⚫ xbl_cfg.elf ⚫ apdp.mbn ⚫ NON-HLOS.ubi EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note 8 / 15 LTE-A Module Series 2.5. QFPROM Configuration The modules include one-time programmable fuses. The initial states of all fuses are 0 (Secure Boot disabled). Once a writing operation is performed on the fuse (or the fuse is blown), the state of the fuse permanently becomes 1 (Secure Boot enabled). The state cannot be changed after the fuse is blown, which means that the Secure Boot enabling is an irreversible operation. To start Secure Boot, the program tool QFPROM is required. QFPROM is used to store, in NVROM, configurations related to chip authentication and can implement the secure environment required by Secure Boot. Configure QFPROM and then blow the fuse, to complete all security functions such as output of Debug port, JTAG, secure file system and software version rollback prevention. EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note 9 / 15 LTE-A Module Series 3 Secure Boot Related AT Commands 3.1. AT Command Syntax 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 Read Command Write Command Execution Command AT+=? AT+? AT+=[,[, [...]]] AT+ Test the existence of the corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. Set user-definable parameter value. Return a specific information parameter or perform a specific action. EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note 10 / 15 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 Commands Description 3.3.1. AT+QSECBOOT Enable or Query Secure Boot AT+QSECBOOT Enable or Query Secure Boot Test Command AT+QSECBOOT=? Response +QSECBOOT: 'status',(list of supported s) +QSECBOOT: 'serialnum', +QSECBOOT: 'progsec',(list of supported s) Maximum Response Time Characteristic OK Or ERROR 300 ms - 3.3.1.1. AT+QSECBOOT='status' Query Enabling Status of Secure Boot This command queries whether Secure Boot is enabled in the module. AT+QSECBOOT='status' Query Enabling Status of Secure Boot Write Command AT+QSECBOOT='status' Response +QSECBOOT: 'status', Maximum Response Time OK Or ERROR 300 ms EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note 11 / 15 Characteristic - Parameter Integer type. Enabling status of Secure Boot. 1 Enabled 0 Disabled LTE-A Module Series 3.3.1.2. AT+QSECBOOT='serialnum' Query Unique Serial Number of Module This command queries the unique serial number of the module. AT+QSECBOOT='serialnum' Query Unique Serial Number of Module Write Command AT+QSECBOOT='serialnum' Response +QSECBOOT: 'serilalnum', Maximum Response Time Characteristic OK Or ERROR 300 ms - Parameter String type. Serial number of the module in hexadecimal format without double quotes. 3.3.1.3. AT+QSECBOOT='progsec' Enable Secure Boot This command enables Secure Boot. AT+QSECBOOT='progsec' Enable Secure Boot Write Command AT+QSECBOOT='progsec'[,] Response If the optional parameter is omitted, query the current setting: +QSECBOOT: 'progsec', OK EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note 12 / 15 LTE-A Module Series Maximum Response Time Characteristic If the optional parameter is specified, enable Secure Boot: OK Or ERROR 300 ms This command takes effect after the module is rebooted. The configuration is saved automatically. Parameter Integer type. Secure Boot is enabled or not. 1 Enabled 0 Disabled (Only valid in the query result) EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note 13 / 15 LTE-A Module Series 4 Development Considerations 1. Secure Boot can only be enabled with the hardware fuse and cannot be disabled after being enabled. 2. It is recommended to use AT+QSECBOOT='progsec', to enable Secure Boot, which is disabled by default. This command burns the image file in the sec partition and automatically activates Secure Boot after the module restarts. 3. After Secure Boot is enabled, it is not supported to use Firehose to downgrade the firmware to a version that does not support Secure Boot. 4. After Secure Boot is enabled, it is not supported to downgrade the firmware to a version that does not support Secure Boot through DFOTA, otherwise the module cannot start normally. 5. The PCIe Fuse mode also burns the image file in the sec partition, which conflicts with the enabling of Secure Boot. If Secure Boot is enabled first, the PCIe Fuse mode cannot be enabled. Thus, it’s necessary to enable Secure Boot of the module after enabling PCIe Fuse mode is enabled. EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note 14 / 15 LTE-A Module Series 5 Appendix Terms and Abbreviations Table 3: Terms and Abbreviations Abbreviation DFOTA ELF MBN PBL PCIe PKCS QFPROM RPM RoT SBL SHA Description Delta Firmware Upgrade Over-The-Air Executable and Linkable Format Multi Boot Image Format Primary Boot Loader Peripheral Component Interconnect Express Public-Key Cryptography Standards Qualcomm Fuse Programmable Read Only Memory RPM Package Manager (originally Red Hat Package Manager) Root of Trust Secondary Boot Loader Secure Hash Algorithm EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note 15 / 15
243.66 KB
BC660K-GL LwM2M Application Note NB-IoT Module Series Version: 1.0 Date: 2022-06-23 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 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. BC660K-GL_LwM2M_Application_Note 1 / 55 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 thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. BC660K-GL_LwM2M_Application_Note 2 / 55 NB-IoT Module Series About the Document Revision History Version 1.0 Date 2022-04-11 2022-06-23 Author Randy LI Randy LI Description Creation of the document First official release BC660K-GL_LwM2M_Application_Note 3 / 55 NB-IoT Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 6 Figure Index ................................................................................................................................................ 7 1 Introduction ......................................................................................................................................... 8 2 General Overview of LwM2M ............................................................................................................. 9 3 LwM2M Implementation ................................................................................................................... 11 3.1. LwM2M Interfaces.....................................................................................................................11 3.1.1. Bootstrap Interface.........................................................................................................11 3.1.2. Client Registration Interface...........................................................................................11 3.1.3. Device Management and Service Enablement Interface ............................................. 12 3.1.4. Information Reporting Interface .................................................................................... 14 3.2. LwM2M Object ......................................................................................................................... 14 3.2.1. Built-in Object ................................................................................................................ 14 3.2.2. Custom Object .............................................................................................................. 15 4 Description of LwM2M AT Commands ........................................................................................... 16 4.1. AT Command Introduction ....................................................................................................... 16 4.1.1. Definitions...................................................................................................................... 16 4.1.2. AT Command Syntax .................................................................................................... 16 4.2. Declaration of AT Command Examples ................................................................................... 17 4.3. AT Commands Description ...................................................................................................... 17 4.3.1. AT+QLWCONFIG Configure Registration Parameters .............................................. 17 4.3.2. AT+QLWREG Send Registration Request ................................................................. 19 4.3.3. AT+QLWUPDATE Send Update Request .................................................................. 19 4.3.4. AT+QLWDEREG Send Deregister Request .............................................................. 21 4.3.5. AT+QLWADDOBJ Add LwM2M Object ...................................................................... 21 4.3.6. AT+QLWDELOBJ Delete LwM2M Object .................................................................. 23 4.3.7. AT+QLWRDRSP Respond to Read Request............................................................. 24 4.3.8. AT+QLWWRRSP Respond to Write Request ............................................................ 25 4.3.9. AT+QLWEXERSP Respond to Execute Request ...................................................... 26 4.3.10. AT+QLWOBSRSP Respond to Observe Request ..................................................... 27 4.3.11. AT+QLWNOTIFY Report Data to Server.................................................................... 28 4.3.12. AT+QLWSTATUS Query Current LwM2M Status ...................................................... 29 4.3.13. AT+QLWRECOVER Manually Trigger LwM2M Context Recovery Process ............. 30 4.4. LwM2M Related URCs ............................................................................................................ 31 4.4.1. +QLWURC: 'ping' Notify TE of Update Operation Result ......................................... 32 4.4.2. +QLWURC: 'write' Notify TE to Respond to Write Request...................................... 33 4.4.3. +QLWURC: 'read' Notify TE to Respond to Read Request ...................................... 33 4.4.4. +QLWURC: 'execute' Notify TE to Respond to Execute Request ............................ 34 BC660K-GL_LwM2M_Application_Note 4 / 55 NB-IoT Module Series 4.4.5. 4.4.6. 4.4.7. 4.4.8. 4.4.9. 4.4.10. 4.4.11. 4.4.12. 4.4.13. +QLWURC: 'observe' Notify TE to Respond to Observe Request ........................... 34 +QLWURC: 'bootstrapping' Notify TE that Bootstrap Phase Starts ............................ 35 +QLWURC: 'bs_finished' Notify TE that Bootstrap Phase Has Completed.............. 35 +QLWURC: 'registering' Notify TE that Register Phase Starts................................. 35 +QLWURC: 'report' Notify TE that CON Data Has Been Sent ................................. 36 +QLWURC: 'report_ack' Notify TE that CON Data Has Been Acked ....................... 36 +QLWURC: 'lifetime_changed' Notify TE of Change in Registration Lifetime .......... 36 +QLWURC: 'binding_changed' Notify TE of Change in Binding Node ..................... 37 +QLWURC: 'recovered' Notify TE of LwM2M Context Recovery Result .................. 37 5 Examples ........................................................................................................................................... 39 5.1. Manual Registration to LwM2M Server ................................................................................... 39 5.2. Custom Object Related Operations ......................................................................................... 40 5.3. Registration to Leshan LwM2M Server ................................................................................... 42 5.4. LwM2M Updates (Leshan Server) ........................................................................................... 45 5.4.1. LwM2M Server Update Operation ................................................................................ 45 5.4.2. LwM2M Client Update Operation.................................................................................. 46 5.5. LwM2M Custom Object Related Operations (Leshan Server) ................................................ 50 5.5.1. Observe Operation........................................................................................................ 50 5.5.2. Notify Operation ............................................................................................................ 51 5.5.3. Read Operation ............................................................................................................. 51 5.5.4. Execute Operation ........................................................................................................ 51 6 Error Codes ....................................................................................................................................... 52 7 Appendix References ....................................................................................................................... 54 BC660K-GL_LwM2M_Application_Note 5 / 55 NB-IoT Module Series Table Index Table 1: Types of AT Commands ............................................................................................................... 16 Table 2: LwM2M Related URCs ................................................................................................................. 31 Table 3: Updateable Parameters ............................................................................................................... 46 Table 4: Summary of LwM2M ........................................................................................................... 52 Table 5: Summary of ......................................................................................................... 52 Table 6: References ................................................................................................................................... 54 Table 7:Terms and Abbreviations ............................................................................................................... 54 BC660K-GL_LwM2M_Application_Note 6 / 55 NB-IoT Module Series Figure Index Figure 1: Overall Architecture of LwM2M Enabler ....................................................................................... 9 Figure 2: Overall Architecture of 3GPP CIoT ............................................................................................. 10 Figure 3: Client Registration Interface Operation Flow.............................................................................. 12 Figure 4: Example Data Flow of Device Management .............................................................................. 13 Figure 5: Example Data Flow of Service Enablement ............................................................................... 13 Figure 6: Example Data Flow of Information Reporting............................................................................. 14 Figure 7: Click 'Add new client security configuration' in SECURITY Tab................................................ 42 Figure 8: Create 'New security configuration' on Leshan Server ............................................................. 43 Figure 9: Check Created 'New security configuration' on Leshan Server ................................................ 43 Figure 10: Online Client on Leshan Server................................................................................................ 44 Figure 11: 'Read' Operation on Leshan Server......................................................................................... 45 Figure 12: 'Write' Operation on Leshan Server......................................................................................... 45 Figure 13: 'Execute' Operation on Leshan Server.................................................................................... 46 Figure 14: Update Flow Example............................................................................................................... 47 Figure 15: Update Registration .................................................................................................................. 48 Figure 16: Update Binding Mode ............................................................................................................... 49 Figure 17: Update Object and Object Instance List ................................................................................... 50 BC660K-GL_LwM2M_Application_Note 7 / 55 NB-IoT Module Series 1 Introduction OMA Lightweight M2M (LwM2M) is a device management protocol designed for sensor networks and for the demands of Machine-to-Machine (M2M) environments. The protocol, designed for remote management of M2M devices and related service enablement, features a modern architectural design based on REST, defines an extensible resource and data model and builds on an efficient secure data transfer standard called the Constrained Application Protocol (CoAP). Quectel NB-IoT BC660K-GL module supports LwM2M V1.0. This document introduces the LwM2M protocol and architecture, and how to use this feature with BC660K-GL module. It also describes the LwM2M-related AT command set supported on the module. BC660K-GL_LwM2M_Application_Note 8 / 55 NB-IoT Module Series 2 General Overview of LwM2M The OMA LwM2M enabler defines an application layer communication protocol between an LwM2M Server and an LwM2M Client as well as between an LwM2M Bootstrap Server and an LwM2M Client. An LwM2M Device includes an LwM2M Client component. The enabler includes device management and service enablement for LwM2M Devices. The target LwM2M Devices for this enabler are mainly resource constrained devices. Therefore, this enabler makes use of lightweight and compact protocol mechanisms, as well as an efficient resource data model. Four interfaces are designed among the three entities, as shown in the architecture below: ⚫ Bootstrap ⚫ Client Registration ⚫ Device Management and Service Enablement ⚫ Information Reporting Figure 1: Overall Architecture of LwM2M Enabler BC660K-GL_LwM2M_Application_Note 9 / 55 NB-IoT Module Series The figure below illustrates the overall architecture of 3GPP CIoT, which is provided to better understand the LwM2M protocol. Figure 2: Overall Architecture of 3GPP CIoT BC660K-GL supports LwM2M Client only. MCU can communicate with LwM2M Server through LwM2M AT commands described in Chapter 4.3. NOTE OMA specifies a set of LwM2M protocol specifications. You can refer to the following links for more details: ⚫ https://www.omaspecworks.org/what-is-oma-specworks/iot/lightweight-m2m-lwm2m/ ⚫ http://www.openmobilealliance.org/release/LightweightM2M/V1_1-20180710-A/OMA-TS- LightweightM2M_Core-V1_1-20180710-A.pdf BC660K-GL_LwM2M_Application_Note 10 / 55 NB-IoT Module Series 3 LwM2M Implementation 3.1. LwM2M Interfaces 3.1.1. Bootstrap Interface The bootstrap interface is used to provision essential information into the LwM2M Client to enable the LwM2M Client to 'register' to one or more LwM2M Servers. ⚫ Bootstrap Modes Supported on BC660K-GL There are four bootstrap modes supported by the LwM2M protocol: Factory Bootstrap, Bootstrap from Smartcard, Client Initiated Bootstrap and Server Initiated Bootstrap. Generally, the LwM2M Client must support at least one bootstrap mode specified in the bootstrap server. Currently, BC660K-GL supports three bootstrap modes: Factory Bootstrap, Client Initiated Bootstrap and Server Initiated Bootstrap. ⚫ Server and Access Control Configurations The Bootstrap Server or LwM2M Server can be configured with AT+QLWCONFIG. AT+QLWREG can be used to register to a dedicated LwM2M Server. During the Client Initiated Bootstrap phase, if disconnection or failure occurs, back-off mechanism will be triggered internally. 3.1.2. Client Registration Interface The client registration interface is used by an LwM2M Client to register to one or more LwM2M Servers, and to maintain registration to or de-registration from the LwM2M Server. ⚫ Register The LwM2M Client performs a 'Register' operation to provide essential information required for registration to the LwM2M Server, such as endpoint name, PSK, registration lifetime, supported objects/instance etc. ⚫ Update After registration, the LwM2M Client performs an 'Update' operation in either a manual mode or an automatic mode periodically before registration lifetime expires. If the LwM2M Server does not receive an update from the LwM2M Client within lifetime, the LwM2M Server will remove the last registration BC660K-GL_LwM2M_Application_Note 11 / 55 NB-IoT Module Series and enter off state. ⚫ Deregister The LwM2M Client performs a 'Deregister' operation to deregister from the LwM2M Server. LwM2M Client Register ep=node1 ,, 2.01 Created LwM2M Server Update 2.04 Changed De-register 2.02 Deleted Figure 3: Client Registration Interface Operation Flow 3.1.3. Device Management and Service Enablement Interface Device management and service enablement interface is a very important interface in LwM2M protocol. ⚫ Allow LwM2M Server to access object instances and resources available on the LwM2M Client. ⚫ Allow LwM2M Server to perform 'Create', 'Read', 'Write', 'Delete', 'Execute', 'Write Attributes', or 'Discover' operations on the object instances and resources. ⚫ Allow the resource related operations to be defined in object definition using the Object Template. The data flow of device management and service enablement is shown as below: BC660K-GL_LwM2M_Application_Note 12 / 55 NB-IoT Module Series LwM2M Client LwM2M Server Read /3/0/0 Success Open Mobile Alliance Write /3/0/1 Lightweight M2M Client Success Execute /3/0/4 Success Figure 4: Example Data Flow of Device Management LwM2M Client LwM2M Server Create /2 Success-Location: /2/3 Write /2 Success-Location: /2/4 Delete /2/3 Success Figure 5: Example Data Flow of Service Enablement BC660K-GL_LwM2M_Application_Note 13 / 55 NB-IoT Module Series 3.1.4. Information Reporting Interface The information reporting interface is used by an LwM2M Server to observe any change in a resource on the LwM2M Client, and to receive notifications when new values are available. ⚫ The observation relationship is initiated by sending an 'Observe' operation to LwM2M Client for an Object, an Object Instance or a Resource. ⚫ An observation ends when a 'Cancel Observation' operation is performed by the LwM2M Server. BC660K-GL LwM2M Client supports observation and notification of objects, object instances and resources. LwM2M Client LwM2M Server Get /4/0/2 Observe 2.05 Content Observe …3.0.. Notify 28 Notify 31 Cancel Observation Figure 6: Example Data Flow of Information Reporting 3.2. LwM2M Object 3.2.1. Built-in Object There are some built-in objects supported by BC660K-GL LwM2M Client by default. The number in parentheses indicates the object ID. ⚫ Security object (0) ⚫ Server object (1) ⚫ Access control object (2) ⚫ Device object (3) ⚫ Connectivity monitoring object (4) ⚫ Firmware update object (5) ⚫ Connectivity statistics object (7) ⚫ Cellular connectivity object (10) BC660K-GL_LwM2M_Application_Note 14 / 55 ⚫ APN connection profile object (11) ⚫ Portfolio object (16) NB-IoT Module Series 3.2.2. Custom Object BC660K-GL also supports users to add custom objects through AT+QLWADDOBJ. Currently, each instance can be added with up to 7 resources. //LwM2M Client has registered to LwM2M Server. //Add a custom object. AT+QLWADDOBJ=3303,0,7,5601,5602,5603,5604,5605,5700,5701 OK +QLWADDOBJ: 0 //0 means that the custom object is added successfully. +QLWURC: 'ping',0,102,0 AT+QLWADDOBJ? +QLWADDOBJ: 3303,0 //Object list updated successfully. //Query custom object and object instance list. OK BC660K-GL custom objects only support 'Observe', 'Read', 'Write', and 'Execute' operations. See Chapter 5.5 for operation examples. NOTE In order to prevent BC660K-GL from entering deep sleep during data interaction, it is recommended that the MCU should actively disable sleep mode of the module with AT+QSCLK=0 before data interaction and then enable sleep mode with AT+QSCLK=1 after data interaction is completed. See document [1] for details of the command. BC660K-GL_LwM2M_Application_Note 15 / 55 NB-IoT Module Series 4 Description of LwM2M AT Commands 4.1. AT Command Introduction 4.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on the command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals to its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 4.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 1: Types of AT Commands Command Type Syntax Description Test Command AT+=? Read Command AT+? Test the existence of 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_LwM2M_Application_Note 16 / 55 NB-IoT Module Series 4.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendation or suggestions about how you should design a program flow or what status you should set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there exists a correlation among these examples, or that they should be executed in a given sequence. 4.3. AT Commands Description 4.3.1. AT+QLWCONFIG Configure Registration Parameters This command configures parameters required for registration of LwM2M client to LwM2M server. AT+QLWCONFIG Configure Registration Parameters Write Command AT+QLWCONFIG=,,,,,[,,< PSK>] Read Command AT+QLWCONFIG? Response OK If there is any error: +CMEE ERROR: Response When =0 is configured, or when =1 is configured but no Bootstrap or DM server is connected: +QLWCONFIG: ,,,,,[,,] OK When =1 is configured and both Bootstrap and DM servers are connected: +QLWCONFIG: ,,,,,[,,] +QLWCONFIG: ,,,,,[,,] Maximum Response Time OK 300 ms BC660K-GL_LwM2M_Application_Note 17 / 55 NB-IoT Module Series Characteristics The command takes effect immediately. Remains valid after deep-sleep wakeup. The configurations are saved to NVRAM automatically. Parameter Integer type. Server type. 0 DM server 1 Bootstrap server 2 Repository server 3 Diagnostics server String type. IP address or domain name of the LwM2M server. The maximum size is 150 bytes. Integer type. Port number of LwM2M server. Range: 0–65535. String type. Endpoint name of an LwM2M device. The maximum size is 150 bytes. Integer type. Lifetime of registration. Range: 50–31536000 (365 days). Unit: second. If lifetime ≤ 100 s, then the Actual Update Interval = 30 + (lifetime - 50) × 4/5 If lifetime ≤ 300 s, then the Actual Update Interval = 70 + (lifetime - 100) × 9/10 If lifetime > 300 s, then the Actual Update Interval = 250 + (lifetime - 300) × 19/20 When the Actual Update Interval timer expires, the module automatically reports data, resets registration lifetime and updates the Actual Update Interval. Integer type. Security mode. 0 Secure mode of PRE_SHARED_KEY 3 No security String type. PSK identifier. The maximum size is 150 bytes. String type. PSK content. It must be a hexadecimal string with an even number of characters. The maximum size is 256 bytes. Error code. For details of error codes, see Chapter 6. Example AT+QLWCONFIG=0,'220.180.239.212',8007,'866971030000710',86400,0,'866971030000710','77c7 55bd8cbb400abf2f0c420eed2cb0' OK AT+QLWCONFIG? +QLWCONFIG: 0,'220.180.239.212',8007,'866971030000710',86400,0,'866971030000710','77c75 5bd8cbb400abf2f0c420eed2cb0' OK BC660K-GL_LwM2M_Application_Note 18 / 55 NB-IoT Module Series 4.3.2. AT+QLWREG Send Registration Request This command sends a registration request to LwM2M server. AT+QLWREG Send Registration Request Execution Command AT+QLWREG Response OK +QLWREG: Maximum Response Time Characteristics If there is any error: +CMEE ERROR: 300 ms / Parameter Integer type. For details of status codes, see Chapter 6. Error code. For details of error codes, see Chapter 6. Example AT+QLWREG OK +QLWREG: 0 //Registered to LwM2M server successfully. 4.3.3. AT+QLWUPDATE Send Update Request This command sends an update request to the LwM2M server. AT+QLWUPDATE Send Update Request Write Command AT+QLWUPDATE=,[,] Response +QLWUPDATE: OK +QLWUPDATE: , If there is any error: +CMEE ERROR: BC660K-GL_LwM2M_Application_Note 19 / 55 NB-IoT Module Series Maximum Response Time Characteristics 300 ms / Parameter Integer type. 0 Updates lifetime 1 Updates binding mode Integer type. Lifetime of registration. Range: 50–31536000 (365 days). Unit: second. If lifetime ≤ 100 s, then the Actual Update Interval = 30 + (lifetime - 50) × 4/5 If lifetime ≤ 300 s, then the Actual Update Interval = 70 + (lifetime - 100) × 9/10 If lifetime > 300 s, then the Actual Update Interval = 250 + (lifetime - 300) × 19/20 When the Actual Update Interval timer times out, the module automatically reports data, resets registration lifetime and updates the Actual Update Interval. Integer type. The transport binding mode configured for the LwM2M client. 0 UDP mode 1 UDP & Queue mode Integer type. Server type. 0 DM server 2 Repository server 3 Diagnostics server Integer type. Message ID. Integer type. For details of status codes, see Chapter 6. Error code. For details of error codes, see Chapter 6. Example AT+QLWUPDATE=0,1000 +QLWUPDATE: 59797 //Update lifetime. OK +QLWUPDATE: 0,59797 AT+QLWUPDATE=1,1 +QLWUPDATE: 61459 //Updated successfully. //Update binding mode as UDP & Queue mode. OK +QLWUPDATE: 0, 61459 //Updated successfully. BC660K-GL_LwM2M_Application_Note 20 / 55 NB-IoT Module Series 4.3.4. AT+QLWDEREG Send Deregister Request This command sends a deregister request to the LwM2M server. AT+QLWDEREG Send Deregister Request Execution Command AT+QLWDEREG Response OK +QLWDEREG: Maximum Response Time Characteristics If there is any error: +CMEE ERROR: 300 ms / Parameter Integer type. For details of status codes, see Chapter 6. Error code. For details of error codes, see Chapter 6. Example AT+ QLWDEREG OK +QLWDEREG: 0 //Send a deregister request. //De-registered successfully. 4.3.5. AT+QLWADDOBJ Add LwM2M Object This command adds a new LwM2M object. AT+QLWADDOBJ Add LwM2M Object Write Command AT+QLWADDOBJ=,,, Response OK +QLWADDOBJ: Read Command AT+QLWADDOBJ? If there is any error: +CMEE ERROR: Response +QLWADDOBJ: , BC660K-GL_LwM2M_Application_Note 21 / 55 NB-IoT Module Series Maximum Response Time Characteristics OK If there is any error: +CMEE ERROR: 300 ms The command takes effect immediately. Remain valid after deep-sleep wakeup. The configurations are saved to NVRAM automatically. Parameter Integer type. Object ID. Integer type. Instance ID. Integer type. Number of resources. Integer type. Resource ID. Error code. For details of error codes, see Chapter 6. NOTE Currently, each instance can define up to 7 resources. Example //A custom object can be added after successful registration to LwM2M server or before the registration is initiated. AT+QLWADDOBJ=3303,0,3,5601,5602,5603 //Add an object 3303 and an instance ID 0. There are 3 resources 5601, 5602 and 5603 configured. OK +QLWADDOBJ: 0 AT+QLWADDOBJ=3303,1,3,5601,5602,5603 OK +QLWADDOBJ: 0 AT+QLWADDOBJ=3303,2,3,5601,5602,5603 OK +QLWADDOBJ: 0 AT+QLWADDOBJ=3303,3,3,5601,5602,5603 OK +QLWADDOBJ: 0 BC660K-GL_LwM2M_Application_Note 22 / 55 AT+QLWADDOBJ? +QLWADDOBJ: 3303,0 +QLWADDOBJ: 3303,1 +QLWADDOBJ: 3303,2 +QLWADDOBJ: 3303,3 OK NB-IoT Module Series 4.3.6. AT+QLWDELOBJ Delete LwM2M Object This command deletes a specified LwM2M object. AT+QLWDELOBJ Delete LwM2M Object Write Command AT+QLWDELOBJ= Response OK +QLWDELOBJ: Maximum Response Time Characteristics If there is any error: +CMEE ERROR: 300 ms The command takes effect immediately. Remain valid after deep-sleep wakeup. The configurations will be saved to NVRAM automatically. Parameter Integer type. Object ID. Error code. For details of error codes, see Chapter 6. Example AT+QLWDELOBJ=17 OK //Delete the object with object ID 17. +QLWDELOBJ: 0 BC660K-GL_LwM2M_Application_Note 23 / 55 NB-IoT Module Series 4.3.7. AT+QLWRDRSP Respond to Read Request This command allows the TE to respond to a read request from server. AT+QLWRDRSP Respond to Read Request Write Command AT+QLWRDRSP=,,,,,,,, Response OK +QLWRDRSP: If there is any error: +CMEE ERROR: Maximum Response Time 300 ms Characteristics / Parameter > Integer type. Message ID. Integer type. Result code indicating result of read operation. Result code CoAP Response Code Description 1 2.05 Content (indicates the correct result) 11 4.00 Bad Request 12 4.01 Unauthorized 13 4.04 Not Found 14 4.05 Method Not Allowed 15 4.06 Not Acceptable Integer type. Object ID. Integer type. Instance ID. Integer type. Resource ID. Integer type. The value types. 1 String 2 Opaque 3 Integer 4 Float 5 Boolean Integer type. The length of . When =1, the maximum length of is 1024 bytes. When =2, the maximum length of is 512 bytes. When =3, indicates the number of characters. When =4, indicates the number of characters. When =5, should be 1. String type. When =2, it is in hexadecimal string format. BC660K-GL_LwM2M_Application_Note 24 / 55 NB-IoT Module Series When =5, it is only 0 or 1. Integer type. The index number of the data. If the data is a combination of several messages, it should be split into several parts. If it is split into N parts, the order number of is from N-1 to 0 in descending order, and the AT command is called in the order from the largest to the smallest number. If is 0, it means that this is the last message of the data. Error code. For details of error codes, see Chapter 6. Example +QLWURC: 'read',62953,9,0,0 //Receive the read request from server AT+QLWRDRSP=62953,1,9,0,0,1,5,'abcde',0 OK +QLWRDRSP: 0 4.3.8. AT+QLWWRRSP Respond to Write Request This command allows the TE to respond to a write request from server. AT+QLWWRRSP Respond to the Write Request Write Command AT+QLWWRRSP=, Response OK +QLWWRRSP: Maximum Response Time Characteristics If there is any error: +CMEE ERROR: 300 ms / Parameter Integer. Message ID. Integer. Result code indicating result of write operation. Result code CoAP Response Code Description 2 2.04 Changed, indicates the correct result 11 4.00 Bad Request 12 4.01 Unauthorized 13 4.04 Not Found 14 4.05 Method Not Allowed BC660K-GL_LwM2M_Application_Note 25 / 55 NB-IoT Module Series Error code. For details of error codes, see Chapter 6. Example +QLWURC: 'write',36560,9,0,0,2,7,'5155454354454C',0 //Receive a write request from server. AT+QLWWRRSP=36560,2 OK +QLWWRRSP: 0 4.3.9. AT+QLWEXERSP Respond to Execute Request This command allows the TE to respond to the execute request from server. AT+QLWEXERSP Respond to Execute Request Write Command AT+QLWEXERSP=, Response OK +QLWEXERSP: Maximum Response Time Characteristics If there is any error: +CMEE ERROR: 300 ms / Parameter Integer type. Message ID. Integer type. Result code indicating result of execute operation. Result code CoAP Response Code Description 2 2.04 Changed, indicates the correct result 11 4.00 Bad Request 12 4.01 Unauthorized 13 4.04 Not Found 14 4.05 Method Not Allowed Error code. For details of error codes, see Chapter 6. Example +QLWURC: 'execute',39040,15,0,5 AT+QLWEXERSP=39040,2 OK //Receive an execute request from server BC660K-GL_LwM2M_Application_Note 26 / 55 NB-IoT Module Series +QLWEXERSP: 0 4.3.10. AT+QLWOBSRSP Respond to Observe Request This command allows the TE to respond to an observe request from server. AT+QLWOBSRSP Respond to Observe Request Write Command AT+QLWOBSRSP=,,,,,,,, Response OK +QLWOBSRSP: If there is any error: +CMEE ERROR: Maximum Response Time 300 ms Characteristics / Parameter > Integer type. Message ID. Integer type. Result code indicating result of observe operation. Result code CoAP Response Code Description 1 2.05 Content, indicates the correct result 11 4.00 Bad Request 12 4.01 Unauthorized 13 4.04 Not Found 14 4.05 Method Not Allowed 15 4.06 Not Acceptable Integer type. Object ID. Integer type. Instance ID. Integer type. Resource ID. Integer type. The value types. 1 String 2 Opaque 3 Integer 4 Float 5 Boolean Integer type. The value length. When =1, the maximum length of is 1000 bytes. When =2, the maximum length of is 500 bytes. When =3, indicates the number of characters. BC660K-GL_LwM2M_Application_Note 27 / 55 NB-IoT Module Series When =4, indicates the number of characters. When =5, should be 1. String type. When =2, it is in hexadecimal string format. When =5, it is only 0 or 1. Integer type. The index number of the data. If the data is a combination of several messages, it should be split into several parts. If it is split into N parts, the order number of is N-1 to 0 in descending order, and the AT command is called in the order from the largest to the smallest number. If is 0, it means that this is the last message of the data. Error code. For details of error codes, see Chapter 6. Example +QLWURC: 'observe',624,0,9,0,0 AT+QLWOBSRSP=624,1,9,0,0,1,5,'abcde',0 OK +QLWOBSRSP: 0 //Receive an observe request from server //Respond to the observe request 4.3.11. AT+QLWNOTIFY Report Data to Server This command reports the data to server. AT+QLWNOTIFY Report Data to Server Write Command AT+QLWNOTIFY=,,,,,,[,[,]] Response OK +QLWNOTIFY: [+QLWURC: 'report',] [+QLWURC: 'report_ack',,] Maximum Response Time Characteristics If there is any error: +CMEE ERROR: 300 ms / Parameter Integer type. Object ID. Integer type. Instance ID. BC660K-GL_LwM2M_Application_Note 28 / 55 NB-IoT Module Series Integer type. Resource ID. -1 indicates all resources. Integer type. The value types. 1 String 2 Opaque 3 Integer 4 Float 5 Boolean Integer type. The length of data to be sent. When =1, the maximum length of is 1000 bytes. When =2, the maximum length of is 500 bytes. When =3, indicates the number of characters. When =4, indicates the number of characters. When =5, should be 1. String type. When =2, it is in hexadecimal string format. When =5, it is only 0 or 1. Integer type. The index number of the data. If the data is combined with several messages, it should be split into several parts. If it is split into N parts, the order number of is N-1 to 0 in descending order, and the AT command is called in the order from the largest to the smallest number. If is 0, it means that this is the last message of the data. Integer type. Response type marker. 0 NON type data 1 CON type data Integer type. Release assistance information (currently not supported). 0 No information available 1 TE will send only 1 UL packet without expecting DL packets 2 TE will send only 1 UL packet and expect only 1 DL packet Integer type. For details of status codes, see Chapter 6. Error code. For details of error codes, see Chapter 6. 4.3.12. AT+QLWSTATUS Query Current LwM2M Status This command queries the current LwM2M status. AT+QLWSTATUS Query Current LwM2M Status Read Command AT+QLWSTATUS? Response +QLWSTATUS: OK Maximum Response Time If there is any error: +CMEE ERROR: 300 ms BC660K-GL_LwM2M_Application_Note 29 / 55 NB-IoT Module Series Characteristics / Parameter Integer type. Status of LwM2M. 0 Not Registered 1 Registering 2 Registered 3 Deregistering 4 Deregistered 5 Invalid 6 Recovering 7 Need Recovery Error code. For details of error codes, see Chapter 6. 4.3.13. AT+QLWRECOVER Manually Trigger LwM2M Context Recovery Process This command manually triggers the LwM2M context recovery process. The command is required to be executed only when the module wakes up from deep sleep mode. AT+QLWRECOVER Manually Trigger LwM2M Context Recovery Process Execution Command AT+QLWRECOVER Response OK +QLWURC: 'recovered',,, Maximum Response Time Characteristics If there is any error: +CMEE ERROR: 300 ms / Parameter Integer type. For details of status codes, see Chapter 6. Integer type. Server ID. 100 Bootstrap Server 101 Diagnostics Server 102 DM Server 1000 Repository Server BC660K-GL_LwM2M_Application_Note 30 / 55 NB-IoT Module Series Integer type. Server type. 0 DM Server 1 Bootstrap Server 2 Repository Server 3 Diagnostics Server Error code. For details of error codes, see Chapter 6. Example //The module has already connected to the server, the Iifetime has not expired, and the module is woken up from deep sleep mode. AT+QLWSTATUS? +QLWSTATUS: 7 //The LwM2M context needs to be recovered. OK AT+QLWRECOVER OK +QLWURC: 'recovered',0,102,0 //Recovered successfully. 4.4. LwM2M Related URCs This chapter introduces LwM2M related URCs. Table 2: LwM2M Related URCs Index Notification Display Description +QLWURC: 'ping',,, update operations. +QLWURC: 'write',,,,,,,, +QLWURC: 'read',,,, request from server. +QLWURC: 'execute',,,, request from server. +QLWURC: 'observe',,,,, request from server. [6] +QLWURC: 'bootstrapping' Notify TE that the bootstrap phase starts. BC660K-GL_LwM2M_Application_Note 31 / 55 NB-IoT Module Series [7] +QLWURC: 'bs_finished' Notify TE that the bootstrap phase has completed. Notify TE that the register phase [8] +QLWURC: 'registering',, starts. [9] +QLWURC: 'report', Notify TE that CON data has been sent. +QLWURC: 'report_ack',, acknowledged. +QLWURC: 'lifetime_changed',,, has been changed. Notify TE of the result of recovering +QLWURC: 'recovered',,, [12] LwM2M context from deep sleep mode. 4.4.1. +QLWURC: 'ping' Notify TE of Update Operation Result This URC notifies TE of a result of an update operation. +QLWURC: 'ping' Notify TE of Update Operation Result +QLWURC: 'ping',,, Parameter Integer type. For details of status codes, see Chapter 6. Integer type. Server ID. 100 Bootstrap Server 101 Diagnostics Server 102 DM Server 1000 Repository Server Integer type. Server type. 0 DM Server 1 Bootstrap Server 2 Repository Server 3 Diagnostics Server BC660K-GL_LwM2M_Application_Note 32 / 55 NB-IoT Module Series 4.4.2. +QLWURC: 'write' Notify TE to Respond to Write Request This URC notifies the TE to respond to a write request from server. The TE should respond to the request with AT+QLWWRRSP. +QLWURC: 'write' Notify TE to Respond to Write Request +QLWURC: 'write',,,,, Notify TE to respond to the write request from server. ,,, Parameter Integer type. Message ID. Integer type. Object ID. Integer type. Instance ID. Integer type. Resource ID. Integer type. The value types. 1 String 2 Opaque 3 Integer 4 Float 5 Boolean Integer type. The value length. When =1, the maximum length of is 1024 bytes. When =2, the maximum length of is 512 bytes. When =3, indicates the number of characters. When =4, indicates the number of characters. When =5, should be 1. String type. The value in hexadecimal string format received from the server. Integer type. The index number of the write request. If the write request is a combination of several messages, it should be split into several parts. If it is split into N parts, the order number of is N-1 to 0 in descending order, and the URC is sorted from the largest one to the smallest. If is 0, it means that this is the last message of the write request. Currently, only =0 is supported. 4.4.3. +QLWURC: 'read' Notify TE to Respond to Read Request This URC notifies the TE to respond to a read request from server. The TE should respond to the request with AT+QLWRDRSP. +QLWURC: 'read' Notify TE to Respond to Read Request +QLWURC: 'read',,,, NB-IoT Module Series Parameter Integer type. Message ID. Integer type. Object ID. Integer type. Instance ID. -1 indicates all resources under a specific object. Integer type. Resource ID. -1 indicates all resources under a specific instance. 4.4.4. +QLWURC: 'execute' Notify TE to Respond to Execute Request This URC notifies the TE to respond to the execute request from server. The TE should respond to the request with AT+QLWEXERSP. +QLWURC: 'execute' Notify TE to Respond to Execute Request +QLWURC: 'execute',, ,, Parameter Integer type. Message ID. Integer type. Object ID. Integer type. Instance ID. Integer type. Resource ID. 4.4.5. +QLWURC: 'observe' Notify TE to Respond to Observe Request This URC notifies the TE to respond to an observe request from server. The TE should respond to the request with AT+QLWOBSRSP. +QLWURC: 'observe' Notify TE to Respond to Observe Request +QLWURC: 'observe',, ,,, Parameter Integer type. Message ID. Indicates whether or not to observe. BC660K-GL_LwM2M_Application_Note 34 / 55 NB-IoT Module Series 0 Observe 1 Cancel observe Integer type. Object ID. Integer type. Instance ID. -1 indicates all resources under all instances. Integer type. Resource ID. -1 indicates all resources under a specific instance. 4.4.6. +QLWURC: 'bootstrapping' Notify TE that Bootstrap Phase Starts This URC notifies the TE that the bootstrap phase starts. +QLWURC: 'bootstrapping' Notify TE that the Bootstrap Phase starts +QLWURC: 'bootstrapping' Notify TE that the bootstrap phase starts. 4.4.7. +QLWURC: 'bs_finished' Notify TE that Bootstrap Phase Has Completed This URC notifies the TE that the bootstrap phase has completed. +QLWURC: 'bs_finished' Notify TE that Bootstrap Phase Has Completed +QLWURC: 'bs_finished' Notify TE that the bootstrap phase has completed. 4.4.8. +QLWURC: 'registering' Notify TE that Register Phase Starts This URC notifies the TE that the register phase starts. +QLWURC: 'registering' Notify TE that Register Phase Starts +QLWURC: 'registering',, Notify TE that the register phase starts. Parameter Integer type. Server ID. 100 Bootstrap Server 101 Diagnostics Server 102 DM Server 1000 Repository Server Integer type. Server type. 0 DM Server 1 Bootstrap Server 2 Repository Server 3 Diagnostics Server BC660K-GL_LwM2M_Application_Note 35 / 55 NB-IoT Module Series 4.4.9. +QLWURC: 'report' Notify TE that CON Data Has Been Sent This URC notifies the TE that CON data has been sent. +QLWURC: 'report' Notify TE that CON Data Has Been Sent +QLWURC: 'report', Notify TE that CON data has been sent. Parameter Integer type. Message ID. 4.4.10. +QLWURC: 'report_ack' Notify TE that CON Data Has Been Acked This URC notifies the TE that CON data has been acknowledged. +QLWURC: 'report_ack' Notify TE that CON Data Has Been Acked +QLWURC: 'report_ack',, Parameter Integer type. For details of status codes, see Chapter 6. Integer type. Message ID. 4.4.11. +QLWURC: 'lifetime_changed' Notify TE of Change in Registration Lifetime This URC notifies the TE of a change in registration lifetime. +QLWURC: 'lifetime_changed' Notify TE of Change in Registration Lifetime +QLWURC: 'lifetime_changed',,, Parameter Integer type. Lifetime of registration. Range: 50–31536000 (365 days). Unit: second. If lifetime ≤ 100 s, then the Actual Update Interval = 30 + (lifetime - 50) × 4/5 If lifetime ≤ 300 s, then the Actual Update Interval = 70 + (lifetime -