STM32Cube USB host library
Contents
1. 0 2 0 ce eee eee 17 3 4 Core interface with low level driver llle 19 4 USB host library class module 21 4 1 Class implementation model 000c cece eee eee 21 4 2 USB mass storage class MSC 0 000 e eee eee 22 4 2 1 MSC class interface initialization llle 22 4 2 2 MSC control class requests 2 00 00 c eee eee eee 23 4 2 3 MSC class process oogen esee epee hee ave e ee eed wag 23 4 2 4 MSC class specific APIS 0200 0c ee eee eee 24 4 2 5 MSC class typical usage flow 00 cee eee 24 4 3 USB HID mouse and keyboard class HID 000000 25 4 3 1 HID class interface initialization llle 26 4 3 2 HID class requests 0000 e eee eee 26 4 3 3 HID class process 0 0 000s 27 4 3 4 HID specific APIs and event callbacks leues 27 4 3 5 HID class usage flow 0 0 00 cee 28 4 4 USB communication device class CDC 000 0 ee eee 28 2 43 DoclD025799 Rev 3 Ly UM1720 Contents 4 4 1 CDC interface initialization llli 29 4 4 2 CDC class requests 000000 cee eee 29 4 4 3 CDC class process llleellle ns 29 4 4 4 CDC specific APIs and callback functions lessen 29 4 4 5 CDC class usage flow lslsessseele eh 30 4 5 USB audio class sesane rani enak E Ea EER E AE e a E R 30 4 5 12. 0 00 cee es 27 CDC class requests aoed srana i ed raa aaa ete 29 CDC class APIs and callback functions naana anaana 29 Audio class control requests nananana 31 AUdIOClaSS APIS s aa ate E E E a E naan al ON aoe Ee eee 32 MTP APIs and callbacks 0 0000 cece eee 34 USB host library configuration options 0 0 0 0 RI 35 USB Host controller HCD HAL driver callbacks 0000 00 eee eee 40 USBH_LL_Init configuration options 0 00000 c cee eee 40 Document revision history 0 0 00 cece tees 42 d DoclD025799 Rev 3 UM1720 List of figures List of figures Figure 1 STM32Cube USB hostlibrary 0 0 ee eae 6 Figure 2 USB host library architecture 0 e 7 Figure 3 USBH_HandleTypedef 0 0 0 ee hh 13 Figure 4 Device descriptor 0 0 0 tne tae 14 Figure 5 Core state machine 0000 te tees 18 Figure 6 Class structure 0 0 ene 21 Figure 7 BOT state machine 0 tee ae 23 Figure 8 USB MSC class USage 6 eee eee 25 d DoclD025799 Rev 3 5 43 STM32Cube USB Host library overview UM1720 1 STM32Cube USB Host library overview This document describes the STM32Cube USB host library middleware module The USB host library sits on top of the STM32Cube USB host HAL driver This library offers the APIs used to access USB devices of various classes The USB host module can be used for the implemen
3. 36 43 DoclD025799 Rev 3 Ly UM1720 Using the USB host library 5 3 Using the host library in RTOS mode In RTOS mode the application needs to define the USBH_USE_OS in the file usbh conf h When the RTOS mode is used the host core background process runs as a separate RTOS task The communication between the application task and the host core task uses the RTOS message queue mechanism The CMSIS RTOS APIs are used to support the RTOS mode From user point of view using the host library in RTOS mode is almost transparent as the same APIs are used in RTOS or in Standalone mode 5 3 1 Typical operation in RTOS mode d In RTOS mode the user needs to define at least one application and also define an initialization thread for the application and host initialization The following is an extract from the MSC_RTOS mode example of the library The example initializes a user thread and a start thread The start thread initializes the application and the USB host by registering the supported class and by starting the host operation in RTOS mode void main defining a User thread and a Start thread osThreadDef USER_Thread StartThread osPriorityNormal 0 8onfigMINIMAL STACK SIZE osThreadCreate osThread USER Thread NULL for static void StartThread void const argument osEvent event Init MSC Application MSC InitApplication Start Host Library USBH Init amp hUSB
4. UM1720 yf i life augmented User manual STM32Cube USB host library Note May 2015 Introduction STMCube initiative was originated by STMicroelectronics to ease developers life by reducing development efforts time and cost STM32Cube covers STM32 portfolio STM32Cube Version 1 x includes e The STM32CubeMX a graphical software configuration tool that allows to generate C initialization code using graphical wizards e Acomprehensive embedded software platform delivered per series such as STM32CubeF4 for STM32F4 series The STM32Cube HAL an STM32 abstraction layer embedded software ensuring maximized portability across STM32 portfolio A consistent set of middleware components such as RTOS USB TCP IP Graphics All embedded software utilities coming with a full set of examples The Universal Serial Bus USB is known to be the defacto standard for communication between Personal Computer PC as host and connected USB peripherals Today with the increasing number of embedded portable devices USB as a host is no more restricted to PC but it is becoming more present in embedded consumer and industrial devices as embedded host with limited functionality like support of a particular USB class for example Mass storage class virtual comport or particular vendor device This user manual describes the STM32Cube USB Host library which is part of the STM32Cube firmware package that can be downloaded free fro
5. USB host library configuration options The configuration options for the host library are defined in file usbh conf h and described in the following table Table 24 USB host library configuration options Configuration options description USBH MAX NUM ENDPOINTS maximum number of supported endpoints USBH MAX NUM INTERFACES maximum number of supported interfaces USBH MAX NUM CONFIGURATION maximum number of supported configurations USBH MAX NUM SUPPORTED CLASS maximum number of supported classes when defined as 1 all the configuration descriptor USBH KEEP CFG DESCRIPTOR will be kept in memory USBH_MAX_SIZE_CONFIGURATION defines the maximum size of configuration descriptor USBH_MAX_DATA_BUFFER defines the maximum data buffer for data transfer defines the log level 0 no logs USBH_DEBUG_LEVEL 1 user messages logs 2 user and error messages logs 3 user error and debug messages logs when defined as 1 configures host to work in OS USBH_USE_OS mode The usbh conf h file provides also the redefinition for memory management functions used in the library USBH malloc USBH free USBH memset USBH memory Using the host library in standalone mode When using the library in standalone mode a typical main function should contain the following void main Init Host Library USBH Init amp hUSBHost USBH UserProcess 0 Add Supported Cl
6. UM1720 USB host library class module Note 4 5 1 Note 4 5 2 4 5 3 d AUDIO AC CLASS SBH AUDIO InterfaceInit SBH AUDIO InterfaceDeInit SBH AUDIO ClassRequest SBH AUDIO Bgnd Process SBH AUDIO SOF Process SOF process to manage isochronous pipe Note x SBH_AUDIO_Handle a OG d GL d 6G in the V3 0 0 of the STM32 host library the SOF callback is not used for handling the isochronous traffic all handling is done in the background process This is changed starting from V3 1 0 release of the library in order to keep isochronous audio data packets transfered by the SOF process and the background process is used for handling the audio play state machine Audio class interface initialization During the interface initialization up to three pipes can be allocated and opened e One isochronous OUT pipe used to handle the speaker audio data e One isochronous IN pipe used when a microphone is detected this pipe is not used in the current audio class implementation e One interrupt IN pipe used to handle the audio control this host audio class implementation does not handle the feedback pipe for audio synchronization The audio device should support some other synchronization methods Audio class control requests Table 27 lists the audio class control requests that are supported Table 21 Audio class control requests Request Description Audio control SE
7. 43 List of tables UM1720 List of tables Table 1 Table 2 Table 3 Table 4 Table 5 Table 6 Table 7 Table 8 Table 9 Table 10 Table 11 Table 12 Table 13 Table 14 Table 15 Table 16 Table 17 Table 18 Table 19 Table 20 Table 21 Table 22 Table 23 Table 24 Table 25 Table 26 Table 27 4 43 USB host core files 2 d een ER cl ge beer LE Re Mp EIE Sees qu 8 Class drivers files ze is rinsio Tizan eR ldme4 ame Dx pe iare RE MR EE 9 Core APIs for application llllsslllllll ee 11 Core user callbacks events liliis 11 Core APIs dedicated to class handlers 2 000 e cece e eae 12 Host handle structure 0 0 ee ee eee eee es 13 Host device structure 00 20 15 USB ROSE STAUUSS ent derart urhe wane coanee ves Sng wed EE E HIR ROI SNR aE ores ae J 15 Low level interface APIS iios ecto ed eet Peed Sad ee tka os ede eae oe oe E 19 Low level event callback functions liliis 20 Host class handler structure lille 21 Files used for USB MSC implementation 0 00000 eee eee eee 22 USB host mass storage class handlers 2 0 0c e eee eee 23 SCS command Sss gece cose T T 24 MSC class specific APIS liliis 24 Files used for the implementation of the HID class 00000 000 25 HID class requests o ih eta fan Meee tan p tee eee Lae ea pen QS 26 HID APIs and event callbacks
8. 5 4 1 3 Customizing the low interface file usbh_conf c To customize the low level interface file usbh_conf c it is recommended to start from the implementation provided in the examples As a reference example we can take the usbh_conf c file used for the MSC class standalone example running on the STM324xG evaluation board This file is available in the STM32Cube_FW_F4 folder from the following path Projects STM324xG_EVAL Applications USB_Host MSC_Standalone Sre When opening the usbh_conf c file you can find three groups of functions e HCD BSP Routines USB Host controller board support package functions e Low Level Driver Callbacks USB Host controller HAL driver callbacks implementations e LL driver Interface USB host library Low Level interface APIs implementation refer to Table 9 Low level interface APIs USB Host Controller BSP functions The HCD BSP routines include two functions e void HAL HCD Msplnit HCD HandleTypeDef hhcd e void HAL HCD MspDelnit HCD HandleTypeDef hhcd The function HAL HCD Msplnit is used for the following e USB Host controller and GPIO ports clock enable The needed lOs configuration e Configuring and enabling the interrupt for USB Host As seen in file usbh_conf c two implementations of the BSP are available depending on the Full speed FS or High speed HS Host controller The users need to customize the IO configuration according to the pin selection on their har
9. be done using the USBH AUDIO ChangeOutBuffer API function The application audio data buffer size should be calculated based on the two following parameters e Application throughput for filling the audio data buffer for example when reading audio file from SD card e The needed audio sampling rate which gives the number of bytes that need to be sent every 1ms frame AUDIO class APIs Table 22 lists the audio class APIs that are supported Table 22 Audio class APIs API Description USBH AUDIO SetVolume Sets the audio voume USBH AUDIO SetFrequency Sets the sampling frequency USBH AUDIO Play Starts play of audio stream from a data source buffer USBH AUDIO Pause Stops audio stream playing USBH AUDIO Resume Resume Audio stream playing USBH AUDIO ChangeOutBuffer Changes audio stream data source buffer USBH AUDIO GetOutOffset Returns the current read position in audio data source buffer Audio class usage flow Before starting the audio play the application should call the function USBH AUDIO SetFrequency to set the needed sampling frequency for the device optionally it can also set the default play volume by calling the function USBH AUDIO SetVolume Then when a first audio stream data buffer is ready the application can start the audio play by calling the function USBH AUDIO Play The application needs to poll for the current read position in the audio buffer using the function USBH
10. class process function to handle the class background process Core interface with low level driver As mentioned in Section 2 1 the USB host library interfaces with the STM32Cube HAL low layer drivers using a low level interface layer which acts as a glue layer with the STM32Cube HAL The low level interface layer implements the following the USB host library low level interface APIs defined in Table 9 the USB host BSP functions clocks GPIOs interrupts the USB Host HAL driver callback functions that call the USB host library callbacks defined in Table 10 In the STM32Cube solution the implementation of the low level interface is provided as part of the USB host examples as some parts of the low level interface are board and system dependent Table 9 lists the low level API functions Table 9 Low level interface APIs API Description USBH LL Init Low level initialization USBH LL Delnit Low level de initialization USBH LL Start Low level start USBH LL Stop Low level stop USBH LL GetSpeed Allows to get the detected speed of the connected device USBH LL ResetPort Issues a USB reset USBH LL GetLastXferSize Gets the last completed transfer size USBH LL DriverVBUS Enables or disables VBUS DoclD025799 Rev 3 19 43 Host library core module UM1720 Table 9 Low level interface APIs continued API USBH_LL_OpenPipe Description Opens a pipe USBH LL ClosePipe Closes a p
11. device As shown in figure below the interface between the FATFS filesystem and the USB host MSC class is done through a diskio interface When not using FATFS you can easily interface your own file system to host the MSC library by writing a diskio driver similar to the one provided in the STM32Cube host library MSC examples for FATFS You can refer to the file usbh diskio c in USB Host MSC Standalone or MSC RTOS example to see implementation of the diskio interface 3 DoclD025799 Rev 3 UM1720 USB host library class module Note 4 3 d Figure 8 USB MSC class usage f mount f read f write disk read disk write USB Host DISKIO Interface USBH MSC Write USBH MSC Read USB HOST MSC Class MSv34974V1 in the standalone diskio driver implementation the disk acess function disk read disk write are blocking function that exit only after end of disk read or write operation or on a timeout For the RTOS diskio driver implementation MSC class APIs USBH MSC Wvrrite and USBH MSC Read functions are blocked when the bulk data transfer is on going to allow other tasks to run while the hardware access is on going USB HID mouse and keyboard class HID The HID class is used to access the mouse and keyboard devices using the boot protocol The class offers also generic HID APIs allowing to customize the class to handle other HID devices The HID class is imple
12. e Device connection disconnection management and standard enumeration e Host pipes control and USB transfer management control interrupt bulk isochronous The core block can be schematically subdivided into two main sub blocks e The core APIs which are called from the user application or from a class driver e The core process which handles the host state machine The class drivers are used for the implementation of the various USB classes DoclD025799 Rev 3 7 43 USB host library architecture and file organization UM1720 A class driver can be seen as the following e A set of class specific APIs for example disk read disk write which can be called from an application layer e A class handler which is called from the core host state machine Core Process to handle the class operation class initialization class de initialization class process Both the host core and the class drivers call user callback functions following some defined events for example device connection disconnection data reception The USB host library interfaces with the STM32Cube HAL drivers using an interface layer A template file implementing the low level interface layer is provided in the library The user can customize the sections in the file that are related to board support package requirements 2 2 USB host library file organization 2 2 1 USB host core files The USB host core files are located in the Core folder STM32_USB_
13. events Table 4 Core user callbacks events HOST USER CONNECT HOST USER DISCONNECT Informs the application about a device disconnection Core user callback event Description Informs the application about a device connection HOST USER CLASS ACTIVE Informs the application about the end of class initialization process HOST USER SET CONFIGURATION Informs the application about end of the device standard enumeration d HOST USER CLASS SELECTED Informs than a supported class is found DoclD025799 Rev 3 11 43 Host library core module UM1720 3 2 3 3 2 4 12 43 Core APIs for class handlers The core APIs dedicated to class handlers are classified as follows e Orequests APIs e Pipe control APIs e Standard class control requests APIs e Interface utility APIs Table 5 lists the core APIs dedicated to class handlers Table 5 Core APIs dedicated to class handlers Function USBH BulkReceiveData USBH BulkSendData USBH CtlReceiveData USBH CtlSendData USBH CtlSendSetup USBH InterruptReceiveData USBH InterruptSendData USBH_IsocReceiveData USBH IsocSendData USBH OpenPipe USBH ClosePipe USBH AllocPipe USBH FreePipe Category IO requests Pipe control Description Receives data on bulk pipe Sends data on bulk pipe Receives data on control pipe Sends data on control endpoint Issues a control
14. AUDIO GetOutOffset When a defined offset is reached the application needs to provide a new audio databuffer that will be used by the audio class when the end of the current buffer user for play is reached The function to be called to allocate this new buffer is USBH AUDIO ChangeOutBuffer 3 DoclD025799 Rev 3 UM1720 USB host library class module 4 6 USB Media Transport Protocol class MTP The Media Transport Protocol class is widely used in portable devices like Android smartphones This protocol is similar to the mass storage class as it allows access to media files for example audio and pictures with the difference that media in the device is not seen as a file system but as a set of objects that can be accessed in transactional way for example get object or delete object operations and not as file system with sectors read write access The MTP protocol comes as an extension to PTP Picture Transfer Protocol which is defined in ISO 15740 specification More details about the MTP protocol can be found in the USB IF MTP class specification document Media Transfer Protocol rev 1 1 The MTP class is implemented in the two files usbh mtp c h and usbh mtp ptp c h it uses the following class handler USBH ClassTypeDef MTP Class MTP USB_MTP_CLASS USBH MTP InterfaceInit USBH MTP InterfaceDeInit USBH MTP ClassRequest USBH MTP Process USBH MTP SOFProcess USBH MTP Handle 4 6 1 MTP interface init
15. Audio class interface initialization nanana anaa 31 4 5 2 Audio class control requests 00000 e eee eee 31 4 5 3 AUDIO class process 00 000 eee 31 4 5 4 AUDIO class APIS 5 5252 3 ocio ex OLOR ea eae eee 32 4 5 5 Audio class usage flow 0 eae 32 4 6 USB Media Transport Protocol class MTP 00000 eee 33 4 6 1 MTP interface initialization llle 33 4 6 2 MTP class control requests 200 00 cece eee eee eee 33 4 6 3 MTP class process eee ras 33 4 6 4 MTP user application APIs and callbacks 34 4 6 5 MTP class usage flow 0 0c een 34 5 Using the USB host library 00002 ee 35 5 1 USB host library configuration options 000 c eee eee 35 5 2 Using the host library in standalone mode 0000 eee 39 5 3 Using the host library in RTOS mode 000 0 eee eee eee 37 5 3 1 Typical operation in RTOS mode 200000 eee eee 37 5 4 Customizing the low interface file usbh_conf c 39 5 4 1 USB Host Controller BSP functions 0 0 005 39 5 4 2 USB Host controller HAL driver callbacks 05 40 5 4 3 USB host library low level interface APIS 000 eae 40 5 5 EAGS sis fiancee eo cited aad uL M tere pees ae 41 6 REVISION history lt 2 6sdeesne sows coset i a aE E N E E a A 42 Ky DoclD025799 Rev 3 3
16. BH_CfgDescTypeDef CfgDesc USBH_DeviceTypeDef Table 7 lists the members of the host device structure d DoclD025799 Rev 3 UM1720 Host library core module d Table 7 Host device structure Structure member Description CfgDesc Raw Full device configuration descriptor Data Data buffer allocated to receive the descriptors Address Device address Speed Device speed low full high speed is connected Device connection status current interface Current selected interface DevDesc Structure with device descriptor data CfgDesc Structure with configuration descriptor data only the first 9 bytes of the configuration descriptor Main enumerated typedefs USBH StatusTypeDef Almost all library functions return a status of the type USBH StatusTypeDef The application should always check the returned status typedef enum USBH_OK 0 USBH_BUSY USBH_FAIL USBH_NOT_SUPPORTED USBH_UNRECOVERED_ERROR USBH_ERROR_SPEED_UNKNOWN JUSBH StatusTypeDef Table 8 describes the above mentioned returned status Table 8 USB host status Status Description USBH OK Returned when the operation is completed successfully USBH BUSY Retuned when the operation is still not completed busy USBH FAIL Returned when the operation has failed due to a low level error or protocol fail USBH NOT SUPPORTED Returned when the requested operation f
17. Function Description USBH_CDC_TransmitCallback Callback for data transmitted event USBH_CDC_ReceiveCallback Callback for data received event The line coding data is managed in a structure of the type CDC_LineCoding TypeDef defined as follows typedef union _CDC_LineCodingStructure uint8 t Array LINE CODING STRUCTURE SIZE uw struct uint32_t dwDTERate Data terminal rate in bits per second uint8_t bCharFormat Stop bits 0 1 Stop bit 1 1 5 Stop bits 2 2 Stop bits uint8 t bParityType Parity 0 None 1 odd 2 Even 3 Mark 4 Space uint8 t bDataBits Data bits 5 6 7 8 or 16 1b CDC LineCodingTypeDef CDC class usage flow When using the CDC class the application needs first to set the coding line parameters for virtual comport device through the function USBH CDC SETLineCoding Then the application can start to send or receive data using API functions USBH CDC Transmit USBH CDC Receive These functions are non blocking functions End or transmit or receive operation is notified by using the callback functions USBH CDC TransmitCallback USBH CDC TransmitCallback USB audio class The USB audio class can be used to access a USB speaker device that is compliant with the USB Audio class 1 0 specification The USB Audio class is implemented in class file usbh audio c h using the following class handler USBH ClassTypeDef AUDIO Class 3 DocID025799 Rev 3
18. G DESC get product string descriptor IUM GET SERIALNUM STRING DESC get serial number string descriptor ENUM StateTypeDef B Ca Exi z CTRL StateTypeDef This enumerated typedef lists the states during a control transfer typedef enum CTRL IDLE 0 CTRL SETUP issue setup packet CTRL SETUP WAIT wait setup ACK 16 43 DoclD025799 Rev 3 d UM1720 Host library core module CTRL_DATA_IN start a data stage IN CTRL DATA IN WAIT wait data IN stage complete CTRL DATA OUT start a data stage OUT CTRL DATA OUT WAIT wait data OUT stage complete CTRL STATUS IN start status IN stage CTRL STATUS IN WAIT wait status IN stage complete CTRL STATUS OUT start status OUT stage CTRL STATUS OUT WAIT wait status OUT stage complete CTRL ERROR control error CTRL STALLED request stalled CTRL COMPLETE full transfer complete JCTRL StateTypeDef 3 3 Overview of the core state machine Figure 5 presents an overview of the core state machine The state machine is handled in the core function USBH Process which can be called in the main polling loop in standalone mode or in RTOS task d DoclD025799 Rev 3 17 43 Host library core module UM1720 Figure 5 Core state machine Host startup or Device Disconnection HO
19. Host USBH UserProcess 0 Add Supported Class USBH RegisterClass amp hUSBHost USBH MSC CLASS Start Host Process as task since USBH USE OS 1 USBH Start amp hUSBHost DoclD025799 Rev 3 37 43 Using the USB host library UM1720 for event osMessageGet AppliEvent osWaitForever if event status osEventMessage switch event value v case APPLICATION_DISCONNECT Appli_state APPLICATION_DISCONNECT break case APPLICATION_READY Appli state APPLICATION READY default break As seen in the above extracted code the Start thread first initializes first the application then it initializes the host as in standalone mode and finally it blocks the waiting for USB application events Application Disconnect Application Ready These events are notified using the host user process callback function which should be implemented as shown hereafter static void USBH UserProcess USBH HandleTypeDef phost uint8 t id switch id case HOST_USER_DISCONNECTION osMessagePut AppliEvent APPLICATION DISCONNECT 0 break case HOST USER CLASS ACTIVE osMessagePut AppliEvent APPLICATION READY 0 break default break j Note as shown in the USBH UserProcess function the message queue mechanism is used to notify the Start thread of USB events 38 43 DoclD025799 Rev 3 Ly UM1720 Using the USB host library 5 4
20. Host_Library Core Table 1 lists the core files Table 1 USB host core files File Description Main host core file Implements the host state machine Manages the device detection and enumeration and handles control to class module for class operation usbh core c h usbh ctlreq c h Implements the standard control requests USB chapter9 APIs for USB transfer management control bulk interrupt usbh ioreq c h isochronous usbh pipes c h APIs for pipe control for example allocate open close Template file for the low layer interface file should be customized by Bs bh een template Ge user and included with application file see details in section 5 x usbh_def h Common library defines d 8 43 DoclD025799 Rev 3 UM1720 USB host library architecture and file organization 2 2 2 d USB host class files Table 2 lists the class files they are located in the C ass folder STM32 USB Host LibraryXCore Table 2 Class drivers files USB class Mass Storage File usbh msc c Description Mass storage class handler usbh msc bot c Bulk Only Transfer BOT protocol usbh msc scsi c SCSI commands HID mouse amp keyboard usbh hid c HID class state handler usbh hid parser c HID descriptor parser usbh hid mouse c HID mouse subclass handler usbh hid keybd c HID Keyboard subclass handler usbh hid usage h Common defin
21. MTP GetObjectHandles returns an array contaings handlers of the objects in a storage unit USBH MTP GetObjectlnfo Gets an object infos USBH MTP DeleteObject Deteles an object USBH MTP GetObject Gets an object USBH MTP GetPartialObject Gets a part of an object USBH MTP GetObjectPropsSupported Checks supported object properties USBH MTP GetObjectPropDesc Gets object properties USBH MTP SendObject Sends an object to MTP device USBH MTP GetDevicePropDesc Gets device properties description data set USBH MTP EventsCallback User callback for MTP event notification 4 6 5 MTP class usage flow Before accessing the MTP device the application needs to check that the session with the device is correctly opened using the API function USBH_MTP_IsReady If it is the case the application can then start to check for objects with specific format for example WAV objects This can be done by using the function USBH_MTP_GetNumObjects to check the number of available objects with specific format The handling of these objects can be retrieved by using the function USBH_MTP_GetObjectHandles To read the object information for example object filename the application needs to call the function USBH_MTP_GetObjectinfo Finally the application can start the access to the MTP object by using the APIs USBH MTP GetPartialObject or USBH MTP GetObject 34 43 DoclD025799 Rev 3 Ly UM1720 Using the USB host library 5 5 1 5 2 d Using the USB host library
22. RTED_CL ASS Description Array assigned with pointers to the registered class handlers structures pActiveClass Points to the active class handler structure ClassNumber Gives the total count of registered classes Maintains the status for each host pipe allocated or free Indicates also Pipes 15 the associated endpoint number if any Timer Counting variable for time management Automatically incremented at each start of frame Pointer initialized with low level host controller data structure in the pData usbh_conf c configuration file allows the interfacing of the library with the low level driver pUser struct _USBH_HandleTypeDe f pHandle uint8 t id Host user event callback function The members under the define USBH USE OS shown in Figure 3 are related to operation with RTOS They maintain the internal information regarding RTOS message queue events Host core device structure The host core device structure maintains the informations regarding the connected device This structure is of the type USBH DeviceTypeDef which is declared as shown in Figure 4 Figure 4 Device descriptor typedef struct if USBH KEEP CFG DESCRIPTOR 1 uint8_t CfgDesc Raw USBH MAX SIZE CONFIGURATION endif uint8_t Data USBH_MAX DATA BUFFER uint8_t address uint8 t speed uint8_t is_connected uint8_t current_interface USBH_DevDescTypeDef DevDesc US
23. ST_IDLE Device connection HOST_DEV_WAIT_FOR_ATTACHMENT Device attached HOST_ENUMERATION Device enumerated HOST_SET_CONFIGURATION Device configured default config HOST_CHECK_CLASS HOST_CLASS_ABORT Class supported p Class Initialized HOST CLASS REQUEST Initialialization class requests issued HOST_CLASS MSv34369V1 d 18 43 DoclD025799 Rev 3 UM1720 Host library core module 3 4 d The various states are described hereafter HOST DLE entered after host start up or when the device is disconnected HOST DEV WAIT FOR ATTACHMENT entered when the device is connected While in this state the host handles the attachment process of the device HOST ENUMERATION entered when the device attachment is finished In this state the host runs a standard enumeration of the device HOST SET CONFIGURATION in this state a Set Config request is issued to select the default configuration HOST CHECK CLASS this state checks if one of the registered classes is supported by the enumerated device HOST CLASS ABORT this state is entered when the enumerated device class is not supported HOST CLASS REQUEST the host enters in this state after initialization of the class interfaces In this state the host issues the required class control requests HOST CLASS in this state the host calls the
24. T request CUR Issued by the audio process state machine to set the volume MAX MIN RES control information Audio control GET request CUR Issued during the HOST CLASS REQUEST state to get MAX MIN REST volume control information Max Min Resolution Audio set sampling frequency Issued by the Audio class process to set the audio sampling frequency before audio play AUDIO class process The Audio class process is handled by both the background process and the SOF process The SOF process is used for isochronous audio data transfer and the background process is used to handle a state machine for audio play and audio volume control The user application needs to call USBH AUDIO Play to start an audio buffer play this function provides the audio data buffer pointer from which out streaming starts and it DoclD025799 Rev 3 31 43 USB host library class module UM1720 4 5 4 4 5 5 32 43 changes the background process state machine to AUDIO_PLAYBACK_PLAY state for the audio play operation After starting the play process it is up to the user application to poll for the current read position in the audio data buffer This is done by using USBH AUDIO GetOutOffset API function If the current buffer read position returned by USBH AUDIO GetOutOffset reaches a defined threshold the user application needs to assign a new data buffer that is used later by the audio play process when the current buffer end is reached This can
25. application layer e A set of event callbacks when applicable e Aclass handler implemented using a structure of the type USBH ClassTypedef The structure member functions are invoked by the USB core process Figure 6 shows the definition of the USBH_ClassTypedef Figure 6 Class structure phost void uint8 t typedef struct StatusTypeDef _StatusTypeDef _StatusTypeDef _StatusTypeDef USBH_StatusTypeDef USBH ClassTypeDef Name ClassCode Init struct USBH HandleTypeDef phost DeInit struct USBH HandleTypeDef phost Requests struct USBH HandleTypeDef phost BgndProcess struct USBH HandleTypeDef SOFProcess struct USBH HandleTypeDef pData Table 11 lists the members of the class handler structure Table 11 Host class handler structure Structure member Description Name Class name ClassCode USB class code Init Class interface Init initializes the pipes needed for handling the class Called during the core HOST CHECK CLASS D Class interface Delnit de initializes the interface Called during the device Deinit i disconnection or when performing a host stop Requests Class control requests state machine for handling class requests called q during class initialization in host core state HOST_CLASS_REQUEST Ba dProc ss Class operation background process Called from the core state machine 9 during HOST_CLASS sta
26. ass example HID class USBH RegisterClass amp hUSBHost USBH HID CLASS Start Host Process DoclD025799 Rev 3 35 43 Using the USB host library UM1720 USBH_Start amp hUSBHost Application main loop while 1 Application background process Application Process USB Host process should be called in the main loop to handle host stack USBH Process The USBH UserProcess callback handles theUSB host core events for example disconnection connection class active Typically it should be implemented as shown hereafter to handle application process state machine void USBH UserProcess USBH HandleTypeDef phost uint8 t id switch id case HOST_USER_DISCONNECTION Appli_state APPLICATION_DISCONNECT break when HOST USER CLASS ACTIVE event is received application can start communication with device case HOST USER CLASS ACTIVE Appli state APPLICATION READY break case HOST USER CONNECTION Appli state APPLICATION START break default break j Please note that the application can register multiple classes for example Add Supported Class example HID and MSC classes USBH RegisterClass amp hUSBHost USBH HID CLASS USBH RegisterClass amp hUSBHost USBH MSC CLASS The user application can determine the enumerated class using core API function USBH GetActiveClass when HOST USER CLASS ACTIVE event occurs
27. dware For example different alternate functions remapping options are available for ULPI DIR line In addition to configuring the USB IOs the users may need to configure one GPIO pin to be able to drive a charge pump IC for VBUS voltage generation See in the example usbh_conf c file where for FS controller the pin PH5 was configured as output push pull to be used for charge pump IC driving For the HS controller no pin is used since the charge pump IC control is done by the PHY DoclD025799 Rev 3 39 43 Using the USB host library UM1720 5 4 2 5 4 3 40 43 USB Host controller HAL driver callbacks The USB Host controller HCD HAL driver implemented callbacks are listed in the following table Table 25 USB Host controller HCD HAL driver callbacks USB Host HAL driver callback Description called by host driver on SOF event it calls host library HAL HCD SOF Callback callback USBH LL IncTimer for USB classes using interrupt and isochronous pipes this callback should call also USBH_LL_SOF host library callback function called by host driver on Connect event it calls host library HAL HCD Connect Callback callback USBH LL Connect called by host driver on disconnect event it calls host library HAL HCD Disconnect Callback callback USBH LL Disconnect Please use the above callback functions as is and do not modify them USB host library low level interface APIs This group of func
28. e bulk pipe IN and one bulk pipe OUT for CDC ACM data transfer e onelnterrupt IN pipe for CDC ACM event notification not used in current CDC class implementation 4 4 2 CDC class requests Table 19 lists the CDC class requests that are issued Table 19 CDC class requests Class request Description Gets the current coding line parameters Issued in Get coding line HOST CLASS REQUEST state Sets the line coding parameters par example baud rate parity stop bit set ceding ine Issued in HOST CLASS state 4 4 3 CDC class process The CDC class background process handles the data reception and transmission on the bulk pipes The application is informed of the operation completion by using the callback functions The USBH CDC Handle stucture maintains internally the variables used during the data transfer This allows a multi instance usage of the CDC class handler 4 4 4 CDC specific APIs and callback functions The APIs listed in Table 20 are used to handle the CDC class Table 20 CDC class APIs and callback functions Function Description USBH CDOC GetLineCoding Gets the current line coding USBH CDC SETLineCoding Sets the current line coding USBH CDC Transmit Transmits data USBH CDC Receive Receives data Ky DoclD025799 Rev 3 29 43 USB host library class module UM1720 4 4 5 4 5 30 43 Table 20 CDC class APIs and callback functions continued
29. eature is not supported USBH UNRECOVERED ERROR Returned when the host process cannot self recover from a error USBH ERROR SPEED UNKNOW N Returned after a device attachment to inform the application that the device speed cannot be detected DoclD025799 Rev 3 15 43 Host library core module UM1720 The following enumerated typedefs are used internally by the USB core However the user can access these through the host handle structure for debug purpose HOST_StateTypeDef This enumerated typedef lists the possible host core states see host state machine in Section 3 3 typedef enum OST_IDLE 0 OST_DEV_ATTACHED OST_DEV_DISCONNECTED OST DETECT DEVICE SPEI OST ENUMERATION H H H H H HOST CLASS REQUEST H H H H H Ei s OST INPUT OST SET CONFIGURATION OST CHECK CLASS OST CLASS OST SUSPENDED HOST ABORT STATE JHOST StateTypeDef ENUM StateTypeDef This enumerated typedef lists the states during device enumeration process typedef enum E IM IDLE O0 ENUM_GET_FULL_DEV_DESC get device descriptor ENUM_SET_ADDR set device address ENUM_GET_CFG_DESC get configuration descriptor first 9 bytes ENUM_GET_FULL_CFG_DESC get full configuration descriptor B C M GET MFC STRING DESC get manufacturer string descriptor IM GET PRODUCT STRIN
30. es for HID Audio speaker CDC virtual com port usbh audio c usbh cdc c Audio class handler CDC virtual comport handler MTP class usbh mtp c MTP class handler usbh mtp ptp MTP class PTP spec implementation DoclD025799 Rev 3 9 43 Host library core module UM1720 3 Host library core module 3 1 Core features The USB host core has the following main features Device attachment management and enumeration independently from the device class State machine based runs in the main loop in background or as an RTOS task thread Use of user event callbacks to inform application layer about host events such as device connection disconnection error state User event log that can be redirected to any interface for example serial port LCD Error management and reporting 3 2 Core APIs user callbacks and data structures As detailed in Section 2 1 USB host library architecture the core APIs can be used by both the application and the class drivers The following sections present each core API For more details please refer to function header in the C code The main APIs usage is further detailed in Chapter 5 10 43 3 DoclD025799 Rev 3 UM1720 Host library core module 3 2 1 Core APIs for application The user application APIs are listed in Table 3 Table 3 Core APIs for application Function Description i Initializes the host stack and the low level Shou
31. evision history Table 27 Document revision history Date Revision Changes 21 May 2014 1 Initial release 05 Feb 2015 2 Updated Section Introduction 27 May 2015 3 Section Introduction updated and merged with section STM32Cube overview DoclD025799 Rev 3 d UM1720 IMPORTANT NOTICE PLEASE READ CAREFULLY STMicroelectronics NV and its subsidiaries ST reserve the right to make changes corrections enhancements modifications and improvements to ST products and or to this document at any time without notice Purchasers should obtain the latest relevant information on ST products before placing orders ST products are sold pursuant to ST s terms and conditions of sale in place at the time of order acknowledgement Purchasers are solely responsible for the choice selection and use of ST products and ST assumes no liability for application assistance or the design of Purchasers products No license express or implied to any intellectual property right is granted by ST herein Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product ST and the ST logo are trademarks of ST All other product or service names are the property of their respective owners Information in this document supersedes and replaces information previously supplied in any prior versions of this document 2015 STMicroelectronic
32. face initialization During the MSC class interface initialization two bulk pipes are created one bulk IN and one bulk OUT for handling BOT protocol d DoclD025799 Rev 3 UM1720 USB host library class module 4 2 2 MSC control class requests Table 13 lists the implemented class requests Table 13 USB host mass storage class handlers Class request Description Issued to get the number of supported logical units This command is Get_Max_LUN issued during the class initialization in the HOST CLASS REQUEST state BOT Reset This class request is issued in case of BOT error in HOST CLASS state 4 2 3 MSC class process The MSC class process handles the issuing of the SCSI commands to get the information about each supported logical unit and to process the disk read write operations The SCSI commands use the Bulk Only Transport BOT protocol which implements the three stages of the state machine command data and status Figure 7 Figure 7 BOT state machine ES Ready Command Transport CBW DATA OUT DATA IN from host To Host i __ Command Status CSW MS34370V1 For more details about the BOT you can refer to the specification available on the website http www usb org 3 DoclD025799 Rev 3 23 43 USB host library class module UM1720 4 2 4 4 2 5 24 43 Table 14 provides the li
33. ialization The MTP class intializes three channels e one Bulk IN channel for MTP data IN transfer e one Bulk OUT channel for MTP data OUT transfer e one Interrupt IN channel for MTP events notification 4 6 2 MTP class control requests The MTP class does not implement any class specific control requests 4 6 3 MTP class process 3 The MTP class is handled by a background process and the SOF process The background process handles the opening of a session with MTP device then it acquires the device information and storage unit information The SOF process handles the interrupt IN channel to get the MTP device event notifications After opening a session with device all subsequent operations are done using the MTP user application APIs which are blocking APIs for example USBH_MTP_GetObjectlnfo USBH MTP GetObject DoclD025799 Rev 3 33 43 USB host library class module UM1720 4 6 4 MTP user application APIs and callbacks The following table lists the APIs and callbacks offered by MTP class Table 23 MTP APIs and callbacks API Description USBH_MTP_IsReady checks if MTP device is ready session opened USBH_MTP_GetNumStorage gets number of storage units in MTP device USBH MTP SelectStorage selects a particular storage unit USBH MTP GetStoragelnfo gets storage unit infos USBH MTP GetNumObjects gets number of objects with particular object format in a storage unit USBH
34. ing HOST_CLASS_REQUEST state Set Protocol Sets the HID protocol to boot protocol for the mouse and HID Issued during HOST_CLASS_REQUEST state d DoclD025799 Rev 3 UM1720 USB host library class module 4 3 3 4 3 4 d HID class process The handling of the boot mouse keyboard is done through the HID report reception using the interrupt IN pipe The boot mouse keyboard handling is assured by two processes the background process and the SOF process e The SOF process handles the issuing of IN transactions synchronized with SOF event e The background process handles the data reception and informs the application layer through a data reception callback function A HID handle structure USBH HID Handle is used internally to keep the process variables HID specific APIs and event callbacks Table 18 lists the APIs and event callbacks defined in the HID class Some APIs are not used to handle the boot mouse keyboard but they are provided in case the user wants to customize the HID class for another usage than mouse keyboard Table 18 HID APIs and event callbacks API USBH HID GetReport USBH HID SetReport Description Gets report data through control channel not used in case of HID boot mouse keyboard Sends report data through control channel not used in case of HID boot mouse keyboard USBH HID Setldle Sets HID polling period USBH HID EventCallback Applicatio
35. ipe USBH LL SubmitURB Submits a host transfer request USBH LL GetURBState Gets the state of a pipe USBH LL SetToggle Sets the initial data toggle for transfer DATAO or DATA1 USBH LL GetToggle Get the data toggle information Table 10 presents the host library callback functions which are called from the low level interface following some USB events Table 10 Low level event callback functions Callback functions USBH LL SetTimer Description Should be called by the USB Host HAL driver during USB Host start up to initialize the host timer USBH LL IncTimer USBH LL SOF Should be called each SOF event to increment the host timer variable Should be called in HAL SOF event callback to handle the USB class processing which should be synchronized with SOF USBH LL Connect Should be called on the USB Host HAL event callback for device connection USBH LL Disconnect USBH LL NotifyURBChange Should be called on the USB Host HAL event callback for device disconnection When using RTOS mode this callback function should be called in USB Host HAL event callback for URB state change 20 43 DoclD025799 Rev 3 d UM1720 USB host library class module 4 4 1 d USB host library class module Class implementation model A class driver is defined as a combination of the following e Asetofclass specific APIs that can be called from the
36. ld be called at USBH Init OAM application startup USBH Delnit Re initializes the host stack variables and runs a low level clean up for example closes all open pipes clears interrupt flags USBH RegisterClass Registers a supported USB class handler After enumeration the host checks if the current device class corresponds to the one of the registered classes USB ReEnumerate Initiates a device re enumeration by re initializing the host stack and by forcing a device VBUS disconnection connection USBH Start Enables the host port VBUS power and starts the low level operation USBH Stop Disables the host port VBUS power and stops the low level operation USBH_GetActiveClass Returns the current active USB class following the device enumeration and class level initialization USBH_Process Host process function that implements the core state machine in standalone mode operation This function should be called in background in the main loop to handle the host state machine 3 2 2 Core user callbacks The host core communicates the USB events to the application layer by calling a user callback function This function is passed as parameter when calling the USBH_Init API The user callback function should be of the following prototype void pUsrFunc USBH HandleTypeDef phost uint8 t event The core user callbacks events are set as event parameter Table 4 describes the core user callback
37. m ST website http www st com stm32cube It allows using an STM32 microcontroller as an USB embedded host for communication with USB peripherals of various USB classes MSC HID CDC Audio and MTP This document is applicable to all STM32 series that feature an USB OTG peripheral However for simplicity reason the STM32F4xx microcontrollers and STM32CubeF4 are used as reference platform To know more about the examples implementation on your STM32 device refer to the readme file provided within the associated STM32Cube firmware package G T DoclD025799 Rev 3 1 43 www st com Contents UM1720 Contents 1 STM32Cube USB Host library overview lesse 6 2 USB host library architecture and file organization 7 2 1 USB host library architecture 0 0 0 ee 7 2 2 USB host library file organization liliis 8 2 2 1 USB host core fileS 52 c05000 4 eiue RR le eee 8 2 2 2 USB host class files ee 9 3 Host library core module 2 00 cece ee eee 10 3 1 Core TeglureS iussa OR RU ee been RON RCR e eee eRe KEES A 10 3 2 Core APIs user callbacks and data structures 10 3 2 1 Core APIs for application lille 11 3 2 2 Core user callbacks llseesle ee 11 3 2 3 Core APIs for class handlers 000 ce eee eee 12 3 2 4 Main host core data structures and enumerated typedefs 12 3 3 Overview of the core state machine
38. mented using the files described in Table 16 Table 16 Files used for the implementation of the HID class File Description usbh hid c Implements the HID class usbh hid parser c HID descriptor and report parsing functions usbh hid mouse c HID mouse specific functions usbh hid keybd c HID keyboard specific functions usbh hid usage h Common defines for HID class The HID class handler is implemented using a structure of type USBH ClassTypeDef which is defined as follows DoclD025799 Rev 3 25 43 USB host library class module UM1720 4 3 1 4 3 2 26 43 USBH ClassTypeDef HID Class SOF process to handle Interrupt pipe HID USB HID CLASS USBH HID InterfaceInit USBH HID InterfaceDeInit USBH HID ClassRequest USBH HID BgndProcess USBH HID SOF Process USBH HID Handle Handle structure to maintain HID background process variable HID class interface initialization During interface initialization and depending on the device endpoint descriptors one interrupt IN endpoint and or one interrupt OUT endpoint are allocated and opened For boot mouse and keyboards only the interrupt IN pipe is used HID class requests The control class requests issued in the HID mouse keyboard class are described in Table 17 Table 17 HID class requests Class request Set Idle Description Sets the HID mouse keyboard polling period Issued dur
39. n event callback called when the mouse or keyboard HID report data is received on IN interrupt pipe USBH HID SetProtocol USBH HID GetHIDDescriptor Issues a Set Protocol control request Gets the HID descriptor USBH HID GetHIDReportDescriptor Gets the HID report descriptor not used for boot mouse keyboard USBH HID GetDeviceType Returns the HID device type mouse of keyboard USBH HID GetMouselnfo USBH HID GetKeybdlnfo Gets the mouse report data in the structure of type HID MOUSE Info TypeDef see below Gets keyboard report data in the structure of type HID KEYBD Info TypeDef see below USBH HID GetASCIICode Converts the keyboard key to ASCII code DoclD025799 Rev 3 27 43 USB host library class module UM1720 4 3 5 4 4 28 43 Below are the structures used for the mouse and the keyboard report data respectively typedef struct _HID_MOUSE_Info int8_t x int8_t y uint8 t buttons 3 HID MOUSE Info TypeDef typedef struct uint8 t lctrl left control uint8 t lshift left shift uint8 t lalt left alt uint8 t lgui left alt graph uint8 t rctrl right control uint8 t rshift right shift uint8 t ralt right alt uint8 t rgui right alt graph uint8 t keys KBR MAX NBR PRESSED array of keyboard keys pressed simulataneously HID KEYBD Info TypeDef HID class usage flow Whe
40. n interfacing to a HID mouse or keyboard device the application can get the HID mouse or keyboard report data by periodically polling for HID reports using USBH HID GetKeybdlnfo or USBH HID GetMouselnfo these APIs allow to read HID report from a dedicated software FIFO memory The application can also use HID class callback function USBH HID EventCallback to get notified in a synchronous way for HID report reception For custom HID devices other than boot mouse keyboard the application can use the USBH HID SetReport or USBH HID GetReport to send or get HID report through the control pipe USB communication device class CDC The CDC class implementation is used to access the CDC virtual comport devices compliant with the Abstract Control Model ACM subclass The CDC class is implemented in the class file usbh cdc c h This file defines the CDC class handler and the class specific API The CDC class handler is of the type USBH ClassTypeDef defined as follows USBH ClassTypeDef CDC Class CDC d DoclD025799 Rev 3 UM1720 USB host library class module SB_CDC_CLASS SBH CDC InterfaceInit U U USBH CDC InterfaceDeInit USBH CDC ClassRequest U SBH_CDC_BgndProcess NULL USBH_CDC_Handle CDC handle to maintain process variable 4 4 1 CDC interface initialization During the class initialization the CDC ACM class interface allocates and opens three pipes e two bulk pipes on
41. request Receives data from the interrupt pipe Sends data to the interrupt pipe Receives data from the isochronous pipe Sends data to the isochronous pipe Opens a pipe Closes a pipe Allocates a new pipe Sets free an allocated pipe USBH GetDescriptor USBH Setlnterface USBH Findlnterface USBH Findlnterfacelndex Standard control requests Interface utility Generic function to get a descriptor Standard control request to set alternate setting value for an interface Parses a configuration descriptor to find an interface descriptor corresponding to a specific class subclass and protocol Parses a configuration descriptor to find the index of an interface descriptor with a particular interface number and alternate setting value Main host core data structures and enumerated typedefs The data structures and enumeration types of the core are defined in the file usbh def h The main data structures are the following e the core handle structure of the type USBH_HandleTypedef e the device handle structure of the type USBH Device Typedef e the class handle structure of the type USBH ClassTypedef DoclD025799 Rev 3 d UM1720 Host library core module 3 The core handle and the device handle structure are detailed in the following sub sections The class handle structure will be detailed in the class section of Chapter 4 Host core handle struct
42. s All rights reserved d DoclD025799 Rev 3 43 43
43. st of supported SCSI commands Table 14 SCSI commands SCSI command Description TestUnitReady Tests if media is ready ReadCapacity10 Reads the media capacity indui Gets some information about the mass storage device for example quiry vendor version RequestSense Used to get error information Writes a data block defined by a number of sectors and a start sector Write 10 address Reads a data block defined by a number of sectors and a start sector Read10 address MSC class specific APIs The MSC class offers the following class specific APIs which are called by a file system interface like the FATFS diskio interface in STM32Cube Table 15 MSC class specific APIs API Description Reads a number of sectors from a logical unit this function blocks Deer Niet Reed until the operation ends Writes a number of sectors in a logical unit this function blocks until the operation ends USBH_MSC_GetMaxLUN _ Gets the number of logical units LUNs USBH_MSC_Write Returns a data structure filled with information about a logical unit for USBH_MSC_GetLUNInfo example the capacity USBH MSC IsReady Checks if the mass storage device is ready for read write operations MSC class typical usage flow To access a mass storage class device the host should implement a file system In STM32Cube solution the FATFS file system is used to access the FAT based mass storage
44. tation of the major USB classes Mass storage class MSC Human interface mouse and keyboard class HID Communication device class CDC Audio class AUDIO Media Transfer protocol class MTP In addition to the above listed classes the users can build their own class using the available library APIs The library is built with the possibility to work in standalone mode or in RTOS mode The library also supports multi instance as it can work simultaneously on two or more USB host peripherals Figure 1 STM32Cube USB host library User Application USB Host Library USB Host Class Management MSC HID CDC AUDIO USB Host Core USB Host HAL Driver USB Host Controller MS34367V1 6 43 DoclD025799 Rev 3 d UM1720 USB host library architecture and file organization 2 2 1 USB host library architecture and file organization USB host library architecture Figure 2 shows an overview of the library architecture Figure 2 USB host library architecture USB Host Core Ex Host Init Start Ex Mass storage READ WRITE E User callbacks USB Host Class Drivers MSv34368V1 d As seen in Figure 2 the USB host library is organized into two main parts the core and the class drivers The host core handles the core services of the library which are mainly used for the following
45. te DoclD025799 Rev 3 21 43 USB host library class module UM1720 Note 4 2 4 2 1 22 43 Table 11 Host class handler structure continued Structure member Description Class SOF process handles the class operation that should be called SOFProcess periodically from SOF interrupt handler Should be used to schedule periodic transfers interrupt isochronous Initialized during class initialization with a class handle structure that Data naar i P maintains the class process variables Control class requests can be also issued in HOST CLASS state USB mass storage class MSC The MSC background class is used to access the common USB flash pendrives using the BOT Bulk Only Transport protocol and the Transparent SCSI command set The MSC class is implemented using the files listed in Table 12 Table 12 Files used for USB MSC implementation File Description usbh msc c Implements mass storage class handler and class APIs usbh msc bot c Implements the Bulk Only Transfer BOT protocol state machine usbh msc scsi c Implements SCSI commands Read10 Write10 The MSC class handler is implemented using a structure of the type USBH ClassTypeDef USBH ClassTypeDef USBH msc MSC SB_MSC_CLASS SBH MSC InterfaceInit U U USBH MSC InterfaceDeInit USBH_MSC_ClassRequest USBH_MSC_BgndProcess NULL USBH_MSC_Handle nn MSC class inter
46. tions implements the low level API layer of the USB host library It acts as link layer with the USB Host controller HAL driver APIs The implemented functions are listed in Table 9 Low level interface APIs When starting from the usbh conf c file given an example three functions can be customized by the user while the other functions must be kept as is e USBH LL Init e USBH LL DriverVBUS e USBH Delay The user can use the parameters listed in the table below to configure the function USBH LL Init Table 26 USBH LL Init configuration options Config option Description hhcd Instance can be USB OTG FS or USB OTG FS when using the OTG HS peripheral you can enable or disable hhcd Init dma enable DMA For future use Allows to handle low power mode during host hhcd Init low power enable suspend mode Selects the PHY interface it can be HCD PHY EMBEDDED hhcd Init phy itface or HCD PHY ULPI hhcd Init Sof enable when enabled it allows to output SOF pulse on SOF pin Host speed can be HCD SPEED FULL or hhcd Init speed HCD SPEED HIGH When USB HS host controller is used this parameter enabled hhcd Init use external vbus VBUS driving from the ULPI PHY DoclD025799 Rev 3 Ly UM1720 Using the USB host library The user needs to customize the function USBH LL DriverVBUS to correctly drive the USB VBUS charge pump IC The following is the implementation in the example
47. ure The main structure used in the host library is the host handle which is of the type USBH_Handle Typedef Figure 3 USBH_HandleTypedef typedef struct uint8_t id if USBH_USE_O osMessageQId osMessageQId osThreadId endif _USBH_HandleTypeDef HOST_StateTypeDef gState ENUM_StateTypeDef EnumState CMD_StateTypeDef RequestState USBH CtrlTypeDef Control USBH DeviceTypeDef device USBH ClassType USBH ClassTypeDef pActiveClass uint32 t ClassNumber uint32 t Pipes 15 IO uint32 t Timer void pData void pUser struct US 1 os event class ready event thread USBH HandleTypeDef Table 6 details the structure of the host handler Def pClass USBH MAX NUM SUPPORTED CLASS BH HandleTypeDef pHandle Table 6 Host handle structure Structure member Description gState Gives the current state in the global host state machine EnumsState Gives the current state in the enumeration state machine RequestState Gives the current state for a control request IDLE SEND or WAIT Control Structure maintaining the information related to the control transfer management Device Structure maintaining the informations about the connected device DocID025799 Rev 3 13 43 Host library core module UM1720 Note 14 43 Table 6 Host handle structure continued Structure member pClass USBH_MAX_N UM_SUPPO
48. usbh conf c file It drives the GPIO pin PH5 USBH StatusTypeDef USBH LL DriverVBUS USBH HandleTypeDef phost uint8 t state if state 0 HAL GPIO WritePin GPIOH GPIO PIN 5 GPIO PIN SET else HAL_GPIO_WritePin GPIOH GPIO_PIN_5 GPIO_PIN_RESET HAL Delay 200 200ms delay VBUS stabilization time return USBH OK Finally the function USBH_LL_Delay is used to handle delays in ms for the USB host library It can be implemented by calling HAL library delay function HAL Delay or by using other custom delay routine 5 5 FAQs 3 Does the USB host library support composite devices for example Mass storage HID Yes providing the users write a custom composite class handler for the composite device Can I use the host library with my own USB host controller driver Yes you just need to implement the low level link interface layer usbh conf c file that sets the adaptation with your USB host controller driver Can I use at the same time the OTG HS and the OTG FS host controller Yes you can refer to the dual core example available in Applications USB_Host DualCore_Standalone Can the USB host library handle devices connected through a USB HUB No The USB host library does not support HUB class Does the USB host library allow to handle multiple configuration devices No Only single configuration devices are supported DoclD025799 Rev 3 41 43 Revision history UM1720 6 42 43 R
Download Pdf Manuals
Related Search