Overview
The USB API follows the USB 2.0 specification and provides access to USB devices through a Logical Device Driver (LDD) interface. You can register drivers for specific USB device classes or vendor-specific devices.Before using USB functions, you must load the SYSMODULE_USB system module using
sysModuleLoad().Error Codes
| Code | Value | Description |
|---|---|---|
USB_OK | 0x00 | Operation successful |
USB_ERR_NOT_INITIALIZED | 0x80110001 | USB subsystem not initialized |
USB_ERR_ALREADY_INITIALIZED | 0x80110002 | Already initialized |
USB_ERR_NO_MEMORY | 0x80110003 | Out of memory |
USB_ERR_INVALID_PARAM | 0x80110004 | Invalid parameter |
USB_ERR_INVALID_TRANSFER_TYPE | 0x80110005 | Invalid transfer type |
USB_ERR_LDD_ALREADY_REGISTERED | 0x80110006 | LDD already registered |
USB_ERR_LDD_NOT_ALLOCATED | 0x80110007 | LDD not allocated |
USB_ERR_LDD_NOT_RELEASED | 0x80110008 | LDD not released |
USB_ERR_LDD_NOT_FOUND | 0x80110009 | LDD not found |
USB_ERR_DEVICE_NOT_FOUND | 0x8011000a | Device not found |
USB_ERR_PIPE_NOT_ALLOCATED | 0x8011000b | Pipe not allocated |
USB_ERR_PIPE_NOT_RELEASED | 0x8011000c | Pipe not released |
USB_ERR_PIPE_NOT_FOUND | 0x8011000d | Pipe not found |
USB_ERR_IOREQ_NOT_ALLOCATED | 0x8011000e | I/O request not allocated |
USB_ERR_IOREQ_NOT_RELEASED | 0x8011000f | I/O request not released |
USB_ERR_IOREQ_NOT_FOUND | 0x80110010 | I/O request not found |
USB_ERR_CANNOT_GET_DESCRIPTOR | 0x80110011 | Cannot get descriptor |
USB_ERR_FATAL | 0x801100ff | Fatal error |
Device Classes
Standard USB device classes.
USB_CLASS_PER_INTERFACE(0x00) - Class defined per interfaceUSB_CLASS_AUDIO(0x01) - Audio deviceUSB_CLASS_COMM(0x02) - Communications deviceUSB_CLASS_HID(0x03) - Human Interface DeviceUSB_CLASS_MONITOR(0x04) - Monitor deviceUSB_CLASS_PHYSICAL(0x05) - Physical interface deviceUSB_CLASS_PTP(0x06) - Picture Transfer ProtocolUSB_CLASS_PRINTER(0x07) - Printer deviceUSB_CLASS_STORAGE(0x08) - Mass storage deviceUSB_CLASS_HUB(0x09) - USB hubUSB_CLASS_DATA(0x0a) - CDC data interfaceUSB_CLASS_CHIP(0x0b) - Smart card deviceUSB_CLASS_SECURITY(0x0d) - Security deviceUSB_CLASS_VIDEO(0x0e) - Video deviceUSB_CLASS_WIRELESS(0xe0) - Wireless controllerUSB_CLASS_MISC(0xef) - Miscellaneous deviceUSB_CLASS_APPLICATION(0xfe) - Application specificUSB_CLASS_VENDOR_SPEC(0xff) - Vendor specific
Transfer Types
USB endpoint transfer types.
USB_ENDPOINT_TRANSFER_TYPE_CONTROL(0x00) - Control transferUSB_ENDPOINT_TRANSFER_TYPE_ISOCHRONOUS(0x01) - Isochronous transferUSB_ENDPOINT_TRANSFER_TYPE_BULK(0x02) - Bulk transferUSB_ENDPOINT_TRANSFER_TYPE_INTERRUPT(0x03) - Interrupt transfer
Device Speed
USB device speed.
USB_DEVICE_SPEED_LS(0) - Low speed (1.5 Mbps)USB_DEVICE_SPEED_FS(1) - Full speed (12 Mbps)USB_DEVICE_SPEED_HS(2) - High speed (480 Mbps)
Core Functions
usbInit
USB_OK on success, error code otherwise.
This is automatically called by the system in most cases. Only call explicitly if needed.
usbEnd
USB_OK on success, error code otherwise.
usbRegisterLdd
LDD operations structure.
Driver name string.
Probe function called when device is detected. Return USB_PROBE_SUCCEEDED to claim device.
Attach function called when driver claims device. Perform initialization here.
Detach function called when device is disconnected. Perform cleanup here.
USB_OK on success, error code otherwise.
usbUnregisterLdd
LDD operations structure to unregister.
USB_OK on success, error code otherwise.
usbRegisterExtraLdd
LDD operations structure.
USB Vendor ID to match.
USB Product ID to match.
USB_OK on success, error code otherwise.
usbRegisterExtraLdd2
LDD operations structure.
USB Vendor ID to match.
Minimum Product ID (inclusive).
Maximum Product ID (inclusive).
USB_OK on success, error code otherwise.
usbUnregisterExtraLdd
LDD operations structure to unregister.
USB_OK on success, error code otherwise.
Pipe Functions
usbOpenPipe
Device ID from probe/attach callback.
Endpoint descriptor pointer (from usbScanStaticDescriptor).
usbClosePipe
Pipe ID from usbOpenPipe.
USB_OK on success, error code otherwise.
Transfer Functions
usbBulkTransfer
Pipe ID for bulk endpoint.
Data buffer (allocated with usbAllocateMemory).
Length of data to transfer.
Callback function called when transfer completes.
User argument passed to callback.
USB_OK on success, error code otherwise.
usbControlTransfer
Pipe ID (typically control pipe 0).
Data buffer for data stage (can be NULL if wLength is 0).
Callback function called when transfer completes.
User argument passed to callback.
USB_OK on success, error code otherwise.
usbInterruptTransfer
Pipe ID for interrupt endpoint.
Data buffer (allocated with usbAllocateMemory).
Length of data to transfer.
Callback function called when transfer completes.
User argument passed to callback.
USB_OK on success, error code otherwise.
usbIsochronousTransfer
Pipe ID for isochronous endpoint.
Callback function called when transfer completes.
User argument passed to callback.
USB_OK on success, error code otherwise.
usbHSIsochronousTransfer
Pipe ID for isochronous endpoint.
High-speed isochronous transfer request structure.
Callback function called when transfer completes.
User argument passed to callback.
USB_OK on success, error code otherwise.
Device Information Functions
usbGetDeviceLocation
Device ID.
Pointer to receive location array.
USB_OK on success, error code otherwise.
usbGetDeviceSpeed
Device ID.
Pointer to receive speed (USB_DEVICE_SPEED_*).
USB_OK on success, error code otherwise.
usbScanStaticDescriptor
Device ID.
Current descriptor pointer (NULL to start from beginning).
Descriptor type to find (USB_DESCRIPTOR_TYPE_*).
Memory Management
usbAllocateMemory
Pointer to receive allocated memory address.
Size of memory to allocate.
USB_OK on success, error code otherwise.
usbFreeMemory
Memory pointer to free.
USB_OK on success, error code otherwise.
Private Data
usbGetPrivateData
Device ID.
usbSetPrivateData
Device ID.
Private data pointer.
USB_OK on success, error code otherwise.
Usage Example
Standard Control Transfer Macros
The USB library provides convenience macros for standard control requests:usbGetDescriptor()- Get device, configuration, or string descriptorusbSetConfiguration()- Set device configurationusbGetConfiguration()- Get current configurationusbSetInterface()- Set alternate interfaceusbGetInterface()- Get current alternate interfaceusbClearEndpointFeature()- Clear endpoint haltusbGetDeviceStatus()- Get device statususbSetAddress()- Set device address (for USB host mode)
Descriptor Structures
Key USB descriptor structures:usbDeviceDescriptor
Contains device information including vendor/product IDs, device class, and configuration count.usbConfigDescriptor
Describes a device configuration including power requirements and interface count.usbInterfaceDescriptor
Describes an interface within a configuration, including class and endpoint count.usbEndpointDescriptor
Describes an endpoint including direction, transfer type, and maximum packet size.Use
usbScanStaticDescriptor() to iterate through descriptors rather than parsing them manually.