alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'docs/update_wifi_api_doc_v4.4' into 'release/v4.4'

Browse Source 
DOC: update wifi api docs ( backport v4.4)

See merge request espressif/esp-idf!18076
This commit is contained in:
Jiang Jiang Jian 2022-07-07 10:57:36 +08:00
commit afc6f7f932
13 changed files with 294 additions and 259 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
components/esp_netif/include/esp_netif.h
View File

@ -619,9 +619,10 @@ esp_err_t esp_netif_dhcps_stop(esp_netif_t *esp_netif);
*
* If DHCP server is enabled, the Main DNS Server setting is used by the DHCP server to provide a DNS Server option
* to DHCP clients (Wi-Fi stations).
* - The default Main DNS server is typically the IP of the Wi-Fi AP interface itself.
* - The default Main DNS server is typically the IP of the DHCP server itself.
* - This function can override it by setting server type ESP_NETIF_DNS_MAIN.
* - Other DNS Server types are not supported for the Wi-Fi AP interface.
* - Other DNS Server types are not supported for the DHCP server.
* - To propagate the DNS info to client, please stop the DHCP server before using this API.
*
* @param[in] esp_netif Handle to esp-netif instance
* @param[in] type Type of DNS Server to set: ESP_NETIF_DNS_MAIN, ESP_NETIF_DNS_BACKUP, ESP_NETIF_DNS_FALLBACK

34
components/esp_wifi/include/esp_now.h
View File

@ -1,16 +1,8 @@
// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
/*
* SPDX-FileCopyrightText: 2019-2022 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef __ESP_NOW_H__
#define __ESP_NOW_H__
@ -190,7 +182,7 @@ esp_err_t esp_now_unregister_send_cb(void);
* - ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized
* - ESP_ERR_ESPNOW_ARG : invalid argument
* - ESP_ERR_ESPNOW_INTERNAL : internal error
* - ESP_ERR_ESPNOW_NO_MEM : out of memory
* - ESP_ERR_ESPNOW_NO_MEM : out of memory, when this happens, you can delay a while before sending the next data
* - ESP_ERR_ESPNOW_NOT_FOUND : peer is not found
* - ESP_ERR_ESPNOW_IF : current WiFi interface doesn't match that of peer
*/
@ -237,6 +229,20 @@ esp_err_t esp_now_del_peer(const uint8_t *peer_addr);
*/
esp_err_t esp_now_mod_peer(const esp_now_peer_info_t *peer);
/**
* @brief Config ESPNOW rate of specified interface
*
* @attention 1. This API should be called after esp_wifi_start().
*
* @param ifx Interface to be configured.
* @param rate Phy rate to be configured.
*
* @return
* - ESP_OK: succeed
* - others: failed
*/
esp_err_t esp_wifi_config_espnow_rate(wifi_interface_t ifx, wifi_phy_rate_t rate);
/**
* @brief Get a peer whose MAC address matches peer_addr from peer list
*

1
components/esp_wifi/include/esp_private/wifi.h
View File

@ -251,6 +251,7 @@ esp_err_t esp_wifi_internal_set_sta_ip(void);
*
* @attention 1. If fixed rate is enabled, both management and data frame are transmitted with fixed rate
* @attention 2. Make sure that the receiver is able to receive the frame with the fixed rate if you want the frame to be received
* @attention 3. Not support to set fix rate for espnow and 80211_tx
*
* @param ifx : wifi interface
* @param en : false - disable, true - enable

16
components/esp_wifi/include/esp_wifi.h
View File

@ -498,7 +498,7 @@ esp_err_t esp_wifi_get_ps(wifi_ps_type_t *type);
* @brief Set protocol type of specified interface
* The default protocol is (WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N)
*
* @attention Currently we only support 802.11b or 802.11bg or 802.11bgn mode
* @attention Support 802.11b or 802.11bg or 802.11bgn or LR mode
*
* @param ifx interfaces
* @param protocol_bitmap WiFi protocol bitmap
@ -1210,20 +1210,6 @@ esp_err_t esp_wifi_ftm_resp_set_offset(int16_t offset_cm);
*/
esp_err_t esp_wifi_config_11b_rate(wifi_interface_t ifx, bool disable);
/**
* @brief Config ESPNOW rate of specified interface
*
* @attention 1. This API should be called after esp_wifi_init() and before esp_wifi_start().
*
* @param ifx Interface to be configured.
* @param rate Phy rate to be configured.
*
* @return
* - ESP_OK: succeed
* - others: failed
*/
esp_err_t esp_wifi_config_espnow_rate(wifi_interface_t ifx, wifi_phy_rate_t rate);
/**
* @brief Set interval for station to wake up periodically at disconnected.
*

6
components/esp_wifi/include/esp_wifi_types.h
View File

@ -343,7 +343,7 @@ typedef struct {
unsigned fec_coding:1; /**< Flag is set for 11n packets which are LDPC */
unsigned sgi:1; /**< Short Guide Interval(SGI). 0: Long GI; 1: Short GI */
#if CONFIG_IDF_TARGET_ESP32
signed noise_floor:8; /**< noise floor of Radio Frequency Module(RF). unit: 0.25dBm*/
signed noise_floor:8; /**< noise floor of Radio Frequency Module(RF). unit: dBm*/
#elif CONFIG_IDF_TARGET_ESP32S2 || CONFIG_IDF_TARGET_ESP32S3 || CONFIG_IDF_TARGET_ESP32C3
unsigned :8; /**< reserved */
#endif
@ -356,14 +356,14 @@ typedef struct {
#if CONFIG_IDF_TARGET_ESP32S2
unsigned :32; /**< reserved */
#elif CONFIG_IDF_TARGET_ESP32S3 || CONFIG_IDF_TARGET_ESP32C3
signed noise_floor:8; /**< noise floor of Radio Frequency Module(RF). unit: 0.25dBm*/
signed noise_floor:8; /**< noise floor of Radio Frequency Module(RF). unit: dBm*/
unsigned :24; /**< reserved */
unsigned :32; /**< reserved */
#endif
unsigned :31; /**< reserved */
unsigned ant:1; /**< antenna number from which this packet is received. 0: WiFi antenna 0; 1: WiFi antenna 1 */
#if CONFIG_IDF_TARGET_ESP32S2
signed noise_floor:8; /**< noise floor of Radio Frequency Module(RF). unit: 0.25dBm*/
signed noise_floor:8; /**< noise floor of Radio Frequency Module(RF). unit: dBm*/
unsigned :24; /**< reserved */
#elif CONFIG_IDF_TARGET_ESP32S3 || CONFIG_IDF_TARGET_ESP32C3
unsigned :32; /**< reserved */

2
components/esp_wifi/lib

@ -1 +1 @@
Subproject commit ce03645819a4c6233270a45e53484703fabc320f
Subproject commit b28a4656cfeee7d444d06c0c459d1de59562706d

4
components/esp_wifi/src/wifi_netif.c
View File

@ -48,7 +48,9 @@ static esp_err_t wifi_ap_receive(void *buffer, uint16_t len, void *eb)
static void wifi_free(void *h, void* buffer)
{
esp_wifi_internal_free_rx_buffer(buffer);
if (buffer) {
esp_wifi_internal_free_rx_buffer(buffer);
}
}
static esp_err_t wifi_transmit(void *h, void *buffer, size_t len)

245
docs/en/api-guides/wifi.rst
View File

@ -5,8 +5,9 @@ Wi-Fi Driver
{IDF_TARGET_NAME} Wi-Fi Feature List
------------------------------------
- Support Station-only mode, AP-only mode, Station/AP-coexistence mode
- Support IEEE 802.11B, IEEE 802.11G, IEEE 802.11N and APIs to configure the protocol mode
- Support 4 virtual WiFi interfaces, which are STA, AP, Sniffer and reserved.
- Support station-only mode, AP-only mode, station/AP-coexistence mode
- Support IEEE 802.11b, IEEE 802.11g, IEEE 802.11n, and APIs to configure the protocol mode
- Support WPA/WPA2/WPA3/WPA2-Enterprise and WPS
- Support AMPDU, HT40, QoS and other key features
- Support Modem-sleep
@ -58,9 +59,9 @@ Whether the error is critical or not depends on the API and the application scen
**The primary principle to write a robust application with Wi-Fi API is to always check the error code and write the error-handling code.** Generally, the error-handling code can be used:
- for recoverable errors, in which case you can write a recoverable-error code. For example, when :cpp:func:`esp_wifi_start` returns ESP_ERR_NO_MEM, the recoverable-error code vTaskDelay can be called, in order to get a microseconds' delay for another try.
- for non-recoverable, yet non-critical, errors, in which case printing the error code is a good method for error handling.
- for non-recoverable, critical errors, in which case "assert" may be a good method for error handling. For example, if :cpp:func:`esp_wifi_set_mode` returns ESP_ERR_WIFI_NOT_INIT, it means that the Wi-Fi driver is not initialized by :cpp:func:`esp_wifi_init` successfully. You can detect this kind of error very quickly in the application development phase.
- For recoverable errors, in which case you can write a recoverable-error code. For example, when :cpp:func:`esp_wifi_start()` returns ESP_ERR_NO_MEM, the recoverable-error code vTaskDelay can be called in order to get a microseconds' delay for another try.
- For non-recoverable, yet non-critical errors, in which case printing the error code is a good method for error handling.
- For non-recoverable and also critical errors, in which case "assert" may be a good method for error handling. For example, if :cpp:func:`esp_wifi_set_mode()` returns ESP_ERR_WIFI_NOT_INIT, it means that the Wi-Fi driver is not initialized by :cpp:func:`esp_wifi_init()` successfully. You can detect this kind of error very quickly in the application development phase.
In esp_err.h, ESP_ERROR_CHECK checks the return values. It is a rather commonplace error-handling code and can be used
as the default error-handling code in the application development phase. However, we strongly recommend that API users write their own error-handling code.
@ -123,9 +124,9 @@ The {IDF_TARGET_NAME} Wi-Fi programming model is depicted as follows:
}
The Wi-Fi driver can be considered a black box that knows nothing about high-layer code, such as the TCP/IP stack, application task, event task, etc. The application task (code) generally calls :doc:`Wi-Fi driver APIs <../api-reference/network/esp_wifi>` to initialize Wi-Fi and handles Wi-Fi events when necessary. Wi-Fi driver receives API calls, handles them, and post events to the application.
The Wi-Fi driver can be considered a black box that knows nothing about high-layer code, such as the TCP/IP stack, application task, and event task. The application task (code) generally calls :doc:`Wi-Fi driver APIs <../api-reference/network/esp_wifi>` to initialize Wi-Fi and handles Wi-Fi events when necessary. Wi-Fi driver receives API calls, handles them, and posts events to the application.
Wi-Fi event handling is based on the :doc:`esp_event library <../api-reference/system/esp_event>`. Events are sent by the Wi-Fi driver to the :ref:`default event loop <esp-event-default-loops>`. Application may handle these events in callbacks registered using :cpp:func:`esp_event_handler_register`. Wi-Fi events are also handled by :doc:`esp_netif component <../api-reference/network/esp_netif>` to provide a set of default behaviors. For example, when Wi-Fi station connects to an AP, esp_netif will automatically start the DHCP client (by default).
Wi-Fi event handling is based on the :doc:`esp_event library <../api-reference/system/esp_event>`. Events are sent by the Wi-Fi driver to the :ref:`default event loop <esp-event-default-loops>`. Application may handle these events in callbacks registered using :cpp:func:`esp_event_handler_register()`. Wi-Fi events are also handled by :doc:`esp_netif component <../api-reference/network/esp_netif>` to provide a set of default behaviors. For example, when Wi-Fi station connects to an AP, esp_netif will automatically start the DHCP client by default.
{IDF_TARGET_NAME} Wi-Fi Event Description
-----------------------------------------
@ -204,11 +205,11 @@ IP_EVENT_GOT_IP6
++++++++++++++++++++++++++++++++++++
This event arises when the IPV6 SLAAC support auto-configures an address for the {IDF_TARGET_NAME}, or when this address changes. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets).
IP_STA_LOST_IP
IP_EVENT_STA_LOST_IP
++++++++++++++++++++++++++++++++++++
This event arises when the IPV4 address become invalid.
IP_STA_LOST_IP doesn't arise immediately after the Wi-Fi disconnects, instead it starts an IPV4 address lost timer, if the IPV4 address is got before ip lost timer expires, IP_EVENT_STA_LOST_IP doesn't happen. Otherwise, the event arises when IPV4 address lost timer expires.
IP_EVENT_STA_LOST_IP doesn't arise immediately after the Wi-Fi disconnects, instead it starts an IPV4 address lost timer, if the IPV4 address is got before ip lost timer expires, IP_EVENT_STA_LOST_IP doesn't happen. Otherwise, the event arises when IPV4 address lost timer expires.
Generally the application don't need to care about this event, it is just a debug event to let the application know that the IPV4 address is lost.
@ -228,8 +229,8 @@ WIFI_EVENT_AP_STADISCONNECTED
++++++++++++++++++++++++++++++++++++
This event can happen in the following scenarios:
- The application calls :cpp:func:`esp_wifi_disconnect()`, or esp_wifi_deauth_sta(), to manually disconnect the station.
- The Wi-Fi driver kicks off the station, e.g. because the AP has not received any packets in the past five minutes, etc. The time can be modified by :cpp:func:`esp_wifi_set_inactive_time`.
- The application calls :cpp:func:`esp_wifi_disconnect()`, or :cpp:func:`esp_wifi_deauth_sta()`, to manually disconnect the station.
- The Wi-Fi driver kicks off the station, e.g., because the AP has not received any packets in the past five minutes. The time can be modified by :cpp:func:`esp_wifi_set_inactive_time()`.
- The station kicks off the AP.
When this event happens, the event task will do nothing, but the application event callback needs to do something, e.g., close the socket which is related to this station, etc.
@ -302,7 +303,7 @@ Below is a "big scenario" which describes some small scenarios in Station mode:
++++++++++++++++++++++++++++++
- s1.1: The main task calls :cpp:func:`esp_netif_init()` to create an LwIP core task and initialize LwIP-related work.
- s1.2: The main task calls :cpp:func:`esp_event_loop_create` to create a system Event task and initialize an application event's callback function. In the scenario above, the application event's callback function does nothing but relaying the event to the application task.
- s1.2: The main task calls :cpp:func:`esp_event_loop_create()` to create a system Event task and initialize an application event's callback function. In the scenario above, the application event's callback function does nothing but relaying the event to the application task.
- s1.3: The main task calls :cpp:func:`esp_netif_create_default_wifi_ap()` or :cpp:func:`esp_netif_create_default_wifi_sta()` to create default network interface instance binding station or AP with TCP/IP stack.
@ -316,7 +317,7 @@ Step 1.1 ~ 1.5 is a recommended sequence that initializes a Wi-Fi-/LwIP-based ap
+++++++++++++++++++++++++++++++
Once the Wi-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode is Station, so you may need to call :cpp:func:`esp_wifi_set_mode` (WIFI_MODE_STA) to configure the Wi-Fi mode as Station. You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, country code, bandwidth, etc. Refer to `{IDF_TARGET_NAME} Wi-Fi Configuration`_.
Generally, we configure the Wi-Fi driver before setting up the Wi-Fi connection, but this is **NOT** mandatory, which means that you can configure the Wi-Fi connection anytime, provided that the Wi-Fi driver is initialized successfully. However, if the configuration does not need to change after the Wi-Fi connection is set up, you should configure the Wi-Fi driver at this stage, because the configuration APIs (such as :cpp:func:`esp_wifi_set_protocol`) will cause the Wi-Fi to reconnect, which may not be desirable.
Generally, the Wi-Fi driver should be configured before the Wi-Fi connection is set up. But this is **NOT** mandatory, which means that you can configure the Wi-Fi connection anytime, provided that the Wi-Fi driver is initialized successfully. However, if the configuration does not need to change after the Wi-Fi connection is set up, you should configure the Wi-Fi driver at this stage, because the configuration APIs (such as :cpp:func:`esp_wifi_set_protocol()`) will cause the Wi-Fi to reconnect, which may not be desirable.
If the Wi-Fi NVS flash is enabled by menuconfig, all Wi-Fi configuration in this phase, or later phases, will be stored into flash. When the board powers on/reboots, you do not need to configure the Wi-Fi driver from scratch. You only need to call esp_wifi_get_xxx APIs to fetch the configuration stored in flash previously. You can also configure the Wi-Fi driver if the previous configuration is not what you want.
@ -468,7 +469,7 @@ The scan modes in above table can be combined arbitrarily, so we totally have 8
Scan Configuration
+++++++++++++++++++++++++++++++++++++++
The scan type and other per-scan attributes are configured by :cpp:func:`esp_wifi_scan_start`. The table below provides a detailed description of wifi_scan_config_t.
The scan type and other per-scan attributes are configured by :cpp:func:`esp_wifi_scan_start()`. The table below provides a detailed description of wifi_scan_config_t.
+------------------+--------------------------------------------------------------+
| Field | Description |
@ -516,7 +517,7 @@ The scan type and other per-scan attributes are configured by :cpp:func:`esp_wif
| | |
+------------------+--------------------------------------------------------------+
There are also some global scan attributes which are configured by API :cpp:func:`esp_wifi_set_config`, refer to `Station Basic Configuration`_
There are also some global scan attributes which are configured by API :cpp:func:`esp_wifi_set_config()`, refer to `Station Basic Configuration`_
Scan All APs on All Channels (Foreground)
+++++++++++++++++++++++++++++++++++++++++++++
@ -1202,37 +1203,31 @@ API esp_wifi_set_config() can be used to configure the AP. The table below descr
Wi-Fi Protocol Mode
+++++++++++++++++++++++++
Currently, the IDF supports the following protocol modes:
Currently, the ESP-IDF supports the following protocol modes:
.. list-table::
:header-rows: 1
:widths: 15 55
* - Protocol Mode
- Description
* - 802.11b
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B) to set the station/AP to 802.11b-only mode.
* - 802.11bg
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) to set the station/AP to 802.11bg mode.
* - 802.11g
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) and esp_wifi_config_11b_rate(ifx, true) to set the station/AP to 802.11g mode.
* - 802.11bgn
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) to set the station/ AP to BGN mode.
* - 802.11gn
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) and esp_wifi_config_11b_rate(ifx, true) to set the station/AP to 802.11gn mode.
* - 802.11 BGNLR
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR) to set the station/AP to BGN and the LR mode.
* - 802.11 LR
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_LR) to set the station/AP only to the LR mode.
**This mode is an Espressif-patented mode which can achieve a one-kilometer line of sight range. Please make sure both the station and the AP are connected to an ESP device.**
+--------------------+------------------------------------------------------------+
| Protocol Mode | Description |
+====================+============================================================+
| 802.11 B | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B) to set |
| | the station/AP to 802.11B-only mode. |
| | |
+--------------------+------------------------------------------------------------+
| 802.11 BG | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_ |
| | PROTOCOL_11G) to set the station/AP to 802.11BG mode. |
| | |
+--------------------+------------------------------------------------------------+
| 802.11 BGN | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| |
| | WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) to set the station/ |
| | AP to BGN mode. |
| | |
+--------------------+------------------------------------------------------------+
| 802.11 BGNLR | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| |
| | WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR) |
| | to set the station/AP to BGN and the |
| | Espressif-specific mode. |
+--------------------+------------------------------------------------------------+
| 802.11 LR | Call esp_wifi_set_protocol (ifx, WIFI_PROTOCOL_LR) to set |
| | the station/AP only to the Espressif-specific mode. |
| | |
| | **This mode is an Espressif-patented mode which can achieve|
| | a one-kilometer line of sight range. Please, make sure both|
| | the station and the AP are connected to an |
| | ESP device** |
+--------------------+------------------------------------------------------------+
Long Range (LR)
+++++++++++++++++++++++++
@ -1292,7 +1287,7 @@ The reception sensitivity of LR has about 4 dB gain than the traditional 802.11B
LR Throughput
*************************
The LR rate has very limited throughput because the raw PHY data rate LR is 1/2 Mbits and 1/4 Mbits.
The LR rate has very limited throughput, because the raw PHY data rates is 1/2 Mbps and 1/4 Mbps.
When to Use LR
*************************
@ -1477,9 +1472,9 @@ Currently, {IDF_TARGET_NAME} Wi-Fi supports the Modem-sleep mode which refers to
Modem-sleep mode includes minimum and maximum power save modes. In minimum power save mode, station wakes up every DTIM to receive beacon. Broadcast data will not be lost because it is transmitted after DTIM. However, it can not save much more power if DTIM is short for DTIM is determined by AP.
In maximum power save mode, station wakes up every listen interval to receive beacon. This listen interval can be set longer than the AP DTIM period. Broadcast data may be lost because station may be in sleep state at DTIM time. If listen interval is longer, more power is saved but broadcast data is more easy to lose. Listen interval can be configured by calling API :cpp:func:`esp_wifi_set_config` before connecting to AP.
In maximum power-saving mode, station wakes up in every listen interval to receive beacon. This listen interval can be set to be longer than the AP DTIM period. Broadcast data may be lost because station may be in sleep state at DTIM time. If listen interval is longer, more power is saved, but broadcast data is more easy to lose. Listen interval can be configured by calling API :cpp:func:`esp_wifi_set_config()` before connecting to AP.
Call ``esp_wifi_set_ps(WIFI_PS_MIN_MODEM)`` to enable Modem-sleep minimum power save mode or ``esp_wifi_set_ps(WIFI_PS_MAX_MODEM)`` to enable Modem-sleep maximum power save mode after calling :cpp:func:`esp_wifi_init`. When station connects to AP, Modem-sleep will start. When station disconnects from AP, Modem-sleep will stop.
Call ``esp_wifi_set_ps(WIFI_PS_MIN_MODEM)`` to enable Modem-sleep minimum power-saving mode or ``esp_wifi_set_ps(WIFI_PS_MAX_MODEM)`` to enable Modem-sleep maximum power-saving mode after calling :cpp:func:`esp_wifi_init()`. When station connects to AP, Modem-sleep will start. When station disconnects from AP, Modem-sleep will stop.
Call ``esp_wifi_set_ps(WIFI_PS_NONE)`` to disable modem sleep entirely. This has much higher power consumption, but provides minimum latency for receiving Wi-Fi data in real time. When modem sleep is enabled, received Wi-Fi data can be delayed for as long as the DTIM period (minimum power save mode) or the listen interval (maximum power save mode). Disabling modem sleep entirely is not possible for Wi-Fi and Bluetooth coexist mode.
@ -1607,113 +1602,68 @@ The table below shows the best throughput results we got in Espressif's lab and
Wi-Fi 80211 Packet Send
---------------------------
The :cpp:func:`esp_wifi_80211_tx` API can be used to:
The :cpp:func:`esp_wifi_80211_tx()` API can be used to:
- Send the beacon, probe request, probe response, action frame.
- Send the non-QoS data frame.
It cannot be used for sending encrypted or QoS frames.
Preconditions of Using :cpp:func:`esp_wifi_80211_tx`
Preconditions of Using :cpp:func:`esp_wifi_80211_tx()`
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- The Wi-Fi mode is Station, or AP, or Station+AP.
- Either esp_wifi_set_promiscuous(true), or :cpp:func:`esp_wifi_start()`, or both of these APIs return ESP_OK. This is because we need to make sure that Wi-Fi hardware is initialized before :cpp:func:`esp_wifi_80211_tx` is called. In {IDF_TARGET_NAME}, both esp_wifi_set_promiscuous(true) and :cpp:func:`esp_wifi_start()` can trigger the initialization of Wi-Fi hardware.
- The parameters of :cpp:func:`esp_wifi_80211_tx` are hereby correctly provided.
- The Wi-Fi mode is station, or AP, or station/AP.
- Either esp_wifi_set_promiscuous(true), or :cpp:func:`esp_wifi_start()`, or both of these APIs return ESP_OK. This is because Wi-Fi hardware must be initialized before :cpp:func:`esp_wifi_80211_tx()` is called. In {IDF_TARGET_NAME}, both esp_wifi_set_promiscuous(true) and :cpp:func:`esp_wifi_start()` can trigger the initialization of Wi-Fi hardware.
- The parameters of :cpp:func:`esp_wifi_80211_tx()` are hereby correctly provided.
Data rate
+++++++++++++++++++++++++++++++++++++++++++++++
- If there is no Wi-Fi connection, the data rate is 1 Mbps.
- If there is Wi-Fi connection and the packet is from station to AP or from AP to station, the data rate is same as the Wi-Fi connection. Otherwise the data rate is 1 Mbps.
- The default data rate is 1 Mbps.
- Can set any rate through :cpp:func:`esp_wifi_config_80211_tx_rate()` API.
- Can set any bandwidth through :cpp:func:`esp_wifi_set_bandwidth()` API.
Side-Effects to Avoid in Different Scenarios
+++++++++++++++++++++++++++++++++++++++++++++++++++++
Theoretically, if we do not consider the side-effects the API imposes on the Wi-Fi driver or other stations/APs, we can send a raw 802.11 packet over the air, with any destination MAC, any source MAC, any BSSID, or any other type of packet. However,robust/useful applications should avoid such side-effects. The table below provides some tips/recommendations on how to avoid the side-effects of :cpp:func:`esp_wifi_80211_tx` in different scenarios.
Theoretically, if the side-effects the API imposes on the Wi-Fi driver or other stations/APs are not considered, a raw 802.11 packet can be sent over the air with any destination MAC, any source MAC, any BSSID, or any other types of packet. However, robust or useful applications should avoid such side-effects. The table below provides some tips and recommendations on how to avoid the side-effects of :cpp:func:`esp_wifi_80211_tx()` in different scenarios.
.. list-table::
:header-rows: 1
:widths: 10 50
* - Scenario
- Description
* - No Wi-Fi connection
- In this scenario, no Wi-Fi connection is set up, so there are no side-effects on the Wi-Fi driver. If en_sys_seq==true, the Wi-Fi driver is responsible for the sequence control. If en_sys_seq==false, the application needs to ensure that the buffer has the correct sequence.
Theoretically, the MAC address can be any address. However, this may impact other stations/APs with the same MAC/BSSID.
Side-effect example#1 The application calls :cpp:func:`esp_wifi_80211_tx()` to send a beacon with BSSID == mac_x in AP mode, but the mac_x is not the MAC of the AP interface. Moreover, there is another AP, e.g., “other-AP”, whose BSSID is mac_x. If this happens, an “unexpected behavior” may occur, because the stations which connect to the “other-AP” cannot figure out whether the beacon is from the “other-AP” or the :cpp:func:`esp_wifi_80211_tx()`.
To avoid the above-mentioned side-effects, it is recommended that:
- If esp_wifi_80211_tx is called in station mode, the first MAC should be a multicast MAC or the exact target-device’s MAC, while the second MAC should be that of the station interface.
- If esp_wifi_80211_tx is called in AP mode, the first MAC should be a multicast MAC or the exact target-device’s MAC, while the second MAC should be that of the AP interface.
The recommendations above are only for avoiding side-effects and can be ignored when there are good reasons.
* - Have Wi-Fi connection
- When the Wi-Fi connection is already set up, and the sequence is controlled by the application, the latter may impact the sequence control of the Wi-Fi connection as a whole. So, the en_sys_seq need to be true, otherwise ESP_ERR_WIFI_ARG is returned.
The MAC-address recommendations in the “No Wi-Fi connection” scenario also apply to this scenario.
If the Wi-Fi mode is station mode, the MAC address1 is the MAC of AP to which the station is connected, and the MAC address2 is the MAC of station interface, it is said that the packet is sent from the station to AP. Otherwise, if the Wi-Fi is in AP mode, the MAC address1 is the MAC of the station that connects to this AP, and the MAC address2 is the MAC of AP interface, it is said that the packet is sent from the AP to station. To avoid conflicting with Wi-Fi connections, the following checks are applied:
- If the packet type is data and is sent from the station to AP, the ToDS bit in IEEE 80211 frame control should be 1 and the FromDS bit should be 0. Otherwise, the packet will be discarded by Wi-Fi driver.
- If the packet type is data and is sent from the AP to station, the ToDS bit in IEEE 80211 frame control should be 0 and the FromDS bit should be 1. Otherwise, the packet will be discarded by Wi-Fi driver.
- If the packet is sent from station to AP or from AP to station, the Power Management, More Data, and Re-Transmission bits should be 0. Otherwise, the packet will be discarded by Wi-Fi driver.
ESP_ERR_WIFI_ARG is returned if any check fails.
+-----------------------------+---------------------------------------------------+
| Scenario | Description |
+=============================+===================================================+
| No WiFi connection | In this scenario, no Wi-Fi connection is set up, |
| | so there are no side-effects on the Wi-Fi driver. |
| | If en_sys_seq==true, the Wi-Fi driver is |
| | responsible for the sequence control. If |
| | en_sys_seq==false, the application needs to ensure|
| | that the buffer has the correct sequence. |
| | |
| | Theoretically, the MAC address can be any address.|
| | However, this may impact other stations/APs |
| | with the same MAC/BSSID. |
| | |
| | Side-effect example#1 |
| | The application calls esp_wifi_80211_tx to send |
| | a beacon with BSSID == mac_x in AP mode, but |
| | the mac_x is not the MAC of the AP interface. |
| | Moreover, there is another AP, say |
| | "other-AP", whose bssid is mac_x. If this |
| | happens, an "unexpected behavior" may occur, |
| | because the stations which connect to the |
| | "other-AP" cannot figure out whether the beacon is|
| | from the "other-AP" or the esp_wifi_80211_tx. |
| | |
| | To avoid the above-mentioned side-effects, we |
| | recommend that: |
| | |
| | - If esp_wifi_80211_tx is called in Station mode,|
| | the first MAC should be a multicast MAC or the |
| | exact target-device's MAC, while the second MAC|
| | should be that of the station interface. |
| | - If esp_wifi_80211_tx is called in AP mode, |
| | the first MAC should be a multicast MAC or the |
| | exact target-device's MAC, while the second MAC|
| | should be that of the AP interface. |
| | |
| | The recommendations above are only for avoiding |
| | side-effects and can be ignored when there are |
| | good reasons for doing this. |
+-----------------------------+---------------------------------------------------+
| Have WiFi connection | When the Wi-Fi connection is already set up, and |
| | the sequence is controlled by the application, the|
| | latter may impact the sequence control of the |
| | Wi-Fi connection, as a whole. So, the |
| | en_sys_seq need to be true, otherwise |
| | ESP_ERR_WIFI_ARG is returned. |
| | |
| | The MAC-address recommendations in the |
| | "No WiFi connection" scenario also apply to this |
| | scenario. |
| | |
| | If the WiFi mode is station mode and the MAC |
| | address1 is the MAC of AP to which the station is |
| | connected, the MAC address2 is the MAC of station |
| | interface, we say the packets is from the station |
| | to AP. On the other hand, if the WiFi mode is |
| | AP mode and the MAC address1 is the MAC of |
| | the station who connects to this AP, the MAC |
| | address2 is the MAC of AP interface, we say |
| | the packet is from the AP to station. |
| | To avoid conflicting with WiFi connections, the |
| | following checks are applied: |
| | |
| | - If the packet type is data and is from the |
| | station to AP, the ToDS bit in IEEE 80211 |
| | frame control should be 1, the FromDS bit |
| | should be 0, otherwise the packet will be |
| | discarded by WiFi driver. |
| | - If the packet type is data and is from the |
| | AP to station, the ToDS bit in IEEE 80211 |
| | frame control should be 0, the FromDS bit |
| | should be 1, otherwise the packet will be |
| | discarded by WiFi driver. |
| | - If the packet is from station to AP or |
| | from AP to station, the Power Management, |
| | More Data, Re-Transmission bits should be 0, |
| | otherwise the packet will be discarded by WiFi |
| | driver. |
| | |
| | ESP_ERR_WIFI_ARG is returned if any check fails. |
+-----------------------------+---------------------------------------------------+
Wi-Fi Sniffer Mode
---------------------------
@ -1754,7 +1704,9 @@ The Wi-Fi multiple antennas selecting can be depicted as following picture::
Up to four GPIOs are connected to the four active high antenna_select pins. {IDF_TARGET_NAME} can select the antenna by control the GPIO[0:3]. The API :cpp:func:`esp_wifi_set_ant_gpio()` is used to configure which GPIOs are connected to antenna_selects. If GPIO[x] is connected to antenna_select[x], then gpio_config->gpio_cfg[x].gpio_select should be set to 1 and gpio_config->gpio_cfg[x].gpio_num should be provided.
Although up to sixteen anteenas are supported, only one or two antennas can be simultaneously enabled for RX/TX. The API :cpp:func:`esp_wifi_set_ant()` is used to configure which antennas are enabled.
For the specific implementation of the antenna switch, there may be illegal values in `antenna_select[0:3]`. It means that {IDF_TARGET_NAME} may support less than sixteen antennas through the switch. For example, ESP32-WROOM-DA which uses RTC6603SP as the antenna switch, supports two antennas. Two GPIOs are connected to two active high antenna selection inputs. The value '0b01' means the antenna 0 is selected, the value '0b10' means the antenna 1 is selected. Values '0b00' and '0b11' are illegal.
Although up to sixteen antennas are supported, only one or two antennas can be simultaneously enabled for RX/TX. The API :cpp:func:`esp_wifi_set_ant()` is used to configure which antennas are enabled.
The enabled antennas selecting algorithm is also configured by :cpp:func:`esp_wifi_set_ant()`. The RX/TX antenna mode can be WIFI_ANT_MODE_ANT0, WIFI_ANT_MODE_ANT1 or WIFI_ANT_MODE_AUTO. If the antenna mode is WIFI_ANT_MODE_ANT0, the enabled antenna 0 is selected for RX/TX data. If the antenna mode is WIFI_ANT_MODE_ANT1, the enabled antenna 1 is selected for RX/TX data. Otherwise, Wi-Fi automatically selects the antenna that has better signal from the enabled antennas.
@ -1830,24 +1782,25 @@ All of the information in the table can be found in the structure wifi_csi_info_
.. note::
- For STBC packet, CSI is provided for every space-time stream without CSD (cyclic shift delay). As each cyclic shift on the additional chains shall be -200 ns, only the CSD angle of first space-time stream is recorded in sub-carrier 0 of HT-LTF and STBC-HT-LTF for there is no channel frequency response in sub-carrier 0. CSD[10:0] is 11 bits, ranging from -pi to pi.
- If LLTF, HT-LTF or STBC-HT-LTF is not enabled by calling API :cpp:func:`esp_wifi_set_csi_config`, the total bytes of CSI data will be fewer than that in the table. For example, if LLTF and HT-LTF is not enabled and STBC-HT-LTF is enabled, when a packet is received with the condition above/HT/40MHz/STBC, the total bytes of CSI data is 244 ((61 + 60) * 2 + 2 = 244, the result is aligned to four bytes and the last two bytes is invalid).
- If LLTF, HT-LTF, or STBC-HT-LTF is not enabled by calling API :cpp:func:`esp_wifi_set_csi_config()`, the total bytes of CSI data will be fewer than that in the table. For example, if LLTF and HT-LTF is not enabled and STBC-HT-LTF is enabled, when a packet is received with the condition above/HT/40MHz/STBC, the total bytes of CSI data is 244 ((61 + 60) * 2 + 2 = 244. The result is aligned to four bytes, and the last two bytes are invalid).
Wi-Fi Channel State Information Configure
-------------------------------------------
To use Wi-Fi CSI, the following steps need to be done.
- Select Wi-Fi CSI in menuconfig. It is "Menuconfig --> Components config --> Wi-Fi --> WiFi CSI(Channel State Information)".
- Set CSI receiving callback function by calling API :cpp:func:`esp_wifi_set_csi_rx_cb`.
- Configure CSI by calling API :cpp:func:`esp_wifi_set_csi_config`.
- Enable CSI by calling API :cpp:func:`esp_wifi_set_csi`.
- Select Wi-Fi CSI in menuconfig. Go to ``Menuconfig`` > ``Components config`` > ``Wi-Fi`` > ``Wi-Fi CSI (Channel State Information)``.
- Set CSI receiving callback function by calling API :cpp:func:`esp_wifi_set_csi_rx_cb()`.
- Configure CSI by calling API :cpp:func:`esp_wifi_set_csi_config()`.
- Enable CSI by calling API :cpp:func:`esp_wifi_set_csi()`.
The CSI receiving callback function runs from Wi-Fi task. So, do not do lengthy operations in the callback function. Instead, post necessary data to a queue and handle it from a lower priority task. Because station does not receive any packet when it is disconnected and only receives packets from AP when it is connected, it is suggested to enable sniffer mode to receive more CSI data by calling :cpp:func:`esp_wifi_set_promiscuous`.
The CSI receiving callback function runs from Wi-Fi task. So, do not do lengthy operations in the callback function. Instead, post necessary data to a queue and handle it from a lower priority task. Because station does not receive any packet when it is disconnected and only receives packets from AP when it is connected, it is suggested to enable sniffer mode to receive more CSI data by calling :cpp:func:`esp_wifi_set_promiscuous()`.
Wi-Fi HT20/40
-------------------------
{IDF_TARGET_NAME} supports Wi-Fi bandwidth HT20 or HT40, it doesn't support HT20/40 coexist. :cpp:func:`esp_wifi_set_bandwidth` can be used to change the default bandwidth of station or AP. The default bandwidth for {IDF_TARGET_NAME} station and AP is HT40.
{IDF_TARGET_NAME} supports Wi-Fi bandwidth HT20 or HT40 and does not support HT20/40 coexist. :cpp:func:`esp_wifi_set_bandwidth()` can be used to change the default bandwidth of station or AP. The default bandwidth for {IDF_TARGET_NAME} station and AP is HT40.
In station mode, the actual bandwidth is firstly negotiated during the Wi-Fi connection. It is HT40 only if both the station and the connected AP support HT40, otherwise it's HT20. If the bandwidth of connected AP is changes, the actual bandwidth is negotiated again without Wi-Fi disconnecting.

37
docs/en/api-reference/network/esp_now.rst
View File

@ -50,7 +50,7 @@ Security
--------
ESP-NOW uses the CCMP method, which is described in IEEE Std. 802.11-2012, to protect the vendor-specific action frame. The Wi-Fi device maintains a Primary Master Key (PMK) and several Local Master Keys (LMK). The lengths of both PMK and LMk are 16 bytes.
* PMK is used to encrypt LMK with the AES-128 algorithm. Call ``esp_now_set_pmk()`` to set PMK. If PMK is not set, a default PMK will be used.
* PMK is used to encrypt LMK with the AES-128 algorithm. Call :cpp:func:`esp_now_set_pmk()` to set PMK. If PMK is not set, a default PMK will be used.
* LMK of the paired device is used to encrypt the vendor-specific action frame with the CCMP method. The maximum number of different LMKs is six. If the LMK of the paired device is not set, the vendor-specific action frame will not be encrypted.
Encrypting multicast vendor-specific action frame is not supported.
@ -58,29 +58,50 @@ Encrypting multicast vendor-specific action frame is not supported.
Initialization and De-initialization
------------------------------------
Call ``esp_now_init()`` to initialize ESP-NOW and ``esp_now_deinit()`` to de-initialize ESP-NOW. ESP-NOW data must be transmitted after Wi-Fi is started, so it is recommended to start Wi-Fi before initializing ESP-NOW and stop Wi-Fi after de-initializing ESP-NOW.
When ``esp_now_deinit()`` is called, all of the information of paired devices will be deleted.
Call :cpp:func:`esp_now_init()` to initialize ESP-NOW and :cpp:func:`esp_now_deinit()` to de-initialize ESP-NOW. ESP-NOW data must be transmitted after Wi-Fi is started, so it is recommended to start Wi-Fi before initializing ESP-NOW and stop Wi-Fi after de-initializing ESP-NOW.
When :cpp:func:`esp_now_deinit()` is called, all of the information of paired devices will be deleted.
Add Paired Device
-----------------
Call ``esp_now_add_peer()`` to add the device to the paired device list before you send data to this device. The maximum number of paired devices is twenty. If security is enabled, the LMK must be set. You can send ESP-NOW data via both the Station and the SoftAP interface.
Make sure that the interface is enabled before sending ESP-NOW data. A device with a broadcast MAC address must be added before sending broadcast data. The range of the channel of paired devices is from 0 to 14. If the channel is set to 0, data will be sent on the current channel. Otherwise, the channel must be set as the channel that the local device is on.
Call :cpp:func:`esp_now_add_peer()` to add the device to the paired device list before you send data to this device. If security is enabled, the LMK must be set. You can send ESP-NOW data via both the Station and the SoftAP interface. Make sure that the interface is enabled before sending ESP-NOW data.
.. only:: esp32c3
The maximum number of paired devices is 20, and the paired encryption devices are no more than 10, the default is 6.
.. only:: esp32 or esp32s2 or esp32s3
The maximum number of paired devices is 20, and the paired encryption devices are no more than 16, the default is 6.
A device with a broadcast MAC address must be added before sending broadcast data. The range of the channel of paired devices is from 0 to 14. If the channel is set to 0, data will be sent on the current channel. Otherwise, the channel must be set as the channel that the local device is on.
Send ESP-NOW Data
-----------------
Call ``esp_now_send()`` to send ESP-NOW data and ``esp_now_register_send_cb`` to register sending callback function. It will return `ESP_NOW_SEND_SUCCESS` in sending callback function if the data is received successfully on the MAC layer. Otherwise, it will return `ESP_NOW_SEND_FAIL`. Several reasons can lead to ESP-NOW fails to send data. For example, the destination device doesn't exist; the channels of the devices are not the same; the action frame is lost when transmitting on the air, etc. It is not guaranteed that application layer can receive the data. If necessary, send back ack data when receiving ESP-NOW data. If receiving ack data timeouts, retransmit the ESP-NOW data. A sequence number can also be assigned to ESP-NOW data to drop the duplicate data.
Call :cpp:func:`esp_now_send()` to send ESP-NOW data and :cpp:func:`esp_now_register_send_cb()` to register sending callback function. It will return `ESP_NOW_SEND_SUCCESS` in sending callback function if the data is received successfully on the MAC layer. Otherwise, it will return `ESP_NOW_SEND_FAIL`. Several reasons can lead to ESP-NOW fails to send data. For example, the destination device doesn't exist; the channels of the devices are not the same; the action frame is lost when transmitting on the air, etc. It is not guaranteed that application layer can receive the data. If necessary, send back ack data when receiving ESP-NOW data. If receiving ack data timeouts, retransmit the ESP-NOW data. A sequence number can also be assigned to ESP-NOW data to drop the duplicate data.
If there is a lot of ESP-NOW data to send, call ``esp_now_send()`` to send less than or equal to 250 bytes of data once a time.
If there is a lot of ESP-NOW data to send, call :cpp:func:`esp_now_send()` to send less than or equal to 250 bytes of data once a time.
Note that too short interval between sending two ESP-NOW data may lead to disorder of sending callback function. So, it is recommended that sending the next ESP-NOW data after the sending callback function of the previous sending has returned. The sending callback function runs from a high-priority Wi-Fi task. So, do not do lengthy operations in the callback function. Instead, post the necessary data to a queue and handle it from a lower priority task.
Receiving ESP-NOW Data
----------------------
Call ``esp_now_register_recv_cb`` to register receiving callback function. Call the receiving callback function when receiving ESP-NOW. The receiving callback function also runs from the Wi-Fi task. So, do not do lengthy operations in the callback function.
Call :cpp:func:`esp_now_register_recv_cb()` to register receiving callback function. Call the receiving callback function when receiving ESP-NOW. The receiving callback function also runs from the Wi-Fi task. So, do not do lengthy operations in the callback function.
Instead, post the necessary data to a queue and handle it from a lower priority task.
Config ESP-NOW Rate
-------------------
Call :cpp:func:`esp_wifi_config_espnow_rate()` to config ESPNOW rate of specified interface. Make sure that the interface is enabled before config rate. This API should be called after :cpp:func:`esp_wifi_start()`.
Application Examples
--------------------
* Example of sending and receiving ESP-NOW data between two devices: :example:`wifi/espnow`.
* For more application examples of how to use ESP-NOW, please visit `ESP-NOW <https://github.com/espressif/esp-now>`_ repository.
API Reference
-------------

115
docs/zh_CN/api-guides/wifi.rst
View File

@ -4,6 +4,7 @@
{IDF_TARGET_NAME} Wi-Fi 功能列表
------------------------------------
- 支持 4 个虚拟接口，即STA、AP、Sniffer 和 reserved。
- 支持仅 station 模式、仅 AP 模式、station/AP 共存模式
- 支持使用 IEEE 802.11B、IEEE 802.11G、IEEE 802.11N 和 API 配置协议模式
- 支持 WPA/WPA2/WPA2-企业版和 WPS
@ -60,9 +61,9 @@ Wi-Fi 初始化
**要使用 Wi-Fi API 编写一个强健的应用程序，根本原则便是要时刻检查错误代码并编写相应的错误处理代码。** 一般来说，错误处理代码可用于解决：
- 可恢复错误，您可以编写一个可恢复错误处理代码解决该类错误。例如，当 :cpp:func:`esp_wifi_start` 返回 ESP_ERR_NO_MEM 时，调用可恢复错误处理代码 vTaskDelay 可以获取几微秒的重试时间。
- 可恢复错误，您可以编写一个可恢复错误处理代码解决该类错误。例如，当 :cpp:func:`esp_wifi_start()` 返回 ESP_ERR_NO_MEM 时，调用可恢复错误处理代码 vTaskDelay 可以获取几微秒的重试时间。
- 不可恢复非关键性错误，打印错误代码可以帮助您更好地处理该类错误。
- 不可恢复关键性错误，可使用 "assert" 语句处理该类错误。例如，如果 :cpp:func:`esp_wifi_set_mode` 返回 ESP_ERR_WIFI_NOT_INIT，该值意为 :cpp:func:`esp_wifi_init` 未成功初始化 Wi-Fi 驱动程序。您可以在应用程序开发阶段非常快速地检测到此类错误。
- 不可恢复关键性错误，可使用 "assert" 语句处理该类错误。例如，如果 :cpp:func:`esp_wifi_set_mode()` 返回 ESP_ERR_WIFI_NOT_INIT，该值意为 :cpp:func:`esp_wifi_init()` 未成功初始化 Wi-Fi 驱动程序。您可以在应用程序开发阶段非常快速地检测到此类错误。
在 esp_err.h 中，ESP_ERROR_CHECK 负责检查返回值。这是一个较为常见的错误处理代码，可在应用程序开发阶段作为默认的错误处理代码。但是，我们强烈建议 API 的使用者自己编写错误处理代码。
@ -126,7 +127,7 @@ Wi-Fi 初始化
Wi-Fi 驱动程序可以看作是一个无法感知上层代码（如 TCP/IP 堆栈、应用程序任务、事件任务等）的黑匣子。通常，应用程序任务（代码）负责调用 :doc:`Wi-Fi 驱动程序 APIs <../api-reference/network/esp_wifi>` 来初始化 Wi-Fi，并在必要时处理 Wi-Fi 事件。然后，Wi-Fi 驱动程序接收并处理 API 数据，并在应用程序中插入事件。
Wi-Fi 事件处理是在 :doc:`esp_event 库 <../api-reference/system/esp_event>` 的基础上进行的。Wi-Fi 驱动程序将事件发送至 :ref:`默认事件循环 <esp-event-default-loops>`，应用程序便可以使用 :cpp:func:`esp_event_handler_register` 中的回调函数处理这些事件。除此之外，:doc:`esp_netif 组件 <../api-reference/network/esp_netif>` 也负责处理 Wi-Fi 事件，并产生一系列默认行为。例如，当 Wi-Fi station 连接至一个 AP 时，esp_netif 将自动开启 DHCP 客户端服务（系统默认）。
Wi-Fi 事件处理是在 :doc:`esp_event 库 <../api-reference/system/esp_event>` 的基础上进行的。Wi-Fi 驱动程序将事件发送至 :ref:`默认事件循环 <esp-event-default-loops>`，应用程序便可以使用 :cpp:func:`esp_event_handler_register()` 中的回调函数处理这些事件。除此之外，:doc:`esp_netif 组件 <../api-reference/network/esp_netif>` 也负责处理 Wi-Fi 事件，并产生一系列默认行为。例如，当 Wi-Fi station 连接至一个 AP 时，esp_netif 将自动开启 DHCP 客户端服务（系统默认）。
{IDF_TARGET_NAME} Wi-Fi 事件描述
-----------------------------------------
@ -205,7 +206,7 @@ IP_EVENT_GOT_IP6
++++++++++++++++++++++++++++++++++++
当 IPV6 SLAAC 支持自动为 {IDF_TARGET_NAME} 配置一个地址，或 {IDF_TARGET_NAME} 地址发生改变时，将引发此事件。此事件意味着应用程序一切就绪，可以开始任务（如：创建套接字）。
IP_STA_LOST_IP
IP_EVENT_STA_LOST_IP
++++++++++++++++++++++++++++++++++++
当 IPV4 地址失效时，将引发此事件。
@ -230,7 +231,7 @@ WIFI_EVENT_AP_STADISCONNECTED
此事件将在以下情况下发生：
- 应用程序通过调用函数 :cpp:func:`esp_wifi_disconnect()` 或 :cpp:func:`esp_wifi_deauth_sta()` 手动断开 station 连接。
- Wi-Fi 驱动程序出于某些原因断开 station 连接，例如：AP 在过去 5 分钟（可通过函数 :cpp:func:`esp_wifi_set_inactive_time` 修改该时间）内未接收到任何数据包等。
- Wi-Fi 驱动程序出于某些原因断开 station 连接，例如：AP 在过去 5 分钟（可通过函数 :cpp:func:`esp_wifi_set_inactive_time()` 修改该时间）内未接收到任何数据包等。
- station 断开与 AP 之间的连接。
发生此事件时，事件任务将不做任何响应，但应用程序的事件回调函数需执行一些操作，例如：关闭与此 station 相关的套接字等。
@ -303,7 +304,7 @@ WIFI_EVENT_AP_PROBEREQRECVED
++++++++++++++++++++++++++++++
- s1.1：主任务通过调用函数 :cpp:func:`esp_netif_init()` 创建一个 LwIP 核心任务，并初始化 LwIP 相关工作。
- s1.2：主任务通过调用函数 :cpp:func:`esp_event_loop_create` 创建一个系统事件任务，并初始化应用程序事件的回调函数。在此情况下，该回调函数唯一的动作就是将事件中继到应用程序任务中。
- s1.2：主任务通过调用函数 :cpp:func:`esp_event_loop_create()` 创建一个系统事件任务，并初始化应用程序事件的回调函数。在此情况下，该回调函数唯一的动作就是将事件中继到应用程序任务中。
- s1.3：主任务通过调用函数 :cpp:func:`esp_netif_create_default_wifi_ap()` 或 :cpp:func:`esp_netif_create_default_wifi_sta()` 创建有 TCP/IP 堆栈的默认网络接口实例绑定 station 或 AP。
@ -317,7 +318,7 @@ WIFI_EVENT_AP_PROBEREQRECVED
+++++++++++++++++++++++++++++++
Wi-Fi 驱动程序初始化成功后，可以进入到配置阶段。该场景下，Wi-Fi 驱动程序处于 station 模式。因此，首先您需调用函数 :cpp:func:`esp_wifi_set_mode` (WIFI_MODE_STA) 将 Wi-Fi 模式配置为 station 模式。可通过调用其它 esp_wifi_set_xxx API 进行更多设置，例如：协议模式、国家代码、带宽等。请参阅 `{IDF_TARGET_NAME} Wi-Fi 配置`_。
一般情况下，我们会在建立 Wi-Fi 连接之前配置 Wi-Fi 驱动程序，但这 **并非** 强制要求。也就是说，只要 Wi-Fi 驱动程序已成功初始化，您可以在任意阶段进行配置。但是，如果您的 Wi-Fi 在建立连接后不需要更改配置，则应先在此阶段完成配置。因为调用配置 API（例如 :cpp:func:`esp_wifi_set_protocol`）将会导致 Wi-Fi 连接断开，为您的操作带来不便。
一般情况下，我们会在建立 Wi-Fi 连接之前配置 Wi-Fi 驱动程序，但这 **并非** 强制要求。也就是说，只要 Wi-Fi 驱动程序已成功初始化，您可以在任意阶段进行配置。但是，如果您的 Wi-Fi 在建立连接后不需要更改配置，则应先在此阶段完成配置。因为调用配置 API（例如 :cpp:func:`esp_wifi_set_protocol()`）将会导致 Wi-Fi 连接断开，为您的操作带来不便。
如果 menuconfig 已使能 Wi-Fi NVS flash，则不论当前阶段还是后续的 Wi-Fi 配置信息都将被存储至该 flash 中。那么，当主板上电/重新启动时，就不需从头开始配置 Wi-Fi 驱动程序。您只需调用函数 esp_wifi_get_xxx API 获取之前存储的配置信息。当然，如果不想使用之前的配置，您依然可以重新配置 Wi-Fi 驱动程序。
@ -455,7 +456,7 @@ Wi-Fi 驱动程序初始化成功后，可以进入到配置阶段。该场景
扫描配置
+++++++++++++++++
扫描类型与其他扫描属性通过函数 :cpp:func:`esp_wifi_scan_start` 进行配置。下表详细描述了函数 wifi_scan_config_t 各字段信息。
扫描类型与其他扫描属性通过函数 :cpp:func:`esp_wifi_scan_start()` 进行配置。下表详细描述了函数 wifi_scan_config_t 各字段信息。
+-------------+----------------------------------------------------------------------------------------------------------------------+
| 字段 | 描述 |
@ -488,7 +489,7 @@ Wi-Fi 驱动程序初始化成功后，可以进入到配置阶段。该场景
| | 如希望提升 Wi-Fi 扫描性能，则可修改上述两个参数。 |
+-------------+----------------------------------------------------------------------------------------------------------------------+
调用 API :cpp:func:`esp_wifi_set_config` 可全局配置一些扫描属性，请参阅 `station 基本配置`_。
调用 API :cpp:func:`esp_wifi_set_config()` 可全局配置一些扫描属性，请参阅 `station 基本配置`_。
在所有信道中扫描全部 AP（前端）
+++++++++++++++++++++++++++++++++++++++++++
@ -1091,35 +1092,36 @@ API esp_wifi_set_config() 可用于配置 AP。下表详细介绍了各个字段
Wi-Fi 协议模式
+++++++++++++++++++++++++
目前，IDF 支持以下协议模式：
目前，ESP-IDF 支持以下协议模式：
+--------------+------------------------------------------------------------------------------------------------------------------+
| 协议模式 | 描述 |
+--------------+------------------------------------------------------------------------------------------------------------------+
| 802.11b | 调用函数 :cpp:func:`esp_wifi_set_protocol` (ifx, WIFI_PROTOCOL_11B)，将 |
| | station/AP 设置为仅 802.11b 模式。 |
+--------------+------------------------------------------------------------------------------------------------------------------+
| 802.11bg | 调用函数 :cpp:func:`esp_wifi_set_protocol` (ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G)，将 station/AP 设置为 |
| | 802.11bg 模式。 |
+--------------+------------------------------------------------------------------------------------------------------------------+
| 802.11bgn | 调用函数 :cpp:func:`esp_wifi_set_protocol` (ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N)，将 |
| | station/AP 设置为 802.11bgn 模式。 |
+--------------+------------------------------------------------------------------------------------------------------------------+
| 802.11 BGNLR | 调用函数 :cpp:func:`esp_wifi_set_protocol` |
| | (ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR)，将 station/AP 设置为 802.11bgn |
| | 和乐鑫专属模式。 |
+--------------+------------------------------------------------------------------------------------------------------------------+
| 802.11 LR | 调用函数 :cpp:func:`esp_wifi_set_protocol` (ifx, WIFI_PROTOCOL_LR)，将 |
| | station/AP 设置为仅乐鑫专属模式。 |
| | |
| | **此模式是乐鑫的专利模式，可以达到 1 公里视线范围。请确保 |
| | station 和 AP 同时连接至 ESP 设备。** |
+--------------+------------------------------------------------------------------------------------------------------------------+
.. list-table::
:header-rows: 1
:widths: 15 55
远程 (LR)
* - 协议模式
- 描述
* - 802.11b
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B)，将 station/AP 设置为仅 802.11b 模式。
* - 802.11bg
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G)，将 station/AP 设置为 802.11bg 模式。
* - 802.11g
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) 和 esp_wifi_config_11b_rate(ifx, true)，将 station/AP 设置为 802.11g 模式。
* - 802.11bgn
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N)，将 station/AP 设置为 802.11bgn 模式。
* - 802.11gn
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) 和 esp_wifi_config_11b_rate(ifx, true)，将 station/AP 设置为 802.11gn 模式。
* - 802.11 BGNLR
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR)，将 station/AP 设置为 802.11bgn 和 LR 模式。
* - 802.11 LR
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_LR)，将 station/AP 设置为 LR 模式。
**此模式是乐鑫的专利模式，可以达到 1 公里视线范围。请确保 station 和 AP 同时连接至 ESP 设备。**
长距离 (LR)
+++++++++++++++++++++++++
远程 (LR) 模式是乐鑫的一项专利 Wi-Fi 模式，可达到 1 公里视线范围。与传统 802.11b 模式相比，接收灵敏度更高，抗干扰能力更强，传输距离更长。
长距离 (LR) 模式是乐鑫的一项专利 Wi-Fi 模式，可达到 1 公里视线范围。与传统 802.11b 模式相比，接收灵敏度更高，抗干扰能力更强，传输距离更长。
LR 兼容性
*************************
@ -1174,7 +1176,7 @@ LR 的接收灵敏度比传统的 802.11B 模式高 4 dB，理论上，传输距
LR 吞吐量
*************************
因为原始 PHY 数据传输速率为 1×2 Mbit 和 1/4 Mbit，LR 的吞吐量有限。
因为原始 PHY 数据传输速率为 1/2 Mbps 和 1/4 Mbps，LR 的吞吐量有限。
何时使用 LR
*************************
@ -1307,9 +1309,9 @@ Station 睡眠
Modem-sleep 模式包括最小和最大节能模式。在最小节能模式下，每个 DTIM 间隔，station 都将唤醒以接收 beacon。广播数据在 DTIM 之后传输，因此不会丢失。但是，由于 DTIM 间隔长短由 AP 决定，如果该间隔时间设置较短，则省电效果不大。
在最大节能模式下，每个监听间隔，station 都将唤醒以接收 beacon。可以设置该监听间隔长于 AP 的 DTIM 周期。在 DTIM 期间内，station 可能处于睡眠状态，广播数据会丢失。如果监听间隔较长，则可以节省更多电量，但广播数据更容易丢失。连接 AP 前，可以通过调用 API :cpp:func:`esp_wifi_set_config` 配置监听间隔。
在最大节能模式下，每个监听间隔，station 都将唤醒以接收 beacon。可以设置该监听间隔长于 AP 的 DTIM 周期。在 DTIM 期间内，station 可能处于睡眠状态，广播数据会丢失。如果监听间隔较长，则可以节省更多电量，但广播数据更容易丢失。连接 AP 前，可以通过调用 API :cpp:func:`esp_wifi_set_config()` 配置监听间隔。
调用 :cpp:func:`esp_wifi_init` 后，调用 ``esp_wifi_set_ps(WIFI_PS_MIN_MODEM)`` 可使能 Modem-sleep 最小节能模式。调用 ``esp_wifi_set_ps(WIFI_PS_MAX_MODEM)`` 可使能 Modem-sleep 最大节能模式。station 连接到 AP 时，Modem-sleep 模式将启动。station 与 AP 断开连接时，Modem-sleep 模式将停止。
调用 :cpp:func:`esp_wifi_init()` 后，调用 ``esp_wifi_set_ps(WIFI_PS_MIN_MODEM)`` 可使能 Modem-sleep 最小节能模式。调用 ``esp_wifi_set_ps(WIFI_PS_MAX_MODEM)`` 可使能 Modem-sleep 最大节能模式。station 连接到 AP 时，Modem-sleep 模式将启动。station 与 AP 断开连接时，Modem-sleep 模式将停止。
调用 ``esp_wifi_set_ps(WIFI_PS_NONE)`` 可以完全禁用 Modem-sleep 模式。禁用会增大功耗，但可以最大限度减少实时接收 Wi-Fi 数据的延迟。使能 Modem-sleep 时，接收 Wi-Fi 数据的延迟时间可能与 DTIM 周期（最小节能模式）或监听间隔（最大节能模式）相同。在 Wi-Fi 与 Bluetooth LE 共存模式下，无法完全禁用 modem-sleep 模式。
@ -1434,32 +1436,33 @@ AP 睡眠
Wi-Fi 80211 数据包发送
---------------------------
**重要说明：API esp_wifi_80211_tx 在 IDF 2.1 中不可用，即将发布的版本将可以使用。**
**重要说明：API esp_wifi_80211_tx() 在 IDF 2.1 中不可用，即将发布的版本将可以使用。**
:cpp:func:`esp_wifi_80211_tx` API 可用于：
:cpp:func:`esp_wifi_80211_tx()` API 可用于：
- 发送 beacon、probe request、probe response 和 action 帧。
- 发送非 QoS 数据帧。
不能用于发送加密或 QoS 帧。
使用 :cpp:func:`esp_wifi_80211_tx` 的前提条件
使用 :cpp:func:`esp_wifi_80211_tx()` 的前提条件
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
- Wi-Fi 模式为 Station 模式， AP 模式，或 Station/AP 共存模式。
- API esp_wifi_set_promiscuous(true) 或 :cpp:func:`esp_wifi_start()`，或者二者都返回 ESP_OK。这是为确保调用函数 :cpp:func:`esp_wifi_80211_tx()` 前，Wi-Fi 硬件已经初始化。对于 {IDF_TARGET_NAME}，esp_wifi_set_promiscuous(true) 和 :cpp:func:`esp_wifi_start()` 都可以触发 Wi-Fi 硬件初始化。
- 提供正确的 :cpp:func:`esp_wifi_80211_tx` 参数。
- Wi-Fi 模式为 station 模式，AP 模式，或 station/AP 共存模式。
- API esp_wifi_set_promiscuous(true) 或 :cpp:func:`esp_wifi_start()`，或者二者都返回 ESP_OK。这是为确保在调用函数 :cpp:func:`esp_wifi_80211_tx()` 前，Wi-Fi 硬件已经初始化。对于 {IDF_TARGET_NAME}，esp_wifi_set_promiscuous(true) 和 :cpp:func:`esp_wifi_start()` 都可以触发 Wi-Fi 硬件初始化。
- 提供正确的 :cpp:func:`esp_wifi_80211_tx()` 参数。
传输速率
+++++++++++++++++++++++++++++
- 如果没有 Wi-Fi 连接，传输速率为 1 Mbps。
- 如果有 WiFi 连接，且数据包是从 station 到 AP 或从 AP 到 station，则传输速率与 Wi-Fi 连接相同。否则，传输速率为 1 Mbps。
- 默认传输速率为 1 Mbps。
- 可以通过函数 :cpp:func:`esp_wifi_config_80211_tx_rate()` 设置任意速率。
- 可以通过函数 :cpp:func:`esp_wifi_set_bandwidth()` 设置任意带宽。
在不同情况下需要避免的副作用
+++++++++++++++++++++++++++++++++++++++++++++++++++++
理论上，如果不考虑 API 对 Wi-Fi 驱动程序或其他 station 或 AP 的副作用，可以通过空中发送一个原始的 802.11 数据包，包括任何目的地址的 MAC、任何源地址的 MAC、任何 BSSID、或任何其他类型的数据包。但是，一个具有强健、有用的应用程序应该避免这种副作用。下表针对如何避免 :cpp:func:`esp_wifi_80211_tx` 的副作用提供了一些提示或建议。
理论上，如果不考虑 API 对 Wi-Fi 驱动程序或其他 station 或 AP 的副作用，可以通过空中发送一个原始的 802.11 数据包，包括任何目的地址的 MAC、任何源地址的 MAC、任何 BSSID、或任何其他类型的数据包。但是，一个具有强健、有用的应用程序应该避免这种副作用。下表针对如何避免 :cpp:func:`esp_wifi_80211_tx()` 的副作用提供了一些提示或建议。
+---------------+--------------------------------------------------------------------------------------------+
| 场景 | 描述 |
@ -1557,7 +1560,9 @@ Wi-Fi 多根天线
四个高电平有效 antenna_select 管脚有多达四个 GPIO 连接。{IDF_TARGET_NAME} 可以通过控制 GPIO[0:3] 选择天线。API :cpp:func:`esp_wifi_set_ant_gpio()` 用于配置 antenna_selects 连接哪些 GPIO。如果 GPIO[x] 连接到 antenna_select[x]，gpio_config->gpio_cfg[x].gpio_select 应设置为 1，且要提供 gpio_config->gpio_cfg[x].gpio_num 的值。
尽管最多支持 16 根天线，发送和接收数据时，最多仅能同时使能两根天线。API :cpp:func:`esp_wifi_set_ant()` 用于配置使能哪根天线。
天线开关的具体实现不同，`antenna_select[0:3]` 的输入值中可能存在非法值，即 {IDF_TARGET_NAME} 通过外部天线开关支持的天线数可能小于 16 根。例如，ESP32-WROOM-DA 使用 RTC6603SP 作为天线开关，仅支持 2 根天线。两个天线选择输入管脚为高电平有效，连接到两个 GPIO。'0b01' 表示选中天线 0，'0b10' 表示选中天线 1。输入值 '0b00' 和 '0b11' 为非法值。
尽管最多支持 16 根天线，发送和接收数据时，最多仅能同时使能两根天线。API :cpp:func:`esp_wifi_set_ant()` 用于配置使能哪些天线。
使能天线后，选择算法的过程同样可由 :cpp:func:`esp_wifi_set_ant()` 配置。接收/发送数据源的天线模式可以是 WIFI_ANT_MODE_ANT0、WIFI_ANT_MODE_ANT1 或 WIFI_ANT_MODE_AUTO。如果天线模式为 WIFI_ANT_MODE_ANT0，使能的天线 0 用于接收/发送数据。如果天线模式为 WIFI_ANT_MODE_ANT1，使能天线 1 用于接收/发送数据。否则，Wi-Fi 会自动选择使能天线中信号较好的天线。
@ -1635,24 +1640,24 @@ Wi-Fi 信道状态信息
- 对于 STBC 数据包，每个空时流都提供了 CSI，不会出现 CSD（循环移位延迟）。由于附加链上的每一次循环移位为 -200 ns，因为子载波 0 中没有信道频率响应，在 HT-LTF 和 STBC-HT-LTF 中只记录第一空时流的 CSD 角度。CSD[10:0] 是 11 位，范围从 -pi 到 pi。
- 如果调用 API :cpp:func:`esp_wifi_set_csi_config` 没有使能 LLTF、HT-LTF 或 STBC-HT-LTF，则 CSI 数据的总字节数会比表中的少。例如，如果没有使能 LLTF 和 HT-LTF，而使能 STBC-HT-LTF，当接收到上述条件、HT、40 MHz 或 STBC的数据包时，CSI 数据的总字节数为 244（(61+60)*2+2=244，结果对齐为四个字节，最后两个字节无效）。
- 如果调用 API :cpp:func:`esp_wifi_set_csi_config()` 没有使能 LLTF、HT-LTF 或 STBC-HT-LTF，则 CSI 数据的总字节数会比表中的少。例如，如果没有使能 LLTF 和 HT-LTF，而使能 STBC-HT-LTF，当接收到上述条件、HT、40 MHz 或 STBC 的数据包时，CSI 数据的总字节数为 244（(61+60)*2+2=244，结果对齐为四个字节，最后两个字节无效）。
Wi-Fi 信道状态信息配置
-------------------------------------------
要使用 Wi-Fi CSI，需要执行以下步骤。
- 在菜单配置中选择 Wi-Fi CSI。方法是“菜单配置 - > 组件配置 -- > Wi-Fi -- > WiFi CSI（信道状态信息）”。
- 调用 API :cpp:func:`esp_wifi_set_csi_rx_cb` 设置 CSI 接收回调函数。
- 调用 API :cpp:func:`esp_wifi_set_csi_config` 配置 CSI。
- 调用 API :cpp:func:`esp_wifi_set_csi` 使能 CSI。
- 在菜单配置中选择 Wi-Fi CSI。方法是“菜单配置 - > 组件配置 -- > Wi-Fi -- > Wi-Fi CSI（信道状态信息）”。
- 调用 API :cpp:func:`esp_wifi_set_csi_rx_cb()` 设置 CSI 接收回调函数。
- 调用 API :cpp:func:`esp_wifi_set_csi_config()` 配置 CSI。
- 调用 API :cpp:func:`esp_wifi_set_csi()` 使能 CSI。
CSI 接收回调函数从 Wi-Fi 任务中运行。因此，不要在回调函数中进行冗长的操作。但是需要将必要的数据发布到队列中，并从一个较低优先级的任务中处理。由于 station 在断开连接时不会收到任何数据包，只有在连接时才会收到来自 AP 的数据包，因此建议通过调用函数 :cpp:func:`esp_wifi_set_promiscuous` 使能 Sniffer 模式接收更多 CSI 数据。
CSI 接收回调函数从 Wi-Fi 任务中运行。因此，不要在回调函数中进行冗长的操作。但是需要将必要的数据发布到队列中，并从一个较低优先级的任务中处理。由于 station 在断开连接时不会收到任何数据包，只有在连接时才会收到来自 AP 的数据包，因此建议通过调用函数 :cpp:func:`esp_wifi_set_promiscuous()` 使能 Sniffer 模式接收更多 CSI 数据。
Wi-Fi HT20/40
-------------------------
{IDF_TARGET_NAME} 支持 Wi-Fi 带宽 HT20 或 HT40，不支持 HT20/40 共存，调用函数 :cpp:func:`esp_wifi_set_bandwidth` 可改变 station/AP 的默认带宽。{IDF_TARGET_NAME} station 和 AP 的默认带宽为 HT40。
{IDF_TARGET_NAME} 支持 Wi-Fi 带宽 HT20 或 HT40，不支持 HT20/40 共存，调用函数 :cpp:func:`esp_wifi_set_bandwidth()` 可改变 station/AP 的默认带宽。{IDF_TARGET_NAME} station 和 AP 的默认带宽为 HT40。
Station 模式下，实际带宽首先在 Wi-Fi 连接时协商。只有当 station 和所连 AP 都支持 HT40 时，带宽才为 HT40，否则为 HT20。如果所连的 AP 的带宽发生变化，则在不断开 Wi-Fi 连接的情况下再次协商实际带宽。
@ -2405,4 +2410,4 @@ Wi-Fi AMPDU
.. toctree::
:hidden:
wireshark-user-guide
wireshark-user-guide

37
docs/zh_CN/api-reference/network/esp_now.rst
View File

@ -50,7 +50,7 @@ ESP-NOW 使用各个供应商的动作帧传输数据，默认比特率为 1 Mbp
--------
ESP-NOW 采用 CCMP 方法保护供应商特定动作帧的安全，具体可参考 IEEE Std. 802.11-2012。Wi-Fi 设备维护一个初始主密钥 (PMK) 和若干本地主密钥 (LMK)，长度均为 16 个字节。
* PMK 可使用 AES-128 算法加密 LMK。请调用 ``esp_now_set_pmk()`` 设置 PMK。如果未设置 PMK，将使用默认 PMK。
* PMK 可使用 AES-128 算法加密 LMK。请调用 :cpp:func:`esp_now_set_pmk()` 设置 PMK。如果未设置 PMK，将使用默认 PMK。
* LMK 可通过 CCMP 方法对供应商特定的动作帧进行加密，最多拥有 6 个不同的 LMK。如果未设置配对设备的 LMK，则动作帧不进行加密。
目前，不支持加密组播供应商特定的动作帧。
@ -58,29 +58,50 @@ ESP-NOW 采用 CCMP 方法保护供应商特定动作帧的安全，具体可参
初始化和反初始化
------------------------------------
调用 ``esp_now_init()`` 初始化 ESP-NOW，调用 ``esp_now_deinit()`` 反初始化 ESP-NOW。ESP-NOW 数据必须在 Wi-Fi 启动后传输，因此建议在初始化 ESP-NOW 之前启动 Wi-Fi，并在反初始化 ESP-NOW 之后停止 Wi-Fi。
当调用 ``esp_now_deinit()`` 时，配对设备的所有信息都将被删除。
调用 :cpp:func:`esp_now_init()` 初始化 ESP-NOW，调用 :cpp:func:`esp_now_deinit()` 反初始化 ESP-NOW。ESP-NOW 数据必须在 Wi-Fi 启动后传输，因此建议在初始化 ESP-NOW 之前启动 Wi-Fi，并在反初始化 ESP-NOW 之后停止 Wi-Fi。
当调用 :cpp:func:`esp_now_deinit()` 时，配对设备的所有信息都将被删除。
添加配对设备
-----------------
在将数据发送到其他设备之前，请先调用 ``esp_now_add_peer()`` 将其添加到配对设备列表中。配对设备的最大数量是 20。如果启用了加密，则必须设置 LMK。ESP-NOW 数据可以从 Station 或 Softap 接口发送。
确保在发送 ESP-NOW 数据之前已启用该接口。在发送广播数据之前必须添加具有广播 MAC 地址的设备。配对设备的信道范围是从 0 ～14。如果信道设置为 0，数据将在当前信道上发送。否则，必须使用本地设备所在的通道。
在将数据发送到其他设备之前，请先调用 :cpp:func:`esp_now_add_peer()` 将其添加到配对设备列表中。如果启用了加密，则必须设置 LMK。ESP-NOW 数据可以从 Station 或 Softap 接口发送。确保在发送 ESP-NOW 数据之前已启用该接口。
.. only:: esp32c3
配对设备的最大数量是 20，其中加密设备的数量不超过 10，默认值是 6。
.. only:: esp32 or esp32s2 or esp32s3
配对设备的最大数量是 20，其中加密设备的数量不超过 16，默认值是 6。
在发送广播数据之前必须添加具有广播 MAC 地址的设备。配对设备的信道范围是从 0 ～14。如果信道设置为 0，数据将在当前信道上发送。否则，必须使用本地设备所在的通道。
发送 ESP-NOW 数据
-----------------
调用 ``esp_now_send()`` 发送 ESP-NOW 数据，调用 ``esp_now_register_send_cb`` 注册发送回调函数。如果 MAC 层成功接收到数据，则该函数将返回 `ESP_NOW_SEND_SUCCESS` 事件。否则，它将返回 `ESP_NOW_SEND_FAIL`。ESP-NOW 数据发送失败可能有几种原因，比如目标设备不存在、设备的信道不相同、动作帧在传输过程中丢失等。应用层并不一定可以总能接收到数据。如果需要，应用层可在接收 ESP-NOW 数据时发回一个应答 (ACK) 数据。如果接收 ACK 数据超时，则将重新传输 ESP-NOW 数据。可以为 ESP-NOW 数据设置序列号，从而删除重复的数据。
调用 :cpp:func:`esp_now_send()` 发送 ESP-NOW 数据，调用 :cpp:func:`esp_now_register_send_cb` 注册发送回调函数。如果 MAC 层成功接收到数据，则该函数将返回 `ESP_NOW_SEND_SUCCESS` 事件。否则，它将返回 `ESP_NOW_SEND_FAIL`。ESP-NOW 数据发送失败可能有几种原因，比如目标设备不存在、设备的信道不相同、动作帧在传输过程中丢失等。应用层并不一定可以总能接收到数据。如果需要，应用层可在接收 ESP-NOW 数据时发回一个应答 (ACK) 数据。如果接收 ACK 数据超时，则将重新传输 ESP-NOW 数据。可以为 ESP-NOW 数据设置序列号，从而删除重复的数据。
如果有大量 ESP-NOW 数据要发送，则调用 ``esp_now_send()`` 一次性发送不大于 250 字节的数据。
如果有大量 ESP-NOW 数据要发送，则调用 :cpp:func:`esp_now_send()` 一次性发送不大于 250 字节的数据。
请注意，两个 ESP-NOW 数据包的发送间隔太短可能导致回调函数返回混乱。因此，建议在等到上一次回调函数返回 ACK 后再发送下一个 ESP-NOW 数据。发送回调函数从高优先级的 Wi-Fi 任务中运行。因此，不要在回调函数中执行冗长的操作。相反，将必要的数据发布到队列，并交给优先级较低的任务处理。
接收 ESP-NOW 数据
----------------------
调用 ``esp_now_register_recv_cb`` 注册接收回调函数。当接收 ESP-NOW 数据时，需要调用接收回调函数。接收回调函数也在 Wi-Fi 任务任务中运行。因此，不要在回调函数中执行冗长的操作。
调用 :cpp:func:`esp_now_register_recv_cb()` 注册接收回调函数。当接收 ESP-NOW 数据时，需要调用接收回调函数。接收回调函数也在 Wi-Fi 任务任务中运行。因此，不要在回调函数中执行冗长的操作。
相反，将必要的数据发布到队列，并交给优先级较低的任务处理。
配置 ESP-NOW 速率
----------------------
调用 :cpp:func:`esp_wifi_config_espnow_rate()` 配置指定接口的 ESPNOW 速率。确保在配置速率之前使能接口。这个 API 应该在 :cpp:func:`esp_wifi_start()` 之后调用。
应用示例
----------
* 如何在设备间传输 ESP-NOW 数据：:example:`wifi/espnow`。
* 了解更多 ESP-NOW 的应用示例，请参考 `README.md 文件 <https://github.com/espressif/esp-now>`_。
API 参考
-------------

25
examples/wifi/getting_started/station/main/Kconfig.projbuild
View File

@ -17,4 +17,29 @@ menu "Example Configuration"
default 5
help
Set the Maximum retry to avoid station reconnecting to the AP unlimited when the AP is really inexistent.
choice ESP_WIFI_SCAN_AUTH_MODE_THRESHOLD
prompt "WiFi Scan auth mode threshold"
default ESP_WIFI_AUTH_OPEN
help
The weakest authmode to accept in the scan mode.
config ESP_WIFI_AUTH_OPEN
bool "OPEN"
config ESP_WIFI_AUTH_WEP
bool "WEP"
config ESP_WIFI_AUTH_WPA_PSK
bool "WPA PSK"
config ESP_WIFI_AUTH_WPA2_PSK
bool "WPA2 PSK"
config ESP_WIFI_AUTH_WPA_WPA2_PSK
bool "WPA/WPA2 PSK"
config ESP_WIFI_AUTH_WPA3_PSK
bool "WPA3 PSK"
config ESP_WIFI_AUTH_WPA2_WPA3_PSK
bool "WPA2/WPA3 PSK"
config ESP_WIFI_AUTH_WAPI_PSK
bool "WAPI PSK"
endchoice
endmenu

26
examples/wifi/getting_started/station/main/station_example_main.c
View File

@ -28,6 +28,24 @@
#define EXAMPLE_ESP_WIFI_PASS CONFIG_ESP_WIFI_PASSWORD
#define EXAMPLE_ESP_MAXIMUM_RETRY CONFIG_ESP_MAXIMUM_RETRY
#if CONFIG_ESP_WIFI_AUTH_OPEN
#define ESP_WIFI_SCAN_AUTH_MODE_THRESHOLD WIFI_AUTH_OPEN
#elif CONFIG_ESP_WIFI_AUTH_WEP
#define ESP_WIFI_SCAN_AUTH_MODE_THRESHOLD WIFI_AUTH_WEP
#elif CONFIG_ESP_WIFI_AUTH_WPA_PSK
#define ESP_WIFI_SCAN_AUTH_MODE_THRESHOLD WIFI_AUTH_WPA_PSK
#elif CONFIG_ESP_WIFI_AUTH_WPA2_PSK
#define ESP_WIFI_SCAN_AUTH_MODE_THRESHOLD WIFI_AUTH_WPA2_PSK
#elif CONFIG_ESP_WIFI_AUTH_WPA_WPA2_PSK
#define ESP_WIFI_SCAN_AUTH_MODE_THRESHOLD WIFI_AUTH_WPA_WPA2_PSK
#elif CONFIG_ESP_WIFI_AUTH_WPA3_PSK
#define ESP_WIFI_SCAN_AUTH_MODE_THRESHOLD WIFI_AUTH_WPA3_PSK
#elif CONFIG_ESP_WIFI_AUTH_WPA2_WPA3_PSK
#define ESP_WIFI_SCAN_AUTH_MODE_THRESHOLD WIFI_AUTH_WPA2_WPA3_PSK
#elif CONFIG_ESP_WIFI_AUTH_WAPI_PSK
#define ESP_WIFI_SCAN_AUTH_MODE_THRESHOLD WIFI_AUTH_WAPI_PSK
#endif
/* FreeRTOS event group to signal when we are connected*/
static EventGroupHandle_t s_wifi_event_group;
@ -41,6 +59,7 @@ static const char *TAG = "wifi station";
static int s_retry_num = 0;
static void event_handler(void* arg, esp_event_base_t event_base,
int32_t event_id, void* event_data)
{
@ -95,7 +114,7 @@ void wifi_init_sta(void)
/* Setting a password implies station will connect to all security modes including WEP/WPA.
* However these modes are deprecated and not advisable to be used. Incase your Access point
* doesn't support WPA2, these mode can be enabled by commenting below line */
.threshold.authmode = WIFI_AUTH_WPA2_PSK,
.threshold.authmode = ESP_WIFI_SCAN_AUTH_MODE_THRESHOLD,
},
};
ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA) );
@ -123,11 +142,6 @@ void wifi_init_sta(void)
} else {
ESP_LOGE(TAG, "UNEXPECTED EVENT");
}
/* The event will not be processed after unregister */
ESP_ERROR_CHECK(esp_event_handler_instance_unregister(IP_EVENT, IP_EVENT_STA_GOT_IP, instance_got_ip));
ESP_ERROR_CHECK(esp_event_handler_instance_unregister(WIFI_EVENT, ESP_EVENT_ANY_ID, instance_any_id));
vEventGroupDelete(s_wifi_event_group);
}
void app_main(void)