HID USB Device Class API

HID USB Device API Events

1.1

The HID CRRT device API sends the following events to the application callback function:
1.
2.
3.
4.
5.
6.

1.2

USB_EVENT_CONNECTED
USB_EVENT_DISCONNECTED
USB_EVENT_ERROR
USBD_HID_EVENT_SET_REPORT
USB_EVENT_TX_COMPLETE
USB_EVENT_RX_AVAILABLE

Using the HID USB Device Class API

To add a USB HID interface to USB application using the HID Device Class Driver,
following steps are taken:
1. Adding the following header les to the source le(s) which are to support USB:
#include "src/usb.h"
#include "usblib/usblib.h"
#include "usblib/usbhid.h"
#include "usblib/device/usbdevice.h"
#include "usblib/device/usbdhid.h"

2. Dening the string table which is used to describe various features of USB device to
the host system
//********************************************************************
//
// The languages supported by this device.
//
//********************************************************************
const uint8_t g_pui8LangDescriptor[] =
{
4,
USB_DTYPE_STRING,
USBShort(USB_LANG_EN_US)
};
//********************************************************************
//
// The manufacturer string.
//
//*******************************************************************
const uint8_t g_pui8ManufacturerString[] =
{
(17 + 1) * 2,

USB_DTYPE_STRING,
T, 0, e, 0, x, 0, a, 0, s, 0, , 0, I, 0, n, 0, s, 0, t, 0, r, 0, u, 0, m, 0,
e, 0, n, 0, t, 0, s, 0,
};
//********************************************************************
//
// The product string.
//
//********************************************************************
const uint8_t g_pui8ProductString[] =
{
(12 + 1) * 2,
USB_DTYPE_STRING,
C, 0, R, 0, R, 0, T, 0, , 0, E, 0, x, 0, a, 0, m, 0, p, 0, l, 0, e, 0
}; // CRRT Example
//********************************************************************
//
// The serial number string.
//
//********************************************************************
const uint8_t g_pui8SerialNumberString[] =
{
(8 + 1) * 2,
USB_DTYPE_STRING,
1, 0, 2, 0, 3, 0, 4, 0, 5, 0, 6, 0, 7, 0, 8, 0
};
//********************************************************************
//
// The interface description string.
//
//********************************************************************
const uint8_t g_pui8HIDInterfaceString[] =
{
(18 + 1) * 2,
USB_DTYPE_STRING,
H, 0, I, 0, D, 0, , 0, C, 0, R, 0, R, 0, T, 0, , 0, I, 0, n, 0, t, 0, e, 0,
r, 0, f, 0, a, 0, c, 0, e, 0
}; //HID CRRT interface
//********************************************************************
//
// The configuration description string.
//
//********************************************************************
const uint8_t g_pui8ConfigString[] =
{
(23 + 1) * 2,
USB_DTYPE_STRING,

H, 0, I, 0, D, 0, , 0, C, 0, R, 0, R, 0, T, 0, , 0, C, 0, o, 0, n, 0, f,
0, i, 0, g, 0, u, 0, r, 0, a, 0, t, 0, i, 0, o, 0, n, 0
}; // HID CRRT Configuration
//********************************************************************
//
// The descriptor string table.
//
//********************************************************************
const uint8_t * const g_pStringDescriptors[] =
{
g_pLangDescriptor,
g_pManufacturerString,
g_pProductString,
g_pSerialNumberString,
g_pHIDInterfaceString,
g_pConfigString
};
#define NUM_STRING_DESCRIPTORS (sizeof(g_pStringDescriptors) / sizeof(uint8_t *))

3. Developing the HID report descriptors for our device.

static const uint8_t g_pCRRTClassDescriptors [] =
{
// Vendor specific value 0xff00
UsagePageVendor(0xff00),
Usage(0x01),
Collection(USB_HID_APPLICATION),
// The number of items in the report
ReportCount(MAX_PACKET_SIZE),
// 8 bits in a byte
ReportSize(0x08),
LogicalMaximum(0xFF),
LogicalMinimum(0x00),
Usage(0x01),
// Input (Data,Var,Abs)
Input(USB_HID_INPUT_DATA | USB_HID_INPUT_VARIABLE |
USB_HID_INPUT_ABS),
// Second report, same except it's output
ReportCount(MAX_PACKET_SIZE),
ReportSize(0x08),
LogicalMaximum(0xFF),
LogicalMinimum(0x00),
Usage(0x01),
Output(USB_HID_INPUT_DATA | USB_HID_INPUT_VARIABLE |
USB_HID_INPUT_ABS),
EndCollection
};
//************************************************************************

//

// The HID class descriptor table. For the CRRT class, we have only a
// single report descriptor.
//
//**************************************************************************
static const uint8_t * const g_pCRRTClassDescriptors[] =
{
g_puCCRRTReportDescriptor
};
//*************************************************************************
//
// The HID descriptor for the CRRT device.
//
//*************************************************************************
static const tHIDDescriptor g_sCRRTHIDDescriptor =
{
9,
// bLength
USB_HID_USB_HID,
// bDescriptorType
0x111,
// bcdHID (version 1.11 compliant)
0,
// bCountryCode (not localized)
1,
// bNumDescriptors
USB_HID_USB_REPORT,
// Report descriptor
sizeof(g_puCRRTReportDescriptor) // Size of report descriptor
};

4. Dening an array of tHIDReportIdle structures in RAM with one entry for each
input report CRRT device supports. Initializing the ucDuration4mS and ucReportID
elds in each of the entries to set the default idle report time for each input report. The
times dened in these structures are used to determine how often a given input report
is resent to the host in the absence of any device state change.
tHIDReportIdle g_psReportIdle[2] =
{
{ 125, 1, 0, 0 }, // Report 1 polled every 500mS (4 * 125).
{ 0, 2, 0, 0} // Report 2 is not polled (0mS timeout)
};

5. Dening a tUSBDHIDCRRTDevice structure and initializing all elds as required

for CRRT application.
const tUSBDHIDCRRTDevice g_sHIDCRRTDevice =
{
//
// The Vendor ID assigned by USB Implementers Forum = 0x1CBE
//
USB_VID_CRRT_VENDOR_ID,
//
// The product ID we have assigned for this device = 01
//
USB_PID_CRRT_PRODUCT_ID,
//

// The power consumption of your device in milliamps = 500ma

//
POWER_CONSUMPTION_MA,
//
// The value to be passed to the host in the USB configuration descriptors
// bmAttributes field = self powered
//
USB_CONF_ATTR_SELF_PWR,
//
// The device has a single input report.
//
1,
//
// A pointer to array of tHIDReportIdle(to track automatic resending). For this
// device, the array must have 1 element (matching the value of the previous field).
//
g_psCRRTReportIdle,
//
// A pointer to receive callback event handler.
//
CRRTUSBReceiveEventCallback,
//
// A value that you want passed to the receive callback alongside every
// event.
//
(void *)&g_sCRRTInstanceData,
//
// A pointer to transmit callback event handler.
//
CRRTUSBTransmitEventCallback,
//
// A value that you we passed to the transmit callback alongside every
// event.
//
(void *)&g_sCRRTInstanceData,
//
// This device does not want to use a dedicated interrupt OUT endpoint
// since there are no output or feature reports required.
//
false,
//
// A pointer to the HID descriptor for the device.
//
//
&g_sCRRTHIDDescriptor,
//
// A pointer to the array of HID class descriptor pointers for this device.
// The number of elements in this array and their order must match the

// information in the HID descriptor provided above.

//
g_pCRRTClassDescriptors,
//
// A pointer to your string table.
//
g_pStringDescriptors,
//
// The number of entries in your string table. This must equal
// (1 + (5 + (num HID strings)) * (num languages)).
//
NUM_STRING_DESCRIPTORS
};

6. Adding a receive event handler function, CRRTUSBReceiveEventCallback to our

application taking care to handle all messages which require a particular response. For
the HID device class the following receive callback events MUST be handled by the
application:
USB_EVENT_RX_AVAILABLE
USBD_HID_EVENT_IDLE_TIMEOUT
USBD_HID_EVENT_GET_REPORT
Although no other events must be handled, USB_EVENT_CONNECTED and
USB_EVENT_DISCONNECTED is typically be required since these indicate when
a host connects or disconnects and allow the application to ush any buffers or reset
state as required. Attempts to send data when the host is disconnected are ignored and
result in an error.
7. Adding a transmit event handler function, CRRTUSBTransmitEventCallback to the
application and using USB_EVENT_TX_COMPLETE to indicate when a new
report may be scheduled for transmission. While a report is being transmitted,
attempts to send another report via USBDHIDReportWrite() are ignored and results
in an error.
8. From the main initialization function call the HID device class driver initialization
function to congure the USB controller and place the device on the bus.
pvDevice = USBDHIDMouseInit(0, &g_sHIDCRRTDevice);

9. Assuming pvDevice returned is not NULL, your device is now ready to communicate
with a USB host.
10. Once the host connects, your control event handler is sent
USB_EVENT_CONNECTED and the rst input report may be sent to the host using
USBDHIDReportWrite() with following packets transmitted as soon as
USB_EVENT_TX_COMPLETE is received via the transmit event handler.

1.3

Initialization flowchart

SysCtlClockFreqSet();
uint32_t SysCtlClockFreqSet(uint32_t ui32Config, uint32_t ui32SysClock);
This function configures the system clocking to 120 MHz with a 480 MHz PLL.
param ui32Config = 480MHz
param ui32SysClock = 120MHz
Return: The actual configured system clock frequency in Hz or zero if the value could not be
changed due to a parameter error or PLL lock failure.

PinoutSet();
Void PinoutSet(void)
This function enables the GPIO modules and configures the device pins for USB operation.
Used to configures PL6 as DP and PL7 as DM.

USBStackModeSet ( );
Void USBStackModeSet(uint32_t ui32Index, tUSBMode iUSBMode, tUSBModeCallback
pfnCallback)
Allows dual mode application to switch to device modes.
Param ui32Index = 0, specifies the USB controller whose mode of operation is to be set.
Param iUSBMode = 0, indicates the mode that the application wishes to operate = 0, for
device mode
Param pfnCallback is a pointer to a function which the USB library will call each time the
mode is changed to indicate the new operating mode.

USBDHIDMouseInit ( );
USBDHIDMouseInit(uint32_t ui32Index, tUSBDHIDMouseDevice *psMouseDevice)
Initialize the USB controller and attach the device to the USB bus. This function performs all
required USB initialization.
Param ui32Index=0, the index of the USB controller which is to be initialized for HID
mouse device operation.
Param psMouseDevice = &g_sHIDCRRTDevice, points to a structure containing
parameters customizing the operation of the HID device.

1.4

Tx Enable flow chart

1.5

Tx Handler flow chart

USBDHIDReportWrite()
Transmits a HID device report to the USB host via the HID interrupt IN endpoint.
pvHIDInstance = &g_sHIDCRRTDevice, is the pointer to the device instance
structure as returned by USBDHIDInit().
pi8Data = ptrTxBuff, points to the rst byte of data which is to be transmitted.
ui32Length = BUFF_SIZE = 64 bytes, is the number of bytes of data to transmit.

bLast=0, is ignored in this implementation. This parameter is required to ensure

compatibility with other device class drivers and USB buffers.

1.6

Rx Handler flow chart

USBDHIDPacketRead( )
Reads a packet of data received from the USB host via the interrupt OUT endpoint.
pvHIDInstance=&g_sHIDCRRTDevice, is the pointer to the device instance
structure as returned by USBDHIDInit().
pi8Data= HostRxBuffx, points to a buffer into which the received data will be
written.
ui32Length= sizeof(HostRxBuff1), is the size of the buffer pointed to by pi8Data.
bLast = 0, indicates whether the client will make a further call to read additional data
from the packet.

1.7

ISR flow chart

1.8

Initialization flow chart in detail

USBDHIDCompositeInit( );
void * USBDHIDCompositeInit(uint32_t ui32Index, tUSBDHIDDevice
*psHIDKbDevice, tCompositeEntry *psCompEntry)
Initializes HID device operation.
Param ui32Index = 0, is the index of the USB controller which is to be initialized for HID
device operation.
Param psHIDKbDevice = descriptors, points to a structure containing device, configuration,
interface and endpoint descriptors customizing the operation of the HID device.
Param psCompEntry=0, is the composite device entry to initialize when creating a
composite device.
Returns zero on failure or a non-zero instance value that should be used with the remaining

USB HID APIs.

USBDCDConfigGetInterfaceEndpoint( );
tEndpointDescriptor *USBDCDConfigGetInterfaceEndpoint(const tConfigHeader
*psConfig, uint32_t ui32InterfaceNumber, uint32_t ui32Index)
Return a pointer to the n-th endpoint descriptor in a particular interface within a configuration
descriptor.
Param psConfig= pointer to descriptor, points to the header structure for the configuration
descriptor that is to be searched.
Param ui32InterfaceNumber = ptr to device information, is the interface number whose
endpoint is to be found.
Param ui32Index = 0 for device descriptor and 1 for other descriptor, is the zero based index
of the endpoint that is to be found within the appropriate alternate setting for the interface.
Returns a pointer to the requested endpoint descriptor if found or NULL otherwise.

USBDCDDeviceInfoInit( );
Void USBDCDDeviceInfoInit(uint32_t ui32Index, tDeviceInfo *psDeviceInfo)
Initialize an instance of the tDeviceInfo structure.
Param ui32Index = 0, is the index of the USB controller which is to be initialized.
Param psDeviceInfo = pointer to descriptors.

MAP_SysCtlPeripheralReset();
Void SysCtlPeripheralReset(uint32_t ui32Peripheral).
Performs a software reset of a peripheral.
Param ui32Peripheral = 0xf0002800 for USB 0, is the peripheral to reset.

USBDevLPMDisable( );
Void USBDevLPMDisable(uint32_t ui32Base)
Disables the USB controller from responding to LPM suspend requests.
Param ui32Base = 0x40050000 for USB 0, specifies the USB module base address.

USBLibDMAInit( );
tUSBDMAInstance *USBLibDMAInit(uint32_t ui32Index)
This function is used to initialize the DMA interface for a USB instance.
param ui32Index = 0, is the index of the USB controller for this instance.

Returns a pointer to use with USBLibDMA APIs.

USBDevConnect( );
Void USBDevConnect(uint32_t ui32Base)
Connects the USB controller to the bus in device mode.
Param ui32Base = 0x40050000 for USB 0, specifies the USB module base address.

IntEnable( );
IntEnable(uint32_t ui32Interrupt)
The specified interrupt is enabled in the interrupt controller.
Param ui32Interrupt = MemManage, bus fault, usage fault, or general interrupt to be
enabled.