From d8af3f0d74268594a3d47218aba3bad7dfcd3f36 Mon Sep 17 00:00:00 2001 From: Felix Hou Date: Wed, 8 May 2024 21:23:01 +0800 Subject: [PATCH] =?UTF-8?q?=20():=20<=E5=A2=9E=E5=8A=A0?= =?UTF-8?q?=E6=97=A0=E7=BA=BF=E8=AE=A4=E8=AF=81=E6=96=B9=E5=BC=8F=E3=80=81?= =?UTF-8?q?=E5=A2=9E=E5=8A=A0STA=E6=96=AD=E5=BC=80=E5=8E=9F=E5=9B=A0>?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit <修改点详述>SW1PQUECPYTHON-4853、SW1PQUECPYTHON-4862 固件版本: N/A 是否需要文案翻译: 否 --- docs/API_reference/en/wifilib/WLAN.md | 192 +++++++-------- docs/API_reference/zh/wifilib/WLAN.md | 337 +++++++++++++------------- 2 files changed, 251 insertions(+), 278 deletions(-) diff --git a/docs/API_reference/en/wifilib/WLAN.md b/docs/API_reference/en/wifilib/WLAN.md index b49a3be1..570704f4 100644 --- a/docs/API_reference/en/wifilib/WLAN.md +++ b/docs/API_reference/en/wifilib/WLAN.md @@ -47,6 +47,7 @@ Initialize WLAN network card and return a WLAN object. - `network.AP_STA_MODE` : `3` - AP+Station mode, supports both wireless client connections and connection to a wireless network. > Note: +> > 1. Only one WLAN network card object can be created. Attempting to create more will raise an exception: `ERR_WLAN_NETIF_IS_BUSY`. > 2. The WLAN network card has a total of four working modes as mentioned above. These four modes are actually operations on two network interfaces: the `softap interface` and the `station interface`. When the mode is `AP_STA_MODE`, both `softap` and `station` interfaces coexist. Therefore, when calling some interface-specific functions, the `interface` parameter needs to be specified to indicate the intended interface, or else it won't be clear which interface you are targeting. @@ -73,12 +74,12 @@ Set or query the wireless network card operating mode. - Query the wireless network card operating mode When called without parameters, it queries the wireless network card operating mode. - - Set the wireless network card operating mode - + When a parameter is provided, it sets the wireless network card operating mode. After mode switching, the wireless network card is in a stopped state. **Parameter:** + - `mode` - Wireless network card operating mode, `int` type. - `network.NONE_MODE` : `0` - Idle mode. - `network.AP_MODE` : `1` - AP (Access Point) mode, supports only wireless client connections. @@ -88,12 +89,12 @@ Set or query the wireless network card operating mode. **Return:** - Query the wireless network card operating mode - - Returns the current operating mode of the wireless network card, `int` type. + Returns the current operating mode of the wireless network card, `int` type. - Set the wireless network card operating mode - + Returns an error code, `int` type. + - `ERR_OK` : `2000` - No error. - `ERR_WIFI_BUSY` : `2003` - Already in this operating mode. - `ERR_INTERNAL` : `2006` - Internal error, the underlying interface encountered an error. @@ -125,55 +126,39 @@ Set or query configuration parameters. - Query configuration parameters Input relevant keywords to query parameters, each time only one parameter can be queried, `str` type. - - Set configuration parameters - + When parameters are keyword arguments, it sets the parameters; multiple parameters can be set simultaneously. **Parameter:** - `ap_ssid` - SoftAP's wireless access point name, `str` type, 1~32 characters, default value: `'quecpython'`. - - `ap_password` - SoftAP's wireless access point password, `str` type, 0~63 characters, default value: `'quecpython'`. - + - `AUTH_OPEN` : `0` characters - No password required. - `AUTH_WEP` : `5` characters - Fixed length of 5. - `AUTH_WPA_PSK` : `8~63` characters. - `AUTH_WPA2_PSK` : `8~63` characters. - `AUTH_WPA_WPA2_PSK` : `8~63` characters. - - `ap_auth` - SoftAP's authentication method, `int` type, default value: `AUTH_WPA_WPA2_PSK`. - + - `AUTH_OPEN` : `0` - Open system authentication. - `AUTH_WEP` : `1` - Wired Equivalent Privacy (WEP) authentication. - `AUTH_WPA_PSK` : `2` - WPA Pre-Shared Key (PSK) authentication. - `AUTH_WPA2_PSK` : `3` - WPA2 PSK authentication. - `AUTH_WPA_WPA2_PSK` : `4` - Mixed mode, combining WPA and WPA2 PSK authentication. - - `ap_channel` - SoftAP's channel, `int` type. The allowable range is: `[1,13]`, default value: `3`. - - `ap_hidden` - Whether the wireless access point name of SoftAP is hidden, `bool` type, `True` for hidden, default value: `False`. - - `ap_max_clients` - Maximum number of client connections for SoftAP, `int` type, default value: `4`. - - `ap_mac` - MAC address of SoftAP, `str` type. - - `sta_ssid` - Wireless access point name to be connected by the station, `str` type, 1~32 characters. - - `sta_password` - Password of the wireless access point to be connected by the station, `str` type, 0~63 characters. - - `sta_bssid` - MAC address of the target wireless access point for the station, `str` type. - - `sta_channel` - Channel of the station, `int` type. The allowable range is: `[1,13]`. - - `sta_mac` - MAC address of the station, `str` type. - - `block` - Whether it is in blocking mode, `bool` type, default is `True`, i.e., blocking mode. Non-blocking mode should be used with event callbacks. - - `timeout` - Connection timeout period, `int` type, unit: s, default value: `15`s. - - `country` - Country code, `str` type. - - `event_callback` - WLAN status callback function, called when WLAN status changes, callback function prototype: ```python @@ -181,11 +166,11 @@ Set or query configuration parameters. ``` Callback function parameter description: - + - `event`: Event information, `dict` type, carrying the parameters as follows: - - `type`: Event type, `int` type, see `Event Type` in [Event Codes](#Event-Codes) for details. - - `id`: Specific event, `int` type, see `Event ID` in [Event Codes](#Event-Codes) for details. - - `msg`: Message passed to the user, see `Message Passed to User in Event Callback` in [Event Codes](#Event-Codes) for details. + - `type`: Event type, `int` type, see `Event Type` in [Event Codes](#Event-Codes) for details. + - `id`: Specific event, `int` type, see `Event ID` in [Event Codes](#Event-Codes) for details. + - `msg`: Message passed to the user, see `Message Passed to User in Event Callback` in [Event Codes](#Event-Codes) for details. **Return Value:** @@ -198,10 +183,10 @@ Set or query configuration parameters. - `ERR_NO_STA_IF` : `2017` - Cannot obtain the current query information as the device is not in `STA` or `AP_STA` mode. - `ERR_INTERNAL` : `2006` - Internal error, the underlying interface encountered an error. - `ERR_NOT_SUPPORT` : `2004` - Unsupported parameter. - - Set configuration parameters: - + Returns an error code. + - `ERR_OK` : `2000` - No error. - `ERR_PARAM_INVALID` : `2002` - Parameter error. - `ERR_INTERNAL` : `2006` - Internal error, the underlying interface encountered an error. @@ -249,11 +234,9 @@ Configure/Query the activation status of the network card. - Query Network Card Status It indicates querying the network card status without passing the parameter. - - Activate the Network Card It represents activating/disabling the network card when the parameter is passed as `True`/`False`. - **Parameter:** @@ -264,7 +247,6 @@ Configure/Query the activation status of the network card. - Network card status query Returns `True`/`False`, indicating activated/deactivated, `bool` type. - - Network card activation Returns error code, `int` type. @@ -311,7 +293,8 @@ Connects to a wireless network. Only supports Station mode and can be used for b **Return Value:** Returns error code, `int` type. - - `ERR_OK`: `2000` - No error. + +- `ERR_OK`: `2000` - No error. - `ERR_WOULDBLOCK`: `2015` - In non-blocking mode, when the conditions for establishing a network connection are met, the interface returns `ERR_WOULDBLOCK` and performs an asynchronous network connection. - `ERR_NO_STA_IF`: `2017` - Cannot connect to the Wi-Fi network, as the device is not in `STA` or `AP_STA` mode. - `ERR_PARAM_INVALID`: `2002` - Invalid parameter. @@ -339,11 +322,9 @@ Disconnect from the network. Passing the corresponding MAC or IP of the station can disconnect from that specific station. If no parameters are passed, it disconnects from all stations. - - In STA mode Disconnect from the AP network. - - In AP_STA mode Specify the WLAN interface to be operated on through the `interface` parameter. @@ -351,9 +332,9 @@ Disconnect from the network. **Parameter:** - `interface` - Mandatory for AP_STA Mode, used to specify the WLAN interface to operate on, `int` type. + - `SOFTAP_IF` : `0` - SoftAP interface. - `STATION_IF` : `1` - Station interface. - - `mac` - Disconnect from the specified station with the given MAC address in AP or AP_STA mode. If MAC is `'FF:XX:XX:XX:XX:XX'`, it disconnects from all stations, `str` type. - `ip` - Disconnect from the specified station with the given IP address in AP or AP_STA mode, `str` type. @@ -362,7 +343,8 @@ Disconnect from the network. **Return Value:** Returns an error code. - - `ERR_OK` : `2000` - No error. + +- `ERR_OK` : `2000` - No error. - `ERR_NO_AP_IF` : `2020` - Unable to operate on the softap interface as the current mode is not `AP` or `AP_STA`. - `ERR_NO_STA_IF` : `2017` - Unable to operate on the station interface as the current mode is not `STA` or `AP_STA`. - `ERR_PARAM_INVALID` : `2002` - Parameter error. @@ -405,46 +387,40 @@ Query the status of the WLAN interface. **Parameter:** - `stations_list` - Only for `AP` or `AP_STA` mode, retrieves a list of all stations currently connected to the AP. - - `ap_list` - Only for `STA` or `AP_STA` mode, retrieves information about the currently connected AP. - - `rf` - Retrieves the RF status, see [Status Codes](#Status-Codes). + - `rf` - Retrieves the RF status, see [Status Codes](#Status-Codes). - `softap_if` - Retrieves the current state of the `softap` interface, see [Status Codes](#Status-Codes). - - `station_if` - Retrieves the current state of the `station` interface, see [Status Codes](#Status-Codes). - - `netcfg` - Retrieves the current network configuration status, see [Status Codes](#Status-Codes). **Return Value:** - `stations_list` - Returns a list of all stations currently connected to the AP, `list` type, format: `[(aid, ip, mac), ...]`. - - `ap_list` - Only for `STA` or `AP_STA` mode, retrieves information about the currently connected AP, `list` type, format: `[ssid, password, mac, rssi, channel, auth, cipher]`. + - `auth` - Authentication method, `int` type. + - `AUTH_OPEN` : `0` - Open system authentication. - `AUTH_WEP` : `1` - Wired Equivalent Privacy (WEP) authentication. - `AUTH_WPA_PSK` : `2` - WPA Pre-Shared Key (PSK) authentication. - `AUTH_WPA2_PSK` : `3` - WPA2 Pre-Shared Key (PSK) authentication. - `AUTH_WPA_WPA2_PSK` : `4` - Mixed mode, a combination of WPA and WPA2 PSK authentication. - - `cipher` - Encryption method, `int` type. + - `CIPHER_NONE` : `0` - No encryption. - `CIPHER_WEP40` : `1` - WEP with 40-bit encryption. - `CIPHER_WEP104` : `2` - WEP with 104-bit encryption. - `CIPHER_TKIP` : `3` - TKIP encryption. - `CIPHER_CCMP` : `4` - CCMP encryption. - - `rf` - Retrieves the RF status, `int` type, see [Status Codes](#Status-Codes). - - `softap_if` - Retrieves the current state of the `softap` interface, `int` type, see [Status Codes](#Status-Codes). - - `station_if` - Retrieves the current state of the `station` interface, `int` type, see [Status Codes](#Status-Codes). - - `netcfg` - Retrieves the current network configuration status, `int` type, see [Status Codes](#Status-Codes). - If the execution of this interface fails, it will return an error code: - - `ERR_NO_AP_IF` : `2020` - Unable to perform operations related to the softap interface as the current mode is not `AP` or `AP_STA`. + +- `ERR_NO_AP_IF` : `2020` - Unable to perform operations related to the softap interface as the current mode is not `AP` or `AP_STA`. - `ERR_AP_UNSTART` : `2019` - Softap is not started, unable to query the stations list. - `ERR_NO_STA_IF` : `2017` - Unable to perform operations related to the station interface as the current mode is not `STA` or `AP_STA`. - `ERR_UNCONNECTED_AP` : `2018` - Not connected to an AP, unable to query AP information. @@ -470,7 +446,6 @@ Wireless network scanning. **Parameter:** - `ssid` - Specify the ssid to scan, `str` type, default is not configured, meaning scan all reachable APs in the current area. - - `bssid` - Specify the bssid to scan, `str` type, default is not configured, meaning scan all reachable APs in the current area. - `channel` - Specify the channel to scan, `int` type, default is not configured, meaning scan all channels. - `passive` - Whether it is a passive scan, `bool` type, `True` for passive scan, default is `False`. @@ -481,8 +456,8 @@ Wireless network scanning. In blocking mode, returns the information of the scanned access points, `list` type, `[(ssid, bssid, channel, rssi, auth, hidden), ...]` -| Parameter | Type | Description | -| --------- | ------ | ---------------------------------- | +| Parameter | Type | Description | +| ----------- | -------- | ---------------------------------- | | `ssid` | `str` | Access point name | | `bssid` | `str` | Access point MAC | | `channel` | `int` | Access point channel | @@ -494,11 +469,11 @@ For non-blocking mode, please use it with event callbacks to receive the scan re If scanning fails, it returns the corresponding error code, `int` type. - - `ERR_OK` : `2000` - No error. - - `ERR_WOULDBLOCK` : `2015` - `2015` - In non-blocking mode, when the conditions for hotspot scanning are met, the interface returns `ERR_WOULDBLOCK` and performs asynchronous hotspot scanning. - - `ERR_NO_STA_IF` : `2017` - Unable to use this method as the current mode is not `STA` or `AP_STA`. - - `ERR_PARAM_INVALID` : `2002` - Parameter error. - - `ERR_INTERNAL` : `2006` - Internal error, underlying interface operation failed. +- `ERR_OK` : `2000` - No error. +- `ERR_WOULDBLOCK` : `2015` - `2015` - In non-blocking mode, when the conditions for hotspot scanning are met, the interface returns `ERR_WOULDBLOCK` and performs asynchronous hotspot scanning. +- `ERR_NO_STA_IF` : `2017` - Unable to use this method as the current mode is not `STA` or `AP_STA`. +- `ERR_PARAM_INVALID` : `2002` - Parameter error. +- `ERR_INTERNAL` : `2006` - Internal error, underlying interface operation failed. **Example:** @@ -520,18 +495,17 @@ Configure or query network information. - `interface` - Must specify the interface to configure/query in AP_STA mode, `int` type. - - `SOFTAP_IF` : `0` - SoftAP interface. - - `STATION_IF` : `1` - Station interface. - + - `SOFTAP_IF` : `0` - SoftAP interface. + - `STATION_IF` : `1` - Station interface. - `config` - IP configuration, `tuple` type, format: `(ip, netmask, gateway, primary_dns, secondary_dns)`. - | Parameter | Type | Description | - | --------------- | ----- | ---------------------------- | - | `ip` | `str` | IP address | - | `netmask` | `str` | Subnet mask | - | `gateway` | `str` | Gateway | - | `primary_dns` | `str` | DNS server primary address | - | `secondary_dns` | `str` | DNS server secondary address | + | Parameter | Type | Description | + | ----------------- | ------- | ---------------------------- | + | `ip` | `str` | IP address | + | `netmask` | `str` | Subnet mask | + | `gateway` | `str` | Gateway | + | `primary_dns` | `str` | DNS server primary address | + | `secondary_dns` | `str` | DNS server secondary address | **Return Value:** @@ -539,7 +513,7 @@ For parameter query, returns the corresponding query result. For parameter configuration, returns the corresponding error code, `int` type. - - `ERR_OK` : `2000` - No error. +- `ERR_OK` : `2000` - No error. - `ERR_NO_AP_IF` : `2020` - Unable to query softAP interface parameters as the current mode is not `AP` or `AP_STA`. - `ERR_NO_STA_IF` : `2017` - Unable to query station interface parameters as the current mode is not `STA` or `AP_STA`. - `ERR_PARAM_INVALID` : `2002` - Parameter error. @@ -570,11 +544,11 @@ Enable or disable network configuration. **Parameter:** - `enable` - Enable/disable network configuration, `bool` type, `True` to enable, default is `True`. - - `type` - Network configuration method, `int` type. - - `NETCFG_SMARTCONFIG` : `0` - SmartConfig, as this configuration mode requires enabling promiscuous mode, it will turn off the already enabled AP and STA. - - `NETCFG_WEBCONFIG` : `1` - Web configuration, this configuration mode depends on AP, so please enable softAP first to use this configuration mode for network configuration. After successful activation, please access this address in the browser: http://`IP`:8080/setting, enter the ssid and password to complete the network configuration. Here, `IP` is the IP of the softAP opened by the module, which can be queried through `nic.ifconfig(interface=nic.SOFTAP_IF)`. - - `NETCFG_BLECONFIG` : `2` - BLE configuration. + + - `NETCFG_SMARTCONFIG` : `0` - SmartConfig, as this configuration mode requires enabling promiscuous mode, it will turn off the already enabled AP and STA. + - `NETCFG_WEBCONFIG` : `1` - Web configuration, this configuration mode depends on AP, so please enable softAP first to use this configuration mode for network configuration. After successful activation, please access this address in the browser: http://`IP`:8080/setting, enter the ssid and password to complete the network configuration. Here, `IP` is the IP of the softAP opened by the module, which can be queried through `nic.ifconfig(interface=nic.SOFTAP_IF)`. + - `NETCFG_BLECONFIG` : `2` - BLE configuration. - `timeout` - Configuration timeout, `int` type, unit: s, default is 120s. **Return Value:** @@ -634,13 +608,15 @@ Returns an error code, `int` type. ### Authentication Modes -| Authentication Mode | Value | Description | -| ------------------- | ----- | ----------------------------------------------- | -| AUTH_OPEN | 0 | Open system authentication | -| AUTH_WEP | 1 | Wired Equivalent Privacy (WEP) authentication | -| AUTH_WPA_PSK | 2 | WPA pre-shared key (PSK) authentication | -| AUTH_WPA2_PSK | 3 | WPA2 pre-shared key (PSK) authentication | -| AUTH_WPA_WPA2_PSK | 4 | Mixed mode with WPA and WPA2 PSK authentication | +| Authentication Mode | Value | Description | +| ------------------- | ----- | ------------------------------------------------- | +| AUTH_OPEN | 0 | Open system authentication | +| AUTH_WEP | 1 | Wired Equivalent Privacy (WEP) authentication | +| AUTH_WPA_PSK | 2 | WPA pre-shared key (PSK) authentication | +| AUTH_WPA2_PSK | 3 | WPA2 pre-shared key (PSK) authentication | +| AUTH_WPA_WPA2_PSK | 4 | Mixed mode with WPA and WPA2 PSK authentication | +| AUTH_WPA3_PSK | 5 | WPA3 pre-shared key (PSK) authentication | +| AUTH_WPA2_WPA3_PSK | 6 | Mixed mode with WPA2 and WPA3 PSK authentication | ### Encryption Modes @@ -660,6 +636,16 @@ Returns an error code, `int` type. | NETCFG_WEBCONFIG | 1 | Web configuration | | NETCFG_BLECONFIG | 2 | BLE configuration | +### Reason for STA disconnection + +| Configuration Mode | Value | Description | +| ---------------------- | ----- | --------------- | +| REASON_USER_DISCONNECT | 1 | User disconnect | +| REASON_BEACON_LOST | 2 | Beacon lost | +| REASON_AP_DISCONNECT | 3 | AP disconnect | +| REASON_SCAN_NOT_FOUND | 4 | Scan not found | +| REASON_PWD_ERROR | 5 | password error | + ### Error Codes | Error Code | Value | Description | @@ -709,29 +695,29 @@ Returns an error code, `int` type. ### Event Codes -| Event Type | Event Name | Event ID | Event Description | Message Passed to User in Event Callback | -| ---------- | -------------------------------- | -------- | ------------------------------------------ | ------------------------------------------------------------ | -| 3000 | EVENT_RF_WAKEUP | 3001 | RF Wakeup | None | -| 3000 | EVENT_RF_SLEEP | 3002 | RF Sleep | None | -| 3100 | EVENT_SCAN_DONE | 3101 | Scan Done | Returns scan results, `list` type, format: `[(ssid, bssid, channel, rssi, auth, hidden),...]` | -| 3200 | EVENT_AP_START_SUCCEED | 3201 | AP Creation Successful | None | -| 3200 | EVENT_AP_START_FAILED | 3202 | AP Creation Failed | None | -| 3200 | EVENT_STA_CONNECTED | 3203 | Connected to Station | Returns information about the Station, `dict` type.
`aid`: ID assigned by AP to Station.
`mac`: Station's MAC address. | -| 3200 | EVENT_STA_DISCONNECTED | 3204 | Disconnected from Station | Returns information about the Station, `dict` type.
`aid`: ID assigned by AP to Station.
`ip`: Station's IP address.
`mac`: Station's MAC address. | -| 3200 | EVENT_STA_IP_ASSIGNED | 3205 | IP Assigned to Station | Returns information about the Station, `dict` type.
`aid`: ID assigned by AP to Station.
`ip`: Station's IP address.
`mac`: Station's MAC address. | -| 3300 | EVENT_STA_START_CONN | 3301 | Start Connecting to AP | None | -| 3300 | EVENT_CONN_SUCCEED | 3302 | Connection to AP Successful | Returns information about the connected AP, `dict` type.
`ssid`: Wireless access point name, `str` type.
`password`: Wireless access point password, `str` type.
`bssid`: Wireless access point MAC address, `str` type.
`channel`: Current channel, `int` type.
`rssi`: Signal strength of the wireless access point, `int` type.
`auth`: Authentication mode, `int` type.
`cipher`: Encryption mode, `int` type. | -| 3300 | EVENT_CONN_FAILED | 3303 | Connection to AP Failed | None | -| 3300 | EVENT_CONN_LOST | 3304 | Connection to AP Lost | Returns information about the disconnected AP, `dict` type.
`ssid`: Wireless access point name, `str` type.
`bssid`: Wireless access point MAC address, `str` type.
`reason`: Disconnection reason, `int` type. | -| 3300 | EVENT_GOT_IP | 3305 | IP Obtained | Returns obtained IP information, `tuple` type, format: `(ip, netmask, gateway, primary_dns, secondary_dns)` | -| 3300 | EVENT_LOST_IP | 3306 | IP Lost | None | -| 3400 | EVENT_NETCFG_START_SUCCEED | 3401 | Network Configuration Start Successful | None | -| 3400 | EVENT_NETCFG_START_FAILED | 3402 | Network Configuration Start Failed | None | -| 3400 | EVENT_NETCFG_STOP_SUCCEED | 3403 | Network Configuration Stop Successful | None | -| 3400 | EVENT_NETCFG_STOP_FAILED | 3404 | Network Configuration Stop Failed | None | -| 3400 | EVENT_NETCFG_STAT_CLIENT_CONNECT | 3405 | Network Configuration Client Connected | None | -| 3400 | EVENT_NETCFG_GOT_KEY | 3406 | Network Configuration Got Account Password | Returns the obtained account and password, `tuple` type, format: `(ssid, password)` | -| 3400 | EVENT_NETCFG_TIMEOUT | 3407 | Network Configuration Timeout | None | +| Event Type | Event Name | Event ID | Event Description | Message Passed to User in Event Callback | +| ---------- | -------------------------------- | -------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 3000 | EVENT_RF_WAKEUP | 3001 | RF Wakeup | None | +| 3000 | EVENT_RF_SLEEP | 3002 | RF Sleep | None | +| 3100 | EVENT_SCAN_DONE | 3101 | Scan Done | Returns scan results,`list` type, format: `[(ssid, bssid, channel, rssi, auth, hidden),...]` | +| 3200 | EVENT_AP_START_SUCCEED | 3201 | AP Creation Successful | None | +| 3200 | EVENT_AP_START_FAILED | 3202 | AP Creation Failed | None | +| 3200 | EVENT_STA_CONNECTED | 3203 | Connected to Station | Returns information about the Station,`dict` type. `
aid`: ID assigned by AP to Station. `
mac`: Station's MAC address. | +| 3200 | EVENT_STA_DISCONNECTED | 3204 | Disconnected from Station | Returns information about the Station,`dict` type. `
aid`: ID assigned by AP to Station. `
ip`: Station's IP address. `
mac`: Station's MAC address. | +| 3200 | EVENT_STA_IP_ASSIGNED | 3205 | IP Assigned to Station | Returns information about the Station,`dict` type. `
aid`: ID assigned by AP to Station. `
ip`: Station's IP address. `
mac`: Station's MAC address. | +| 3300 | EVENT_STA_START_CONN | 3301 | Start Connecting to AP | None | +| 3300 | EVENT_CONN_SUCCEED | 3302 | Connection to AP Successful | Returns information about the connected AP,`dict` type. `
ssid`: Wireless access point name, `str` type.`
password`: Wireless access point password, `str` type. `
bssid`: Wireless access point MAC address, `str` type. `
channel`: Current channel, `int` type. `
rssi`: Signal strength of the wireless access point, `int` type. `
auth`: Authentication mode, `int` type. `
cipher`: Encryption mode, `int` type. | +| 3300 | EVENT_CONN_FAILED | 3303 | Connection to AP Failed | None | +| 3300 | EVENT_CONN_LOST | 3304 | Connection to AP Lost | Returns information about the disconnected AP,`dict` type. `
ssid`: Wireless access point name, `str` type.`
bssid`: Wireless access point MAC address, `str` type.`
reason`: Disconnection reason, `int` type. | +| 3300 | EVENT_GOT_IP | 3305 | IP Obtained | Returns obtained IP information,`tuple` type, format: `(ip, netmask, gateway, primary_dns, secondary_dns)` | +| 3300 | EVENT_LOST_IP | 3306 | IP Lost | None | +| 3400 | EVENT_NETCFG_START_SUCCEED | 3401 | Network Configuration Start Successful | None | +| 3400 | EVENT_NETCFG_START_FAILED | 3402 | Network Configuration Start Failed | None | +| 3400 | EVENT_NETCFG_STOP_SUCCEED | 3403 | Network Configuration Stop Successful | None | +| 3400 | EVENT_NETCFG_STOP_FAILED | 3404 | Network Configuration Stop Failed | None | +| 3400 | EVENT_NETCFG_STAT_CLIENT_CONNECT | 3405 | Network Configuration Client Connected | None | +| 3400 | EVENT_NETCFG_GOT_KEY | 3406 | Network Configuration Got Account Password | Returns the obtained account and password,`tuple` type, format: `(ssid, password)` | +| 3400 | EVENT_NETCFG_TIMEOUT | 3407 | Network Configuration Timeout | None | ### Status Codes diff --git a/docs/API_reference/zh/wifilib/WLAN.md b/docs/API_reference/zh/wifilib/WLAN.md index faaac8e5..168713bf 100644 --- a/docs/API_reference/zh/wifilib/WLAN.md +++ b/docs/API_reference/zh/wifilib/WLAN.md @@ -1,9 +1,8 @@ - # WLAN - 无线网络控制 该类主要用于内置 Wi-Fi 网卡控制。 -> 支持模组型号：FCM360W +> 支持模组型号：FCM360W **示例：** @@ -48,8 +47,9 @@ class network.WLAN(mode) - `network.AP_STA_MODE` : `3` - AP+Station模式，既支持无线客户端接入，同时也支持接入无线网络。 > 注意： +> > 1. WLAN网卡对象只能创建一个，如果重复创建将会抛出异常：`ERR_WLAN_NETIF_IS_BUSY`。 -> 2. WLAN网卡总共有以上四种工作模式，这四种工作模式实际上都是在对两个网络接口进行操作：`softap网口`和`station网口`。当模式为`AP_STA_MODE`时，此时`softap`和`station`两种网口并存，所以在调用一些有网口指向性的接口时需要指定`interface`参数，否则我们无法知道您预期操作的网口。 +> 2. WLAN网卡总共有以上四种工作模式，这四种工作模式实际上都是在对两个网络接口进行操作：`softap网口`和 `station网口`。当模式为 `AP_STA_MODE`时，此时 `softap`和 `station`两种网口并存，所以在调用一些有网口指向性的接口时需要指定 `interface`参数，否则我们无法知道您预期操作的网口。 **示例：** @@ -74,12 +74,12 @@ WLAN.mode([mode]) - 查询无线网卡工作模式 不传参时，为查询无线网卡工作模式。 - - 设置无线网卡工作模式 - + 传参时，为设置无线网卡工作模式。模式切换后，无线网卡处于停止工作的状态。 **参数描述：** + - `mode` - 无线网卡工作模式，`int`类型。 - `network.NONE_MODE` : `0` - 空闲模式。 - `network.AP_MODE` : `1` - AP模式，只支持无线客户端接入。 @@ -89,12 +89,12 @@ WLAN.mode([mode]) **返回值描述：** - 查询无线网卡工作模式 - - 返回无线网卡当前的工作模式，`int`类型。 + 返回无线网卡当前的工作模式，`int`类型。 - 设置无线网卡工作模式 - + 返回错误码，`int`类型。 + - `ERR_OK` : `2000` - 无错误。 - `ERR_WIFI_BUSY` : `2003` - 已经处于该工作模式。 - `ERR_INTERNAL` : `2006` - 内部错误，底层接口运行出错。 @@ -126,53 +126,39 @@ WLAN.config(param=value) - 查询配置参数 输入相关的关键字进行参数查询，每次只能查询一个参数，`str`类型。 - - 设置配置参数 - + 当参数为关键字参数时，进行参数设置；可同时设置多个参数。 **参数描述：** - `ap_ssid` - softap的无线接入点名称，`str`类型，1~32 个字符，默认值：`'quecpython'`。 - - `ap_password` - softap的无线接入点密码，`str`类型，0~63 个字符，默认值：`'quecpython'`。 + - `AUTH_OPEN` : `0`个字符 - 无需密码。 - `AUTH_WEP` : `5`个字符 - 固定长度为5。 - `AUTH_WPA_PSK` : `8~63`个字符。 - `AUTH_WPA2_PSK` : `8~63`个字符。 - `AUTH_WPA_WPA2_PSK` : `8~63`个字符。 - - `ap_auth` - softap的认证方式，`int`类型，默认值：`AUTH_WPA_WPA2_PSK`。 + - `AUTH_OPEN` : `0` - 开放式身份认证。 - `AUTH_WEP` : `1` - 有线等效加密身份认证。 - `AUTH_WPA_PSK` : `2` - WPA预共享密钥身份认证。 - `AUTH_WPA2_PSK` : `3` - WPA2预共享密钥身份认证。 - `AUTH_WPA_WPA2_PSK` : `4` - 混合模式，结合WPA和WPA2的PSK身份认证。 - - `ap_channel` - softap的信道，`int`类型。可设置的范围为：`[1,13]`，默认值：`3`。 - - `ap_hidden` - softap的无线接入点名称是否隐藏，`bool`类型，`True`为隐藏，默认值：`False`。 - - `ap_max_clients` - softap的最大client连接数，`int`类型，默认值：`4`。 - - `ap_mac` - softap的MAC地址，`str`类型。 - - `sta_ssid` - station待连接的无线接入点名称，`str`类型，1~32 个字符。 - - `sta_password` - station待连接的无线接入点密码，`str`类型，0~63 个字符。 - - `sta_bssid` - station目标无线接入点的MAC地址，`str`类型。 - - `sta_channel` - station的信道，`int`类型。可设置的范围为：`[1,13]`。 - - `sta_mac` - station的MAC地址，`str`类型。 - -- `block` - 是否为阻塞模式，`bool`类型，默认为`True`，即阻塞模式。非阻塞模式请配合事件回调使用。 - +- `block` - 是否为阻塞模式，`bool`类型，默认为 `True`，即阻塞模式。非阻塞模式请配合事件回调使用。 - `timeout` - 连接超时时间，`int`类型，单位：s，默认值：`15`s。 - - `country` - 国家码，`str`类型。 - - `event_callback` - WLAN状态回调函数，当WLAN状态发生改变时会产生回调，回调函数原型： ``` @@ -180,12 +166,11 @@ WLAN.config(param=value) ``` 回调函数参数描述： - + - `event`：事件信息，`dict`类型，携带的参数如下： - `type`：事件类型，`int`类型，详见[事件码.事件类型](#事件码)。 - `id`：具体的事件，`int`类型，详见[事件码.事件ID](#事件码)。 - `msg`：传递给用户的消息，详见[事件码.事件回调传递给用户的消息](#事件码)。 - **返回值描述：** @@ -194,19 +179,19 @@ WLAN.config(param=value) 返回查询结果。 如果执行该接口失败，将返回错误码。 - - `ERR_NO_AP_IF` : `2020` - 当前不处于`AP`或`AP_STA`模式，无法获取当前查询的信息。 - - `ERR_NO_STA_IF` : `2017` - 当前不处于`STA`或`AP_STA`模式，无法获取当前查询的信息。 + - `ERR_NO_AP_IF` : `2020` - 当前不处于 `AP`或 `AP_STA`模式，无法获取当前查询的信息。 + - `ERR_NO_STA_IF` : `2017` - 当前不处于 `STA`或 `AP_STA`模式，无法获取当前查询的信息。 - `ERR_INTERNAL` : `2006` - 内部错误，底层接口运行出错。 - `ERR_NOT_SUPPORT` : `2004` - 不支持的参数。 - - 设置配置参数： - + 返回错误码。 + - `ERR_OK` : `2000` - 无错误。 - `ERR_PARAM_INVALID` : `2002` - 参数错误。 - `ERR_INTERNAL` : `2006` - 内部错误，底层接口运行出错。 -**示例：** +**示例：** ```python # 查询AP ssid名称配置 @@ -244,16 +229,14 @@ WLAN.config(param=value) WLAN.active([enable]) ``` -网卡激活状态配置/查询 +网卡激活状态配置/查询 - 网卡状态查询 若不传参则表示查询网卡状态。 - - 网卡激活 - 若传参为`True`/`False`，则表示激活/停用网卡。 - + 若传参为 `True`/`False`，则表示激活/停用网卡。 **参数描述：** @@ -263,17 +246,17 @@ WLAN.active([enable]) - 网卡状态查询 - 返回`True`/`False`，表示已激活/未激活，`bool`类型。 - + 返回 `True`/`False`，表示已激活/未激活，`bool`类型。 - 网卡激活 - 返回错误码，`int`类型。 + 返回错误码，`int`类型。 + - `ERR_OK` : `2000` - 无错误。 - `ERR_WOULDBLOCK` : `2015` - 在非阻塞模式下，符合网卡激活的条件后，接口返回 `ERR_WOULDBLOCK`，并进行异步的网卡激活。 - `ERR_PARAM_INVALID` : `2002` - 参数错误。 - `ERR_TIMEOUT` : `2023` - 执行超时。 -**示例：** +**示例：** ```python # 查询网卡状态 @@ -306,19 +289,20 @@ WLAN.connect([ssid, password, bssid, timeout]) - `AUTH_WPA2_PSK` : `8~63`个字符。 - `AUTH_WPA_WPA2_PSK` : `8~63`个字符。 - `bssid` - 填写所要连接的 Wi-Fi 的bssid信息，该参数是目标AP的MAC地址，`str`类型。 -- `timeout` - 连接超时时间，`int`类型，单位：s，默认`15`s。 +- `timeout` - 连接超时时间，`int`类型，单位：s，默认 `15`s。 **返回值描述：** 返回错误码，`int`类型。 - - `ERR_OK` : `2000` - 无错误。 - - `ERR_WOULDBLOCK` : `2015` - 在非阻塞模式下，符合建立网络连接的条件后，接口返回 `ERR_WOULDBLOCK`，并进行异步的网络连接。 - - `ERR_NO_STA_IF` : `2017` - 当前不处于`STA`或`AP_STA`模式，无法连接网络。 - - `ERR_PARAM_INVALID` : `2002` - 参数错误。 - - `ERR_TIMEOUT` : `2023` - 执行超时。 +- `ERR_OK` : `2000` - 无错误。 +- `ERR_WOULDBLOCK` : `2015` - 在非阻塞模式下，符合建立网络连接的条件后，接口返回 `ERR_WOULDBLOCK`，并进行异步的网络连接。 +- `ERR_NO_STA_IF` : `2017` - 当前不处于 `STA`或 `AP_STA`模式，无法连接网络。 +- `ERR_PARAM_INVALID` : `2002` - 参数错误。 +- `ERR_TIMEOUT` : `2023` - 执行超时。 示例： + ```python # 连接AP，并设置超时时间为10s >>> import network @@ -338,14 +322,12 @@ WLAN.disconnect([interface, mac, ip]) 传入对应station的mac或ip可以断开与对应station的连接。 不传参表示断开与所有 station 的连接。 - - 处于 STA 模式时 断开与热点的连接。 - - 处于 AP_STA 模式时 - 通过`interface`参数指定需要操作的 WLAN 网口。 + 通过 `interface`参数指定需要操作的 WLAN 网口。 **参数描述：** @@ -353,7 +335,6 @@ WLAN.disconnect([interface, mac, ip]) - `SOFTAP_IF` : `0` - softap网口 - `STATION_IF` : `1` - station网口。 - - `mac` - AP或者AP_STA模式下断开指定MAC的station连接，如果MAC为'FF:XX:XX:XX:XX:XX'，则表示与所有station断开连接，`str`类型。 - `ip` - AP或者AP_STA模式下断开指定IP的station连接，`str`类型。 @@ -362,13 +343,14 @@ WLAN.disconnect([interface, mac, ip]) **返回值描述：** 返回错误码。 - - `ERR_OK` : `2000` - 无错误。 - - `ERR_NO_AP_IF` : `2020` - 当前不处于`AP`或`AP_STA`模式，无法对softap网口进行操作。 - - `ERR_NO_STA_IF` : `2017` - 当前不处于`STA`或`AP_STA`模式，无法对station网口进行操作。 - - `ERR_PARAM_INVALID` : `2002` - 参数错误。 - - `ERR_INTERNAL` : `2006` - 内部错误，底层接口运行出错。 -**示例：** +- `ERR_OK` : `2000` - 无错误。 +- `ERR_NO_AP_IF` : `2020` - 当前不处于 `AP`或 `AP_STA`模式，无法对softap网口进行操作。 +- `ERR_NO_STA_IF` : `2017` - 当前不处于 `STA`或 `AP_STA`模式，无法对station网口进行操作。 +- `ERR_PARAM_INVALID` : `2002` - 参数错误。 +- `ERR_INTERNAL` : `2006` - 内部错误，底层接口运行出错。 + +**示例：** ```python # AP模式下断开MAC为'7e:d0:3f:21:5d:34'的station @@ -404,54 +386,47 @@ WLAN.status('param') **参数描述：** -- `stations_list` - 仅`AP`或`AP_STA`模式下使用，查询与当前AP连接的所有station列表。 - -- `ap_list` - 仅`STA`或`AP_STA`模式下使用，获取当前连接的AP的信息。 - +- `stations_list` - 仅 `AP`或 `AP_STA`模式下使用，查询与当前AP连接的所有station列表。 +- `ap_list` - 仅 `STA`或 `AP_STA`模式下使用，获取当前连接的AP的信息。 - `rf` - 获取射频状态，见[状态码](#状态码)。 - -- `softap_if` - 获取当前`softap`网口状态，见[状态码](#状态码)。 - -- `station_if` - 获取当前`station`网口状态，见[状态码](#状态码)。 - +- `softap_if` - 获取当前 `softap`网口状态，见[状态码](#状态码)。 +- `station_if` - 获取当前 `station`网口状态，见[状态码](#状态码)。 - `netcfg` - 获取当前配网状态，见[状态码](#状态码)。 +**返回值描述：** -**返回值描述：** - `stations_list` - 返回与当前AP连接的所有station列表，`list`类型，格式：`[(aid, ip, mac),...]`。 +- `ap_list` - 仅 `STA`或 `AP_STA`模式下生效，获取当前连接的AP的信息，`list`类型，格式：`[ssid, password, mac, rssi, channel, auth, cipher]`。 -- `ap_list` - 仅`STA`或`AP_STA`模式下生效，获取当前连接的AP的信息，`list`类型，格式：`[ssid, password, mac, rssi, channel, auth, cipher]`。 - `auth` - 认证方式，`int`类型。 + - `AUTH_OPEN` : `0` - 开放式身份认证。 - `AUTH_WEP` : `1` - 有线等效加密身份认证 - `AUTH_WPA_PSK` : `2` - WPA预共享密钥身份认证。 - `AUTH_WPA2_PSK` : `3` - WPA2预共享密钥身份认证。 - `AUTH_WPA_WPA2_PSK` : `4` - 混合模式，结合WPA和WPA2的PSK身份认证。 - - `cipher` - 加密方式，`int`类型 + - `CIPHER_NONE` : `0` - 无加密。 - `CIPHER_WEP40` : `1` - WEP40加密。 - `CIPHER_WEP104` : `2` - WEP104加密。 - `CIPHER_TKIP` : `3` - TKIP加密。 - `CIPHER_CCMP` : `4` - CCMP加密。 - - `rf` - 获取射频状态，`int`类型，见[状态码](#状态码)。 - -- `softap_if` - 获取当前`softap`网口状态，`int`类型，见[状态码](#状态码)。 - -- `station_if` - 获取当前`station`网口状态，`int`类型，见[状态码](#状态码)。 - +- `softap_if` - 获取当前 `softap`网口状态，`int`类型，见[状态码](#状态码)。 +- `station_if` - 获取当前 `station`网口状态，`int`类型，见[状态码](#状态码)。 - `netcfg` - 获取当前配网状态，`int`类型，见[状态码](#状态码)。 如果执行该接口失败，将返回错误码： - - `ERR_NO_AP_IF` : `2020` - 当前不处于`AP`或`AP_STA`模式，无法执行与softap网口相关的操作。 - - `ERR_AP_UNSTART` : `2019` - softap未开启，无法查询stations列表。 - - `ERR_NO_STA_IF` : `2017` - 当前不处于`STA`或`AP_STA`模式，无法执行与station网口相关的操作。 - - `ERR_UNCONNECTED_AP` : `2018` - 未连接AP，无法查询AP信息。 - - `ERR_PARAM_INVALID` : `2002` - 参数错误。 - - `ERR_INTERNAL` : `2006` - 内部错误，底层接口运行出错。 -**示例：** +- `ERR_NO_AP_IF` : `2020` - 当前不处于 `AP`或 `AP_STA`模式，无法执行与softap网口相关的操作。 +- `ERR_AP_UNSTART` : `2019` - softap未开启，无法查询stations列表。 +- `ERR_NO_STA_IF` : `2017` - 当前不处于 `STA`或 `AP_STA`模式，无法执行与station网口相关的操作。 +- `ERR_UNCONNECTED_AP` : `2018` - 未连接AP，无法查询AP信息。 +- `ERR_PARAM_INVALID` : `2002` - 参数错误。 +- `ERR_INTERNAL` : `2006` - 内部错误，底层接口运行出错。 + +**示例：** ```python # STA模式下获取当前连接的AP信息 @@ -470,23 +445,18 @@ WLAN.scan([ssid, bssid, channel, passive, max_item, scan_time]) **参数描述：** - `ssid` - 指定扫描的ssid，`str`类型，默认不配置，即扫描当前区域内的所有可达的AP。 - - `bssid` - 指定扫描的bssid，`str`类型，默认不配置，即扫描当前区域内的所有可达的AP。 - - `channel` - 指定扫描的信道，`int`类型，默认不配置，即扫描所有信道。 - -- `passive` - 是否为被动扫描，`bool`类型，`True`为被动扫描，默认值为`False`。 - -- `max_item` - 指定扫描的最大AP数，`int`类型，默认值为`128`。 - +- `passive` - 是否为被动扫描，`bool`类型，`True`为被动扫描，默认值为 `False`。 +- `max_item` - 指定扫描的最大AP数，`int`类型，默认值为 `128`。 - `scan_time` - 每个通道的扫描时间，单位：ms，`int`类型，默认不配置。 **返回值描述：** -阻塞模式扫描成功返回扫描到的可接入点信息，`list`类型，`[(ssid, bssid, channel, rssi, auth, hidden)，...]` +阻塞模式扫描成功返回扫描到的可接入点信息，`list`类型，`[(ssid, bssid, channel, rssi, auth, hidden)，...]` -| 参数 | 类型 | 说明 | -| --------- | ------ | ----------------- | +| 参数 | 类型 | 说明 | +| ----------- | -------- | ----------------- | | `ssid` | `str` | 可接入点 名称 | | `bssid` | `str` | 可接入点 MAC | | `channel` | `int` | 可接入点 所在信道 | @@ -497,14 +467,14 @@ WLAN.scan([ssid, bssid, channel, passive, max_item, scan_time]) 非阻塞模式请配合事件回调使用，在回调中返回扫描结果。 扫描失败返回对应错误码，`int`类型。 - - `ERR_OK` : `2000` - 无错误。 - - `ERR_WOULDBLOCK` : `2015` - 在非阻塞模式下，符合热点扫描的条件后，接口返回 `ERR_WOULDBLOCK`，并进行异步的热点扫描。 - - `ERR_NO_STA_IF` : `2017` - 当前不处于`STA`或`AP_STA`模式，无法使用该方法。 - - `ERR_PARAM_INVALID` : `2002` - 参数错误。 - - `ERR_INTERNAL` : `2006` - 内部错误，底层接口运行出错。 +- `ERR_OK` : `2000` - 无错误。 +- `ERR_WOULDBLOCK` : `2015` - 在非阻塞模式下，符合热点扫描的条件后，接口返回 `ERR_WOULDBLOCK`，并进行异步的热点扫描。 +- `ERR_NO_STA_IF` : `2017` - 当前不处于 `STA`或 `AP_STA`模式，无法使用该方法。 +- `ERR_PARAM_INVALID` : `2002` - 参数错误。 +- `ERR_INTERNAL` : `2006` - 内部错误，底层接口运行出错。 -**示例：** +**示例：** ```python # STA模式下扫描ssid名为'Tenda_996'的AP @@ -526,10 +496,10 @@ WLAN.ifconfig([interface, config]) - `SOFTAP_IF` : `0` - softap网口 - `STATION_IF` : `1` - station网口。 - - `config` - ip配置，`tuple`类型，格式：`(ip, netmask, gateway, primary_dns, secondary_dns)`。 - | 参数 | 类型 | 说明 | - | --------------- | ----- | --------------- | + + | 参数 | 类型 | 说明 | + | ----------------- | ------- | --------------- | | `ip` | `str` | ip地址 | | `netmask` | `str` | 子网掩码 | | `gateway` | `str` | 网关 | @@ -541,13 +511,14 @@ WLAN.ifconfig([interface, config]) 参数查询返回对应的查询结果。 参数配置返回对应错误码，`int`类型。 - - `ERR_OK` : `2000` - 无错误。 - - `ERR_NO_AP_IF` : `2020` - 当前不处于`AP`或`AP_STA`模式，无法使用查询softap网口参数。 - - `ERR_NO_STA_IF` : `2017` - 当前不处于`STA`或`AP_STA`模式，无法查询station网口参数。 - - `ERR_PARAM_INVALID` : `2002` - 参数错误。 - - `ERR_INTERNAL` : `2006` - 内部错误，底层接口运行出错。 -**示例：** +- `ERR_OK` : `2000` - 无错误。 +- `ERR_NO_AP_IF` : `2020` - 当前不处于 `AP`或 `AP_STA`模式，无法使用查询softap网口参数。 +- `ERR_NO_STA_IF` : `2017` - 当前不处于 `STA`或 `AP_STA`模式，无法查询station网口参数。 +- `ERR_PARAM_INVALID` : `2002` - 参数错误。 +- `ERR_INTERNAL` : `2006` - 内部错误，底层接口运行出错。 + +**示例：** 查询station网口的ip信息： @@ -556,6 +527,7 @@ nic.ifconfig(interface=nic.STATION_IF) ``` 设置station网口的ip信息： + ```python nic.ifconfig(interface=nic.STATION_IF, config=('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8', '114.114.114.114')) ``` @@ -570,31 +542,29 @@ WLAN.netcfg(enable=True, type=nic.NETCFG_SMARTCONFIG, timeout=120) **参数描述：** -- `enable` - 开启/关闭配网，`bool`类型，`True`为开启，默认为`True`。 - +- `enable` - 开启/关闭配网，`bool`类型，`True`为开启，默认为 `True`。 - `type` - 配网方式，`int`类型。 - `NETCFG_SMARTCONFIG` : `0` - smartconfig配网，由于该配网模式需要开启混杂模式，所以启动后会关闭已开启的AP和STA。 - - - `NETCFG_WEBCONFIG` : `1` - web配网，该配网模式依赖AP，所有请先开启softap才能使用该配网模式进行配网，成功开启后，请使用浏览器访问该地址：http://`IP`:8080/setting，输入ssid和密码后即可完成配网。此处`IP`为模组开启的softap的IP，可以通过`nic.ifconfig(interface=nic.SOFTAP_IF)`来查询。 - + - `NETCFG_WEBCONFIG` : `1` - web配网，该配网模式依赖AP，所有请先开启softap才能使用该配网模式进行配网，成功开启后，请使用浏览器访问该地址：http://`IP`:8080/setting，输入ssid和密码后即可完成配网。此处 `IP`为模组开启的softap的IP，可以通过 `nic.ifconfig(interface=nic.SOFTAP_IF)`来查询。 - `NETCFG_BLECONFIG` : `2` - ble配网。 - - `timeout` - 配网超时时间，`int`类型，单位：s，默认120s。 **返回值描述：** 返回错误码，`int`类型。 - - `ERR_OK` : `2000` - 无错误。 - - `ERR_WOULDBLOCK` : `2015` - 在非阻塞模式下，符合配网的条件后，接口返回 `ERR_WOULDBLOCK`，并进行异步的配网流程。 - - `ERR_NETCFG_BUSY` : `2024` - 重复开启配网。 - - `ERR_AP_UNSTART` : `2019` - 使用webconfig前需开启AP，webconfig业务逻辑依赖于此AP。 - - `ERR_TIMEOUT` : `2023` - 执行超时。 - - `ERR_PARAM_INVALID` : `2002` - 参数错误。 - - `ERR_INTERNAL` : `2006` - 内部错误，底层接口运行出错。 - - `ERR_NOT_SUPPORT` : `2004` - 不支持的操作。 -**示例：** +- `ERR_OK` : `2000` - 无错误。 +- `ERR_WOULDBLOCK` : `2015` - 在非阻塞模式下，符合配网的条件后，接口返回 `ERR_WOULDBLOCK`，并进行异步的配网流程。 +- `ERR_NETCFG_BUSY` : `2024` - 重复开启配网。 +- `ERR_AP_UNSTART` : `2019` - 使用webconfig前需开启AP，webconfig业务逻辑依赖于此AP。 +- `ERR_TIMEOUT` : `2023` - 执行超时。 +- `ERR_PARAM_INVALID` : `2002` - 参数错误。 +- `ERR_INTERNAL` : `2006` - 内部错误，底层接口运行出错。 +- `ERR_NOT_SUPPORT` : `2004` - 不支持的操作。 + +**示例：** + ```python # 开启AP模式并开始web配网 >>> import network @@ -618,44 +588,62 @@ WLAN.netcfg(enable=True, type=nic.NETCFG_SMARTCONFIG, timeout=120) ``` ## 常量 + ### 模式 -| 模式 | 值 | 说明 | -| ----------- | --- | -------------- | -| NONE_MODE | 0 | 空闲模式 | -| AP_MODE | 1 | AP模式 | -| STA_MODE | 2 | Station模式 | -| AP_STA_MODE | 3 | AP+Station模式 | + +| 模式 | 值 | 说明 | +| ----------- | -- | -------------- | +| NONE_MODE | 0 | 空闲模式 | +| AP_MODE | 1 | AP模式 | +| STA_MODE | 2 | Station模式 | +| AP_STA_MODE | 3 | AP+Station模式 | ### 网口 -| 网口 | 值 | 说明 | -| ---------- | --- | ----------- | -| SOFTAP_IF | 0 | softap网口 | -| STATION_IF | 1 | station网口 | + +| 网口 | 值 | 说明 | +| ---------- | -- | ----------- | +| SOFTAP_IF | 0 | softap网口 | +| STATION_IF | 1 | station网口 | ### 认证方式 -| 认证方式 | 值 | 说明 | -| ----------------- | --- | ------------------------------------ | -| AUTH_OPEN | 0 | 开放式身份认证 | -| AUTH_WEP | 1 | 有线等效加密身份认证 | -| AUTH_WPA_PSK | 2 | WPA预共享密钥身份认证 | -| AUTH_WPA2_PSK | 3 | WPA2预共享密钥身份认证 | -| AUTH_WPA_WPA2_PSK | 4 | 混合模式，结合WPA和WPA2的PSK身份认证 | + +| 认证方式 | 值 | 说明 | +| ------------------ | -- | ------------------------------------- | +| AUTH_OPEN | 0 | 开放式身份认证 | +| AUTH_WEP | 1 | 有线等效加密身份认证 | +| AUTH_WPA_PSK | 2 | WPA预共享密钥身份认证 | +| AUTH_WPA2_PSK | 3 | WPA2预共享密钥身份认证 | +| AUTH_WPA_WPA2_PSK | 4 | 混合模式，结合WPA和WPA2的PSK身份认证 | +| AUTH_WPA3_PSK | 5 | WPA3预共享密钥身份认证 | +| AUTH_WPA2_WPA3_PSK | 6 | 混合模式，结合WPA2和WPA3的PSK身份认证 | ### 加密方式 -| 加密方式 | 值 | 说明 | -| ------------- | --- | ---------- | -| CIPHER_NONE | 0 | 无加密 | -| CIPHER_WEP40 | 1 | WEP40加密 | -| CIPHER_WEP104 | 2 | WEP104加密 | -| CIPHER_TKIP | 3 | TKIP加密 | -| CIPHER_CCMP | 4 | CCMP加密 | + +| 加密方式 | 值 | 说明 | +| ------------- | -- | ---------- | +| CIPHER_NONE | 0 | 无加密 | +| CIPHER_WEP40 | 1 | WEP40加密 | +| CIPHER_WEP104 | 2 | WEP104加密 | +| CIPHER_TKIP | 3 | TKIP加密 | +| CIPHER_CCMP | 4 | CCMP加密 | ### 配网方式 -| 配网方式 | 值 | 说明 | -| ------------------ | --- | --------------- | -| NETCFG_SMARTCONFIG | 0 | smartconfig配网 | -| NETCFG_WEBCONFIG | 1 | web配网 | -| NETCFG_BLECONFIG | 2 | ble配网 | + +| 配网方式 | 值 | 说明 | +| ------------------ | -- | --------------- | +| NETCFG_SMARTCONFIG | 0 | smartconfig配网 | +| NETCFG_WEBCONFIG | 1 | web配网 | +| NETCFG_BLECONFIG | 2 | ble配网 | + +### STA断开原因 + +| 配网方式 | 值 | 说明 | +| ---------------------- | -- | ------------------ | +| REASON_USER_DISCONNECT | 1 | 用户主动断开 | +| REASON_BEACON_LOST | 2 | 失去Beacon信号 | +| REASON_AP_DISCONNECT | 3 | 无线接入点主动断开 | +| REASON_SCAN_NOT_FOUND | 4 | 没有找到特定的网络 | +| REASON_PWD_ERROR | 5 | 密码错误 | ### 错误码 @@ -706,29 +694,29 @@ WLAN.netcfg(enable=True, type=nic.NETCFG_SMARTCONFIG, timeout=120) ### 事件码 -| 事件类型 | 事件名 | 事件ID | 事件说明 | 事件回调传递给用户的消息 | -| -------- | -------------------------------- | ------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 3000 | EVENT_RF_WAKEUP | 3001 | 射频唤醒 | None | -| 3000 | EVENT_RF_SLEEP | 3002 | 射频休眠 | None | -| 3100 | EVENT_SCAN_DONE | 3101 | 扫描结束 | 返回扫描结果，`list`类型，格式：`[(ssid, bssid, channel, rssi, auth, hidden)，...]` | -| 3200 | EVENT_AP_START_SUCCEED | 3201 | AP创建成功 | None | -| 3200 | EVENT_AP_START_FAILED | 3202 | AP创建失败 | None | -| 3200 | EVENT_STA_CONNECTED | 3203 | 与Station建立连接 | 返回Station的信息，`dict`类型。
`aid`: AP为Station分配的id。
`mac`: Station的MAC地址。 | -| 3200 | EVENT_STA_DISCONNECTED | 3204 | 与Station断开连接 | 返回Station的信息，`dict`类型。
`aid`: AP为Station分配的id。
`ip`: Station的IP地址。
`mac`: Station的MAC地址。 | -| 3200 | EVENT_STA_IP_ASSIGNED | 3205 | 已为Station分配IP | 返回Station的信息，`dict`类型。
`aid`: AP为Station分配的id。
`ip`: Station的IP地址。
`mac`: Station的MAC地址。 | -| 3300 | EVENT_STA_START_CONN | 3301 | 开始连接AP | None | -| 3300 | EVENT_CONN_SUCCEED | 3302 | 连接AP成功 | 返回已连接的AP信息，`dict`类型。
`ssid`: 无线接入点名称，`str`类型。
`password`: 无线接入点密码，`str`类型。
`bssid`: 无线接入点MAC地址，`str`类型。
`channel`: 当前所处信道，`int`类型。
`rssi`: 无线接入点信号强度，`int`类型。
`auth`: 认证方式，`int`类型。
`cipher`: 加密方式，`int`类型。 | -| 3300 | EVENT_CONN_FAILED | 3303 | 连接AP失败 | None | -| 3300 | EVENT_CONN_LOST | 3304 | 与AP断开连接 | 返回断开连接的AP信息，`dict`类型。
`ssid`: 无线接入点名称，`str`类型。
`bssid`: 无线接入点MAC地址，`str`类型。
`reason`: 断连原因，`int`类型。 | -| 3300 | EVENT_GOT_IP | 3305 | 获取到IP | 返回获取到的IP信息，`tuple`类型，格式：`(ip, netmask, gateway, primary_dns, secondary_dns)` | -| 3300 | EVENT_LOST_IP | 3306 | IP丢失 | None | -| 3400 | EVENT_NETCFG_START_SUCCEED | 3401 | 配网启动成功 | None | -| 3400 | EVENT_NETCFG_START_FAILED | 3402 | 配网启动失败 | None | -| 3400 | EVENT_NETCFG_STOP_SUCCEED | 3403 | 配网停止成功 | None | -| 3400 | EVENT_NETCFG_STOP_FAILED | 3404 | 配网停止失败 | None | -| 3400 | EVENT_NETCFG_STAT_CLIENT_CONNECT | 3405 | 配网有客户端连接 | None | -| 3400 | EVENT_NETCFG_GOT_KEY | 3406 | 配网获取到账号密码 | 返回获取到的账号密码，`tuple`类型，格式：`(ssid, password)` | -| 3400 | EVENT_NETCFG_TIMEOUT | 3407 | 配网超时 | None | +| 事件类型 | 事件名 | 事件ID | 事件说明 | 事件回调传递给用户的消息 | +| -------- | -------------------------------- | ------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 3000 | EVENT_RF_WAKEUP | 3001 | 射频唤醒 | None | +| 3000 | EVENT_RF_SLEEP | 3002 | 射频休眠 | None | +| 3100 | EVENT_SCAN_DONE | 3101 | 扫描结束 | 返回扫描结果，`list`类型，格式：`[(ssid, bssid, channel, rssi, auth, hidden)，...]` | +| 3200 | EVENT_AP_START_SUCCEED | 3201 | AP创建成功 | None | +| 3200 | EVENT_AP_START_FAILED | 3202 | AP创建失败 | None | +| 3200 | EVENT_STA_CONNECTED | 3203 | 与Station建立连接 | 返回Station的信息，`dict`类型。`
aid`: AP为Station分配的id。`
mac`: Station的MAC地址。 | +| 3200 | EVENT_STA_DISCONNECTED | 3204 | 与Station断开连接 | 返回Station的信息，`dict`类型。`
aid`: AP为Station分配的id。`
ip`: Station的IP地址。`
mac`: Station的MAC地址。 | +| 3200 | EVENT_STA_IP_ASSIGNED | 3205 | 已为Station分配IP | 返回Station的信息，`dict`类型。`
aid`: AP为Station分配的id。`
ip`: Station的IP地址。`
mac`: Station的MAC地址。 | +| 3300 | EVENT_STA_START_CONN | 3301 | 开始连接AP | None | +| 3300 | EVENT_CONN_SUCCEED | 3302 | 连接AP成功 | 返回已连接的AP信息，`dict`类型。 `
ssid`: 无线接入点名称，`str`类型。`
password`: 无线接入点密码，`str`类型。 `
bssid`: 无线接入点MAC地址，`str`类型。 `
channel`: 当前所处信道，`int`类型。 `
rssi`: 无线接入点信号强度，`int`类型。 `
auth`: 认证方式，`int`类型。 `
cipher`: 加密方式，`int`类型。 | +| 3300 | EVENT_CONN_FAILED | 3303 | 连接AP失败 | None | +| 3300 | EVENT_CONN_LOST | 3304 | 与AP断开连接 | 返回断开连接的AP信息，`dict`类型。 `
ssid`: 无线接入点名称，`str`类型。`
bssid`: 无线接入点MAC地址，`str`类型。`
reason`: 断连原因，`int`类型。 | +| 3300 | EVENT_GOT_IP | 3305 | 获取到IP | 返回获取到的IP信息，`tuple`类型，格式：`(ip, netmask, gateway, primary_dns, secondary_dns)` | +| 3300 | EVENT_LOST_IP | 3306 | IP丢失 | None | +| 3400 | EVENT_NETCFG_START_SUCCEED | 3401 | 配网启动成功 | None | +| 3400 | EVENT_NETCFG_START_FAILED | 3402 | 配网启动失败 | None | +| 3400 | EVENT_NETCFG_STOP_SUCCEED | 3403 | 配网停止成功 | None | +| 3400 | EVENT_NETCFG_STOP_FAILED | 3404 | 配网停止失败 | None | +| 3400 | EVENT_NETCFG_STAT_CLIENT_CONNECT | 3405 | 配网有客户端连接 | None | +| 3400 | EVENT_NETCFG_GOT_KEY | 3406 | 配网获取到账号密码 | 返回获取到的账号密码，`tuple`类型，格式：`(ssid, password)` | +| 3400 | EVENT_NETCFG_TIMEOUT | 3407 | 配网超时 | None | ### 状态码 @@ -750,4 +738,3 @@ WLAN.netcfg(enable=True, type=nic.NETCFG_SMARTCONFIG, timeout=120) | STATUS_NETCFG_NOT_INTO | 1013 | 配网模式未启动 | | STATUS_NETCFG_INTO | 1014 | 进入配网模式 | | STATUS_NETCFG_GOT_KEY | 1015 | 已获取到 ssid 和 passwd | - -- Gitee