UM1021 - STMicroelectronics

USB host library

7.7

7.7.1

UM1021

USB host user interface

Library user API

The library user API functions are limited to the two following functions:

● void USBH_Process (void)

: this function implements core state machine process.

It should be called periodically from the user main loop.

●

USBH_Init

: this function should be called for the initialization of the USB host hardware and library.

USBH_Init

has the following function prototype: void USBH_Init (USB_OTG_CORE_HANDLE *pdev,

USB_OTG_CORE_ID_TypeDef coreID,

USBH_HOST *phost,

USBH_Class_cb_TypeDef *class_cb,

USBH_Usr_cb_TypeDef *usr_cb);

●

●

●

●

● pdev

: pointer on the USB host core register structure

CoreID

: USB OTG core identifier (select the USB core to be used) .

phost

: pointer on the USB host machine structure (reserved for future use).

class_cb

: pointer to a class structure of type USBH_Class_cb_TypeDef. It can be either USBH_MSC_cb for handling MSC devices or USBH_HID_cb for handling HID mouse/keyboard devices.

usr_cb

: pointer to a structure of type USBH_Usr_cb_TypeDef. This structure defines class-independent callbacks (see

Class-independent callback functions on page 89

).

●

●

User callbacks are declared in the usbh_usr.c user template file. Two types of user callbacks are defined:

Callback functions related to the class operations (MSC or HID).

Callback functions independent from class operations. They are mainly called during the enumeration phase. These callbacks are defined in a structure of type

USBH_Usr_cb_TypeDef

. They are generally used to show messages in the different enumeration stage.

MSC user callback functions

For MSC, the following callback is used: USBH_USR_MSC_Application (). After the end of the class initializations, this function is called by the MSC state machine in order to give hand to the user for file system access operations.

In this callback, the user can implement any access to the FAT file system (file open, file read, file write...) using the FAT FS file system API. The user can also have access to a structure variable exported from the library MSC class driver: USBH_MSC_Param.

88/107 Doc ID 18153 Rev 3

UM1021

Note:

USB host library

This variable provides some information about the mass storage key. It is defined using a structure of type MassStorageParameter_TypeDef, as described below: typedef struct __MassStorageParameter

{ uint32_t MSCapacity; /*MS device capacity in bytes */ uint32_t MSSenseKey; /*Request Sense SCSI command returned value */ uint16_t MSPageLength; /* MS device Page length */ uint8_t MSBulkOutEp; /* Bulk OUT endpoint address */ uint8_t MSBulkInEp; /*Bulk IN endpoint address */ uint8_t MSWriteProtect; /*Write protection status, 0: non protected,

1:protected */

} MassStorageParameter_TypeDef;

HID user callback functions

For the HID class, the following callbacks are defined:

●

●

● void USR_MOUSE_Init(void)

: user initialization for mouse application.

void USR_KEYBRD_Init(void)

: user initialization for keyboard application.

● void USR_MOUSE_ProcessData(HID_MOUSE_Data_TypeDef *data)

: this callback is called when an input parameter data of type HID_MOUSE_Data_TypeDef

(see Note below) is available.

void USR_KEYBRD_ProcessData (uint8_t data)

: this callback is called when a new ASCII character is typed. The character is received in input parameter data.

HID_MOUSE_Data_TypeDef is defined as follows:

typedef struct _HID_MOUSE_Data

{ uint8_t x; uint8_t y; uint8_t z; /* Not Supported */ uint8_t button; /*Bitmap showing pressed buttons 1:pressed, 0: non pressed

*/

} HID_MOUSE_Data_TypeDef;

Class-independent callback functions

The class-independent callback functions are defined in a structure of type

USBH_Usr_cb_TypeDef

as follows: typedef struct _USBH_USR_PROP

{ void (*Init)(void); void (*DeviceAttached)(void); void (*ResetDevice)(void); void (*DeviceDisconnected)(void); void (*OverCurrentDetected)(void); void (*DeviceSpeedDetected)(uint8_t DeviceSpeed); void (*DeviceDescAvailable)(void *); void (*DeviceAddressAssigned)(void);

Doc ID 18153 Rev 3 89/107

USB host library

Note:

UM1021

void (*ConfigurationDescAvailable)(USBH_CfgDesc_TypeDef *,

USBH_InterfaceDesc_TypeDef *,

USBH_EpDesc_TypeDef *); void (*ManufacturerString)(void *); void (*ProductString)(void *); void (*SerialNumString)(void *); void (*EnumerationDone)(void);

USBH_USR_Status (*UserInput)(void); int (*USBH_USR_MSC_Application) (void); void (*USBH_USR_DeviceNotSupported)(void); void (*UnrecoveredError)(void);

}

USBH_Usr_cb_TypeDef;

●

●

●

●

●

●

●

●

●

●

●

●

●

●

The above callback functions are described below.

●

Init

: called during initialization by USBH_Init core function. In this function, the user can implement any specific intialization related to his application.

●

DeviceAttached

: called when a USB device is attached. It can be useful to inform the user of any device attachment using a display screen.

DeviceReset

: called after a USB reset is generated from the host.

DeviceDisconnect

: called when a device is disconnected.

OverCurrentDetected

DeviceSpeedDetected

DeviceDescAvailable

: called when an overcurrent is detected on USB VBUS.

: called when the device speed is detected (see note 1).

: called when a device descriptor is available (see note 2).

DeviceAddressAssigned

: called when the device address is assigned.

ConfigurationDescAvailable

: called when configuration, interface and endpoint descriptors are available (see note 3).

ManufacturingString

: called when manufacturing string is extracted.

ProductString

: called when product string is extractcted.

SerialNumString

EnumerationDone

: called when serial num string is extracted.

: called when enumeration is finished.

UserInput

: called after the end of the enumeration process, for prompting the user for further action, such as pressing a button to start a host class operation (see note 4).

USBH_USR_MSC_Application

: called to launch the class application process.

USBH_USR_DeviceNotSupported

: called when the detected device is not supported by the current class driver.

●

UnrecoveredError

: called when the core state machine is in

"HOST_ERROR_STATE" state. It allows the user to handle any error, by displaying an error message on the LCD screen for example.

Device speed information is returned in the DeviceSpeed parameter. Possible values are:

0x1 for Full speed devices and 0x2 for Low speed devices.

Device descriptor information is returned in the pointer DeviceDesc, which points to a

structure of type USBH_DevDesc_TypeDef defined as follows: typedef struct _DeviceDescriptor

{

90/107 Doc ID 18153 Rev 3

UM1021 USB host library

uint8_t bLength; uint8_t bDescriptorType; uint16_t bcdUSB; /* USB Specification Number which device complies too */ uint8_t bDeviceClass; uint8_t bDeviceSubClass; uint8_t bDeviceProtocol; uint8_t bMaxPacketSize; uint16_t idVendor; /* Vendor ID (Assigned by USB Org) */ uint16_t idProduct; /* Product ID (Assigned by Manufacturer) */ uint16_t bcdDevice; /* Device Release Number */ uint8_t iManufacturer; /* Index of Manufacturer String Descriptor */ uint8_t iProduct; /* Index of Product String Descriptor */ uint8_t iSerialNumber; /* Index of Serial Number String Descriptor */ uint8_t bNumConfigurations; /* Number of Possible Configurations */

}

USBH_DevDesc_TypeDef

Device configuration information (config, interface and endpoint descriptors) are returned

with pointers on structures USBH_CfgDesc_TypeDef, USBH_InterfaceDesc_TypeDef

and USBH_EpDesc_TypeDef defined as follows: typedef struct _ConfigurationDescriptor

{ uint8_t bLength; uint8_t bDescriptorType; uint16_t wTotalLength; uint8_t bNumInterfaces; uint8_t bConfigurationValue; uint8_t iConfiguration; uint8_t bmAttributes; uint8_t bMaxPower;

}

USBH_CfgDesc_TypeDef; typedef struct _InterfaceDescriptor

{ uint8_t bLength; uint8_t bDescriptorType; uint8_t bInterfaceNumber; uint8_t bAlternateSetting; /* Value used to select alternative setting */ uint8_t bNumEndpoints; /* Number of Endpoints used for this interface */ uint8_t bInterfaceClass; /* Class Code (Assigned by USB Org) */ uint8_t bInterfaceSubClass; /* Subclass Code (Assigned by USB Org) */ uint8_t bInterfaceProtocol; /* Protocol Code */ uint8_t iInterface; /* Index of String Descriptor Describing this interface

*/

}

Doc ID 18153 Rev 3 91/107