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

Functions
uint8_t	USBH_CustomClass_GetDevice (uint8_t instance)
	Get Device instance of Custom Class Device.

usbStatus	USBH_CustomClass_GetStatus (uint8_t instance)
	Get status of Custom Class Device.

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.

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.

usbStatus	USBH_CustomClass_Initialize (uint8_t instance)
	Callback function called when custom class device is connected and needs to initialize custom class device instance.

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.

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.

usbStatus	USBH_PipeRegisterCallback (USBH_PIPE_HANDLE pipe_hndl, USBH_PipeEvent_t cb_pipe_event)
	Register a callback for Pipe events.

usbStatus	USBH_PipeUpdate (USBH_PIPE_HANDLE pipe_hndl)
	Update Pipe.

usbStatus	USBH_PipeDelete (USBH_PIPE_HANDLE pipe_hndl)
	Delete Pipe.

usbStatus	USBH_PipeReset (USBH_PIPE_HANDLE pipe_hndl)
	Reset Pipe (reset data toggle)

usbStatus	USBH_PipeReceive (USBH_PIPE_HANDLE pipe_hndl, uint8_t *buf, uint32_t len)
	Receive data on Pipe.

uint32_t	USBH_PipeReceiveGetResult (USBH_PIPE_HANDLE pipe_hndl)
	Get result of receive data operation on Pipe.

usbStatus	USBH_PipeSend (USBH_PIPE_HANDLE pipe_hndl, const uint8_t *buf, uint32_t len)
	Send data on Pipe.

uint32_t	USBH_PipeSendGetResult (USBH_PIPE_HANDLE pipe_hndl)
	Get result of send data operation on Pipe.

usbStatus	USBH_PipeAbort (USBH_PIPE_HANDLE pipe_hndl)
	Abort send/receive operation on Pipe.

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.

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.

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.

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.

usbStatus	USBH_DeviceRequest_SetAddress (uint8_t device, uint8_t device_address)
	Standard Device Request on Default Pipe - SET_ADDRESS.

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.

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.

usbStatus	USBH_DeviceRequest_GetConfiguration (uint8_t device, uint8_t *ptr_configuration)
	Standard Device Request on Default Pipe - GET_CONFIGURATION.

usbStatus	USBH_DeviceRequest_SetConfiguration (uint8_t device, uint8_t configuration)
	Standard Device Request on Default Pipe - SET_CONFIGURATION.

usbStatus	USBH_DeviceRequest_GetInterface (uint8_t device, uint8_t index, uint8_t *ptr_alternate)
	Standard Device Request on Default Pipe - GET_INTERFACE.

usbStatus	USBH_DeviceRequest_SetInterface (uint8_t device, uint8_t index, uint8_t alternate)
	Standard Device Request on Default Pipe - SET_INTERFACE.

usbStatus	USBH_DeviceRequest_SynchFrame (uint8_t device, uint8_t index, uint8_t *ptr_frame_number)
	Standard Device Request on Default Pipe - SYNCH_FRAME.

Description

User API reference of the Custom Class.

Function Documentation

◆ 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]	device	index of USB Device.
[in]	setup_packet	pointer to setup packet.
[in,out]	data	buffer containing data bytes to send or where data should be received in data stage of Control Transfer.
[in]	len	number 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_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]	device	index of USB Device.
[in]	ptr_dev_desc	pointer to device descriptor.
[in]	ptr_cfg_desc	pointer 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) {
                      (void)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
            default:
              break;
          }
          break;
        default:
          break;
      }
      break;
    default:
      break;
  }
 
  return 255U;                          // Device not handled
}

◆ USBH_CustomClass_GetDevice()

uint8_t USBH_CustomClass_GetDevice ( uint8_t instance )

Get Device instance of Custom Class Device.

Parameters

[in] instance instance 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] instance instance 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_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] instance index 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                 = 0x8484U;
  setup_packet.wIndex                 = 0U;
  setup_packet.wLength                = 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                 = 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                 = 0x8484U;
  if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, buf,  1U) != usbOK) { return usbClassErrorCustom; }
 
  setup_packet.wValue                 = 0x8383U;
  if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, buf,  1U) != usbOK) { return usbClassErrorCustom; }
 
  setup_packet.wValue                 = 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                 = 0x0404U;
  setup_packet.wIndex                 = 1U;
  setup_packet.wLength                = 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                 = 0x8484U;
  setup_packet.wIndex                 = 0U;
  setup_packet.wLength                = 1U;
  if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, buf,  1U) != usbOK) { return usbClassErrorCustom; }
 
  setup_packet.wValue                 = 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                 = 0U;
  setup_packet.wIndex                 = 1U;
  setup_packet.wLength                = 0U;
  if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, NULL, 0U) != usbOK) { return usbClassErrorCustom; }
 
  setup_packet.wValue                 = 1U;
  setup_packet.wIndex                 = 0U;
  if (USBH_ControlTransfer (USBH_CC_Device, &setup_packet, NULL, 0U) != usbOK) { return usbClassErrorCustom; }
 
  setup_packet.wValue                 = 2U;
  setup_packet.wIndex                 = 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                 = 0U;
  setup_packet.wIndex                 = 0U;
  setup_packet.wLength                = 7U;
  br                                  = 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_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] instance index 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) {
    (void)USBH_PipeDelete (USBH_CC_PipeHandle[i]);
    USBH_CC_PipeHandle[i] = 0U;
  }
}
 
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] instance index 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_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]	device	index of USB Device.
[in]	recipient	recipient.
[in]	index	interface or endpoint index.
[in]	feature_selector	feature 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_GetConfiguration()

usbStatus USBH_DeviceRequest_GetConfiguration	(	uint8_t	device,
		uint8_t *	ptr_configuration
	)

Standard Device Request on Default Pipe - GET_CONFIGURATION.

Parameters

[in]	device	index of USB Device.
[out]	ptr_configuration	pointer 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_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]	device	index of USB Device.
[in]	recipient	recipient.
[in]	descriptor_type	descriptor type.
[in]	descriptor_index	descriptor index.
[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_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_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]	device	index of USB Device.
[in]	index	interface index.
[out]	ptr_alternate	pointer 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_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]	device	index of USB Device.
[in]	recipient	recipient.
[in]	index	interface or endpoint index.
[out]	ptr_stat_dat	pointer 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_SetAddress()

usbStatus USBH_DeviceRequest_SetAddress	(	uint8_t	device,
		uint8_t	device_address
	)

Standard Device Request on Default Pipe - SET_ADDRESS.

Parameters

[in]	device	index of USB Device.
[in]	device_address	device 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_SetConfiguration()

usbStatus USBH_DeviceRequest_SetConfiguration	(	uint8_t	device,
		uint8_t	configuration
	)

Standard Device Request on Default Pipe - SET_CONFIGURATION.

Parameters

[in]	device	index of USB Device.
[in]	configuration	configuration.

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_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]	device	index of USB Device.
[in]	recipient	recipient.
[in]	descriptor_type	descriptor type.
[in]	descriptor_index	descriptor index.
[in]	language_id	language ID.
[in]	descriptor_data	pointer to descriptor data to be written.
[in]	descriptor_length	descriptor 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_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]	device	index of USB Device.
[in]	recipient	recipient.
[in]	index	interface or endpoint index.
[in]	feature_selector	feature 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_SetInterface()

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

Standard Device Request on Default Pipe - SET_INTERFACE.

Parameters

[in]	device	index of USB Device.
[in]	index	interface index.
[in]	alternate	alternate 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]	device	index of USB Device.
[in]	index	interface or endpoint index.
[out]	ptr_frame_number	pointer 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.

◆ USBH_PipeAbort()

usbStatus USBH_PipeAbort ( USBH_PIPE_HANDLE pipe_hndl )

Abort send/receive operation on Pipe.

Parameters

[in] pipe_hndl pipe 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_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]	device	index of USB Device.
[in]	ep_addr	endpoint address : ep_addr.0..3 : address ep_addr.7 : direction
[in]	ep_type	endpoint type.
[in]	ep_max_packet_size	endpoint maximum packet size.
[in]	ep_interval	endpoint 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_PipeDelete()

usbStatus USBH_PipeDelete ( USBH_PIPE_HANDLE pipe_hndl )

Delete Pipe.

Parameters

[in] pipe_hndl pipe 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_PipeReceive()

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

Receive data on Pipe.

Parameters

[in]	pipe_hndl	pipe handle.
[out]	buf	buffer that receives data.
[in]	len	maximum 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_hndl pipe 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_PipeRegisterCallback()

usbStatus USBH_PipeRegisterCallback	(	USBH_PIPE_HANDLE	pipe_hndl,
		USBH_PipeEvent_t	cb_pipe_event
	)

Register a callback for Pipe events.

Parameters

[in]	pipe_hndl	pipe handle.
[in]	cb_pipe_event	pointer 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_PipeReset()

usbStatus USBH_PipeReset ( USBH_PIPE_HANDLE pipe_hndl )

Reset Pipe (reset data toggle)

Parameters

[in] pipe_hndl pipe 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_PipeSend()

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

Send data on Pipe.

Parameters

[in]	pipe_hndl	pipe handle.
[in]	buf	buffer containing data bytes to send.
[in]	len	number 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_hndl pipe 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_PipeUpdate()

usbStatus USBH_PipeUpdate ( USBH_PIPE_HANDLE pipe_hndl )

Update Pipe.

Parameters

[in] pipe_hndl pipe 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.

Functions

Description

Function Documentation

◆ USBH_ControlTransfer()

◆ USBH_CustomClass_Configure()

◆ USBH_CustomClass_GetDevice()

◆ USBH_CustomClass_GetStatus()

◆ USBH_CustomClass_Initialize()

◆ USBH_CustomClass_Unconfigure()

◆ USBH_CustomClass_Uninitialize()

◆ USBH_DeviceRequest_ClearFeature()

◆ USBH_DeviceRequest_GetConfiguration()

◆ USBH_DeviceRequest_GetDescriptor()

◆ USBH_DeviceRequest_GetInterface()

◆ USBH_DeviceRequest_GetStatus()

◆ USBH_DeviceRequest_SetAddress()

◆ USBH_DeviceRequest_SetConfiguration()

◆ USBH_DeviceRequest_SetDescriptor()

◆ USBH_DeviceRequest_SetFeature()

◆ USBH_DeviceRequest_SetInterface()

◆ USBH_DeviceRequest_SynchFrame()

◆ USBH_PipeAbort()

◆ USBH_PipeCreate()

◆ USBH_PipeDelete()

◆ USBH_PipeReceive()

◆ USBH_PipeReceiveGetResult()

◆ USBH_PipeRegisterCallback()

◆ USBH_PipeReset()

◆ USBH_PipeSend()

◆ USBH_PipeSendGetResult()

◆ USBH_PipeUpdate()