Download Zone

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

Filter

Welcome to the Quectel Download Zone!

Please use the search bar and filters to find the files you need to support your use of our products. You can also find these listed on the relevant pages of our Product Selector.

Access to most files will require a user account, so please either log in or register to download the files available to you.

Results

0 Files in basket

View basket

Antenna Brochure

Select all (max. 100)

1 Contents 01 Quectel Antenna Services 01 Quectel Advantages 01 Instruments 02 5G Antennas 04 Cellular (4G/3G/2G) Antennas 08 GNSS Antennas 14 Wi-Fi & Bluetooth Antennas 15 Combo Antennas 17 ISM Antennas 17 Cable Assemblies Quectel Antenna Services Consulting & Evaluation ■ Feasibility & Architecture Study ■ Risk Identiﬁcation ■ Initial Proof of Concept ■ Antenna Component Selection Testing & Certiﬁcation ■ Antenna OTA Testing ■ Interference Mitigation ■ Support for CE/FCC/PTCRB Radio Approval ■ Pre-certiﬁcation OTA Testing for 2G/3G/4G/5G Quectel Advantages Solutions for the Entire Wireless RF Front End Complete RF Antenna Testing Services Global One Stop Engineering Support Vertical Integration of Antenna Resources Approved for Use with Quectel Modules Instruments Design ■ Antenna Placement ■ Antenna Layout Design ■ RF Speciﬁcation Design ■ Antenna System Design & Optimization ■ Gerber File Review Manufacturing ■ Antenna Samples ■ Tooling & Molding ■ Assembly and Production Testing ■ Delivery Antenna Module Engineering Support Keysight CATR2305G Rhode & Schwarz WPTC-XS RayZone2800 ETS-AMS-8923-150 1 Quectel Antennas 5G Antennas Product YE0001BA YE0003AA YE0007AA YE0025AA Frequency Bands (MHz) 600–6000 Technology 5G Cable Length (mm) n/a Connector Type SMA Male (center pin) Mounting Type Terminal Dimensions (mm) 221 × 26.95 × 13.5 Matched Quectel Modules 5G/4G/3G/2G/LPWA 699–5000 5G n/a SMA Male (center pin) Terminal 190 × Φ 16 600–6000 5G n/a SMA Male (center pin) Terminal 152.4 × 21.79 × 14.49 698–960,1710–5000 5G n/a SMA Male (center pin) Terminal 199 × 22 5G Antennas Product YE0027AA YE0028AA YE0037AA YXH001AA YBY00A0KA Frequency Bands (MHz) 699–5000 Technology 5G Cable Length (mm) 3000 Connector Type SMA Male (center pin) Mounting Type Magnetic Dimensions (mm) 221 × Φ 61 Matched Quectel Modules 5G/4G/3G/2G/LPWA 700–2700, 3300–5000 5G 1500 SMA Male (center pin) Magnetic 234 × Φ 60 700–5000 5G 1000 SMA Male (center pin) Magnetic 88 × Φ 30 700–960, 1710–2690, 3300–5000 5G 1000 SMA Male (center pin) Magnetic 285 × 45 700–960, 1710–2690, 3300–5000 5G n/a N-J (Male pin with internal thread) Terminal Φ 20 × 300 The parameters shall be subject to the Speciﬁcation. 2 Quectel Antennas 5G Antennas Product YF0002AA YF0002BA YF0002CA YF0002DA Frequency Bands (MHz) 700-960, 1710-2700, 3300-5000 Technology 5G 1710-2700, 3300-5000 5G Cable Length (mm) n/a n/a Connector Type Spring contact Spring contact Mounting Type Screw Screw Dimensions (mm) 60.1 × 12.25 × 10.1 Matched Quectel Modules 5G/4G/3G/2G/LPWA 41.25 × 10.1 × 10.1 1710-2700, 3300-5000 5G n/a Spring contact Screw 37.25 × 9.6 × 10.1 700-960, 1710-2700, 3300-5000 5G n/a Spring contact Screw 50.25 × 20.1 × 10.1 5G Antennas Product YF0017AA YF0017BA YF0020AA YC0018AA YC0018AAEVB Frequency Bands (MHz) 1500–6000 Technology 5G Cable Length (mm) 193 ±3 Connector Type IPEX Ⅳ Mounting Type Adhesive Dimensions (mm) 49 × 13 × 0.13 Matched Quectel Modules 5G/4G/3G/2G/LPWA 1100–6000 5G 193 ±3 IPEX Ⅳ Adhesive 49 × 13 × 0.13 600–6000 5G 184 ±3 IPEX Ⅳ Adhesive 90.15 × 15.2 × 0.13 617-6000 5G n/a n/a SMD 42 × 7 × 3 617-6000 5G n/a n/a n/a 140 × 40.4 The parameters shall be subject to the Speciﬁcation. 3 Quectel Antennas 5G Antennas Product YP0009AA YP0009BA YP0009CA Frequency Bands (MHz) 1500–6000 Technology 5G Cable Length (mm) 193 ±3 Connector Type IPEX Ⅳ Mounting Type Adhesive Dimensions (mm) 49 × 13 × 0.85 Matched Quectel Modules 5G/4G/3G/2G/LPWA 1100–6000 5G 193 ±3 IPEX Ⅳ Adhesive 49 × 13 × 0.85 600–6000 5G 188 ±3 IPEX Ⅳ Adhesive 78.5 × 14.2 × 0.85 Cellular (4G/3G/2G) Antennas Product YC0001AA YC0002AA YC0003AA YC0003AAEVB YC0017BA YC0017BAEVB Frequency Bands 698–960, (MHz) 1710–2690 Technology LTE (4G) Cable Length (mm) n/a Connector Type n/a Mounting Type SMD Dimensions (mm) 35.0 × 8.5 × 3.0 Matched Quectel Modules 4G/3G/2G/LPWA 698–960, 1710–2690 LTE (4G) n/a n/a SMD 42 × 10 × 3 The parameters shall be subject to the Speciﬁcation. 4 698-2700 LTE (4G) n/a n/a SMD 40 × 7 × 3 698-2700 LTE (4G) n/a n/a n/a 120 × 43 698-3800 LTE (4G) n/a n/a SMD 26 × 8 × 3 698-3800 LTE (4G) n/a n/a n/a 140 × 36 Quectel Antennas Cellular (4G/3G/2G) Antennas Product YF0022AA YF0007BA YPCA004AA Frequency Bands (MHz) 700–2690 Technology LTE (4G) Cable Length (mm) 75 ±3 Connector Type RF1 Mounting Type Adhesive Dimensions (mm) 40 × 15 × 1.6 Matched Quectel Modules 4G/3G/2G/LPWA 600–960, 1427.9–1495.9, 1710–2170, 2300–2700 LTE (4G) 75 ±3 RF1 Adhesive 50 × 25 × 0.85 Cellular (4G/3G/2G) Antennas Product YFCA002AA YF0006DA 700–2690 LTE (4G) 100 ±3 IPEX Ⅰ Adhesive 40 ×10 × 1 YF0028AA Frequency Bands (MHz) 700–2690 Technology LTE (4G) Cable Length (mm) 75 ±3 Connector Type RF1 Mounting Type Adhesive Dimensions (mm) 30 × 20 × 0.13 Matched Quectel Modules 4G/3G/2G/LPWA 690–960, 1710–2170, 2300–2690 LTE (4G) 75±3 IPEX Ⅰ Adhesive 50 × 25 × 0.13 698-3000 LTE (4G) 150 ±2 IPEX Ⅰ Adhesive 96 × 21 × 0.2 The parameters shall be subject to the Speciﬁcation. 5 Quectel Antennas Cellular (4G/3G/2G) Antennas Product YECT002AA YECT003AA YE0009AA YPR00A0AA YCN001AA Frequency Bands (MHz) 700–960,1710–2690 Technology LTE (4G) Cable Length (mm) n/a Connector Type SMA Male (center pin) Mounting Type Terminal Dimensions (mm) 196.2 × 16 × 13 Matched Quectel Modules 4G/3G/2G/LPWA 698-960, 1710-2700 LTE (4G) n/a SMA Male (center pin) Terminal 113× Φ 10 824–2700 LTE (4G) n/a SMA Male (center pin) Terminal 190 × 16 700–2700 LTE (4G) n/a SMA Male (center pin) Terminal 194.3 ×15.95 700–2700 LTE (4G) n/a SMA Male (center pin) Terminal 144 × Φ 13 Cellular (4G/3G/2G) Antennas Product YE0006AA YE0010AA YB0010AA YB0016AA Frequency Bands (MHz) 700–2700 Technology LTE (4G) Cable Length (mm) 1500 Connector Type SMA Male (center pin) Mounting Type Magnetic Dimensions (mm) 318 × Φ 30 Matched Quectel Modules 4G/3G/2G/LPWA 698–2700 LTE (4G) 1000 ±30 SMA Male (center pin) Adhesive 152 × 18 × 5.9 The parameters shall be subject to the Speciﬁcation. 6 698–960, 1710–2690 LTE (4G) 2000 ±30 SMA Male Magnetic Φ 81.5 × 16 698–960, 1710–2700 LTE (4G) 3000 ±50 SMA Male (center pin) Screw 54 × 91 Quectel Antennas Cellular (4G/3G/2G) Antennas Product YE0012AA YE0021AA YE0029AA Frequency Bands 824–960, (MHz) 1710–2690 Technology LTE (4G) Cable Length (mm) 250 ±10 Connector Type SMA Male (center pin) Mounting Type Adhesive Dimensions (mm) 116.5 × 21.7 × 5.6 Matched Quectel Modules 4G/3G/2G/LPWA 690–960, 1710–2690 LTE (4G) 1500 ±30 SMA Male (center pin) Magnetic 112 × 29.8 700–2700 LTE (4G) 3000 ±50 SMA Male (center pin) Magnetic 88 × Φ 30 Cellular (4G/3G/2G) Antennas Product YDX001AA YE0002AA YE0013AA YGL001AA Frequency Bands (MHz) 824–2690 Technology LTE (4G) Cable Length (mm) n/a Connector Type SMA Male (center pin) Mounting Type Terminal Dimensions (mm) 208 × Φ 12 Matched Quectel Modules 4G/3G/2G/LPWA 699–2700 LTE (4G) n/a RP-SMA Male (center receptacle) Terminal 174.6 × 19.2 700–2700 LTE (4G) n/a SMA Male (center pin) Terminal 115.4 × 17.5 × Φ 10.2 700–960,1710–2690 LTE (4G) n/a SMA Male (center pin) Terminal 196.2 × 16 × 13 The parameters shall be subject to the Speciﬁcation. 7 Quectel Antennas Cellular (4G/3G/2G) Antennas Product YE0008AA YE0011AA YKL001CA Frequency Bands (MHz) 824–960, 1710–2170 , 2500–2700 Technology LTE (4G) Cable Length (mm) n/a Connector Type SMA Male (center pin) Mounting Type Terminal Dimensions (mm) 52 × Φ 10 Matched Quectel Modules LPWA/3G/2G module series 824–960, 1710–2170, 2500–2700 LTE (4G) n/a SMA Male (center pin) Terminal 50 × Φ 10 NB: 800–1000, 1700–1900 2G/3G/NB-IoT 310 ±10 SMA Male (center pin) Screw 50 × 48 GNSS Antennas Product YC0013AA YC0013AAEVB YC0008AA YC0008AAEVB Frequency Bands (MHz) 1559-1606 Technology GNSS Cable Length (mm) n/a Connector Type n/a Mounting Type SMD Dimensions (mm) 3.2 × 1.6 × 0.6 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS n/a n/a n/a 90 × 50 The parameters shall be subject to the Speciﬁcation. 8 1173, 1575 GNSS L1 & L5 (passive) n/a n/a SMD 30 × 5 × 5 GNSS L1/L5 module series 1173, 1575 GNSS L1 & L5 (passive) n/a n/a n/a 80 × 36 Quectel Antennas GNSS Antennas Product YCGA001AA YCGA002AA YG0038AA Frequency Bands (MHz) 1559-1606 Technology GNSS L1 Cable Length (mm) n/a Connector Type n/a Mounting Type Pin Mounting Dimensions (mm) 10 × 10 × 4 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS L1 n/a n/a Pin Mounting 12 × 12 × 4 1559-1606 GNSS L1 n/a n/a Pin Mounting 13 × 13 × 4 GNSS Antennas Product YG0043AA YG0046AA YG0005AA YG0062AA YG0048AA Frequency Bands (MHz) 1559-1606 Technology GNSS L1 Cable Length (mm) n/a Connector Type n/a Mounting Type Pin Mounting Dimensions (mm) 15 × 15 × 4 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS L1 n/a n/a Pin Mounting 18 × 18 × 2 1559-1606 GNSS L1 n/a n/a Pin Mounting 18 × 18 × 4 1559-1606 GNSS L1 n/a n/a Pin Mounting 25 × 25 × 4 1176, 1575 GNSS L1 & L5 n/a n/a Pin mounting 18 × 18 × 4 & 25 × 25 × 4 GNSS L1/L5 module series The parameters shall be subject to the Speciﬁcation. 9 Quectel Antennas GNSS Antennas Product YCGO004AA YCGO005AA YCGO006AA YCGO007AA YG0034AA YG0021AA Frequency Bands (MHz) 1559-1606 Technology GNSS L1 (passive) 1559-1606 GNSS L1 (passive) Cable Length (mm) 50±2 50±2 Connector Type IPEX Ⅰ IPEX Ⅰ Mounting Type Cable Mounting Cable Mounting Dimensions (mm) 10 × 10 × 6.5 15 × 15 × 6.5 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS L1 (passive) 50±2 IPEX Ⅰ Cable Mounting 18 × 18 × 6.5 1559-1606 GNSS L1 (passive) 50±2 IPEX Ⅰ Cable Mounting 25 × 25 × 6.5 1559–1606 GNSS L1 (active) 35±2 IPEX Ⅰ Cable Mounting 13 ×13 × 6.8 1560–1605 GNSS L1 & B1 & G1 (active) 42 ±3 IPEX Ⅰ Cable Mounting 18.4 × 18.4 × 8.86 GNSS Antennas Product YG0032AA YG0015AA YCGO008AA YCGO009AA YCGO010AA YCGO011AA Frequency Bands (MHz) Technology Beidou: 1561 ±5 ; GPS: 1575 ±5 GNSS L1 & B1 & G1 (active) Cable Length (mm) 55 1559–1606 GNSS L1 (active) 55 ±3 Connector Type IPEX Ⅰ IPEX Ⅰ Mounting Type Cable Mounting Cable Mounting Dimensions (mm) 18 × 18 × 6.6 25 × 25 × 8.25 Matched Quectel Modules GNSS L1 module series 1559-1606 GNSS L1 (active) 50±3 IPEX Ⅰ Cable Mounting 10 × 10 × 6.5 1559-1606 GNSS L1 (active) 50±2 IPEX Ⅰ Cable Mounting 15 × 15 × 6.5 1559-1606 GNSS L1 (active) 50±3 IPEX Ⅰ Cable Mounting 18 × 18 × 6.5 1559-1606 GNSS L1 (active) 50±3 IPEX Ⅰ Cable Mounting 25 × 25 × 6.5 The parameters shall be subject to the Speciﬁcation. 10 Quectel Antennas GNSS Antennas Product YCGS004AA YCGS005AA YCGS006AA Frequency Bands (MHz) 1560–1606 Technology GNSS L1 & G1 Cable Length (mm) n/a Connector Type n/a Mounting Type SMD Dimensions (mm) 9 × 9 × 4 Matched Quectel Modules GNSS L1 module series GNSS Antennas Product YAT001AA 1560–1606 GNSS L1 & G1 n/a n/a SMD 18 × 18 × 4 YAT001BA 1560–1606 GNSS L1 & G1 n/a n/a SMD 25 × 25 × 4 YBS00A1AA Frequency Bands (MHz) 1176, 1575 Technology GNSS L1 & L5 (active) Cable Length (mm) n/a Connector Type n/a Mounting Type Cable Mounting Dimensions (mm) 25 × 25 × 4 & 18 × 18 × 4 Matched Quectel Modules GNSS L1/L5 module series 1176, 1575 GNSS L1 & L5 (active) n/a n/a Cable Mounting 25 × 25 × 2 & 18 × 18 × 2 1176, 1575 GNSS L1 & L5 (active) n/a n/a Cable Mounting 40 × 40 × 4 & 45 × 45 × 6 The parameters shall be subject to the Speciﬁcation. 11 Quectel Antennas GNSS Antennas Product YAT001CA YG0030AA YCGO014AA Frequency Bands (MHz) 1176, 1575 Technology GNSS L1 & L5 (active) Cable Length (mm) 40 ±2 Connector Type IPEX Ⅰ Mounting Type Cable Mounting Dimensions (mm) 25 × 25 × 2 & 18 × 18 × 4 Matched Quectel Modules GNSS L1/L5 module series 1176, 1575 GNSS L1 & L5 (passive) 100 ±2 IPEX Ⅰ Cable Mounting 52 × 52 × 9.9 L5: 1166–1186 L1: 1559–1606 GNSS L1 & L5 (passive) 142 IPEX Ⅰ Cable Mounting 50 × 50 × 19.0 GNSS Antennas Product YFGA001AA YFGA002AA YFGA003AA YFGA004AA Frequency Bands 1160–1270, (MHz) 1560–1605 Technology GNSS L1 & 2 & L5 & L6 Cable Length (mm) 100 Connector Type IPEX Ⅰ Mounting Type Adhesive Dimensions (mm) 74.56 × 24.5 × 0.25 Matched Quectel Modules GNSS L1/L5 module series 1559–1609 GNSS L1 100 IPEX Ⅰ Adhesive 61.15 × 11.24 GNSS L1 module series The parameters shall be subject to the Speciﬁcation. 12 1559–1609 GNSS L1 100 IPEX Ⅰ Adhesive 39.45 x 13.25 1160–1270, 1560–1605 GNSS L1 & 2 & L5 & L6 100 IPEX Ⅰ Adhesive 43 × 24 × 0.12 GNSS L1/L5 modules Quectel Antennas GNSS Antennas Product YG0035AA YLY001CA YB0017AA YG0028AA Frequency Bands (MHz) 1561, 1575 Technology GNSS L1 & B1 & G1 (active) Cable Length (mm) 3000 ±20 Connector Type SMA Male (center pin) Mounting Type Magnetic Dimensions (mm) 50.3 × 38.4 × 17.1 Matched Quectel Modules GNSS L1 module series 1568 ±10 GNSS L1 & B1 & G1 (active) 2000 SMA Male (center pin) Magnetic 45.5 × 38 × 13.5 GPS L1/L5, BD B1/B2, GLONASS L1 1561–1602, 1166–1186 GNSS L1 & L5 (active) GNSS L1 & L5 (active) L = 3000 SMA Male (center pin) Magnetic 3000 SMA Male (center pin) Magnetic 61.5 × 56.5 × 23 Φ 54 × 38 GNSS L1/L5 module series GNSS Antennas Product YG0065AA YEGT001AA YEGT002AA YG0063AA Frequency Bands (MHz) 1575–1602 Technology GNSS L1 (active) Cable Length (mm) 3000 Connector Type FAKRA Female (Code C) Mounting Type Magnetic Dimensions (mm) 34.5 × 37.5 × 12.5 Matched Quectel Modules GNSS L1 modules 1559-1606 GNSS L1 n/a SMA Male (center pin) Terminal 50 × Ø10 All GNSS L1 modules 1559–1606 GNSS L1 n/a SMA Male (center pin) Terminal 52 × Ø10 GPS L1/L2/L5; BDS B1/B2/B3; GLONASS L1/L2; Galileo E1/E5a/E5b/E6; L-band All GNSS bands + L-band Corrections n/a TNC Female Screw Φ 165 × 68 All GNSS L1/L2/L5 modules The parameters shall be subject to the Speciﬁcation. 13 Quectel Antennas Wi-Fi & Bluetooth Antennas Product YC0009AA YC0010AA YEWM001AA Frequency Bands (MHz) 2400–2500 Technology Wi-Fi (Bluetooth) Cable Length (mm) n/a Connector Type n/a Mounting Type SMD Dimensions (mm) 3.2 × 1.6 × 0.5 Matched Quectel Modules FC30R 2400–2500 Wi-Fi (Bluetooth) n/a n/a SMD 5.2 × 2.0 × 1.2 2400–2500 Wi-Fi (Bluetooth) 1500 SMA Male (center pin) Magnetic Φ 30 ×77.4 Wi-Fi & Bluetooth Antennas Product YF0011AA YF0026AA YF0027AA YF0029AA YF0023AA YF0023CA Frequency Bands 2400–2500, (MHz) 5150–5850 2400–2500, 4900–5850, 5925-7125 2400–2500, 4900–5850, 5925-7125 2410–2490 , 4920–5925 2400–2500, 5150–5850, 5925-7125 2400–2500, 5150–5850, 5925-7125 Technology Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Wi-Fi (Bluetooth) Cable Length (mm) 44 ±13 100 ±2 100 ±2 100 ±2 100±2 Connector Type IPEX Ⅰ (U.FL Generation Ⅰ) IPEX Ⅰ (U.FL Generation Ⅰ) IPEX Ⅰ (U.FL Generation Ⅰ) IPEX Ⅰ (U.FL Generation Ⅰ) RF I Generation Mounting Type Adhesive Adhesive Adhesive Adhesive Adhesive 100±2 RF I Generation Adhesive Dimensions (mm) Matched Quectel Modules 38.9 × 9 × 0.12 All Wi-Fi/BT modules (Except Wi-Fi 6E) 28.9 × 11 × 0.2 All Wi-Fi/BT modules 42 × 7 × 0.2 30 × 30 × 0.25 All Wi-Fi/BT modules (Except Wi-Fi 6E) 22.90 × 11.70 All Wi-Fi/BT modules 37.80 × 7.50 The parameters shall be subject to the Speciﬁcation. 14 Quectel Antennas Wi-Fi & Bluetooth Antennas Product YE0031AA YE0032AA YE0038AA YEWT004AA YEWN001AA Frequency Bands 2.4–2.5 GHz, (MHz) 5.15–5.85 GHz Technology Wi-Fi (Bluetooth) 2.4–2.5 GHz, 5.15–5.85 GHz Wi-Fi (Bluetooth) Cable Length (mm) n/a n/a Connector Type SMA Male (center pin) SMA Male (center pin) Mounting Type Terminal Terminal Dimensions (mm) 52 ±2 50 ±2 Matched Quectel Modules All Wi-Fi/BT modules (Except Wi-Fi 6E) 2400–2500, 5150–5850 Wi-Fi (Bluetooth) n/a SMA Male (center pin) Terminal 195 × 13 2400–2500, 5150–7150 Wi-Fi 6E (Bluetooth) n/a SMA Male (center pin) Terminal 109 × Φ 10 All Wi-Fi/BT modules 2400–2500, 5150–5850 Wi-Fi (Bluetooth) n/a RP-SMA Male (Center Receptacle) Terminal 200 × 13 All Wi-Fi/BT modules (Except Wi-Fi 6E) Combo Antennas Product YB0007AA YB0008AA YB0009AA YB0014AA Frequency Bands (MHz) Technology 700–960, 1710–2690 , 3300–5000 5G Cable Length (mm) 500 Connector Type SMA Male (center pin) Mounting Type Screw Dimensions (mm) Matched Quectel Modules Φ 120 × 43 All 5G modules (RM50xQ Series, RG50xQ Series) & All 4G/3G/2G modules & GNSS L1 modules 4G MAIN: 698–960, 1710–2690; GNSS: 1575.42 ±5, 1561.098 ±5; 4G DIV: 1710–2690 Main LTE & DIV LTE & GNSS 300 SMA Male (center pin) Adhesive Φ 84 × 17.5 4G: 824–960, 1710–2690; GPS, BD: 1575.42 ±10, 1561 ±10 LTE & GNSS 310 SMA Male (center pin) Screw 33 × 48 All 4G/3G/2G modules & GNSS L1 modules LTE Main & Div: 698–960, 1700–2700; GNSS: 1561–1571; 1602–1606 Main LTE & DIV LTE & GNSS 3000 SMA Male (center pin) Screw 81 × 27.5 The parameters shall be subject to the Speciﬁcation. 15 Quectel Antennas Combo Antennas Product YB0015AA YKL001AA YB0032AA YB0033AA YB0022AA Frequency Bands (MHz) Technology LTE: 698–960, 1700–2700; Wi-Fi, Bluetooth: 2400– 2500; GNSS: 1561 ±5, 1575 ±5 LTE/GPS & BD/Wi-Fi Bluetooth: 2400–2500; 4G: 824–960; 1710–2690; GPS, BD: 1575.42 ±10, 1561 ±10 700–960, 1700–2700 LTE/GPS & BD/Wi-Fi Main LTE & DIV LTE Cable Length (mm) 300 310 2000 Connector Type SMA Male (center pin) SMA Male (center pin) SMA Male (Center Pin) Mounting Type Screw Screw Screw Dimensions (mm) 54 × 91 33 × 48 Φ 120 × 43 Matched Quectel Modules 4G/3G/2G modules & GNSS L1 modules & Wi-Fi modules All 4G/3G/2G modules LTE Main & Div: 700–960, 1700–2700 ; GNSS: 1559– 1610 (active) Main LTE & DIV LTE & GNSS 2000 LTE Main & Div: 700–2700; Wi-Fi: 2400–5850 ; GNSS: 1561/1575.42/1602 Main LTE & DIV LTE & GNSS & Wi-Fi1 & Wi-Fi2 1000 SMA Male (Center Pin) FME Female Connector Screw Screw Φ 120 × 43 All 4G/3G/2G modules & GNSS L1 modules Φ 120 × 43 4G/3G/2G modules & GNSS L1 modules & Wi-Fi, Bluetooth modules Combo Antennas Product YB0031AA YEMA003AA YEMA004AA YWL00A0AA YB0026AA YEWN004AA Frequency Bands (MHz) LTE: 698–960; 1710–2690; GNSS: 1575.42 ±5, 1561.098 ±5 LTE: 700–2700 1561/1575.42/1602 Technology LTE & GNSS LTE & GNSS Cable Length (mm) 300 3000 Connector Type SMA Male (center pin) 4G: FAKRA D GNSS: FAKRA C Mounting Type Dimensions (mm) Adhesive Φ 84 ×17.5 Adhesive Φ 84 × 17.5 Matched Quectel Modules All 4G/3G/2G modules & GNSS L1 modules 4G: 698–960 , 1710–2690 Wi-Fi & Bluetooth: 2400–2500 698–960, 1710–2690 LTE: 700–2700 ; Wi-Fi: 2400–5850; GNSS: 1561/1575.42/1602 2400–2500, 5150–5850 LTE & Wi-Fi Main LTE & DIV LTE LTE & GNSS & Wi-Fi1 & Wi-Fi2 Wi-Fi MIMO 900 1500 1000 300 GNSS: FAKRA_C, LTE: SMA Male (Center Pin) SMA Male (Center Pin) FAKRA_D, Wi-Fi 1: FAKRA_ SMA Male (Center Pin) I, Wi-Fi 2: FAKRA_I Screw Screw Screw Screw Φ 81 ×14.5 Φ 81 × 27.5 Φ 120 ×43 Φ 46 ×15 All 4G/3G/2G modules & Wi-Fi modules All 4G/3G/2G modules All 4G/3G/2G modules & GNSS L1 modules & Wi-Fi, Bluetooth modules Wi-Fi modules The parameters shall be subject to the Speciﬁcation. 16 Quectel Antennas ISM Antennas Product YE0019AA YE0039BA YEIM001AA Frequency Bands (MHz) Technology Cable Length (mm) Connector Type Mounting Type Dimensions (mm) 450–470 ISM SMA Male (center pin) Terminal 109 × 10 430-470, 790-960 ISM 75 SMA Male (center pin) Adhesive 117 × 21.81 × 5.47 Cable Assemblies Product YM0003AA YM0015AA YM0003CA 465–475 ISM 2000 SMA Male (center pin) Magnetic Φ 30 × 131 YM0003AB YM0013AA Frequency Bands (MHz) Technology Cable Length (mm) Connector Type Mounting Type Dimensions (mm) Matched Quectel Modules 0–6000 0–6000 Cable Cable 100 150 SMA-female to IPEX Ⅰ SMA-female to IPEX Ⅰ Screw Screw 100 150 All modules (5G excluded) 0–6000 Cable 200 SMA-female to IPEX Ⅰ Screw 200 0–6000 Cable 200 RP-SMA-female to IPEX Ⅰ Screw 200 0–6000 Cable 300 SMA-female to IPEX Ⅰ Screw 300 Product YM0004AA YM0005AA YSAN001AA YBY00A0HA YBY00A0JA YBY00A0IA Frequency Bands (MHz) Technology Cable Length (mm) Connector Type Mounting Type Dimensions (mm) Matched Quectel Modules 0–6000 0–6000 0–6000 Cable Cable Cable 100 150 300 SMA-female to IPEX Ⅳ SMA-female to RF Ⅳ SMA-female to RF Ⅳ Screw Screw Screw 100 150 300 All 5G modules (RM50xQ Series, RG50xQ Series) 0–6000 Cable 200 0–6000 Cable 250 N-K-female to IPEX Ⅰ N-female to IPEX Ⅰ Screw Screw 200 250 All modules (5G excluded) Bracket - - All modules The parameters shall be subject to the Speciﬁcation. 17 V1.7.4 2022.04

Quectel Antenna Brochure 2022

PDF

6.53 MB

Download

Application Note

Select all (max. 100)

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

Quectel_EP06&EG06&EM06_Series_FILE_Application_Note_V1.0

PDF

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

Quectel_EM12&EG12&EG18_Series_FILE_Application_Note_V1.0

PDF

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

Quectel_EG512R&EM12xR&EM160R_Series_FILE_Application_Note_V1.0

PDF

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

Quectel_EG06xK&Ex120K&EM060K_Series_FILE_Application_Note_V1.0

PDF

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

Quectel_BG95&BG77&BG600L_Series_Voice_Application_Note_V1.0

PDF

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

Quectel_BG95&BG77&BG600L_Series_MQTT-SN_Application_Note_V1.0

PDF

349.31 KB

Quectel_BG95&BG77&BG600L_Series_Voice_Application_Note_V1.0

PDF

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

Quectel_BG77xA-GL&BG95xA-GL_LwM2M_Application_Note_V1.0

PDF

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

Quectel_BG77xA-GL&BG95xA-GL_CoAP_Application_Note_V1.0

PDF

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

Quectel_EP06&EG06&EM06_Series_Data_Call_Application_Note_V1.0

PDF

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

Quectel_EM12&EG12&EG18_Series_Data_Call_Application_Note_V1.0

PDF

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

Quectel_EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note_V1.0

PDF

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

Quectel_EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note_V1.0

PDF

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

Quectel_EG060V-EA_RF_FTM_Application_Note_V1.0

PDF

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

Quectel_BG95&BG77&BG600L_Series_GTP_Application_Note_V1.0

PDF

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

Quectel_BG77xA-GL&BG95xA-GL_NIDD_Application_Note_V1.0

PDF

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&LTE 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

Quectel_BG77xA-GL&BG95xA-GL_EMUX_Application_Note_V1.0

PDF

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

Quectel_BG77xA-GL&BG95xA-GL_SSL_Application_Note_V1.0

PDF

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.

Quectel_BC65&BC92_HTTP(S)_Application_Note_V1.0

PDF

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&lt=900', the length is 40 bytes. Use & connect between multiple options. AT+QCOAPOPTION=0,0,15,40,'lwm2m=1.0&ep=867725030012276&b=U&lt=900' OK AT+QCOAPSEND=0 //Query the sending status of CoAP CON data +QCOAPSEND: 0,0 //Data is not sent. OK AT+QCOAPSEND=0,0,2,0 //Send a CON type POST request to the COAP server. > ;rt='oma.lwm2m';ct=11543,,,,,, 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&lt=1600', the length is 40 bytes. Use & connect between multiple options. AT+QCOAPOPTION=0,0,15,40,'lwm2m=1.0&ep=869154040004132&b=U&lt=1600' OK AT+QCOAPSEND=0 //Query the sending status of CoAP CON data +QCOAPSEND: 0,0 //Data is not sent. OK AT+QCOAPSEND=0,0,2,0 //Send a CON type POST request to the COAP server. > ;rt='oma.lwm2m';ct=11543,,,,,, OK //URC below is returned after the request is received from the server, with as 201, as 12345, as 132, as 4 bytes, as '01020304', as 8 and 8 corresponding to ' rd ' and '869154040004132' of respectively. +QCOAPURC: 0,2,201,12345,132,4,'01020304',8,'rd',8,'869154040004132' // After receiving the request from the server, 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

Quectel_BC65&BC92_CoAP_Application_Note_V1.0

PDF

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&lt=900' //Configure the CoAP option as 15 (Uri-Query), the option value is 'lwm2m=1.0&ep=867725030012276 &b=U&lt=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&lt=1600' //Configure the CoAP option as 15 (Uri-Query), the option value is 'lwm2m=1.0&ep=869619050023990&b=U&lt=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

Quectel_BC68-GV&BC95-GV_CoAP_Application_Note_V1.0

PDF

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

Quectel_EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note_V1.0

PDF

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 - 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 BC660K-GL_LwM2M_Application_Note 36 / 55 data, updates and resets registration lifetime. 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 NB-IoT Module Series 4.4.12. +QLWURC: 'binding_changed' Notify TE of Change in Binding Node This URC notifies the TE of a change in the binding mode. +QLWURC: 'binding_changed' Notify TE of Binding Mode Changed +QLWURC: 'binding_changed',,, Parameter String type. Only support 'U' or 'UQ'. 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 4.4.13. +QLWURC: 'recovered' Notify TE of LwM2M Context Recovery Result This URC notifies the TE of the result of recovering LwM2M context from deep sleep mode. +QLWURC: 'recovered' Notify TE of LwM2M Context Recovery Result +QLWURC: 'recovered',,, sleep mode. BC660K-GL_LwM2M_Application_Note 37 / 55 NB-IoT Module Series 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 38 / 55 NB-IoT Module Series 5 Examples 5.1. Manual Registration to LwM2M Server AT+CEREG? +CEREG: 0,1 //EPS network registered. (+CEREG: 0,5 indicating registered roaming service is also possible.) OK AT+CGPADDR=0 +CGPADDR: 0, '100.88.40.249' OK AT+QSCLK=0 // Disable sleep mode OK //Before configuring LwM2M information, you should check LwM2M status with AT+QLWSTATUS?, LwM2M information can be configured only when LwM2M status is 'Not Registered'. AT+QLWCONFIG=1,'bootp.iot.t-mobile.com',5584,'urn:imei:867997030052996',900,0,'urn:imei:86 7997030052996','3083693CF1E6766A2408BFD88278249A2DB498B40A6BF6049300FD47DE325CF C' OK AT+ QLWREG //Send a registration request. OK +QLWURC:'bootstrapping' +QLWURC: 'lifetime_changed',300,100,1 +QLWURC: 'binding_changed','U',100,1 +QLWURC: 'bs_finished' +QLWURC: 'registering',102,0 +QLWREG: 0 AT+QLWUPDATE=0,1000 +QLWUPDATE: 59797 //Registered successfully. BC660K-GL_LwM2M_Application_Note 39 / 55 OK +QLWUPDATE: 0,59797 AT+ QLWDEREG OK +QLWDEREG: 0 //Updated successfully. //De-registered successfully. NB-IoT Module Series 5.2. Custom Object Related Operations AT+CEREG? +CEREG: 0,1 //EPS network registered. (+CEREG: 0,5 indicating registered roaming service is also possible.) OK AT+CGPADDR=0 +CGPADDR: 0, '100.88.40.249' OK AT+QSCLK=0 OK // Disable sleep mode //Before configuring LwM2M information, you should check LwM2M status via AT+QLWSTATUS?, LwM2M information can be configured only when LwM2M status is 'Not Registered'. AT+QLWCONFIG=0,220.180.239.212,8085,'Test_dev',30,3 //Configure server relevant parameters. OK AT+QLWREG //Send a registration request. OK +QLWREG: 0 AT+QLWADDOBJ=19,0,5,0,1,2,3,4 OK //Registered successfully. //Add a custom object. +QLWADDOBJ: 0 +QLWURC: 'ping',0,102,0 AT+QLWADDOBJ? //Updated the object to server successfully. //Query the current custom object. +QLWADDOBJ: 19,0 OK BC660K-GL_LwM2M_Application_Note 40 / 55 NB-IoT Module Series //The application server has sent a read request to UE with the intention of reading the resource (9/0/0). +QLWURC: 'read',32191,9,0,0 AT+QLWRDRSP=32191,1,9,0,0,1,7,'quectel',0 OK +QLWRDRSP: 0 //The server has sent a write request to UE with the intention of writing the resource (9/0/3). +QLWURC: 'write',32193,9,0,3,2,1,'31',0 AT+QLWWRRSP=32193,2 OK +QLWWRRSP: 0 //The application server has sent an execute request to UE. +QLWURC: 'execute',32198,9,0,4 AT+QLWEXERSP=32198,2 OK +QLWEXERSP: 0 //The application server has observed the resource (9/0/0). +QLWURC: 'observe',32201,0,19,0,0 AT+QLWOBSRSP=32201,1,19,0,0,1,7,'quectel',0 OK +QLWOBSRSP: 0 AT+QLWNOTIFY=19,0,0,1,10,'0123456789',0,1 OK +QLWNOTIFY: 0 +QLWURC: 'report',34180 +QLWURC: 'report_ack',0,34180 //Report the data to server successfully. BC660K-GL_LwM2M_Application_Note 41 / 55 NB-IoT Module Series 5.3. Registration to Leshan LwM2M Server LwM2M Client features can be tested on Leshan server. Please follow the steps below to register to Leshan server: ⚫ In non-security mode: AT+QLWCONFIG=0,'leshan.eclipseprojects.io',5683,'urn:imei:866971030000717',900,3 OK ⚫ In PSK security mode: AT+QLWCONFIG=0,'leshan.eclipseprojects.io',5684,'urn:imei:867997030056338',900,0,'urn:imei: 867997030056338','30313233343536373839' OK If PSK security mode is used, client security configuration should be added into the web interface of the server according to steps illustrated below. Figure 7: Click 'Add new client security configuration' in SECURITY Tab BC660K-GL_LwM2M_Application_Note 42 / 55 NB-IoT Module Series Figure 8: Create 'New security configuration' on Leshan Server Figure 9: Check Created 'New security configuration' on Leshan Server BC660K-GL_LwM2M_Application_Note 43 / 55 NB-IoT Module Series AT+CEREG? +CEREG: 0,1 //EPS network registered (+CEREG: 0,5 indicates that registered roaming service is also possible). OK AT+CGPADDR=0 +CGPADDR: 0, '100.88.40.249' OK AT+QSCLK=0 // Disable sleep mode. OK AT+QLWCONFIG=0,'leshan.eclipseprojects.io',5684,'urn:imei:867997030056338',900,0,'urn:imei: 867997030056338','30313233343536373839' OK AT+QLWREG OK +QLWREG: 0 AT+QLWSTATUS? +QLWSTATUS: 2 //Registered successfully. //Query the current LwM2M status. //LwM2M status: registered. OK After successful connection to Leshan server, the server will present various operation permissions for each resource on the webpage. For instance, the 'Lifetime' value can be read through clicking 'Read' button on the webpage, and any resource value can be updated through clicking 'Write' button and then inputting a new value on the webpage. Figure 10: Online Client on Leshan Server BC660K-GL_LwM2M_Application_Note 44 / 55 NB-IoT Module Series Figure 11: 'Read' Operation on Leshan Server Figure 12: 'Write' Operation on Leshan Server 5.4. LwM2M Updates (Leshan Server) Periodically or based on certain events of LwM2M Client or initiated by the LwM2M Server, the LwM2M Client updates its registration information with an LwM2M Server by sending an 'Update' request to the LwM2M Server. 5.4.1. LwM2M Server Update Operation The 'Update' operation can be initiated by the LwM2M Server via an 'Execute' operation on the 'Registration Update Trigger' Resource of the LwM2M Server Object. The LwM2M Client can perform an 'Update' operation to refresh the lifetime of its registration to the LwM2M Server. BC660K-GL_LwM2M_Application_Note 45 / 55 NB-IoT Module Series Figure 13: 'Execute' Operation on Leshan Server +QLWURC: 'ping',0 //'Update' operation initiated by the LwM2M Server successfully. 5.4.2. LwM2M Client Update Operation When any of the parameters listed in the table below changes, the LwM2M Client must send an 'Update' operation to the LwM2M Server. The 'Update' operation must only contain parameters which have changed values compared to the last registration to the LwM2M Server. Table 3: Updateable Parameters Parameter Lifetime Binding Mode SMS Number Objects and Object Instances Required No No No No Three common LwM2M Client update operations are provided in the subsequent chapters. NOTE SMS number updating is not supported currently. BC660K-GL_LwM2M_Application_Note 46 / 55 NB-IoT Module Series 5.4.2.1. Extend Lifetime of Registration In this case the LwM2M Client sends an 'Update' operation with no parameters or with lifetime. The figure below shows an update flow example where the LwM2M Client sends an 'Update' operation that only refreshes the registration, i.e. the message does not contain any parameter. With the second 'Update' the Client changes the lifetime field to 6000 (unit: second) and hence the parameter is included in the message. Update ( = 6000) Figure 14: Update Flow Example //The LwM2M Client has registered to Leshan Server successfully, and the default update period is 30 seconds. The module will update periodically (every 30 seconds), and can change the lifetime by AT+QLWUPDATE. AT+CEREG? +CEREG: 0,1 //EPS network registered (+CEREG: 0,5 indicating registered roaming service is also possible). OK AT+CGPADDR? BC660K-GL_LwM2M_Application_Note 47 / 55 NB-IoT Module Series +CGPADDR: 1,100.97.37.69 OK AT+QLWCONFIG=0,'leshan.eclipse.org',5683,'urn:imei:866971030000717',30,3 OK AT+QLWREG OK +QLWREG: 0 AT+QLWUPDATE=0,200 +QLWUPDATE: 35270 //Registered successfully. OK +QLWUPDATE: 0,35270 //Updated successfully. Figure 15: Update Registration 5.4.2.2. Update Binding Mode of Registration //The LwM2M Client has registered to Leshan Server successfully. AT+QLWUPDATE=1,0 //Update binding mode as UDP mode. +QLWUPDATE: 38296 OK +QLWUPDATE: 0,38296 //Updated successfully. BC660K-GL_LwM2M_Application_Note 48 / 55 NB-IoT Module Series Figure 16: Update Binding Mode 5.4.2.3. Add/Remove Objects and Object Instances In this case the LwM2M Client sends an 'Update' operation with a body listing the complete list of objects and object instances. As illustrated below, the LwM2M Client starts with an initial registration with lifetime of 3000 seconds. Later, AT+QLWADDOBJ is executed to add objects 3303/0 and 3303/1. With the 'Update' operation, both of the LwM2M Client and the LwM2M Server include the new list of Objects and Object Instances. AT+CEREG? +CEREG: 0,1 OK AT+CGPADDR? +CGPADDR: 1,100.97.37.69 //EPS network registered (+CEREG: 0,5 indicates that registered roaming service is also possible). OK AT+QLWCONFIG=0,'leshan.eclipse.org',5683,'urn:imei:866971030000717',3000,3 OK AT+QLWREG OK +QLWREG: 0 //Registered successfully. AT+QLWADDOBJ=3303,0,3,5601,5602,5603 OK BC660K-GL_LwM2M_Application_Note 49 / 55 +QLWADDOBJ: 0 +QLWURC: 'ping',0 NB-IoT Module Series //Object list updated successfully. Figure 17: Update Object and Object Instance List 5.5. LwM2M Custom Object Related Operations (Leshan Server) Currently, BC660K-GL supports instance or resource level operations only for custom objects. 5.5.1. Observe Operation //The LwM2M Client has registered to Leshan Server successfully, and custom object 3303 is observed by the server. +QLWURC: 'observe',16987,0,3303,0,5601 //The server initiates an observation request for resource level (3303/0/5601) change. AT+QLWOBSRSP=16987,1,3303,0,5601,4,4,88.88,0 OK +QLWOBSRSP: 0 //Observed successfully. +QLWURC: 'observe',16988,0,3303,0,-1 //The server initiates an observation request for instance level (3303/0) change. BC660K-GL_LwM2M_Application_Note 50 / 55 AT+QLWOBSRSP=16988,1,3303,0,5601,4,4,88.88,0 OK +QLWOBSRSP: 0 //Observed successfully. NB-IoT Module Series 5.5.2. Notify Operation //The LwM2M Client has registered to Leshan Server successfully and object 3303 has been observed successfully by the server. AT+QLWNOTIFY=3303,0,5601,4,4,88.88,0,1 //Send CON data. OK +QLWNOTIFY: 0 +QLWURC: 'report',17111 +QLWURC: 'report_ack',0,17111 //Successfully responded to the notify request. 5.5.3. Read Operation //The LwM2M Client has registered to Leshan Server successfully and a read request related to 3303/0/5601 has been initiated by the LwM2M Server. +QLWURC: 'read',17123,3303,0,5601 AT+QLWRDRSP=17123,1,3303,0,5601,4,4,66.66,0 OK +QLWRDRSP: 0 //Successfully responded to the read request. 5.5.4. Execute Operation //The LwM2M Client has registered to Leshan Server successfully and an execute request related to 3303/0/5605 has been initiated by the LwM2M Server. +QLWURC: 'execute',27452,3303,0,5605 AT+QLWEXERSP=27452,2 OK +QLWEXERSP: 0 //Successfully responded to the execute request. BC660K-GL_LwM2M_Application_Note 51 / 55 6 Error Codes Table 4: Summary of LwM2M 0 1 2 3 4 7 13 15 32 33 34 Description Operation successful Other error Parameter number error Parameter value error Not register error Disable error Data length odd error Not ready to receive error Keep connecting error Already registered error Create LwM2M error Table 5: Summary of 0 1 2 3 4 9 Description Success Timeout Packet not sent Recovery failed Update failed Reset BC660K-GL_LwM2M_Application_Note NB-IoT Module Series 52 / 55 10 Bad request 13 Forbidden 14 Not found 22 Precondition failed NB-IoT Module Series BC660K-GL_LwM2M_Application_Note 53 / 55 NB-IoT Module Series 7 Appendix References Table 6: References Reference [1] Quectel_BC660K-GL_AT_Commands_Manual Table 7:Terms and Abbreviations Abbreviation 3GPP AS CIoT CoAP CON DTLS IMEI IoT IP IWMSC LwM2M MME NAS NB-IoT Description 3rd Generation Partnership Project Application Server Cellular Internet of Things Constrained Application Protocol Confirmable Datagram Transport Layer Security International Mobile Equipment Identity Internet of Things Internet Protocol Interworking Mobile Switching Center Lightweight Machine to Machine Mobility Management Entity Non-Access Stratum. Narrowband Internet of Things BC660K-GL_LwM2M_Application_Note 54 / 55 NON OMA PSK REST SCEF SGN SMS SMSC TCP TLS UDP UE URC Non-Confirmable Open Mobile Alliance Pre-shared Key Representational State Transfer Service Creation Environment Function Serving Gateway Node Short Message Service Short Message Service Center Transmission Control Protocol Transport Layer Security User Datagram Protocol User Equipment Unsolicited Result Code NB-IoT Module Series BC660K-GL_LwM2M_Application_Note 55 / 55

Quectel_BC660K-GL_LwM2M_Application_Note_V1.0

PDF

1.12 MB

RG500U-EA DFOTA Application Note 5G Module Series Version: 1.0 Date: 2022-09-06 Status: Released 5G Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. RG500U-EA_DFOTA_Application_Note 1 / 24 5G Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any thirdparty intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. RG500U-EA_DFOTA_Application_Note 2 / 24 5G Module Series About the Document Revision History Version Date - 2022-08-10 1.0 2022-09-06 Author Neil SHI Neil SHI Description Creation of the document First official release RG500U-EA_DFOTA_Application_Note 3 / 24 5G Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index .................................................................................................................................................. 5 1 Introduction ......................................................................................................................................... 6 2 Firmware Upgrade Procedure via DFOTA ........................................................................................ 7 2.1. Get Delta Firmware Package..................................................................................................... 8 2.2. Store Delta Firmware Package on FTP/HTTP(S) Server or in Local File System .................... 8 2.3. Check Network Status ............................................................................................................... 9 2.4. Execute AT Command to Update the Firmware ........................................................................ 9 3 Description of DFOTA AT Commands ............................................................................................ 10 3.1. AT Command Introduction ....................................................................................................... 10 3.1.1. Definitions...................................................................................................................... 10 3.1.2. AT Command Syntax .................................................................................................... 10 3.2. Declaration of AT Command Examples ....................................................................................11 3.3. AT+QFOTADL Upgrade Firmware via DFOTA .........................................................................11 3.3.1. AT+QFOTADL= Upgrade Firmware over FTP Server...............................11 3.3.2. AT+QFOTADL= Upgrade Firmware over HTTP Server ........................ 14 3.3.3. AT+QFOTADL= Upgrade Firmware over HTTPS Server ................... 16 3.3.4. AT+QFOTADL= Upgrade Firmware over Local File System .................... 18 4 Notes .................................................................................................................................................. 20 5 Result Codes ..................................................................................................................................... 21 6 Appendix References ....................................................................................................................... 23 RG500U-EA_DFOTA_Application_Note 4 / 24 5G Module Series Table Index Table 1: Types of AT Commands ............................................................................................................... 10 Table 2: Codes ......................................................................................................................... 21 Table 3: and Codes ....................................................................................... 21 Table 4: Codes.................................................................................................................................. 21 Table 5: Related Document........................................................................................................................ 23 Table 6: Terms and Abbreviations .............................................................................................................. 23 RG500U-EA_DFOTA_Application_Note 5 / 24 5G Module Series 1 Introduction Quectel RG500U-EA module supports DFOTA (Delta Firmware Over-The-Air) function, and the function can realize the wireless upgrade or downgrade of the module firmware. You can upgrade or degrade the firmware with delta firmware package over the air. The delta firmware package only contains the difference between the current firmware version and the target firmware version, with the amount of data transmission greatly reduced and the transmission time greatly shortened. RG500U-EA_DFOTA_Application_Note 6 / 24 5G Module Series 2 Firmware Upgrade Procedure via DFOTA The following chart illustrates the firmware upgrade procedure via DFOTA when the delta firmware package is stored on an FTP/HTTP/HTTPS server. 2. Store the package on an FTP/HTTP/HTTPS server. FTP/H TTP/HTT PS server 1. Get a delta firmware package. 5G NR/LTE/WCDMA (FTP/HTTP/HTTPS) 4. Automatically download the delta firmware package from the FTP/HTTP/HTTPS server through 5G NR/LTE/WCDMA network. External 3. Execute AT+QFOTADL MCU Quectel Module 5. Automatically upgrade the module s firmware. Figure 1: Firmware Upgrade Procedure via DFOTA RG500U-EA_DFOTA_Application_Note 7 / 24 5G Module Series As shown in the above figure, the firmware is updated via DFOTA by following steps: Step 1: Get a delta firmware package from Quectel or the agent. Step 2: Store the delta firmware package on an FTP/HTTP/HTTPS server or in the local file system of the module. Step 3: Execute AT+QFOTADL. Step 4: The module automatically downloads the package from the FTP/HTTP/HTTPS server via 5G NR/LTE/WCDMA network or upgrade the firmware package in the local file system directly. Step 5: The module’s firmware will be automatically upgraded. 2.1. Get Delta Firmware Package Before upgrading, check the current firmware version by executing ATI, and also confirm the target firmware version. Then send the two firmware versions to Quectel or the agent to get a delta firmware package. 2.2. Store Delta Firmware Package on FTP/HTTP(S) Server or in Local File System The steps for storing delta firmware package on the FTP/HTTP/HTTPS server are as follows: Step 1: Set up an FTP/HTTP/HTTPS server before using DFOTA function. (Quectel does not provide such servers.) Step 2: Store the delta firmware package on the server and record the storage path. It is recommended that, the storage path of delta firmware package in local file system be: /mnt/data/update/update.zip. NOTE If the module automatically downloads the delta firmware package from the FTP/HTTP/HTTPS server via 5G NR/LTE/WCDMA network, the storage path of delta firmware package may not be /mnt/data/update/update.zip. RG500U-EA_DFOTA_Application_Note 8 / 24 5G Module Series 2.3. Check Network Status After the module is booted, make sure that the module has registered on the network before upgrading the firmware. Network registration commands are as follows. See document [1] for details. ⚫ AT+COPS? Query the current mode and the selected operator ⚫ AT+CEREG? Query the EPS network registration status ⚫ AT+CREG? Query the CS domain network registration status ⚫ AT+CGATT? Query the PS domain attachment status ⚫ AT+CGPADDR? Query the IP address assigned by the default PDP ⚫ AT+C5GREG? Query the 5GS network registration status ⚫ AT+QNETDEVSTATUS= Query the RmNet device status 2.4. Execute AT Command to Update the Firmware Execute AT+QFOTADL after the module has registered on the network, and then the module downloads the delta firmware package from the FTP/HTTP/HTTPS server over the air or gets the delta firmware package from the local file system and upgrade the firmware automatically. For more details about the AT commands, see Chapter 3.3. RG500U-EA_DFOTA_Application_Note 9 / 24 5G Module Series 3 Description of DFOTA AT Commands 3.1. AT Command Introduction 3.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on 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. RG500U-EA_DFOTA_Application_Note 10 / 24 5G Module Series 3.2. Declaration of AT Command Examples The AT command examples in this document are provided to help you learn about the use of the AT commands introduced herein. The examples, however, should not be taken as Quectel’s recommendations or suggestions about how to design a program flow or what status to set the module into. Sometimes multiple examples may be provided for one AT command. However, this does not mean that there is a correlation among these examples, or that they should be executed in a given sequence. 3.3. AT+QFOTADL Upgrade Firmware via DFOTA This command enables automatic firmware upgrade via DFOTA. After the delta firmware package is stored on the FTP/HTTP/HTTPS server or in the local file system, you can execute AT+QFOTADL related commands to download the delta firmware package from FTP/HTTP/HTTPS server or local file system. After the package is obtained successfully, the module will automatically upgrade the firmware and reboot. AT+QFOTADL Upgrade Firmware via DFOTA Test Command AT+QFOTADL=? Response OK Maximum Response Time 300 ms Characteristics / 3.3.1. AT+QFOTADL= Upgrade Firmware over FTP Server If the delta firmware package is stored on an FTP server, execute AT+QFOTADL= to enable DFOTA upgrade over FTP server. Then the module will download the package from the FTP server over the air and upgrade the firmware automatically. AT+QFOTADL= Upgrade Firmware over FTP Server Write Command AT+QFOTADL= Response OK +QIND: 'FOTA','FTPSTART' +QIND: 'FOTA','FTPDL', ... +QIND: 'FOTA','FTPDL', RG500U-EA_DFOTA_Application_Note 11 / 24 Maximum Response Time Characteristics 5G Module Series +QIND: 'FOTA','FTPEND', +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ... +QIND: 'FOTA','END', If there is any error: ERROR 300 ms / Parameter String type. URL of the delta firmware package on FTP server. Maximum length: 255 bytes. It should be started with 'ftp://'. For example, 'ftp://:@:/'. String type. The user name for authentication. Maximum length: 50 bytes. String type. The password for authentication. Maximum length: 50 bytes. String type. The IP address of the FTP server. Maximum length: 50 bytes. Integer type. The port of the FTP server. Range: 1–65535. Default value: 21. String type. The file path on FTP server. Maximum length: 50 bytes. Integer type. The download or upgrade progress in percentage. Range: 0–100. Integer type. FTP result code. 0 Download the delta firmware package successfully Other values Failed to download the delta firmware package. See Table 2 for details. Integer type. Result codes of upgrade. 0 Upgrade the firmware successfully Other values Failed to upgrade the firmware. See Table 4 for details. RG500U-EA_DFOTA_Application_Note 12 / 24 5G Module Series Example //Upgrade firmware after the delta firmware package is stored on an FTP server. For example, the FTP server address is 'ftp://test:test@124.74.41.170:21/update.zip'. Execute the following command to enable DFOTA upgrade over FTP server. The module will start to download the delta firmware package and upgrade firmware automatically. AT+QFOTADL='ftp://test:test@124.74.41.170:21/update.zip' OK +QIND: 'FOTA','FTPSTART' +QIND: 'FOTA','FTPDL',1 +QIND: 'FOTA','FTPDL',15 ... +QIND: 'FOTA','FTPDL',100 +QIND: 'FOTA','FTPEND',0 //Finish downloading the delta firmware package from the FTP server. //The module will reboot automatically and enter recovery mode. The USB port will be re-initialized. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',20 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //Firmware is updated successfully. //The module will reboot automatically and enter normal mode. RG500U-EA_DFOTA_Application_Note 13 / 24 5G Module Series 3.3.2. AT+QFOTADL= Upgrade Firmware over HTTP Server If the delta firmware package is stored on an HTTP server, execute AT+QFOTADL= to enable DFOTA upgrade over HTTP server. Then the module will download the package from the HTTP server over the air and upgrade the firmware automatically. AT+QFOTADL= Upgrade Firmware over HTTP Server Write Command AT+QFOTADL= Response OK +QIND: 'FOTA','HTTPSTART' +QIND: 'FOTA','HTTPDL', ... +QIND: 'FOTA','HTTPDL', +QIND: 'FOTA','HTTPEND', +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ... +QIND: 'FOTA','END', Maximum Response Time Characteristics If there is any error: ERROR 300 ms / Parameter String type. URL of the delta firmware package on HTTP server. Maximum length: 255 bytes. It should be started with 'http://'. For example, 'http://:/'. String type. The IP address or domain name of the HTTP server. Integer type. The port of the HTTP server. Range: 1–65535. Default value: 80. RG500U-EA_DFOTA_Application_Note 14 / 24 5G Module Series String type. The file path on HTTP server. Integer type. HTTP result code. 0 Download the delta firmware package successfully Other values Failed to download the delta firmware package. See Table 3 for details. Integer type. The download or upgrade progress in percentage. Range: 0–100. Integer type. Result codes of upgrade. 0 Upgrade the firmware successfully Other values Failed to upgrade the firmware. See Table 4 for details. Example //Upgrade firmware after the delta firmware package is stored on an HTTP server. The HTTP server address is 'http://www.quectel.com:100/update.zip'. Execute the following command to enable DFOTA upgrade over HTTP server, and then the module will start to download the delta firmware package and upgrade firmware automatically. AT+QFOTADL='http://www.quectel.com:100/update.zip' OK +QIND: 'FOTA','HTTPSTART' +QIND: 'FOTA','HTTPDL',1 +QIND: 'FOTA','HTTPDL',15 ... +QIND: 'FOTA','HTTPDL',100 +QIND: 'FOTA','HTTPEND',0 //Finish downloading the delta firmware package from the HTTP server. //The module will reboot automatically and enter recovery mode. The USB port will be re-initialized. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',2 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //Firmware is updated successfully. //The module will reboot automatically and enter normal mode. RG500U-EA_DFOTA_Application_Note 15 / 24 5G Module Series 3.3.3. AT+QFOTADL= Upgrade Firmware over HTTPS Server If the delta firmware package is stored on an HTTPS server, execute AT+QFOTADL= to enable DFOTA upgrade over HTTPS server. Then the module will download the package from the HTTPS server over the air and upgrade the firmware automatically. AT+QFOTADL= Upgrade Firmware over HTTPS Server Write Command AT+QFOTADL= Response OK +QIND: 'FOTA','HTTPSSTART' +QIND: 'FOTA','HTTPSDL', ... +QIND: 'FOTA','HTTPSDL', +QIND: 'FOTA','HTTPSEND', +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ... +QIND: 'FOTA','END', Maximum Response Time Characteristics If there is any error: ERROR 300 ms / Parameter String type. URL of the delta firmware package on HTTPS server. Maximum length: 255 bytes. It should be started with 'https://'. For example, 'https://:/'. String type. The IP address or domain name of the HTTPS server. Integer type. The port of the HTTP server. RG500U-EA_DFOTA_Application_Note 16 / 24 5G Module Series Range: 1–65535. Default value: 80. String type. The file path on HTTPS server. Integer type. HTTPS result code. 0 Download the delta firmware package successfully Other values Failed to download the delta firmware package. See Table 3 for details. Integer type. The download or upgrade progress in percentage. Range: 0–100. Integer type. Result codes of upgrade. 0 Upgrade the firmware successfully Other values Failed to upgrade the firmware. See Table 4 for details. Example //Upgrade firmware after the delta firmware package is stored on an HTTPS server. The HTTPS server address is 'https://www.quectel.com:100/update.zip'. Execute the following command to enable DFOTA upgrade over HTTPS server, and then the module will start to download the delta firmware package and upgrade firmware automatically. AT+QFOTADL='https://www.quectel.com:100/update.zip' OK +QIND: 'FOTA','HTTPSSTART' +QIND: 'FOTA','HTTPSDL',1 +QIND: 'FOTA','HTTPSDL',20 ... +QIND: 'FOTA','HTTPSDL',100 +QIND: 'FOTA','HTTPSEND',0 //Finish downloading the delta firmware package from the HTTPS server. //The module will reboot automatically and enter recovery mode. The USB port will be re-initialized. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',2 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //Firmware is updated successfully. //The module will reboot automatically and enter normal mode. RG500U-EA_DFOTA_Application_Note 17 / 24 5G Module Series 3.3.4. AT+QFOTADL= Upgrade Firmware over Local File System If the delta firmware package has already been stored in the local file system, execute AT+QFOTADL= to enable DFOTA upgrade over local file system. Then the module will upgrade the firmware automatically. AT+QFOTADL= Upgrade Firmware over Local File System Write Command AT+QFOTADL= Response OK +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING', +QIND: 'FOTA','UPDATING', ... +QIND: 'FOTA','END', Maximum Response Time Characteristics If there is any error: ERROR 300 ms / Parameter String type. The path under which the delta firmware package is stored in the local file system. Maximum length: 255 bytes. The recommended path is /mnt/data/update/update.zip. Integer type. The upgrade progress in percentage. Range: 0–100. Integer type. Result codes of upgrade. 0 Upgrade the firmware successfully Other values Failed to upgrade the firmware. See Table 4 for details. RG500U-EA_DFOTA_Application_Note 18 / 24 5G Module Series Example //Upgrade firmware when the delta firmware package is stored in the local file system. AT+QFOTADL='/mnt/data/update/update.zip' OK //The module will reboot automatically and enter recovery mode. The USB port will be re-initialized. +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',1 +QIND: 'FOTA','UPDATING',2 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 //Firmware is updated successfully. //The module will reboot automatically and enter normal mode. RG500U-EA_DFOTA_Application_Note 19 / 24 5G Module Series 4 Notes Before upgrading the firmware, you need pay attention to the following when you have obtained the delta firmware package from FTP/HTTP/HTTPS server or the local file system: 1. If the module is powered down when it is in 'UPDATING' state, it will automatically enter the forced upgrade mode, that is, the upgrade will continue after the module is rebooted next time. The upgrade progress is as follows: +QIND: 'FOTA','START' +QIND: 'FOTA','UPDATING',20 +QIND: 'FOTA','UPDATING',30 ... +QIND: 'FOTA','UPDATING',100 +QIND: 'FOTA','END',0 2. When the module enters recovery mode after downloading the delta firmware package, it verifies the delta firmware package firstly. If an error occurs in the delta firmware package, an error code will be reported through URC. See Table 4 for details of the error codes. If the firmware is upgraded successfully, the module will reboot and enter normal mode. If the firmware failed to be upgraded, the module will reboot and enter recovery mode again, and then retry to upgrade the firmware until the upgrade is successful. The firmware will try to be upgraded consecutively for a maximum of 10 times. RG500U-EA_DFOTA_Application_Note 20 / 24 5G Module Series 5 Result Codes This chapter introduces the result codes related to Quectel module or network. The details about , , and are described as follows. Table 2: Codes 0 601 602 Description Download the delta firmware package from the FTP server successfully FTP Unknown error URL length exceeds limit Table 3: and Codes / 0 Description Download the delta firmware package from the HTTP(S) server successfully 701 HTTP(S) unknown error 702 HTTP(S) URL length exceeds limit Table 4: Codes 0 502 505 Description DFOTA upgrade successfully The upgrade process exits due to some unknown errors or exceptions, or the delta firmware package is incorrect. The module will reboot and enter recovery mode, and then retry to upgrade the firmware until the upgrade is successful. The firmware will try to be upgraded consecutively for a maximum of 10 times. Verification of the delta firmware package fails due to an error of Zip format. If the Zip format is wrong, the delta firmware package will be deleted. RG500U-EA_DFOTA_Application_Note 21 / 24 5G Module Series The delta firmware package does not match the current firmware version of the 510 module. Check whether the delta firmware package is correct. 511 The file system has no enough space for upgrade. Failed to upgrade the firmware. The module will reboot and enter recovery mode, and 520 then retry to upgrade the firmware until the upgrade is successful. The firmware will try to be upgraded consecutively for a maximum of 10 times. RG500U-EA_DFOTA_Application_Note 22 / 24 5G Module Series 6 Appendix References Table 5: Related Document Document Name [1] Quectel_RG500U-EA_AT_Commands_Manual Table 6: Terms and Abbreviations Abbreviation 5G NR 5GS CS DFOTA EPS FTP GPRS HTTP HTTPS IP LTE MCU PDN PS URC Description 5th Generation New Radio 5G System Circuit Switched Delta Firmware Upgrade Over-The-Air Evolved Packet System File Transfer Protocol General Packet Radio Service Hypertext Transfer Protocol Hypertext Transfer Protocol Secure Internet Protocol Long Term Evolution Microcontroller Unit Public Data Network Packet Switch Unsolicited Result Code RG500U-EA_DFOTA_Application_Note 23 / 24 USB URL WCDMA Universal Serial Bus Uniform Resource Locator Wideband Code Division Multiple Access 5G Module Series RG500U-EA_DFOTA_Application_Note 24 / 24

Quectel_RG500U-EA_DFOTA_Application_Note_V1.0

PDF

369.81 KB

LC26G&LC76G&LC86G Series AGNSS Application Note GNSS Module Series Version: 1.0 Date: 2022-10-10 Status: Released GNSS Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 1 / 44 GNSS Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade. Privacy Policy To implement module functionality, certain device data are uploaded to Quectel’s or third-party’s servers, including carriers, chipset suppliers or customer-designated servers. Quectel, strictly abiding by the relevant laws and regulations, shall retain, use, disclose or otherwise process relevant data for the purpose of performing the service only or as permitted by applicable laws. Before data interaction with third parties, please be informed of their privacy and data security policy. Disclaimer a) We acknowledge no liability for any injury or damage arising from the reliance upon the information. b) We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein. c) While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable. d) We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources. Copyright © Quectel Wireless Solutions Co., Ltd. 2022. All rights reserved. LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 2 / 44 GNSS Module Series About the Document Document Information Title LC26G&LC76G&LC86G Series AGNSS Application Note Subtitle GNSS Module Series Document Type Application Note Document Status Released Revision History Revision 1.0 Date 2022-07-11 2022-10-10 Description Creation of the document First official release LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 3 / 44 GNSS Module Series Contents About the Document ................................................................................................................................... 3 Contents ....................................................................................................................................................... 4 Table Index................................................................................................................................................... 6 Figure Index ................................................................................................................................................. 7 1 Introduction .......................................................................................................................................... 8 1.1. Differences Between Host EPO and Flash EPO ...................................................................... 8 1.2. AGNSS Requirements............................................................................................................... 9 2 Download EPO Files .......................................................................................................................... 10 2.1. Get EPO Files from Server...................................................................................................... 10 2.2. EPO File Format ...................................................................................................................... 11 2.2.1. EPO File Format – GPS Only ........................................................................................ 12 2.2.2. EPO File Format – BDS/Galileo Only ............................................................................ 13 2.2.3. EPO File Format – GPS + GLONASS ........................................................................... 15 2.3. EPO File Types........................................................................................................................ 15 2.4. Recommended Download Procedures of EPO Files .............................................................. 16 2.5. EPO File Validity Period .......................................................................................................... 17 3 AGNSS Implementation..................................................................................................................... 19 3.1. AGNSS with Flash EPO .......................................................................................................... 19 3.1.1. Binary Protocol ............................................................................................................... 19 3.1.2. EPO Data Transfer Protocol .......................................................................................... 21 3.1.2.1 Pseudo Code for EPO Data Transfer Protocol ...................................................... 21 3.1.3. AGNSS Procedure with Flash EPO ............................................................................... 25 3.2. AGNSS with Host EPO............................................................................................................ 26 3.2.1. Recommended Sequence for Host EPO ....................................................................... 26 3.2.2. Sample Code to Send EPO ........................................................................................... 27 4 AGNSS Related Messages ................................................................................................................ 30 4.1. PAIR470 PAIR_EPO_GET_STATUS ..................................................................................... 30 4.2. PAIR471 PAIR_EPO_SET_DATA .......................................................................................... 31 4.3. PAIR472 PAIR_EPO_ERASE_FLASH_DATA ....................................................................... 32 4.4. PAIR590 PAIR_TIME_SET_REF_UTC .................................................................................. 33 4.5. PAIR600 PAIR_LOC_SET_REF ............................................................................................. 34 5 Download EPO Data with QGNSS .................................................................................................... 36 5.1. Download Flash EPO with QGNSS......................................................................................... 36 5.2. Download Host EPO with QGNSS .......................................................................................... 37 6 AGNSS Implementation Example..................................................................................................... 39 6.1. Flash EPO Implementation...................................................................................................... 39 6.2. Host EPO Implementation ....................................................................................................... 40 7 Appendix A References..................................................................................................................... 42 LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 4 / 44 GNSS Module Series 8 Appendix B Special Characters ....................................................................................................... 44 LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 5 / 44 GNSS Module Series Table Index Table 1: Differences Between Flash EPO and Host EPO ........................................................................... 8 Table 2: AGNSS Related Commands.......................................................................................................... 9 Table 3: Download URL of EPO Files........................................................................................................ 10 Table 4: EPO Data SVID Range ................................................................................................................ 11 Table 5: EPO File Types ............................................................................................................................ 15 Table 6: Description of Binary Protocol Fields........................................................................................... 20 Table 7: Start of EPO Binary Format ......................................................................................................... 20 Table 8: EPO Data Binary Format ............................................................................................................. 20 Table 9: End of EPO Binary Format .......................................................................................................... 20 Table 10: Related Document ..................................................................................................................... 42 Table 11: Terms and Abbreviations ........................................................................................................... 42 Table 12: Special Characters..................................................................................................................... 44 LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 6 / 44 GNSS Module Series Figure Index Figure 1: EPO File Format – GPS Only ..................................................................................................... 12 Figure 2: Format of Several Segments of EPO Files ................................................................................ 12 Figure 3: EPO File Format – BDS/Galileo Only......................................................................................... 13 Figure 4: Galileo EPO Header ................................................................................................................... 14 Figure 5: BDS EPO Header ....................................................................................................................... 14 Figure 6: EPO File Format – GPS + GLONASS........................................................................................ 15 Figure 7: Recommended Download Procedures of EPO Files ................................................................. 16 Figure 8: Binary Protocol Structure ............................................................................................................ 19 Figure 9: AGNSS Procedure with Flash EPO............................................................................................ 25 Figure 10: Suggested Sequence for Host EPO ......................................................................................... 27 Figure 11: QGNSS Interface for Setting Flash EPO.................................................................................. 36 Figure 12: Download Flash EPO File......................................................................................................... 37 Figure 13: QGNSS Interface for Setting Host EPO ................................................................................... 38 Figure 14: Download Host EPO File .......................................................................................................... 38 LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 7 / 44 GNSS Module Series 1 Introduction EPO (Extended Prediction Orbit) is an AGNSS feature implemented by the chipset supplier, which should improve the TTFF duration of the GNSS receivers. This document mainly describes the EPO file downloading process, AGNSS implementation, EPO related PAIR commands and how to download EPO data through the QGNSS tool. Please be aware that AGNSS can’t improve the TTFF duration in cases where the signal level is too low (either due to poor RF design, or signal reception quality). 1.1. Differences Between Host EPO and Flash EPO Both methods (Host EPO and Flash EPO) help the GNSS receiver to shorten the TTFF duration, but their differences make each of them suitable for different applications. Host EPO (also called Real Time AGNSS) allows the receiver to store data in the internal RAM. Up to 6 hours of assistance data are sent to the receiver through NMEA PAIR commands listed in Chapter 4 AGNSS Related Messages. For Host EPO, there is no data retention after the GNSS receiver reboots, and the data should be re-downloaded. Flash EPO, on the other hand, allows the receiver to store in the flash for 3, 7 or 14 days’ assistance data which are sent to the receiver through Binary Protocol defined by the chipset supplier. Flash EPO enables the receiver to reuse all assistance information stored in flash before the information expires. See Chapter 2.5 EPO File Validity Period for the validity period of EPO files. Table 1: Differences Between Flash EPO and Host EPO Type Storage Space Storage Capacity Protocol Flash EPO Flash 3, 7 and 14 days’ assistance data Binary Host EPO RAM 6-hour assistance data NMEA (ASCII) NOTE The maximum flash memory EPO data retention period is 14 days for GPS-only and GPS + GLONASS LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 8 / 44 GNSS Module Series EPO files, 7 days for Galileo EPO files and 3 days for BDS EPO files. If 30-day GPS-only or GPS + GLONASS EPO files are sent, only the first 14 days of EPO data will be stored. 1.2. AGNSS Requirements The host needs to provide the Reference Time, Reference Position and EPO data to the GNSS receiver. The information provided by the host must meet the following requirements so that the GNSS receiver can make better use of EPO: ⚫ The Reference Time should be accurate within 3 seconds and must be specified in UTC time. ⚫ The Reference Position should be accurate within 30 km from the receiver’s actual position. Keep in mind that if the receiver’s view of the sky is limited, the accuracy of the Reference Position needs to be increased. ⚫ The EPO data should be valid. Wrong (out of boundaries) reference time and position will extend the TTFF duration. The receiver can benefit from any of the assistance data to improve the TTFF. All assistance data (Reference Time, Reference Position and EPO data) are useful but none of them are mandatory. If some of them are not available or have expired, it is recommended to avoid using them. The host can provide the Reference Time, Reference Position and EPO data to the GNSS receiver through the messages listed in the following table. See Chapter 4 AGNSS Related Messages for a detailed description of these messages. Table 2: AGNSS Related Commands Packet Type $PAIR471 $PAIR590 $PAIR600 Data Content GPS/GLONASS/Galileo/BDS EPO data for a single satellite. Reference UTC Time. Reference Position. LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 9 / 44 GNSS Module Series 2 Download EPO Files Quectel does not provide any Service Level Agreement for the EPO files. You are expected to download the EPO data to your own server and share the files to end devices to ensure EPO data availability. 2.1. Get EPO Files from Server Table 3: Download URL of EPO Files EPO Type Unified QEPO Unified QEPO Unified QEPO Unified QEPO EPO EPO EPO EPO GNSS Type EPO File URL File Name GPS only GPS + GLONASS BDS only Galileo only GPS only GPS + GLONASS BDS only Galileo only http://wpepodownload.mediatek.co m/QGPS.DAT?vendorinfo http://wpepodownload.mediatek.co m/QG_R.DAT?vendorinfo http://wpepodownload.mediatek.co m/QBD2.DAT?vendorinfo http://wpepodownload.mediatek.co m/QGA.DAT?vendorinfo http://wpepodownload.mediatek.co m/EPO_GPS_3_X.DAT?vendorinfo http://wpepodownload.mediatek.co m/EPO_GR_3_X.DAT?vendorinfo http://wpepodownload.mediatek.co m/EPO_BDS_3.DAT?vendorinfo http://wpepodownload.mediatek.co m/EPO_GAL_X.DAT?vendorinfo Single name: QGPS.DAT Single name: QG_R.DAT Single name: QBD2.DAT Single name: QGA.DAT X = 1–10 EPO_GPS_3_1.DAT to EPO_GPS_3_10.DAT X = 1–10 EPO_GR_3_1.DAT to EPO_GR_3_10.DAT EPO_BDS_3.DAT X = 3 or 7 EPO_GAL_3.DAT or EPO_GAL_7.DAT The following is a complete URL sample: http://wpepodownload.mediatek.com/QGPS.DAT?vendor=AAA&project=BBB&device_id=CCC ⚫ The query string starts with '?' and is separated by '&'. ⚫ The values of 'vendor' and 'project' (AAA and BBB in the example) are issued by Quectel. Contact LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 10 / 44 GNSS Module Series Quectel Technical Support to get the value. ⚫ The value of 'device_id' (CCC in the example) contains two parts – one is assigned by Quectel and the other by the customer. For example: if CCC = XXX_YYY, the value XXX is provided by Quectel and you can contact Quectel Technical Support to get the value, while YYY can be assigned by yourself and it must be a unique value, such as IMEI. Each device must have a unique ID. NOTE There will be up to 10 files as the GPS-only or GPS + GLONASS EPO files may include a maximum of 30 days of predictions. Slices of 30-day EPO: _1 for days 1 to 3, _2 for days 4 to 6, ... _10 for days 28 to 30. 2.2. EPO File Format This chapter mainly illustrates the format of the EPO files. The SVID numbers of EPO files for different constellations are shown below. Table 4: EPO Data SVID Range GNSS Type GPS GLONASS Galileo BDS PRN 1–32 1–24 1–36 1–54, 55–63 EPO Data SVID 1–32 65–88 101–136 201–254, 190–198 LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 11 / 44 2.2.1. EPO File Format – GPS Only GNSS Module Series Day1 Day2 ... Day7 ... Day29 Day30 EPO Format (1 day) Segment UTC Segment1 0:00-6:00 Segment2 6:00-12:00 Segment3 12:00-18:00 Segment4 18:00-24:00 EPO Format (1 Segment) SV1 SV2 ... SV31 SV32 EPO Format (1 SV) Data GPS_Hour SVID Byte offset 0[LSB]~2[MSB] 3 Data ... Byte offset ... ... 4~7 ... 64~67 ... 8~11 CheckSum 68~71 Figure 1: EPO File Format – GPS Only GPS_Secs = GPS_Hour × 3600 GPS_Week Number = GPS_Secs / 604800 GPS TOW = GPS_Secs % 604800 An EPO file contains GPS Time (GPS_Week, GPS_Hour and GPS_Secs). The maximum unit in GPS Time is GPS week which starts at approximately midnight of January 5th to 6th, 1980. The following figure illustrates the format of several segments of EPO files. SAT data SAT data 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 EPO SET 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 EPO SET 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 EPO SET Figure 2: Format of Several Segments of EPO Files LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 12 / 44 GNSS Module Series The basic unit of an EPO file is SAT Data and the size of each SAT Data is 72 bytes. One EPO SET contains 32 SAT Data, so the data size of an EPO SET is 2304 bytes. Each EPO file contains several EPO SETs and thus the file size must be a multiple of 2304 bytes. An EPO SET is valid for 6 hours. Therefore, there will be 4 EPO SETs for one day. 2.2.2. EPO File Format – BDS/Galileo Only Galileo EPO data consist of the 72-byte header and 3- or 7- day fundamental EPO data. BDS EPO data consist of the 72-byte header and 3-day EPO data only. The EPO format for both has no fixed size. Header 72 bytes Day1 Day2 Day3 ... Day7 EPO Format (1 day) Segment UTC Segment1 0:00-6:00 Segment2 6:00-12:00 Segment3 12:00-18:00 Segment4 18:00-24:00 EPO Format (1 Segment) SV SV ... SV SV EPO Format (1 SV) Data GPS_Hour SVID Byte offset 0[LSB]~2[MSB] 3 Data ... Byte offset ... ... 4~7 ... 64~67 ... 8~11 CheckSum 68~71 Figure 3: EPO File Format – BDS/Galileo Only The 72-byte header contains the SV available bitmask that can be used for calculating the available satellite ID. When the SV available bitmask position is 1, it indicates that the satellite is available, and the number of the bit indicates the satellite ID. For example, you can parse the data from Figure 4: Galileo EPO Header as follows. ⚫ SVID is FE for Galileo. ⚫ SV available bitmask: 09 67 94 5D DF. ⚫ Total available SVs: 22. ⚫ Available SVs: 1, 2, 3, 4, 5, 7, 8, 9, 11, 12, 13, 15, 19, 21, 24, 25, 26, 27, 30, 31, 33, 36. LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 13 / 44 GNSS Module Series Data *** Byte offset 0~2 Example SVID 3 SV available bitmask(Lbytes) 4[LSB]~7[MSB] FE DF 5D 94 67 Data SV available bitmask(Hbytes) Byte offset 16[LSB]~19[MSB] Example 09 00 00 00 *** 20~23 *** 8~11 *** 24~27 *** 12~15 *** 18~31 Figure 4: Galileo EPO Header You can parse the data from Figure 5: BDS EPO Header as follows. ⚫ SVID is FF for BDS. ⚫ SV available bitmask: 3F FF BF FC 3F FF. ⚫ Total available SVs: 41. ⚫ Available SVs: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46. Data *** Byte offset 0~2 Example SVID 3 SV available bitmask(Lbytes) 4[LSB]~7[MSB] FF FF 3F FC BF Data SV available bitmask(Hbytes) Byte offset 16[LSB]~19[MSB] Example FF 3F 00 00 *** 20~23 *** 8~11 *** 24~27 Figure 5: BDS EPO Header *** 12~15 *** 18~31 LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 14 / 44 2.2.3. EPO File Format – GPS + GLONASS GNSS Module Series SAT data SAT data 1 2 1 2 31 32 65 66 31 32 65 66 87 88 87 88 1 2 31 32 65 66 87 88 GPS EPO SET GLONASS EPO SET Figure 6: EPO File Format – GPS + GLONASS The basic unit of an EPO file is SAT Data, and the size of SAT Data is 72 bytes. In GPS + GLONASS EPO files, one EPO SET contains 56 SAT Data, so the EPO SET data size is 4032 bytes. Each EPO file contains several EPO SETs. The file size must be a multiple of 4032 bytes. An EPO SET is valid for 6 hours. Therefore, there will be 4 EPO SETs for one day. 2.3. EPO File Types The EPO data can be downloaded in the form of files. You can select the most suitable file type to download based on the availability of a data connection and storage space of your application. See Table 3: Download URL of EPO Files and Table 5: EPO File Types to decide on the file type to be downloaded. Table 5: EPO File Types EPO Type Unified QEPO Unified QEPO GNSS Type Description GPS only GPS + GLONASS 6-hour prediction orbit (ephemeris). Single file containing the latest available GPS EPO data. 6-hour prediction orbit (ephemeris). Single file containing the latest available GPS + GLONASS EPO data. LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 15 / 44 GNSS Module Series EPO Type GNSS Type Unified QEPO BDS/Galileo only EPO EPO GPS only Galileo only Description 6-hour prediction orbit (ephemeris). Single file containing the latest available BDS/Galileo EPO data. 3–14 days of prediction orbit (ephemeris). Split into 5 files, each containing 3-day information. 3- or 7-day prediction orbit (ephemeris). EPO EPO BDS only 3-day prediction orbit (ephemeris). 3–14 days of prediction orbit (ephemeris). GPS + GLONASS Split in 5 files, each containing 3-day information. 2.4. Recommended Download Procedures of EPO Files Set daily timer to check EPO effectiveness Daily timer expires Power on GNSS receiver Will EPO files expire today? 1) Yes Download EPO file(s) for backup Verify downloaded data 2) Have valid EPO Yes files? 3) No Download unified QEPO files EPO aiding with backup file Verify downloaded data Position fixed Back up prepared EPO files Position fixed Figure 7: Recommended Download Procedures of EPO Files LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 16 / 44 GNSS Module Series NOTE 1. 1) You must know the current UTC time to download valid EPO files. 2. 2) Send $PAIR470 to check if the data are correct. 3. 3) If the device is powered off for a long time, EPO files stored in flash may expire. 2.5. EPO File Validity Period EPO file validity period is related to the current UTC time. The EPO file validity period can be obtained from the last segment of the EPO file. See Figure 1: EPO File Format – GPS Only or the sample of how to calculate EPO file validity period (GPS_Hour + 6). It is necessary to download the EPO file 12 hours in advance. The following codes show the conversion between UTC time and GPS time. void utc_to_gpstime(kal_uint32 year, //Input year kal_uint8 mon, //Input month: 1~12 kal_uint8 day, //Input day: 1~31 kal_uint8 hour, //Input hour: 0~23 kal_uint8 min, //Input minute: 0~59 kal_uint8 sec, //Input second: 0~59 kal_int32* wn, //Output GPS week number double* tow) //Output GPS time of week { kal_int32 iYearsElapsed; //Elapsed years since 1980 kal_int32 iDaysElapsed; //Elapsed days since Jan 5/Jan 6, 1980 kal_int32 iLeapDays; //Leap days since Jan 5/Jan 6, 1980 kal_int32 i; //Number of days at the start of each month (ignore leap years). kal_uint16 doy[12] = {0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334}; iYearsElapsed = year - 1980; i = 0; iLeapDays = 0; while (i <= iYearsElapsed) { if ((i % 100) == 20) { if ((i % 400) == 20) { iLeapDays++; } } LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 17 / 44 GNSS Module Series else if ((i % 4) == 0) { iLeapDays++; } i++; } /* iLeapDays = iYearsElapsed / 4 + 1; */. if ((iYearsElapsed % 100) == 20) { if (((iYearsElapsed % 400) == 20) && (mon <= 2)) { iLeapDays--; } } else if (((iYearsElapsed % 4) == 0) && (mon <= 2)) { iLeapDays--; } iDaysElapsed = iYearsElapsed * 365 + doy[mon - 1] + day + iLeapDays - 6; //Convert time to GPS weeks and seconds. *wn = iDaysElapsed / 7; *tow = (double)(iDaysElapsed % 7) * 86400 + hour * 3600 + min * 60 + sec; } LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 18 / 44 GNSS Module Series 3 AGNSS Implementation This chapter describes the two AGNSS implementation methods: Host EPO and Flash EPO. ⚫ Implement AGNSS with Host EPO The host sends EPO data to the GNSS receiver through NMEA (ASCII) PAIR commands, such as $PAIR471. ⚫ Implement AGNSS with Flash EPO The EPO data are downloaded to the flash of GNSS receiver through Binary Protocol. Flash EPO retains data longer than Host EPO. 3.1. AGNSS with Flash EPO Flash EPO can store up to 14 days of EPO assistance data in flash, which enables the receiver to use the available data since boot time. The communication protocol of Flash EPO is Binary Protocol. Thus, you need to download assistance data to the GNSS receiver in the binary format specified in this document. See Chapter 3.1.2 EPO Data Transfer Protocol and Chapter 3.1.3 AGNSS Procedure with Flash EPO for details. 3.1.1. Binary Protocol Frame preamble, fixed as 0x04 0x24 2-byte Message ID 2-byte Message 1-byte Frame tail, Checksum fixed as 0xAA 0x44 Preamble MsgID Length Payload Checksum Tail The range for checksum calculation Figure 8: Binary Protocol Structure LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 19 / 44 GNSS Module Series Table 6: Description of Binary Protocol Fields Field Preamble MsgID Length Payload Checksum Tail Length (Byte) 2 2 2 Variable 1 2 Description Fixed as 0x2404. Little-endian. Message ID. Payload length. Unit: byte. Default packet size: 72 bytes. Little-endian. Payload data to be transferred. The checksum is the 8-bit exclusive OR of all bytes in the message between (but not including) the Preamble and the Checksum. Fixed as 0x44AA. Little-endian. The EPO binary format is divided into start message, EPO data message and end message. Table 7: Start of EPO Binary Format Preamble MsgID Length 0x04 0x24 0xB0 0x04 1 2 Bytes 2 Bytes 2 Bytes Payload ‘G’ – GPS ‘R’ – GLONASS ‘E’ – Galileo ‘C’ – BDS 2 Bytes Checksum 0x** 1 Byte Tail 0xAA 0x44 2 Bytes Table 8: EPO Data Binary Format Preamble 0x04 0x24 2 Bytes MsgID 0xB1 0x04 2 Bytes Length 72 2 Bytes Payload EPO Data 72 Bytes Checksum 0x** 1 Byte Tail 0xAA 0x44 2 Bytes Table 9: End of EPO Binary Format Preamble 0x04 0x24 MsgID Length 0xB2 0x04 1 Payload ‘G’ – GPS ‘R’ – GLONASS Checksum 0x** Tail 0xAA 0x44 LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 20 / 44 Preamble MsgID Length 2 Bytes 2 Bytes 2 Bytes Payload ‘E’ – Galileo ‘C’ – BDS 2 Bytes GNSS Module Series Checksum Tail 1 Byte 2 Bytes 3.1.2. EPO Data Transfer Protocol When transmitting assistance data, the host first sends the start message packet, then splits the EPO data into data packets and sends them, and finally sends the end message packet. The host should follow the EPO Data Transfer Protocol when transferring EPO data to the GNSS receiver. 3.1.2.1 Pseudo Code for EPO Data Transfer Protocol Pseudo code for the EPO data transfer procedure of GPS + GLONASS, for reference only: #define GNSS_APP_BINARY_BINARY_PREAMBLE1 #define GNSS_APP_BINARY_BINARY_PREAMBLE2 #define GNSS_APP_BINARY_BINARY_ENDWORD1 #define GNSS_APP_BINARY_BINARY_ENDWORD2 (0x04) (0x24) (0xAA) (0x44) #define GNSS_APP_BINARY_BINARY_PREAMBLE_SIZE (2) #define GNSS_APP_BINARY_BINARY_CHECKSUM_SIZE (1) #define GNSS_APP_BINARY_BINARY_ENDWORD_SIZE (2) #define GNSS_APP_BINARY_BINARY_CONTROL_SIZE (GNSS_APP_BINARY_BINARY_PREAMBLE_SIZE + GNSS_APP_BINARY_BINARY_CHECKSUM_SIZE + GNSS_APP_BINARY_BINARY_ENDWORD_SIZE) #define GNSS_APP_BINARY_BINARY_MESSAGE_ID_SIZE (2) #define GNSS_APP_BINARY_BINARY_PAYLOAD_LENGTH_SIZE (2) #define GNSS_APP_BINARY_BINARY_PAYLOAD_HEADER_SIZE (GNSS_APP_BINARY_BINARY_MESSAGE_ID_SIZE + GNSS_APP_BINARY_BINARY_PAYLOAD_LENGTH_SIZE) #define GNSS_APP_BINARY_BINARY_MAX_DATA_SIZE (512) #define GNSS_APP_BINARY_BINARY_MAX_PAYLOAD_DATA_SIZE (GNSS_APP_BINARY_BINARY_MAX_DATA_SIZE - GNSS_APP_BINARY_BINARY_CONTROL_SIZE - GNSS_APP_BINARY_BINARY_PAYLOAD_HEADER_SIZE) typedef enum gnss_app_binary_binary_decode_results { GNSS_APP_BINARY_BINARY_DECODE_SUCCESS = 0, LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 21 / 44 GNSS Module Series GNSS_APP_BINARY_BINARY_DECODE_WRONG_PARAMETER = -1, GNSS_APP_BINARY_BINARY_DECODE_WRONG_PREAMBLE = -2, GNSS_APP_BINARY_BINARY_DECODE_WRONG_CHECKSUM = -3, GNSS_APP_BINARY_BINARY_DECODE_WRONG_ENDWORD = -4, }gnss_app_binary_binary_decode_results_t; typedef struct gnss_app_binary_binary_payload { uint16_t message_id; uint16_t data_size; /* actual size of data in payload data buffer */ uint8_t data[GNSS_APP_BINARY_BINARY_MAX_PAYLOAD_DATA_SIZE]; }gnss_app_binary_binary_payload_t; uint8_t gnss_app_binary_calculate_binary_checksum(const gnss_app_binary_binary_payload_t* const payload) { uint8_t checksum = 0; uint8_t* pheader = NULL; uint8_t* pdata = NULL; uint16_t i; if (NULL == payload) { return 0; } /* The checksum is the 8-bit exclusive OR of all bytes in the payload. */ pheader = (uint8_t*)payload; for (i = 0; i < GNSS_APP_BINARY_BINARY_PAYLOAD_HEADER_SIZE; i++) { checksum ^= *pheader; pheader++; } pdata = (uint8_t*)payload->data; for (i = 0; i < payload->data_size; i++) { checksum ^= *pdata; pdata++; } return checksum; } int16_t gnss_app_binary_encode_binary_packet(uint8_t* const buffer, uint16_t max_buffer_size, const gnss_app_binary_binary_payload_t* const payload) { uint8_t* pbyte; uint16_t required_length; if (NULL == buffer || payload == NULL) { return -1; } required_length = payload->data_size + GNSS_APP_BINARY_BINARY_CONTROL_SIZE + LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 22 / 44 GNSS Module Series GNSS_APP_BINARY_BINARY_PAYLOAD_HEADER_SIZE; if (max_buffer_size < required_length) { return -1; } memset((void*)buffer, 0, max_buffer_size); buffer[0] = GNSS_APP_BINARY_BINARY_PREAMBLE1; buffer[1] = GNSS_APP_BINARY_BINARY_PREAMBLE2; pbyte = &buffer[2]; memcpy(pbyte, payload, GNSS_APP_BINARY_BINARY_PAYLOAD_HEADER_SIZE); pbyte += GNSS_APP_BINARY_BINARY_PAYLOAD_HEADER_SIZE; memcpy(pbyte, payload->data, payload->data_size); pbyte += payload->data_size; *pbyte++ = gnss_app_binary_calculate_binary_checksum(payload); *pbyte++ = GNSS_APP_BINARY_BINARY_ENDWORD1; *pbyte = GNSS_APP_BINARY_BINARY_ENDWORD2; return required_length; } FILE* gnss_epo_file = NULL; #define GNSS_MAX_EPO_NUMBER (37) #define GNSS_MAX_RECORD_SIZE (72) static uint32_t gnss_epo_sv_buf[(GNSS_MAX_EPO_NUMBER * GNSS_MAX_RECORD_SIZE) / sizeof(uint32_t)]; int16_t gnss_epo_encode_binary(uint16_t msg_id, char* buffer, uint16_t buffer_size, char* data_input, int32_t data_length) { gnss_app_binary_binary_payload_t payload; int16_t binary_message_length; memset((void*)&payload, 0, sizeof(gnss_app_binary_binary_payload_t)); payload.message_id = msg_id; payload.data_size = (uint16_t)data_length; memcpy(payload.data, data_input, sizeof(uint8_t) * data_length); binary_message_length = gnss_app_binary_encode_binary_packet(buffer, buffer_size, &payload); return binary_message_length; } void gnss_epo_binary_demo() { gnss_app_binary_data_t data; gnss_app_binary_data_result_t result = { 0 }; uint32_t* epobuf; int32_t i; char buffer[500]; uint16_t length = 0; int32_t buffer_size = 0; LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 23 / 44 GNSS Module Series uint8_t segment = 0; uint8_t curr_sys_type = 'G'; //type is the GPS gnss_epo_file = fopen('EPO_GR_3_1.DAT', 'rb'); length = gnss_epo_encode_binary(1200, buffer, 512, &curr_sys_type, 1); gnss_app_uart_send_data(buffer, length); memset(&gnss_epo_sv_buf, 0, sizeof(gnss_epo_sv_buf)); while (gnss_epo_read_data(&gnss_epo_sv_buf, 32 * GNSS_MAX_RECORD_SIZE, segment * (32 + 24) * GNSS_MAX_RECORD_SIZE)) { segment++; for (i = 0; i < 32; i++) { epobuf = (uint32_t*)(gnss_epo_sv_buf + ((i * GNSS_MAX_RECORD_SIZE) / 4)); length = gnss_epo_encode_binary(1201, buffer, 512, (char*)epobuf, GNSS_MAX_RECORD_SIZE); gnss_app_uart_send_data(buffer, length); } memset(&gnss_epo_sv_buf, 0, sizeof(gnss_epo_sv_buf)); } length = gnss_epo_encode_binary(1202, buffer, 512, &curr_sys_type, 1); gnss_app_uart_send_data(buffer, length); curr_sys_type = 'R'; //type is the GLONASS length = gnss_epo_encode_binary(1200, buffer, 512, &curr_sys_type, 1); gnss_app_uart_send_data(&data, &result); memset(&gnss_epo_sv_buf, 0, sizeof(gnss_epo_sv_buf)); segment = 0; while (gnss_epo_read_data(&gnss_epo_sv_buf, 37 * GNSS_MAX_RECORD_SIZE, (segment * (32 + 24) * GNSS_MAX_RECORD_SIZE) + (32 * GNSS_MAX_RECORD_SIZE))) { segment++; for (i = 0; i < 24; i++) { epobuf = (uint32_t*)(gnss_epo_sv_buf + ((i * GNSS_MAX_RECORD_SIZE) / 4)); length = gnss_epo_encode_binary(1201, buffer, 512, (char*)epobuf, GNSS_MAX_RECORD_SIZE); gnss_app_uart_send_data(buffer, length); } memset(&gnss_epo_sv_buf, 0, sizeof(gnss_epo_sv_buf)); } length = gnss_epo_encode_binary(1202, buffer, 512, &curr_sys_type, 1); gnss_app_uart_send_data(buffer, length); fclose(gnss_epo_file); } LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 24 / 44 3.1.3. AGNSS Procedure with Flash EPO Power on GNSS GNSS Module Series Have an EPO file? NO YES Has EPO file expired? YES Erase EPO file NO Send Reference Time Download EPO files with Binary Protocol Verify downloaded data Restart GNSS Send Reference Position Position fixed Figure 9: AGNSS Procedure with Flash EPO 1. Power on the GNSS module. 2. Check if there are EPO data in the GNSS module flash memory with $PAIR470. 3. If the flash memory contains EPO data, go to the next step to check data validity. Otherwise, download EPO data to the GNSS module and verify the downloaded data, then restart the GNSS module and go to Step 5. 4. Check whether the EPO file in the GNSS module flash memory has expired. 5. If the EPO file is still valid, go to Step 6. Otherwise, erase the expired EPO file with $PAIR472 and download a new EPO file. 6. Send reference time to the GNSS module with $PAIR590. 7. Send reference position to GNSS module with $PAIR600. 8. Wait for the GNSS module to fix position. LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 25 / 44 GNSS Module Series 3.2. AGNSS with Host EPO Host EPO allows for a simpler text-based implementation that enables the receiver to perform a fast start-up where assistance data must be sent to the receiver each time it boots. When using Host EPO, the receiver can only receive one block of assistance data valid for 6 hours. Implementing Host EPO only requires a few PAIR sentences and the whole data transfer can be performed in NMEA mode. See Chapter 4 AGNSS Related Messages for detailed description of $PAIR471, $PAIR590 and $PAIR600. 3.2.1. Recommended Sequence for Host EPO After the module is powered on, it sends an aiding request 1) to notify the expiration of the stored GNSS assistance data when both assistance data and ephemeris are invalid. Therefore, if the module does not report an aiding request, it is recommended to determine whether the assistance data have expired by sending $PAIR470 after the host receives the system startup message. The host sends the assistance data in the sequence shown in Figure 10: Suggested Sequence for Host EPO. Host EPO procedure: 1. GNSS module starts up; 2. Host sends Reference Time; 3. Host sends Reference Position; 4. Host sends EPO data. The supplied Reference Time, Reference Position and EPO data must comply with the requirements listed in Chapter 1.2 AGNSS Requirements. NOTE 1. 1) The module automatically outputs $PAIR010 messages to indicate the expiration of stored GNSS assistance data. For details about $PAIR010, see document [1] protocol specification. 2. In the current implementation, the host needs to wait for a $PAIR001 packet to be returned before sending another segment of EPO data. For details about $PAIR001, see document [1] protocol specification. LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 26 / 44 GNSS Receiver Host EPO Sequence GNSS Module Powers Up Start up message Assistance Data (Time) PAIR001 (ACK) Assistance Data (Position) PAIR001 (ACK) Loop [Repeats until all EPO data are sent] EPO Assistance Data Segment 001 PAIR001 (ACK) EPO Assistance Data Segment 002 PAIR001 (ACK) Host needs to wait for ACK packages GNSS Module Series Host Figure 10: Suggested Sequence for Host EPO 3.2.2. Sample Code to Send EPO The following is the reference code to send one segment EPO data to GNSS chip. It indicates how to construct PAIR messages for GNSS receiver. PAIR messages for Reference Time and Reference Position are not included in this example. #define GNSS_GLONASS_EPO_BASE_ID (64) #define GNSS_GALILEO_EPO_BASE_ID (100) #define GNSS_BDS_EPO_BASE_ID (200) #define MNL_SERVICE_MAX_COMMAND_LEN (352) #define EPO_DEMO_RECORD_SIZE (72) typedef enum{ EPO_DEMO_MODE_GPS, EPO_DEMO_MODE_GLONASS, LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 27 / 44 GNSS Module Series EPO_DEMO_MODE_GALILEO, EPO_DEMO_MODE_BEIDOU }epo_demo_mode_t; int32_t epo_demo_get_sv_prn(int32_t type, uint8_t *data) { int32_t sv_id, sv_prn = 0; sv_id = data[3]; switch(type) { case EPO_DEMO_MODE_GPS: sv_prn = sv_id; break; case EPO_DEMO_MODE_GLONASS: sv_prn = sv_id - GNSS_GLONASS_EPO_BASE_ID; break; case EPO_DEMO_MODE_GALILEO: if(sv_id == 255) { sv_prn = 255; } else { sv_prn = sv_id - GNSS_GALILEO_EPO_BASE_ID; } break; case EPO_DEMO_MODE_BDS: if(sv_id == 255) { sv_prn = 255; } else { sv_prn = sv_id - GNSS_BDS_EPO_BASE_ID; } break; default: sv_prn = 0; } return sv_prn; } void epo_demo_send_data(epo_demo_epo_data_t *data_p, int32_t data_num, int32_t type){ char temp_buffer[MNL_SERVICE_MAX_COMMAND_LEN] = {0}; uint8_t data_buffer[EPO_DEMO_RECORD_SIZE] = {0}; int32_t i; int32_t sv_prn = 0; for(i = 0; i < data_num; i++) { LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 28 / 44 GNSS Module Series unsigned int *epobuf = (unsigned int *)data_buffer; epo_demo_epo_fread(data_p, data_buffer, EPO_DEMO_RECORD_SIZE); sv_prn = epo_demo_get_sv_prn(type, data_buffer); sprintf((char *) temp_buffer, '471,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X,%X', (unsigned int)type, (unsigned int)sv_prn, epobuf[0], epobuf[1], epobuf[2], epobuf[3], epobuf[4], epobuf[5], epobuf[6], epobuf[7], epobuf[8], epobuf[9], epobuf[10], epobuf[11], epobuf[12], epobuf[13], epobuf[14], epobuf[15], epobuf[16], epobuf[17]); gnss_app_send_command_ex(temp_buffer); memset(temp_buffer, 0, MNL_SERVICE_MAX_COMMAND_LEN); } } LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 29 / 44 GNSS Module Series 4 AGNSS Related Messages This chapter outlines AGNSS related PAIR messages (proprietary NMEA messages defined by the chipset supplier). 'P' means proprietary message, 'AIR' means the command defined by the chipset supplier. 4.1. PAIR470 PAIR_EPO_GET_STATUS Queries the status of EPO data stored on the GNSS chip. Type: Command Synopsis: $PAIR470,* Parameter: Field Format Unit Numeric - Description GNSS system ID. 0 = GPS 1 = GLONASS 2 = Galileo 3 = BDS Result: Returns $PAIR001 message and the query result. Query result message format: $PAIR470,,,,,,,,,,* LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 30 / 44 GNSS Module Series Parameter included in the result: Field Format Numeric Numeric Unit Description GNSS system ID. 0 = GPS - 1 = GLONASS 2 = Galileo 3 = BDS - Total number of EPO data sets stored in GNSS chip. Numeric - GPS week number of the first set of EPO data stored in flash. Numeric - GPS TOW of the first set of EPO data stored in flash. Numeric - GPS week number of the last set of EPO data stored in flash. Numeric - Numeric - Numeric - Numeric - Numeric - GPS TOW of the last set of EPO data stored in flash. GPS week number of the first set of EPO data that are currently being used. GPS TOW of the first set of EPO data that are currently being used. GPS week number of the last set of EPO data that are currently being used. GPS TOW of the last set of EPO data that are currently being used. Example: $PAIR470,0*25 $PAIR001,470,0*38 $PAIR470,0,1,2098,194400,2098,216000,2098,194400,2098,216000*38 4.2. PAIR471 PAIR_EPO_SET_DATA Sends the packet containing EPO data for a single satellite. Type: Input LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 31 / 44 GNSS Module Series Synopsis: $PAIR471,,,,...,* Parameter: Field Format Unit Numeric - Hexadecimal - – - - Description GNSS system ID. 0 = GPS 1 = GLONASS 2 = Galileo 3 = BDS PRN number of the satellite whose EPO data are being sent. GPS Range: 1–32. GLONASS Range: 1–24. Galileo Range: 1–30. BDS Range: 1–37. Special 255: BDS IONO data. Special 254: Galileo IONO data. 18 words (LSB-first) of one EPO segment data (total 72 bytes). Result: Returns $PAIR001 message. Example: $PAIR471,1,16,56056272,F2BC0244,4F19AE34,F95C534D,FAE67014,4F19AF6B,F96749BD,9F341F2 D,6F4EA9F,77DB4710,66ADAC2,9ADF3B01,8CC8B19C,29D2D20C,FC5B2E94,1000001C,11005000,7 48B45F4*0A $PAIR001,471,0*39 4.3. PAIR472 PAIR_EPO_ERASE_FLASH_DATA Erases the EPO data stored in the flash memory. Type: Command LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 32 / 44 Synopsis: $PAIR472* Parameter: None Result: Returns $PAIR001 message. Example: $PAIR472*3B $PAIR001,472,0*3A GNSS Module Series 4.4. PAIR590 PAIR_TIME_SET_REF_UTC Sends reference UTC time to GNSS chip for TTFF improvments. Local time should be avoided due to time-zone offset. To achieve a faster TTFF, the reference time should be accurate within 3 seconds and must be specified in UTC time. Type: Set Synopsis: $PAIR590,,,,,,* Parameter: Field Format Numeric Numeric Numeric Numeric Numeric Numeric Unit Description - UTC year. Minimum value: 1980. - UTC month. Range: 1–12. - UTC day. Range: 1–31. - UTC hours. Range: 0–23. - UTC minutes. Range: 0–59. - UTC seconds. Range: 0–59. LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 33 / 44 Result: Returns $PAIR001 message. Example: $PAIR590,2019,2,10,9,0,58*0B $PAIR001,590,0*37 NOTE This command needs to be sent every time after GNSS module reboots. GNSS Module Series 4.5. PAIR600 PAIR_LOC_SET_REF Sends reference position to GNSS chip for faster TTFF. Type: Set Synopsis: $PAIR600,,,,,,,* Parameter: Field Format Numeric Numeric Numeric Numeric Numeric Numeric Unit Description Degree Degree Reference latitude. Range: -90 to 90. Minus: south; plus: north. It is recommended to express this value in floating point with 6 decimal points. Reference longitude. Range: -180 to 180. Minus: west; plus: east. It is recommended to express this value in floating point with 6 decimal points. Meter Reference height. Meter Semi-major RMS accuracy. Meter Semi-minor RMS accuracy. Degree Bearing. LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 34 / 44 Field Format Numeric Unit Meter Description Vertical RMS accuracy. Result: Returns $PAIR001 message. Example: $PAIR600,24.772816,121.022636,175.0,50.0,50.0,0.0,100.0*06 $PAIR001,600,0*3D NOTE This command needs to be sent every time after GNSS module reboots. GNSS Module Series LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 35 / 44 GNSS Module Series 5 Download EPO Data with QGNSS This chapter describes how to download EPO data through QGNSS. Contact Quectel Technical Support for details on QGNSS. 5.1. Download Flash EPO with QGNSS Steps to download Flash EPO with the QGNSS tool: 1. Run the QGNSS tool. 2. In the main interface, click 'AGNSS' → 'Assistant GNSS Offline' as shown below. Figure 11: QGNSS Interface for Setting Flash EPO 3. Download EPO file to the module. a) Click the 'Connect' button to connect to the FTP server. b) Select EPO file. c) Click the 'Download selected file' button to download the EPO file to computer. d) Select Satellites type. LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 36 / 44 e) Click the '…' button to select EPO file. f) Click 'Download' button to download the EPO file to module. GNSS Module Series Figure 12: Download Flash EPO File 5.2. Download Host EPO with QGNSS Steps to download Host EPO with the QGNSS tool: 1. Run the QGNSS tool. 2. In the main interface, click 'AGNSS' → 'Assistant GNSS Online' as shown below. LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 37 / 44 GNSS Module Series Figure 13: QGNSS Interface for Setting Host EPO 3. Configure parameters: a) Check 'Use Current Position' to use current position. b) Check 'Use Current UTC' to use current time. c) Click 'Transfer' to download host EPO file. Figure 14: Download Host EPO File LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 38 / 44 GNSS Module Series 6 AGNSS Implementation Example This chapter gives examples of how to download EPO files to the module. 6.1. Flash EPO Implementation Blue: Sent data Red: ACK information //Host sends $PAIR472*3B to erase the EPO data stored in the flash memory: $PAIR472*3B //Module returns a $PAIR001 message: $PAIR001,472,0*3A //Host sends EPO start message in hexadecimal format: 04 24 B0 04 01 00 47 F2 AA 44 //Module returns an ACK message: 04 24 E8 03 04 00 B0 04 00 00 5B AA 44 //Host sends EPO data in hexadecimal format: 04 24 B1 04 48 00 00 A9 05 01 CD 00 80 B6 73 DE ……. FD AA 44 //Module returns an ACK message: 04 24 E8 03 04 00 B1 04 00 00 5A AA 44 …… //Host sends EPO data in hexadecimal format: 04 24 B1 04 48 00 42 A9 05 20 AF 3F 80 B7 71 CE……. FD AA 44 //Module returns an ACK message: 04 24 E8 03 04 00 B1 04 00 00 5A AA 44 //Host sends EPO end data in hexadecimal format: 04 24 B2 04 01 00 52 E5 AA 44 //Module returns an ACK message: LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 39 / 44 04 24 E8 03 04 00 B2 04 00 00 59 AA 44 //Host queries the EPO data status stored in the GPS chip: $PAIR470,0*25 //Module returns $PAIR001 and $PAIR470 messages: $PAIR001,470,0*38 $PAIR470,0,12,2208,86400,2208,345600,0,0,0,0*34 GNSS Module Series 6.2. Host EPO Implementation Blue: Sent data Red: ACK information //Host sends the power-on GNSS system command $PAIR002: $PAIR002*38 //Module returns $PAIR001: $PAIR001,002,0*39 //Module outputs $PAIR010 messages automatically: $PAIR010,1,-1*16 $PAIR010,2,-1*15 //Host sends the reference UTC time command $PAIR590: $PAIR590,2022,05,01,07,10,27*33 //Module returns a $PAIR001 message: $PAIR001,590,0*37 //Host sends the reference position information command $PAIR600: $PAIR600,31.822203,117.115219,175.0,50.0,50.0,0.0,100.0*0F //Module returns a $PAIR001 message: $PAIR001,600,0*3D //Host sends EPO data: $PAIR471,0,1,105A906,B58000F9,248DE73,F3A00478,F2FD36BA,248DE5E,F844379B,84C21659,6F1 8FEA,124FCF96,103EC82,A6034274,7D15B64A,2F4E5561,24984FBC,1000001C,1100000,1D33F8D3 *3F //Module returns a $PAIR001 message: $PAIR001,471,0*39 LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 40 / 44 GNSS Module Series //Host sends EPO data: $PAIR471,0,2,205A906,803F5B,24811C6,F67D3826,F4A80421,2481133,7110470,85A4863A,6F1BED3 ,1C59F758,D76D644,A60354C6,7166D3CC,2052969A,C611DBC7,1000001C,0,B41D7D61*08 //Module returns a $PAIR001 message: $PAIR001,471,0*39 …… //Host sends EPO data: $PAIR471,0,E,E05A906,EC80019B,2482E2A,950E550,B55D902,248D1E5,708F5C8,83F256C6,6F175 E1,E620A86A,7E544E8,A6039859,22C26DDF,21DDAAB5,7D32DCE7,1000001C,2210000,4941D2A5* 7D //Module returns a $PAIR001 message: $PAIR001,471,0*39 LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 41 / 44 GNSS Module Series 7 Appendix A References Table 10: Related Document Document Name [1] Quectel_LC26G&LC76G&LC86G_Series_Protocol Specification Table 11: Terms and Abbreviations Abbreviation ACK AGNSS EPO GLONASS GNSS GPS IMEI IONO MNL PRN RAM SV SVID TOW Description Acknowledgement Assisted GNSS (Global Navigation Satellite System) Extended Prediction Orbit Global Navigation Satellite System (Russia) Global Navigation Satellite System Global Positioning System International Mobile Equipment Identity Ionospheric MTK Navigation Lib Pseudo Random Noise Random Access Memory Space Vehicle Space Vehicle Identification Time of Week LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 42 / 44 TTFF UART UTC URL GNSS Module Series Time to First Fix Universal Asynchronous Receiver/Transmitter Coordinated Universal Time Uniform Resource Locator LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 43 / 44 GNSS Module Series 8 Appendix B Special Characters Table 12: Special Characters Special Character [...] {…} Underline Definition Carriage return character. Line feed character. Parameter name. Angle brackets do not appear in the message. Optional field of a message. Square brackets do not appear in the message. Repeated field of a message. Curly brackets do not appear in the message. Default setting of a parameter. LC26G&LC76G&LC86G_Series_AGNSS_Application_Note 44 / 44

Quectel_LC26G&LC76G&LC86G_Series_AGNSS_Application_Note_V1.0

PDF

734.21 KB

L89 R2.0&LC29H&LC79H Series I2C Application Note GNSS Module Series Version: 1.0 Date: 2022-10-10 Status: Released GNSS Module Series At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters: Quectel Wireless Solutions Co., Ltd. Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China Tel: +86 21 5108 6236 Email: info@quectel.com Or our local offices. For more information, please visit: http://www.quectel.com/support/sales.htm. For technical support, or to report documentation errors, please visit: http://www.quectel.com/support/technical.htm. Or email us at: support@quectel.com. Legal Notices We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an 'as available' basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you. Use and Disclosure Restrictions License Agreements Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein. Copyright Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal nonexclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material. L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 1 / 23 GNSS Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any 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. L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 2 / 23 GNSS Module Series About the Document Document Information Title Subtitle Document Type Document Status L89 R2.0&LC29H&LC79H Series I2C Application Note GNSS Module Series Application Note Released Revision History Revision Date - 2022-01-25 1.0 2022-10-10 Description Creation of the document First official release L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 3 / 23 GNSS Module Series Contents About the Document .................................................................................................................................. 3 Contents ...................................................................................................................................................... 4 Table Index.................................................................................................................................................. 5 Figure Index ................................................................................................................................................ 6 1 Introduction ......................................................................................................................................... 7 2 Data Reading ....................................................................................................................................... 8 2.1. Data Reading Flow of Master .................................................................................................... 8 3 Data Writing ....................................................................................................................................... 12 3.1. Data Writing Flow of Master..................................................................................................... 12 4 Sample Code for I2C Reading/Writing Sequence.......................................................................... 16 4.1. Sample Code ........................................................................................................................... 16 5 Appendix References ....................................................................................................................... 23 L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 4 / 23 GNSS Module Series Table Index Table 1: Related Documents ...................................................................................................................... 23 Table 2: Terms and Abbreviations .............................................................................................................. 23 L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 5 / 23 GNSS Module Series Figure Index Figure 1: Data Reading Flow of Master in Step 1........................................................................................ 9 Figure 2: Data Reading Flow of Master in Step 2...................................................................................... 10 Figure 3: Data Reading Flow of Master ......................................................................................................11 Figure 4: Data Writing Flow of Master in Step 1 ........................................................................................ 13 Figure 5: Data Writing Flow of Master in Step 2 ........................................................................................ 14 Figure 6: Data Writing Flow of Master ....................................................................................................... 15 L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 6 / 23 GNSS Module Series 1 Introduction This document outlines the I2C function and its usage on Quectel’ s L89 R2.0, LC29H series, and LC79H series GNSS modules. The above module always operates as a slave device while communicating with the master (client-side MCU). The master can read/write any data via the I2C bus. The features of the module’s I2C interface: ⚫ Works in slave mode ⚫ Standard mode (100 kbps) and fast mode (400 kbps) ⚫ 7-bit address ⚫ Supports sending and receiving variable length messages ⚫ I2C pins: I2C_SDA and I2C_SCL In addition, this document provides a detailed introduction as well as a flow chart and sample code to illustrate how the master reads/writes data via the I2C bus. L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 7 / 23 GNSS Module Series 2 Data Reading The following chapter provides a detailed explanations on how the master reads data packets via I2C bus. The data length is not fixed. The capacity of the slave’s I2C buffer is 4096 bytes, which means that the master can read one I2C data packet of a maximum size of 4096 bytes each time. To read a complete packet of one second (meaning all the GNSS data messages during 1 second), the master needs to read several I2C data packets and then extract valid data from them. 2.1. Data Reading Flow of Master The master reads data as following: Step 1 The master reads data length in the slave transmit buffer. a) The master sends a configuration read command to the slave. ⚫ 7-bit slave address is 0x50. ⚫ The sent data is two words: 0xAA510008 and 0x00000004 (little-endian transmission). b) The master receives the data length from the slave transmit buffer. ⚫ 7-bit slave address is 0x54. ⚫ The master receives the data length from the slave transmit buffer. L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 8 / 23 GNSS Module Series Data (8 bytes) DEVICE ADDRESS 0xAA510008 0x00000004 S T MASTER A R T (0x50<<1) & 0xFE 0x08 0x00 0x51 0xAA 0x04 0x00 0x00 S 0x00 T O P SLAVE A A A A A A A A A C C C C C C C C C K K K K K K K K K DEVICE ADDRESS Data Length (4 bytes) S T MASTER A R T (0x54<<1 ) | 0x01 A C K A C K A C K S NACK T O P SLAVE A C DATA 1 K DATA 2 DATA 3 DATA 4 Figure 1: Data Reading Flow of Master in Step 1 Step 2 The master reads the data_read_len 1) bytes of data. a) The master sends configuration read command to the slave. ⚫ 7-bit slave address is 0x50. ⚫ The sent data is two words: 0xAA512000 and data_read_len 1) (little-endian transmission). b) The master receives the data_read_len 1) bytes of data. ⚫ 7-bit slave address is 0x54. ⚫ The master receives the data_read_len 1) bytes of data. L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 9 / 23 GNSS Module Series Data (8 bytes) DEVICE ADDRESS 0xAA512000 data_read_len (e.g. 200 bytes) S T MASTER A R T (0x50<<1) & 0xFE 0x00 0x20 0x51 0xAA 0xC8 0x00 0x00 S 0x00 T O P SLAVE A A A A A A A A A C C C C C C C C C K K K K K K K K K DEVICE ADDRESS Data (data_read_len bytes) S T MASTER A R T (0x54<<1) | 0x01 A A A C C C K K K SLAVE A C DATA 1 K DATA 2 DATA 3 A C K S NACK T O P DATA N Figure 2: Data Reading Flow of Master in Step 2 NOTE 1. 1) Unsigned int data_read_len defines the data length that the master needs to receive. The data_read_len should be less than or equal to the length read in the Step 1. 2. If the user does not read the data on time, the transmit buffer will be full and the I2C transmitter will enter sleep state. Sending any command to the module via I2C port can wake up the I2C transmitter. 3. 1 word = 4 bytes. 4. The module transmits data in little-endian format. L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 10 / 23 Master GNSS Module Series Slave Delay 1) Slave address: 0x50 Sends two words of data: 0xAA510008 and 0x00000004 Delay 1) Slave address: 0x54 Receives the data length Delay 1) Slave address: 0x50 Sends two words of data: 0xAA512000 and data_read_len Delay 1) Slave address: 0x54 Receives data (data_read_len bytes) Figure 3: Data Reading Flow of Master NOTE 1) The time of delay is about 10 ms. L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 11 / 23 GNSS Module Series 3 Data Writing The master can send messages to the slave via I2C bus. See documents [1] and [2] protocol specifications for detailed information on the messages. As the maximum capacity of the slave’s I2C buffer is 4096 bytes, each message input by the master should be 4096 bytes at most. The interval between two input messages cannot be less than 10 ms because the slave needs 10 ms to process the input data. 3.1. Data Writing Flow of Master The master writes data as follows: Step 1 The master reads the free length in the slave receive buffer. a) The master sends a configuration read command to the slave. ⚫ 7-bit slave address is 0x50. ⚫ The sent data is two words: 0xAA510004 and 0x00000004 (little-endian transmission). b) The master receives the free length from the slave receive buffer. ⚫ 7-bit slave address is 0x54. ⚫ The master receives the free length from the slave receive buffer. L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 12 / 23 GNSS Module Series Data (8 bytes) DEVICE ADDRESS 0xAA510004 0x00000004 S MASTER T A R (0x50<<1) & 0xFE T 0x04 0x00 0x51 0xAA 0x04 0x00 0x00 S 0x00 T O P SLAVE A A A A A A A A A C C C C C C C C C K K K K K K K K K DEVICE ADDRESS Free Length in slave receive buffer (4 bytes) S T MASTER A R T (0x54<<1) | 0x01 A C K A C K A C K S NACK T O P SLAVE A C DATA 1 K DATA 2 DATA 3 DATA 4 Figure 4: Data Writing Flow of Master in Step 1 Step 2 The master writes data_written_len 1) bytes of data. a) The master sends configuration write command to the slave. ⚫ 7-bit slave address is 0x50. ⚫ The sent data is two words: 0xAA531000 and data_written_len 1) (little-endian transmission). b) The master writes data_written_len 1) bytes of data. ⚫ 7-bit slave address is 0x58. ⚫ The master writes data_written_len 1) bytes of data. L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 13 / 23 GNSS Module Series Data (8 bytes) DEVICE ADDRESS 0xAA531000 data_written_len (e.g. 30 bytes) S T MASTER A R T (0x50<<1) & 0xFE 0x00 0x10 0x53 0xAA 0x1E 0x00 0x00 S 0x00 T O P SLAVE A A A A A A A A A C C C C C C C C C K K K K K K K K K DEVICE ADDRESS Data (data_written_len bytes) S T MASTER A R T (0x58<<1) & 0xFE DATA 1 DATA 2 DATA 3 SLAVE A A A A C C C C K K K K S DATA N T O P A A C C K K Figure 5: Data Writing Flow of Master in Step 2 NOTE 1. 1) Unsigned int data_written_len defines the data length that the master needs to write. 2. The free length in the slave receive buffer is the maximum length the master can write. Sent data that exceeds the free length in the slave receive buffer cannot be written into the module. 3. 1 word = 4 bytes. 4. The module transmits data in little-endian format. L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 14 / 23 GNSS Module Series Master Slave Delay 1) Slave address: 0x50 Sends two words of data: 0xAA510004 and 0x00000004 Delay 1) Slave address: 0x54 Receives the free length Delay 1) Slave address: 0x50 Sends two words of data: 0xAA531000 and data_written_len Delay 1) Slave address: 0x58 Writes data (data_written_len bytes) Figure 6: Data Writing Flow of Master NOTE 1) The time of delay is about 10 ms. L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 15 / 23 GNSS Module Series 4 Sample Code for I2C Reading/Writing Sequence 4.1. Sample Code The sample code for reading data from and writing data to the I2C buffer is shown below. #define QUECTEL_I2C_SLAVE_CR_CMD 0xaa51 #define QUECTEL_I2C_SLAVE_CW_CMD 0xaa53 #define QUECTEL_I2C_SLAVE_CMD_LEN #define QUECTEL_I2C_SLAVE_TX_LEN_REG_OFFSET #define QUECTEL_I2C_SLAVE_TX_BUF_REG_OFFSET 8 0x08 0x2000 #define QUECTEL_I2C_SLAVE_RX_LEN_REG_OFFSET #define QUECTEL_I2C_SLAVE_RX_BUF_REG_OFFSET 0x04 0x1000 #define QUECTEL_I2C_SLAVE_ADDRESS_CR_OR_CW #define QUECTEL_I2C_SLAVE_ADDRESS_R #define QUECTEL_I2C_SLAVE_ADDRESS_W 0x50 0x54 0x58 #define MAX_ERROR_NUMBER 20 #define MAX_I2C_BUFFER 1024 typedef enum { I2C_ACK = 0, I2C_NACK = 1 }I2c_Resp_FlagStatus; typedef enum { DEV_REP_SUCCESS = 0, DEV_REP_ERROR = 1 }Dev_Resp_FlagStatus; I2c_Resp_FlagStatus I2c_Master_Receive(uint8_t addr, uint8_t *Data, uint16_t Length) L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 16 / 23 GNSS Module Series { mcu_i2c_start(); mcu_i2c_send_byte(addr|0x01); if(mcu_i2c_wait_ack() != I2C_ACK) { mcu_i2c_stop(); return I2C_NACK; } for(int i = 0; i < Length; i++) { *(Data + i) = mcu_i2c_receive_byte(); if(i != (Length - 1)) { mcu_i2c_ack(); } } mcu_i2c_no_ack(); mcu_i2c_stop(); return I2C_ACK; } I2c_Resp_FlagStatus I2c_Master_Transmit(uint8_t addr, uint8_t *Data, uint8_t Length) { uint8_t i = 0; uint8_t flag=0; mcu_i2c_start(); mcu_i2c_send_byte(addr); if(mcu_i2c_wait_ack() == I2C_NACK) { mcu_i2c_stop(); return I2C_NACK; } for(i = 0; i < Length; i++) { mcu_i2c_send_byte(*(Data+i)); if(mcu_i2c_wait_ack() == I2C_NACK) { mcu_i2c_stop(); return I2C_NACK; } } mcu_i2c_stop(); return I2C_ACK; } L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 17 / 23 GNSS Module Series Dev_Resp_FlagStatus Quectel_Dev_Receive(uint8_t* pData, uint16_t maxLength, uint16_t* pRecLength) { uint32_t request_cmd[2]; uint16_t* pRxLength = pRecLength; uint8_t* pBuff = pData; uint8_t i2c_master_receive_error_counter = 0; I2c_Resp_FlagStatus status; //step 1_a request_cmd[0] = (uint32_t)((uint32_t)(QUECTEL_I2C_SLAVE_CR_CMD << 16) | QUECTEL_I2C_SLAVE_TX_LEN_REG_OFFSET); request_cmd[1] = 4; i2c_master_receive_error_counter = 0; while(1) { delay_ms(10); status = I2c_Master_Transmit(QUECTEL_I2C_SLAVE_ADDRESS_CR_OR_CW << 1, (uint8_t *)request_cmd, QUECTEL_I2C_SLAVE_CMD_LEN); if(status == I2C_ACK) { break; } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { return DEV_REP_ERROR; } } //step 1_b i2c_master_receive_error_counter = 0; while(1) { delay_ms(10); status = I2c_Master_Receive(QUECTEL_I2C_SLAVE_ADDRESS_R << 1, (uint8_t*)pRxLength, 4); if(status == I2C_ACK) { break; } L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 18 / 23 GNSS Module Series i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { return DEV_REP_ERROR; } } if(*pRxLength == 0) { return DEV_REP_ERROR; } if(*pRxLength > MAX_I2C_BUFFER) { *pRxLength = MAX_I2C_BUFFER; } //step 2_a request_cmd[0] = (uint32_t)(QUECTEL_I2C_SLAVE_CR_CMD << 16) | QUECTEL_I2C_SLAVE_TX_BUF_REG_OFFSET; request_cmd[1] = *pRxLength; i2c_master_receive_error_counter = 0; while(1) { delay_ms(10); status = I2c_Master_Transmit(QUECTEL_I2C_SLAVE_ADDRESS_CR_OR_CW << 1, (uint8_t *)request_cmd, QUECTEL_I2C_SLAVE_CMD_LEN); if(status == I2C_ACK) { break; } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { *pRxLength = 0; return DEV_REP_ERROR; } } //step 2_b i2c_master_receive_error_counter = 0; while(1) { L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 19 / 23 GNSS Module Series delay_ms(10); status = I2c_Master_Receive(QUECTEL_I2C_SLAVE_ADDRESS_R << 1, pBuff, *pRxLength); if(status == I2C_ACK) { return DEV_REP_SUCCESS; } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { *pRxLength = 0; return DEV_REP_ERROR; } } return DEV_REP_SUCCESS; } Dev_Resp_FlagStatus Quectel_Dev_Transmit(uint8_t *pData, uint16_t dataLength) { uint32_t request_cmd[2]; uint16_t rxBuffLength = 0; uint8_t i2c_master_receive_error_counter = 0; I2c_Resp_FlagStatus status; //step 1_a request_cmd[0] = (uint32_t)((QUECTEL_I2C_SLAVE_CR_CMD << 16) | QUECTEL_I2C_SLAVE_RX_LEN_REG_OFFSET); request_cmd[1] = 4; i2c_master_receive_error_counter = 0; while(1) { delay_ms(10); status = I2c_Master_Transmit(QUECTEL_I2C_SLAVE_ADDRESS_CR_OR_CW << 1, (uint8_t *)request_cmd, QUECTEL_I2C_SLAVE_CMD_LEN); if(status == I2C_ACK) { break; } L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 20 / 23 GNSS Module Series i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { return DEV_REP_ERROR; } } //step 1_b i2c_master_receive_error_counter = 0; while(1) { delay_ms(10); status = I2c_Master_Receive(QUECTEL_I2C_SLAVE_ADDRESS_R << 1, (uint8_t*)&rxBuffLength, 4); if(status == I2C_ACK) { break; } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { return DEV_REP_ERROR; } } if(dataLength > rxBuffLength) { return DEV_REP_ERROR; } //step 2_a request_cmd[0] = (uint32_t)(QUECTEL_I2C_SLAVE_CW_CMD << 16) | QUECTEL_I2C_SLAVE_RX_BUF_REG_OFFSET; request_cmd[1] = dataLength; i2c_master_receive_error_counter = 0; while(1) { delay_ms(10); status = I2c_Master_Transmit(QUECTEL_I2C_SLAVE_ADDRESS_CR_OR_CW << 1, (uint8_t *)request_cmd, QUECTEL_I2C_SLAVE_CMD_LEN); if(status == I2C_ACK) { break; L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 21 / 23 GNSS Module Series } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { return DEV_REP_ERROR; } } //step 2_b i2c_master_receive_error_counter = 0; while(1) { delay_ms(10); status = I2c_Master_Transmit(QUECTEL_I2C_SLAVE_ADDRESS_W << 1, pData, dataLength); if(status == I2C_ACK) { return DEV_REP_SUCCESS; } i2c_master_receive_error_counter++; if(i2c_master_receive_error_counter > MAX_ERROR_NUMBER) { return DEV_REP_ERROR; } } return DEV_REP_SUCCESS; } L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 22 / 23 GNSS Module Series 5 Appendix References Table 1: Related Documents Document Name [1] Quectel_LC29H&LC79H_Series_GNSS_Protocol_Specification [2] Quectel_L89 R2.0_GNSS_Protocol_Specification Table 2: Terms and Abbreviations Abbreviation ACK GNSS I2C MCU SCL SDA Description Acknowledge Global Navigation Satellite System Inter-Integrated Circuit Microcontroller Unit Serial Clock Serial Data L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note 23 / 23

Quectel_L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note_V1.0

PDF

377.51 KB

BG77xA-GL&BG95xA-GL DFOTA Application Note LPWA Module Series Version: 1.0 Date: 2022-09-15 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_DFOTA_Application_Note 1 / 31 LPWA Module Series Trademarks Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects. Third-Party Rights This document may refer to hardware, software and/or documentation owned by one or more third parties ('third-party materials'). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto. We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non-infringement of any 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_DFOTA_Application_Note 2 / 31 LPWA Module Series About the Document Revision History Version 1.0 Date 2021-04-25 2022-09-15 Author Nikola BLAZIC/ Milan DJORDJEVIC Nikola BLAZIC/ Milan DJORDJEVIC Description Creation of the document First official release BG77xA-GL&BG95xA-GL_DFOTA_Application_Note 3 / 31 LPWA Module Series Contents About the Document ................................................................................................................................3 Contents .................................................................................................................................................... 4 Table Index ...............................................................................................................................................6 Figure Index ..............................................................................................................................................7 1 Introduction .......................................................................................................................................8 1.1. Applicable Modules ..................................................................................................................8 1.2. Special Mark.............................................................................................................................9 2 Trigger DFOTA by AT Commands .................................................................................................10 2.1. Firmware Update Procedure ..................................................................................................10 2.1.1. Get Delta Firmware Package ....................................................................................... 11 2.1.2. Put Delta Firmware Package on HTTP(S)/CoAP(S) Server......................................... 11 2.1.3. Check APN Setting and Network Status ...................................................................... 11 2.1.4. Execute AT Command to Update Firmware.................................................................12 2.2. DFOTA-Related AT Commands..............................................................................................12 2.2.1. AT Command Introduction ...........................................................................................12 2.2.1.1. Definitions .........................................................................................................12 2.2.1.2. AT Command Syntax ........................................................................................12 2.2.2. Declaration of AT Command Examples .......................................................................13 2.2.3. Description of At Command Mode and Data Mode......................................................13 2.2.4. AT+QFOTADL Update Firmware via DOFTA ............................................................14 2.2.4.1. AT+QFOTADL= Update Firmware When Delta Firmware Package is Stored on HTTP(S) Server .............................................................14 2.2.4.2. AT+QFOTADL= Update Firmware When Delta Firmware Package is Stored on CoAP(S) Server..............................................................16 2.2.4.3. AT+QFOTADL='COM:', Upload Delta a Firmware Package to Flash .......................................................................................................................... 17 2.2.4.4. AT+QFOTADL=,[] Extended DFOTA Functions....................18 2.2.5. AT+QCFGEXT='fota_apn' Configure IP Family and APN for DFOTA* .....................20 2.3. Example .................................................................................................................................20 3 Trigger DFOTA with LwM2M* .........................................................................................................22 3.1. Firmware Update Procedure ..................................................................................................22 3.1.1. Download Firmware Image ..........................................................................................23 3.1.2. Update Firmware .........................................................................................................24 3.2. URC of Firmware Updating with LwM2M................................................................................25 3.2.1. Download Progress URCs ...........................................................................................25 3.2.1.1. In-Band Mode ...................................................................................................25 3.2.1.2. Out-of-Band HTTP(S) Mode .............................................................................25 3.2.1.3. Out-of-Band CoAP(S) Mode .............................................................................26 3.2.2. Update Progress URCs ...............................................................................................27 3.2.2.1. +QIND: 'FOTA','START' Updating Started ....................................................27 BG77xA-GL&BG95xA-GL_DFOTA_Application_Note 4 / 31 LPWA Module Series 3.2.2.2. +QIND: 'FOTA','END', Updating Finished ............................................27 4 Summary of Error Codes................................................................................................................28 5 Appendix References .....................................................................................................................30 BG77xA-GL&BG95xA-GL_DFOTA_Application_Note 5 / 31 LPWA Module Series Table Index Table 1: Special Mark ................................................................................................................................ 9 Table 1: Type of AT Commands............................................................................................................... 12 Table 2: Summary of / Codes .......................................................................... 28 Table 3: Summary of Codes.............................................................................................. 28 Table 4: Summary of Codes........................................................................................................... 29 Table 5: Related Documents ................................................................................................................... 30 Table 6: Terms and Abbreviations............................................................................................................ 30 BG77xA-GL&BG95xA-GL_DFOTA_Application_Note 6 / 31 LPWA Module Series Figure Index Figure 1: DFOTA Procedure (Triggered by AT Command) ...................................................................... 10 Figure 2: LwM2M Firmware Image Downloading .................................................................................... 23 Figure 3: Call Flow of Package URI Observing and Firmware Downloading........................................... 24 Figure 4: Call Flow of 'Update' Resource Observing and Update Event Processing.............................. 25 BG77xA-GL&BG95xA-GL_DFOTA_Application_Note 7 / 31 LPWA Module Series 1 Introduction Quectel BG77xA-GL and BG95xA-GL modules support DFOTA (Delta Firmware Upgrade Over-The-Air) feature, which allows users to update firmware wirelessly. A delta firmware package, which contains only the differences between the current and the target update version, is needed before firmware updating in DFOTA. Therefore, DFOTA is time-saving and can reduce unnecessary data transmission. This document mainly explains how to update the firmware of BG77xA-GL and BG95xA-GL modules via DFOTA, which can be triggered either by AT+QFOTADL or the LwM2M server. 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_DFOTA_Application_Note 8 / 31 LPWA Module Series 1.2. Special Mark Table 2: Special Mark Mark * Definition Unless otherwise specified, an asterisk (*) after a function, feature, interface, pin name, 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 the model is currently unavailable. BG77xA-GL&BG95xA-GL_DFOTA_Application_Note 9 / 31 LPWA Module Series 2 Trigger DFOTA by AT Commands 2.1. Firmware Update Procedure The following chart illustrates the DFOTA procedure triggered by the AT command, provided that the delta firmware package is stored on an HTTP(S)/CoAP(S) server. 2. Put the package on HTTP(S)/CoAP(S) Server HTTP(S)/CoAP(S) Server 1. Get delta firmware package LTE/EGPRS (HTTP(S)/CoAP(S)) 5. Automatically download the package from HTTP(S)/CoAP(S) server via LTE/EGPRS network Ext. MCU 3. Check APN setting and network status Quectel Module 4. Execute AT+QFOTADL 6. Automatically update module firmware Figure 1: DFOTA Procedure (Triggered by AT Command) BG77xA-GL&BG95xA-GL_DFOTA_Application_Note 10 / 31 LPWA Module Series As shown in the above figure, the following steps need to be performed to update the firmware when the delta firmware package is stored on the HTTP(S)/CoAP(S) server: Step 1: Get a delta firmware package from Quectel. Step 2: Put the delta firmware package on the HTTP(S)/CoAP(S) server. Step 3: Check the APN setting and network status. Step 4: Execute AT+QFOTADL, and the delta firmware package will be downloaded automatically to the module from the HTTP(S)/CoAP(S) server via LTE/EGPRS network (Step '5' in the figure above). Then, the firmware of the module will be updated automatically (Step '6' in the figure above). 2.1.1. Get Delta Firmware Package Before updating, check the current firmware version with AT+GMR and select a target firmware version, and then send the two firmware versions to Quectel or module supplier to get a delta firmware package. 2.1.2. Put Delta Firmware Package on HTTP(S)/CoAP(S) Server Step 1: Set up the HTTP(S)/CoAP(S) server before using the DFOTA function (Quectel does not provide such servers). Step 2: Put the delta firmware package on the server and record its storage path. Step 3: After executing the corresponding AT command, the module downloads the delta firmware package using the URL path of the file uploaded on the server. 2.1.3. Check APN Setting and Network Status Step 1: Check APN setting: check if the APN is set properly after putting the delta firmware package on the HTTP(S)/CoAP(S) server. For instance, the APN for a Telstra (U)SIM card should be 'Telstra.internet'. The relevant AT commands are listed below: ⚫ AT+QCFGEXT='fota_apn': Query DFOTA APN. ⚫ AT+QCFGEXT='fota_apn',0,'Telstra.internet': Set DFOTA APN. Step 2: Check network status: after the APN setting is confirmed, make sure that the data network is registered before firmware updating. The relevant AT commands are listed below: ⚫ AT+CSQ: Query signal quality ⚫ AT+CEREG?: Query network registration status (Optional: AT+CGREG? for modules using 2G network) ⚫ AT+COPS?: Query the registered operator For more information about the above commands, see document [1]. BG77xA-GL&BG95xA-GL_DFOTA_Application_Note 11 / 31 LPWA Module Series 2.1.4. Execute AT Command to Update Firmware After checking the APN setting and network status, execute AT+QFOTADL to download the delta firmware package to the module from the HTTP(S)/CoAP(S) server via LTE/EGPRS network. Then, the firmware of the module will be updated. For an example, see Chapter 2.3. 2.2. DFOTA-Related AT Commands 2.2.1. AT Command Introduction 2.2.1.1. Definitions ⚫ Carriage return character. ⚫ Line feed character. ⚫ Parameter name. Angle brackets do not appear on command line. ⚫ [...] Optional parameter of a command or an optional part of TA information response. Square brackets do not appear on the command line. When an optional parameter is not given in a command, the new value equals its previous value or the default settings, unless otherwise specified. ⚫ Underline Default setting of a parameter. 2.2.1.2. AT Command Syntax All command lines must start with AT or at and end with . Information responses and result codes always start and end with a carriage return character and a line feed character: . In tables presenting commands and responses throughout this document, only the commands and responses are presented, and and are deliberately omitted. Table 3: Type of AT Commands Command Type Test Command Read Command Write Command Syntax Description AT+=? AT+? Test the existence of corresponding command and return information about the type, value, or range of its parameter. Check the current parameter value of the corresponding command. AT+=[,[,[...]]] Set user-definable parameter value. BG77xA-GL&BG95xA-GL_DFOTA_Application_Note 12 / 31 Execution Command AT+ LPWA Module Series Return a specific information parameter or perform a specific action. 2.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.2.3. Description of At Command Mode and Data Mode The COM port of the modules has two working modes: AT command mode and data mode. In AT command mode, the data inputted via the COM port are treated as AT commands, while in data mode, they are treated as data. ⚫ Exit Data Mode Inputting +++ or pulling the MAIN_DTR pin up can make the COM port exit data mode. To prevent +++ from being misinterpreted as data: 1) Do not input any character for at least 1 s before and after inputting +++. 2) Input +++ within 1 s, and wait until OK is returned. When OK is returned, the COM port exits

Products

Services

Support

About

Industries

Technologies

Resources

Masterclasses

Download Zone

Antenna Brochure

Quectel Antenna Brochure 2022

Application Note

Quectel_EP06&EG06&EM06_Series_FILE_Application_Note_V1.0

Quectel_EM12&EG12&EG18_Series_FILE_Application_Note_V1.0

Quectel_EG512R&EM12xR&EM160R_Series_FILE_Application_Note_V1.0

Quectel_EG06xK&Ex120K&EM060K_Series_FILE_Application_Note_V1.0

Quectel_BG95&BG77&BG600L_Series_Voice_Application_Note_V1.0

Quectel_BG95&BG77&BG600L_Series_MQTT-SN_Application_Note_V1.0

Quectel_BG95&BG77&BG600L_Series_Voice_Application_Note_V1.0

Quectel_BG77xA-GL&BG95xA-GL_LwM2M_Application_Note_V1.0

Quectel_BG77xA-GL&BG95xA-GL_CoAP_Application_Note_V1.0

Quectel_EP06&EG06&EM06_Series_Data_Call_Application_Note_V1.0

Quectel_EM12&EG12&EG18_Series_Data_Call_Application_Note_V1.0

Quectel_EG512R&EM12xR&EM160R_Series_Data_Call_Application_Note_V1.0

Quectel_EG06xK&Ex120K&EM060K_Series_Data_Call_Application_Note_V1.0

Quectel_EG060V-EA_RF_FTM_Application_Note_V1.0

Quectel_BG95&BG77&BG600L_Series_GTP_Application_Note_V1.0

Quectel_BG77xA-GL&BG95xA-GL_NIDD_Application_Note_V1.0

Quectel_BG77xA-GL&BG95xA-GL_EMUX_Application_Note_V1.0

Quectel_BG77xA-GL&BG95xA-GL_SSL_Application_Note_V1.0

Quectel_BC65&BC92_HTTP(S)_Application_Note_V1.0

Quectel_BC65&BC92_CoAP_Application_Note_V1.0

Quectel_BC68-GV&BC95-GV_CoAP_Application_Note_V1.0

Quectel_EM12xR-GL&EM160R-GL_Secure_Boot_Application_Note_V1.0

Quectel_BC660K-GL_LwM2M_Application_Note_V1.0

Quectel_RG500U-EA_DFOTA_Application_Note_V1.0

Quectel_LC26G&LC76G&LC86G_Series_AGNSS_Application_Note_V1.0

Quectel_L89_R2.0&LC29H&LC79H_Series_I2C_Application_Note_V1.0