USB Component  Version 6.17.0
MDK Middleware for USB Device and Host Communication
User API

User API reference of the USB Host Core. More...

Functions

uint32_t USBH_GetVersion (void)
 Get version of USB Host stack. More...
 
usbStatus USBH_Initialize (uint8_t ctrl)
 Initialize USB Host stack and controller. More...
 
usbStatus USBH_Uninitialize (uint8_t ctrl)
 De-initialize USB Host stack and controller. More...
 
usbStatus USBH_Port_Suspend (uint8_t ctrl, uint8_t port)
 Suspend a root HUB port on specified controller. More...
 
usbStatus USBH_Port_Resume (uint8_t ctrl, uint8_t port)
 Resume a root HUB port on specified controller. More...
 
uint8_t USBH_Device_GetController (uint8_t device)
 Get index of USB Host controller to which USB Device is connected. More...
 
uint8_t USBH_Device_GetPort (uint8_t device)
 Get index of USB Host Root HUB port to which USB Device is connected. More...
 
usbStatus USBH_Device_GetStatus (uint8_t device)
 Get status of USB Device. More...
 
int32_t USBH_Device_GetSpeed (uint8_t device)
 Get communication speed of USB Device. More...
 
uint8_t USBH_Device_GetAddress (uint8_t device)
 Get communication address of USB Device. More...
 
uint16_t USBH_Device_GetVID (uint8_t device)
 Get Vendor ID (VID) of USB Device. More...
 
uint16_t USBH_Device_GetPID (uint8_t device)
 Get Product ID (PID) of USB Device. More...
 
usbStatus USBH_Device_GetStringDescriptor (uint8_t device, uint8_t index, uint16_t language_id, uint8_t *descriptor_data, uint16_t descriptor_length)
 Get String Descriptor of USB Device. More...
 
void USBH_Notify (uint8_t ctrl, uint8_t port, uint8_t device, USBH_NOTIFY notify)
 Callback function called when some event has happened on corresponding controller and port. More...
 

Description

User API reference of the USB Host Core.

Function Documentation

◆ USBH_GetVersion()

uint32_t USBH_GetVersion ( void  )

Get version of USB Host stack.

Returns
version (major.minor.revision : mmnnnrrrr decimal)

The function USBH_GetVersion retrieves version of the USB Host library.

Version is encoded as follows:

  • decimal digits 9..7: major
  • decimal digits 6..4: minor
  • decimal digits 3..0: revision
Note
Example: value 10020003 decimal represents version: major = 1, minor = 2, revision = 3

◆ USBH_Initialize()

usbStatus USBH_Initialize ( uint8_t  ctrl)

Initialize USB Host stack and controller.

Parameters
[in]ctrlindex of USB Host controller.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_Initialize initializes the USB Host Stack and the USB Host Controller Hardware and prepares the USB Host Controller to detect whether an USB device gets attached or detached from the USB bus. It starts a thread responsible for the USB Device enumeration process. Call this function before calling any other USB Host functions. The function does not initialize any non-USB Host hardware features.

Code Example

#include <rl_usb.h>
int main (void) {
..
USBH_Initialize(0); // USB Host 0 Initialize
..
}

◆ USBH_Uninitialize()

usbStatus USBH_Uninitialize ( uint8_t  ctrl)

De-initialize USB Host stack and controller.

Parameters
[in]ctrlindex of USB Host controller.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_Uninitialize de-initializes the USB Host Stack and the USB Host Controller Hardware. It can be used if during the application run-time the USB Host Stack needs to be disabled for whatever reason (for example for lowering power consumption). Reinitialize the USB Host Stack only with USBH_Initialize.

Code Example

#include <rl_usb.h>
int main (void) {
..
USBH_Initialize(0); // USB Host 0 Initialize
..
USBH_Uninitialize(0); // USB Host 0 De-Initialize
..
}

◆ USBH_Port_Suspend()

usbStatus USBH_Port_Suspend ( uint8_t  ctrl,
uint8_t  port 
)

Suspend a root HUB port on specified controller.

Parameters
[in]ctrlindex of USB Host controller.
[in]portroot HUB port.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_Port_Suspend suspends the USB bus, stops generating Start Of Frame or Keep-Alive signals.

The argument ctrl specifies the USB Host controller number.

The argument port specifies the USB Host root HUB port number.

◆ USBH_Port_Resume()

usbStatus USBH_Port_Resume ( uint8_t  ctrl,
uint8_t  port 
)

Resume a root HUB port on specified controller.

Parameters
[in]ctrlindex of USB Host controller.
[in]portroot HUB port.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_Port_Resume re-activates the USB bus from suspended state, starts generating Start Of Frame or Keep-Alive signals.

The argument ctrl specifies the USB Host controller number.

The argument port specifies the USB Host root HUB port number.

◆ USBH_Device_GetController()

uint8_t USBH_Device_GetController ( uint8_t  device)

Get index of USB Host controller to which USB Device is connected.

Parameters
[in]deviceindex of USB Device.
Returns
index of USB Host controller or non-existing USB Host controller :
  • value != 255 : index of USB Host controller
  • value 255 : non-existing USB Host controller

The function USBH_Device_GetController retrieves the USB Host controller index to which the requested device is connected to.

The argument device specifies the instance of the device.

◆ USBH_Device_GetPort()

uint8_t USBH_Device_GetPort ( uint8_t  device)

Get index of USB Host Root HUB port to which USB Device is connected.

Parameters
[in]deviceindex of USB Device.
Returns
index of USB Host Root HUB port or non-existing USB Host Root HUB port :
  • value <= 15 : index of USB Host Root HUB port
  • value 255 : non-existing USB Host Root HUB port

The function USBH_Device_GetPort retrieves the USB Host root HUB port index to which the requested device is connected to.

The argument device specifies the instance of the device.

◆ USBH_Device_GetStatus()

usbStatus USBH_Device_GetStatus ( uint8_t  device)

Get status of USB Device.

Parameters
[in]deviceindex of USB Device.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_Device_GetStatus checks if a device instance is connected and initialized.

The argument device specifies the instance of the device.

◆ USBH_Device_GetSpeed()

int32_t USBH_Device_GetSpeed ( uint8_t  device)

Get communication speed of USB Device.

Parameters
[in]deviceindex of USB Device.
Returns
communication speed :
  • USB_SPEED_LOW = low speed
  • USB_SPEED_FULL = full speed
  • USB_SPEED_HIGH = high speed

The function USBH_Device_GetSpeed retrieves current communication speed of the connected device.

The argument device specifies the instance of the device.

◆ USBH_Device_GetAddress()

int32_t USBH_Device_GetAddress ( uint8_t  device)

Get communication address of USB Device.

Parameters
[in]deviceindex of USB Device.
Returns
enumerated address or invalid address :
  • value <= 127 : enumerated address
  • value 255 : invalid address

The function USBH_Device_GetAddress retrieves current communication address of the connected device.

The argument device specifies the instance of the device.

◆ USBH_Device_GetVID()

uint16_t USBH_Device_GetVID ( uint8_t  device)

Get Vendor ID (VID) of USB Device.

Parameters
[in]deviceindex of USB Device.
Returns
Vendor ID.

The function USBH_Device_GetVID retrieves Vendor ID of the connected device.

The argument device specifies the instance of the device.

◆ USBH_Device_GetPID()

uint16_t USBH_Device_GetPID ( uint8_t  device)

Get Product ID (PID) of USB Device.

Parameters
[in]deviceindex of USB Device.
Returns
Product ID.

The function USBH_Device_GetPID retrieves Product ID of the connected device.

The argument device specifies the instance of the device.

◆ USBH_Device_GetStringDescriptor()

usbStatus USBH_Device_GetStringDescriptor ( uint8_t  device,
uint8_t  index,
uint16_t  language_id,
uint8_t *  descriptor_data,
uint16_t  descriptor_length 
)

Get String Descriptor of USB Device.

Parameters
[in]deviceindex of USB Device.
[in]indexindex of string descriptor.
[in]language_idlanguage ID.
[out]descriptor_datapointer to where descriptor data will be read.
[in]descriptor_lengthmaximum descriptor length.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_Device_GetStringDescriptor is used for retrieving string descriptor form the device and is implemented with standard device request GET_DESCRIPTOR. This request returns the specified string descriptor if the descriptor exists.

The argument device specifies the instance of the device.

The argument index specifies the string descriptor index.

The argument language_id specifies the Language ID of string descriptor.

The argument descriptor_data is a pointer to where descriptor data will be read and descriptor_length specifies the number of bytes to return.

◆ USBH_Notify()

void USBH_Notify ( uint8_t  ctrl,
uint8_t  port,
uint8_t  device,
USBH_NOTIFY  notify 
)

Callback function called when some event has happened on corresponding controller and port.

Parameters
[in]ctrlindex of USB Host controller.
[in]portindex of Root HUB port.
[in]deviceindex of USB Device :
  • value <= 127: index of of USB Device for device notifications
  • value 255: no device information for port notifications
[in]notifynotification :
  • USBH_NOTIFY_CONNECT = Port connection happened
  • USBH_NOTIFY_DISCONNECT = Port disconnection happened
  • USBH_NOTIFY_OVERCURRENT = Port overcurrent happened
  • USBH_NOTIFY_REMOTE_WAKEUP = Port remote wakeup signaling happened
  • USBH_NOTIFY_READY = Device was successfully enumerated, initialized and is ready for communication
  • USBH_NOTIFY_UNKNOWN_DEVICE = Device was successfully enumerated but there is no driver for it
  • USBH_NOTIFY_INSUFFICIENT_POWER = Device requires more power consumption than available
  • USBH_NOTIFY_CONFIGURATION_FAILED = Device was not successfully configured (not enough resources)
  • USBH_NOTIFY_INITIALIZATION_FAILED = Device was not successfully initialized

The function USBH_Notify is called from the USB Host Core module on any of the available notification events. For example, when a device is connected to a USB port, this function will get called with the notification value USBH_NOTIFY_CONNECT.

The argument ctrl specifies the USB Host controller number.

The argument port specifies the USB Host root HUB port number.

The argument device specifies the instance of the device.

The argument notify specifies the type of event that has occurred.

Code Example

#include <Board_LED.h>
#include <rl_usb.h>
void USBH_Notify (uint8_t ctrl, uint8_t port, uint8_t device, USBH_NOTIFY notify) {
switch (notify) {
// A new device was connected on port
LED_On(0);
break;
// A device was dis-connected from a port
LED_Off(0);
break;
// An overcurrent has happened on a port
break;
// Resume signaling has started on a port
break;
// Device was enumerated, initialized and is ready for communication
break;
// A new device was connected but USB Host does not have a driver for it
break;
// A new device was connected but we can not supply it with enough power
break;
// A new device was connected but there aren't enough of resources to use it
break;
// A new device was connected but initialization of it has failed
break;
}
}
int main (void) {
..
LED_Initialize();
USBH_Initialize(0); // USB Host 0 Initialize
..
USBH_Uninitialize(0); // USB Host 0 De-Initialize
..
}