USB Component  Version 6.6
MDK-Professional Middleware for USB Device and Host
 All Data Structures Functions Variables Enumerations Enumerator Groups Pages
Functions
User API
Custom Class

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

Functions

uint8_t USBH_CustomClass_Configure (const USBH_DEV *ptr_dev, 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 * USBH_PipeCreate (uint8_t ctrl, uint8_t dev_addr, uint8_t dev_speed, uint8_t hub_addr, uint8_t hub_port, uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size, uint8_t ep_interval)
 Create Pipe.
 
usbStatus USBH_PipeModify (uint8_t ctrl, USBH_PIPE *ptr_pipe, uint8_t dev_addr, uint8_t dev_speed, uint8_t hub_addr, uint8_t hub_port, uint16_t ep_max_packet_size)
 Modify Pipe.
 
usbStatus USBH_PipeDelete (uint8_t ctrl, USBH_PIPE *ptr_pipe)
 Delete Pipe.
 
usbStatus USBH_PipeReset (uint8_t ctrl, USBH_PIPE *ptr_pipe)
 Reset Pipe (reset data toggle)
 
usbStatus USBH_PipeReceive (uint8_t ctrl, USBH_PIPE *ptr_pipe, uint8_t *buf, uint32_t len)
 Receive data on Pipe.
 
uint32_t USBH_PipeReceiveGetResult (uint8_t ctrl, const USBH_PIPE *ptr_pipe)
 Get result of receive data operation on Pipe.
 
usbStatus USBH_PipeSend (uint8_t ctrl, USBH_PIPE *ptr_pipe, const uint8_t *buf, uint32_t len)
 Send data on Pipe.
 
uint32_t USBH_PipeSendGetResult (uint8_t ctrl, const USBH_PIPE *ptr_pipe)
 Get result of send data operation on Pipe.
 
usbStatus USBH_PipeAbort (uint8_t ctrl, const USBH_PIPE *ptr_pipe)
 Abort send/receive operation on Pipe.
 
usbStatus USBH_DefaultPipeReceive (uint8_t ctrl, uint8_t *buf, uint32_t len)
 Receive data on Default Pipe.
 
uint32_t USBH_DefaultPipeReceiveGetResult (uint8_t ctrl)
 Get result of receive data operation on Default Pipe.
 
usbStatus USBH_DefaultPipeSendSetup (uint8_t ctrl, const USB_SETUP_PACKET *setup_packet)
 Send Setup Packet on Default Pipe.
 
usbStatus USBH_DefaultPipeSend (uint8_t ctrl, const uint8_t *buf, uint32_t len)
 Send data on Default Pipe.
 
uint32_t USBH_DefaultPipeSendGetResult (uint8_t ctrl)
 Get result of send data operation on Default Pipe.
 
usbStatus USBH_DefaultPipeAbort (uint8_t ctrl)
 Abort send/receive operation on Default Pipe.
 
usbStatus USBH_ControlTransfer (uint8_t ctrl, 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 ctrl, 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 ctrl, uint8_t recipient, uint8_t index, uint8_t feature_selector)
 Standard Device Request on Default Pipe - CLEAR_FEATURE.
 
usbStatus USBH_DeviceRequest_SetFeature (uint8_t ctrl, uint8_t recipient, uint8_t index, uint8_t feature_selector)
 Standard Device Request on Default Pipe - SET_FEATURE.
 
usbStatus USBH_DeviceRequest_SetAddress (uint8_t ctrl, uint8_t device_address)
 Standard Device Request on Default Pipe - SET_ADDRESS.
 
usbStatus USBH_DeviceRequest_GetDescriptor (uint8_t ctrl, uint8_t recipient, uint8_t descriptor_type, uint8_t descriptor_index, uint8_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 ctrl, uint8_t recipient, uint8_t descriptor_type, uint8_t descriptor_index, uint8_t language_id, uint8_t *descriptor_data, uint16_t descriptor_length)
 Standard Device Request on Default Pipe - SET_DESCRIPTOR.
 
usbStatus USBH_DeviceRequest_GetConfiguration (uint8_t ctrl, uint8_t *ptr_configuration)
 Standard Device Request on Default Pipe - GET_CONFIGURATION.
 
usbStatus USBH_DeviceRequest_SetConfiguration (uint8_t ctrl, uint8_t configuration)
 Standard Device Request on Default Pipe - SET_CONFIGURATION.
 
usbStatus USBH_DeviceRequest_GetInterface (uint8_t ctrl, uint8_t index, uint8_t *ptr_alternate)
 Standard Device Request on Default Pipe - GET_INTERFACE.
 
usbStatus USBH_DeviceRequest_SetInterface (uint8_t ctrl, uint8_t index, uint8_t alternate)
 Standard Device Request on Default Pipe - SET_INTERFACE.
 
usbStatus USBH_DeviceRequest_SynchFrame (uint8_t ctrl, 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

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

Do a Control Transfer on Default Pipe.

Parameters
[in]ctrlindex of USB Host controller.
[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 ctrl is the index of the USB Host controller that is to be used.

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(0x8484);
setup_packet.wIndex = U16_LE(0);
setup_packet.wLength = U16_LE(1);
if (USBH_ControlTransfer (USBH_CustomClass_Ctrl, &setup_packet, buf, 1) != usbOK) return usbClassErrorCustom;
:
uint8_t USBH_CustomClass_Configure ( const USBH_DEV *  ptr_dev,
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]ptr_devpointer to device structure.
[in]ptr_dev_descpointer to device descriptor.
[in]ptr_cfg_descpointer to configuration descriptor.
Returns
value <= 127 index of configured custom class device instance.
value == 0xFF 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 ptr_dev specifies the pointer to 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 (const USBH_DEV *ptr_dev, const USB_DEVICE_DESCRIPTOR *ptr_dev_desc, const USB_CONFIGURATION_DESCRIPTOR *ptr_cfg_desc) {
USBH_PIPE *ptr_pipe;
USB_INTERFACE_DESCRIPTOR *ptr_if_desc;
USB_ENDPOINT_DESCRIPTOR *ptr_ep_desc;
uint8_t num, i;
USBH_CustomClass_Ctrl = ptr_dev->ctrl; // Store controller number
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 != 0x067B) || (ptr_dev_desc->idProduct != 0x2303))
return 0xFF;
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 = 0;
while (num--) {
ptr_pipe = USBH_PipeCreate (ptr_dev->ctrl, ptr_dev->dev_addr, ptr_dev->dev_speed, 0, 0, ptr_ep_desc->bEndpointAddress, ptr_ep_desc->bmAttributes & USB_ENDPOINT_TYPE_MASK, ptr_ep_desc->wMaxPacketSize & 0x7FF, ptr_ep_desc->bInterval);
if (!ptr_pipe) {
// If creation of pipe failed delete previously created pipes
for (i = 0; i < 8; i++) {
if (USBH_CustomClass_Pipes[i]) {
USBH_PipeDelete (USBH_CustomClass_Ctrl, USBH_CustomClass_Pipes[i]);
USBH_CustomClass_Pipes[i] = NULL;
}
}
return 0xFF;
}
USBH_CustomClass_Pipes[i++] = ptr_pipe;
ptr_ep_desc++;
}
return 0; // Device connected and configured
// Only single instance supported
// so it's instance index is 0
}
break;
}
break;
}
return 0xFF; // Device not handled
}
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;
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(0x8484);
setup_packet.wIndex = U16_LE(0);
setup_packet.wLength = U16_LE(1);
if (USBH_ControlTransfer (USBH_CustomClass_Ctrl, &setup_packet, buf, 1) != usbOK) return usbClassErrorCustom;
setup_packet.bmRequestType.Dir = USB_REQUEST_HOST_TO_DEVICE;
setup_packet.wValue = U16_LE(0x0404);
if (USBH_ControlTransfer (USBH_CustomClass_Ctrl, &setup_packet, buf, 1) != usbOK) return usbClassErrorCustom;
setup_packet.bmRequestType.Dir = USB_REQUEST_DEVICE_TO_HOST;
setup_packet.wValue = U16_LE(0x8484);
if (USBH_ControlTransfer (USBH_CustomClass_Ctrl, &setup_packet, buf, 1) != usbOK) return usbClassErrorCustom;
setup_packet.wValue = U16_LE(0x8383);
if (USBH_ControlTransfer (USBH_CustomClass_Ctrl, &setup_packet, buf, 1) != usbOK) return usbClassErrorCustom;
setup_packet.wValue = U16_LE(0x8484);
if (USBH_ControlTransfer (USBH_CustomClass_Ctrl, &setup_packet, buf, 1) != usbOK) return usbClassErrorCustom;
setup_packet.bmRequestType.Dir = USB_REQUEST_HOST_TO_DEVICE;
setup_packet.wValue = U16_LE(0x0404);
setup_packet.wIndex = U16_LE(1);
setup_packet.wLength = U16_LE(0);
if (USBH_ControlTransfer (USBH_CustomClass_Ctrl, &setup_packet, NULL, 0) != usbOK) return usbClassErrorCustom;
setup_packet.bmRequestType.Dir = USB_REQUEST_DEVICE_TO_HOST;
setup_packet.wValue = U16_LE(0x8484);
setup_packet.wIndex = U16_LE(0);
setup_packet.wLength = U16_LE(1);
if (USBH_ControlTransfer (USBH_CustomClass_Ctrl, &setup_packet, buf, 1) != usbOK) return usbClassErrorCustom;
setup_packet.wValue = U16_LE(0x8383);
if (USBH_ControlTransfer (USBH_CustomClass_Ctrl, &setup_packet, buf, 1) != usbOK) return usbClassErrorCustom;
setup_packet.bmRequestType.Dir = USB_REQUEST_HOST_TO_DEVICE;
setup_packet.wValue = U16_LE(0);
setup_packet.wIndex = U16_LE(1);
setup_packet.wLength = U16_LE(0);
if (USBH_ControlTransfer (USBH_CustomClass_Ctrl, &setup_packet, NULL, 0) != usbOK) return usbClassErrorCustom;
setup_packet.wValue = U16_LE(1);
setup_packet.wIndex = U16_LE(0);
if (USBH_ControlTransfer (USBH_CustomClass_Ctrl, &setup_packet, NULL, 0) != usbOK) return usbClassErrorCustom;
setup_packet.wValue = U16_LE(2);
setup_packet.wIndex = U16_LE(0x44);
if (USBH_ControlTransfer (USBH_CustomClass_Ctrl, &setup_packet, NULL, 0) != 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 = 0x20;
setup_packet.wValue = U16_LE(0);
setup_packet.wIndex = U16_LE(0);
setup_packet.wLength = U16_LE(7);
*((uint32_t *)&buf[0]) = U32_LE(9600);// Data terminal rate in bits per second = 9600 baud
buf[4] = 0; // Number of stop bits = 1
buf[5] = 0; // Parity bit type = None
buf[6] = 8; // Number of data bits = 8
if (USBH_ControlTransfer (USBH_CustomClass_Ctrl, &setup_packet, buf, 7) != usbOK) return usbClassErrorCustom;
return usbOK;
}
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

usbStatus USBH_CustomClass_Unconfigure (uint8_t instance) {
uint8_t i;
USBH_CustomClass_Ctrl = 0;
for (i = 0; i < 8; i++) {
if (USBH_CustomClass_Pipes[i]) {
USBH_PipeDelete (USBH_CustomClass_Ctrl, USBH_CustomClass_Pipes[i]);
USBH_CustomClass_Pipes[i] = NULL;
}
}
return usbOK;
}
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) {
// Do de-initialization of device if necessary
return usbOK;
}
usbStatus USBH_DefaultPipeAbort ( uint8_t  ctrl)

Abort send/receive operation on Default Pipe.

Parameters
[in]ctrlindex of USB Host controller.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_DefaultPipeAbort aborts active send/receive operation on the Default Pipe.

The argument ctrl is the index of the USB Host controller that is to be used.

usbStatus USBH_DefaultPipeReceive ( uint8_t  ctrl,
uint8_t *  buf,
uint32_t  len 
)

Receive data on Default Pipe.

Parameters
[in]ctrlindex of USB Host controller.
[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_DefaultPipeReceive receives data on the Default Pipe. Number of bytes received can be retrieved by USBH_DefaultPipeReceiveGetResult function.

The argument ctrl is the index of the USB Host controller that is to be used.

The argument buf buffer that receives data.

The argument len maximum number of bytes to receive.

uint32_t USBH_DefaultPipeReceiveGetResult ( uint8_t  ctrl)

Get result of receive data operation on Default Pipe.

Parameters
[in]ctrlindex of USB Host controller.
Returns
number of successfully received data bytes.

The function USBH_DefaultPipeReceiveGetResult retrieves number of received data bytes on the Default Pipe.

The argument ctrl is the index of the USB Host controller that is to be used.

usbStatus USBH_DefaultPipeSend ( uint8_t  ctrl,
const uint8_t *  buf,
uint32_t  len 
)

Send data on Default Pipe.

Parameters
[in]ctrlindex of USB Host controller.
[in]bufbuffer containing data bytes to send.
[in]lenmaximum number of bytes to send.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_DefaultPipeSend sends data on the Default Pipe. Number of bytes sent can be retrieved by USBH_DefaultPipeSendGetResult function.

The argument ctrl is the index of the USB Host controller that is to be used.

The argument buf buffer containing data bytes to send.

The argument len maximum number of bytes to send.

uint32_t USBH_DefaultPipeSendGetResult ( uint8_t  ctrl)

Get result of send data operation on Default Pipe.

Parameters
[in]ctrlindex of USB Host controller.
Returns
number of successfully sent data bytes.

The function USBH_DefaultPipeSendGetResult retrieves number of successfully sent data bytes on the Default Pipe.

The argument ctrl is the index of the USB Host controller that is to be used.

usbStatus USBH_DefaultPipeSendSetup ( uint8_t  ctrl,
const USB_SETUP_PACKET *  setup_packet 
)

Send Setup Packet on Default Pipe.

Parameters
[in]ctrlindex of USB Host controller.
[in]setup_packetpointer to setup packet.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_DefaultPipeSendSetup sends a setup packet on the Default Pipe.

The argument ctrl is the index of the USB Host controller that is to be used.

The argument setup_packet pointer to setup packet.

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

Standard Device Request on Default Pipe - CLEAR_FEATURE.

Parameters
[in]ctrlindex of USB Host controller.
[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 ctrl is the index of the USB Host controller that is to be used.

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.

usbStatus USBH_DeviceRequest_GetConfiguration ( uint8_t  ctrl,
uint8_t *  ptr_configuration 
)

Standard Device Request on Default Pipe - GET_CONFIGURATION.

Parameters
[in]ctrlindex of USB Host controller.
[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 ctrl is the index of the USB Host controller that is to be used.

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

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

Standard Device Request on Default Pipe - GET_DESCRIPTOR.

Parameters
[in]ctrlindex of USB Host controller.
[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_lengthdescriptor 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 ctrl is the index of the USB Host controller that is to be used.

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

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

Standard Device Request on Default Pipe - GET_INTERFACE.

Parameters
[in]ctrlindex of USB Host controller.
[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 ctrl is the index of the USB Host controller that is to be used.

The argument index specifies the interface index.

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

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

Standard Device Request on Default Pipe - GET_STATUS.

Parameters
[in]ctrlindex of USB Host controller.
[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 ctrl is the index of the USB Host controller that is to be used.

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.

usbStatus USBH_DeviceRequest_SetAddress ( uint8_t  ctrl,
uint8_t  device_address 
)

Standard Device Request on Default Pipe - SET_ADDRESS.

Parameters
[in]ctrlindex of USB Host controller.
[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 ctrl is the index of the USB Host controller that is to be used.

The argument device_address specifies the new device address.

usbStatus USBH_DeviceRequest_SetConfiguration ( uint8_t  ctrl,
uint8_t  configuration 
)

Standard Device Request on Default Pipe - SET_CONFIGURATION.

Parameters
[in]ctrlindex of USB Host controller.
[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 ctrl is the index of the USB Host controller that is to be used.

The argument configuration contains the new configuration to be set.

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

Standard Device Request on Default Pipe - SET_DESCRIPTOR.

Parameters
[in]ctrlindex of USB Host controller.
[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 ctrl is the index of the USB Host controller that is to be used.

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.

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

Standard Device Request on Default Pipe - SET_FEATURE.

Parameters
[in]ctrlindex of USB Host controller.
[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 ctrl is the index of the USB Host controller that is to be used.

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.

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

Standard Device Request on Default Pipe - SET_INTERFACE.

Parameters
[in]ctrlindex of USB Host controller.
[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 ctrl is the index of the USB Host controller that is to be used.

The argument index specifies the interface index.

The argument alternate specifies the alternate setting to be set.

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

Standard Device Request on Default Pipe - SYNCH_FRAME.

Parameters
[in]ctrlindex of USB Host controller.
[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 ctrl is the index of the USB Host controller that is to be used.

The argument index specifies the interface index.

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

usbStatus USBH_PipeAbort ( uint8_t  ctrl,
const USBH_PIPE *  ptr_pipe 
)

Abort send/receive operation on Pipe.

Parameters
[in]ctrlindex of USB Host controller.
[in]ptr_pipepointer to pipe.
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 ctrl is the index of the USB Host controller that is to be used.

The argument ptr_pipe is a pointer to pipe.

USBH_PIPE * USBH_PipeCreate ( uint8_t  ctrl,
uint8_t  dev_addr,
uint8_t  dev_speed,
uint8_t  hub_addr,
uint8_t  hub_port,
uint8_t  ep_addr,
uint8_t  ep_type,
uint16_t  ep_max_packet_size,
uint8_t  ep_interval 
)

Create Pipe.

Parameters
[in]ctrlindex of USB Host controller.
[in]dev_addrdevice address.
[in]dev_speeddevice speed.
[in]hub_addrhub address.
[in]hub_porthub port.
[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
pointer to created pipe or pipe creation failed
  • value > 0: pointer to created pipe
  • value 0: pipe creation failed

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

The argument ctrl is the index of the USB Host controller that is to be used.

The argument dev_addr is the device address.

The argument dev_speed is the device speed.

The argument hub_addr is the hub address.

The argument hub_port is the hub port.

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 (const USBH_DEV *ptr_dev, const USB_DEVICE_DESCRIPTOR *ptr_dev_desc, const USB_CONFIGURATION_DESCRIPTOR *ptr_cfg_desc) {
USBH_PIPE *ptr_pipe;
:
ptr_pipe = USBH_PipeCreate (ptr_dev->ctrl, ptr_dev->dev_addr, ptr_dev->dev_speed, 0, 0, ptr_ep_desc->bEndpointAddress, ptr_ep_desc->bmAttributes & USB_ENDPOINT_TYPE_MASK, ptr_ep_desc->wMaxPacketSize & 0x7FF, ptr_ep_desc->bInterval);
:
}
usbStatus USBH_PipeDelete ( uint8_t  ctrl,
USBH_PIPE *  ptr_pipe 
)

Delete Pipe.

Parameters
[in]ctrlindex of USB Host controller.
[in]ptr_pipepointer to pipe.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_PipeDelete removes a Pipe.

The argument ctrl is the index of the USB Host controller that is to be used.

The argument ptr_pipe is a pointer to pipe to be removed.

Code Example

// If creation of pipe failed delete previously created pipes
for (i = 0; i < 8; i++) {
if (USBH_CustomClass_Pipes[i]) {
USBH_PipeDelete (USBH_CustomClass_Ctrl, USBH_CustomClass_Pipes[i]);
USBH_CustomClass_Pipes[i] = NULL;
}
}
usbStatus USBH_PipeModify ( uint8_t  ctrl,
USBH_PIPE *  ptr_pipe,
uint8_t  dev_addr,
uint8_t  dev_speed,
uint8_t  hub_addr,
uint8_t  hub_port,
uint16_t  ep_max_packet_size 
)

Modify Pipe.

Parameters
[in]ctrlindex of USB Host controller.
[in]ptr_pipepointer to pipe.
[in]dev_addrdevice address.
[in]dev_speeddevice speed.
[in]hub_addrhub address.
[in]hub_porthub port.
[in]ep_max_packet_sizeendpoint maximum packet size.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_PipeModify modifies a Pipe.

The argument ctrl is the index of the USB Host controller that is to be used.

The argument ptr_pipe is a pointer to pipe to be modified.

The argument dev_addr is the modified device address.

The argument dev_speed is the modified device speed.

The argument hub_addr is the modified hub address.

The argument hub_port is the modified hub port.

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

usbStatus USBH_PipeReceive ( uint8_t  ctrl,
USBH_PIPE *  ptr_pipe,
uint8_t *  buf,
uint32_t  len 
)

Receive data on Pipe.

Parameters
[in]ctrlindex of USB Host controller.
[in]ptr_pipepointer to pipe.
[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 ctrl is the index of the USB Host controller that is to be used.

The argument ptr_pipe is a pointer to pipe.

The argument buf buffer that receives data.

The argument len maximum number of bytes to receive.

Code Example

do {
status = USBH_PipeReceive (USBH_CustomClass_Ctrl, USBH_CustomClass_Pipes[PL2303_RECEIVE_PIPE_INDEX], usart_receive_data, usart_receive_num);
} while (status == usbTimeout);
uint32_t USBH_PipeReceiveGetResult ( uint8_t  ctrl,
const USBH_PIPE *  ptr_pipe 
)

Get result of receive data operation on Pipe.

Parameters
[in]ctrlindex of USB Host controller.
[in]ptr_pipepointer to pipe.
Returns
number of successfully received data bytes.

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

The argument ctrl is the index of the USB Host controller that is to be used.

The argument ptr_pipe is a pointer to pipe used for data reception.

usbStatus USBH_PipeReset ( uint8_t  ctrl,
USBH_PIPE *  ptr_pipe 
)

Reset Pipe (reset data toggle)

Parameters
[in]ctrlindex of USB Host controller.
[in]ptr_pipepointer to pipe.
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 ctrl is the index of the USB Host controller that is to be used.

The argument ptr_pipe is a pointer to pipe.

usbStatus USBH_PipeSend ( uint8_t  ctrl,
USBH_PIPE *  ptr_pipe,
const uint8_t *  buf,
uint32_t  len 
)

Send data on Pipe.

Parameters
[in]ctrlindex of USB Host controller.
[in]ptr_pipepointer to pipe.
[in]bufbuffer containing data bytes to send.
[in]lenmaximum 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 ctrl is the index of the USB Host controller that is to be used.

The argument ptr_pipe is a pointer to pipe.

The argument buf buffer containing data bytes to send.

The argument len maximum number of bytes to send.

Code Example

// Send Data on Bulk Out Pipe in thread
USBH_PipeSend (USBH_CustomClass_Ctrl, USBH_CustomClass_Pipes[PL2303_SEND_PIPE_INDEX], usart_send_data, usart_send_num);
uint32_t USBH_PipeSendGetResult ( uint8_t  ctrl,
const USBH_PIPE *  ptr_pipe 
)

Get result of send data operation on Pipe.

Parameters
[in]ctrlindex of USB Host controller.
[in]ptr_pipepointer to pipe.
Returns
number of successfully sent data bytes.

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

The argument ctrl is the index of the USB Host controller that is to be used.

The argument ptr_pipe is a pointer to pipe used for sending data.