USB Device Development Kit for HT32 Series Microcontrollers

Transcription

1 USB Device Development Kit for HT32 Series Microcontrollers D/N:AN0309E Introduction The HT32 series USB device development kit provides several components including a HT32 series USB device firmware library, class examples, and Windows based demo UI. The kit supports all Holtek HT32 series microcontrollers which have a USB device controller. This application note familiarises users with the HT32 series USB device development kit to enable them to start creating their own USB applications. The class example code includes all the USB transfer types such as control, interrupt, bulk and isochronous. This document provides a description of the following components: HT32 series USB device firmware library: Peripheral driver, USB core, and application layer Human Interface Device (HID) demo: Control and interrupt transfer Mass Storage demo: Bulk transfer Virtual COM Port demo: Interrupt and bulk transfer USB video demo: Isochronous transfer HT32 USB Device Firmware Library This chapter describes the architecture and Application Programming Interface (API) of the HT32 USB device firmware library. The HT32 USB device firmware library provides a reference implementation of the following functions: HT32 USB device controller Initialisation USB bus event handle USB enumeration USB descriptor USB standard request USB class request USB endpoint IN and OUT transmission 1

2 Overview Architecture The architecture of the HT32 USB device firmware library can be divided into three layers, the hardware and peripheral drivers, the USB core and the and application. Figure 1 shows the interface and interaction of each layer. With some modification, any HT32 series microcontroller with a USB device controller can reuse the USB core and application layer. For most of the class applications, it is only necessary to modify the class and descriptor to fit the application demand. The USB core and USB driver layer do not require modification in most cases. Figure 1 HT32 USB Device Library Block Diagram The functions of each layer are: USB peripheral driver: The USB peripheral driver provides the basic hardware initialisation, register level accessing and endpoint buffer accessing functions. USB core: The USB core layer manages the major USB protocol including bus events, enumeration and standard requests. It provides an interrupt service routine to handle all the USB bus activity. Application: The application layer includes the USB descriptor data, the class request and the endpoint data processing. The major USB class functions are located in this layer. 2

3 File Organisation Figure 2 shows the file organisation of the HT32 series of USB device drivers, the USB core and class example code. Note that files for the class application layer may be different for each class example code. Figure 2 HT32 USB Device library File Organisation Class / Descriptor / Application USB Core USB Driver Table 1 shows the files of each layer: Table 1 HT32 USB Device Firmware Library File List Layer File Description ht32_usb.h Header file provides API with HT32 firmware library. USB peripheral driver ht32fxxxx_usbdinit.h ht32fxxxx_usbd.c ht32_usbd_core.h USB core ht32f_usbd_core.c ht32f_usbd_class.c ht32fxxxx_usbd.h Peripheral driver header file. Header file checks and processes the definitions from the ht32fxxxx_usbdconf.h file. Peripheral driver source file. USB core header file. USB core source file. Class example code source file. ht32f_usbd_class.h Class example code header file. Application ht32_usbd_descriptor.c Descriptor source file. ht32_usbd_descriptor.h Descriptor header file. 3

4 Source Code Naming Rules The HT32 USB device firmware library uses the following naming rules. The clear and friendly naming rules help users to understand and modify the source code. Table 2 HT32 USB Device Firmware Library Naming Rules Type Naming Rule / Example Description Prefix_FunctionName (module name prefix) All the function names add the module USBDCore_FunctionName: USB core Function Name name prefix to help the user identify USBD_FunctionName: USB driver which function belongs to which module. USBDClass_FunctionName: Class application The USB core layer uses the API Macro definitions as the interface to the USB API Macro API_USB_NAME(Parameter) #define API_USB_INIT(driver) (USBD_Init(driver)) driver layer. It gives flexibility to the function name of the USB driver. You can use any function name to implement the USB driver, just define the specific API macro in the header file of the driver. Constants #define DEFINE_NAME definition #define DESC_LEN_HID ((u32)(9)) Definitions are all uppercase. Prefix_NAME_Enum typedef enum Enumeration type Starts with a module name prefix and { definition ends with an Enum.. } USBD_EPTn_Enum; Prefix_NAME_TypeDef typedef struct Structure type Starts with a module name prefix and { definition ends with a TypeDef. } USBDCore_Info_TypeDef; Pointer: u32 *pdriver; Pointer with p prefix. u8/u16/u32: u32 upara; Unsigned variables with u prefix. Variable s8/s16/s32: s32 sbytelength; Signed variables with s prefix. Structure: USBDCore_TypeDef USBCore; Enumeration: USBDCore_Action_Enum Action; All the struct or enumeration variables are pure without any prefix. Global Variable u8 ginputreportbuffer[64]; Global variable with a g prefix. 4

5 USB Peripheral Driver The USB peripheral driver consists of several files including ht32_usb.h, ht32fxxxx_usbd.h, ht32fxxxx_usbdinit.h, and ht32fxxxx_usbd.c. The following table presents the USB peripheral driver modules. Table 3 USB Peripheral Driver Modules Module Description HT32 firmware library API for the USB core. The USB core includes this file ht32_usb.h to know the peripheral driver file names. Peripheral driver which provides hardware initialisation, register level ht32fxxxx_usbd (.h,.c) accessing and endpoint buffer accessing functions. This file provides preprocessor checking of the parameters which are ht32fxxxx_usbdinit.h defined in the ht32fxxxx_usbdconf.h file in the application layer. The USB peripheral driver provides an API for the hardware initialisation, register level accessing, endpoint buffer accessing and so on. The API can be divided into two kinds, global and endpoint APIs. The following sections give an overview of the global and endpoint API. Additionally, the following sections also describe the API macro in which the USB core is used as an interface with the USB peripheral driver. Refer to the Programming Guide of your device for more detailed information. Global API Global API represents the functions for the common setting of USB device controllers such as power control, device addresses, and interrupt operations. As mentioned before, all global APIs have a USBD_ prefix and a meaningful function name. Table 4 Peripheral Driver USB Global API API Name void USBD_Init(u32 *pdriver); void USBD_PreInit(USBD_Driver_TypeDef *pdriver); void USBD_DeInit(void); void USBD_PowerOff(void); void USBD_PowerOn(void); void USBD_RemoteWakeup(void); void USBD_ReadSETUPData(u32 *pbuffer); void USBD_SetAddress(u32 address); void USBD_EnableINT(u32 INTFlag); void USBD_DisableINT(u32 INTFlag); u32 USBD_GetINT(void); void USBD_ClearINT(u32 INTFlag); USBD_EPTn_Enum USBD_GetEPTnINTNumber(u32 INTFlag); Description USB device peripheral initialisation including endpoint initial value, power control, and interrupt mask. This function initiates the "USBD_Driver_TypeDef" structure using values from the ht32fxxxx_usbdconf.h file in the application layer. USB device peripheral de-initialisation. Enter USB device power down mode. Exit USB device power down mode. Generate a resume request to the USB host for a remote wakeup function. Read Endpoint 0 SETUP data from USB buffer. Set USB device address. Enable USB device interrupt. Disable USB device interrupt. Get USB device interrupt flag. Clear USB device interrupt flag. Get active USB interrupt endpoint number. 5

6 Endpoint API Endpoint API represents the functions for the endpoint including endpoint initialisation, reset, buffer accessing, bus response (STALL / NAK / ACK), and interrupt operations. All endpoint APIs have a USBD_EPT prefix and a meaningful function name. Table 5 Peripheral Driver USB Endpoint API API Name void USBD_EPTInit(USBD_EPTn_Enum EPTn, u32 *pdriver); void USBD_EPTReset(USBD_EPTn_Enum EPTn); void USBD_EPTEnableINT(USBD_EPTn_Enum EPTn, u32 INTFlag); u32 USBD_EPTGetINT(USBD_EPTn_Enum EPTn); void USBD_EPTClearINT(USBD_EPTn_Enum EPTn, u32 INTFlag); u32 USBD_EPTGetHalt(USBD_EPTn_Enum EPTn); void USBD_EPTSendSTALL(USBD_EPTn_Enum EPTn); void USBD_EPTSetHalt(USBD_EPTn_Enum EPTn); void USBD_EPTClearHalt(USBD_EPTn_Enum EPTn); void USBD_EPTWaitSTALLSent(USBD_EPTn_Enum EPTn); void USBD_EPTClearDTG(USBD_EPTn_Enum EPTn); u32 USBD_EPTGetBuffer0Addr(USBD_EPTn_Enum EPTn); u32 USBD_EPTGetBuffer1Addr(USBD_EPTn_Enum EPTn); u32 USBD_EPTGetBufferLen(USBD_EPTn_Enum EPTn); u32 USBD_EPTGetTransferCount(USBD_EPTn_Enum EPTn, USBD_TCR_Enum type); u32 USBD_EPTWriteINData(USBD_EPTn_Enum EPTn, u32 *pfrom, u32 len); u32 USBD_EPTReadOUTData(USBD_EPTn_Enum EPTn, u32 *pto, u32 len); u32 USBD_EPTReadMemory(USBD_EPTn_Enum EPTn, u32 *pto, u32 len); Description Endpoint initialisation including control and interrupt register. Reset endpoint to default status. Enable endpoint interrupt source. Get endpoint interrupt flag. Clear endpoint interrupt flag. Get endpoint halt status. Send STALL on specific endpoint. Set endpoint halt status. Clear endpoint halt status. Wait until STALL sent. Clear endpoint data toggle bit. Get endpoint buffer 0 address. Get endpoint buffer 1 address. Get endpoint buffer length. Get endpoint transfer count. Write IN data to USB buffer. Read OUT data from endpoint buffer and then clear NAK bit. Read OUT data from endpoint buffer. 6

7 API Macro The USB core uses an API macro as the interface to the USB peripheral driver layer to maintain transparency between themselves. The following table shows all API macros which are used by the USB core. You can find more detailed information in the ht32fxxxx_usbd.h file. Any peripheral driver which works with the USB core layer shall define the specific API macro correctly in the header file. Similarly with the USB peripheral driver, the API macro can be divided into two kinds, global and endpoint. All global API macros have an API_USB prefix and a meaningful function name. All endpoint API macros have an "API_USB_EPTn" prefix and a meaningful function name. Table 6 API Macro between the USB Core and the USB Peripheral Driver Layer API Macro Name Global API Macro API_USB_INIT(driver) API_USB_DEINIT() API_USB_POWER_OFF() API_USB_POWER_ON() API_USB_REMOTE_WAKEUP() API_USB_READ_SETUP(buffer) API_USB_SET_ADDR(addr) API_USB_GET_CTRL_IN_LEN() API_USB_ENABLE_INT(flag) API_USB_GET_INT() API_USB_GET_EPT_NUM(flag) API_USB_IS_RESET_INT(flag) API_USB_CLR_RESET_INT() API_USB_IS_SOF_INT(flag) API_USB_CLR_SOF_INT() API_USB_IS_RESUME_INT(flag) API_USB_CLR_RESUME_INT() API_USB_IS_SUSPEND_INT(flag) API_USB_CLR_SUSPEND_INT() API_USB_IS_EPTn_INT(flag, EPTn) API_USB_CLR_EPTn_INT(EPTn) Endpoint API Macro API_USB_EPTn_INIT(EPTn, driver) API_USB_EPTn_RESET(EPTn) API_USB_EPTn_SEND_STALL(EPTn) API_USB_EPTn_GET_INT(EPTn) API_USB_EPTn_IS_IN_INT(flag) API_USB_EPTn_CLR_IN_INT(EPTn) Description USB device peripheral initialisation API macro which is called by the USBDCore_Init() function. USB device peripheral de-initialisation function. When a reset event has occurred on the USB bus, the USBDCore_Reset() function will call this API macro. API macro used to turn off the USB device power. API macro used to turn on the USB device power. API macro used to generate a resume request to the USB Host for remote wakeup function. Read SETUP data from USB buffer. Set USB device address. Get CONTROL IN data length. Enable global interrupt. Get global interrupt flag. Get active USB interrupt endpoint number. Decide if a reset interrupt occurred. Clear reset interrupt. Decide if start of frame interrupt occurred. Clear start of frame interrupt. Decide if resume interrupt occurred. Clear resume interrupt. Decide if suspend interrupt occurred. Clear suspend interrupt. Decide if endpoint interrupt occurred. Clear endpoint interrupt. Endpoint initialisation API macro which is called by the Set Configuration standard command. Reset endpoint into its default status. Send STALL on specific endpoint. Get endpoint interrupt flag. Decide if an endpoint IN interrupt occurred. Clear endpoint IN interrupt flag. 7

8 API Macro Name API_USB_EPTn_IS_OUT_INT(flag) API_USB_EPTn_CLR_OUT_INT(EPTn) API_USB_EPTn_IS_INT(flag) API_USB_EPTn_CLR_INT(EPTn) API_USB_EPTn_GET_HALT(EPTn) API_USB_EPTn_SET_HALT(EPTn) API_USB_EPTn_CLR_HALT(EPTn) API_USB_EPTn_WAIT_STALL_SENT(EPTn) API_USB_EPTn_CLR_DTG(EPTn) API_USB_EPTn_GET_BUFFLEN(EPTn) API_USB_EPTn_GET_CNT(EPTn, type) API_USB_EPTn_WRITE_IN(EPTn, from, len) API_USB_EPTn_READ_OUT(EPTn, to, len) API_USB_EPTn_READ_MEM(EPTn, to, len) Description Decide if an endpoint OUT interrupt occurred. Clear endpoint OUT interrupt flag. Decide if an endpoint IN or OUT interrupt occurred. Clear endpoint IN and OUT interrupt flag. Get endpoint halt status. Set endpoint halt status. Clear endpoint halt status. Wait until STALL sent. Clear endpoint data toggle bit. Get endpoint buffer length. Get endpoint transfer count. Write IN data to USB buffer. Read OUT data from endpoint buffer and then clear NAK bit. Read OUT data from endpoint buffer. USB Core The USB core consists of only two files, "ht32_usbd_core.h" and "ht32_usbd_core.c". All the USB core functions such as bus event handler, standard request, enumeration, and control IN/OUT are implemented in this layer. The following section describes the variable architecture, USB core operations, and USB core API. Table 7 USB Core Module Module Description USB core module including USB bus event handler, standard request, ht32_usbd_core (.h,.c) enumeration, and control IN/OUT function. Variable Architecture For the USB core operation, the USB core layer provides a structure which is named "USBDCore_TypeDef" to arrange the necessary variables for the USB core function. The users should declare this structure as a global variable and pass its memory address into the "USBDCore_Init()" function. The "USBDCore_TypeDef" structure also provides the necessary variables for the application layer functions such as the "USBDDesc_Init()" and "USBDClass_Init()" functions. Detailed usage information will be discussed in the application layer later. The following table shows all members of the "USBDCore_TypeDef" structure and its description. More information can be found in the "ht32_usbd_core.c/h" file. 8

9 Table 8 USB Core Variable Architecture USBCore. (USBDCore_ TypeDef) Name (type) Description bmrequesttype: Request Characteristics. brequest: Specific request. Request. wvaluel: Low byte of request parameter. (USBDCore_Req wvalueh: High byte of request parameter. uest_typedef) windex: Request parameter. wlength: Number of bytes to transfer in data stage. Desc. pdevicedesc: Data pointer of Device Descriptor. Device. (USBDCore_Des pconfndesc: Configuration Descriptor Data Pointer. (USBDCore_De c_typedef) pstringdesc[n]: String Descriptor Data Pointer. vice_typedef) ubuffer[2]: Temporary Buffer. pdata: Control IN/OUT Data Pointer. sbytelength: Total length for control IN/OUT Transfer. Transfer. (USBDCore_Tran Action: STALL, control IN or control OUT. sfer_typedef) (USBDCore_Action_Enum) CallBack_OUT.func/uPara: Call back function pointer and parameter for Control OUT ucurrentconfiguration: For Set/GetConfiguration request. ucurrentinterface: For Set/GetInterface request. CurrentStatus: Device State. (USBDCore_Status_Enum) Info. LastStatus: Device State before SUSPEND. (USBDCore_Status_Enum) (USBDCore_Inf CurrentFeature: For Set/ClearFeature and GetStatus request. o_typedef) (USBDCore_Feature_TypeDef) uisdiscardclearfeature: Discard ClearFeature request for Mass Storage CallBack_MainRoutine.func/uPara: Class main routine call back function/parameter. CallBack_StartOfFrame: Class SOF call back function. Class. CallBack_ClassGetDescriptor: Class Get Descriptor call back function. (USBDCore_Cla CallBack_ClassSetInterface(pDev): Class Set Interface call back ss_typedef) function. CallBack_ClassRequest(pDev): Class Request call back function. CallBack_EPTn[MAX_EP_NUM](EPTn): Endpoint n call back function. pdriver (u32) USB Device Driver initialisation structure. Power. CallBack_Suspend.func/uPara: System low power function/parameter (USBDCore_Po for SUSPEND. wer_typedef) 9

10 USB Core Operations When a specific USB bus event occurs, the USB device IP generates an interrupt signal to notify the CPU that an event has occurred and needs to be serviced. After the interrupt controller and the CPU have finished all the necessary operations, the CPU starts executing the Interrupt Service Routine (ISR) to handle the USB bus event. The USB core layer provides the ISR function, named "USBDCore_IRQHandler()" for the above operation. "USBDCore_IRQHandler()" will check the status register of the USB device IP using the API macro (peripheral driver layer) to identify the USB bus event and then call the corresponding function to handle it. The following table descries all the USB bus events and their corresponding functions. Refer to the "USBDCore_IRQHandler()" function in the "ht32_usbd_core.c" file for the detailed operation. Table 9 USB bus Event and its Corresponding Functions of USB Core Layer Bus Event Corresponding Function Description When a USB bus reset occurs, the USB core resets all states into their default value, turns on the USB IP power, initializes the control endpoint and Reset _USBDCore_Reset(pCore); enables the USB interrupt. After this has completed the control endpoint will get ready to receive/send data via USB address 0. The states to be reset include the global status variables and the USB device IP control register. Resume _USBDCore_Resume(pCore); When the USB bus resume event occurs, the USB core will turn on the IP power and recover the current status variable (recover back to the value before going entering the suspend mode). Suspend _USBDCore_Suspend(pCore); The USB core changes the current status variable to "SUSPEND" when the USB bus suspend event occurs. It causes the USB core to execute the suspend call back function of application which forces the device into the low power mode. Control Endpoint SETUP packet ready Control Endpoint IN data transmitted Control Endpoint OUT data ready Endpoint n IN data transmitted Endpoint n OUT data ready _USBDCore_Setup(pCore); _USBDCore_ControlIN (pcore); _USBDCore_ControlOUT (pcore); pcore->class.callback_eptn [EPTn](EPTn); When the SETUP data is ready, the USB core uses this function to process the SETUP data. This function takes care of the USB standard, class, and vendor request. When the last control IN data transmission has completed, the USB core uses this function to process the next IN data. This function also takes care of the Zero Length Packet (ZLP) when necessary. When the control OUT data has been received, the USB core uses this function to process the OUT data. The call back function takes care of the data transmission of endpoint IN or OUT. It is installed by the "USBDClass_Init()" function. 10

11 The USB core layer provides a "call back" capability for some known cases where the bus event needs the application layer involved. For example, a start-of-frame, get class descriptor, set interface or class request may need extra operations which are not included in the USB core layer. The user needs to specify the call back function for the USB core layer in the class initialisation stage. However, in some specific situations, the user may need to modify the USB core layer to fit the class application requirements. However such cases do not occur often. USB Core API The USB core layer provides the following API for the application layer to achieve the functions of class application. For a unified user interface, some of the USB core API functions do not actually exist but rather just re-define the API name of the API macro (USB peripheral driver layer). Note that the application layer shall prevent use of any functions other than the USB core API. Therefore it can maintain the independence of each layer and increase the possibility of module replacement. Table 10 USB Core API API Name Description Initialisation and system API void USBDCore_Init(USBDCore_TypeDef *pcore); USB core initialisation. void USBDCore_IRQHandler(USBDCore_TypeDef *pcore); USB core Interrupt service routine. USB core main routine for void USBDCore_MainRoutine(USBDCore_TypeDef *pcore); application. u32 USBDCore_IsSuspend(USBDCore_TypeDef *pcore); Return suspend status. Return remote wake status which is u32 USBDCore_GetRemoteWakeUpFeature(USBDCore_TypeDef *pcore); set by SET FEATURE standard command. Turn on the USB power and remotely void USBDCore_TriggerRemoteWakeup(void); wakeup the Host. Endpoint API void USBDCore_EPTReset(USBD_EPTn_Enum EPTn); Reset endpoint into its default status. u32 USBDCore_EPTGetBufferLen(USBD_EPTn_Enum EPTn); Get endpoint buffer length. u32 USBDCore_EPTGetTransferCount(USBD_EPTn_Enum EPTn, Get endpoint transfer count of. USBD_TCR_Enum type); void USBDCore_EPTSetSTALL(USBD_EPTn_Enum EPTn); Set endpoint halt status. Void USBDCore_EPTWaitSTALLSent(USBD_EPTn_Enum EPTn); Wait until STALL sent. Void USBDCore_EPTClearDataToggle(USBD_EPTn_Enum EPTn); Clear endpoint halt status. Endpoint Data API u32 USBDCore_EPTWriteINData(USBD_EPTn_Enum EPTn, u32 Write IN data to USB buffer. *pfrom, u32 len); u32 USBDCore_EPTReadOUTData(USBD_EPTn_Enum EPTn, Read OUT data from endpoint buffer u32 *pto, u32 len); and then clear NAK bit. u32 USBDCore_EPTReadMemory(USBD_EPTn_Enum EPTn, u32 Read OUT data from endpoint buffer. *pto, u32 len); 11

12 Application Layer The application layer includes several files for the configuration, descriptor, class request, and endpoint data processing. The major functions of USB class are located in this layer. The user can modify the files in the application layer to fit the application demands. Following table shows the modules and files of application layer. The detailed information of each module will be discussed later in this section. This section also provides detailed information of how to configure and initialise the USB core and descriptor. Table 11 Application Layer Modules Module Description The USB Device configurations file. It includes interrupt and endpoint related ht32fxxxx_usbdconf.h setting of the USB device IP. USB device descriptor including device, configuration, and, string. This ht32_usbd_descriptor (.c,.h) module provides initialisation functions for setup of the data pointer of the descriptor for the USB core to get a descriptor request. Class related function including initialisation, main routine, standard request ht32f_usbd_class (.c,.h) for class, class request, and data process of the endpoint. 12

13 Configuration File (ht32fxxxx_usbdconf.h) The configurations file is used to configure the HT32 USB device peripheral including the global interrupt enable bit and endpoint setting. The following figure shows the screen of Configuration Wizard of Keil uvision IDE. The user can also change the setting by editing the "ht32fxxxx_usbdconf.h" file directly. Note that the items with "(Default)" mark can not be disabled in general cases. Figure 3 Keil uvision IDE Configuration Wizard 13

14 The following steps show the configuration flow and notice. For the USB Interrupt Setting (UIER), make sure the items with a "(Default)" mark are enabled. Enable the endpoint n Interrupt (EPnIE) according to the endpoint usage of your class / application. Configure the buffer length of the control endpoint 0 as 8, 16, 32, or 64 bytes. This depends on the USB buffer memory usage. Make sure the ODRXIE, IDTXIE, and SDRXIE interrupt enable bit of endpoint 0 are enabled. The USB core layer depends on those bus events to process USB control transfer. Configure the endpoint n setting according to the endpoint usage of your class / application. The following table shows the settings that must receive special attention. Table 12 Endpoint Settings Settings Endpoint Address Endpoint Enable Endpoint Transfer Type Endpoint Direction Endpoint Buffer Length Endpoint Interrupt Enable Description No need to modify for general cases. Shall be turned on before using the endpoint. Endpoint 1 ~ 3: Bulk or Interrupt Endpoint 4 ~ 7: Isochronous, Bulk, or Interrupt. IN or OUT Interrupt: 1 ~ 64 bytes Bulk: 8, 16, 32, or 64 bytes Isochronous: 1 ~ 1023 (Note: Since at least bytes of USB buffer are reserved for SETUP data and endpoint 0, the actual maximum buffer length of Isochronous endpoint is 1008 bytes) For IN endpoint, the firmware usually uses the IN Data Packet Transmitted Interrupt Enable (IDTXIE) to take care of the data transmission procedures. For the OUT endpoint, the firmware usually uses the OUT Data Packet Received Interrupt Enable (ODRXIE) to take care the data transmission procedures. Other interrupts can be used for debug or other purposes. Refer to the HT32Fxxxx user manual for more information. 14

15 Descriptor Setting The device, configuration, interface, endpoint, and string descriptor are located in "ht32_usbd_descriptor.c" file of the application layer. The user shall modify them according to the requirement of class / application. The following figure shows the Keil uvision IDE Configuration Wizard for the device and configuration descriptor. For other IDEs or other descriptors, the user can modify the descriptor by editing the "ht32_usbd_descriptor.c" file directly. Figure 4 Keil uvision IDE Configuration Wizard for Device and Configuration Descriptors 15

16 Initialisation Flow The following source code gives an example of how to initiate the USB descriptor, class, and core. After the initialisation flow has completed, the application will call the "USBDCore_MainRoutine(&gUSBCore)" function regularly which handles the suspend call back function and class main routine. ALIGN4 USBDCore_TypeDef gusbcore; /* Memory for USB core, must 4 bytes alignment */ USBD_Driver_TypeDef gusbdriver; /* Memory for USB driver */ void USB_Configuration(void) { gusbcore.pdriver = (u32 *)&gusbdriver; /* Initiate memory pointer of USB driver */ gusbcore.power.callback_suspend.func = Suspend; /* Install suspend call back function into USB core */ USBDDesc_Init(&gUSBCore.Device.Desc); descriptor */ USBDClass_Init(&gUSBCore.Class); */ USBDCore_Init(&gUSBCore); */ /* Initiate memory pointer of /* Initiate USB Class layer /* Initiate USB Core layer NVIC_EnableIRQ(USB_IRQn); /* Enable USB Device interrupt */ } int main(void) {... USB_Configuration(); /* USB Related configuration */ /* Connetc USB and wait enumeration finish */ HT32F_DVB_USBConnect(); while(gusbcore.info.currentstatus!= USB_STATE_CONFIGURED);... while (1) {... USBDCore_MainRoutine(&gUSBCore); /* USB core main routine */ } }

17 Class Implementation This section provides detailed information of the class implementation including, class request, endpoint data process and class main routine. The purpose of this section is to describe how to modify the application layer to fit the USB class requirement. Class Initialisation Class initialisation installs related call back functions / parameters including: Class main routine Start of Frame Standard Get Descriptor request for class Standard Set Interface request Class request Endpoint handler You can find the initialisation function named "USBDClass_Init" in the "ht32_usbd_class.c" file of each class example code. The user can follow the example to install the call back function of their class / application. Figure 5 Example of class initialisation 17

18 Class Request When the USB core receives a SETUP transfer and decodes it as a class request, the USB core will execute the class request call back function (CallBack_ClassRequest). The USB core pass the "USBDCore_Device_TypeDef" structure point as the parameter to the class request call back function. Refer to the "Table 8 Variable architecture of the USB core" for more information. The "USBDClass_Request()" function in the "ht32_usbd_class.c" file gives an example of how to deal with a class request. Users can implement there own class request function according to their requirement. The class request function shall be installed as a call back function in the "USBDClass_Init" function as shown below. static void USBDClass_Request(USBDCore_Device_TypeDef *pdev); void USBDClass_Init(USBDCore_Class_TypeDef *pclass) {... pclass->callback_classrequest = USBDClass_Request;... } 18

19 Endpoint Handler For the USB characteristics, the firmware usually configures the USB device controller to issue the endpoint interrupt when the IN data packet is transmitted or the OUT data packet is received. When an endpoint interrupt has occurred, the USB core will check the interrupt flag and execute the corresponding endpoint handler. The endpoint handler is responsible for the endpoint data process. The following functions of the USB core are used for the endpoint data process. Table 13 USB core data process API API Name USBDCore_EPTWriteINData USBDCore_EPTReadOUTData USBDCore_EPTReadMemory Description Write IN data to USB buffer. Read OUT data from endpoint buffer and then clear NAK bit. Read OUT data from endpoint buffer. The firmware can process the data inside the endpoint handler or just set a software flag to notify the application for IN/OUT data. Note that endpoint handler is executed under the MCU interrupt mode and will therefore block other interrupts according to their priority. If the USB data is large, data processing shall be prevented inside the endpoint handler. The user shall the install endpoint handler as a call back function in the "USBDClass_Init" function as shown below. static void USBDClass_Request(USBDCore_Device_TypeDef *pdev); void USBDClass_Init(USBDCore_Class_TypeDef *pclass) {... pclass->callback_eptn[1] = USBDClass_Endpoint1; pclass->callback_eptn[2] = USBDClass_Endpoint2; //pclass->callback_eptn[3] = USBDClass_Endpoint3; //pclass->callback_eptn[4] = USBDClass_Endpoint4; //pclass->callback_eptn[5] = USBDClass_Endpoint5; //pclass->callback_eptn[6] = USBDClass_Endpoint6; //pclass->callback_eptn[7] = USBDClass_Endpoint7;... } 19

20 Class Main Routine If the firmware spends too much time on the endpoint data process during the endpoint USB ISR handler, the interrupt whose priority is lower then the USB device controller can not be serviced by the MCU. It may therefore not be suitable in some peripherals which require a specific response time. Therefore, we suggest processing the low priority endpoint data outside of the endpoint handler. "USBDClass_MainRoutine()" can help the user to do this. The user can set a software flag in the endpoint handler when an endpoint interrupt occurs. After the USB ISR returns, check the flag and process the IN or OUT data in the "USBDClass_MainRoutine()" function. Meanwhile, for the MCU with DMA controller, using the DMA to prevent the above situation is also a good method. You can trigger the DMA in the endpoint handler and take care of the data in the "USBDClass_MainRoutine()" function when the DMA transfer has completed. The "USBDClass_MainRoutine()" function will be executed regularly by the USB core. The user should install it as the call back function in the "USBDClass_Init" function. The call back function reserves an "upara" parameter for future usage. Refer to the "ht32_usbd_class.c" file for more information. static void USBDClass_MainRoutine(u32 upara) void USBDClass_Init(USBDCore_Class_TypeDef *pclass) {... pclass->callback_mainroutine.func = USBDClass_MainRoutine; //pclass->callback_mainroutine.upara = (u32)null;... } 20

21 Using the HT32 USB Device Class Example Code This chapter describes the basic usage of class example code including Project, Windows driver, and The USB core debug mode. Project Files Class example code provides project files of Keil MDK-ARM, IAR EWARM, and CooCox CoIDE. The project files are: USBD/CLASS_EXAMPLE/CoIDE_EXAMPLENAME/CoIDE_EXAMPLENAME.cob USBD/CLASS_EXAMPLE/EWARM/Project.eww USBD/CLASS_EXAMPLE/MDK_ARM/Project.uvproj USBD/CLASS_EXAMPLE/SourceryG++Lite/Project.uvproj Figure 6 Class Example Code Project Files You can open the project file of each class example code with the preferred IDE to test it on the development board. Refer to the Quick Start Guide of each IDE for compiler, download, and debug operations. 21

22 Windows USB Driver All the class example codes (expect Virtual COM Port Demo) connect to your PC with a Windows integrated driver. You do not need to specify the driver for them. The Virtual COM Port Demo uses the HT32_VCP.inf file provided by Holtek to tell Windows which driver should be loaded. You need specify the path of HT32_VCP.inf when you connect the Virtual COM Port Demo to Windows. HT32_VCP.inf is located at {Firmware Library Path}\xxxx_CMSIS_FWLib\example\USBD\Virtual_COM\. All the class example codes use the same VID and PID, 0x04D9 and 0x8008. Windows may not load the driver correctly when you connect different class example codes with the same VID and PID on the same PC. Meanwhile, if you modify the descriptor but keep the VID and PID the same, the above situation may also occur. The Windows device manager displays a Malfunctioning message on the USB device. The steps below show how to solve the above problem under Windows XP. In other versions of Windows or other operating systems you may have to search for the same functionality. Open the Device Manager by press the button on the Hardware tab of the Control Panel System dialog. Find the correct USB device on the list which you plug in to your PC (with a Malfunctioning icon). Right click on the device and choose Uninstall, then unplug it from the PC and reconnect it. Windows should re-install the correct USB device drive automatically. USB Core Debug Mode For debug purposes, your can turn on the USB core debug mode by setting the "USBDCORE_DEBUG" definition value as 1 (which is located in ht32_usbd_core.h). According to the firmware library retarget setting, the USB core usesthe printf function to show the debug message through the UART or ITM interface. Note that the USB core debug mode degrades the performance and may cause an USB error under some conditions. You should turn off the USB debug mode on your final application. We strongly recommend to turn off the "Dump USB Debug data (USBDCORE_DEBUG_DATA)" option when the USB debug message is retargeted to the UART interface. 22

23 Figure 7 USB Core Debug Mode Setting Figure 8 shows the output example of the USB core debug mode. Figure 8 USB Core Debug Mode Output Example 23

24 Human Interface Device HID USB Device Development Kit for HT32 Series Microcontrollers Introduction The Human Interface Device (HID) is designed for the device that is used for human control of the PC host. The HID uses the report concept to exchange data via the control or interrupt pipe. Since most operation systems support an integrated HID driver, we can use the HID class for a convenient way to exchange data with the PC without implementing any operation system drivers. The USB Device HID example code shows how to use the HT32 USB device library, enumeration, endpoint interrupt transfer and HID Get/Set Report. This example simply shows how to loopback the HID output report to the input report. Additionally, the set feature report also loops back to the get the feature report. Using the HID Example Code The HID example code is implemented in the USB HID class on the HT32 series development board. When the example code is downloaded into the development board and the USB cable is connected to the PC, you will out a new HID device (VID = 0x04D9, PID = 0x8008) in the Device Manager as shown in the figure below. Figure 9 Device Manager HID Device 24

25 The HID example code also provides a PC based demo UI named "HID_Demo_UI.exe" to show how the HID device exchanges data with the PC. The demo UI is based on the Microsoft Virtual C The source code of the HID demo UI is located in the "HID_Demo_UI_Src.zip" file in the path of HID example code. The user can use the HID demo UI example code as base code to develop and customize PC based applications. Figure 10 PC Based Demo UI HID Example Code 25

26 HID Class Implementation This section descries the implementation of HID class including HID report descriptor, endpoint configuration, class request, and data transmission. HID Report Descriptor The HID report descriptor, "USB_HID_ReportDesc[]" array is located in the "ht32_usnd_class.c" file. It defines the format and purpose of the HID report. Refer to the HID specification for more information. The USB Implementers Forum provides a tool named "HID Descriptor Tool" to generate the HID report descriptor automatically. You can use this tool to make the HID report descriptor and save it as a Header File (*.h). The array data of the report descriptor in the header file can be copied and pasted directly to the "USB_HID_ReportDesc[]" array. Note that the length definition (DESC_LEN_RPOT) of HID report descriptor is located in the "ht32_usbd_class.h" file. It must be modified when the length of HID report descriptor is changed. Figure 11 HID report Descriptor Length Definition Endpoint Configuration The HID example code uses three endpoints for the control and report transmission. The following table shows the endpoint number, direction and transfer type. The detailed endpoint settings can be found in the "ht32xxxx_usbdconf.h" file. Table 14 Endpoints of HID example code Endpoint Number Transfer Type Endpoint 0 Control IN or OUT Endpoint 1 Interrupt IN Endpoint 2 Interrupt OUT Endpoint 0 (Control): For USB standard / class request. Set Report and Get Report use this endpoint for data transmission. Endpoint 1 (Interrupt IN): For HID input report data transmission. Endpoint 2 (Interrupt OUT): For HID output report data transmission. 26

27 Class Request USB HID defines six class-specific requests. Those class requests are implemented in the "ht32_usbd_class.c" file of the HID example code. Not all commands are required. The following table shows all defined HID class request and its implementation status in this example code. Table 15 Class request of HID Class Request Description Required? Implemented? Get Report Host receives an input or feature report from the device via the control pipe. Y Y Get Idle Host reads the current idle rate. N N Get Protocol Host reads which protocol is currently active (boot or report). N(*) N Set Report Host sends an output or feature report to the device via the control pipe. N Y Set Idle Host set the idle rate of the device for saving the bandwidth. N N Set Protocol Host switches the boot or report protocol of the device. N (*) N *Note: Required for boot device Data Transmission The following table shows the data transfer flow of the HID demo example code. Refer to the endpoint handler and class main routine of "ht32_usbd_class.c" file for more information. Table 16 HID Demo Example Code Data Transfer Flow HOST Device Action Set Output Report Endpoint 0 (Control) Save to goutputreportbuffer and copy to Output Report (ReadFile) Endpoint 2 (OUT) ginputreportbuffer Get Input Report Endpoint 0 (Control) Input Report (WriteFile) Endpoint 1 (IN) Transmit data from ginputreportbuffer Set Feature Report Endpoint 0 (Control) Save to gfeaturereportbuffer Get Feature Report Endpoint 0 (Control) Transmit data from gfeaturereportbuffer 27

28 Mass Storage Introduction The USB device Mass Storage example code shows how to use the HT32 USB device library, enumeration, and endpoint bulk transfer. This example code communicates with the PC host using the Bulk Only Transport (BOT) protocol. For media accessing, the SCSI (Small Computer System Interface) Block Command, RAM and SD disk related function are also implemented in this example code. A RAM disk and SD disk are supported by the example code. RAM disk example helps the user to understand the architecture of USB Mass Storage, BOT, and SCSI commands. The RAM disk function is also a good starting point for the creation of customised data exchange applications. Customer data exchange can utilise the benefits of mass storage such as fast bulk transfer and drive-less transfer of most operation systems. Using Mass Storage Example Code Refer to the Chapter 3 to build and download the Mass Storage example code into the HT32 series development board. Insert the SD card and connect the USB cable with the PC host. When the USB enumeration has finished, you can access the RAM disk and SD disk using the Windows file explorer. The data can be read from or written to the SD card using the file explorer. This is useful for updating the contents of SD cards using the PC. Figure 12 Example Code for RAM Disk and SD Disk Mass Storage in Windows The RAM disk has a "README.TXT" file which contains example text data. You can simply open this file by double clicking on it. It shows how to exchange data between the PC host and the USB device using the RAM disk function. Figure 13 "README.TXT" Example Text Data 28

29 Mass Storage Class Implementation The Mass Storage example implements Bulk-Only Transport protocol (BOT), SCSI Block Command (SBC-3 and SPC-4), RAM and SD disk related functions. This section provides the basic information for the above functions. The Mass Storage Class example code architecture can be divided into three layers, BOT, SCSI command and media accessing. The following table lists the Mass Storage example code modules. Table 17 Modules of Mass Storage example code Module Description The middle layer between the USB core and BOT protocol. Is in ht32f_usbd_class (.c,.h) charge of the initialisation, data transmission, and class request. usb_bulk_only_transport (.c,. h) BOT protocol command handler and functions. usb_scsi_block_command (.c,.h) SCSI Block command handler and functions. usb_scsi.h SCSI protocol related definition, structure and constant. MEDIA_disk (.c,.h) Media accessing related functions. The example code supports the SCSI transparent command set (0x06 which is set by the "binterfacesubclass" subclass code on the configuration descriptor) and the USB Mass Storage Class Bulk-Only Transport (0x50 BBB protocol which is set by the "binterfaceprotocol" on the configuration descriptor). The following sections give a brief description of the BOT and SCSI commands. Refer to each specification for more information. Bulk-Only Transport - BOT The Bulk-Only Transport protocol uses bulk IN and OUT endpoints to transfer the Command Block Wrapper (CBW), Command Status Wrapper (CSW) and data IN/OUT. No transfer is required for the control and interrupt pipe of the BOT protocol. The Mass Storage BOT transaction is divided into three phases, command stage (CBW), optional data stage (IN or OUT) and status stage (CSW). Figure 14 Mass Storage BOT Protocol Flow 29

30 The following two figures show the CBW and CSW format. Refer to the Bulk-Only Transport specification for more information. Figure 15 Command Block Wrapper Format Figure 16 Command Status Wrapper Format 30

31 The BOT CBW includes CBWCB field which carry out the command block to be execute by the device. In this example code, CBWCB carry out the SCSI SBC-3 and SPC-4 command which will be delivered to the SCSI layer. All the necessary functions are implemented in the "usb_bulk_only_transport.c" file. The following table shows the functions and its description. Table 18 API of the BOT Layer Function Description void BOT_Init(void); BOT Initialisation function. The initialisation includes CSW field, SCSI layer, media. void BOT_Reset(void); BOT reset function for the Bulk-Only Mass Storage Reset class request. uc8 *BOT_GetMaxLUNAddress(void); Get maximum Logical Unit Number (LUN). void BOT_OUTProcess(void); This function is used to process the USB OUT data. This function shall be executed in the endpoint handler or class main routine. void BOT_INProcess(void); This function is used to process the USB IN data. This function shall be executed in the endpoint handler or class main routine. u32 BOT_CheckCBWParameter(BOT_Dir_Enum DeviceDirection, u32 udevicelength); This function is used to check whether the CBW parameter is valid or not (Cass1 ~ Cass 13). void BOT_WriteINData(u8 *pbuffer, u32 ulen, BOT_State_Enum status); Write BOT IN data and update the BOT State/CSW. void BOT_ReadOUTData(u8 *pbuffer, u32 ulen); Read the BOT OUT data and update CSW. void BOT_SendCSW(BOT_CSW_STATUS_Enum status); This function is used to send CSW to the Host. void BOT_ErrorHandler(BOT_STALL_Enum StallEPT, BOT_CSW_STATUS_Enum CSWstatus); This function is used to take the error status including stall endpoint and send CSW. 31

32 Small Computer System Interface (SCSI) Command The Small Computer System Interface (SCSI) command is used to provide efficient communication between the SCSI device and the host PC. The Mass Storage example code implements part of the SBC-3 and SPC-4 command. Refer to the specification of SBC-3 and SPC-4 for more information. The following tables show the supported Mass Storage example code commands. These commands are implemented in the "usb_scsi_block_command.c" file. The BOT layer will pass the Command Block (CB) to the SBC_CMDHandler() function of SCSI layer. This function finds out the operation code of the command and execute the corresponding function of the SCSI command. Table 19 Supported SCSI command set Command Name Operation Code Description TEST UNIT READY 0x00 The TEST UNIT READY command provides a means to check if the logical unit is ready. REQUEST SENSE 0x03 The REQUEST SENSE command requests that the device server transfers parameter data containing sense data to the application client. INQUIRY 0x12 The INQUIRY command requests that information regarding the logical unit and SCSI target device be sent to the application client. MODE SENSE (6) 0x1A The MODE SENSE(6) command provides a means for a device server to report parameters to an application client. READ FORMAT CAPACITY 0x23 The READ FORMAT CAPACITIES command allows the host to request a list of the possible format capacities for an installed media. The ALLOW MEDIUM REMOVAL command PREVENT ALLOW MEDIUM 0x1E requests that the logical unit enables or disables the REMOVAL removal of the medium. The READ CAPACITY (10) command requests that READ CAPACITY (10) 0x25 the device server transfers 8 bytes of parameter data describing the capacity and medium format of the direct-access block device to the data-in buffer. READ (10) 0x28 The READ (10) command requests that the device server reads the specified logical block(s) and transfers them to the data-in buffer. WRITE (10) 0x2A The WRITE (10) command requests that the device server transfers the specified logical block(s) from the data-out buffer and write them into media. 32

33 Media Accessing Media accessing related functions are located in files such as "ram_disk.c" or "sd_disk.c". The BOT layer provides a structure named "BOT_Media_TypeDef" for the media information. The disk information and accessing functions are defined by this structure as a global variable, "gmediainfo" in the "usb_bulk_inly_transport.c" file. The following table shows the "gmediainfo" variable members. Table 20 "BOT_Media_TypeDef" Structure Members Member Description Unique ID for media. This ID is used to identify different media on the u32 uid; single media driver which supports multiple LUN. The SCSI layer will pass this ID to the media driver. BOT_MediaSize_Typedef Size; Size information including block count, block size, and media size. pinit Init; Media Initialisation function. preadfun Read; Media Read function. pwritefun Write; Media Write function. pgetstatusfun GetStatus; SCSI layer uses this function to test whether the media is ready or not. u8 *psbc_inquirydata; Inquiry command data pointer. u8 *psbc_sensedata; Request sense data command data pointer. The user should follow the above format to implement other media accessing functions. The BOT and SCSI layers depend on this information and functions to access specific media. The following tables give an example of RAM disk accessing functions. Table 21 RAM Disk Accessing Functions Function u32 RAMDISK_Read(u32 uid, u8 **pbuffer, u32 uaddress, u32 ulength); u32 RAMDISK_Write(u32 uid, u8 *pbuffer, u32 uaddress, u32 ulength); u32 RAMDISK_GetStatus(u32 uid, BOT_MediaSize_Typedef *psizeinfo); Description Read media based on the parameters. The SCSI read command uses this function to read from the media. Write media based on the parameters. The SCSI write command uses this function to write to the media. This function is used to report the status of media. The SCSI test unit ready command uses this function to test the media status. Endpoint Configuration The Mass Storage example code uses three endpoints for control, and bulk transfer. The following table shows the endpoint number, direction and transfer type. The endpoint detailed settings can be found in the "ht32xxxx_usbdconf.h" file. Table 22 Endpoints of HID example code Endpoint Number Endpoint 0 Endpoint 1 Endpoint 2 Transfer Type Control IN or OUT Bulk IN Bulk OUT Endpoint 0 (Control): For USB standard / class request. Endpoint 1 (Bulk IN): For CSW transmission of Mass Storage BOT protocol. Endpoint 2 (Interrupt OUT): For CBW transmission of Mass Storage BOT protocol. 33

34 Class Request The Mass Storage BOT protocol defines two class-specific requests. These class requests are implemented in the "ht32_usbd_class.c" file in the Mass Storage example code. The following table shows all the defined class requests and their description. Table 23 Class request of BOT for Mass Storage Class request Bulk-Only Mass Storage Reset Get Max LUN Description This request is used to reset the mass storage device and its associated interface. The Get Max LUN request is used to determine the number of logical units supported by the device. LUN should be numbered consecutively starting from LUN 0 to 15 (maximum). Configuration The example code supports multiple LUN (Logical Unit Number) functions which can be used to access different media by a single USB Mass Storage Device. A RAM Disk and SD Disk are supported by this example code. The RAM disk and SD disk function can be enabled or disabled by the "usb_bulk_only_transport.h" file. The number of LUN can also be changed in the same file. Figure 17 Configuration of total LUN, media, and access LED The RAM disk provides FAT12 example data to show the disk content and information on the PC host. The FAT table is defined in the variable named "gumemory0" and " gumemory1" in the "ram_disk.c" file. The filename, file content, disk label and etc. can be found and modified in the FAT table. Refer to the FAT12 specification for more information. 34

35 USB Video Introduction This chapter uses the HT32 series development board to show the USB Video Device Demo. Send a 320x240 color change screen to PC to show the USB Isochronous transmission function. The USB Video Class (UVC) device defined by the USB device class is a general video device, includes dynamic video device, such as digital camera, Webcam. This device connected to PC can plug and play directly without additional driver. Using USB Video Example Code This Demo uses the HT32 series development board and is written as the USB UVC Device. Using general video example code on the PC to open the device, the UVC device will send video data to the PC to complete an Isochronous data transmission function. After connecting to a PC, the device can be found in the Device Manager as Figure 18 shows. The device can be opened using any PC video software, such as AMCAP ( Taking AMCAP as an example, install this video software on the PC. After executing the software, select the USB-UVC Demo in the Device. Then click Option Preview, as shown in Figure 19. In the Demo, after Preview has been selected, the USB starts to upload data. The colour change screen is shown in Figure 20. Figure 18 Device Manager USB Video Device 35

36 Figure 19 Select USB video device on AMCAP Figure 20 USB Video Device Displays Colour Change Screen USB Video Class Implementation The USB Video Example Code uses an Uncompressed Payload as defined in the USB Video Device The class specification is to mount the UVC device and implement Isochronous Data Transfer. Refer to the USB Video Payload specification for more information regarding the video format definition. Endpoint Configuration The UVC device uses three endpoints for data transmission as shown in Table 24. Table 24 USB Video Example Code Endpoint Number Endpoint 0 Endpoint 1 Endpoint 4 Transfer Type Control IN or OUT Interrupt IN Isochronous IN Endpoint 0 - Control: USB Enumeration data transfer and USB request response. Endpoint 1 - Interrupt: Status return interrupt. This endpoint is optional but may be mandatory under certain conditions. Endpoint 4 - Isochronous: Mainly for video data transmission. Sends the Payload Header and Payload Data to the PC. 36

37 Class Request To implement a UVC device, the device must support the USB Class Request defined in the USB Video Class, as shown in Table 25. These functions are defined in the "ht32_usb_class.c" file. Refer to the "USB Device Class Definition for Video Devices" specification chapter 4 for more detailed information. Table 25 UVC class request Class Request GET_CUR GET_MIN GET_MAX GET_RES GET_DEF GET_LEN GET_INFO SET_CUR Description Returns the current state. Returns the minimum value. Returns the maximum value. Returns the resolution. Returns the default value. Returns the length. Queries the capabilities and status Sets the current state. Configuration The user can modify the sample code for the UVC. The Demo code provides the user with commonly used variables and isochronous data transmission functions which are convenient for user modifications according to their requirements. Change the image size as shown in Table 26. Table 26 Change Image Size File Name Definition Name Description DESC_IMAGE_WIDTH Image width ht32_usbd_class.h DESC_IMAGE_HEIGHT Image height Isochronous data transmission function void USBDClass_Endpoint4 (USBD_EPTn_Enum EPTn) The user writes the data to be transferred into this function which can then implement isochronous data transfer via the USB. This function is located in the ht32_usbd_class.c file. USB related hardware configuration The user can modify the USB related configuration in the ht32fxxxx_usbdconf.h file, as shown in Figure 21. In addition, the USB1.1 specification defines the maximum Isochronous transmission rate up to 1023 Byte/ms. The data size that the UVC device can transmit in 1ms is set by the Endpoint Buffer. The user needs to pay special attention to the above notes when implementing any related modification. Figure 21 USB Endpoint Configuration - ht32fxxxx_usbdconf.h 37

38 Virtual COM Port Introduction This chapter uses the HT32 series development board to show how to use the USB virtual COM port or VCP. It executes a simple data transmission loopback to illustrate the USB bulk IN/OUT function. The USB is a standard interface specification to connect the PC to peripheral devices. However before the USB was in existence, communication between the PC and external peripheral devices was mainly implemented using the COM port and even today there are still quite a number of peripherals around which still use this interface. The USB provides a standard class to implement a COM port function, which greatly reduces software re-development time and increases the transmission speed. The USB VCP Demo provides an HT32 series IC firmware example and a PC driver. The following sections will describe how to use this Demo. Using Virtual COM Port Example Code This Demo uses the HT32 series development board and is written as a USB VCP Class Device. It uses the Hyper Terminal on the PC to transfer data to the USB VCP Class Device on the HT32 series development board. The HT32 series development board will receive the USB data and send back to the Hyper Terminal to complete a data loopback function. The development environment is shown in Figure 22. Figure 22 Virtual Com Port Example Code Environment USB When first setting up the USB VCP Demo, it is necessary to install the program when connecting the HT32 series development board to the PC. Therefore search for HT32_VCP.inf in the USB VCP Demo and install. After the installation completed, you can find the new Holtek USB virtual COM port in the Device Manager. After the installation is completed, it can be verified in the Device Manager as shown in Figure

39 Figure 23 VCP device Device Manager Virtual COM Port Class Implementation The VCP example code uses the Abstract Control Mode as defined in the USB Communication Device Class (CDC) specification to implement a general COM port device. Endpoint Configuration The Virtual Com port device uses four endpoints for data transmission. Endpoint 0 - Control IN/OUT: USB Enumeration data transfer and response to USB standard request. Endpoint 2 - Interrupt IN: Main transfer Notification request - do not transfer any data in this Demo. Endpoint 3 - Bulk Out: Receive the COM port data from the PC. Endpoint 1 - Bulk IN: Transfer the COM port data to the PC. Class Request The Abstract Control Mode in the USB Communication devices class (CDC) defines the necessary Class-specific requests of the Virtual Com port device. SET_LINE_CODING: This command is used for configuring serial port parameters, which includes bit rate, number of Stop bits, parity, and number of data bits. GET_LINE_CODING: This command is used for requesting serial port parameters, which includes bit rate, number of Stop bits, parity, and number of data bits. SET_CONTROL_LINE_STATE: This command is used for setting Rs-232 signals RTS and DTR.a 39