USB Component  Version 6.17.0
MDK Middleware for USB Device and Host Communication
Functions
User API
USB Host » Device Class » Custom Class

User API reference of the Custom Class. More...

Functions

uint8_t USBH_CustomClass_GetDevice (uint8_t instance)
 Get Device instance of Custom Class Device. More...
 
usbStatus USBH_CustomClass_GetStatus (uint8_t instance)
 Get status of Custom Class Device. More...
 
uint8_t USBH_CustomClass_Configure (uint8_t device, const USB_DEVICE_DESCRIPTOR *ptr_dev_desc, const USB_CONFIGURATION_DESCRIPTOR *ptr_cfg_desc)
 Callback function called when custom class device is connected and needs to configure resources used by custom class device instance. More...
 
usbStatus USBH_CustomClass_Unconfigure (uint8_t instance)
 Callback function called when custom class device is disconnected and needs to de-configure resources used by custom class device instance. More...
 
usbStatus USBH_CustomClass_Initialize (uint8_t instance)
 Callback function called when custom class device is connected and needs to initialize custom class device instance. More...
 
usbStatus USBH_CustomClass_Uninitialize (uint8_t instance)
 Callback function called when custom class device is disconnected and needs to de-initialize custom class device instance. More...
 
USBH_PIPE_HANDLE USBH_PipeCreate (uint8_t device, uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size, uint8_t ep_interval)
 Create Pipe. More...
 
usbStatus USBH_PipeRegisterCallback (USBH_PIPE_HANDLE pipe_hndl, USBH_PipeEvent_t cb_pipe_event)
 Register a callback for Pipe events. More...
 
usbStatus USBH_PipeUpdate (USBH_PIPE_HANDLE pipe_hndl)
 Update Pipe. More...
 
usbStatus USBH_PipeDelete (USBH_PIPE_HANDLE pipe_hndl)
 Delete Pipe. More...
 
usbStatus USBH_PipeReset (USBH_PIPE_HANDLE pipe_hndl)
 Reset Pipe (reset data toggle) More...
 
usbStatus USBH_PipeReceive (USBH_PIPE_HANDLE pipe_hndl, uint8_t *buf, uint32_t len)
 Receive data on Pipe. More...
 
uint32_t USBH_PipeReceiveGetResult (USBH_PIPE_HANDLE pipe_hndl)
 Get result of receive data operation on Pipe. More...
 
usbStatus USBH_PipeSend (USBH_PIPE_HANDLE pipe_hndl, const uint8_t *buf, uint32_t len)
 Send data on Pipe. More...
 
uint32_t USBH_PipeSendGetResult (USBH_PIPE_HANDLE pipe_hndl)
 Get result of send data operation on Pipe. More...
 
usbStatus USBH_PipeAbort (USBH_PIPE_HANDLE pipe_hndl)
 Abort send/receive operation on Pipe. More...
 
usbStatus USBH_ControlTransfer (uint8_t device, const USB_SETUP_PACKET *setup_packet, uint8_t *data, uint32_t len)
 Do a Control Transfer on Default Pipe. More...
 
usbStatus USBH_DeviceRequest_GetStatus (uint8_t device, uint8_t recipient, uint8_t index, uint8_t *ptr_stat_dat)
 Standard Device Request on Default Pipe - GET_STATUS. More...
 
usbStatus USBH_DeviceRequest_ClearFeature (uint8_t device, uint8_t recipient, uint8_t index, uint8_t feature_selector)
 Standard Device Request on Default Pipe - CLEAR_FEATURE. More...
 
usbStatus USBH_DeviceRequest_SetFeature (uint8_t device, uint8_t recipient, uint8_t index, uint8_t feature_selector)
 Standard Device Request on Default Pipe - SET_FEATURE. More...
 
usbStatus USBH_DeviceRequest_SetAddress (uint8_t device, uint8_t device_address)
 Standard Device Request on Default Pipe - SET_ADDRESS. More...
 
usbStatus USBH_DeviceRequest_GetDescriptor (uint8_t device, uint8_t recipient, uint8_t descriptor_type, uint8_t descriptor_index, uint16_t language_id, uint8_t *descriptor_data, uint16_t descriptor_length)
 Standard Device Request on Default Pipe - GET_DESCRIPTOR. More...
 
usbStatus USBH_DeviceRequest_SetDescriptor (uint8_t device, uint8_t recipient, uint8_t descriptor_type, uint8_t descriptor_index, uint16_t language_id, const uint8_t *descriptor_data, uint16_t descriptor_length)
 Standard Device Request on Default Pipe - SET_DESCRIPTOR. More...
 
usbStatus USBH_DeviceRequest_GetConfiguration (uint8_t device, uint8_t *ptr_configuration)
 Standard Device Request on Default Pipe - GET_CONFIGURATION. More...
 
usbStatus USBH_DeviceRequest_SetConfiguration (uint8_t device, uint8_t configuration)
 Standard Device Request on Default Pipe - SET_CONFIGURATION. More...
 
usbStatus USBH_DeviceRequest_GetInterface (uint8_t device, uint8_t index, uint8_t *ptr_alternate)
 Standard Device Request on Default Pipe - GET_INTERFACE. More...
 
usbStatus USBH_DeviceRequest_SetInterface (uint8_t device, uint8_t index, uint8_t alternate)
 Standard Device Request on Default Pipe - SET_INTERFACE. More...
 
usbStatus USBH_DeviceRequest_SynchFrame (uint8_t device, uint8_t index, uint8_t *ptr_frame_number)
 Standard Device Request on Default Pipe - SYNCH_FRAME. More...
 

Description

User API reference of the Custom Class.

Function Documentation

◆ USBH_CustomClass_GetDevice()

uint8_t USBH_CustomClass_GetDevice ( uint8_t  instance)

Get Device instance of Custom Class Device.

Parameters
[in]instanceinstance of Custom Class Device.
Returns
instance of Device or non-existing Device instance :
  • value <= 127 : instance of Device
  • value 255 : non-existing Device instance

The function USBH_CustomClass_GetDevice is used to retrieve device instance that is used to handle custom class device instance.

The argument instance specifies the custom class device instance.

◆ USBH_CustomClass_GetStatus()

usbStatus USBH_CustomClass_GetStatus ( uint8_t  instance)

Get status of Custom Class Device.

Parameters
[in]instanceinstance of Custom Class Device.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_CustomClass_GetStatus checks if a custom class device is connected and initialized.

The argument instance specifies the custom class device instance.

◆ USBH_CustomClass_Configure()

uint8_t USBH_CustomClass_Configure ( uint8_t  device,
const USB_DEVICE_DESCRIPTOR *  ptr_dev_desc,
const USB_CONFIGURATION_DESCRIPTOR *  ptr_cfg_desc 
)

Callback function called when custom class device is connected and needs to configure resources used by custom class device instance.

Parameters
[in]deviceindex of USB Device.
[in]ptr_dev_descpointer to device descriptor.
[in]ptr_cfg_descpointer to configuration descriptor.
Returns
index of configured custom class device instance or configuration failed :
  • value <= 127 : index of configured custom class device instance
  • value 255 : configuration failed

The function USBH_CustomClass_Configure should create all necessary pipes for the custom class. It needs to be adapted to the specific needs of the Custom Class that is to be supported. For more information on the USB_DEVICE_DESCRIPTOR, please refer to Device Descriptor. For more information on the USB_CONFIGURATION_DESCRIPTOR, please refer to Configuration Descriptor.

The argument device specifies the instance of the connected device.

The argument ptr_dev_desc specifies the pointer to the device descriptor (Device Descriptor) of the Custom Class.

The argument ptr_cfg_desc specifies the pointer to the configuration descriptor (Configuration Descriptor) of the Custom Class.

Code Example

uint8_t USBH_CustomClass_Configure (uint8_t device, const USB_DEVICE_DESCRIPTOR *ptr_dev_desc, const USB_CONFIGURATION_DESCRIPTOR *ptr_cfg_desc) {
USB_INTERFACE_DESCRIPTOR *ptr_if_desc;
USB_ENDPOINT_DESCRIPTOR *ptr_ep_desc;
USBH_PIPE_HANDLE pipe_hndl;
uint8_t num, i;
USBH_CC_Device = device; // Store device
for (i = 0U; i < 8U; i++) { // Clear all pipe handles
USBH_CC_PipeHandle[i] = 0U;
}
ptr_if_desc = (USB_INTERFACE_DESCRIPTOR *)((uint32_t)ptr_cfg_desc + ptr_cfg_desc->bLength);
num = ptr_if_desc->bNumEndpoints; // Number of endpoints
// Supported device: - Prolific PL2303 (VID = 0x067B, PID = 0x2303)
if ((ptr_dev_desc->idVendor != 0x067BU) || (ptr_dev_desc->idProduct != 0x2303U)) {
return 255U;
}
switch (ptr_if_desc->bInterfaceClass) {
case CUSTOM_CLASS_IF_CLASS: // Interface class
switch (ptr_if_desc->bInterfaceSubClass) {
case CUSTOM_CLASS_IF_SUBCLASS: // Interface subclass
switch (ptr_if_desc->bInterfaceProtocol) {
case CUSTOM_CLASS_IF_PROTOCOL: // Interface protocol
// Create Pipes
ptr_ep_desc = (USB_ENDPOINT_DESCRIPTOR *)((uint32_t)ptr_if_desc + ptr_if_desc->bLength);
i = 0U;
while (num-- != 0U) {
pipe_hndl = USBH_PipeCreate (device, ptr_ep_desc->bEndpointAddress, ptr_ep_desc->bmAttributes & USB_ENDPOINT_TYPE_MASK, ptr_ep_desc->wMaxPacketSize & 0x7FFU, ptr_ep_desc->bInterval);
if (pipe_hndl == 0U) {
// If creation of pipe has failed delete previously created pipes
for (i = 0U; i < 8U; i++) {
if (USBH_CC_PipeHandle[i] != 0U) {
USBH_PipeDelete (USBH_CC_PipeHandle[i]);
USBH_CC_PipeHandle[i] = 0U;
}
}
return 255U;
}
USBH_CC_PipeHandle[i++] = pipe_hndl;
ptr_ep_desc++;
}
return 0U; // Device connected and configured
// Only single instance supported
// so it's instance index is 0
}
break;
}
break;
}
return 255U; // Device not handled
}

◆ USBH_CustomClass_Unconfigure()

usbStatus USBH_CustomClass_Unconfigure ( uint8_t  instance)

Callback function called when custom class device is disconnected and needs to de-configure resources used by custom class device instance.

Parameters
[in]instanceindex of custom class device instance.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_CustomClass_Unconfigure should release all resources that were used by the Custom Class device after it has been de-initialized using USBH_CustomClass_Uninitialize. All pipes relating to the Custom Class should be removed. It needs to be adapted to the specific needs of the Custom Class that is to be supported.

The argument instance specifies device instance of the Custom Class USB Device.

Code Example

uint8_t i;
USBH_CC_Device = 0U;
for (i = 0U; i < 8U; i++) {
if (USBH_CC_PipeHandle[i] != 0U) {
USBH_PipeDelete (USBH_CC_PipeHandle[i]);
USBH_CC_PipeHandle[i] = 0U;
}
}
return usbOK;

◆ USBH_CustomClass_Initialize()

usbStatus USBH_CustomClass_Initialize ( uint8_t  instance)

Callback function called when custom class device is connected and needs to initialize custom class device instance.

Parameters
[in]instanceindex of custom class device instance.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_CustomClass_Initialize initializes the Custom Class device when connected to the system. It needs to be adapted to the specific needs of the Custom Class that is to be supported.

The argument instance specifies device instance of the Custom Class USB Device.

Code Example

usbStatus USBH_CustomClass_Initialize (uint8_t instance) {
USB_SETUP_PACKET setup_packet;
uint32_t br;
uint8_t buf[8];
// Custom PL2303 initialization
setup_packet.bmRequestType.Dir = USB_REQUEST_DEVICE_TO_HOST;
setup_packet.bmRequestType.Type = USB_REQUEST_VENDOR;
setup_packet.bmRequestType.Recipient= USB_REQUEST_TO_DEVICE;
setup_packet.bRequest = 1U;
setup_packet.wValue = U16_LE(0x8484U);
setup_packet.wIndex = U16_LE(0U);
setup_packet.wLength = U16_LE(1U);
if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, buf, 1U) != usbOK) { return usbClassErrorCustom; }
setup_packet.bmRequestType.Dir = USB_REQUEST_HOST_TO_DEVICE;
setup_packet.wValue = U16_LE(0x0404U);
if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, buf, 1U) != usbOK) { return usbClassErrorCustom; }
setup_packet.bmRequestType.Dir = USB_REQUEST_DEVICE_TO_HOST;
setup_packet.wValue = U16_LE(0x8484U);
if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, buf, 1U) != usbOK) { return usbClassErrorCustom; }
setup_packet.wValue = U16_LE(0x8383U);
if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, buf, 1U) != usbOK) { return usbClassErrorCustom; }
setup_packet.wValue = U16_LE(0x8484U);
if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, buf, 1U) != usbOK) { return usbClassErrorCustom; }
setup_packet.bmRequestType.Dir = USB_REQUEST_HOST_TO_DEVICE;
setup_packet.wValue = U16_LE(0x0404U);
setup_packet.wIndex = U16_LE(1U);
setup_packet.wLength = U16_LE(0U);
if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, NULL, 0U) != usbOK) { return usbClassErrorCustom; }
setup_packet.bmRequestType.Dir = USB_REQUEST_DEVICE_TO_HOST;
setup_packet.wValue = U16_LE(0x8484U);
setup_packet.wIndex = U16_LE(0U);
setup_packet.wLength = U16_LE(1U);
if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, buf, 1U) != usbOK) { return usbClassErrorCustom; }
setup_packet.wValue = U16_LE(0x8383U);
if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, buf, 1U) != usbOK) { return usbClassErrorCustom; }
setup_packet.bmRequestType.Dir = USB_REQUEST_HOST_TO_DEVICE;
setup_packet.wValue = U16_LE(0U);
setup_packet.wIndex = U16_LE(1U);
setup_packet.wLength = U16_LE(0U);
if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, NULL, 0U) != usbOK) { return usbClassErrorCustom; }
setup_packet.wValue = U16_LE(1U);
setup_packet.wIndex = U16_LE(0U);
if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, NULL, 0U) != usbOK) { return usbClassErrorCustom; }
setup_packet.wValue = U16_LE(2U);
setup_packet.wIndex = U16_LE(0x44U);
if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, NULL, 0U) != usbOK) { return usbClassErrorCustom; }
// Initial CDC SetLineCoding request: Set 9600 baud, 8 data bits, 1 stop bit, no parity
setup_packet.bmRequestType.Dir = USB_REQUEST_HOST_TO_DEVICE;
setup_packet.bmRequestType.Type = USB_REQUEST_CLASS;
setup_packet.bmRequestType.Recipient= USB_REQUEST_TO_INTERFACE;
setup_packet.bRequest = 0x20U;
setup_packet.wValue = U16_LE(0U);
setup_packet.wIndex = U16_LE(0U);
setup_packet.wLength = U16_LE(7U);
br = U32_LE(9600U); // Data terminal rate in bits per second = 9600 baud
buf[0] = (uint8_t)( br & 0xFFU);
buf[1] = (uint8_t)((br >> 8) & 0xFFU);
buf[2] = (uint8_t)((br >> 16) & 0xFFU);
buf[3] = (uint8_t)((br >> 24) & 0xFFU);
buf[4] = 0U; // Number of stop bits = 1
buf[5] = 0U; // Parity bit type = None
buf[6] = 8U; // Number of data bits = 8
if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, buf, 7U) != usbOK) { return usbClassErrorCustom; }
return usbOK;
}

◆ USBH_CustomClass_Uninitialize()

usbStatus USBH_CustomClass_Uninitialize ( uint8_t  instance)

Callback function called when custom class device is disconnected and needs to de-initialize custom class device instance.

Parameters
[in]instanceindex of custom class device instance.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_CustomClass_Uninitialize de-initializes the Custom Class device after it has been disconnected from the system. It needs to be adapted to the specific needs of the Custom Class that is to be supported.

The argument instance specifies device instance of the Custom Class USB Device.

Code Example

usbStatus USBH_CustomClass_Uninitialize (uint8_t instance) {
return usbOK;
}

◆ USBH_PipeCreate()

USBH_PIPE_HANDLE USBH_PipeCreate ( uint8_t  device,
uint8_t  ep_addr,
uint8_t  ep_type,
uint16_t  ep_max_packet_size,
uint8_t  ep_interval 
)

Create Pipe.

Parameters
[in]deviceindex of USB Device.
[in]ep_addrendpoint address :
  • ep_addr.0..3 : address
  • ep_addr.7 : direction
[in]ep_typeendpoint type.
[in]ep_max_packet_sizeendpoint maximum packet size.
[in]ep_intervalendpoint polling interval.
Returns
pipe handle or pipe creation failed :
  • value > 0 : pipe handle
  • value 0 : pipe creation failed

The function USBH_PipeCreate a Pipe for communication with specific Endpoint in a Device.

The argument device specifies the instance of the device.

The argument ep_addr is the address of the endpoint.

The argument ep_type is the type of the endpoint.

The argument ep_max_packet_size is the maximum packet size of the endpoint.

The argument ep_interval is the endpoint polling interval of the endpoint.

Code Example

uint8_t USBH_CustomClass_Configure (uint8_t device, const USB_DEVICE_DESCRIPTOR *ptr_dev_desc, const USB_CONFIGURATION_DESCRIPTOR *ptr_cfg_desc) {
USBH_PIPE_HANDLE pipe_hndl;
:
pipe_hndl = USBH_PipeCreate (device, ptr_ep_desc->bEndpointAddress, ptr_ep_desc->bmAttributes & USB_ENDPOINT_TYPE_MASK, ptr_ep_desc->wMaxPacketSize & 0x7FF, ptr_ep_desc->bInterval);
:
}

◆ USBH_PipeRegisterCallback()

usbStatus USBH_PipeRegisterCallback ( USBH_PIPE_HANDLE  pipe_hndl,
USBH_PipeEvent_t  cb_pipe_event 
)

Register a callback for Pipe events.

Parameters
[in]pipe_hndlpipe handle.
[in]cb_pipe_eventpointer to pipe event callback function :
  • value > 0 : pointer to pipe event callback function
  • value 0 : unregister pipe event callback
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_PipeRegisterCallback registers a callback function that will be called upon pipe event.

The argument pipe_hndl is a handle to pipe for registering callback.

The argument cb_pipe_event specifies the callback function.

Note
Currently supported only for isochronous pipes. Callback function is called from interrupt context so it may not call functions like USBH_PipeSend or USBH_PipeReceive directly. It is recommended to set a flag for a thread that can then call USBH_PipeSend or USBH_PipeReceive to start a new transfer.

Code Example

void IsoReceived (uint32_t event, const uint8_t *buf, uint32_t len) {
osThreadFlagsSet(thread_id_iso, 1U);
}
uint8_t USBH_CustomClass_Configure (uint8_t device, const USB_DEVICE_DESCRIPTOR *ptr_dev_desc, const USB_CONFIGURATION_DESCRIPTOR *ptr_cfg_desc) {
USBH_PIPE_HANDLE pipe_hndl;
:
pipe_hndl = USBH_PipeCreate (device, ptr_ep_desc->bEndpointAddress, ptr_ep_desc->bmAttributes & USB_ENDPOINT_TYPE_MASK, ptr_ep_desc->wMaxPacketSize & 0x7FF, ptr_ep_desc->bInterval);
USBH_PipeRegisterCallback (pipe_hndl, IsoReceived);
:
}

◆ USBH_PipeUpdate()

usbStatus USBH_PipeUpdate ( USBH_PIPE_HANDLE  pipe_hndl)

Update Pipe.

Parameters
[in]pipe_hndlpipe handle.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_PipeUpdate modifies a Pipe with changed device parameters (for example if device address has changed).

The argument pipe_hndl is a handle to pipe to be updated.

◆ USBH_PipeDelete()

usbStatus USBH_PipeDelete ( USBH_PIPE_HANDLE  pipe_hndl)

Delete Pipe.

Parameters
[in]pipe_hndlpipe handle.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_PipeDelete removes a Pipe.

The argument pipe_hndl is a handle to pipe to be updated.

Code Example

// If creation of pipe failed delete previously created pipes
for (i = 0U; i < 8U; i++) {
if (USBH_CC_PipeHandle[i] != 0U) {
USBH_PipeDelete (USBH_CC_PipeHandle[i]);
USBH_CC_PipeHandle[i] = NULL;
}
}

◆ USBH_PipeReset()

usbStatus USBH_PipeReset ( USBH_PIPE_HANDLE  pipe_hndl)

Reset Pipe (reset data toggle)

Parameters
[in]pipe_hndlpipe handle.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_PipeReset resets data toggle of a Pipe.

The argument pipe_hndl is a handle to pipe to be reset.

◆ USBH_PipeReceive()

usbStatus USBH_PipeReceive ( USBH_PIPE_HANDLE  pipe_hndl,
uint8_t *  buf,
uint32_t  len 
)

Receive data on Pipe.

Parameters
[in]pipe_hndlpipe handle.
[out]bufbuffer that receives data.
[in]lenmaximum number of bytes to receive.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_PipeReceive receives data on a Pipe. Number of bytes received can be retrieved by USBH_PipeReceiveGetResult function.

The argument pipe_hndl is a handle to pipe used for data reception.

The argument buf buffer that receives data. It is recommended that buffer is 4-byte aligned as some drivers might not support 1-byte alignment if DMA is used.

The argument len maximum number of bytes to receive (must be multiple of device endpoint maximum packet size).

Note
For isochronous transfer, with registered callback, this function is non-blocking and returns when transfer is queued (double-buffering). The parameter data must point to memory accessible by the USB Host controller and parameter len must be same as maximum packet size or it will be downsized to a maximum packet size of the isochronous endpoint. Only supported for full-speed transfers on the EHCI controller.

Code Example

do {
status = USBH_PipeReceive (USBH_CC_PipeHandle[PL2303_RECEIVE_PIPE_INDEX], usart_receive_data, usart_receive_num);
} while (status == usbTimeout);

◆ USBH_PipeReceiveGetResult()

uint32_t USBH_PipeReceiveGetResult ( USBH_PIPE_HANDLE  pipe_hndl)

Get result of receive data operation on Pipe.

Parameters
[in]pipe_hndlpipe handle.
Returns
number of successfully received data bytes.

The function USBH_PipeReceiveGetResult retrieves number of received data bytes on a Pipe.

The argument pipe_hndl is a handle to pipe used for data reception.

Note
For non-blocking isochronous transfer, this function always returns 0.

◆ USBH_PipeSend()

usbStatus USBH_PipeSend ( USBH_PIPE_HANDLE  pipe_hndl,
const uint8_t *  buf,
uint32_t  len 
)

Send data on Pipe.

Parameters
[in]pipe_hndlpipe handle.
[in]bufbuffer containing data bytes to send.
[in]lennumber of bytes to send.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_PipeSend sends data on a Pipe. Number of bytes sent can be retrieved by USBH_PipeSendGetResult function.

The argument pipe_hndl is a handle to pipe used for sending data.

The argument buf buffer containing data bytes to send. It is recommended that buffer is 4-byte aligned as some drivers might not support 1-byte alignment if DMA is used.

The argument len maximum number of bytes to send.

Note
For isochronous transfer, with registered callback, this function is non-blocking and returns when transfer is queued (double-buffering). The parameter data must point to memory accessible by the USB Host controller and parameter len must be same as maximum packet size or it will be downsized to a maximum packet size of the isochronous endpoint. Only supported for full-speed transfers on the EHCI controller.

Code Example

// Send Data on Bulk Out Pipe in thread
USBH_PipeSend (USBH_CC_PipeHandle[PL2303_SEND_PIPE_INDEX], usart_send_data, usart_send_num);

◆ USBH_PipeSendGetResult()

uint32_t USBH_PipeSendGetResult ( USBH_PIPE_HANDLE  pipe_hndl)

Get result of send data operation on Pipe.

Parameters
[in]pipe_hndlpipe handle.
Returns
number of successfully sent data bytes.

The function USBH_PipeSendGetResult retrieves number of successfully sent data bytes on a Pipe.

The argument pipe_hndl is a handle to pipe used for sending data.

Note
For non-blocking isochronous transfer, this function always returns 0.

◆ USBH_PipeAbort()

usbStatus USBH_PipeAbort ( USBH_PIPE_HANDLE  pipe_hndl)

Abort send/receive operation on Pipe.

Parameters
[in]pipe_hndlpipe handle.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_PipeAbort aborts active send/receive operation on a Pipe.

The argument pipe_hndl is a handle to pipe on which active transfer should be aborted.

◆ USBH_ControlTransfer()

usbStatus USBH_ControlTransfer ( uint8_t  device,
const USB_SETUP_PACKET *  setup_packet,
uint8_t *  data,
uint32_t  len 
)

Do a Control Transfer on Default Pipe.

Parameters
[in]deviceindex of USB Device.
[in]setup_packetpointer to setup packet.
[in,out]databuffer containing data bytes to send or where data should be received in data stage of Control Transfer.
[in]lennumber of bytes to send or receive in data stage of Control Transfer.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_ControlTransfer does an Control Transfer on the Default Pipe.

The argument device is the index of the USB Device to which Control Transfer is addressed.

The argument setup_packet pointer to setup packet.

The argument data containing data bytes to send or where data should be received in data stage of Control Transfer.

The argument len number of bytes to send or receive in data stage of Control Transfer.

Code Example

USB_SETUP_PACKET setup_packet;
uint8_t buf[8];
// Custom PL2303 initialization
setup_packet.bmRequestType.Dir = USB_REQUEST_DEVICE_TO_HOST;
setup_packet.bmRequestType.Type = USB_REQUEST_VENDOR;
setup_packet.bmRequestType.Recipient= USB_REQUEST_TO_DEVICE;
setup_packet.bRequest = 1;
setup_packet.wValue = U16_LE(0x8484U);
setup_packet.wIndex = U16_LE(0U);
setup_packet.wLength = U16_LE(1U);
if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, buf, 1U) != usbOK) { return usbClassErrorCustom; }
:

◆ USBH_DeviceRequest_GetStatus()

usbStatus USBH_DeviceRequest_GetStatus ( uint8_t  device,
uint8_t  recipient,
uint8_t  index,
uint8_t *  ptr_stat_dat 
)

Standard Device Request on Default Pipe - GET_STATUS.

Parameters
[in]deviceindex of USB Device.
[in]recipientrecipient.
[in]indexinterface or endpoint index.
[out]ptr_stat_datpointer to where status data should be received.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_DeviceRequest_GetStatus implements the standard device request GET_STATUS. This request returns the current device configuration value.

The argument device is the index of the USB Device to which standard device request is addressed.

The argument recipient defines the recipient of the GET_STATUS command.

The argument index denotes the interface or endpoint index to be used.

The argument ptr_stat_dat is a pointer to the where the data should be received.

◆ USBH_DeviceRequest_ClearFeature()

usbStatus USBH_DeviceRequest_ClearFeature ( uint8_t  device,
uint8_t  recipient,
uint8_t  index,
uint8_t  feature_selector 
)

Standard Device Request on Default Pipe - CLEAR_FEATURE.

Parameters
[in]deviceindex of USB Device.
[in]recipientrecipient.
[in]indexinterface or endpoint index.
[in]feature_selectorfeature selector.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_DeviceRequest_ClearFeature implements the standard device request CLEAR_FEATURE. This request is used to clear or disable a specific feature.

The argument device is the index of the USB Device to which standard device request is addressed.

The argument recipient defines the recipient of the CLEAR_FEATURE command.

The argument index denotes the interface or endpoint index to be used.

The argument feature_selector indicates the feature to be cleared.

◆ USBH_DeviceRequest_SetFeature()

usbStatus USBH_DeviceRequest_SetFeature ( uint8_t  device,
uint8_t  recipient,
uint8_t  index,
uint8_t  feature_selector 
)

Standard Device Request on Default Pipe - SET_FEATURE.

Parameters
[in]deviceindex of USB Device.
[in]recipientrecipient.
[in]indexinterface or endpoint index.
[in]feature_selectorfeature selector.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_DeviceRequest_SetFeature implements the standard device request SET_FEATURE. This request is used to set or enable a specific feature.

The argument device is the index of the USB Device to which standard device request is addressed.

The argument recipient defines the recipient of the SET_FEATURE command.

The argument index denotes the interface or endpoint index to be used.

The argument feature_selector indicates the feature to be cleared.

◆ USBH_DeviceRequest_SetAddress()

usbStatus USBH_DeviceRequest_SetAddress ( uint8_t  device,
uint8_t  device_address 
)

Standard Device Request on Default Pipe - SET_ADDRESS.

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

The function USBH_DeviceRequest_SetAddress implements the standard device request SET_ADDRESS. This request sets the device address for all future device accesses.

The argument device is the index of the USB Device to which standard device request is addressed.

The argument device_address specifies the new device address.

◆ USBH_DeviceRequest_GetDescriptor()

usbStatus USBH_DeviceRequest_GetDescriptor ( uint8_t  device,
uint8_t  recipient,
uint8_t  descriptor_type,
uint8_t  descriptor_index,
uint16_t  language_id,
uint8_t *  descriptor_data,
uint16_t  descriptor_length 
)

Standard Device Request on Default Pipe - GET_DESCRIPTOR.

Parameters
[in]deviceindex of USB Device.
[in]recipientrecipient.
[in]descriptor_typedescriptor type.
[in]descriptor_indexdescriptor index.
[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_DeviceRequest_GetDescriptor implements the standard device request GET_DESCRIPTOR. This request returns the specified descriptor if the descriptor exists.

The argument device is the index of the USB Device to which standard device request is addressed.

The argument recipient defines the recipient of the GET_DESCRIPTOR command.

The argument descriptor_type specifies the descriptor type to be queried, whereas the argument descriptor_index is used to select a specific descriptor (only for configuration and string descriptors) when several descriptors of the same type are implemented in a device.

The argument language_id specifies the Language ID of string descriptors or is set to zero for other descriptors.

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_DeviceRequest_SetDescriptor()

usbStatus USBH_DeviceRequest_SetDescriptor ( uint8_t  device,
uint8_t  recipient,
uint8_t  descriptor_type,
uint8_t  descriptor_index,
uint16_t  language_id,
const uint8_t *  descriptor_data,
uint16_t  descriptor_length 
)

Standard Device Request on Default Pipe - SET_DESCRIPTOR.

Parameters
[in]deviceindex of USB Device.
[in]recipientrecipient.
[in]descriptor_typedescriptor type.
[in]descriptor_indexdescriptor index.
[in]language_idlanguage ID.
[in]descriptor_datapointer to descriptor data to be written.
[in]descriptor_lengthdescriptor length.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_DeviceRequest_SetDescriptor implements the standard device request SET_DESCRIPTOR. This request may be used to update existing or add new descriptors.

The argument device is the index of the USB Device to which standard device request is addressed.

The argument recipient defines the recipient of the SET_DESCRIPTOR command.

The argument descriptor_type specifies the descriptor type to be queried, whereas the argument descriptor_index is used to select a specific descriptor (only for configuration and string descriptors) when several descriptors of the same type are implemented in a device.

The argument language_id specifies the Language ID for string descriptors or is set to zero for other descriptors.

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

◆ USBH_DeviceRequest_GetConfiguration()

usbStatus USBH_DeviceRequest_GetConfiguration ( uint8_t  device,
uint8_t *  ptr_configuration 
)

Standard Device Request on Default Pipe - GET_CONFIGURATION.

Parameters
[in]deviceindex of USB Device.
[out]ptr_configurationpointer to where configuration will be read.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_DeviceRequest_GetConfiguration implements the standard device request GET_CONFIGURATION. This request returns the current device configuration value.

The argument device is the index of the USB Device to which standard device request is addressed.

The argument ptr_configuration specifies the pointer to where the configuration will be read.

◆ USBH_DeviceRequest_SetConfiguration()

usbStatus USBH_DeviceRequest_SetConfiguration ( uint8_t  device,
uint8_t  configuration 
)

Standard Device Request on Default Pipe - SET_CONFIGURATION.

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

The function USBH_DeviceRequest_SetConfiguration implements the standard device request SET_CONFIGURATION. This request sets the device configuration.

The argument device is the index of the USB Device to which standard device request is addressed.

The argument configuration contains the new configuration to be set.

◆ USBH_DeviceRequest_GetInterface()

usbStatus USBH_DeviceRequest_GetInterface ( uint8_t  device,
uint8_t  index,
uint8_t *  ptr_alternate 
)

Standard Device Request on Default Pipe - GET_INTERFACE.

Parameters
[in]deviceindex of USB Device.
[in]indexinterface index.
[out]ptr_alternatepointer to where alternate setting data will be read.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_DeviceRequest_GetInterface implements the standard device request GET_INTERFACE. This request returns the selected alternate setting for the specified interface.

The argument device is the index of the USB Device to which standard device request is addressed.

The argument index specifies the interface index.

The argument ptr_alternate specifies the pointer to where alternate setting data will be read.

◆ USBH_DeviceRequest_SetInterface()

usbStatus USBH_DeviceRequest_SetInterface ( uint8_t  device,
uint8_t  index,
uint8_t  alternate 
)

Standard Device Request on Default Pipe - SET_INTERFACE.

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

The function USBH_DeviceRequest_SetInterface implements the standard device request SET_INTERFACE. This request allows the host to select an alternate setting for the specified interface.

The argument device is the index of the USB Device to which standard device request is addressed.

The argument index specifies the interface index.

The argument alternate specifies the alternate setting to be set.

◆ USBH_DeviceRequest_SynchFrame()

usbStatus USBH_DeviceRequest_SynchFrame ( uint8_t  device,
uint8_t  index,
uint8_t *  ptr_frame_number 
)

Standard Device Request on Default Pipe - SYNCH_FRAME.

Parameters
[in]deviceindex of USB Device.
[in]indexinterface or endpoint index.
[out]ptr_frame_numberpointer to where frame number data will be read.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_DeviceRequest_SynchFrame implements the standard device request SYNCH_FRAME. This request is used to set and then report an endpoint's synchronization frame. When an endpoint supports isochronous transfers, the endpoint may also require per-frame transfers to vary in size according to a specific pattern. The host and the endpoint must agree on which frame the repeating pattern begins. The number of the frame in which the pattern began is returned to the host.

The argument device is the index of the USB Device to which standard device request is addressed.

The argument index specifies the interface index.

The argument ptr_frame_number is a pointer to where frame number data will be sent.