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

Functions
uint32_t	USBD_GetVersion (void)
	Get version of USB Device stack. More...

usbStatus	USBD_Initialize (uint8_t device)
	Initialize USB Device stack and controller. More...

usbStatus	USBD_Uninitialize (uint8_t device)
	De-initialize USB Device stack and controller. More...

usbStatus	USBD_Connect (uint8_t device)
	Activate pull-up on D+ or D- line to signal USB Device connection on USB Bus. More...

usbStatus	USBD_Disconnect (uint8_t device)
	Disconnect USB Device from USB Bus. More...

bool	USBD_Configured (uint8_t device)
	Retrieve USB Device configuration status. More...

USBD_STATE	USBD_GetState (uint8_t device)
	Retrieve USB Device state. More...

usbStatus	USBD_SetSerialNumber (uint8_t device, const char *string)
	Set USB Device serial number string. More...

void	USBD_Devicen_Initialize (void)
	Callback function called during USBD_Initialize to initialize the USB Device. More...

void	USBD_Devicen_Uninitialize (void)
	Callback function called during USBD_Uninitialize to de-initialize the USB Device. More...

void	USBD_Devicen_VbusChanged (bool level)
	Callback function called when VBUS level changes. More...

void	USBD_Devicen_Reset (void)
	Callback function called upon USB Bus Reset signaling. More...

void	USBD_Devicen_HighSpeedActivated (void)
	Callback function called when USB Bus speed has changed to high-speed. More...

void	USBD_Devicen_Suspended (void)
	Callback function called when USB Bus goes into suspend mode (no bus activity for 3 ms) More...

void	USBD_Devicen_Resumed (void)
	Callback function called when USB Bus activity has resumed. More...

void	USBD_Devicen_ConfigurationChanged (uint8_t val)
	Callback function called when Device configuration has changed. More...

void	USBD_Devicen_EnableRemoteWakeup (void)
	Callback function called when Set Feature for Remote Wakeup was requested over Control Endpoint 0. More...

void	USBD_Devicen_DisableRemoteWakeup (void)
	Callback function called when Clear Feature for Remote Wakeup was requested over Control Endpoint 0. More...

usbdRequestStatus	USBD_Devicen_Endpoint0_SetupPacketReceived (const USB_SETUP_PACKET setup_packet, uint8_t buf, uint32_t len)
	Callback function called when Device received SETUP PACKET on Control Endpoint 0. More...

void	USBD_Devicen_Endpoint0_SetupPacketProcessed (const USB_SETUP_PACKET *setup_packet)
	Callback function called when SETUP PACKET was processed by USB library. More...

usbdRequestStatus	USBD_Devicen_Endpoint0_OutDataReceived (uint32_t len)
	Callback function called when Device received OUT DATA on Control Endpoint 0. More...

usbdRequestStatus	USBD_Devicen_Endpoint0_InDataSent (uint32_t len)
	Callback function called when Device sent IN DATA on Control Endpoint 0. More...

Description

User API reference of the USB Device Core.

For a general function overview refer to the section Core.

Function Documentation

◆ USBD_GetVersion()

uint32_t USBD_GetVersion ( void )

Get version of USB Device stack.

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

The function USBD_GetVersion retrieves version of the USB Device 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

◆ USBD_Initialize()

usbStatus USBD_Initialize ( uint8_t device )

Initialize USB Device stack and controller.

Parameters

[in] device index of USB Device.

Returns: status code that indicates the execution status of the function as defined with usbStatus.

The function USBD_Initialize initializes the USB Device Controller Core and Hardware Driver (such as the USB clock and pins). It starts all the tasks and sets up the main USB interrupt service routine. In any application, the USBD_Initialize function must be called before invoking any other USB Device function. The function does not initialize any non-USB hardware features.

The argument device specifies the instance of the USB Device.

Code Example

#include "rl_usb.h"
  
__NO_RETURN void app_main (void *arg) {
  ...
  USBD_Initialize (0);       // USB Device 0 Initialization
  USBD_Connect    (0);       // USB Device 0 Connect       
  ...
  for (;;) {
    ...
  }
}

◆ USBD_Uninitialize()

usbStatus USBD_Uninitialize ( uint8_t device )

De-initialize USB Device stack and controller.

Parameters

[in] device index of USB Device.

Returns: status code that indicates the execution status of the function as defined with usbStatus.

De-initialize the USB Device Controller Core and Hardware Driver. Invoke this function when USB is not to be used any more.

The argument device specifies the instance of the USB Device.

◆ USBD_Connect()

usbStatus USBD_Connect ( uint8_t device )

Activate pull-up on D+ or D- line to signal USB Device connection on USB Bus.

Parameters

[in] device index of USB Device.

Returns: status code that indicates the execution status of the function as defined with usbStatus.

The function USBD_Connect connects the USB Device to the USB Bus. This typically initiates the enumeration on the USB Host side for the USB Device.

The argument device specifies the instance of the USB Device.

Code Example

#include "rl_usb.h"
  
__NO_RETURN void app_main (void *arg) {
  ...
  USBD_Initialize (0);       // USB Device 0 Initialization
  USBD_Connect    (0);       // USB Device 0 Connect       
  ...
  for (;;) {
    ...
  }
}

◆ USBD_Disconnect()

usbStatus USBD_Disconnect ( uint8_t device )

Disconnect USB Device from USB Bus.

Parameters

[in] device index of USB Device.

Returns: status code that indicates the execution status of the function as defined with usbStatus.

The function USBD_Disconnect disconnects the USB Device from the USB Bus. After executing this function the USB Device can no longer be accessed from the USB Host.

The argument device specifies the instance of the USB Device.

◆ USBD_Configured()

bool USBD_Configured ( uint8_t device )

Retrieve USB Device configuration status.

Parameters

[in] device index of USB Device.

Returns

device is in configured state and ready to communicate or is not configured and not ready to communicate :

value true : device is in configured state and ready to communicate
value false : device is not configured and not ready to communicate

The function USBD_Configured retrieves the configuration status of the USB Device. It determines whether the USB Device has been configured and is ready to communicate.

The argument device specifies the instance of the USB Device.

◆ USBD_GetState()

USBD_STATE USBD_GetState ( uint8_t device )

Retrieve USB Device state.

Parameters

[in] device index of USB Device.

Returns: structure containing device state information.

The function USBD_GetState retrieves the bus state of the USB Device. It determines whether the USB Device has valid VBUS, on which speed it was enumerated and if it is active on the bus.

The argument device specifies the instance of the USB Device.

◆ USBD_SetSerialNumber()

usbStatus USBD_SetSerialNumber	(	uint8_t	device,
		const char *	string
	)

Set USB Device serial number string.

Parameters

[in]	device	index of USB Device.
[in]	string	serial number string.

Returns: status code that indicates the execution status of the function as defined with usbStatus.

The function USBD_SetSerialNumber is used to set Serial Number String of the USB Device during run-time. This function should be called before USBD_Connect function.

The argument device specifies the instance of the USB Device.

The argument string is a pointer to the new string to be used for Serial Number.

Code Example

#include "rl_usb.h"
  
__NO_RETURN void app_main (void *arg) {
  ...
  USBD_Initialize      (0);          // USB Device 0 Initialization
  USBD_SetSerialNumber (0, "1234");  // USB Device 0 new Serial Number
  USBD_Connect         (0);          // USB Device 0 Connect       
  ...
  for (;;) {
    ...
  }
}

◆ USBD_Devicen_Initialize()

void USBD_Devicen_Initialize ( void )

Callback function called during USBD_Initialize to initialize the USB Device.

Returns: none.

If available, the function USBD_Devicen_Initialize is called automatically upon initialization of the USB Device and needs no invocation in the user code. Modify this function for custom USB Device handling. This function can be modified in the user code template file USBD_User_Device_n.c.

Code Example

#include "rl_usb.h"
 
int main (void)  {
  ..
  USBD_Initialize (0);   // USB Device 0 Initialization calls USBD_Devicen_Initialize() automatically
  USBD_Connect (0);      // USB Device 0 Connect
  ..
}

◆ USBD_Devicen_Uninitialize()

void USBD_Devicen_Uninitialize ( void )

Callback function called during USBD_Uninitialize to de-initialize the USB Device.

Returns: none.

If available, the function USBD_Devicen_Uninitialize is called automatically upon un-initialization of the USB Device and needs no invocation in the user code. Modify this function for custom USB Device handling. This function can be found in the user code template file USBD_User_Device_n.c.

Code Example

#include "rl_usb.h"
 
int main (void)  {
  ..
  USBD_Initialize (0);   // USB Device 0 Initialization 
  ..
  USBD_Uninitialize (0); // USB Device 0 Un-Initialization calls USBD_Devicen_Uninitialize() automatically
  ..
}

◆ USBD_Devicen_VbusChanged()

void USBD_Devicen_VbusChanged ( bool level )

Callback function called when VBUS level changes.

Parameters

[in]

level

current VBUS level :

value true : VBUS level is high
value false : VBUS level is low

Returns: none.

The callback function USBD_Devicen_VbusChanged is called when the state of the VBUS pin of the USB Device Instance n changes level.

This function can be modified in the user code template file USBD_User_Device_n.c.

◆ USBD_Devicen_Reset()

void USBD_Devicen_Reset ( void )

Callback function called upon USB Bus Reset signaling.

Returns: none.

The callback function USBD_Devicen_Reset is called when reset signaling was detected by the USB Device Instance n.

This function can be modified in the user code template file USBD_User_Device_n.c.

◆ USBD_Devicen_HighSpeedActivated()

void USBD_Devicen_HighSpeedActivated ( void )

Callback function called when USB Bus speed has changed to high-speed.

Returns: none.

The callback function USBD_Devicen_HighSpeedActivated is called when the bus speed of the USB Device Instance n changes to high speed.

This function can be modified in the user code template file USBD_User_Device_n.c.

◆ USBD_Devicen_Suspended()

void USBD_Devicen_Suspended ( void )

Callback function called when USB Bus goes into suspend mode (no bus activity for 3 ms)

Returns: none.

The callback function USBD_Devicen_Suspended is called when bus of the USB Device Instance n was suspended (no SOFs for 3 ms).

This function can be modified in the user code template file USBD_User_Device_n.c.

◆ USBD_Devicen_Resumed()

void USBD_Devicen_Resumed ( void )

Callback function called when USB Bus activity has resumed.

Returns: none.

The callback function USBD_Devicen_Resumed is called when bus activity has been resumed by the USB Device Instance n.

This function can be modified in the user code template file USBD_User_Device_n.c.

◆ USBD_Devicen_ConfigurationChanged()

void USBD_Devicen_ConfigurationChanged ( uint8_t val )

Callback function called when Device configuration has changed.

Parameters

[in]

val

current configuration value :

value 0 : not configured
value > 0 : active configuration

Returns: none.

The callback function USBD_Devicen_ConfigurationChanged is called when the USB Device Instance n was requested by the USB Host to change the configuration.

The argument val specifies the activated configuration.

This function can be modified in the user code template file USBD_User_Device_n.c.

◆ USBD_Devicen_EnableRemoteWakeup()

void USBD_Devicen_EnableRemoteWakeup ( void )

Callback function called when Set Feature for Remote Wakeup was requested over Control Endpoint 0.

Returns: none.

The callback function USBD_Devicen_EnableRemoteWakeup is called when the USB Device Instance n receives Set Feature request on the Control Endpoint 0 to enable remote wakeup feature on the device.

This function can be modified in the user code template file USBD_User_Device_n.c.

◆ USBD_Devicen_DisableRemoteWakeup()

void USBD_Devicen_DisableRemoteWakeup ( void )

Callback function called when Clear Feature for Remote Wakeup was requested over Control Endpoint 0.

Returns: none.

The callback function USBD_Devicen_DisableRemoteWakeup is called when the USB Device Instance n receives Clear Feature request on the Control Endpoint 0 to disable remote wakeup feature on the device.

This function can be modified in the user code template file USBD_User_Device_n.c.

◆ USBD_Devicen_Endpoint0_SetupPacketReceived()

usbdRequestStatus USBD_Devicen_Endpoint0_SetupPacketReceived	(	const USB_SETUP_PACKET *	setup_packet,
		uint8_t **	buf,
		uint32_t *	len
	)

Callback function called when Device received SETUP PACKET on Control Endpoint 0.

Parameters

[in]	setup_packet	pointer to received setup packet.
[in,out]	buf	pointer to data buffer used for data stage requested by setup packet.
[in,out]	len	pointer to number of data bytes in data stage requested by setup packet.

Returns

usbdRequestStatus enumerator value indicating the function execution status :

value usbdRequestNotProcessed : request was not processed; processing will be done by USB library
value usbdRequestOK : request was processed successfully (send Zero-Length Packet if no data stage)
value usbdRequestStall : request was processed but is not supported (stall Endpoint 0)

The callback function USBD_Devicen_Endpoint0_SetupPacketReceived is called when the USB Device Instance n received a SETUP PACKET on Control Endpoint 0.

The argument setup_packet is a pointer to the received setup packet.

The argument buf is a pointer to the data buffer that is used for data stage requested by setup packet.

The argument len is a pointer to the number of data bytes in the data stage requested by setup packet.

This function can be modified in the user code template file USBD_User_Device_n.c.

Code Example

usbdRequestStatus USBD_Device0_Endpoint0_SetupPacketReceived (const USB_SETUP_PACKET *setup_packet, uint8_t **buf, uint32_t *len) {
 
  switch (setup_packet->bmRequestType.Type) {
    case USB_REQUEST_STANDARD:
      if ((setup_packet->bmRequestType.Dir       == USB_REQUEST_DEVICE_TO_HOST) && 
          (setup_packet->bmRequestType.Recipient == USB_REQUEST_TO_DEVICE     ) && 
          (setup_packet->bRequest                == USB_REQUEST_GET_DESCRIPTOR) && 
          (setup_packet->wValueH                 == USB_DEVICE_DESCRIPTOR_TYPE) && 
          (setup_packet->wIndex                  == 0                         )) {
        *buf = (uint8_t *)device%Instance%_dev_desc;
        *len = sizeof    (device%Instance%_dev_desc);
        return usbdRequestOK;
      }
      break;
    case USB_REQUEST_CLASS:
      break;
    case USB_REQUEST_VENDOR:
      break;
    case USB_REQUEST_RESERVED:
      break;
  }
 
  return usbdRequestNotProcessed;
}

◆ USBD_Devicen_Endpoint0_SetupPacketProcessed()

void USBD_Devicen_Endpoint0_SetupPacketProcessed ( const USB_SETUP_PACKET * setup_packet )

Callback function called when SETUP PACKET was processed by USB library.

Parameters

[in] setup_packet pointer to processed setup packet.

Returns: none.

The callback function USBD_Devicen_Endpoint0_SetupPacketProcessed is called when a SETUP PACKET was processed by the USB library.

The argument setup_packet is a pointer to the processed setup packet.

This function can be modified in the user code template file USBD_User_Device_n.c.

Code Example

void USBD_Device0_Endpoint0_SetupPacketProcessed (const USB_SETUP_PACKET *setup_packet) {
 
  switch (setup_packet->bmRequestType.Type) {
    case USB_REQUEST_STANDARD:
      break;
    case USB_REQUEST_CLASS:
      break;
    case USB_REQUEST_VENDOR:
      break;
    case USB_REQUEST_RESERVED:
      break;
  }
}

◆ USBD_Devicen_Endpoint0_OutDataReceived()

usbdRequestStatus USBD_Devicen_Endpoint0_OutDataReceived ( uint32_t len )

Callback function called when Device received OUT DATA on Control Endpoint 0.

Parameters

[in] len number of received data bytes.

Returns

usbdRequestStatus enumerator value indicating the function execution status :

value usbdRequestNotProcessed : request was not processed; processing will be done by USB library
value usbdRequestOK : request was processed successfully (send Zero-Length Packet)
value usbdRequestStall : request was processed but is not supported (stall Endpoint 0)
value usbdRequestNAK : request was processed but the device is busy (return NAK)

The callback function USBD_Devicen_Endpoint0_OutDataReceived is called when the USB Device received an OUT DATA on Control Endpoint 0.

The argument len specifies the number of received data bytes.

This function can be modified in the user code template file USBD_User_Device_n.c.

◆ USBD_Devicen_Endpoint0_InDataSent()

usbdRequestStatus USBD_Devicen_Endpoint0_InDataSent ( uint32_t len )

Callback function called when Device sent IN DATA on Control Endpoint 0.

Parameters

[in] len number of sent data bytes.

Returns

usbdRequestStatus enumerator value indicating the function execution status :

value usbdRequestNotProcessed : request was not processed; processing will be done by USB library
value usbdRequestOK : request was processed successfully (return ACK)
value usbdRequestStall : request was processed but is not supported (stall Endpoint 0)
value usbdRequestNAK : request was processed but the device is busy (return NAK)

The callback function USBD_Devicen_Endpoint0_InDataSent is called when the USB Device sent IN DATA on Control Endpoint 0.

The argument len specifies the number of sent data bytes.

This function can be modified in the user code template file USBD_User_Device_n.c.

Functions

Description

Function Documentation

◆ USBD_GetVersion()

◆ USBD_Initialize()

◆ USBD_Uninitialize()

◆ USBD_Connect()

◆ USBD_Disconnect()

◆ USBD_Configured()

◆ USBD_GetState()

◆ USBD_SetSerialNumber()

◆ USBD_Devicen_Initialize()

◆ USBD_Devicen_Uninitialize()

◆ USBD_Devicen_VbusChanged()

◆ USBD_Devicen_Reset()

◆ USBD_Devicen_HighSpeedActivated()

◆ USBD_Devicen_Suspended()

◆ USBD_Devicen_Resumed()

◆ USBD_Devicen_ConfigurationChanged()

◆ USBD_Devicen_EnableRemoteWakeup()

◆ USBD_Devicen_DisableRemoteWakeup()

◆ USBD_Devicen_Endpoint0_SetupPacketReceived()

◆ USBD_Devicen_Endpoint0_SetupPacketProcessed()

◆ USBD_Devicen_Endpoint0_OutDataReceived()

◆ USBD_Devicen_Endpoint0_InDataSent()