Merge branch 'feat/esp_netif_status_event' into 'master'

[esp_netif]: Add support for netif status events

Closes IDF-13357

See merge request espressif/esp-idf!42143

Author: david-cermak

components/esp_netif/include/esp_netif_types.h

@@ -109,6 +109,8 @@ typedef enum {
     IP_EVENT_PPP_GOT_IP,               /*!< PPP interface got IP */
     IP_EVENT_PPP_LOST_IP,              /*!< PPP interface lost IP */
     IP_EVENT_TX_RX,                    /*!< transmitting/receiving data packet */
+    IP_EVENT_NETIF_UP,                 /*!< unified netif status: interface became up */
+    IP_EVENT_NETIF_DOWN,               /*!< unified netif status: interface went down */
 } ip_event_t;
 
 /** @brief IP event base declaration */
@@ -198,6 +200,11 @@ typedef struct {
 } ip_event_tx_rx_t;
 #endif
 
+/** Event structure for IP_EVENT_LINK_UP/DOWN and IP_EVENT_NETIF_UP/DOWN */
+typedef struct {
+    esp_netif_t *esp_netif; /*!< Pointer to the associated netif handle */
+} ip_event_netif_status_t;
+
 typedef enum esp_netif_flags {
     ESP_NETIF_DHCP_CLIENT = 1 << 0,
     ESP_NETIF_DHCP_SERVER = 1 << 1,

components/esp_netif/lwip/esp_netif_lwip.c

@@ -137,13 +137,35 @@ static void netif_unset_mldv6_flag(esp_netif_t *netif);
 
 static esp_err_t esp_netif_destroy_api(esp_netif_api_msg_t *msg);
 
+static inline esp_netif_t* lwip_get_esp_netif(struct netif *netif)
+{
+#if LWIP_ESP_NETIF_DATA
+    return (esp_netif_t*)netif_get_client_data(netif, lwip_netif_client_id);
+#else
+    return (esp_netif_t*)netif->state;
+#endif
+}
+
 static void netif_callback_fn(struct netif* netif, netif_nsc_reason_t reason, const netif_ext_callback_args_t* args)
 {
 #if LWIP_IPV4
     if (reason & DHCP_CB_CHANGE) {
         esp_netif_internal_dhcpc_cb(netif);
     }
 #endif /* LWIP_IPV4 */
+    // Normalize link/admin status: post only NETIF_UP/NETIF_DOWN when the effective state flips
+    if ((reason & (LWIP_NSC_LINK_CHANGED | LWIP_NSC_STATUS_CHANGED)) != 0) {
+        esp_netif_t *esp_netif = lwip_get_esp_netif(netif);
+        if (esp_netif) {
+            bool now_up = esp_netif_is_netif_up(esp_netif);
+            if (now_up != esp_netif->last_status_up) {
+                ip_event_netif_status_t evt = { .esp_netif = esp_netif };
+                esp_event_post(IP_EVENT, now_up ? IP_EVENT_NETIF_UP : IP_EVENT_NETIF_DOWN,
+                               &evt, sizeof(evt), 0);
+                esp_netif->last_status_up = now_up;
+            }
+        }
+    }
 #if LWIP_IPV6
     if ((reason & LWIP_NSC_IPV6_ADDR_STATE_CHANGED) && (args != NULL)) {
         s8_t addr_idx = args->ipv6_addr_state_changed.addr_index;
@@ -395,15 +417,6 @@ esp_netif_t *esp_netif_get_default_netif(void)
     return s_last_default_esp_netif;
 }
 
-static inline esp_netif_t* lwip_get_esp_netif(struct netif *netif)
-{
-#if LWIP_ESP_NETIF_DATA
-    return (esp_netif_t*)netif_get_client_data(netif, lwip_netif_client_id);
-#else
-    return (esp_netif_t*)netif->state;
-#endif
-}
-
 static inline void lwip_set_esp_netif(struct netif *netif, esp_netif_t* esp_netif)
 {
 #if LWIP_ESP_NETIF_DATA

components/esp_netif/lwip/esp_netif_lwip_internal.h

@@ -99,6 +99,7 @@ struct esp_netif_obj {
     // event translation
     ip_event_t get_ip_event;
     ip_event_t lost_ip_event;
+    bool last_status_up;   // last effective up/down state for unified status event
 #ifdef CONFIG_ESP_NETIF_REPORT_DATA_TRAFFIC
     bool tx_rx_events_enabled;
 #endif

components/esp_netif/test_apps/test_app_esp_netif/main/esp_netif_test_lwip.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Unlicense OR CC0-1.0
  */
@@ -18,6 +18,8 @@
 #include "memory_checks.h"
 #include "lwip/netif.h"
 #include "esp_netif_test.h"
+#include "esp_event.h"
+#include "freertos/semphr.h"
 
 TEST_GROUP(esp_netif);
 
@@ -147,6 +149,87 @@ TEST(esp_netif, find_netifs)
     }
 }
 
+static esp_err_t dummy_transmit(void* hd, void *buf, size_t length)
+{
+    return ESP_OK;
+}
+
+static SemaphoreHandle_t s_netif_up_sem;
+static SemaphoreHandle_t s_netif_down_sem;
+static volatile int s_netif_up_count;
+static volatile int s_netif_down_count;
+
+static void netif_status_evt_handler(void *arg, esp_event_base_t base, int32_t id, void *data)
+{
+    (void)arg; (void)base; (void)data;
+    if (id == IP_EVENT_NETIF_UP) {
+        s_netif_up_count++;
+        if (s_netif_up_sem) {
+            xSemaphoreGive(s_netif_up_sem);
+        }
+    } else if (id == IP_EVENT_NETIF_DOWN) {
+        s_netif_down_count++;
+        if (s_netif_down_sem) {
+            xSemaphoreGive(s_netif_down_sem);
+        }
+    }
+}
+
+TEST(esp_netif, unified_netif_status_event)
+{
+    test_case_uses_tcpip();
+    TEST_ESP_OK(esp_event_loop_create_default());
+
+    s_netif_up_sem = xSemaphoreCreateBinary();
+    s_netif_down_sem = xSemaphoreCreateBinary();
+    TEST_ASSERT_NOT_NULL(s_netif_up_sem);
+    TEST_ASSERT_NOT_NULL(s_netif_down_sem);
+    s_netif_up_count = 0;
+    s_netif_down_count = 0;
+
+    TEST_ESP_OK(esp_event_handler_register(IP_EVENT, IP_EVENT_NETIF_UP, &netif_status_evt_handler, NULL));
+    TEST_ESP_OK(esp_event_handler_register(IP_EVENT, IP_EVENT_NETIF_DOWN, &netif_status_evt_handler, NULL));
+
+    // Create a simple netif (no real driver needed)
+    esp_netif_driver_ifconfig_t driver_config = { .handle = (void*)1, .transmit = dummy_transmit };
+    esp_netif_inherent_config_t base_netif_config = { .if_key = "if_status", .if_desc = "if_status" };
+    esp_netif_config_t cfg = { .base = &base_netif_config, .stack = ESP_NETIF_NETSTACK_DEFAULT_WIFI_STA, .driver = &driver_config };
+    esp_netif_t *netif = esp_netif_new(&cfg);
+    TEST_ASSERT_NOT_NULL(netif);
+
+    // Bring interface up (should emit exactly one NETIF_UP)
+    esp_netif_action_start(netif, NULL, 0, NULL);
+    esp_netif_action_connected(netif, NULL, 0, NULL);
+    TEST_ASSERT_EQUAL(pdTRUE, xQueueSemaphoreTake(s_netif_up_sem, pdMS_TO_TICKS(1000)));
+    vTaskDelay(pdMS_TO_TICKS(50));
+    TEST_ASSERT_EQUAL(1, s_netif_up_count);
+    TEST_ASSERT_EQUAL(0, s_netif_down_count);
+
+    // Bring interface down (should emit exactly one NETIF_DOWN)
+    esp_netif_action_disconnected(netif, NULL, 0, NULL);
+    TEST_ASSERT_EQUAL(pdTRUE, xQueueSemaphoreTake(s_netif_down_sem, pdMS_TO_TICKS(1000)));
+    vTaskDelay(pdMS_TO_TICKS(50));
+    TEST_ASSERT_EQUAL(1, s_netif_down_count);
+    TEST_ASSERT_EQUAL(1, s_netif_up_count);
+
+    // Bring up again (should increment up count to 2)
+    esp_netif_action_connected(netif, NULL, 0, NULL);
+    TEST_ASSERT_EQUAL(pdTRUE, xQueueSemaphoreTake(s_netif_up_sem, pdMS_TO_TICKS(1000)));
+    vTaskDelay(pdMS_TO_TICKS(50));
+    TEST_ASSERT_EQUAL(2, s_netif_up_count);
+    TEST_ASSERT_EQUAL(1, s_netif_down_count);
+
+    // Cleanup
+    TEST_ESP_OK(esp_event_handler_unregister(IP_EVENT, IP_EVENT_NETIF_UP, &netif_status_evt_handler));
+    TEST_ESP_OK(esp_event_handler_unregister(IP_EVENT, IP_EVENT_NETIF_DOWN, &netif_status_evt_handler));
+    vSemaphoreDelete(s_netif_up_sem);
+    vSemaphoreDelete(s_netif_down_sem);
+    s_netif_up_sem = s_netif_down_sem = NULL;
+
+    esp_netif_destroy(netif);
+    TEST_ESP_OK(esp_event_loop_delete_default());
+}
+
 #ifdef CONFIG_ESP_WIFI_ENABLED
 /*
  * This test creates a default WiFi station and checks all possible transitions
@@ -438,11 +521,6 @@ TEST(esp_netif, get_set_hostname)
 }
 #endif // CONFIG_ESP_WIFI_ENABLED
 
-static esp_err_t dummy_transmit(void* hd, void *buf, size_t length)
-{
-    return ESP_OK;
-}
-
 /*
  * This test validates the route priority of multiple netifs. It checks that the default route (default netif)
  * is set correctly for the netifs according to their `route_prio` value and `link_up` state.
@@ -610,6 +688,7 @@ TEST_GROUP_RUNNER(esp_netif)
 #endif
     RUN_TEST_CASE(esp_netif, route_priority)
     RUN_TEST_CASE(esp_netif, set_get_dnsserver)
+    RUN_TEST_CASE(esp_netif, unified_netif_status_event)
 }
 
 void app_main(void)

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

@@ -338,6 +338,31 @@ The event data structure, :cpp:class:`ip_event_tx_rx_t`, contains the following
 - :cpp:member:`ip_event_tx_rx_t::len`: Length of the data frame.
 - :cpp:member:`ip_event_tx_rx_t::esp_netif`: The network interface on which the packet was sent or received.
 
+IP Events: Netif Status (Unified)
+---------------------------------
+
+ESP-NETIF emits unified status events when an interface becomes usable for L3 traffic or goes down. These are derived from the lwIP extended netif callbacks and posted on ``IP_EVENT``:
+
+- ``IP_EVENT_NETIF_UP`` / ``IP_EVENT_NETIF_DOWN``
+
+ESP-IDF normalizes link and administrative state changes into these two events (including PPP). Subscribe as follows:
+
+.. code-block:: c
+
+    static void netif_status_handler(void *arg, esp_event_base_t base, int32_t id, void *data)
+    {
+        const ip_event_netif_status_t *evt = (const ip_event_netif_status_t *)data;
+        ESP_LOGI("netif", "status %s on %s", (id == IP_EVENT_NETIF_UP) ? "UP" : "DOWN", esp_netif_get_desc(evt->esp_netif));
+    }
+
+    esp_event_handler_register(IP_EVENT, IP_EVENT_NETIF_UP, &netif_status_handler, NULL);
+    esp_event_handler_register(IP_EVENT, IP_EVENT_NETIF_DOWN, &netif_status_handler, NULL);
+
+Event Data Structure
+^^^^^^^^^^^^^^^^^^^^
+
+The event data structure is :cpp:type:`ip_event_netif_status_t`, which contains the ``esp_netif`` handle of the interface that changed state.
+
 
 .. _esp_netif_api_reference: