Merge branch 'feat/usb_4g_through_rndis' into 'master'

feat(rndis): add usb rndis example

See merge request ae_group/esp-iot-solution!1205

Author: lijunru-hub

.github/workflows/upload_component.yml

@@ -56,6 +56,7 @@ jobs:
             components/extended_vfs;
             components/gprof;
             components/i2c_bus;
+            components/iot_eth;
             components/ir/ir_learn;
             components/keyboard_button;
             components/knob;
@@ -95,6 +96,7 @@ jobs:
             components/usb/iot_usbh_modem;
             components/usb/usb_device_uac;
             components/usb/usb_device_uvc;
+            components/usb/iot_usbh_rndis;
             components/usb/usb_stream;
             components/utilities/adc_tp_calibration;
             components/utilities/xz;

.gitlab/ci/build.yml

@@ -969,6 +969,19 @@ build_example_usb_host_usb_msc_ota:
   variables:
     EXAMPLE_DIR: examples/usb/host/usb_msc_ota
 
+build_example_usb_host_usb_rndis_4g_module:
+  extends:
+    - .build_examples_template
+    - .rules:build:example_usb_host_usb_rndis_4g_module
+  parallel:
+    matrix:
+      - IMAGE: espressif/idf:release-v5.1
+      - IMAGE: espressif/idf:release-v5.2
+      - IMAGE: espressif/idf:release-v5.3
+      - IMAGE: espressif/idf:release-v5.4
+  variables:
+    EXAMPLE_DIR: examples/usb/host/usb_rndis_4g_module
+
 build_example_usb_otg_usb_host_device_mode_manual_switch:
   extends:
     - .build_examples_template
@@ -1597,6 +1610,14 @@ build_components_usb_esp_msc_ota_test_apps:
     IMAGE: espressif/idf:release-v5.1
     EXAMPLE_DIR: components/usb/esp_msc_ota/test_apps
 
+build_components_usb_iot_usbh_rndis_test_apps:
+  extends:
+    - .build_examples_template
+    - .rules:build:components_usb_iot_usbh_rndis_test_apps
+    - .build_idf_version_greater_equal_v5_0
+  variables:
+    EXAMPLE_DIR: components/usb/iot_usbh_rndis/test_apps
+
 build_components_usb_usb_stream_test_apps:
   extends:
     - .build_examples_template

.gitlab/ci/rules.yml

@@ -315,12 +315,20 @@
   - "components/usb/iot_usbh_modem/**/*"
   - "tools/cmake_utilities/package_manager.cmake"
 
+.patterns-components_usb_usb_host_rndis_test_apps: &patterns-components_usb_usb_host_rndis_test_apps
+  - "components/usb/usb_host_rndis/test_apps/**/*"
+  - "tools/cmake_utilities/package_manager.cmake"
+
 .patterns-components_usb_usb_device_uac: &patterns-components_usb_usb_device_uac
   - "components/usb/usb_device_uac/**/*"
 
 .patterns-components_usb_usb_device_uvc: &patterns-components_usb_usb_device_uvc
   - "components/usb/usb_device_uvc/**/*"
 
+.patterns-components_usb_iot_usbh_rndis: &patterns-components_usb_iot_usbh_rndis
+  - "components/usb/iot_usbh_rndis/**/*"
+  - "tools/cmake_utilities/package_manager.cmake"
+
 .patterns-components_usb_usb_stream: &patterns-components_usb_usb_stream
   - "components/usb/usb_stream/**/*"
   - "tools/cmake_utilities/package_manager.cmake"
@@ -343,6 +351,10 @@
   - "components/i2c_bus/**/*"
   - "tools/cmake_utilities/package_manager.cmake"
 
+.patterns-components_iot_eth: &patterns-components_iot_eth
+  - "components/iot_eth/**/*"
+  - "tools/cmake_utilities/package_manager.cmake"
+
 .patterns-components_sensors_power_monitor_ina236: &patterns-components_sensors_power_monitor_ina236
   - "components/sensors/power_monitor/ina236/**/*"
   - "tools/cmake_utilities/package_manager.cmake"
@@ -630,6 +642,9 @@
 .patterns-example_usb_host_usb_msc_ota: &patterns-example_usb_host_usb_msc_ota
   - "examples/usb/host/usb_msc_ota/**/*"
 
+.patterns-example_usb_host_usb_rndis_4g_module: &patterns-example_usb_host_usb_rndis_4g_module
+  - "examples/usb/host/usb_rndis_4g_module/**/*"
+
 .patterns-example_usb_otg_usb_host_device_mode_manual_switch: &patterns-example_usb_otg_usb_host_device_mode_manual_switch
   - "examples/usb/otg/usb_host_device_mode_manual_switch/**/*"
 
@@ -1602,6 +1617,22 @@
     - <<: *if-dev-push
       changes: *patterns-example_usb_host_usb_msc_ota
 
+.rules:build:example_usb_host_usb_rndis_4g_module:
+  rules:
+    - <<: *if-protected
+    - <<: *if-label-build
+    - <<: *if-trigger-job
+    - <<: *if-dev-push
+      changes: *patterns-build_system
+    - <<: *if-dev-push
+      changes: *patterns-components_usb_iot_usbh_cdc
+    - <<: *if-dev-push
+      changes: *patterns-components_usb_iot_usbh_rndis
+    - <<: *if-dev-push
+      changes: *patterns-components_iot_eth
+    - <<: *if-dev-push
+      changes: *patterns-example_usb_host_usb_rndis_4g_module
+
 .rules:build:example_usb_otg_usb_host_device_mode_manual_switch:
   rules:
     - <<: *if-protected
@@ -2451,6 +2482,32 @@
     - <<: *if-dev-push
       changes: *patterns-components_touch_touch_slider_sensor
 
+.rules:build:components_usb_usb_host_rndis_test_apps:
+  rules:
+    - <<: *if-protected
+    - <<: *if-label-build
+    - <<: *if-label-target_test
+    - <<: *if-trigger-job
+    - <<: *if-dev-push
+      changes: *patterns-build_system
+    - <<: *if-dev-push
+      changes: *patterns-components_usb_usb_host_rndis_test_apps
+    - <<: *if-dev-push
+      changes: *patterns-components_usb_iot_usbh_cdc
+
+.rules:build:components_usb_iot_usbh_rndis_test_apps:
+  rules:
+    - <<: *if-protected
+    - <<: *if-label-build
+    - <<: *if-label-target_test
+    - <<: *if-trigger-job
+    - <<: *if-dev-push
+      changes: *patterns-build_system
+    - <<: *if-dev-push
+      changes: *patterns-components_usb_iot_usbh_rndis
+    - <<: *if-dev-push
+      changes: *patterns-components_usb_iot_usbh_cdc
+
 .rules:build:components_usb_esp_msc_ota_test_apps:
   rules:
     - <<: *if-protected

README.md

@@ -108,9 +108,11 @@ The registered components in ESP-IoT-Solution are listed below:
 | [hdc2010](https://components.espressif.com/components/espressif/hdc2010) | [![Component Registry](https://components.espressif.com/components/espressif/hdc2010/badge.svg)](https://components.espressif.com/components/espressif/hdc2010) |
 | [i2c_bus](https://components.espressif.com/components/espressif/i2c_bus) | [![Component Registry](https://components.espressif.com/components/espressif/i2c_bus/badge.svg)](https://components.espressif.com/components/espressif/i2c_bus) |
 | [ina236](https://components.espressif.com/components/espressif/ina236) | [![Component Registry](https://components.espressif.com/components/espressif/ina236/badge.svg)](https://components.espressif.com/components/espressif/ina236) |
+| [iot_eth](https://components.espressif.com/components/espressif/iot_eth) | [![Component Registry](https://components.espressif.com/components/espressif/iot_eth/badge.svg)](https://components.espressif.com/components/espressif/iot_eth) |
 | [iot_usbh](https://components.espressif.com/components/espressif/iot_usbh) | [![Component Registry](https://components.espressif.com/components/espressif/iot_usbh/badge.svg)](https://components.espressif.com/components/espressif/iot_usbh) |
 | [iot_usbh_cdc](https://components.espressif.com/components/espressif/iot_usbh_cdc) | [![Component Registry](https://components.espressif.com/components/espressif/iot_usbh_cdc/badge.svg)](https://components.espressif.com/components/espressif/iot_usbh_cdc) |
 | [iot_usbh_modem](https://components.espressif.com/components/espressif/iot_usbh_modem) | [![Component Registry](https://components.espressif.com/components/espressif/iot_usbh_modem/badge.svg)](https://components.espressif.com/components/espressif/iot_usbh_modem) |
+| [iot_usbh_rndis](https://components.espressif.com/components/espressif/iot_usbh_rndis) | [![Component Registry](https://components.espressif.com/components/espressif/iot_usbh_rndis/badge.svg)](https://components.espressif.com/components/espressif/iot_usbh_rndis) |
 | [ir_learn](https://components.espressif.com/components/espressif/ir_learn) | [![Component Registry](https://components.espressif.com/components/espressif/ir_learn/badge.svg)](https://components.espressif.com/components/espressif/ir_learn) |
 | [keyboard_button](https://components.espressif.com/components/espressif/keyboard_button) | [![Component Registry](https://components.espressif.com/components/espressif/keyboard_button/badge.svg)](https://components.espressif.com/components/espressif/keyboard_button) |
 | [knob](https://components.espressif.com/components/espressif/knob) | [![Component Registry](https://components.espressif.com/components/espressif/knob/badge.svg)](https://components.espressif.com/components/espressif/knob) |

README_CN.md

@@ -108,9 +108,11 @@ ESP-IoT-Solution 中注册的组件如下:
 | [hdc2010](https://components.espressif.com/components/espressif/hdc2010) | [![Component Registry](https://components.espressif.com/components/espressif/hdc2010/badge.svg)](https://components.espressif.com/components/espressif/hdc2010) |
 | [i2c_bus](https://components.espressif.com/components/espressif/i2c_bus) | [![Component Registry](https://components.espressif.com/components/espressif/i2c_bus/badge.svg)](https://components.espressif.com/components/espressif/i2c_bus) |
 | [ina236](https://components.espressif.com/components/espressif/ina236) | [![Component Registry](https://components.espressif.com/components/espressif/ina236/badge.svg)](https://components.espressif.com/components/espressif/ina236) |
+| [iot_eth](https://components.espressif.com/components/espressif/iot_eth) | [![Component Registry](https://components.espressif.com/components/espressif/iot_eth/badge.svg)](https://components.espressif.com/components/espressif/iot_eth) |
 | [iot_usbh](https://components.espressif.com/components/espressif/iot_usbh) | [![Component Registry](https://components.espressif.com/components/espressif/iot_usbh/badge.svg)](https://components.espressif.com/components/espressif/iot_usbh) |
 | [iot_usbh_cdc](https://components.espressif.com/components/espressif/iot_usbh_cdc) | [![Component Registry](https://components.espressif.com/components/espressif/iot_usbh_cdc/badge.svg)](https://components.espressif.com/components/espressif/iot_usbh_cdc) |
 | [iot_usbh_modem](https://components.espressif.com/components/espressif/iot_usbh_modem) | [![Component Registry](https://components.espressif.com/components/espressif/iot_usbh_modem/badge.svg)](https://components.espressif.com/components/espressif/iot_usbh_modem) |
+| [iot_usbh_rndis](https://components.espressif.com/components/espressif/iot_usbh_rndis) | [![Component Registry](https://components.espressif.com/components/espressif/iot_usbh_rndis/badge.svg)](https://components.espressif.com/components/espressif/iot_usbh_rndis) |
 | [ir_learn](https://components.espressif.com/components/espressif/ir_learn) | [![Component Registry](https://components.espressif.com/components/espressif/ir_learn/badge.svg)](https://components.espressif.com/components/espressif/ir_learn) |
 | [keyboard_button](https://components.espressif.com/components/espressif/keyboard_button) | [![Component Registry](https://components.espressif.com/components/espressif/keyboard_button/badge.svg)](https://components.espressif.com/components/espressif/keyboard_button) |
 | [knob](https://components.espressif.com/components/espressif/knob) | [![Component Registry](https://components.espressif.com/components/espressif/knob/badge.svg)](https://components.espressif.com/components/espressif/knob) |

components/.build-rules.yml

@@ -33,6 +33,10 @@ components/usb/esp_msc_ota/test_apps:
   enable:
     - if: IDF_TARGET in ["esp32s3"]
 
+components/usb/iot_usbh_rndis/test_apps:
+  enable:
+    - if: SOC_USB_OTG_SUPPORTED == 1
+
 components/usb/usb_stream/test_apps:
   enable:
     - if: IDF_TARGET in ["esp32s2","esp32s3"]

components/iot_eth/CHANGELOG.md

@@ -0,0 +1,5 @@
+# ChangeLog
+
+## v0.1.0 - 2025-04-22
+
+* publish official version

components/iot_eth/CMakeLists.txt

@@ -0,0 +1,6 @@
+idf_component_register(SRCS "iot_eth.c" "iot_eth_netif_glue.c"
+                    INCLUDE_DIRS "include" "interface"
+                    REQUIRES esp_netif)
+
+include(package_manager)
+cu_pkg_define_version(${CMAKE_CURRENT_LIST_DIR})

components/iot_eth/idf_component.yml

@@ -0,0 +1,14 @@
+version: "0.1.0"
+description: Ethernet interface driver for cellular modems and USB-to-Ethernet adapters
+url: https://github.com/espressif/esp-iot-solution/tree/master/components/iot_eth
+repository: https://github.com/espressif/esp-iot-solution.git
+documentation: https://docs.espressif.com/projects/esp-iot-solution/en/latest/solution/4g/iot_eth.html
+issues: https://github.com/espressif/esp-iot-solution/issues
+examples:
+  - path: ../../examples/usb/host/usb_rndis_4g_module
+dependencies:
+  idf: ">=4.4"
+  cmake_utilities: "*"
+sbom:
+  supplier: 'Organization: Espressif Systems (Shanghai) CO LTD'
+  originator: 'Organization: Espressif Systems (Shanghai) CO LTD'

components/iot_eth/include/iot_eth.h

@@ -0,0 +1,165 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include "esp_err.h"
+#include "esp_event.h"
+#include "iot_eth_interface.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+* @brief iot_eth event declarations
+*
+*/
+typedef enum {
+    IOT_ETH_EVENT_START,        /*!< IOT_ETH driver start */
+    IOT_ETH_EVENT_STOP,         /*!< IOT_ETH driver stop */
+    IOT_ETH_EVENT_CONNECTED,    /*!< IOT_ETH got a valid link */
+    IOT_ETH_EVENT_DISCONNECTED, /*!< IOT_ETH lost a valid link */
+} iot_eth_event_t;
+
+/**
+* @brief iot_eth event base declaration
+*
+*/
+/** @cond **/
+ESP_EVENT_DECLARE_BASE(IOT_ETH_EVENT);
+/** @endcond **/
+
+/**
+ * @brief Ethernet handle type
+ *
+ * This is a handle to an Ethernet instance, used for managing Ethernet operations.
+ */
+typedef void *iot_eth_handle_t;
+
+/**
+ * @brief Static input callback function type
+ *
+ * This type defines a function pointer for a static input callback.
+ * It takes an Ethernet handle, a pointer to data, the length of the data,
+ * and a user data pointer as arguments.
+ */
+typedef esp_err_t (*static_input_cb_t)(iot_eth_handle_t handle, uint8_t *data, size_t len, void *user_data);
+
+/**
+ * @brief Ethernet configuration structure
+ *
+ * This structure holds the configuration for initializing an Ethernet instance.
+ */
+typedef struct {
+    iot_eth_driver_t *driver; /*!< Pointer to the Ethernet driver */
+    static_input_cb_t stack_input; /*!< Function pointer for stack input */
+    void *user_data; /*!< User data for callbacks */
+} iot_eth_config_t;
+
+/*
+ * @brief Install Ethernet driver
+ *
+ * This function initializes the Ethernet driver and network interface.
+ *
+ * @param config Ethernet configuration
+ * @param handle Pointer to the Ethernet handle
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if arguments are invalid
+ *      - ESP_ERR_NO_MEM if memory allocation fails
+ *      - Other error codes from initialization functions
+ */
+esp_err_t iot_eth_install(iot_eth_config_t *config, iot_eth_handle_t *handle);
+
+/*
+ * @brief Uninstall Ethernet driver
+ *
+ * This function deinitializes the Ethernet driver and frees resources.
+ *
+ * @param handle Ethernet handle
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - Error code from driver deinitialization
+ */
+esp_err_t iot_eth_uninstall(iot_eth_handle_t handle);
+
+/*
+ * @brief Start Ethernet driver
+ *
+ * This function starts the Ethernet driver.
+ *
+ * @param handle Ethernet handle
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - Error code from driver start function
+ */
+esp_err_t iot_eth_start(iot_eth_handle_t handle);
+
+/*
+ * @brief Stop Ethernet driver
+ *
+ * This function stops the Ethernet driver.
+ *
+ * @param handle Ethernet handle
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - Error code from driver stop function
+ */
+esp_err_t iot_eth_stop(iot_eth_handle_t handle);
+
+/*
+ * @brief Transmit data over Ethernet
+ *
+ * This function sends data through the Ethernet driver.
+ *
+ * @param handle Ethernet handle
+ * @param data Pointer to the data to be sent
+ * @param len Length of the data to be sent
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if arguments are invalid
+ *      - ESP_ERR_INVALID_STATE if Ethernet link is down
+ */
+esp_err_t iot_eth_transmit(iot_eth_handle_t handle, void *data, size_t len);
+
+/*
+ * @brief Get Ethernet MAC address
+ *
+ * This function retrieves the MAC address of the Ethernet interface.
+ *
+ * @param handle Ethernet handle
+ * @param mac Pointer to the MAC address buffer
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - Error code from driver get address function
+ */
+esp_err_t iot_eth_get_addr(iot_eth_handle_t handle, uint8_t *mac);
+
+/*
+ * @brief Update the input path for Ethernet data
+ *
+ * This function updates the stack input callback function and user data pointer
+ * that will be used when receiving Ethernet packets.
+ *
+ * @param[in] handle Ethernet handle
+ * @param[in] stack_input Function pointer for stack input callback
+ * @param[in] user_data User data to be passed to stack input callback
+ *
+ * @return
+ *      - ESP_OK: Successfully updated input path
+ *      - ESP_ERR_INVALID_ARG: Invalid handle argument
+ */
+esp_err_t iot_eth_update_input_path(iot_eth_handle_t handle, static_input_cb_t stack_input, void *user_data);
+
+#ifdef __cplusplus
+}
+#endif