USB ECM Host Driver

[中文]

iot_usbh_ecm is a host driver for the ECM protocol based on USB interface.

ECM Protocol

ECM (Ethernet Control Model) enables network communication by encapsulating Ethernet frames in USB packets.

USB Descriptors

ECM interface typically consists of two interface descriptors and class-specific descriptors. The first interface descriptor has bInterfaceClass as 0x02 and bInterfaceSubClass as 0x06. In the ECM function descriptor usb_ecm_function_desc_t, iMACAddress is the string index for MAC address, and wMaxSegmentSize is the maximum Ethernet frame size (default 1514).

Note

Some ECM devices don’t use the default config 1 descriptor, so you need to enable CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK and implement the enumeration filter callback function.

Example Descriptor:

*** Interface descriptor ***
bLength 9
bDescriptorType 4
bInterfaceNumber 0
bAlternateSetting 0
bNumEndpoints 1
bInterfaceClass 0x2
bInterfaceSubClass 0x6
bInterfaceProtocol 0x0
iInterface 5
        *** Endpoint descriptor ***
        bLength 7
        bDescriptorType 5
        bEndpointAddress 0x81   EP 1 IN
        bmAttributes 0x3        INT
        wMaxPacketSize 64
        bInterval 8
*** Interface descriptor ***
bLength 9
bDescriptorType 4
bInterfaceNumber 1
bAlternateSetting 0
bNumEndpoints 0
bInterfaceClass 0xa
bInterfaceSubClass 0x0
bInterfaceProtocol 0x0
iInterface 0
*** Interface descriptor ***
bLength 9
bDescriptorType 4
bInterfaceNumber 1
bAlternateSetting 1
bNumEndpoints 2
bInterfaceClass 0xa
bInterfaceSubClass 0x0
bInterfaceProtocol 0x0
iInterface 0
        *** Endpoint descriptor ***
        bLength 7
        bDescriptorType 5
        bEndpointAddress 0x82   EP 2 IN
        bmAttributes 0x2        BULK
        wMaxPacketSize 64
        bInterval 0
        *** Endpoint descriptor ***
        bLength 7
        bDescriptorType 5
        bEndpointAddress 0x3    EP 3 OUT
        bmAttributes 0x2        BULK
        wMaxPacketSize 64
        bInterval 0

Speed Test

Ethernet to USB Device

ESP32-S3/P4 connected to Ethernet to USB device (CH397A), with softAP enabled and phone connected to softAP for network speed test:

Chip

Upload(Mbps)

Download(Mbps)

ESP32-S3

6.6

7.2

ESP32-P4 with ESP32-C6

11.7

14.7

4G Module

Not available yet

Resources

CDC1.2 Protocol Document

API Reference

Header File

Functions

esp_err_t iot_eth_new_usb_ecm(const iot_usbh_ecm_config_t *config, iot_eth_driver_t **ret_handle)

Create a new USB ECM Ethernet driver.

This function initializes a new USB ECM Ethernet driver with the specified configuration. It allocates memory for the driver, sets up the driver functions, and returns a handle to the driver.

Parameters

  • config – Pointer to the ECM configuration structure.

  • ret_handle – Pointer to a location where the handle to the new Ethernet driver will be stored.

Returns

  • ESP_OK: Driver created successfully

  • ESP_ERR_INVALID_ARG: Invalid argument (NULL config or ret_handle)

  • ESP_ERR_NO_MEM: Memory allocation failed

Structures

struct iot_usbh_ecm_config_t

USB Host Ethernet ECM Configuration.

Public Members

bool auto_detect

Auto detect ECM device

TickType_t auto_detect_timeout

Auto detect timeout in ticks, used when auto_detect is true

uint16_t vid

USB device vendor ID, used when auto_detect is false

uint16_t pid

USB device product ID, used when auto_detect is false

int itf_num

ecm device notif interface numbers, used when auto_detect is false

Provide feedback about this document