USB Component  Version 6.12.4
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 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

bool USBD_Configured ( uint8_t  device)

Retrieve USB Device configuration status.

Parameters
[in]deviceindex 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.

usbStatus USBD_Connect ( uint8_t  device)

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

Parameters
[in]deviceindex 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 "cmsis_os.h"
#include "rl_usb.h"
int main (void) {
...
USBD_Initialize (0); // USB Device 0 Initialization
USBD_Connect (0); // USB Device 0 Connect
while (1) { // Loop forever
...
}
}
void USBD_Devicen_ConfigurationChanged ( uint8_t  val)

Callback function called when Device configuration has changed.

Parameters
[in]valcurrent 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.

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.

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.

usbdRequestStatus USBD_Devicen_Endpoint0_InDataSent ( uint32_t  len)

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

Parameters
[in]lennumber 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.

usbdRequestStatus USBD_Devicen_Endpoint0_OutDataReceived ( uint32_t  len)

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

Parameters
[in]lennumber 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.

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_packetpointer 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;
}
}
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_packetpointer to received setup packet.
[in,out]bufpointer to data buffer used for data stage requested by setup packet.
[in,out]lenpointer 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;
}
}
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.

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

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.

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.

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
..
}
void USBD_Devicen_VbusChanged ( bool  level)

Callback function called when VBUS level changes.

Parameters
[in]levelcurrent 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.

usbStatus USBD_Disconnect ( uint8_t  device)

Disconnect USB Device from USB Bus.

Parameters
[in]deviceindex 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_STATE USBD_GetState ( uint8_t  device)

Retrieve USB Device state.

Parameters
[in]deviceindex 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.

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
usbStatus USBD_Initialize ( uint8_t  device)

Initialize USB Device stack and controller.

Parameters
[in]deviceindex 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 "cmsis_os.h"
#include "rl_usb.h"
int main (void) {
...
USBD_Initialize (0); // USB Device 0 Initialization
USBD_Connect (0); // USB Device 0 Connect
while (1) { // Loop forever
...
}
}
usbStatus USBD_SetSerialNumber ( uint8_t  device,
const char *  string 
)

Set USB Device serial number string.

Parameters
[in]deviceindex of USB Device.
[in]stringserial 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 "cmsis_os.h"
#include "rl_usb.h"
int main (void) {
...
USBD_Initialize (0); // USB Device 0 Initialization
USBD_SetSerialNumber (0, "1234"); // USB Device 0 new Serial Number
USBD_Connect (0); // USB Device 0 Connect
while (1) { // Loop forever
...
}
}
usbStatus USBD_Uninitialize ( uint8_t  device)

De-initialize USB Device stack and controller.

Parameters
[in]deviceindex 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.