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] ctrl index 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] ctrl index 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]	ctrl	index of USB Host controller.
[in]	port	root 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]	ctrl	index of USB Host controller.
[in]	port	root 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] device index 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] device index 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] device index 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] device index 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] device index 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] device index 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] device index 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]	device	index of USB Device.
[in]	index	index of string descriptor.
[in]	language_id	language ID.
[out]	descriptor_data	pointer to where descriptor data will be read.
[in]	descriptor_length	maximum 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]	ctrl	index of USB Host controller.
[in]	port	index of Root HUB port.
[in]	device	index of USB Device : value <= 127: index of of USB Device for device notifications value 255: no device information for port notifications
[in]	notify	notification : 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) {
    case USBH_NOTIFY_CONNECT:
      // A new device was connected on port
      LED_On(0);
      break;
    case USBH_NOTIFY_DISCONNECT:
      // A device was dis-connected from a port
      LED_Off(0);
      break;
    case USBH_NOTIFY_OVERCURRENT:
      // An overcurrent has happened on a port
      break;
    case USBH_NOTIFY_REMOTE_WAKEUP:
      // Resume signaling has started on a port
      break;
    case USBH_NOTIFY_READY:
      // Device was enumerated, initialized and is ready for communication
      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;
  }
}
 
int main (void)  {
  ..
  LED_Initialize();
  USBH_Initialize(0);               // USB Host 0 Initialize
  ..
  USBH_Uninitialize(0);             // USB Host 0 De-Initialize
  ..
}

Functions

Description

Function Documentation

◆ USBH_GetVersion()

◆ USBH_Initialize()

◆ USBH_Uninitialize()

◆ USBH_Port_Suspend()

◆ USBH_Port_Resume()

◆ USBH_Device_GetController()

◆ USBH_Device_GetPort()

◆ USBH_Device_GetStatus()

◆ USBH_Device_GetSpeed()

◆ USBH_Device_GetAddress()

◆ USBH_Device_GetVID()

◆ USBH_Device_GetPID()

◆ USBH_Device_GetStringDescriptor()

◆ USBH_Notify()