AN1143
Generic Client Driver for a USB Embedded Host
For more information about USB transfers, please refer
Authors: Kim Otten and Bud Caldwell
to Microchip Application Note AN1140, “USB Embedded
Microchip Technology Inc.
Host Stack “.
INTRODUCTION ABOUT THE DRIVER
With the introduction of Microchip's microcontrollers with The Generic Client Driver provided with the Microchip
the USB OTG peripheral, microcontroller applications USB Embedded Host Stack provides support for a
can easily support USB embedded host functionality. device with one IN endpoint (i.e., data transfer to the
Many devices fall under one of the defined USB classes, host) and one OUT endpoint (data transfer from the
such as Mass Storage Device (thumb drives and host), in addition to Endpoint 0. By default, Endpoint 1
external hard drives), Human Interface Device (or HID, is used. The transfer type for these endpoints can be
such as computer mice), Printer and so on. Some any of the four possible transfer types: control, bulk,
devices, however, do not fit well within the restrictions of interrupt or isochronous. The USB Embedded Host
these classes. Instead, they utilize the fundamental USB Driver will manage the specific timing and packet size
transfers without any additional protocols. requirements of whatever transfer type is used.
Microchip provides a USB Generic Client Driver to The type, length and format of the data transferred is
facilitate USB communication with these unclassified or totally application dependent. The only requirement is
vendor-specific devices. This application note provides that both the USB peripheral device and the USB
a brief overview on its configuration and use. embedded host are aware of the data format.
USB TRANSFERS USING THE GENERIC CLIENT
The USB Specification defines four different types of DRIVER
transfers:
• Control Transfers: Used to configure a device at Application Architecture
attach time and can be used for other device- Functionally, the Generic Client Driver is a layer
specific purposes, including control of other pipes between the application software and the embedded
on the device. host USB driver. The general architecture is shown in
• Bulk Data Transfers: Generated or consumed in Figure 1.
relatively large and “bursty” quantities and have
wide dynamic latitude in transmission constraints FIGURE 1: APPLICATION
(e.g., printers and mass storage devices).
ARCHITECTURE
• Interrupt Data Transfers: Used for timely but
reliable delivery of data. For example, characters
or coordinates with human perceptible echo or
feedback response characteristics (e.g.,
keyboards, mice and joysticks). Application
• Isochronous Data Transfers: Occupy a
Generic Client Driver
pre-negotiated amount of USB bandwidth with a
pre-negotiated delivery latency (e.g., audio data). Embedded Host Driver
These are also called streaming real-time
transfers.
Control transfers are typically performed on Endpoint 0,
and are performed automatically by the USB Embedded
Host Stack. Application level transfers are usually on
other endpoints, and are bulk, interrupt or isochronous,
depending on the type of application.
© 2009 Microchip Technology Inc. DS01143A-page 1
AN1143
Configuring the Generic Client Driver 1. From the Main tab (Figure 2):
a) Select the Target Device Family from the
Use the USB configuration tool, USBConfig.exe, or
drop-down combo box.
the USB library configuration tool provided in the
MPLAB® IDE VDI to configure the Generic Client b) Select the Device Type. To use the Generic
Driver. The tool generates two files which must be Client Driver, the device must be an embed-
included in the project: usb_config.c and ded host. The USB Embedded Host, USB
usb_config.h. Dual Role and USB OTG options all provide
embedded host functionality.
There are items to configure in four of the tabs, in the
c) Select the Ping-Pong Buffer mode, if
following order:
applicable. Using Ping-Pong mode requires
more data memory, but results in higher
data throughput.
FIGURE 2: CONFIGURATION TOOL, MAIN TAB
DS01143A-page 2 © 2009 Microchip Technology Inc.
AN1143
2. From the Host tab (Figure 3): b) If the host application will utilize transfer
a) Enable the transfer type that the USB events, check Generate Transfer Events.
peripheral device uses. The transfer type Otherwise, the application must poll for
used by the USB peripheral is transparent transfer completion. Refer to the “Generic
to the application. As long as the application Client Driver Events” section for more
provides support for the transfer type, the information on transfer events.
application can communicate with the
peripheral.
FIGURE 3: CONFIGURATION TOOL, HOST TAB
© 2009 Microchip Technology Inc. DS01143A-page 3
AN1143
3. From the TPL tab (Figure 4), add support for c) At the Client Driver drop-down combo box,
each of the required devices. All devices select Generic.
supported by the Generic Client Driver must be d) Fill in the Initial Configuration and Initial-
supported by VID and PID, since there are no ization Flags fields, as needed. Currently,
class identifiers. the Generic Client Driver does not use
For each device to be supported: these fields; leave them as 0.
a) Enter a brief text description of the peripheral e) Click Add to TPL to update the Targeted
device in the Description field. Peripheral List.
b) Select Support via VID/PID, then enter the
hexadecimal values for the USB Vendor ID
and Product ID in the appropriate fields.
These values must be entered in hexa-
decimal, in the format ‘0xnnnn’, as shown in
the figure.
FIGURE 4: CONFIGURATION TOOL, TPL TAB
DS01143A-page 4 © 2009 Microchip Technology Inc.
AN1143
4. From the Generic tab (Figure 5): c) The USB specification requires that a
a) If you want the Generic Client Driver to utilize transfer should not be terminated as long as
device serial numbers, check Include Serial a device returns a NAK. In an embedded
Number Support and indicate the application, transfers are often terminated
maximum length of the serial number. after a certain time-out duration. If you
b) If Generate Transfer Events is checked on would like the stack to automatically termi-
the Host tab, then the Generic Client Driver nate a transfer if no response is received
will also generate transfer events. Other- within a certain time, check Enable NAK
wise, the application must poll for transfer Timeout and adjust the Number of NAK’s
completion. Allowed for the transfer type specified on
the Host tab.
FIGURE 5: CONFIGURATION TOOL, GENERIC TAB
© 2009 Microchip Technology Inc. DS01143A-page 5
AN1143
Generic Client Driver Events Communicating with the USB Peripheral
The Generic Client Driver generates four events: After the application receives the
• EVENT_GENERIC_ATTACH: This event indicates EVENT_GENERIC_ATTACH event, it can communicate
that a generic device has been attached. The with the USB peripheral. The available function calls
address of the attached device is sent with the are summarized in Example 1.
event, as well as the VID, PID and serial number Note: Refer to the Help file documentation
(if supported). installed with the USB Embedded Host
• EVENT_GENERIC_DETACH: This event indicates Stack for the complete list of API calls.
that a generic device has detached from the bus.
Depending on its structure, the application may use
The address previously used by the device is sent
four of these function calls. All applications use the
with the event.
function calls, USBHostGenericRead() and
• EVENT_GENERIC_TX_DONE: This event indicates USBHostGenericWrite(), to communicate with
that a write request has completed. This event will the device after it is attached.
be sent only if transfer events are enabled.
Otherwise, the application must poll for transfer If the application does not use transfer events, the appli-
completion status. cation will use USBHostGenericRxIsComplete()
and USBHostGenericTxIsComplete() to determine
• EVENT_GENERIC_RX_DONE: This event indicates
if the transfer is complete. An example of their use is
that a read request has completed. This event will
shown in Example 2.
be sent only if transfer events are enabled.
Otherwise, the application must poll for transfer If the application uses transfer events, the application
completion status. will receive the EVENT_GENERIC_RX_DONE event when
a read terminates and the EVENT_GENERIC_TX_DONE
These events should be handled in the event handler
event when a write terminates. Before initiating a trans-
specified in the Name of Application Event Handler
fer, the application can see if a transfer is already in
field on the Host tab (Figure 3). For more information
progress by using USBHostGenericRxIsBusy()and
about the function prototype and structure of the event
USBHostGenericTxIsBusy(). An example of their
handler, refer to Microchip Application Note AN1140,
use is shown in Example 3.
“USB Embedded Host Stack”.
EXAMPLE 1: GENERIC CLIENT DRIVER FUNCTION PROTOTYPES
For Communications:
BYTE USBHostGenericRead( BYTE deviceAddress, void *buffer, DWORD length);
BYTE USBHostGenericWrite( BYTE deviceAddress, void *buffer, DWORD length);
For Applications Not Using Transfer Events:
BOOL USBHostGenericRxIsComplete( BYTE deviceAddress, BYTE *errorCode, DWORD *byteCount );
BOOL USBHostGenericTxIsComplete( BYTE deviceAddress, BYTE *errorCode );
For Applications Using Transfer Events:
BOOL USBHostGenericRxIsBusy( BYTE deviceAddress );
BOOL USBHostGenericTxIsBusy( BYTE deviceAddress );
EXAMPLE 2: STARTING A READ USING POLLING
if (USBHostGenericRxIsComplete( deviceAddress,&errorCode,&byteCount ))
{
USBHostGenericRead( deviceAddress, &buffer,
sizeof( buffer ) );
}
EXAMPLE 3: STARTING A READ USING TRANSFER EVENTS
if (!USBHostGenericRxIsBusy( deviceAddress ))
{
USBHostGenericRead( deviceAddress, &buffer,
sizeof( buffer ) );
}
DS01143A-page 6 © 2009 Microchip Technology Inc.
AN1143
DEMONSTRATION PROGRAM REFERENCES
The USB Embedded Host Generic Client Driver is The following application notes pertain specifically to
installed with the USB software support packages the Generic Client Driver:
available for download from the Microchip web site, at • Microchip Application Note AN1140, “USB
www.microchip.com/USB. Refer to the Release Notes Embedded Host Stack” (DS01140)
for the installation location of the Generic Client Driver
• Microchip Application Note AN1141, “USB
files.
Embedded Host Stack Programmer's Guide”
One demonstration project is provided for the Generic (DS01141)
Client Driver. This project shows how to use the driver
Additional detailed information is available in the Help
to communicate with the USB Peripheral Generic
file installed with the Microchip USB Embedded Host
Device Driver. Refer to the Release Notes for the
Stack. This file is located in the directory path:
installation location of the demonstration.
.\Microchip\Help
To use the projects:
For more information on components of the Microchip
1. Program one Explorer 16 Demonstration Board USB solutions, as well as more USB Embedded Host
with the USB embedded host example. Client Drivers and Peripheral Function Drivers, visit the
2. Program another demonstration board (either a Microchip USB Design Center at:
second Explorer 16 board or a PICDEM™ FS www.microchip.com/usb
USB Demonstration Board) with the USB For more information on USB in general:
peripheral example.
• USB Implementers Forum, “Universal Serial Bus
3. Connect the two boards using a USB cable and
Revision 2.0 Specification”,
allow them to execute.
http://www.usb.org/developers/docs/
The USB peripheral device reads the temperature and
potentiometer value on its demo board. The USB
embedded host example requests this information from
the USB peripheral and displays the information on the
LCD. For more information about these projects, refer
to the additional documentation installed with each of
them.
CONCLUSION
Many USB peripheral devices utilize one of the
standard USB classes, but some do not. The USB
Embedded Host Generic Client Driver provides a
simple mechanism to interface with a USB peripheral
that does not fall under a standard USB class.
© 2009 Microchip Technology Inc. DS01143A-page 7
AN1143
NOTES:
DS01143A-page 8 © 2009 Microchip Technology Inc.
Note the following details of the code protection feature on Microchip devices:
• Microchip products meet the specification contained in their particular Microchip Data Sheet.
• Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the
intended manner and under normal conditions.
• There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our
knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data
Sheets. Most likely, the person doing so is engaged in theft of intellectual property.
• Microchip is willing to work with the customer who is concerned about the integrity of their code.
• Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not
mean that we are guaranteeing the product as “unbreakable.”
Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our
products. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts
allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act.
Information contained in this publication regarding device Trademarks
applications and the like is provided only for your convenience
The Microchip name and logo, the Microchip logo, Accuron,
and may be superseded by updates. It is your responsibility to
dsPIC, KEELOQ, KEELOQ logo, MPLAB, PIC, PICmicro,
ensure that your application meets with your specifications.
PICSTART, rfPIC, SmartShunt and UNI/O are registered
MICROCHIP MAKES NO REPRESENTATIONS OR
trademarks of Microchip Technology Incorporated in the
WARRANTIES OF ANY KIND WHETHER EXPRESS OR
U.S.A. and other countries.
IMPLIED, WRITTEN OR ORAL, STATUTORY OR
OTHERWISE, RELATED TO THE INFORMATION, FilterLab, Linear Active Thermistor, MXDEV, MXLAB,
INCLUDING BUT NOT LIMITED TO ITS CONDITION, SEEVAL, SmartSensor and The Embedded Control Solutions
QUALITY, PERFORMANCE, MERCHANTABILITY OR Company are registered trademarks of Microchip Technology
FITNESS FOR PURPOSE. Microchip disclaims all liability Incorporated in the U.S.A.
arising from this information and its use. Use of Microchip Analog-for-the-Digital Age, Application Maestro, CodeGuard,
devices in life support and/or safety applications is entirely at dsPICDEM, dsPICDEM.net, dsPICworks, dsSPEAK, ECAN,
the buyer’s risk, and the buyer agrees to defend, indemnify and ECONOMONITOR, FanSense, In-Circuit Serial
hold harmless Microchip from any and all damages, claims, Programming, ICSP, ICEPIC, Mindi, MiWi, MPASM, MPLAB
suits, or expenses resulting from such use. No licenses are Certified logo, MPLIB, MPLINK, mTouch, PICkit, PICDEM,
conveyed, implicitly or otherwise, under any Microchip PICDEM.net, PICtail, PIC32 logo, PowerCal, PowerInfo,
intellectual property rights. PowerMate, PowerTool, REAL ICE, rfLAB, Select Mode, Total
Endurance, WiperLock and ZENA are trademarks of
Microchip Technology Incorporated in the U.S.A. and other
countries.
SQTP is a service mark of Microchip Technology Incorporated
in the U.S.A.
All other trademarks mentioned herein are property of their
respective companies.
© 2009, Microchip Technology Incorporated, Printed in the
U.S.A., All Rights Reserved.
Printed on recycled paper.
Microchip received ISO/TS-16949:2002 certification for its worldwide
headquarters, design and wafer fabrication facilities in Chandler and
Tempe, Arizona; Gresham, Oregon and design centers in California
and India. The Company’s quality system processes and procedures
are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping
devices, Serial EEPROMs, microperipherals, nonvolatile memory and
analog products. In addition, Microchip’s quality system for the design
and manufacture of development systems is ISO 9001:2000 certified.
© 2009 Microchip Technology Inc. DS01143A-page 9
WORLDWIDE SALES AND SERVICE
AMERICAS ASIA/PACIFIC ASIA/PACIFIC EUROPE
Corporate Office Asia Pacific Office India - Bangalore Austria - Wels
2355 West Chandler Blvd. Suites 3707-14, 37th Floor Tel: 91-80-3090-4444 Tel: 43-7242-2244-39
Chandler, AZ 85224-6199 Tower 6, The Gateway Fax: 91-80-3090-4080 Fax: 43-7242-2244-393
Tel: 480-792-7200 Harbour City, Kowloon Denmark - Copenhagen
India - New Delhi
Fax: 480-792-7277 Hong Kong Tel: 45-4450-2828
Tel: 91-11-4160-8631
Technical Support: Tel: 852-2401-1200 Fax: 45-4485-2829
Fax: 91-11-4160-8632
http://support.microchip.com Fax: 852-2401-3431
India - Pune France - Paris
Web Address:
Australia - Sydney Tel: 91-20-2566-1512 Tel: 33-1-69-53-63-20
www.microchip.com
Tel: 61-2-9868-6733 Fax: 91-20-2566-1513 Fax: 33-1-69-30-90-79
Atlanta Fax: 61-2-9868-6755
Japan - Yokohama Germany - Munich
Duluth, GA
China - Beijing Tel: 49-89-627-144-0
Tel: 678-957-9614 Tel: 81-45-471- 6166
Tel: 86-10-8528-2100 Fax: 49-89-627-144-44
Fax: 678-957-1455 Fax: 81-45-471-6122
Fax: 86-10-8528-2104 Italy - Milan
Boston Korea - Daegu
China - Chengdu Tel: 39-0331-742611
Westborough, MA Tel: 82-53-744-4301
Tel: 86-28-8665-5511 Fax: 39-0331-466781
Tel: 774-760-0087 Fax: 82-53-744-4302
Fax: 86-28-8665-7889 Netherlands - Drunen
Fax: 774-760-0088 Korea - Seoul
China - Hong Kong SAR Tel: 82-2-554-7200 Tel: 31-416-690399
Chicago
Tel: 852-2401-1200 Fax: 82-2-558-5932 or Fax: 31-416-690340
Itasca, IL
Tel: 630-285-0071 Fax: 852-2401-3431 82-2-558-5934 Spain - Madrid
Fax: 630-285-0075 China - Nanjing Tel: 34-91-708-08-90
Malaysia - Kuala Lumpur
Tel: 86-25-8473-2460 Tel: 60-3-6201-9857 Fax: 34-91-708-08-91
Cleveland
Independence, OH Fax: 86-25-8473-2470 Fax: 60-3-6201-9859 UK - Wokingham
Tel: 216-447-0464 China - Qingdao Tel: 44-118-921-5869
Malaysia - Penang
Fax: 216-447-0643 Tel: 86-532-8502-7355 Fax: 44-118-921-5820
Tel: 60-4-227-8870
Dallas Fax: 86-532-8502-7205 Fax: 60-4-227-4068
Addison, TX China - Shanghai Philippines - Manila
Tel: 972-818-7423 Tel: 86-21-5407-5533 Tel: 63-2-634-9065
Fax: 972-818-2924 Fax: 86-21-5407-5066 Fax: 63-2-634-9069
Detroit China - Shenyang Singapore
Farmington Hills, MI Tel: 86-24-2334-2829 Tel: 65-6334-8870
Tel: 248-538-2250 Fax: 86-24-2334-2393 Fax: 65-6334-8850
Fax: 248-538-2260
China - Shenzhen Taiwan - Hsin Chu
Kokomo Tel: 86-755-8203-2660 Tel: 886-3-572-9526
Kokomo, IN Fax: 86-755-8203-1760 Fax: 886-3-572-6459
Tel: 765-864-8360
Fax: 765-864-8387 China - Wuhan Taiwan - Kaohsiung
Tel: 86-27-5980-5300 Tel: 886-7-536-4818
Los Angeles Fax: 86-27-5980-5118 Fax: 886-7-536-4803
Mission Viejo, CA
Tel: 949-462-9523 China - Xiamen Taiwan - Taipei
Fax: 949-462-9608 Tel: 86-592-2388138 Tel: 886-2-2500-6610
Fax: 86-592-2388130 Fax: 886-2-2508-0102
Santa Clara
Santa Clara, CA China - Xian Thailand - Bangkok
Tel: 408-961-6444 Tel: 86-29-8833-7252 Tel: 66-2-694-1351
Fax: 408-961-6445 Fax: 86-29-8833-7256 Fax: 66-2-694-1350
Toronto China - Zhuhai
Mississauga, Ontario, Tel: 86-756-3210040
Canada Fax: 86-756-3210049
Tel: 905-673-0699
Fax: 905-673-6509
02/04/09
DS01143A-page 10 © 2009 Microchip Technology Inc.
