USB Host¶

Warning

The USB Host Library API is a beta version thus is subject to change.

The following document lists the API and types of the USB Host Library (that is currently under development).

API Reference¶

The API of the USB Host Library is separated into the following header files. However, it is sufficient for applications to only #include "usb/usb_host.h" and all of USB Host Library headers will also be included.

usb/include/usb/usb_host.h contains the functions and types of the USB Host Library
usb/include/usb/usb_helpers.h contains various helper functions that are related to the USB protocol such as descriptor parsing.
usb/include/usb/usb_types_stack.h contains types that are are used across multiple layers of the USB Host stack.
usb/include/usb/usb_types_ch9.h contains types and macros related to Chapter 9 of the USB2.0 specification (i.e., descriptors and standard requests).

Header File¶

components/usb/include/usb/usb_host.h

Functions¶

esp_err_t usb_host_install(const usb_host_config_t *config)¶

Install the USB Host Library.

This function should only once to install the USB Host Library
This function should be called before any other USB Host Library functions are called

Return

esp_err_t

Parameters

[in] config: USB Host Library configuration

esp_err_t usb_host_uninstall(void)¶

Uninstall the USB Host Library.

This function should be called to uninstall the USB Host Library, thereby freeing its resources
All clients must have been deregistered before calling this function
All devices must have been freed by calling usb_host_device_free_all() and receiving the USB_HOST_LIB_EVENT_FLAGS_ALL_FREE event flag

Return: esp_err_t

esp_err_t usb_host_lib_handle_events(TickType_t timeout_ticks, uint32_t *event_flags_ret)¶

Handle USB Host Library events.

This function handles all of the USB Host Library’s processing and should be called repeatedly in a loop
Check event_flags_ret to see if an flags are set indicating particular USB Host Library events

Note

This function can block

Return

esp_err_t

Parameters

[in] timeout_ticks: Timeout in ticks to wait for an event to occur
[out] event_flags_ret: Event flags that indicate what USB Host Library event occurred

esp_err_t usb_host_lib_unblock(void)¶

Unblock the USB Host Library handler.

This function simply unblocks the USB Host Library event handling function (usb_host_lib_handle_events())

Return: esp_err_t

esp_err_t usb_host_client_register(const usb_host_client_config_t *client_config, usb_host_client_handle_t *client_hdl_ret)¶

Register a client of the USB Host Library.

This function registers a client of the USB Host Library
Once a client is registered, its processing function usb_host_client_handle_events() should be called repeatedly

Return

esp_err_t

Parameters

[in] client_config: Client configuration
[out] client_hdl_ret: Client handle

esp_err_t usb_host_client_deregister(usb_host_client_handle_t client_hdl)¶

Deregister a USB Host Library client.

This function deregisters a client of the USB Host Library
The client must have closed all previously opened devices before attempting to deregister

Return

esp_err_t

Parameters

[in] client_hdl: Client handle

esp_err_t usb_host_client_handle_events(usb_host_client_handle_t client_hdl, TickType_t timeout_ticks)¶

USB Host Library client processing function.

This function handles all of a client’s processing and should be called repeatedly in a loop

Note

This function can block

Return

esp_err_t

Parameters

[in] client_hdl: Client handle
[in] timeout_ticks: Timeout in ticks to wait for an event to occur

esp_err_t usb_host_client_unblock(usb_host_client_handle_t client_hdl)¶

Unblock a client.

This function simply unblocks a client if it is blocked on the usb_host_client_handle_events() function.
This function is useful when need to unblock a client in order to deregister it.

Return

esp_err_t

Parameters

[in] client_hdl: Client handle

esp_err_t usb_host_device_open(usb_host_client_handle_t client_hdl, uint8_t dev_addr, usb_device_handle_t *dev_hdl_ret)¶

Open a device.

This function allows a client to open a device
A client must open a device first before attempting to use it (e.g., sending transfers, device requests etc.)

Return

esp_err_t

Parameters

[in] client_hdl: Client handle
[in] dev_addr: Device’s address
[out] dev_hdl_ret: Device’s handle

esp_err_t usb_host_device_close(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl)¶

Close a device.

This function allows a client to close a device
A client must close a device after it has finished using the device (claimed interfaces must also be released)
A client must close all devices it has opened before deregistering

Note

This function can block

Return

esp_err_t

Parameters

[in] client_hdl: Client handle
[in] dev_hdl: Device handle

esp_err_t usb_host_device_free_all(void)¶

Indicate that all devices can be freed when possible.

This function marks all devices as waiting to be freed
If a device is not opened by any clients, it will be freed immediately
If a device is opened by at least one client, the device will be free when the last client closes that device.
Wait for the USB_HOST_LIB_EVENT_FLAGS_ALL_FREE flag to be set by usb_host_lib_handle_events() in order to know when all devices have been freed
This function is useful when cleaning up devices before uninstalling the USB Host Library

Return

ESP_ERR_NOT_FINISHED: There are one or more devices that still need to be freed. Wait for USB_HOST_LIB_EVENT_FLAGS_ALL_FREE event
ESP_OK: All devices already freed (i.e., there were no devices)
Other: Error

esp_err_t usb_host_device_addr_list_fill(int list_len, uint8_t *dev_addr_list, int *num_dev_ret)¶

Fill a list of device address.

This function fills an empty list with the address of connected devices
The Device addresses can then used in usb_host_device_open()
If there are more devices than the list_len, this function will only fill up to list_len number of devices.

Return

esp_err_t

Parameters

[in] list_len: Length of the empty list
[inout] dev_addr_list: Empty list to be filled
[out] num_dev_ret: Number of devices

esp_err_t usb_host_device_info(usb_device_handle_t dev_hdl, usb_device_info_t *dev_info)¶

Get device’s information.

This function gets some basic information of a device
The device must be opened first before attempting to get its information

Note

This function can block

Return

esp_err_t

Parameters

[in] dev_hdl: Device handle
[out] dev_info: Device information

esp_err_t usb_host_get_device_descriptor(usb_device_handle_t dev_hdl, const usb_device_desc_t **device_desc)¶

Get device’s device descriptor.

A client must call usb_host_device_open() first
No control transfer is sent. The device’s descriptor is cached on enumeration
This function simple returns a pointer to the cached descriptor

Note

No control transfer is sent. The device’s descriptor is cached on enumeration

Return

esp_err_t

Parameters

[in] dev_hdl: Device handle
[out] device_desc: Device descriptor

esp_err_t usb_host_get_active_config_descriptor(usb_device_handle_t dev_hdl, const usb_config_desc_t **config_desc)¶

Get device’s active configuration descriptor.

A client must call usb_host_device_open() first
No control transfer is sent. The device’s active configuration descriptor is cached on enumeration
This function simple returns a pointer to the cached descriptor

Note

This function can block

Note

No control transfer is sent. A device’s active configuration descriptor is cached on enumeration

Return

esp_err_t

Parameters

[in] dev_hdl: Device handle
[out] config_desc: Configuration descriptor

esp_err_t usb_host_interface_claim(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl, uint8_t bInterfaceNumber, uint8_t bAlternateSetting)¶

Function for a client to claim a device’s interface.

A client must claim a device’s interface before attempting to communicate with any of its endpoints
Once an interface is claimed by a client, it cannot be claimed by any other client.

Note

This function can block

Return

esp_err_t

Parameters

[in] client_hdl: Client handle
[in] dev_hdl: Device handle
[in] bInterfaceNumber: Interface number
[in] bAlternateSetting: Interface alternate setting number

esp_err_t usb_host_interface_release(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl, uint8_t bInterfaceNumber)¶

Function for a client to release a previously claimed interface.

A client should release a device’s interface after it no longer needs to communicate with the interface
A client must release all of its interfaces of a device it has claimed before being able to close the device

Note

This function can block

Return

esp_err_t

Parameters

[in] client_hdl: Client handle
[in] dev_hdl: Device handle
[in] bInterfaceNumber: Interface number

esp_err_t usb_host_endpoint_halt(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress)¶

Halt a particular endpoint.

The device must have been opened by a client
The endpoint must be part of an interface claimed by a client
Once halted, the endpoint must be cleared using usb_host_endpoint_clear() before it can communicate again

Note

This function can block

Return

esp_err_t

Parameters

dev_hdl: Device handle
bEndpointAddress: Endpoint address

esp_err_t usb_host_endpoint_flush(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress)¶

Flush a particular endpoint.

The device must have been opened by a client
The endpoint must be part of an interface claimed by a client
The endpoint must have been halted (either through a transfer error, or usb_host_endpoint_halt())
Flushing an endpoint will caused an queued up transfers to be canceled

Note

This function can block

Return

esp_err_t

Parameters

dev_hdl: Device handle
bEndpointAddress: Endpoint address

esp_err_t usb_host_endpoint_clear(usb_device_handle_t dev_hdl, uint8_t bEndpointAddress)¶

Clear a halt on a particular endpoint.

The device must have been opened by a client
The endpoint must be part of an interface claimed by a client
The endpoint must have been halted (either through a transfer error, or usb_host_endpoint_halt())
If the endpoint has any queued up transfers, clearing a halt will resume their execution

Note

This function can block

Return

esp_err_t

Parameters

dev_hdl: Device handle
bEndpointAddress: Endpoint address

esp_err_t usb_host_transfer_alloc(size_t data_buffer_size, int num_isoc_packets, usb_transfer_t **transfer)¶

Allocate a transfer object.

This function allocates a transfer object
Each transfer object has a fixed sized buffer specified on allocation
A transfer object can be re-used indefinitely
A transfer can be submitted using usb_host_transfer_submit() or usb_host_transfer_submit_control()

Return

esp_err_t

Parameters

[in] data_buffer_size: Size of the transfer’s data buffer
[in] num_isoc_packets: Number of isochronous packets in transfer (set to 0 for non-isochronous transfers)
[out] transfer: Transfer object

esp_err_t usb_host_transfer_free(usb_transfer_t *transfer)¶

Free a transfer object.

Free a transfer object previously allocated using usb_host_transfer_alloc()
The transfer must not be in-flight when attempting to free it
If a NULL pointer is passed, this function will simply return ESP_OK

Return

esp_err_t

Parameters

[in] transfer: Transfer object

esp_err_t usb_host_transfer_submit(usb_transfer_t *transfer)¶

Submit a non-control transfer.

Submit a transfer to a particular endpoint. The device and endpoint number is specified inside the transfer
The transfer must be properly initialized before submitting
On completion, the transfer’s callback will be called from the client’s usb_host_client_handle_events() function.

Return

esp_err_t

Parameters

[in] transfer: Initialized transfer object

esp_err_t usb_host_transfer_submit_control(usb_host_client_handle_t client_hdl, usb_transfer_t *transfer)¶

Submit a control transfer.

Submit a control transfer to a particular device. The client must have opened the device first
The transfer must be properly initialized before submitting. The first 8 bytes of the transfer’s data buffer should contain the control transfer setup packet
On completion, the transfer’s callback will be called from the client’s usb_host_client_handle_events() function.

Return

esp_err_t

Parameters

[in] client_hdl: Client handle
[in] transfer: Initialized transfer object

Structures¶

struct usb_host_client_event_msg_t¶

Client event message.

Client event messages are sent to each client of the USB Host Library in order to notify them of various USB Host Library events such as:

Addition of new devices
Removal of existing devices

Note: The event message structure has a union with members corresponding to each particular event. Based on the event type, only the relevant member field should be accessed.

Public Members

usb_host_client_event_t event¶: Type of event

uint8_t address¶: New device’s address

usb_device_handle_t dev_hdl¶: The handle of the device that was gone

struct usb_host_config_t¶

USB Host Library configuration.

Configuration structure of the USB Host Library. Provided in the usb_host_install() function

Public Members

int intr_flags¶: Interrupt flags for the underlying ISR used by the USB Host stack

struct usb_host_client_config_t¶

USB Host Library Client configuration.

Configuration structure for a USB Host Library client. Provided in usb_host_client_register()

Public Members

bool is_synchronous¶: Whether the client is asynchronous or synchronous or not. Set to false for now.

int max_num_event_msg¶: Maximum number of event messages that can be stored (e.g., 3)

usb_host_client_event_cb_t client_event_callback¶: Client’s event callback function

void *callback_arg¶: Event callback function argument

Macros¶

USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS¶: All clients have been deregistered from the USB Host Library

USB_HOST_LIB_EVENT_FLAGS_ALL_FREE¶: The USB Host Library has freed all devices

Type Definitions¶

typedef struct usb_host_client_handle_s *usb_host_client_handle_t¶

Handle to a USB Host Library asynchronous client.

An asynchronous client can be registered using usb_host_client_register()

Note: Asynchronous API

typedef void (*usb_host_client_event_cb_t)(const usb_host_client_event_msg_t *event_msg, void *arg)¶

Client event callback.

Each client of the USB Host Library must register an event callback to receive event messages from the USB Host Library.
The client event callback is run from the context of the clients usb_host_client_handle_events() function

Enumerations¶

enum usb_host_client_event_t¶

The type event in a client event message.

Values:

USB_HOST_CLIENT_EVENT_NEW_DEV¶: A new device has been enumerated and added to the USB Host Library

USB_HOST_CLIENT_EVENT_DEV_GONE¶: A device opened by the client is now gone

Header File¶

components/usb/include/usb/usb_helpers.h

Functions¶

const usb_standard_desc_t *usb_parse_next_descriptor(const usb_standard_desc_t *cur_desc, uint16_t wTotalLength, int *offset)¶

Get the next descriptor.

Given a particular descriptor within a full configuration descriptor, get the next descriptor within the configuration descriptor. This is a convenience function that can be used to walk each individual descriptor within a full configuration descriptor.

Return

usb_standard_desc_t* Next descriptor, NULL if end of configuration descriptor reached

Parameters

[in] cur_desc: Current descriptor
[in] wTotalLength: Total length of the configuration descriptor
[inout] offset: Byte offset relative to the start of the configuration descriptor. On input, it is the offset of the current descriptor. On output, it is the offset of the returned descriptor.

const usb_standard_desc_t *usb_parse_next_descriptor_of_type(const usb_standard_desc_t *cur_desc, uint16_t wTotalLength, uint8_t bDescriptorType, int *offset)¶

Get the next descriptor of a particular type.

Given a particular descriptor within a full configuration descriptor, get the next descriptor of a particular type (i.e., using the bDescriptorType value) within the configuration descriptor.

Return

usb_standard_desc_t* Next descriptor, NULL if end descriptor is not found or configuration descriptor reached

Parameters

[in] cur_desc: Current descriptor
[in] wTotalLength: Total length of the configuration descriptor
[in] bDescriptorType: Type of the next descriptor to get
[inout] offset: Byte offset relative to the start of the configuration descriptor. On input, it is the offset of the current descriptor. On output, it is the offset of the returned descriptor.

int usb_parse_interface_number_of_alternate(const usb_config_desc_t *config_desc, uint8_t bInterfaceNumber)¶

Get the number of alternate settings for a bInterfaceNumber.

Given a particular configuration descriptor, for a particular bInterfaceNumber, get the number of alternate settings available for that interface (i.e., the max possible value of bAlternateSetting for that bInterfaceNumber).

Return

int The number of alternate settings that the interface has, -1 if bInterfaceNumber not found

Parameters

[in] config_desc: Pointer to the start of a full configuration descriptor
[in] bInterfaceNumber: Interface number

const usb_intf_desc_t *usb_parse_interface_descriptor(const usb_config_desc_t *config_desc, uint8_t bInterfaceNumber, uint8_t bAlternateSetting, int *offset)¶

Get a particular interface descriptor (using bInterfaceNumber and bAlternateSetting)

Given a full configuration descriptor, get a particular interface descriptor.

Note

To get the number of alternate settings for a particular bInterfaceNumber, call usb_parse_interface_number_of_alternate()

Return

const usb_intf_desc_t* Pointer to interface descriptor, NULL if not found.

Parameters

[in] config_desc: Pointer to the start of a full configuration descriptor
[in] bInterfaceNumber: Interface number
[in] bAlternateSetting: Alternate setting number
[out] offset: Byte offset of the interface descriptor relative to the start of the configuration descriptor. Can be NULL.

const usb_ep_desc_t *usb_parse_endpoint_descriptor_by_index(const usb_intf_desc_t *intf_desc, int index, uint16_t wTotalLength, int *offset)¶

Get an endpoint descriptor within an interface descriptor.

Given an interface descriptor, get the Nth endpoint descriptor of the interface. The number of endpoints in an interface is indicated by the bNumEndpoints field of the interface descriptor.

Note

If bNumEndpoints is 0, it means the interface uses the default endpoint only

Return

const usb_ep_desc_t* Pointer to endpoint descriptor, NULL if not found.

Parameters

[in] intf_desc: Pointer to thee start of an interface descriptor
[in] index: Endpoint index
[in] wTotalLength: Total length of the containing configuration descriptor
[inout] offset: Byte offset relative to the start of the configuration descriptor. On input, it is the offset of the interface descriptor. On output, it is the offset of the endpoint descriptor.

const usb_ep_desc_t *usb_parse_endpoint_descriptor_by_address(const usb_config_desc_t *config_desc, uint8_t bInterfaceNumber, uint8_t bAlternateSetting, uint8_t bEndpointAddress, int *offset)¶

Get an endpoint descriptor based on an endpoint’s address.

Given a configuration descriptor, get an endpoint descriptor based on it’s bEndpointAddress, bAlternateSetting, and bInterfaceNumber.

Return

const usb_ep_desc_t* Pointer to endpoint descriptor, NULL if not found.

Parameters

[in] config_desc: Pointer to the start of a full configuration descriptor
[in] bInterfaceNumber: Interface number
[in] bAlternateSetting: Alternate setting number
[in] bEndpointAddress: Endpoint address
[out] offset: Byte offset of the endpoint descriptor relative to the start of the configuration descriptor. Can be NULL

static int usb_round_up_to_mps(int num_bytes, int mps)¶

Round up to an integer multiple of endpoint’s MPS.

This is a convenience function to round up a size/length to an endpoint’s MPS (Maximum packet size). This is useful when calculating transfer or buffer lengths of IN endpoints.

Return

int Round up integer multiple of MPS

Parameters

[in] num_bytes: Number of bytes
[in] mps: MPS

esp_err_t usb_print_descriptors(usb_device_handle_t device, print_class_descriptor_cb class_specific_cb)¶

Prints usb descriptors.

Return

esp_err_t

Parameters

[in] device: Handle to device
[in] class_specific_cb: Optional callback to print class specific descriptors

Type Definitions¶

typedef void (*print_class_descriptor_cb)(const usb_standard_desc_t *)¶

Print class specific descriptor callback.

Optional callback to be provided to usb_print_descriptors() function. The callback is called when when a non-standard descriptor is encountered. The callback should decode the descriptor as print it.

Header File¶

components/usb/include/usb/usb_types_stack.h

Structures¶

struct usb_device_info_t¶

Basic information of an enumerated device.

Public Members

usb_speed_t speed¶: Device’s speed

uint8_t dev_addr¶: Device’s address

uint8_t bMaxPacketSize0¶: The maximum packet size of the device’s default endpoint

uint8_t bConfigurationValue¶: Device’s current configuration number

struct usb_isoc_packet_desc_t¶

Isochronous packet descriptor.

If the number of bytes in an Isochronous transfer is larger than the MPS of the endpoint, the transfer is split into multiple packets transmitted at the endpoint’s specified interval. An array of Isochronous packet descriptors describes how an Isochronous transfer should be split into multiple packets.

Public Members

int num_bytes¶: Number of bytes to transmit/receive in the packet. IN packets should be integer multiple of MPS

int actual_num_bytes¶: Actual number of bytes transmitted/received in the packet

usb_transfer_status_t status¶: Status of the packet

struct usb_transfer_s¶

Public Members

uint8_t *const data_buffer¶: Pointer to data buffer

const size_t data_buffer_size¶: Size of the data buffer in bytes

int num_bytes¶: Number of bytes to transfer. Control transfers should include the size of the setup packet. Isochronous transfer should be the total transfer size of all packets. For non-control IN transfers, num_bytes should be an integer multiple of MPS.

int actual_num_bytes¶: Actual number of bytes transferred

uint32_t flags¶: Transfer flags

usb_device_handle_t device_handle¶: Device handle

uint8_t bEndpointAddress¶: Endpoint Address

usb_transfer_status_t status¶: Status of the transfer

uint32_t timeout_ms¶: Timeout (in milliseconds) of the packet (currently not supported yet)

usb_transfer_cb_t callback¶: Transfer callback

void *context¶: Context variable for transfer to associate transfer with something

const int num_isoc_packets¶: Only relevant to Isochronous. Number of service periods (i.e., intervals) to transfer data buffer over.

usb_isoc_packet_desc_t isoc_packet_desc[0]¶: Descriptors for each Isochronous packet

Macros¶

USB_TRANSFER_FLAG_ZERO_PACK¶: (For bulk OUT only). Indicates that a bulk OUT transfers should always terminate with a short packet, even if it means adding an extra zero length packet

Type Definitions¶

typedef struct usb_device_handle_s *usb_device_handle_t¶: Handle of a USB Device connected to a USB Host.

typedef struct usb_transfer_s usb_transfer_t¶

USB transfer structure.

This structure is used to represent a transfer from a software client to an endpoint over the USB bus. Some of the fields are made const on purpose as they are fixed on allocation. Users should call the appropriate USB Host Library function to allocate a USB transfer structure instead of allocating this structure themselves.

The transfer type is inferred from the endpoint this transfer is sent to. Depending on the transfer type, users should note the following:

Bulk: This structure represents a single bulk transfer. If the number of bytes exceeds the endpoint’s MPS, the transfer will be split into multiple MPS sized packets followed by a short packet.
Control: This structure represents a single control transfer. This first 8 bytes of the data_buffer must be filled with the setup packet (see usb_setup_packet_t). The num_bytes field should be the total size of the transfer (i.e., size of setup packet + wLength).
Interrupt: Represents an interrupt transfer. If num_bytes exceeds the MPS of the endpoint, the transfer will be split into multiple packets, and each packet is transferred at the endpoint’s specified interval.
Isochronous: Represents a stream of bytes that should be transferred to an endpoint at a fixed rate. The transfer is split into packets according to the each isoc_packet_desc. A packet is transferred at each interval of the endpoint. If an entire ISOC URB was transferred without error (skipped packets do not count as errors), the URB’s overall status and the status of each packet descriptor will be updated, and the actual_num_bytes reflects the total bytes transferred over all packets. If the ISOC URB encounters an error, the entire URB is considered erroneous so only the overall status will updated.

Note: For Bulk/Control/Interrupt IN transfers, the num_bytes must be a integer multiple of the endpoint’s MPS
Note: This structure should be allocated via usb_host_transfer_alloc()
Note: Once the transfer has be submitted, users should not modify the structure until the transfer has completed

typedef void (*usb_transfer_cb_t)(usb_transfer_t *transfer)¶: USB transfer completion callback.

Enumerations¶

enum usb_speed_t¶

USB Standard Speeds.

Values:

USB_SPEED_LOW = 0¶: USB Low Speed (1.5 Mbit/s)

USB_SPEED_FULL¶: USB Full Speed (12 Mbit/s)

enum usb_transfer_type_t¶

The type of USB transfer.

Note: The enum values need to match the bmAttributes field of an EP descriptor

Values:

USB_TRANSFER_TYPE_CTRL = 0¶

USB_TRANSFER_TYPE_ISOCHRONOUS¶

USB_TRANSFER_TYPE_BULK¶

USB_TRANSFER_TYPE_INTR¶

enum usb_transfer_status_t¶

The status of a particular transfer.

Values:

USB_TRANSFER_STATUS_COMPLETED¶: The transfer was successful (but may be short)

USB_TRANSFER_STATUS_ERROR¶: The transfer failed because due to excessive errors (e.g. no response or CRC error)

USB_TRANSFER_STATUS_TIMED_OUT¶: The transfer failed due to a time out

USB_TRANSFER_STATUS_CANCELED¶: The transfer was canceled

USB_TRANSFER_STATUS_STALL¶: The transfer was stalled

USB_TRANSFER_STATUS_OVERFLOW¶: The transfer as more data was sent than was requested

USB_TRANSFER_STATUS_SKIPPED¶: ISOC packets only. The packet was skipped due to system latency or bus overload

USB_TRANSFER_STATUS_NO_DEVICE¶: The transfer failed because the target device is gone

Header File¶

components/usb/include/usb/usb_types_ch9.h

Unions¶

union usb_setup_packet_t¶

#include <usb_types_ch9.h>

Structure representing a USB control transfer setup packet.

See Table 9-2 of USB2.0 specification for more details

Public Members

uint8_t bmRequestType¶: Characteristics of request

uint8_t bRequest¶: Specific request

uint16_t wValue¶: Word-sized field that varies according to request

uint16_t wIndex¶: Word-sized field that varies according to request; typically used to pass an index or offset

uint16_t wLength¶: Number of bytes to transfer if there is a data stage

struct usb_setup_packet_t::[anonymous] [anonymous]¶

uint8_t val[USB_SETUP_PACKET_SIZE]¶

union usb_standard_desc_t¶

#include <usb_types_ch9.h>

USB standard descriptor.

All USB standard descriptors start with these two bytes. Use this type when traversing over configuration descriptors

Public Members

uint8_t bLength¶: Size of the descriptor in bytes

uint8_t bDescriptorType¶: Descriptor Type

struct usb_standard_desc_t::[anonymous] USB_DESC_ATTR¶

uint8_t val[USB_STANDARD_DESC_SIZE]¶

union usb_device_desc_t¶

#include <usb_types_ch9.h>

Structure representing a USB device descriptor.

See Table 9-8 of USB2.0 specification for more details

Public Members

uint8_t bLength¶: Size of the descriptor in bytes

uint8_t bDescriptorType¶: DEVICE Descriptor Type

uint16_t bcdUSB¶: USB Specification Release Number in Binary-Coded Decimal (i.e., 2.10 is 210H)

uint8_t bDeviceClass¶: Class code (assigned by the USB-IF)

uint8_t bDeviceSubClass¶: Subclass code (assigned by the USB-IF)

uint8_t bDeviceProtocol¶: Protocol code (assigned by the USB-IF)

uint8_t bMaxPacketSize0¶: Maximum packet size for endpoint zero (only 8, 16, 32, or 64 are valid)

uint16_t idVendor¶: Vendor ID (assigned by the USB-IF)

uint16_t idProduct¶: Product ID (assigned by the manufacturer)

uint16_t bcdDevice¶: Device release number in binary-coded decimal

uint8_t iManufacturer¶: Index of string descriptor describing manufacturer

uint8_t iProduct¶: Index of string descriptor describing product

uint8_t iSerialNumber¶: Index of string descriptor describing the device’s serial number

uint8_t bNumConfigurations¶: Number of possible configurations

struct usb_device_desc_t::[anonymous] USB_DESC_ATTR¶

uint8_t val[USB_DEVICE_DESC_SIZE]¶

union usb_config_desc_t¶

#include <usb_types_ch9.h>

Structure representing a short USB configuration descriptor.

See Table 9-10 of USB2.0 specification for more details

Note: The full USB configuration includes all the interface and endpoint descriptors of that configuration.

Public Members

uint8_t bLength¶: Size of the descriptor in bytes

uint8_t bDescriptorType¶: CONFIGURATION Descriptor Type

uint16_t wTotalLength¶: Total length of data returned for this configuration

uint8_t bNumInterfaces¶: Number of interfaces supported by this configuration

uint8_t bConfigurationValue¶: Value to use as an argument to the SetConfiguration() request to select this configuration

uint8_t iConfiguration¶: Index of string descriptor describing this configuration

uint8_t bmAttributes¶: Configuration characteristics

uint8_t bMaxPower¶: Maximum power consumption of the USB device from the bus in this specific configuration when the device is fully operational.

struct usb_config_desc_t::[anonymous] USB_DESC_ATTR¶

uint8_t val[USB_CONFIG_DESC_SIZE]¶

union usb_iad_desc_t¶

#include <usb_types_ch9.h>

Structure representing a USB interface association descriptor.

Public Members

uint8_t bLength¶: Size of the descriptor in bytes

uint8_t bDescriptorType¶: INTERFACE ASSOCIATION Descriptor Type

uint8_t bFirstInterface¶: Interface number of the first interface that is associated with this function

uint8_t bInterfaceCount¶: Number of contiguous interfaces that are associated with this function

uint8_t bFunctionClass¶: Class code (assigned by USB-IF)

uint8_t bFunctionSubClass¶: Subclass code (assigned by USB-IF)

uint8_t bFunctionProtocol¶: Protocol code (assigned by USB-IF)

uint8_t iFunction¶: Index of string descriptor describing this function

struct usb_iad_desc_t::[anonymous] USB_DESC_ATTR¶

uint8_t val[USB_IAD_DESC_SIZE]¶

union usb_intf_desc_t¶

#include <usb_types_ch9.h>

Structure representing a USB interface descriptor.

See Table 9-12 of USB2.0 specification for more details

Public Members

uint8_t bLength¶: Size of the descriptor in bytes

uint8_t bDescriptorType¶: INTERFACE Descriptor Type

uint8_t bInterfaceNumber¶: Number of this interface.

uint8_t bAlternateSetting¶: Value used to select this alternate setting for the interface identified in the prior field

uint8_t bNumEndpoints¶: Number of endpoints used by this interface (excluding endpoint zero).

uint8_t bInterfaceClass¶: Class code (assigned by the USB-IF)

uint8_t bInterfaceSubClass¶: Subclass code (assigned by the USB-IF)

uint8_t bInterfaceProtocol¶: Protocol code (assigned by the USB)

uint8_t iInterface¶: Index of string descriptor describing this interface

struct usb_intf_desc_t::[anonymous] USB_DESC_ATTR¶

uint8_t val[USB_INTF_DESC_SIZE]¶

union usb_ep_desc_t¶

#include <usb_types_ch9.h>

Structure representing a USB endpoint descriptor.

See Table 9-13 of USB2.0 specification for more details

Public Members

uint8_t bLength¶: Size of the descriptor in bytes

uint8_t bDescriptorType¶: ENDPOINT Descriptor Type

uint8_t bEndpointAddress¶: The address of the endpoint on the USB device described by this descriptor

uint8_t bmAttributes¶: This field describes the endpoint’s attributes when it is configured using the bConfigurationValue.

uint16_t wMaxPacketSize¶: Maximum packet size this endpoint is capable of sending or receiving when this configuration is selected.

uint8_t bInterval¶: Interval for polling Isochronous and Interrupt endpoints. Expressed in frames or microframes depending on the device operating speed (1 ms for Low-Speed and Full-Speed or 125 us for USB High-Speed and above).

struct usb_ep_desc_t::[anonymous] USB_DESC_ATTR¶

uint8_t val[USB_EP_DESC_SIZE]¶

union usb_str_desc_t¶

#include <usb_types_ch9.h>

Structure representing a USB string descriptor.

Public Members

uint8_t bLength¶: Size of the descriptor in bytes

uint8_t bDescriptorType¶: STRING Descriptor Type

uint16_t wData[1]¶: UTF-16LE encoded

struct usb_str_desc_t::[anonymous] USB_DESC_ATTR¶

uint8_t val[USB_STR_DESC_SIZE]¶

Macros¶

USB_DESC_ATTR¶

USB_B_DESCRIPTOR_TYPE_DEVICE¶: Descriptor types from USB2.0 specification table 9.5.

USB_B_DESCRIPTOR_TYPE_CONFIGURATION¶

USB_B_DESCRIPTOR_TYPE_STRING¶

USB_B_DESCRIPTOR_TYPE_INTERFACE¶

USB_B_DESCRIPTOR_TYPE_ENDPOINT¶

USB_B_DESCRIPTOR_TYPE_DEVICE_QUALIFIER¶

USB_B_DESCRIPTOR_TYPE_OTHER_SPEED_CONFIGURATION¶

USB_B_DESCRIPTOR_TYPE_INTERFACE_POWER¶

USB_B_DESCRIPTOR_TYPE_OTG¶: Descriptor types from USB 2.0 ECN.

USB_B_DESCRIPTOR_TYPE_DEBUG¶

USB_B_DESCRIPTOR_TYPE_INTERFACE_ASSOCIATION¶

USB_B_DESCRIPTOR_TYPE_SECURITY¶: Descriptor types from Wireless USB spec.

USB_B_DESCRIPTOR_TYPE_KEY¶

USB_B_DESCRIPTOR_TYPE_ENCRYPTION_TYPE¶

USB_B_DESCRIPTOR_TYPE_BOS¶

USB_B_DESCRIPTOR_TYPE_DEVICE_CAPABILITY¶

USB_B_DESCRIPTOR_TYPE_WIRELESS_ENDPOINT_COMP¶

USB_B_DESCRIPTOR_TYPE_WIRE_ADAPTER¶

USB_B_DESCRIPTOR_TYPE_RPIPE¶

USB_B_DESCRIPTOR_TYPE_CS_RADIO_CONTROL¶

USB_B_DESCRIPTOR_TYPE_PIPE_USAGE¶: Descriptor types from UAS specification.

USB_SETUP_PACKET_SIZE¶: Size of a USB control transfer setup packet in bytes.

USB_BM_REQUEST_TYPE_DIR_OUT¶: Bit masks belonging to the bmRequestType field of a setup packet.

USB_BM_REQUEST_TYPE_DIR_IN¶

USB_BM_REQUEST_TYPE_TYPE_STANDARD¶

USB_BM_REQUEST_TYPE_TYPE_CLASS¶

USB_BM_REQUEST_TYPE_TYPE_VENDOR¶

USB_BM_REQUEST_TYPE_TYPE_RESERVED¶

USB_BM_REQUEST_TYPE_TYPE_MASK¶

USB_BM_REQUEST_TYPE_RECIP_DEVICE¶

USB_BM_REQUEST_TYPE_RECIP_INTERFACE¶

USB_BM_REQUEST_TYPE_RECIP_ENDPOINT¶

USB_BM_REQUEST_TYPE_RECIP_OTHER¶

USB_BM_REQUEST_TYPE_RECIP_MASK¶

USB_B_REQUEST_GET_STATUS¶: Bit masks belonging to the bRequest field of a setup packet.

USB_B_REQUEST_CLEAR_FEATURE¶

USB_B_REQUEST_SET_FEATURE¶

USB_B_REQUEST_SET_ADDRESS¶

USB_B_REQUEST_GET_DESCRIPTOR¶

USB_B_REQUEST_SET_DESCRIPTOR¶

USB_B_REQUEST_GET_CONFIGURATION¶

USB_B_REQUEST_SET_CONFIGURATION¶

USB_B_REQUEST_GET_INTERFACE¶

USB_B_REQUEST_SET_INTERFACE¶

USB_B_REQUEST_SYNCH_FRAME¶

USB_W_VALUE_DT_DEVICE¶: Bit masks belonging to the wValue field of a setup packet.

USB_W_VALUE_DT_CONFIG¶

USB_W_VALUE_DT_STRING¶

USB_W_VALUE_DT_INTERFACE¶

USB_W_VALUE_DT_ENDPOINT¶

USB_W_VALUE_DT_DEVICE_QUALIFIER¶

USB_W_VALUE_DT_OTHER_SPEED_CONFIG¶

USB_W_VALUE_DT_INTERFACE_POWER¶

USB_SETUP_PACKET_INIT_SET_ADDR(setup_pkt_ptr, addr)¶

Initializer for a SET_ADDRESS request.

Sets the address of a connected device

USB_SETUP_PACKET_INIT_GET_DEVICE_DESC(setup_pkt_ptr)¶: Initializer for a request to get a device’s device descriptor.

USB_SETUP_PACKET_INIT_GET_CONFIG(setup_pkt_ptr)¶: Initializer for a request to get a device’s current configuration number.

USB_SETUP_PACKET_INIT_GET_CONFIG_DESC(setup_pkt_ptr, desc_index, desc_len)¶

Initializer for a request to get one of the device’s current configuration descriptor.

desc_index indicates the configuration’s index number
Number of bytes of the configuration descriptor to get

USB_SETUP_PACKET_INIT_SET_CONFIG(setup_pkt_ptr, config_num)¶: Initializer for a request to set a device’s current configuration number.

USB_SETUP_PACKET_INIT_SET_INTERFACE(setup_pkt_ptr, intf_num, alt_setting_num)¶: Initializer for a request to set an interface’s alternate setting.

USB_SETUP_PACKET_INIT_GET_STR_DESC(setup_pkt_ptr, string_index, desc_len)¶: Initializer for a request to get an string descriptor.

USB_STANDARD_DESC_SIZE¶: Size of dummy USB standard descriptor.

USB_DEVICE_DESC_SIZE¶: Size of a USB device descriptor in bytes.

USB_CLASS_PER_INTERFACE¶: Possible base class values of the bDeviceClass field of a USB device descriptor.

USB_CLASS_AUDIO¶

USB_CLASS_COMM¶

USB_CLASS_HID¶

USB_CLASS_PHYSICAL¶

USB_CLASS_STILL_IMAGE¶

USB_CLASS_PRINTER¶

USB_CLASS_MASS_STORAGE¶

USB_CLASS_HUB¶

USB_CLASS_CDC_DATA¶

USB_CLASS_CSCID¶

USB_CLASS_CONTENT_SEC¶

USB_CLASS_VIDEO¶

USB_CLASS_WIRELESS_CONTROLLER¶

USB_CLASS_PERSONAL_HEALTHCARE¶

USB_CLASS_AUDIO_VIDEO¶

USB_CLASS_BILLBOARD¶

USB_CLASS_USB_TYPE_C_BRIDGE¶

USB_CLASS_MISC¶

USB_CLASS_APP_SPEC¶

USB_CLASS_VENDOR_SPEC¶

USB_SUBCLASS_VENDOR_SPEC¶: Vendor specific subclass code.

USB_CONFIG_DESC_SIZE¶

Size of a short USB configuration descriptor in bytes.

Note: The size of a full USB configuration includes all the interface and endpoint descriptors of that configuration.

USB_BM_ATTRIBUTES_ONE¶: Bit masks belonging to the bmAttributes field of a configuration descriptor.

USB_BM_ATTRIBUTES_SELFPOWER¶

USB_BM_ATTRIBUTES_WAKEUP¶

USB_BM_ATTRIBUTES_BATTERY¶

USB_IAD_DESC_SIZE¶: Size of a USB interface association descriptor in bytes.

USB_INTF_DESC_SIZE¶: Size of a USB interface descriptor in bytes.

USB_EP_DESC_SIZE¶: Size of a USB endpoint descriptor in bytes.

USB_B_ENDPOINT_ADDRESS_EP_NUM_MASK¶: Bit masks belonging to the bEndpointAddress field of an endpoint descriptor.

USB_B_ENDPOINT_ADDRESS_EP_DIR_MASK¶

USB_BM_ATTRIBUTES_XFERTYPE_MASK¶: Bit masks belonging to the bmAttributes field of an endpoint descriptor.

USB_BM_ATTRIBUTES_XFER_CONTROL¶

USB_BM_ATTRIBUTES_XFER_ISOC¶

USB_BM_ATTRIBUTES_XFER_BULK¶

USB_BM_ATTRIBUTES_XFER_INT¶

USB_BM_ATTRIBUTES_SYNCTYPE_MASK¶

USB_BM_ATTRIBUTES_SYNC_NONE¶

USB_BM_ATTRIBUTES_SYNC_ASYNC¶

USB_BM_ATTRIBUTES_SYNC_ADAPTIVE¶

USB_BM_ATTRIBUTES_SYNC_SYNC¶

USB_BM_ATTRIBUTES_USAGETYPE_MASK¶

USB_BM_ATTRIBUTES_USAGE_DATA¶

USB_BM_ATTRIBUTES_USAGE_FEEDBACK¶

USB_BM_ATTRIBUTES_USAGE_IMPLICIT_FB¶

USB_EP_DESC_GET_XFERTYPE(desc_ptr)¶: Macro helpers to get information about an endpoint from its descriptor.

USB_EP_DESC_GET_EP_NUM(desc_ptr)¶

USB_EP_DESC_GET_EP_DIR(desc_ptr)¶

USB_EP_DESC_GET_MPS(desc_ptr)¶

USB_STR_DESC_SIZE¶: Size of a short USB string descriptor in bytes.

Enumerations¶

enum usb_device_state_t¶

USB2.0 device states.

See Table 9-1 of USB2.0 specification for more details

Note: The USB_DEVICE_STATE_NOT_ATTACHED is not part of the USB2.0 specification, but is a catch all state for devices that need to be cleaned up after a sudden disconnection or port error.

Values:

USB_DEVICE_STATE_NOT_ATTACHED¶: The device was previously configured or suspended, but is no longer attached (either suddenly disconnected or a port error)

USB_DEVICE_STATE_ATTACHED¶: Device is attached to the USB, but is not powered.

USB_DEVICE_STATE_POWERED¶: Device is attached to the USB and powered, but has not been reset.

USB_DEVICE_STATE_DEFAULT¶: Device is attached to the USB and powered and has been reset, but has not been assigned a unique address. Device responds at the default address.

USB_DEVICE_STATE_ADDRESS¶: Device is attached to the USB, powered, has been reset, and a unique device address has been assigned. Device is not configured.

USB_DEVICE_STATE_CONFIGURED¶: Device is attached to the USB, powered, has been reset, has a unique address, is configured, and is not suspended. The host may now use the function provided by the device.

USB_DEVICE_STATE_SUSPENDED¶: Device is, at minimum, attached to the USB and is powered and has not seen bus activity for 3 ms. It may also have a unique address and be configured for use. However, because the device is suspended, the host may not use the device’s function.

Provide feedback about this document