mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'docs/update_wifi_api_doc_v4.2' into 'release/v4.2'
DOC: update wifi api docs ( backport v4.2) See merge request espressif/esp-idf!18083
This commit is contained in:
Jiang Jiang Jian
commit
c5875e64b1
@ -190,7 +190,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
|
||||
*/
|
||||
|
||||
@ -488,7 +488,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
|
||||
|
||||
@ -1 +1 @@
|
||||
Subproject commit 90fa34580fc0067bf580b6b37ffcf8e3f8fd37ee
|
||||
Subproject commit 55834424263464de72126263e328bc9235853911
|
||||
@ -3,10 +3,11 @@ 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, IEEE802.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/WPA2-Enterprise and WPS
|
||||
- Support AMPDU, HT40, QoS and other key features
|
||||
- Support AMPDU, HT40, QoS, and other key features
|
||||
- Support Modem-sleep
|
||||
- Support an Espressif-specific protocol which, in turn, supports up to **1 km** of data traffic
|
||||
- Up to 20 MBit/sec TCP throughput and 30 MBit/sec UDP throughput over the air
|
||||
@ -56,9 +57,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 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 esp_wifi_set_mode returns ESP_ERR_WIFI_NOT_INIT, it means that the Wi-Fi driver is not initialized by 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.
|
||||
@ -120,9 +121,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
|
||||
-----------------------------------------
|
||||
@ -224,8 +225,9 @@ 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.
|
||||
@ -296,13 +298,14 @@ Below is a "big scenario" which describes some small scenarios in Station mode:
|
||||
|
||||
1. Wi-Fi/LwIP Init Phase
|
||||
++++++++++++++++++++++++++++++
|
||||
- s1.1: The main task calls esp_netif_init() to create an LwIP core task and initialize LwIP-related work.
|
||||
- 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 esp_event_loop_init() 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_init()` 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 esp_netif_create_default_wifi_ap() or esp_netif_create_default_wifi_sta() to create default network interface instance binding station or AP with TCP/IP stack.
|
||||
|
||||
- s1.4: The main task calls esp_wifi_init() to create the Wi-Fi driver task and initialize the Wi-Fi driver.
|
||||
- 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.
|
||||
|
||||
- s1.4: The main task calls :cpp:func:`esp_wifi_init()` to create the Wi-Fi driver task and initialize the Wi-Fi driver.
|
||||
|
||||
- s1.5: The main task calls OS API to create the application task.
|
||||
|
||||
@ -312,7 +315,7 @@ Step 1.1~1.5 is a recommended sequence that initializes a Wi-Fi-/LwIP-based appl
|
||||
+++++++++++++++++++++++++++++++
|
||||
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 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 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.
|
||||
|
||||
@ -1213,11 +1216,11 @@ Currently, the IDF supports the following protocol modes:
|
||||
+--------------------+------------------------------------------------------------+
|
||||
| 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. |
|
||||
| | 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 Espressif-specific mode. |
|
||||
| | 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|
|
||||
@ -1281,7 +1284,7 @@ The reception sensitivity of LR has about 4 dB gain than the traditional 802.11
|
||||
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 are 1/2 Mbps and 1/4 Mbps.
|
||||
|
||||
When to Use LR
|
||||
*************************
|
||||
@ -1464,9 +1467,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.
|
||||
|
||||
@ -1515,19 +1518,19 @@ When the throughput is tested by iperf example, the sdkconfig is :idf_file:`exam
|
||||
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 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 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 esp_wifi_80211_tx() is called. In {IDF_TARGET_NAME}, both esp_wifi_set_promiscuous(true) and esp_wifi_start() can trigger the initialization of Wi-Fi hardware.
|
||||
- The parameters of 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
|
||||
+++++++++++++++++++++++++++++++++++++++++++++++
|
||||
@ -1748,25 +1751,26 @@ When imaginary part and real part data of sub-carrier are used, please refer to
|
||||
|
||||
.. 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 -200ns, 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).
|
||||
- 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 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. `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.
|
||||
|
||||
|
||||
@ -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,27 +58,32 @@ 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 ``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:: esp32 or esp32s2
|
||||
|
||||
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.
|
||||
|
||||
API Reference
|
||||
|
||||
@ -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,27 +58,32 @@ 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，数据将在当前信道上发送。否则，必须使用本地设备所在的通道。
|
||||
在将数据发送到其他设备之前，请先调用 ``esp_now_add_peer()`` 将其添加到配对设备列表中。如果启用了加密，则必须设置 LMK。ESP-NOW 数据可以从 Station 或 Softap 接口发送。确保在发送 ESP-NOW 数据之前已启用该接口。
|
||||
|
||||
.. only:: esp32 or esp32s2
|
||||
|
||||
配对设备的最大数量是 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 任务任务中运行。因此，不要在回调函数中执行冗长的操作。
|
||||
相反，将必要的数据发布到队列，并交给优先级较低的任务处理。
|
||||
|
||||
API 参考
|
||||
|
||||
Loading…
Reference in New Issue
Block a user