esp_wifi: fix some connectionless related issue and add connectionless power save guide

components/esp_wifi/Kconfig

@@ -10,6 +10,7 @@ menu "Wi-Fi"
         bool "Software controls WiFi/Bluetooth coexistence"
         depends on ESP32_WIFI_ENABLED && BT_ENABLED
         default y
+        select ESP_WIFI_STA_DISCONNECTED_PM_ENABLE
         help
             If enabled, WiFi & Bluetooth coexistence is controlled by software rather than hardware.
             Recommended for heavy traffic scenarios. Both coexistence configuration options are
@@ -307,6 +308,7 @@ menu "Wi-Fi"
 
     config ESP_WIFI_STA_DISCONNECTED_PM_ENABLE
         bool "Power Management for station at disconnected"
+        default y
         help
             Select this option to enable power_management for station when disconnected.
             Chip will do modem-sleep when rf module is not in use any more.

components/esp_wifi/include/esp_wifi.h

@@ -1227,6 +1227,7 @@ 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);
 
+#define ESP_WIFI_CONNECTIONLESS_INTERVAL_DEFAULT_MODE 0
 /**
   * @brief      Set wake interval for connectionless modules to wake up periodically.
   *
@@ -1235,6 +1236,7 @@ esp_err_t esp_wifi_config_11b_rate(wifi_interface_t ifx, bool disable);
   *               When ESP_WIFI_STA_DISCONNECTED_PM_ENABLE is enabled, this configuration could work at disconnected status.
   * @attention 3. Event WIFI_EVENT_CONNECTIONLESS_MODULE_WAKE_INTERVAL_START would be posted each time wake interval starts.
   * @attention 4. Recommend to configure interval in multiples of hundred. (e.g. 100ms)
+  * @attention 5. Recommend to configure interval to ESP_WIFI_CONNECTIONLESS_INTERVAL_DEFAULT_MODE to get stable performance at coexistence mode.
   *
   * @param      wake_interval  Milliseconds after would the chip wake up, from 1 to 65535.
   */

components/esp_wifi/lib

@@ -1 +1 @@
-Subproject commit 69e8def447c7f8730dbc92d07629eae68847ea3a
+Subproject commit f1c5a06856aba43a4de572ed2d0631cae1e3800a

docs/en/api-guides/coexist.rst

@@ -27,13 +27,13 @@ Supported Coexistence Scenario for {IDF_TARGET_NAME}
       +       +--------+-----------+-----+------------+-----------+----------+
       |       |SOFTAP  |TX Beacon  |Y    |Y           |Y          |Y         |
       +       +        +-----------+-----+------------+-----------+----------+
-      |       |        |Connecting |Y    |Y           |Y          |Y         |
+      |       |        |Connecting |C1   |C1          |C1         |C1        |
       +       +        +-----------+-----+------------+-----------+----------+
       |       |        |Connected  |C1   |C1          |C1         |C1        |
       +       +--------+-----------+-----+------------+-----------+----------+
-      |       |Sniffer |RX         |C2   |C2          |C2         |C2        |
+      |       |Sniffer |RX         |C1   |C1          |C1         |C1        |
       +       +--------+-----------+-----+------------+-----------+----------+
-      |       |ESP-NOW |RX         |X    |X           |X          |X         |
+      |       |ESP-NOW |RX         |S    |S           |S          |S         |
       +       +        +-----------+-----+------------+-----------+----------+
       |       |        |TX         |Y    |Y           |Y          |Y         |
       +-------+--------+-----------+-----+------------+-----------+----------+
@@ -56,13 +56,13 @@ Supported Coexistence Scenario for {IDF_TARGET_NAME}
       +       +--------+-----------+--------+-------------+-----+----------+-----------+
       |       |SOFTAP  |TX Beacon  |Y       |Y            |Y    |Y         |Y          |
       +       +        +-----------+--------+-------------+-----+----------+-----------+
-      |       |        |Connecting |Y       |Y            |Y    |Y         |Y          |
+      |       |        |Connecting |C1      |C1           |C1   |C1        |C1         |
       +       +        +-----------+--------+-------------+-----+----------+-----------+
       |       |        |Connected  |C1      |C1           |C1   |C1        |C1         |
       +       +--------+-----------+--------+-------------+-----+----------+-----------+
-      |       |Sniffer |RX         |C2      |C2           |C2   |C2        |C2         |
+      |       |Sniffer |RX         |C1      |C1           |C1   |C1        |C1         |
       +       +--------+-----------+--------+-------------+-----+----------+-----------+
-      |       |ESP-NOW |RX         |X       |X            |X    |X         |X          |
+      |       |ESP-NOW |RX         |S       |S            |S    |S         |S          |
       +       +        +-----------+--------+-------------+-----+----------+-----------+
       |       |        |TX         |Y       |Y            |Y    |Y         |Y          |
       +-------+--------+-----------+--------+-------------+-----+----------+-----------+
@@ -72,9 +72,8 @@ Supported Coexistence Scenario for {IDF_TARGET_NAME}
 
   Y: supported and performance is stable
   C1: supported but the performance is unstable
-  C2: supported but the packet loss rate of Sniffer is unstable
   X: not supported
-
+  S: supported and performance is stable in STA mode, otherwise not supported
 
 Coexistence Mechanism and Policy
 ------------------------------------------------
@@ -152,6 +151,16 @@ Dynamic Priority
 
 The coexistence module assigns different priorities to different status of Wi-Fi and Bluetooth. And the priority for each status is dynamic. For example, in every N BLE Advertising events, there is always one event with high priority. If a high-priority BLE Advertising event occurs within the Wi-Fi time slice, the right to use the RF may be preempted by BLE.
 
+.. only:: SOC_WIFI_SUPPORTED
+
+    Wi-Fi Connectionless Modules Coexistence
+    """"""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+    To some extent, some combinations of connectionless power-saving parameters `Window` and `Interval` would lead to extra Wi-Fi priority request out of Wi-Fi time slice. It`s for obtaining RF resources at coexistence for customized parameters, while leading to impact on Bluetooth performance.
+
+    If connectionless power-saving parameters are configured with default values, the coexistence module would perform in stable mode and the behaviour above would not happen. So please configure Wi-Fi connectionless power-saving parameters to default values unless you have plenty of coexistence performance tests for customized parameters.
+
+    Please refer to :ref:`connectionless module power save <connectionless-module-power-save>` to get more detail.
 
 How to Use the Coexistence Feature
 --------------------------------------

docs/en/api-guides/wifi.rst

@@ -266,6 +266,11 @@ WIFI_EVENT_STA_BEACON_TIMEOUT
 
 If the station does not receive the beacon of the connected AP within the inactive time, the beacon timeout happens, the `WIFI_EVENT_STA_BEACON_TIMEOUT`_ will arise. The application can set inactive time via API :cpp:func:`esp_wifi_set_inactive_time()`.
 
+WIFI_EVENT_CONNECTIONLESS_MODULE_WAKE_INTERVAL_START
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The `WIFI_EVENT_CONNECTIONLESS_MODULE_WAKE_INTERVAL_START`_ will arise at the start of connectionless module `Interval`. See :ref:`connectionless module power save <connectionless-module-power-save>`.
+
 {IDF_TARGET_NAME} Wi-Fi Station General Scenario
 ------------------------------------------------
 Below is a "big scenario" which describes some small scenarios in station mode:
@@ -1637,6 +1642,81 @@ Currently, {IDF_TARGET_NAME} AP does not support all of the power-saving feature
 
 In the future, all power-saving features will be supported on {IDF_TARGET_NAME} AP.
 
+Disconnected State Sleep
++++++++++++++++++++++++++++++++
+
+Disconnected state is the duration without Wi-Fi connection between :cpp:func:`esp_wifi_start` to :cpp:func:`esp_wifi_stop`.
+
+Currently, {IDF_TARGET_NAME} Wi-Fi supports sleep mode in disconnected state if running at station mode. This feature could be configured by Menuconfig choice :ref:`CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE`.
+
+If :ref:`CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE` is enabled, RF, PHY and BB would be turned off in disconnected state when IDLE. The current would be same with current at modem-sleep.
+
+The choice :ref:`CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE` would be selected by default, while it would be selected forcefully in Menuconfig at coexistence mode.
+
+.. _connectionless-module-power-save:
+
+Connectionless Modules Power-saving
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Connectionless modules are those Wi-Fi modules not relying on Wi-Fi connection, e.g ESP-NOW, DPP, FTM. These modules start from :cpp:func:`esp_wifi_start`, working until :cpp:func:`esp_wifi_stop`.
+
+Currently, if ESP-NOW works at station mode, its supported to sleep at both connected state and disconnected state.
+
+Connectionless Modules TX
+*******************************
+
+For each connectionless module, its supported to TX at any sleeping time without any extra configuration.
+
+Meanwhile, :cpp:func:`esp_wifi_80211_tx` is supported at sleep as well.
+
+Connectionless Modules RX
+*******************************
+
+For each connectionless module, two parameters shall be configured to RX at sleep, which are `Window` and `Interval`.
+
+At the start of `Interval` time, RF, PHY, BB would be turned on and kept for `Window` time. Connectionless Module could RX in the duration.
+
+**Interval**
+
+ - There is only one `Interval`. Its configured by :cpp:func:`esp_wifi_set_connectionless_interval`. The unit is milliseconds.
+
+ - The default value of `Interval` is `ESP_WIFI_CONNECTIONLESS_INTERVAL_DEFAULT_MODE`.
+
+ - Event `WIFI_EVENT_CONNECTIONLESS_MODULE_WAKE_INTERVAL_START`_ would be posted at the start of `Interval`. Since `Window` also starts at that momemt, its recommended to TX in that event.
+
+ - At connected state, the start of `Interval` would be aliged with TBTT.
+
+**Window**
+
+ - Each connectionless module has its own `Window` after start. Connectionless Modules Power-saving would work with the max one among them.
+
+ - `Window` is configured by :cpp:func:`module_name_set_wake_window`. The unit is milliseconds.
+
+ - The default value of `Window` is the maximum.
+
+.. table:: RF, PHY and BB usage under different circumstances
+
+    +----------------------+-------------------------------------------------+---------------------------------------------------------------------------+
+    |                      | Interval                                                                                                                    |
+    +                      +-------------------------------------------------+---------------------------------------------------------------------------+
+    |                      | ESP_WIFI_CONNECTIONLESS_INTERVAL_DEFAULT_MODE   | 1 - maximum                                                               |
+    +--------+-------------+-------------------------------------------------+---------------------------------------------------------------------------+
+    | Window | 0           | not used                                                                                                                    |
+    +        +-------------+-------------------------------------------------+---------------------------------------------------------------------------+
+    |        | 1 - maximum | default mode                                    | used periodically (Window < Interval) / used all time (Window ≥ Interval) |
+    +--------+-------------+-------------------------------------------------+---------------------------------------------------------------------------+
+
+Default mode
+*******************************
+
+If `Interval` is `ESP_WIFI_CONNECTIONLESS_INTERVAL_DEFAULT_MODE` with non-zero `Window`, Connectionless Modules Power-saving would work in default mode.
+
+In default mode, RF, PHY, BB would be kept on if no coexistence with non-Wi-Fi protocol.
+
+With coexistence, RF, PHY, BB resources are allocated by coexistence module to Wi-Fi connectionless module and non-Wi-Fi module， using time-division method. In default mode, Wi-Fi connectionless module is allowed to use RF, BB, PHY periodically under a stable performance.
+
+Its recommended to configure Connectionless Modules Power-saving to default mode if there is Wi-Fi connectionless module coexists with non-Wi-Fi module.
+
 {IDF_TARGET_NAME} Wi-Fi Throughput
 -----------------------------------
 

docs/en/api-reference/network/esp_now.rst

@@ -98,6 +98,19 @@ 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()`.
 
+Config ESP-NOW Power-saving Parameter
+--------------------------------------------
+
+Sleep is supported only when {IDF_TARGET_NAME} is configured as station.
+
+Call :cpp:func:`esp_now_set_wake_window()` to configure Window for ESP-NOW RX at sleep. The default value is the maximum, which allowing RX all the time.
+
+If Power-saving is needed for ESP-NOW, call :cpp:func:`esp_wifi_connectionless_module_set_wake_interval()` to configure Interval as well. 
+
+.. only:: SOC_WIFI_SUPPORTED
+
+    Please refer to :ref:`connectionless module power save <connectionless-module-power-save>` to get more detail.
+
 Application Examples
 --------------------
 

docs/zh_CN/api-guides/coexist.rst

@@ -27,13 +27,13 @@ RF 共存
       +       +--------+-----------+-----+------------+-----------+----------+
       |       |SOFTAP  |TX Beacon  |Y    |Y           |Y          |Y         |
       +       +        +-----------+-----+------------+-----------+----------+
-      |       |        |Connecting |Y    |Y           |Y          |Y         |
+      |       |        |Connecting |C1   |C1          |C1         |C1        |
       +       +        +-----------+-----+------------+-----------+----------+
       |       |        |Connected  |C1   |C1          |C1         |C1        |
       +       +--------+-----------+-----+------------+-----------+----------+
-      |       |Sniffer |RX         |C2   |C2          |C2         |C2        |
+      |       |Sniffer |RX         |C1   |C1          |C1         |C1        |
       +       +--------+-----------+-----+------------+-----------+----------+
-      |       |ESP-NOW |RX         |X    |X           |X          |X         |
+      |       |ESP-NOW |RX         |S    |S           |S          |S         |
       +       +        +-----------+-----+------------+-----------+----------+
       |       |        |TX         |Y    |Y           |Y          |Y         |
       +-------+--------+-----------+-----+------------+-----------+----------+
@@ -56,13 +56,13 @@ RF 共存
       +       +--------+-----------+--------+-------------+-----+----------+-----------+
       |       |SOFTAP  |TX Beacon  |Y       |Y            |Y    |Y         |Y          |
       +       +        +-----------+--------+-------------+-----+----------+-----------+
-      |       |        |Connecting |Y       |Y            |Y    |Y         |Y          |
+      |       |        |Connecting |C1      |C1           |C1   |C1        |C1         |
       +       +        +-----------+--------+-------------+-----+----------+-----------+
       |       |        |Connected  |C1      |C1           |C1   |C1        |C1         |
       +       +--------+-----------+--------+-------------+-----+----------+-----------+
-      |       |Sniffer |RX         |C2      |C2           |C2   |C2        |C2         |
+      |       |Sniffer |RX         |C1      |C1           |C1   |C1        |C1         |
       +       +--------+-----------+--------+-------------+-----+----------+-----------+
-      |       |ESP-NOW |RX         |X       |X            |X    |X         |X          |
+      |       |ESP-NOW |RX         |S       |S            |S    |S         |S          |
       +       +        +-----------+--------+-------------+-----+----------+-----------+
       |       |        |TX         |Y       |Y            |Y    |Y         |Y          |
       +-------+--------+-----------+--------+-------------+-----+----------+-----------+
@@ -72,8 +72,8 @@ RF 共存
 
   Y：支持且性能稳定。
   C1：不能保证性能处于稳定状态。
-  C2：sniffer 无法保证丢包率。
   X：不支持。
+  S：在STA模式下支持且性能稳定，否则不支持。
 
 
 共存机制与策略
@@ -152,6 +152,16 @@ RF 共存
 
 共存模块对 Wi-Fi 和 Bluetooth 不同的状态赋予其不同的优先级。每种状态下的优先级并不是一成不变的，例如每 N 个广播事件 (Advertising event) 中会有一个广播事件使用高优先级。如果高优先级的广播事件发生在 Wi-Fi 时间片内，RF 的使用权可能会被 BLE 抢占。
 
+.. only:: SOC_WIFI_SUPPORTED
+
+    Wi-Fi 非连接模块的共存
+    """"""""""""""""""""""""""""
+
+    在一定程度上，某些 Wi-Fi 非连接模块功耗参数 Window 与 Interval 的组合会导致共存模块在 Wi-Fi 时间片外申请共存优先级。这是为了按设定的功耗参数在共存时获取 RF 资源，但这会影响既定的蓝牙性能。
+
+    如果 Wi-Fi 非连接模块功耗参数为默认值时，上述动作不会发生，共存模块会按照性能稳定的模式运行。因此，除非您对特定非连接功耗参数下的共存性能有足够的测试，请在共存场景下将 Wi-Fi 非连接模块功耗参数配置为默认参数。
+
+    请参考 :ref:`非连接模块功耗管理 <connectionless-module-power-save-cn>` 获取更多信息。
 
 如何使用共存功能
 ----------------------------------

docs/zh_CN/api-guides/wifi.rst

@@ -266,6 +266,11 @@ WIFI_EVENT_STA_BEACON_TIMEOUT
 
 如果 station 在 inactive 时间内未收到所连接 AP 的 beacon，将发生 beacon 超时，将引发此事件。inactive 时间通过调用函数 :cpp:func:`esp_wifi_set_inactive_time()` 设置。
 
+WIFI_EVENT_CONNECTIONLESS_MODULE_WAKE_INTERVAL_START
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+非连接模块在 `Interval` 开始时触发此事件。 请参考 :ref:`非连接模块功耗管理 <connectionless-module-power-save-cn>` 。
+
 {IDF_TARGET_NAME} Wi-Fi station 一般情况
 ------------------------------------------------
 下图为 station 模式下的宏观场景，其中包含不同阶段的具体描述：
@@ -1638,6 +1643,81 @@ AP 睡眠
 
 未来，{IDF_TARGET_NAME} AP 将支持所有节能功能。
 
+非连接状态下的休眠
++++++++++++++++++++++++++++++++
+
+非连接状态指的是 :cpp:func:`esp_wifi_start` 至 :cpp:func:`esp_wifi_stop` 期间内，没有建立 Wi-Fi 连接的阶段。
+
+目前, {IDF_TARGET_NAME} Wi-Fi 支持以 station 模式运行时，在非连接状态下休眠。可以通过选项 :ref:`CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE` 配置该功能。
+
+如果打开配置选项 :ref:`CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE`，则在该阶段内，RF, PHY and BB 将在空闲时被关闭，电流将会等同于 Modem-sleep 模式下的休眠电流。
+
+配置选项 :ref:`CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE` 默认情况下将会被打开，共存模式下被 Menuconfig 强制打开。
+
+.. _connectionless-module-power-save-cn:
+
+非连接模块功耗管理
++++++++++++++++++++++++++++++++
+
+非连接模块指的是一些不依赖于 Wi-Fi 连接的 Wi-Fi 模块，例如 ESP-NOW， DPP， FTM。这些模块从 :cpp:func:`esp_wifi_start` 开始工作至 :cpp:func:`esp_wifi_stop` 结束。
+
+目前，ESP-NOW 以 station 模式工作时，既支持在连接状态下休眠，也支持在非连接状态下休眠。
+
+非连接模块发包
+*******************************
+
+对于任何非连接模块，在开启了休眠的任何时间点都可以发包，不需要进行任何额外的配置。
+
+此外，:cpp:func:`esp_wifi_80211_tx` 也在休眠时被支持。
+
+非连接模块收包
+*******************************
+
+对于非连接模块，在开启休眠时如果需要进行收包，需要配置两个参数，分别为 `Window` 和 `Interval`。
+
+在每个 `Interval` 开始时，RF, PHY and BB 将会被打开并保持 `Window` 的时间。非连接模块可以在此时间内收包。
+
+**Interval**
+
+ - 全局只有一个 `Interval` 参数，所有非连接模块共享它。其数值由 API :cpp:func:`esp_wifi_set_connectionless_interval` 配置，单位为毫秒。
+
+ - `Interval` 的默认值为 `ESP_WIFI_CONNECTIONLESS_INTERVAL_DEFAULT_MODE` 。
+
+ - 在 `Interval` 开始时，将会给出 `WIFI_EVENT_CONNECTIONLESS_MODULE_WAKE_INTERVAL_START`_ 事件，由于 `Window` 将在此时开始，可以在此事件内布置发包动作。
+
+ - 在连接状态下，`Interval` 开始的时间点将会与 TBTT 时间点对齐。
+
+**Window**
+
+ - 每个非连接模块在启动后都有其自身的 `Window` 参数，休眠模块将取所有模块 `Window` 的最大值运作。
+
+ - 其数值由 API :cpp:func:`module_name_set_wake_window` 配置，单位为毫秒。
+
+ - 模块 `Window` 的默认值为最大值。
+
+.. table:: 不同 Window 与 Interval 组合下的 RF, PHY and BB 使用情况
+
+    +----------------------+-------------------------------------------------+---------------------------------------------------------------------------+
+    |                      | Interval                                                                                                                    |
+    +                      +-------------------------------------------------+---------------------------------------------------------------------------+
+    |                      | ESP_WIFI_CONNECTIONLESS_INTERVAL_DEFAULT_MODE   | 1 - maximum                                                               |
+    +--------+-------------+-------------------------------------------------+---------------------------------------------------------------------------+
+    | Window | 0           | not used                                                                                                                    |
+    +        +-------------+-------------------------------------------------+---------------------------------------------------------------------------+
+    |        | 1 - maximum | default mode                                    | used periodically (Window < Interval) / used all time (Window ≥ Interval) |
+    +--------+-------------+-------------------------------------------------+---------------------------------------------------------------------------+
+
+默认模式
+*******************************
+
+当 `Interval` 参数被配置为 `ESP_WIFI_CONNECTIONLESS_INTERVAL_DEFAULT_MODE` ，且有非零的 `Window` 参数时，非连接模块功耗管理将会按默认模式运行。
+
+在没有与非 Wi-Fi 协议共存时，RF, PHY and BB 将会在默认模式下被一直打开。
+
+在与非 Wi-Fi 协议共存时，RF, PHY and BB 资源被共存模块分时划给 Wi-Fi 非连接模块和非 Wi-Fi 协议使用。在默认模式下， Wi-Fi 非连接模块被允许周期性使用 RF, PHY and BB ，并且具有稳定性能。
+
+推荐在与非 Wi-Fi 协议共存时将非连接模块功耗管理配置为默认模式。
+
 {IDF_TARGET_NAME} Wi-Fi 吞吐量
 -----------------------------------
 

docs/zh_CN/api-reference/network/esp_now.rst

@@ -98,6 +98,19 @@ ESP-NOW 采用 CCMP 方法保护供应商特定动作帧的安全，具体可参
 
 调用 :cpp:func:`esp_wifi_config_espnow_rate()` 配置指定接口的 ESPNOW 速率。确保在配置速率之前使能接口。这个 API 应该在 :cpp:func:`esp_wifi_start()` 之后调用。
 
+配置 ESP-NOW 功耗参数
+----------------------
+
+当且仅当 {IDF_TARGET_NAME} 配置为 STA 模式时，允许其进行休眠。
+
+进行休眠时，调用 :cpp:func:`esp_now_set_wake_window()` 为 ESP-NOW 收包配置 Window。默认情况下 Window 为最大值，将允许一直收包。
+
+如果对 ESP-NOW 进功耗管理，也需要调用 :cpp:func:`esp_wifi_connectionless_module_set_wake_interval()`。
+
+.. only:: SOC_WIFI_SUPPORTED
+
+    请参考 :ref:`非连接模块功耗管理 <connectionless-module-power-save-cn>` 获取更多信息。
+
 应用示例
 ----------