Merge branch 'bugfix/publish_wifi_connectionless_feature' into 'master'

esp_wifi: fix connectionless issues and add connectionless power-save documenation

Closes BT-2595 和 WIFI-4822

See merge request espressif/esp-idf!20600

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.
   */

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>` 获取更多信息。
 
 如何使用共存功能
 ----------------------------------