diff --git a/components/esp_wifi/Kconfig b/components/esp_wifi/Kconfig index f93301f024..de3c6c9f3b 100644 --- a/components/esp_wifi/Kconfig +++ b/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. diff --git a/components/esp_wifi/include/esp_wifi.h b/components/esp_wifi/include/esp_wifi.h index 1e61050042..abb403be44 100644 --- a/components/esp_wifi/include/esp_wifi.h +++ b/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. */ diff --git a/components/esp_wifi/lib b/components/esp_wifi/lib index 69e8def447..f1c5a06856 160000 --- a/components/esp_wifi/lib +++ b/components/esp_wifi/lib @@ -1 +1 @@ -Subproject commit 69e8def447c7f8730dbc92d07629eae68847ea3a +Subproject commit f1c5a06856aba43a4de572ed2d0631cae1e3800a diff --git a/docs/en/api-guides/coexist.rst b/docs/en/api-guides/coexist.rst index 544b9d9a61..b012998fc1 100644 --- a/docs/en/api-guides/coexist.rst +++ b/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 ` to get more detail. How to Use the Coexistence Feature -------------------------------------- diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index ca3300c81e..e24e86af64 100644 --- a/docs/en/api-guides/wifi.rst +++ b/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 `. + {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 ----------------------------------- diff --git a/docs/en/api-reference/network/esp_now.rst b/docs/en/api-reference/network/esp_now.rst index 60eb2a18e1..a5bbd0dad4 100644 --- a/docs/en/api-reference/network/esp_now.rst +++ b/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 ` to get more detail. + Application Examples -------------------- diff --git a/docs/zh_CN/api-guides/coexist.rst b/docs/zh_CN/api-guides/coexist.rst index 1746b480d0..5f9186c268 100644 --- a/docs/zh_CN/api-guides/coexist.rst +++ b/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:`非连接模块功耗管理 ` 获取更多信息。 如何使用共存功能 ---------------------------------- diff --git a/docs/zh_CN/api-guides/wifi.rst b/docs/zh_CN/api-guides/wifi.rst index c1cab9fce9..0fc11d545b 100644 --- a/docs/zh_CN/api-guides/wifi.rst +++ b/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:`非连接模块功耗管理 ` 。 + {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 吞吐量 ----------------------------------- diff --git a/docs/zh_CN/api-reference/network/esp_now.rst b/docs/zh_CN/api-reference/network/esp_now.rst index b6dff688b9..cffc9438e9 100644 --- a/docs/zh_CN/api-reference/network/esp_now.rst +++ b/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:`非连接模块功耗管理 ` 获取更多信息。 + 应用示例 ----------