Merge branch 'bugfix/fix_wifi_espnow_coexist_API_doc' into 'master'

esp_wifi: fix ret when setting channel at wifi not started, fix timer callback

Closes IDF-7270, WIFI-5607, WIFI-5736, and WIFI-3607

See merge request espressif/esp-idf!23782

components/esp_coex/include/esp_coexist_internal.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2018-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2018-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -90,12 +90,6 @@ esp_err_t coex_preference_set(coex_prefer_t prefer);
  */
 uint32_t coex_status_get(void);
 
-/**
- * @brief Set software coexist condition.
- * @return : software coexist condition
- */
-void coex_condition_set(uint32_t type, bool dissatisfy);
-
 /**
  * @brief WiFi requests coexistence.
  *

components/esp_rom/esp32c2/ld/esp32c2.rom.ld

@@ -1773,7 +1773,7 @@ pm_on_probe_resp_rx = 0x40001ecc;
 hal_set_sta_tsf = 0x40001ed0;
 ic_update_sta_tsf = 0x40001ed4;
 ic_tx_pkt = 0x40001ed8;
-pm_send_probe_stop = 0x40001edc;
+//pm_send_probe_stop = 0x40001edc;
 pm_send_probe_start = 0x40001ee0;
 pm_on_coex_schm_process_restart = 0x40001ee4;
 hal_mac_set_rxq_policy = 0x40001ee8;
@@ -1944,7 +1944,7 @@ ieee80211_setup_phy_mode = 0x4000207c;
 ieee80211_sta_is_connected = 0x40002080;
 current_task_is_wifi_task = 0x40002084;
 wifi_get_init_state = 0x40002088;
-ieee80211_timer_process = 0x4000208c;
+/* ieee80211_timer_process = 0x4000208c; */
 /* cnx_coexist_timeout = 0x40002090; */
 /* sta_recv_mgmt = 0x40002094;*/
 ieee80211_send_setup = 0x40002098;

components/esp_wifi/esp32/esp_adapter.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -424,13 +424,6 @@ static IRAM_ATTR uint32_t coex_status_get_wrapper(void)
 #endif
 }
 
-static void coex_condition_set_wrapper(uint32_t type, bool dissatisfy)
-{
-#if CONFIG_SW_COEXIST_ENABLE
-    coex_condition_set(type, dissatisfy);
-#endif
-}
-
 static int coex_wifi_request_wrapper(uint32_t event, uint32_t latency, uint32_t duration)
 {
 #if CONFIG_SW_COEXIST_ENABLE
@@ -657,7 +650,6 @@ wifi_osi_funcs_t g_wifi_osi_funcs = {
     ._coex_enable = coex_enable_wrapper,
     ._coex_disable = coex_disable_wrapper,
     ._coex_status_get = coex_status_get_wrapper,
-    ._coex_condition_set = coex_condition_set_wrapper,
     ._coex_wifi_request = coex_wifi_request_wrapper,
     ._coex_wifi_release = coex_wifi_release_wrapper,
     ._coex_wifi_channel_set = coex_wifi_channel_set_wrapper,

components/esp_wifi/esp32c2/esp_adapter.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -390,13 +390,6 @@ static IRAM_ATTR uint32_t coex_status_get_wrapper(void)
 #endif
 }
 
-static void coex_condition_set_wrapper(uint32_t type, bool dissatisfy)
-{
-#if CONFIG_SW_COEXIST_ENABLE || CONFIG_EXTERNAL_COEX_ENABLE
-    coex_condition_set(type, dissatisfy);
-#endif
-}
-
 static int coex_wifi_request_wrapper(uint32_t event, uint32_t latency, uint32_t duration)
 {
 #if CONFIG_SW_COEXIST_ENABLE || CONFIG_EXTERNAL_COEX_ENABLE
@@ -626,7 +619,6 @@ wifi_osi_funcs_t g_wifi_osi_funcs = {
     ._coex_enable = coex_enable_wrapper,
     ._coex_disable = coex_disable_wrapper,
     ._coex_status_get = coex_status_get_wrapper,
-    ._coex_condition_set = coex_condition_set_wrapper,
     ._coex_wifi_request = coex_wifi_request_wrapper,
     ._coex_wifi_release = coex_wifi_release_wrapper,
     ._coex_wifi_channel_set = coex_wifi_channel_set_wrapper,

components/esp_wifi/esp32c3/esp_adapter.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -407,13 +407,6 @@ static IRAM_ATTR uint32_t coex_status_get_wrapper(void)
 #endif
 }
 
-static void coex_condition_set_wrapper(uint32_t type, bool dissatisfy)
-{
-#if CONFIG_SW_COEXIST_ENABLE || CONFIG_EXTERNAL_COEX_ENABLE
-    coex_condition_set(type, dissatisfy);
-#endif
-}
-
 static int coex_wifi_request_wrapper(uint32_t event, uint32_t latency, uint32_t duration)
 {
 #if CONFIG_SW_COEXIST_ENABLE || CONFIG_EXTERNAL_COEX_ENABLE
@@ -643,7 +636,6 @@ wifi_osi_funcs_t g_wifi_osi_funcs = {
     ._coex_enable = coex_enable_wrapper,
     ._coex_disable = coex_disable_wrapper,
     ._coex_status_get = coex_status_get_wrapper,
-    ._coex_condition_set = coex_condition_set_wrapper,
     ._coex_wifi_request = coex_wifi_request_wrapper,
     ._coex_wifi_release = coex_wifi_release_wrapper,
     ._coex_wifi_channel_set = coex_wifi_channel_set_wrapper,

components/esp_wifi/esp32c6/esp_adapter.c

@@ -396,13 +396,6 @@ static IRAM_ATTR uint32_t coex_status_get_wrapper(void)
 #endif
 }
 
-static void coex_condition_set_wrapper(uint32_t type, bool dissatisfy)
-{
-#if CONFIG_SW_COEXIST_ENABLE || CONFIG_EXTERNAL_COEX_ENABLE
-    coex_condition_set(type, dissatisfy);
-#endif
-}
-
 static int coex_wifi_request_wrapper(uint32_t event, uint32_t latency, uint32_t duration)
 {
 #if CONFIG_SW_COEXIST_ENABLE || CONFIG_EXTERNAL_COEX_ENABLE
@@ -632,7 +625,6 @@ wifi_osi_funcs_t g_wifi_osi_funcs = {
     ._coex_enable = coex_enable_wrapper,
     ._coex_disable = coex_disable_wrapper,
     ._coex_status_get = coex_status_get_wrapper,
-    ._coex_condition_set = coex_condition_set_wrapper,
     ._coex_wifi_request = coex_wifi_request_wrapper,
     ._coex_wifi_release = coex_wifi_release_wrapper,
     ._coex_wifi_channel_set = coex_wifi_channel_set_wrapper,

components/esp_wifi/esp32s2/esp_adapter.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -415,13 +415,6 @@ static IRAM_ATTR uint32_t coex_status_get_wrapper(void)
 #endif
 }
 
-static void coex_condition_set_wrapper(uint32_t type, bool dissatisfy)
-{
-#if CONFIG_EXTERNAL_COEX_ENABLE
-    coex_condition_set(type, dissatisfy);
-#endif
-}
-
 static int coex_wifi_request_wrapper(uint32_t event, uint32_t latency, uint32_t duration)
 {
 #if CONFIG_EXTERNAL_COEX_ENABLE
@@ -653,7 +646,6 @@ wifi_osi_funcs_t g_wifi_osi_funcs = {
     ._coex_enable = coex_enable_wrapper,
     ._coex_disable = coex_disable_wrapper,
     ._coex_status_get = coex_status_get_wrapper,
-    ._coex_condition_set = coex_condition_set_wrapper,
     ._coex_wifi_request = coex_wifi_request_wrapper,
     ._coex_wifi_release = coex_wifi_release_wrapper,
     ._coex_wifi_channel_set = coex_wifi_channel_set_wrapper,

components/esp_wifi/esp32s3/esp_adapter.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -432,13 +432,6 @@ static IRAM_ATTR uint32_t coex_status_get_wrapper(void)
 #endif
 }
 
-static void coex_condition_set_wrapper(uint32_t type, bool dissatisfy)
-{
-#if CONFIG_SW_COEXIST_ENABLE || CONFIG_EXTERNAL_COEX_ENABLE
-    coex_condition_set(type, dissatisfy);
-#endif
-}
-
 static int coex_wifi_request_wrapper(uint32_t event, uint32_t latency, uint32_t duration)
 {
 #if CONFIG_SW_COEXIST_ENABLE || CONFIG_EXTERNAL_COEX_ENABLE
@@ -668,7 +661,6 @@ wifi_osi_funcs_t g_wifi_osi_funcs = {
     ._coex_enable = coex_enable_wrapper,
     ._coex_disable = coex_disable_wrapper,
     ._coex_status_get = coex_status_get_wrapper,
-    ._coex_condition_set = coex_condition_set_wrapper,
     ._coex_wifi_request = coex_wifi_request_wrapper,
     ._coex_wifi_release = coex_wifi_release_wrapper,
     ._coex_wifi_channel_set = coex_wifi_channel_set_wrapper,

components/esp_wifi/include/esp_wifi.h

@@ -584,7 +584,7 @@ esp_err_t esp_wifi_get_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t *bw);
 /**
   * @brief     Set primary/secondary channel of device
   *
-  * @attention 1. This API should be called after esp_wifi_start()
+  * @attention 1. This API should be called after esp_wifi_start() and before esp_wifi_stop()
   * @attention 2. When device is in STA mode, this API should not be called when STA is scanning or connecting to an external AP
   * @attention 3. When device is in softAP mode, this API should not be called when softAP has connected to external STAs
   * @attention 4. When device is in STA+softAP mode, this API should not be called when in the scenarios described above
@@ -599,6 +599,7 @@ esp_err_t esp_wifi_get_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t *bw);
   *    - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
   *    - ESP_ERR_WIFI_IF: invalid interface
   *    - ESP_ERR_INVALID_ARG: invalid argument
+  *    - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start
   */
 esp_err_t esp_wifi_set_channel(uint8_t primary, wifi_second_chan_t second);
 

docs/en/api-guides/coexist.rst

@@ -111,6 +111,8 @@ The RF resource allocation mechanism is based on priority. As shown below, both
     }
 
 
+.. _coexist_policy:
+
 Coexistence Policy
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/en/api-guides/wifi.rst

@@ -1706,7 +1706,11 @@ In maximum power-saving mode, station wakes up in every listen interval to recei
 
 Call ``esp_wifi_set_ps(WIFI_PS_MIN_MODEM)`` to enable Modem-sleep minimum power-saving mode or ``esp_wifi_set_ps(WIFI_PS_MAX_MODEM)`` to enable Modem-sleep maximum power-saving mode after calling :cpp:func:`esp_wifi_init()`. When station connects to AP, Modem-sleep will start. When station disconnects from AP, Modem-sleep will stop.
 
-Call ``esp_wifi_set_ps(WIFI_PS_NONE)`` to disable Modem-sleep entirely. This has much higher power consumption, but provides minimum latency for receiving Wi-Fi data in real time. When Modem-sleep is enabled, received Wi-Fi data can be delayed for as long as the DTIM period (minimum power-saving mode) or the listen interval (maximum power-saving mode). Disabling Modem-sleep entirely is not possible for Wi-Fi and Bluetooth coexist mode.
+Call ``esp_wifi_set_ps(WIFI_PS_NONE)`` to disable Modem-sleep mode entirely. Disabling it increases power consumption, but minimizes the delay in receiving Wi-Fi data in real time. When Modem-sleep mode is enabled, the delay in receiving Wi-Fi data may be the same as the DTIM cycle (minimum power-saving mode) or the listening interval (maximum power-saving mode).
+
+.. only:: SOC_SUPPORT_COEXISTENCE
+
+    Note that in coexist mode, Wi-Fi will remain active only during Wi-Fi time slice, and sleep during non Wi-Fi time slice even if ``esp_wifi_set_ps(WIFI_PS_NONE)`` is called. Please refer to :ref:`coexist policy <coexist_policy>`.
 
 The default Modem-sleep mode is WIFI_PS_MIN_MODEM.
 

docs/zh_CN/api-guides/coexist.rst

@@ -110,6 +110,7 @@ RF 共存
    	  Coexistence -> RF;
     }
 
+.. _coexist_policy-cn:
 
 共存策略
 ^^^^^^^^^^^^^^

docs/zh_CN/api-guides/wifi.rst

@@ -1706,7 +1706,11 @@ Modem-sleep 模式包括最小和最大节能模式。在最小节能模式下
 
 调用 :cpp:func:`esp_wifi_init()` 后，调用 ``esp_wifi_set_ps(WIFI_PS_MIN_MODEM)`` 可使能 Modem-sleep 最小节能模式。调用 ``esp_wifi_set_ps(WIFI_PS_MAX_MODEM)`` 可使能 Modem-sleep 最大节能模式。station 连接到 AP 时，Modem-sleep 模式将启动。station 与 AP 断开连接时，Modem-sleep 模式将停止。
 
-调用 ``esp_wifi_set_ps(WIFI_PS_NONE)`` 可以完全禁用 Modem-sleep 模式。禁用会增大功耗，但可以最大限度减少实时接收 Wi-Fi 数据的延迟。使能 Modem-sleep 时，接收 Wi-Fi 数据的延迟时间可能与 DTIM 周期（最小节能模式）或监听间隔（最大节能模式）相同。在 Wi-Fi 与 Bluetooth LE 共存模式下，无法完全禁用 modem-sleep 模式。
+调用 ``esp_wifi_set_ps(WIFI_PS_NONE)`` 可以完全禁用 Modem-sleep 模式。禁用会增大功耗，但可以最大限度减少实时接收 Wi-Fi 数据的延迟。使能 Modem-sleep 模式时，接收 Wi-Fi 数据的延迟时间可能与 DTIM 周期（最小节能模式）或监听间隔（最大节能模式）相同。
+
+.. only:: SOC_SUPPORT_COEXISTENCE
+
+    注意在共存模式下, 即使调用 ``esp_wifi_set_ps(WIFI_PS_NONE)``, Wi-Fi 也仅会在 Wi-Fi 时间片内保持活动状态, 非 Wi-Fi 时间片内仍然睡眠。请参照 :ref:`共存策略 <coexist_policy-cn>`。
 
 默认的 Modem-sleep 模式是 WIFI_PS_MIN_MODEM。
 

examples/wifi/espnow/main/Kconfig.projbuild

@@ -58,4 +58,29 @@ menu "Example Configuration"
         help
             When enable long range, the PHY rate of ESP32 will be 512Kbps or 256Kbps
 
+    config ESPNOW_ENABLE_POWER_SAVE
+        bool "Enable ESPNOW Power Save"
+        default "n"
+        select ESP_WIFI_STA_DISCONNECTED_PM_ENABLE
+        depends on ESPNOW_WIFI_MODE_STATION
+        help
+            With ESPNOW power save enabled, chip would be able to wakeup and sleep periodically
+            Notice ESP_WIFI_STA_DISCONNECTED_PM_ENABLE is essential at Wi-Fi disconnected
+
+    config ESPNOW_WAKE_WINDOW
+        int "ESPNOW wake window, unit in millisecond"
+        range 0 65535
+        default 50
+        depends on ESPNOW_ENABLE_POWER_SAVE
+        help
+            ESPNOW wake window
+
+    config ESPNOW_WAKE_INTERVAL
+        int "ESPNOW wake interval, unit in millisecond"
+        range 1 65535
+        default 100
+        depends on ESPNOW_ENABLE_POWER_SAVE
+        help
+            ESPNOW wake interval
+
 endmenu

examples/wifi/espnow/main/espnow_example_main.c

@@ -299,8 +299,9 @@ static esp_err_t example_espnow_init(void)
     ESP_ERROR_CHECK( esp_now_init() );
     ESP_ERROR_CHECK( esp_now_register_send_cb(example_espnow_send_cb) );
     ESP_ERROR_CHECK( esp_now_register_recv_cb(example_espnow_recv_cb) );
-#if CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE
-    ESP_ERROR_CHECK( esp_now_set_wake_window(65535) );
+#if CONFIG_ESPNOW_ENABLE_POWER_SAVE
+    ESP_ERROR_CHECK( esp_now_set_wake_window(CONFIG_ESPNOW_WAKE_WINDOW) );
+    ESP_ERROR_CHECK( esp_wifi_connectionless_module_set_wake_interval(CONFIG_ESPNOW_WAKE_INTERVAL) );
 #endif
     /* Set primary master key. */
     ESP_ERROR_CHECK( esp_now_set_pmk((uint8_t *)CONFIG_ESPNOW_PMK) );