diff --git a/docs/API_reference/en/peripherals/machine.UART.md b/docs/API_reference/en/peripherals/machine.UART.md index 2ad77fd66476638dacdaffb89821b149990a164c..e193f289bc5c3c52540776bb3cdd5c23e158727d 100644 --- a/docs/API_reference/en/peripherals/machine.UART.md +++ b/docs/API_reference/en/peripherals/machine.UART.md @@ -18,7 +18,7 @@ class machine.UART(UART.UARTn, buadrate, databits, parity, stopbits, flowctl) EC200U/EC600U/EG912U/EG915U series support 2400、4800、9600、14400、19200、28800、33600、38400、57600、115200、230400、460800、921600、1000000. -- `databits` - Integer type. Data bit. Range: [5–8]. EC600U/EC200U/EG915U series module only supports 8 data bits. +- `databits` - Integer type. Data bit. Range: [5–8]. EC600U/EC200U/EG915U/EC800G series module only supports 8 data bits. - `parity` - Integer type. Parity check. `0` – NONE, `1` – EVEN, `2` – ODD. diff --git a/docs/API_reference/zh/peripherals/machine.UART.md b/docs/API_reference/zh/peripherals/machine.UART.md index 757309f391637d10c508cd8a32b5f9948cf7fcf8..371b6d9e67e157200f7190459bf7f1b959055fdb 100644 --- a/docs/API_reference/zh/peripherals/machine.UART.md +++ b/docs/API_reference/zh/peripherals/machine.UART.md @@ -18,7 +18,7 @@ class machine.UART(UART.UARTn, baudrate, databits, parity, stopbits, flowctl) EC200U/EC600U/EG912U/EG915U系列支持2400、4800、9600、14400、19200、28800、33600、38400、57600、115200、230400、460800、921600、1000000。 -- `databits` - 数据位[5 ~ 8]，int类型，EC600U/EC200U/EG915U仅支持8位。 +- `databits` - 数据位[5 ~ 8]，int类型，EC600U/EC200U/EG915U/EC800G仅支持8位。 - `parity` - 奇偶校验(`0` – NONE，`1` – EVEN，`2` – ODD)，int类型。 diff --git a/docs/Application_guide/en/README.md b/docs/Application_guide/en/README.md index cea0c60f2fc5d8d8489438962cad55f812b849f4..1df0015c33e6f6f5b83bc7b7ca0fb91d2eea5cc6 100644 --- a/docs/Application_guide/en/README.md +++ b/docs/Application_guide/en/README.md @@ -7,7 +7,7 @@ QuecPython Application Guide is a guide on how to use the commonly used function
Background Knowledge -- [Introduction to IoT and Low-code Development](background/iot-and-low-code.md) +- [Introduction to IoT and Low Code Development](background/iot-and-low-code.md) - [Introduction to Wireless Communication Modules](background/wireless-modules.md) @@ -104,7 +104,7 @@ QuecPython Application Guide is a guide on how to use the commonly used function
Helios SDK -- [Helios SDK Development Guide - Beginner](helios-sdk/quick-start.md) -- [Helios SDK Development Guide - Intermediate](helios-sdk/junior.md) -- [Helios SDK Development Guide - Advanced](helios-sdk/advanced.md) +- [Helios SDK Development Guide__Beginner](helios-sdk/quick-start.md) +- [Helios SDK Development Guide__Intermediate](helios-sdk/junior.md) +- [Helios SDK Development Guide__Advanced](helios-sdk/advanced.md)
diff --git a/docs/Application_guide/en/background/project-dev.md b/docs/Application_guide/en/background/project-dev.md index 1a3cbe02098f9da5b428bd0d91a272bc82eafaa9..c7de9a692d2e6aac7c5f16a7f204b14415a320e4 100644 --- a/docs/Application_guide/en/background/project-dev.md +++ b/docs/Application_guide/en/background/project-dev.md @@ -1 +1,3 @@ +# Project Development Process + ![](../media/background/project-dev/project.png) \ No newline at end of file diff --git a/docs/Application_guide/en/dev-tools/Thonny/README.md b/docs/Application_guide/en/dev-tools/Thonny/README.md index 8297f204070b46fc2cb467901a3a2f0b4e6baf04..f79f126d36f520286f2834bd27c6260b77404d95 100644 --- a/docs/Application_guide/en/dev-tools/Thonny/README.md +++ b/docs/Application_guide/en/dev-tools/Thonny/README.md @@ -141,7 +141,7 @@ Click "`select`" in the plugin bar to choose the firmware file you want to downl With Thonny, you can directly write and debug code through the REPL, or edit script files for execution and debugging. -### Select and Configure Interpreter +### Select & Configure Interpreter In the menu bar, select "**`Run`**" --> "**`Configure interpreter`**" --> "**`QuecPython(generic)`**" diff --git a/docs/Application_guide/en/dev-tools/VSCode-Plugin-quecpython/README.md b/docs/Application_guide/en/dev-tools/VSCode-Plugin-quecpython/README.md index a4030de4c3db6d9313b5ad5279e8d7730e0b1705..c82a3c66c4a529675909671483d9ffbb0e7c5ffe 100644 --- a/docs/Application_guide/en/dev-tools/VSCode-Plugin-quecpython/README.md +++ b/docs/Application_guide/en/dev-tools/VSCode-Plugin-quecpython/README.md @@ -39,12 +39,12 @@ The following steps are demonstrated based on the [U-235 development board](http - Use the shortcut `Ctrl+Shift+P` to open the command palette, type `> QuecPython` in it, and select `QuecPython: Focus on Firmware Manager View` from the options, as shown below: - ![cmd-palette.png](../../media/dev-tools/VSCode-Plugin-quecpython/cmd-palette.png) + ![cmd-palette.png](../../media/dev-tools/VSCode-Plugin-quecpython/cmd-palette.png) The firmware flashing interface on the primary sidebar is shown in the following image: -![fw-flash-ui.png](../../media/dev-tools/VSCode-Plugin-quecpython/fw-flash-ui.png) + ![fw-flash-ui.png](../../media/dev-tools/VSCode-Plugin-quecpython/fw-flash-ui.png) 2. **Select Firmware** @@ -52,7 +52,7 @@ The following steps are demonstrated based on the [U-235 development board](http The path to the firmware package will be displayed on the interface: -![selected-fw-path.png](../../media/dev-tools/VSCode-Plugin-quecpython/selected-fw-path.png) + ![selected-fw-path.png](../../media/dev-tools/VSCode-Plugin-quecpython/selected-fw-path.png) 3. **Flash Firmware** @@ -126,7 +126,7 @@ The following steps are demonstrated based on the [U-235 development board](http Press the up or down arrow keys to move the cursor to the desired interface, and press the `Tab` or `Enter` key to complete the code in the `test.py` file. -![code-auto-completed.gif](../../media/dev-tools/VSCode-Plugin-quecpython/code-auto-completed.gif) + ![code-auto-completed.gif](../../media/dev-tools/VSCode-Plugin-quecpython/code-auto-completed.gif) ### File Transfer @@ -149,7 +149,7 @@ During the file transfer process, a pop-up window appears in the bottom right co The imported file `test.py` is shown in the following image: - ![directory-list.png](../../media/dev-tools/VSCode-Plugin-quecpython/directory-list.png) +![directory-list.png](../../media/dev-tools/VSCode-Plugin-quecpython/directory-list.png) ### Run Script File diff --git a/docs/Application_guide/en/hardware/display/touch_screen.md b/docs/Application_guide/en/hardware/display/touch_screen.md index 6169b1cc38fd63b0e6d1455cdfed07b0c48efbe0..b31834f591e6a55908fa48b3c4f972fdc9d0857a 100644 --- a/docs/Application_guide/en/hardware/display/touch_screen.md +++ b/docs/Application_guide/en/hardware/display/touch_screen.md @@ -1,5 +1,5 @@ -## Touchscreen +## Touch Screen In embedded devices, a touchscreen is a common input device used to replace a mouse or other pointing devices for interacting with and controlling the device's interface. It is typically a flat surface on which users can touch and slide their fingers to perform corresponding actions. diff --git a/docs/Application_guide/en/media/network-comm/net-protocols/tcp-udp/osi-7-layers-en.png b/docs/Application_guide/en/media/network-comm/net-protocols/tcp-udp/osi-7-layers-en.png new file mode 100644 index 0000000000000000000000000000000000000000..0c81f9ce425d900f04c2967be753353058cb1b91 Binary files /dev/null and b/docs/Application_guide/en/media/network-comm/net-protocols/tcp-udp/osi-7-layers-en.png differ diff --git a/docs/Application_guide/en/media/network-comm/net-protocols/tcp-udp/tcpip-4-layers-en.png b/docs/Application_guide/en/media/network-comm/net-protocols/tcp-udp/tcpip-4-layers-en.png new file mode 100644 index 0000000000000000000000000000000000000000..013d3ee1806e5adff99038fcfdc5a84ddcb67dc9 Binary files /dev/null and b/docs/Application_guide/en/media/network-comm/net-protocols/tcp-udp/tcpip-4-layers-en.png differ diff --git a/docs/Application_guide/en/network-comm/net-protocols/tcp-udp.md b/docs/Application_guide/en/network-comm/net-protocols/tcp-udp.md index 9dd3befb21bf44d2ee62245869af702de90c3a1d..3933857465bdb6982396ad6092866f18970d36c6 100644 --- a/docs/Application_guide/en/network-comm/net-protocols/tcp-udp.md +++ b/docs/Application_guide/en/network-comm/net-protocols/tcp-udp.md @@ -20,11 +20,11 @@ The Open System Interconnection (OSI) model defined by the International Organiz The seven layers are "Application Layer", "Presentation Layer", "Session Layer", "Transport Layer", "Network Layer", "Data Link Layer", and "Physical Layer". -![](../../media/network-comm/net-protocols/tcp-udp/osi-7-layers.png) +![](../../media/network-comm/net-protocols/tcp-udp/osi-7-layers-en.png) To simplify protocol implementation or facilitate understanding, the models of five layers or four layers have emerged. The four-layer model is generally mentioned more frequently, including "Application Layer", "Transport Layer", "Network Layer" and "Network Interface Layer". -![](../../media/network-comm/net-protocols/tcp-udp/tcpip-4-layers.png) +![](../../media/network-comm/net-protocols/tcp-udp/tcpip-4-layers-en.png) The IP address mentioned earlier belongs to the network layer. diff --git a/docs/Application_guide/en/network-comm/nic/ethernet/ethernet-wan-example.md b/docs/Application_guide/en/network-comm/nic/ethernet/ethernet-wan-example.md index 061a992f8fe8100f0e0016e87513a69da2c0bf6d..a34e8956d8fb4fde7f017583e5eeae5ed1b8327a 100644 --- a/docs/Application_guide/en/network-comm/nic/ethernet/ethernet-wan-example.md +++ b/docs/Application_guide/en/network-comm/nic/ethernet/ethernet-wan-example.md @@ -120,9 +120,9 @@ The following examples demonstrate two methods of TCP communication using Ethern **TCP client binds Ethernet NIC for communication** -In this example, the module performs TCP communication by using the Ethernet NIC and calls *sock.bind()* in the socket module to specify the Ethernet NIC for data sending. +In this example, the module performs TCP communication by using the Ethernet NIC and calls `sock.bind()` in the socket module to specify the Ethernet NIC for data sending. ->In the example below, the parameter 192.168.1.100 in *sock.bind()* specifies the IP address of the Ethernet NIC. +>In the example below, the parameter 192.168.1.100 in `sock.bind()` specifies the IP address of the Ethernet NIC. ```python # Import the usocket module. diff --git a/docs/Application_guide/en/network-comm/nic/network-config.md b/docs/Application_guide/en/network-comm/nic/network-config.md index 4a072fa3c3cbf5dfbd7fd3efec16692d3afc9c2d..710b88f0fbf1674961a58d557391a64635073591 100644 --- a/docs/Application_guide/en/network-comm/nic/network-config.md +++ b/docs/Application_guide/en/network-comm/nic/network-config.md @@ -38,7 +38,7 @@ QuecPython supports various types of NICs. How can we configure the NICs to enab QuecPython provides two ways to configure NICs: 1. QuecPython APIs. 2. Built-in web service. -> Note: Only cellular network modules cannot use the web service. +> Only cellular network modules cannot use the web service. ![](../../media/network-comm/nic/network_config_cmd.png) @@ -72,7 +72,7 @@ Cellular NICs rely on the network operator. A module must be integrated with a S Wi-Fi NICs have different application scenarios in different working modes. In station mode, the NIC needs to connect to a Wi-Fi hotspot (such as a router) to connect to the network. In AP mode, the Wi-Fi NIC serves as a hotspot, accepting connections from other Wi-Fi devices and providing network services to them. -There are multiple ways to configure Wi-Fi NICs, such as directly entering the hotspot name and password, quick configuration, AP configuration and web page configuration. However, the ultimate goal is to successfully obtain the hotspot name and password. This chapter focuses on loading the Wi-Fi NIC and connecting to the hotspot directly. For other configuration methods, please refer to [Wi-Fi NIC](../nic/WIFI/README.md). +There are multiple ways to configure Wi-Fi NICs, such as directly entering the hotspot name and password, quick configuration, AP configuration and web page configuration. However, the ultimate goal is to successfully obtain the hotspot name and password. This chapter focuses on loading the Wi-Fi NIC and connecting to the hotspot directly. For other configuration methods, please refer to [Wi-Fi NIC](../nic/wifi/README.md). ![](../../media/network-comm/nic/network_wifi_station.png) @@ -201,7 +201,7 @@ Cellular communication modules that support USB network adapter are connected to ![](../../media/network-comm/nic/network_usbnet.png) -After calling *set_worktype(USBNET_Type)* to set the protocol type of the USB network adapter, call *USBNET.open()* to enable the USB network adapter. +After calling `set_worktype(USBNET_Type)` to set the protocol type of the USB network adapter, call `USBNET.open()` to enable the USB network adapter. **USBNET_Type** description: @@ -444,7 +444,7 @@ if __name__ == '__main__': In AP mode, the 4G NIC provides network services for devices within the AP LAN, and the 4G NIC is the default NIC. If the module needs to communicate using the Wi-Fi NIC, call *socket.bind()* to specify which NIC to use for network communication. -> Note: For single-NIC devices, IP address binding is not required. +> For single-NIC devices, IP address binding is not required. ![](../../media/network-comm/nic/network_wifi_ap.png) ![](../../media/network-comm/nic/network_wifi_single.png) @@ -503,8 +503,8 @@ In scenarios with multiple NICs, it is unclear which one will be used for networ Call *nic.set_default_NIC(ip)* to set an NIC as the default for external network access. Then enable NAT to forward data from other NICs. As shown below, after calling `nic.set_default_NIC('10.11.129.252')`, data from the Ethernet NIC is forwarded through the 4G NIC. -> Note 1: The interface for configuring the default NIC is mainly designed for users to maintain the default NIC, making it easy to switch network forwarding. -> Note 2: The 4G NIC is fixed as the default. After it makes a data call, it will be configured as the default again. Currently, 4G is mostly used as the default NIC for external forwarding, to avoid the uncertainty that leads to network unavailability. +> The interface for configuring the default NIC is mainly designed for users to maintain the default NIC, making it easy to switch network forwarding. +> The 4G NIC is fixed as the default. After it makes a data call, it will be configured as the default again. Currently, 4G is mostly used as the default NIC for external forwarding, to avoid the uncertainty that leads to network unavailability. ![](../../media/network-comm/nic/network_eth_gateway_default.png) diff --git a/docs/Application_guide/en/network-comm/nic/usbnet/README.md b/docs/Application_guide/en/network-comm/nic/usbnet/README.md index 59f0af8b03594d41ae1de1d7e58403cb0096e268..978321fb10bbd143ca2eea942cc33df9f32f36ec 100644 --- a/docs/Application_guide/en/network-comm/nic/usbnet/README.md +++ b/docs/Application_guide/en/network-comm/nic/usbnet/README.md @@ -164,7 +164,7 @@ USBNET.close() **2. When using the USB network adapter functionality on Unisoc 8910 modules, the computer cannot connect to the network after the first open in default ECM mode.** -> The USBnet of Unisoc 8910 modules requires NAT support. NAT is not enabled by default at boot and needs to be enabled before the USBnet can be used normally. Please refer to the corresponding [USBNET](https://python.quectel.com/doc/API_reference/en/peripherals/misc.USBNET.html) section on the Wiki. For specific Unisoc 8910 modules, see [The Correspondence Between Platforms and Modules](https://python.quectel.com/doc/Application_guide/en/background/hardware-platform.html#Unisoc-Platform). +> The USBNET of Unisoc 8910 modules requires NAT support. NAT is not enabled by default at boot and needs to be enabled before the USBNET can be used normally. Please refer to the corresponding [USBNET](https://python.quectel.com/doc/API_reference/en/peripherals/misc.USBNET.html) section on the Wiki. For specific Unisoc 8910 modules, see [The Correspondence Between Platforms and Modules](https://python.quectel.com/doc/Application_guide/en/background/hardware-platform.html#Unisoc-Platform). **3. For Unisoc 8850 modules, the module opens normally after the USB network adapter is set to RNDIS, but returns -1 when reopened.** diff --git a/docs/Application_guide/en/system/info.md b/docs/Application_guide/en/system/info.md index f81cb3ca463eec3d75ad29f25f40a31357a02341..4bbaf9286f844fdfeb16d9e441190b9fa195d57f 100644 --- a/docs/Application_guide/en/system/info.md +++ b/docs/Application_guide/en/system/info.md @@ -1,4 +1,4 @@ -# System Information +# Device Information This article introduces how to use the `uos`, `usys`, `modem`, and other features to query the firmware information and remaining memory size of the Quectel QuecPython modules, which are frequently concerned by users. This article will be continuously updated to facilitate users in understanding the basic information of the module. diff --git a/docs/Application_guide/en/system/log.md b/docs/Application_guide/en/system/log.md index fe0e2344c11798c6df6788c92ff1417fa5313f00..6d55afd4d08ec5634bbc010a27756ea550a07bc9 100644 --- a/docs/Application_guide/en/system/log.md +++ b/docs/Application_guide/en/system/log.md @@ -1,4 +1,4 @@ -# log - Output Log +# Log Output A log is a tool used to record the runtime state of an application in program development, as well as help developers diagnose and troubleshoot problems. Developers can quickly identify the root causes of problems and better understand the behaviors and performance of applications by viewing logs. `log` feature can output different log levels, including the DEBUG level, WARNING level, and ERROR level. diff --git a/docs/Application_guide/en/system/memory-device.md b/docs/Application_guide/en/system/memory-device.md index 40b75b505a5a8b020e67f428b28853c84556ce02..fd1eb8c4ba30f8cc4061ff6f38a4f111f8deffc5 100644 --- a/docs/Application_guide/en/system/memory-device.md +++ b/docs/Application_guide/en/system/memory-device.md @@ -1,4 +1,4 @@ -# Storage Device Application Note +# Memory Device This document aims to introduce the types, usage, and common issues of QuecPython storage devices, and provide guidance for using QuecPython storage devices. diff --git a/docs/Getting_started/en/network-dev.md b/docs/Getting_started/en/network-dev.md new file mode 100644 index 0000000000000000000000000000000000000000..8ca590dd84ed46b2e1eae821a2e3b47882792c4d --- /dev/null +++ b/docs/Getting_started/en/network-dev.md @@ -0,0 +1,176 @@ +# Cellular infrastructure development + +> This chapter mainly introduces the dial-up internet process of QuecPython module, how to register for network dial-up after receiving the module, and how to handle network exceptions + +## QuecPython dial-up internet process + +### **Equipment hardware connection** + +Firstly, follow the hardware preparation steps above to install the antenna that comes with the development board (some development board models with onboard antennas do not require installation), and insert the SIM card into the SIM card slot on the development board. Then connect the module to the power supply and turn it on. After turning on, the module will automatically activate the network card. + +### **Get dialing information** + +The QuecPython module automatically activates the first cellular wireless network card upon startup. Only when the cellular wireless network card is successfully activated can network services such as socket, HTTP, MQTT, etc. be performed. + +So before taking any business action, it is necessary to obtain dialing information, including dialing status, IP address, DNS server address, etc., in order to determine whether the network card has been successfully activated + +```python +import dataCall +dataCall.getInfo(profileID, ipType) +# profileID - PDP context ID, integer value, range 1-3 +# ipType - IP protocol type, integer value, 0: IPV4 1: IPV6 2: IPV4&IPV6 +``` + +The return value format is + +`(profileID, ipType, [state, reconnect, addr, priDNS, secDNS])` + +The operation of querying the status information of the network card is mandatory for users. Regardless of the application scenario, as long as users need to perform network business operations, they must first check the activation status of the network card and confirm that the cellular wireless network card has been successfully activated. Specifically, as long as users have the following requirements, they need to use `dataCall.getInfo` to query: + +- Confirm whether the activation of the cellular wireless network card is successful by using the state returned by the `dataCall.getInfo` method, where a value of 1 indicates successful activation. +- When users use QuecPython's socket function, they need to know the current IP address of the module. +- After activating multiple cellular wireless network cards, multiple sockets need to be established, and different sockets use different network cards. At this time, it is necessary to obtain the IP address information of each network card and bind it with the corresponding socket. +- Obtain the current DNS address used by the cellular wireless network card. + +If the dial-up information shows that the network card activation has failed, manual activation of the network card is required + +### **Manually activate the network card** + +After the above query processing, if the network card activation fails, the network card needs to be manually activated. Use the following API to manually activate the network card + +```python +dataCall.activate(profileID) +# profileID - PDP context ID, integer value, range 1~3. +``` + +The QuecPython module automatically activates the cellular wireless network card when it is turned on by default. Under normal circumstances, there is no need to manually set the activation or deactivation operation. However, in some special scenarios or user specific needs, the above methods need to be used to manually activate or deactivate the cellular wireless network card, such as: + +The user has disabled the automatic activation of the cellular wireless network card upon startup, and the user application will activate and deactivate the network card at a certain time as needed. In this case, users need to call the `dataCall.activate` and `dataCall.deactivate` methods as needed in their application. + +### **Get SIM card status** + +If the manual activation of the module cellular wireless network card fails, it is necessary to sequentially check the SIM card and network registration status. To query the SIM status, the following API needs to be used to obtain it + +```python +import sim +sim.getStatus() +``` + +If the return value of `sim.getStatus()` is 0, it means that the device did not detect the SIM card, and it is necessary to determine whether the SIM card is inserted. If the user has already inserted the SIM card and restarted the device, but the query status value is still 0, the possible reasons are as follows: + +- The SIM card is not properly inserted, such as being inserted incorrectly or not securely fastened. You can reinsert the SIM card and restart the device, then check if the SIM card status is 1 again after booting up. +- The SIM card itself is damaged. You can insert a functional SIM card, restart the device, and then check if the SIM card status is 1 again. +- The SIM card slot is damaged. If this issue is confirmed, a new card slot needs to be replaced. +- There is a hardware circuit issue with the SIM card, such as poor contact, which prevents the device from recognizing the SIM card properly. Hardware engineers need to check the circuit to confirm the issue. + +Users can investigate the above situations in sequence to confirm the problem. + +If the return value is 1, it means that the SIM card has been detected and the network registration status needs to be checked + +Reference for SIM card abnormalities in other states [SIM card abnormality handling](https://python.quectel.com/doc/Application_guide/en/network-comm/nic/cellular/exception-handling.html#SIM-Card-Exception) + +### **Get device network registration status** + +The cellular wireless network registration status of the device is a very important parameter. The prerequisite for successfully activating the cellular wireless network card is that the device must first successfully subscribe to the network. QuecPython provides relevant APIs for querying the device's registration status. This API allows you to query the network status of the current device + +```python +import net +net.getState() +``` + +The API return value is + +`([voice_state, voice_lac, voice_cid, voice_rat, voice_reject_cause, voice_psc], [data_state, data_lac, data_cid, data_rat, data_reject_cause, data_psc])` + +Among them, data_state represents the network registration status, which can have various situations. When the return value is 1 or 5, it can be considered as a successful network registration. For specific return values, please refer to [Get Network Registration Information](https://python.quectel.com/doc/API_reference/en/iotlib/net.html#Get-Network-Registration-Information), When the network registration status is not 1 or 5, it can be considered as a network abnormality. There may be multiple reasons for network abnormalities, such as SIM card arrears, SIM card only supporting specific network standards or frequency bands, poor RF performance, and no APN configuration. For detailed handling steps of the above abnormal situations, please refer to [Module Network Registration Failure](https://python.quectel.com/doc/Application_guide/en/network-comm/nic/cellular/exception-handling.html#Module-Network-Registration-Failure) + +Under normal circumstances, as long as the module network card can be successfully activated, users do not need to check the network registration status. The main scenarios that require querying the device's network registration status are as follows: + +- The activation of the module cellular wireless network card failed, and it is necessary to investigate the SIM card and network registration status in sequence. At this point, you can use `net.getState` to query the network registration status and confirm whether the device has successfully registered. If the registration network status is abnormal, you need to continue checking according to the above steps. + +### **Network status detection** + +QuecPython provides an API interface for detecting network status, which can be used to check if the network status is ready. + +```none +checkNet.waitNetworkReady(timeout) +``` + +Wait for the module network to be ready. This method will sequentially detect the SIM card status, module network registration status, and PDP Context activation status; Within the set timeout period, if successful activation of PDP Context is detected, it will immediately return; otherwise, it will only exit after timeout. You can directly use this API interface to detect the network instead of the three steps of detecting SIM card status, module network registration status, and PDP Context activation status mentioned earlier. If any abnormalities are detected in the corresponding steps, the abnormal parts can be detected and processed + +**Parameter description:** + +- `timeout` - Timeout, integer value, range 1~3600 seconds, default '60' seconds. + +**Return value description:** + +Return a tuple in the following format:`(stage, state)` + +| parameter | type | meaning | +| ----- | ---- | ------------------------------------------------------------ | +| stage | integer | Indicate what state is currently being detected: 1 - Detecting SIM card status; 2 - Detecting network registration status; 3 - Detecting PDP Context activation status. | +| state | integer | According to the stage value, different states are represented as follows: When stage=1, state represents the status of the SIM card, range 0-21, detailed description of each state value, please refer to[`sim.getStatus()`](https://python.quectel.com/doc/API_reference/en/iotlib/sim.html#%3Ccode%3Esim.getStatus%3C/code%3E)the return value description of the method; When stage = 2, state indicate network registration status, range 0-11, detailed description of each state value, please refer to[`net.getState()`](https://python.quectel.com/doc/API_reference/en/iotlib/net.html#%3Ccode%3Enet.getState%3C/code%3E)the return value description of the method; When stage = 3, state represents the PDP Context activation status, 0 indicates no successful activation, 1 indicates successful activation. | + + + +### **Exception handling** + +There are two types of network anomalies. One is when a network exception occurs during startup, and the other is when the startup has been successfully logged into the network, and then the network exception occurs during subsequent business processing + +#### Network exception handling during device startup + +The network abnormalities during module startup mainly include three situations, namely: + +- SIM card abnormality +- Module network registration failed +- Cellular wireless network card automatic activation failed + +The direct result of these three situations is that the module cannot connect to the network. Therefore, we refer to these situations as "network anomalies", and the inspection and handling procedures for the above three types of anomalies are described in the previous text. + +#### Network exception handling during device operation + +After the cellular wireless network card is successfully activated, the user's application still needs to pay attention to one thing - the connection status between the device and the network. This is because during the operation of the device, the connection between the module and the network may be disconnected due to some abnormal reasons, such as network abnormalities, environmental interference, poor signals, etc. If the user application does not pay attention to such network events, it is likely to cause abnormal execution of network related business in the user application, resulting in unforeseen problems. + +QuecPython provides network event monitoring functionality, allowing user applications to listen for network state change events by registering callback functions. When the connection status between the device and the wireless network changes, the system will automatically push the corresponding event to the user's application through the callback function registered by the user. + +The method for registering a network listening callback function is as follows: + +```python +dataCall.setCallback(fun) +``` + +An example of a callback function is as follows: + +```python +def netCallback(args): + profileID = args[0] + netState = args[1] + if netState == 0: + print('### network {} disconnected.'.format(profileID)) + elif netState == 1: + print('### network {} connected.'.format(profileID)) +``` + +The parameter of this callback function is a tuple containing 3 elements, and currently users only need to focus on the first two elements. The first two parameters are described as follows: + +| parameter | type | explain | +| ------- | ---- | ------------------------------------------------------------ | +| args[0] | integer | The cellular wireless network card number indicates which wireless network card's network connection status has changed. | +| args[1] | integer | Network status, 0 indicates network connection disconnected, 1 indicates network connection successful. | + +It is recommended that users register this callback function to monitor the network connection status, ensuring that when the network connection status changes, the user application can handle it in a timely manner according to the network status changes. Usually, we can refer to the following methods to handle it: + +- After receiving an event indicating a change in network connection status in the callback function, the message queue function sends the network event to other threads for processing. Of course, users can also use QuecPython's `sys_bus` feature to replace message queues. +- When other threads receive a network event, they determine if it is a network disconnection event and stop network related services such as sockets and MQTT. At the same time, the thread can also choose to start a timer, such as setting the timer time to 60 seconds first. If the network has not been restored after 60 seconds, perform a CFUN0/1 switch and see if the network can be restored. + +> **What is CFUN0/1 switching?** +> +> Through the explanation of CFUN in the chapter "Basic Concepts of Cellular Networks", it can be known that CFUN refers to the functional mode of mobile terminals. CFUN0/1 switching refers to using the `net.setModemFun(0)` method to first switch the device to mode 0 (minimum function mode), and then using the `net.setModemFun(1)` method to switch the device to mode 1 (full function mode). When switching to mode 0, the entire RF network protocol stack of the device is shut down, and the SIM card module stops supplying power; When switching to Mode 1 again, the power supply to the SIM card will be restored and initialized again. At the same time, the software and hardware functions related to RF will be restarted, and the device will initiate the network registration process again. +> +> **Why do we need to switch between CFUN0/1?** +> +> QuecPython has an automatic reconnection function. If a network exception occurs and the device is disconnected from the network, shouldn't it automatically recover after the exception disappears? Why is there still a need to switch between CFUN0/1 in the processing method mentioned above? +> +> We need to clarify that QuecPython's automatic reconnection function refers to the module automatically reactivating the wireless network card after a network anomaly is restored, rather than re registering with the network. The network registration behavior of the device is automatically controlled by the RF network protocol stack of the system. In theory, after the network abnormal factors disappear, the RF network protocol stack will automatically initiate network registration again. However, it cannot be ruled out that due to some reasons, the device may not have re registered with the network in a timely manner. At this point, because the device's network registration has not been successful, the wireless network card cannot be reactivated. Therefore, we took the initiative to switch between CFUN0/1. In fact, it's like when we encounter poor network or no signal when using our mobile phones, we choose to turn off the mobile network first and then turn it back on. Of course, users can also choose to restart. + +