Merge branch 'fix/netif_enable_lostip_timer' into 'master'

[esp_netif]: Enable/disable the lost-ip-timer explicitely

Closes IDF-10922

See merge request espressif/esp-idf!42044

components/esp_netif/Kconfig

@@ -1,17 +1,24 @@
 menu "ESP NETIF Adapter"
 
+    config ESP_NETIF_LOST_IP_TIMER_ENABLE
+        bool "Enable IPv4 lost IP event timer"
+        default y
+        help
+            Enable raising LOST_IP events using a timer when the IPv4 address becomes invalid.
+            When disabled, the timer is not started and LOST_IP events are not posted.
+            The delay is configured by ESP_NETIF_IP_LOST_TIMER_INTERVAL.
+
     config ESP_NETIF_IP_LOST_TIMER_INTERVAL
         int "IP Address lost timer interval (seconds)"
         range 0 65535
         default 120
         help
-            The value of 0 indicates the IP lost timer is disabled, otherwise the timer is enabled.
-
             The IP address may be lost because of some reasons, e.g. when the station disconnects
             from soft-AP, or when DHCP IP renew fails etc. If the IP lost timer is enabled, it will
             be started every time the IP is lost. Event SYSTEM_EVENT_STA_LOST_IP will be raised if
-            the timer expires. The IP lost timer is stopped if the station get the IP again before
-            the timer expires.
+            the timer expires. The IP lost timer is stopped if the station gets the IP again before
+            the timer expires. For backward compatibility, setting the interval to 0 disables the
+            timer as well.
 
     config ESP_NETIF_PROVIDE_CUSTOM_IMPLEMENTATION
         bool "Use only ESP-NETIF headers"

components/esp_netif/lwip/esp_netif_lwip.c

@@ -1589,14 +1589,16 @@ static esp_err_t esp_netif_start_ip_lost_timer(esp_netif_t *esp_netif)
         return ESP_OK;
     }
 
+#if CONFIG_ESP_NETIF_LOST_IP_TIMER_ENABLE
     if ( netif && (CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL > 0)) {
         esp_netif->timer_running = true;
         sys_timeout(CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL * 1000, esp_netif_ip_lost_timer, (void *)esp_netif);
         ESP_LOGD(TAG, "if%p start ip lost tmr: interval=%d", esp_netif, CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL);
         return ESP_OK;
     }
+#endif
 
-    ESP_LOGD(TAG, "if%p start ip lost tmr: no need start because netif=%p interval=%d ip=%" PRIx32,
+    ESP_LOGD(TAG, "if%p start ip lost tmr: disabled or not needed (netif=%p interval=%d ip=%" PRIx32 ")",
              esp_netif, netif, (CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL), ip_info_old->ip.addr);
 
     return ESP_OK;

docs/en/api-guides/wifi.rst

@@ -320,7 +320,7 @@ IP_EVENT_STA_LOST_IP
 
 This event arises when the IPV4 address becomes invalid.
 
-IP_EVENT_STA_LOST_IP does not arise immediately after the Wi-Fi disconnects. Instead, it starts an IPV4 address lost timer. If the IPV4 address is got before ip lost timer expires, IP_EVENT_STA_LOST_IP does not happen. Otherwise, the event arises when the IPV4 address lost timer expires.
+IP_EVENT_STA_LOST_IP does not arise immediately after the Wi-Fi disconnects. Instead, it starts an IPV4 address lost timer (configurable via :ref:`CONFIG_ESP_NETIF_LOST_IP_TIMER_ENABLE` and :ref:`CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL`). If the IPV4 address is got before the timer expires, IP_EVENT_STA_LOST_IP does not happen. Otherwise, the event arises when the IPV4 address lost timer expires.
 
 Generally, the application can ignore this event, because it is just a debug event to inform that the IPV4 address is lost.
 

docs/en/api-reference/network/esp_netif.rst

@@ -137,7 +137,9 @@ Registering event handlers is crucial due to the asynchronous nature of networki
 
 .. note::
 
-    Lost IP events are triggered by a timer configurable by :ref:`CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL`. The timer is started upon losing the IP address and the event will be raised after the configured interval, which is 120 s by default. The event could be disabled when setting the interval to 0.
+    Lost IP events are triggered by a timer that can be enabled or disabled by :ref:`CONFIG_ESP_NETIF_LOST_IP_TIMER_ENABLE`,
+    with the delay configured by :ref:`CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL`. The timer is started upon losing the IP address, and the event is raised after the configured interval (120 s by default).
+    For backward compatibility, setting the interval to 0 also disables the timer.
 
 .. _esp-netif structure:
 

docs/zh_CN/api-guides/wifi.rst

@@ -319,7 +319,7 @@ IP_EVENT_STA_LOST_IP
 
 当 IPV4 地址失效时，将引发此事件。
 
-此事件不会在 Wi-Fi 断连后立刻出现。Wi-Fi 连接断开后，首先将启动一个 IPV4 地址丢失计时器，如果 station 在该计时器超时之前成功获取了 IPV4 地址，则不会发生此事件。否则，此事件将在计时器超时时发生。
+此事件不会在 Wi-Fi 断连后立刻出现。Wi-Fi 连接断开后，首先将启动一个 IPV4 地址丢失计时器（可通过 :ref:`CONFIG_ESP_NETIF_LOST_IP_TIMER_ENABLE` 与 :ref:`CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL` 配置）。如果 station 在该计时器超时之前成功获取了 IPV4 地址，则不会发生此事件。否则，此事件将在计时器超时时发生。
 
 一般来说，应用程序可忽略此事件。这只是一个调试事件，主要使应用程序获知 IPV4 地址已丢失。
 

docs/zh_CN/api-reference/network/esp_netif.rst

@@ -137,7 +137,9 @@ IP 事件
 
 .. note::
 
-    丢失 IP 事件由一个可配置的定时器触发，配置项为 :ref:`CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL`。当 IP 地址丢失时定时器启动，事件将在配置的时间间隔后触发，默认值为 120 秒。将时间间隔设置为 0 时可禁用该事件。
+    丢失 IP 事件由一个可配置的定时器触发，可通过 :ref:`CONFIG_ESP_NETIF_LOST_IP_TIMER_ENABLE` 启用或禁用，
+    延迟由 :ref:`CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL` 配置。当 IP 地址丢失时定时器启动，事件将在配置的
+    时间间隔后触发（默认 120 秒）。为保持向后兼容，将时间间隔设置为 0 也会禁用该定时器。
 
 .. _esp-netif structure: