USB RNDIS Host Driver

iot_usbh_rndis is a host driver for the RNDIS protocol based on USB interface.

RNDIS Protocol

RNDIS (Remote NDIS) enables network communication by encapsulating TCP/IP in USB packets.

USB Descriptors

RNDIS devices default to being the only function in a USB configuration. For composite devices, RNDIS expects to be the first USB configuration, i.e. interface with bInterfaceNumber 0.

The RNDIS interface typically consists of one IAD descriptor and two interface descriptors. The IAD descriptor has bInterfaceCount of 2 and bFunctionClass of 0xe0.

Example:

*** Interface Association Descriptor ***
bLength 8
bDescriptorType 11
bFirstInterface 0
bInterfaceCount 2
bFunctionClass 0xe0
bFunctionSubClass 0x1
bFunctionProtocol 0x3
iFunction 5
    *** Interface descriptor ***
    bLength 9
    bDescriptorType 4
    bInterfaceNumber 0
    bAlternateSetting 0
    bNumEndpoints 1
    bInterfaceClass 0xe0
    bInterfaceSubClass 0x1
    bInterfaceProtocol 0x3
    iInterface 5
            *** Endpoint descriptor ***
            bLength 7
            bDescriptorType 5
            bEndpointAddress 0x85   EP 5 IN
            bmAttributes 0x3        INT
            wMaxPacketSize 16
            bInterval 16
    *** Interface descriptor ***
    bLength 9
    bDescriptorType 4
    bInterfaceNumber 1
    bAlternateSetting 0
    bNumEndpoints 2
    bInterfaceClass 0xa
    bInterfaceSubClass 0x0
    bInterfaceProtocol 0x0
    iInterface 5
            *** Endpoint descriptor ***
            bLength 7
            bDescriptorType 5
            bEndpointAddress 0x87   EP 7 IN
            bmAttributes 0x2        BULK
            wMaxPacketSize 64
            bInterval 0
            *** Endpoint descriptor ***
            bLength 7
            bDescriptorType 5
            bEndpointAddress 0x6    EP 6 OUT
            bmAttributes 0x2        BULK
            wMaxPacketSize 64
            bInterval 0

Communication Flow

Send initialization message REMOTE_NDIS_INITIALIZE_MSG through control endpoint, device will return REMOTE_NDIS_INITIALIZE_CMPLT_MSG message.
Then host needs to send REMOTE_NDIS_QUERY_MSG message to query Object Identifier (OID), and use OID to query and support the device. For example, getting device MAC address, connection status, connection speed etc.
Then host can initiate DHCP request to obtain IP address.

Frame Format

The RNDIS protocol frame format is as follows:

Send: RNDIS data packets need to add RNDIS data header rndis_data_packet_t before the Ethernet frame, then add the Ethernet frame message.

Receive: RNDIS data packets add RNDIS data header rndis_data_packet_t at the beginning of Ethernet frame. Need to parse RNDIS data header first, then get the Ethernet frame.

Speed Test

ESP32-S3 connected to 4G network card and started softAP, mobile phone connected to softAP for network speed test:

Chip	Upload(Mbps)	Download(Mbps)
ESP32-S3	5.8	7.9

API Reference

Header File

components/usb/iot_usbh_rndis/include/iot_usbh_rndis.h

Functions

esp_err_t iot_eth_new_usb_rndis(const iot_usbh_rndis_config_t *config, iot_eth_driver_t **ret_handle)

Create a new USB RNDIS Ethernet driver.

This function initializes a new USB RNDIS 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 RNDIS 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_rndis_config_t

USB Host Ethernet ECM Configuration.

Public Members

bool auto_detect: Auto detect RNDIS 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: interface numbers, used when auto_detect is false

Provide feedback about this document