HT32 Series USB Device Development Kit · API_USB_CLR_RESET_INT() Clear reset interrupt....

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


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


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

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.

ht32fxxxx_usbd.h Peripheral driver header file.

ht32fxxxx_usbdinit.h Header file checks and processes the definitions from

the “ht32fxxxx_usbdconf.h” file.

USB peripheral

driver

ht32fxxxx_usbd.c Peripheral driver source file.

ht32_usbd_core.h USB core header file. USB core

ht32f_usbd_core.c USB core source file.

ht32f_usbd_class.c Class example code source file.

ht32f_usbd_class.h Class example code header file .

ht32_usbd_descriptor.c Descriptor source file. Application

ht32_usbd_descriptor.h Descriptor header file.

CCllaassss // DDeessccrriippttoorr // AApppplliiccaattiioonn

UUSSBB CCoorree

UUSSBB DDrriivveerr

3


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

Function Name

Prefix_FunctionName (module name prefix)

USBDCore_FunctionName: USB core

USBD_FunctionName: USB driver

USBDClass_FunctionName: Class application

All the function names add the module

name prefix to help the user identify

which function belongs to which module.

API Macro

API_USB_NAME(Parameter)

#define API_USB_INIT(driver)

(USBD_Init(driver))

The USB core layer uses the API Macro

definitions as the interface to the USB

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

definition

#define DEFINE_NAME

#define DESC_LEN_HID ((u32)(9)) Definitions are all uppercase.

Enumeration type

definition

Prefix_NAME_Enum

typedef enum

{

….

} USBD_EPTn_Enum;

Starts with a module name prefix and

ends with an “Enum”.

Structure type

definition

Prefix_NAME_TypeDef

typedef struct

{

…

} USBDCore_Info_TypeDef;

Starts with a module name prefix and

ends with a “TypeDef”.

Pointer: u32 *pDriver; Pointer with “p” prefix.

u8/u16/u32: u32 uPara; Unsigned variables with “u” prefix.

s8/s16/s32: s32 sByteLength; Signed variables with “s” prefix. Variable

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


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_usb.h HT32 firmware library API for the USB core. The USB core includes this file

to know the peripheral driver file names.

ht32fxxxx_usbd (.h, .c) Peripheral driver which provides hardware initialisation, register level

accessing and endpoint buffer accessing functions.

ht32fxxxx_usbdinit.h This file provides preprocessor checking of the parameters which are

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 Description

void USBD_Init(u32 *pDriver); USB device peripheral initialisation including endpoint initial

value, power control, and interrupt mask.

void USBD_PreInit(USBD_Driver_TypeDef

*pDriver);

This function initiates the "USBD_Driver_TypeDef"

structure using values from the “ht32fxxxx_usbdconf.h” file

in the application layer.

void USBD_DeInit(void); USB device peripheral de-initialisation.

void USBD_PowerOff(void); Enter USB device power down mode.

void USBD_PowerOn(void); Exit USB device power down mode.

void USBD_RemoteWakeup(void); Generate a resume request to the USB host for a remote

wakeup function.

void USBD_ReadSETUPData(u32 *pBuffer); Read Endpoint 0 SETUP data from USB buffer.

void USBD_SetAddress(u32 address); Set USB device address.

void USBD_EnableINT(u32 INTFlag); Enable USB device interrupt.

void USBD_DisableINT(u32 INTFlag); Disable USB device interrupt.

u32 USBD_GetINT(void); Get USB device interrupt flag.

void USBD_ClearINT(u32 INTFlag); Clear USB device interrupt flag.

USBD_EPTn_Enum

USBD_GetEPTnINTNumber(u32 INTFlag); Get active USB interrupt endpoint number.

5


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


void USBD_EPTInit(USBD_EPTn_Enum EPTn, u32 *pDriver); Endpoint initialisation including

control and interrupt register.

void USBD_EPTReset(USBD_EPTn_Enum EPTn); Reset endpoint to default status.

void USBD_EPTEnableINT(USBD_EPTn_Enum EPTn, u32 INTFlag); Enable endpoint interrupt source.

u32 USBD_EPTGetINT(USBD_EPTn_Enum EPTn); Get endpoint interrupt flag.

void USBD_EPTClearINT(USBD_EPTn_Enum EPTn, u32 INTFlag); Clear endpoint interrupt flag.

u32 USBD_EPTGetHalt(USBD_EPTn_Enum EPTn); Get endpoint halt status.

void USBD_EPTSendSTALL(USBD_EPTn_Enum EPTn); Send STALL on specific endpoint.

void USBD_EPTSetHalt(USBD_EPTn_Enum EPTn); Set endpoint halt status.

void USBD_EPTClearHalt(USBD_EPTn_Enum EPTn); Clear endpoint halt status.

void USBD_EPTWaitSTALLSent(USBD_EPTn_Enum EPTn); Wait until STALL sent.

void USBD_EPTClearDTG(USBD_EPTn_Enum EPTn); Clear endpoint data toggle bit.

u32 USBD_EPTGetBuffer0Addr(USBD_EPTn_Enum EPTn); Get endpoint buffer 0 address.

u32 USBD_EPTGetBuffer1Addr(USBD_EPTn_Enum EPTn); Get endpoint buffer 1 address.

u32 USBD_EPTGetBufferLen(USBD_EPTn_Enum EPTn); Get endpoint buffer length.

u32 USBD_EPTGetTransferCount(USBD_EPTn_Enum EPTn,

USBD_TCR_Enum type); Get endpoint transfer count.

u32 USBD_EPTWriteINData(USBD_EPTn_Enum EPTn, u32 *pFrom,

u32 len); Write IN data to USB buffer.

u32 USBD_EPTReadOUTData(USBD_EPTn_Enum EPTn, u32 *pTo,

u32 len);

Read OUT data from endpoint

buffer and then clear NAK bit.

u32 USBD_EPTReadMemory(USBD_EPTn_Enum EPTn, u32 *pTo,

u32 len);

Read OUT data from endpoint

buffer.

6


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 Description

Global API Macro

API_USB_INIT(driver) USB device peripheral initialisation API macro which

is called by the USBDCore_Init() function.

API_USB_DEINIT()

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_USB_POWER_OFF() API macro used to turn off the USB device power.

API_USB_POWER_ON() API macro used to turn on the USB device power.

API_USB_REMOTE_WAKEUP() API macro used to generate a resume request to the

USB Host for remote wakeup function.

API_USB_READ_SETUP(buffer) Read SETUP data from USB buffer.

API_USB_SET_ADDR(addr) Set USB device address.

API_USB_GET_CTRL_IN_LEN() Get CONTROL IN data length.

API_USB_ENABLE_INT(flag) Enable global interrupt.

API_USB_GET_INT() Get global interrupt flag.

API_USB_GET_EPT_NUM(flag) Get active USB interrupt endpoint number.

API_USB_IS_RESET_INT(flag) Decide if a reset interrupt occurred.

API_USB_CLR_RESET_INT() Clear reset interrupt.

API_USB_IS_SOF_INT(flag) Decide if start of frame interrupt occurred.

API_USB_CLR_SOF_INT() Clear start of frame interrupt.

API_USB_IS_RESUME_INT(flag) Decide if resume interrupt occurred.

API_USB_CLR_RESUME_INT() Clear resume interrupt.

API_USB_IS_SUSPEND_INT(flag) Decide if suspend interrupt occurred.

API_USB_CLR_SUSPEND_INT() Clear suspend interrupt.

API_USB_IS_EPTn_INT(flag, EPTn) Decide if endpoint interrupt occurred.

API_USB_CLR_EPTn_INT(EPTn) Clear endpoint interrupt.

Endpoint API Macro

API_USB_EPTn_INIT(EPTn, driver) Endpoint initialisation API macro which is called by

the Set Configuration standard command.

API_USB_EPTn_RESET(EPTn) Reset endpoint into its default status.

API_USB_EPTn_SEND_STALL(EPTn) Send STALL on specific endpoint.

API_USB_EPTn_GET_INT(EPTn) Get endpoint interrupt flag.

API_USB_EPTn_IS_IN_INT(flag) Decide if an endpoint IN interrupt occurred.

API_USB_EPTn_CLR_IN_INT(EPTn) Clear endpoint IN interrupt flag.

7


8

API Macro Name Description

API_USB_EPTn_IS_OUT_INT(flag) Decide if an endpoint OUT interrupt occurred.

API_USB_EPTn_CLR_OUT_INT(EPTn) Clear endpoint OUT interrupt flag.

API_USB_EPTn_IS_INT(flag) Decide if an endpoint IN or OUT interrupt occurred.

API_USB_EPTn_CLR_INT(EPTn) Clear endpoint IN and OUT interrupt flag.

API_USB_EPTn_GET_HALT(EPTn) Get endpoint halt status.

API_USB_EPTn_SET_HALT(EPTn) Set endpoint halt status.

API_USB_EPTn_CLR_HALT(EPTn) Clear endpoint halt status.

API_USB_EPTn_WAIT_STALL_SENT(EPTn) Wait until STALL sent.

API_USB_EPTn_CLR_DTG(EPTn) Clear endpoint data toggle bit.

API_USB_EPTn_GET_BUFFLEN(EPTn) Get endpoint buffer length.

API_USB_EPTn_GET_CNT(EPTn, type) Get endpoint transfer count.

API_USB_EPTn_WRITE_IN(EPTn, from, len) Write IN data to USB buffer.

API_USB_EPTn_READ_OUT(EPTn, to, len) Read OUT data from endpoint buffer and then clear

NAK bit.

API_USB_EPTn_READ_MEM(EPTn, to, len) 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

ht32_usbd_core (.h, .c) USB core module including USB bus event handler, standard request,

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.


Table 8 USB Core Variable Architecture

Name (type) Description

bmRequestType: Request Characteristics.

bRequest: Specific request.

wValueL: Low byte of request parameter.

wValueH: High byte of request parameter.

wIndex: Request parameter.

Request.

(USBDCore_Req

uest_TypeDef)

wLength: Number of bytes to transfer in data stage.

pDeviceDesc: Data pointer of Device Descriptor.

pConfnDesc: Configuration Descriptor Data Pointer.

Desc.

(USBDCore_Des

c_TypeDef) pStringDesc[n]: String Descriptor Data Pointer.

uBuffer[2]: Temporary Buffer.

pData: Control IN/OUT Data Pointer.

sByteLength: Total length for control IN/OUT

Transfer.

Action: STALL, control IN or control OUT.

(USBDCore_Action_Enum)

Device.

(USBDCore_De

vice_TypeDef)

Transfer.

(USBDCore_Tran

sfer_TypeDef)

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)

LastStatus: Device State before SUSPEND. (USBDCore_Status_Enum)

CurrentFeature: For Set/ClearFeature and GetStatus request.

(USBDCore_Feature_TypeDef)

Info.

(USBDCore_Inf

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

CallBack_ClassGetDescriptor: Class Get Descriptor call back function.

CallBack_ClassSetInterface(pDev): Class Set Interface call back

function.

CallBack_ClassRequest(pDev): Class Request call back function.

Class.

(USBDCore_Cla

ss_TypeDef)

CallBack_EPTn[MAX_EP_NUM](EPTn): Endpoint n call back function.

pDriver (u32) USB Device Driver initialisation structure.

USBCore.

(USBDCore_

TypeDef)

Power.

(USBDCore_Po

wer_TypeDef)

CallBack_Suspend.func/uPara: System low power function/parameter

for SUSPEND.

9


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

Reset _USBDCore_Reset(pCore);

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

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 _USBDCore_Setup(pCore);

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.

Control Endpoint IN data

transmitted _USBDCore_ControlIN (pCore);

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.

Control Endpoint OUT

data ready _USBDCore_ControlOUT (pCore);

When the control OUT data has been

received, the USB core uses this function

to process the OUT data.

Endpoint n IN data

transmitted Endpoint n

OUT data ready

pCore->Class.CallBack_EPTn

[EPTn](EPTn);

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


Initialisation and system API

void USBDCore_Init(USBDCore_TypeDef *pCore); USB core initialisation.

void USBDCore_IRQHandler(USBDCore_TypeDef *pCore); USB core Interrupt service routine.

void USBDCore_MainRoutine(USBDCore_TypeDef *pCore); USB core main routine for

application.

u32 USBDCore_IsSuspend(USBDCore_TypeDef *pCore); Return suspend status.

u32 USBDCore_GetRemoteWakeUpFeature(USBDCore_TypeDef *pCore);

Return remote wake status which is

set by SET FEATURE standard

command.

void USBDCore_TriggerRemoteWakeup(void); Turn on the USB power and remotely

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,

USBD_TCR_Enum type); Get endpoint transfer count of.

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

*pFrom, u32 len); Write IN data to USB buffer.

u32 USBDCore_EPTReadOUTData(USBD_EPTn_Enum EPTn,

u32 *pTo, u32 len);

Read OUT data from endpoint buffer

and then clear NAK bit.

u32 USBDCore_EPTReadMemory(USBD_EPTn_Enum EPTn, u32

*pTo, u32 len); Read OUT data from endpoint buffer.


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

ht32fxxxx_usbdconf.h The USB Device configurations file. It includes interrupt and endpoint related

setting of the USB device IP.

ht32_usbd_descriptor (.c, .h)

USB device descriptor including device, configuration, and, string. This

module provides initialisation functions for setup of the data pointer of the

descriptor for the USB core to get a descriptor request.

ht32f_usbd_class (.c, .h) Class related function including initialisation, main routine, standard request

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


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 Description

Endpoint Address No need to modify for general cases.

Endpoint Enable Shall be turned on before using the endpoint.

Endpoint Transfer Type Endpoint 1 ~ 3: Bulk or Interrupt

Endpoint 4 ~ 7: Isochronous, Bulk, or Interrupt.

Endpoint Direction IN or OUT

Endpoint Buffer Length

Interrupt: 1 ~ 64 bytes

Bulk: 8, 16, 32, or 64 bytes

Isochronous: 1 ~ 1023 (Note: Since at least 8 + 8 bytes of USB buffer are

reserved for SETUP data and endpoint 0, the actual maximum buffer length

of Isochronous endpoint is 1008 bytes)

Endpoint Interrupt Enable

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


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


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); /* Initiate memory pointer of descriptor */ USBDClass_Init(&gUSBCore.Class); /* Initiate USB Class layer */ USBDCore_Init(&gUSBCore); /* 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 */ ... } ... }

16


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


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


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


USBDCore_EPTWriteINData Write IN data to USB buffer.

USBDCore_EPTReadOUTData Read OUT data from endpoint buffer and then clear NAK bit.

USBDCore_EPTReadMemory 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; ...

}


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


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


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


Human Interface Device ‒ HID

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


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++ 2005. 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


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


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)

Output Report (ReadFile) Endpoint 2 (OUT)

Save to gOutputReportBuffer and copy to

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


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


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

ht32f_usbd_class (.c, .h) The middle layer between the USB core and BOT protocol. Is in

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


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.


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.

PREVENT ALLOW MEDIUM

REMOVAL 0x1E

The ALLOW MEDIUM REMOVAL command

requests that the logical unit enables or disables the

removal of the medium.

READ CAPACITY (10) 0x25

The READ CAPACITY (10) command requests that

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


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

u32 uId;

Unique ID for media. This ID is used to identify different media on the

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 Description

u32 RAMDISK_Read(u32 uId, u8 **pBuffer,

u32 uAddress, u32 uLength);

Read media based on the parameters. The SCSI read

command uses this function to read from the media.

u32 RAMDISK_Write(u32 uId, u8 *pBuffer,

u32 uAddress, u32 uLength);

Write media based on the parameters. The SCSI write

command uses this function to write to the media.

u32 RAMDISK_GetStatus(u32 uId,

BOT_MediaSize_Typedef *pSizeInfo);

This function is used to report the status of media. The

SCSI test unit ready command uses this function to test the

media status.


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 Transfer Type

Endpoint 0 Control IN or OUT

Endpoint 1 Bulk IN

Endpoint 2 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 Description

Bulk-Only Mass Storage ResetThis request is used to reset the mass storage device and its associated

interface.

Get Max LUN

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.


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

(http://noeld.com/programs.asp?cat=video). 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


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.


The UVC device uses three endpoints for data transmission as shown in Table 24.

Table 24 USB Video Example Code

Endpoint Number Transfer Type

Endpoint 0 Control IN or OUT

Endpoint 1 Interrupt IN

Endpoint 4 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


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 Description

GET_CUR Returns the current state.

GET_MIN Returns the minimum value.

GET_MAX Returns the maximum value.

GET_RES Returns the resolution.

GET_DEF Returns the default value.

GET_LEN Returns the length.

GET_INFO Queries the capabilities and status

SET_CUR 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


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

38


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.


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

Date post:	21-Jul-2020
Category:	Documents
Upload:	others
View:	15 times
Download:	0 times

HT32 Series USB Device Development Kit · API_USB_CLR_RESET_INT() Clear reset interrupt....

Documents