fix(examples): Split two station example into local/remote sources

Author: david-cermak

components/esp_wifi_remote/examples/two_stations/README.md

@@ -3,15 +3,48 @@
 ## How to use this example
 
 * Run `server` example as the slave project (communication coprocessor)
-* Configure both the server and the client with mutual keys/certs as described in [mqtt example](../mqtt/README.md)
+* Select the backend solution
+  - (in case of EPPP configure both the server and the client with mutual keys/certs as described in [mqtt example](../mqtt/README.md))
 * Configure SSID and Password for two access points
   - one for local Wi-Fi (using the Wi-Fi library on the chip itself)
   - the second one for remote Wi-Fi (using the network offloading -- communication coprocessor)
 * Build and run the example
 
-## Note
+## Wi-Fi types limitation
+
+The `esp_wifi_remote` component faces type name conflicts when used alongside local Wi-Fi functionality. Both APIs use identical type names (e.g., `wifi_config_t`) but with different definitions for different hardware targets.
+
+### The Solution: Separate Compilation Units
+
+The component requires **separate compilation units** for local and remote Wi-Fi code:
+
+```c
+// two_stations.c - Local Wi-Fi only
+#include "esp_wifi.h"
+
+// remote_station.c - Remote Wi-Fi only
+#include "injected/esp_wifi.h"  // SLAVE_ prefixed types
+#include "esp_wifi_remote.h"
+```
+
+### How It Works
+
+Wi-Fi remote provides generated "injected" headers with slave-specific types by transforming SOC capabilities:
+
+```python
+# generate_and_check.py transforms:
+SOC_WIFI_ → SLAVE_SOC_WIFI_
+IDF_TARGET_ → SLAVE_IDF_TARGET_
+```
+
+This allows the same Wi-Fi types to coexist with different definitions based on the target hardware.
+
+### Best Practices
+
+- Include injected headers before `esp_wifi_remote.h` in remote Wi-Fi files
+- Keep local and remote Wi-Fi code in separate `.c` files
+- Use function declarations to call between compilation units
 
-This example supports EPPP RPC library with both UART and SPI transport options. Configure the transport method and pins using `idf.py menuconfig` under "WiFi Remote" settings.
 
 ## Example output
 
@@ -57,3 +90,4 @@ I (7381) rpc_client: WIFI GW:192.168.32.3
 I (7381) rpc_client: WIFI mask:255.255.254.0
 I (7381) two wifi stations: connected to ap SSID:EspressifSystems
 I (7391) main_task: Returned from app_main()
+```

components/esp_wifi_remote/examples/two_stations/main/CMakeLists.txt

@@ -1,2 +1,2 @@
-idf_component_register(SRCS "two_stations.c"
+idf_component_register(SRCS "two_stations.c" "remote_station.c"
                     INCLUDE_DIRS ".")

components/esp_wifi_remote/examples/two_stations/main/remote_station.c

@@ -0,0 +1,78 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+#include "freertos/FreeRTOS.h"
+#include "freertos/event_groups.h"
+// It is important to include *injected* headers before *esp-wifi-remote*
+// to use **SOC_SLAVE** Wi-Fi types in API typedefs, enums, structs
+#include "injected/esp_wifi.h"
+#include "esp_wifi_remote.h"
+#include "esp_event.h"
+#include "esp_log.h"
+
+#define WIFI_REMOTE_CONNECTED_BIT BIT2
+#define WIFI_REMOTE_FAIL_BIT      BIT3
+#define WIFI_REMOTE_BITS (WIFI_REMOTE_CONNECTED_BIT | WIFI_REMOTE_FAIL_BIT)
+#define EXAMPLE_ESP_MAXIMUM_RETRY  CONFIG_ESP_MAXIMUM_RETRY
+
+static const char *TAG_remote = "two_stations_remote";
+static int s_retry_num = 0;
+static EventGroupHandle_t s_wifi_event_group;
+
+static void event_handler_remote(void* arg, esp_event_base_t event_base,
+                                int32_t event_id, void* event_data)
+{
+    if (event_base == WIFI_REMOTE_EVENT && event_id == WIFI_EVENT_STA_START) {
+        esp_wifi_remote_connect();
+    } else if (event_base == WIFI_REMOTE_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
+        if (s_retry_num < EXAMPLE_ESP_MAXIMUM_RETRY) {
+            esp_wifi_remote_connect();
+            s_retry_num++;
+            ESP_LOGI(TAG_remote, "retry to connect to the AP");
+        } else {
+            xEventGroupSetBits(s_wifi_event_group, WIFI_REMOTE_FAIL_BIT);
+        }
+        ESP_LOGI(TAG_remote,"connect to the AP fail");
+    } else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
+        ip_event_got_ip_t* event = (ip_event_got_ip_t*) event_data;
+        ESP_LOGI(TAG_remote, "Remote Wi-Fi got IP:" IPSTR, IP2STR(&event->ip_info.ip));
+        s_retry_num = 0;
+        xEventGroupSetBits(s_wifi_event_group, WIFI_REMOTE_CONNECTED_BIT);
+    }
+}
+
+void wifi_init_remote_sta(void)
+{
+    esp_wifi_remote_create_default_sta();
+
+    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
+    ESP_ERROR_CHECK(esp_wifi_remote_init(&cfg));
+
+    ESP_ERROR_CHECK(esp_event_handler_register(WIFI_REMOTE_EVENT, ESP_EVENT_ANY_ID, event_handler_remote, NULL));
+    ESP_ERROR_CHECK(esp_event_handler_register(IP_EVENT, IP_EVENT_STA_GOT_IP, event_handler_remote, NULL));
+
+    wifi_config_t wifi_config = {
+        .sta = {
+            .ssid = CONFIG_ESP_WIFI_REMOTE_SSID,
+            .password = CONFIG_ESP_WIFI_REMOTE_PASSWORD,
+        },
+    };
+    ESP_ERROR_CHECK(esp_wifi_remote_set_mode(WIFI_MODE_STA));
+    ESP_ERROR_CHECK(esp_wifi_remote_set_config(WIFI_IF_STA, &wifi_config));
+    ESP_ERROR_CHECK(esp_wifi_remote_start());
+
+    ESP_LOGI(TAG_remote, "wifi_init_remote_sta finished.");
+
+    /* Waiting until either the connection is established the same way for REMOTE wifi */
+    EventBits_t bits = xEventGroupWaitBits(s_wifi_event_group, WIFI_REMOTE_BITS, pdFALSE, pdFALSE, portMAX_DELAY);
+
+    if (bits & WIFI_REMOTE_CONNECTED_BIT) {
+        ESP_LOGI(TAG_remote, "connected to ap SSID:%s", CONFIG_ESP_WIFI_REMOTE_SSID);
+    } else if (bits & WIFI_REMOTE_FAIL_BIT) {
+        ESP_LOGW(TAG_remote, "Failed to connect to SSID:%s", CONFIG_ESP_WIFI_REMOTE_SSID);
+    } else {
+        ESP_LOGE(TAG_remote, "UNEXPECTED EVENT");
+    }
+}

components/esp_wifi_remote/examples/two_stations/main/two_stations.c

@@ -3,14 +3,6 @@
  *
  * SPDX-License-Identifier: Unlicense OR CC0-1.0
  */
-/* WiFi station Example
-
-   This example code is in the Public Domain (or CC0 licensed, at your option.)
-
-   Unless required by applicable law or agreed to in writing, this
-   software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-   CONDITIONS OF ANY KIND, either express or implied.
-*/
 #include <string.h>
 #include "freertos/FreeRTOS.h"
 #include "freertos/event_groups.h"
@@ -19,7 +11,6 @@
 #include "esp_event.h"
 #include "esp_log.h"
 #include "nvs_flash.h"
-#include "esp_wifi_remote.h"
 #include "console_ping.h"
 #include "iperf_cmd.h"
 
@@ -29,14 +20,20 @@
 #define WIFI_CONNECTED_BIT BIT0
 #define WIFI_FAIL_BIT      BIT1
 #define WIFI_BITS (WIFI_CONNECTED_BIT | WIFI_FAIL_BIT)
-#define WIFI_REMOTE_CONNECTED_BIT BIT2
-#define WIFI_REMOTE_FAIL_BIT      BIT3
-#define WIFI_REMOTE_BITS (WIFI_REMOTE_CONNECTED_BIT | WIFI_REMOTE_FAIL_BIT)
 #define EXAMPLE_ESP_MAXIMUM_RETRY  CONFIG_ESP_MAXIMUM_RETRY
 
 static int s_retry_num = 0;
 static EventGroupHandle_t s_wifi_event_group;
 
+#if CONFIG_ESP_WIFI_REMOTE_ENABLE
+/* Remote Wi-Fi is defined in another compilation unit,
+ * as wifi_remote API uses the same type names as local WiFi
+ * and since the types might be slightly different for different
+ * targets, we cannot combine both in a single compilation unit
+ */
+void wifi_init_remote_sta(void);
+#endif
+
 #if CONFIG_ESP_WIFI_LOCAL_ENABLE
 static const char *TAG_local = "two_stations_local";
 
@@ -67,32 +64,6 @@ static void event_handler(void* arg, esp_event_base_t event_base,
 }
 #endif
 
-#if CONFIG_ESP_WIFI_REMOTE_ENABLE
-static const char *TAG_remote = "two_stations_remote";
-
-static void event_handler_remote(void* arg, esp_event_base_t event_base,
-                                int32_t event_id, void* event_data)
-{
-    if (event_base == WIFI_REMOTE_EVENT && event_id == WIFI_EVENT_STA_START) {
-        esp_wifi_remote_connect();
-    } else if (event_base == WIFI_REMOTE_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
-        if (s_retry_num < EXAMPLE_ESP_MAXIMUM_RETRY) {
-            esp_wifi_remote_connect();
-            s_retry_num++;
-            ESP_LOGI(TAG_remote, "retry to connect to the AP");
-        } else {
-            xEventGroupSetBits(s_wifi_event_group, WIFI_REMOTE_FAIL_BIT);
-        }
-        ESP_LOGI(TAG_remote,"connect to the AP fail");
-    } else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
-        ip_event_got_ip_t* event = (ip_event_got_ip_t*) event_data;
-        ESP_LOGI(TAG_remote, "Remote Wi-Fi got IP:" IPSTR, IP2STR(&event->ip_info.ip));
-        s_retry_num = 0;
-        xEventGroupSetBits(s_wifi_event_group, WIFI_REMOTE_CONNECTED_BIT);
-    }
-}
-#endif
-
 static void init_system_components(void)
 {
     s_wifi_event_group = xEventGroupCreate();
@@ -137,42 +108,6 @@ static void wifi_init_sta(void)
 }
 #endif
 
-#if CONFIG_ESP_WIFI_REMOTE_ENABLE
-static void wifi_init_remote_sta(void)
-{
-    esp_wifi_remote_create_default_sta();
-
-    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
-    ESP_ERROR_CHECK(esp_wifi_remote_init(&cfg));
-
-    ESP_ERROR_CHECK(esp_event_handler_register(WIFI_REMOTE_EVENT, ESP_EVENT_ANY_ID, event_handler_remote, NULL));
-    ESP_ERROR_CHECK(esp_event_handler_register(IP_EVENT, IP_EVENT_STA_GOT_IP, event_handler_remote, NULL));
-
-    wifi_config_t wifi_config = {
-        .sta = {
-            .ssid = CONFIG_ESP_WIFI_REMOTE_SSID,
-            .password = CONFIG_ESP_WIFI_REMOTE_PASSWORD,
-        },
-    };
-    ESP_ERROR_CHECK(esp_wifi_remote_set_mode(WIFI_MODE_STA));
-    ESP_ERROR_CHECK(esp_wifi_remote_set_config(WIFI_IF_STA, &wifi_config));
-    ESP_ERROR_CHECK(esp_wifi_remote_start());
-
-    ESP_LOGI(TAG_remote, "wifi_init_remote_sta finished.");
-
-    /* Waiting until either the connection is established the same way for REMOTE wifi */
-    EventBits_t bits = xEventGroupWaitBits(s_wifi_event_group, WIFI_REMOTE_BITS, pdFALSE, pdFALSE, portMAX_DELAY);
-
-    if (bits & WIFI_REMOTE_CONNECTED_BIT) {
-        ESP_LOGI(TAG_remote, "connected to ap SSID:%s", CONFIG_ESP_WIFI_REMOTE_SSID);
-    } else if (bits & WIFI_REMOTE_FAIL_BIT) {
-        ESP_LOGW(TAG_remote, "Failed to connect to SSID:%s", CONFIG_ESP_WIFI_REMOTE_SSID);
-    } else {
-        ESP_LOGE(TAG_remote, "UNEXPECTED EVENT");
-    }
-}
-#endif
-
 void app_main(void)
 {
     esp_log_level_set("*", ESP_LOG_INFO);