USB Component  Version 6.8
MDK Middleware for USB Device and Host Communication
 All Data Structures Functions Variables Enumerations Enumerator Groups Pages
User API

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

Functions

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

Description

User API reference of the USB Host Core.

Function Documentation

int32_t USBH_Device_GetAddress ( uint8_t  device)

Get communication address of USB Device.

Parameters
[in]deviceindex of USB Device.
Returns
value <= 127 enumerated address.
value == 0xFF invalid address.

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

The argument device specifies the instance of the device.

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
value <= 3 index of USB Host controller.
value == 0xFF 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.

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.

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
value == 0 index of USB Host Root HUB port.
value == 0xFF 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.

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.

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.

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.

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
..
}
void USBH_Port_Notify ( uint8_t  ctrl,
uint8_t  port,
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]notifynotification:
  • USBH_NOTIFY_CONNECT = Device was connected
  • USBH_NOTIFY_DISCONNECT = Device was disconnected
  • USBH_NOTIFY_READY = Device was successfully enumerated and initialized and is ready for communication
  • USBH_NOTIFY_OVERCURRENT = Overcurrent happened
  • USBH_NOTIFY_REMOTE_WAKEUP = Device executed remote wakeup
  • 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_Port_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 notify specifies the type of event that has occurred.

Code Example

#include <Board_LED.h>
#include <rl_usb.h>
void USBH_Port_Notify (uint8_t ctrl, uint8_t port, USBH_NOTIFY notify) {
switch (notify) {
case USBH_NOTIFY_CONNECT:
// A new device was connected
LED_On(0);
break;
case USBH_NOTIFY_DISCONNECT:
// A device was dis-connected
LED_Off(0);
break;
case USBH_NOTIFY_READY:
// Device was enumerated and initialized and is ready for communication
break;
case USBH_NOTIFY_OVERCURRENT:
// An overcurrent has happened on this port
break;
case USBH_NOTIFY_REMOTE_WAKEUP:
// Device connected to this port has started a resume signaling
break;
case USBH_NOTIFY_UNKNOWN_DEVICE:
// A new device was connected but USB Host does not have a driver for it
break;
case USBH_NOTIFY_INSUFFICIENT_POWER:
// A new device was connected but we can not supply it with enough power
break;
case USBH_NOTIFY_CONFIGURATION_FAILED:
// A new device was connected but there aren't enough of resources to use it
break;
case USBH_NOTIFY_INITIALIZATION_FAILED:
// A new device was connected but initialization of it has failed
break;
default:
break;
}
}
int main (void) {
..
LED_Initialize();
USBH_Initialize(0); // USB Host 0 Initialize
..
USBH_Uninitialize(0); // USB Host 0 De-Initialize
..
}
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.

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.

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
..
}