Skip to content

Commit

Permalink
Merge branch 'bugfix/publish_wifi_connectionless_feature' into 'master'
Browse files Browse the repository at this point in the history
esp_wifi: fix connectionless issues and add connectionless power-save documenation

Closes BT-2595 和 WIFI-4822

See merge request espressif/esp-idf!20600
  • Loading branch information
Espressif-liuuuu committed Nov 11, 2022
2 parents 69926e6 + b153469 commit 6bb28c4
Show file tree
Hide file tree
Showing 9 changed files with 225 additions and 16 deletions.
2 changes: 2 additions & 0 deletions components/esp_wifi/Kconfig
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions components/esp_wifi/include/esp_wifi.h
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand All @@ -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.
*/
Expand Down
25 changes: 17 additions & 8 deletions docs/en/api-guides/coexist.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
+-------+--------+-----------+-----+------------+-----------+----------+
Expand All @@ -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 |
+-------+--------+-----------+--------+-------------+-----+----------+-----------+
Expand All @@ -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
------------------------------------------------
Expand Down Expand Up @@ -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
--------------------------------------
Expand Down
80 changes: 80 additions & 0 deletions docs/en/api-guides/wifi.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
-----------------------------------

Expand Down
13 changes: 13 additions & 0 deletions docs/en/api-reference/network/esp_now.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------------------

Expand Down
24 changes: 17 additions & 7 deletions docs/zh_CN/api-guides/coexist.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
+-------+--------+-----------+-----+------------+-----------+----------+
Expand All @@ -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 |
+-------+--------+-----------+--------+-------------+-----+----------+-----------+
Expand All @@ -72,8 +72,8 @@ RF 共存

Y:支持且性能稳定。
C1:不能保证性能处于稳定状态。
C2:sniffer 无法保证丢包率。
X:不支持。
S:在STA模式下支持且性能稳定,否则不支持。


共存机制与策略
Expand Down Expand Up @@ -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>` 获取更多信息。

如何使用共存功能
----------------------------------
Expand Down
Loading

0 comments on commit 6bb28c4

Please sign in to comment.