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 'bugfix/publish_wifi_connectionless_feature' into 'master'

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

Closes BT-2595 和 WIFI-4822

See merge request espressif/esp-idf!20600
This commit is contained in:
Liu Ning 2022-11-11 19:40:15 +08:00
commit 6bb28c4cdc
9 changed files with 225 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
components/esp_wifi/Kconfig
View File

@ -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.

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

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

2
components/esp_wifi/lib

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

25
docs/en/api-guides/coexist.rst
View File

@ -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
--------------------------------------

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

@ -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
-----------------------------------

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

@ -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
--------------------

24
docs/zh_CN/api-guides/coexist.rst
View File

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

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

@ -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 吞吐量
-----------------------------------

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

@ -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>` 获取更多信息。
应用示例
----------