API Documentation: usbd-fs-stm32

void usbd_init(void);

Library initializer.

Function that initializes the USB peripheral, including the internal memory buffers.

This function must be called during firmware initialization, before entering the firmware main loop.

void usbd_task(void);

Library main loop task.

Function that runs all the operations related to the USB peripheral.

This function must be called periodically from the firmware main loop or from the USB IRQ handler (make sure to initialize the handler function properly).

const usb_string_descriptor_t* usbd_serial_internal_string_descriptor(void);

Generate USB string descriptor from the internal STM32 serial number.

Returns

A reference to an internally managed usb_string_descriptor_t.

Function that generates a USB string descriptor based on the internal serial number inserted by ST during manufacturing.

It should be called from the usbd_get_string_descriptor_cb when handling the request for a string descriptor with the index iSerialNumber, as defined by the device descriptor.

bool usbd_in(uint8_t ept, const void *buf, uint16_t buflen);

Transmit data to the host in response to a USB IN request.

Arguments

[in] ept	Endpoint number.
[in] buf	Pointer to a buffer containing data to be transmitted to the host.
[in] buflen	Size of the buf buffer, in bytes.

Returns

A boolean indicating that the data was successfully scheduled for transmission.

The buffer should not exceed the size of the endpoint, as defined by the endpoint descriptor via usb_endpoint_descriptor_t. To send larger chunks of data the caller must split the data and call the function multiple times in response to multiple IN requests.

Usually if the final chunk of data sent has the same size of the endpoint buffer, a zero length packet must be also transmitted to the host, to inform that the transmission is complete. This is NOT handled automatically by the library.

uint16_t usbd_out(uint8_t ept, void *buf, uint16_t buflen);

Receive data from the host following a USB OUT request.

Arguments

[in] ept	Endpoint number.
[out] buf	Pointer to a buffer to receive the data transmitted by the host.
[in] buflen	Size of the buf buffer, in bytes.

Returns

The number of bytes received from the host.

The buffer should not exceed the size of the endpoint, as defined by the endpoint descriptor via usb_endpoint_descriptor_t. Ideally it should be at least the same size of the endpoint.

Usually the firmware should continue accepting USB OUT requests and receive the data by calling this function while the number of bytes received is equal to the endpoint size. When the number of bytes received is smaller than then endpoint size the reception is completed. This is NOT handled automatically by the library.

void usbd_control_in(const void *buf, uint16_t buflen, uint16_t reqlen);

Transmit data to the host in response to a CONTROL USB IN request on endpoint 0.

Arguments

[in] buf	Pointer to a buffer containing data to be transmitted to the host.
[in] buflen	Size of the buf buffer, in bytes.
[in] reqlen	Size of the CONTROL USB IN request data.

The buffer may exceed the size of the endpoint 0 (64 bytes). The function is capable of handling the transmission of the whole buffer automatically.

const usb_device_descriptor_t* usbd_get_device_descriptor_cb(void);

Required callback to define USB device descriptor.

Returns

A reference to a constant usb_device_descriptor_t.

const usb_config_descriptor_t* usbd_get_config_descriptor_cb(void);

Required callback to define USB configuration descriptor.

Returns

A reference to a constant usb_config_descriptor_t.

const usb_interface_descriptor_t* usbd_get_interface_descriptor_cb(uint16_t itf);

Required callback to define USB interface descriptor.

Arguments

[in] itf	Interface number.

Returns

A reference to a constant usb_interface_descriptor_t.

const usb_string_descriptor_t* usbd_get_string_descriptor_cb(uint16_t lang, uint8_t idx);

Required callback to define USB string descriptor.

Arguments

[in] lang	The 16 bits identifier of the requested language.
[in] idx	The index of the string descriptor to be returned, as defined by the descriptor.

Returns

A reference to a constant usb_string_descriptor_t.

void usbd_reset_hook_cb(bool before) __attribute__((weak));

Optional hook callback for USB RESET requests.

Arguments

[in] before	Notifies if the callback call is happening before or after the device reset.

void usbd_set_address_hook_cb(uint8_t addr) __attribute__((weak));

Optional hook callback for USB SET_ADDRESS control requests.

Arguments

[in] addr	The address assigned by the host.

Setting the address is the last step of the device enumeration process. The device can be considered as enumerated by the host when this hook is called.

void usbd_suspend_hook_cb(void) __attribute__((weak));

Optional hook callback for USB SUSPEND requests.

This function is responsible for taking any required actions to reduce the power consumption of the device during suspension. The library will enable the internal STM32 low-power mode automatically, but this only reduces the consumption of the USB peripheral itself.

void usbd_resume_hook_cb(void) __attribute__((weak));

Optional hook callback for USB RESUME requests.

This function is responsible for taking any required actions to return the device to normal execution after a suspension, usually by reversing the actions taken by the usbd_suspend_hook_cb callback when the device entered suspension. The library will disable the internal STM32 low-power mode automatically.

void usbd_out_cb(uint8_t ept) __attribute__((weak));

Optional callback for USB OUT requests.

Arguments

[in] ept	Endpoint number.

void usbd_in_cb(uint8_t ept) __attribute__((weak));

Optional callback for USB IN requests.

Arguments

[in] ept	Endpoint number.

bool usbd_ctrl_request_handle_class_cb(usb_ctrl_request_t *req) __attribute__((weak));

Optional callback for USB CONTROL class requests.

Arguments

[in] req	A reference to a usb_ctrl_request_t.

bool usbd_ctrl_request_handle_vendor_cb(usb_ctrl_request_t *req) __attribute__((weak));

Optional callback for USB CONTROL vendor requests.

Arguments

[in] req	A reference to a usb_ctrl_request_t.

bool usbd_ctrl_request_get_descriptor_interface_cb(usb_ctrl_request_t *req) __attribute__((weak));

Optional callback for USB CONTROL GET_DESCRIPTOR INTERFACE requests.

Arguments

[in] req	A reference to a usb_ctrl_request_t.

#define USBD_EP0_SIZE 64

Size of Endpoint 0 memory buffers.

These buffers are always 64 bytes.

When defining USB descriptors via usbd_device_descriptor_t struct, make sure to set bMaxPacketSize0 property to USBD_EP0_SIZE.

typedef struct __attribute__((packed)) {
    uint8_t  bmRequestType;
    uint8_t  bRequest;
    uint16_t wValue;
    uint16_t wIndex;
    uint16_t wLength;
} usb_ctrl_request_t;

USB control request (setup) type.

typedef struct __attribute__((packed)) {
    uint8_t  bLength;
    uint8_t  bDescriptorType;
    uint16_t bcdUSB;
    uint8_t  bDeviceClass;
    uint8_t  bDeviceSubClass;
    uint8_t  bDeviceProtocol;
    uint8_t  bMaxPacketSize0;
    uint16_t idVendor;
    uint16_t idProduct;
    uint16_t bcdDevice;
    uint8_t  iManufacturer;
    uint8_t  iProduct;
    uint8_t  iSerialNumber;
    uint8_t  bNumConfigurations;
} usb_device_descriptor_t;

USB device descriptor type.

typedef struct __attribute__((packed)) {
    uint8_t  bLength;
    uint8_t  bDescriptorType;
    uint16_t wTotalLength;
    uint8_t  bNumInterfaces;
    uint8_t  bConfigurationValue;
    uint8_t  iConfiguration;
    uint8_t  bmAttributes;
    uint8_t  bMaxPower;
} usb_config_descriptor_t;

USB configuration descriptor type.

typedef struct __attribute__((packed)) {
    uint8_t  bLength;
    uint8_t  bDescriptorType;
    uint16_t wData[];
} usb_string_descriptor_t;

USB string descriptor type.

typedef struct __attribute__((packed)) {
    uint8_t bLength;
    uint8_t bDescriptorType;
    uint8_t bInterfaceNumber;
    uint8_t bAlternateSetting;
    uint8_t bNumEndpoints;
    uint8_t bInterfaceClass;
    uint8_t bInterfaceSubClass;
    uint8_t bInterfaceProtocol;
    uint8_t iInterface;
} usb_interface_descriptor_t;

USB interface descriptor type.

typedef struct __attribute__((packed)) {
    uint8_t  bLength;
    uint8_t  bDescriptorType;
    uint8_t  bEndpointAddress;
    uint8_t  bmAttributes;
    uint16_t wMaxPacketSize;
    uint8_t  bInterval;
} usb_endpoint_descriptor_t;

USB endpoint descriptor type.

#define USB_REQ_DIR_HOST_TO_DEVICE (0 << 7)

#define USB_REQ_DIR_DEVICE_TO_HOST (1 << 7)

#define USB_REQ_DIR_MASK           (1 << 7)

#define USB_REQ_TYPE_STANDARD (0 << 5)

#define USB_REQ_TYPE_CLASS    (1 << 5)

#define USB_REQ_TYPE_VENDOR   (2 << 5)

#define USB_REQ_TYPE_MASK     (3 << 5)

#define USB_REQ_RCPT_DEVICE    (0 << 0)

#define USB_REQ_RCPT_INTERFACE (1 << 0)

#define USB_REQ_RCPT_ENDPOINT  (2 << 0)

#define USB_REQ_RCPT_OTHER     (3 << 0)

#define USB_REQ_RCPT_MASK      (3 << 0)

#define USB_REQ_GET_STATUS        0x00

#define USB_REQ_CLEAR_FEATURE     0x01

#define USB_REQ_SET_FEATURE       0x03

#define USB_REQ_SET_ADDRESS       0x05

#define USB_REQ_GET_DESCRIPTOR    0x06

#define USB_REQ_SET_DESCRIPTOR    0x07

#define USB_REQ_GET_CONFIGURATION 0x08

#define USB_REQ_SET_CONFIGURATION 0x09

#define USB_REQ_GET_INTERFACE     0x0a

#define USB_REQ_SET_INTERFACE     0x0b

#define USB_REQ_SYNCH_FRAME       0x0c

#define USB_DESCR_TYPE_DEVICE                    0x01

#define USB_DESCR_TYPE_CONFIGURATION             0x02

#define USB_DESCR_TYPE_STRING                    0x03

#define USB_DESCR_TYPE_INTERFACE                 0x04

#define USB_DESCR_TYPE_ENDPOINT                  0x05

#define USB_DESCR_TYPE_DEVICE_QUALIFIER          0x06

#define USB_DESCR_TYPE_OTHER_SPEED_CONFIGURATION 0x07

#define USB_DESCR_CONFIG_ATTR_RESERVED      (1 << 7)

#define USB_DESCR_CONFIG_ATTR_SELF_POWERED  (1 << 6)

#define USB_DESCR_CONFIG_ATTR_REMOTE_WAKEUP (1 << 5)

#define USB_DESCR_DEV_CLASS_PER_INTERFACE       0x00

#define USB_DESCR_DEV_CLASS_AUDIO               0x01

#define USB_DESCR_DEV_CLASS_COMM                0x02

#define USB_DESCR_DEV_CLASS_HID                 0x03

#define USB_DESCR_DEV_CLASS_PHYSICAL            0x05

#define USB_DESCR_DEV_CLASS_STILL_IMAGE         0x06

#define USB_DESCR_DEV_CLASS_PRINTER             0x07

#define USB_DESCR_DEV_CLASS_MASS_STORAGE        0x08

#define USB_DESCR_DEV_CLASS_HUB                 0x09

#define USB_DESCR_DEV_CLASS_CDC_DATA            0x0a

#define USB_DESCR_DEV_CLASS_CSCID               0x0b

#define USB_DESCR_DEV_CLASS_CONTENT_SEC         0x0d

#define USB_DESCR_DEV_CLASS_VIDEO               0x0e

#define USB_DESCR_DEV_CLASS_WIRELESS_CONTROLLER 0xe0

#define USB_DESCR_DEV_CLASS_PERSONAL_HEALTHCARE 0x0f

#define USB_DESCR_DEV_CLASS_AUDIO_VIDEO         0x10

#define USB_DESCR_DEV_CLASS_BILLBOARD           0x11

#define USB_DESCR_DEV_CLASS_USB_TYPE_C_BRIDGE   0x12

#define USB_DESCR_DEV_CLASS_MISC                0xef

#define USB_DESCR_DEV_CLASS_APP_SPEC            0xfe

#define USB_DESCR_DEV_CLASS_VENDOR_SPEC         0xff

#define USB_DESCR_DEV_SUBCLASS_VENDOR_SPEC      0xff

#define USB_DESCR_EPT_ADDR_DIR_OUT  (0 << 7)

#define USB_DESCR_EPT_ADDR_DIR_IN   (1 << 7)

#define USB_DESCR_EPT_ADDR_DIR_MASK (1 << 7)

#define USB_DESCR_EPT_ATTR_CONTROL                (0 << 0)

#define USB_DESCR_EPT_ATTR_ISOCHRONOUS            (1 << 0)

#define USB_DESCR_EPT_ATTR_BULK                   (2 << 0)

#define USB_DESCR_EPT_ATTR_INTERRUPT              (3 << 0)

#define USB_DESCR_EPT_ATTR_NO_SYNC                (0 << 2)

#define USB_DESCR_EPT_ATTR_ASYNC                  (1 << 2)

#define USB_DESCR_EPT_ATTR_ADAPTIVE               (2 << 2)

#define USB_DESCR_EPT_ATTR_SYNC                   (3 << 2)

#define USB_DESCR_EPT_ATTR_DATA                   (0 << 4)

#define USB_DESCR_EPT_ATTR_FEEDBACK               (1 << 2)

#define USB_DESCR_EPT_ATTR_IMPLICIT_FEEDBACK_DATA (2 << 2)

#define USB_DESCR_FEAT_ENDPOINT_HALT        0x00

#define USB_DESCR_FEAT_DEVICE_REMOTE_WAKEUP 0x01

#define USB_DESCR_FEAT_TEST_MODE            0x02

typedef struct __attribute__((packed)) {
    uint8_t  bLength;
    uint8_t  bDescriptorType;
    uint8_t  bDescriptorSubtype;
    uint16_t bcdMSC;
    uint16_t wTotalLength;
} usb_midi_streaming_header_t;

USB MIDI streaming header type.

typedef struct __attribute__((packed)) {
    uint8_t bLength;
    uint8_t bDescriptorType;
    uint8_t bDescriptorSubtype;
    uint8_t bJackType;
    uint8_t bJackID;
    uint8_t iJack;
} usb_midi_streaming_in_jack_t;

USB MIDI streaming input jack type.

typedef struct __attribute__((packed)) {
    uint8_t bLength;
    uint8_t bDescriptorType;
    uint8_t bDescriptorSubtype;
    uint8_t bJackType;
    uint8_t bJackID;
    uint8_t bNrInputPins;
    uint8_t baSourceID;
    uint8_t baSourcePin;
    uint8_t iJack;
} usb_midi_streaming_out_jack_t;

USB MIDI streaming output jack type.

typedef struct __attribute__((packed)) {
    uint8_t bLength;
    uint8_t bDescriptorType;
    uint8_t bDescriptorSubtype;
    uint8_t bNumEmbMIDIJack;
    uint8_t baAssocJackID;
} usb_midi_streaming_endpoint_descriptor_t;

USB MIDI streaming endpoint descriptor type.

#define USB_MIDI_DESCR_SUBTYPE_MS_HEADER        0x01

#define USB_MIDI_DESCR_SUBTYPE_MS_MIDI_IN_JACK  0x02

#define USB_MIDI_DESCR_SUBTYPE_MS_MIDI_OUT_JACK 0x03

#define USB_MIDI_DESCR_SUBTYPE_MS_ELEMENT       0x04

#define USB_MIDI_DESCR_EPT_SUBTYPE_MS_GENERAL 0x01

#define USB_MIDI_DESCR_JACK_TYPE_MS_EMBEDDED 0x01

#define USB_MIDI_DESCR_JACK_TYPE_MS_EXTERNAL 0x02

typedef struct __attribute__((packed)) {
    uint8_t  bLength;
    uint8_t  bDescriptorType;
    uint8_t  bEndpointAddress;
    uint8_t  bmAttributes;
    uint16_t wMaxPacketSize;
    uint8_t  bInterval;
    uint8_t  bRefresh;
    uint8_t  bSynchAddress;
} usb_audio_endpoint_descriptor_t;

USB audio endpoint descriptor type.

typedef struct __attribute__((packed)) {
    uint8_t  bLength;
    uint8_t  bDescriptorType;
    uint8_t  bDescriptorSubtype;
    uint16_t bcdADC;
    uint16_t wTotalLength;
    uint8_t  bInCollection;
    uint8_t  baInterfaceNr;
} usb_audio_ctrl_header_t;

USB audio control header type.

#define USB_AUDIO_DESCR_UAC_VERSION_1 0x00

#define USB_AUDIO_DESCR_UAC_VERSION_2 0x20

#define USB_AUDIO_DESCR_UAC_VERSION_3 0x30

#define USB_AUDIO_DESCR_DEV_SUBCLASS_AUDIOCONTROL   0x01

#define USB_AUDIO_DESCR_DEV_SUBCLASS_AUDIOSTREAMING 0x02

#define USB_AUDIO_DESCR_DEV_SUBCLASS_MIDISTREAMING  0x03

#define USB_AUDIO_DESCR_SUBTYPE_UAC_HEADER           0x01

#define USB_AUDIO_DESCR_SUBTYPE_UAC_INPUT_TERMINAL   0x02

#define USB_AUDIO_DESCR_SUBTYPE_UAC_OUTPUT_TERMINAL  0x03

#define USB_AUDIO_DESCR_SUBTYPE_UAC_MIXER_UNIT       0x04

#define USB_AUDIO_DESCR_SUBTYPE_UAC_SELECTOR_UNIT0   0x05

#define USB_AUDIO_DESCR_SUBTYPE_UAC_FEATURE_UNIT     0x06

#define USB_AUDIO_DESCR_SUBTYPE_UAC1_PROCESSING_UNIT 0x07

#define USB_AUDIO_DESCR_SUBTYPE_UAC1_EXTENSION_UNIT  0x08

typedef struct __attribute__((packed)) {
    uint8_t  bLength;
    uint8_t  bDescriptorType;
    uint16_t bcdHID;
    uint8_t  bCountryCode;
    uint8_t  bNumDescriptors;
    uint8_t  bDescriptorType2;
    uint16_t wDescriptorLength;
} usb_hid_descriptor_t;

USB HID descriptor type.

#define USB_REQ_HID_GET_REPORT    0x01

#define USB_REQ_HID_GET_IDLE      0x02

#define USB_REQ_HID_GET_PROTOCOL  0x03

#define USB_REQ_HID_SET_REPORT    0x09

#define USB_REQ_HID_SET_IDLE      0x0a

#define USB_REQ_HID_SET_PROTOCOL  0x0b

#define USB_DESCR_TYPE_HID        0x21

#define USB_DESCR_TYPE_HID_REPORT 0x22

#define USB_DESCR_TYPE_HID_PHYS   0x23