Introduction

MCHPFSUSB Library Help
Contents | Index
Next
Introduction

MCHPFSUSB v2.9e

for Microchip PIC18/PIC24F/PIC32MX Microcontrollers

MCHPFSUSB is a distribution package containing a variety of USB related firmware projects, USB drivers and resources intended for use on the PC. The MCHPFSUSB firmware examples include projects for USB peripheral/device, Embedded Host, OTG, and Dual Role.

Introduction
Microchip MCHPFSUSB v2.9e - April 2012
Copyright © 2012 Microchip Technology, Inc. All rights reserved.


Software License Agreement

Contents | Index | Home
Previous | Next
Software License Agreement

MICROCHIP IS WILLING TO LICENSE THE ACCOMPANYING SOFTWARE AND DOCUMENTATION TO YOU ONLY ON THE CONDITION THAT YOU ACCEPT ALL OF THE FOLLOWING TERMS. TO ACCEPT THE TERMS OF THIS LICENSE, CLICK "I ACCEPT" AND PROCEED WITH THE DOWNLOAD OR INSTALL. IF YOU DO NOT ACCEPT THESE LICENSE TERMS, CLICK "I DO NOT ACCEPT," AND DO NOT DOWNLOAD OR INSTALL THIS SOFTWARE.

NON-EXCLUSIVE SOFTWARE LICENSE AGREEMENT

This Nonexclusive Software License Agreement ("Agreement") is a contract between you, your heirs, successors and assigns ("Licensee") and Microchip Technology Incorporated, a Delaware corporation, with a principal place of business at 2355 W. Chandler Blvd., Chandler, AZ 85224-6199, and its subsidiary, Microchip Technology (Barbados) II Incorporated (collectively, "Microchip") for the accompanying Microchip software including, but not limited to, Graphics Library Software, IrDA Stack Software, MCHPFSUSB Stack Software, Memory Disk Drive File System Software, mTouch(TM) Capacitive Library Software, Smart Card Library Software, TCP/IP Stack Software, MiWi(TM) DE Software, Security Package Software, and/or any PC programs and any updates thereto (collectively, the "Software"), and accompanying documentation, including images and any other graphic resources provided by Microchip ("Documentation").

1. Definitions. As used in this Agreement, the following capitalized terms will have the meanings defined below:

a. "Microchip Products" means Microchip microcontrollers and Microchip digital signal controllers.

b. "Licensee Products" means Licensee products that use or incorporate Microchip Products.

c. "Object Code" means the Software computer programming code that is in binary form (including related documentation, if any), and error corrections, improvements, modifications, and updates.

d. "Source Code" means the Software computer programming code that may be printed out or displayed in human readable form (including related programmer comments and documentation, if any), and error corrections, improvements, modifications, and updates.

e. "Third Party" means Licensee’s agents, representatives, consultants, clients, customers, or contract manufacturers.

f. "Third Party Products" means Third Party products that use or incorporate Microchip Products.

2. Software License Grant. Microchip grants strictly to Licensee a non-exclusive, non-transferable, worldwide license to:

a. use the Software in connection with Licensee Products and/or Third Party Products;

b. if Source Code is provided, modify the Software; provided that Licensee clearly notifies Third Parties regarding the source of such modifications;

c. distribute the Software to Third Parties for use in Third Party Products, so long as such Third Party agrees to be bound by this Agreement (in writing or by "click to accept") and this Agreement accompanies such distribution;

d. sublicense to a Third Party to use the Software, so long as such Third Party agrees to be bound by this Agreement (in writing or by "click to accept");

e. with respect to the TCP/IP Stack Software, Licensee may port the ENC28J60.c, ENC28J60.h, ENCX24J600.c, and ENCX24J600.h driver source files to a non-Microchip Product used in conjunction with a Microchip ethernet controller;

f. with respect to the MiWi (TM) DE Software, Licensee may only exercise its rights when the Software is embedded on a Microchip Product and used with a Microchip radio frequency transceiver or UBEC UZ2400 radio frequency transceiver which are integrated into Licensee Products or Third Party Products.

For purposes of clarity, Licensee may NOT embed the Software on a non-Microchip Product, except as described in this Section.

3. Documentation License Grant. Microchip grants strictly to Licensee a non-exclusive, non-transferable, worldwide license to use the Documentation in support of Licensee's authorized use of the Software

4. Third Party Requirements. Licensee acknowledges that it is Licensee’s responsibility to comply with any third party license terms or requirements applicable to the use of such third party software, specifications, systems, or tools. This includes, by way of example but not as a limitation, any standards setting organizations requirements and, particularly with respect to the Security Package Software, local encryption laws and requirements. Microchip is not responsible and will not be held responsible in any manner for Licensee’s failure to comply with such applicable terms or requirements.

5. Open Source Components. Notwithstanding the license grant in Section 1 above, Licensee further acknowledges that certain components of the Software may be covered by so-called "open source" software licenses ("Open Source Components"). Open Source Components means any software licenses approved as open source licenses by the Open Source Initiative or any substantially similar licenses, including without limitation any license that, as a condition of distribution of the software licensed under such license, requires that the distributor make the software available in source code format. To the extent required by the licenses covering Open Source Components, the terms of such license will apply in lieu of the terms of this Agreement. To the extent the terms of the licenses applicable to Open Source Components prohibit any of the restrictions in this Agreement with respect to such Open Source Components, such restrictions will not apply to such Open Source Component.

6. Licensee Obligations. Licensee will not: (a) engage in unauthorized use, modification, disclosure or distribution of Software or Documentation, or its derivatives; (b) use all or any portion of the Software, Documentation, or its derivatives except in conjunction with Microchip Products, Licensee Products or Third Party Products; or (c) reverse engineer (by disassembly, decompilation or otherwise) Software or any portion thereof. Licensee may not remove or alter any Microchip copyright or other proprietary rights notice posted in any portion of the Software or Documentation. Licensee will defend, indemnify and hold Microchip and its subsidiaries harmless from and against any and all claims, costs, damages, expenses (including reasonable attorney's fees), liabilities, and losses, including without limitation: (x) any claims directly or indirectly arising from or related to the use, modification, disclosure or distribution of the Software, Documentation, or any intellectual property rights related thereto; (y) the use, sale and distribution of Licensee Products or Third Party Products; and (z) breach of this Agreement.

7. Confidentiality. Licensee agrees that the Software (including but not limited to the Source Code, Object Code and library files) and its derivatives, Documentation and underlying inventions, algorithms, know-how and ideas relating to the Software and the Documentation are proprietary information belonging to Microchip and its licensors ("Proprietary Information"). Except as expressly and unambiguously allowed herein, Licensee will hold in confidence and not use or disclose any Proprietary Information and will similarly bind its employees and Third Party(ies) in writing. Proprietary Information will not include information that: (i) is in or enters the public domain without breach of this Agreement and through no fault of the receiving party; (ii) the receiving party was legally in possession of prior to receiving it; (iii) the receiving party can demonstrate was developed by the receiving party independently and without use of or reference to the disclosing party's Proprietary Information; or (iv) the receiving party receives from a third party without restriction on disclosure. If Licensee is required to disclose Proprietary Information by law, court order, or government agency, License will give Microchip prompt notice of such requirement in order to allow Microchip to object or limit such disclosure. Licensee agrees that the provisions of this Agreement regarding unauthorized use and nondisclosure of the Software, Documentation and related Proprietary Rights are necessary to protect the legitimate business interests of Microchip and its licensors and that monetary damage alone cannot adequately compensate Microchip or its licensors if such provisions are violated. Licensee, therefore, agrees that if Microchip alleges that Licensee or Third Party has breached or violated such provision then Microchip will have the right to injunctive relief, without the requirement for the posting of a bond, in addition to all other remedies at law or in equity.

8. Ownership of Proprietary Rights. Microchip and its licensors retain all right, title and interest in and to the Software and Documentation including, but not limited to all patent, copyright, trade secret and other intellectual property rights in the Software, Documentation, and underlying technology and all copies and derivative works thereof (by whomever produced). Licensee and Third Party use of such modifications and derivatives is limited to the license rights described in this Agreement.

9. Termination of Agreement. Without prejudice to any other rights, this Agreement terminates immediately, without notice by Microchip, upon a failure by Licensee or Third Party to comply with any provision of this Agreement. Upon termination, Licensee and Third Party will immediately stop using the Software, Documentation, and derivatives thereof, and immediately destroy all such copies.

10. Warranty Disclaimers. THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. MICROCHIP AND ITS LICENSORS ASSUME NO RESPONSIBILITY FOR THE ACCURACY, RELIABILITY OR APPLICATION OF THE SOFTWARE OR DOCUMENTATION. MICROCHIP AND ITS LICENSORS DO NOT WARRANT THAT THE SOFTWARE WILL MEET REQUIREMENTS OF LICENSEE OR THIRD PARTY, BE UNINTERRUPTED OR ERROR-FREE. MICROCHIP AND ITS LICENSORS HAVE NO OBLIGATION TO CORRECT ANY DEFECTS IN THE SOFTWARE.

11. Limited Liability. IN NO EVENT WILL MICROCHIP OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER ANY LEGAL OR EQUITABLE THEORY FOR ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS. The aggregate and cumulative liability of Microchip and its licensors for damages hereunder will in no event exceed $1000 or the amount Licensee paid Microchip for the Software and Documentation, whichever is greater. Licensee acknowledges that the foregoing limitations are reasonable and an essential part of this Agreement.

12. General. THIS AGREEMENT WILL BE GOVERNED BY AND CONSTRUED UNDER THE LAWS OF THE STATE OF ARIZONA AND THE UNITED STATES WITHOUT REGARD TO CONFLICTS OF LAWS PROVISIONS. Licensee agrees that any disputes arising out of or related to this Agreement, Software or Documentation will be brought exclusively in either the U.S. District Court for the District of Arizona, Phoenix Division, or the Superior Court of Arizona located in Maricopa County, Arizona. This Agreement will constitute the entire agreement between the parties with respect to the subject matter hereof. It will not be modified except by a written agreement signed by an authorized representative of Microchip. If any provision of this Agreement will be held by a court of competent jurisdiction to be illegal, invalid or unenforceable, that provision will be limited or eliminated to the minimum extent necessary so that this Agreement will otherwise remain in full force and effect and enforceable. No waiver of any breach of any provision of this Agreement will constitute a waiver of any prior, concurrent or subsequent breach of the same or any other provisions hereof, and no waiver will be effective unless made in writing and signed by an authorized representative of the waiving party. Licensee agrees to comply with all import and export laws and restrictions and regulations of the Department of Commerce or other United States or foreign agency or authority. The indemnities, obligations of confidentiality, and limitations on liability described herein, and any right of action for breach of this Agreement prior to termination, will survive any termination of this Agreement. Any prohibited assignment will be null and void. Use, duplication or disclosure by the United States Government is subject to restrictions set forth in subparagraphs (a) through (d) of the Commercial Computer-Restricted Rights clause of FAR 52.227-19 when applicable, or in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013, and in similar clauses in the NASA FAR Supplement. Contractor/manufacturer is Microchip Technology Inc., 2355 W. Chandler Blvd., Chandler, AZ 85224-6199.

If Licensee has any questions about this Agreement, please write to Microchip Technology Inc., 2355 W. Chandler Blvd., Chandler, AZ 85224-6199 USA. ATTN: Marketing.

Copyright (c) 2012 Microchip Technology Inc. All rights reserved.

License Rev. No. 05-012412

Software License Agreement


Release Notes

Contents | Index | Home
Previous | Next
Release Notes
Topics
Name | Description
What's New | Find out what is new for this stack release.
What's Next | Find out what the USB development team is working on and what will be out in the near future.
Support | Find out how to get help with your USB design, support questions, or USB training.
Online Reference and Resources | This section includes useful links to online USB development resources.
Demo Board Support and Limitations | This section shows which demos are supported on each of the USB demo boards.
Operating System Support and Limitations | This section describes which operating systems support each of the provided demos.
Tool Information | Specifies the versions of the tools used to test this release.
Revision History | This section describes in more detail the changes made between versions of the MCHPFSUSB stack. This section generally discusses only changes made to the core files (those found in the <install directory>\Microchip folder). This section generally doesn't include changes to the demo projects unless those changes are important to know about. This section also doesn't encompass minor changes to the stack files such as arrangement or locations of definitions or any other organizational changes. For more information about how to compare the actual source of two different revisions, please see the Appendix - Using a diff tool section of this... more
Library Migration |
Release Notes


What's New

Contents | Index | Home
Previous | Up | Next
What's New

New to v2.9e

  • Host
    • Bug fixes. See Revision History section v2.9e for more details.
  • Device
    • Bug fixes. See Revision History section v2.9e for more details.

New to v2.9d

  • Adding PIC24FJ64GB502 support
  • Host
    • Bug fixes. See Revision History section v2.9d for more details.
  • Device
    • Bug fixes. See Revision History section v2.9d for more details.
    • Added new PHDC demos

New to v2.9c

  • PC
    • Fixed HID boot loader executable issue on Windows systems
  • Device
    • Fixed issue with some dsPIC33E projects not building correctly

New to v2.9b

  • Host
    • Added MIDI host support
    • Bug fixes to various demos and client drivers
  • Device
    • Addition of DTS support for CDC driver
    • Bug fixes to various demos
    • Added example showing how to connect to custom HID, LibUSB, WinUSB, and MCHPUSB demos from an Android v3.1+ host.

New to v2.9a

  • PC Utilities
    • Bug fixes to cross-platform HID boot loader.

New to v2.9

  • Device
    • Bug fixes and enhancements
    • Addition of PHDC class
  • Host/OTG/Dual Role
    • Bug fixes and enhancements
    • Addition of Android host mode accessory support for OpenAccessory framework
  • PC Utilities
    • Cross-platform custom HID application
    • Cross-platform HID boot loader

For more information about changes in this revision please refer to the Revision History section.

For potential migration questions, please refer to the Library Migration section.

Release Notes > What's New


What's Next

Contents | Index | Home
Previous | Up | Next
What's Next

The following are the projects that are being worked on. These may not be released in the next release but are in development

  • General improvements to the documentation and demos.
Release Notes > What's Next


Support

Contents | Index | Home
Previous | Up | Next
Support

The Microchip Web Site

Microchip provides online support via our web site at http://www.microchip.com. This web site is used as a means to make files and information easily available to customers. Accessible by using your favorite Internet browser, the web site contains the following information:

• Product Support - Data sheets and errata, application notes and sample programs, design resources, user's guides and hardware support documents, latest software releases and archived software

• General Technical Support - Frequently Asked Questions (FAQs), technical support requests ( [image] http://support.microchip.com), online discussion groups/forums ( [image] http://forum.microchip.com, or more specifically the USB forum topic), Microchip consultant program member listing

• Business of Microchip - Product selector and ordering guides, latest Microchip press releases, listing of seminars and events, listings of Microchip sales offices, distributors and factory representatives

Development Systems Customer Change Notification Service

Microchip's customer notification service helps keep customers current on Microchip products. Subscribers will receive e-mail notification whenever there are changes, updates, revisions or errata related to a specified product family or development tool of interest.

To register, access the Microchip web site at www.microchip.com, click on Customer Change Notification and follow the registration instructions.

Additional Support

Users of Microchip products can receive assistance through several channels:

• Distributor or Representative

• Local Sales Office

• Field Application Engineer (FAE)

• Technical Support

Customers should contact their distributor, representative or field application engineer (FAE) for support. Local sales offices are also available to help customers. A listing of sales offices and locations is available on our website.

Technical support is available through the web site at: http://support.microchip.com

Training

• Regional Training Centers: http://www.microchip.com/rtc

• MASTERs Conference: http://www.microchip.com/masters

• Webseminars: http://techtrain.microchip.com/webseminars/QuickList.aspx

Release Notes > Support


Online Reference and Resources

Contents | Index | Home
Previous | Up | Next
Online Reference and Resources

Note: Newer versions of the documents below may be available. Please check www.microchip.com for the latest version.

USB Design Center

http://www.microchip.com/usb

Application Notes

Microchip USB Device Firmware Framework User’s Guide

AN950 – Power Management for PIC18 USB Microcontrollers with nanoWatt Technology

AN956 – Migrating Applications to USB from RS-232 UART with Minimal Impact on PC Software

AN1140 – USB Embedded Host Stack

AN1141 – USB Embedded Host Stack Programmer’s Guide

AN1142 – USB Mass Storage Class on an Embedded Host

AN1143 – Generic Client Driver for a USB Embedded Host

AN1144 - USB Human Interface Device Class on an Embedded Host

AN1145 – Using a USB Flash Drive on an Embedded Host

AN1189 – Implementing a Mass Storage Device Using the Microchip

AN1212 – Using USB Keyboard with an Embedded Host

AN1233 – USB Printer Class on an Embedded Host

USB Demonstration Videos

http://www.youtube.com/watch?v=ljF4KQ2mfD0

http://www.youtube.com/watch?v=cmtjKUv_yPs&feature=related

http://www.youtube.com/watch?v=BOosLeO7D58&feature=related

Release Notes > Online Reference and Resources


Demo Board Support and Limitations

Contents | Index | Home
Previous | Up | Next
Demo Board Support and Limitations

This section shows which demos are supported on each of the USB demo boards.

Limitations

1) "Neither compound nor composite devices are supported. Some keyboards are either compound or composite.

The “~” prints as an arrow character instead (“->”). This is an effect of the LCD screen on the Explorer 16. The ascii character for “~” is remapped in the LCD controller.

The “\” prints as a “¥” character instead. This is an effect of the LCD screen on the Explorer 16. The ascii character for “\” is remapped in the LCD controller.

Backspace and arrow keys may have issues on Explorer 16 boards with certain LCD modules"

2) The PIC24F starter kit does not have a physical push button. The board uses capacitive touch buttons instead. The cap touch functionality has not been added to the demos yet so the functionality required by the demos is not currently available.

3) PIC32 USB Starter kit does not have a potentiometer, a temperature sensor, or a 4th LED on the board. Demos using these features do not function in their full capacity.

4) Due to the size of this demo, optimizations must be enabled in the compiler in order for this demo to work on the specified hardware platform. Optimizations are not available on all versions of the compilers.

5) The PIC32MX795F512L Family devices have a register bit named READ. This conflicts with a definition in the MDD library. The MDD Library READ definition should not be used. Instead a 'r' should be used.

Release Notes > Demo Board Support and Limitations


Operating System Support and Limitations

Contents | Index | Home
Previous | Up | Next
Operating System Support and Limitations

This section describes which operating systems support each of the provided demos.

Limitations

1) These devices enumerate successfully by the OS but currently there is not an example program to interface these devices.

2) Devices that implement the LibUSB demo will enumerate successfully on Macintosh based operating systems (provided the correct drivers are installed). Currently there is not an example program to communicate to these devices on these operating systems in this installation.

3) Only single touch gestures are supported in Windows Vista. For the multi touch demo only the single touch gestures will work as a gesture. The multi touch gestures in Vista will appears as two separate touch events that do not produce a usable pattern.

4) When used with Windows XP SP2 or earlier, this demo requires a Microsoft hotfix in order to run properly. This hotfix is linked from the demo folder. Windows XP SP3 works properly without needing any hotfix.

5) When adding a VID/PID string to the “%DESCRIPTION%=DriverInstall” and “%DESCRIPTION%=DriverInstall64” sections in the mchpusb.inf file, remove one or more of the pre-existing VID/PID strings from the list. There is a limit to the maximum number of VID/PID strings that can be supported simultaneously. If the list contains too many entries, the following error message will occur when installing the driver under Vista: "The Data Area Passed to a System Call Is Too Small"

6) The CDC PC example code does not run as implemented on the 64-bit version of the Windows Vista operating system with some versions of the .net framework. The .NET SerialPort object does not appear to receive data as implemented in these examples in the early versions of the .net framework for Vista.

7) The HID keyboard example does not work as implemented on the Windows 2000 operating system or any earlier revisions of the Windows operating systems.

8) Firmware successfully enumerates but test machine was unable to verify functionality. This is either due to lack of support in the OS for these types of devices or lack of an Application that uses these devices.

9) This demo uses the USB IAD specification. Some versions of Macintosh OSX do not support IAD.

Release Notes > Operating System Support and Limitations


Tool Information

Contents | Index | Home
Previous | Up | Next
Tool Information

This release was tested with the following tools:

Compiler | Version
MPLAB C18 | 3.40
MPLAB C30 | 3.31
MPLAB C32 | 2.02a
IDE | Version
MPLAB | 8.83
MPLAB X | 1.00

Some demos in this release require the full versions of the above compilers (the boot loaders and a few of the demo applications). For most demos, either the commercial version, or the evaluation version can be used to build the example projects. Some The compilers may be obtained from http://www.microchip.com/c18, http://www.microchip.com/c30, and http://www.microchip.com/c32.

Release Notes > Tool Information


Revision History

Contents | Index | Home
Previous | Up | Next
Revision History

This section describes in more detail the changes made between versions of the MCHPFSUSB stack. This section generally discusses only changes made to the core files (those found in the <install directory>\Microchip folder). This section generally doesn't include changes to the demo projects unless those changes are important to know about. This section also doesn't encompass minor changes to the stack files such as arrangement or locations of definitions or any other organizational changes.

For more information about how to compare the actual source of two different revisions, please see the Appendix - Using a diff tool section of this document.

Topics
Name
Description
v2.9e

  1. Read-modify-write race condition in the way the USB interrupt flag was getting cleared on the PIC32 devices.
    • Stack files affected: usb_hal_pic32.h
  2. Added option to disable NAK timeouts for CDC host transfers (USB_HOST_CDC_NAK_TIMEOUT)
    • Stack files affected: usb_host_cdc.c
  3. The ALLOW_GLOBAL_VID_AND_PID option does not issue the EVENT_OVERRIDE_CLIENT_DRIVER_SELECTION event.
    • Stack files affected: usb_host.c
  4. USB host isochronous writes did not function correctly
    • Stack files affected: usb_host.c
  5. USB host isochronous writes and reads could not occur during the same frame
    • Stack files affected: usb_host.c
  6. NULL pointer dereference could occur if a malloc() call failed during device enumeration in USB host stack while creating the endpoint data... more
v2.9d
  1. Data event handler of Android driver not passing events to protocol handler resulting in possible memory leak.
    • Stack files affected: usb_host_android.c
  2. Issues with mass storage demos on OS X 10.7 when SD-card is read-only.
    • Stack files affected: usb_function_msd.c
  3. Fixed compile warnings when -Wall option selected on C32
    • Stack files affected: usb_host_msd.c
  4. Fixed issue with call back redirection macro for EP0 request handler.
    • Stack files affected: usb_device_local.h
  5. Added configuration option to disable DTS checking in hardware
    • Stack files affected: usb_device.c
  6. Fixed a race condition between the 1msec interrupt and the detach interrupt. If the detach interrupt occurs just before the 1msec... more
v2.9c
  1. Added example showing how to connect to custom HID, LibUSB, WinUSB, and MCHPUSB demos from an Android v3.1+ host.
    • Stack files affected: none
  2. Updated libusb driver INF to be signed, so now it can be installed with Windows 7
    • Stack files affected: none
  3. Some dsPIC projects not building correctly
    • Stack files affected: usb_hal_dspic33e.h, usb_hal_pic24e.h
v2.9b
  1. UART RX functionality fixed on several demos using the PIC24FJ256DA210 development board.
    • Stack files affected: none
  2. Race condition fixed in Android OpenAccessory framework that could lead to the accessory not attaching periodically.
    • Stack files affected: usb_host_android_protocol_v1.c
  3. Added Android Accessory workaround for when Android device attaches in accessory mode without first attaching as the manufacturer's mode (happens when accessory is reset but not detached from bus).
    • Stack files affected: usb_host_android_protocol_v1.c, usb_host_android.c, usb_host_android.h
  4. Fixed issue where non-supported Android protocol versions would try to enumerate.
    • Stack files affected: usb_host_android.c
  5. PIC18F Starter Kit MSD SD card reader demo not working correctly.
    • Stack files affected:... more
v2.9a
  1. Fixes issues in the cross-platform HID boot loader that caused certain hex files not to work if the various sections in the hex file were not order in increasing address in the .hex file.
    • Stack files affected: none
  2. Added UART output support for PIC24FJ256DA210 Development Board in Host – Printer Full sheet demo.
    • Stack files affected: none
v2.9
  1. Adds PHDC peripheral support.
  2. Adds Android accessory support for host mode accessories.
  3. Added MPLAB X project files for most demo projects.
  4. Added code to allow subclass 0x05 (SFF-8070i devices) to enumerate to the MSD host. Support limited to devices that use SCSI command set only.
    • Stack files affected: usb_host_msd.c
  5. Added additional logic to MSD SCSI host code to improve support for various MSD devices by trying to reset various error conditions that may occur.
    • Stack files affected: usb_host_msd_scsi.c
  6. Fixed issue with CDC host where SET_CONTROL_LINE_STATE command response was formatted incorrectly.
    • Stack files affected: usb_host_cdc.c
  7. Added support for both input and... more
v2.8
  1. Fixed issue with SetFeature(ENDPOINT_HALT) handling in the device stack. Error could cause one packet of data to get lost per endpoint after clearing a ENDPOINT_HALT event on an endpoint. Issue could also cause the user to lose control of endpoints that may not have been enabled before the SetFeature(ENDPOINT_HALT) was received. Parts of the issue described in the following forum thread: http://www.microchip.com/forums/tm.aspx?m=503200.
    • Stack files affected: usb_device.c
  2. Fixed stability issue in device stack when interrupts enabled related to the improper enabling of the interrupt control bits in an interrupt context.
    • Stack files affected: usb_device.c
  3. Fixed issue STALLs were not handled correctly... more
v2.7a
  1. Fixed USBSetBDTAddress() macro, so that it correctly loads the entire U1BDTPx register set, enabling the BDT to be anywhere in RAM. Previous implementation wouldn't work on a large RAM device if the linker decided to place the BDT[] array at an address > 64kB.
    • Stack files affected: usb_hal_pic32.h
  2. Fixed initialization issue where HID parse result information wasn't cleared before loading with new parse result data.
    • Stack files affected: usb_host_hid_parser.c
  3. Update to support the PIC18F47J53 A1 and later revision devices.
    • Stack files affected: usb_device.c
  4. Fixed an error on 16-bit and 32-bit processors where a word access could be performed on a... more
v2.7
  1. Fixed error where USBHandleGetAddr() didn't convert the return address from a physical address to a virtual address for PIC32.
    • Stack files affected: usb_device.h
  2. Added macro versions of USBDeviceAttach() and USBDeviceDetach() so they will compile without error when using polling mode.
    • Stack files affected: usb_device.h
  3. Fixes issue in dual role example where a device in polling mode can still have interrupts enabled from the host mode causing an incorrect vectoring to the host interrupt controller while in device mode.
    • Stack files affected: usb_hal_pic18.h, usb_hal_pic24.h, usb_hal-pic32.h, usb_device.c
  4. Modified the SetConfigurationOptions() function for PIC32 to explicitly reconfigure the pull-up/pull-down settings... more
Release Notes > Revision History


v2.9e

Contents | Index | Home
Previous | Up | Next
v2.9e

  1. Read-modify-write race condition in the way the USB interrupt flag was getting cleared on the PIC32 devices.
    • Stack files affected: usb_hal_pic32.h
  2. Added option to disable NAK timeouts for CDC host transfers (USB_HOST_CDC_NAK_TIMEOUT)
    • Stack files affected: usb_host_cdc.c
  3. The ALLOW_GLOBAL_VID_AND_PID option does not issue the EVENT_OVERRIDE_CLIENT_DRIVER_SELECTION event.
    • Stack files affected: usb_host.c
  4. USB host isochronous writes did not function correctly
    • Stack files affected: usb_host.c
  5. USB host isochronous writes and reads could not occur during the same frame
    • Stack files affected: usb_host.c
  6. NULL pointer dereference could occur if a malloc() call failed during device enumeration in USB host stack while creating the endpoint data structure.
    • Stack files affected: usb_host.c
  7. Optimazation settings other than -O0 for C30 could cause MSD internal flash demos not to work.
    • Stack files affected: None (Files.c in user folder updated)

Release Notes > Revision History > v2.9e


v2.9d

Contents | Index | Home
Previous | Up | Next
v2.9d

  1. Data event handler of Android driver not passing events to protocol handler resulting in possible memory leak.
    • Stack files affected: usb_host_android.c
  2. Issues with mass storage demos on OS X 10.7 when SD-card is read-only.
    • Stack files affected: usb_function_msd.c
  3. Fixed compile warnings when -Wall option selected on C32
    • Stack files affected: usb_host_msd.c
  4. Fixed issue with call back redirection macro for EP0 request handler.
    • Stack files affected: usb_device_local.h
  5. Added configuration option to disable DTS checking in hardware
    • Stack files affected: usb_device.c
  6. Fixed a race condition between the 1msec interrupt and the detach interrupt. If the detach interrupt occurs just before the 1msec interrupt, the interrupt handler could cause the host stack state machine to go into an unknown state requiring a reset of the system to recover. Typically only seen when rapidly attaching/detaching a device repeatedly.
    • Stack files affected: usb_host.c
  7. Added an error handing case to check for a size larger than 256.
    • Stack files affected: usb_function_phdc.c
  8. Write attempts to a drive that is write protected does not report the status correct.
    • Stack files affected: usb_function_msd.c
  9. Updated PHDC code to pass Continua testing
    • Stack files affected: usb_function_phdc.c, usb_function_phdc.h, usb_function_phdc_com_model.c/.h added

Release Notes > Revision History > v2.9d


v2.9c

Contents | Index | Home
Previous | Up | Next
v2.9c

  1. Added example showing how to connect to custom HID, LibUSB, WinUSB, and MCHPUSB demos from an Android v3.1+ host.
    • Stack files affected: none
  2. Updated libusb driver INF to be signed, so now it can be installed with Windows 7
    • Stack files affected: none
  3. Some dsPIC projects not building correctly
    • Stack files affected: usb_hal_dspic33e.h, usb_hal_pic24e.h

Release Notes > Revision History > v2.9c


v2.9b

Contents | Index | Home
Previous | Up | Next
v2.9b

  1. UART RX functionality fixed on several demos using the PIC24FJ256DA210 development board.
    • Stack files affected: none
  2. Race condition fixed in Android OpenAccessory framework that could lead to the accessory not attaching periodically.
    • Stack files affected: usb_host_android_protocol_v1.c
  3. Added Android Accessory workaround for when Android device attaches in accessory mode without first attaching as the manufacturer's mode (happens when accessory is reset but not detached from bus).
    • Stack files affected: usb_host_android_protocol_v1.c, usb_host_android.c, usb_host_android.h
  4. Fixed issue where non-supported Android protocol versions would try to enumerate.
    • Stack files affected: usb_host_android.c
  5. PIC18F Starter Kit MSD SD card reader demo not working correctly.
    • Stack files affected: none
  6. Null pointer dereference on Android OpenAccessory detach event.
    • Stack files affected: usb_host_android_protocol_v1.c
  7. Removed the restriction of MSD drives with the VID = 0x0930 and PID = 0x6545 for the USB MSD host data logging demo. These drives now show no issues with recent robustness enhancements in the past several releases.
    • Stack files affected: none
  8. Link issues on Linux and Macintosh machines for PIC18 demos. The latest versions of the C18 compiler for Linux and Macintosh change the linker and library file capitalization scheme resulting in link errors when using older linker files. Linker files updated to use latest capitalization scheme.
    • Stack files affected: none
  9. Cleaned up the configuration bits sections for several processors in several demos.
    • Stack files affected: none
  10. CCID demo descriptors updated to enable operation on Macintosh machines.
    • Stack files affected: none
  11. Update the precompiled MSD library to support .elf files.
    • Stack files affected: none
  12. PCL5 printer host would send out a 0-length packet if an empty string was passed to it. This results in some PCL5 printers to lock up. The updated driver will not send out a text string to a printer if it is empty.
    • Stack files affected: none
  13. USB_HID_FEATURE_REPORT was assigned the incorrect value.
    • Stack files affected: usb_host_hid.c
  14. Some CDC device demos had incorrect USB_MAX_NUM_INT definition.
    • Stack files affected: none
  15. Added examples showing how to connect to various USB demos with the Android USB host API.
    • Stack files affected: none
  16. Optional support for DTS signalling added
    • Stack files affected: usb_function_cdc.c, usb_function_cdc.h
  17. Added MIDI host support
    • Stack files affected: usb_host_midi.c, usb_host_midi.h
  18. Added Android OpenAccessory boot loader example
    • Stack files affected: none
  19. Fixed issues with PIC32 support with the MSD host boot loader. Now supports C32 versions 2.x and later.
    • Stack files affected: none

Release Notes > Revision History > v2.9b


v2.9a

Contents | Index | Home
Previous | Up | Next
v2.9a

  1. Fixes issues in the cross-platform HID boot loader that caused certain hex files not to work if the various sections in the hex file were not order in increasing address in the .hex file.
    • Stack files affected: none
  2. Added UART output support for PIC24FJ256DA210 Development Board in Host – Printer Full sheet demo.
    • Stack files affected: none

Release Notes > Revision History > v2.9a


v2.9

Contents | Index | Home
Previous | Up | Next
v2.9

  1. Adds PHDC peripheral support.
  2. Adds Android accessory support for host mode accessories.
  3. Added MPLAB X project files for most demo projects.
  4. Added code to allow subclass 0x05 (SFF-8070i devices) to enumerate to the MSD host. Support limited to devices that use SCSI command set only.
    • Stack files affected: usb_host_msd.c
  5. Added additional logic to MSD SCSI host code to improve support for various MSD devices by trying to reset various error conditions that may occur.
    • Stack files affected: usb_host_msd_scsi.c
  6. Fixed issue with CDC host where SET_CONTROL_LINE_STATE command response was formatted incorrectly.
    • Stack files affected: usb_host_cdc.c
  7. Added support for both input and output functionality in the Audio host driver.
    • Stack files affected: usb_host_audio.c
  8. Added support for SOF, 1 millisecond timer, and data transfer event notifications to USB host drivers.
    • Stack files affected: usb_host.c
  9. Added mechanism for a host client driver to override or reject the stacks selection for the class driver associated with an attached device.
    • Stack files affected: usb_host.c, usb_common.h
  10. Fixed an issue with STALL handling behavior on non-EP0 endpoints for PIC24 and PIC32 devices.
    • Stack files affected: usb_device.c
  11. Fixed an issue where some variables/flags were not getting re-initialized correctly after a set configuration event leading to communication issues when ping-pong is enabled and multiple set configuration commands are received.
    • Stack files affected: usb_device.c
  12. Added mechanism to get the handle for the next available ping-pong transfer.
    • Stack files affected: usb_device.h
  13. Fixed incorrect value for USB_CDC_CONTROL_LINE_LENGTH Stack files affected: usb_host_cdc.h
  14. Updated MSD device driver to pass command verifier tests.
    • Stack files affected: usb_device_msd.c, usb_device_msd.h
  15. Change to CDC device driver to allow handling of terminated transfers.
    • Stack files affected: usb_device_cdc.c

Release Notes > Revision History > v2.9


v2.8

Contents | Index | Home
Previous | Up | Next
v2.8

  1. Fixed issue with SetFeature(ENDPOINT_HALT) handling in the device stack. Error could cause one packet of data to get lost per endpoint after clearing a ENDPOINT_HALT event on an endpoint. Issue could also cause the user to lose control of endpoints that may not have been enabled before the SetFeature(ENDPOINT_HALT) was received. Parts of the issue described in the following forum thread: http://www.microchip.com/forums/tm.aspx?m=503200.
    • Stack files affected: usb_device.c
  2. Fixed stability issue in device stack when interrupts enabled related to the improper enabling of the interrupt control bits in an interrupt context.
    • Stack files affected: usb_device.c
  3. Fixed issue STALLs were not handled correctly when event transfers are enabled. This could result in the attached device remaining in a non-responsive state where their endpoints are STALLed.
    • Stack files affected: usb_host_msd.c
  4. Fixed issue where MSD function driver could not always reinitialize itself to a known state.
    • Stack files affected: usb_function_msd.c
  5. Added USBCtrlEPAllowStatusStage(), USBDeferStatusStage(), USBCtrlEPAllowDataStage(), USBDeferOUTDataStage(), USBOUTDataStageDeffered(), USBDeferInDataStage(), and USBINDataStageDeferred() functions. These functions allow users to defer the handling of control transfers received in interrupt context until a later point of time.
    • Stack files affected: usb_device.c, usb_device.h
  6. Fixed issue in PIC18F starter kit SD-card bootloader issue. Bootloader could have errors loading hex files if there was an hex entry starting at an odd address with an even number of bytes in the payload.
    • Stack files affected: none
  7. Reorganization of many of the definitions and data types.
    • Stack files affected: usb_hal_pic18.h, usb_hal_pic24.h, usb_hal_pic32.h, usb_device_local.h, usb_device.c, usb_device.h
  8. Changed the behavior of the PIC24F HID bootloader linker scripts. The remapping.s file is no longer required. Interrupt vector remapping is now handled by the provided linker scripts (no customization required). Applications should be able to run with the bootloader linker script when either programmed or loaded through the bootloader allowing for more easy development and debugging. Interrupt latency should also be the same when using the bootloader or the debugger. For more information about usage, please refer to the HID bootloader documentation.
  9. Changed the behavior of the PIC32 HID bootloader linker scripts. The dual-linker script requirement has been replaced by a single required linker script that should be attached to the application project. Applications should be able to run with the bootloader linker script when either programmed or loaded through the bootloader allowing for more easy development and debugging. Interrupt latency should also be the same when using the bootloader or the debugger. For more information about usage, please refer to the HID bootloader documentation.
  10. Added files for the PIC18F starter kit contest winners. Located in “<INSTALL_DIRECTORY>/PIC18F Starter Kit 1/Demos/Customer Submissions/Contest 1”
  11. Added initial support for the PIC24FJ256DA210 development board.
  12. Added initial support for the PIC24FJ256GB210 Plug-in module.

Release Notes > Revision History > v2.8


v2.7a

Contents | Index | Home
Previous | Up | Next
v2.7a

  1. Fixed USBSetBDTAddress() macro, so that it correctly loads the entire U1BDTPx register set, enabling the BDT to be anywhere in RAM. Previous implementation wouldn't work on a large RAM device if the linker decided to place the BDT[] array at an address > 64kB.
    • Stack files affected: usb_hal_pic32.h
  2. Fixed initialization issue where HID parse result information wasn't cleared before loading with new parse result data.
    • Stack files affected: usb_host_hid_parser.c
  3. Update to support the PIC18F47J53 A1 and later revision devices.
    • Stack files affected: usb_device.c
  4. Fixed an error on 16-bit and 32-bit processors where a word access could be performed on a byte pointer resulting in possible address errors with odd aligned pointers.
    • Stack files affected: usb_device.c
  5. Fixed issue where the USBSleepOnSuspend() function would cause the USB communication to fail after being called when _IPL is equal to 0.
    • Stack files affected: usb_hal_pic24.c
  6. Fixed issue where placing the micro in idle mode would cause the host stack to stop sending out SOF packets.
    • Stack files affected: usb_host.c
  7. Fixed several issues in the USBConfig.exe
  8. Made changes to the starting address of the HID bootloader for PIC32. Reduced the size used by the bootloader. Also added application linker scripts for each processor.
  9. Added a three point touch digitizer example
  10. Updated some of the PC examples to build and run properly in the 2010 .net Express versions.
  11. Added information and batch file showing how to enter a special mode of device manager that allows removal/uninstallation of devices that are not currently attached to the system.

Release Notes > Revision History > v2.7a


v2.7

Contents | Index | Home
Previous | Up | Next
v2.7

  1. Fixed error where USBHandleGetAddr() didn't convert the return address from a physical address to a virtual address for PIC32.
    • Stack files affected: usb_device.h
  2. Added macro versions of USBDeviceAttach() and USBDeviceDetach() so they will compile without error when using polling mode.
    • Stack files affected: usb_device.h
  3. Fixes issue in dual role example where a device in polling mode can still have interrupts enabled from the host mode causing an incorrect vectoring to the host interrupt controller while in device mode.
    • Stack files affected: usb_hal_pic18.h, usb_hal_pic24.h, usb_hal-pic32.h, usb_device.c
  4. Modified the SetConfigurationOptions() function for PIC32 to explicitly reconfigure the pull-up/pull-down settings for the D+/D- pins in case the host code leaves the pull-downs enabled when running in a dual role configuration.
    • Stack files affected: usb_hal_pic32.h
  5. Fixed error where the USB error interrupt flag was not getting cleared properly for PIC32 resulting in extra error interrupts (http://www.microchip.com/forums/tm.aspx?m=479085).
    • Stack files affected: usb_device.c
  6. Updated the device stack to move to the configuration state only after the user event completes.
    • Stack files affected: usb_device.c
  7. Fixed error in the part support list of the variables section where the address of the CDC variables are defined. The PIC18F2553 was incorrectly named PIC18F2453 and the PIC18F4558 was incorrectly named PIC18F4458 (http://www.microchip.com/forums/fb.aspx?m=487397).
    • Stack files affected: usb_function_cdc.c
  8. Fixed an error where the USBHostClearEndpointErrors() function didn't properly return USB_SUCCESS if the errors were successfully cleared (http://www.microchip.com/forums/fb.aspx?m=490651).
    • Stack files affected: usb_host.c
  9. Fixed issue where deviceInfoHID[i].rptDescriptor was incorrectly freed twice. The second free results in possible issues in future malloc() calls in the C32 compiler.
    • Stack files affected: usb_host_hid.c
  10. Fixed an issue where the MSD client driver would issue a transfer events to an incorrect/invalid client driver number when transfer events are enabled.
    • Stack files affected: usb_host_msd.c
  11. Fixed issue where a device that is already connected to the embedded host when the system is initialized may not enumerate.
    • Stack files affected: usb_host.c
  12. Fixed issue where the embedded host or OTG device did not properly check bmRequestType when it thinks that a HALT_ENDPOINT request was sent to the device. This resulted in the DTS bits for the attached device getting reset causing possible communication issues.
    • Stack files affected: usb_host.c
  13. Changed how the bus sensing works. In previous revisions it was impossible to use the USBDeviceDetach to detach from the bus if the bus voltage was still present. This is now possible. It was also possible to move the device to the ATTACHED state in interrupt mode even if the bus voltage wasn't available. This is now prohibited unless VBUS is present.
    • Stack files affected: usb_device.c
  14. Added USBSleepOnSuspend() function. This function shows how to put the PIC24F to sleep while the USB module is in suspend and have the USB module wake up the device on activity on the bus.
    • Stack files affected: usb_hal_pic24.h, usb_hal_pic24.c
  15. Modified the code to allow connection of USB-RS232 dongles that do not fully comply with CDC specifications.
    • Stack files affected: usb_host_cdc.h, usb_host_cdc.c, usb_host_cdc_interface.c, usb_host_interface.h
  16. Modified API USBHostCDC_Api_Send_OUT_Data to allow data transfers more than 256 bytes.
    • Stack files affected: usb_host_cdc.h, usb_host_cdc.c, usb_host_cdc_interface.c, usb_host_interface.h
  17. Improved error case handling when the host sends more OUT bytes in a control transfer than the firmware was expecting to receive (based on the size parameter when calling USBEP0Receive()).
    • Stack files affected: usb_device.c
  18. Added CCID (Circuit Cards Interface Device) class device/function support.
    • Stack Files affected: usb_function_ccid.h, usb_function_ccid.c
  19. Added Audio v1 class embedded host support.
    • Stack files affected: usb_host_audio_v1.h, usb_host_audio_v1.c

Release Notes > Revision History > v2.7


Library Migration

Contents | Index | Home
Previous | Up | Next
Library Migration
Topics
Name
Description
From v2.9d to v2.9e
No changes required
From v2.9c to v2.9d
No changes required.
From v2.9b to v2.9c
No changes required.
From v2.9a to v2.9b
No changes required.
From v2.9 to v2.9a
No changes required.
From v2.8 to v2.9
No changes required.
From v2.7a to v2.8
  1. HID Bootloader for PIC32 devices
    • An error was fixed in PIC32 bootloader. The previous implementations placed the interrupt vector table on a 1K-page aligned boundary. This table should be on a such a boundary. The user reset vector and the interrupt vector section addresses were switched to meet this requirement. Applications/bootloaders using the old reset vector will not work with applications/bootloaders using the new bootloader linker files.
From v2.7 to v2.7a
  1. HID Bootloader for PIC32 devices
    • The PIC32 bootloader was changed in this revision. The memory region used by the HID bootloader was reduced. This could result in issues loading application projects built with the new linker scripts on a system with the old bootloader. It could also result in issues loading an old application with the new bootloader.
From v2.6a to v2.7
No changes required.
From v2.6 to v2.6a
  1. HID Bootloader for PIC24F devices
    • The HID Bootloader for PIC24F has been reworked for the v2.6a release. The change involve how interrupt remapping is handled and how applications relocate their code to make room for the bootloader. Applications built with the v2.6 or earlier PIC24F compiler should continue using the v2.6 bootloader and support files. It is recommended for new projects that new bootloader and support files should be used.
    • In previous revisions of the stack there was a “PIC24F HID Bootloader Remapping.s” file that was added to any PIC24F project to relocate the application code out of the bootloader... more
From v2.5 to v2.6
  1. Include Files
    • The files that must be included into a project has changed from v2.5 to v2.6.
    • Version v2.5 of the MCHPFSUSB stack required multiple include files in order to work properly in device mode. The usb_device.h, usb.h, usb_config.h, and class specific files (i.e. - “./usb/usb_function_msd.h”) had to be included in all of the application files that accessed the USB stack as well as other common include files like the GenericTypeDefs.h and Compiler.h files.
    • In MHCPFSUSB v2.6, only the usb.h file and the class specific files (i.e. - “./usb/usb_function_msd.h”) must be included in the project. The usb_device.h and usb_config.h files... more
Release Notes > Library Migration


From v2.9d to v2.9e

Contents | Index | Home
Previous | Up | Next
From v2.9d to v2.9e

No changes required

Release Notes > Library Migration > From v2.9d to v2.9e


From v2.9c to v2.9d

Contents | Index | Home
Previous | Up | Next
From v2.9c to v2.9d

No changes required.

Release Notes > Library Migration > From v2.9c to v2.9d


From v2.9b to v2.9c

Contents | Index | Home
Previous | Up | Next
From v2.9b to v2.9c

No changes required.

Release Notes > Library Migration > From v2.9b to v2.9c


From v2.9a to v2.9b

Contents | Index | Home
Previous | Up | Next
From v2.9a to v2.9b

No changes required.

Release Notes > Library Migration > From v2.9a to v2.9b


From v2.9 to v2.9a

Contents | Index | Home
Previous | Up | Next
From v2.9 to v2.9a

No changes required.

Release Notes > Library Migration > From v2.9 to v2.9a


From v2.8 to v2.9

Contents | Index | Home
Previous | Up | Next
From v2.8 to v2.9

No changes required.

Release Notes > Library Migration > From v2.8 to v2.9


From v2.7a to v2.8

Contents | Index | Home
Previous | Up | Next
From v2.7a to v2.8

  1. HID Bootloader for PIC32 devices
    • An error was fixed in PIC32 bootloader. The previous implementations placed the interrupt vector table on a 1K-page aligned boundary. This table should be on a such a boundary. The user reset vector and the interrupt vector section addresses were switched to meet this requirement. Applications/bootloaders using the old reset vector will not work with applications/bootloaders using the new bootloader linker files.

Release Notes > Library Migration > From v2.7a to v2.8


From v2.7 to v2.7a

Contents | Index | Home
Previous | Up | Next
From v2.7 to v2.7a

  1. HID Bootloader for PIC32 devices
    • The PIC32 bootloader was changed in this revision. The memory region used by the HID bootloader was reduced. This could result in issues loading application projects built with the new linker scripts on a system with the old bootloader. It could also result in issues loading an old application with the new bootloader.

Release Notes > Library Migration > From v2.7 to v2.7a


From v2.6a to v2.7

Contents | Index | Home
Previous | Up | Next
From v2.6a to v2.7

No changes required.

Release Notes > Library Migration > From v2.6a to v2.7


From v2.6 to v2.6a

Contents | Index | Home
Previous | Up | Next
From v2.6 to v2.6a

  1. HID Bootloader for PIC24F devices
    • The HID Bootloader for PIC24F has been reworked for the v2.6a release. The change involve how interrupt remapping is handled and how applications relocate their code to make room for the bootloader. Applications built with the v2.6 or earlier PIC24F compiler should continue using the v2.6 bootloader and support files. It is recommended for new projects that new bootloader and support files should be used.
    • In previous revisions of the stack there was a “PIC24F HID Bootloader Remapping.s” file that was added to any PIC24F project to relocate the application code out of the bootloader space. These files have been deprecated and should not be used with the new revision of the bootloader. Instead there is a custom linker script (boot_hid_p24fjxxxGBxxx.gld) file in the HID bootloader folder specifically designed for the application. These are located in the “Application Files” folder in each of the respective bootloader folders. Copy this file from this folder into the application folder and add it to the target project. All of the possible interrupts should already be remapped. To use an interrupt, merely define the interrupt handler as you normally would if you weren’t using a bootloader.
    • The bootloader for PIC18 and PIC32 devices were not modified.

Release Notes > Library Migration > From v2.6 to v2.6a


From v2.5 to v2.6

Contents | Index | Home
Previous | Up | Next
From v2.5 to v2.6

  1. Include Files
    • The files that must be included into a project has changed from v2.5 to v2.6.
    • Version v2.5 of the MCHPFSUSB stack required multiple include files in order to work properly in device mode. The usb_device.h, usb.h, usb_config.h, and class specific files (i.e. - “./usb/usb_function_msd.h”) had to be included in all of the application files that accessed the USB stack as well as other common include files like the GenericTypeDefs.h and Compiler.h files.
    • In MHCPFSUSB v2.6, only the usb.h file and the class specific files (i.e. - “./usb/usb_function_msd.h”) must be included in the project. The usb_device.h and usb_config.h files should no longer be included in the application specific files.

  2. Include Search Paths and Build Directory Policy
    • The preferred include path list has changed since the initial v2.x release. MPLAB now support compiling projects with respect to the project file instead of the source file. This is now the preferred method. With this modification the required include paths are the following:
      • .
      • ../Microchip/Include
    • If your project file located in a different format than the example projects, please add or remove the appropriate path modifiers such that the include path indirectly points to the /Microchip/Include folder.
    • To change the build directory policy and set the include paths, go to the “Project->Build Options->Project” menu. On the directories tab, select the include directories from the show directories drop down box.

  3. Disabling Interrupt Handlers
    • In MCHPFSUSB v2.6, the interrupt handler routines are disabled through the usb_config.h file using the following definitions:
      • USB_DISABLE_SET_CONFIGURATION_HANDLER
      • USB_DISABLE_SUSPEND_HANDLER
      • USB_DISABLE_WAKEUP_FROM_SUSPEND_HANDLER
      • USB_DISABLE_SOF_HANDLER
      • USB_DISABLE_ERROR_HANDLER
      • USB_DISABLE_NONSTANDARD_EP0_REQUEST_HANDLER
      • USB_DISABLE_SET_DESCRIPTOR_HANDLER
      • USB_DISABLE_TRANSFER_COMPLETE_HANDLER
    • Defining any of these definitions in the usb_config.h file will disable the callback from the stack during these events. Please note that some of these events are required to be USB compliant. For example all USB devices must go into suspend mode when requested. The suspend handler is how the stack notifies the user that the bus has requested the device to go into suspend mode.
    • Also note that some device classes or demos may require certain handlers to be available in order to operate properly. For example, the audio class demo uses the start of frames provided by the SOF handler to properly synchronize the audio data playback.

Release Notes > Library Migration > From v2.5 to v2.6


Demos

Contents | Index | Home
Previous | Next
Demos
Topics
Name | Description
Device - Audio Microphone Basic Demo | This demo shows how to implement a simple USB microphone. This demo uses a pre-recorded sound file in flash and plays that file when a pushbutton is pressed.
Device - Audio MIDI Demo | This demo shows how to implement a simple bi-directional USB MIDI device.
Device - Audio Speaker Demo |
Device - Boot Loader - HID | In many types of applications, it is often desirable to be able to field update the firmware used on the flash microcontroller, such as to perform bug fixes, or to provide new features. Microchip’s flash memory based USB microcontrollers have self programming capability, and are therefore able to perform self updates of application firmware. This can be achieved by downloading a new firmware image (.hex file) through the USB port, and using the microcontroller’s self programming ability to update the flash memory. As of this release the “HID Bootloader” is intended to be used with all PIC18 and PIC24F released... more
Device - Boot Loader - MCHPUSB | The “MCHPUSB Bootloader” is a custom device class (requires driver installation) bootloader. The HID Bootloader is superior in a number of ways, and if developing a new application, it is recommended to consider developing with the HID bootloader instead. The MCHPUSB bootloader only supports the following microcontrollers: PIC18F4550, PIC18F4455, PIC18F2550, PIC18F2455, PIC18F4553, PIC18F4458, PIC18F2553, PIC18F2458, PIC18F4450, PIC18F2450.
Device - CCID Smart Card Reader |
Device - CDC Basic Demo | This example shows how to create a basic CDC demo. CDC devices appear like COM ports on the host computer and be communicated with via regular terminal software.
Device - CDC - Serial Emulator | This demo shows how to use the CDC class to create a USB to UART bridge device. For a more simple starting point in using CDC based solutions, please consider using the Device - CDC Basic Demo as a starting point instead of this demo.
Device - Composite - HID + MSD Demo | This document describes how to run the Composite HID + MSD demo. Composite devices allow a single USB peripheral to appear like two different devices/function on the computer.
Device - Composite - MSD + CDC Demo | This demo shows how to create a mass storage device (MSD) and communication device class (CDC) composite device.
Device - Composite - WinUSB + MSD Demo | This document describes how to run the Composite WinUSB + MSD demo. Composite devices allow a single USB peripheral to appear like two different devices/function on the computer.
Device - HID - Custom Demo |
Device - HID - Digitizer Demos | These are examples of HID digitizers. There are single, and various multi-point touch examples.
Device - HID - Joystick Demo | This demo shows how to create a USB joystick
Device - HID - Keyboard Demo | This example shows how to create a USB keyboard and how to send data to the host.
Device - HID - Mouse Demo | This demo is a simple mouse demo that causes the mouse to move in a circle on the screen.
Device - HID - Uninterruptible Power Supply |
Device - LibUSB Generic Driver Demo |
Device - Mass Storage - Internal Flash Demo | This demo uses the selected hardware platform as an drive on the computer using the internal flash of the device as the drive storage media. Connect the hardware platform to a computer through a USB cable. The device should appear as a new drive on the computer named “Drive Name”. The volume label or file information can be changed in the Files.c file located in the project directory.
Device - Mass Storage - SD Card Data Logger | This demo shows how to data log to an SD card using the Microchip MDD file system and present the data to the PC using the Mass Storage data class to appear like an SD card reader.
Device - Mass Storage - SD Card Reader | This demo shows how to implement a simple SD card reader
Device - MCHPUSB Generic Driver Demo |
Device - Personal Healthcare Device Class (PHDC) Demo | Four different medical device specialization demos are available for Personal Health Care Devices. 1) Blood Pressure Monitor Agent Demo 2) Glucose Meter Agent Demo 3) Thermometer Agent Demo 4) Weigh Scale Agent Demo
Device - WinUSB Generic Driver Demo |
Device - WinUSB High Bandwidth Demo |
Dual Role - MSD Host + HID Device | This demo shows how to create a dual role device (one that supports both host and device functionality.
Host - Audio MIDI Demo |
Host - Boot Loader - Thumb Drive Boot Loader |
Host - CDC Serial Demo | This demo shows how to interface to USB CDC devices. This typically includes many cell phone models and USB modems.
Host - Charger - Simple Charger |
Host - Composite - MSD+ CDC |
Host - Composite - HID + MSD |
Host - HID - Keyboard Demo | This demo shows how to interface to USB keyboards. Many USB barcode scanners also appear as a USB keyboard.
Host - HID - Mouse Demo |
Host - Mass Storage (MSD) - Simple Demo |
Host - Mass Storage - Thumb Drive Data Logger | This demo shows how to create a console based interface to a system that can read, write, and log data to a thumb drive. This demo is great for showing the various capabilities of the MDD library and the the USB host stack, but is a fairly complex demo. For a more simple introduction to interfacing to a thumb drive, consider starting from the Host - Mass Storage - Simple Demo instead of this demo.
Host - MCHPUSB - Generic Driver Demo | This demo shows how to interface to Vendor class devices. It uses "Device - MCHPUSB - Generic Driver Demo" as the target device.
Host - Printer - Print Screen Demo |
Host - Printer - Simple Full Sheet | This demo shows how to create a host that can send a simple print out to a full sheet printer.
Host - Printer - Simple Point of Sale (POS) | This demo shows how to create a simple embedded host application that talks to an Epson Point of Sale (POS) printer.
Loading a precompiled demo | This section describes how to load a pre-compiled demo hex file.
PC - WM_DEVICECHANGE Demo | This demo uses the "Device - HID Simple Custom Demo" as the firmware. Please refer to that demos documentation for the supported boards and setups. Before you can run the WM_DEVICECHANGE_Demo.exe executable, you will need to have the Microsoft® .NET Framework Version 2.0 Redistributable Package (later versions probably okay, but not tested) installed on your computer. Programs which were built in the Visual Studio® .NET languages require the .NET redistributable package in order to run. The redistributable package can be freely downloaded from Microsoft’s website. Users of Windows Vista® operating systems will not need to install the .NET framework, as... more
OTG - MCHPUSB Device/MCHPUSB Host Demo | This demo shows how to implement an OTG device. Both the device and the host are both MCHPUSB custom class demos. More information about the device portion of the demo and how it would work on other hosts can be found in the Device - MCHPUSB Generic Driver Demo section. More information about the host portion of this demo can be found in the Host - MCHPUSB Generic Driver Demo section.
Demos


Device - Audio Microphone Basic Demo

Contents | Index | Home
Previous | Up | Next
Device - Audio Microphone Basic Demo
Topics
Name
Description
Supported Demo Boards
Configuring the Hardware
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered... more
Running the Demo
This demo uses the selected hardware platform as a USB Microphone Device. The demo emulates a PCM, 16 bits/Sample, 8000 Samples/ second, mono Microphone. Connect the device to the computer. Open a sound recording software package. Each sound recording software interface is different so the following instructions may not apply the to software package you are using. Please refer to the user’s manual for the software package you are using for more details of how to configure that tool for Sound recording.
Using Sound Recorder [Windows Computers]
Open Sound Recorder from Start->Programs->Accessories->Entertainement->Sound Recorder. Click on File-> Properties.

Now the ‘Properties... more
Demos > Device - Audio Microphone Basic Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - Audio Microphone Basic Demo > Supported Demo Boards


Configuring the Hardware

Contents | Index | Home
Previous | Up | Next
Configuring the Hardware

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24F64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - Audio Microphone Basic Demo > Configuring the Hardware


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo uses the selected hardware platform as a USB Microphone Device. The demo emulates a PCM, 16 bits/Sample, 8000 Samples/ second, mono Microphone. Connect the device to the computer. Open a sound recording software package. Each sound recording software interface is different so the following instructions may not apply the to software package you are using. Please refer to the user’s manual for the software package you are using for more details of how to configure that tool for Sound recording.

Using Sound Recorder [Windows Computers]

Open Sound Recorder from Start->Programs->Accessories->Entertainement->Sound Recorder. Click on File-> Properties.

Now the ‘Properties for Sound’ Window gets opened as shown below. Click on ‘Convert Now’ button.

This opens up the ‘Sound Selection’ window as shown below.

Change the ‘Attributes’ to “8.00kHz, 16 Bit, Mono 15kb/sec” in the ‘Sound Selection’ Window.

Click on OK button on the ‘Sound Selection’ Window. Click OK button on the ‘Properties for Sound’ Window.

Click on the Record Button on the Sound Recorder.

At this point you can press the pushbutton on the demo board and it will record a voice that is stored in the USB device. Once you finish with the recording click on the ‘Play’ button to play the recorded voice which can be heard through your computer Speaker.

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick | S1
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Demos > Device - Audio Microphone Basic Demo > Running the Demo


Device - Audio MIDI Demo

Contents | Index | Home
Previous | Up | Next
Device - Audio MIDI Demo
Topics
Name
Description
Supported Demo Boards
Configuring the Hardware
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered... more
Running the Demo
This demo uses the selected hardware platform as a USB MIDI device. Connect the device to the computer. Open a MIDI recording software package. Each MIDI recording software interface is different so the following instructions may not apply the to software package you are using. Please refer to the user’s manual for the software package you are using for more details of how to configure that tool for a USB MIDI input.
In this demo each time you press the button on the board, it will cycle through a series of notes.
Demos > Device - Audio MIDI Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - Audio MIDI Demo > Supported Demo Boards


Configuring the Hardware

Contents | Index | Home
Previous | Up | Next
Configuring the Hardware

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24F64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - Audio MIDI Demo > Configuring the Hardware


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo uses the selected hardware platform as a USB MIDI device. Connect the device to the computer. Open a MIDI recording software package. Each MIDI recording software interface is different so the following instructions may not apply the to software package you are using. Please refer to the user’s manual for the software package you are using for more details of how to configure that tool for a USB MIDI input.

In this demo each time you press the button on the board, it will cycle through a series of notes.

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick | S1
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Topics
Name | Description
Garage Band '08 [Macintosh Computers] | Open Garage Band. If you haven’t opened Garage Band before you will see an opening window. Select “Create New Music Project” The next window will prompt you for information about the song. Change any of the information is desired. Click “Create” when done. The Garage Band main window will open. In this window there should be a single default track if the USB device is already attached. At this point you can press the pushbutton on the demo board and it will cycle through a series of notes and play these notes through the computer speakers.
Using Linux MultiMedia Studio (LMMS) [Linux and Windows Computers] | In this example we will be using Linux MultiMedia Studio (LMMS) available at [image] http://sourceforge.net/projects/lmms/. Install LMMS. Attach the demo board to the computer. Make sure to attach the USB Audio MIDI example board to the computer before opening LMMS as LMMS polls for USB MIDI devices upon opening but may not find the devices attached after the program is opened. Click on the instrument plug-in button and click and drag the desired instrument plug in to the song editor window. Once the new instrument is available in the song editor window, “click on the actions” for this track button.... more
Demos > Device - Audio MIDI Demo > Running the Demo


Garage Band '08 [Macintosh Computers]

Contents | Index | Home
Previous | Up | Next
Garage Band '08 [Macintosh Computers]

Open Garage Band. If you haven’t opened Garage Band before you will see an opening window. Select “Create New Music Project”

The next window will prompt you for information about the song. Change any of the information is desired. Click “Create” when done.

The Garage Band main window will open. In this window there should be a single default track if the USB device is already attached. At this point you can press the pushbutton on the demo board and it will cycle through a series of notes and play these notes through the computer speakers.

Demos > Device - Audio MIDI Demo > Running the Demo > Garage Band '08 [Macintosh Computers]


Using Linux MultiMedia Studio (LMMS) [Linux and Windows Computers]

Contents | Index | Home
Previous | Up | Next
Using Linux MultiMedia Studio (LMMS) [Linux and Windows Computers]

In this example we will be using Linux MultiMedia Studio (LMMS) available at [image] http://sourceforge.net/projects/lmms/. Install LMMS. Attach the demo board to the computer. Make sure to attach the USB Audio MIDI example board to the computer before opening LMMS as LMMS polls for USB MIDI devices upon opening but may not find the devices attached after the program is opened.

Click on the instrument plug-in button and click and drag the desired instrument plug in to the song editor window.

Once the new instrument is available in the song editor window, “click on the actions” for this track button. Select the “MIDI > Input > USB Audio Device” option.

If you open this option again you should see a green check mark indicating that the device is selected as the input.

At this point you can press the pushbutton on the demo board and it will cycle through a series of notes and play these notes through the computer speakers.

Demos > Device - Audio MIDI Demo > Running the Demo > Using Linux MultiMedia Studio (LMMS) [Linux and Windows Computers]


Device - Audio Speaker Demo

Contents | Index | Home
Previous | Up | Next
Device - Audio Speaker Demo
Topics
Name
Description
Supported Demo Boards
Configuring the Hardware
PICDEM FS USB:
  1. If header J6 is not populated on the board, you will need to populate it with a female header
  2. Connect the Speech Playback Board.
PIC18 Explorer Based Demos
For all of the PIC18 Explorer based demo boards, please follow the following instructions:
  1. Set switch S4 to the "ICE" position
  2. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC18F46J50 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options are shorted together.
    2. Short JP3. This allows the demo board to be powered through the USB bus power.
  • PIC18F47J53 Plug-In-Module:... more
Running the Demo
This demo functions as a speaker when plugged into a computer. Using any feature on the computer that normal produces sound on the speaker will work with this demo.
Please note that some applications lock into a sound source when they open or close (such as some web browsers or plug-ins), so that if you plug in the speaker with the webpage or video already playing, the sound might not get redirected to the USB based speakers until you close and reopen the browser.
The audio device created in this demo has the following characteristics:
  • Sampling rate of 48 KHz... more
Demos > Device - Audio Speaker Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PICDEM FS USB | 1
PIC18F46J50 Plug-In-Module (PIM) | 1, 2
PIC18F47J53 Plug-In-Module (PIM) | 1, 2
PIC18F87J50 Plug-In-Module (PIM) | 1, 2
PIC24FJ64GB004 Plug-In-Module (PIM) | 1, 3
PIC24FJ256GB110 Plug-In-Module (PIM) | 1, 3
PIC24FJ256GB210 Plug-In-Module (PIM) | 1, 3
PIC24EP512GU810 Plug-In-Module (PIM) | 1, 3
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1, 3
PIC32 USB Plug-In-Module (PIM) | 1, 3
PIC32 CAN-USB Plug-In-Module (PIM) | 1, 3

Notes:

  1. These boards require the Speech Playback PICTail/PICTail+ daughter board in order to run this demo.
  2. This board can not be used by itself. It requires a PIC18 Explorer board in order to operate with this demo.
  3. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Device - Audio Speaker Demo > Supported Demo Boards


Configuring the Hardware

Contents | Index | Home
Previous | Up | Next
Configuring the Hardware

PICDEM FS USB:

  1. If header J6 is not populated on the board, you will need to populate it with a female header
  2. Connect the Speech Playback Board.
PIC18 Explorer Based Demos

For all of the PIC18 Explorer based demo boards, please follow the following instructions:

  1. Set switch S4 to the "ICE" position
  2. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC18F46J50 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options are shorted together.
    2. Short JP3. This allows the demo board to be powered through the USB bus power.
  • PIC18F47J53 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options are shorted together.
    2. Short JP3. This allows the demo board to be powered through the USB bus power.
  • PIC18F87J50 Plug-In-Module:
    1. Short JP1 such that the "R" and the "U" options are shorted together.
    2. Short JP4. This allows the demo board to be powered through the USB bus power.
    3. Short JP5. This enabled the LED operation on the board.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to the center pin
    3. Short J2 pin 1 (marked "Temp") to the center pin
    4. Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    1. Short JP1 "U" option to the center pin
    2. Short JP2 "U" option to the center pin
    3. Short JP3 "U" option to the center pin
    4. Short JP4
  • PIC24EP512GU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    1. Open J10
    2. Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

Demos > Device - Audio Speaker Demo > Configuring the Hardware


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo functions as a speaker when plugged into a computer. Using any feature on the computer that normal produces sound on the speaker will work with this demo.

Please note that some applications lock into a sound source when they open or close (such as some web browsers or plug-ins), so that if you plug in the speaker with the webpage or video already playing, the sound might not get redirected to the USB based speakers until you close and reopen the browser.

The audio device created in this demo has the following characteristics:

  • Sampling rate of 48 KHz
  • 1 Channel (Mono)
  • PCM Format - 16 bits per Sample
  • Asynchronous Audio Endpoint
And the following audio topology:

The feature unit only supports the Mute control.

Demos > Device - Audio Speaker Demo > Running the Demo


Device - Boot Loader - HID

Contents | Index | Home
Previous | Up | Next
Device - Boot Loader - HID

In many types of applications, it is often desirable to be able to field update the firmware used on the flash microcontroller, such as to perform bug fixes, or to provide new features. Microchip’s flash memory based USB microcontrollers have self programming capability, and are therefore able to perform self updates of application firmware. This can be achieved by downloading a new firmware image (.hex file) through the USB port, and using the microcontroller’s self programming ability to update the flash memory.

As of this release the “HID Bootloader” is intended to be used with all PIC18 and PIC24F released Microchip USB flash microcontrollers.

The bootloader comes with full firmware and PC software source code, and is intended to be easily modified to support future Microchip USB microcontrollers. The PC software is designed to be independent of the microcontroller device being used, so only one PC application is needed to update any of the microcontroller devices.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered... more
Running the Demo
All variants of the HID Bootloader firmware are intended to interface with the “HIDBootLoader.exe” PC application.
Before you can run the HIDBootLoader.exe executable, you will need to have the Microsoft® .NET Framework Version 2.0 Redistributable Package (later versions probably okay, but not tested) installed on your computer. Programs which were built in the Visual Studio® .NET languages require the .NET redistributable package in order to run. The redistributable package can be freely downloaded from Microsoft’s website. Users of Windows Vista® and Windows 7 operating systems will not need to install the .NET framework, as it comes pre-installed as part of... more
Implementation and Customization Details
Demos > Device - Boot Loader - HID


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Device - Boot Loader - HID > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
PIC24FJ64GB502 Microstick:
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - Boot Loader - HID > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

All variants of the HID Bootloader firmware are intended to interface with the “HIDBootLoader.exe” PC application.

Before you can run the HIDBootLoader.exe executable, you will need to have the Microsoft® .NET Framework Version 2.0 Redistributable Package (later versions probably okay, but not tested) installed on your computer. Programs which were built in the Visual Studio® .NET languages require the .NET redistributable package in order to run. The redistributable package can be freely downloaded from Microsoft’s website. Users of Windows Vista® and Windows 7 operating systems will not need to install the .NET framework, as it comes pre-installed as part of the operating system.

The source code for the HIDBootLoader.exe file was created in Microsoft Visual C++® 2005 Express Edition. The source code can be found in the “<Install Directory>\USB USB Device - Bootloaders\HID - Bootloader\HID Bootloader - PC Software” directory. Microsoft currently distributes Visual C++ 2005 Express Edition for free, and can be downloaded from Microsoft’s website. When downloading Microsoft Visual C++ 2005 Express Edition, also make sure to download and install the Platform SDK, and follow Microsoft’s instructions for integrating it with the development environment.

It is not necessary to install either Microsoft Visual C++ 2005 or the Platform SDK in order to use the HID Bootloader. These are only required in order to modify or recompile the PC software source code.

To run the application, simply double click on the executable, which can be found in the following directory: “<Install Directory>\USB USB Device - Bootloaders\HID – Bootloader”. Upon launching the application, a window like that shown below should appear:

If the application fails to launch, but instead causes a non-descript error message pop up box to appear, it is likely that the .NET framework redistributable has not been installed. Please install the .NET framework and try again.

Upon launch, the HIDBootLoader.exe program will do a search, looking for HID class devices with VID = 0x04D8, and PID = 0x003C. This is the same VID/PID that is used in the HID Bootloader firmware projects, which is found in the following directory: “<Install Directory>\USB Device - Bootloaders\HID - Bootloader\HID Bootloader - Firmware for (microcontroller family name)”. When commercializing a product that will be using this bootloader, it is important to change the VID/PID in both the firmware and the PC application source code.

In order to use the bootloader, you will need to program a device with the bootloader firmware. If using a Microchip demo board, such as the PIC18F46J50 FS USB Demo Board (also known as “PIC18F46J50 PIM”), precompiled demo .hex files can be used (without any modifications). These pre-compiled .hex files are located in the “<Install Directory>\USB Precompiled Demos” folder. After the HID bootloader firmware (ex: the .hex file named “USB Device - HID - HID Bootloader - C18 – PIC(device name).hex” has been programmed, continuously hold down the relevant pushbutton on the demo board, and then tap and release the MCLR pushbutton. After exiting from MCLR reset, the bootloader firmware will make a quick check of the pushbutton I/O pin state. If the pushbutton is pressed, it will stay in the bootloader.

By default, the I/O pin that gets checked after exiting from reset will be:

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick | S1
PIC24FJ256DA210 Development Board | S1

Notes:

1) This is the button number on the Explorer 16.

Assuming that the device is connected correctly, and in bootload mode, the HIDBootLoader.exe application should automatically detect the device. The application uses WM_DEVICECHANGE messages in order to make for a smooth plug and play experience. Once the application detects the device, some of the buttons in the application should automatically become enabled.

At this point, “main application” firmware images can be loaded and programmed using the bootloader. The main application should not try to put code in addresses 0x00-0xFFF, because the bootloader will not attempt to program these locations (which is where the bootloader firmware resides). Therefore, when building the main application hex files, a modified linker script should be used. The “rm18f87j50.lkr” file included in the various USB device projects (such as in the “HID Mouse” project) shows an example of how this can be done.

By default, most of the pre-compiled demo .hex files are pre-configured to be useable with the HID Bootloader. Therefore, the pre-compiled demo firmware files, such as the “USB Device - HID - Mouse - C18 - PIC18F87J50 PIM.hex” can be directly programmed with the bootloader.

After an appropriate hex file has been programmed, simply reset the microcontroller (without holding down the bootloader entry pushbutton) to exit the bootloader and begin running the main application code. The main application firmware should begin running.

NOTE: The “USB Device - Mass Storage - SD Card reader” and “USB Device - Mass Storage - SD Card data logger” demos make use of the SD Card PICtail™ Daughter Board (Microchip Direct: AC164122). This PICtail uses the RB4 I/O pin for the card detect (CD) signal when used with the PIC18F87J50 FS USB Demo Board (PIM), and is actively driven by the PICtail. The active drive overpowers the pull up resistor on the RB4 pushbutton (on the PIC18F87J50 FS USB Demo Board). As a result, if the PIC18F87J50 is programmed with the HID bootloader, and an SD Card is installed in the socket when the microcontroller comes out of reset, the firmware will immediately enter the bootloader (irrespective of the RB4 pushbutton state). To exit the bootloader firmware, remove the SD Card from the SD Card socket, and tap the MCLR button. When the SD Card is not plugged in, the PICtail will drive the card detect signal (which is connected to RB4) logic high, which will enable the bootloader to exit to the main application after coming out of reset. Once the main application firmware is operating, the SD Card can be plugged in. The SD Card is “hot-swappable” and should be recognized by the host upon insertion. To avoid this inconvenience when using the bootloader with the PICtail, it is suggested to modify the bootloader firmware to use some other I/O pin for bootloader entry, such as RB0 (which has a pushbutton on it on the HPC Explorer board).
Demos > Device - Boot Loader - HID > Running the Demo


Implementation and Customization Details

Contents | Index | Home
Previous | Up | Next
Implementation and Customization Details
Topics
Name | Description
Configuration Bits | Typically, when downloading new firmware images into the microcontroller, the configuration bit settings do not need to be modified. In some applications, it is sometimes desirable to be able to program new configuration bit settings into the microcontroller. Doing so entails a small amount of risk however, since it is potentially possible to program a new .hex file containing configuration bit settings that would be incompatible with USB operation (for example, if the oscillator settings are completely wrong). It is therefore generally recommended not to check the “Allow Configuration Word Programming” check box, unless strictly necessary. Special considerations should be... more
Vendor ID (VID) and Product ID (PID) | When commercializing a product that will be using a USB bootloader, always make sure to use a unique VID and PID combination. Do not use the default VID/PID combination (from the bootloader firmware and PC application) in your commercialized product. If a PC has two devices, both containing the same bootloader with VID/PID = 0x04D8/0x003C, one made by manufacturer A (ex: a keyboard), and another device made by manufacturer B (ex: a CDC serial emulation device), then it is not certain which device the HID Bootloader PC application will connect to. The HID Bootloader PC application will search the system... more
Part Specific Details |
Demos > Device - Boot Loader - HID > Implementation and Customization Details


Configuration Bits

Contents | Index | Home
Previous | Up | Next
Configuration Bits

Typically, when downloading new firmware images into the microcontroller, the configuration bit settings do not need to be modified. In some applications, it is sometimes desirable to be able to program new configuration bit settings into the microcontroller. Doing so entails a small amount of risk however, since it is potentially possible to program a new .hex file containing configuration bit settings that would be incompatible with USB operation (for example, if the oscillator settings are completely wrong). It is therefore generally recommended not to check the “Allow Configuration Word Programming” check box, unless strictly necessary. Special considerations should be kept in mind regarding the “Allow Configuration Word Programming” check box:

On currently supported PIC18xxJxx devices, the configuration words are stored in flash memory at the end of the implemented program memory space. However, the minimum erase page size is currently fixed at 1024 bytes for the currently supported microcontrollers. Therefore, if the “Allow Configuration Word Programming” box is left unchecked, then the last page of program memory will not get erase and will not get updated by the bootloader. If the main application firmware .hex file contains program code on the last page of implemented flash memory, it will not get updated. This can however be worked around, simply by checking the “Allow Configuration Word Programming” check box. The bootloader firmware will then erase and reprogram the last 1024 byte page of flash memory (which contains the configuration words).

Demos > Device - Boot Loader - HID > Implementation and Customization Details > Configuration Bits


Vendor ID (VID) and Product ID (PID)

Contents | Index | Home
Previous | Up | Next
Vendor ID (VID) and Product ID (PID)

When commercializing a product that will be using a USB bootloader, always make sure to use a unique VID and PID combination. Do not use the default VID/PID combination (from the bootloader firmware and PC application) in your commercialized product. If a PC has two devices, both containing the same bootloader with VID/PID = 0x04D8/0x003C, one made by manufacturer A (ex: a keyboard), and another device made by manufacturer B (ex: a CDC serial emulation device), then it is not certain which device the HID Bootloader PC application will connect to. The HID Bootloader PC application will search the system for any devices attached with matching VID/PID, but if there is more than one simultaneously attached, it will connect to the first one it finds. This could potentially lead to inadvertent flash updating of the wrong product, leading to unexpected and undesired consequences. By using a unique VID/PID for each product line of a given type, this ensures that the HID bootloader PC application will only find the correct device. To change the VID and PID in the bootloader firmware, simply change the USB device descriptor and rebuild the firmware. To change the HID Bootloader PC application, change the “MY_DEVICE_ID” string at the top of Form1.h, so that the VID/PID matches the firmware and then rebuild the project. The PC application is built in Microsoft Visual C++ 2005 .NET express edition. Microsoft currently distributes the express editions of Visual Studio languages for free download on their website.

Demos > Device - Boot Loader - HID > Implementation and Customization Details > Vendor ID (VID) and Product ID (PID)


Part Specific Details

Contents | Index | Home
Previous | Up | Next
Part Specific Details
Topics
Name | Description
PIC18F | Software entry to boot loader from application: In the MCHPFSUSB v2.4 release, the PIC18F87J50 family and PIC18F46J50 family versions of the HID bootloader firmware also contains an alternative software only entry method into the bootloader. If executing the main application (non-bootloader) software, the main application may enter the bootloader by: 1. Clearing the global interrupt enable bit (INTCON<GIEH> 2. Execute the instruction: “_asm goto 0x001C _endasm” It is not necessary to have the I/O pin in the logic low state when using this software entry method. Memory Map Overview: As configured by default, the HID bootloader firmware uses... more
PIC24F | Please refer to the PIC24F Boot Loader Implementation Specific Details appendix section for more information about how the boot loader works and fits in a PIC24F specifically.
Demos > Device - Boot Loader - HID > Implementation and Customization Details > Part Specific Details


PIC18F

Contents | Index | Home
Previous | Up | Next
PIC18F

Software entry to boot loader from application:

In the MCHPFSUSB v2.4 release, the PIC18F87J50 family and PIC18F46J50 family versions of the HID bootloader firmware also contains an alternative software only entry method into the bootloader. If executing the main application (non-bootloader) software, the main application may enter the bootloader by:

1. Clearing the global interrupt enable bit (INTCON<GIEH>

2. Execute the instruction: “_asm goto 0x001C _endasm”

It is not necessary to have the I/O pin in the logic low state when using this software entry method.

Memory Map Overview:

As configured by default, the HID bootloader firmware uses the below memory mapping. The memory map can readily be modified by editing the HID bootloader firmware project. It should not be necessary to modify the PC application source code to change the memory map.

0x000-0xFFF - Occupied by the HID bootloader firmware

  • 0x08 (high priority interrupt vector) contains a “goto 0x1008” instruction
  • 0x18 (low priority interrupt vector) contains a “goto 0x1018” instruction
  • 0x1C is a main application firmware software only entry point into the bootloader (this entry point is currently implemented on the PIC18F87J50 family and PIC18F46J50 family versions of the firmware)
  • 0x1000-(end of device flash memory) – Available for use by the main application firmware
  • If programming in C18, normally should place a “goto _startup” instruction at address 0x1000, to allow the C initializer to run
Vector Remapping:

As currently configured, the bootloader occupies the address range 0x00-0xFFF (on PIC18), which means it occupies the PIC18 reset, high priority, and low priority interrupt vector locations. The bootloader firmware itself does not enable or use interrupts. In order to make interrupts available for use by the main application firmware, the interrupt vectors are effectively “remapped” by placing goto instructions at the actual vector locations. In other words:

Address 0x08 (high priority interrupt vector), contains a “goto 0x1008”.

Address 0x18 (low priority interrupt vector), contains a “goto 0x1018”.

For example, if a high priority interrupt is enabled and used in the main application firmware, the following will occur:

1. Main application enables the interrupt source.

2. Sometime later, the interrupt event occurs.

3. Microcontroller PC jumps to 0x08.

4. Microcontroller executes a “goto 0x1008”.

5. Microcontroller executes the main application interrupt handler routine, which has an entry point at address 0x1008. (Note: The interrupt handler routine itself is not required to be at address 0x1008, instead another bra/goto may optionally be located at 0x1008 to get to the real handler routine)

Demos > Device - Boot Loader - HID > Implementation and Customization Details > Part Specific Details > PIC18F


PIC24F

Contents | Index | Home
Previous | Up | Next
PIC24F

Please refer to the PIC24F Boot Loader Implementation Specific Details appendix section for more information about how the boot loader works and fits in a PIC24F specifically.

Demos > Device - Boot Loader - HID > Implementation and Customization Details > Part Specific Details > PIC24F


Device - Boot Loader - MCHPUSB

Contents | Index | Home
Previous | Up | Next
Device - Boot Loader - MCHPUSB

The “MCHPUSB Bootloader” is a custom device class (requires driver installation) bootloader. The HID Bootloader is superior in a number of ways, and if developing a new application, it is recommended to consider developing with the HID bootloader instead. The MCHPUSB bootloader only supports the following microcontrollers: PIC18F4550, PIC18F4455, PIC18F2550, PIC18F2455, PIC18F4553, PIC18F4458, PIC18F2553, PIC18F2458, PIC18F4450, PIC18F2450.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
Running the Demo
The MCHPUSB bootloader uses the PICDEM FS USB Demo Tool (pdfsusb.exe) for downloading/programming new firmware images from the PC. This program can be found in the following directory: “<install directory>\USB Tools\Pdfsusb”. Documentation describing how to use this tool is found in chapter 3 of the PICDEM FS USB Demo Board User’s Guide (DS51526). This document can be found in the following directory, “<install directory>\Microchip\USB\Documentation\Board Information\51526b.pdf”. (Note: A newer version of this document may exist, please check the Microchip website. The 51526b.pdf version of the document is written with the assumption that the user is working with MCHPFSUSB v1.x, which uses... more
Implementation and Customization Details
Two USB Stacks Approach:
The bootloader firmware contains all of the code needed for self programming, as well as all of the necessary code to enumerate as a custom (vendor) class USB device (which uses the mchpusb.sys custom driver).
The MCHPUSB bootloader firmware is an entirely stand alone MPLAB IDE based project. The “main application” firmware should be a separate MPLAB IDE based project altogether. The main application firmware is intended to be entirely independent of the bootloader. This requires that the main application should also contain a fully functional and complete USB stack. However, only one of the... more
Demos > Device - Boot Loader - MCHPUSB


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PICDEM FS USB |
Demos > Device - Boot Loader - MCHPUSB > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

PICDEM FS USB:

  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - Boot Loader - MCHPUSB > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

The MCHPUSB bootloader uses the PICDEM FS USB Demo Tool (pdfsusb.exe) for downloading/programming new firmware images from the PC. This program can be found in the following directory: “<install directory>\USB Tools\Pdfsusb”. Documentation describing how to use this tool is found in chapter 3 of the PICDEM FS USB Demo Board User’s Guide (DS51526). This document can be found in the following directory, “<install directory>\Microchip\USB\Documentation\Board Information\51526b.pdf”. (Note: A newer version of this document may exist, please check the Microchip website. The 51526b.pdf version of the document is written with the assumption that the user is working with MCHPFSUSB v1.x, which uses a somewhat different directory structure compared to that of MCHPFSUSB v2.2)

Demos > Device - Boot Loader - MCHPUSB > Running the Demo


Implementation and Customization Details

Contents | Index | Home
Previous | Up | Next
Implementation and Customization Details

Two USB Stacks Approach:

The bootloader firmware contains all of the code needed for self programming, as well as all of the necessary code to enumerate as a custom (vendor) class USB device (which uses the mchpusb.sys custom driver).

The MCHPUSB bootloader firmware is an entirely stand alone MPLAB IDE based project. The “main application” firmware should be a separate MPLAB IDE based project altogether. The main application firmware is intended to be entirely independent of the bootloader. This requires that the main application should also contain a fully functional and complete USB stack. However, only one of the USB stacks is used at any given time.

With this approach, the main application firmware need not be a custom class device (nor does it need to be a “composite” device). In order to switch between the main application and the USB bootloader, the device “functionally detaches” itself from the USB bus (by temporarily turning off the pull up resistor), and then re-enumerates as the other firmware project.

Bootloader Entry Method:

As currently configured, the bootloader firmware resides in program memory in address range 0x00-0x7FF. Almost immediately after coming out of reset, the bootloader firmware checks I/O pin RB4 (which happens to have a pushbutton attached to it on the PICDEM™ FS USB Demo Board). If the pushbutton is not pressed, the bootloader will immediately exit the bootloader and go to the main application firmware “reset vector”.

In other words, the bootloader effectively does this:

//Device powers up, and comes out of POR

if(RB4 pushbutton is not pressed) --> goto 0x800 //main application “reset vector”

if(RB4 pushbutton is pressed) --> goto/stay in main bootloader project.

Effectively, the “reset” vector for the main application firmware is at address 0x800. In the main application firmware project, the user should place a “goto _startup” at address 0x800. This will allow the C initializer code to execute, which will initialize things like the software stack pointers and any user “idata” variables. For an example, see one of the USB device firmware projects, such as the “HID - Mouse” project. The PICDEM FSUSB version of this project is already configured to allow the generated .hex file to function along with the USB bootloader project.

Vector Remapping:

As currently configured, the bootloader occupies the address range 0x00-0x7FF, which means it occupies the PIC18 reset, high priority, and low priority interrupt vector locations. The bootloader firmware itself does not enable or use interrupts. In order to make interrupts available for use by the main application firmware, the interrupt vectors are effectively “remapped” by placing goto instructions at the actual vector locations. In other words:

Address 0x08 (high priority interrupt vector), contains a “goto 0x808”.

Address 0x18 (low priority interrupt vector), contains a “goto 0x818”.

For example, if a high priority interrupt is enabled and used in the main application firmware, the following will occur:

1. Main application enables the interrupt source.

2. Sometime later, the interrupt event occurs.

3. Microcontroller PC jumps to 0x08.

4. Microcontroller executes a “goto 0x808”.

5. Microcontroller executes the main application interrupt handler routine, which has an entry point at address 0x808. (Note: The interrupt handler routine itself might not be at address 0x808, but another bra/goto may be located at 0x808 to get to the real routine)

Demos > Device - Boot Loader - MCHPUSB > Implementation and Customization Details


Device - CCID Smart Card Reader

Contents | Index | Home
Previous | Up | Next
Device - CCID Smart Card Reader
Topics
Name
Description
Supported Demo Boards
Configuring the Hardware
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
  3. One side of J4 port pins of the SC (Smart/Sim Card) PICTail Board match with the J11 port of LPC board. Insert the matching side of J4 port of SC PICTail board into the J11 port of LPC board. Make sure that the Smart Card Connector is facing towards the LPC board. Insert the Smart Card in SC PICTail board.
  4. Short Tx & Rx line of the UART at J13 port... more
Running the Demo
This demo allows the selected hardware platform as a USB CCID Smart Card Reader to the host. In order to run this demo first compile and program the target device. Attach the device to the host. If the host is a Windows PC and this is the first time you have plugged this device into the computer then you may be prompted with “New hardware found” wizard.

Click on Next to continue.

Select “Install the Software automatically” and click on next.

Click on Next to continue.

Click on Finish to complete the installation.
Note: Microsoft states that Usbccid.sys is compliant... more
Demos > Device - CCID Smart Card Reader


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit | 1
PICDEM FS USB | 1
PIC18F46J50 Plug-In-Module (PIM) | 1, 2
PIC18F47J53 Plug-In-Module (PIM) | 1, 2
PIC18F87J50 Plug-In-Module (PIM) | 1, 2
PIC24FJ256GB110 Plug-In-Module (PIM) | 1, 3

Notes:

  1. These boards require the Smart/Sim Card PICTail/PICTail+ daughter board in order to run this demo.
  2. This board can not be used by itself. It requires a PIC18 Explorer board in order to operate with this demo.
  3. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Device - CCID Smart Card Reader > Supported Demo Boards


Configuring the Hardware

Contents | Index | Home
Previous | Up | Next
Configuring the Hardware

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
  3. One side of J4 port pins of the SC (Smart/Sim Card) PICTail Board match with the J11 port of LPC board. Insert the matching side of J4 port of SC PICTail board into the J11 port of LPC board. Make sure that the Smart Card Connector is facing towards the LPC board. Insert the Smart Card in SC PICTail board.
  4. Short Tx & Rx line of the UART at J13 port using a wire and connect it to I/O pin of SC PICTail board.
  5. Connect RB6 (of J13 port) to “Card Present” signal pin of SC PICTail board.

PICDEM FS USB:

  1. If header J6 is not populated on the board, you will need to populate it with a female header
  2. Connect the Speech Playback Board.
  3. The Jumper JP11 needs to be open in this board. In some revision of the board it may necessary to cut the PCB track that is shorting the jumper.
  4. Insert the J2 port of SC (Smart/Sim Card) PICTail card into J3 port of PICDEM FSUSB board as per the pin configuration. Insert the Smart Card in SC PICTail board.
PIC18 Explorer Based Demos

For all of the PIC18 Explorer based demo boards, please follow the following instructions:

  1. Set switch S4 to the "ICE" position
  2. Insert the J4 port of SC (Smart/Sim Card) PICTail Board to the J3 port of HPC Explorer board. Make sure that the Smart Card Connector is facing towards the HPC Explorer board. Insert the Smart Card in SC PICTail Board.
  3. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC18F46J50 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options are shorted together.
    2. Short JP3. This allows the demo board to be powered through the USB bus power.
  • PIC18F47J53 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options are shorted together.
    2. Short JP3. This allows the demo board to be powered through the USB bus power.
  • PIC18F87J50 Plug-In-Module:
    1. Short JP1 such that the "R" and the "U" options are shorted together.
    2. Short JP4. This allows the demo board to be powered through the USB bus power.
    3. Short JP5. This enabled the LED operation on the board.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Insert the Smart/Sim Card daughter board into the first PICTail+ connector of the Explorer 16 (J5)

Demos > Device - CCID Smart Card Reader > Configuring the Hardware


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo allows the selected hardware platform as a USB CCID Smart Card Reader to the host. In order to run this demo first compile and program the target device. Attach the device to the host. If the host is a Windows PC and this is the first time you have plugged this device into the computer then you may be prompted with “New hardware found” wizard.

Click on Next to continue.

Select “Install the Software automatically” and click on next.

Click on Next to continue.

Click on Finish to complete the installation.

Note: Microsoft states that Usbccid.sys is compliant with Microsoft Windows 2000, Windows XP, and Microsoft Windows Server 2003 operating systems, and is available on Windows Update (http://www.microsoft.com/whdc/device/input/smartcard/usb_ccid.mspx). You might need to do a ‘Windows update’ if you windows computer does not have usbccid driver (or software required to install a usbccid driver) currently.

Using jSmartCardExplorer

Download SmartCardExplorer from [image] http://www.primianotucci.com/default.php?view=112. Attach the demo board to the Computer. Ensure that the Smart Card is inserted on the SC Pictail Card. Launch the jSmartCardExplorer Application.

Select Protocol T=0 or T=1 based on the type of Smart card you insert and click on Connect Button. If the Smart Card is inserted on the SC Pictail Card, the ‘Status’ field turns green and the ATR of the Smart Card is displayed on the ‘Card ATR’ field.

The APDU can be send to the Smart Card by clicking on the ‘Send’ Button in the Send APDU section. The Command and Data fields need to be filled before sending an APDU to the Smart Card. Please refer the Smart Card reference manual from the manufacturer of the Card for the Command list supported by the Card. The Response from the Smart Card is displayed in the APDU History Section.

A few sample commands for the ACS ACOS3 card is listed below.

Command | CLA | INS | P1 | P2 | LC | DATA | LE | Description
Select File | 80 | A4 | 00 | 00 | 02 | FF00 | 00 | Selects file FF00
Read Record | 80 | B2 | 00 | 00 | 00 | -- | 08 | Reads 8 bytes from record number 0 of FF00 file
Demos > Device - CCID Smart Card Reader > Running the Demo


Device - CDC Basic Demo

Contents | Index | Home
Previous | Up | Next
Device - CDC Basic Demo

This example shows how to create a basic CDC demo. CDC devices appear like COM ports on the host computer and be communicated with via regular terminal software.

Topics
Name
Description
Supported Demo Boards
Configuring the Hardware
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered... more
Running the Demo
This demo allows the device to appear like a serial (COM) port to the host. In order to run this demo first compile and program the target device. Attach the device to the host. If the host is a PC and this is the first time you have plugged this device into the computer then you may be asked for a .inf file.

Select the “Install from a list or specific location (Advanced)” option. Point to the “<Install Directory>\USB Device - CDC – Basic Demo\inf\win2k_winxp” directory.

Once the device is successfully installed, open up a terminal program, such as hyperterminal.... more
Demos > Device - CDC Basic Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - CDC Basic Demo > Supported Demo Boards


Configuring the Hardware

Contents | Index | Home
Previous | Up | Next
Configuring the Hardware

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - CDC Basic Demo > Configuring the Hardware


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo allows the device to appear like a serial (COM) port to the host. In order to run this demo first compile and program the target device. Attach the device to the host. If the host is a PC and this is the first time you have plugged this device into the computer then you may be asked for a .inf file.

Select the “Install from a list or specific location (Advanced)” option. Point to the “<Install Directory>\USB Device - CDC – Basic Demo\inf\win2k_winxp” directory.

Once the device is successfully installed, open up a terminal program, such as hyperterminal. Select the appropriate COM port. On most machines this will be COM5 or higher.

Once connected to the device, there are two ways to run this example project. Typing a key in the terminal window will result in the device echoing that key plus one. So if the user presses “a”, the device will echo “b”. If the pushbutton is pressed the device will echo “ – Button Pressed – “ to the terminal window.

Note: Some terminal programs, like hyperterminal, require users to click the disconnect button before removing the device from the computer. Failing to do so may result in having to close and open the program again in order to reconnect to the device.

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick | S1
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Demos > Device - CDC Basic Demo > Running the Demo


Device - CDC - Serial Emulator

Contents | Index | Home
Previous | Up | Next
Device - CDC - Serial Emulator

This demo shows how to use the CDC class to create a USB to UART bridge device. For a more simple starting point in using CDC based solutions, please consider using the Device - CDC Basic Demo as a starting point instead of this demo.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No board specific settings are required
PIC18 Explorer Based Demos
For all of the PIC18 Explorer based demo boards, please follow the following instructions:
  1. Set switch S4 to the "ICE" position
  2. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC18F46J50 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options are shorted together.
    2. Short JP3. This allows the demo... more
Running the Demo
This demo allows the device to appear like a serial (COM) port to the host. This demo will take data sent over the USB CDC interface and send it on the UART of the microcontroller.
In order to run this demo first compile and program the target device. Attach the device to the host with the USB cable. Also connect the RS232 port of the demo board to a computer. This computer and be the same computer as the USB connection or it can be a different computer. If the host is a PC and this is the first time... more
Demos > Device - CDC - Serial Emulator


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB | 1
PIC18F46J50 Plug-In-Module (PIM) | 1, 2
PIC18F47J53 Plug-In-Module (PIM) | 1, 2
PIC18F87J50 Plug-In-Module (PIM) | 1, 2
PIC24FJ64GB004 Plug-In-Module (PIM) | 1, 3
PIC24FJ256GB110 Plug-In-Module (PIM) | 1, 3
PIC24FJ256GB210 Plug-In-Module (PIM) | 1, 3
PIC24EP512GU810 Plug-In-Module (PIM) | 1, 3
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1, 3
PIC32 USB Plug-In-Module (PIM) | 1, 3
PIC32 CAN-USB Plug-In-Module (PIM) | 1, 3

Notes:

  1. These boards require the Speech Playback PICTail/PICTail+ daughter board in order to run this demo.
  2. This board can not be used by itself. It requires a PIC18 Explorer board in order to operate with this demo.
  3. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Device - CDC - Serial Emulator > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No board specific settings are required
PIC18 Explorer Based Demos

For all of the PIC18 Explorer based demo boards, please follow the following instructions:

  1. Set switch S4 to the "ICE" position
  2. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC18F46J50 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options are shorted together.
    2. Short JP3. This allows the demo board to be powered through the USB bus power.
  • PIC18F47J53 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options are shorted together.
    2. Short JP3. This allows the demo board to be powered through the USB bus power.
  • PIC18F87J50 Plug-In-Module:
    1. Short JP1 such that the "R" and the "U" options are shorted together.
    2. Short JP4. This allows the demo board to be powered through the USB bus power.
    3. Short JP5. This enabled the LED operation on the board.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to the center pin
    3. Short J2 pin 1 (marked "Temp") to the center pin
    4. Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    1. Short JP1 "U" option to the center pin
    2. Short JP2 "U" option to the center pin
    3. Short JP3 "U" option to the center pin
    4. Short JP4
  • PIC24EP512GU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    1. Open J10
    2. Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

Demos > Device - CDC - Serial Emulator > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo allows the device to appear like a serial (COM) port to the host. This demo will take data sent over the USB CDC interface and send it on the UART of the microcontroller.

In order to run this demo first compile and program the target device. Attach the device to the host with the USB cable. Also connect the RS232 port of the demo board to a computer. This computer and be the same computer as the USB connection or it can be a different computer. If the host is a PC and this is the first time you have plugged this device into the computer then you may be asked for a .inf file.

Select the “Install from a list or specific location (Advanced)” option. Point to the “<Install Directory>\USB Device - CDC – Serial Emulator\inf\” directory

Once the device is successfully installed, open up a terminal program, such as hyperterminal. Select the appropriate COM port for the USB virtual COM port. On most machines this will be COM5 or higher. On the computer where the RS232 cable it attached, open a second terminal program. Select the hardware COM port associated with that computer. Please insure that the baud rate for both terminal windows is the same.

Once everything is configured correctly, typing a key in one terminal window will result in the same data to show up in the second terminal window.

Note: Some terminal programs, like hyperterminal, require users to click the disconnect button before removing the device from the computer. Failing to do so may result in having to close and open the program again in order to reconnect to the device.
Demos > Device - CDC - Serial Emulator > Running the Demo


Device - Composite - HID + MSD Demo

Contents | Index | Home
Previous | Up | Next
Device - Composite - HID + MSD Demo

This document describes how to run the Composite HID + MSD demo. Composite devices allow a single USB peripheral to appear like two different devices/function on the computer.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to... more
Running the Demo
This demo uses the selected hardware platform as both a flash drive using the internal flash as storage and a custom HID device. It will appear to the computer as if two USB devices were attached.
For details how to run the demo for each of the functions please see the respective getting started documents: “USB Device – Mass Storage – Internal Flash” and “USB Device – HID – Simple Custom Demo”.
Demos > Device - Composite - HID + MSD Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - Composite - HID + MSD Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

PICDEM FS USB:

  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - Composite - HID + MSD Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo uses the selected hardware platform as both a flash drive using the internal flash as storage and a custom HID device. It will appear to the computer as if two USB devices were attached.

For details how to run the demo for each of the functions please see the respective getting started documents: “USB Device – Mass Storage – Internal Flash” and “USB Device – HID – Simple Custom Demo”.

NOTE: the “USB Device – HID – Simple Custom Demo” application is expecting a PID of 0x003F. Because these two different applications can’t have the same PID, this demo uses PID 0x0054. The PC application that corresponds to this application is only looking for devices with PID 0x003F so the PC application will not be able connect to this demo without modification. Modify the MY_DEVICE_ID field to "Vid_04d8&Pid_0054" and recompile. The MY_DEVICE_ID field is located in the "<install path>\USB\Device - HID - Custom Demos\Simple Demo - Windows Software\Microsoft Visual C++ 2005 Express\Form1.h" file.
NOTE: that for the PIC24F Starter Kit 1 the pushbutton functionality is not implemented.
Demos > Device - Composite - HID + MSD Demo > Running the Demo


Device - Composite - MSD + CDC Demo

Contents | Index | Home
Previous | Up | Next
Device - Composite - MSD + CDC Demo

This demo shows how to create a mass storage device (MSD) and communication device class (CDC) composite device.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to... more
Running the Demo
This demo creates a mass storage (MSD) and communication device class (CDC) composite device.
The MSD portion of the demo runs like the Device - Mass Storage - Internal Flash Demo. When the device is plugged in, a drive will appear on the computer. The internal flash of the device is used as the storage for this small drive.
The CDC portion of this demo runs like the Device - CDC - Basic Demo. When the device is plugged in a COM port will appear on the computer. Any key presses sent to the terminal will be responded... more
Demos > Device - Composite - MSD + CDC Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - Composite - MSD + CDC Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

PICDEM FS USB:

  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - Composite - MSD + CDC Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo creates a mass storage (MSD) and communication device class (CDC) composite device.

The MSD portion of the demo runs like the Device - Mass Storage - Internal Flash Demo. When the device is plugged in, a drive will appear on the computer. The internal flash of the device is used as the storage for this small drive.

The CDC portion of this demo runs like the Device - CDC - Basic Demo. When the device is plugged in a COM port will appear on the computer. Any key presses sent to the terminal will be responded to by its ASCII value + 1 (for example if 'B' is pressed, 'C' is returned since 'B'=0x42 and 'C'=0x43). Pressing a button on the demo board will cause "Button Pressed" to be transmitted to the terminal as well.

Demos > Device - Composite - MSD + CDC Demo > Running the Demo


Device - Composite - WinUSB + MSD Demo

Contents | Index | Home
Previous | Up | Next
Device - Composite - WinUSB + MSD Demo

This document describes how to run the Composite WinUSB + MSD demo. Composite devices allow a single USB peripheral to appear like two different devices/function on the computer.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to... more
Running the Demo
This demo uses the selected hardware platform as both a flash drive using the internal flash as storage and WinUSB class USB device. It will appear to the computer as if two USB devices were attached.
For details how to run the demo for each of the functions please see the respective getting started documents: “USB Device – Mass Storage – Internal Flash” and “USB Device – WinUSB – Generic Driver Demo”.
Demos > Device - Composite - WinUSB + MSD Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - Composite - WinUSB + MSD Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

PICDEM FS USB:

  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - Composite - WinUSB + MSD Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo uses the selected hardware platform as both a flash drive using the internal flash as storage and WinUSB class USB device. It will appear to the computer as if two USB devices were attached.

For details how to run the demo for each of the functions please see the respective getting started documents: “USB Device – Mass Storage – Internal Flash” and “USB Device – WinUSB – Generic Driver Demo”.

For PIC24F Starter Kit 1, “Get pushbutton State” functionality is not implemented.
For PIC18F Starter Kit 1, “Toggle LED” functionality is not implemented.
Demos > Device - Composite - WinUSB + MSD Demo > Running the Demo


Device - HID - Custom Demo

Contents | Index | Home
Previous | Up | Next
Device - HID - Custom Demo
Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered... more
Running the Demo
This demo uses the selected hardware platform as a HID class USB device, but uses the HID class for general purpose I/O operations. Typically, the HID class is used to implement human interface products, such as mice and keyboards. The HID protocol is however quite flexible, and can be adapted and used to send/receive general purpose data to/from a USB device. Using the HID class for general purpose I/O operations is quite advantageous, in that it does not require any kind of custom driver installation process. HID class drivers are already provided by and are distributed with common operating systems.... more
Demos > Device - HID - Custom Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - HID - Custom Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - HID - Custom Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo uses the selected hardware platform as a HID class USB device, but uses the HID class for general purpose I/O operations. Typically, the HID class is used to implement human interface products, such as mice and keyboards. The HID protocol is however quite flexible, and can be adapted and used to send/receive general purpose data to/from a USB device. Using the HID class for general purpose I/O operations is quite advantageous, in that it does not require any kind of custom driver installation process. HID class drivers are already provided by and are distributed with common operating systems. Therefore, upon plugging in a HID class device into a typical computer system, no user installation of drivers is required, the installation is fully automatic.

HID devices primarily communicate through one interrupt IN endpoint and one interrupt OUT endpoint. In most applications, this effectively limits the maximum achievable bandwidth for full speed HID devices to 64kBytes/s of IN traffic, and 64kBytes/s of OUT traffic (64kB/s, but effectively “full duplex”).

The GenericHIDSimpleDemo.exe program, and the associated firmware demonstrate how to use the HID protocol for basic general purpose USB data transfer. To make the PC source code as easy to understand as possible, the demo has deliberately been made simple, and only sends/receives small amounts of data.

Before you can run the GenericHIDSimpleDemo.exe executable, you will need to have the Microsoft® .NET Framework Version 2.0 Redistributable Package (later versions probably okay, but not tested) installed on your computer. Programs which were built in the Visual Studio® .NET languages require the .NET redistributable package in order to run. The redistributable package can be freely downloaded from Microsoft’s website. Users of Windows Vista® operating systems will not need to install the .NET framework, as it comes pre-installed as part of the operating system.

The source code for GenericHIDSimpleDemo.exe file was created in Microsoft Visual C++® 2005 Express Edition. The source code can be found in the “<Install Directory>\ USB Device - HID - Custom Demos\Generic HID - Simple Demo - PC Software” directory. Microsoft currently distributes Visual C++ 2005 Express Edition for free, and can be downloaded from Microsoft’s website. When downloading Microsoft Visual C++ 2005 Express Edition, also make sure to download and install the Platform SDK, and follow Microsoft’s instructions for integrating it with the development environment.

It is not necessary to install either Microsoft Visual C++ 2005, or the Platform SDK in order to begin using the GenericHIDSimpleDemo.exe program. These are only required if the source code will be modified or compiled.

To launch the application, simply double click on the executable “GenericHIDSimpleDemo.exe” in the “<Install Directory>\USB Device - HID - Custom Demos” directory. A window like that shown below should appear:

If instead of this window, an error message pops up while trying to launch the application, it is likely the Microsoft .NET Framework Version 2.0 Redistributable Package has not yet been installed. Please install it and try again.

In order to begin sending/receiving packets to the device, you must first find and “connect” to the device. As configured by default, the application is looking for HID class USB devices with VID = 0x04D8 and PID = 0x003F. The device descriptor in the firmware project meant to be used with this demo uses the same VID/PID. If you plug in a USB device programmed with the correct precompiled .hex file, and hit the “Connect” button, the other pushbuttons should become enabled. If hitting the connect button has no effect, it is likely the USB device is either not connected, or has not been programmed with the correct firmware.

Hitting the Toggle LED(s) should send a single packet of general purpose generic data to the HID class USB peripheral device. The data will arrive on the interrupt OUT endpoint. The firmware has been configured to receive this generic data packet, parse the packet looking for the “Toggle LED(s)” command, and should respond appropriately by controlling the LED(s) on the demo board.

The “Get Pushbutton State” button will send one packet of data over the USB to the peripheral device (to the interrupt OUT endpoint) requesting the current pushbutton state. The firmware will process the received Get Pushbutton State command, and will prepare an appropriate response packet depending upon the pushbutton state.

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick | S1
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

The PC then requests a packet of data from the device (which will be taken from the interrupt IN endpoint). Once the PC application receives the response packet, it will update the pushbutton state label.

Try experimenting with the application by holding down the appropriate pushbutton on the demo board, and then simultaneously clicking on the “Get Pushbutton State” button. Then try to repeat the process, but this time without holding down the pushbutton on the demo board.

To make for a more fluid and gratifying end user experience, a real USB application would probably want to launch a separate thread to periodically poll the pushbutton state, so as to get updates regularly. This is not done in this simple demo, so as to avoid cluttering the PC application project with source code that is not related to USB communication.

Running the demo on an Android v3.1+ device

There are two main ways to get the example application on to the target Android device: the Android Market and by compiling the source code.

  1. The demo application can be downloaded from Microchip’s Android Marketplace page: https://market.android.com/developer?pub=Microchip+Technology+Inc
  2. The source code for this demo is also provided in the demo project folder. For more information about how to build and load Android applications, please refer to the following pages:
    • http://developer.android.com/index.html
    • http://developer.android.com/sdk/index.html
    • http://developer.android.com/sdk/installing.html
While there are no devices attached, the Android application will indicate that no devices are attached.

When the device is attached, the an alternative screen will allow various control/status features with the hardware on the board.

Demos > Device - HID - Custom Demo > Running the Demo


Device - HID - Digitizer Demos

Contents | Index | Home
Previous | Up | Next
Device - HID - Digitizer Demos

These are examples of HID digitizers. There are single, and various multi-point touch examples.

Topics
Name
Description
Supported Demo Boards
Configuring the Hardware
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered... more
Running the Demo
These demos use the selected hardware platform as a USB HID class digitizer device. The Single-Touch demo is a HID class pen digitizer demo, which emulates a pen digitizer touch screen capable of sensing a single contact point. The Multi-Touch demo emulates a touch sensitive touch screen, capable of sensing two simultaneous contact points. The multi-touch demo can potentially be expanded to support additional simultaneous contacts (by modifying the HID report descriptor), however, the standard built in gestures that are recognized by the Microsoft Windows 7 platform only use one or two contacts.
To use the Single-Touch pen digitizer demo,... more
Demos > Device - HID - Digitizer Demos


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - HID - Digitizer Demos > Supported Demo Boards


Configuring the Hardware

Contents | Index | Home
Previous | Up | Next
Configuring the Hardware

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - HID - Digitizer Demos > Configuring the Hardware


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

These demos use the selected hardware platform as a USB HID class digitizer device. The Single-Touch demo is a HID class pen digitizer demo, which emulates a pen digitizer touch screen capable of sensing a single contact point. The Multi-Touch demo emulates a touch sensitive touch screen, capable of sensing two simultaneous contact points. The multi-touch demo can potentially be expanded to support additional simultaneous contacts (by modifying the HID report descriptor), however, the standard built in gestures that are recognized by the Microsoft Windows 7 platform only use one or two contacts.

To use the Single-Touch pen digitizer demo, plug the demo board into a free USB port on a Windows Vista or Windows 7 machine. The device should automatically enumerate as a HID class pen digitizer device, and certain additional functions and capabilities built into the operating system will become activated. No manual USB driver installation is necessary, as the built in HID class drivers are used for this device.

To use the Multi-Touch digitizer demo, plug the demo board into a free USB port on a Windows 7 machine. Windows 7 has significantly more “Windows Touch” capabilities than Vista. Although the device will enumerate and provide limited functionality on Windows Vista, multi-touch gestures will not be recognized unless run on Windows 7.

Since the standard demo boards that these demos are meant to be run on do not have an actual touch sensitive contact area, the firmware demos emulate the data that would be generated by a real touch screen. Both demo projects use a single user pushbutton. By pressing the button, the firmware will send a flurry of USB packets to the host, which contain contact position data that is meant to mimic an actual “gesture” of various types. Each subsequent press of the pushbutton will advance the internal state machine, and cause the firmware to send a gesture to the PC.

To use the demos, it is best to have Microsoft Internet Explorer installed on the machine (although some demo functions can be observed using the pen flick practice area available from the control panel). The latest versions of Internet Explorer (when run on the proper OS: preferably Windows 7, but some function on Windows Vista) supports recognition and use of certain basic gestures, such as “back”, “forward”, as well as certain scroll and zoom operations. To see a full detailed description of how best to use Internet Explorer or the pen flick practice area, see the detailed comments at the top of SingleTouch.c file (for the Single Touch pen digitizer demo: “<Install Directory>\USB Device - HID - Digitizers\Single Touch – Firmware”). For details on how best to use and what to expect with the multi-touch demo, see the detailed comments at the top of the MultiTouch.c file (<Install Directory>\ “USB Device - HID - Digitizers\Multi Touch – Firmware”).

Other Info: Windows 7 adds support for Windows messages such as “WM_GESTURE” and “WM_TOUCH”. These messages can be used to help build customized “touch enabled” PC applications. Documentation for these messages can be found in MSDN.

The following Microsoft developer blog contains useful additional information relating to Windows Touch:

http://blogs.msdn.com/e7/archive/2009/03/25/touching-windows-7.aspx

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick | S1
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Demos > Device - HID - Digitizer Demos > Running the Demo


Device - HID - Joystick Demo

Contents | Index | Home
Previous | Up | Next
Device - HID - Joystick Demo

This demo shows how to create a USB joystick

Topics
Name
Description
Supported Demo Boards
Configuring the Hardware
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered... more
Running the Demo
This demo uses the selected hardware platform as a USB Joystick. To test the joystick feature, go to the “<Install Directory\USB Device – HID - Joystick” directory and open the JoystickTester.exe:

Pressing the button will cause the device to:
  • Indicate that the “x” button is pressed, but none others;
  • Move the hat switch to the "east" position;
  • Move the X and Y coordinates to the their extreme values;
Demos > Device - HID - Joystick Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - HID - Joystick Demo > Supported Demo Boards


Configuring the Hardware

Contents | Index | Home
Previous | Up | Next
Configuring the Hardware

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - HID - Joystick Demo > Configuring the Hardware


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo uses the selected hardware platform as a USB Joystick. To test the joystick feature, go to the “<Install Directory\USB Device – HID - Joystick” directory and open the JoystickTester.exe:

Pressing the button will cause the device to:

  • Indicate that the “x” button is pressed, but none others;
  • Move the hat switch to the "east" position;
  • Move the X and Y coordinates to the their extreme values;

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick | S1
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Demos > Device - HID - Joystick Demo > Running the Demo


Device - HID - Keyboard Demo

Contents | Index | Home
Previous | Up | Next
Device - HID - Keyboard Demo

This example shows how to create a USB keyboard and how to send data to the host.

Topics
Name
Description
Supported Demo Boards
Configuring the Hardware
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered... more
Running the Demo
This demo uses the selected hardware platform as a USB keyboard. Before pressing the button, select a window in which it is safe to type text freely. Pressing the button will cause the device to print a character on the screen.
Demos > Device - HID - Keyboard Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - HID - Keyboard Demo > Supported Demo Boards


Configuring the Hardware

Contents | Index | Home
Previous | Up | Next
Configuring the Hardware

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - HID - Keyboard Demo > Configuring the Hardware


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo uses the selected hardware platform as a USB keyboard. Before pressing the button, select a window in which it is safe to type text freely. Pressing the button will cause the device to print a character on the screen.

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick | S1
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Demos > Device - HID - Keyboard Demo > Running the Demo


Device - HID - Mouse Demo

Contents | Index | Home
Previous | Up | Next
Device - HID - Mouse Demo

This demo is a simple mouse demo that causes the mouse to move in a circle on the screen.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered... more
Running the Demo
This demo uses the selected hardware platform as a USB mouse. Before connecting the board to the computer through the USB cable please be aware that the device will start moving the mouse cursor around on the computer. There are two ways to stop the device from making the cursor to continue to move. The first way is to disconnect the device from the computer. The second is to press the correct button on the hardware platform. Pressing the button again will cause the mouse cursor to start moving in a circle again.
Demos > Device - HID - Mouse Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - HID - Mouse Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - HID - Mouse Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo uses the selected hardware platform as a USB mouse. Before connecting the board to the computer through the USB cable please be aware that the device will start moving the mouse cursor around on the computer. There are two ways to stop the device from making the cursor to continue to move. The first way is to disconnect the device from the computer. The second is to press the correct button on the hardware platform. Pressing the button again will cause the mouse cursor to start moving in a circle again.

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick | S1
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Demos > Device - HID - Mouse Demo > Running the Demo


Device - HID - Uninterruptible Power Supply

Contents | Index | Home
Previous | Up | Next
Device - HID - Uninterruptible Power Supply
Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered... more
Running the Demo
This demo uses the selected hardware platform as a HID class USB Uninterruptible power supply (UPS). When the device is plugged into a computer, the computer should have an indicator showing that it is connected to a UPS and it should show a charge percentage of the battery of the UPS. This demo uses a fixed time derived from the USB start of frame (SOF) packets to emulate the battery charging by sending updates about the battery status to the computer.
Holding the specified button on the demo board puts the UPS in a emulated discharge state, as if the... more
Demos > Device - HID - Uninterruptible Power Supply


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - HID - Uninterruptible Power Supply > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - HID - Uninterruptible Power Supply > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo uses the selected hardware platform as a HID class USB Uninterruptible power supply (UPS). When the device is plugged into a computer, the computer should have an indicator showing that it is connected to a UPS and it should show a charge percentage of the battery of the UPS. This demo uses a fixed time derived from the USB start of frame (SOF) packets to emulate the battery charging by sending updates about the battery status to the computer.

Holding the specified button on the demo board puts the UPS in a emulated discharge state, as if the main power has been removed/failed. As time progresses the board sends updated information about the charge left on the battery. As the battery approaches the minimum threshold, the UPS will send a command to shut down the computer. Release the button at any point of time to simulate a reconnection of the main power supply and to emulate the UPS returning to a charging state.

Below is a table that specifies the button used for each of the demo boards.

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Demos > Device - HID - Uninterruptible Power Supply > Running the Demo


Device - LibUSB Generic Driver Demo

Contents | Index | Home
Previous | Up | Next
Device - LibUSB Generic Driver Demo
Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered... more
Running the Demo
When running this demo, the following push buttons are used. Please refer to each of the following sections for a description of how to run the demo on various operating systems:
Demos > Device - LibUSB Generic Driver Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - LibUSB Generic Driver Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - LibUSB Generic Driver Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

When running this demo, the following push buttons are used. Please refer to each of the following sections for a description of how to run the demo on various operating systems:

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick | S1
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Topics
Name
Description
Windows
This demo uses the selected hardware platform as a Libusb class USB device. Libusb-Win32 is a USB Library for the Windows operating systems. The library allows user space applications to access any USB device on Windows in a generic way without writing any line of kernel driver code. This driver allows users to have access to interrupt, bulk, and control transfers directly.
The SimpleLibUSBDemo.exe program and the associated firmware demonstrate how to use the Libusb device drivers for basic general purpose USB data transfer. To make the PC source code as easy to understand as possible, the demo has deliberately... more
Linux
The SimpleLibUSBDemo program and the associated firmware demonstrate how to use the Libusb device drivers for basic general purpose USB data transfer. To make the PC source code as easy to understand as possible, the demo has deliberately been made simple, and only sends/receives small amounts of data.
Before you can run the SimpleLibUSBDemo executable, you will need to have the libusb 0.1 driver installed on your computer. The libusb can be downloaded from sourceforge.net.
The source code for SimpleLibUSBDemo.exe file was created using QT3 Designer. The source code can be found in the “<Install Directory>\ USB Device - Libusb... more
Android 3.1+
There are two main ways to get the example application on to the target Android device: the Android Market and by compiling the source code.
  1. The demo application can be downloaded from Microchip’s Android Marketplace page: https://market.android.com/developer?pub=Microchip+Technology+Inc
  2. The source code for this demo is also provided in the demo project folder. For more information about how to build and load Android applications, please refer to the following pages:
    • http://developer.android.com/index.html
    • http://developer.android.com/sdk/index.html
    • http://developer.android.com/sdk/installing.html
While there are no devices attached, the Android application will indicate that no devices are attached.

When the device is attached, the an alternative screen will allow various control/status... more
Demos > Device - LibUSB Generic Driver Demo > Running the Demo


Windows

Contents | Index | Home
Previous | Up | Next
Windows

This demo uses the selected hardware platform as a Libusb class USB device. Libusb-Win32 is a USB Library for the Windows operating systems. The library allows user space applications to access any USB device on Windows in a generic way without writing any line of kernel driver code. This driver allows users to have access to interrupt, bulk, and control transfers directly.

The SimpleLibUSBDemo.exe program and the associated firmware demonstrate how to use the Libusb device drivers for basic general purpose USB data transfer. To make the PC source code as easy to understand as possible, the demo has deliberately been made simple, and only sends/receives small amounts of data.

Before you can run the SimpleLibUSBDemo.exe executable, you will need to have the Microsoft® .NET Framework Version 3.5 Redistributable Package (later versions probably okay, but not tested) installed on your computer. Programs which were built in the Visual Studio® .NET languages require the .NET redistributable package in order to run. The redistributable package can be freely downloaded from Microsoft’s website. Users of Windows Vista® operating systems will not need to install the .NET framework, as it comes pre-installed as part of the operating system.

The source code for SimpleLibUSBDemo.exe file was created in Microsoft Visual C++® 2008 Express Edition. The source code can be found in the “<Install Directory>\ USB Device - Libusb - Generic Driver Demo\ Libusb Simple Demo - Windows Application\Libusb Simple Demo - PC Application - MS VC++ 2008 Express” directory. Microsoft currently distributes Visual C++ 2008 Express Edition for free, and can be downloaded from Microsoft’s website.

To launch the application, simply double click on the executable “SimpleLIbusbDemo.exe” in the “<Install Directory>\USB Device - Libusb - Generic Driver Demo\Windows Application” directory. A window like that shown below should appear:

If instead of this window, an error message pops up while trying to launch the application, it is likely the Microsoft .NET Framework Version 3.5 Redistributable Package has not yet been installed. Please install it and try again.

In order to begin sending/receiving packets to the device, you must first find and “connect” to the device. As configured by default, the application is looking for USB devices with VID = 0x04D8 and PID = 0x0204. The device descriptor in the firmware project meant to be used with this demo uses the same VID/PID. To run the demo program the USB device with the correct precompiled .hex file. If you are connecting the device for the first time, Windows pops up a window asking you to install the driver for the device. When asked for the driver point it to the inf file provided along with the demo. Windows takes while to install the driver for the USB device that is just plugged in. Open the Device manager and ensure that the USB device is listed under the ‘Libusb Demo Devices’. Once the driver is installed hit the “Connect” button, the other pushbuttons should become enabled. If hitting the connect button has no effect, it is likely the USB device is either not connected, or has not been programmed with the correct firmware.

If a different VID/PID combination from the default is desired, then the descriptors in the firmware must be changed as well as the inf file. The easiest way to change the inf file is to use the utility provided with the LibUSB download for windows on the LibUSB [image] website. This utility can create a new inf file based on a connected device. So make sure to change the VID/PID combination first in the firmware, connect the device, and then run the inf file creator utility. After completing the utility, a new signed driver with inf file is created.

Once the driver is installed hit the “Connect” button, the other pushbuttons should become enabled. If hitting the connect button has no effect, it is likely the USB device is either not connected, or has not been programmed with the correct firmware.

Hitting the Toggle LED(s) should send a single packet of general purpose generic data to the Custom class USB peripheral device. The data will arrive on the Bulk OUT endpoint. The firmware has been configured to receive this generic data packet, parse the packet looking for the “Toggle LED(s)” command, and should respond appropriately by controlling the LED(s) on the demo board.

The “Get Pushbutton State” button will send one packet of data over the USB to the peripheral device (to the Bulk OUT endpoint) requesting the current pushbutton state. The firmware will process the received Get Pushbutton State command, and will prepare an appropriate response packet depending upon the pushbutton state.

The PC then requests a packet of data from the device (which will be taken from the Bulk IN endpoint). Once the PC application receives the response packet, it will update the pushbutton state label.

Try experimenting with the application by holding down the appropriate pushbutton on the demo board, and then simultaneously clicking on the “Get Pushbutton State” button. Then try to repeat the process, but this time without holding down the pushbutton on the demo board.

To make for a more fluid and gratifying end user experience, a real USB application would probably want to launch a separate thread to periodically poll the pushbutton state, so as to get updates regularly. This is not done in this simple demo, so as to avoid cluttering the PC application project with source code that is not related to USB communication.

In order to build the application, copy the file <libusb-win32 unzipped folder>\ libusb-win32-device-bin-0.1.12.1\lib\msvc\libusb.lib and paste to ‘lib’ folder of the VC++. Also copy the file

<libusb-win32 unzipped folder>\ libusb-win32-device-bin-0.1.12.1\ include\usb.h and paste to the “<Install Directory>\USB Device - Libusb - Generic Driver Demo\Windows Application\Microsoft VC++ 2008 Express\SimpleLibusbDemo’ folder.

Demos > Device - LibUSB Generic Driver Demo > Running the Demo > Windows


Linux

Contents | Index | Home
Previous | Up | Next
Linux

The SimpleLibUSBDemo program and the associated firmware demonstrate how to use the Libusb device drivers for basic general purpose USB data transfer. To make the PC source code as easy to understand as possible, the demo has deliberately been made simple, and only sends/receives small amounts of data.

Before you can run the SimpleLibUSBDemo executable, you will need to have the libusb 0.1 driver installed on your computer. The libusb can be downloaded from sourceforge.net.

The source code for SimpleLibUSBDemo.exe file was created using QT3 Designer. The source code can be found in the “<Install Directory>\ USB Device - Libusb - Generic Driver Demo\Libusb Simple Demo - Linux Application\ Libusb Simple Demo - Linux Application -QT3” directory.

To launch the application, open the Terminal and navigate to the “<Install Directory>\USB Device - LibUSB - Generic Driver Demo\Linux Application” directory and execute the following commands

  1. chmod a+x SimpleLibusbDemo_Linux (This command gives executable right to the file on this Linux computer
  2. sudo ./SimpleLibusbDemo_Linux.
Enter the Super user password when requested. A window like that shown below should appear:

In order to begin sending/receiving packets to the device, you must first find and “connect” to the device. As configured by default, the application is looking for USB devices with VID = 0x04D8 and PID = 0x0204. The device descriptor in the firmware project meant to be used with this demo uses the same VID/PID. To run the demo program the USB device with the correct precompiled .hex file. If you are connecting the device for the first time, Windows pops up a window asking you to install the driver for the device. When asked for the driver point it to the inf file provided along with the demo. Windows takes while to install the driver for the USB device that is just plugged in. Open the Device manager and ensure that the USB device is listed under the ‘Libusb Demo Devices’. Once the driver is installed hit the “Connect” button, the other pushbuttons should become enabled. If hitting the connect button has no effect, it is likely the USB device is either not connected, or has not been programmed with the correct firmware.

Hitting the Toggle LED(s) should send a single packet of general purpose generic data to the Custom class USB peripheral device. The data will arrive on the Bulk OUT endpoint. The firmware has been configured to receive this generic data packet, parse the packet looking for the “Toggle LED(s)” command, and should respond appropriately by controlling the LED(s) on the demo board.

The “Get Pushbutton State” button will send one packet of data over the USB to the peripheral device (to the Bulk OUT endpoint) requesting the current pushbutton state. The firmware will process the received Get Pushbutton State command, and will prepare an appropriate response packet depending upon the pushbutton state.

The PC then requests a packet of data from the device (which will be taken from the Bulk IN endpoint). Once the PC application receives the response packet, it will update the pushbutton state label.

Try experimenting with the application by holding down the appropriate pushbutton on the demo board, and then simultaneously clicking on the “Get Pushbutton State” button. Then try to repeat the process, but this time without holding down the pushbutton on the demo board.

To make for a more fluid and gratifying end user experience, a real USB application would probably want to launch a separate thread to periodically poll the pushbutton state, so as to get updates regularly. This is not done in this simple demo, so as to avoid cluttering the PC application project with source code that is not related to USB communication.

In order to build the application navigate to the “<Install Directory>\USB Device - LibUSB - Generic Driver Demo\Linux Application\Qt3” directory and execute the command “make”.

Demos > Device - LibUSB Generic Driver Demo > Running the Demo > Linux


Android 3.1+

Contents | Index | Home
Previous | Up | Next
Android 3.1+

There are two main ways to get the example application on to the target Android device: the Android Market and by compiling the source code.

  1. The demo application can be downloaded from Microchip’s Android Marketplace page: https://market.android.com/developer?pub=Microchip+Technology+Inc
  2. The source code for this demo is also provided in the demo project folder. For more information about how to build and load Android applications, please refer to the following pages:
    • http://developer.android.com/index.html
    • http://developer.android.com/sdk/index.html
    • http://developer.android.com/sdk/installing.html
While there are no devices attached, the Android application will indicate that no devices are attached.

When the device is attached, the an alternative screen will allow various control/status features with the hardware on the board.

Demos > Device - LibUSB Generic Driver Demo > Running the Demo > Android 3.1+


Device - Mass Storage - Internal Flash Demo

Contents | Index | Home
Previous | Up | Next
Device - Mass Storage - Internal Flash Demo

This demo uses the selected hardware platform as an drive on the computer using the internal flash of the device as the drive storage media. Connect the hardware platform to a computer through a USB cable.

The device should appear as a new drive on the computer named “Drive Name”. The volume label or file information can be changed in the Files.c file located in the project directory.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to... more
Running the Demo
This demo uses the selected hardware platform as an drive on the computer using the internal flash of the device as the drive storage media. Connect the hardware platform to a computer through a USB cable.
The device should appear as a new drive on the computer named “Drive Name”. The volume label or file information can be changed in the Files.c file located in the project directory.
Demos > Device - Mass Storage - Internal Flash Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ256DA210 Development Board |
PIC24FJ64GB502 Microstick |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - Mass Storage - Internal Flash Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

PICDEM FS USB:

  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - Mass Storage - Internal Flash Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo uses the selected hardware platform as an drive on the computer using the internal flash of the device as the drive storage media. Connect the hardware platform to a computer through a USB cable.

The device should appear as a new drive on the computer named “Drive Name”. The volume label or file information can be changed in the Files.c file located in the project directory.

Topics
Name | Description
Troubleshooting | Issue 1: The device appears correctly in the device manager, but no new drive letters appear on a Windows® operating system based machine. Solution: See Microsoft knowledge base article 297694: http://support.microsoft.com/kb/297694 If there is a drive letter conflict (ex: because a network drive has been mapped to a letter low in the alphabet), on some operating systems the newly attached USB drive may not appear. If this occurs, either obtain the hotfix from Microsoft, or remap the conflicting mapped network drive to a letter at the end of the alphabet (ex: Z:). Issue 2: The device enumerates... more
Demos > Device - Mass Storage - Internal Flash Demo > Running the Demo


Troubleshooting

Contents | Index | Home
Previous | Up | Next
Troubleshooting

Issue 1: The device appears correctly in the device manager, but no new drive letters appear on a Windows® operating system based machine.

Solution: See Microsoft knowledge base article 297694: http://support.microsoft.com/kb/297694

If there is a drive letter conflict (ex: because a network drive has been mapped to a letter low in the alphabet), on some operating systems the newly attached USB drive may not appear. If this occurs, either obtain the hotfix from Microsoft, or remap the conflicting mapped network drive to a letter at the end of the alphabet (ex: Z:).

Issue 2: The device enumerates correctly and I can access the new drive. Even though the drive is not full yet, when I try to write to the drive, I get an error message something like, “Cannot copy (some name): The directory or file cannot be created.”

Solution: In order to copy new files onto the drive volume, both the file contents themselves must be copied to the drive, and the FAT table must also be updated in order to accommodate the new file name and path. Even if the drive has plenty of free space available, the FAT table may have reached its limit. In order to keep the default demos small, the FAT table is configured to be only 512 bytes long. This is not very large, and can easily be exceeded, especially if the files on the drive have long file names. In order to use the remaining space available on the drive, it is recommended to keep the individual file names as short as possible to minimize their size in the FAT table. Alternatively, the firmware can be modified so that the FAT table is larger, and therefore able to accommodate more file name and path characters.

Issue 3: When I try to format the drive, I get an error message and the drive does not get formatted properly.

Solution: By default, common Windows based operating systems will try to place a large FAT table on the newly formatted disk (larger than the default 512 bytes of the demo firmware). If the FAT table is larger than the total drive space, the drive cannot be formatted. In order to successfully format the drive, an alternative method of formatting will be needed that places a smaller FAT table on the drive. For example, the drive can be effectively reformatted by reprogramming the microcontroller with the original HEX file. Alternatively, if the firmware is modified to increase the total drive space, the Windows operating system managed FAT table may be able to fit. Unfortunately, this will shrink the effective drive size, making less of it available for actual file data.

Issue 4: When I format the drive, the drive size shrinks.

Solution: See the solution to issue #3 above.

Demos > Device - Mass Storage - Internal Flash Demo > Running the Demo > Troubleshooting


Device - Mass Storage - SD Card Data Logger

Contents | Index | Home
Previous | Up | Next
Device - Mass Storage - SD Card Data Logger

This demo shows how to data log to an SD card using the Microchip MDD file system and present the data to the PC using the Mass Storage data class to appear like an SD card reader.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
PIC18 Explorer Based Demos
For all of the PIC18 Explorer based demo boards, please follow the following instructions:
  1. Set switch S4 to the "ICE" position
  2. On the SD Card PICTail™ Plus board, short JP1, JP2, and JP3 on the side farthest from the SD Card holder. Depending on the revision of the board you have the silk-screen on the board may incorrectly label the top as the “HPC-EXP” setting. Please ignore this silk screen and place the jumpers as described above and seen below.
  3. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC18F46J50... more
Running the Demo
Logging Data:
Make sure that there is a FAT or FAT32 formatted SD card in the card reader. This can be done by either connecting the device to a regulator SD card reader or connecting the hardware platform to the computer through the USB cable. The device should appear as a new drive on the computer named “Removable Drive”.

Power the demo board if it is not powered already.
Press and hold down the specified button below. This will cause the unit to soft detach from the computer (if it is attached) and start to log data to the... more
Demos > Device - Mass Storage - SD Card Data Logger


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC18F46J50 Plug-In-Module (PIM) | 1, 2
PIC18F47J53 Plug-In-Module (PIM) | 1, 2
PIC18F87J50 Plug-In-Module (PIM) | 1, 2
PIC24FJ64GB004 Plug-In-Module (PIM) | 1, 3
PIC24FJ256GB110 Plug-In-Module (PIM) | 1, 3
PIC24FJ256GB210 Plug-In-Module (PIM) | 1, 3
PIC24EP512GU810 Plug-In-Module (PIM) | 1, 3
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1, 3
PIC32 USB Plug-In-Module (PIM) | 1, 3
PIC32 CAN-USB Plug-In-Module (PIM) | 1, 3

Notes:

  1. These boards require the SD Card PICTail/PICTail+ daughter board in order to run this demo.
  2. This board can not be used by itself. It requires a PIC18 Explorer board in order to operate with this demo.
  3. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Device - Mass Storage - SD Card Data Logger > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

PIC18 Explorer Based Demos

For all of the PIC18 Explorer based demo boards, please follow the following instructions:

  1. Set switch S4 to the "ICE" position
  2. On the SD Card PICTail™ Plus board, short JP1, JP2, and JP3 on the side farthest from the SD Card holder. Depending on the revision of the board you have the silk-screen on the board may incorrectly label the top as the “HPC-EXP” setting. Please ignore this silk screen and place the jumpers as described above and seen below.
  3. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC18F46J50 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options are shorted together.
    2. Short JP3. This allows the demo board to be powered through the USB bus power.
  • PIC18F47J53 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options are shorted together.
    2. Short JP3. This allows the demo board to be powered through the USB bus power.
  • PIC18F87J50 Plug-In-Module:
    1. Short JP1 such that the "R" and the "U" options are shorted together.
    2. Short JP4. This allows the demo board to be powered through the USB bus power.
    3. Short JP5. This enabled the LED operation on the board.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. On the SD Card PICTail™ Plus board, short JP1, JP2, and JP3 on the side farthest from the SD Card holder. Depending on the revision of the board you have the silk-screen on the board may incorrectly label the top as the “HPC-EXP” setting. Please ignore this silk screen and place the jumpers as described above and seen below.
  7. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to the center pin
    3. Short J2 pin 1 (marked "Temp") to the center pin
    4. Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    1. Short JP1 "U" option to the center pin
    2. Short JP2 "U" option to the center pin
    3. Short JP3 "U" option to the center pin
    4. Short JP4
  • PIC24EP512GU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    1. Open J10
    2. Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

Demos > Device - Mass Storage - SD Card Data Logger > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

Logging Data:

Make sure that there is a FAT or FAT32 formatted SD card in the card reader. This can be done by either connecting the device to a regulator SD card reader or connecting the hardware platform to the computer through the USB cable. The device should appear as a new drive on the computer named “Removable Drive”.

Power the demo board if it is not powered already.

Press and hold down the specified button below. This will cause the unit to soft detach from the computer (if it is attached) and start to log data to the card.

Demo Board (click link for board information) | Button
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ256DA210 Development Board | S1
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)

Notes:

1) This is the button number on the Explorer 16.

Reading the Data:

Connect the hardware platform to a computer through a USB cable. If the device was attached to the computer while the data logging occurred, you may need to remove the SD card from the card slot or disconnect and reconnect the device from the computer for the files to appear. Most computers are not expecting the files on an attached drive to change if they are not making the change so some operating systems will not look for additional drive changes.

The device should appear as a new drive on the computer named “Removable Drive”.

If no SD Card is inserted in the SD Card PICTail Plus, the following dialog will pop-up.

Once a compatible card is inserted in the card reader, files can be read, deleted, and manipulated like any other drive on the computer. If the instructions in the “Logging Data” are performed, there should be a “LOG.CSV” file on the card.

This file can be read by a simple text editor program or graphical/statistical programs, like Microsoft® Excel®.

To plot the data in Excel, select the entire column that contains the data.

Click on the chart wizard button.

Select the “Line” option chart.

Click “Next” and “Finish” until the chart is generated.

Toubleshooting Tips:

Issue 1: The device appears correctly in the device manager, but no new drive letters appear on a Windows® operating system based machine.

Solution: See Microsoft knowledge base article 297694: http://support.microsoft.com/kb/297694

If there is a drive letter conflict (ex: because a network drive has been mapped to a letter low in the alphabet), on some operating systems, the newly attached USB drive may not appear. If this occurs, either obtain the hotfix from Microsoft, or remap the conflicting mapped network drive to a letter at the end of the alphabet (ex: Z:).

NOTE WHEN USING THE HID BOOTLOADER (for PIC18F87J50 PIM): The “USB Device - Mass Storage - SD Card reader” and “USB Device - Mass Storage - SD Card data logger” demos make use of the SD Card PICtail Daughter Board (Microchip® Direct: AC164122). This PICtail uses the RB4 I/O pin for the card detect (CD) signal, and is actively driven by the PICtail. The active drive overpowers the pull up resistor on the RB4 pushbutton (on the PIC18F87J50 FS USB Plug-In Module board). As a result, if the PIC18F87J50 is programmed with the HID bootloader, and an SD Card is installed in the socket when the microcontroller comes out of reset, the firmware will immediately enter the bootloader (irrespective of the RB4 pushbutton state). To exit the bootloader firmware, remove the SD Card from the SD Card socket, and tap the MCLR button. When the SD Card is not plugged in, the PICtail will drive the card detect signal (which is connected to RB4) logic high, which will enable the bootloader to exit to the main application after coming out of reset. Once the main application firmware is operating, the SD Card can be plugged in. The SD Card is “hot-swappable” and should be recognized by the host upon insertion. To avoid this inconvenience when using the bootloader with the PICtail, it is suggested to modify the bootloader firmware to use some other I/O pin for bootloader entry, such as RB0 (which has a pushbutton on it on the HPC Explorer board).
Demos > Device - Mass Storage - SD Card Data Logger > Running the Demo


Device - Mass Storage - SD Card Reader

Contents | Index | Home
Previous | Up | Next
Device - Mass Storage - SD Card Reader

This demo shows how to implement a simple SD card reader

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
PIC18 Explorer Based Demos
For all of the PIC18 Explorer based demo boards, please follow the following instructions:
  1. Set switch S4 to the "ICE" position
  2. On the SD Card PICTail™ Plus board, short JP1, JP2, and JP3 on the side farthest from the SD Card holder. Depending on the revision of the board you have the silk-screen on the board may incorrectly label the top as the “HPC-EXP” setting. Please ignore this silk screen and place the jumpers as described above and seen below.
  3. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC18F46J50... more
Running the Demo
Connect the hardware platform to a computer through a USB cable. If the device was attached to the computer while the data logging occurred, you may need to remove the SD card from the card slot or disconnect and reconnect the device from the computer for the files to appear. Most computers are not expecting the files on an attached drive to change if they are not making the change so some operating systems will not look for additional drive changes.
The device should appear as a new drive on the computer named “Removable Drive”.

If no SD Card is... more
Demos > Device - Mass Storage - SD Card Reader


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC18F46J50 Plug-In-Module (PIM) | 1, 2
PIC18F47J53 Plug-In-Module (PIM) | 1, 2
PIC18F87J50 Plug-In-Module (PIM) | 1, 2
PIC24FJ64GB004 Plug-In-Module (PIM) | 1, 3
PIC24FJ256GB110 Plug-In-Module (PIM) | 1, 3
PIC24FJ256GB210 Plug-In-Module (PIM) | 1, 3
PIC24EP512GU810 Plug-In-Module (PIM) | 1, 3
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1, 3
PIC32 USB Plug-In-Module (PIM) | 1, 3
PIC32 CAN-USB Plug-In-Module (PIM) | 1, 3

Notes:

  1. These boards require the SD Card PICTail/PICTail+ daughter board in order to run this demo.
  2. This board can not be used by itself. It requires a PIC18 Explorer board in order to operate with this demo.
  3. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Device - Mass Storage - SD Card Reader > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

PIC18 Explorer Based Demos

For all of the PIC18 Explorer based demo boards, please follow the following instructions:

  1. Set switch S4 to the "ICE" position
  2. On the SD Card PICTail™ Plus board, short JP1, JP2, and JP3 on the side farthest from the SD Card holder. Depending on the revision of the board you have the silk-screen on the board may incorrectly label the top as the “HPC-EXP” setting. Please ignore this silk screen and place the jumpers as described above and seen below.
  3. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC18F46J50 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options are shorted together.
    2. Short JP3. This allows the demo board to be powered through the USB bus power.
  • PIC18F47J53 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options are shorted together.
    2. Short JP3. This allows the demo board to be powered through the USB bus power.
  • PIC18F87J50 Plug-In-Module:
    1. Short JP1 such that the "R" and the "U" options are shorted together.
    2. Short JP4. This allows the demo board to be powered through the USB bus power.
    3. Short JP5. This enabled the LED operation on the board.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. On the SD Card PICTail™ Plus board, short JP1, JP2, and JP3 on the side farthest from the SD Card holder. Depending on the revision of the board you have the silk-screen on the board may incorrectly label the top as the “HPC-EXP” setting. Please ignore this silk screen and place the jumpers as described above and seen below.
  7. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to the center pin
    3. Short J2 pin 1 (marked "Temp") to the center pin
    4. Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    1. Short JP1 "U" option to the center pin
    2. Short JP2 "U" option to the center pin
    3. Short JP3 "U" option to the center pin
    4. Short JP4
  • PIC24EP512GU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    1. Open J10
    2. Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

Demos > Device - Mass Storage - SD Card Reader > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

Connect the hardware platform to a computer through a USB cable. If the device was attached to the computer while the data logging occurred, you may need to remove the SD card from the card slot or disconnect and reconnect the device from the computer for the files to appear. Most computers are not expecting the files on an attached drive to change if they are not making the change so some operating systems will not look for additional drive changes.

The device should appear as a new drive on the computer named “Removable Drive”.

If no SD Card is inserted in the SD Card PICTail Plus, the following dialog will pop-up.

Once a compatible card is inserted in the card reader, files can be read, deleted, and manipulated like any other drive on the computer.

Demos > Device - Mass Storage - SD Card Reader > Running the Demo


Device - MCHPUSB Generic Driver Demo

Contents | Index | Home
Previous | Up | Next
Device - MCHPUSB Generic Driver Demo
Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered... more
Running the Demo
When running this demo, the following push buttons are used. Please refer to each of the following sections for a description of how to run the demo on various operating systems:
Demos > Device - MCHPUSB Generic Driver Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - MCHPUSB Generic Driver Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - MCHPUSB Generic Driver Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

When running this demo, the following push buttons are used. Please refer to each of the following sections for a description of how to run the demo on various operating systems:

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick | S1
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Topics
Name
Description
Installing Windows Drivers
The generic driver (custom class) demo uses a custom class driver. Like any custom driver when first plugged into a computer, a driver needs to be installed. When the device is plugged in to the computer the following window will pop-up:

Continue by selecting either options and clicking next.
If the driver has been installed on the computer before the installation process may complete itself without further action.

If the driver has not been installed before on the computer, then the driver will need to be installed. The Found New Hardware Wizard will be looking for a *.inf file with... more
PDFSUSB
The example application can be found in the “<Install Directory>\USB Device - MCHPUSB - Generic Driver Demo\PC Software\Pdfsusb” directory.
When the application is first launched it will look like the following.

Select the “Demo Mode” tab.

In the listbox at the top of the application, select the “PICDEM FS USB…” option. If this option is not available then the device is either not connected to the computer, the driver was not installed correctly, or the firmware programmed into the device was not the correct project needed to interface with the generic driver.

With the listbox selecting the “PICDEM FS USB…”... more
MCHPUSB PnP Demo
The example application can be found in the “<Install Directory>\USB Device - MCHPUSB - Generic Driver Demo\PC Software\Visual C++ 2005 Express” directory.
When the application is launched and the MCHPUSB custom device is not attached, it will look like the following:

Once the device is attached the application will reflect that the device is attached and look like the following. Moving the potentiometer will cause the status bar of the application to move to reflect the current value. While using Explorer 16 with dsPIC33EP512MU810 or PIC24EP512GU810 PIM, the potentiometer interface is not supported.
Running the Demo (Android v3.1+)
There are two main ways to get the example application on to the target Android device: the Android Market and by compiling the source code.
  1. The demo application can be downloaded from Microchip’s Android Marketplace page: https://market.android.com/developer?pub=Microchip+Technology+Inc
  2. The source code for this demo is also provided in the demo project folder. For more information about how to build and load Android applications, please refer to the following pages:
    • http://developer.android.com/index.html
    • http://developer.android.com/sdk/index.html
    • http://developer.android.com/sdk/installing.html
While there are no devices attached, the Android application will indicate that no devices are attached.

When the device is attached, the an alternative screen will allow various control/status... more
Demos > Device - MCHPUSB Generic Driver Demo > Running the Demo


Installing Windows Drivers

Contents | Index | Home
Previous | Up | Next
Installing Windows Drivers

The generic driver (custom class) demo uses a custom class driver. Like any custom driver when first plugged into a computer, a driver needs to be installed. When the device is plugged in to the computer the following window will pop-up:

Continue by selecting either options and clicking next.

If the driver has been installed on the computer before the installation process may complete itself without further action.

If the driver has not been installed before on the computer, then the driver will need to be installed. The Found New Hardware Wizard will be looking for a *.inf file with a matching VID/PID as the newly attached USB device. The driver can be found in the following location: “<Install Directory>\USB Tools\MCHPUSB Custom Driver\MCHPUSB Driver\Release”. Point the install wizard to this directory. The install wizard should then continue and finally complete.

Some example PC applications which interface with the driver can be found at “<Install Directory>\USB Tools\MCHPUSB Custom Driver\Mpusbapi”. PC applications can be written to either directly interface with the custom class USB driver (by using standard I/O functions like CreateFile(), ReadFile(), WriteFile(), CloseHandle()), or indirectly through the use of mpusbapi.dll. Mpusbapi.dll is a dynamic linked library file, which makes the process of interfacing with the custom class USB driver (and therefore, your USB device) somewhat simpler.

Demos > Device - MCHPUSB Generic Driver Demo > Running the Demo > Installing Windows Drivers


PDFSUSB

Contents | Index | Home
Previous | Up | Next
PDFSUSB

The example application can be found in the “<Install Directory>\USB Device - MCHPUSB - Generic Driver Demo\PC Software\Pdfsusb” directory.

When the application is first launched it will look like the following.

Select the “Demo Mode” tab.

In the listbox at the top of the application, select the “PICDEM FS USB…” option. If this option is not available then the device is either not connected to the computer, the driver was not installed correctly, or the firmware programmed into the device was not the correct project needed to interface with the generic driver.

With the listbox selecting the “PICDEM FS USB…” click the connect button. Once the button is clicked the application should start reading the potentiometer and temperature data from the hardware. The application can also change the state of the LEDs. NOTE: the Low Pin Count USB Development Kit does not have an on board temperature sensor. This feature is not currently implemented. Clicking LED3 button will toggle LED D7 on the Explorer 16 board. Clicking LED4 button will toggle LED D8 on the Explorer 16 board. While using Explorer 16 and dsPIC33EP512MU810 or PIC24EP512GU810 PIM, the temperature sensor and potentiometer interface are not supported.

Demos > Device - MCHPUSB Generic Driver Demo > Running the Demo > PDFSUSB


MCHPUSB PnP Demo

Contents | Index | Home
Previous | Up | Next
MCHPUSB PnP Demo

The example application can be found in the “<Install Directory>\USB Device - MCHPUSB - Generic Driver Demo\PC Software\Visual C++ 2005 Express” directory.

When the application is launched and the MCHPUSB custom device is not attached, it will look like the following:

Once the device is attached the application will reflect that the device is attached and look like the following. Moving the potentiometer will cause the status bar of the application to move to reflect the current value. While using Explorer 16 with dsPIC33EP512MU810 or PIC24EP512GU810 PIM, the potentiometer interface is not supported.

Demos > Device - MCHPUSB Generic Driver Demo > Running the Demo > MCHPUSB PnP Demo


Running the Demo (Android v3.1+)

Contents | Index | Home
Previous | Up | Next
Running the Demo (Android v3.1+)

There are two main ways to get the example application on to the target Android device: the Android Market and by compiling the source code.

  1. The demo application can be downloaded from Microchip’s Android Marketplace page: https://market.android.com/developer?pub=Microchip+Technology+Inc
  2. The source code for this demo is also provided in the demo project folder. For more information about how to build and load Android applications, please refer to the following pages:
    • http://developer.android.com/index.html
    • http://developer.android.com/sdk/index.html
    • http://developer.android.com/sdk/installing.html
While there are no devices attached, the Android application will indicate that no devices are attached.

When the device is attached, the an alternative screen will allow various control/status features with the hardware on the board.

Demos > Device - MCHPUSB Generic Driver Demo > Running the Demo > Running the Demo (Android v3.1+)


Device - Personal Healthcare Device Class (PHDC) Demo

Contents | Index | Home
Previous | Up | Next
Device - Personal Healthcare Device Class (PHDC) Demo

Four different medical device specialization demos are available for Personal Health Care Devices.

1) Blood Pressure Monitor Agent Demo

2) Glucose Meter Agent Demo

3) Thermometer Agent Demo

4) Weigh Scale Agent Demo

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18 Explorer Based Demos
For all of the PIC18 Explorer based demo boards, please follow the following instructions:
  1. Set switch S4 to the "ICE" position
  2. Apply power to the board.
  3. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC18F46J50 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options... more
Running the PHDC Blood Pressure Monitor Demo
The user needs to install the Continua Manager GUI in order to see the measured data that would be transmitted from the device. To obtain the Continua manager GUI one needs to be a member of the Continua Alliance organization. The Continua Manager is part of Continua Reference Code Library (CESL V1.x Gold release). The CESL V1.x Gold release can be downloaded from the following link [image] http://members.continuaalliance.org/members/rc_library/.
After navigating to this webpage click on “Please click this link to electronically sign the Reference Code Agreement”. You will get an email with ftp site link, username and password. After downloading... more
Running the PHDC Glucose Meter Demo
The user needs to install the Continua Manager GUI in order to see the measured data that would be transmitted from the device. To obtain the Continua manager GUI one needs to be a member of the Continua Alliance organization. The Continua Manager is part of Continua Reference Code Library (CESL V1.x Gold release). The CESL V1.x Gold release can be downloaded from the following link [image] http://members.continuaalliance.org/members/rc_library/.
After navigating to this webpage click on “Please click this link to electronically sign the Reference Code Agreement”. You will get an email with ftp site link, username and password. After downloading... more
Running the PHDC Themometer Demo
The user needs to install the Continua Manager GUI in order to see the measured data that would be transmitted from the device. To obtain the Continua manager GUI one needs to be a member of the Continua Alliance organization. The Continua Manager is part of Continua Reference Code Library (CESL V1.x Gold release). The CESL V1.x Gold release can be downloaded from the following link [image] http://members.continuaalliance.org/members/rc_library/.
After navigating to this webpage click on “Please click this link to electronically sign the Reference Code Agreement”. You will get an email with ftp site link, username and password. After downloading... more
Running the PHDC Weigh Scale Demo
The user needs to install the Continua Manager GUI in order to see the measured data that would be transmitted from the device. To obtain the Continua manager GUI one needs to be a member of the Continua Alliance organization. The Continua Manager is part of Continua Reference Code Library (CESL V1.x Gold release). The CESL V1.x Gold release can be downloaded from the following link [image] http://members.continuaalliance.org/members/rc_library/.
After navigating to this webpage click on “Please click this link to electronically sign the Reference Code Agreement”. You will get an email with ftp site link, username and password. After downloading... more
Performing the Continua Precertification Tests
This PHDC Agent demo passes Continua Alliance pre certification tests using the Continua Precertification tool. The pre certfication tool can be downloaded from Continua Alliance web site: http://members.continuaalliance.org/members/td_library/?referring_url=%2Fkws.To obtain the Continua precertification tool one needs to be a member of the Continua Alliance organization. Follow procedure given in the Test tool documentation for performing the tests.
PICS and PIXIT for each demo is given below.

PICS - USB Device PHDC Blood Pressure Monitor Demo
The USB Device PHDC Blood Pressure Monitor demo supports following PICS for the tests.
Demos > Device - Personal Healthcare Device Class (PHDC) Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit | 4,5,6,7
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1,4,5,6,7
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1,4,5,6,7
PIC32 USB Plug-In-Module (PIM) | 1,4,5,6
PIC32 CAN-USB Plug-In-Module (PIM) | 1,4,5,6,7
PIC32 USB Starter Kit | 3,4,5,6
PIC32 USB Starter Kit II | 4,5,6

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.
  4. The USB Device PHDC - Blood Pressure Monitor demo is not currently available for this demo board. However it is very easy to create a new project for this board by adding hardware profile file of the board.
  5. The USB DevicePHDC - Glucose Meter demo is not currently available for this demo board. However it is very easy to create a new project for this board by adding hardware profile file of the board.
  6. The USB DevicePHDC - Thermometer demo is not currently available for this demo board. However it is very easy to create a new project for this board by adding hardware profile file of the board.
  7. The USB DevicePHDC - Weigh Scale demo is not currently available for this demo board. However it is very easy to create a new project for this board by adding hardware profile file of the board.

Demos > Device - Personal Healthcare Device Class (PHDC) Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18 Explorer Based Demos

For all of the PIC18 Explorer based demo boards, please follow the following instructions:

  1. Set switch S4 to the "ICE" position
  2. Apply power to the board.
  3. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC18F46J50 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options are shorted together.
    2. Short JP3. This allows the demo board to be powered through the USB bus power.
  • PIC18F47J53 Plug-In-Module:
    1. Short JP2 such that the "R" and the "U" options are shorted together.
    2. Short JP3. This allows the demo board to be powered through the USB bus power.
  • PIC18F87J50 Plug-In-Module:
    1. Short JP1 such that the "R" and the "U" options are shorted together.
    2. Short JP4. This allows the demo board to be powered through the USB bus power.
    3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - Personal Healthcare Device Class (PHDC) Demo > Configuring the Demo


Running the PHDC Blood Pressure Monitor Demo

Contents | Index | Home
Previous | Up | Next
Running the PHDC Blood Pressure Monitor Demo

The user needs to install the Continua Manager GUI in order to see the measured data that would be transmitted from the device. To obtain the Continua manager GUI one needs to be a member of the Continua Alliance organization. The Continua Manager is part of Continua Reference Code Library (CESL V1.x Gold release). The CESL V1.x Gold release can be downloaded from the following link [image] http://members.continuaalliance.org/members/rc_library/.

After navigating to this webpage click on “Please click this link to electronically sign the Reference Code Agreement”. You will get an email with ftp site link, username and password. After downloading the file unzip and install CESL-SDK-1.5.0.zip file. This installs Continua Manager Utility.

In order to run this demo first compile and program the target device. Apply external power to the board if using PIC18 Explorer board or Explorer 16 board. If the demo board has an LCD display, it should displayed as shown below.

The systolic, diastolic blood pressure and Pulse rate are displayed on the LCD screen. The LCD also displays Connection status to the Continua Manager and Time(if RTCC is available on the demo board). Initially Connection Status is shown as DISCTD (disconnected).The potentiometer on the board emulates systolic blood pressure. Rotate the potentiometer on the demo board to vary the systolic blood pressure.

Now attach the device to the USB Host.

If the host is a Windows PC and this is the first time you have plugged this device into the computer then you may be asked for an .inf file. Microchip provides inf file along with the demo.

Select the “Install from a list or specific location (Advanced)” option. Point to the “<Install Directory>\USB\Device - PHDC - Blood Pressure Monitor\Windows Driver and INF” directory.

Once the device is successfully installed, open up the Continua Manager GUI. On the GUI the “Start Transport” button has to be pressed to connect with the device.

This enables the transport layer and the demo name will be shown in the "Device List" box.

Click on Start Transport Button

The demo needs two push buttons on the device board to showcase the PHDC application. The PHDC application provided emulates a Blood Pressure Monitor. Each press on a push button performs specific tasks. One of the push button toggles between “Unassociated” and “Operating” state. When the Device enters operating the connection status on the LCD changes to "CONCTD"(connected). The other pushbutton on assertion sends the measured data to the Continua Manager. The measurement will be sent only when both Manager and agent are in Operating States.

In some of the Microchip USB demo boards there is only one Pushbutton. In those demo boards with only one pushbutton the Agent (PHDC Device) Connects to the Manager when the pushbutton is pressed for the First time. When the pushbutton is pressed for the second, third and fourth time the device sends measured data to the device. The Agent gets disconnected from the Manager if the pushbutton is pressed for the Fifth time and this cycle repeats. Examples for demo boards with only one pushbutton are PIC18F46J50 PIM, PIC18F46J50 PIM, PIC18F87J50 PIM, PIC18F Starter Kit, PIC24FJ64GB502 Microstick, and Low Pin Count USB Development Kit.

Press Push Button on the device to enter in Operating state. The Continua Manager indicates that it is in Operating State.

Press the pushbutton on the device to Send Measured Data to the Manager. The continua Manager displays the received data from the Agent (PHDC device).

The demo configuration can be changed by modifying the below macros in the hardware profile file of the demo board.

/************ PHDC Demo Configuration *******************/

#define PHD_USE_POT_FOR_TEMP_SIMULATION

#define PHD_USE_LCD_DISPLAY

#define PHD_USE_RTCC_FOR_TIME_STAMP

#define DEMO_BOARD_HAS_ONLY_ONE_PUSH_BUTTON

When running this demo, the following push buttons are used. Please refer to each of the following sections for a description of how to run the demo on various operating systems:

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Demos > Device - Personal Healthcare Device Class (PHDC) Demo > Running the PHDC Blood Pressure Monitor Demo


Running the PHDC Glucose Meter Demo

Contents | Index | Home
Previous | Up | Next
Running the PHDC Glucose Meter Demo

The user needs to install the Continua Manager GUI in order to see the measured data that would be transmitted from the device. To obtain the Continua manager GUI one needs to be a member of the Continua Alliance organization. The Continua Manager is part of Continua Reference Code Library (CESL V1.x Gold release). The CESL V1.x Gold release can be downloaded from the following link [image] http://members.continuaalliance.org/members/rc_library/.

After navigating to this webpage click on “Please click this link to electronically sign the Reference Code Agreement”. You will get an email with ftp site link, username and password. After downloading the file unzip and install CESL-SDK-1.5.0.zip file. This installs Continua Manager Utility.

In order to run this demo first compile and program the target device. Apply external power to the board if using PIC18 Explorer board or Explorer 16 board. If the demo board has an LCD display, it should displayed as shown below.

The blood glucose is displayed on the LCD screen. The LCD also displays Connection status to the Continua Manager and Time(if RTCC is available on the demo board). Initially Connection Status is shown as DISCTD (disconnected).The potentiometer on the board emulates blood glucose. Rotate the potentiometer on the demo board to vary the blood glucose.

Now attach the device to the USB Host.

If the host is a Windows PC and this is the first time you have plugged this device into the computer then you may be asked for an .inf file. Microchip provides inf file along with the demo.

Select the “Install from a list or specific location (Advanced)” option. Point to the “<Install Directory>\USB\Device - PHDC - Glucose Meter\Windows Driver and INF” directory.

Once the device is successfully installed, open up the Continua Manager GUI. On the GUI the “Start Transport” button has to be pressed to connect with the device.

This enables the transport layer and the demo name will be shown in the "Device List" box.

Click on Start Transport Button

The demo needs two push buttons on the device board to showcase the PHDC application. The PHDC application provided emulates a Glucose Meter. Each press on a push button performs specific tasks. One of the push button toggles between “Unassociated” and “Operating” state. When the Device enters operating the connection status on the LCD changes to "CONCTD"(connected). The other pushbutton on assertion sends the measured data to the Continua Manager. The measurement will be sent only when both Manager and agent are in Operating States.

In some of the Microchip USB demo boards there is only one Pushbutton. In those demo boards with only one pushbutton the Agent (PHDC Device) Connects to the Manager when the pushbutton is pressed for the First time. When the pushbutton is pressed for the second, third and fourth time the device sends measured data to the device. The Agent gets disconnected from the Manager if the pushbutton is pressed for the Fifth time and this cycle repeats. Examples for demo boards with only one pushbutton are PIC18F46J50 PIM, PIC18F46J50 PIM, PIC18F87J50 PIM, PIC18F Starter Kit, PIC24FJ64GB502 Microstick, and Low Pin Count USB Development Kit.

Press Push Button on the device to enter in Operating state. The Continua Manager indicates that it is in Operating State.

Press the pushbutton on the device to Send Measured Data to the Manager. The continua Manager displays the received data from the Agent (PHDC device).

The demo configuration can be changed by modifying the below macros in the hardware profile file of the demo board.

/************ PHDC Demo Configuration *******************/

#define PHD_USE_POT_FOR_TEMP_SIMULATION

#define PHD_USE_LCD_DISPLAY

#define PHD_USE_RTCC_FOR_TIME_STAMP

#define DEMO_BOARD_HAS_ONLY_ONE_PUSH_BUTTON

When running this demo, the following push buttons are used. Please refer to each of the following sections for a description of how to run the demo on various operating systems:

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Demos > Device - Personal Healthcare Device Class (PHDC) Demo > Running the PHDC Glucose Meter Demo


Running the PHDC Themometer Demo

Contents | Index | Home
Previous | Up | Next
Running the PHDC Themometer Demo

The user needs to install the Continua Manager GUI in order to see the measured data that would be transmitted from the device. To obtain the Continua manager GUI one needs to be a member of the Continua Alliance organization. The Continua Manager is part of Continua Reference Code Library (CESL V1.x Gold release). The CESL V1.x Gold release can be downloaded from the following link [image] http://members.continuaalliance.org/members/rc_library/.

After navigating to this webpage click on “Please click this link to electronically sign the Reference Code Agreement”. You will get an email with ftp site link, username and password. After downloading the file unzip and install CESL-SDK-1.5.0.zip file. This installs Continua Manager Utility.

In order to run this demo first compile and program the target device. Apply external power to the board if using PIC18 Explorer board or Explorer 16 board. If the demo board has an LCD display, it should displayed as shown below.

The Body Temperature is displayed on the LCD screen. The LCD also displays Connection status to the Continua Manager and Time(if RTCC is available on the demo board). Initially Connection Status is shown as DISCTD (disconnected).The potentiometer on the board emulates Temperature. Rotate the potentiometer on the demo board to vary the Temperature.

Now attach the device to the USB Host.

If the host is a Windows PC and this is the first time you have plugged this device into the computer then you may be asked for an .inf file. Microchip provides inf file along with the demo.

Select the “Install from a list or specific location (Advanced)” option. Point to the “<Install Directory>\USB\Device - PHDC -Thermometer\Windows Driver and INF” directory.

Once the device is successfully installed, open up the Continua Manager GUI. On the GUI the “Start Transport” button has to be pressed to connect with the device.

This enables the transport layer and the demo name will be shown in the "Device List" box.

Click on Start Transport Button

The demo needs two push buttons on the device board to showcase the PHDC application. The PHDC application provided emulates a Thermometer. Each press on a push button performs specific tasks. One of the push button toggles between “Unassociated” and “Operating” state. When the Device enters operating the connection status on the LCD changes to "CONCTD"(connected). The other pushbutton on assertion sends the measured data to the Continua Manager. The measurement will be sent only when both Manager and agent are in Operating States.

In some of the Microchip USB demo boards there is only one Pushbutton. In those demo boards with only one pushbutton the Agent (PHDC Device) Connects to the Manager when the pushbutton is pressed for the First time. When the pushbutton is pressed for the second, third and fourth time the device sends measured data to the device. The Agent gets disconnected from the Manager if the pushbutton is pressed for the Fifth time and this cycle repeats. Examples for demo boards with only one pushbutton are PIC18F46J50 PIM, PIC18F46J50 PIM, PIC18F87J50 PIM, PIC18F Starter Kit, PIC24FJ64GB502 Microstick, and Low Pin Count USB Development Kit.

Press Push Button on the device to enter in Operating state. The Continua Manager indicates that it is in Operating State.

Press the pushbutton on the device to Send Measured Data to the Manager. The continua Manager displays the received data from the Agent (PHDC device).

The demo configuration can be changed by modifying the below macros in the hardware profile file of the demo board.

/************ PHDC Demo Configuration *******************/

#define PHD_USE_POT_FOR_TEMP_SIMULATION

#define PHD_USE_LCD_DISPLAY

#define PHD_USE_RTCC_FOR_TIME_STAMP

#define DEMO_BOARD_HAS_ONLY_ONE_PUSH_BUTTON

When running this demo, the following push buttons are used. Please refer to each of the following sections for a description of how to run the demo on various operating systems:

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Demos > Device - Personal Healthcare Device Class (PHDC) Demo > Running the PHDC Themometer Demo


Running the PHDC Weigh Scale Demo

Contents | Index | Home
Previous | Up | Next
Running the PHDC Weigh Scale Demo

The user needs to install the Continua Manager GUI in order to see the measured data that would be transmitted from the device. To obtain the Continua manager GUI one needs to be a member of the Continua Alliance organization. The Continua Manager is part of Continua Reference Code Library (CESL V1.x Gold release). The CESL V1.x Gold release can be downloaded from the following link [image] http://members.continuaalliance.org/members/rc_library/.

After navigating to this webpage click on “Please click this link to electronically sign the Reference Code Agreement”. You will get an email with ftp site link, username and password. After downloading the file unzip and install CESL-SDK-1.5.0.zip file. This installs Continua Manager Utility.

In order to run this demo first compile and program the target device. Apply external power to the board if using PIC18 Explorer board or Explorer 16 board. If the demo board has an LCD display, it should displayed as shown below.

The Weight is displayed on the LCD screen. The LCD also displays Connection status to the Continua Manager and Time(if RTCC is available on the demo board). Initially Connection Status is shown as DISCTD (disconnected).The potentiometer on the board emulates Weight. Rotate the potentiometer on the demo board to vary the Weight.

Now attach the device to the USB Host.

If the host is a Windows PC and this is the first time you have plugged this device into the computer then you may be asked for an .inf file. Microchip provides inf file along with the demo.

Select the “Install from a list or specific location (Advanced)” option. Point to the “<Install Directory>\USB\Device - PHDC - Weighing Scale\Windows Driver and INF” directory.

Once the device is successfully installed, open up the Continua Manager GUI. On the GUI the “Start Transport” button has to be pressed to connect with the device.

This enables the transport layer and the demo name will be shown in the "Device List" box.

Click on Start Transport Button

The demo needs two push buttons on the device board to showcase the PHDC application. The PHDC application provided emulates a Weight Scale. Each press on a push button performs specific tasks. One of the push button toggles between “Unassociated” and “Operating” state. When the Device enters operating the connection status on the LCD changes to "CONCTD"(connected). The other pushbutton on assertion sends the measured data to the Continua Manager. The measurement will be sent only when both Manager and agent are in Operating States.

In some of the Microchip USB demo boards there is only one Pushbutton. In those demo boards with only one pushbutton the Agent (PHDC Device) Connects to the Manager when the pushbutton is pressed for the First time. When the pushbutton is pressed for the second, third and fourth time the device sends measured data to the device. The Agent gets disconnected from the Manager if the pushbutton is pressed for the Fifth time and this cycle repeats. Examples for demo boards with only one pushbutton are PIC18F46J50 PIM, PIC18F46J50 PIM, PIC18F87J50 PIM, PIC18F Starter Kit, PIC24FJ64GB502 Microstick, and Low Pin Count USB Development Kit.

Press Push Button on the device to enter in Operating state. The Continua Manager indicates that it is in Operating State.

Press the pushbutton on the device to Send Measured Data to the Manager. The continua Manager displays the received data from the Agent (PHDC device).

The demo configuration can be changed by modifying the below macros in the hardware profile file of the demo board.

/************ PHDC Demo Configuration *******************/

#define PHD_USE_POT_FOR_TEMP_SIMULATION

#define PHD_USE_LCD_DISPLAY

#define PHD_USE_RTCC_FOR_TIME_STAMP

#define DEMO_BOARD_HAS_ONLY_ONE_PUSH_BUTTON

When running this demo, the following push buttons are used. Please refer to each of the following sections for a description of how to run the demo on various operating systems:

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Demos > Device - Personal Healthcare Device Class (PHDC) Demo > Running the PHDC Weigh Scale Demo


Performing the Continua Precertification Tests

Contents | Index | Home
Previous | Up | Next
Performing the Continua Precertification Tests

This PHDC Agent demo passes Continua Alliance pre certification tests using the Continua Precertification tool. The pre certfication tool can be downloaded from Continua Alliance web site: http://members.continuaalliance.org/members/td_library/?referring_url=%2Fkws.To obtain the Continua precertification tool one needs to be a member of the Continua Alliance organization. Follow procedure given in the Test tool documentation for performing the tests.

PICS and PIXIT for each demo is given below.

PICS - USB Device PHDC Blood Pressure Monitor Demo

The USB Device PHDC Blood Pressure Monitor demo supports following PICS for the tests.

Sl No | PICS | Caption
1 | C_OXP_000 | The SUT is an Agent
2 | C_AG_OXP_001 | Agent supports standard configuration
3 | C_AG_OXP_006 | Agent has an internal real-time clock
4 | C_AG_OXP_008 | Agent supports settable time.
5 | C_AG_OXP_009 | Agent reports AbsoluteTime
6 | C_AG_OXP_040 | Agent supports at least one Numeric object.
7 | C_AG_OXP_053 | Agent supports Confirmed event reports
8 | C_AG_OXP_182 | Agent uses fixed format value messages to report dynamic data for Numeric Objects
9 | C_AG_OXP_192 | Agent supports Absolute-Time Time Stamp for Numeric objects
10 | C_AG_UDG_001 | Agent supports USB transport
11 | C_AG_OXP_013 | Agent supports Mds-Time-Info attribute (MDS Objetc)
12 | C_AG_BPM_003 | Agent supports Pulse Object
13 | C_AG_OXP_236 | Do you want to apply for Blood pressure monitor specialization?
14 | C_AG_OXP_177 | Configuration under test supports Blood pressure monitor specialization
15 | C_AG_OXP_207 | Agent supports Blood Pressure Monitor Specialization
16 | C_AG_OXP_190 | Agent supports Metric-Id-List at least for a Numeric object

PIXITS - USB Device PHDC Blood Pressure Monitor demo

Sl No | PIXIT | Caption | Value
1 | I_AG_OXP_001 | System-Id: OUI | '313233'O
2 | I_AG_OXP_002 | System-Id: 40-bit manufacturer part | '3435363738'O
3 | I_AG_OXP_003 | System-Model: manufacturer | "Microchip "
4 | I_AG_OXP_004 | System-Model: model-number | "BP Monitor "
5 | I_AG_OXP_005 | Product-Specification: serial number | DE124567
6 | I_AG_OXP_006 | Product-Specification: Firmware revision | -
7 | I_AG_OXP_007 | Config-Id: Id for Configuration that is going to be tested. | 700

PICS - USB Device PHDC Glucose meter demo

The USB Device PHDC Glucose meter demo supports following PICS for the tests.

Sl No | PICS | Caption
1 | C_OXP_000 | The SUT is an Agent
2 | C_AG_OXP_001 | Agent supports standard configuration
3 | C_AG_OXP_006 | Agent has an internal real-time clock
4 | C_AG_OXP_008 | Agent supports settable time.
5 | C_AG_OXP_009 | Agent reports AbsoluteTime
6 | C_AG_OXP_040 | Agent supports at least one Numeric object.
7 | C_AG_OXP_053 | Agent supports Confirmed event reports
8 | C_AG_OXP_182 | Agent uses fixed format value messages to report dynamic data for Numeric Objects
9 | C_AG_OXP_192 | Agent supports Absolute-Time Time Stamp for Numeric objects
10 | C_AG_UDG_001 | Agent supports USB transport
11 | C_AG_OXP_013 | Agent supports Mds-Time-Info attribute (MDS Objetc)
12 | C_AG_OXP_233 | Do you want to apply for Glucose meter specialization?
13 | C_AG_OXP_178 | Configuration under test supports Glucose meter specialization
14 | C_AG_OXP_204 | Agent supports Glucose Meter Specialization
15 | C_AG_OXP_190 | Agent supports Metric-Id-List at least for a Numeric object

PIXITS - USB Device PHDC Glucose Meter demo

Sl No | PIXIT | Caption | Value
1 | I_AG_OXP_001 | System-Id: OUI | '313233'O
2 | I_AG_OXP_002 | System-Id: 40-bit manufacturer part | '3435363738'O
3 | I_AG_OXP_003 | System-Model: manufacturer | "Microchip "
4 | I_AG_OXP_004 | System-Model: model-number | "GlucoseMeter"
5 | I_AG_OXP_005 | Product-Specification: serial number | DE124567
6 | I_AG_OXP_006 | Product-Specification: Firmware revision | -
7 | I_AG_OXP_007 | Config-Id: Id for Configuration that is going to be tested. | 1700

PICS - USB Device PHDC Thermometer demo

The USB Device PHDC Thermometer demo supports following PICS for the tests.

Sl No | PICS | Caption
1 | C_OXP_000 | The SUT is an Agent
2 | C_AG_OXP_001 | Agent supports standard configuration
3 | C_AG_OXP_006 | Agent has an internal real-time clock
4 | C_AG_OXP_008 | Agent supports settable time.
5 | C_AG_OXP_009 | Agent reports AbsoluteTime
6 | C_AG_OXP_040 | Agent supports at least one Numeric object.
7 | C_AG_OXP_053 | Agent supports Confirmed event reports
8 | C_AG_OXP_182 | Agent uses fixed format value messages to report dynamic data for Numeric Objects
9 | C_AG_OXP_192 | Agent supports Absolute-Time Time Stamp for Numeric objects
10 | C_AG_UDG_001 | Agent supports USB transport
11 | C_AG_OXP_013 | Agent supports Mds-Time-Info attribute (MDS Objetc)
12 | C_AG_OXP_234 | Do you want to apply for Thermometer specialization?
13 | C_AG_OXP_171 | Configuration under test supports Thermometer specialization
14 | C_AG_OXP_205 | Agent supports ThermoMeter Specialization
15 | C_AG_OXP_190 | Agent supports Metric-Id-List at least for a Numeric object

PIXITS - USB Device PHDC Themometer demo

Sl No | PIXIT | Caption | Value
1 | I_AG_OXP_001 | System-Id: OUI | '313233'O
2 | I_AG_OXP_002 | System-Id: 40-bit manufacturer part | '3435363738'O
3 | I_AG_OXP_003 | System-Model: manufacturer | "Microchip "
4 | I_AG_OXP_004 | System-Model: model-number | "Thermometer "
5 | I_AG_OXP_005 | Product-Specification: serial number | DE124567
6 | I_AG_OXP_006 | Product-Specification: Firmware revision | -
7 | I_AG_OXP_007 | Config-Id: Id for Configuration that is going to be tested. | 800

PICS - USB Device PHDC Weight Scale demo

The USB Device PHDC Weight Scale demo supports following PICS for the tests.

Sl No | PICS | Caption
1 | C_OXP_000 | The SUT is an Agent
2 | C_AG_OXP_001 | Agent supports standard configuration
3 | C_AG_OXP_006 | Agent has an internal real-time clock
4 | C_AG_OXP_008 | Agent supports settable time.
5 | C_AG_OXP_009 | Agent reports AbsoluteTime
6 | C_AG_OXP_040 | Agent supports at least one Numeric object.
7 | C_AG_OXP_053 | Agent supports Confirmed event reports
8 | C_AG_OXP_182 | Agent uses fixed format value messages to report dynamic data for Numeric Objects
9 | C_AG_OXP_192 | Agent supports Absolute-Time Time Stamp for Numeric objects
10 | C_AG_UDG_001 | Agent supports USB transport
11 | C_AG_OXP_013 | Agent supports Mds-Time-Info attribute (MDS Objetc)
12 | C_AG_OXP_237 | Do you want to apply for Weigh Scale specialization?
13 | C_AG_OXP_174 | Configuration under test supports Weigh Scale specialization
14 | C_AG_OXP_208 | Agent supports Weigh Scale Specialization
15 | C_AG_OXP_190 | Agent supports Metric-Id-List at least for a Numeric object

PIXITS - USB Device PHDC Weigh Scale demo

Sl No | PIXIT | Caption | Value
1 | I_AG_OXP_001 | System-Id: OUI | '313233'O
2 | I_AG_OXP_002 | System-Id: 40-bit manufacturer part | '3435363738'O
3 | I_AG_OXP_003 | System-Model: manufacturer | "Microchip "
4 | I_AG_OXP_004 | System-Model: model-number | "Weigh Scale "
5 | I_AG_OXP_005 | Product-Specification: serial number | DE124567
6 | I_AG_OXP_006 | Product-Specification: Firmware revision | -
7 | I_AG_OXP_007 | Config-Id: Id for Configuration that is going to be tested. | 1500
Demos > Device - Personal Healthcare Device Class (PHDC) Demo > Performing the Continua Precertification Tests


Device - WinUSB Generic Driver Demo

Contents | Index | Home
Previous | Up | Next
Device - WinUSB Generic Driver Demo
Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered... more
Running the Demo
When running this demo, the following push buttons are used. Please refer to each of the following sections for a description of how to run the demo on various operating systems:
Demos > Device - WinUSB Generic Driver Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - WinUSB Generic Driver Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - WinUSB Generic Driver Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

When running this demo, the following push buttons are used. Please refer to each of the following sections for a description of how to run the demo on various operating systems:

Demo Board (click link for board information) | Button
Low Pin Count USB Development Kit | S1
PICDEM FS USB | S2
PIC18F46J50 Plug-In-Module (PIM) | S2
PIC18F47J53 Plug-In-Module (PIM) | S2
PIC18F87J50 Plug-In-Module (PIM) | S4
PIC18F Starter Kit | S1
PIC24FJ64GB004 Plug-In-Module (PIM) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1)
PIC24FJ64GB502 Microstick | S1
PIC24FJ256DA210 Development Board | S1
PIC24F Starter Kit | N/A(2)
PIC24EP512GU810 Plug-In-Module (PIM) | S3(1)
dsPIC33EP512MU810 Plug-In-Module (PIM) | S3(1)
PIC32 USB Plug-In-Module (PIM) | S3(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1)
PIC32 USB Starter Kit | SW1
PIC32 USB Starter Kit II | SW1

Notes:

1) This is the button number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Topics
Name
Description
Windows
This demo uses the selected hardware platform as a WinUSB class USB device. WinUSB is a vender specific driver produced by Microsoft for use with Windows® XP service pack 2 and Windows Vista® operating systems. This driver allows users to have access to interrupt, bulk, and control transfers directly.
The SimpleWinUSBDemo.exe program, and the associated firmware demonstrate how to use the WinUSB device drivers for basic general purpose USB data transfer. To make the PC source code as easy to understand as possible, the demo has deliberately been made simple, and only sends/receives small amounts of data.
Before you can... more
Android v3.1+
There are two main ways to get the example application on to the target Android device: the Android Market and by compiling the source code.
  1. The demo application can be downloaded from Microchip’s Android Marketplace page: https://market.android.com/developer?pub=Microchip+Technology+Inc
  2. The source code for this demo is also provided in the demo project folder. For more information about how to build and load Android applications, please refer to the following pages:
    • http://developer.android.com/index.html
    • http://developer.android.com/sdk/index.html
    • http://developer.android.com/sdk/installing.html
While there are no devices attached, the Android application will indicate that no devices are attached.

When the device is attached, the an alternative screen will allow various control/status... more
Demos > Device - WinUSB Generic Driver Demo > Running the Demo


Windows

Contents | Index | Home
Previous | Up | Next
Windows

This demo uses the selected hardware platform as a WinUSB class USB device. WinUSB is a vender specific driver produced by Microsoft for use with Windows® XP service pack 2 and Windows Vista® operating systems. This driver allows users to have access to interrupt, bulk, and control transfers directly.

The SimpleWinUSBDemo.exe program, and the associated firmware demonstrate how to use the WinUSB device drivers for basic general purpose USB data transfer. To make the PC source code as easy to understand as possible, the demo has deliberately been made simple, and only sends/receives small amounts of data.

Before you can run the SimpleWinUSBDemo.exe executable, you will need to have the Microsoft® .NET Framework Version 2.0 Redistributable Package (later versions probably okay, but not tested) installed on your computer. Programs which were built in the Visual Studio® .NET languages require the .NET redistributable package in order to run. The redistributable package can be freely downloaded from Microsoft’s website. Users of Windows Vista® operating systems will not need to install the .NET framework, as it comes pre-installed as part of the operating system.

The source code for SimpleWinUSBDemo.exe file was created in Microsoft Visual C++® 2005 Express Edition. The source code can be found in the “<Install Directory>\ USB Device - WinUSB - Generic Driver Demo\WinUSB Simple Demo - PC Application - MS VC++ 2005 Express” directory. Microsoft currently distributes Visual C++ 2005 Express Edition for free, and can be downloaded from Microsoft’s website. When downloading Microsoft Visual C++ 2005 Express Edition, also make sure to download and install the Platform SDK, and follow Microsoft’s instructions for integrating it with the development environment.

It is not necessary to install either Microsoft Visual C++ 2005, or the Platform SDK in order to begin using the SimpleWinUSBDemo.exe program. These are only required if the source code will be modified or compiled.

To launch the application, simply double click on the executable “SimpleWinUSBDemo.exe” in the “<Install Directory>\USB Device - WinUSB - Generic Driver Demo” directory. A window like that shown below should appear:

If instead of this window, an error message pops up while trying to launch the application, it is likely the Microsoft .NET Framework Version 2.0 Redistributable Package has not yet been installed. Please install it and try again.

In order to begin sending/receiving packets to the device, you must first find and “connect” to the device. As configured by default, the application is looking for USB devices with VID = 0x04D8 and PID = 0x0053. The device descriptor in the firmware project meant to be used with this demo uses the same VID/PID. If you plug in a USB device programmed with the correct precompiled .hex file, and hit the “Connect” button, the other pushbuttons should become enabled. If hitting the connect button has no effect, it is likely the USB device is either not connected, or has not been programmed with the correct firmware.

Hitting the Toggle LED(s) should send a single packet of general purpose generic data to the HID class USB peripheral device. The data will arrive on the interrupt OUT endpoint. The firmware has been configured to receive this generic data packet, parse the packet looking for the “Toggle LED(s)” command, and should respond appropriately by controlling the LED(s) on the demo board.

Please see the "Running the Demo" section for information about specific board limitations. Not all demo features may be available on all boards.

The “Get Pushbutton State” button will send one packet of data over the USB to the peripheral device (to the interrupt OUT endpoint) requesting the current pushbutton state. The firmware will process the received Get Pushbutton State command, and will prepare an appropriate response packet depending upon the pushbutton state.

The PC then requests a packet of data from the device (which will be taken from the interrupt IN endpoint). Once the PC application receives the response packet, it will update the pushbutton state label.

Try experimenting with the application by holding down the appropriate pushbutton on the demo board, and then simultaneously clicking on the “Get Pushbutton State” button. Then try to repeat the process, but this time without holding down the pushbutton on the demo board.

To make for a more fluid and gratifying end user experience, a real USB application would probably want to launch a separate thread to periodically poll the pushbutton state, so as to get updates regularly. This is not done in this simple demo, so as to avoid cluttering the PC application project with source code that is not related to USB communication.

Demos > Device - WinUSB Generic Driver Demo > Running the Demo > Windows


Android v3.1+

Contents | Index | Home
Previous | Up | Next
Android v3.1+

There are two main ways to get the example application on to the target Android device: the Android Market and by compiling the source code.

  1. The demo application can be downloaded from Microchip’s Android Marketplace page: https://market.android.com/developer?pub=Microchip+Technology+Inc
  2. The source code for this demo is also provided in the demo project folder. For more information about how to build and load Android applications, please refer to the following pages:
    • http://developer.android.com/index.html
    • http://developer.android.com/sdk/index.html
    • http://developer.android.com/sdk/installing.html
While there are no devices attached, the Android application will indicate that no devices are attached.

When the device is attached, the an alternative screen will allow various control/status features with the hardware on the board.

Demos > Device - WinUSB Generic Driver Demo > Running the Demo > Android v3.1+


Device - WinUSB High Bandwidth Demo

Contents | Index | Home
Previous | Up | Next
Device - WinUSB High Bandwidth Demo
Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Low Pin Count USB Development Kit
  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered... more
Running the Demo
This demo uses the selected hardware platform as a WinUSB class USB device. WinUSB is a vender specific driver produced by Microsoft for use with Windows® XP service pack 2 and later operating systems. This driver allows users to have access to interrupt, bulk, and control transfers directly.
The HighBandwidthWinUSB.exe program, and the associated firmware demonstrate how to use the WinUSB device drivers for USB Bulk data transfers. Total Time taken to transmit the data & data transmission rate (Bytes/Sec) is shown in the GUI once the data transmission of 9,60,000 bytes is completed from the PC side.
Before you... more
Demos > Device - WinUSB High Bandwidth Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
Low Pin Count USB Development Kit |
PICDEM FS USB |
PIC18F46J50 Plug-In-Module (PIM) |
PIC18F47J53 Plug-In-Module (PIM) |
PIC18F87J50 Plug-In-Module (PIM) |
PIC18F Starter Kit |
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 3
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Device - WinUSB High Bandwidth Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Low Pin Count USB Development Kit

  1. Short J14 between pins 2 and 3. This will power the board from the USB port.
  2. Make sure that J12 is left open.
PICDEM FS USB:
  • No hardware related configuration or jumper setting changes are necessary.
PIC18F46J50 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F47J53 Plug-In-Module:
  1. Short JP2 such that the "R" and the "U" options are shorted together.
  2. Short JP3. This allows the demo board to be powered through the USB bus power.
PIC18F87J50 Plug-In-Module:
  1. Short JP1 such that the "R" and the "U" options are shorted together.
  2. Short JP4. This allows the demo board to be powered through the USB bus power.
  3. Short JP5. This enabled the LED operation on the board.
PIC18F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Device - WinUSB High Bandwidth Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo uses the selected hardware platform as a WinUSB class USB device. WinUSB is a vender specific driver produced by Microsoft for use with Windows® XP service pack 2 and later operating systems. This driver allows users to have access to interrupt, bulk, and control transfers directly.

The HighBandwidthWinUSB.exe program, and the associated firmware demonstrate how to use the WinUSB device drivers for USB Bulk data transfers. Total Time taken to transmit the data & data transmission rate (Bytes/Sec) is shown in the GUI once the data transmission of 9,60,000 bytes is completed from the PC side.

Before you can run the HighBandwidthWinUSB.exe executable, you will need to have the Microsoft® .NET Framework Version 2.0 Redistributable Package (later versions probably okay, but not tested) installed on your computer. Programs which were built in the Visual Studio® .NET languages require the .NET redistributable package in order to run. The redistributable package can be freely downloaded from Microsoft’s website. Users of Windows Vista® operating systems will not need to install the .NET framework, as it comes pre-installed as part of the operating system.

The source code for HighBandwidthWinUSB.exe file was created in Microsoft Visual C++® 2005 Express Edition. The source code can be found in the “<Install Directory>\ USB Device - WinUSB - High Bandwidth Demo\WinUSB High Bandwidth Demo - PC Application - MS VC++ 2005 Express” directory. Microsoft currently distributes Visual C++ 2005 Express Edition for free, and can be downloaded from Microsoft’s website. When downloading Microsoft Visual C++ 2005 Express Edition, also make sure to download and install the Platform SDK, and follow Microsoft’s instructions for integrating it with the development environment.

It is not necessary to install either Microsoft Visual C++ 2005, or the Platform SDK in order to begin using the HighBandwidthWinUSB.exe program. These are only required if the source code will be modified or compiled.

To launch the application, simply double click on the executable “HighBandwidthWinUSB.exe” in the “<Install Directory>\USB Device - WinUSB - High Bandwidth Demo” directory. A window like that shown below should appear:

If instead of this window, an error message pops up while trying to launch the application, it is likely the Microsoft .NET Framework Version 2.0 Redistributable Package has not yet been installed. Please install it and try again.

As configured by default, the application is looking for USB devices with VID = 0x04D8 and PID = 0x0052. The device descriptor in the firmware project meant to be used with this demo uses the same VID/PID. Once the device flashed with corresponding firmware is connected to the PC, the below window appears:

Hitting the “Send Bulk OUT Packets” tab will transmit 960,000 bytes of data on the USB bus to the corresponding endpoints ( EP1 Only or EP1,EP2, EP3 Simultaneously depending upon the button pressed in the GUI). Elapsed Time (ms) & Bandwidth (Bytes/Sec) are displayed in the GUI once the data transmission is complete.

Demos > Device - WinUSB High Bandwidth Demo > Running the Demo


Dual Role - MSD Host + HID Device

Contents | Index | Home
Previous | Up | Next
Dual Role - MSD Host + HID Device

This demo shows how to create a dual role device (one that supports both host and device functionality.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center... more
Running the Demo
This demo has two separate portions, the host portion and the device portion. You must press a button on the board for the demo to enter host mode. It will remain in this mode until a device is attached and then removed. A second button is used to place the demo into device mode. It will stay in this mode until it detects a detachment from the USB bus.
The host portion is a MSD host and acts exactly the same as the Host - Mass Storage (MSD) - Simple Demo. Make sure to use the Configuring the Demo... more
Demos > Dual Role - MSD Host + HID Device


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ256DA210 Development Board |
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Dual Role - MSD Host + HID Device > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

Demos > Dual Role - MSD Host + HID Device > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo has two separate portions, the host portion and the device portion. You must press a button on the board for the demo to enter host mode. It will remain in this mode until a device is attached and then removed. A second button is used to place the demo into device mode. It will stay in this mode until it detects a detachment from the USB bus.

The host portion is a MSD host and acts exactly the same as the Host - Mass Storage (MSD) - Simple Demo. Make sure to use the Configuring the Demo from this section and the Running the Demo from the MSD host demo. Simply plug in a FAT/FAT32 thumb drive to the host port and this demo will write a test file to the drive.

The device portion of this demo acts exactly the same as the Device - HID - Custom Demo. Make sure to use the Configuring the Demo from this section and the Running the Demo from the HID device demo. Please read the description of how to run this demo provided in the link above.

You can not have both the device port and the host port connected when running this demo. The host functionality and device functionality are using the same USB peripheral on the device, even though it is using two separate USB connectors.

Demo Board (click link for board information) | Button to enter host mode | Button to enter device mode
PIC24FJ64GB004 Plug-In-Module (PIM) | S3(1) | S6(1)
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1) | S6(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1) | S6(1)
PIC24FJ256DA210 Development Board | S2 | S3
PIC32 USB Plug-In-Module (PIM) | S3(1) | S6(1)
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1) | S6(1)

Notes:

1) This is the button number on the Explorer 16.

Demos > Dual Role - MSD Host + HID Device > Running the Demo


Host - Audio MIDI Demo

Contents | Index | Home
Previous | Up | Next
Host - Audio MIDI Demo
Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to the... more
Running the Demo
This is a simple demo to show how an embedded MIDI host can be implemented. When a USB MIDI device is attached to the host, the demo host application polls for input data from the device and converts the data from MIDI USB packets to MIDI UART packets and sends the UART packets over the UART bus. And when a UART MIDI device is connected to the host, the demo host application polls for input data from that device and converts the data from MIDI UART packets to MIDI USB packets, and sends the USB packets over the USB bus.... more
Demos > Host - Audio MIDI Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ64GB004 Plug-In-Module (PIM) | 1, 2
PIC24FJ256GB110 Plug-In-Module (PIM) | 1, 2
PIC24FJ256GB210 Plug-In-Module (PIM) | 1, 2
PIC24EP512GU810 Plug-In-Module (PIM) | 1, 2
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1, 2
PIC32 USB Plug-In-Module (PIM) | 1, 2
PIC32 CAN-USB Plug-In-Module (PIM) | 1, 2

Notes:

  1. These boards require the Speech Playback PICTail/PICTail+ daughter board in order to run this demo.
  2. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Host - Audio MIDI Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP1 on the USB PICTail+ board
  3. Open JP2, JP3, and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to the center pin
    3. Short J2 pin 1 (marked "Temp") to the center pin
    4. Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    1. Short JP1 "U" option to the center pin
    2. Short JP2 "U" option to the center pin
    3. Short JP3 "U" option to the center pin
    4. Short JP4
  • PIC24EP512GU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    1. Open J10
    2. Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

Demos > Host - Audio MIDI Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This is a simple demo to show how an embedded MIDI host can be implemented. When a USB MIDI device is attached to the host, the demo host application polls for input data from the device and converts the data from MIDI USB packets to MIDI UART packets and sends the UART packets over the UART bus. And when a UART MIDI device is connected to the host, the demo host application polls for input data from that device and converts the data from MIDI UART packets to MIDI USB packets, and sends the USB packets over the USB bus.

To test this demo, connect a USB MIDI device to the development board, and either connect the board to a computer via RS-232 or a MIDI UART device. The USB MIDI packets will be converted to UART MIDI packets and will be sent to the attached UART MIDI device, or if connected to a computer, send to a terminal program.

To test with a terminal program, make sure that a baud rate of 32150 is used, and the terminal program reads hex, not ascii. The packets sent will be shown in the terminal following the MIDI protocol, which is explained here:

http://www.srm.com/qtma/davidsmidispec.html

Demos > Host - Audio MIDI Demo > Running the Demo


Host - Boot Loader - Thumb Drive Boot Loader

Contents | Index | Home
Previous | Up | Next
Host - Boot Loader - Thumb Drive Boot Loader
Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the... more
Running the Demo
Once the image.hex file is created using the process described in the Creating a Hex File to Load section, copy this file onto a thumbdrive. Insert the thumbdrive into the USB A connector. Press and hold the boot load button specified in the table below while resetting the board by pressing the MCLR button or applying power to the board.
An LED on the board should illuminate if this is done correctly (see table below). The LED should turn itself off once the bootload process is complete. At this point of time the application should be running. If you wish... more
Demos > Host - Boot Loader - Thumb Drive Boot Loader


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ256DA210 Development Board |
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Host - Boot Loader - Thumb Drive Boot Loader > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

PIC24FJ256DA210 Development Board Based Demos

For all of the PIC24FJ256DA210 demo board based demos, please follow the following instructions

  1. Short JP13 between the S1 and RG8 taps.
  2. Short JP14 between the S2 and RE9 taps.
  3. Short JP15 between the S3 and RB5 taps.
  4. Short JP6
  5. Open JP5 and JP7

PIC32 USB Starter Kit

  • No hardware related configuration or jumper setting changes are necessary.

PIC32 USB Starter Kit II

  • No hardware related configuration or jumper setting changes are necessary.

Demos > Host - Boot Loader - Thumb Drive Boot Loader > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

Once the image.hex file is created using the process described in the Creating a Hex File to Load section, copy this file onto a thumbdrive. Insert the thumbdrive into the USB A connector. Press and hold the boot load button specified in the table below while resetting the board by pressing the MCLR button or applying power to the board.

An LED on the board should illuminate if this is done correctly (see table below). The LED should turn itself off once the bootload process is complete. At this point of time the application should be running. If you wish to abort a bootload sequence you can press the abort switch or power cycle the board.

Demo Board (click link for board information) | Boot Load Button | Abort Button | LED
PIC24FJ256GB110 Plug-In-Module (PIM) | S3(1) | S6(1) | D5(1)
PIC24FJ256GB210 Plug-In-Module (PIM) | S3(1) | S6(1) | D5(1)
PIC24FJ256DA210 Development Board | S3 | S2 | D1
PIC32 CAN-USB Plug-In-Module (PIM) | S3(1) | S6(1) | D5(1)
PIC32 USB Starter Kit II | SW1 | SW2 | LED3

Notes:

1) This is the button/LED number on the Explorer 16.

2) This demo board only has capacitive touch buttons. At this time the button feature of this demo does not work on this board.

Topics
Name
Description
Creating a Hex File to Load
Any application in the MCHPFSUSB release can be used to create a hex file the can be loaded with this bootloader.
In order to create a new hex file to bootload, follow these steps:
MPLAB 8:
  1. First open up the target project.
  2. Insure that the correct processor is selected in the “Configure->Select Device” option of MPLAB 8
  3. If there is a linker script already attached to the project, remove it from the project by right clicking on it and selecting remove.
  4. Copy the appropriate linker file to the demo project folder. The linker files for the thumbdrive bootloader can... more
Customizing the Boot Loader and Target Application Linker Scripts for PIC32 devices
The PIC32 USB MSD Host boot loader uses the PIC32MX795F512L device by default. To use the boot loader with another PIC32 device (for example, say the PIC32MX564F128H device), the following steps should be followed.
For Boot Loader Applications:
  1. Copy the procdefs.ld file from \Program Files\Microchip\mplabc32\v2.01\pic32mx\lib\proc\32MX564F128H folder to the boot loader project folder ( the folder that contains USB Host - Mass Storage Bootloader - C32.mcp file). You may have to overwrite the existing procdefs.ld file.
  2. Open the procdefs.ld file in a text editor. Change the length of the kseg0_program_mem section to 0xE000. See the figure below. This is the... more
Demos > Host - Boot Loader - Thumb Drive Boot Loader > Running the Demo


Creating a Hex File to Load

Contents | Index | Home
Previous | Up | Next
Creating a Hex File to Load

Any application in the MCHPFSUSB release can be used to create a hex file the can be loaded with this bootloader.

In order to create a new hex file to bootload, follow these steps:

MPLAB 8:

  1. First open up the target project.
  2. Insure that the correct processor is selected in the “Configure->Select Device” option of MPLAB 8
  3. If there is a linker script already attached to the project, remove it from the project by right clicking on it and selecting remove.
  4. Copy the appropriate linker file to the demo project folder. The linker files for the thumbdrive bootloader can be found in the “<install directory>\USB Host - Bootloaders\Mass Storage Bootloader\Application Files\Linker Files” folder. For PIC32 target device refer to Customizing the Boot loader and Target application Linker Scripts for PIC32 devices.
  5. Add this file to the project by right clicking on the “linker scripts” folder in the project window, select “Add Files…”.
  6. Compile the project.
  7. Rename the resulting .hex file to “image.hex”. It is important that the name be exact. The bootloader is looking for that file specifically by name.

MPLAB X:

1) first open up the target project.

2) Select the configuration that corresponds to your demo board.

3) Copy the appropriate linker file to the demo project folder. The linker files for the thumbdrive bootloader can be found in the “<install directory>\USB Host - Bootloaders\Mass Storage Bootloader\Application Files\Linker Files” folder. For PIC32 target device refer to Customizing the Boot loader and Target application Linker Scripts for PIC32 devices.

4) Add this file to the project by right clicking on the “linker scripts” folder in the project window, select “Add Existing Item…”. Select the correct file that corresponds to the processor that is being used on the demo board.

5) Compile the project.

6) Rename the resulting .hex file to “image.hex”. It is important that the name be exact. The bootloader is looking for that file specifically by name.

Demos > Host - Boot Loader - Thumb Drive Boot Loader > Running the Demo > Creating a Hex File to Load


Customizing the Boot Loader and Target Application Linker Scripts for PIC32 devices

Contents | Index | Home
Previous | Up | Next
Customizing the Boot Loader and Target Application Linker Scripts for PIC32 devices

The PIC32 USB MSD Host boot loader uses the PIC32MX795F512L device by default. To use the boot loader with another PIC32 device (for example, say the PIC32MX564F128H device), the following steps should be followed.

For Boot Loader Applications:

  1. Copy the procdefs.ld file from \Program Files\Microchip\mplabc32\v2.01\pic32mx\lib\proc\32MX564F128H folder to the boot loader project folder ( the folder that contains USB Host - Mass Storage Bootloader - C32.mcp file). You may have to overwrite the existing procdefs.ld file.
  2. Open the procdefs.ld file in a text editor. Change the length of the kseg0_program_mem section to 0xE000. See the figure below. This is the memory allocated for the boot loader code with compiler size optimization enabled. If the compiler size optimization is disabled, this number should be changed to 0x17000. If the size is not increased, the linker would indicate an error saying that it cannot fit the code within the specified memory region.
  3. Save and close procdefs.ld file. Build the USB Host - Mass Storage Bootloader - C32.mcp project and program the boot loader on to the device.

For Target Applications:

  1. Copy the procdefs.ld file from \Program Files\Microchip\mplabc32\v2.01\pic32mx\lib\proc\32MX564F128H folder to the target application folder ( the folder that contains the project to be boot loaded).
  2. Open the procdefs.ld file in a text editor. Multiple changes are needed to the application procdefs.ld file.
    1. Change _RESET_ADDR to 0x9D00F000
    2. Change _BEV_EXCPT_ADDR to 0x9D00F380
    3. Change _DBG_EXCPT_ADDR to 0x9D00F480
    4. Change the exception_mem origin to start from 0x9D00E000. This origin address is obtained by adding the size of boot loader application (which is 0xE000 in our case) to the actual start of the KSEG0 program memory (that is 0x9D000000).
    5. Change the kseg1_boot_mem origin to start from 0x9D00F000
    6. Change the kseg0_boot_mem origin to start from 0x9D00F490
    7. Change the kseg0_program_mem origin to start from 0x9D00FA00. Change the length to 0x10600 ( i.e. 0x20000 (the total memory on device) - 0xFA00). The changes are shown in the screen shot below.
  3. Save and close the procdefs.ld file. Compile and build the target application. This completes the steps required for using the boot loader with another PIC32 device.

Demos > Host - Boot Loader - Thumb Drive Boot Loader > Running the Demo > Customizing the Boot Loader and Target Application Linker Scripts for PIC32 devices


Host - CDC Serial Demo

Contents | Index | Home
Previous | Up | Next
Host - CDC Serial Demo

This demo shows how to interface to USB CDC devices. This typically includes many cell phone models and USB modems.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to... more
Running the Demo
This is a simple demo to show how an embedded CDC host can be implemented. When a CDC-RS232 device is attached to the host, the demo host application polls for input data from the device and displays the data on the LCD mounted on the explorer 16 board. When a switch SW6 on explorer 16 board is pressed a string “**** Test Data *****” is sent to the attached device to simulate the OUT transfer.
Demos > Host - CDC Serial Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ64GB004 Plug-In-Module (PIM) | 1, 2
PIC24FJ256GB110 Plug-In-Module (PIM) | 2
PIC24FJ256GB210 Plug-In-Module (PIM) | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 2
dsPIC33EP512MU810 Plug-In-Module (PIM) | 2
PIC32 USB Plug-In-Module (PIM) | 2
PIC32 CAN-USB Plug-In-Module (PIM) | 2

Notes:

  1. This configuration requires optimizations in order to fit the memory of the part. Not all versions of the compilers support all optimization levels.
  2. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Host - CDC Serial Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to the center pin
    3. Short J2 pin 1 (marked "Temp") to the center pin
    4. Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    1. Short JP1 "U" option to the center pin
    2. Short JP2 "U" option to the center pin
    3. Short JP3 "U" option to the center pin
    4. Short JP4
  • PIC24EP512GU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    1. Open J10
    2. Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

Demos > Host - CDC Serial Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This is a simple demo to show how an embedded CDC host can be implemented. When a CDC-RS232 device is attached to the host, the demo host application polls for input data from the device and displays the data on the LCD mounted on the explorer 16 board. When a switch SW6 on explorer 16 board is pressed a string “**** Test Data *****” is sent to the attached device to simulate the OUT transfer.

Demos > Host - CDC Serial Demo > Running the Demo


Host - Charger - Simple Charger

Contents | Index | Home
Previous | Up | Next
Host - Charger - Simple Charger
Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to... more
Running the Demo
This demo shows how to create a simple USB host based charger. To run the demo, plug in a device to the USB port. If it is capable of charging from USB at a 500mA rate, it should start charging.
Not all devices are capable of charging from USB, so not all devices may work with this demo. Some devices can charge over USB, but require a device that implements the USB battery charging specification device to allow higher charge rates than 500mA. This demo does not currently support the USB battery charging specification, so it will not be able... more
Demos > Host - Charger - Simple Charger


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Host - Charger - Simple Charger > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Host - Charger - Simple Charger > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo shows how to create a simple USB host based charger. To run the demo, plug in a device to the USB port. If it is capable of charging from USB at a 500mA rate, it should start charging.

Not all devices are capable of charging from USB, so not all devices may work with this demo. Some devices can charge over USB, but require a device that implements the USB battery charging specification device to allow higher charge rates than 500mA. This demo does not currently support the USB battery charging specification, so it will not be able to charge these devices either.

For more information about the USB battery charging specification, please refer to the specification at the USB website ( [image] http://www.usb.org/developers/devclass_docs).

Demos > Host - Charger - Simple Charger > Running the Demo


Host - Composite - MSD+ CDC

Contents | Index | Home
Previous | Up | Next
Host - Composite - MSD+ CDC
Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to... more
Running the Demo
This demo supports a composite device with MSD and CDC interfaces only. Please refer CDC host and MSD hostdocumentation to understand the individual host requirements. The device end can be programmed on any of the development boards for which "USB Device - Composite - MSD + CDC" demo is implemented. The composite host demo works in two steps.
Step 1 - The MSD interface opens a file "test.txt" with text "This is from Composite Host." as the content of the file.
Step 2 - On pressing switch 'S6' on host i.e Explorer 16 board the demo send a character... more
Demos > Host - Composite - MSD+ CDC


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ64GB004 Plug-In-Module (PIM) | 1, 2
PIC24FJ256GB110 Plug-In-Module (PIM) | 2
PIC24FJ256GB210 Plug-In-Module (PIM) | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 2
dsPIC33EP512MU810 Plug-In-Module (PIM) | 2
PIC32 USB Plug-In-Module (PIM) | 2
PIC32 CAN-USB Plug-In-Module (PIM) | 2

Notes:

  1. This configuration requires optimizations in order to fit the memory of the part. Not all versions of the compilers support all optimization levels.
  2. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Host - Composite - MSD+ CDC > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to the center pin
    3. Short J2 pin 1 (marked "Temp") to the center pin
    4. Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    1. Short JP1 "U" option to the center pin
    2. Short JP2 "U" option to the center pin
    3. Short JP3 "U" option to the center pin
    4. Short JP4
  • PIC24EP512GU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    1. Open J10
    2. Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

Demos > Host - Composite - MSD+ CDC > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo supports a composite device with MSD and CDC interfaces only. Please refer CDC host and MSD hostdocumentation to understand the individual host requirements. The device end can be programmed on any of the development boards for which "USB Device - Composite - MSD + CDC" demo is implemented. The composite host demo works in two steps.

Step 1 - The MSD interface opens a file "test.txt" with text "This is from Composite Host." as the content of the file.

Step 2 - On pressing switch 'S6' on host i.e Explorer 16 board the demo send a character on the CDC interface. The same character is echoed back by the device firmware. On reception the character is displayed on the LCD display on the Explorer 16 demo board.

Demos > Host - Composite - MSD+ CDC > Running the Demo


Host - Composite - HID + MSD

Contents | Index | Home
Previous | Up | Next
Host - Composite - HID + MSD
Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to... more
Running the Demo
This demo supports a composite device with HID and MSD interfaces only. Please refer HID host and MSD host documentation to understand the individual host requirements. The device end can be programmed on any of the development boards for which "USB Device - Composite - HID + MSD" demo is implemented. The composite host demo works in two steps.
Step 1 - The MSD interface opens a file "test.txt" with text "This is from Composite Host." as the content of the file.
Step 2 - The HID interface gets POT value from the device and displays it on... more
Demos > Host - Composite - HID + MSD


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ64GB004 Plug-In-Module (PIM) | 1, 2
PIC24FJ256GB110 Plug-In-Module (PIM) | 2
PIC24FJ256GB210 Plug-In-Module (PIM) | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 2
dsPIC33EP512MU810 Plug-In-Module (PIM) | 2
PIC32 USB Plug-In-Module (PIM) | 2
PIC32 CAN-USB Plug-In-Module (PIM) | 2

Notes:

  1. This configuration requires optimizations in order to fit the memory of the part. Not all versions of the compilers support all optimization levels.
  2. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Host - Composite - HID + MSD > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to the center pin
    3. Short J2 pin 1 (marked "Temp") to the center pin
    4. Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    1. Short JP1 "U" option to the center pin
    2. Short JP2 "U" option to the center pin
    3. Short JP3 "U" option to the center pin
    4. Short JP4
  • PIC24EP512GU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    1. Open J10
    2. Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

Demos > Host - Composite - HID + MSD > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo supports a composite device with HID and MSD interfaces only. Please refer HID host and MSD host documentation to understand the individual host requirements. The device end can be programmed on any of the development boards for which "USB Device - Composite - HID + MSD" demo is implemented. The composite host demo works in two steps.

Step 1 - The MSD interface opens a file "test.txt" with text "This is from Composite Host." as the content of the file.

Step 2 - The HID interface gets POT value from the device and displays it on the LCD mounted on the Explorer 16 board. On press of switch 'S6' on Explorer 16 board HID interface sends a command to toggle the LED's on the device board.

Demos > Host - Composite - HID + MSD > Running the Demo


Host - HID - Keyboard Demo

Contents | Index | Home
Previous | Up | Next
Host - HID - Keyboard Demo

This demo shows how to interface to USB keyboards. Many USB barcode scanners also appear as a USB keyboard.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to... more
Running the Demo
When the device is programmed correctly with the HID host keyboard application the LCD screen on the Explorer 16 should read “Device Detached” if there is no device attached to the USB port. At this point plug in a USB keyboard, bar code scanner that supports HID keyboard emulation, or magnetic card reader that supports HID keyboard emulation. Type a key on the keyboard. This character should be printed on the LCD screen. Pressing the “ESC” key will clear the screen and return the cursor to the first position.
Demos > Host - HID - Keyboard Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Host - HID - Keyboard Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

Demos > Host - HID - Keyboard Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

When the device is programmed correctly with the HID host keyboard application the LCD screen on the Explorer 16 should read “Device Detached” if there is no device attached to the USB port. At this point plug in a USB keyboard, bar code scanner that supports HID keyboard emulation, or magnetic card reader that supports HID keyboard emulation. Type a key on the keyboard. This character should be printed on the LCD screen. Pressing the “ESC” key will clear the screen and return the cursor to the first position.

Limitations:
  • Neither compound nor composite devices are supported. Some keyboards are either compound or composite.
  • The “~” prints as an arrow character instead (“->”). This is an effect of the LCD screen on the Explorer 16. The ascii character for “~” is remapped in the LCD controller.
  • The “\” prints as a “¥” character instead. This is an effect of the LCD screen on the Explorer 16. The ascii character for “\” is remapped in the LCD controller.
  • Backspace and arrow keys may have issues on Explorer 16 boards with certain LCD modules
Demos > Host - HID - Keyboard Demo > Running the Demo


Host - HID - Mouse Demo

Contents | Index | Home
Previous | Up | Next
Host - HID - Mouse Demo
Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to... more
Running the Demo
When the device is programmed correctly with the HID host mouse application the LCD screen on the Explorer 16 should read “Device Detached” if there is no device attached to the USB port. At this point plug in a USB mouse. As you move the mouse the X & Y co-ordinates of the mouse are displayed on the LCD display mounted on the Explorer 16 demo board. The display also toggles the status of Left/Right click status received from the mouse.
Demos > Host - HID - Mouse Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board does not contain all of the hardware features to run all of the features of the demo, but will work in a limited capacity or has the hardware feature emulated in software.
  3. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Host - HID - Mouse Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

Demos > Host - HID - Mouse Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

When the device is programmed correctly with the HID host mouse application the LCD screen on the Explorer 16 should read “Device Detached” if there is no device attached to the USB port. At this point plug in a USB mouse. As you move the mouse the X & Y co-ordinates of the mouse are displayed on the LCD display mounted on the Explorer 16 demo board. The display also toggles the status of Left/Right click status received from the mouse.

Limitations:
  • Composite and compound device are not currently supported. These devices may not enumerate or operate correctly. Devices with built in USB hubs are likely compound device. Many multimedia devices with mouse as one of the interface are composite devices.
Demos > Host - HID - Mouse Demo > Running the Demo


Host - Mass Storage (MSD) - Simple Demo

Contents | Index | Home
Previous | Up | Next
Host - Mass Storage (MSD) - Simple Demo
Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to... more
Running the Demo
This demo is a simple example of how to write files to a thumb drive through the Microchip MDD file system library. When a thumb drive is plugged in the code will create a text file on the drive. This process only takes a brief moment. After connecting the thumb drive to the board and waiting for a couple of seconds, remove the drive and plug it back into a computer. There should be an additional text file created named “test.txt”.
Demos > Host - Mass Storage (MSD) - Simple Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ64GB502 Microstick |
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit |
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 2
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Host - Mass Storage (MSD) - Simple Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC24FJ64GB502 Microstick
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Host - Mass Storage (MSD) - Simple Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo is a simple example of how to write files to a thumb drive through the Microchip MDD file system library. When a thumb drive is plugged in the code will create a text file on the drive. This process only takes a brief moment. After connecting the thumb drive to the board and waiting for a couple of seconds, remove the drive and plug it back into a computer. There should be an additional text file created named “test.txt”.

Limitations:
  • Due to the size of this demo, optimizations must be enabled in the compiler in order for this demo to work on the certain hardware platforms. Optimizations are not available on all versions of the compilers.
Demos > Host - Mass Storage (MSD) - Simple Demo > Running the Demo


Host - Mass Storage - Thumb Drive Data Logger

Contents | Index | Home
Previous | Up | Next
Host - Mass Storage - Thumb Drive Data Logger

This demo shows how to create a console based interface to a system that can read, write, and log data to a thumb drive. This demo is great for showing the various capabilities of the MDD library and the the USB host stack, but is a fairly complex demo. For a more simple introduction to interfacing to a thumb drive, consider starting from the Host - Mass Storage - Simple Demo instead of this demo.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to... more
Running the Demo
Once the device is programmed with the correct firmware, connect a serial cable from the Explorer 16 to the computer. Open up a terminal program with the following settings: baud rate – 57600, data – 8bit, parity – none, stop – 1 bit, and flow control – none.

Connect power to the Explorer 16. If power was already connected to the board before the serial port was connected, either cycle power, press reset, or press enter. This should give a “>” prompt. Connect a USB Thumb Drive to the host connector. If the prompt does not appear then verify that... more
Demos > Host - Mass Storage - Thumb Drive Data Logger


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ64GB004 Plug-In-Module (PIM) | 1, 2
PIC24FJ256GB110 Plug-In-Module (PIM) | 2
PIC24FJ256GB210 Plug-In-Module (PIM) | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 2
dsPIC33EP512MU810 Plug-In-Module (PIM) | 2
PIC32 USB Plug-In-Module (PIM) | 2
PIC32 CAN-USB Plug-In-Module (PIM) | 2

Notes:

  1. This configuration requires optimizations in order to fit the memory of the part. Not all versions of the compilers support all optimization levels.
  2. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Host - Mass Storage - Thumb Drive Data Logger > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to the center pin
    3. Short J2 pin 1 (marked "Temp") to the center pin
    4. Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    1. Short JP1 "U" option to the center pin
    2. Short JP2 "U" option to the center pin
    3. Short JP3 "U" option to the center pin
    4. Short JP4
  • PIC24EP512GU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    1. Open J10
    2. Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

Demos > Host - Mass Storage - Thumb Drive Data Logger > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

Once the device is programmed with the correct firmware, connect a serial cable from the Explorer 16 to the computer. Open up a terminal program with the following settings: baud rate – 57600, data – 8bit, parity – none, stop – 1 bit, and flow control – none.

Connect power to the Explorer 16. If power was already connected to the board before the serial port was connected, either cycle power, press reset, or press enter. This should give a “>” prompt. Connect a USB Thumb Drive to the host connector. If the prompt does not appear then verify that you programmed the firmware correctly and that you have the correct serial port settings.

Type “HELP” in the prompt for a list of the available commands.

Demos > Host - Mass Storage - Thumb Drive Data Logger > Running the Demo


Host - MCHPUSB - Generic Driver Demo

Contents | Index | Home
Previous | Up | Next
Host - MCHPUSB - Generic Driver Demo

This demo shows how to interface to Vendor class devices. It uses "Device - MCHPUSB - Generic Driver Demo" as the target device.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to... more
Running the Demo
This demo will require two Microchip devices to run. One will act as the USB host and the other will run the USB peripheral.
Program the peripheral with the firmware found in the “USB Device – MCHPUSB – Generic driver demo” folder. Program the host with the firmware found in the “USB Host – MCHPUSB – Generic driver demo” folder.
Power the host. The LCD screen should show the revision number of the MCHPUSB class driver. Plug in the peripheral device. The LCD screen should now update with the potentiometer and temperature data from the attached peripheral.
Demos > Host - MCHPUSB - Generic Driver Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ64GB004 Plug-In-Module (PIM) | 1, 2
PIC24FJ256GB110 Plug-In-Module (PIM) | 2
PIC24FJ256GB210 Plug-In-Module (PIM) | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 2
dsPIC33EP512MU810 Plug-In-Module (PIM) | 2
PIC32 USB Plug-In-Module (PIM) | 2
PIC32 CAN-USB Plug-In-Module (PIM) | 2

Notes:

  1. This configuration requires optimizations in order to fit the memory of the part. Not all versions of the compilers support all optimization levels.
  2. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.

Demos > Host - MCHPUSB - Generic Driver Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to the center pin
    3. Short J2 pin 1 (marked "Temp") to the center pin
    4. Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    1. Short JP1 "U" option to the center pin
    2. Short JP2 "U" option to the center pin
    3. Short JP3 "U" option to the center pin
    4. Short JP4
  • PIC24EP512GU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    1. Open J10
    2. Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

Demos > Host - MCHPUSB - Generic Driver Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo will require two Microchip devices to run. One will act as the USB host and the other will run the USB peripheral.

Program the peripheral with the firmware found in the “USB Device – MCHPUSB – Generic driver demo” folder. Program the host with the firmware found in the “USB Host – MCHPUSB – Generic driver demo” folder.

Power the host. The LCD screen should show the revision number of the MCHPUSB class driver. Plug in the peripheral device. The LCD screen should now update with the potentiometer and temperature data from the attached peripheral.

Demos > Host - MCHPUSB - Generic Driver Demo > Running the Demo


Host - Printer - Print Screen Demo

Contents | Index | Home
Previous | Up | Next
Host - Printer - Print Screen Demo
Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to... more
Running the Demo
The first step required before running this demo is to calibrate the touch screen. Touch screen calibration is done by holding the touch screen down and power cycling the board. This will bring you to the touch screen calibration screen.

Follow the instructions on the screen.

Once the touch screen calibration is complete, plug in a printer into the board and reset the board. If the following screen comes up, then the printer that was plugged in is not supported or there is no printer plugged in. Please plug in a printer and reset the demo.

If the printer is... more
Demos > Host - Printer - Print Screen Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ64GB004 Plug-In-Module (PIM) | 1, 2
PIC24FJ256GB110 Plug-In-Module (PIM) | 2
PIC24FJ256GB210 Plug-In-Module (PIM) | 2
PIC24EP512GU810 Plug-In-Module (PIM) | 2
dsPIC33EP512MU810 Plug-In-Module (PIM) | 2
PIC32 USB Plug-In-Module (PIM) | 2
PIC32 CAN-USB Plug-In-Module (PIM) | 2

Notes:

  1. This configuration requires optimizations in order to fit the memory of the part. Not all versions of the compilers support all optimization levels.
  2. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board, and a Graphics PICTail+ daughter board 3.2" (AC164127-3) in order to operate.

Demos > Host - Printer - Print Screen Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to the center pin
    3. Short J2 pin 1 (marked "Temp") to the center pin
    4. Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    1. Short JP1 "U" option to the center pin
    2. Short JP2 "U" option to the center pin
    3. Short JP3 "U" option to the center pin
    4. Short JP4
  • PIC24EP512GU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    1. Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    2. Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    1. Open J10
    2. Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2

Demos > Host - Printer - Print Screen Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

The first step required before running this demo is to calibrate the touch screen. Touch screen calibration is done by holding the touch screen down and power cycling the board. This will bring you to the touch screen calibration screen.

Follow the instructions on the screen.

Once the touch screen calibration is complete, plug in a printer into the board and reset the board. If the following screen comes up, then the printer that was plugged in is not supported or there is no printer plugged in. Please plug in a printer and reset the demo.

If the printer is successfully loaded then the following screen should come up. You can then draw on the screen and press print. When you press print the attached printer should print exactly what is on the screen and clear the screen.

Demos > Host - Printer - Print Screen Demo > Running the Demo


Host - Printer - Simple Full Sheet

Contents | Index | Home
Previous | Up | Next
Host - Printer - Simple Full Sheet

This demo shows how to create a host that can send a simple print out to a full sheet printer.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to... more
Running the demo
To run this demo, power the target printer. Plug the USB cable from the printer into the demo board. This should cause a sheet to be printed with example images and text. To run the demo again, either reset the board, or remove and reconnect the USB cable to the printer.
Demos > Host - Printer - Simple Full Sheet


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit |
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 2
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Host - Printer - Simple Full Sheet > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Host - Printer - Simple Full Sheet > Configuring the Demo


Running the demo

Contents | Index | Home
Previous | Up | Next
Running the demo

To run this demo, power the target printer. Plug the USB cable from the printer into the demo board. This should cause a sheet to be printed with example images and text. To run the demo again, either reset the board, or remove and reconnect the USB cable to the printer.

Demos > Host - Printer - Simple Full Sheet > Running the demo


Host - Printer - Simple Point of Sale (POS)

Contents | Index | Home
Previous | Up | Next
Host - Printer - Simple Point of Sale (POS)

This demo shows how to create a simple embedded host application that talks to an Epson Point of Sale (POS) printer.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to... more
Running the Demo
To run this demo, power the target printer. Plug the USB cable from the printer into the demo board. This should cause a sheet to be printed with example images and text. To run the demo again, either reset the board, or remove and reconnect the USB cable to the printer.
Demos > Host - Printer - Simple Point of Sale (POS)


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Notes
PIC24FJ64GB004 Plug-In-Module (PIM) | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | 1
PIC24FJ256DA210 Development Board |
PIC24F Starter Kit |
PIC24EP512GU810 Plug-In-Module (PIM) | 1
dsPIC33EP512MU810 Plug-In-Module (PIM) | 1
PIC32 USB Plug-In-Module (PIM) | 1
PIC32 CAN-USB Plug-In-Module (PIM) | 1
PIC32 USB Starter Kit | 2
PIC32 USB Starter Kit II |

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 and a USB PICTail+ Daughter Board in order to operate.
  2. This board is no longer sold. It was replaced by the PIC32 USB Starter Kit II.

Demos > Host - Printer - Simple Point of Sale (POS) > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP2 and JP3 on the USB PICTail+ board
  3. Open JP1 and JP4 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    • Set switch S1 to the "PGX1" setting
    • Short J1 pin 1 (marked "POT") to the center pin
    • Short J2 pin 1 (marked "Temp") to the center pin
    • Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    • Short JP1 "U" option to the center pin
    • Short JP2 "U" option to the center pin
    • Short JP3 "U" option to the center pin
    • Short JP4
  • PIC24EP512GU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • dsPIC33EP512MU810 PIM
    • Short pins 2 and 3 on jumpers J1, J2, J3, J4, and J5
    • Open jumpers J6, J7, J8, J9, and J10
  • PIC32MX795F512L PIM
    • Open J10
    • Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2
PIC24F Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit
  • No hardware related configuration or jumper setting changes are necessary.
PIC32 USB Starter Kit II
  • No hardware related configuration or jumper setting changes are necessary.

Demos > Host - Printer - Simple Point of Sale (POS) > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

To run this demo, power the target printer. Plug the USB cable from the printer into the demo board. This should cause a sheet to be printed with example images and text. To run the demo again, either reset the board, or remove and reconnect the USB cable to the printer.

Demos > Host - Printer - Simple Point of Sale (POS) > Running the Demo


Loading a precompiled demo

Contents | Index | Home
Previous | Up | Next
Loading a precompiled demo

This section describes how to load a pre-compiled demo hex file.

Topics
Name
Description
MPLAB 8
Selecting a target device:
  1. Open MPLAB® IDE
  2. Select Configure->Select Device
  3. Select the target device from the drop down menu

Importing a hex file:
  1. Make sure that the correct device is selected before the hex file is imported (see above for instructions).
  2. Select File->Import
  3. Select the desired hex file
Programming the device:
  1. Once the correct device is selected and a hex file is imported it is ready to be programmed into a device. Select Programmer->Select Programmer->… and select the programmer that you have available and connected to the computer.
  2. After the programmer is enabled connect it to the target device.
  3. Select... more
Demos > Loading a precompiled demo


MPLAB 8

Contents | Index | Home
Previous | Up | Next
MPLAB 8

Selecting a target device:

  1. Open MPLAB® IDE
  2. Select Configure->Select Device
  3. Select the target device from the drop down menu

Importing a hex file:

  1. Make sure that the correct device is selected before the hex file is imported (see above for instructions).
  2. Select File->Import
  3. Select the desired hex file
Programming the device:
  1. Once the correct device is selected and a hex file is imported it is ready to be programmed into a device. Select Programmer->Select Programmer->… and select the programmer that you have available and connected to the computer.
  2. After the programmer is enabled connect it to the target device.
  3. Select Programmer->Program to program the device.

Running the device:

  1. After the device is programmed, some programmers hold the device in reset. The easiest way to get the device running despite what programmer is being used is to disconnect the programmer from the target device.

Demos > Loading a precompiled demo > MPLAB 8


PC - WM_DEVICECHANGE Demo

Contents | Index | Home
Previous | Up | Next
PC - WM_DEVICECHANGE Demo

This demo uses the "Device - HID Simple Custom Demo" as the firmware. Please refer to that demos documentation for the supported boards and setups.

Before you can run the WM_DEVICECHANGE_Demo.exe executable, you will need to have the Microsoft® .NET Framework Version 2.0 Redistributable Package (later versions probably okay, but not tested) installed on your computer. Programs which were built in the Visual Studio® .NET languages require the .NET redistributable package in order to run. The redistributable package can be freely downloaded from Microsoft’s website. Users of Windows Vista® operating systems will not need to install the .NET framework, as it comes pre-installed as part of the operating system.

The source code for the WM_DEVICECHANGE_Demo.exe file was created in Microsoft Visual C++® 2005 Express Edition. The source code can be found in the “<Install Directory>\USB PC - WM_DEVICECHANGE Demo\WM_DEVICECHANGE Demo - PC Software” directory. Microsoft currently distributes Visual C++ 2005 Express Edition for free, and can be downloaded from Microsoft’s website. When downloading Microsoft Visual C++ 2005 Express Edition, also make sure to download and install the Platform SDK, and follow Microsoft’s instructions for integrating it with the development environment.

It is not necessary to install either Microsoft Visual C++ 2005, or the Platform SDK in order to begin using the WM_DEVICECHANGE_Demo.exe file. These are only required if the source code will be modified or compiled.

To run the demo, simply run the executable by double clicking on it. The executable can be found in the “<Install Directory>\USB PC - WM_DEVICECHANGE Demo” directory. If the application launches successfully, a window similar to that shown below should appear:

Demos > PC - WM_DEVICECHANGE Demo


OTG - MCHPUSB Device/MCHPUSB Host Demo

Contents | Index | Home
Previous | Up | Next
OTG - MCHPUSB Device/MCHPUSB Host Demo

This demo shows how to implement an OTG device. Both the device and the host are both MCHPUSB custom class demos. More information about the device portion of the demo and how it would work on other hosts can be found in the Device - MCHPUSB Generic Driver Demo section. More information about the host portion of this demo can be found in the Host - MCHPUSB Generic Driver Demo section.

Topics
Name
Description
Supported Demo Boards
Configuring the Demo
Explorer 16 Based Demos
For all of the Explorer 16-based demo boards, please follow the following instructions
  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP4 on the USB PICTail+ board
  3. Open JP1, JP2, and JP3 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to the... more
Running the Demo
This demo will require two Microchip devices to run. One will act as the USB host and the other will run the USB peripheral.
To demo the full OTG functionality, program 2 sets of boards with the code provided in the “USB OTG – MCHPUSB – Generic driver demo” folder.
Power both boards. For this demo you will need a micro-A to micro-B cable. At the time of this release these cables are rare and still hard to find. When purchasing a cable please insure that the ID pin on both connectors is correct. On the A side of the... more
Demos > OTG - MCHPUSB Device/MCHPUSB Host Demo


Supported Demo Boards

Contents | Index | Home
Previous | Up | Next
Supported Demo Boards
Demo Board (click link for board information) | Part Number (click link for ordering information) | Notes
PIC24FJ64GB004 Plug-In-Module (PIM) | MA240019 | 1
PIC24FJ256GB110 Plug-In-Module (PIM) | MA240014 | 1
PIC24FJ256GB210 Plug-In-Module (PIM) | MA240021 | 1

Notes:

  1. This board can not be used by itself. It requires an Explorer 16 ( [image] DM240001) and a USB PICTail+ Daughter Board ( [image] AC164131) in order to operate.

Demos > OTG - MCHPUSB Device/MCHPUSB Host Demo > Supported Demo Boards


Configuring the Demo

Contents | Index | Home
Previous | Up | Next
Configuring the Demo

Explorer 16 Based Demos

For all of the Explorer 16-based demo boards, please follow the following instructions

  1. Connect the USB PICTail+ Daughter Board to the Explorer 16.
  2. Short JP4 on the USB PICTail+ board
  3. Open JP1, JP2, and JP3 on the USB PICTail+ board
  4. Make sure that S2 on the Explorer 16 is switched to the "PIM" setting.
  5. Short JP2 on the Explorer 16 to enable the LEDs.
  6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated:
  • PIC24FJ64GB004 PIM
    1. Set switch S1 to the "PGX1" setting
    2. Short J1 pin 1 (marked "POT") to the center pin
    3. Short J2 pin 1 (marked "Temp") to the center pin
    4. Short J3 pin 1 (marked "EEPROM CS") to the center pin
  • PIC24FJ256GB210 PIM
    1. Short JP1 "U" option to the center pin
    2. Short JP2 "U" option to the center pin
    3. Short JP3 "U" option to the center pin
    4. Short JP4

Demos > OTG - MCHPUSB Device/MCHPUSB Host Demo > Configuring the Demo


Running the Demo

Contents | Index | Home
Previous | Up | Next
Running the Demo

This demo will require two Microchip devices to run. One will act as the USB host and the other will run the USB peripheral.

To demo the full OTG functionality, program 2 sets of boards with the code provided in the “USB OTG – MCHPUSB – Generic driver demo” folder.

Power both boards. For this demo you will need a micro-A to micro-B cable. At the time of this release these cables are rare and still hard to find. When purchasing a cable please insure that the ID pin on both connectors is correct. On the A side of the cable the ID pin should be less than 10 ohms to ground. On the B-side of the cable the ID pin should be more than 100k ohms to gnd. There are several manufactures that produce micro-A to micro-B cables that are not OTG compliant and these cables have the ID pin connected straight through the cable instead of grounded on one end and floating on the other as the OTG specification calls for.

When the A end of the cable is plugged into either of the boards, that board will become host. When the B end of the cable is connected to either of the boards, that board will become peripheral. On the host board, press the S3 button (seen below). This will cause the host to start supplying 5v to the peripheral. At this point the peripheral should start to operate.

Changing the POT on the peripheral board will cause the LCD on the host to reflect the new value. Similarly the temperature will be affected. Pressing S3 again will cause the host to power down the peripheral. With the power to the peripheral off, press the S3 button on the peripheral. This initiates a Session Request Protocol (SRP). This requests that the host power the bus again. At this point the device should run again without enabling the power from the device.

To switch roles, while both devices are power and the host is communicating to the peripheral, press the S6 button (seen below) on the host (the A device). This initiates a Host Negotiate Protocol (HNP). This causes the A device to become the peripheral and the B device to become the host. The demo is run the same as before except that the POT on the A device is now read on the LCD of the B device. To return to the original configuration, press the S6 button on the B device (now the host). This will suspend the bus and return host control to the A device.

Demos > OTG - MCHPUSB Device/MCHPUSB Host Demo > Running the Demo


Demo Board Information

Contents | Index | Home
Previous | Next
Demo Board Information
Topics
Name
Description
Low Pin Count USB Development Board
PICDEM FS USB Board
PIC18F46J50 Plug-In-Module (PIM)
PIC18F47J53 Plug-In-Module (PIM)
PIC18F87J50 Plug-In-Module (PIM) Demo Board
PIC18 Starter Kit
PIC24FJ64GB004 Plug-In-Module (PIM)
PIC24FJ64GB502 Microstick
PIC24FJ256GB110 Plug-In-Module (PIM)
PIC24FJ256GB210 Plug-In-Module (PIM)
PIC24FJ256DA210 Development Board
PIC24F Starter Kit
PIC24EP512GU810 Plug-In-Module (PIM)
dsPIC33EP512MU810 Plug-In-Module (PIM)
PIC32MX460F512L Plug-In-Module (PIM)
PIC32MX795F512L Plug-In-Module (PIM)
PIC32 USB Starter Kit
PIC32 USB Starter Kit II
USB PICTail Plus Daughter Board
Overview

JP1 - Connects the VBUS pin of the mini-B connector to the VBUS pin of the microcontroller.
JP2 - Connects the VBUS pin of the A connector (and associated circuitry) to the VBUS pin of the microcontroller.
JP3 - Connects the VBUS voltage detection resistor divider circuit to the microcontroller (pin varies depending on the processor module).
JP4 - Connects the VBUS pin of the micro-A/B connector (and associated circuitry) to the VBUS pin of the microcontroller.

This board has 3 USB connectors on it.
  • The mini-B connector is for USB device operation. For use in this mode JP1... more
Explorer 16
Overview:

S1 - Reset button (MCLR)
S2 - Processor switch. This switch determines which processor is running, the processor on the board or the processor on the Plug-In-Module (PIM).
S3, S4, S5, S6 - Application switches. For information about what pin is connected to this switch, please refer to the information for the PIM in use.

D3 through D10 - Application LEDs. For information about what pin is connected to this LED, please refer to the information for the PIM in use.
More Information:
Product webpage
Demo Board Information


Low Pin Count USB Development Board

Contents | Index | Home
Previous | Up | Next
Low Pin Count USB Development Board
Overview

This board features the [image] PIC18F14K50 microcontroller. This controller has 20 pins, 16KB of flash, 768 bytes of RAM and an 8-bit core running up to 12MIPS.

J12 - Shorts the VUSB pin to Vdd rail.

J14 - Selects the power source for the board. Short pins 1 and 2 to power from J9. Short pins 2 and 3 to power from the USB VBUS line.

S1 - Application button. Connected to RA3

D1 - Application LED. Connected to RC0

D2 - Application LED. Connected to RC1

D3 - Application LED. Connected to RC2

D4 - Application LED. Connected to RC3

More Information

Product webpage

PIC18F14K50 webpage

Demo Board Information > Low Pin Count USB Development Board


PICDEM FS USB Board

Contents | Index | Home
Previous | Up | Next
PICDEM FS USB Board
Overview

S1 - MCLR reset button

S2 - Application button

S3 - Application button

D1 - Application LED

D2 - Application LED

D3 - Application LED

D4 - Application LED

D7 - Bus powered indicator - When this LED is illuminated, the board is being powered by the USB bus.

D8 - Self powered indicator - When this LED is illuminated, the board is being powered by an external power supply.

JP11 - connects RB2 of the microcontroller to the temperature sensor on the board (U4). On some revisions of the board there is a trace shorting this jumper that needs to be cut in order to open this jumper.

More Information

Product website

Demo Board Information > PICDEM FS USB Board


PIC18F46J50 Plug-In-Module (PIM)

Contents | Index | Home
Previous | Up | Next
PIC18F46J50 Plug-In-Module (PIM)
Overview

  • JP2 - This is a three-pin header with the labels, "I", "R" and "U". The "R" is an abbreviation referring to microcontroller pin, RC2. "I" is an abbreviation referring to the "ICE" female header pin for the RC2 signal. "U" is an abbreviation for the USB VBUS line. When the jumper is in the "R" to "I" position, the RC2 pin connects only to the ICE female header pin, just like most of the other general purpose I/O pins. When the jumper is in the "R" to "U" position, RC2 (which is 5.5V tolerant) can be used to sense when the USB cable has been attached to the host, and when the host is actively providing power to the +5V VBUS line. According to the USB 2.0 specifications, no device should ever pull the D+ or D- lines high (such as with the D+ or D- pull-up resistor) until the host actively powers the +5V VBUS line. This is intended to prevent self-powered peripherals from ever sourcing even small amounts of power to the host when the host is not powered. Small amounts of current could potentially prevent the host (and possibly other USB peripherals connected to that host) from fully becoming depowered, which may cause problems during power-up and initialization. Self-powered peripherals should periodically monitor the +5V VBUS line and detect when it is driven high. Only when it is powered should user firmware enable the USB module and turn on the D+ (for full speed) or D- (for low speed) pull-up resistor, signaling device attach to the host. The recommended method of monitoring the +5V VBUS line is to connect it to one of the microcontroller.s 5.5V tolerant I/O pins through a large value resistor (such as 100 kOhms). The resistor serves to improve the ESD ruggedness of the circuit as well as to prevent microcontroller damage if user firmware should ever unintentionally configure the I/O pin as an output. Peripherals which are purely bus powered obtain all of their power directly from the +5V VBUS line itself. For these types of devices, it is unnecessary to monitor when the VBUS is powered, as the peripheral will not be able to source current on the D+, D- or VBUS lines when the host is not powered.
  • JP3 - This jumper is located in series with the +5V VBUS power supply line from the USB connector. When the jumper is removed, a current meter may be placed between the header pins to measure the board current which is being drawn from the USB port. Additionally, by removing the jumper cap altogether, JP3 provides a means of preventing the board from consuming USB power.
  • S2 - Switch for application use. Tied to RB2.
  • S4 - MCLR reset switch
  • D1 - LED for application use. Tied to RE0.
  • D2 - LED for application use. Tied to RE1.

More Information

Product webpage

Demo Board Information > PIC18F46J50 Plug-In-Module (PIM)


PIC18F47J53 Plug-In-Module (PIM)

Contents | Index | Home
Previous | Up | Next
PIC18F47J53 Plug-In-Module (PIM)
Overview

  • JP2 - This is a three-pin header with the labels, "I", "R" and "U". The "R" is an abbreviation referring to microcontroller pin, RC2. "I" is an abbreviation referring to the "ICE" female header pin for the RC2 signal. "U" is an abbreviation for the USB VBUS line. When the jumper is in the "R" to "I" position, the RC2 pin connects only to the ICE female header pin, just like most of the other general purpose I/O pins. When the jumper is in the "R" to "U" position, RC2 (which is 5.5V tolerant) can be used to sense when the USB cable has been attached to the host, and when the host is actively providing power to the +5V VBUS line. According to the USB 2.0 specifications, no device should ever pull the D+ or D- lines high (such as with the D+ or D- pull-up resistor) until the host actively powers the +5V VBUS line. This is intended to prevent self-powered peripherals from ever sourcing even small amounts of power to the host when the host is not powered. Small amounts of current could potentially prevent the host (and possibly other USB peripherals connected to that host) from fully becoming depowered, which may cause problems during power-up and initialization. Self-powered peripherals should periodically monitor the +5V VBUS line and detect when it is driven high. Only when it is powered should user firmware enable the USB module and turn on the D+ (for full speed) or D- (for low speed) pull-up resistor, signaling device attach to the host. The recommended method of monitoring the +5V VBUS line is to connect it to one of the microcontroller.s 5.5V tolerant I/O pins through a large value resistor (such as 100 kOhms). The resistor serves to improve the ESD ruggedness of the circuit as well as to prevent microcontroller damage if user firmware should ever unintentionally configure the I/O pin as an output. Peripherals which are purely bus powered obtain all of their power directly from the +5V VBUS line itself. For these types of devices, it is unnecessary to monitor when the VBUS is powered, as the peripheral will not be able to source current on the D+, D- or VBUS lines when the host is not powered.
  • JP3 - This jumper is located in series with the +5V VBUS power supply line from the USB connector. When the jumper is removed, a current meter may be placed between the header pins to measure the board current which is being drawn from the USB port. Additionally, by removing the jumper cap altogether, JP3 provides a means of preventing the board from consuming USB power.
  • S2 - Switch for application use. Tied to RB2.
  • S4 - MCLR reset switch
  • D1 - LED for application use. Tied to RE0.
  • D2 - LED for application use. Tied to RE1.

More Information

Product website

Demo Board Information > PIC18F47J53 Plug-In-Module (PIM)


PIC18F87J50 Plug-In-Module (PIM) Demo Board

Contents | Index | Home
Previous | Up | Next
PIC18F87J50 Plug-In-Module (PIM) Demo Board
Overview

  • JP1 - This is a three-pin header with the labels, "I", "R" and "U". The "R" is an abbreviation referring to microcontroller pin, RB5. "I" is an abbreviation referring to the "ICE" female header pin for the RB5 signal. "U" is an abbreviation for the USB VBUS line. When the jumper is in the "R" to "I" position, the RB5 pin connects only to the ICE female header pin, just like most of the other general purpose I/O pins. When the jumper is in the "R" to "U" position, RB5 (which is 5.5V tolerant) can be used to sense when the USB cable has been attached to the host, and when the host is actively providing power to the +5V VBUS line. According to the USB 2.0 specifications, no device should ever pull the D+ or D- lines high (such as with the D+ or D- pull-up resistor) until the host actively powers the +5V VBUS line. This is intended to prevent self-powered peripherals from ever sourcing even small amounts of power to the host when the host is not powered. Small amounts of current could potentially prevent the host (and possibly other USB peripherals connected to that host) from fully becoming depowered, which may cause problems during power-up and initialization. Self-powered peripherals should periodically monitor the +5V VBUS line and detect when it is driven high. Only when it is powered should user firmware enable the USB module and turn on the D+ (for full speed) or D- (for low speed) pull-up resistor, signaling device attach to the host. The recommended method of monitoring the +5V VBUS line is to connect it to one of the microcontroller.s 5.5V tolerant I/O pins through a large value resistor (such as 100 kOhms). The resistor serves to improve the ESD ruggedness of the circuit as well as to prevent microcontroller damage if user firmware should ever unintentionally configure the I/O pin as an output. Peripherals which are purely bus powered obtain all of their power directly from the +5V VBUS line itself. For these types of devices, it is unnecessary to monitor when the VBUS is powered, as the peripheral will not be able to source current on the D+, D- or VBUS lines when the host is not powered.
  • JP4 - This jumper is located in series with the +5V VBUS power supply line from the USB connector. When the jumper is removed, a current meter may be placed between the header pins to measure the board current which is being drawn from the USB port. Additionally, by removing the jumper cap altogether, JP4 provides a means of preventing the board from consuming USB power.
  • JP5 - This jumper provides a means of removing the LED pin loading on the RE0 and RE1 pins.
  • S4 - Switch for application use. Tied to RB4.
  • D3 - LED for application use. Tied to RE0.
  • D4 - LED for application use. Tied to RE1.

More Information

  • Product webpage

Demo Board Information > PIC18F87J50 Plug-In-Module (PIM) Demo Board


PIC18 Starter Kit

Contents | Index | Home
Previous | Up | Next
PIC18 Starter Kit
Overview

S1 - Application switch. Connected to RB0.

More Information

Product Website

Introduction Video

Demo Board Information > PIC18 Starter Kit


PIC24FJ64GB004 Plug-In-Module (PIM)

Contents | Index | Home
Previous | Up | Next
PIC24FJ64GB004 Plug-In-Module (PIM)
Overview

S1 - Select which programming pins are going to be used on the microcontroller. The "PGX1" setting must be used for USB operation.

J1 - A/D setting for RC1 (center tap). Setting the jumper to "POT" connects the pin to the potentiometer on the Explorer 16. Setting the jumper to "PT+" connects the pin to the PICTail+ connector on the Explorer 16.

J2 - A/D setting for RC0 (center tap). Setting the jumper to "Temp" connects the pin to the temperature sensor on the Explorer 16. Setting the jumper to "PT+" connects the pin to the PICTail+ connector on the Explorer 16.

J3 - I/O selection for RA8 (center tap). Setting the jumper to "EEPROM CS" connects the pin to the chip select line of the EEPROM on the Explorer 16. Setting the jumper to "PT+" connects the pin to the PICTail+ connector on the Explorer 16.

More Information

Plug-In-Module (PIM) Information Sheet

Demo Board Information > PIC24FJ64GB004 Plug-In-Module (PIM)


PIC24FJ64GB502 Microstick

Contents | Index | Home
Previous | Up | Next
PIC24FJ64GB502 Microstick
Overview

S1 - Application switch. Tied to RB7.

D1 - Application LED. Tied to RB9.

D2 - Application LED. Tied to RB8.

This board has 3 USB connectors on it.

  • The mini-B connector is for the PICkit on-board debugger. It is located on the top of the board.
  • The mini-B connector is for USB device operation on the target microcontroller. It is located on the bottom side of the board.
  • The A connector is for USB host support on the target microcontroller.

More Information

Product webpage

Demo Board Information > PIC24FJ64GB502 Microstick


PIC24FJ256GB110 Plug-In-Module (PIM)

Contents | Index | Home
Previous | Up | Next
PIC24FJ256GB110 Plug-In-Module (PIM)
Overview

The PIC24FJ256GB110 Plug-In-Module (PIM) is not a standalone board. It requires the use of the Explorer 16 ( [image] DM240001). For USB applications the USB PICTail plus daughter board ( [image] AC164131) is also required.

More Information

Information sheet

Demo Board Information > PIC24FJ256GB110 Plug-In-Module (PIM)


PIC24FJ256GB210 Plug-In-Module (PIM)

Contents | Index | Home
Previous | Up | Next
PIC24FJ256GB210 Plug-In-Module (PIM)
Overview

The PIC24FJ256GB110 Plug-In-Module (PIM) is not a standalone board. It requires the use of the Explorer 16 ( [image] DM240001). For USB applications the USB PICTail plus daughter board ( [image] AC164131) is also required.

For USB operation, jumpers JP1, JP2, and JP3 should be shorted from pins 1 to 2.

More Information

Information sheet

Demo Board Information > PIC24FJ256GB210 Plug-In-Module (PIM)


PIC24FJ256DA210 Development Board

Contents | Index | Home
Previous | Up | Next
PIC24FJ256DA210 Development Board
Overview

S1 - Application switch. Tied to RG8 when JP13 is shorted from S1 to RG8 settings.

S2 - Application switch. Tied to RE9 when JP14 is shorted from S1 to RE9 settings.

S3 - Application switch. Tied to RB5 when JP15 is shorted from S1 to RB5 settings.

S4 - MCLR reset button. Resets the microcontroller on the board.

D1 - Application LED. Connected to RG8 when JP13 is shorted from PAD1 to RG8.

D2 - Application LED. Connected to RE9 when JP14 is shorted from PAD2 to RE9.

D3 - Application LED. Connected to RB5 when JP15 is shorted from PAD3 to RB5.

D4 - Application LED. Connected to RA7 when JP11 is shorted from 1 to 2.

JP5 - Connect USB OTG port to VBUS.

JP6 - Connect USB Host port to VBUS.

JP7 - Connect USB Device port to VBUS.

JP11 - Functionality selection for RA7.

JP13 - Functionality selection for RG8.

JP14 - Functionality selection for RE9.

JP15 - Functionality selection for RB5.

More Information

Product Webpage

Demo Board Information > PIC24FJ256DA210 Development Board


PIC24F Starter Kit

Contents | Index | Home
Previous | Up | Next
PIC24F Starter Kit
Overview

D8 - For dual role examples on the PIC24F starter kit, D8 needs to be removed. D8 allows the firmware to verify that the 5v has been delivered to the application USB host port. This, however, is also tied to the application USB device port. With the diode in place the controller can not determine if the 5v it sees is from the USB host port being powered or from the USB device port on an attachment to a USB host.

More Information

Product Website

Introduction Video

Demo Board Information > PIC24F Starter Kit


PIC24EP512GU810 Plug-In-Module (PIM)

Contents | Index | Home
Previous | Up | Next
PIC24EP512GU810 Plug-In-Module (PIM)
More Information

Information Sheet

Demo Board Information > PIC24EP512GU810 Plug-In-Module (PIM)


dsPIC33EP512MU810 Plug-In-Module (PIM)

Contents | Index | Home
Previous | Up | Next
dsPIC33EP512MU810 Plug-In-Module (PIM)
More Information

Information Sheet

Demo Board Information > dsPIC33EP512MU810 Plug-In-Module (PIM)


PIC32MX460F512L Plug-In-Module (PIM)

Contents | Index | Home
Previous | Up | Next
PIC32MX460F512L Plug-In-Module (PIM)
More Information

Schematic

Demo Board Information > PIC32MX460F512L Plug-In-Module (PIM)


PIC32MX795F512L Plug-In-Module (PIM)

Contents | Index | Home
Previous | Up | Next
PIC32MX795F512L Plug-In-Module (PIM)
More Information

Information Sheet

Demo Board Information > PIC32MX795F512L Plug-In-Module (PIM)


PIC32 USB Starter Kit

Contents | Index | Home
Previous | Up | Next
PIC32 USB Starter Kit
Overview

SW1 - Application switch. Tied to RD6.

SW2 - Application switch. Tied to RD7.

SW3 - Application switch. Tied to RD13.

LED1 - Application LED. Tied to RD0.

LED2 - Application LED. Tied to RD1.

LED3 - Application LED. Tied to RD2.

This board has 3 USB connectors on it.

  • The mini-B connector is for on-board debugger. It is located on the top of the board.
  • The micro-A/B connector is for USB OTG operation on the target microcontroller. It is located on the bottom side of the board.
  • The A connector is for USB host support on the target microcontroller.

More Information

The PIC32 USB Starter Kit is no longer sold. It has been replaced by the PIC32 USB Starter Kit II.

Demo Board Information > PIC32 USB Starter Kit


PIC32 USB Starter Kit II

Contents | Index | Home
Previous | Up | Next
PIC32 USB Starter Kit II
Overview

SW1 - Application switch. Tied to RD6.

SW2 - Application switch. Tied to RD7.

SW3 - Application switch. Tied to RD13.

LED1 - Application LED. Tied to RD0.

LED2 - Application LED. Tied to RD1.

LED3 - Application LED. Tied to RD2.

This board has 3 USB connectors on it.

  • The mini-B connector is for on-board debugger. It is located on the top of the board.
  • The micro-A/B connector is for USB OTG operation on the target microcontroller. It is located on the bottom side of the board.
  • The A connector is for USB host support on the target microcontroller.

More Information

Product webpage

Demo Board Information > PIC32 USB Starter Kit II


USB PICTail Plus Daughter Board

Contents | Index | Home
Previous | Up | Next
USB PICTail Plus Daughter Board

Overview

JP1 - Connects the VBUS pin of the mini-B connector to the VBUS pin of the microcontroller.

JP2 - Connects the VBUS pin of the A connector (and associated circuitry) to the VBUS pin of the microcontroller.

JP3 - Connects the VBUS voltage detection resistor divider circuit to the microcontroller (pin varies depending on the processor module).

JP4 - Connects the VBUS pin of the micro-A/B connector (and associated circuitry) to the VBUS pin of the microcontroller.

This board has 3 USB connectors on it.

  • The mini-B connector is for USB device operation. For use in this mode JP1 should be shorted and JP2, JP3, and JP4 should be open.
  • The A connector is for USB host support. JP2 should be short for this mode. JP3 can be shorted to enable VBUS voltage sensing. Some demos may require this feature. JP1 and JP4 should be open.
  • The micro-A/B connector is for USB OTG operation. JP4 should be short and JP1, JP2, and JP3 should be open.
More Information

Product website

Ordering information

Demo Board Information > USB PICTail Plus Daughter Board


Explorer 16

Contents | Index | Home
Previous | Up | Next
Explorer 16

Overview:

S1 - Reset button (MCLR)

S2 - Processor switch. This switch determines which processor is running, the processor on the board or the processor on the Plug-In-Module (PIM).

S3, S4, S5, S6 - Application switches. For information about what pin is connected to this switch, please refer to the information for the PIM in use.

D3 through D10 - Application LEDs. For information about what pin is connected to this LED, please refer to the information for the PIM in use.

More Information:

Product webpage

Demo Board Information > Explorer 16


PC Tools and Example Code

Contents | Index | Home
Previous | Next
PC Tools and Example Code

Microchip General Purpose (Custom/Vendor Class) USB Driver

See: <Install Directory>\USB Tools\MCHP Custom Driver\MCHPUSB Driver\Release

Microchip provides a general purpose Windows driver which can be used by Windows applications to interface with a custom class USB device. This driver will not be necessary in many USB applications, such as USB HID class devices, which would normally use built in HID class drivers which distribute with the OS.

For USB applications that do not readily fit within the constraints of these other device class options, Microchip’s general purpose driver may be used. Windows applications can access USB devices either by directly interfacing with the driver (mchpusb.sys), or they may indirectly use the driver through a pre-compiled library.

The custom class firmware examples are intended to be used with the general purpose USB driver.

After installation, the release notes for the general purpose USB driver are located at: <Install Directory>\Microchip\USB\Utilities\MCHP Custom Driver\MCHPUSB Driver\MCHPUSB Driver Release Notes.htm

MPUSBAPI Library and DLL Source

See: <Install Directory>\USB Tools\MCHPUSB Custom Driver\Mpusbapi

A custom class Windows application using the Microchip General Purpose USB driver may interface directly with the driver (mchpusb.sys). Doing so directly requires more effort and more time to learn than using a pre-compiled library that exposes a simple to use API including basic functions like open(), read(), write(), and close().

The MPUSBAPI.DLL file is a library which provides a number of functions including the basic ones needed for reading and writing to a USB device. A list of the functions available, and the calling conventions for those functions is currently documented in the form of inline comments in the source code for the DLL file. The DLL is compiled using Borland® C++ Builder™ 6 development environment, and the source code is provided in the “<install directory>\Microchip\USB\Utilities\MCHPUSB Custom Driver\Mpusbapi\Dll\Borland_C\Source” directory.

A load time linking and a run time linking example showing how to use the DLL are included in “<install directory>\Microchip\USB\Utilities\MCHPUSB Custom Driver\Mpusbapi\Example Applications\Borland_C” directory.

PICDEM FS USB Demo Tool “Pdfsusb”

See: <Install Directory>\USB Tools\Pdfsusb

This computer program demonstrates basic USB communication using the Microchip Custom class driver with a Windows GUI based application. The USB Device – MCHPUSB – Generic Driver Demo Firmware is intended to be used in conjunction with the “PICDEM FS USB Demo Tool” which can be launched by executing the PDFSUSB.exe file. The features and use of this application are described in the PICDEM FS USB Demonstration Board User’s Guide (DS51526).

This application was originally intended to be used with the PICDEM FS USB Demo Board, but it can be used with the other available USB platforms as well. The demo tool makes use of hardware features, such as a temperature sensor and potentiometer which are not found on all of the hardware platforms. In order to use the demo tool with the PIC18F87J50 PIM, the PIM should be used while it is plugged into the HPC Explorer board. The HPC Explorer board has the needed potentiometer, temperature sensor, and additional LEDs.

In order to use the PICDEM FS USB Demo Tool with any of the hardware platforms, the board will need to be programmed with the code generated by the Custom class device example project or from the custom class precompiled examples.

USBConfig.exe Tool

See: <Install Directory>\USB Tools\USBConfig Tool

Each of the firmware projects requires a usb_config.h that defines several macros that the USB stack uses to know how it should perform. In the case of the embedded host applications there is also a .c file that needs to be create that describes the Targeted Peripheral List (TPL). The TPL is a list of supported devices. This .c file also contains various information that the stack needs to know in order to load and execute the correct client drivers for these devices.

The USBConfig.exe tool is a simple to use interface to help generate the files required by the USB stack.

At the moment the USBConfig.exe tool is only functional for the embedded host examples.

Driver Management Tool

See: <Install Directory>\USB PC - Driver Management Tool

This tool provides an example of how to install a USB driver from within a PC application. This is useful for operating systems like Windows Vista or Windows 7 where the operating system doesn't always ask the user for the driver files if they are not pre-installed.

PC Tools and Example Code


Application Programming Interface (API)

Contents | Index | Home
Previous | Next
Application Programming Interface (API)
Topics
Name | Description
Stack Configuration | This section describes how the stack is configured and how it ties to various external hardware features that are required.
Device/Peripheral |
Embedded Host API | These are the various client drivers that are available for use with the USB Embedded Host driver.
On-The-Go (OTG) | This module provides support for USB OTG (On-The-Go) functionality.
Application Programming Interface (API)


Stack Configuration

Contents | Index | Home
Previous | Up | Next
Stack Configuration

The USB device stack configuration is done mostly through three files:

  1. usb_config.h
  2. usb_config.c
  3. HardwareProfile.h
The usb_config.h and usb_config.c files configure the stack options and features through macros and tables.

HardwareProfile.h links the stack to hardware specific features and requirements.

The various class drivers, client drivers, and main stacks (device/peripheral, host, and OTG) have various requirements for each of these files. Each section in this document describes what is required in the configuration files in order to use these code blocks. Please refer to configuration section of each module for more details.

Application Programming Interface (API) > Stack Configuration


Device/Peripheral

Contents | Index | Home
Previous | Up | Next
Device/Peripheral
Topics
Name | Description
Device Stack |
Audio Function Driver |
CCID (Smart/Sim Card) Function Driver |
CDC Function Driver |
HID Function Driver |
MSD Function Driver |
Personal Healthcare Device Class (PHDC) Function Driver |
Vendor Class (Generic) Function Driver |
Application Programming Interface (API) > Device/Peripheral


Device Stack

Contents | Index | Home
Previous | Up | Next
Device Stack
Topics
Name | Description
Configuration Options |
Interface Routines |
Data Types and Constants |
Macros |
Application Programming Interface (API) > Device/Peripheral > Device Stack


Configuration Options

Contents | Index | Home
Previous | Up | Next
Configuration Options
Topics
Name | Description
usb_config.h |
Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options


usb_config.h

Contents | Index | Home
Previous | Up | Next
usb_config.h
Topics
Name
Description
Ping Pong buffering (USB_PING_PONG_MODE)
Ping Pong buffering is a mechanism that allows the stack and users to operate and prepare a buffer and the USB module to receive/transmit data out of a second buffer. This allows maximum data throughput at the expense of additional RAM usage.
There are 4 ping-pong buffering options available in the stack:
  • No ping-pong
  • Full ping-pong
  • Endpoint 0 OUT only ping-pong
  • All but Endpoint 0 ping-pong
Endpoint 0 size (USB_EP0_BUFF_SIZE)
Each USB device must communicate over endpoint 0 in order to enumerate. This is done mostly through the USB stack and not through the function drivers or through the user interface. Thus the stack takes ownership of endpoint 0. The USB specification allows endpoint 0 to be one of 4 sizes: 8, 16, 32, or 64. The MCHPFSUSB stack allows users to modify the endpoint 0 buffer size through a configuration option. The definition used is the USB_EP0_BUFF_SIZE macro and it can be set to either 8, 16, 32, or 64. For example:
#define USB_EP0_BUFF_SIZE 8
Changing the endpoint 0... more
Endpoints Used (USB_MAX_EP_NUMBER)
In order to conserve RAM usage in the stack, variables used to track the status of each of the endpoints is only allocated when required. The stack does this through the USB_MAX_EP_NUMBER definition. The optimization technique used removes the variables for all endpoints above the maximum endpoint number used. For example, if only endpoint 1 is used:
#define USB_MAX_EP_NUMBER 1
This definition prevents the RAM to be allocated for endpoints 2-15. Note that this technique means that if endpoint 15 needs to be used for compatibility reasons USB_MAX_EP_NUMBER must be defined to be 15 and the RAM for all of... more
Interface mode (USB_POLLING or USB_INTERRUPT)
The USB device stack can operate in one of two modes, polling or interrupt. There are two definitions that are use to select between the two modes.
#define USB_POLLING
#define USB_INTERRUPT
Speed selection (USB_SPEED_OPTION)
The MCHPFSUSB stack is capable of both full-speed and low-speed operation. The speed of operation is selected via the USB_SPEED_OPTION macro. The valid settings are:
  • USB_FULL_SPEED
  • USB_LOW_SPEED
For example
#define USB_SPEED_OPTION USB_FULL_SPEED
D+/D- Internal Pull-ups (USB_PULLUP_OPTION)
Many Microchip USB controllers have the option of using an internal D+/D- pull up for their attach signaling. In some usage cases users may rather have this as an external resistor instead of using the internal one. The USB_PULLUP_OPTION macro can be used to enable or disable the internal pull-ups. The options available are:
  • USB_PULLUP_ENABLE
  • USB_PULLUP_DISABLED
For example:
#define USB_PULLUP_OPTION USB_PULLUP_ENABLE
Device Mode Enable (USB_SUPPORT_DEVICE)
To enable the USB device mode, the USB_SUPPORT_DEVICE macro must be defined. This macro tells the USB stack that it will be running in device mode. Example:
#define USB_SUPPORT_DEVICE
Transceiver Option (USB_TRANSCEIVER_OPTION)
Some of the Microchip USB products have the option of using an external USB transceiver instead of the internal transceiver. The selection between the two options is done via the USB_TRANSCEIVER_OPTION configuration macro. This macro should be set to one of two options:
  • USB_INTERNAL_TRANSCEIVER
  • USB_EXTERNAL_TRANSCEIVER
For example:
#define USB_TRANSCEIVER_OPTION USB_INTERNAL_TRANSCEIVER
Number of Interfaces (USB_MAX_NUM_INT)
The USB stack needs to track the interfaces and alternate interfaces being used. In order to do this the stack must allocate space to trace each interface. In order to conserve RAM the stack only allocates space for the number of interfaces being used. The user must configure the stack to tell it how many interfaces are being used. This is done with the USB_MAX_NUM_INT macro in the usb_config.h file. This macro should be set to the highest totol number of interfaces used in a single configuration. For example, if an application has two configurations, one has one interface and... more
Status Stage Timout Enable (USB_ENABLE_STATUS_STAGE_TIMEOUTS and USB_STATUS_STAGE_TIMEOUT)
Option to enable auto-arming of the status stage of control transfers, if no "progress" has been made for the USB_STATUS_STAGE_TIMEOUT value. If progress is made (any successful transactions completing on EP0 IN or OUT) the timeout counter gets reset to the USB_STATUS_STAGE_TIMEOUT value.
During normal control transfer processing, the USB stack or the application firmware will call USBCtrlEPAllowStatusStage() as soon as the firmware is finished processing the control transfer. Therefore, the status stage completes as quickly as is physically possible. The USB_ENABLE_STATUS_STAGE_TIMEOUTS feature, and the USB_STATUS_STAGE_TIMEOUT value are only relevant, when:
1. The application uses the USBDeferStatusStage() API... more
String Descriptor Array size (USB_NUM_STRING_DESCRIPTORS)
The USB stack needs to know how many string descriptors that there are on a device so that if a host requests a string descriptor index that is higher than what is supported, the stack can respond correctly to that event. This is done with the USB_NUM_STRING_DESCRIPTORS definition.
Example:
#define USB_NUM_STRING_DESCRIPTORS 3
Event Notifications
The USB stack passes events that the user might want to handle to the USER_USB_CALLBACK_EVENT_HANDLER() function. Some applications may not want to handle certain types of events. The stack provides a mechanism to disable certain events. Disabling an event in most cases will only stop the event handler from being called. This will slightly reduce the code size and slightly increase the code performance, but in most cases it will not stop the interrupt generation from occurring in the first place (if USB_INTERRUPT mode is being used).
The valid options are:
  • USB_DISABLE_SUSPEND_HANDLER
  • USB_DISABLE_WAKEUP_FROM_SUSPEND_HANDLER
  • USB_DISABLE_SOF_HANDLER
  • USB_DISABLE_TRANSFER_TERMINATED_HANDLER
  • USB_DISABLE_ERROR_HANDLER
  • USB_DISABLE_NONSTANDARD_EP0_REQUEST_HANDLER
  • USB_DISABLE_SET_DESCRIPTOR_HANDLER
  • USB_DISABLE_SET_CONFIGURATION_HANDLER... more
Disable DTS checking (USB_DEVICE_DISABLE_DTS_CHECKING)
Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options > usb_config.h


Ping Pong buffering (USB_PING_PONG_MODE)

Contents | Index | Home
Previous | Up | Next
Ping Pong buffering (USB_PING_PONG_MODE)

Ping Pong buffering is a mechanism that allows the stack and users to operate and prepare a buffer and the USB module to receive/transmit data out of a second buffer. This allows maximum data throughput at the expense of additional RAM usage.

There are 4 ping-pong buffering options available in the stack:

  • No ping-pong
  • Full ping-pong
  • Endpoint 0 OUT only ping-pong
  • All but Endpoint 0 ping-pong

Note: Not all ping-pong modes are available in every device. Please check the datasheet for the device you are using to know what options, if any, are available.

The ping-pong option is determined by defining the USB_PING_PONG_MODE macro to the desired ping-pong mode. The options are:

  • USB_PING_PONG__NO_PING_PONG
  • USB_PING_PONG__FULL_PING_PONG
  • USB_PING_PONG__EP0_OUT_ONLY
  • USB_PING_PONG__ALL_BUT_EP0
For example, to use full ping-pong buffering, define the following in the usb_config.h file:

#define USB_PING_PONG_MODE USB_PING_PONG__FULL_PING_PONG

Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options > usb_config.h > Ping Pong buffering (USB_PING_PONG_MODE)


Endpoint 0 size (USB_EP0_BUFF_SIZE)

Contents | Index | Home
Previous | Up | Next
Endpoint 0 size (USB_EP0_BUFF_SIZE)

Each USB device must communicate over endpoint 0 in order to enumerate. This is done mostly through the USB stack and not through the function drivers or through the user interface. Thus the stack takes ownership of endpoint 0. The USB specification allows endpoint 0 to be one of 4 sizes: 8, 16, 32, or 64. The MCHPFSUSB stack allows users to modify the endpoint 0 buffer size through a configuration option. The definition used is the USB_EP0_BUFF_SIZE macro and it can be set to either 8, 16, 32, or 64. For example:

#define USB_EP0_BUFF_SIZE 8

Changing the endpoint 0 buffer size will have a small impact on the RAM footprint of the overall USB stack, but can be useful on small devices to conserve limited RAM space. Increasing the endpoint zero size can slightly decrease the time required for enumeration and other EP0 communications.

Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options > usb_config.h > Endpoint 0 size (USB_EP0_BUFF_SIZE)


Endpoints Used (USB_MAX_EP_NUMBER)

Contents | Index | Home
Previous | Up | Next
Endpoints Used (USB_MAX_EP_NUMBER)

In order to conserve RAM usage in the stack, variables used to track the status of each of the endpoints is only allocated when required. The stack does this through the USB_MAX_EP_NUMBER definition. The optimization technique used removes the variables for all endpoints above the maximum endpoint number used. For example, if only endpoint 1 is used:

#define USB_MAX_EP_NUMBER 1

This definition prevents the RAM to be allocated for endpoints 2-15. Note that this technique means that if endpoint 15 needs to be used for compatibility reasons USB_MAX_EP_NUMBER must be defined to be 15 and the RAM for all of the endpoints is allocated even though they may not be used. When designing systems that have flexibility in endpoint number selection, selecting lower number endpoints can reduce RAM usage.

The valid value range for this definition is 1-15.

Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options > usb_config.h > Endpoints Used (USB_MAX_EP_NUMBER)


Interface mode (USB_POLLING or USB_INTERRUPT)

Contents | Index | Home
Previous | Up | Next
Interface mode (USB_POLLING or USB_INTERRUPT)

The USB device stack can operate in one of two modes, polling or interrupt. There are two definitions that are use to select between the two modes.

#define USB_POLLING

#define USB_INTERRUPT

Note: Only one of these two modes should be defined at a given point of time.

If USB_POLLING is defined, then the stack is in polling mode and only operates when called. The USBDeviceTasks() function must be called periodically in order to keep the stack running and for data to be transfers. The event notification routine (USB_APPLICATION_EVENT_HANDLER) is called from the USBDeviceTasks() function, so these notifications are only as timely as the calls to the USBDeviceTasks().

In interrupt mode, the USBDeviceTasks() function should be placed in the interrupt handler for PIC18 devices. For PIC24 and PIC32 devices the USBDeviceTasks() function is automatically defined as the USB interrupt function so there is no need to call this function in interrupt mode. In interrupt mode all events from the USB_APPLICATION_EVENT_HANDLER function are in interrupt context. As such care should be taken not to perform tasks in the handler that have any significant duration. In interrupt mode the USB stack will take up as much CPU time as it requires that is allowed via the interrupt priority scheme/settings for the target controller.

Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options > usb_config.h > Interface mode (USB_POLLING or USB_INTERRUPT)


Speed selection (USB_SPEED_OPTION)

Contents | Index | Home
Previous | Up | Next
Speed selection (USB_SPEED_OPTION)

The MCHPFSUSB stack is capable of both full-speed and low-speed operation. The speed of operation is selected via the USB_SPEED_OPTION macro. The valid settings are:

  • USB_FULL_SPEED
  • USB_LOW_SPEED
For example

#define USB_SPEED_OPTION USB_FULL_SPEED

Note: Not every speed mode is available on every device. Please refer to the specific device datasheet for the capabilities of the target controller.
Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options > usb_config.h > Speed selection (USB_SPEED_OPTION)


D+/D- Internal Pull-ups (USB_PULLUP_OPTION)

Contents | Index | Home
Previous | Up | Next
D+/D- Internal Pull-ups (USB_PULLUP_OPTION)

Many Microchip USB controllers have the option of using an internal D+/D- pull up for their attach signaling. In some usage cases users may rather have this as an external resistor instead of using the internal one. The USB_PULLUP_OPTION macro can be used to enable or disable the internal pull-ups. The options available are:

  • USB_PULLUP_ENABLE
  • USB_PULLUP_DISABLED
For example:

#define USB_PULLUP_OPTION USB_PULLUP_ENABLE

Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options > usb_config.h > D+/D- Internal Pull-ups (USB_PULLUP_OPTION)


Device Mode Enable (USB_SUPPORT_DEVICE)

Contents | Index | Home
Previous | Up | Next
Device Mode Enable (USB_SUPPORT_DEVICE)

To enable the USB device mode, the USB_SUPPORT_DEVICE macro must be defined. This macro tells the USB stack that it will be running in device mode. Example:

#define USB_SUPPORT_DEVICE

Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options > usb_config.h > Device Mode Enable (USB_SUPPORT_DEVICE)


Transceiver Option (USB_TRANSCEIVER_OPTION)

Contents | Index | Home
Previous | Up | Next
Transceiver Option (USB_TRANSCEIVER_OPTION)

Some of the Microchip USB products have the option of using an external USB transceiver instead of the internal transceiver. The selection between the two options is done via the USB_TRANSCEIVER_OPTION configuration macro. This macro should be set to one of two options:

  • USB_INTERNAL_TRANSCEIVER
  • USB_EXTERNAL_TRANSCEIVER
For example:

#define USB_TRANSCEIVER_OPTION USB_INTERNAL_TRANSCEIVER

Note: External Transceiver support is not available on all product families. Please refer to the product family datasheet for more information if this feature is available on the target processor.
Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options > usb_config.h > Transceiver Option (USB_TRANSCEIVER_OPTION)


Number of Interfaces (USB_MAX_NUM_INT)

Contents | Index | Home
Previous | Up | Next
Number of Interfaces (USB_MAX_NUM_INT)

The USB stack needs to track the interfaces and alternate interfaces being used. In order to do this the stack must allocate space to trace each interface. In order to conserve RAM the stack only allocates space for the number of interfaces being used. The user must configure the stack to tell it how many interfaces are being used. This is done with the USB_MAX_NUM_INT macro in the usb_config.h file. This macro should be set to the highest totol number of interfaces used in a single configuration. For example, if an application has two configurations, one has one interface and the second has 3 interfaces, this value should be set to 3.

Example usage:

#define USB_MAX_NUM_INT 1

Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options > usb_config.h > Number of Interfaces (USB_MAX_NUM_INT)


Status Stage Timout Enable (USB_ENABLE_STATUS_STAGE_TIMEOUTS and USB_STATUS_STAGE_TIMEOUT)

Contents | Index | Home
Previous | Up | Next
Status Stage Timout Enable (USB_ENABLE_STATUS_STAGE_TIMEOUTS and USB_STATUS_STAGE_TIMEOUT)

Option to enable auto-arming of the status stage of control transfers, if no "progress" has been made for the USB_STATUS_STAGE_TIMEOUT value. If progress is made (any successful transactions completing on EP0 IN or OUT) the timeout counter gets reset to the USB_STATUS_STAGE_TIMEOUT value.

During normal control transfer processing, the USB stack or the application firmware will call USBCtrlEPAllowStatusStage() as soon as the firmware is finished processing the control transfer. Therefore, the status stage completes as quickly as is physically possible. The USB_ENABLE_STATUS_STAGE_TIMEOUTS feature, and the USB_STATUS_STAGE_TIMEOUT value are only relevant, when:

1. The application uses the USBDeferStatusStage() API function, but never calls USBCtrlEPAllowStatusStage(). Or:

2. The application uses host to device (OUT) control transfers with data stage, and some abnormal error occurs, where the host might try to abort the control transfer, before it has sent all of the data it claimed it was going to send.

If the application firmware never uses the USBDeferStatusStage() API function, and it never uses host to device control transfers with data stage, then it is not required to enable the USB_ENABLE_STATUS_STAGE_TIMEOUTS feature.

Section 9.2.6 of the USB 2.0 specifications indicate that:

1. Control transfers with no data stage: Status stage must complete within 50ms of the start of the control transfer.

2. Control transfers with (IN) data stage: Status stage must complete within 50ms of sending the last IN data packet in fullfilment of the data stage.

3. Control transfers with (OUT) data stage: No specific status stage timing requirement. However, the total time of the entire control transfer (ex: including the OUT data stage and IN status stage) must not exceed 5 seconds.

Therefore, if the USB_ENABLE_STATUS_STAGE_TIMEOUTS feature is used, it is suggested to set the USB_STATUS_STAGE_TIMEOUT value to timeout in less than 50ms. If the USB_ENABLE_STATUS_STAGE_TIMEOUTS feature is not enabled, then the USB_STATUS_STAGE_TIMEOUT parameter is not relevant.

The USB_STATUS_STAGE_TIMEOUT is approximately the timeout in milliseconds, except when USB_POLLING mode is used, and USBDeviceTasks() is called at < 1kHz. In this special case, the timeout becomes approximately:

Timeout(in milliseconds) = ((1000 * (USB_STATUS_STAGE_TIMEOUT - 1)) / (USBDeviceTasks() polling frequency in Hz))

This feature is optional and is not required unless needed by the application.

Example Usage:

#define USB_ENABLE_STATUS_STAGE_TIMEOUTS

#define USB_STATUS_STAGE_TIMEOUT (BYTE)45

Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options > usb_config.h > Status Stage Timout Enable (USB_ENABLE_STATUS_STAGE_TIMEOUTS and USB_STATUS_STAGE_TIMEOUT)


String Descriptor Array size (USB_NUM_STRING_DESCRIPTORS)

Contents | Index | Home
Previous | Up | Next
String Descriptor Array size (USB_NUM_STRING_DESCRIPTORS)

The USB stack needs to know how many string descriptors that there are on a device so that if a host requests a string descriptor index that is higher than what is supported, the stack can respond correctly to that event. This is done with the USB_NUM_STRING_DESCRIPTORS definition.

Example:

#define USB_NUM_STRING_DESCRIPTORS 3

Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options > usb_config.h > String Descriptor Array size (USB_NUM_STRING_DESCRIPTORS)


Event Notifications

Contents | Index | Home
Previous | Up | Next
Event Notifications

The USB stack passes events that the user might want to handle to the USER_USB_CALLBACK_EVENT_HANDLER() function. Some applications may not want to handle certain types of events. The stack provides a mechanism to disable certain events. Disabling an event in most cases will only stop the event handler from being called. This will slightly reduce the code size and slightly increase the code performance, but in most cases it will not stop the interrupt generation from occurring in the first place (if USB_INTERRUPT mode is being used).

The valid options are:

  • USB_DISABLE_SUSPEND_HANDLER
  • USB_DISABLE_WAKEUP_FROM_SUSPEND_HANDLER
  • USB_DISABLE_SOF_HANDLER
  • USB_DISABLE_TRANSFER_TERMINATED_HANDLER
  • USB_DISABLE_ERROR_HANDLER
  • USB_DISABLE_NONSTANDARD_EP0_REQUEST_HANDLER
  • USB_DISABLE_SET_DESCRIPTOR_HANDLER
  • USB_DISABLE_SET_CONFIGURATION_HANDLER
  • USB_DISABLE_TRANSFER_COMPLETE_HANDLER
To disable any specific event, just define one of these options in the usb_config.h file. For example:

#define USB_DISABLE_SOF_HANDLER

will cause the stack to stop sending SOF notifications to the application when SOF events occur.

Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options > usb_config.h > Event Notifications


Disable DTS checking (USB_DEVICE_DISABLE_DTS_CHECKING)

Contents | Index | Home
Previous | Up | Next
Disable DTS checking (USB_DEVICE_DISABLE_DTS_CHECKING)
Note: Developers should use caution when enabling this option. This option should only be used in cases where it is understood that this option is required due to a target host that is non-compliant and having DTS mismatch issues. This option should not be required when talking to compliant hosts.

The stack by default enables DTS checking to verify that incoming packets have the correct DTS setting and filters out any packets that have a DTS mismatch. In a case where a host is sending an incorrect DTS, the application will appear to miss data from the host. In order to disable DTS checking, add the following to the usb_config.h file:

#define USB_DEVICE_DISABLE_DTS_CHECKING

Application Programming Interface (API) > Device/Peripheral > Device Stack > Configuration Options > usb_config.h > Disable DTS checking (USB_DEVICE_DISABLE_DTS_CHECKING)


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
USB_APPLICATION_EVENT_HANDLER | This function is called whenever the USB stack wants to notify the user of an event.
USBCancelIO | This function cancels the transfers pending on the specified endpoint. This function can only be used after a SETUP packet is received and before that setup packet is handled. This is the time period in which the EVENT_EP0_REQUEST is thrown, before the event handler function returns to the stack.
USBCtrlEPAllowDataStage | This function allows the data stage of either a host-to-device or device-to-host control transfer (with data stage) to complete. This function is meant to be used in conjunction with either the USBDeferOUTDataStage() or USBDeferINDataStage(). If the firmware does not call either USBDeferOUTDataStage() or USBDeferINDataStage(), then the firmware does not need to manually call USBCtrlEPAllowDataStage(), as the USB stack will call this function instead.
USBCtrlEPAllowStatusStage | This function prepares the proper endpoint 0 IN or endpoint 0 OUT (based on the controlTransferState) to allow the status stage packet of a control transfer to complete. This function gets used internally by the USB stack itself, but it may also be called from the application firmware, IF the application firmware called the USBDeferStatusStage() function during the initial processing of the control transfer request. In this case, the application must call the USBCtrlEPAllowStatusStage() once, after it has fully completed processing and handling the data stage portion of the request. If the application firmware has no need for delaying... more
USBDeferINDataStage | This function will cause the USB hardware to continuously NAK the IN token packets sent from the host, during the data stage of a device to host control transfer. This allows the firmware more time to process and prepare the IN data packets that will eventually be sent to the host. This is also useful, if the firmware needs to process/prepare the IN data in a different context than what the USBDeviceTasks() function executes at. Calling this function (macro) will assert ownership of the currently pending control transfer. Therefore, the USB stack will not STALL when it reaches the... more
USBDeferOUTDataStage | This function will cause the USB hardware to continuously NAK the OUT data packets sent from the host, during the data stage of a device to host control transfer. This allows the firmware more time to prepare the RAM buffer that will eventually be used to receive the data from the host. This is also useful, if the firmware wishes to receive the OUT data in a different context than what the USBDeviceTasks() function executes at. Calling this function (macro) will assert ownership of the currently pending control transfer. Therefore, the USB stack will not STALL when it reaches... more
USBDeferStatusStage | Calling this function will prevent the USB stack from automatically enabling the status stage for the currently pending control transfer from completing immediately after all data bytes have been sent or received. This is useful if a class handler or USB application firmware project uses control transfers for sending/receiving data over EP0, but requires time in order to finish processing and/or to consume the data. For example: Consider an application which receives OUT data from the USB host, through EP0 using control transfers. Now assume that this application wishes to do something time consuming with this data (ex: transmit it... more
USBDeviceAttach | Checks if VBUS is present, and that the USB module is not already initalized, and if so, enables the USB module so as to signal device attachment to the USB host.
USBDeviceDetach | This function configures the USB module to "soft detach" itself from the USB host.
USBDeviceInit | This function initializes the device stack it in the default state. The USB module will be completely reset including all of the internal variables, registers, and interrupt flags.
USBDeviceTasks | This function is the main state machine/transaction handler of the USB device side stack. When the USB stack is operated in "USB_POLLING" mode (usb_config.h user option) the USBDeviceTasks() function should be called periodically to receive and transmit packets through the stack. This function also takes care of control transfers associated with the USB enumeration process, and detecting various USB events (such as suspend). This function should be called at least once every 1.8ms during the USB enumeration process. After the enumeration process is complete (which can be determined when USBGetDeviceState() returns CONFIGURED_STATE), the USBDeviceTasks() handler may be called the... more
USBEnableEndpoint | This function will enable the specified endpoint with the specified options
USBEP0Receive | Sets the destination, size, and a function to call on the completion of the next control write.
USBEP0SendRAMPtr | Sets the source, size, and options of the data you wish to send from a RAM source
USBEP0SendROMPtr | Sets the source, size, and options of the data you wish to send from a ROM source
USBEP0Transmit | Sets the address of the data to send over the control endpoint
USBGetDeviceState | This function will return the current state of the device on the USB. This function should return CONFIGURED_STATE before an application tries to send information on the bus.
USBGetNextHandle | Retrieves the handle to the next endpoint BDT entry that the USBTransferOnePacket() will use.
USBGetRemoteWakeupStatus | This function indicates if remote wakeup has been enabled by the host. Devices that support remote wakeup should use this function to determine if it should send a remote wakeup.
USBGetSuspendState | This function indicates if the USB port that this device is attached to is currently suspended. When suspended, it will not be able to transfer data over the bus.
USBHandleBusy | Checks to see if the input handle is busy
USBHandleGetAddr | Retrieves the address of the destination buffer of the input handle
USBHandleGetLength | Retrieves the length of the destination buffer of the input handle
USBINDataStageDeferred | Returns TRUE if a control transfer with IN data stage is pending, and the firmware has called USBDeferINDataStage(), but has not yet called USBCtrlEPAllowDataStage(). Returns FALSE if a control transfer with IN data stage is either not pending, or the firmware did not call USBDeferINDataStage() at the start of the control transfer. This function (macro) would typically be used in the case where the USBDeviceTasks() function executes in the interrupt context (ex: USB_INTERRUPT option selected in usb_config.h), but the firmware wishes to take care of handling the data stage of the control transfer in the main... more
USBIsBusSuspended | This function indicates if the USB bus is in suspend mode.
USBIsDeviceSuspended | This function indicates if the USB module is in suspend mode.
USBRxOnePacket | Receives the specified data out the specified endpoint
USBSoftDetach | This function performs a detach from the USB bus via software.
USBOUTDataStageDeferred | Returns TRUE if a control transfer with OUT data stage is pending, and the firmware has called USBDeferOUTDataStage(), but has not yet called USBCtrlEPAllowDataStage(). Returns FALSE if a control transfer with OUT data stage is either not pending, or the firmware did not call USBDeferOUTDataStage() at the start of the control transfer. This function (macro) would typically be used in the case where the USBDeviceTasks() function executes in the interrupt context (ex: USB_INTERRUPT option selected in usb_config.h), but the firmware wishes to take care of handling the data stage of the control transfer in the main... more
USBStallEndpoint | Configures the specified endpoint to send STALL to the host, the next time the host tries to access the endpoint.
USBTransferOnePacket | Transfers a single packet (one transaction) of data on the USB bus.
USBTxOnePacket | Sends the specified data out the specified endpoint
Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines


USB_APPLICATION_EVENT_HANDLER Function

Contents | Index | Home
Previous | Up | Next
USB_APPLICATION_EVENT_HANDLER Function
C
BOOL USB_APPLICATION_EVENT_HANDLER(
    BYTE address,
    USB_EVENT event,
    void * pdata,
    WORD size
);
Description

This function is called whenever the USB stack wants to notify the user of an event. This function should be implemented by the user.

Example Usage:

Preconditions

None

Parameters
Parameters | Description
BYTE address | the address of the device when the event happened
BYTE event | The event input specifies which event happened. The possible options are listed in the USB_DEVICE_STACK_EVENTS enumeration.
Returns

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USB_APPLICATION_EVENT_HANDLER Function


USBCancelIO Function

Contents | Index | Home
Previous | Up | Next
USBCancelIO Function
C
void USBCancelIO(
    BYTE endpoint
);
Description

This function cancels the transfers pending on the specified endpoint. This function can only be used after a SETUP packet is received and before that setup packet is handled. This is the time period in which the EVENT_EP0_REQUEST is thrown, before the event handler function returns to the stack.

Parameters
Parameters | Description
BYTE endpoint | the endpoint number you wish to cancel the transfers for
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBCancelIO Function


USBCtrlEPAllowDataStage Function

Contents | Index | Home
Previous | Up | Next
USBCtrlEPAllowDataStage Function
C
void USBCtrlEPAllowDataStage();
Preconditions

A control transfer (with data stage) should already be pending, if the firmware calls this function. Additionally, the firmware should have called either USBDeferOUTDataStage() or USBDeferINDataStage() at the start of the control transfer, if the firmware will be calling this function manually.

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBCtrlEPAllowDataStage Function


USBCtrlEPAllowStatusStage Function

Contents | Index | Home
Previous | Up | Next
USBCtrlEPAllowStatusStage Function
C
void USBCtrlEPAllowStatusStage();
Preconditions

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBCtrlEPAllowStatusStage Function


USBDeferINDataStage Function

Contents | Index | Home
Previous | Up | Next
USBDeferINDataStage Function
C
void USBDeferINDataStage();
Preconditions

Before calling USBDeferINDataStage(), the firmware should first verify that the control transfer has a data stage, and that it is of type device-to-host (IN).

Remarks

Section 9.2.6 of the official USB 2.0 specifications indicates that the USB device must return the first IN data packet within 500ms of the start of the control transfer. In order to meet this specification, the firmware must call USBEP0SendRAMPtr() or USBEP0SendROMPtr(), and then call USBCtrlEPAllowDataStage(), in less than 500ms from the start of the control transfer.

If the firmware calls USBDeferINDataStage(), it must eventually call USBEP0SendRAMPtr() or USBEP0SendROMPtr(), and then call USBCtrlEPAllowDataStage(). If it does not do this, the control transfer will never be able to complete.

The firmware should never call both USBDeferINDataStage() and USBDeferOUTDataStage() during the same control transfer. These functions are mutually exclusive (a control transfer with data stage can never contain both IN and OUT data packets during the data stage).

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBDeferINDataStage Function


USBDeferOUTDataStage Function

Contents | Index | Home
Previous | Up | Next
USBDeferOUTDataStage Function
C
void USBDeferOUTDataStage();
Preconditions

Before calling USBDeferOUTDataStage(), the firmware should first verify that the control transfer has a data stage, and that it is of type host-to-device (OUT).

Remarks

Section 9.2.6 of the official USB 2.0 specifications indicates that the USB device must be able to receive all bytes and complete the control transfer within a maximum of 5 seconds.

If the firmware calls USBDeferOUTDataStage(), it must eventually call USBEP0Receive(), and then call USBCtrlEPAllowDataStage(). If it does not do this, the control transfer will never be able to complete. This will break the USB connection, as the host needs to be able to communicate over EP0, in order to perform basic tasks including enumeration.

The firmware should never call both USBDeferINDataStage() and USBDeferOUTDataStage() during the same control transfer. These functions are mutually exclusive (a control transfer with data stage can never contain both IN and OUT data packets during the data stage).

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBDeferOUTDataStage Function


USBDeferStatusStage Function

Contents | Index | Home
Previous | Up | Next
USBDeferStatusStage Function
C
void USBDeferStatusStage();
Preconditions

None

Remarks

If this function is called, is should get called after the SETUP packet has arrived (the control transfer has started), but before the USBCtrlEPServiceComplete() function has been called by the USB stack. Therefore, the normal place to call USBDeferStatusStage() would be from within the USBCBCheckOtherReq() handler context. For example, in a HID application using control transfers, the USBDeferStatusStage() function would be called from within the USER_GET_REPORT_HANDLER or USER_SET_REPORT_HANDLER functions.

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBDeferStatusStage Function


USBDeviceAttach Function

Contents | Index | Home
Previous | Up | Next
USBDeviceAttach Function
C
void USBDeviceAttach();
Description

This function indicates to the USB host that the USB device has been attached to the bus. This function needs to be called in order for the device to start to enumerate on the bus.

Preconditions

Should only be called when USB_INTERRUPT is defined. Also, should only be called from the main() loop context. Do not call USBDeviceAttach() from within an interrupt handler, as the USBDeviceAttach() function may modify global interrupt enable bits and settings.

For normal USB devices: Make sure that if the module was previously on, that it has been turned off for a long time (ex: 100ms+) before calling this function to re-enable the module. If the device turns off the D+ (for full speed) or D- (for low speed) ~1.5k ohm pull up resistor, and then turns it back on very quickly, common hosts will sometimes reject this event, since no human could ever unplug and reattach a USB device in a microseconds (or nanoseconds) timescale. The host could simply treat this as some kind of glitch and ignore the event altogether.

Remarks

See also the USBDeviceDetach() API function documentation.

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBDeviceAttach Function


USBDeviceDetach Function

Contents | Index | Home
Previous | Up | Next
USBDeviceDetach Function
C
void USBDeviceDetach();
Description

This function configures the USB module to perform a "soft detach" operation, by disabling the D+ (or D-) ~1.5k pull up resistor, which lets the host know the device is present and attached. This will make the host think that the device has been unplugged. This is potentially useful, as it allows the USB device to force the host to re-enumerate the device (on the firmware has re-enabled the USB module/pull up, by calling USBDeviceAttach(), to "soft re-attach" to the host).

Preconditions

Should only be called when USB_INTERRUPT is defined. See remarks section if USB_POLLING mode option is being used (usb_config.h option).

Additionally, this function should only be called from the main() loop context. Do not call this function from within an interrupt handler, as this function may modify global interrupt enable bits and settings.

Remarks

If the application firmware calls USBDeviceDetach(), it is strongly recommended that the firmware wait at least >= 80ms before calling USBDeviceAttach(). If the firmeware performs a soft detach, and then re-attaches too soon (ex: after a few micro seconds for instance), some hosts may interpret this as an unexpected "glitch" rather than as a physical removal/re-attachment of the USB device. In this case the host may simply ignore the event without re-enumerating the device. To ensure that the host properly detects and processes the device soft detach/re-attach, it is recommended to make sure the device remains detached long enough to mimic a real human controlled USB unplug/re-attach event (ex: after calling USBDeviceDetach(), do not call USBDeviceAttach() for at least 80+ms, preferrably longer.

Neither the USBDeviceDetach() or USBDeviceAttach() functions are blocking or take long to execute. It is the application firmware's responsibility for adding the 80+ms delay, when using these API functions.

The Windows plug and play event handler processing is fairly slow, especially in certain versions of Windows, and for certain USB device classes. It has been observed that some device classes need to provide even more USB detach dwell interval (before calling USBDeviceAttach()), in order to work correctly after re-enumeration. If the USB device is a CDC class device, it is recommended to wait at least 1.5 seconds or longer, before soft re-attaching to the host, to provide the plug and play event handler enough time to finish processing the removal event, before the re-attach occurs.

If the application is using the USB_POLLING mode option, then the USBDeviceDetach() and USBDeviceAttach() functions are not available. In this mode, the USB stack relies on the "#define USE_USB_BUS_SENSE_IO" and "#define USB_BUS_SENSE" options in the HardwareProfile – [platform name].h file.

When using the USB_POLLING mode option, and the "#define USE_USB_BUS_SENSE_IO" definition has been commented out, then the USB stack assumes that it should always enable the USB module at pretty much all times. Basically, anytime the application firmware calls USBDeviceTasks(), the firmware will automatically enable the USB module. This mode would typically be selected if the application was designed to be a purely bus powered device. In this case, the application is powered from the +5V VBUS supply from the USB port, so it is correct and sensible in this type of application to power up and turn on the USB module, at anytime that the microcontroller is powered (which implies the USB cable is attached and the host is also powered).

In a self powered application, the USB stack is designed with the intention that the user will enable the "#define USE_USB_BUS_SENSE_IO" option in the HardwareProfile – [platform name].h file. When this option is defined, then the USBDeviceTasks() function will automatically check the I/O pin port value of the designated pin (based on the #define USB_BUS_SENSE option in the HardwareProfile – [platform name].h file), every time the application calls USBDeviceTasks(). If the USBDeviceTasks() function is executed and finds that the pin defined by the #define USB_BUS_SENSE is in a logic low state, then it will automatically disable the USB module and tri-state the D+ and D- pins. If however the USBDeviceTasks() function is executed and finds the pin defined by the #define USB_BUS_SENSE is in a logic high state, then it will automatically enable the USB module, if it has not already been enabled.

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBDeviceDetach Function


USBDeviceInit Function

Contents | Index | Home
Previous | Up | Next
USBDeviceInit Function
C
void USBDeviceInit();
Description

This function initializes the device stack it in the default state. The USB module will be completely reset including all of the internal variables, registers, and interrupt flags.

Preconditions

This function must be called before any of the other USB Device functions can be called, including USBDeviceTasks().

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBDeviceInit Function


USBDeviceTasks Function

Contents | Index | Home
Previous | Up | Next
USBDeviceTasks Function
C
void USBDeviceTasks();
Description

This function is the main state machine/transaction handler of the USB device side stack. When the USB stack is operated in "USB_POLLING" mode (usb_config.h user option) the USBDeviceTasks() function should be called periodically to receive and transmit packets through the stack. This function also takes care of control transfers associated with the USB enumeration process, and detecting various USB events (such as suspend). This function should be called at least once every 1.8ms during the USB enumeration process. After the enumeration process is complete (which can be determined when USBGetDeviceState() returns CONFIGURED_STATE), the USBDeviceTasks() handler may be called the faster of: either once every 9.8ms, or as often as needed to make sure that the hardware USTAT FIFO never gets full. A good rule of thumb is to call USBDeviceTasks() at a minimum rate of either the frequency that USBTransferOnePacket() gets called, or, once/1.8ms, whichever is faster. See the inline code comments near the top of usb_device.c for more details about minimum timing requirements when calling USBDeviceTasks().

When the USB stack is operated in "USB_INTERRUPT" mode, it is not necessary to call USBDeviceTasks() from the main loop context. In the USB_INTERRUPT mode, the USBDeviceTasks() handler only needs to execute when a USB interrupt occurs, and therefore only needs to be called from the interrupt context.

Typical usage:

Copy Code
void main(void)
{
    USBDeviceInit();
    while(1)
    {
        USBDeviceTasks(); //Takes care of enumeration and other USB events
        if((USBGetDeviceState() < CONFIGURED_STATE) ||
           (USBIsDeviceSuspended() == TRUE))
        {
            //Either the device is not configured or we are suspended,
            // so we don't want to execute any USB related application code
            continue;   //go back to the top of the while loop
        }
        else
        {
            //Otherwise we are free to run USB and non-USB related user
            //application code.
            UserApplication();
        }
    }
}
Preconditions

Make sure the USBDeviceInit() function has been called prior to calling USBDeviceTasks() for the first time.

Remarks

USBDeviceTasks() does not need to be called while in the USB suspend mode, if the user application firmware in the USBCBSuspend() callback function enables the ACTVIF USB interrupt source and put the microcontroller into sleep mode. If the application firmware decides not to sleep the microcontroller core during USB suspend (ex: continues running at full frequency, or clock switches to a lower frequency), then the USBDeviceTasks() function must still be called periodically, at a rate frequent enough to ensure the 10ms resume recovery interval USB specification is met. Assuming a worst case primary oscillator and PLL start up time of <5ms, then USBDeviceTasks() should be called once every 5ms in this scenario.

When the USB cable is detached, or the USB host is not actively powering the VBUS line to +5V nominal, the application firmware does not always have to call USBDeviceTasks() frequently, as no USB activity will be taking place. However, if USBDeviceTasks() is not called regularly, some alternative means of promptly detecting when VBUS is powered (indicating host attachment), or not powered (host powered down or USB cable unplugged) is still needed. For self or dual self/bus powered USB applications, see the USBDeviceAttach() and USBDeviceDetach() API documentation for additional considerations.

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBDeviceTasks Function


USBEnableEndpoint Function

Contents | Index | Home
Previous | Up | Next
USBEnableEndpoint Function
C
void USBEnableEndpoint(
    BYTE ep,
    BYTE options
);
Description

This function will enable the specified endpoint with the specified options.

Typical Usage:

Copy Code
void USBCBInitEP(void)
{
    USBEnableEndpoint(MSD_DATA_IN_EP,USB_IN_ENABLED|USB_OUT_ENABLED|USB_HANDSHAKE_ENABLED|USB_DISALLOW_SETUP);
    USBMSDInit();
}

In the above example endpoint number MSD_DATA_IN_EP is being configured for both IN and OUT traffic with handshaking enabled. Also since MSD_DATA_IN_EP is not endpoint 0 (MSD does not allow this), then we can explicitly disable SETUP packets on this endpoint.

Preconditions

None

Parameters
Parameters
Description
BYTE ep
the endpoint to be configured
BYTE options
optional settings for the endpoint. The options should be ORed together to form a single options string. The available optional settings for the endpoint. The options should be ORed together to form a single options string. The available options are the following:
  • USB_HANDSHAKE_ENABLED enables USB handshaking (ACK, NAK)
  • USB_HANDSHAKE_DISABLED disables USB handshaking (ACK, NAK)
  • USB_OUT_ENABLED enables the out direction
  • USB_OUT_DISABLED disables the out direction
  • USB_IN_ENABLED enables the in direction
  • USB_IN_DISABLED disables the in direction
  • USB_ALLOW_SETUP enables control transfers
  • USB_DISALLOW_SETUP disables control transfers
  • USB_STALL_ENDPOINT STALLs this endpoint
Returns

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBEnableEndpoint Function


USBEP0Receive Function

Contents | Index | Home
Previous | Up | Next
USBEP0Receive Function
C
void USBEP0Receive(
    BYTE* dest,
    WORD size,
    void (*function)
);
Preconditions

None

Parameters
Parameters | Description
dest | address of where the incoming data will go (make sure that this address is directly accessable by the USB module for parts with dedicated USB RAM this address must be in that space)
size | the size of the data being received (is almost always going tobe presented by the preceeding setup packet SetupPkt.wLength)
(*function) | a function that you want called once the data is received. If this is specificed as NULL then no function is called.
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBEP0Receive Function


USBEP0SendRAMPtr Function

Contents | Index | Home
Previous | Up | Next
USBEP0SendRAMPtr Function
C
void USBEP0SendRAMPtr(
    BYTE* src,
    WORD size,
    BYTE Options
);
Preconditions

None

Parameters
Parameters
Description
src
address of the data to send
size
the size of the data needing to be transmitted
options
the various options that you want when sending the control data. Options are:
  • USB_EP0_ROM
  • USB_EP0_RAM
  • USB_EP0_BUSY
  • USB_EP0_INCLUDE_ZERO
  • USB_EP0_NO_DATA
  • USB_EP0_NO_OPTIONS
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBEP0SendRAMPtr Function


USBEP0SendROMPtr Function

Contents | Index | Home
Previous | Up | Next
USBEP0SendROMPtr Function
C
void USBEP0SendROMPtr(
    BYTE* src,
    WORD size,
    BYTE Options
);
Preconditions

None

Parameters
Parameters
Description
src
address of the data to send
size
the size of the data needing to be transmitted
options
the various options that you want when sending the control data. Options are:
  • USB_EP0_ROM
  • USB_EP0_RAM
  • USB_EP0_BUSY
  • USB_EP0_INCLUDE_ZERO
  • USB_EP0_NO_DATA
  • USB_EP0_NO_OPTIONS
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBEP0SendROMPtr Function


USBEP0Transmit Function

Contents | Index | Home
Previous | Up | Next
USBEP0Transmit Function
C
void USBEP0Transmit(
    BYTE options
);
Preconditions

None

Paramters: options - the various options that you want when sending the control data. Options are: USB_EP0_ROM USB_EP0_RAM USB_EP0_BUSY USB_EP0_INCLUDE_ZERO USB_EP0_NO_DATA USB_EP0_NO_OPTIONS

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBEP0Transmit Function


USBGetDeviceState Function

Contents | Index | Home
Previous | Up | Next
USBGetDeviceState Function
C
USB_DEVICE_STATE USBGetDeviceState();
Description

This function returns the current state of the device on the USB. This function is used to determine when the device is ready to communicate on the bus. Applications should not try to send or receive data until this function returns CONFIGURED_STATE.

It is also important that applications yield as much time as possible to the USBDeviceTasks() function as possible while the this function returns any value between ATTACHED_STATE through CONFIGURED_STATE.

For more information about the various device states, please refer to the USB specification section 9.1 available from www.usb.org.

Typical usage:

Copy Code
void main(void)
{
    USBDeviceInit()
    while(1)
    {
        USBDeviceTasks();
        if((USBGetDeviceState() < CONFIGURED_STATE) ||
           (USBIsDeviceSuspended() == TRUE))
        {
            //Either the device is not configured or we are suspended
            //  so we don't want to do execute any application code
            continue;   //go back to the top of the while loop
        }
        else
        {
            //Otherwise we are free to run user application code.
            UserApplication();
        }
    }
}
Preconditions

None

Return Values
Return Values | Description
USB_DEVICE_STATE | the current state of the device on the bus
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBGetDeviceState Function


USBGetNextHandle Function

Contents | Index | Home
Previous | Up | Next
USBGetNextHandle Function
C
USB_HANDLE USBGetNextHandle(
    BYTE ep_num,
    BYTE ep_dir
);
Description

Retrieves the handle to the next endpoint BDT that the USBTransferOnePacket() will use. Useful for initialization and when ping pong buffering will be used on application endpoints.

Preconditions

Will return NULL if the USB device has not yet been configured/the endpoint specified has not yet been initalized by USBEnableEndpoint().

Parameters
Parameters | Description
BYTE ep_num | The endpoint number to get the handle for (valid values are 1-15, 0 is not a valid input value for this API)
BYTE ep_dir | The endpoint direction associated with the endpoint number to get the handle for (valid values are OUT_FROM_HOST and IN_TO_HOST).
Return Values
Return Values | Description
USB_HANDLE | Returns the USB_HANDLE (a pointer) to the BDT that will be used next time the USBTransferOnePacket() function is called, for the given ep_num and ep_dir
Remarks

This API is useful for initializing USB_HANDLEs during initialization of the application firmware. It is also useful when ping-pong bufferring is enabled, and the application firmware wishes to arm both the even and odd BDTs for an endpoint simultaneously. In this case, the application firmware for sending data to the host would typically be something like follows:

Copy Code
    USB_HANDLE Handle1;
USB_HANDLE Handle2;
USB_HANDLE* pHandle = &Handle1;
BYTE UserDataBuffer1[64];
BYTE UserDataBuffer2[64];
BYTE* pDataBuffer = &UserDataBuffer1[0];

//Add some code that loads UserDataBuffer1[] with useful data to send,
//using the pDataBuffer pointer, for example:
//for(i = 0; i < 64; i++)
//{
//  *pDataBuffer++ = [useful data value];
//}

//Check if the next USB endpoint BDT is available
if(!USBHandleBusy(USBGetNextHandle(ep_num, IN_TO_HOST))
{
    //The endpoint is available.  Send the data.
    *pHandle = USBTransferOnePacket(ep_num, ep_dir, pDataBuffer, bytecount);
    //Toggle the handle and buffer pointer for the next transaction
    if(pHandle == &Handle1)
    {
        pHandle = &Handle2;
        pDataBuffer = &UserDataBuffer2[0];
    }
    else
    {
        pHandle = &Handle1;
        pDataBuffer = &UserDataBuffer1[0];
    }
}

//The firmware can then load the next data buffer (in this case
//UserDataBuffer2)with useful data, and send it using the same
//process.  For example:

//Add some code that loads UserDataBuffer2[] with useful data to send,
//using the pDataBuffer pointer, for example:
//for(i = 0; i < 64; i++)
//{
//  *pDataBuffer++ = [useful data value];
//}

//Check if the next USB endpoint BDT is available
if(!USBHandleBusy(USBGetNextHandle(ep_num, IN_TO_HOST))
{
    //The endpoint is available.  Send the data.
    *pHandle = USBTransferOnePacket(ep_num, ep_dir, pDataBuffer, bytecount);
    //Toggle the handle and buffer pointer for the next transaction
    if(pHandle == &Handle1)
    {
        pHandle = &Handle2;
        pDataBuffer = &UserDataBuffer2[0];
    }
    else
    {
        pHandle = &Handle1;
        pDataBuffer = &UserDataBuffer1[0];
    }
}
Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBGetNextHandle Function


USBGetRemoteWakeupStatus Function

Contents | Index | Home
Previous | Up | Next
USBGetRemoteWakeupStatus Function
C
BOOL USBGetRemoteWakeupStatus();
Description

This function indicates if remote wakeup has been enabled by the host. Devices that support remote wakeup should use this function to determine if it should send a remote wakeup.

If a device does not support remote wakeup (the Remote wakeup bit, bit 5, of the bmAttributes field of the Configuration descriptor is set to 1), then it should not send a remote wakeup command to the PC and this function is not of any use to the device. If a device does support remote wakeup then it should use this function as described below.

If this function returns FALSE and the device is suspended, it should not issue a remote wakeup (resume).

If this function returns TRUE and the device is suspended, it should issue a remote wakeup (resume).

A device can add remote wakeup support by having the _RWU symbol added in the configuration descriptor (located in the usb_descriptors.c file in the project). This done in the 8th byte of the configuration descriptor. For example:

Copy Code
  ROM BYTE configDescriptor1[]={
    0x09,                           // Size
    USB_DESCRIPTOR_CONFIGURATION,   // descriptor type
    DESC_CONFIG_WORD(0x0022),       // Total length
    1,                              // Number of interfaces
    1,                              // Index value of this cfg
    0,                              // Configuration string index
    _DEFAULT | _SELF | _RWU,        // Attributes, see usb_device.h
    50,                             // Max power consumption in 2X mA(100mA)

    //The rest of the configuration descriptor should follow

For more information about remote wakeup, see the following section of the USB v2.0 specification available at www.usb.org:

  • Section 9.2.5.2
  • Table 9-10
  • Section 7.1.7.7
  • Section 9.4.5

Preconditions

None

Return Values
Return Values | Description
TRUE | Remote Wakeup has been enabled by the host
FALSE | Remote Wakeup is not currently enabled
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBGetRemoteWakeupStatus Function


USBGetSuspendState Function

Contents | Index | Home
Previous | Up | Next
USBGetSuspendState Function
C
BOOL USBGetSuspendState();
Description

This function indicates if the USB port that this device is attached to is currently suspended. When suspended, it will not be able to transfer data over the bus. This function can be used by the application to skip over section of code that do not need to exectute if the device is unable to send data over the bus. This function can also be used to help determine when it is legal to perform USB remote wakeup signalling, for devices supporting this feature.

Typical usage:

Copy Code
   void main(void)
   {
       USBDeviceInit()
       while(1)
       {
           USBDeviceTasks();
           if((USBGetDeviceState() < CONFIGURED_STATE) ||
              (USBGetSuspendState() == TRUE))
           {
               //Either the device is not configured or we are suspended
               //  so we don't want to do execute any application code
               continue;   //go back to the top of the while loop
           }
           else
           {
               //Otherwise we are free to run user application code.
               UserApplication();
           }
       }
   }
Preconditions

None

Return Values
Return Values | Description
TRUE | the USB port this device is attached to is suspended.
FALSE | the USB port this device is attached to is not suspended.
Remarks

This function is the same as USBIsBusSuspended().

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBGetSuspendState Function


USBHandleBusy Function

Contents | Index | Home
Previous | Up | Next
USBHandleBusy Function
C
BOOL USBHandleBusy(
    USB_HANDLE handle
);
Description

Checks to see if the input handle is busy

Typical Usage

Copy Code
//make sure that the last transfer isn't busy by checking the handle
if(!USBHandleBusy(USBGenericInHandle))
{
    //Send the data contained in the INPacket[] array out on
    //  endpoint USBGEN_EP_NUM
    USBGenericInHandle = USBGenWrite(USBGEN_EP_NUM,(BYTE*)&INPacket[0],sizeof(INPacket));
}
Preconditions

None

Parameters
Parameters | Description
USB_HANDLE handle | handle of the transfer that you want to check the status of
Return Values
Return Values | Description
TRUE | The specified handle is busy
FALSE | The specified handle is free and available for a transfer
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBHandleBusy Function


USBHandleGetAddr Function

Contents | Index | Home
Previous | Up | Next
USBHandleGetAddr Function
C
WORD USBHandleGetAddr(
    USB_HANDLE
);
Description

Retrieves the address of the destination buffer of the input handle

Preconditions

None

Parameters
Parameters | Description
USB_HANDLE handle | the handle to the transfer you want the address for.
Return Values
Return Values | Description
WORD | address of the current buffer that the input handle points to.
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBHandleGetAddr Function


USBHandleGetLength Function

Contents | Index | Home
Previous | Up | Next
USBHandleGetLength Function
C
WORD USBHandleGetLength(
    USB_HANDLE handle
);
Description

Retrieves the length of the destination buffer of the input handle

Preconditions

None

Parameters
Parameters | Description
USB_HANDLE handle | the handle to the transfer you want the address for.
Return Values
Return Values | Description
WORD | length of the current buffer that the input handle points to. If the transfer is complete then this is the length of the data transmitted or the length of data actually received.
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBHandleGetLength Function


USBINDataStageDeferred Function

Contents | Index | Home
Previous | Up | Next
USBINDataStageDeferred Function
C
BOOL USBINDataStageDeferred();
Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBINDataStageDeferred Function


USBIsBusSuspended Function

Contents | Index | Home
Previous | Up | Next
USBIsBusSuspended Function
C
BOOL USBIsBusSuspended();
Description

This function indicates if the USB bus is in suspend mode. This function is typically used for checking if the conditions are consistent with performing a USB remote wakeup sequence.

Typical Usage:

Copy Code
if((USBIsBusSuspended() == TRUE) && (USBGetRemoteWakeupStatus() == TRUE))
{
    //Check if some stimulus occured, which will be used as the wakeup source
    if(sw3 == 0)
    {
        USBCBSendResume();  //Send the remote wakeup signalling to the host
    }
}
// otherwise do some other application specific tasks
Preconditions

None

Returns

None

Remarks

The USBIsBusSuspended() function relies on the USBBusIsSuspended boolean variable, which gets updated by the USBDeviceTasks() function. Therefore, in order to be sure the return value is not "stale", it is suggested to make sure USBDeviceTasks() has executed recently (if using USB polling mode).

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBIsBusSuspended Function


USBIsDeviceSuspended Function

Contents | Index | Home
Previous | Up | Next
USBIsDeviceSuspended Function
C
BOOL USBIsDeviceSuspended();
Description

This function indicates if the USB module is in suspend mode. This function does NOT indicate that a suspend request has been received. It only reflects the state of the USB module.

Typical Usage:

Copy Code
if(USBIsDeviceSuspended() == TRUE)
{
    return;
}
// otherwise do some application specific tasks
Preconditions

None

Returns

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBIsDeviceSuspended Function


USBRxOnePacket Function

Contents | Index | Home
Previous | Up | Next
USBRxOnePacket Function
C
USB_HANDLE USBRxOnePacket(
    BYTE ep,
    BYTE* data,
    WORD len
);
Preconditions

None

Parameters
Parameters | Description
ep | The endpoint number you want to receive the data on.
data | Pointer to a user buffer where the data will go when
it arrives from the host. Note | This RAM must be USB module accessible.
len | The len parameter should always be set to the maximum endpoint packet size, specified in the USB descriptor for this endpoint. The host may send <= the number of bytes as the endpoint size in the endpoint descriptor. After the transaction is complete, the application firmware can call USBHandleGetLength() to determine how many bytes the host actually sent in the last transaction on this endpoint.
Return Values
Return Values | Description
USB_HANDLE | Returns a pointer to the BDT entry associated with the transaction. The firmware can check for completion of the transaction by using the USBHandleBusy() function, using the returned USB_HANDLE value.
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBRxOnePacket Function


USBSoftDetach Function

Contents | Index | Home
Previous | Up | Next
USBSoftDetach Function
C
void USBSoftDetach();
Description

This function performs a detach from the USB bus via software.

Preconditions

None

Returns

None

Remarks

Caution should be used when detaching from the bus. Some PC drivers and programs may require additional time after a detach before a device can be reattached to the bus.

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBSoftDetach Function


USBOUTDataStageDeferred Function

Contents | Index | Home
Previous | Up | Next
USBOUTDataStageDeferred Function
C
BOOL USBOUTDataStageDeferred();
Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBOUTDataStageDeferred Function


USBStallEndpoint Function

Contents | Index | Home
Previous | Up | Next
USBStallEndpoint Function
C
void USBStallEndpoint(
    BYTE ep,
    BYTE dir
);
Preconditions

None

Parameters
Parameters | Description
BYTE ep | The endpoint number that should be configured to send STALL.
BYTE dir | The direction of the endpoint to STALL, either IN_TO_HOST or OUT_FROM_HOST.
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBStallEndpoint Function


USBTransferOnePacket Function

Contents | Index | Home
Previous | Up | Next
USBTransferOnePacket Function
C
USB_HANDLE USBTransferOnePacket(
    BYTE ep,
    BYTE dir,
    BYTE* data,
    BYTE len
);
Description

The USBTransferOnePacket() function prepares a USB endpoint so that it may send data to the host (an IN transaction), or receive data from the host (an OUT transaction). The USBTransferOnePacket() function can be used both to receive and send data to the host. This function is the primary API function provided by the USB stack firmware for sending or receiving application data over the USB port.

The USBTransferOnePacket() is intended for use with all application endpoints. It is not used for sending or receiving applicaiton data through endpoint 0 by using control transfers. Separate API functions, such as USBEP0Receive(), USBEP0SendRAMPtr(), and USBEP0SendROMPtr() are provided for this purpose.

The USBTransferOnePacket() writes to the Buffer Descriptor Table (BDT) entry associated with an endpoint buffer, and sets the UOWN bit, which prepares the USB hardware to allow the transaction to complete. The application firmware can use the USBHandleBusy() macro to check the status of the transaction, to see if the data has been successfully transmitted yet.

Typical Usage

Copy Code
//make sure that the we are in the configured state
if(USBGetDeviceState() == CONFIGURED_STATE)
{
    //make sure that the last transaction isn't busy by checking the handle
    if(!USBHandleBusy(USBInHandle))
    {
        //Write the new data that we wish to send to the host to the INPacket[] array
        INPacket[0] = USEFUL_APPLICATION_VALUE1;
        INPacket[1] = USEFUL_APPLICATION_VALUE2;
        //INPacket[2] = ... (fill in the rest of the packet data)

        //Send the data contained in the INPacket[] array through endpoint "EP_NUM"
        USBInHandle = USBTransferOnePacket(EP_NUM,IN_TO_HOST,(BYTE*)&INPacket[0],sizeof(INPacket));
    }
}
Preconditions

Before calling USBTransferOnePacket(), the following should be true.

  1. The USB stack has already been initialized (USBDeviceInit() was called).
  2. A transaction is not already pending on the specified endpoint. This is done by checking the previous request using the USBHandleBusy() macro (see the typical usage example).
  3. The host has already sent a set configuration request and the enumeration process is complete. This can be checked by verifying that the USBGetDeviceState() macro returns "CONFIGURED_STATE", prior to calling USBTransferOnePacket().

Parameters
Parameters | Description
BYTE ep | The endpoint number that the data will be transmitted or received on
BYTE dir | The direction of the transfer This value is either OUT_FROM_HOST or IN_TO_HOST
BYTE* data | For IN transactions: pointer to the RAM buffer containing
the data to be sent to the host. For OUT transactions | pointer to the RAM buffer that the received data should get written to.
BYTE len | Length of the data needing to be sent (for IN transactions). For OUT transactions, the len parameter should normally be set to the endpoint size specified in the endpoint descriptor.
Return Values
Return Values | Description
USB_HANDLE | handle to the transfer. The handle is a pointer to the BDT entry associated with this transaction. The
status of the transaction (ex | if it is complete or still pending) can be checked using the USBHandleBusy() macro and supplying the USB_HANDLE provided by USBTransferOnePacket().
Remarks

If calling the USBTransferOnePacket() function from within the USBCBInitEP() callback function, the set configuration is still being processed and the USBDeviceState may not be == CONFIGURED_STATE yet. In this special case, the USBTransferOnePacket() may still be called, but make sure that the endpoint has been enabled and initialized by the USBEnableEndpoint() function first.

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBTransferOnePacket Function


USBTxOnePacket Function

Contents | Index | Home
Previous | Up | Next
USBTxOnePacket Function
C
USB_HANDLE USBTxOnePacket(
    BYTE ep,
    BYTE* data,
    WORD len
);
Preconditions

None

Parameters
Parameters | Description
ep | the endpoint number you want to send the data out of
data | pointer to a user buffer that contains the data that you wish to
send to the host. Note | This RAM buffer must be accessible by the USB module.
len | the number of bytes of data that you wish to send to the host,
in the next transaction on this endpoint. Note | this value should always be less than or equal to the endpoint size, as specified in the USB endpoint descriptor.
Return Values
Return Values | Description
USB_HANDLE | Returns a pointer to the BDT entry associated with the transaction. The firmware can check for completion of the transaction by using the USBHandleBusy() function, using the returned USB_HANDLE value.
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Device Stack > Interface Routines > USBTxOnePacket Function


Data Types and Constants

Contents | Index | Home
Previous | Up | Next
Data Types and Constants
Enumerations
Name | Description
USB_DEVICE_STATE | USB Device States as returned by USBGetDeviceState(). Only the defintions for these states should be used. The actual value for each state should not be relied upon as constant and may change based on the implementation.
USB_DEVICE_STACK_EVENTS | USB device stack events description here - DWF
Macros
Name | Description
USB_EP0_BUSY | The PIPE is busy
USB_EP0_INCLUDE_ZERO | include a trailing zero packet
USB_EP0_NO_DATA | no data to send
USB_EP0_NO_OPTIONS | no options set
USB_EP0_RAM | Data comes from ROM
USB_EP0_ROM | Data comes from RAM
USB_HANDLE | USB_HANDLE is a pointer to an entry in the BDT. This pointer can be used to read the length of the last transfer, the status of the last transfer, and various other information. Insure to initialize USB_HANDLE objects to NULL so that they are in a known state during their first usage.
Application Programming Interface (API) > Device/Peripheral > Device Stack > Data Types and Constants


USB_DEVICE_STATE Enumeration

Contents | Index | Home
Previous | Up | Next
USB_DEVICE_STATE Enumeration
C
typedef enum {
  DETACHED_STATE,
  ATTACHED_STATE,
  POWERED_STATE,
  DEFAULT_STATE,
  ADR_PENDING_STATE,
  ADDRESS_STATE,
  CONFIGURED_STATE
} USB_DEVICE_STATE;
Description

USB Device States as returned by USBGetDeviceState(). Only the defintions for these states should be used. The actual value for each state should not be relied upon as constant and may change based on the implementation.

Members
Members | Description
DETACHED_STATE | Detached is the state in which the device is not attached to the bus. When in the detached state a device should not have any pull-ups attached to either the D+ or D- line.
ATTACHED_STATE | Attached is the state in which the device is attached ot the bus but the hub/port that it is attached to is not yet configured.
POWERED_STATE | Powered is the state in which the device is attached to the bus and the hub/port that it is attached to is configured.
DEFAULT_STATE | Default state is the state after the device receives a RESET command from the host.
ADR_PENDING_STATE | Address pending state is not an official state of the USB defined states. This state is internally used to indicate that the device has received a SET_ADDRESS command but has not received the STATUS stage of the transfer yet. The device is should not switch addresses until after the STATUS stage is complete.
ADDRESS_STATE | Address is the state in which the device has its own specific address on the bus.
CONFIGURED_STATE | Configured is the state where the device has been fully enumerated and is operating on the bus. The device is now allowed to excute its application specific tasks. It is also allowed to increase its current consumption to the value specified in the configuration descriptor of the current configuration.
Application Programming Interface (API) > Device/Peripheral > Device Stack > Data Types and Constants > USB_DEVICE_STATE Enumeration


USB_DEVICE_STACK_EVENTS Enumeration

Contents | Index | Home
Previous | Up | Next
USB_DEVICE_STACK_EVENTS Enumeration
C
typedef enum {
  EVENT_CONFIGURED,
  EVENT_SET_DESCRIPTOR,
  EVENT_EP0_REQUEST,
  EVENT_ATTACH,
  EVENT_TRANSFER_TERMINATED
} USB_DEVICE_STACK_EVENTS;
Description

USB device stack events description here - DWF

Members
Members | Description
EVENT_CONFIGURED | Notification that a SET_CONFIGURATION() command was received (device)
EVENT_SET_DESCRIPTOR | A SET_DESCRIPTOR request was received (device)
EVENT_EP0_REQUEST | An endpoint 0 request was received that the stack did not know how to handle. This is most often a request for one of the class drivers. Please refer to the class driver documenation for information related to what to do if this request is received. (device)
EVENT_ATTACH | Device-mode USB cable has been attached. This event is not used by the Host stack. The client driver may provide an application event when a device attaches.
EVENT_TRANSFER_TERMINATED | A user transfer was terminated by the stack. This event will pass back the value of the handle that was terminated. Compare this value against the current valid handles to determine which transfer was terminated.
Application Programming Interface (API) > Device/Peripheral > Device Stack > Data Types and Constants > USB_DEVICE_STACK_EVENTS Enumeration


USB_EP0_BUSY Macro

Contents | Index | Home
Previous | Up | Next
USB_EP0_BUSY Macro
C
#define USB_EP0_BUSY 0x80     //The PIPE is busy
Description

The PIPE is busy

Application Programming Interface (API) > Device/Peripheral > Device Stack > Data Types and Constants > USB_EP0_BUSY Macro


USB_EP0_INCLUDE_ZERO Macro

Contents | Index | Home
Previous | Up | Next
USB_EP0_INCLUDE_ZERO Macro
C
#define USB_EP0_INCLUDE_ZERO 0x40     //include a trailing zero packet
Description

include a trailing zero packet

Application Programming Interface (API) > Device/Peripheral > Device Stack > Data Types and Constants > USB_EP0_INCLUDE_ZERO Macro


USB_EP0_NO_DATA Macro

Contents | Index | Home
Previous | Up | Next
USB_EP0_NO_DATA Macro
C
#define USB_EP0_NO_DATA 0x00     //no data to send
Description

no data to send

Application Programming Interface (API) > Device/Peripheral > Device Stack > Data Types and Constants > USB_EP0_NO_DATA Macro


USB_EP0_NO_OPTIONS Macro

Contents | Index | Home
Previous | Up | Next
USB_EP0_NO_OPTIONS Macro
C
#define USB_EP0_NO_OPTIONS 0x00     //no options set
Description

no options set

Application Programming Interface (API) > Device/Peripheral > Device Stack > Data Types and Constants > USB_EP0_NO_OPTIONS Macro


USB_EP0_RAM Macro

Contents | Index | Home
Previous | Up | Next
USB_EP0_RAM Macro
C
#define USB_EP0_RAM 0x01     //Data comes from ROM
Description

Data comes from ROM

Application Programming Interface (API) > Device/Peripheral > Device Stack > Data Types and Constants > USB_EP0_RAM Macro


USB_EP0_ROM Macro

Contents | Index | Home
Previous | Up | Next
USB_EP0_ROM Macro
C
#define USB_EP0_ROM 0x00     //Data comes from RAM
Description

Data comes from RAM

Application Programming Interface (API) > Device/Peripheral > Device Stack > Data Types and Constants > USB_EP0_ROM Macro


USB_HANDLE Macro

Contents | Index | Home
Previous | Up | Next
USB_HANDLE Macro
C
#define USB_HANDLE void*
Description

USB_HANDLE is a pointer to an entry in the BDT. This pointer can be used to read the length of the last transfer, the status of the last transfer, and various other information. Insure to initialize USB_HANDLE objects to NULL so that they are in a known state during their first usage.

Application Programming Interface (API) > Device/Peripheral > Device Stack > Data Types and Constants > USB_HANDLE Macro


Macros

Contents | Index | Home
Previous | Up | Next
Macros
Macros
Name | Description
DESC_CONFIG_BYTE | The DESC_CONFIG_BYTE() macro is implemented for convinence. The DESC_CONFIG_BYTE() macro provides a consistant macro for use with a byte when generating a configuratin descriptor when using either the DESC_CONFIG_WORD() or DESC_CONFIG_DWORD() macros.
DESC_CONFIG_DWORD | The DESC_CONFIG_DWORD() macro is implemented for convinence. Since the configuration descriptor array is a BYTE array, each entry needs to be a BYTE in LSB format. The DESC_CONFIG_DWORD() macro breaks up a DWORD into the appropriate BYTE entries in LSB.
DESC_CONFIG_WORD | The DESC_CONFIG_WORD() macro is implemented for convinence. Since the configuration descriptor array is a BYTE array, each entry needs to be a BYTE in LSB format. The DESC_CONFIG_WORD() macro breaks up a WORD into the appropriate BYTE entries in LSB. Typical Usage:
Application Programming Interface (API) > Device/Peripheral > Device Stack > Macros


DESC_CONFIG_BYTE Macro

Contents | Index | Home
Previous | Up | Next
DESC_CONFIG_BYTE Macro
C
#define DESC_CONFIG_BYTE(a) (a)
Description

The DESC_CONFIG_BYTE() macro is implemented for convinence. The DESC_CONFIG_BYTE() macro provides a consistant macro for use with a byte when generating a configuratin descriptor when using either the DESC_CONFIG_WORD() or DESC_CONFIG_DWORD() macros.

Application Programming Interface (API) > Device/Peripheral > Device Stack > Macros > DESC_CONFIG_BYTE Macro


DESC_CONFIG_DWORD Macro

Contents | Index | Home
Previous | Up | Next
DESC_CONFIG_DWORD Macro
C
#define DESC_CONFIG_DWORD(a) (a&0xFF),((a>>8)&0xFF),((a>>16)&0xFF),((a>>24)&0xFF)
Description

The DESC_CONFIG_DWORD() macro is implemented for convinence. Since the configuration descriptor array is a BYTE array, each entry needs to be a BYTE in LSB format. The DESC_CONFIG_DWORD() macro breaks up a DWORD into the appropriate BYTE entries in LSB.

Application Programming Interface (API) > Device/Peripheral > Device Stack > Macros > DESC_CONFIG_DWORD Macro


DESC_CONFIG_WORD Macro

Contents | Index | Home
Previous | Up | Next
DESC_CONFIG_WORD Macro
C
#define DESC_CONFIG_WORD(a) (a&0xFF),((a>>8)&0xFF)
Description

The DESC_CONFIG_WORD() macro is implemented for convinence. Since the configuration descriptor array is a BYTE array, each entry needs to be a BYTE in LSB format. The DESC_CONFIG_WORD() macro breaks up a WORD into the appropriate BYTE entries in LSB. Typical Usage:

Copy Code
    ROM BYTE configDescriptor1[]={
        0x09,                           // Size of this descriptor in bytes
        USB_DESCRIPTOR_CONFIGURATION,   // CONFIGURATION descriptor type
        DESC_CONFIG_WORD(0x0022),       // Total length of data for this cfg
Application Programming Interface (API) > Device/Peripheral > Device Stack > Macros > DESC_CONFIG_WORD Macro


Audio Function Driver

Contents | Index | Home
Previous | Up | Next
Audio Function Driver
Topics
Name | Description
Interface Routines |
Data Types and Constants |
Application Programming Interface (API) > Device/Peripheral > Audio Function Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
USBCheckAudioRequest | This routine checks the setup data packet to see if it knows how to handle it
Application Programming Interface (API) > Device/Peripheral > Audio Function Driver > Interface Routines


USBCheckAudioRequest Function

Contents | Index | Home
Previous | Up | Next
USBCheckAudioRequest Function
C
void USBCheckAudioRequest();
Description

This routine checks the setup data packet to see if it knows how to handle it

Preconditions

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Audio Function Driver > Interface Routines > USBCheckAudioRequest Function


Data Types and Constants

Contents | Index | Home
Previous | Up | Next
Data Types and Constants
Application Programming Interface (API) > Device/Peripheral > Audio Function Driver > Data Types and Constants


CCID (Smart/Sim Card) Function Driver

Contents | Index | Home
Previous | Up | Next
CCID (Smart/Sim Card) Function Driver
Topics
Name | Description
Interface Routines |
Application Programming Interface (API) > Device/Peripheral > CCID (Smart/Sim Card) Function Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
USBCCIDBulkInService | USBCCIDBulkInService handles device-to-host transaction(s). This function should be called once per Main Program loop after the device reaches the configured state.
USBCCIDInitEP | This function initializes the CCID function driver. This function should be called after the SET_CONFIGURATION command.
USBCCIDSendDataToHost | USBCCIDSendDataToHost writes an array of data to the USB. Use this version, is capable of transfering 0x00 (what is typically a NULL character in any of the string transfer functions).
USBCheckCCIDRequest | This routine checks the setup data packet to see if it knows how to handle it
Application Programming Interface (API) > Device/Peripheral > CCID (Smart/Sim Card) Function Driver > Interface Routines


USBCCIDBulkInService Function

Contents | Index | Home
Previous | Up | Next
USBCCIDBulkInService Function
C
void USBCCIDBulkInService();
Description

USBCCIDBulkInService handles device-to-host transaction(s). This function should be called once per Main Program loop after the device reaches the configured state.

Typical Usage:

Copy Code
void main(void)
{
    USBDeviceInit();
    while(1)
    {
        USBDeviceTasks();
        if((USBGetDeviceState() < CONFIGURED_STATE) ||
           (USBIsDeviceSuspended() == TRUE))
        {
            //Either the device is not configured or we are suspended
            //  so we don't want to do execute any application code
            continue;   //go back to the top of the while loop
        }
        else
        {
            //Run application code.
            UserApplication();

            //Keep trying to send data to the PC as required
            USBCCIDBulkInService();
        }
    }
}
Preconditions

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > CCID (Smart/Sim Card) Function Driver > Interface Routines > USBCCIDBulkInService Function


USBCCIDInitEP Function

Contents | Index | Home
Previous | Up | Next
USBCCIDInitEP Function
C
void USBCCIDInitEP();
Description

This function initializes the CCID function driver. This function sets the default line coding (baud rate, bit parity, number of data bits, and format). This function also enables the endpoints and prepares for the first transfer from the host.

This function should be called after the SET_CONFIGURATION command. This is most simply done by calling this function from the USBCBInitEP() function.

Typical Usage:

Copy Code
    void USBCBInitEP(void)
    {
        USBCCIDInitEP();
    }
Preconditions

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > CCID (Smart/Sim Card) Function Driver > Interface Routines > USBCCIDInitEP Function


USBCCIDSendDataToHost Function

Contents | Index | Home
Previous | Up | Next
USBCCIDSendDataToHost Function
C
void USBCCIDSendDataToHost(
    BYTE * pData,
    WORD len
);
Description

USBCCIDSendDataToHost writes an array of data to the USB. Use this version, is capable of transfering 0x00 (what is typically a NULL character in any of the string transfer functions).

The transfer mechanism for device-to-host(put) is more flexible than host-to-device(get). It can handle a string of data larger than the maximum size of bulk IN endpoint. A state machine is used to transfer a long string of data over multiple USB transactions. USBCCIDBulkInService() must be called periodically to keep sending blocks of data to the host.

Parameters
Parameters | Description
BYTE *data | pointer to a RAM array of data to be transfered to the host
WORD length | the number of bytes to be transfered
Application Programming Interface (API) > Device/Peripheral > CCID (Smart/Sim Card) Function Driver > Interface Routines > USBCCIDSendDataToHost Function


USBCheckCCIDRequest Function

Contents | Index | Home
Previous | Up | Next
USBCheckCCIDRequest Function
C
void USBCheckCCIDRequest();
Description

This routine checks the setup data packet to see if it knows how to handle it

Preconditions

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > CCID (Smart/Sim Card) Function Driver > Interface Routines > USBCheckCCIDRequest Function


CDC Function Driver

Contents | Index | Home
Previous | Up | Next
CDC Function Driver
Topics
Name | Description
Interface Routines |
Data Types and Constants |
Application Programming Interface (API) > Device/Peripheral > CDC Function Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
CDCInitEP | This function initializes the CDC function driver. This function should be called after the SET_CONFIGURATION command (ex: within the context of the USBCBInitEP() function).
CDCTxService | CDCTxService handles device-to-host transaction(s). This function should be called once per Main Program loop after the device reaches the configured state.
getsUSBUSART | getsUSBUSART copies a string of BYTEs received through USB CDC Bulk OUT endpoint to a user's specified location. It is a non-blocking function. It does not wait for data if there is no data available. Instead it returns '0' to notify the caller that there is no data available.
putrsUSBUSART | putrsUSBUSART writes a string of data to the USB including the null character. Use this version, 'putrs', to transfer data literals and data located in program memory.
putsUSBUSART | putsUSBUSART writes a string of data to the USB including the null character. Use this version, 'puts', to transfer data from a RAM buffer.
putUSBUSART | putUSBUSART writes an array of data to the USB. Use this version, is capable of transfering 0x00 (what is typically a NULL character in any of the string transfer functions).
USBCheckCDCRequest | This routine checks the most recently received SETUP data packet to see if the request is specific to the CDC class. If the request was a CDC specific request, this function will take care of handling the request and responding appropriately.
Macros
Name | Description
CDCSetBaudRate | This macro is used set the baud rate reported back to the host during a get line coding request. (optional)
CDCSetCharacterFormat | This macro is used manually set the character format reported back to the host during a get line coding request. (optional)
CDCSetDataSize | This function is used manually set the number of data bits reported back to the host during a get line coding request. (optional)
CDCSetLineCoding | This function is used to manually set the data reported back to the host during a get line coding request. (optional)
CDCSetParity | This function is used manually set the parity format reported back to the host during a get line coding request. (optional)
USBUSARTIsTxTrfReady | This macro is used to check if the CDC class is ready to send more data.
Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Interface Routines


CDCInitEP Function

Contents | Index | Home
Previous | Up | Next
CDCInitEP Function
C
void CDCInitEP();
Description

This function initializes the CDC function driver. This function sets the default line coding (baud rate, bit parity, number of data bits, and format). This function also enables the endpoints and prepares for the first transfer from the host.

This function should be called after the SET_CONFIGURATION command. This is most simply done by calling this function from the USBCBInitEP() function.

Typical Usage:

Copy Code
    void USBCBInitEP(void)
    {
        CDCInitEP();
    }
Preconditions

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Interface Routines > CDCInitEP Function


CDCTxService Function

Contents | Index | Home
Previous | Up | Next
CDCTxService Function
C
void CDCTxService();
Description

CDCTxService handles device-to-host transaction(s). This function should be called once per Main Program loop after the device reaches the configured state (after the CDCIniEP() function has already executed). This function is needed, in order to advance the internal software state machine that takes care of sending multiple transactions worth of IN USB data to the host, associated with CDC serial data. Failure to call CDCTxService() perioidcally will prevent data from being sent to the USB host, over the CDC serial data interface.

Typical Usage:

Copy Code
void main(void)
{
    USBDeviceInit();
    while(1)
    {
        USBDeviceTasks();
        if((USBGetDeviceState() < CONFIGURED_STATE) ||
           (USBIsDeviceSuspended() == TRUE))
        {
            //Either the device is not configured or we are suspended
            //  so we don't want to do execute any application code
            continue;   //go back to the top of the while loop
        }
        else
        {
            //Keep trying to send data to the PC as required
            CDCTxService();

            //Run application code.
            UserApplication();
        }
    }
}
Preconditions

CDCIniEP() function should have already exectuted/the device should be in the CONFIGURED_STATE.

Remarks

None

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Interface Routines > CDCTxService Function


getsUSBUSART Function

Contents | Index | Home
Previous | Up | Next
getsUSBUSART Function
C
BYTE getsUSBUSART(
    char * buffer,
    BYTE len
);
Description

getsUSBUSART copies a string of BYTEs received through USB CDC Bulk OUT endpoint to a user's specified location. It is a non-blocking function. It does not wait for data if there is no data available. Instead it returns '0' to notify the caller that there is no data available.

Typical Usage:

Copy Code
    BYTE numBytes;
    BYTE buffer[64]

    numBytes = getsUSBUSART(buffer,sizeof(buffer)); //until the buffer is free.
    if(numBytes > 0)
    {
        //we received numBytes bytes of data and they are copied into
        //  the "buffer" variable.  We can do something with the data
        //  here.
    }
Preconditions

Value of input argument 'len' should be smaller than the maximum endpoint size responsible for receiving bulk data from USB host for CDC class. Input argument 'buffer' should point to a buffer area that is bigger or equal to the size specified by 'len'.

Parameters
Parameters | Description
buffer | Pointer to where received BYTEs are to be stored
len | The number of BYTEs expected.
Returns

BYTE - Returns a byte indicating the total number of bytes that were actually received and copied into the specified buffer. The returned value can be anything from 0 up to the len input value. A return value of 0 indicates that no new CDC bulk OUT endpoint data was available.

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Interface Routines > getsUSBUSART Function


putrsUSBUSART Function

Contents | Index | Home
Previous | Up | Next
putrsUSBUSART Function
C
void putrsUSBUSART(
    const ROM char * data
);
Description

putrsUSBUSART writes a string of data to the USB including the null character. Use this version, 'putrs', to transfer data literals and data located in program memory.

Typical Usage:

Copy Code
    if(USBUSARTIsTxTrfReady())
    {
        putrsUSBUSART("Hello World");
    }

The transfer mechanism for device-to-host(put) is more flexible than host-to-device(get). It can handle a string of data larger than the maximum size of bulk IN endpoint. A state machine is used to transfer a long string of data over multiple USB transactions. CDCTxService() must be called periodically to keep sending blocks of data to the host.

Preconditions

USBUSARTIsTxTrfReady() must return TRUE. This indicates that the last transfer is complete and is ready to receive a new block of data. The string of characters pointed to by 'data' must equal to or smaller than 255 BYTEs.

Parameters
Parameters | Description
const ROM char *data | null-terminated string of constant data. If a null character is not found, 255 BYTEs of data will be transferred to the host.
Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Interface Routines > putrsUSBUSART Function


putsUSBUSART Function

Contents | Index | Home
Previous | Up | Next
putsUSBUSART Function
C
void putsUSBUSART(
    char * data
);
Description

putsUSBUSART writes a string of data to the USB including the null character. Use this version, 'puts', to transfer data from a RAM buffer.

Typical Usage:

Copy Code
    if(USBUSARTIsTxTrfReady())
    {
        char data[] = "Hello World";
        putsUSBUSART(data);
    }

The transfer mechanism for device-to-host(put) is more flexible than host-to-device(get). It can handle a string of data larger than the maximum size of bulk IN endpoint. A state machine is used to transfer a long string of data over multiple USB transactions. CDCTxService() must be called periodically to keep sending blocks of data to the host.

Preconditions

USBUSARTIsTxTrfReady() must return TRUE. This indicates that the last transfer is complete and is ready to receive a new block of data. The string of characters pointed to by 'data' must equal to or smaller than 255 BYTEs.

Parameters
Parameters | Description
char *data | null-terminated string of constant data. If a null character is not found, 255 BYTEs of data will be transferred to the host.
Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Interface Routines > putsUSBUSART Function


putUSBUSART Function

Contents | Index | Home
Previous | Up | Next
putUSBUSART Function
C
void putUSBUSART(
    char * data,
    BYTE Length
);
Description

putUSBUSART writes an array of data to the USB. Use this version, is capable of transfering 0x00 (what is typically a NULL character in any of the string transfer functions).

Typical Usage:

Copy Code
    if(USBUSARTIsTxTrfReady())
    {
        char data[] = {0x00, 0x01, 0x02, 0x03, 0x04};
        putUSBUSART(data,5);
    }

The transfer mechanism for device-to-host(put) is more flexible than host-to-device(get). It can handle a string of data larger than the maximum size of bulk IN endpoint. A state machine is used to transfer a long string of data over multiple USB transactions. CDCTxService() must be called periodically to keep sending blocks of data to the host.

Preconditions

USBUSARTIsTxTrfReady() must return TRUE. This indicates that the last transfer is complete and is ready to receive a new block of data. The string of characters pointed to by 'data' must equal to or smaller than 255 BYTEs.

Parameters
Parameters | Description
char *data | pointer to a RAM array of data to be transfered to the host
BYTE length | the number of bytes to be transfered (must be less than 255).
Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Interface Routines > putUSBUSART Function


USBCheckCDCRequest Function

Contents | Index | Home
Previous | Up | Next
USBCheckCDCRequest Function
C
void USBCheckCDCRequest();
Description

This routine checks the most recently received SETUP data packet to see if the request is specific to the CDC class. If the request was a CDC specific request, this function will take care of handling the request and responding appropriately.

Preconditions

This function should only be called after a control transfer SETUP packet has arrived from the host.

Remarks

This function does not change status or do anything if the SETUP packet did not contain a CDC class specific request.

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Interface Routines > USBCheckCDCRequest Function


CDCSetBaudRate Macro

Contents | Index | Home
Previous | Up | Next
CDCSetBaudRate Macro
C
#define CDCSetBaudRate(baudRate) {line_coding.dwDTERate.Val=baudRate;}
Description

This macro is used set the baud rate reported back to the host during a get line coding request.

Typical Usage:

Copy Code
    CDCSetBaudRate(19200);

This function is optional for CDC devices that do not actually convert the USB traffic to a hardware UART.

Preconditions

None

Parameters
Parameters | Description
DWORD baudRate | The desired baudrate
Remarks

None

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Interface Routines > CDCSetBaudRate Macro


CDCSetCharacterFormat Macro

Contents | Index | Home
Previous | Up | Next
CDCSetCharacterFormat Macro
C
#define CDCSetCharacterFormat(charFormat) {line_coding.bCharFormat=charFormat;}
Description

This macro is used manually set the character format reported back to the host during a get line coding request.

Typical Usage:

Copy Code
    CDCSetCharacterFormat(NUM_STOP_BITS_1);

This function is optional for CDC devices that do not actually convert the USB traffic to a hardware UART.

Preconditions

None

Parameters
Parameters
Description
BYTE charFormat
number of stop bits. Available options are:
  • NUM_STOP_BITS_1 - 1 Stop bit
  • NUM_STOP_BITS_1_5 - 1.5 Stop bits
  • NUM_STOP_BITS_2 - 2 Stop bits
Remarks

None

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Interface Routines > CDCSetCharacterFormat Macro


CDCSetDataSize Macro

Contents | Index | Home
Previous | Up | Next
CDCSetDataSize Macro
C
#define CDCSetDataSize(dataBits) {line_coding.bDataBits=dataBits;}
Description

This function is used manually set the number of data bits reported back to the host during a get line coding request.

Typical Usage:

Copy Code
    CDCSetDataSize(8);

This function is optional for CDC devices that do not actually convert the USB traffic to a hardware UART.

Preconditions

None

Parameters
Parameters | Description
BYTE dataBits | number of data bits. The options are 5, 6, 7, 8, or 16.
Remarks

None

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Interface Routines > CDCSetDataSize Macro


CDCSetLineCoding Macro

Contents | Index | Home
Previous | Up | Next
CDCSetLineCoding Macro
C
#define CDCSetLineCoding(baud,format,parity,dataSize) {\
            CDCSetBaudRate(baud);\
            CDCSetCharacterFormat(format);\
            CDCSetParity(parity);\
            CDCSetDataSize(dataSize);\
        }
Description

This function is used to manually set the data reported back to the host during a get line coding request.

Typical Usage:

Copy Code
    CDCSetLineCoding(19200, NUM_STOP_BITS_1, PARITY_NONE, 8);

This function is optional for CDC devices that do not actually convert the USB traffic to a hardware UART.

Preconditions

None

Parameters
Parameters
Description
DWORD baud
The desired baudrate
BYTE format
number of stop bits. Available options are:
  • NUM_STOP_BITS_1 - 1 Stop bit
  • NUM_STOP_BITS_1_5 - 1.5 Stop bits
  • NUM_STOP_BITS_2 - 2 Stop bits
BYTE parity
Type of parity. The options are the following:
  • PARITY_NONE
  • PARITY_ODD
  • PARITY_EVEN
  • PARITY_MARK
  • PARITY_SPACE
BYTE dataSize
number of data bits. The options are 5, 6, 7, 8, or 16.
Remarks

None

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Interface Routines > CDCSetLineCoding Macro


CDCSetParity Macro

Contents | Index | Home
Previous | Up | Next
CDCSetParity Macro
C
#define CDCSetParity(parityType) {line_coding.bParityType=parityType;}
Description

This macro is used manually set the parity format reported back to the host during a get line coding request.

Typical Usage:

Copy Code
    CDCSetParity(PARITY_NONE);

This function is optional for CDC devices that do not actually convert the USB traffic to a hardware UART.

Preconditions

None

Parameters
Parameters
Description
BYTE parityType
Type of parity. The options are the following:
  • PARITY_NONE
  • PARITY_ODD
  • PARITY_EVEN
  • PARITY_MARK
  • PARITY_SPACE
Remarks

None

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Interface Routines > CDCSetParity Macro


USBUSARTIsTxTrfReady Macro

Contents | Index | Home
Previous | Up | Next
USBUSARTIsTxTrfReady Macro
C
#define USBUSARTIsTxTrfReady (cdc_trf_state == CDC_TX_READY)
Description

This macro is used to check if the CDC class handler firmware is ready to send more data to the host over the CDC bulk IN endpoint.

Typical Usage:

Copy Code
    if(USBUSARTIsTxTrfReady())
    {
        putrsUSBUSART("Hello World");
    }
Preconditions

The return value of this function is only valid if the device is in a configured state (i.e. - USBDeviceGetState() returns CONFIGURED_STATE)

Remarks

Make sure the application periodically calls the CDCTxService() handler, or pending USB IN transfers will not be able to advance and complete.

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Interface Routines > USBUSARTIsTxTrfReady Macro


Data Types and Constants

Contents | Index | Home
Previous | Up | Next
Data Types and Constants
Macros
Name | Description
NUM_STOP_BITS_1 | 1 stop bit - used by CDCSetLineCoding() and CDCSetCharacterFormat()
NUM_STOP_BITS_1_5 | 1.5 stop bit - used by CDCSetLineCoding() and CDCSetCharacterFormat()
NUM_STOP_BITS_2 | 2 stop bit - used by CDCSetLineCoding() and CDCSetCharacterFormat()
PARITY_EVEN | even parity - used by CDCSetLineCoding() and CDCSetParity()
PARITY_MARK | mark parity - used by CDCSetLineCoding() and CDCSetParity()
PARITY_NONE | no parity - used by CDCSetLineCoding() and CDCSetParity()
PARITY_ODD | odd parity - used by CDCSetLineCoding() and CDCSetParity()
PARITY_SPACE | space parity - used by CDCSetLineCoding() and CDCSetParity()
Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Data Types and Constants


NUM_STOP_BITS_1 Macro

Contents | Index | Home
Previous | Up | Next
NUM_STOP_BITS_1 Macro
C
#define NUM_STOP_BITS_1 0   //1 stop bit - used by CDCSetLineCoding() and CDCSetCharacterFormat()
Description

1 stop bit - used by CDCSetLineCoding() and CDCSetCharacterFormat()

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Data Types and Constants > NUM_STOP_BITS_1 Macro


NUM_STOP_BITS_1_5 Macro

Contents | Index | Home
Previous | Up | Next
NUM_STOP_BITS_1_5 Macro
C
#define NUM_STOP_BITS_1_5 1   //1.5 stop bit - used by CDCSetLineCoding() and CDCSetCharacterFormat()
Description

1.5 stop bit - used by CDCSetLineCoding() and CDCSetCharacterFormat()

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Data Types and Constants > NUM_STOP_BITS_1_5 Macro


NUM_STOP_BITS_2 Macro

Contents | Index | Home
Previous | Up | Next
NUM_STOP_BITS_2 Macro
C
#define NUM_STOP_BITS_2 2   //2 stop bit - used by CDCSetLineCoding() and CDCSetCharacterFormat()
Description

2 stop bit - used by CDCSetLineCoding() and CDCSetCharacterFormat()

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Data Types and Constants > NUM_STOP_BITS_2 Macro


PARITY_EVEN Macro

Contents | Index | Home
Previous | Up | Next
PARITY_EVEN Macro
C
#define PARITY_EVEN 2 //even parity - used by CDCSetLineCoding() and CDCSetParity()
Description

even parity - used by CDCSetLineCoding() and CDCSetParity()

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Data Types and Constants > PARITY_EVEN Macro


PARITY_MARK Macro

Contents | Index | Home
Previous | Up | Next
PARITY_MARK Macro
C
#define PARITY_MARK 3 //mark parity - used by CDCSetLineCoding() and CDCSetParity()
Description

mark parity - used by CDCSetLineCoding() and CDCSetParity()

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Data Types and Constants > PARITY_MARK Macro


PARITY_NONE Macro

Contents | Index | Home
Previous | Up | Next
PARITY_NONE Macro
C
#define PARITY_NONE 0 //no parity - used by CDCSetLineCoding() and CDCSetParity()
Description

no parity - used by CDCSetLineCoding() and CDCSetParity()

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Data Types and Constants > PARITY_NONE Macro


PARITY_ODD Macro

Contents | Index | Home
Previous | Up | Next
PARITY_ODD Macro
C
#define PARITY_ODD 1 //odd parity - used by CDCSetLineCoding() and CDCSetParity()
Description

odd parity - used by CDCSetLineCoding() and CDCSetParity()

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Data Types and Constants > PARITY_ODD Macro


PARITY_SPACE Macro

Contents | Index | Home
Previous | Up | Next
PARITY_SPACE Macro
C
#define PARITY_SPACE 4 //space parity - used by CDCSetLineCoding() and CDCSetParity()
Description

space parity - used by CDCSetLineCoding() and CDCSetParity()

Application Programming Interface (API) > Device/Peripheral > CDC Function Driver > Data Types and Constants > PARITY_SPACE Macro


HID Function Driver

Contents | Index | Home
Previous | Up | Next
HID Function Driver
Topics
Name | Description
Interface Routines |
Data Types and Constants |
Application Programming Interface (API) > Device/Peripheral > HID Function Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Macros
Name | Description
HIDRxHandleBusy | Retreives the status of the buffer ownership
HIDRxPacket | Receives the specified data out the specified endpoint
HIDTxHandleBusy | Retreives the status of the buffer ownership
HIDTxPacket | Sends the specified data out the specified endpoint
Application Programming Interface (API) > Device/Peripheral > HID Function Driver > Interface Routines


HIDRxHandleBusy Macro

Contents | Index | Home
Previous | Up | Next
HIDRxHandleBusy Macro
C
#define HIDRxHandleBusy(handle) USBHandleBusy(handle)
Description

Retreives the status of the buffer ownership. This function will indicate if the previous transfer is complete or not.

This function will take the input handle (pointer to a BDT entry) and will check the UOWN bit. If the UOWN bit is set then that indicates that the transfer is not complete and the USB module still owns the data memory. If the UOWN bit is clear that means that the transfer is complete and that the CPU now owns the data memory.

For more information about the BDT, please refer to the appropriate datasheet for the device in use.

Typical Usage:

Copy Code
if(!HIDRxHandleBusy(USBOutHandle))
{
    //The data is available in the buffer that was specified when the
    //  HIDRxPacket() was called.
}
Preconditions

None

Parameters
Parameters | Description
USB_HANDLE handle | the handle for the transfer in question. The handle is returned by the HIDTxPacket() and HIDRxPacket() functions. Please insure that USB_HANDLE objects are initialized to NULL.
Return Values
Return Values | Description
TRUE | the HID handle is still busy
FALSE | the HID handle is not busy and is ready to receive additional data.
Remarks

None

Application Programming Interface (API) > Device/Peripheral > HID Function Driver > Interface Routines > HIDRxHandleBusy Macro


HIDRxPacket Macro

Contents | Index | Home
Previous | Up | Next
HIDRxPacket Macro
C
#define HIDRxPacket USBRxOnePacket
Description

Receives the specified data out the specified endpoint.

Typical Usage:

Copy Code
//Read 64-bytes from endpoint HID_EP, into the ReceivedDataBuffer array.
//  Make sure to save the return handle so that we can check it later
//  to determine when the transfer is complete.
USBOutHandle = HIDRxPacket(HID_EP,(BYTE*)&ReceivedDataBuffer,64);
Preconditions

None

Parameters
Parameters | Description
BYTE ep | the endpoint you want to receive the data into
BYTE* data | pointer to where the data will go when it arrives
WORD len | the length of the data that you wish to receive
Return Values
Return Values | Description
USB_HANDLE | a handle for the transfer. This information should be kept to track the status of the transfer
Remarks

None

Application Programming Interface (API) > Device/Peripheral > HID Function Driver > Interface Routines > HIDRxPacket Macro


HIDTxHandleBusy Macro

Contents | Index | Home
Previous | Up | Next
HIDTxHandleBusy Macro
C
#define HIDTxHandleBusy(handle) USBHandleBusy(handle)
Description

Retreives the status of the buffer ownership. This function will indicate if the previous transfer is complete or not.

This function will take the input handle (pointer to a BDT entry) and will check the UOWN bit. If the UOWN bit is set then that indicates that the transfer is not complete and the USB module still owns the data memory. If the UOWN bit is clear that means that the transfer is complete and that the CPU now owns the data memory.

For more information about the BDT, please refer to the appropriate datasheet for the device in use.

Typical Usage:

Copy Code
//make sure that the last transfer isn't busy by checking the handle
if(!HIDTxHandleBusy(USBInHandle))
{
    //Send the data contained in the ToSendDataBuffer[] array out on
    //  endpoint HID_EP
    USBInHandle = HIDTxPacket(HID_EP,(BYTE*)&ToSendDataBuffer[0],sizeof(ToSendDataBuffer));
}
Preconditions

None.

Parameters
Parameters | Description
USB_HANDLE handle | the handle for the transfer in question. The handle is returned by the HIDTxPacket() and HIDRxPacket() functions. Please insure that USB_HANDLE objects are initialized to NULL.
Return Values
Return Values | Description
TRUE | the HID handle is still busy
FALSE | the HID handle is not busy and is ready to send additional data.
Remarks

None

Application Programming Interface (API) > Device/Peripheral > HID Function Driver > Interface Routines > HIDTxHandleBusy Macro


HIDTxPacket Macro

Contents | Index | Home
Previous | Up | Next
HIDTxPacket Macro
C
#define HIDTxPacket USBTxOnePacket
Description

This function sends the specified data out the specified endpoint and returns a handle to the transfer information.

Typical Usage:

Copy Code
//make sure that the last transfer isn't busy by checking the handle
if(!HIDTxHandleBusy(USBInHandle))
{
    //Send the data contained in the ToSendDataBuffer[] array out on
    //  endpoint HID_EP
    USBInHandle = HIDTxPacket(HID_EP,(BYTE*)&ToSendDataBuffer[0],sizeof(ToSendDataBuffer));
}
Preconditions

None

Parameters
Parameters | Description
BYTE ep | the endpoint you want to send the data out of
BYTE* data | pointer to the data that you wish to send
WORD len | the length of the data that you wish to send
Return Values
Return Values | Description
USB_HANDLE | a handle for the transfer. This information should be kept to track the status of the transfer
Remarks

None

Application Programming Interface (API) > Device/Peripheral > HID Function Driver > Interface Routines > HIDTxPacket Macro


Data Types and Constants

Contents | Index | Home
Previous | Up | Next
Data Types and Constants
Macros
Name | Description
BOOT_INTF_SUBCLASS | HID Interface Class SubClass Codes
BOOT_PROTOCOL | Protocol Selection
HID_PROTOCOL_KEYBOARD | This is macro HID_PROTOCOL_KEYBOARD.
HID_PROTOCOL_MOUSE | This is macro HID_PROTOCOL_MOUSE.
HID_PROTOCOL_NONE | HID Interface Class Protocol Codes
Application Programming Interface (API) > Device/Peripheral > HID Function Driver > Data Types and Constants


BOOT_INTF_SUBCLASS Macro

Contents | Index | Home
Previous | Up | Next
BOOT_INTF_SUBCLASS Macro
C
#define BOOT_INTF_SUBCLASS 0x01
Description

HID Interface Class SubClass Codes

Application Programming Interface (API) > Device/Peripheral > HID Function Driver > Data Types and Constants > BOOT_INTF_SUBCLASS Macro


BOOT_PROTOCOL Macro

Contents | Index | Home
Previous | Up | Next
BOOT_PROTOCOL Macro
C
#define BOOT_PROTOCOL 0x00
Description

Protocol Selection

Application Programming Interface (API) > Device/Peripheral > HID Function Driver > Data Types and Constants > BOOT_PROTOCOL Macro


HID_PROTOCOL_KEYBOARD Macro

Contents | Index | Home
Previous | Up | Next
HID_PROTOCOL_KEYBOARD Macro
C
#define HID_PROTOCOL_KEYBOARD 0x01
Description

This is macro HID_PROTOCOL_KEYBOARD.

Application Programming Interface (API) > Device/Peripheral > HID Function Driver > Data Types and Constants > HID_PROTOCOL_KEYBOARD Macro


HID_PROTOCOL_MOUSE Macro

Contents | Index | Home
Previous | Up | Next
HID_PROTOCOL_MOUSE Macro
C
#define HID_PROTOCOL_MOUSE 0x02
Description

This is macro HID_PROTOCOL_MOUSE.

Application Programming Interface (API) > Device/Peripheral > HID Function Driver > Data Types and Constants > HID_PROTOCOL_MOUSE Macro


HID_PROTOCOL_NONE Macro

Contents | Index | Home
Previous | Up | Next
HID_PROTOCOL_NONE Macro
C
#define HID_PROTOCOL_NONE 0x00
Description

HID Interface Class Protocol Codes

Application Programming Interface (API) > Device/Peripheral > HID Function Driver > Data Types and Constants > HID_PROTOCOL_NONE Macro


MSD Function Driver

Contents | Index | Home
Previous | Up | Next
MSD Function Driver
Topics
Name | Description
Interface Routines |
Data Types and Constants |
Application Programming Interface (API) > Device/Peripheral > MSD Function Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
MSDTasks | This is function MSDTasks.
USBCheckMSDRequest |
USBMSDInit | This is function USBMSDInit.
Application Programming Interface (API) > Device/Peripheral > MSD Function Driver > Interface Routines


MSDTasks Function

Contents | Index | Home
Previous | Up | Next
MSDTasks Function
C
BYTE MSDTasks();
Description

This is function MSDTasks.

Application Programming Interface (API) > Device/Peripheral > MSD Function Driver > Interface Routines > MSDTasks Function


USBCheckMSDRequest Function

Contents | Index | Home
Previous | Up | Next
USBCheckMSDRequest Function
C
void USBCheckMSDRequest();
Application Programming Interface (API) > Device/Peripheral > MSD Function Driver > Interface Routines > USBCheckMSDRequest Function


USBMSDInit Function

Contents | Index | Home
Previous | Up | Next
USBMSDInit Function
C
void USBMSDInit();
Description

This is function USBMSDInit.

Application Programming Interface (API) > Device/Peripheral > MSD Function Driver > Interface Routines > USBMSDInit Function


Data Types and Constants

Contents | Index | Home
Previous | Up | Next
Data Types and Constants
Types
Name | Description
LUN_FUNCTIONS | LUN_FUNCTIONS is a structure of function pointers that tells the stack where to find each of the physical layer functions it is looking for. This structure needs to be defined for any project for PIC24F or PIC32.
Application Programming Interface (API) > Device/Peripheral > MSD Function Driver > Data Types and Constants


LUN_FUNCTIONS Type

Contents | Index | Home
Previous | Up | Next
LUN_FUNCTIONS Type
C
typedef struct LUN_FUNCTIONS@1 LUN_FUNCTIONS;
Description

LUN_FUNCTIONS is a structure of function pointers that tells the stack where to find each of the physical layer functions it is looking for. This structure needs to be defined for any project for PIC24F or PIC32.

Typical Usage:

Copy Code
    LUN_FUNCTIONS LUN[MAX_LUN + 1] =
    {
        {
            &MDD_SDSPI_MediaInitialize,
            &MDD_SDSPI_ReadCapacity,
            &MDD_SDSPI_ReadSectorSize,
            &MDD_SDSPI_MediaDetect,
            &MDD_SDSPI_SectorRead,
            &MDD_SDSPI_WriteProtectState,
            &MDD_SDSPI_SectorWrite
        }
    };

In the above code we are passing the address of the SDSPI functions to the corresponding member of the LUN_FUNCTIONS structure. In the above case we have created an array of LUN_FUNCTIONS structures so that it is possible to have multiple physical layers by merely increasing the MAX_LUN variable and by adding one more set of entries in the array. Please take caution to insure that each function is in the the correct location in the structure. Incorrect alignment will cause the USB stack to call the incorrect function for a given command.

See the MDD File System Library for additional information about the available physical media, their requirements, and how to use their associated functions.

Application Programming Interface (API) > Device/Peripheral > MSD Function Driver > Data Types and Constants > LUN_FUNCTIONS Type


Personal Healthcare Device Class (PHDC) Function Driver

Contents | Index | Home
Previous | Up | Next
Personal Healthcare Device Class (PHDC) Function Driver
Topics
Name | Description
Interface Routines |
Application Programming Interface (API) > Device/Peripheral > Personal Healthcare Device Class (PHDC) Function Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
PHDAppInit | This function is used to initialize the PHD stack.
PHDSendAppBufferPointer | This function is used to send measurement data to the PHD Manager.
PHDConnect | This function is used to connect to the PHD Manager.
PHDDisConnect | This function is used to disconnect from the PHD Manager.
PHDSendMeasuredData | This function is used to send measurement data to the PHD Manager.
PHDTimeoutHandler | This function is used to handle all timeout.
USBDevicePHDCInit | This function initializes the PHDC function driver. This function should be called after the SET_CONFIGURATION command.
USBDevicePHDCReceiveData | USBDevicePHDCReceiveData copies a string of BYTEs received through USB PHDC Bulk OUT endpoint to a user's specified location. It is a non-blocking function. It does not wait for data if there is no data available. Instead it returns '0' to notify the caller that there is no data available.
USBDevicePHDCSendData | USBDevicePHDCSendData writes an array of data to the USB.
USBDevicePHDCTxRXService | USBDevicePHDCTxRXService handles device-to-host transaction(s) and host-to-device transaction(s). This function should be called once per Main Program loop after the device reaches the configured state.
USBDevicePHDCCheckRequest | This routine checks the setup data packet to see if it is class specific request or vendor specific request and handles it
USBDevicePHDCUpdateStatus | USBDevicePHDCUpdateStatus Function Gets the current status of an Endpoint and holds the status in variable phdcEpDataBitmap. The Status is sent to the host upon the "Get Data Status" request from the host.
Application Programming Interface (API) > Device/Peripheral > Personal Healthcare Device Class (PHDC) Function Driver > Interface Routines


PHDAppInit Function

Contents | Index | Home
Previous | Up | Next
PHDAppInit Function
C
void PHDAppInit(
    PHDC_APP_CB
);
Description

This function initializes all the application related items. The input to the function is address of the callback function. This callback function which will be called by PHD stack when there is a change in Agent's connection status.

Preconditions

None

Parameters
Parameters | Description
PHDC_APP_CB callback | Pointer to application Call Back Function.
Returns

None

Side Effects

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Personal Healthcare Device Class (PHDC) Function Driver > Interface Routines > PHDAppInit Function


PHDSendAppBufferPointer Function

Contents | Index | Home
Previous | Up | Next
PHDSendAppBufferPointer Function
C
void PHDSendAppBufferPointer(
    UINT8 * pAppBuffer
);
Description

This function passes the application buffer pointer to the PHD stack. The PHD stack uses this pointer send and receive data through the transport layer.

Parameters
Parameters | Description
UINT8 *pAppBuffer | Pointer to Application Buffer.
Returns

None

Side Effects

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Personal Healthcare Device Class (PHDC) Function Driver > Interface Routines > PHDSendAppBufferPointer Function


PHDConnect Function

Contents | Index | Home
Previous | Up | Next
PHDConnect Function
C
void PHDConnect();
Description

This function initiates connection to the PHD Manager by sending an Association request to manager. The Agent doesn't get connected to the Manager immediately after calling this function. Upon receiving the association request from an Agent, the PHD Manager responds with an association response. The association response tells whether Manager accepting the request or rejecting it. The Association response from the Manager is handled by the PHD stack. The PHD stack calls a callback function (void(* PHDC_APP_CB)(UINT8)) to the application with status of the connection. The Manager should respond to the Agent within the specified timeout of ASSOCIATION_REQUEST_TIMEOUT. The Agent should send the Association request once more if no response is received from Manager and ASSOCIATION_REQUEST_TIMEOUT is expired. This function starts a Timer for the Association Timeout request. The timeout is handled by the PHDTimeoutHandler() function.

Preconditions

The agent should be in PHD_INITIALIZED state.

Returns

None

Side Effects

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Personal Healthcare Device Class (PHDC) Function Driver > Interface Routines > PHDConnect Function


PHDDisConnect Function

Contents | Index | Home
Previous | Up | Next
PHDDisConnect Function
C
void PHDDisConnect();
Description

This function initiates disconnection of the Agent from the PHD Manager by sending an Release request to manager. The Agent doesn't get disconnected from the Manager immediately after calling this function. The PHD Manager sends back a release response to the Agent. The Agent responds back with an Abort Message and the Agent moves to DISCONNECTED state. The PHD stack calls a callback function (void(* PHDC_APP_CB)(UINT8)) to the application with status of the connection. This function disables all timeout.

Preconditions

None.

Returns

None

Side Effects

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Personal Healthcare Device Class (PHDC) Function Driver > Interface Routines > PHDDisConnect Function


PHDSendMeasuredData Function

Contents | Index | Home
Previous | Up | Next
PHDSendMeasuredData Function
C
void PHDSendMeasuredData();
Description

This function sends measurement data to manager. Before calling this function the caller should fill the Application buffer with the data to send. The Agent expects a Confirmation from the Manager for the data sent. This confirmation should arrive at the Agent within a specified time of CONFIRM_TIMEOUT. The function starts a Timer to see if the Confirmation from the Manager arrives within specified time. The timeout is handled by the PHDTimeoutHandler() function.

Preconditions

Before calling this function the caller should fill the Application buffer with the data to send.

Returns

None

Side Effects

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Personal Healthcare Device Class (PHDC) Function Driver > Interface Routines > PHDSendMeasuredData Function


PHDTimeoutHandler Function

Contents | Index | Home
Previous | Up | Next
PHDTimeoutHandler Function
C
void PHDTimeoutHandler();
Description

This function handles all timers. This function should be called once in every milli Second.

Preconditions

None

Returns

None

Side Effects

None

Remarks

If USB is used at the Transport layer then the USB SOF handler can call this function.

Application Programming Interface (API) > Device/Peripheral > Personal Healthcare Device Class (PHDC) Function Driver > Interface Routines > PHDTimeoutHandler Function


USBDevicePHDCInit Function

Contents | Index | Home
Previous | Up | Next
USBDevicePHDCInit Function
C
void USBDevicePHDCInit(
    USB_PHDC_CB
);
Description

This function initializes the PHDC function driver. This function sets the default line coding (baud rate, bit parity, number of data bits, and format). This function also enables the endpoints and prepares for the first transfer from the host.

This function should be called after the SET_CONFIGURATION command. This is most simply done by calling this function from the USBCBInitEP() function.

Typical Usage:

Copy Code
    void USBCBInitEP(void)
    {
        PHDCInitEP();
    }
Preconditions

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Personal Healthcare Device Class (PHDC) Function Driver > Interface Routines > USBDevicePHDCInit Function


USBDevicePHDCReceiveData Function

Contents | Index | Home
Previous | Up | Next
USBDevicePHDCReceiveData Function
C
UINT8 USBDevicePHDCReceiveData(
    UINT8 qos,
    UINT8 * buffer,
    UINT16 len
);
Description

USBDevicePHDCReceiveData copies a string of BYTEs received through USB PHDC Bulk OUT endpoint to a user's specified location. It is a non-blocking function. It does not wait for data if there is no data available. Instead it returns '0' to notify the caller that there is no data available.

Typical Usage:

Copy Code
    BYTE numBytes;
    BYTE buffer[64]

    numBytes = USBDevicePHDCReceiveData(buffer,sizeof(buffer)); //until the buffer is free.
    if(numBytes > 0)
    {
        //we received numBytes bytes of data and they are copied into
        //  the "buffer" variable.  We can do something with the data
        //  here.
    }
Preconditions

Value of input argument 'len' should be smaller than the maximum endpoint size responsible for receiving bulk data from USB host for PHDC class. Input argument 'buffer' should point to a buffer area that is bigger or equal to the size specified by 'len'.

Parameters
Parameters | Description
qos | quality of service
buffer | Pointer to where received BYTEs are to be stored
len | The number of BYTEs expected.
Application Programming Interface (API) > Device/Peripheral > Personal Healthcare Device Class (PHDC) Function Driver > Interface Routines > USBDevicePHDCReceiveData Function


USBDevicePHDCSendData Function

Contents | Index | Home
Previous | Up | Next
USBDevicePHDCSendData Function
C
void USBDevicePHDCSendData(
    UINT8 qos,
    UINT8 * data,
    UINT16 length,
    BOOL memtype
);
Description

USBDevicePHDCSendData writes an array of data to the USB.

Typical Usage:

Copy Code
    if(USBUSARTIsTxTrfReady())
    {
        char data[] = {0x00, 0x01, 0x02, 0x03, 0x04};
        USBDevicePHDCSendData(1,data,5);
    }

The transfer mechanism for device-to-host(put) is more flexible than host-to-device(get). It can handle a string of data larger than the maximum size of bulk IN endpoint. A state machine is used to transfer a long string of data over multiple USB transactions. USBDevicePHDCTxRXService() must be called periodically to keep sending blocks of data to the host.

Preconditions

USBUSARTIsTxTrfReady() must return TRUE. This indicates that the last transfer is complete and is ready to receive a new block of data.

Parameters
Parameters | Description
qos | Quality of service information
*data | pointer to a RAM array of data to be transfered to the host
length | the number of bytes to be transfered.
Application Programming Interface (API) > Device/Peripheral > Personal Healthcare Device Class (PHDC) Function Driver > Interface Routines > USBDevicePHDCSendData Function


USBDevicePHDCTxRXService Function

Contents | Index | Home
Previous | Up | Next
USBDevicePHDCTxRXService Function
C
void USBDevicePHDCTxRXService(
    USTAT_FIELDS* event
);
Description

USBDevicePHDCTxRXService handles device-to-host transaction(s) and host-to-device transaction(s). This function should be called once per Main Program loop after the device reaches the configured state.

Typical Usage:

Copy Code
void main(void)
{
    USBDeviceInit();
    while(1)
    {
        USBDeviceTasks();
        if((USBGetDeviceState() < CONFIGURED_STATE) ||
           (USBIsDeviceSuspended() == TRUE))
        {
            //Either the device is not configured or we are suspended
            //  so we don't want to do execute any application code
            continue;   //go back to the top of the while loop
        }
        else
        {
            //Keep trying to send data to the PC as required
            USBDevicePHDCTxRXService();

            //Run application code.
            UserApplication();
        }
    }
}
Preconditions

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Personal Healthcare Device Class (PHDC) Function Driver > Interface Routines > USBDevicePHDCTxRXService Function


USBDevicePHDCCheckRequest Function

Contents | Index | Home
Previous | Up | Next
USBDevicePHDCCheckRequest Function
C
void USBDevicePHDCCheckRequest();
Description

This routine checks the setup data packet to see if it is class specific request or vendor specific request and handles it

Preconditions

None

Remarks

None

Application Programming Interface (API) > Device/Peripheral > Personal Healthcare Device Class (PHDC) Function Driver > Interface Routines > USBDevicePHDCCheckRequest Function


USBDevicePHDCUpdateStatus Function

Contents | Index | Home
Previous | Up | Next
USBDevicePHDCUpdateStatus Function
C
void USBDevicePHDCUpdateStatus(
    WORD EndpointNo,
    BIT Status
);
Description

USBDevicePHDCUpdateStatus Function helps to handle the "Get Data Status" PHDC specfic request received from the Host as mentioned in the section 7.1.2 of the Personal Healthcare Devices Specification. This function Gets the current status of an Endpoint and holds the status in variable phdcEpDataBitmap.

Preconditions

None

Parameters
Parameters | Description
WORD EndpointNo | The number of the endpoint, for which the status is requested.
BIT Status | Current status of the Endpoint.
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Personal Healthcare Device Class (PHDC) Function Driver > Interface Routines > USBDevicePHDCUpdateStatus Function


Vendor Class (Generic) Function Driver

Contents | Index | Home
Previous | Up | Next
Vendor Class (Generic) Function Driver
Topics
Name | Description
Interface Routines |
Application Programming Interface (API) > Device/Peripheral > Vendor Class (Generic) Function Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Macros
Name | Description
USBGenRead | Receives the specified data out the specified endpoint
USBGenWrite | Sends the specified data out the specified endpoint
Application Programming Interface (API) > Device/Peripheral > Vendor Class (Generic) Function Driver > Interface Routines


USBGenRead Macro

Contents | Index | Home
Previous | Up | Next
USBGenRead Macro
C
#define USBGenRead(ep,data,len) USBRxOnePacket(ep,data,len)
Description

Receives the specified data out the specified endpoint.

Typical Usage:

Copy Code
//Read 64-bytes from endpoint USBGEN_EP_NUM, into the OUTPacket array.
//  Make sure to save the return handle so that we can check it later
//  to determine when the transfer is complete.
if(!USBHandleBusy(USBOutHandle))
{
    USBOutHandle = USBGenRead(USBGEN_EP_NUM,(BYTE*)&OUTPacket,64);
}
Preconditions

None

Parameters
Parameters | Description
BYTE ep | the endpoint you want to receive the data into
BYTE* data | pointer to where the data will go when it arrives
WORD len | the length of the data that you wish to receive
Return Values
Return Values | Description
USB_HANDLE | a handle for the transfer. This information should be kept to track the status of the transfer
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Vendor Class (Generic) Function Driver > Interface Routines > USBGenRead Macro


USBGenWrite Macro

Contents | Index | Home
Previous | Up | Next
USBGenWrite Macro
C
#define USBGenWrite(ep,data,len) USBTxOnePacket(ep,data,len)
Description

This function sends the specified data out the specified endpoint and returns a handle to the transfer information.

Typical Usage:

Copy Code
//make sure that the last transfer isn't busy by checking the handle
if(!USBHandleBusy(USBGenericInHandle))
{
    //Send the data contained in the INPacket[] array out on
    //  endpoint USBGEN_EP_NUM
    USBGenericInHandle = USBGenWrite(USBGEN_EP_NUM,(BYTE*)&INPacket[0],sizeof(INPacket));
}
Preconditions

None

Parameters
Parameters | Description
BYTE ep | the endpoint you want to send the data out of
BYTE* data | pointer to the data that you wish to send
WORD len | the length of the data that you wish to send
Return Values
Return Values | Description
USB_HANDLE | a handle for the transfer. This information should be kept to track the status of the transfer
Remarks

None

Application Programming Interface (API) > Device/Peripheral > Vendor Class (Generic) Function Driver > Interface Routines > USBGenWrite Macro


Embedded Host API

Contents | Index | Home
Previous | Up | Next
Embedded Host API
Topics
Name | Description
Embedded Host Stack | The USB Embedded Host driver provides low-level USB functionality for all host client drivers.
Audio Client Driver |
Audio MIDI Client Driver |
Android Accessory Client Driver |
CDC Client Driver | This is a CDC client driver for use with the USB Embedded Host driver.
Charger Client Driver | This Client Driver gives an application the ability to charge the rechargeable batteries of many USB devices.
Generic Client Driver | This is a generic client driver for use with the USB Embedded Host driver.
HID Client Driver | This client driver provides USB Embedded Host support for HID devices.
Mass Storage Client Driver | This client driver provides USB Embedded Host support for mass storage devices.
Printer Client Driver | This client driver provides USB Embedded Host support for printer devices.
Application Programming Interface (API) > Embedded Host API


Embedded Host Stack

Contents | Index | Home
Previous | Up | Next
Embedded Host Stack

The USB Embedded Host driver provides low-level USB functionality for all host client drivers. This layer is responsible for enumerating devices, managing data transfers, and detecting device detach.

Typically, only host client drivers will interact with this layer. Applications can be configured to receive some events from this layer, such as EVENT_REQUEST_POWER and EVENT_RELEASE_POWER.

See AN1140 USB Embedded Host Stack for more information about this layer. See AN1141 USB Embedded Host Stack Programmer's Guide for more information about creating a client driver that uses this layer.

Topics
Name | Description
Interface Routines |
Data Types and Constants |
Macros |
Application Programming Interface (API) > Embedded Host API > Embedded Host Stack


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
USB_HOST_APP_EVENT_HANDLER | This is a typedef to use when defining the application level events handler.
USBHostClearEndpointErrors | This function clears an endpoint's internal error condition.
USBHostDeviceSpecificClientDriver | This function indicates if the specified device has explicit client driver support specified in the TPL.
USBHostDeviceStatus | This function returns the current status of a device.
USBHostInit | This function initializes the variables of the USB host stack.
USBHostRead | This function initiates a read from the attached device.
USBHostResetDevice | This function resets an attached device.
USBHostResumeDevice | This function issues a RESUME to the attached device.
USBHostSetDeviceConfiguration | This function changes the device's configuration.
USBHostSetNAKTimeout | This function specifies NAK timeout capability.
USBHostSuspendDevice | This function suspends a device.
USBHostTerminateTransfer | This function terminates the current transfer for the given endpoint.
USBHostTransferIsComplete | This function initiates whether or not the last endpoint transaction is complete.
USBHostVbusEvent | This function handles Vbus events that are detected by the application.
USBHostWrite | This function initiates a write to the attached device.
Macros
Name | Description
USBHostGetCurrentConfigurationDescriptor | This function returns a pointer to the current configuration descriptor of the requested device.
USBHostGetDeviceDescriptor | This function returns a pointer to the device descriptor of the requested device.
USBHostGetStringDescriptor | This routine initiates a request to obtains the requested string descriptor.
Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines


USB_HOST_APP_EVENT_HANDLER Function

Contents | Index | Home
Previous | Up | Next
USB_HOST_APP_EVENT_HANDLER Function
C
BOOL USB_HOST_APP_EVENT_HANDLER(
    BYTE address,
    USB_EVENT event,
    void * data,
    DWORD size
);
Description

This function is implemented by the application. The function name can be anything - the macro USB_HOST_APP_EVENT_HANDLER must be set in usb_config.h to the name of the application function.

In the application layer, this function is responsible for handling all application-level events that are generated by the stack. See the enumeration USB_EVENT for a complete list of all events that can occur. Note that some of these events are intended for client drivers (e.g. EVENT_TRANSFER), while some are intended for for the application layer (e.g. EVENT_UNSUPPORTED_DEVICE).

If the application can handle the event successfully, the function should return TRUE. For example, if the function receives the event EVENT_VBUS_REQUEST_POWER and the system can allocate that much power to an attached device, the function should return TRUE. If, however, the system cannot allocate that much power to an attached device, the function should return FALSE.

Preconditions

None

Parameters
Parameters | Description
BYTE address | Address of the USB device generating the event
USB_EVENT event | Event that occurred
void *data | Optional pointer to data for the event
DWORD size | Size of the data pointed to by *data
Return Values
Return Values | Description
TRUE | Event was processed successfully
FALSE | Event was not processed successfully
Remarks

If this function is not provided by the application, then all application events are assumed to function without error.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USB_HOST_APP_EVENT_HANDLER Function


USBHostClearEndpointErrors Function

Contents | Index | Home
Previous | Up | Next
USBHostClearEndpointErrors Function
C
BYTE USBHostClearEndpointErrors(
    BYTE deviceAddress,
    BYTE endpoint
);
Description

This function is called to clear the internal error condition of a device's endpoint. It should be called after the application has dealt with the error condition on the device. This routine clears internal status only; it does not interact with the device.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Address of device
BYTE endpoint | Endpoint to clear error condition
Return Values
Return Values | Description
USB_SUCCESS | Errors cleared
USB_UNKNOWN_DEVICE | Device not found
USB_ENDPOINT_NOT_FOUND | Specified endpoint not found
Remarks

None

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostClearEndpointErrors Function


USBHostDeviceSpecificClientDriver Function

Contents | Index | Home
Previous | Up | Next
USBHostDeviceSpecificClientDriver Function
C
BOOL USBHostDeviceSpecificClientDriver(
    BYTE deviceAddress
);
Description

This function indicates if the specified device has explicit client driver support specified in the TPL. It is used in client drivers' USB_CLIENT_INIT routines to indicate that the client driver should be used even though the class, subclass, and protocol values may not match those normally required by the class. For example, some printing devices do not fulfill all of the requirements of the printer class, so their class, subclass, and protocol fields indicate a custom driver rather than the printer class. But the printer class driver can still be used, with minor limitations.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Address of device
Return Values
Return Values | Description
TRUE | This device is listed in the TPL by VID andPID, and has explicit client driver support.
FALSE | This device is not listed in the TPL by VID and PID.
Remarks

This function is used so client drivers can allow certain devices to enumerate. For example, some printer devices indicate a custom class rather than the printer class, even though the device has only minor limitations from the full printer class. The printer client driver will fail to initialize the device if it does not indicate printer class support in its interface descriptor. The printer client driver could allow any device with an interface that matches the printer class endpoint configuration, but both printer and mass storage devices utilize one bulk IN and one bulk OUT endpoint. So a mass storage device would be erroneously initialized as a printer device. This function allows a client driver to know that the client driver support was specified explicitly in the TPL, so for this particular device only, the class, subclass, and protocol fields can be safely ignored.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostDeviceSpecificClientDriver Function


USBHostDeviceStatus Function

Contents | Index | Home
Previous | Up | Next
USBHostDeviceStatus Function
C
BYTE USBHostDeviceStatus(
    BYTE deviceAddress
);
Description

This function returns the current status of a device. If the device is in a holding state due to an error, the error is returned.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
Return Values
Return Values | Description
USB_DEVICE_ATTACHED | Device is attached and running
USB_DEVICE_DETACHED | No device is attached
USB_DEVICE_ENUMERATING | Device is enumerating
USB_HOLDING_OUT_OF_MEMORY | Not enough heap space available
USB_HOLDING_UNSUPPORTED_DEVICE | Invalid configuration or unsupported class
USB_HOLDING_UNSUPPORTED_HUB | Hubs are not supported
USB_HOLDING_INVALID_CONFIGURATION | Invalid configuration requested
USB_HOLDING_PROCESSING_CAPACITY | Processing requirement excessive
USB_HOLDING_POWER_REQUIREMENT | Power requirement excessive
USB_HOLDING_CLIENT_INIT_ERROR | Client driver failed to initialize
USB_DEVICE_SUSPENDED | Device is suspended
Other | Device is holding in an error state. The return value indicates the error.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostDeviceStatus Function


USBHostGetCurrentConfigurationDescriptor Macro

Contents | Index | Home
Previous | Up | Next
USBHostGetCurrentConfigurationDescriptor Macro
C
#define USBHostGetCurrentConfigurationDescriptor( deviceAddress) ( pCurrentConfigurationDescriptor )
Description

This function returns a pointer to the current configuration descriptor of the requested device.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Address of device
Returns

BYTE * - Pointer to the Configuration Descriptor.

Remarks

This will need to be expanded to a full function when multiple device support is added.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostGetCurrentConfigurationDescriptor Macro


USBHostGetDeviceDescriptor Macro

Contents | Index | Home
Previous | Up | Next
USBHostGetDeviceDescriptor Macro
C
#define USBHostGetDeviceDescriptor( deviceAddress ) ( pDeviceDescriptor )
Description

This function returns a pointer to the device descriptor of the requested device.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Address of device
Returns

BYTE * - Pointer to the Device Descriptor.

Remarks

This will need to be expanded to a full function when multiple device support is added.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostGetDeviceDescriptor Macro


USBHostGetStringDescriptor Macro

Contents | Index | Home
Previous | Up | Next
USBHostGetStringDescriptor Macro
C
#define USBHostGetStringDescriptor( deviceAddress, stringNumber, LangID, stringDescriptor, stringLength, clientDriverID ) \
        USBHostIssueDeviceRequest( deviceAddress, USB_SETUP_DEVICE_TO_HOST | USB_SETUP_TYPE_STANDARD | USB_SETUP_RECIPIENT_DEVICE,   \
                USB_REQUEST_GET_DESCRIPTOR, (USB_DESCRIPTOR_STRING << 8) | stringNumber,                                            \
                LangID, stringLength, stringDescriptor, USB_DEVICE_REQUEST_GET, clientDriverID )
Description

This routine initiates a request to obtains the requested string descriptor. If the request cannot be started, the routine returns an error. Otherwise, the request is started, and the requested string descriptor is stored in the designated location.

Example Usage:

Copy Code
USBHostGetStringDescriptor(
    deviceAddress,
    stringDescriptorNum,
    LangID,
    stringDescriptorBuffer,
    sizeof(stringDescriptorBuffer),
    0xFF
    );

while(1)
{
    if(USBHostTransferIsComplete( deviceAddress , 0, &errorCode, &byteCount))
    {
        if(errorCode)
        {
            //There was an error reading the string, bail out of loop
        }
        else
        {
            //String is located in specified buffer, do something with it.

            //The length of the string is both in the byteCount variable
            //  as well as the first byte of the string itself
        }
        break;
    }
    USBTasks();
}
Preconditions

None

Parameters
Parameters | Description
deviceAddress | Address of the device
stringNumber | Index of the desired string descriptor
LangID | The Language ID of the string to read (should be 0 if trying to read the language ID list
*stringDescriptor | Pointer to where to store the string.
stringLength | Maximum length of the returned string.
clientDriverID | Client driver to return the completion event to.
Return Values
Return Values | Description
USB_SUCCESS | The request was started successfully.
USB_UNKNOWN_DEVICE | Device not found
USB_INVALID_STATE | We must be in a normal running state.
USB_ENDPOINT_BUSY | The endpoint is currently processing a request.
Remarks

The returned string descriptor will be in the exact format as obtained from the device. The length of the entire descriptor will be in the first byte, and the descriptor type will be in the second. The string itself is represented in UNICODE. Refer to the USB 2.0 Specification for more information about the format of string descriptors.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostGetStringDescriptor Macro


USBHostInit Function

Contents | Index | Home
Previous | Up | Next
USBHostInit Function
C
BOOL USBHostInit(
    unsigned long flags
);
Description

This function initializes the variables of the USB host stack. It does not initialize the hardware. The peripheral itself is initialized in one of the state machine states. Therefore, USBHostTasks() should be called soon after this function.

Preconditions

None

Parameters
Parameters | Description
flags | reserved
Return Values
Return Values | Description
TRUE | Initialization successful
FALSE | Could not allocate memory.
Remarks

If the endpoint list is empty, an entry is created in the endpoint list for EP0. If the list is not empty, free all allocated memory other than the EP0 node. This allows the routine to be called multiple times by the application.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostInit Function


USBHostRead Function

Contents | Index | Home
Previous | Up | Next
USBHostRead Function
C
BYTE USBHostRead(
    BYTE deviceAddress,
    BYTE endpoint,
    BYTE * data,
    DWORD size
);
Description

This function initiates a read from the attached device.

If the endpoint is isochronous, special conditions apply. The pData and size parameters have slightly different meanings, since multiple buffers are required. Once started, an isochronous transfer will continue with no upper layer intervention until USBHostTerminateTransfer() is called. The ISOCHRONOUS_DATA_BUFFERS structure should not be manipulated until the transfer is terminated.

To clarify parameter usage and to simplify casting, use the macro USBHostReadIsochronous() when reading from an isochronous endpoint.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE endpoint | Endpoint number
BYTE *pData | Pointer to where to store the data. If the endpoint is isochronous, this points to an ISOCHRONOUS_DATA_BUFFERS structure, with multiple data buffer pointers.
DWORD size | Number of data bytes to read. If the endpoint is isochronous, this is the number of data buffer pointers pointed to by pData.
Return Values
Return Values | Description
USB_SUCCESS | Read started successfully.
USB_UNKNOWN_DEVICE | Device with the specified address not found.
USB_INVALID_STATE | We are not in a normal running state.
USB_ENDPOINT_ILLEGAL_TYPE | Must use USBHostControlRead to read from a control endpoint.
USB_ENDPOINT_ILLEGAL_DIRECTION | Must read from an IN endpoint.
USB_ENDPOINT_STALLED | Endpoint is stalled. Must be cleared by the application.
USB_ENDPOINT_ERROR | Endpoint has too many errors. Must be cleared by the application.
USB_ENDPOINT_BUSY | A Read is already in progress.
USB_ENDPOINT_NOT_FOUND | Invalid endpoint.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostRead Function


USBHostResetDevice Function

Contents | Index | Home
Previous | Up | Next
USBHostResetDevice Function
C
BYTE USBHostResetDevice(
    BYTE deviceAddress
);
Description

This function places the device back in the RESET state, to issue RESET signaling. It can be called only if the state machine is not in the DETACHED state.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
Return Values
Return Values | Description
USB_SUCCESS | Success
USB_UNKNOWN_DEVICE | Device not found
USB_ILLEGAL_REQUEST | Device cannot RESUME unless it is suspended
Remarks

In order to do a full clean-up, the state is set back to STATE_DETACHED rather than a reset state. The ATTACH interrupt will automatically be triggered when the module is re-enabled, and the proper reset will be performed.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostResetDevice Function


USBHostResumeDevice Function

Contents | Index | Home
Previous | Up | Next
USBHostResumeDevice Function
C
BYTE USBHostResumeDevice(
    BYTE deviceAddress
);
Description

This function issues a RESUME to the attached device. It can called only if the state machine is in the suspend state.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
Return Values
Return Values | Description
USB_SUCCESS | Success
USB_UNKNOWN_DEVICE | Device not found
USB_ILLEGAL_REQUEST | Device cannot RESUME unless it is suspended
Remarks

None

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostResumeDevice Function


USBHostSetDeviceConfiguration Function

Contents | Index | Home
Previous | Up | Next
USBHostSetDeviceConfiguration Function
C
BYTE USBHostSetDeviceConfiguration(
    BYTE deviceAddress,
    BYTE configuration
);
Description

This function is used by the application to change the device's Configuration. This function must be used instead of USBHostIssueDeviceRequest(), because the endpoint definitions may change.

To see when the reconfiguration is complete, use the USBHostDeviceStatus() function. If configuration is still in progress, this function will return USB_DEVICE_ENUMERATING.

Preconditions

The host state machine should be in the running state, and no reads or writes should be in progress.

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE configuration | Index of the new configuration
Return Values
Return Values | Description
USB_SUCCESS | Process of changing the configuration was started successfully.
USB_UNKNOWN_DEVICE | Device not found
USB_INVALID_STATE | This function cannot be called during enumeration or while performing a device request.
USB_BUSY | No IN or OUT transfers may be in progress.
Remarks

If an invalid configuration is specified, this function cannot return an error. Instead, the event USB_UNSUPPORTED_DEVICE will the sent to the application layer and the device will be placed in a holding state with a USB_HOLDING_UNSUPPORTED_DEVICE error returned by USBHostDeviceStatus().

Example
Copy Code
rc = USBHostSetDeviceConfiguration( attachedDevice, configuration );
if (rc)
{
    // Error - cannot set configuration.
}
else
{
    while (USBHostDeviceStatus( attachedDevice ) == USB_DEVICE_ENUMERATING)
    {
        USBHostTasks();
    }
}
if (USBHostDeviceStatus( attachedDevice ) != USB_DEVICE_ATTACHED)
{
    // Error - cannot set configuration.
}
Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostSetDeviceConfiguration Function


USBHostSetNAKTimeout Function

Contents | Index | Home
Previous | Up | Next
USBHostSetNAKTimeout Function
C
BYTE USBHostSetNAKTimeout(
    BYTE deviceAddress,
    BYTE endpoint,
    WORD flags,
    WORD timeoutCount
);
Description

This function is used to set whether or not an endpoint on a device should time out a transaction based on the number of NAKs received, and if so, how many NAKs are allowed before the timeout.

Preconditions

None

Parameters
Parameters
Description
BYTE deviceAddress
Device address
BYTE endpoint
Endpoint number to configure
WORD flags
Bit 0:
  • 0 = disable NAK timeout
  • 1 = enable NAK timeout
WORD timeoutCount
Number of NAKs allowed before a timeout
Return Values
Return Values | Description
USB_SUCCESS | NAK timeout was configured successfully.
USB_UNKNOWN_DEVICE | Device not found.
USB_ENDPOINT_NOT_FOUND | The specified endpoint was not found.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostSetNAKTimeout Function


USBHostSuspendDevice Function

Contents | Index | Home
Previous | Up | Next
USBHostSuspendDevice Function
C
BYTE USBHostSuspendDevice(
    BYTE deviceAddress
);
Description

This function put a device into an IDLE state. It can only be called while the state machine is in normal running mode. After 3ms, the attached device should go into SUSPEND mode.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device to suspend
Return Values
Return Values | Description
USB_SUCCESS | Success
USB_UNKNOWN_DEVICE | Device not found
USB_ILLEGAL_REQUEST | Cannot suspend unless device is in normal run mode
Remarks

None

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostSuspendDevice Function


USBHostTerminateTransfer Function

Contents | Index | Home
Previous | Up | Next
USBHostTerminateTransfer Function
C
void USBHostTerminateTransfer(
    BYTE deviceAddress,
    BYTE endpoint
);
Description

This function terminates the current transfer for the given endpoint. It can be used to terminate reads or writes that the device is not responding to. It is also the only way to terminate an isochronous transfer.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE endpoint | Endpoint number
Returns

None

Remarks

None

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostTerminateTransfer Function


USBHostTransferIsComplete Function

Contents | Index | Home
Previous | Up | Next
USBHostTransferIsComplete Function
C
BOOL USBHostTransferIsComplete(
    BYTE deviceAddress,
    BYTE endpoint,
    BYTE * errorCode,
    DWORD * byteCount
);
Description

This function initiates whether or not the last endpoint transaction is complete. If it is complete, an error code and the number of bytes transferred are returned.

For isochronous transfers, byteCount is not valid. Instead, use the returned byte counts for each EVENT_TRANSFER event that was generated during the transfer.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE endpoint | Endpoint number
BYTE *errorCode | Error code indicating the status of the transfer. Only valid if the transfer is complete.
DWORD *byteCount | The number of bytes sent or received. Invalid for isochronous transfers.
Return Values
Return Values | Description
TRUE | Transfer is complete.
FALSE | Transfer is not complete.
Remarks

Possible values for errorCode are:

  • USB_SUCCESS - Transfer successful
  • USB_UNKNOWN_DEVICE - Device not attached
  • USB_ENDPOINT_STALLED - Endpoint STALL'd
  • USB_ENDPOINT_ERROR_ILLEGAL_PID - Illegal PID returned
  • USB_ENDPOINT_ERROR_BIT_STUFF
  • USB_ENDPOINT_ERROR_DMA
  • USB_ENDPOINT_ERROR_TIMEOUT
  • USB_ENDPOINT_ERROR_DATA_FIELD
  • USB_ENDPOINT_ERROR_CRC16
  • USB_ENDPOINT_ERROR_END_OF_FRAME
  • USB_ENDPOINT_ERROR_PID_CHECK
  • USB_ENDPOINT_ERROR - Other error

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostTransferIsComplete Function


USBHostVbusEvent Function

Contents | Index | Home
Previous | Up | Next
USBHostVbusEvent Function
C
BYTE USBHostVbusEvent(
    USB_EVENT vbusEvent,
    BYTE hubAddress,
    BYTE portNumber
);
Description

This function handles Vbus events that are detected by the application. Since Vbus management is application dependent, the application is responsible for monitoring Vbus and detecting overcurrent conditions and removal of the overcurrent condition. If the application detects an overcurrent condition, it should call this function with the event EVENT_VBUS_OVERCURRENT with the address of the hub and port number that has the condition. When a port returns to normal operation, the application should call this function with the event EVENT_VBUS_POWER_AVAILABLE so the stack knows that it can allow devices to attach to that port.

Preconditions

None

Parameters
Parameters
Description
USB_EVENT vbusEvent
Vbus event that occured. Valid events:
  • EVENT_VBUS_OVERCURRENT
  • EVENT_VBUS_POWER_AVAILABLE
BYTE hubAddress
Address of the hub device (USB_ROOT_HUB for the root hub)
BYTE portNumber
Number of the physical port on the hub (0 - based)
Return Values
Return Values | Description
USB_SUCCESS | Event handled
USB_ILLEGAL_REQUEST | Invalid event, hub, or port
Remarks

None

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostVbusEvent Function


USBHostWrite Function

Contents | Index | Home
Previous | Up | Next
USBHostWrite Function
C
BYTE USBHostWrite(
    BYTE deviceAddress,
    BYTE endpoint,
    BYTE * data,
    DWORD size
);
Description

This function initiates a write to the attached device. The data buffer pointed to by *data must remain valid during the entire time that the write is taking place; the data is not buffered by the stack.

If the endpoint is isochronous, special conditions apply. The pData and size parameters have slightly different meanings, since multiple buffers are required. Once started, an isochronous transfer will continue with no upper layer intervention until USBHostTerminateTransfer() is called. The ISOCHRONOUS_DATA_BUFFERS structure should not be manipulated until the transfer is terminated.

To clarify parameter usage and to simplify casting, use the macro USBHostWriteIsochronous() when writing to an isochronous endpoint.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE endpoint | Endpoint number
BYTE *data | Pointer to where the data is stored. If the endpoint is isochronous, this points to an ISOCHRONOUS_DATA_BUFFERS structure, with multiple data buffer pointers.
DWORD size | Number of data bytes to send. If the endpoint is isochronous, this is the number of data buffer pointers pointed to by pData.
Return Values
Return Values | Description
USB_SUCCESS | Write started successfully.
USB_UNKNOWN_DEVICE | Device with the specified address not found.
USB_INVALID_STATE | We are not in a normal running state.
USB_ENDPOINT_ILLEGAL_TYPE | Must use USBHostControlWrite to write to a control endpoint.
USB_ENDPOINT_ILLEGAL_DIRECTION | Must write to an OUT endpoint.
USB_ENDPOINT_STALLED | Endpoint is stalled. Must be cleared by the application.
USB_ENDPOINT_ERROR | Endpoint has too many errors. Must be cleared by the application.
USB_ENDPOINT_BUSY | A Write is already in progress.
USB_ENDPOINT_NOT_FOUND | Invalid endpoint.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Interface Routines > USBHostWrite Function


Data Types and Constants

Contents | Index | Home
Previous | Up | Next
Data Types and Constants
Macros
Name | Description
USB_NUM_BULK_NAKS | Define how many NAK's are allowed during a bulk transfer before erroring.
USB_NUM_COMMAND_TRIES | During enumeration, define how many times each command will be tried before giving up and resetting the device.
USB_NUM_CONTROL_NAKS | Define how many NAK's are allowed during a control transfer before erroring.
USB_NUM_ENUMERATION_TRIES | Define how many times the host will try to enumerate the device before giving up and setting the state to DETACHED.
USB_NUM_INTERRUPT_NAKS | Define how many NAK's are allowed during an interrupt OUT transfer before erroring. Interrupt IN transfers that are NAK'd are terminated without error.
TPL_SET_CONFIG | Bitmask for setting the configuration.
TPL_CLASS_DRV | Bitmask for class driver support.
TPL_ALLOW_HNP | Bitmask for Host Negotiation Protocol.
Structures
Name | Description
_CLIENT_DRIVER_TABLE | Client Driver Table Structure This structure is used to define an entry in the client-driver table. Each entry provides the information that the Host layer needs to manage a particular USB client driver, including pointers to the interface routines that the Client Driver must implement.
_HOST_TRANSFER_DATA | Host Transfer Information This structure is used when the event handler is used to notify the upper layer of transfer completion.
_USB_TPL | Targeted Peripheral List This structure is used to define the devices that this host can support. If the host is a USB Embedded Host or Dual Role Device that does not support OTG, the TPL may contain both specific devices and generic classes. If the host supports OTG, then the TPL may contain ONLY specific devices.
CLIENT_DRIVER_TABLE | Client Driver Table Structure This structure is used to define an entry in the client-driver table. Each entry provides the information that the Host layer needs to manage a particular USB client driver, including pointers to the interface routines that the Client Driver must implement.
HOST_TRANSFER_DATA | Host Transfer Information This structure is used when the event handler is used to notify the upper layer of transfer completion.
USB_TPL | Targeted Peripheral List This structure is used to define the devices that this host can support. If the host is a USB Embedded Host or Dual Role Device that does not support OTG, the TPL may contain both specific devices and generic classes. If the host supports OTG, then the TPL may contain ONLY specific devices.
Types
Name | Description
USB_CLIENT_INIT | This is a typedef to use when defining a client driver initialization handler.
USB_CLIENT_EVENT_HANDLER | This is a typedef to use when defining a client driver event handler.
Unions
Name | Description
TRANSFER_ATTRIBUTES | This is type TRANSFER_ATTRIBUTES.
Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants


CLIENT_DRIVER_TABLE Structure

Contents | Index | Home
Previous | Up | Next
CLIENT_DRIVER_TABLE Structure
C
typedef struct _CLIENT_DRIVER_TABLE {
  USB_CLIENT_INIT Initialize;
  USB_CLIENT_EVENT_HANDLER EventHandler;
  USB_CLIENT_EVENT_HANDLER DataEventHandler;
  DWORD flags;
} CLIENT_DRIVER_TABLE;
Description

Client Driver Table Structure

This structure is used to define an entry in the client-driver table. Each entry provides the information that the Host layer needs to manage a particular USB client driver, including pointers to the interface routines that the Client Driver must implement.

Members
Members | Description
USB_CLIENT_INIT Initialize; | Initialization routine
USB_CLIENT_EVENT_HANDLER EventHandler; | Event routine
USB_CLIENT_EVENT_HANDLER DataEventHandler; | Data Event routine
DWORD flags; | Initialization flags
Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants > CLIENT_DRIVER_TABLE Structure


HOST_TRANSFER_DATA Structure

Contents | Index | Home
Previous | Up | Next
HOST_TRANSFER_DATA Structure
C
typedef struct _HOST_TRANSFER_DATA {
  DWORD dataCount;
  BYTE * pUserData;
  BYTE bEndpointAddress;
  BYTE bErrorCode;
  TRANSFER_ATTRIBUTES bmAttributes;
  BYTE clientDriver;
} HOST_TRANSFER_DATA;
Description

Host Transfer Information

This structure is used when the event handler is used to notify the upper layer of transfer completion.

Members
Members | Description
DWORD dataCount; | Count of bytes transferred.
BYTE * pUserData; | Pointer to transfer data.
BYTE bEndpointAddress; | Transfer endpoint.
BYTE bErrorCode; | Transfer error code.
TRANSFER_ATTRIBUTES bmAttributes; | INTERNAL USE ONLY - Endpoint transfer attributes.
BYTE clientDriver; | INTERNAL USE ONLY - Client driver index for sending the event.
Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants > HOST_TRANSFER_DATA Structure


TRANSFER_ATTRIBUTES Union

Contents | Index | Home
Previous | Up | Next
TRANSFER_ATTRIBUTES Union
C
typedef union {
  BYTE val;
  struct {
    BYTE bfTransferType : 2;
    BYTE bfSynchronizationType : 2;
    BYTE bfUsageType : 2;
  }
} TRANSFER_ATTRIBUTES;
Description

This is type TRANSFER_ATTRIBUTES.

Members
Members | Description
BYTE bfTransferType : 2; | See USB_TRANSFER_TYPE_* for values.
BYTE bfSynchronizationType : 2; | For isochronous endpoints only.
BYTE bfUsageType : 2; | For isochronous endpoints only.
Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants > TRANSFER_ATTRIBUTES Union


USB_TPL Structure

Contents | Index | Home
Previous | Up | Next
USB_TPL Structure
C
typedef struct _USB_TPL {
  union {
    DWORD val;
    struct {
      WORD idVendor;
      WORD idProduct;
    }
    struct {
      BYTE bClass;
      BYTE bSubClass;
      BYTE bProtocol;
    }
  } device;
  BYTE bConfiguration;
  BYTE ClientDriver;
  union {
    BYTE val;
    struct {
      BYTE bfAllowHNP : 1;
      BYTE bfIsClassDriver : 1;
      BYTE bfSetConfiguration : 1;
    }
  } flags;
} USB_TPL;
Description

Targeted Peripheral List

This structure is used to define the devices that this host can support. If the host is a USB Embedded Host or Dual Role Device that does not support OTG, the TPL may contain both specific devices and generic classes. If the host supports OTG, then the TPL may contain ONLY specific devices.

Members
Members | Description
WORD idVendor; | Vendor ID
WORD idProduct; | Product ID
BYTE bClass; | Class ID
BYTE bSubClass; | SubClass ID
BYTE bProtocol; | Protocol ID
BYTE bConfiguration; | Initial device configuration
BYTE ClientDriver; | Index of client driver in the Client Driver table
BYTE bfAllowHNP : 1; | Is HNP allowed?
BYTE bfIsClassDriver : 1; | Client driver is a class-level driver
BYTE bfSetConfiguration : 1; | bConfiguration is valid
Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants > USB_TPL Structure


USB_CLIENT_INIT Type

Contents | Index | Home
Previous | Up | Next
USB_CLIENT_INIT Type
C
typedef BOOL (* USB_CLIENT_INIT)(BYTE address, DWORD flags, BYTE clientDriverID);
Description

This routine is a call out from the host layer to a USB client driver. It is called when the system has been configured as a USB host and a new device has been attached to the bus. Its purpose is to initialize and activate the client driver.

Preconditions

The device has been configured.

Parameters
Parameters | Description
BYTE address | Device's address on the bus
DWORD flags | Initialization flags
BYTE clientDriverID | ID to send when issuing a Device Request via USBHostIssueDeviceRequest() or USBHostSetDeviceConfiguration().
Return Values
Return Values | Description
TRUE | Successful
FALSE | Not successful
Remarks

There may be multiple client drivers. If so, the USB host layer will call the initialize routine for each of the clients that are in the selected configuration.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants > USB_CLIENT_INIT Type


USB_CLIENT_EVENT_HANDLER Type

Contents | Index | Home
Previous | Up | Next
USB_CLIENT_EVENT_HANDLER Type
C
typedef BOOL (* USB_CLIENT_EVENT_HANDLER)(BYTE address, USB_EVENT event, void *data, DWORD size);
Description

This data type defines a pointer to a call-back function that must be implemented by a client driver if it needs to be aware of events on the USB. When an event occurs, the Host layer will call the client driver via this pointer to handle the event. Events are identified by the "event" parameter and may have associated data. If the client driver was able to handle the event, it should return TRUE. If not (or if additional processing is required), it should return FALSE.

Preconditions

The client must have been initialized.

Parameters
Parameters | Description
BYTE address | Address of device where event occurred
USB_EVENT event | Identifies the event that occured
void *data | Pointer to event-specific data
DWORD size | Size of the event-specific data
Return Values
Return Values | Description
TRUE | The event was handled
FALSE | The event was not handled
Remarks

The application may also implement an event handling routine if it requires knowledge of events. To do so, it must implement a routine that matches this function signature and define the USB_HOST_APP_EVENT_HANDLER macro as the name of that function.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants > USB_CLIENT_EVENT_HANDLER Type


USB_NUM_BULK_NAKS Macro

Contents | Index | Home
Previous | Up | Next
USB_NUM_BULK_NAKS Macro
C
#define USB_NUM_BULK_NAKS 10000   // Define how many NAK's are allowed
Description

Define how many NAK's are allowed during a bulk transfer before erroring.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants > USB_NUM_BULK_NAKS Macro


USB_NUM_COMMAND_TRIES Macro

Contents | Index | Home
Previous | Up | Next
USB_NUM_COMMAND_TRIES Macro
C
#define USB_NUM_COMMAND_TRIES 3   // During enumeration, define how many
Description

During enumeration, define how many times each command will be tried before giving up and resetting the device.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants > USB_NUM_COMMAND_TRIES Macro


USB_NUM_CONTROL_NAKS Macro

Contents | Index | Home
Previous | Up | Next
USB_NUM_CONTROL_NAKS Macro
C
#define USB_NUM_CONTROL_NAKS 20  // Define how many NAK's are allowed
Description

Define how many NAK's are allowed during a control transfer before erroring.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants > USB_NUM_CONTROL_NAKS Macro


USB_NUM_ENUMERATION_TRIES Macro

Contents | Index | Home
Previous | Up | Next
USB_NUM_ENUMERATION_TRIES Macro
C
#define USB_NUM_ENUMERATION_TRIES 3   // Define how many times the host will try
Description

Define how many times the host will try to enumerate the device before giving up and setting the state to DETACHED.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants > USB_NUM_ENUMERATION_TRIES Macro


USB_NUM_INTERRUPT_NAKS Macro

Contents | Index | Home
Previous | Up | Next
USB_NUM_INTERRUPT_NAKS Macro
C
#define USB_NUM_INTERRUPT_NAKS 3   // Define how many NAK's are allowed
Description

Define how many NAK's are allowed during an interrupt OUT transfer before erroring. Interrupt IN transfers that are NAK'd are terminated without error.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants > USB_NUM_INTERRUPT_NAKS Macro


TPL_SET_CONFIG Macro

Contents | Index | Home
Previous | Up | Next
TPL_SET_CONFIG Macro
C
#define TPL_SET_CONFIG 0x04                    // Bitmask for setting the configuration.
Description

Bitmask for setting the configuration.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants > TPL_SET_CONFIG Macro


TPL_CLASS_DRV Macro

Contents | Index | Home
Previous | Up | Next
TPL_CLASS_DRV Macro
C
#define TPL_CLASS_DRV 0x02                    // Bitmask for class driver support.
Description

Bitmask for class driver support.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants > TPL_CLASS_DRV Macro


TPL_ALLOW_HNP Macro

Contents | Index | Home
Previous | Up | Next
TPL_ALLOW_HNP Macro
C
#define TPL_ALLOW_HNP 0x01                    // Bitmask for Host Negotiation Protocol.
Description

Bitmask for Host Negotiation Protocol.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Data Types and Constants > TPL_ALLOW_HNP Macro


Macros

Contents | Index | Home
Previous | Up | Next
Macros
Macros
Name | Description
INIT_CL_SC_P | Set class support in the TPL (non-OTG only).
INIT_VID_PID | Set VID/PID support in the TPL.
Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Macros


INIT_CL_SC_P Macro

Contents | Index | Home
Previous | Up | Next
INIT_CL_SC_P Macro
C
#define INIT_CL_SC_P(c,s,p) {((c)|((s)<<8)|((p)<<16))}  // Set class support in the TPL (non-OTG only).
Description

Set class support in the TPL (non-OTG only).

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Macros > INIT_CL_SC_P Macro


INIT_VID_PID Macro

Contents | Index | Home
Previous | Up | Next
INIT_VID_PID Macro
C
#define INIT_VID_PID(v,p) {((v)|((p)<<16))}           // Set VID/PID support in the TPL.
Description

Set VID/PID support in the TPL.

Application Programming Interface (API) > Embedded Host API > Embedded Host Stack > Macros > INIT_VID_PID Macro


Audio Client Driver

Contents | Index | Home
Previous | Up | Next
Audio Client Driver
Topics
Name | Description
Interface Routines |
Data Types and Constants |
Application Programming Interface (API) > Embedded Host API > Audio Client Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
USBHostAudioV1DataEventHandler | This function is the data event handler for this client driver.
USBHostAudioV1EventHandler | This function is the event handler for this client driver.
USBHostAudioV1Initialize | This function is the initialization routine for this client driver.
USBHostAudioV1ReceiveAudioData | This function starts the reception of streaming, isochronous audio data.
USBHostAudioV1SetInterfaceFullBandwidth | This function sets the full bandwidth interface.
USBHostAudioV1SetInterfaceZeroBandwidth | This function sets the zero bandwidth interface.
USBHostAudioV1SetSamplingFrequency | This function sets the sampling frequency for the device.
USBHostAudioV1SupportedFrequencies | This function returns a pointer to the list of supported frequencies.
USBHostAudioV1TerminateTransfer | This function terminates an audio stream.
Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Interface Routines


USBHostAudioV1DataEventHandler Function

Contents | Index | Home
Previous | Up | Next
USBHostAudioV1DataEventHandler Function
C
BOOL USBHostAudioV1DataEventHandler(
    BYTE address,
    USB_EVENT event,
    void * data,
    DWORD size
);
Description

This function is the data event handler for this client driver. It is called by the host layer when isochronous data events occur.

Preconditions

The device has been initialized.

Parameters
Parameters | Description
BYTE address | Address of the device
USB_EVENT event | Event that has occurred
void *data | Pointer to data pertinent to the event
WORD size | Size of the data
Return Values
Return Values | Description
TRUE | Event was handled
FALSE | Event was not handled
Remarks

The client driver does not need to process the data. Just pass the event up to the application layer.

Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Interface Routines > USBHostAudioV1DataEventHandler Function


USBHostAudioV1EventHandler Function

Contents | Index | Home
Previous | Up | Next
USBHostAudioV1EventHandler Function
C
BOOL USBHostAudioV1EventHandler(
    BYTE address,
    USB_EVENT event,
    void * data,
    DWORD size
);
Description

This function is the event handler for this client driver. It is called by the host layer when various events occur.

Preconditions

The device has been initialized.

Parameters
Parameters | Description
BYTE address | Address of the device
USB_EVENT event | Event that has occurred
void *data | Pointer to data pertinent to the event
WORD size | Size of the data
Return Values
Return Values | Description
TRUE | Event was handled
FALSE | Event was not handled
Remarks

None

Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Interface Routines > USBHostAudioV1EventHandler Function


USBHostAudioV1Initialize Function

Contents | Index | Home
Previous | Up | Next
USBHostAudioV1Initialize Function
C
BOOL USBHostAudioV1Initialize(
    BYTE address,
    DWORD flags,
    BYTE clientDriverID
);
Description

This function is the initialization routine for this client driver. It is called by the host layer when the USB device is being enumerated.

Preconditions

None

Parameters
Parameters | Description
BYTE address | Address of the new device
DWORD flags | Initialization flags
BYTE clientDriverID | ID to send when issuing a Device Request via USBHostIssueDeviceRequest() or USBHostSetDeviceConfiguration().
Return Values
Return Values | Description
TRUE | We can support the device.
FALSE | We cannot support the device.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Interface Routines > USBHostAudioV1Initialize Function


USBHostAudioV1ReceiveAudioData Function

Contents | Index | Home
Previous | Up | Next
USBHostAudioV1ReceiveAudioData Function
C
BYTE USBHostAudioV1ReceiveAudioData(
    BYTE deviceAddress,
    ISOCHRONOUS_DATA * pIsochronousData
);
Description

This function starts the reception of streaming, isochronous audio data.

Preconditions

USBHostAudioV1SetInterfaceFullBandwidth() must be called to set the device to its full bandwidth interface.

Parameters
Parameters | Description
BYTE deviceAddress | Device address
ISOCHRONOUS_DATA *pIsochronousData | Pointer to an ISOCHRONOUS_DATA structure, containing information for the application and the host driver for the isochronous transfer.
Return Values
Return Values | Description
USB_SUCCESS | Request started successfully
USB_AUDIO_DEVICE_NOT_FOUND | No device with specified address
USB_AUDIO_DEVICE_BUSY | Device is already receiving audio data or setting an interface.
Others | See USBHostIssueDeviceRequest() errors.
Remarks

Some devices require other operations between setting the full bandwidth interface and starting the streaming audio data. Therefore, these two functions are broken out separately.

Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Interface Routines > USBHostAudioV1ReceiveAudioData Function


USBHostAudioV1SetInterfaceFullBandwidth Function

Contents | Index | Home
Previous | Up | Next
USBHostAudioV1SetInterfaceFullBandwidth Function
C
BYTE USBHostAudioV1SetInterfaceFullBandwidth(
    BYTE deviceAddress
);
Description

This function sets the full bandwidth interface. This function should be called before calling USBHostAudioV1ReceiveAudioData() to receive the audio stream. Upon completion, the event EVENT_AUDIO_INTERFACE_SET will be generated.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
Return Values
Return Values | Description
USB_SUCCESS | Request started successfully
USB_AUDIO_DEVICE_NOT_FOUND | No device with specified address
USB_AUDIO_DEVICE_BUSY | Device is already receiving audio data or setting an interface.
Others | See USBHostIssueDeviceRequest() errors.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Interface Routines > USBHostAudioV1SetInterfaceFullBandwidth Function


USBHostAudioV1SetInterfaceZeroBandwidth Function

Contents | Index | Home
Previous | Up | Next
USBHostAudioV1SetInterfaceZeroBandwidth Function
C
BYTE USBHostAudioV1SetInterfaceZeroBandwidth(
    BYTE deviceAddress
);
Description

This function sets the full bandwidth interface. This function can be called after calling USBHostAudioV1TerminateTransfer() to terminate the audio stream. Upon completion, the event EVENT_AUDIO_INTERFACE_SET will be generated.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
Return Values
Return Values | Description
USB_SUCCESS | Request started successfully
USB_AUDIO_DEVICE_NOT_FOUND | No device with the specified address.
Others | See USBHostIssueDeviceRequest()
Remarks

None

Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Interface Routines > USBHostAudioV1SetInterfaceZeroBandwidth Function


USBHostAudioV1SetSamplingFrequency Function

Contents | Index | Home
Previous | Up | Next
USBHostAudioV1SetSamplingFrequency Function
C
BYTE USBHostAudioV1SetSamplingFrequency(
    BYTE deviceAddress,
    BYTE * frequency
);
Description

This function sets the sampling frequency for the device. If the exact frequency is not supported by the device, the device will round it to the closest supported value.

IMPORTANT: If the request is initiated successfully, the frequency value must remain valid until the EVENT_AUDIO_FREQUENCY_SET event is received. Therefore, this value cannot be a local (stack) variable. The application can either use a global variable for this value, or it can use the function USBHostAudioV1SupportedFrequencies() to obtain a pointer to the number and list of supported frequencies, and pass a pointer to the desired frequency in this list.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE *frequency | Pointer to three bytes that specify the desired
sampling frequency. NOTE | If the request is initiated successfully, this location must remain valid until the EVENT_AUDIO_FREQUENCY_SET event is received.
Return Values
Return Values | Description
USB_SUCCESS | Request started successfully
Others | See USBHostIssueDeviceRequest() errors.
Remarks

If a global variable is used to old the frequency, it can be declared as a DWORD. Since PIC Microcontrollers are little endian machines, a pointer to the DWORD can be used as the frequency parameter:

Copy Code
DWORD   desiredFrequency = 44100;   // Hertz

rc = USBHostAudioV1SetSamplingFrequency( deviceAddress, (BYTE *)(&desiredFrequency) );
Example
Copy Code
BYTE  numFrequencies;
BYTE  *ptr;

ptr = USBHostAudioV1SupportedFrequencies( deviceAddress );
if (ptr)
{
    numFrequencies = *ptr;
    ptr++;
    if (numFrequencies == 0)
    {
        // Continuous sampling, minimum and maximum are specified.
        DWORD   minFrequency;
        DWORD   maxFrequency;

        minFrequency = *ptr + (*(ptr+1) << 8) + (*(ptr+2) << 16);
        ptr += 3;
        maxFrequency = *ptr + (*(ptr+1) << 8) + (*(ptr+2) << 16);
        if ((minFrequency <= desiredFrequency) && (desiredFrequency <= maxFrequency))
        {
            rc = USBHostAudioV1SetSamplingFrequency( deviceAddress, &desiredFrequency );
        }
        else
        {
            // Desired frequency out of range
        }
    }
    else
    {
        // Discrete sampling frequencies are specified.
        DWORD frequency;

        while (numFrequencies)
        {
            frequency = *ptr + (*(ptr+1) << 8) + (*(ptr+2) << 16);
            if (frequency == desiredFrequency)
            {
                rc = USBHostAudioV1SetSamplingFrequency( deviceAddress, ptr );
                continue;
            }
            numFrequencies--;
            ptr += 3;
        }
        if (numFrequencies == 0)
        {
            // Desired frequency not found.
        }
    }
}
Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Interface Routines > USBHostAudioV1SetSamplingFrequency Function


USBHostAudioV1SupportedFrequencies Function

Contents | Index | Home
Previous | Up | Next
USBHostAudioV1SupportedFrequencies Function
C
BYTE * USBHostAudioV1SupportedFrequencies(
    BYTE deviceAddress
);
Description

This function returns a pointer to the list of supported frequencies. It is intended to be used with the function USBHostAudioV1SetSamplingFrequency() to set the device's sampling frequency.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
Returns

This function returns a BYTE pointer to the list of supported frequencies. The first byte of this list is the number of supported frequencies. Each supported frequency is then listed, with three bytes for each frequency.

Remarks

None

Example
Copy Code
BYTE  numFrequencies;
BYTE  *ptr;

ptr = USBHostAudioV1SupportedFrequencies( deviceAddress );
if (ptr)
{
    numFrequencies = *ptr;
    ptr++;
    if (numFrequencies == 0)
    {
        // Continuous sampling, minimum and maximum are specified.
        DWORD   minFrequency;
        DWORD   maxFrequency;

        minFrequency = *ptr + (*(ptr+1) << 8) + (*(ptr+2) << 16);
        ptr += 3;
        maxFrequency = *ptr + (*(ptr+1) << 8) + (*(ptr+2) << 16);
        if ((minFrequency <= desiredFrequency) && (desiredFrequency <= maxFrequency))
        {
            rc = USBHostAudioV1SetSamplingFrequency( deviceAddress, &desiredFrequency );
        }
        else
        {
            // Desired frequency out of range
        }
    }
    else
    {
        // Discrete sampling frequencies are specified.
        DWORD frequency;

        while (numFrequencies)
        {
            frequency = *ptr + (*(ptr+1) << 8) + (*(ptr+2) << 16);
            if (frequency == desiredFrequency)
            {
                rc = USBHostAudioV1SetSamplingFrequency( deviceAddress, ptr );
                continue;
            }
            numFrequencies--;
            ptr += 3;
        }
        if (numFrequencies == 0)
        {
            // Desired frequency not found.
        }
    }
}
Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Interface Routines > USBHostAudioV1SupportedFrequencies Function


USBHostAudioV1TerminateTransfer Function

Contents | Index | Home
Previous | Up | Next
USBHostAudioV1TerminateTransfer Function
C
void USBHostAudioV1TerminateTransfer(
    BYTE deviceAddress
);
Description

This function terminates an audio stream. It does not change the device's selected interface. The application may wish to call USBHostAudioV1SetInterfaceZeroBandwidth() after this function to set the device to the zero bandwidth interface.

Between terminating one audio stream and starting another, the application should call USBHostIsochronousBuffersReset() to reset the data buffers. This is done from the application layer rather than from this function, so the application can process all received audio data.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
Returns

None

Remarks

None

Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Interface Routines > USBHostAudioV1TerminateTransfer Function


Data Types and Constants

Contents | Index | Home
Previous | Up | Next
Data Types and Constants
Macros
Name | Description
EVENT_AUDIO_ATTACH | An audio device has attached. The returned data pointer points to a USB_AUDIO_V1_DEVICE_ID structure.
EVENT_AUDIO_DETACH | An audio device has detached. The returned data pointer points to a byte with the previous address of the detached device.
EVENT_AUDIO_FREQUENCY_SET | This event is returned after the sampling frequency is set via USBHostAudioV1SetSamplingFrequency(). The returned data pointer points to a HOST_TRANSFER_DATA structure, with the error code for this request.
EVENT_AUDIO_INTERFACE_SET | This event is returned after the full or zero bandwidth interface has been set. The returned data pointer is NULL, but the size is the error code from the transfer.
EVENT_AUDIO_NONE | No event occured (NULL event).
EVENT_AUDIO_OFFSET | If the application has not defined an offset for audio events, set it to 0.
EVENT_AUDIO_STREAM_RECEIVED | An audio stream data packet has been received. The returned data pointer points to a HOST_TRANSFER_DATA structure, with information about the most recent transfer. One event will be returned for each transfer, so the application will know how much data was actually received in each transfer. If there was a bus error, both the returned data pointer and the size will be zero.
Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Data Types and Constants


EVENT_AUDIO_ATTACH Macro

Contents | Index | Home
Previous | Up | Next
EVENT_AUDIO_ATTACH Macro
C
#define EVENT_AUDIO_ATTACH EVENT_AUDIO_BASE + EVENT_AUDIO_OFFSET + 1
Description

An audio device has attached. The returned data pointer points to a USB_AUDIO_V1_DEVICE_ID structure.

Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Data Types and Constants > EVENT_AUDIO_ATTACH Macro


EVENT_AUDIO_DETACH Macro

Contents | Index | Home
Previous | Up | Next
EVENT_AUDIO_DETACH Macro
C
#define EVENT_AUDIO_DETACH EVENT_AUDIO_BASE + EVENT_AUDIO_OFFSET + 2
Description

An audio device has detached. The returned data pointer points to a byte with the previous address of the detached device.

Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Data Types and Constants > EVENT_AUDIO_DETACH Macro


EVENT_AUDIO_FREQUENCY_SET Macro

Contents | Index | Home
Previous | Up | Next
EVENT_AUDIO_FREQUENCY_SET Macro
C
#define EVENT_AUDIO_FREQUENCY_SET EVENT_AUDIO_BASE + EVENT_AUDIO_OFFSET + 4
Description

This event is returned after the sampling frequency is set via USBHostAudioV1SetSamplingFrequency(). The returned data pointer points to a HOST_TRANSFER_DATA structure, with the error code for this request.

Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Data Types and Constants > EVENT_AUDIO_FREQUENCY_SET Macro


EVENT_AUDIO_INTERFACE_SET Macro

Contents | Index | Home
Previous | Up | Next
EVENT_AUDIO_INTERFACE_SET Macro
C
#define EVENT_AUDIO_INTERFACE_SET EVENT_AUDIO_BASE + EVENT_AUDIO_OFFSET + 5
Description

This event is returned after the full or zero bandwidth interface has been set. The returned data pointer is NULL, but the size is the error code from the transfer.

Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Data Types and Constants > EVENT_AUDIO_INTERFACE_SET Macro


EVENT_AUDIO_NONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_AUDIO_NONE Macro
C
#define EVENT_AUDIO_NONE EVENT_AUDIO_BASE + EVENT_AUDIO_OFFSET + 0
Description

No event occured (NULL event).

Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Data Types and Constants > EVENT_AUDIO_NONE Macro


EVENT_AUDIO_OFFSET Macro

Contents | Index | Home
Previous | Up | Next
EVENT_AUDIO_OFFSET Macro
C
#define EVENT_AUDIO_OFFSET 0
Description

If the application has not defined an offset for audio events, set it to 0.

Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Data Types and Constants > EVENT_AUDIO_OFFSET Macro


EVENT_AUDIO_STREAM_RECEIVED Macro

Contents | Index | Home
Previous | Up | Next
EVENT_AUDIO_STREAM_RECEIVED Macro
C
#define EVENT_AUDIO_STREAM_RECEIVED EVENT_AUDIO_BASE + EVENT_AUDIO_OFFSET + 3
Description

An audio stream data packet has been received. The returned data pointer points to a HOST_TRANSFER_DATA structure, with information about the most recent transfer. One event will be returned for each transfer, so the application will know how much data was actually received in each transfer. If there was a bus error, both the returned data pointer and the size will be zero.

Application Programming Interface (API) > Embedded Host API > Audio Client Driver > Data Types and Constants > EVENT_AUDIO_STREAM_RECEIVED Macro


Audio MIDI Client Driver

Contents | Index | Home
Previous | Up | Next
Audio MIDI Client Driver
Topics
Name | Description
Interface Functions |
Data Types and Constants |
Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver


Interface Functions

Contents | Index | Home
Previous | Up | Next
Interface Functions
Functions
Name | Description
USBHostMIDIRead | This function will attempt to read length number of bytes from the attached MIDI device located at handle, and will save the contents to ram located at buffer.
USBHostMIDITransferIsComplete | This routine indicates whether or not the last transfer over endpointIndex is complete.
USBHostMIDIWrite | This function will attempt to write length number of bytes from memory at location buffer to the attached MIDI device located at handle.
Macros
Name | Description
USBHostMIDIDeviceDetached | This interface is used to check if the device has been detached from the bus.
USBHostMIDIEndpointDirection | This function retrieves the endpoint direction of the endpoint at endpointIndex for device that's located at handle.
USBHostMIDINumberOfEndpoints | This function retrieves the number of endpoints for the device that's located at handle.
USBHostMIDISizeOfEndpoint | This function retrieves the endpoint size of the endpoint at endpointIndex for device that's located at handle.
USBHostMIDITransferIsBusy | This interface is used to check if the client driver is currently busy transferring data over endponitIndex for the device at handle.
Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver > Interface Functions


USBHostMIDIDeviceDetached Macro

Contents | Index | Home
Previous | Up | Next
USBHostMIDIDeviceDetached Macro
C
#define USBHostMIDIDeviceDetached(a) ( (((a)==NULL) ? FALSE : TRUE )
Description

This interface is used to check if the device has been detached from the bus.

Preconditions

None

Parameters
Parameters | Description
void* handle | Pointer to a structure containing the Device Info
Return Values
Return Values | Description
TRUE | The device has been detached, or an invalid handle is given.
FALSE | The device is attached
Remarks

None

Example
Copy Code
if (USBHostMIDIDeviceDetached( deviceAddress ))
{
    // Handle detach
}
Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver > Interface Functions > USBHostMIDIDeviceDetached Macro


USBHostMIDIEndpointDirection Macro

Contents | Index | Home
Previous | Up | Next
USBHostMIDIEndpointDirection Macro
C
#define USBHostMIDIEndpointDirection(a,b) (((MIDI_DEVICE*)a)->endpoints[b].endpointAddress & 0x80) ? IN : OUT
Description

This function retrieves the endpoint direction of the endpoint at endpointIndex for device that's located at handle.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
void* handle | Pointer to a structure containing the Device Info
BYTE endpointIndex | the index of the endpoint whose direction is requested
Returns

MIDI_ENDPOINT_DIRECTION - Returns the direction of the endpoint (IN or OUT)

Remarks

None

Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver > Interface Functions > USBHostMIDIEndpointDirection Macro


USBHostMIDINumberOfEndpoints Macro

Contents | Index | Home
Previous | Up | Next
USBHostMIDINumberOfEndpoints Macro
C
#define USBHostMIDINumberOfEndpoints(a) ((MIDI_DEVICE*)a)->numEndpoints
Description

This function retrieves the number of endpoints for the device that's located at handle.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
void* handle | Pointer to a structure containing the Device Info
Returns

BYTE - Returns the number of endpoints for the device at handle.

Remarks

None

Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver > Interface Functions > USBHostMIDINumberOfEndpoints Macro


USBHostMIDIRead Function

Contents | Index | Home
Previous | Up | Next
USBHostMIDIRead Function
C
BYTE USBHostMIDIRead(
    void* handle,
    BYTE endpointIndex,
    void * buffer,
    WORD length
);
Description

This function will attempt to read length number of bytes from the attached MIDI device located at handle, and will save the contents to ram located at buffer.

Preconditions

The device must be connected and enumerated. The array at *buffer should have at least length number of bytes available.

Parameters
Parameters | Description
void* handle | Pointer to a structure containing the Device Info
BYTE endpointIndex | the index of the endpoint whose direction is requested
void* buffer | Pointer to the data buffer
WORD length | Number of bytes to be read
Return Values
Return Values | Description
USB_SUCCESS | The Read was started successfully
(USB error code) | The Read was not started. See USBHostRead() for a list of errors.
Remarks

None

Example
Copy Code
if (!USBHostMIDITransferIsBusy( deviceHandle, currentEndpoint )
{
    USBHostMIDIRead( deviceHandle, currentEndpoint, &buffer, sizeof(buffer));
}
Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver > Interface Functions > USBHostMIDIRead Function


USBHostMIDISizeOfEndpoint Macro

Contents | Index | Home
Previous | Up | Next
USBHostMIDISizeOfEndpoint Macro
C
#define USBHostMIDISizeOfEndpoint(a,b) ((MIDI_DEVICE*)a)->endpoints[b].endpointSize
Description

This function retrieves the endpoint size of the endpoint at endpointIndex for device that's located at handle.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
void* handle | Pointer to a structure containing the Device Info
BYTE endpointIndex | the index of the endpoint whose direction is requested
Returns

DWORD - Returns the number of bytes for the endpoint (4 - 64 bytes per USB spec)

Remarks

None

Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver > Interface Functions > USBHostMIDISizeOfEndpoint Macro


USBHostMIDITransferIsBusy Macro

Contents | Index | Home
Previous | Up | Next
USBHostMIDITransferIsBusy Macro
C
#define USBHostMIDITransferIsBusy(a,b) ((MIDI_DEVICE*)a)->endpoints[b].busy
Description

This interface is used to check if the client driver is currently busy receiving or sending data from the device at the endpoint with number endpointIndex. This function is intended for use with transfer events. With polling, the function USBHostMIDITransferIsComplete() should be used.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
void* handle | Pointer to a structure containing the Device Info
BYTE endpointIndex | the index of the endpoint whose direction is requested
Return Values
Return Values | Description
TRUE | The device is receiving data or an invalid handle is given.
FALSE | The device is not receiving data
Remarks

None

Example
Copy Code
if (!USBHostMIDITransferIsBusy( handle, endpointIndex ))
{
    USBHostMIDIRead( handle, endpointIndex, &buffer, sizeof( buffer ) );
}
Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver > Interface Functions > USBHostMIDITransferIsBusy Macro


USBHostMIDITransferIsComplete Function

Contents | Index | Home
Previous | Up | Next
USBHostMIDITransferIsComplete Function
C
BOOL USBHostMIDITransferIsComplete(
    void* handle,
    BYTE endpointIndex,
    BYTE * errorCode,
    DWORD * byteCount
);
Description

This routine indicates whether or not the last transfer over endpointIndex is complete. If it is, then the returned errorCode and byteCount are valid, and reflect the error code and the number of bytes received.

This function is intended for use with polling. With transfer events, the function USBHostMIDITransferIsBusy() should be used.

Preconditions

None

Parameters
Parameters | Description
void* handle | Pointer to a structure containing the Device Info
BYTE endpointIndex | index of endpoint in endpoints array
BYTE *errorCode | Error code of the last transfer, if complete
DWORD *byteCount | Bytes transferred during the last transfer, if complete
Return Values
Return Values | Description
TRUE | The IN transfer is complete. errorCode and byteCount are valid.
FALSE | The IN transfer is not complete. errorCode and byteCount are invalid.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver > Interface Functions > USBHostMIDITransferIsComplete Function


USBHostMIDIWrite Function

Contents | Index | Home
Previous | Up | Next
USBHostMIDIWrite Function
C
BYTE USBHostMIDIWrite(
    void* handle,
    BYTE endpointIndex,
    void * buffer,
    WORD length
);
Description

This function will attempt to write length number of bytes from memory at location buffer to the attached MIDI device located at handle.

Preconditions

The device must be connected and enumerated. The array at *buffer should have at least length number of bytes available.

Parameters
Parameters | Description
handle | Pointer to a structure containing the Device Info
endpointIndex | Index of the endpoint
buffer | Pointer to the data being transferred
length | Size of the data being transferred
Return Values
Return Values | Description
USB_SUCCESS | The Write was started successfully
(USB error code) | The Write was not started. See USBHostWrite() for a list of errors.
Remarks

None

Example
Copy Code
if (!USBHostMIDITransferIsBusy( deviceHandle, currentEndpoint )
{
    USBHostMIDIWrite( deviceAddress, &buffer, sizeof(buffer) );
}
Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver > Interface Functions > USBHostMIDIWrite Function


Data Types and Constants

Contents | Index | Home
Previous | Up | Next
Data Types and Constants
Macros
Name | Description
EVENT_MIDI_ATTACH | This event indicates that a MIDI device has been attached. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to a MIDI_DEVICE_ID structure, and size is the size of the MIDI_DEVICE_ID structure.
EVENT_MIDI_DETACH | This event indicates that the specified device has been detached from the USB. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to a BYTE that contains the device address, and size is the size of a BYTE.
EVENT_MIDI_OFFSET | This is an optional offset for the values of the generated events. If necessary, the application can use a non-zero offset for the MIDI events to resolve conflicts in event number.
EVENT_MIDI_TRANSFER_DONE | This event indicates that a previous write/read request has completed. These events are enabled if USB Embedded Host transfer events are enabled (USB_ENABLE_TRANSFER_EVENT is defined). When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to the buffer that completed transmission, and size is the actual number of bytes that were written to the device.
Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver > Data Types and Constants


EVENT_MIDI_ATTACH Macro

Contents | Index | Home
Previous | Up | Next
EVENT_MIDI_ATTACH Macro
C
#define EVENT_MIDI_ATTACH (EVENT_AUDIO_BASE+EVENT_MIDI_OFFSET+0)
Description

This event indicates that a MIDI device has been attached. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to a MIDI_DEVICE_ID structure, and size is the size of the MIDI_DEVICE_ID structure.

Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver > Data Types and Constants > EVENT_MIDI_ATTACH Macro


EVENT_MIDI_DETACH Macro

Contents | Index | Home
Previous | Up | Next
EVENT_MIDI_DETACH Macro
C
#define EVENT_MIDI_DETACH (EVENT_AUDIO_BASE+EVENT_MIDI_OFFSET+1)
Description

This event indicates that the specified device has been detached from the USB. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to a BYTE that contains the device address, and size is the size of a BYTE.

Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver > Data Types and Constants > EVENT_MIDI_DETACH Macro


EVENT_MIDI_OFFSET Macro

Contents | Index | Home
Previous | Up | Next
EVENT_MIDI_OFFSET Macro
C
#define EVENT_MIDI_OFFSET 0
Description

This is an optional offset for the values of the generated events. If necessary, the application can use a non-zero offset for the MIDI events to resolve conflicts in event number.

Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver > Data Types and Constants > EVENT_MIDI_OFFSET Macro


EVENT_MIDI_TRANSFER_DONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_MIDI_TRANSFER_DONE Macro
C
#define EVENT_MIDI_TRANSFER_DONE (EVENT_AUDIO_BASE+EVENT_MIDI_OFFSET+2)
Description

This event indicates that a previous write/read request has completed. These events are enabled if USB Embedded Host transfer events are enabled (USB_ENABLE_TRANSFER_EVENT is defined). When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to the buffer that completed transmission, and size is the actual number of bytes that were written to the device.

Application Programming Interface (API) > Embedded Host API > Audio MIDI Client Driver > Data Types and Constants > EVENT_MIDI_TRANSFER_DONE Macro


Android Accessory Client Driver

Contents | Index | Home
Previous | Up | Next
Android Accessory Client Driver
Topics
Name | Description
Interface Routines |
Data Type and Constants |
Macros |
Internal Members |
Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
AndroidAppIsReadComplete | Check to see if the last read to the Android device was completed
AndroidAppIsWriteComplete | Check to see if the last write to the Android device was completed
AndroidAppRead | Attempts to read information from the specified Android device
AndroidAppStart | Sets the accessory information and initializes the client driver information after the initial power cycles.
AndroidAppWrite | Sends data to the Android device specified by the passed in handle.
AndroidTasks | Tasks function that keeps the Android client driver moving
Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Interface Routines


AndroidAppIsReadComplete Function

Contents | Index | Home
Previous | Up | Next
AndroidAppIsReadComplete Function
C
BOOL AndroidAppIsReadComplete(
    void* handle,
    BYTE* errorCode,
    DWORD* size
);
Description

Check to see if the last read to the Android device was completed. If complete, returns the amount of data that was sent and the corresponding error code for the transmission.

Preconditions

Transfer has previously been requested from an Android device.

Parameters
Parameters | Description
void* handle | the handle passed to the device in the EVENT_ANDROID_ATTACH event
BYTE* errorCode | a pointer to the location where the resulting error code should be written
DWORD* size | a pointer to the location where the resulting size information should be written
Return Values
Return Values | Description
TRUE | Transfer is complete.
FALSE | Transfer is not complete.
Remarks

Possible values for errorCode are:

  • USB_SUCCESS - Transfer successful
  • USB_UNKNOWN_DEVICE - Device not attached
  • USB_ENDPOINT_STALLED - Endpoint STALL'd
  • USB_ENDPOINT_ERROR_ILLEGAL_PID - Illegal PID returned
  • USB_ENDPOINT_ERROR_BIT_STUFF
  • USB_ENDPOINT_ERROR_DMA
  • USB_ENDPOINT_ERROR_TIMEOUT
  • USB_ENDPOINT_ERROR_DATA_FIELD
  • USB_ENDPOINT_ERROR_CRC16
  • USB_ENDPOINT_ERROR_END_OF_FRAME
  • USB_ENDPOINT_ERROR_PID_CHECK
  • USB_ENDPOINT_ERROR - Other error

Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Interface Routines > AndroidAppIsReadComplete Function


AndroidAppIsWriteComplete Function

Contents | Index | Home
Previous | Up | Next
AndroidAppIsWriteComplete Function
C
BOOL AndroidAppIsWriteComplete(
    void* handle,
    BYTE* errorCode,
    DWORD* size
);
Description

Check to see if the last write to the Android device was completed. If complete, returns the amount of data that was sent and the corresponding error code for the transmission.

Preconditions

Transfer has previously been sent to Android device.

Parameters
Parameters | Description
void* handle | the handle passed to the device in the EVENT_ANDROID_ATTACH event
BYTE* errorCode | a pointer to the location where the resulting error code should be written
DWORD* size | a pointer to the location where the resulting size information should be written
Return Values
Return Values | Description
TRUE | Transfer is complete.
FALSE | Transfer is not complete.
Remarks

Possible values for errorCode are:

  • USB_SUCCESS - Transfer successful
  • USB_UNKNOWN_DEVICE - Device not attached
  • USB_ENDPOINT_STALLED - Endpoint STALL'd
  • USB_ENDPOINT_ERROR_ILLEGAL_PID - Illegal PID returned
  • USB_ENDPOINT_ERROR_BIT_STUFF
  • USB_ENDPOINT_ERROR_DMA
  • USB_ENDPOINT_ERROR_TIMEOUT
  • USB_ENDPOINT_ERROR_DATA_FIELD
  • USB_ENDPOINT_ERROR_CRC16
  • USB_ENDPOINT_ERROR_END_OF_FRAME
  • USB_ENDPOINT_ERROR_PID_CHECK
  • USB_ENDPOINT_ERROR - Other error

Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Interface Routines > AndroidAppIsWriteComplete Function


AndroidAppRead Function

Contents | Index | Home
Previous | Up | Next
AndroidAppRead Function
C
BYTE AndroidAppRead(
    void* handle,
    BYTE* data,
    DWORD size
);
Description

Attempts to read information from the specified Android device. This function does not block. Data availability is checked via the AndroidAppIsReadComplete() function.

Preconditions

A read request is not already in progress and an Android device is attached.

Parameters
Parameters | Description
void* handle | the handle passed to the device in the EVENT_ANDROID_ATTACH event
BYTE* data | a pointer to the location of where the data should be stored. This location should be accessible by the USB module
DWORD size | the amount of data to read.
Return Values
Return Values | Description
USB_SUCCESS | Read started successfully.
USB_UNKNOWN_DEVICE | Device with the specified address not found.
USB_INVALID_STATE | We are not in a normal running state.
USB_ENDPOINT_ILLEGAL_TYPE | Must use USBHostControlRead to read from a control endpoint.
USB_ENDPOINT_ILLEGAL_DIRECTION | Must read from an IN endpoint.
USB_ENDPOINT_STALLED | Endpoint is stalled. Must be cleared by the application.
USB_ENDPOINT_ERROR | Endpoint has too many errors. Must be cleared by the application.
USB_ENDPOINT_BUSY | A Read is already in progress.
USB_ENDPOINT_NOT_FOUND | Invalid endpoint.
USB_ERROR_BUFFER_TOO_SMALL | The buffer passed to the read function was smaller than the endpoint size being used (buffer must be larger than or equal to the endpoint size).
Remarks

None

Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Interface Routines > AndroidAppRead Function


AndroidAppStart Function

Contents | Index | Home
Previous | Up | Next
AndroidAppStart Function
C
void AndroidAppStart(
    ANDROID_ACCESSORY_INFORMATION* accessoryInfo
);
Description

Sets the accessory information and initializes the client driver information after the initial power cycles. Since this resets all device information this function should be used only after a compete system reset. This should not be called while the USB is active or while connected to a device.

Preconditions

USB module should not be in operation

Parameters
Parameters | Description
ANDROID_ACCESSORY_INFORMATION *info | the information about the Android accessory
Remarks

None

Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Interface Routines > AndroidAppStart Function


AndroidAppWrite Function

Contents | Index | Home
Previous | Up | Next
AndroidAppWrite Function
C
BYTE AndroidAppWrite(
    void* handle,
    BYTE* data,
    DWORD size
);
Description

Sends data to the Android device specified by the passed in handle.

Preconditions

Transfer is not already in progress. USB module is initialized and Android device has attached.

Parameters
Parameters | Description
void* handle | the handle passed to the device in the EVENT_ANDROID_ATTACH event
BYTE* data | the data to send to the Android device
DWORD size | the size of the data that needs to be sent
Return Values
Return Values | Description
USB_SUCCESS | Write started successfully.
USB_UNKNOWN_DEVICE | Device with the specified address not found.
USB_INVALID_STATE | We are not in a normal running state.
USB_ENDPOINT_ILLEGAL_TYPE | Must use USBHostControlWrite to write to a control endpoint.
USB_ENDPOINT_ILLEGAL_DIRECTION | Must write to an OUT endpoint.
USB_ENDPOINT_STALLED | Endpoint is stalled. Must be cleared by the application.
USB_ENDPOINT_ERROR | Endpoint has too many errors. Must be cleared by the application.
USB_ENDPOINT_BUSY | A Write is already in progress.
USB_ENDPOINT_NOT_FOUND | Invalid endpoint.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Interface Routines > AndroidAppWrite Function


AndroidTasks Function

Contents | Index | Home
Previous | Up | Next
AndroidTasks Function
C
void AndroidTasks();
Description

Tasks function that keeps the Android client driver moving. Keeps the driver processing requests and handling events. This function should be called periodically (the same frequency as USBHostTasks() would be helpful).

Preconditions

AndroidAppStart() function has been called before the first calling of this function

Remarks

This function should be called periodically to keep the Android driver moving.

Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Interface Routines > AndroidTasks Function


Data Type and Constants

Contents | Index | Home
Previous | Up | Next
Data Type and Constants
Structures
Name | Description
ANDROID_ACCESSORY_INFORMATION | This structure contains the informatin that is required to successfully create a link between the Android device and the accessory. This information must match the information entered in the accessory filter in the Android application in order for the Android application to access the device. An instance of this structure should be passed into the AndroidAppStart() at initialization.
Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Data Type and Constants


ANDROID_ACCESSORY_INFORMATION Structure

Contents | Index | Home
Previous | Up | Next
ANDROID_ACCESSORY_INFORMATION Structure
C
typedef struct {
  char* manufacturer;
  BYTE manufacturer_size;
  char* model;
  BYTE model_size;
  char* description;
  BYTE description_size;
  char* version;
  BYTE version_size;
  char* URI;
  BYTE URI_size;
  char* serial;
  BYTE serial_size;
} ANDROID_ACCESSORY_INFORMATION;
Description

This structure contains the informatin that is required to successfully create a link between the Android device and the accessory. This information must match the information entered in the accessory filter in the Android application in order for the Android application to access the device. An instance of this structure should be passed into the AndroidAppStart() at initialization.

Members
Members | Description
char* manufacturer; | String: manufacturer name
BYTE manufacturer_size; | length of manufacturer string
char* model; | String: model name
BYTE model_size; | length of model name string
char* description; | String: description of the accessory
BYTE description_size; | length of the description string
char* version; | String: version number
BYTE version_size; | length of the version number string
char* URI; | String: URI for the accessory (most commonly a URL)
BYTE URI_size; | length of the URI string
char* serial; | String: serial number of the device
BYTE serial_size; | length of the serial number string
Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Data Type and Constants > ANDROID_ACCESSORY_INFORMATION Structure


Macros

Contents | Index | Home
Previous | Up | Next
Macros
Macros
Name | Description
ANDROID_BASE_OFFSET | Defines the event offset for the Android specific events. If not defined, then a default of 0 is used.
EVENT_ANDROID_ATTACH | This event is thrown when an Android device is attached and successfully entered into accessory mode already. The data portion of this event is the handle that is required to communicate to the device and should be saved so that it can be passed to all of the transfer functions. Always use this definition in the code and never put a static value as the value of this event may change based on various build options.
EVENT_ANDROID_DETACH | This event is thrown when an Android device is removed. The data portion of the event is the handle of the device that has been removed. Always use this definition in the code and never put a static value as the value of this event may change based on various build options.
NUM_ANDROID_DEVICES_SUPPORTED | Defines the number of concurrent Android devices this implementation is allowed to talk to. This definition is only used for implementations where the accessory is the host and the Android device is the slave. This is also most often defined to be 1. If this is not defined by the user, a default of 1 is used. This option is only used when compiling the source version of the library. This value is set to 1 for pre-compiled versions of the library.
USB_ERROR_BUFFER_TOO_SMALL | Error code indicating that the buffer passed to the read function was too small. Since the USB host can't control how much data it will receive in a single packet, the user must provide a buffer that is at least the size of the endpoint of the attached device. If a buffer is passed in that is too small, the read will not start and this error is returned to the user.
ANDROID_INIT_FLAG_BYPASS_PROTOCOL | This defintion is used in the usbClientDrvTable[] in the flags field in order to bypass the Android accessory initialization phase. This should be used only when a device is known to already be in accessory mode (in protocol v1 if the VID/PID are already matching the accessory mode VID/PID). In some cases an Android device doesn't exit accessory mode and thus those other protocol commands will not work. This flag must be used to save those devices
Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Macros


ANDROID_BASE_OFFSET Macro

Contents | Index | Home
Previous | Up | Next
ANDROID_BASE_OFFSET Macro
C
#define ANDROID_BASE_OFFSET 0
Description

Defines the event offset for the Android specific events. If not defined, then a default of 0 is used.

Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Macros > ANDROID_BASE_OFFSET Macro


EVENT_ANDROID_ATTACH Macro

Contents | Index | Home
Previous | Up | Next
EVENT_ANDROID_ATTACH Macro
C
#define EVENT_ANDROID_ATTACH ANDROID_EVENT_BASE + 0
Description

This event is thrown when an Android device is attached and successfully entered into accessory mode already. The data portion of this event is the handle that is required to communicate to the device and should be saved so that it can be passed to all of the transfer functions. Always use this definition in the code and never put a static value as the value of this event may change based on various build options.

Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Macros > EVENT_ANDROID_ATTACH Macro


EVENT_ANDROID_DETACH Macro

Contents | Index | Home
Previous | Up | Next
EVENT_ANDROID_DETACH Macro
C
#define EVENT_ANDROID_DETACH ANDROID_EVENT_BASE + 1
Description

This event is thrown when an Android device is removed. The data portion of the event is the handle of the device that has been removed. Always use this definition in the code and never put a static value as the value of this event may change based on various build options.

Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Macros > EVENT_ANDROID_DETACH Macro


NUM_ANDROID_DEVICES_SUPPORTED Macro

Contents | Index | Home
Previous | Up | Next
NUM_ANDROID_DEVICES_SUPPORTED Macro
C
#define NUM_ANDROID_DEVICES_SUPPORTED 1
Description

Defines the number of concurrent Android devices this implementation is allowed to talk to. This definition is only used for implementations where the accessory is the host and the Android device is the slave. This is also most often defined to be 1. If this is not defined by the user, a default of 1 is used.

This option is only used when compiling the source version of the library. This value is set to 1 for pre-compiled versions of the library.

Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Macros > NUM_ANDROID_DEVICES_SUPPORTED Macro


USB_ERROR_BUFFER_TOO_SMALL Macro

Contents | Index | Home
Previous | Up | Next
USB_ERROR_BUFFER_TOO_SMALL Macro
C
#define USB_ERROR_BUFFER_TOO_SMALL USB_ERROR_CLASS_DEFINED + 0
Description

Error code indicating that the buffer passed to the read function was too small. Since the USB host can't control how much data it will receive in a single packet, the user must provide a buffer that is at least the size of the endpoint of the attached device. If a buffer is passed in that is too small, the read will not start and this error is returned to the user.

Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Macros > USB_ERROR_BUFFER_TOO_SMALL Macro


ANDROID_INIT_FLAG_BYPASS_PROTOCOL Macro

Contents | Index | Home
Previous | Up | Next
ANDROID_INIT_FLAG_BYPASS_PROTOCOL Macro
C
#define ANDROID_INIT_FLAG_BYPASS_PROTOCOL 0x00000001
Description

This defintion is used in the usbClientDrvTable[] in the flags field in order to bypass the Android accessory initialization phase. This should be used only when a device is known to already be in accessory mode (in protocol v1 if the VID/PID are already matching the accessory mode VID/PID). In some cases an Android device doesn't exit accessory mode and thus those other protocol commands will not work. This flag must be used to save those devices

Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Macros > ANDROID_INIT_FLAG_BYPASS_PROTOCOL Macro


Internal Members

Contents | Index | Home
Previous | Up | Next
Internal Members
Application Programming Interface (API) > Embedded Host API > Android Accessory Client Driver > Internal Members


CDC Client Driver

Contents | Index | Home
Previous | Up | Next
CDC Client Driver
Communication Device Class (CDC) Host

CDC - Overview

Several type of communication can benefit from USB. Communication Device Class specification provides common specification for communication devices. There are three classes that make up the definition for communications devices:

* Communications Device Class

* Communications Interface Class

* Data Interface Class.

The Communications Device Class is a device-level definition and is used by the host to properly identify a communications device that may present several different types of interfaces.

The Communications Interface Class defines a general-purpose mechanism that can be used to enable all types of communications services on the Universal Serial Bus (USB). This interface consist of two elements, a management element and a notification element. The management element configures and controls the device, it consist of endpoint 0. Notification element is optional and is used to handle transport events. In the current stack notification element is not implemented.

The Data Interface Class defines a general-purpose mechanism to enable bulk or isochronous transfer on the USB when the data does not meet the requirements for any other class. This interface is used to transmit/receive data to/from the device. The type of endpoints belonging to a Data Class interface are restricted to being either isochronous or bulk, and are expected to exist in pairs of the same type (one In and one Out). Current version of the stack is tested for Bulk transfers.

Class-Specific Codes

This section lists the codes for the Communications Device Class, Communications Interface Class and Data Interface Class, including subclasses and protocols supported in the current version of the stack. The current version of the stack supports RS232 emulation over USB. Below is the list of codes to support this functionality.

The following table defines the Communications Device Class code:

Code | Class
0x02 | Communications Device Class
Communication Interface Codes

The following table defines the Communications Class code:

Code | Class
0x02 | Communications Interface Class

CDC specification mentions various subclass , current version of the Microchip CDC host stack supports below mentioned subclasses. The following table defines the currently supported Subclass codes for the Communications Interface Class:

Code | SubClass
0x02 | Abstract Control Model

The following table defines supported Communications Class Protocol Codes:

Code | Protocol
0x01 | AT Commands: V.250 etc.
Data Interface Code

The following table defines the Data Interface Class code:

Code | Class
0x0A | Data Interface Class

No specific Subclass and Protocol codes are required to achieve RS232 functionality over USB.

Communication and Data Transfer Handling

Communication Management : The CDC client deriver takes care of enumerating the device connected on the bus. The application must define Line Coding parameters in file usb_config.h . USBConfig utility can be used to set these parameters. If the connected device complies with the setting then the device is successfully attached else the device is not attached onto the bus. If the application needs to change the setting dynamically after the device has been successfully enumerated , interface function USBHostCDC_Api_ACM_Request()can be used to do so. Following standard requests are currently implemented:

Request | Summary
SendEncapsulatedCommand | Issues a command in the format of the supported control protocol.
GetEncapsulatedResponse | Requests a response in the format of the supported control protocol.
SetLineCoding | Configures DTE rate, stop-bits, parity, and number-of-character bits.
GetLineCoding | Requests current DTE rate, stop-bits, parity, and number-of-character bits.
SetControlLineState | [V24] signal used to tell the DCE device the DTE device is now present.

Data transfers : Once the device is attached the application is ready to start data transfers. Usually two endpoints one in each direction are supported by the device.

* To receive data from the device the application must set up a IN request at the rate depending on the baudrate settings. Application can use a timer interrupt to precisely set up the request. Function USBHostCDC_Api_Get_IN_Data()is used to setup the request. Maximum of 64 bytes can be received in single transfer.

* To transmit data to the device application must set up a OUT request. Function USBHostCDC_Api_Send_OUT_Data()is used to setup out request. Any amount of data can be transferred to the device. The Client driver takes care of sending the data in 64 bytes packet.

* USBHostCDC_ApiTransferIsComplete() is used to poll for the status of previous transfer.

* USBHostCDC_ApiDeviceDetect() is used to get the status of the device. If the device is ready for new transfer then the function returns TRUE.

Topics
Name | Description
Interface Routines |
Data Types and Constants |
Application Programming Interface (API) > Embedded Host API > CDC Client Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
USBHostCDC_Api_ACM_Request | This function can be used by application code to dynamically access ACM specific requests. This function should be used only if apllication intends to modify for example the Baudrate from previouly configured rate. Data transmitted/received to/from device is a array of bytes. Application must take extra care of understanding the data format before using this function.
USBHostCDC_Api_Get_IN_Data | This function is called by application to receive Input data over DATA interface. This function setsup the request to receive data from the device.
USBHostCDC_ApiTransferIsComplete | This function is called by application to poll for transfer status. This function returns true in the transfer is over. To check whether the transfer was successfull or not , application must check the error code returned by reference.
USBHostCDCDeviceStatus | This function determines the status of a CDC device.
USBHostCDCEventHandler | This function is the event handler for this client driver.
USBHostCDCInitAddress | This function intializes the address of the attached CDC device.
USBHostCDCInitialize | This function is the initialization routine for this client driver.
USBHostCDCResetDevice | This function starts a CDC reset.
USBHostCDCTransfer | This function starts a CDC transfer.
USBHostCDCTransferIsComplete | This function indicates whether or not the last transfer is complete.
Macros
Name | Description
USBHostCDCRead_DATA | This function intiates a read request from a attached CDC device.
USBHostCDCSend_DATA | This function intiates a write request to a attached CDC device.
Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Interface Routines


USBHostCDC_Api_ACM_Request Function

Contents | Index | Home
Previous | Up | Next
USBHostCDC_Api_ACM_Request Function
C
BYTE USBHostCDC_Api_ACM_Request(
    BYTE requestType,
    BYTE size,
    BYTE* data
);
Description

This function can be used by application code to dynamically access ACM specific requests. This function should be used only if apllication intends to modify for example the Baudrate from previouly configured rate. Data transmitted/received to/from device is a array of bytes. Application must take extra care of understanding the data format before using this function.

Preconditions

Device must be enumerated and attached successfully.

Parameters
Parameters | Description
BYTE size | Number bytes to be transferred.
BYTE *data | Pointer to data being transferred.
Return Values
Return Values | Description
USB_SUCCESS | Request started successfully
USB_CDC_DEVICE_NOT_FOUND | No device with specified address
USB_CDC_DEVICE_BUSY | Device not in proper state for performing a transfer
USB_CDC_COMMAND_FAILED | Request is not supported.
USB_CDC_ILLEGAL_REQUEST | Requested ID is invalid.
Remarks

None

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Interface Routines > USBHostCDC_Api_ACM_Request Function


USBHostCDC_Api_Get_IN_Data Function

Contents | Index | Home
Previous | Up | Next
USBHostCDC_Api_Get_IN_Data Function
C
BOOL USBHostCDC_Api_Get_IN_Data(
    BYTE no_of_bytes,
    BYTE* data
);
Description

This function is called by application to receive Input data over DATA interface. This function setsup the request to receive data from the device.

Preconditions

None

Parameters
Parameters | Description
BYTE no_of_bytes | Number of Bytes expected from the device.
BYTE* data | Pointer to application receive data buffer.
Return Values
Return Values | Description
TRUE | Transfer request is placed successfully.
FALSE | Transfer request failed.
Remarks

None

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Interface Routines > USBHostCDC_Api_Get_IN_Data Function


USBHostCDC_ApiTransferIsComplete Function

Contents | Index | Home
Previous | Up | Next
USBHostCDC_ApiTransferIsComplete Function
C
BOOL USBHostCDC_ApiTransferIsComplete(
    BYTE* errorCodeDriver,
    BYTE* byteCount
);
Description

This function is called by application to poll for transfer status. This function returns true in the transfer is over. To check whether the transfer was successfull or not , application must check the error code returned by reference.

Preconditions

None

Parameters
Parameters | Description
BYTE *errorCodeDriver | returns.
BYTE *byteCount | Number of bytes transferred.
Return Values
Return Values | Description
TRUE | Transfer is has completed.
FALSE | Transfer is pending.
Remarks

None

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Interface Routines > USBHostCDC_ApiTransferIsComplete Function


USBHostCDCDeviceStatus Function

Contents | Index | Home
Previous | Up | Next
USBHostCDCDeviceStatus Function
C
BYTE USBHostCDCDeviceStatus(
    BYTE deviceAddress
);
Description

This function determines the status of a CDC device.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | address of device to query
Return Values
Return Values | Description
USB_CDC_DEVICE_NOT_FOUND | Illegal device address, or the device is not an CDC
USB_CDC_INITIALIZING | CDC is attached and in the process of initializing
USB_PROCESSING_REPORT_DESCRIPTOR | CDC device is detected and report descriptor is being parsed
USB_CDC_NORMAL_RUNNING | CDC Device is running normal, ready to send and receive reports
USB_CDC_DEVICE_HOLDING | Device is holding due to error
USB_CDC_DEVICE_DETACHED | CDC detached.
Remarks

None

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Interface Routines > USBHostCDCDeviceStatus Function


USBHostCDCEventHandler Function

Contents | Index | Home
Previous | Up | Next
USBHostCDCEventHandler Function
C
BOOL USBHostCDCEventHandler(
    BYTE address,
    USB_EVENT event,
    void * data,
    DWORD size
);
Description

This function is the event handler for this client driver. It is called by the host layer when various events occur.

Preconditions

The device has been initialized.

Parameters
Parameters | Description
BYTE address | Address of the device
USB_EVENT event | Event that has occurred
void *data | Pointer to data pertinent to the event
DWORD size | Size of the data
Return Values
Return Values | Description
TRUE | Event was handled
FALSE | Event was not handled
Remarks

None

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Interface Routines > USBHostCDCEventHandler Function


USBHostCDCInitAddress Function

Contents | Index | Home
Previous | Up | Next
USBHostCDCInitAddress Function
C
BOOL USBHostCDCInitAddress(
    BYTE address,
    DWORD flags,
    BYTE clientDriverID
);
Description

This function intializes the address of the attached CDC device. Once the device is enumerated without any errors, the CDC client call this function. For all the transfer requesets this address is used to indentify the CDC device.

Preconditions

The device has been enumerated without any errors.

Parameters
Parameters | Description
BYTE address | Address of the new device
DWORD flags | Initialization flags
BYTE clientDriverID | Client driver identification for device requests
Return Values
Return Values | Description
TRUE | We can support the device.
FALSE | We cannot support the device.
Remarks

None

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Interface Routines > USBHostCDCInitAddress Function


USBHostCDCInitialize Function

Contents | Index | Home
Previous | Up | Next
USBHostCDCInitialize Function
C
BOOL USBHostCDCInitialize(
    BYTE address,
    DWORD flags,
    BYTE clientDriverID
);
Description

This function is the initialization routine for this client driver. It is called by the host layer when the USB device is being enumerated.For a CDC device we need to look into CDC descriptor, interface descriptor and endpoint descriptor.

Preconditions

None

Parameters
Parameters | Description
BYTE address | Address of the new device
DWORD flags | Initialization flags
BYTE clientDriverID | Client driver identification for device requests
Return Values
Return Values | Description
TRUE | We can support the device.
FALSE | We cannot support the device.
Remarks

None

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Interface Routines > USBHostCDCInitialize Function


USBHostCDCRead_DATA Macro

Contents | Index | Home
Previous | Up | Next
USBHostCDCRead_DATA Macro
C
#define USBHostCDCRead_DATA( address,interface,size,data,endpointData) \
         USBHostCDCTransfer( address,0,1,interface, size,data,endpointData)
Description

This function starts a CDC read transfer.

Preconditions

None

Parameters
Parameters | Description
address | Device address
interface | interface number of the requested transfer
size | Number of bytes to be read from the device
data | address of location where received data is to be stored
endpointDATA | endpoint details on which the transfer is requested
Return Values
Return Values | Description
USB_SUCCESS | Request started successfully
USB_CDC_DEVICE_NOT_FOUND | No device with specified address
USB_CDC_DEVICE_BUSY | Device not in proper state for performing a transfer
Remarks

None

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Interface Routines > USBHostCDCRead_DATA Macro


USBHostCDCResetDevice Function

Contents | Index | Home
Previous | Up | Next
USBHostCDCResetDevice Function
C
BYTE USBHostCDCResetDevice(
    BYTE deviceAddress
);
Description

This function starts a CDC reset. A reset can be issued only if the device is attached and not being initialized.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
Return Values
Return Values | Description
USB_SUCCESS | Reset started
USB_MSD_DEVICE_NOT_FOUND | No device with specified address
USB_MSD_ILLEGAL_REQUEST | Device is in an illegal state for reset
Remarks

None

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Interface Routines > USBHostCDCResetDevice Function


USBHostCDCSend_DATA Macro

Contents | Index | Home
Previous | Up | Next
USBHostCDCSend_DATA Macro
C
#define USBHostCDCSend_DATA( address,interface,size,data,endpointData) \
         USBHostCDCTransfer( address,0,0,interface, size,data,endpointData)
Description

This function starts a CDC write transfer.

Preconditions

None

Parameters
Parameters | Description
address | Device address
interface | interface number of the requested transfer
size | Number of bytes to be transfered to the device
data | address of location where the data to be transferred is stored
endpointDATA | endpoint details on which the transfer is requested
Return Values
Return Values | Description
USB_SUCCESS | Request started successfully
USB_CDC_DEVICE_NOT_FOUND | No device with specified address
USB_CDC_DEVICE_BUSY | Device not in proper state for performing a transfer
Remarks

None

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Interface Routines > USBHostCDCSend_DATA Macro


USBHostCDCTransfer Function

Contents | Index | Home
Previous | Up | Next
USBHostCDCTransfer Function
C
BYTE USBHostCDCTransfer(
    BYTE deviceAddress,
    BYTE request,
    BYTE direction,
    BYTE interfaceNum,
    WORD size,
    BYTE * data,
    BYTE endpointDATA
);
Description

This function starts a CDC transfer. A read/write wrapper is provided in application interface file to access this function.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE request | Request type for Communication Interface
BYTE direction | 1=read, 0=write
BYTE interfaceNum | interface number of the requested transfer
BYTE size | Byte size of the data buffer
BYTE *data | Pointer to the data buffer
BYTE endpointDATA | endpoint details on which the transfer is requested
Return Values
Return Values | Description
USB_SUCCESS | Request started successfully
USB_CDC_DEVICE_NOT_FOUND | No device with specified address
USB_CDC_DEVICE_BUSY | Device not in proper state for performing a transfer
Remarks

None

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Interface Routines > USBHostCDCTransfer Function


USBHostCDCTransferIsComplete Function

Contents | Index | Home
Previous | Up | Next
USBHostCDCTransferIsComplete Function
C
BOOL USBHostCDCTransferIsComplete(
    BYTE deviceAddress,
    BYTE * errorCode,
    BYTE * byteCount
);
Description

This function indicates whether or not the last transfer is complete. If the functions returns TRUE, the returned byte count and error code are valid. Since only one transfer can be performed at once and only one endpoint can be used, we only need to know the device address.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE *errorCode | Error code from last transfer
DWORD *byteCount | Number of bytes transferred
Return Values
Return Values | Description
TRUE | Transfer is complete, errorCode is valid
FALSE | Transfer is not complete, errorCode is not valid
Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Interface Routines > USBHostCDCTransferIsComplete Function


Data Types and Constants

Contents | Index | Home
Previous | Up | Next
Data Types and Constants
Macros
Name | Description
DEVICE_CLASS_CDC | CDC Interface Class Code
EVENT_CDC_COMM_READ_DONE | A CDC Communication Read transfer has completed
EVENT_CDC_COMM_WRITE_DONE | A CDC Communication Write transfer has completed
EVENT_CDC_DATA_READ_DONE | A CDC Data Read transfer has completed
EVENT_CDC_DATA_WRITE_DONE | A CDC Data Write transfer has completed
EVENT_CDC_NAK_TIMEOUT | CDC device NAK timeout has occurred
EVENT_CDC_NONE | No event occured (NULL event)
EVENT_CDC_OFFSET | If the application has not defined an offset for CDC events, set it to 0.
EVENT_CDC_RESET | CDC reset complete
USB_CDC_ABSTRACT_CONTROL_MODEL | Abstract Control Model
USB_CDC_ATM_NETWORKING_CONTROL_MODEL | ATM Networking Control Model
USB_CDC_CAPI_CONTROL_MODEL | CAPI Control Model
USB_CDC_CLASS_ERROR | CDC Class Error Codes
USB_CDC_COMM_INTF | Communication Interface Class Code
USB_CDC_COMMAND_FAILED | Command failed at the device.
USB_CDC_COMMAND_PASSED | Command was successful.
USB_CDC_CONTROL_LINE_LENGTH | Number of bytes Control line transfer
USB_CDC_CS_ENDPOINT | This is macro USB_CDC_CS_ENDPOINT.
USB_CDC_CS_INTERFACE | Functional Descriptor Details Type Values for the bDscType Field
USB_CDC_DATA_INTF | Data Interface Class Codes
USB_CDC_DEVICE_BUSY | A transfer is currently in progress.
USB_CDC_DEVICE_DETACHED | Device is detached.
USB_CDC_DEVICE_HOLDING | Device is holding due to error
USB_CDC_DEVICE_MANAGEMENT | Device Management
USB_CDC_DEVICE_NOT_FOUND | Device with the specified address is not available.
USB_CDC_DIRECT_LINE_CONTROL_MODEL | Direct Line Control Model
USB_CDC_DSC_FN_ACM | ACM - Abstract Control Management
USB_CDC_DSC_FN_CALL_MGT | This is macro USB_CDC_DSC_FN_CALL_MGT.
USB_CDC_DSC_FN_COUNTRY_SELECTION | This is macro USB_CDC_DSC_FN_COUNTRY_SELECTION.
USB_CDC_DSC_FN_DLM | DLM - Direct Line Managment
USB_CDC_DSC_FN_HEADER | bDscSubType in Functional Descriptors
USB_CDC_DSC_FN_RPT_CAPABILITIES | This is macro USB_CDC_DSC_FN_RPT_CAPABILITIES.
USB_CDC_DSC_FN_TEL_OP_MODES | This is macro USB_CDC_DSC_FN_TEL_OP_MODES.
USB_CDC_DSC_FN_TELEPHONE_RINGER | This is macro USB_CDC_DSC_FN_TELEPHONE_RINGER.
USB_CDC_DSC_FN_UNION | This is macro USB_CDC_DSC_FN_UNION.
USB_CDC_DSC_FN_USB_TERMINAL | This is macro USB_CDC_DSC_FN_USB_TERMINAL.
USB_CDC_ETHERNET_EMULATION_MODEL | Ethernet Emulation Model
USB_CDC_ETHERNET_NETWORKING_CONTROL_MODEL | Ethernet Networking Control Model
USB_CDC_GET_COMM_FEATURE | Returns the current settings for the communications feature.
USB_CDC_GET_ENCAPSULATED_REQUEST | Requests a response in the format of the supported control protocol.
USB_CDC_GET_LINE_CODING | Requests current DTE rate, stop-bits, parity, and number-of-character bits.
USB_CDC_ILLEGAL_REQUEST | Cannot perform requested operation.
USB_CDC_INITIALIZING | Device is initializing.
USB_CDC_INTERFACE_ERROR | The interface layer cannot support the device.
USB_CDC_LINE_CODING_LENGTH | Number of bytes Line Coding transfer
USB_CDC_MOBILE_DIRECT_LINE_MODEL | Mobile Direct Line Model
USB_CDC_MULTI_CHANNEL_CONTROL_MODEL | Multi-Channel Control Model
USB_CDC_NO_PROTOCOL | No class specific protocol required For more.... see Table 7 in USB CDC Specification 1.2
USB_CDC_NO_REPORT_DESCRIPTOR | No report descriptor found
USB_CDC_NORMAL_RUNNING | Device is running and available for data transfers.
USB_CDC_OBEX | OBEX
USB_CDC_PHASE_ERROR | Command had a phase error at the device.
USB_CDC_REPORT_DESCRIPTOR_BAD | Report Descriptor for not proper
USB_CDC_RESET_ERROR | An error occurred while resetting the device.
USB_CDC_RESETTING_DEVICE | Device is being reset.
USB_CDC_SEND_BREAK | Sends special carrier modulation used to specify [V24] style break.
USB_CDC_SEND_ENCAPSULATED_COMMAND | Issues a command in the format of the supported control protocol.
USB_CDC_SET_COMM_FEATURE | Controls the settings for a particular communications feature.
USB_CDC_SET_CONTROL_LINE_STATE | V24] signal used to tell the DCE device the DTE device is now present.
USB_CDC_SET_LINE_CODING | Configures DTE rate, stop-bits, parity, and number-of-character bits.
USB_CDC_TELEPHONE_CONTROL_MODEL | Telephone Control Model
USB_CDC_V25TER | Common AT commands ("Hayes(TM)")
USB_CDC_WIRELESS_HANDSET_CONTROL_MODEL | Wireless Handset Control Model
Structures
Name | Description
_COMM_INTERFACE_DETAILS | This structure stores communication interface details of the attached CDC device
_DATA_INTERFACE_DETAILS | This structure stores data interface details of the attached CDC device
_USB_CDC_ACM_FN_DSC | Abstract Control Management Functional Descriptor
_USB_CDC_CALL_MGT_FN_DSC | Call Management Functional Descriptor
_USB_CDC_DEVICE_INFO | This structure is used to hold information about an attached CDC device
_USB_CDC_HEADER_FN_DSC | Header Functional Descriptor
_USB_CDC_UNION_FN_DSC | Union Functional Descriptor
COMM_INTERFACE_DETAILS | This structure stores communication interface details of the attached CDC device
DATA_INTERFACE_DETAILS | This structure stores data interface details of the attached CDC device
USB_CDC_ACM_FN_DSC | Abstract Control Management Functional Descriptor
USB_CDC_CALL_MGT_FN_DSC | Call Management Functional Descriptor
USB_CDC_DEVICE_INFO | This structure is used to hold information about an attached CDC device
USB_CDC_HEADER_FN_DSC | Header Functional Descriptor
USB_CDC_UNION_FN_DSC | Union Functional Descriptor
Unions
Name | Description
_USB_CDC_CONTROL_SIGNAL_BITMAP | This is type USB_CDC_CONTROL_SIGNAL_BITMAP.
_USB_CDC_LINE_CODING | This is type USB_CDC_LINE_CODING.
USB_CDC_CONTROL_SIGNAL_BITMAP | This is type USB_CDC_CONTROL_SIGNAL_BITMAP.
USB_CDC_LINE_CODING | This is type USB_CDC_LINE_CODING.
Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants


COMM_INTERFACE_DETAILS Structure

Contents | Index | Home
Previous | Up | Next
COMM_INTERFACE_DETAILS Structure
C
typedef struct _COMM_INTERFACE_DETAILS {
  BYTE interfaceNum;
  BYTE noOfEndpoints;
  USB_CDC_HEADER_FN_DSC Header_Fn_Dsc;
  USB_CDC_ACM_FN_DSC ACM_Fn_Desc;
  USB_CDC_UNION_FN_DSC Union_Fn_Desc;
  USB_CDC_CALL_MGT_FN_DSC Call_Mgt_Fn_Desc;
  WORD endpointMaxDataSize;
  WORD endpointInDataSize;
  WORD endpointOutDataSize;
  BYTE endpointPollInterval;
  BYTE endpointType;
  BYTE endpointIN;
  BYTE endpointOUT;
} COMM_INTERFACE_DETAILS;
Description

This structure stores communication interface details of the attached CDC device

Members
Members | Description
BYTE interfaceNum; | communication interface number
BYTE noOfEndpoints; | Number endpoints for communication interface Functional Descriptor Details
USB_CDC_HEADER_FN_DSC Header_Fn_Dsc; | Header Function Descriptor
USB_CDC_ACM_FN_DSC ACM_Fn_Desc; | Abstract Control Model Function Descriptor
USB_CDC_UNION_FN_DSC Union_Fn_Desc; | Union Function Descriptor
USB_CDC_CALL_MGT_FN_DSC Call_Mgt_Fn_Desc; | Call Management Function Descriptor Endpoint Descriptor Details
WORD endpointMaxDataSize; | Max data size for a interface.
WORD endpointInDataSize; | Max data size for a interface.
WORD endpointOutDataSize; | Max data size for a interface.
BYTE endpointPollInterval; | Polling rate of corresponding interface.
BYTE endpointType; | Endpoint type - either Isochronous or Bulk
BYTE endpointIN; | IN endpoint for comm interface.
BYTE endpointOUT; | IN endpoint for comm interface.
Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > COMM_INTERFACE_DETAILS Structure


DATA_INTERFACE_DETAILS Structure

Contents | Index | Home
Previous | Up | Next
DATA_INTERFACE_DETAILS Structure
C
typedef struct _DATA_INTERFACE_DETAILS {
  BYTE interfaceNum;
  BYTE noOfEndpoints;
  WORD endpointInDataSize;
  WORD endpointOutDataSize;
  BYTE endpointType;
  BYTE endpointIN;
  BYTE endpointOUT;
} DATA_INTERFACE_DETAILS;
Description

This structure stores data interface details of the attached CDC device

Members
Members | Description
BYTE interfaceNum; | Data interface number
BYTE noOfEndpoints; | number of endpoints associated with data interface
WORD endpointInDataSize; | Max data size for a interface.
WORD endpointOutDataSize; | Max data size for a interface.
BYTE endpointType; | Endpoint type - either Isochronous or Bulk
BYTE endpointIN; | IN endpoint for comm interface.
BYTE endpointOUT; | IN endpoint for comm interface.
Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > DATA_INTERFACE_DETAILS Structure


USB_CDC_ACM_FN_DSC Structure

Contents | Index | Home
Previous | Up | Next
USB_CDC_ACM_FN_DSC Structure
C
typedef struct _USB_CDC_ACM_FN_DSC {
  BYTE bFNLength;
  BYTE bDscType;
  BYTE bDscSubType;
  BYTE bmCapabilities;
} USB_CDC_ACM_FN_DSC;
Description

Abstract Control Management Functional Descriptor

Members
Members | Description
BYTE bFNLength; | Size of this functional descriptor, in bytes.
BYTE bDscType; | CS_INTERFACE
BYTE bDscSubType; | Abstract Control Management functional descriptor subtype as defined in [USBCDC1.2].
BYTE bmCapabilities; | The capabilities that this configuration supports. (A bit value of zero means that the request is not supported.)
Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_ACM_FN_DSC Structure


USB_CDC_CALL_MGT_FN_DSC Structure

Contents | Index | Home
Previous | Up | Next
USB_CDC_CALL_MGT_FN_DSC Structure
C
typedef struct _USB_CDC_CALL_MGT_FN_DSC {
  BYTE bFNLength;
  BYTE bDscType;
  BYTE bDscSubType;
  BYTE bmCapabilities;
  BYTE bDataInterface;
} USB_CDC_CALL_MGT_FN_DSC;
Description

Call Management Functional Descriptor

Members
Members | Description
BYTE bFNLength; | Size of this functional descriptor, in bytes.
BYTE bDscType; | CS_INTERFACE
BYTE bDscSubType; | Call Management functional descriptor subtype, as defined in [USBCDC1.2].
BYTE bmCapabilities; | The capabilities that this configuration supports:
BYTE bDataInterface; | Interface number of Data Class interface optionally used for call management.
Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_CALL_MGT_FN_DSC Structure


USB_CDC_CONTROL_SIGNAL_BITMAP Union

Contents | Index | Home
Previous | Up | Next
USB_CDC_CONTROL_SIGNAL_BITMAP Union
C
typedef union _USB_CDC_CONTROL_SIGNAL_BITMAP {
  BYTE _byte;
  struct {
    unsigned DTE_PRESENT : 1;
    unsigned CARRIER_CONTROL : 1;
  }
} USB_CDC_CONTROL_SIGNAL_BITMAP;
Description

This is type USB_CDC_CONTROL_SIGNAL_BITMAP.

Members
Members | Description
unsigned DTE_PRESENT : 1; | 0] Not Present [1] Present
unsigned CARRIER_CONTROL : 1; | 0] Deactivate [1] Activate
Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_CONTROL_SIGNAL_BITMAP Union


USB_CDC_DEVICE_INFO Structure

Contents | Index | Home
Previous | Up | Next
USB_CDC_DEVICE_INFO Structure
C
typedef struct _USB_CDC_DEVICE_INFO {
  BYTE* userData;
  WORD reportSize;
  WORD remainingBytes;
  WORD bytesTransferred;
  union {
    struct {
      BYTE bfDirection : 1;
      BYTE bfReset : 1;
      BYTE bfClearDataIN : 1;
      BYTE bfClearDataOUT : 1;
    }
    BYTE val;
  } flags;
  BYTE driverSupported;
  BYTE deviceAddress;
  BYTE errorCode;
  BYTE state;
  BYTE returnState;
  BYTE noOfInterfaces;
  BYTE interface;
  BYTE endpointDATA;
  BYTE commRequest;
  BYTE clientDriverID;
  COMM_INTERFACE_DETAILS commInterface;
  DATA_INTERFACE_DETAILS dataInterface;
} USB_CDC_DEVICE_INFO;
Description

This structure is used to hold information about an attached CDC device

Members
Members | Description
BYTE* userData; | Data pointer to application buffer.
WORD reportSize; | Total length of user data
WORD remainingBytes; | Number bytes remaining to be transferrerd in case user data length is more than 64 bytes
WORD bytesTransferred; | Number of bytes transferred to/from the user's data buffer.
BYTE bfDirection : 1; | Direction of current transfer (0=OUT, 1=IN).
BYTE bfReset : 1; | Flag indicating to perform CDC Reset.
BYTE bfClearDataIN : 1; | Flag indicating to clear the IN endpoint.
BYTE bfClearDataOUT : 1; | Flag indicating to clear the OUT endpoint.
BYTE driverSupported; | If CDC driver supports requested Class,Subclass & Protocol.
BYTE deviceAddress; | Address of the device on the bus.
BYTE errorCode; | Error code of last error.
BYTE state; | State machine state of the device.
BYTE returnState; | State to return to after performing error handling.
BYTE noOfInterfaces; | Total number of interfaces in the device.
BYTE interface; | Interface number of current transfer.
BYTE endpointDATA; | Endpoint to use for the current transfer.
BYTE commRequest; | Current Communication code
BYTE clientDriverID; | Client driver ID for device requests.
COMM_INTERFACE_DETAILS commInterface; | This structure stores communication interface details.
DATA_INTERFACE_DETAILS dataInterface; | This structure stores data interface details.
Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DEVICE_INFO Structure


USB_CDC_HEADER_FN_DSC Structure

Contents | Index | Home
Previous | Up | Next
USB_CDC_HEADER_FN_DSC Structure
C
typedef struct _USB_CDC_HEADER_FN_DSC {
  BYTE bFNLength;
  BYTE bDscType;
  BYTE bDscSubType;
  BYTE bcdCDC[2];
} USB_CDC_HEADER_FN_DSC;
Description

Header Functional Descriptor

Members
Members | Description
BYTE bFNLength; | Size of this functional descriptor, in bytes.
BYTE bDscType; | CS_INTERFACE
BYTE bDscSubType; | Header. This is defined in [USBCDC1.2], which defines this as a header.
BYTE bcdCDC[2]; | USB Class Definitions for Communications Devices Specification release number in binary-coded decimal.
Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_HEADER_FN_DSC Structure


USB_CDC_LINE_CODING Union

Contents | Index | Home
Previous | Up | Next
USB_CDC_LINE_CODING Union
C
typedef union _USB_CDC_LINE_CODING {
  struct {
    BYTE _byte[USB_CDC_LINE_CODING_LENGTH];
  }
  struct {
    DWORD_VAL dwDTERate;
    BYTE bCharFormat;
    BYTE bParityType;
    BYTE bDataBits;
  }
} USB_CDC_LINE_CODING;
Description

This is type USB_CDC_LINE_CODING.

Members
Members | Description
DWORD_VAL dwDTERate; | Data terminal rate, in bits per second.
BYTE bCharFormat; | Stop bits 0:1 Stop bit, 1:1.5 Stop bits, 2:2 Stop bits
BYTE bParityType; | Parity 0:None, 1:Odd, 2:Even, 3:Mark, 4:Space
BYTE bDataBits; | Data bits (5, 6, 7, 8 or 16)
Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_LINE_CODING Union


USB_CDC_UNION_FN_DSC Structure

Contents | Index | Home
Previous | Up | Next
USB_CDC_UNION_FN_DSC Structure
C
typedef struct _USB_CDC_UNION_FN_DSC {
  BYTE bFNLength;
  BYTE bDscType;
  BYTE bDscSubType;
  BYTE bMasterIntf;
  BYTE bSaveIntf0;
} USB_CDC_UNION_FN_DSC;
Description

Union Functional Descriptor

Members
Members | Description
BYTE bFNLength; | Size of this functional descriptor, in bytes.
BYTE bDscType; | CS_INTERFACE
BYTE bDscSubType; | Union Descriptor Functional Descriptor subtype as defined in [USBCDC1.2].
BYTE bMasterIntf; | Interface number of the control (Communications Class) interface
BYTE bSaveIntf0; | Interface number of the subordinate (Data Class) interface
Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_UNION_FN_DSC Structure


DEVICE_CLASS_CDC Macro

Contents | Index | Home
Previous | Up | Next
DEVICE_CLASS_CDC Macro
C
#define DEVICE_CLASS_CDC 0x02 // CDC Interface Class Code
Description

CDC Interface Class Code

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > DEVICE_CLASS_CDC Macro


EVENT_CDC_COMM_READ_DONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_CDC_COMM_READ_DONE Macro
C
#define EVENT_CDC_COMM_READ_DONE EVENT_CDC_BASE + EVENT_CDC_OFFSET + 2   // A CDC Communication Read transfer has completed
Description

A CDC Communication Read transfer has completed

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > EVENT_CDC_COMM_READ_DONE Macro


EVENT_CDC_COMM_WRITE_DONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_CDC_COMM_WRITE_DONE Macro
C
#define EVENT_CDC_COMM_WRITE_DONE EVENT_CDC_BASE + EVENT_CDC_OFFSET + 3   // A CDC Communication Write transfer has completed
Description

A CDC Communication Write transfer has completed

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > EVENT_CDC_COMM_WRITE_DONE Macro


EVENT_CDC_DATA_READ_DONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_CDC_DATA_READ_DONE Macro
C
#define EVENT_CDC_DATA_READ_DONE EVENT_CDC_BASE + EVENT_CDC_OFFSET + 4   // A CDC Data Read transfer has completed
Description

A CDC Data Read transfer has completed

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > EVENT_CDC_DATA_READ_DONE Macro


EVENT_CDC_DATA_WRITE_DONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_CDC_DATA_WRITE_DONE Macro
C
#define EVENT_CDC_DATA_WRITE_DONE EVENT_CDC_BASE + EVENT_CDC_OFFSET + 5   // A CDC Data Write transfer has completed
Description

A CDC Data Write transfer has completed

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > EVENT_CDC_DATA_WRITE_DONE Macro


EVENT_CDC_NAK_TIMEOUT Macro

Contents | Index | Home
Previous | Up | Next
EVENT_CDC_NAK_TIMEOUT Macro
C
#define EVENT_CDC_NAK_TIMEOUT EVENT_CDC_BASE + EVENT_CDC_OFFSET + 7   // CDC device NAK timeout has occurred
Description

CDC device NAK timeout has occurred

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > EVENT_CDC_NAK_TIMEOUT Macro


EVENT_CDC_NONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_CDC_NONE Macro
C
#define EVENT_CDC_NONE EVENT_CDC_BASE + EVENT_CDC_OFFSET + 0   // No event occured (NULL event)
Description

No event occured (NULL event)

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > EVENT_CDC_NONE Macro


EVENT_CDC_OFFSET Macro

Contents | Index | Home
Previous | Up | Next
EVENT_CDC_OFFSET Macro
C
#define EVENT_CDC_OFFSET 0
Description

If the application has not defined an offset for CDC events, set it to 0.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > EVENT_CDC_OFFSET Macro


EVENT_CDC_RESET Macro

Contents | Index | Home
Previous | Up | Next
EVENT_CDC_RESET Macro
C
#define EVENT_CDC_RESET EVENT_CDC_BASE + EVENT_CDC_OFFSET + 6   // CDC reset complete
Description

CDC reset complete

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > EVENT_CDC_RESET Macro


USB_CDC_ABSTRACT_CONTROL_MODEL Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_ABSTRACT_CONTROL_MODEL Macro
C
#define USB_CDC_ABSTRACT_CONTROL_MODEL 0x02 // Abstract Control Model
Description

Abstract Control Model

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_ABSTRACT_CONTROL_MODEL Macro


USB_CDC_ATM_NETWORKING_CONTROL_MODEL Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_ATM_NETWORKING_CONTROL_MODEL Macro
C
#define USB_CDC_ATM_NETWORKING_CONTROL_MODEL 0x07 // ATM Networking Control Model
Description

ATM Networking Control Model

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_ATM_NETWORKING_CONTROL_MODEL Macro


USB_CDC_CAPI_CONTROL_MODEL Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_CAPI_CONTROL_MODEL Macro
C
#define USB_CDC_CAPI_CONTROL_MODEL 0x05 // CAPI Control Model
Description

CAPI Control Model

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_CAPI_CONTROL_MODEL Macro


USB_CDC_CLASS_ERROR Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_CLASS_ERROR Macro
C
#define USB_CDC_CLASS_ERROR USB_ERROR_CLASS_DEFINED
Description

CDC Class Error Codes

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_CLASS_ERROR Macro


USB_CDC_COMM_INTF Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_COMM_INTF Macro
C
#define USB_CDC_COMM_INTF 0x02 // Communication Interface Class Code
Description

Communication Interface Class Code

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_COMM_INTF Macro


USB_CDC_COMMAND_FAILED Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_COMMAND_FAILED Macro
C
#define USB_CDC_COMMAND_FAILED (USB_CDC_CLASS_ERROR | 0x01) // Command failed at the device.
Description

Command failed at the device.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_COMMAND_FAILED Macro


USB_CDC_COMMAND_PASSED Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_COMMAND_PASSED Macro
C
#define USB_CDC_COMMAND_PASSED USB_SUCCESS                 // Command was successful.
Description

Command was successful.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_COMMAND_PASSED Macro


USB_CDC_CONTROL_LINE_LENGTH Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_CONTROL_LINE_LENGTH Macro
C
#define USB_CDC_CONTROL_LINE_LENGTH 0x00   // Number of bytes Control line transfer
Description

Number of bytes Control line transfer

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_CONTROL_LINE_LENGTH Macro


USB_CDC_CS_ENDPOINT Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_CS_ENDPOINT Macro
C
#define USB_CDC_CS_ENDPOINT 0x25
Description

This is macro USB_CDC_CS_ENDPOINT.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_CS_ENDPOINT Macro


USB_CDC_CS_INTERFACE Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_CS_INTERFACE Macro
C
#define USB_CDC_CS_INTERFACE 0x24
Description

Functional Descriptor Details Type Values for the bDscType Field

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_CS_INTERFACE Macro


USB_CDC_DATA_INTF Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DATA_INTF Macro
C
#define USB_CDC_DATA_INTF 0x0A
Description

Data Interface Class Codes

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DATA_INTF Macro


USB_CDC_DEVICE_BUSY Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DEVICE_BUSY Macro
C
#define USB_CDC_DEVICE_BUSY (USB_CDC_CLASS_ERROR | 0x04) // A transfer is currently in progress.
Description

A transfer is currently in progress.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DEVICE_BUSY Macro


USB_CDC_DEVICE_DETACHED Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DEVICE_DETACHED Macro
C
#define USB_CDC_DEVICE_DETACHED 0x50    // Device is detached.
Description

Device is detached.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DEVICE_DETACHED Macro


USB_CDC_DEVICE_HOLDING Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DEVICE_HOLDING Macro
C
#define USB_CDC_DEVICE_HOLDING 0x54    // Device is holding due to error
Description

Device is holding due to error

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DEVICE_HOLDING Macro


USB_CDC_DEVICE_MANAGEMENT Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DEVICE_MANAGEMENT Macro
C
#define USB_CDC_DEVICE_MANAGEMENT 0x09 // Device Management
Description

Device Management

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DEVICE_MANAGEMENT Macro


USB_CDC_DEVICE_NOT_FOUND Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DEVICE_NOT_FOUND Macro
C
#define USB_CDC_DEVICE_NOT_FOUND (USB_CDC_CLASS_ERROR | 0x03) // Device with the specified address is not available.
Description

Device with the specified address is not available.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DEVICE_NOT_FOUND Macro


USB_CDC_DIRECT_LINE_CONTROL_MODEL Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DIRECT_LINE_CONTROL_MODEL Macro
C
#define USB_CDC_DIRECT_LINE_CONTROL_MODEL 0x01 // Direct Line Control Model
Description

Direct Line Control Model

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DIRECT_LINE_CONTROL_MODEL Macro


USB_CDC_DSC_FN_ACM Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DSC_FN_ACM Macro
C
#define USB_CDC_DSC_FN_ACM 0x02    // ACM - Abstract Control Management
Description

ACM - Abstract Control Management

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DSC_FN_ACM Macro


USB_CDC_DSC_FN_CALL_MGT Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DSC_FN_CALL_MGT Macro
C
#define USB_CDC_DSC_FN_CALL_MGT 0x01
Description

This is macro USB_CDC_DSC_FN_CALL_MGT.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DSC_FN_CALL_MGT Macro


USB_CDC_DSC_FN_COUNTRY_SELECTION Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DSC_FN_COUNTRY_SELECTION Macro
C
#define USB_CDC_DSC_FN_COUNTRY_SELECTION 0x07
Description

This is macro USB_CDC_DSC_FN_COUNTRY_SELECTION.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DSC_FN_COUNTRY_SELECTION Macro


USB_CDC_DSC_FN_DLM Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DSC_FN_DLM Macro
C
#define USB_CDC_DSC_FN_DLM 0x03    // DLM - Direct Line Managment
Description

DLM - Direct Line Managment

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DSC_FN_DLM Macro


USB_CDC_DSC_FN_HEADER Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DSC_FN_HEADER Macro
C
#define USB_CDC_DSC_FN_HEADER 0x00
Description

bDscSubType in Functional Descriptors

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DSC_FN_HEADER Macro


USB_CDC_DSC_FN_RPT_CAPABILITIES Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DSC_FN_RPT_CAPABILITIES Macro
C
#define USB_CDC_DSC_FN_RPT_CAPABILITIES 0x05
Description

This is macro USB_CDC_DSC_FN_RPT_CAPABILITIES.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DSC_FN_RPT_CAPABILITIES Macro


USB_CDC_DSC_FN_TEL_OP_MODES Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DSC_FN_TEL_OP_MODES Macro
C
#define USB_CDC_DSC_FN_TEL_OP_MODES 0x08
Description

This is macro USB_CDC_DSC_FN_TEL_OP_MODES.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DSC_FN_TEL_OP_MODES Macro


USB_CDC_DSC_FN_TELEPHONE_RINGER Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DSC_FN_TELEPHONE_RINGER Macro
C
#define USB_CDC_DSC_FN_TELEPHONE_RINGER 0x04
Description

This is macro USB_CDC_DSC_FN_TELEPHONE_RINGER.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DSC_FN_TELEPHONE_RINGER Macro


USB_CDC_DSC_FN_UNION Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DSC_FN_UNION Macro
C
#define USB_CDC_DSC_FN_UNION 0x06
Description

This is macro USB_CDC_DSC_FN_UNION.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DSC_FN_UNION Macro


USB_CDC_DSC_FN_USB_TERMINAL Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_DSC_FN_USB_TERMINAL Macro
C
#define USB_CDC_DSC_FN_USB_TERMINAL 0x09
Description

This is macro USB_CDC_DSC_FN_USB_TERMINAL.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_DSC_FN_USB_TERMINAL Macro


USB_CDC_ETHERNET_EMULATION_MODEL Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_ETHERNET_EMULATION_MODEL Macro
C
#define USB_CDC_ETHERNET_EMULATION_MODEL 0x0C // Ethernet Emulation Model
Description

Ethernet Emulation Model

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_ETHERNET_EMULATION_MODEL Macro


USB_CDC_ETHERNET_NETWORKING_CONTROL_MODEL Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_ETHERNET_NETWORKING_CONTROL_MODEL Macro
C
#define USB_CDC_ETHERNET_NETWORKING_CONTROL_MODEL 0x06 // Ethernet Networking Control Model
Description

Ethernet Networking Control Model

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_ETHERNET_NETWORKING_CONTROL_MODEL Macro


USB_CDC_GET_COMM_FEATURE Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_GET_COMM_FEATURE Macro
C
#define USB_CDC_GET_COMM_FEATURE 0x03    // Returns the current settings for the communications feature.
Description

Returns the current settings for the communications feature.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_GET_COMM_FEATURE Macro


USB_CDC_GET_ENCAPSULATED_REQUEST Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_GET_ENCAPSULATED_REQUEST Macro
C
#define USB_CDC_GET_ENCAPSULATED_REQUEST 0x01    // Requests a response in the format of the supported control protocol.
Description

Requests a response in the format of the supported control protocol.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_GET_ENCAPSULATED_REQUEST Macro


USB_CDC_GET_LINE_CODING Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_GET_LINE_CODING Macro
C
#define USB_CDC_GET_LINE_CODING 0x21    // Requests current DTE rate, stop-bits, parity, and number-of-character bits.
Description

Requests current DTE rate, stop-bits, parity, and number-of-character bits.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_GET_LINE_CODING Macro


USB_CDC_ILLEGAL_REQUEST Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_ILLEGAL_REQUEST Macro
C
#define USB_CDC_ILLEGAL_REQUEST (USB_CDC_CLASS_ERROR | 0x0B) // Cannot perform requested operation.
Description

Cannot perform requested operation.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_ILLEGAL_REQUEST Macro


USB_CDC_INITIALIZING Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_INITIALIZING Macro
C
#define USB_CDC_INITIALIZING 0x51    // Device is initializing.
Description

Device is initializing.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_INITIALIZING Macro


USB_CDC_INTERFACE_ERROR Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_INTERFACE_ERROR Macro
C
#define USB_CDC_INTERFACE_ERROR (USB_CDC_CLASS_ERROR | 0x06) // The interface layer cannot support the device.
Description

The interface layer cannot support the device.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_INTERFACE_ERROR Macro


USB_CDC_LINE_CODING_LENGTH Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_LINE_CODING_LENGTH Macro
C
#define USB_CDC_LINE_CODING_LENGTH 0x07   // Number of bytes Line Coding transfer
Description

Number of bytes Line Coding transfer

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_LINE_CODING_LENGTH Macro


USB_CDC_MOBILE_DIRECT_LINE_MODEL Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_MOBILE_DIRECT_LINE_MODEL Macro
C
#define USB_CDC_MOBILE_DIRECT_LINE_MODEL 0x0A // Mobile Direct Line Model
Description

Mobile Direct Line Model

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_MOBILE_DIRECT_LINE_MODEL Macro


USB_CDC_MULTI_CHANNEL_CONTROL_MODEL Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_MULTI_CHANNEL_CONTROL_MODEL Macro
C
#define USB_CDC_MULTI_CHANNEL_CONTROL_MODEL 0x04 // Multi-Channel Control Model
Description

Multi-Channel Control Model

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_MULTI_CHANNEL_CONTROL_MODEL Macro


USB_CDC_NO_PROTOCOL Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_NO_PROTOCOL Macro
C
#define USB_CDC_NO_PROTOCOL 0x00    // No class specific protocol required
Description

No class specific protocol required For more.... see Table 7 in USB CDC Specification 1.2

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_NO_PROTOCOL Macro


USB_CDC_NO_REPORT_DESCRIPTOR Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_NO_REPORT_DESCRIPTOR Macro
C
#define USB_CDC_NO_REPORT_DESCRIPTOR (USB_CDC_CLASS_ERROR | 0x05) // No report descriptor found
Description

No report descriptor found

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_NO_REPORT_DESCRIPTOR Macro


USB_CDC_NORMAL_RUNNING Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_NORMAL_RUNNING Macro
C
#define USB_CDC_NORMAL_RUNNING 0x53    // Device is running and available for data transfers.
Description

Device is running and available for data transfers.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_NORMAL_RUNNING Macro


USB_CDC_OBEX Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_OBEX Macro
C
#define USB_CDC_OBEX 0x0B // OBEX
Description

OBEX

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_OBEX Macro


USB_CDC_PHASE_ERROR Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_PHASE_ERROR Macro
C
#define USB_CDC_PHASE_ERROR (USB_CDC_CLASS_ERROR | 0x02) // Command had a phase error at the device.
Description

Command had a phase error at the device.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_PHASE_ERROR Macro


USB_CDC_REPORT_DESCRIPTOR_BAD Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_REPORT_DESCRIPTOR_BAD Macro
C
#define USB_CDC_REPORT_DESCRIPTOR_BAD (USB_CDC_CLASS_ERROR | 0x05) // Report Descriptor for not proper
Description

Report Descriptor for not proper

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_REPORT_DESCRIPTOR_BAD Macro


USB_CDC_RESET_ERROR Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_RESET_ERROR Macro
C
#define USB_CDC_RESET_ERROR (USB_CDC_CLASS_ERROR | 0x0A) // An error occurred while resetting the device.
Description

An error occurred while resetting the device.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_RESET_ERROR Macro


USB_CDC_RESETTING_DEVICE Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_RESETTING_DEVICE Macro
C
#define USB_CDC_RESETTING_DEVICE 0x55    // Device is being reset.
Description

Device is being reset.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_RESETTING_DEVICE Macro


USB_CDC_SEND_BREAK Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_SEND_BREAK Macro
C
#define USB_CDC_SEND_BREAK 0x23    // Sends special carrier modulation used to specify [V24] style break.
Description

Sends special carrier modulation used to specify [V24] style break.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_SEND_BREAK Macro


USB_CDC_SEND_ENCAPSULATED_COMMAND Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_SEND_ENCAPSULATED_COMMAND Macro
C
#define USB_CDC_SEND_ENCAPSULATED_COMMAND 0x00    // Issues a command in the format of the supported control protocol.
Description

Issues a command in the format of the supported control protocol.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_SEND_ENCAPSULATED_COMMAND Macro


USB_CDC_SET_COMM_FEATURE Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_SET_COMM_FEATURE Macro
C
#define USB_CDC_SET_COMM_FEATURE 0x02    // Controls the settings for a particular communications feature.
Description

Controls the settings for a particular communications feature.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_SET_COMM_FEATURE Macro


USB_CDC_SET_CONTROL_LINE_STATE Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_SET_CONTROL_LINE_STATE Macro
C
#define USB_CDC_SET_CONTROL_LINE_STATE 0x22    // [V24] signal used to tell the DCE device the DTE device is now present.
Description

V24] signal used to tell the DCE device the DTE device is now present.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_SET_CONTROL_LINE_STATE Macro


USB_CDC_SET_LINE_CODING Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_SET_LINE_CODING Macro
C
#define USB_CDC_SET_LINE_CODING 0x20    // Configures DTE rate, stop-bits, parity, and number-of-character bits.
Description

Configures DTE rate, stop-bits, parity, and number-of-character bits.

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_SET_LINE_CODING Macro


USB_CDC_TELEPHONE_CONTROL_MODEL Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_TELEPHONE_CONTROL_MODEL Macro
C
#define USB_CDC_TELEPHONE_CONTROL_MODEL 0x03 // Telephone Control Model
Description

Telephone Control Model

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_TELEPHONE_CONTROL_MODEL Macro


USB_CDC_V25TER Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_V25TER Macro
C
#define USB_CDC_V25TER 0x01    // Common AT commands ("Hayes(TM)")
Description

Common AT commands ("Hayes(TM)")

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_V25TER Macro


USB_CDC_WIRELESS_HANDSET_CONTROL_MODEL Macro

Contents | Index | Home
Previous | Up | Next
USB_CDC_WIRELESS_HANDSET_CONTROL_MODEL Macro
C
#define USB_CDC_WIRELESS_HANDSET_CONTROL_MODEL 0x08 // Wireless Handset Control Model
Description

Wireless Handset Control Model

Application Programming Interface (API) > Embedded Host API > CDC Client Driver > Data Types and Constants > USB_CDC_WIRELESS_HANDSET_CONTROL_MODEL Macro


Charger Client Driver

Contents | Index | Home
Previous | Up | Next
Charger Client Driver

USB devices that obey the USB specification will only draw 100mA from the bus until they are enumerated and less than 2.5mA when the bus is idle. In some situations this is not sufficient for a quick charge of the batteries. These devices often have a mode where they request more than 100mA but require permission from the host before drawing that current. This client driver simply allows a device to enumerate for the purpose of allowing this charging rate.

This client driver can be utilized for any device where the VID and PID are known. But the stack also contains a provision to allow a client driver to be used for any VID and PID by specifying a VID of 0xFFFF and a PID of 0xFFFF in the TPL. BE SURE THAT THIS IS THE LAST ENTRY IN THE TPL.

Chargers and devices can also follow the USB Battery Charging specification (http://www.usb.org/developers/devclass_docs/batt_charging_1_0.zip). Not all devices implement this specification, however, so some devices will not be able to charge with chargers using this specification.

Topics
Name | Description
Interface Routines |
Data Type and Constants |
Application Programming Interface (API) > Embedded Host API > Charger Client Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
USBHostChargerDeviceDetached | This interface is used to check if the devich has been detached from the bus.
USBHostChargerEventHandler | This routine is called by the Host layer to notify the charger client of events that occur.
USBHostChargerGetDeviceAddress | This interface is used get the address of a specific generic device on the USB.
Application Programming Interface (API) > Embedded Host API > Charger Client Driver > Interface Routines


USBHostChargerDeviceDetached Function

Contents | Index | Home
Previous | Up | Next
USBHostChargerDeviceDetached Function
C
BOOL USBHostChargerDeviceDetached(
    BYTE deviceAddress
);
Description

This interface is used to check if the devich has been detached from the bus.

Preconditions

None

Parameters
Parameters | Description
deviceAddress | USB Address of the device.
Return Values
Return Values | Description
TRUE | The device has been detached, or an invalid deviceAddress is given.
FALSE | The device is attached
Remarks

None

Example
Copy Code
if (USBHostChargerDeviceDetached( deviceAddress ))
{
    // Handle detach
}
Application Programming Interface (API) > Embedded Host API > Charger Client Driver > Interface Routines > USBHostChargerDeviceDetached Function


USBHostChargerEventHandler Function

Contents | Index | Home
Previous | Up | Next
USBHostChargerEventHandler Function
C
BOOL USBHostChargerEventHandler(
    BYTE address,
    USB_EVENT event,
    void * data,
    DWORD size
);
Description

This routine is called by the Host layer to notify the charger client of events that occur. If the event is recognized, it is handled and the routine returns TRUE. Otherwise, it is ignored and the routine returns FALSE.

Preconditions

None

Parameters
Parameters | Description
BYTE address | Address of device with the event
USB_EVENT event | The bus event that occured
void *data | Pointer to event-specific data
DWORD size | Size of the event-specific data
Return Values
Return Values | Description
TRUE | The event was handled
FALSE | The event was not handled
Remarks

None

Application Programming Interface (API) > Embedded Host API > Charger Client Driver > Interface Routines > USBHostChargerEventHandler Function


USBHostChargerGetDeviceAddress Function

Contents | Index | Home
Previous | Up | Next
USBHostChargerGetDeviceAddress Function
C
BOOL USBHostChargerGetDeviceAddress(
    USB_CHARGING_DEVICE_ID * pDevID
);
Description

This interface is used get the address of a specific generic device on the USB.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
pDevID | Pointer to a structure containing the Device ID Info (VID, PID, and device address).
Return Values
Return Values | Description
TRUE | The device is connected
FALSE | The device is not connected.
Remarks

None

Example
Copy Code
USB_CHARGING_DEVICE_ID  deviceID;
BYTE                    deviceAddress;

deviceID.vid          = 0x1234;
deviceID.pid          = 0x5678;

if (USBHostChargerGetDeviceAddress(&deviceID))
{
    deviceAddress = deviceID.deviceAddress;
}
Application Programming Interface (API) > Embedded Host API > Charger Client Driver > Interface Routines > USBHostChargerGetDeviceAddress Function


Data Type and Constants

Contents | Index | Home
Previous | Up | Next
Data Type and Constants
Macros
Name | Description
EVENT_CHARGER_ATTACH | This event indicates that a device has been attached for charging. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to a USB_CHARGING_DEVICE_ID structure, and size is the size of the USB_CHARGING_DEVICE_ID structure.
EVENT_CHARGER_DETACH | This event indicates that the specified device has been detached from the USB. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to a BYTE that contains the device address, and size is the size of a BYTE.
EVENT_CHARGER_OFFSET | This is an optional offset for the values of the generated events. If necessary, the application can use a non-zero offset for the generic events to resolve conflicts in event number.
USB_MAX_CHARGING_DEVICES | Max Number of Supported Devices This value represents the maximum number of attached devices this client driver can support. If the user does not define a value, it will be set to 1.
Application Programming Interface (API) > Embedded Host API > Charger Client Driver > Data Type and Constants


EVENT_CHARGER_ATTACH Macro

Contents | Index | Home
Previous | Up | Next
EVENT_CHARGER_ATTACH Macro
C
#define EVENT_CHARGER_ATTACH (EVENT_CHARGER_BASE+EVENT_CHARGER_OFFSET+0)
Description

This event indicates that a device has been attached for charging. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to a USB_CHARGING_DEVICE_ID structure, and size is the size of the USB_CHARGING_DEVICE_ID structure.

Application Programming Interface (API) > Embedded Host API > Charger Client Driver > Data Type and Constants > EVENT_CHARGER_ATTACH Macro


EVENT_CHARGER_DETACH Macro

Contents | Index | Home
Previous | Up | Next
EVENT_CHARGER_DETACH Macro
C
#define EVENT_CHARGER_DETACH (EVENT_CHARGER_BASE+EVENT_CHARGER_OFFSET+1)
Description

This event indicates that the specified device has been detached from the USB. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to a BYTE that contains the device address, and size is the size of a BYTE.

Application Programming Interface (API) > Embedded Host API > Charger Client Driver > Data Type and Constants > EVENT_CHARGER_DETACH Macro


EVENT_CHARGER_OFFSET Macro

Contents | Index | Home
Previous | Up | Next
EVENT_CHARGER_OFFSET Macro
C
#define EVENT_CHARGER_OFFSET 0
Description

This is an optional offset for the values of the generated events. If necessary, the application can use a non-zero offset for the generic events to resolve conflicts in event number.

Application Programming Interface (API) > Embedded Host API > Charger Client Driver > Data Type and Constants > EVENT_CHARGER_OFFSET Macro


USB_MAX_CHARGING_DEVICES Macro

Contents | Index | Home
Previous | Up | Next
USB_MAX_CHARGING_DEVICES Macro
C
#define USB_MAX_CHARGING_DEVICES 1
Description

Max Number of Supported Devices

This value represents the maximum number of attached devices this client driver can support. If the user does not define a value, it will be set to 1.

Application Programming Interface (API) > Embedded Host API > Charger Client Driver > Data Type and Constants > USB_MAX_CHARGING_DEVICES Macro


Generic Client Driver

Contents | Index | Home
Previous | Up | Next
Generic Client Driver

Many USB applications do not fall under the category of an existing class. For these applications, the developer can create a custom driver, and utilize the Generic client driver to communicate with the device.

The Generic class offers simple wrappers to USB functions, with additional device management support.

See AN1143 - USB Generic Client on an Embedded Host for more information about this client driver.

Topics
Name | Description
Interface Routines |
Data Types and Constants |
Application Programming Interface (API) > Embedded Host API > Generic Client Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
USBHostGenericEventHandler | This routine is called by the Host layer to notify the general client of events that occur.
USBHostGenericGetDeviceAddress | This interface is used get the address of a specific generic device on the USB.
USBHostGenericInit | This function is called by the USB Embedded Host layer when a "generic" device attaches.
USBHostGenericRead | Use this routine to receive from the device and store it into memory.
USBHostGenericRxIsComplete | This routine indicates whether or not the last IN transfer is complete.
USBHostGenericTxIsComplete | This routine indicates whether or not the last OUT transfer is complete.
USBHostGenericWrite | Use this routine to transmit data from memory to the device.
Macros
Name | Description
USBHostGenericDeviceDetached | This interface is used to check if the devich has been detached from the bus.
USBHostGenericGetRxLength | This function retrieves the number of bytes copied to user's buffer by the most recent call to the USBHostGenericRead() function.
USBHostGenericRxIsBusy | This interface is used to check if the client driver is currently busy receiving data from the device.
USBHostGenericTxIsBusy | This interface is used to check if the client driver is currently busy transmitting data to the device.
Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Interface Routines


USBHostGenericDeviceDetached Macro

Contents | Index | Home
Previous | Up | Next
USBHostGenericDeviceDetached Macro
C
#define USBHostGenericDeviceDetached(a) ( (((a)==gc_DevData.ID.deviceAddress) && gc_DevData.flags.initialized == 1) ? FALSE : TRUE )
Description

This interface is used to check if the devich has been detached from the bus.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | USB Address of the device.
Return Values
Return Values | Description
TRUE | The device has been detached, or an invalid deviceAddress is given.
FALSE | The device is attached
Remarks

None

Example
Copy Code
if (USBHostGenericDeviceDetached( deviceAddress ))
{
    // Handle detach
}
Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Interface Routines > USBHostGenericDeviceDetached Macro


USBHostGenericEventHandler Function

Contents | Index | Home
Previous | Up | Next
USBHostGenericEventHandler Function
C
BOOL USBHostGenericEventHandler(
    BYTE address,
    USB_EVENT event,
    void * data,
    DWORD size
);
Description

This routine is called by the Host layer to notify the general client of events that occur. If the event is recognized, it is handled and the routine returns TRUE. Otherwise, it is ignored and the routine returns FALSE.

Preconditions

None

Parameters
Parameters | Description
BYTE address | Address of device with the event
USB_EVENT event | The bus event that occured
void *data | Pointer to event-specific data
DWORD size | Size of the event-specific data
Return Values
Return Values | Description
TRUE | The event was handled
FALSE | The event was not handled
Remarks

None

Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Interface Routines > USBHostGenericEventHandler Function


USBHostGenericGetDeviceAddress Function

Contents | Index | Home
Previous | Up | Next
USBHostGenericGetDeviceAddress Function
C
BOOL USBHostGenericGetDeviceAddress(
    GENERIC_DEVICE_ID * pDevID
);
Description

This interface is used get the address of a specific generic device on the USB.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
GENERIC_DEVICE_ID* pDevID | Pointer to a structure containing the Device ID Info (VID, PID, serial number, and device address).
Return Values
Return Values | Description
TRUE | The device is connected
FALSE | The device is not connected.
Remarks

None

Example
Copy Code
GENERIC_DEVICE_ID   deviceID;
WORD                serialNumber[] = { '1', '2', '3', '4', '5', '6' };
BYTE                deviceAddress;

deviceID.vid          = 0x1234;
deviceID.pid          = 0x5678;
deviceID.serialNumber = &serialNumber;

if (USBHostGenericGetDeviceAddress(&deviceID))
{
    deviceAddress = deviceID.deviceAddress;
}
Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Interface Routines > USBHostGenericGetDeviceAddress Function


USBHostGenericGetRxLength Macro

Contents | Index | Home
Previous | Up | Next
USBHostGenericGetRxLength Macro
C
#define USBHostGenericGetRxLength(a) ( (API_VALID(a)) ? gc_DevData.rxLength : 0 )
Description

This function retrieves the number of bytes copied to user's buffer by the most recent call to the USBHostGenericRead() function.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
BYTE deviceAddress | USB Address of the device
Returns

Returns the number of bytes most recently received from the Generic device with address deviceAddress.

Remarks

This function can only be called once per transfer. Subsequent calls will return zero until new data has been received.

Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Interface Routines > USBHostGenericGetRxLength Macro


USBHostGenericInit Function

Contents | Index | Home
Previous | Up | Next
USBHostGenericInit Function
C
BOOL USBHostGenericInit(
    BYTE address,
    DWORD flags,
    BYTE clientDriverID
);
Description

This routine is a call out from the USB Embedded Host layer to the USB generic client driver. It is called when a "generic" device has been connected to the host. Its purpose is to initialize and activate the USB Generic client driver.

Preconditions

The device has been configured.

Parameters
Parameters | Description
BYTE address | Device's address on the bus
DWORD flags | Initialization flags
BYTE clientDriverID | ID to send when issuing a Device Request via USBHostIssueDeviceRequest(), USBHostSetDeviceConfiguration(), or USBHostSetDeviceInterface().
Return Values
Return Values | Description
TRUE | Initialization was successful
FALSE | Initialization failed
Remarks

Multiple client drivers may be used in a single application. The USB Embedded Host layer will call the initialize routine required for the attached device.

Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Interface Routines > USBHostGenericInit Function


USBHostGenericRead Function

Contents | Index | Home
Previous | Up | Next
USBHostGenericRead Function
C
BYTE USBHostGenericRead(
    BYTE deviceAddress,
    void * buffer,
    DWORD length
);
Description

Use this routine to receive from the device and store it into memory.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
BYTE deviceAddress | USB Address of the device.
BYTE *buffer | Pointer to the data buffer
DWORD length | Number of bytes to be transferred
Return Values
Return Values | Description
USB_SUCCESS | The Read was started successfully
(USB error code) | The Read was not started. See USBHostRead() for a list of errors.
Remarks

None

Example
Copy Code
if (!USBHostGenericRxIsBusy( deviceAddress ))
{
    USBHostGenericRead( deviceAddress, &buffer, sizeof(buffer) );
}
Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Interface Routines > USBHostGenericRead Function


USBHostGenericRxIsBusy Macro

Contents | Index | Home
Previous | Up | Next
USBHostGenericRxIsBusy Macro
C
#define USBHostGenericRxIsBusy(a) ( (API_VALID(a)) ? ((gc_DevData.flags.rxBusy == 1) ? TRUE : FALSE) : TRUE )
Description

This interface is used to check if the client driver is currently busy receiving data from the device. This function is intended for use with transfer events. With polling, the function USBHostGenericRxIsComplete() should be used.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
BYTE deviceAddress | USB Address of the device
Return Values
Return Values | Description
TRUE | The device is receiving data or an invalid deviceAddress is given.
FALSE | The device is not receiving data
Remarks

None

Example
Copy Code
if (!USBHostGenericRxIsBusy( deviceAddress ))
{
    USBHostGenericRead( deviceAddress, &buffer, sizeof( buffer ) );
}
Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Interface Routines > USBHostGenericRxIsBusy Macro


USBHostGenericRxIsComplete Function

Contents | Index | Home
Previous | Up | Next
USBHostGenericRxIsComplete Function
C
BOOL USBHostGenericRxIsComplete(
    BYTE deviceAddress,
    BYTE * errorCode,
    DWORD * byteCount
);
Description

This routine indicates whether or not the last IN transfer is complete. If it is, then the returned errorCode and byteCount are valid, and reflect the error code and the number of bytes received.

This function is intended for use with polling. With transfer events, the function USBHostGenericRxIsBusy() should be used.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Address of the attached peripheral
BYTE *errorCode | Error code of the last transfer, if complete
DWORD *byteCount | Bytes transferred during the last transfer, if complete
Return Values
Return Values | Description
TRUE | The IN transfer is complete. errorCode and byteCount are valid.
FALSE | The IN transfer is not complete. errorCode and byteCount are invalid.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Interface Routines > USBHostGenericRxIsComplete Function


USBHostGenericTxIsBusy Macro

Contents | Index | Home
Previous | Up | Next
USBHostGenericTxIsBusy Macro
C
#define USBHostGenericTxIsBusy(a) ( (API_VALID(a)) ? ((gc_DevData.flags.txBusy == 1) ? TRUE : FALSE) : TRUE )
Description

This interface is used to check if the client driver is currently busy transmitting data to the device. This function is intended for use with transfer events. With polling, the function USBHostGenericTxIsComplete() should be used.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
BYTE deviceAddress | USB Address of the device
Return Values
Return Values | Description
TRUE | The device is transmitting data or an invalid deviceAddress is given.
FALSE | The device is not transmitting data
Remarks

None

Example
Copy Code
if (!USBHostGenericTxIsBusy( deviceAddress ) )
{
    USBHostGenericWrite( deviceAddress, &buffer, sizeof( buffer ) );
}
Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Interface Routines > USBHostGenericTxIsBusy Macro


USBHostGenericTxIsComplete Function

Contents | Index | Home
Previous | Up | Next
USBHostGenericTxIsComplete Function
C
BOOL USBHostGenericTxIsComplete(
    BYTE deviceAddress,
    BYTE * errorCode
);
Description

This routine indicates whether or not the last OUT transfer is complete. If it is, then the returned errorCode is valid, and reflect the error code of the transfer.

This function is intended for use with polling. With transfer events, the function USBHostGenericTxIsBusy() should be used.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Address of the attached peripheral
BYTE *errorCode | Error code of the last transfer, if complete
Return Values
Return Values | Description
TRUE | The OUT transfer is complete. errorCode is valid.
FALSE | The OUT transfer is not complete. errorCode is invalid.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Interface Routines > USBHostGenericTxIsComplete Function


USBHostGenericWrite Function

Contents | Index | Home
Previous | Up | Next
USBHostGenericWrite Function
C
BYTE USBHostGenericWrite(
    BYTE deviceAddress,
    void * buffer,
    DWORD length
);
Description

Use this routine to transmit data from memory to the device.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
BYTE deviceAddress | USB Address of the device.
BYTE *buffer | Pointer to the data buffer
DWORD length | Number of bytes to be transferred
Return Values
Return Values | Description
USB_SUCCESS | The Write was started successfully
(USB error code) | The Write was not started. See USBHostWrite() for a list of errors.
Remarks

None

Example
Copy Code
if (!USBHostGenericTxIsBusy( deviceAddress ))
{
    USBHostGenericWrite( deviceAddress, &buffer, sizeof(buffer) );
}
Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Interface Routines > USBHostGenericWrite Function


Data Types and Constants

Contents | Index | Home
Previous | Up | Next
Data Types and Constants
Macros
Name | Description
EVENT_GENERIC_ATTACH | This event indicates that a Generic device has been attached. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to a GENERIC_DEVICE_ID structure, and size is the size of the GENERIC_DEVICE_ID structure.
EVENT_GENERIC_DETACH | This event indicates that the specified device has been detached from the USB. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to a BYTE that contains the device address, and size is the size of a BYTE.
EVENT_GENERIC_OFFSET | This is an optional offset for the values of the generated events. If necessary, the application can use a non-zero offset for the generic events to resolve conflicts in event number.
EVENT_GENERIC_RX_DONE | This event indicates that a previous read request has completed. These events are enabled if USB Embedded Host transfer events are enabled (USB_ENABLE_TRANSFER_EVENT is defined). When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to the receive buffer, and size is the actual number of bytes read from the device.
EVENT_GENERIC_TX_DONE | This event indicates that a previous write request has completed. These events are enabled if USB Embedded Host transfer events are enabled (USB_ENABLE_TRANSFER_EVENT is defined). When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to the buffer that completed transmission, and size is the actual number of bytes that were written to the device.
USB_GENERIC_EP | This is the default Generic Client Driver endpoint number.
Types
Name | Description
GENERIC_DEVICE | Generic Device Information This structure contains information about an attached device, including status flags and device identification.
GENERIC_DEVICE_ID | Generic Device ID Information This structure contains identification information about an attached device.
Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Data Types and Constants


GENERIC_DEVICE Type

Contents | Index | Home
Previous | Up | Next
GENERIC_DEVICE Type
C
typedef struct _GENERIC_DEVICE GENERIC_DEVICE;
Description

Generic Device Information

This structure contains information about an attached device, including status flags and device identification.

Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Data Types and Constants > GENERIC_DEVICE Type


GENERIC_DEVICE_ID Type

Contents | Index | Home
Previous | Up | Next
GENERIC_DEVICE_ID Type
C
typedef struct _GENERIC_DEVICE_ID GENERIC_DEVICE_ID;
Description

Generic Device ID Information

This structure contains identification information about an attached device.

Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Data Types and Constants > GENERIC_DEVICE_ID Type


EVENT_GENERIC_ATTACH Macro

Contents | Index | Home
Previous | Up | Next
EVENT_GENERIC_ATTACH Macro
C
#define EVENT_GENERIC_ATTACH (EVENT_GENERIC_BASE+EVENT_GENERIC_OFFSET+0)
Description

This event indicates that a Generic device has been attached. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to a GENERIC_DEVICE_ID structure, and size is the size of the GENERIC_DEVICE_ID structure.

Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Data Types and Constants > EVENT_GENERIC_ATTACH Macro


EVENT_GENERIC_DETACH Macro

Contents | Index | Home
Previous | Up | Next
EVENT_GENERIC_DETACH Macro
C
#define EVENT_GENERIC_DETACH (EVENT_GENERIC_BASE+EVENT_GENERIC_OFFSET+1)
Description

This event indicates that the specified device has been detached from the USB. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to a BYTE that contains the device address, and size is the size of a BYTE.

Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Data Types and Constants > EVENT_GENERIC_DETACH Macro


EVENT_GENERIC_OFFSET Macro

Contents | Index | Home
Previous | Up | Next
EVENT_GENERIC_OFFSET Macro
C
#define EVENT_GENERIC_OFFSET 0
Description

This is an optional offset for the values of the generated events. If necessary, the application can use a non-zero offset for the generic events to resolve conflicts in event number.

Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Data Types and Constants > EVENT_GENERIC_OFFSET Macro


EVENT_GENERIC_RX_DONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_GENERIC_RX_DONE Macro
C
#define EVENT_GENERIC_RX_DONE (EVENT_GENERIC_BASE+EVENT_GENERIC_OFFSET+3)
Description

This event indicates that a previous read request has completed. These events are enabled if USB Embedded Host transfer events are enabled (USB_ENABLE_TRANSFER_EVENT is defined). When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to the receive buffer, and size is the actual number of bytes read from the device.

Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Data Types and Constants > EVENT_GENERIC_RX_DONE Macro


EVENT_GENERIC_TX_DONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_GENERIC_TX_DONE Macro
C
#define EVENT_GENERIC_TX_DONE (EVENT_GENERIC_BASE+EVENT_GENERIC_OFFSET+2)
Description

This event indicates that a previous write request has completed. These events are enabled if USB Embedded Host transfer events are enabled (USB_ENABLE_TRANSFER_EVENT is defined). When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to the buffer that completed transmission, and size is the actual number of bytes that were written to the device.

Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Data Types and Constants > EVENT_GENERIC_TX_DONE Macro


USB_GENERIC_EP Macro

Contents | Index | Home
Previous | Up | Next
USB_GENERIC_EP Macro
C
#define USB_GENERIC_EP 1
Description

This is the default Generic Client Driver endpoint number.

Application Programming Interface (API) > Embedded Host API > Generic Client Driver > Data Types and Constants > USB_GENERIC_EP Macro


HID Client Driver

Contents | Index | Home
Previous | Up | Next
HID Client Driver

This client driver provides USB Embedded Host support for HID devices. Common HID devices include mice, keyboards, and bar code scanners. Many other USB peripherals also use the HID class to transfer data, since it provides a simple, flexible interface and does not require a custom Windows driver when used with a PC.

See AN1144 - USB HID Class on an Embedded Host and AN1212 - Using USB Keyboard with an Embedded Host for more information.

Topics
Name | Description
Interface Routines |
Data Types and Constants |
Application Programming Interface (API) > Embedded Host API > HID Client Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
USBHostHID_ApiFindBit | This function is used to locate a specific button or indicator. Once the report descriptor is parsed by the HID layer without any error, data from the report descriptor is stored in pre defined dat structures. This function traverses these data structure and exract data required by application
USBHostHID_ApiFindValue | Find a specific Usage Value. Once the report descriptor is parsed by the HID layer without any error, data from the report descriptor is stored in pre defined dat structures. This function traverses these data structure and exract data required by application.
USBHostHID_ApiGetCurrentInterfaceNum | This function reurns the interface number of the cuurent report descriptor parsed. This function must be called to fill data interface detail data structure and passed as parameter when requesinf for report transfers.
USBHostHID_ApiImportData | This function can be used by application to extract data from the input reports. On receiving the input report from the device application can call the function with required inputs 'HID_DATA_DETAILS'.
USBHostHID_HasUsage | This function is used to locate the usage in a report descriptor. Function will look into the data structures created by the HID parser and return the appropriate location.
USBHostHIDDeviceDetect | This function determines if a HID device is attached and ready to use.
USBHostHIDDeviceStatus |
USBHostHIDEventHandler | This function is the event handler for this client driver.
USBHostHIDInitialize | This function is the initialization routine for this client driver.
USBHostHIDResetDevice | This function starts a HID reset.
USBHostHIDResetDeviceWithWait | This function resets a HID device, and waits until the reset is complete.
USBHostHIDTasks | This function performs the maintenance tasks required by HID class
USBHostHIDTerminateTransfer | This function terminates a transfer that is in progress.
USBHostHIDTransfer | This function starts a HID transfer.
USBHostHIDTransferIsComplete | This function indicates whether or not the last transfer is complete.
Macros
Name | Description
USBHostHID_ApiGetReport | This macro provides legacy support for an older API function.
USBHostHID_ApiSendReport | This macro provides legacy support for an older API function.
USBHostHID_ApiTransferIsComplete | This macro provides legacy support for an older API function.
USBHostHID_GetCurrentReportInfo | This function returns a pointer to the current report info structure.
USBHostHID_GetItemListPointers | This function returns a pointer to list of item pointers stored in a structure.
USBHostHIDRead | This function starts a Get report transfer reuest from the device, utilizing the function USBHostHIDTransfer();
USBHostHIDWrite | This function starts a Set report transfer request to the device, utilizing the function USBHostHIDTransfer();
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines


USBHostHID_ApiFindBit Function

Contents | Index | Home
Previous | Up | Next
USBHostHID_ApiFindBit Function
C
BOOL USBHostHID_ApiFindBit(
    WORD usagePage,
    WORD usage,
    HIDReportTypeEnum type,
    BYTE* Report_ID,
    BYTE* Report_Length,
    BYTE* Start_Bit
);
Description

This function is used to locate a specific button or indicator. Once the report descriptor is parsed by the HID layer without any error, data from the report descriptor is stored in pre defined dat structures. This function traverses these data structure and exract data required by application

Preconditions

None

Parameters
Parameters | Description
WORD usagePage | usage page supported by application
WORD usage | usage supported by application
HIDReportTypeEnum type | report type Input/Output for the particular usage
BYTE* Report_ID | returns the report ID of the required usage
BYTE* Report_Length | returns the report length of the required usage
BYTE* Start_Bit | returns the start bit of the usage in a particular report
Return Values
Return Values | Description
TRUE | If the required usage is located in the report descriptor
FALSE | If the application required usage is not supported by the device(i.e report descriptor).
Remarks

Application event handler with event 'EVENT_HID_RPT_DESC_PARSED' is called. Application is suppose to fill in data details in structure 'HID_DATA_DETAILS'. This function can be used to the get the details of the required usages.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHID_ApiFindBit Function


USBHostHID_ApiFindValue Function

Contents | Index | Home
Previous | Up | Next
USBHostHID_ApiFindValue Function
C
BOOL USBHostHID_ApiFindValue(
    WORD usagePage,
    WORD usage,
    HIDReportTypeEnum type,
    BYTE* Report_ID,
    BYTE* Report_Length,
    BYTE* Start_Bit,
    BYTE* Bit_Length
);
Description

Find a specific Usage Value. Once the report descriptor is parsed by the HID layer without any error, data from the report descriptor is stored in pre defined dat structures. This function traverses these data structure and exract data required by application.

Preconditions

None

Parameters
Parameters | Description
WORD usagePage | usage page supported by application
WORD usage | usage supported by application
HIDReportTypeEnum type | report type Input/Output for the particular usage
BYTE* Report_ID | returns the report ID of the required usage
BYTE* Report_Length | returns the report length of the required usage
BYTE* Start_Bit | returns the start bit of the usage in a particular report
BYTE* Bit_Length | returns size of requested usage type data in bits
Return Values
Return Values | Description
TRUE | If the required usage is located in the report descriptor
FALSE | If the application required usage is not supported by the device(i.e report descriptor).
Remarks

Application event handler with event 'EVENT_HID_RPT_DESC_PARSED' is called. Application is suppose to fill in data details structure 'HID_DATA_DETAILS' This function can be used to the get the details of the required usages.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHID_ApiFindValue Function


USBHostHID_ApiGetCurrentInterfaceNum Function

Contents | Index | Home
Previous | Up | Next
USBHostHID_ApiGetCurrentInterfaceNum Function
C
BYTE USBHostHID_ApiGetCurrentInterfaceNum();
Description

This function reurns the interface number of the cuurent report descriptor parsed. This function must be called to fill data interface detail data structure and passed as parameter when requesinf for report transfers.

Preconditions

None

Return Values
Return Values | Description
TRUE | Transfer is complete, errorCode is valid
FALSE | Transfer is not complete, errorCode is not valid
Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHID_ApiGetCurrentInterfaceNum Function


USBHostHID_ApiGetReport Macro

Contents | Index | Home
Previous | Up | Next
USBHostHID_ApiGetReport Macro
C
#define USBHostHID_ApiGetReport( r, i, s, d ) USBHostHIDRead( 1, r, i, s, d )
Description

This macro provides legacy support for an older API function.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHID_ApiGetReport Macro


USBHostHID_ApiImportData Function

Contents | Index | Home
Previous | Up | Next
USBHostHID_ApiImportData Function
C
BOOL USBHostHID_ApiImportData(
    BYTE * report,
    WORD reportLength,
    HID_USER_DATA_SIZE * buffer,
    HID_DATA_DETAILS * pDataDetails
);
Description

This function can be used by application to extract data from the input reports. On receiving the input report from the device application can call the function with required inputs 'HID_DATA_DETAILS'.

Preconditions

None

Parameters
Parameters | Description
BYTE *report | Input report received from device
WORD reportLength | Length of input report report
HID_USER_DATA_SIZE *buffer | Buffer into which data needs to be populated
HID_DATA_DETAILS *pDataDetails | data details extracted from report descriptor
Return Values
Return Values | Description
TRUE | If the required data is retrieved from the report
FALSE | If required data is not found.
Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHID_ApiImportData Function


USBHostHID_ApiSendReport Macro

Contents | Index | Home
Previous | Up | Next
USBHostHID_ApiSendReport Macro
C
#define USBHostHID_ApiSendReport( r, i, s, d ) USBHostHIDWrite( 1, r, i, s, d )
Description

This macro provides legacy support for an older API function.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHID_ApiSendReport Macro


USBHostHID_ApiTransferIsComplete Macro

Contents | Index | Home
Previous | Up | Next
USBHostHID_ApiTransferIsComplete Macro
C
#define USBHostHID_ApiTransferIsComplete( e, c ) USBHostHIDTransferIsComplete( 1, e, c )
Description

This macro provides legacy support for an older API function.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHID_ApiTransferIsComplete Macro


USBHostHID_GetCurrentReportInfo Macro

Contents | Index | Home
Previous | Up | Next
USBHostHID_GetCurrentReportInfo Macro
C
#define USBHostHID_GetCurrentReportInfo (&deviceRptInfo)
Description

This function returns a pointer to the current report info structure.

Preconditions

None

Returns

BYTE * - Pointer to the report Info structure.

Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHID_GetCurrentReportInfo Macro


USBHostHID_GetItemListPointers Macro

Contents | Index | Home
Previous | Up | Next
USBHostHID_GetItemListPointers Macro
C
#define USBHostHID_GetItemListPointers (&itemListPtrs)
Description

This function returns a pointer to list of item pointers stored in a structure.

Preconditions

None

Returns

BYTE * - Pointer to list of item pointers structure.

Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHID_GetItemListPointers Macro


USBHostHID_HasUsage Function

Contents | Index | Home
Previous | Up | Next
USBHostHID_HasUsage Function
C
BOOL USBHostHID_HasUsage(
    HID_REPORTITEM * reportItem,
    WORD usagePage,
    WORD usage,
    WORD * pindex,
    BYTE* count
);
Description

This function is used to locate the usage in a report descriptor. Function will look into the data structures created by the HID parser and return the appropriate location.

Preconditions

None

Parameters
Parameters | Description
HID_REPORTITEM *reportItem | Report item index to be searched
WORD usagePage | Application needs to pass the usagePage as the search criteria for the usage
WORD usage | Application needs to pass the usageto be searched
WORD *pindex | returns index to the usage item requested.
BYTE* count | returns the remaining number of reports
Return Values
Return Values | Description
BOOL | FALSE - If requested usage is not found
TRUE | if requested usage is found
Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHID_HasUsage Function


USBHostHIDDeviceDetect Function

Contents | Index | Home
Previous | Up | Next
USBHostHIDDeviceDetect Function
C
BOOL USBHostHIDDeviceDetect(
    BYTE deviceAddress
);
Description

This function determines if a HID device is attached and ready to use.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Address of the attached device.
Return Values
Return Values | Description
TRUE | HID present and ready
FALSE | HID not present or not ready
Remarks

This function replaces the USBHostHID_ApiDeviceDetect() function.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHIDDeviceDetect Function


USBHostHIDDeviceStatus Function

Contents | Index | Home
Previous | Up | Next
USBHostHIDDeviceStatus Function
C
BYTE USBHostHIDDeviceStatus(
    BYTE deviceAddress
);
Description

This function determines the status of a HID device.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | address of device to query
Return Values
Return Values | Description
USB_HID_DEVICE_NOT_FOUND | Illegal device address, or the device is not an HID
USB_HID_INITIALIZING | HID is attached and in the process of initializing
USB_PROCESSING_REPORT_DESCRIPTOR | HID device is detected and report descriptor is being parsed
USB_HID_NORMAL_RUNNING | HID Device is running normal, ready to send and receive reports
USB_HID_DEVICE_HOLDING | Driver has encountered error and could not recover
USB_HID_DEVICE_DETACHED | HID detached.
Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHIDDeviceStatus Function


USBHostHIDEventHandler Function

Contents | Index | Home
Previous | Up | Next
USBHostHIDEventHandler Function
C
BOOL USBHostHIDEventHandler(
    BYTE address,
    USB_EVENT event,
    void * data,
    DWORD size
);
Description

This function is the event handler for this client driver. It is called by the host layer when various events occur.

Preconditions

The device has been initialized.

Parameters
Parameters | Description
BYTE address | Address of the device
USB_EVENT event | Event that has occurred
void *data | Pointer to data pertinent to the event
DWORD size | Size of the data
Return Values
Return Values | Description
TRUE | Event was handled
FALSE | Event was not handled
Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHIDEventHandler Function


USBHostHIDInitialize Function

Contents | Index | Home
Previous | Up | Next
USBHostHIDInitialize Function
C
BOOL USBHostHIDInitialize(
    BYTE address,
    DWORD flags,
    BYTE clientDriverID
);
Description

This function is the initialization routine for this client driver. It is called by the host layer when the USB device is being enumerated.For a HID device we need to look into HID descriptor, interface descriptor and endpoint descriptor.

Preconditions

None

Parameters
Parameters | Description
BYTE address | Address of the new device
DWORD flags | Initialization flags
BYTE clientDriverID | Client driver identification for device requests
Return Values
Return Values | Description
TRUE | We can support the device.
FALSE | We cannot support the device.
Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHIDInitialize Function


USBHostHIDRead Macro

Contents | Index | Home
Previous | Up | Next
USBHostHIDRead Macro
C
#define USBHostHIDRead( deviceAddress,reportid,interface,size,data) \
         USBHostHIDTransfer( deviceAddress,1,interface,reportid,size,data)
Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE reportid | Report ID of the requested report
BYTE interface | Interface number
BYTE size | Byte size of the data buffer
BYTE *data | Pointer to the data buffer
Return Values
Return Values | Description
USB_SUCCESS | Request started successfully
USB_HID_DEVICE_NOT_FOUND | No device with specified address
USB_HID_DEVICE_BUSY | Device not in proper state for performing a transfer
Others | Return values from USBHostRead()
Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHIDRead Macro


USBHostHIDResetDevice Function

Contents | Index | Home
Previous | Up | Next
USBHostHIDResetDevice Function
C
BYTE USBHostHIDResetDevice(
    BYTE deviceAddress
);
Description

This function starts a HID reset. A reset can be issued only if the device is attached and not being initialized.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
Return Values
Return Values | Description
USB_SUCCESS | Reset started
USB_MSD_DEVICE_NOT_FOUND | No device with specified address
USB_MSD_ILLEGAL_REQUEST | Device is in an illegal state for reset
Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHIDResetDevice Function


USBHostHIDResetDeviceWithWait Function

Contents | Index | Home
Previous | Up | Next
USBHostHIDResetDeviceWithWait Function
C
BYTE USBHostHIDResetDeviceWithWait(
    BYTE deviceAddress
);
Description

This function resets a HID device, and waits until the reset is complete.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Address of the device to reset.
Return Values
Return Values | Description
USB_SUCCESS | Reset successful
USB_HID_RESET_ERROR | Error while resetting device
Others | See return values for USBHostHIDResetDevice() and error codes that can be returned in the errorCode parameter of USBHostHIDTransferIsComplete();
Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHIDResetDeviceWithWait Function


USBHostHIDTasks Function

Contents | Index | Home
Previous | Up | Next
USBHostHIDTasks Function
C
void USBHostHIDTasks();
Description

This function performs the maintenance tasks required by the HID class. If transfer events from the host layer are not being used, then it should be called on a regular basis by the application. If transfer events from the host layer are being used, this function is compiled out, and does not need to be called.

Preconditions

USBHostHIDInitialize() has been called.

Returns

None

Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHIDTasks Function


USBHostHIDTerminateTransfer Function

Contents | Index | Home
Previous | Up | Next
USBHostHIDTerminateTransfer Function
C
BYTE USBHostHIDTerminateTransfer(
    BYTE deviceAddress,
    BYTE direction,
    BYTE interfaceNum
);
Description

This function terminates a transfer that is in progress.

Preconditions

None

Parameters
Parameters
Description
BYTE deviceAddress
Device address
BYTE direction
Transfer direction. Valid values are:
  • 1 = In (Read)
  • 0 = Out (Write)
BYTE interfaceNum
Interface number
Return Values
Return Values | Description
USB_SUCCESS | Transfer terminated
USB_HID_DEVICE_NOT_FOUND | No device with specified address
Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHIDTerminateTransfer Function


USBHostHIDTransfer Function

Contents | Index | Home
Previous | Up | Next
USBHostHIDTransfer Function
C
BYTE USBHostHIDTransfer(
    BYTE deviceAddress,
    BYTE direction,
    BYTE interfaceNum,
    WORD reportid,
    WORD size,
    BYTE * data
);
Description

This function starts a HID transfer. A read/write wrapper is provided in application interface file to access this function.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE direction | 1=read, 0=write
BYTE interfaceNum | Interface number
BYTE reportid | Report ID of the requested report
BYTE size | Byte size of the data buffer
BYTE *data | Pointer to the data buffer
Return Values
Return Values | Description
USB_SUCCESS | Request started successfully
USB_HID_DEVICE_NOT_FOUND | No device with specified address
USB_HID_DEVICE_BUSY | Device not in proper state for performing a transfer
Others | Return values from USBHostIssueDeviceRequest(), USBHostRead(), and USBHostWrite()
Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHIDTransfer Function


USBHostHIDTransferIsComplete Function

Contents | Index | Home
Previous | Up | Next
USBHostHIDTransferIsComplete Function
C
BOOL USBHostHIDTransferIsComplete(
    BYTE deviceAddress,
    BYTE * errorCode,
    BYTE * byteCount
);
Description

This function indicates whether or not the last transfer is complete. If the functions returns TRUE, the returned byte count and error code are valid. Since only one transfer can be performed at once and only one endpoint can be used, we only need to know the device address.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE *errorCode | Error code from last transfer
DWORD *byteCount | Number of bytes transferred
Return Values
Return Values | Description
TRUE | Transfer is complete, errorCode is valid
FALSE | Transfer is not complete, errorCode is not valid
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHIDTransferIsComplete Function


USBHostHIDWrite Macro

Contents | Index | Home
Previous | Up | Next
USBHostHIDWrite Macro
C
#define USBHostHIDWrite( address,reportid,interface,size,data) \
               USBHostHIDTransfer( address,0,interface,reportid,size,data)
Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE reportid | Report ID of the requested report
BYTE interface | Interface number
BYTE size | Byte size of the data buffer
BYTE *data | Pointer to the data buffer
Return Values
Return Values | Description
USB_SUCCESS | Request started successfully
USB_HID_DEVICE_NOT_FOUND | No device with specified address
USB_HID_DEVICE_BUSY | Device not in proper state for performing a transfer
Others | Return values from USBHostIssueDeviceRequest(), and USBHostWrite()
Remarks

None

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Interface Routines > USBHostHIDWrite Macro


Data Types and Constants

Contents | Index | Home
Previous | Up | Next
Data Types and Constants
Enumerations
Name | Description
HIDReportTypeEnum | This is type HIDReportTypeEnum.
USB_HID_RPT_DESC_ERROR | HID parser error codes This enumerates the error encountered during the parsing of report descriptor. In case of any error parsing is sttopped and the error is flagged. Device is not attched successfully.
Macros
Name | Description
DEVICE_CLASS_HID | HID Interface Class Code
DSC_HID | HID Descriptor Code
DSC_PHY | Pysical Descriptor Code
DSC_RPT | Report Descriptor Code
EVENT_HID_ATTACH | A HID device has attached. The returned data pointer points to a USB_HID_DEVICE_ID structure.
EVENT_HID_BAD_REPORT_DESCRIPTOR | There was a problem parsing the report descriptor of the attached device. Communication with the device is not allowed, and the device should be detached.
EVENT_HID_DETACH | A HID device has detached. The returned data pointer points to a byte with the previous address of the detached device.
EVENT_HID_NONE | No event occured (NULL event)
EVENT_HID_OFFSET | If the application has not defined an offset for HID events, set it to 0.
EVENT_HID_READ_DONE | #define EVENT_HID_TRANSFER EVENT_HID_BASE + EVENT_HID_OFFSET + 3 // Unused - value retained for legacy. A HID Read transfer has completed. The returned data pointer points to a HID_TRANSFER_DATA structure, with information about the transfer.
EVENT_HID_RESET | HID reset complete. The returned data pointer is NULL.
EVENT_HID_RESET_ERROR | An error occurred while trying to do a HID reset. The returned data pointer is NULL.
EVENT_HID_RPT_DESC_PARSED | A Report Descriptor has been parsed. The returned data pointer is NULL. The application must collect details, or simply return TRUE if the application is already aware of the data format.
EVENT_HID_WRITE_DONE | A HID Write transfer has completed. The returned data pointer points to a HID_TRANSFER_DATA structure, with information about the transfer.
USB_HID_CLASS_ERROR |
USB_HID_COMMAND_FAILED | Command failed at the device.
USB_HID_COMMAND_PASSED | Command was successful.
USB_HID_DEVICE_BUSY | A transfer is currently in progress.
USB_HID_DEVICE_DETACHED | Device is detached.
USB_HID_DEVICE_HOLDING | Device is holding due to error
USB_HID_DEVICE_NOT_FOUND | Device with the specified address is not available.
USB_HID_ILLEGAL_REQUEST | Cannot perform requested operation.
USB_HID_INITIALIZING | Device is initializing.
USB_HID_INTERFACE_ERROR | The interface layer cannot support the device.
USB_HID_NO_REPORT_DESCRIPTOR | No report descriptor found
USB_HID_NORMAL_RUNNING | Device is running and available for data transfers.
USB_HID_PHASE_ERROR | Command had a phase error at the device.
USB_HID_REPORT_DESCRIPTOR_BAD | Report Descriptor for not proper
USB_HID_RESET_ERROR | An error occurred while resetting the device.
USB_HID_RESETTING_DEVICE | Device is being reset.
USB_PROCESSING_REPORT_DESCRIPTOR | Parser is processing report descriptor.
Structures
Name | Description
_HID_COLLECTION | HID Collection Details This structure contains information about each collection encountered in the report descriptor.
_HID_DATA_DETAILS | HID Data Details This structure defines the objects used by the application to access required report. Application must use parser interface functions to fill these details. e.g. USBHostHID_ApiFindValue
_HID_GLOBALS | HID Global Item Information This structure contains information about each Global Item of the report descriptor.
_HID_ITEM_INFO | HID Item Information This structure contains information about each Item of the report descriptor.
_HID_REPORT | HID Report details This structure contains information about each report exchanged with the device.
_HID_REPORTITEM | HID Report Details This structure contains information about each Report encountered in the report descriptor.
_HID_STRINGITEM | HID String Item Details This structure contains information about each Report encountered in the report descriptor.
_HID_TRANSFER_DATA | HID Transfer Information This structure is used when the event handler is used to notify the upper layer of transfer completion (EVENT_HID_READ_DONE or EVENT_HID_WRITE_DONE).
_HID_USAGEITEM | HID Report Details This structure contains information about each Usage Item encountered in the report descriptor.
_USB_HID_DEVICE_ID | HID Device ID Information This structure contains identification information about an attached device.
_USB_HID_DEVICE_RPT_INFO | Report Descriptor Information This structure contains top level information of the report descriptor. This information is important and is used to understand the information during th ecourse of parsing. This structure also stores temporary data needed during parsing the report descriptor. All of this information may not be of much inportance to the application.
_USB_HID_ITEM_LIST | List of Items This structure contains array of pointers to all the Items in the report descriptor. HID parser will populate the lists while parsing the report descriptor. This data is used by interface functions provided in file usb_host_hid_interface.c to retrive data from the report received from the device. Application can also access these details to retreive the intended information incase provided interface function fail to do so.
HID_COLLECTION | HID Collection Details This structure contains information about each collection encountered in the report descriptor.
HID_DATA_DETAILS | HID Data Details This structure defines the objects used by the application to access required report. Application must use parser interface functions to fill these details. e.g. USBHostHID_ApiFindValue
HID_DESIGITEM | HID String Item Details This structure contains information about each Report encountered in the report descriptor.
HID_GLOBALS | HID Global Item Information This structure contains information about each Global Item of the report descriptor.
HID_ITEM_INFO | HID Item Information This structure contains information about each Item of the report descriptor.
HID_REPORT | HID Report details This structure contains information about each report exchanged with the device.
HID_REPORTITEM | HID Report Details This structure contains information about each Report encountered in the report descriptor.
HID_STRINGITEM | HID String Item Details This structure contains information about each Report encountered in the report descriptor.
HID_TRANSFER_DATA | HID Transfer Information This structure is used when the event handler is used to notify the upper layer of transfer completion (EVENT_HID_READ_DONE or EVENT_HID_WRITE_DONE).
HID_USAGEITEM | HID Report Details This structure contains information about each Usage Item encountered in the report descriptor.
USB_HID_DEVICE_ID | HID Device ID Information This structure contains identification information about an attached device.
USB_HID_DEVICE_RPT_INFO | Report Descriptor Information This structure contains top level information of the report descriptor. This information is important and is used to understand the information during th ecourse of parsing. This structure also stores temporary data needed during parsing the report descriptor. All of this information may not be of much inportance to the application.
USB_HID_ITEM_LIST | List of Items This structure contains array of pointers to all the Items in the report descriptor. HID parser will populate the lists while parsing the report descriptor. This data is used by interface functions provided in file usb_host_hid_interface.c to retrive data from the report received from the device. Application can also access these details to retreive the intended information incase provided interface function fail to do so.
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants


DEVICE_CLASS_HID Macro

Contents | Index | Home
Previous | Up | Next
DEVICE_CLASS_HID Macro
C
#define DEVICE_CLASS_HID 0x03 /* HID Interface Class Code */
Description

HID Interface Class Code

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > DEVICE_CLASS_HID Macro


DSC_HID Macro

Contents | Index | Home
Previous | Up | Next
DSC_HID Macro
C
#define DSC_HID 0x21 /* HID Descriptor Code */
Description

HID Descriptor Code

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > DSC_HID Macro


DSC_PHY Macro

Contents | Index | Home
Previous | Up | Next
DSC_PHY Macro
C
#define DSC_PHY 0x23 /* Pysical Descriptor Code */
Description

Pysical Descriptor Code

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > DSC_PHY Macro


DSC_RPT Macro

Contents | Index | Home
Previous | Up | Next
DSC_RPT Macro
C
#define DSC_RPT 0x2200 /* Report Descriptor Code */
Description

Report Descriptor Code

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > DSC_RPT Macro


EVENT_HID_ATTACH Macro

Contents | Index | Home
Previous | Up | Next
EVENT_HID_ATTACH Macro
C
#define EVENT_HID_ATTACH EVENT_HID_BASE + EVENT_HID_OFFSET + 7
Description

A HID device has attached. The returned data pointer points to a USB_HID_DEVICE_ID structure.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > EVENT_HID_ATTACH Macro


EVENT_HID_BAD_REPORT_DESCRIPTOR Macro

Contents | Index | Home
Previous | Up | Next
EVENT_HID_BAD_REPORT_DESCRIPTOR Macro
C
#define EVENT_HID_BAD_REPORT_DESCRIPTOR EVENT_HID_BASE + EVENT_HID_OFFSET + 9
Description

There was a problem parsing the report descriptor of the attached device. Communication with the device is not allowed, and the device should be detached.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > EVENT_HID_BAD_REPORT_DESCRIPTOR Macro


EVENT_HID_DETACH Macro

Contents | Index | Home
Previous | Up | Next
EVENT_HID_DETACH Macro
C
#define EVENT_HID_DETACH EVENT_HID_BASE + EVENT_HID_OFFSET + 8
Description

A HID device has detached. The returned data pointer points to a byte with the previous address of the detached device.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > EVENT_HID_DETACH Macro


EVENT_HID_NONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_HID_NONE Macro
C
#define EVENT_HID_NONE EVENT_HID_BASE + EVENT_HID_OFFSET + 0
Description

No event occured (NULL event)

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > EVENT_HID_NONE Macro


EVENT_HID_OFFSET Macro

Contents | Index | Home
Previous | Up | Next
EVENT_HID_OFFSET Macro
C
#define EVENT_HID_OFFSET 0
Description

If the application has not defined an offset for HID events, set it to 0.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > EVENT_HID_OFFSET Macro


EVENT_HID_READ_DONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_HID_READ_DONE Macro
C
#define EVENT_HID_READ_DONE EVENT_HID_BASE + EVENT_HID_OFFSET + 4
Description

#define EVENT_HID_TRANSFER EVENT_HID_BASE + EVENT_HID_OFFSET + 3 // Unused - value retained for legacy. A HID Read transfer has completed. The returned data pointer points to a HID_TRANSFER_DATA structure, with information about the transfer.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > EVENT_HID_READ_DONE Macro


EVENT_HID_RESET Macro

Contents | Index | Home
Previous | Up | Next
EVENT_HID_RESET Macro
C
#define EVENT_HID_RESET EVENT_HID_BASE + EVENT_HID_OFFSET + 6
Description

HID reset complete. The returned data pointer is NULL.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > EVENT_HID_RESET Macro


EVENT_HID_RESET_ERROR Macro

Contents | Index | Home
Previous | Up | Next
EVENT_HID_RESET_ERROR Macro
C
#define EVENT_HID_RESET_ERROR EVENT_HID_BASE + EVENT_HID_OFFSET + 10
Description

An error occurred while trying to do a HID reset. The returned data pointer is NULL.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > EVENT_HID_RESET_ERROR Macro


EVENT_HID_RPT_DESC_PARSED Macro

Contents | Index | Home
Previous | Up | Next
EVENT_HID_RPT_DESC_PARSED Macro
C
#define EVENT_HID_RPT_DESC_PARSED EVENT_HID_BASE + EVENT_HID_OFFSET + 1
Description

A Report Descriptor has been parsed. The returned data pointer is NULL. The application must collect details, or simply return TRUE if the application is already aware of the data format.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > EVENT_HID_RPT_DESC_PARSED Macro


EVENT_HID_WRITE_DONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_HID_WRITE_DONE Macro
C
#define EVENT_HID_WRITE_DONE EVENT_HID_BASE + EVENT_HID_OFFSET + 5
Description

A HID Write transfer has completed. The returned data pointer points to a HID_TRANSFER_DATA structure, with information about the transfer.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > EVENT_HID_WRITE_DONE Macro


HID_COLLECTION Structure

Contents | Index | Home
Previous | Up | Next
HID_COLLECTION Structure
C
typedef struct _HID_COLLECTION {
  DWORD data;
  WORD usagePage;
  BYTE firstUsageItem;
  BYTE usageItems;
  BYTE firstReportItem;
  BYTE reportItems;
  BYTE parent;
  BYTE firstChild;
  BYTE nextSibling;
} HID_COLLECTION;
Description

HID Collection Details

This structure contains information about each collection encountered in the report descriptor.

Members
Members | Description
DWORD data; | Collection raw data
WORD usagePage; | Usage page associated with current level of collection
BYTE firstUsageItem; | Index of First Usage Item in the current collection
BYTE usageItems; | Number of Usage Items in the current collection
BYTE firstReportItem; | Index of First report Item in the current collection
BYTE reportItems; | Number of report Items in the current collection
BYTE parent; | Index to Parent collection
BYTE firstChild; | Index to next child collection in the report descriptor
BYTE nextSibling; | Index to next child collection in the report descriptor
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > HID_COLLECTION Structure


HID_DATA_DETAILS Structure

Contents | Index | Home
Previous | Up | Next
HID_DATA_DETAILS Structure
C
typedef struct _HID_DATA_DETAILS {
  WORD reportLength;
  WORD reportID;
  BYTE bitOffset;
  BYTE bitLength;
  BYTE count;
  BYTE signExtend;
  BYTE interfaceNum;
} HID_DATA_DETAILS;
Description

HID Data Details

This structure defines the objects used by the application to access required report. Application must use parser interface functions to fill these details. e.g. USBHostHID_ApiFindValue

Members
Members | Description
WORD reportLength; | reportLength - the expected length of the parent report.
WORD reportID; | reportID - report ID - the first byte of the parent report.
BYTE bitOffset; | BitOffset - bit offset within the report.
BYTE bitLength; | bitlength - length of the data in bits.
BYTE count; | count - what's left of the message after this data.
BYTE signExtend; | extend - sign extend the data.
BYTE interfaceNum; | interfaceNum - informs HID layer about interface number.
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > HID_DATA_DETAILS Structure


HID_DESIGITEM Structure

Contents | Index | Home
Previous | Up | Next
HID_DESIGITEM Structure
C
typedef struct _HID_STRINGITEM {
  BOOL isRange;
  WORD index;
  WORD minimum;
  WORD maximum;
} HID_STRINGITEM, HID_DESIGITEM;
Description

HID String Item Details

This structure contains information about each Report encountered in the report descriptor.

Members
Members | Description
BOOL isRange; | If range of String Item is valid
WORD index; | String index for a String descriptor; allows a string to be associated with a particular item or control
WORD minimum; | Specifies the first string index when assigning a group of sequential strings to controls in an array or bitmap
WORD maximum; | Specifies the last string index when assigning a group of sequential strings to controls in an array or bitmap
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > HID_DESIGITEM Structure


HID_GLOBALS Structure

Contents | Index | Home
Previous | Up | Next
HID_GLOBALS Structure
C
typedef struct _HID_GLOBALS {
  WORD usagePage;
  LONG logicalMinimum;
  LONG logicalMaximum;
  LONG physicalMinimum;
  LONG physicalMaximum;
  LONG unitExponent;
  LONG unit;
  WORD reportIndex;
  BYTE reportID;
  BYTE reportsize;
  BYTE reportCount;
} HID_GLOBALS;
Description

HID Global Item Information

This structure contains information about each Global Item of the report descriptor.

Members
Members | Description
WORD usagePage; | Specifies current Usage Page
LONG logicalMinimum; | This is the minimum value that a variable or array item will report
LONG logicalMaximum; | This is the maximum value that a variable or array item will report
LONG physicalMinimum; | Minimum value for the physical extent of a variable item
LONG physicalMaximum; | Maximum value for the physical extent of a variable item
LONG unitExponent; | Value of the unit exponent in base 10
LONG unit; | Unit values
WORD reportIndex; | Conter to keep track of report being processed in the parser
BYTE reportID; | Report ID. All the reports are preceded by a single byte report ID
BYTE reportsize; | Size of current report in bytes
BYTE reportCount; | This field determines number of fields in the report
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > HID_GLOBALS Structure


HID_ITEM_INFO Structure

Contents | Index | Home
Previous | Up | Next
HID_ITEM_INFO Structure
C
typedef struct _HID_ITEM_INFO {
  union {
    struct {
      BYTE ItemSize : 2;
      BYTE ItemType : 2;
      BYTE ItemTag : 4;
    }
    BYTE val;
  } ItemDetails;
  union {
    LONG sItemData;
    DWORD uItemData;
    BYTE bItemData[4];
  } Data;
} HID_ITEM_INFO;
Description

HID Item Information

This structure contains information about each Item of the report descriptor.

Members
Members | Description
BYTE ItemSize : 2; | Numeric expression specifying size of data
BYTE ItemType : 2; | This field identifies type of item(Main, Global or Local)
BYTE ItemTag : 4; | This field specifies the function of the item
BYTE val; | to access the data in byte format
LONG sItemData; | Item Data is stored in signed format
DWORD uItemData; | Item Data is stored in unsigned format
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > HID_ITEM_INFO Structure


HID_REPORT Structure

Contents | Index | Home
Previous | Up | Next
HID_REPORT Structure
C
typedef struct _HID_REPORT {
  WORD reportID;
  WORD inputBits;
  WORD outputBits;
  WORD featureBits;
} HID_REPORT;
Description

HID Report details

This structure contains information about each report exchanged with the device.

Members
Members | Description
WORD reportID; | Report ID of the associated report
WORD inputBits; | If input report then length of report in bits
WORD outputBits; | If output report then length of report in bits
WORD featureBits; | If feature report then length of report in bits
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > HID_REPORT Structure


HID_REPORTITEM Structure

Contents | Index | Home
Previous | Up | Next
HID_REPORTITEM Structure
C
typedef struct _HID_REPORTITEM {
  HIDReportTypeEnum reportType;
  HID_GLOBALS globals;
  BYTE startBit;
  BYTE parent;
  DWORD dataModes;
  BYTE firstUsageItem;
  BYTE usageItems;
  BYTE firstStringItem;
  BYTE stringItems;
  BYTE firstDesignatorItem;
  BYTE designatorItems;
} HID_REPORTITEM;
Description

HID Report Details

This structure contains information about each Report encountered in the report descriptor.

Members
Members | Description
HIDReportTypeEnum reportType; | Type of Report Input/Output/Feature
HID_GLOBALS globals; | Stores all the global items associated with the current report
BYTE startBit; | Starting Bit Position of the report
BYTE parent; | Index of parent collection
DWORD dataModes; | this tells the data mode is array or not
BYTE firstUsageItem; | Index to first usage item related to the report
BYTE usageItems; | Number of usage items in the current report
BYTE firstStringItem; | Index to first srting item in the list
BYTE stringItems; | Number of string items in the current report
BYTE firstDesignatorItem; | Index to first designator item
BYTE designatorItems; | Number of designator items in the current report
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > HID_REPORTITEM Structure


HID_STRINGITEM Structure

Contents | Index | Home
Previous | Up | Next
HID_STRINGITEM Structure
C
typedef struct _HID_STRINGITEM {
  BOOL isRange;
  WORD index;
  WORD minimum;
  WORD maximum;
} HID_STRINGITEM, HID_DESIGITEM;
Description

HID String Item Details

This structure contains information about each Report encountered in the report descriptor.

Members
Members | Description
BOOL isRange; | If range of String Item is valid
WORD index; | String index for a String descriptor; allows a string to be associated with a particular item or control
WORD minimum; | Specifies the first string index when assigning a group of sequential strings to controls in an array or bitmap
WORD maximum; | Specifies the last string index when assigning a group of sequential strings to controls in an array or bitmap
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > HID_STRINGITEM Structure


HID_TRANSFER_DATA Structure

Contents | Index | Home
Previous | Up | Next
HID_TRANSFER_DATA Structure
C
typedef struct _HID_TRANSFER_DATA {
  DWORD dataCount;
  BYTE bErrorCode;
} HID_TRANSFER_DATA;
Description

HID Transfer Information

This structure is used when the event handler is used to notify the upper layer of transfer completion (EVENT_HID_READ_DONE or EVENT_HID_WRITE_DONE).

Members
Members | Description
DWORD dataCount; | Count of bytes transferred.
BYTE bErrorCode; | Transfer error code.
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > HID_TRANSFER_DATA Structure


HID_USAGEITEM Structure

Contents | Index | Home
Previous | Up | Next
HID_USAGEITEM Structure
C
typedef struct _HID_USAGEITEM {
  BOOL isRange;
  WORD usagePage;
  WORD usage;
  WORD usageMinimum;
  WORD usageMaximum;
} HID_USAGEITEM;
Description

HID Report Details

This structure contains information about each Usage Item encountered in the report descriptor.

Members
Members | Description
BOOL isRange; | True if Usage item has a valid MAX and MIN range
WORD usagePage; | Usage page ID asscociated with the Item
WORD usage; | Usage ID asscociated with the Item
WORD usageMinimum; | Defines the starting usage associated with an array or bitmap
WORD usageMaximum; | Defines the ending usage associated with an array or bitmap
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > HID_USAGEITEM Structure


HIDReportTypeEnum Enumeration

Contents | Index | Home
Previous | Up | Next
HIDReportTypeEnum Enumeration
C
typedef enum {
  hidReportInput,
  hidReportOutput,
  hidReportFeature,
  hidReportUnknown
} HIDReportTypeEnum;
Description

This is type HIDReportTypeEnum.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > HIDReportTypeEnum Enumeration


USB_HID_CLASS_ERROR Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_CLASS_ERROR Macro
C
#define USB_HID_CLASS_ERROR USB_ERROR_CLASS_DEFINED
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_CLASS_ERROR Macro


USB_HID_COMMAND_FAILED Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_COMMAND_FAILED Macro
C
#define USB_HID_COMMAND_FAILED (USB_HID_CLASS_ERROR | HID_COMMAND_FAILED) // Command failed at the device.
Description

Command failed at the device.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_COMMAND_FAILED Macro


USB_HID_COMMAND_PASSED Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_COMMAND_PASSED Macro
C
#define USB_HID_COMMAND_PASSED USB_SUCCESS                               // Command was successful.
Description

Command was successful.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_COMMAND_PASSED Macro


USB_HID_DEVICE_BUSY Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_DEVICE_BUSY Macro
C
#define USB_HID_DEVICE_BUSY (USB_HID_CLASS_ERROR | 0x04)               // A transfer is currently in progress.
Description

A transfer is currently in progress.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_DEVICE_BUSY Macro


USB_HID_DEVICE_DETACHED Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_DEVICE_DETACHED Macro
C
#define USB_HID_DEVICE_DETACHED 0x50    // Device is detached.
Description

Device is detached.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_DEVICE_DETACHED Macro


USB_HID_DEVICE_HOLDING Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_DEVICE_HOLDING Macro
C
#define USB_HID_DEVICE_HOLDING 0x54    // Device is holding due to error
Description

Device is holding due to error

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_DEVICE_HOLDING Macro


USB_HID_DEVICE_ID Structure

Contents | Index | Home
Previous | Up | Next
USB_HID_DEVICE_ID Structure
C
typedef struct _USB_HID_DEVICE_ID {
  WORD vid;
  WORD pid;
  BYTE deviceAddress;
  BYTE clientDriverID;
} USB_HID_DEVICE_ID;
Description

HID Device ID Information

This structure contains identification information about an attached device.

Members
Members | Description
WORD vid; | Vendor ID of the device
WORD pid; | Product ID of the device
BYTE deviceAddress; | Address of the device on the USB
BYTE clientDriverID; | Client driver ID for device requests
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_DEVICE_ID Structure


USB_HID_DEVICE_NOT_FOUND Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_DEVICE_NOT_FOUND Macro
C
#define USB_HID_DEVICE_NOT_FOUND (USB_HID_CLASS_ERROR | 0x03)               // Device with the specified address is not available.
Description

Device with the specified address is not available.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_DEVICE_NOT_FOUND Macro


USB_HID_DEVICE_RPT_INFO Structure

Contents | Index | Home
Previous | Up | Next
USB_HID_DEVICE_RPT_INFO Structure
C
typedef struct _USB_HID_DEVICE_RPT_INFO {
  WORD reportPollingRate;
  BYTE interfaceNumber;
  BOOL haveDesignatorMax;
  BOOL haveDesignatorMin;
  BOOL haveStringMax;
  BOOL haveStringMin;
  BOOL haveUsageMax;
  BOOL haveUsageMin;
  WORD designatorMaximum;
  WORD designatorMinimum;
  WORD designatorRanges;
  WORD designators;
  WORD rangeUsagePage;
  WORD stringMaximum;
  WORD stringMinimum;
  WORD stringRanges;
  WORD usageMaximum;
  WORD usageMinimum;
  WORD usageRanges;
  BYTE collectionNesting;
  BYTE collections;
  BYTE designatorItems;
  BYTE firstUsageItem;
  BYTE firstDesignatorItem;
  BYTE firstStringItem;
  BYTE globalsNesting;
  BYTE maxCollectionNesting;
  BYTE maxGlobalsNesting;
  BYTE parent;
  BYTE reportItems;
  BYTE reports;
  BYTE sibling;
  BYTE stringItems;
  BYTE strings;
  BYTE usageItems;
  BYTE usages;
  HID_GLOBALS globals;
} USB_HID_DEVICE_RPT_INFO;
Description

Report Descriptor Information

This structure contains top level information of the report descriptor. This information is important and is used to understand the information during th ecourse of parsing. This structure also stores temporary data needed during parsing the report descriptor. All of this information may not be of much inportance to the application.

Members
Members | Description
WORD reportPollingRate; | This stores the pollrate for the input report. Application can use this to decide the rate of transfer
BYTE interfaceNumber; | This stores the interface number for the current report descriptor
BOOL haveDesignatorMax; | True if report descriptor has a valid Designator Max
BOOL haveDesignatorMin; | True if report descriptor has a valid Designator Min
BOOL haveStringMax; | True if report descriptor has a valid String Max
BOOL haveStringMin; | True if report descriptor has a valid String Min
BOOL haveUsageMax; | True if report descriptor has a valid Usage Max
BOOL haveUsageMin; | True if report descriptor has a valid Usage Min
WORD designatorMaximum; | Last designator max value
WORD designatorMinimum; | Last designator min value
WORD designatorRanges; | Last designator range
WORD designators; | This tells toatal number of designator items
WORD rangeUsagePage; | current usage page during parsing
WORD stringMaximum; | current string maximum
WORD stringMinimum; | current string minimum
WORD stringRanges; | current string ranges
WORD usageMaximum; | current usage maximum
WORD usageMinimum; | current usage minimum
WORD usageRanges; | current usage ranges
BYTE collectionNesting; | this number tells depth of collection nesting
BYTE collections; | total number of collections
BYTE designatorItems; | total number of designator items
BYTE firstUsageItem; | index of first usage item for the current collection
BYTE firstDesignatorItem; | index of first designator item for the current collection
BYTE firstStringItem; | index of first string item for the current collection
BYTE globalsNesting; | On encountering every PUSH item , this is incremented , keep track of current depth of Globals
BYTE maxCollectionNesting; | Maximum depth of collections
BYTE maxGlobalsNesting; | Maximum depth of Globals
BYTE parent; | Parent collection
BYTE reportItems; | total number of report items
BYTE reports; | total number of reports
BYTE sibling; | current sibling collection
BYTE stringItems; | total number of string items , used to index the array of strings
BYTE strings; | total sumber of strings
BYTE usageItems; | total number of usage items , used to index the array of usage
BYTE usages; | total sumber of usages
HID_GLOBALS globals; | holds cuurent globals items
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_DEVICE_RPT_INFO Structure


USB_HID_ILLEGAL_REQUEST Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_ILLEGAL_REQUEST Macro
C
#define USB_HID_ILLEGAL_REQUEST (USB_HID_CLASS_ERROR | 0x0B) // Cannot perform requested operation.
Description

Cannot perform requested operation.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_ILLEGAL_REQUEST Macro


USB_HID_INITIALIZING Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_INITIALIZING Macro
C
#define USB_HID_INITIALIZING 0x51    // Device is initializing.
Description

Device is initializing.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_INITIALIZING Macro


USB_HID_INTERFACE_ERROR Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_INTERFACE_ERROR Macro
C
#define USB_HID_INTERFACE_ERROR (USB_HID_CLASS_ERROR | 0x06)               // The interface layer cannot support the device.
Description

The interface layer cannot support the device.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_INTERFACE_ERROR Macro


USB_HID_ITEM_LIST Structure

Contents | Index | Home
Previous | Up | Next
USB_HID_ITEM_LIST Structure
C
typedef struct _USB_HID_ITEM_LIST {
  HID_COLLECTION * collectionList;
  HID_DESIGITEM * designatorItemList;
  HID_GLOBALS * globalsStack;
  HID_REPORTITEM * reportItemList;
  HID_REPORT * reportList;
  HID_STRINGITEM * stringItemList;
  HID_USAGEITEM * usageItemList;
  BYTE * collectionStack;
} USB_HID_ITEM_LIST;
Description

List of Items

This structure contains array of pointers to all the Items in the report descriptor. HID parser will populate the lists while parsing the report descriptor. This data is used by interface functions provided in file usb_host_hid_interface.c to retrive data from the report received from the device. Application can also access these details to retreive the intended information incase provided interface function fail to do so.

Members
Members | Description
HID_COLLECTION * collectionList; | List of collections, see HID_COLLECTION for details in the structure
HID_DESIGITEM * designatorItemList; | List of designator Items, see HID_DESIGITEM for details in the structure
HID_GLOBALS * globalsStack; | List of global Items, see HID_GLOBALS for details in the structure
HID_REPORTITEM * reportItemList; | List of report Items, see HID_REPORTITEM for details in the structure
HID_REPORT * reportList; | List of reports , see HID_REPORT for details in the structure
HID_STRINGITEM * stringItemList; | List of string item , see HID_STRINGITEM for details in the structure
HID_USAGEITEM * usageItemList; | List of Usage item , see HID_USAGEITEM for details in the structure
BYTE * collectionStack; | stores the array of parents ids for the collection
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_ITEM_LIST Structure


USB_HID_NO_REPORT_DESCRIPTOR Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_NO_REPORT_DESCRIPTOR Macro
C
#define USB_HID_NO_REPORT_DESCRIPTOR (USB_HID_CLASS_ERROR | 0x05)               // No report descriptor found
Description

No report descriptor found

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_NO_REPORT_DESCRIPTOR Macro


USB_HID_NORMAL_RUNNING Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_NORMAL_RUNNING Macro
C
#define USB_HID_NORMAL_RUNNING 0x53    // Device is running and available for data transfers.
Description

Device is running and available for data transfers.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_NORMAL_RUNNING Macro


USB_HID_PHASE_ERROR Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_PHASE_ERROR Macro
C
#define USB_HID_PHASE_ERROR (USB_HID_CLASS_ERROR | HID_PHASE_ERROR)    // Command had a phase error at the device.
Description

Command had a phase error at the device.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_PHASE_ERROR Macro


USB_HID_REPORT_DESCRIPTOR_BAD Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_REPORT_DESCRIPTOR_BAD Macro
C
#define USB_HID_REPORT_DESCRIPTOR_BAD (USB_HID_CLASS_ERROR | 0x07)               // Report Descriptor for not proper
Description

Report Descriptor for not proper

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_REPORT_DESCRIPTOR_BAD Macro


USB_HID_RESET_ERROR Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_RESET_ERROR Macro
C
#define USB_HID_RESET_ERROR (USB_HID_CLASS_ERROR | 0x0A) // An error occurred while resetting the device.
Description

An error occurred while resetting the device.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_RESET_ERROR Macro


USB_HID_RESETTING_DEVICE Macro

Contents | Index | Home
Previous | Up | Next
USB_HID_RESETTING_DEVICE Macro
C
#define USB_HID_RESETTING_DEVICE 0x55    // Device is being reset.
Description

Device is being reset.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_RESETTING_DEVICE Macro


USB_HID_RPT_DESC_ERROR Enumeration

Contents | Index | Home
Previous | Up | Next
USB_HID_RPT_DESC_ERROR Enumeration
C
typedef enum {
  HID_ERR = 0,
  HID_ERR_NotEnoughMemory,
  HID_ERR_NullPointer,
  HID_ERR_UnexpectedEndCollection,
  HID_ERR_UnexpectedPop,
  HID_ERR_MissingEndCollection,
  HID_ERR_MissingTopLevelCollection,
  HID_ERR_NoReports,
  HID_ERR_UnmatchedUsageRange,
  HID_ERR_UnmatchedStringRange,
  HID_ERR_UnmatchedDesignatorRange,
  HID_ERR_UnexpectedEndOfDescriptor,
  HID_ERR_BadLogicalMin,
  HID_ERR_BadLogicalMax,
  HID_ERR_BadLogical,
  HID_ERR_ZeroReportSize,
  HID_ERR_ZeroReportID,
  HID_ERR_ZeroReportCount,
  HID_ERR_BadUsageRangePage,
  HID_ERR_BadUsageRange
} USB_HID_RPT_DESC_ERROR;
Description

HID parser error codes

This enumerates the error encountered during the parsing of report descriptor. In case of any error parsing is sttopped and the error is flagged. Device is not attched successfully.

Members
Members | Description
HID_ERR = 0 | No error
HID_ERR_NotEnoughMemory | If not enough Heap can be allocated, make sure sufficient dynamic memory is aloocated for the parser
HID_ERR_NullPointer | Pointer to report descriptor is NULL
HID_ERR_UnexpectedEndCollection | End of collection not expected
HID_ERR_UnexpectedPop | POP not expected
HID_ERR_MissingEndCollection | No end of collection found
HID_ERR_MissingTopLevelCollection | Atleast one collection must be present
HID_ERR_NoReports | atlest one report must be present
HID_ERR_UnmatchedUsageRange | Either Minimum or Maximum for usage range missing
HID_ERR_UnmatchedStringRange | Either Minimum or Maximum for string range missing
HID_ERR_UnmatchedDesignatorRange | Either Minimum or Maximum for designator range missing
HID_ERR_UnexpectedEndOfDescriptor | Report descriptor not formatted properly
HID_ERR_BadLogicalMin | Logical Min greater than report size
HID_ERR_BadLogicalMax | Logical Max greater than report size
HID_ERR_BadLogical | If logical Min is greater than Max
HID_ERR_ZeroReportSize | Report size is zero
HID_ERR_ZeroReportID | report ID is zero
HID_ERR_ZeroReportCount | Number of reports is zero
HID_ERR_BadUsageRangePage | Bad Usage page range
HID_ERR_BadUsageRange | Bad Usage range
Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_HID_RPT_DESC_ERROR Enumeration


USB_PROCESSING_REPORT_DESCRIPTOR Macro

Contents | Index | Home
Previous | Up | Next
USB_PROCESSING_REPORT_DESCRIPTOR Macro
C
#define USB_PROCESSING_REPORT_DESCRIPTOR 0x52    // Parser is processing report descriptor.
Description

Parser is processing report descriptor.

Application Programming Interface (API) > Embedded Host API > HID Client Driver > Data Types and Constants > USB_PROCESSING_REPORT_DESCRIPTOR Macro


Mass Storage Client Driver

Contents | Index | Home
Previous | Up | Next
Mass Storage Client Driver

This client driver provides USB Embedded Host support for mass storage devices. Mass storage devices use USB Bulk transfers to efficiently transfer large amounts of data. Bulk transfers may utilize all remaining bandwidth on the bus after all of the Control, Interrupt, and Isochronous transfers for the frame have completed. The exact amount of time required for a bulk transfer will depend on the amount of other traffic that is on the bus. Therefore, Bulk transfers should be used only for non-time critical operations.

This implementation of the Mass Storage Class provides support for the Bulk Only Transport.

See AN1142 - USB Mass Storage Class on an Embedded Host for more information about the Mass Storage Class and this client driver.

Topics
Name | Description
Interface Routines |
Data Types and Constants |
Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
USBHostMSDDeviceStatus | This function determines the status of a mass storage device.
USBHostMSDEventHandler | This function is the event handler for this client driver.
USBHostMSDInitialize | This function is the initialization routine for this client driver.
USBHostMSDResetDevice | This function starts a bulk-only mass storage reset.
USBHostMSDSCSIEventHandler | This function is called when various events occur in the USB Host Mass Storage client driver.
USBHostMSDSCSIInitialize | This function is called when a USB Mass Storage device is being enumerated.
USBHostMSDSCSISectorRead | This function reads one sector.
USBHostMSDSCSISectorWrite | This function writes one sector.
USBHostMSDTerminateTransfer | This function terminates a mass storage transfer.
USBHostMSDTransfer | This function starts a mass storage transfer.
USBHostMSDTransferIsComplete | This function indicates whether or not the last transfer is complete.
Macros
Name | Description
USBHostMSDRead | This function starts a mass storage read, utilizing the function USBHostMSDTransfer();
USBHostMSDWrite | This function starts a mass storage write, utilizing the function USBHostMSDTransfer();
Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Interface Routines


USBHostMSDDeviceStatus Function

Contents | Index | Home
Previous | Up | Next
USBHostMSDDeviceStatus Function
C
BYTE USBHostMSDDeviceStatus(
    BYTE deviceAddress
);
Description

This function determines the status of a mass storage device.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | address of device to query
Return Values
Return Values | Description
USB_MSD_DEVICE_NOT_FOUND | Illegal device address, or the device is not an MSD
USB_MSD_INITIALIZING | MSD is attached and in the process of initializing
USB_MSD_NORMAL_RUNNING | MSD is in normal running mode
USB_MSD_RESETTING_DEVICE | MSD is resetting
USB_MSD_DEVICE_DETACHED | MSD detached. Should not occur
USB_MSD_ERROR_STATE | MSD is holding due to an error. No communication is allowed.
Other | Return codes from USBHostDeviceStatus() will also be returned if the device is in the process of enumerating.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Interface Routines > USBHostMSDDeviceStatus Function


USBHostMSDEventHandler Function

Contents | Index | Home
Previous | Up | Next
USBHostMSDEventHandler Function
C
BOOL USBHostMSDEventHandler(
    BYTE address,
    USB_EVENT event,
    void * data,
    DWORD size
);
Description

This function is the event handler for this client driver. It is called by the host layer when various events occur.

Preconditions

The device has been initialized.

Parameters
Parameters | Description
BYTE address | Address of the device
USB_EVENT event | Event that has occurred
void *data | Pointer to data pertinent to the event
WORD size | Size of the data
Return Values
Return Values | Description
TRUE | Event was handled
FALSE | Event was not handled
Remarks

None

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Interface Routines > USBHostMSDEventHandler Function


USBHostMSDInitialize Function

Contents | Index | Home
Previous | Up | Next
USBHostMSDInitialize Function
C
BOOL USBHostMSDInitialize(
    BYTE address,
    DWORD flags,
    BYTE clientDriverID
);
Description

This function is the initialization routine for this client driver. It is called by the host layer when the USB device is being enumerated. For a mass storage device, we need to make sure that we have room for a new device, and that the device has at least one bulk IN and one bulk OUT endpoint.

Preconditions

None

Parameters
Parameters | Description
BYTE address | Address of the new device
DWORD flags | Initialization flags
BYTE clientDriverID | ID to send when issuing a Device Request via USBHostSendDeviceRequest(), USBHostSetDeviceConfiguration(), or USBHostSetDeviceInterface().
Return Values
Return Values | Description
TRUE | We can support the device.
FALSE | We cannot support the device.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Interface Routines > USBHostMSDInitialize Function


USBHostMSDRead Macro

Contents | Index | Home
Previous | Up | Next
USBHostMSDRead Macro
C
#define USBHostMSDRead( deviceAddress,deviceLUN,commandBlock,commandBlockLength,data,dataLength ) \
        USBHostMSDTransfer( deviceAddress, deviceLUN, 1, commandBlock, commandBlockLength, data, dataLength )
Description

This function starts a mass storage read, utilizing the function USBHostMSDTransfer();

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE deviceLUN | Device LUN to access
BYTE *commandBlock | Pointer to the command block for the CBW
BYTE commandBlockLength | Length of the command block
BYTE *data | Pointer to the data buffer
DWORD dataLength | Byte size of the data buffer
Return Values
Return Values | Description
USB_SUCCESS | Request started successfully
USB_MSD_DEVICE_NOT_FOUND | No device with specified address
USB_MSD_DEVICE_BUSY | Device not in proper state for performing a transfer
USB_MSD_INVALID_LUN | Specified LUN does not exist
Remarks

None

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Interface Routines > USBHostMSDRead Macro


USBHostMSDResetDevice Function

Contents | Index | Home
Previous | Up | Next
USBHostMSDResetDevice Function
C
BYTE USBHostMSDResetDevice(
    BYTE deviceAddress
);
Description

This function starts a bulk-only mass storage reset. A reset can be issued only if the device is attached and not being initialized.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
Return Values
Return Values | Description
USB_SUCCESS | Reset started
USB_MSD_DEVICE_NOT_FOUND | No device with specified address
USB_MSD_ILLEGAL_REQUEST | Device is in an illegal state for reset
Remarks

None

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Interface Routines > USBHostMSDResetDevice Function


USBHostMSDSCSIEventHandler Function

Contents | Index | Home
Previous | Up | Next
USBHostMSDSCSIEventHandler Function
C
BOOL USBHostMSDSCSIEventHandler(
    BYTE address,
    USB_EVENT event,
    void * data,
    DWORD size
);
Description

This function is called when various events occur in the USB Host Mass Storage client driver.

Preconditions

The device has been initialized.

Parameters
Parameters | Description
BYTE address | Address of the device
USB_EVENT event | Event that has occurred
void *data | Pointer to data pertinent to the event
DWORD size | Size of the data
Return Values
Return Values | Description
TRUE | Event was handled
FALSE | Event was not handled
Remarks

None

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Interface Routines > USBHostMSDSCSIEventHandler Function


USBHostMSDSCSIInitialize Function

Contents | Index | Home
Previous | Up | Next
USBHostMSDSCSIInitialize Function
C
BOOL USBHostMSDSCSIInitialize(
    BYTE address,
    DWORD flags,
    BYTE clientDriverID
);
Description

This function is called when a USB Mass Storage device is being enumerated.

Preconditions

None

Parameters
Parameters | Description
BYTE address | Address of the new device
DWORD flags | Initialization flags
BYTE clientDriverID | ID for this layer. Not used by the media interface layer.
Return Values
Return Values | Description
TRUE | We can support the device.
FALSE | We cannot support the device.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Interface Routines > USBHostMSDSCSIInitialize Function


USBHostMSDSCSISectorRead Function

Contents | Index | Home
Previous | Up | Next
USBHostMSDSCSISectorRead Function
C
BYTE USBHostMSDSCSISectorRead(
    DWORD sectorAddress,
    BYTE * dataBuffer
);
Description

This function uses the SCSI command READ10 to read one sector. The size of the sector was determined in the USBHostMSDSCSIMediaInitialize() function. The data is stored in the application buffer.

Preconditions

None

Parameters
Parameters | Description
DWORD sectorAddress | address of sector to read
BYTE *dataBuffer | buffer to store data
Return Values
Return Values | Description
TRUE | read performed successfully
FALSE | read was not successful
Remarks

The READ10 command block is as follows:

Copy Code
    Byte/Bit    7       6       5       4       3       2       1       0
       0                    Operation Code (0x28)
       1        [    RDPROTECT      ]  DPO     FUA      -     FUA_NV    -
       2        [ (MSB)
       3                        Logical Block Address
       4
       5                                                          (LSB) ]
       6        [         -         ][          Group Number            ]
       7        [ (MSB)         Transfer Length
       8                                                          (LSB) ]
       9        [                    Control                            ]
Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Interface Routines > USBHostMSDSCSISectorRead Function


USBHostMSDSCSISectorWrite Function

Contents | Index | Home
Previous | Up | Next
USBHostMSDSCSISectorWrite Function
C
BYTE USBHostMSDSCSISectorWrite(
    DWORD sectorAddress,
    BYTE * dataBuffer,
    BYTE allowWriteToZero
);
Description

This function uses the SCSI command WRITE10 to write one sector. The size of the sector was determined in the USBHostMSDSCSIMediaInitialize() function. The data is read from the application buffer.

Preconditions

None

Parameters
Parameters | Description
DWORD sectorAddress | address of sector to write
BYTE *dataBuffer | buffer with application data
BYTE allowWriteToZero | If a write to sector 0 is allowed.
Return Values
Return Values | Description
TRUE | write performed successfully
FALSE | write was not successful
Remarks

To follow convention, this function blocks until the write is complete.

The WRITE10 command block is as follows:

Copy Code
    Byte/Bit    7       6       5       4       3       2       1       0
       0                    Operation Code (0x2A)
       1        [    WRPROTECT      ]  DPO     FUA      -     FUA_NV    -
       2        [ (MSB)
       3                        Logical Block Address
       4
       5                                                          (LSB) ]
       6        [         -         ][          Group Number            ]
       7        [ (MSB)         Transfer Length
       8                                                          (LSB) ]
       9        [                    Control                            ]
Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Interface Routines > USBHostMSDSCSISectorWrite Function


USBHostMSDTerminateTransfer Function

Contents | Index | Home
Previous | Up | Next
USBHostMSDTerminateTransfer Function
C
void USBHostMSDTerminateTransfer(
    BYTE deviceAddress
);
Description

This function terminates a mass storage transfer.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
Returns

None

Remarks

After executing this function, the application may have to reset the device in order for the device to continue working properly.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Interface Routines > USBHostMSDTerminateTransfer Function


USBHostMSDTransfer Function

Contents | Index | Home
Previous | Up | Next
USBHostMSDTransfer Function
C
BYTE USBHostMSDTransfer(
    BYTE deviceAddress,
    BYTE deviceLUN,
    BYTE direction,
    BYTE * commandBlock,
    BYTE commandBlockLength,
    BYTE * data,
    DWORD dataLength
);
Description

This function starts a mass storage transfer. Usually, applications will probably utilize a read/write wrapper to access this function.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE deviceLUN | Device LUN to access
BYTE direction | 1=read, 0=write
BYTE *commandBlock | Pointer to the command block for the CBW
BYTE commandBlockLength | Length of the command block
BYTE *data | Pointer to the data buffer
DWORD dataLength | Byte size of the data buffer
Return Values
Return Values | Description
USB_SUCCESS | Request started successfully
USB_MSD_DEVICE_NOT_FOUND | No device with specified address
USB_MSD_DEVICE_BUSY | Device not in proper state for performing a transfer
USB_MSD_INVALID_LUN | Specified LUN does not exist
Remarks

None

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Interface Routines > USBHostMSDTransfer Function


USBHostMSDTransferIsComplete Function

Contents | Index | Home
Previous | Up | Next
USBHostMSDTransferIsComplete Function
C
BOOL USBHostMSDTransferIsComplete(
    BYTE deviceAddress,
    BYTE * errorCode,
    DWORD * byteCount
);
Description

This function indicates whether or not the last transfer is complete. If the functions returns TRUE, the returned byte count and error code are valid. Since only one transfer can be performed at once and only one endpoint can be used, we only need to know the device address.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE *errorCode | Error code from last transfer
DWORD *byteCount | Number of bytes transferred
Return Values
Return Values | Description
TRUE | Transfer is complete, errorCode is valid
FALSE | Transfer is not complete, errorCode is not valid
Remarks

None

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Interface Routines > USBHostMSDTransferIsComplete Function


USBHostMSDWrite Macro

Contents | Index | Home
Previous | Up | Next
USBHostMSDWrite Macro
C
#define USBHostMSDWrite( deviceAddress,deviceLUN,commandBlock,commandBlockLength,data,dataLength ) \
        USBHostMSDTransfer( deviceAddress, deviceLUN, 0, commandBlock, commandBlockLength, data, dataLength )
Description

This function starts a mass storage write, utilizing the function USBHostMSDTransfer();

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | Device address
BYTE deviceLUN | Device LUN to access
BYTE *commandBlock | Pointer to the command block for the CBW
BYTE commandBlockLength | Length of the command block
BYTE *data | Pointer to the data buffer
DWORD dataLength | Byte size of the data buffer
Return Values
Return Values | Description
USB_SUCCESS | Request started successfully
USB_MSD_DEVICE_NOT_FOUND | No device with specified address
USB_MSD_DEVICE_BUSY | Device not in proper state for performing a transfer
USB_MSD_INVALID_LUN | Specified LUN does not exist
Remarks

None

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Interface Routines > USBHostMSDWrite Macro


Data Types and Constants

Contents | Index | Home
Previous | Up | Next
Data Types and Constants
Macros
Name | Description
DEVICE_CLASS_MASS_STORAGE | Class code for Mass Storage.
DEVICE_INTERFACE_PROTOCOL_BULK_ONLY | Protocol code for Bulk-only mass storage.
DEVICE_SUBCLASS_CD_DVD | SubClass code for a CD/DVD drive (not supported).
DEVICE_SUBCLASS_FLOPPY_INTERFACE | SubClass code for a floppy disk interface (not supported).
DEVICE_SUBCLASS_RBC | SubClass code for Reduced Block Commands (not supported).
DEVICE_SUBCLASS_REMOVABLE | SubClass code for removable media (not supported).
DEVICE_SUBCLASS_SCSI | SubClass code for a SCSI interface device (supported).
DEVICE_SUBCLASS_TAPE_DRIVE | SubClass code for a tape drive (not supported).
EVENT_MSD_MAX_LUN | Set maximum LUN for the device
EVENT_MSD_NONE | No event occured (NULL event)
EVENT_MSD_OFFSET | If the application has not defined an offset for MSD events, set it to 0.
EVENT_MSD_RESET | MSD reset complete
EVENT_MSD_TRANSFER | A MSD transfer has completed
MSD_COMMAND_FAILED | Transfer failed. Returned in dCSWStatus.
MSD_COMMAND_PASSED | Transfer was successful. Returned in dCSWStatus.
MSD_PHASE_ERROR | Transfer phase error. Returned in dCSWStatus.
USB_MSD_CBW_ERROR | The CBW was not transferred successfully.
USB_MSD_COMMAND_FAILED | Command failed at the device.
USB_MSD_COMMAND_PASSED | Command was successful.
USB_MSD_CSW_ERROR | The CSW was not transferred successfully.
USB_MSD_DEVICE_BUSY | A transfer is currently in progress.
USB_MSD_DEVICE_DETACHED | Device is detached.
USB_MSD_DEVICE_NOT_FOUND | Device with the specified address is not available.
USB_MSD_ERROR | Error code offset.
USB_MSD_ERROR_STATE | Device is holding due to a MSD error.
USB_MSD_ILLEGAL_REQUEST | Cannot perform requested operation.
USB_MSD_INITIALIZING | Device is initializing.
USB_MSD_INVALID_LUN | Invalid LUN specified.
USB_MSD_MEDIA_INTERFACE_ERROR | The media interface layer cannot support the device.
USB_MSD_NORMAL_RUNNING | Device is running and available for data transfers.
USB_MSD_OUT_OF_MEMORY | No dynamic memory is available.
USB_MSD_PHASE_ERROR | Command had a phase error at the device.
USB_MSD_RESET_ERROR | An error occurred while resetting the device.
USB_MSD_RESETTING_DEVICE | Device is being reset.
Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants


DEVICE_CLASS_MASS_STORAGE Macro

Contents | Index | Home
Previous | Up | Next
DEVICE_CLASS_MASS_STORAGE Macro
C
#define DEVICE_CLASS_MASS_STORAGE 0x08    // Class code for Mass Storage.
Description

Class code for Mass Storage.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > DEVICE_CLASS_MASS_STORAGE Macro


DEVICE_INTERFACE_PROTOCOL_BULK_ONLY Macro

Contents | Index | Home
Previous | Up | Next
DEVICE_INTERFACE_PROTOCOL_BULK_ONLY Macro
C
#define DEVICE_INTERFACE_PROTOCOL_BULK_ONLY 0x50    // Protocol code for Bulk-only mass storage.
Description

Protocol code for Bulk-only mass storage.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > DEVICE_INTERFACE_PROTOCOL_BULK_ONLY Macro


DEVICE_SUBCLASS_CD_DVD Macro

Contents | Index | Home
Previous | Up | Next
DEVICE_SUBCLASS_CD_DVD Macro
C
#define DEVICE_SUBCLASS_CD_DVD 0x02    // SubClass code for a CD/DVD drive (not supported).
Description

SubClass code for a CD/DVD drive (not supported).

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > DEVICE_SUBCLASS_CD_DVD Macro


DEVICE_SUBCLASS_FLOPPY_INTERFACE Macro

Contents | Index | Home
Previous | Up | Next
DEVICE_SUBCLASS_FLOPPY_INTERFACE Macro
C
#define DEVICE_SUBCLASS_FLOPPY_INTERFACE 0x04    // SubClass code for a floppy disk interface (not supported).
Description

SubClass code for a floppy disk interface (not supported).

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > DEVICE_SUBCLASS_FLOPPY_INTERFACE Macro


DEVICE_SUBCLASS_RBC Macro

Contents | Index | Home
Previous | Up | Next
DEVICE_SUBCLASS_RBC Macro
C
#define DEVICE_SUBCLASS_RBC 0x01    // SubClass code for Reduced Block Commands (not supported).
Description

SubClass code for Reduced Block Commands (not supported).

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > DEVICE_SUBCLASS_RBC Macro


DEVICE_SUBCLASS_REMOVABLE Macro

Contents | Index | Home
Previous | Up | Next
DEVICE_SUBCLASS_REMOVABLE Macro
C
#define DEVICE_SUBCLASS_REMOVABLE 0x05    // SubClass code for removable media (not supported).
Description

SubClass code for removable media (not supported).

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > DEVICE_SUBCLASS_REMOVABLE Macro


DEVICE_SUBCLASS_SCSI Macro

Contents | Index | Home
Previous | Up | Next
DEVICE_SUBCLASS_SCSI Macro
C
#define DEVICE_SUBCLASS_SCSI 0x06    // SubClass code for a SCSI interface device (supported).
Description

SubClass code for a SCSI interface device (supported).

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > DEVICE_SUBCLASS_SCSI Macro


DEVICE_SUBCLASS_TAPE_DRIVE Macro

Contents | Index | Home
Previous | Up | Next
DEVICE_SUBCLASS_TAPE_DRIVE Macro
C
#define DEVICE_SUBCLASS_TAPE_DRIVE 0x03    // SubClass code for a tape drive (not supported).
Description

SubClass code for a tape drive (not supported).

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > DEVICE_SUBCLASS_TAPE_DRIVE Macro


EVENT_MSD_MAX_LUN Macro

Contents | Index | Home
Previous | Up | Next
EVENT_MSD_MAX_LUN Macro
C
#define EVENT_MSD_MAX_LUN EVENT_MSD_BASE + EVENT_MSD_OFFSET + 3   // Set maximum LUN for the device
Description

Set maximum LUN for the device

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > EVENT_MSD_MAX_LUN Macro


EVENT_MSD_NONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_MSD_NONE Macro
C
#define EVENT_MSD_NONE EVENT_MSD_BASE + EVENT_MSD_OFFSET + 0   // No event occured (NULL event)
Description

No event occured (NULL event)

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > EVENT_MSD_NONE Macro


EVENT_MSD_OFFSET Macro

Contents | Index | Home
Previous | Up | Next
EVENT_MSD_OFFSET Macro
C
#define EVENT_MSD_OFFSET 0
Description

If the application has not defined an offset for MSD events, set it to 0.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > EVENT_MSD_OFFSET Macro


EVENT_MSD_RESET Macro

Contents | Index | Home
Previous | Up | Next
EVENT_MSD_RESET Macro
C
#define EVENT_MSD_RESET EVENT_MSD_BASE + EVENT_MSD_OFFSET + 2   // MSD reset complete
Description

MSD reset complete

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > EVENT_MSD_RESET Macro


EVENT_MSD_TRANSFER Macro

Contents | Index | Home
Previous | Up | Next
EVENT_MSD_TRANSFER Macro
C
#define EVENT_MSD_TRANSFER EVENT_MSD_BASE + EVENT_MSD_OFFSET + 1   // A MSD transfer has completed
Description

A MSD transfer has completed

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > EVENT_MSD_TRANSFER Macro


MSD_COMMAND_FAILED Macro

Contents | Index | Home
Previous | Up | Next
MSD_COMMAND_FAILED Macro
C
#define MSD_COMMAND_FAILED 0x01    // Transfer failed. Returned in dCSWStatus.
Description

Transfer failed. Returned in dCSWStatus.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > MSD_COMMAND_FAILED Macro


MSD_COMMAND_PASSED Macro

Contents | Index | Home
Previous | Up | Next
MSD_COMMAND_PASSED Macro
C
#define MSD_COMMAND_PASSED 0x00    // Transfer was successful. Returned in dCSWStatus.
Description

Transfer was successful. Returned in dCSWStatus.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > MSD_COMMAND_PASSED Macro


MSD_PHASE_ERROR Macro

Contents | Index | Home
Previous | Up | Next
MSD_PHASE_ERROR Macro
C
#define MSD_PHASE_ERROR 0x02    // Transfer phase error. Returned in dCSWStatus.
Description

Transfer phase error. Returned in dCSWStatus.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > MSD_PHASE_ERROR Macro


USB_MSD_CBW_ERROR Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_CBW_ERROR Macro
C
#define USB_MSD_CBW_ERROR (USB_MSD_ERROR | 0x04)              // The CBW was not transferred successfully.
Description

The CBW was not transferred successfully.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_CBW_ERROR Macro


USB_MSD_COMMAND_FAILED Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_COMMAND_FAILED Macro
C
#define USB_MSD_COMMAND_FAILED (USB_MSD_ERROR | MSD_COMMAND_FAILED)// Command failed at the device.
Description

Command failed at the device.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_COMMAND_FAILED Macro


USB_MSD_COMMAND_PASSED Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_COMMAND_PASSED Macro
C
#define USB_MSD_COMMAND_PASSED USB_SUCCESS                         // Command was successful.
Description

Command was successful.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_COMMAND_PASSED Macro


USB_MSD_CSW_ERROR Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_CSW_ERROR Macro
C
#define USB_MSD_CSW_ERROR (USB_MSD_ERROR | 0x05)              // The CSW was not transferred successfully.
Description

The CSW was not transferred successfully.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_CSW_ERROR Macro


USB_MSD_DEVICE_BUSY Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_DEVICE_BUSY Macro
C
#define USB_MSD_DEVICE_BUSY (USB_MSD_ERROR | 0x07)              // A transfer is currently in progress.
Description

A transfer is currently in progress.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_DEVICE_BUSY Macro


USB_MSD_DEVICE_DETACHED Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_DEVICE_DETACHED Macro
C
#define USB_MSD_DEVICE_DETACHED 0x50    // Device is detached.
Description

Device is detached.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_DEVICE_DETACHED Macro


USB_MSD_DEVICE_NOT_FOUND Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_DEVICE_NOT_FOUND Macro
C
#define USB_MSD_DEVICE_NOT_FOUND (USB_MSD_ERROR | 0x06)              // Device with the specified address is not available.
Description

Device with the specified address is not available.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_DEVICE_NOT_FOUND Macro


USB_MSD_ERROR Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_ERROR Macro
C
#define USB_MSD_ERROR USB_ERROR_CLASS_DEFINED             // Error code offset.
Description

Error code offset.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_ERROR Macro


USB_MSD_ERROR_STATE Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_ERROR_STATE Macro
C
#define USB_MSD_ERROR_STATE 0x55    // Device is holding due to a MSD error.
Description

Device is holding due to a MSD error.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_ERROR_STATE Macro


USB_MSD_ILLEGAL_REQUEST Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_ILLEGAL_REQUEST Macro
C
#define USB_MSD_ILLEGAL_REQUEST (USB_MSD_ERROR | 0x0B)              // Cannot perform requested operation.
Description

Cannot perform requested operation.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_ILLEGAL_REQUEST Macro


USB_MSD_INITIALIZING Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_INITIALIZING Macro
C
#define USB_MSD_INITIALIZING 0x51    // Device is initializing.
Description

Device is initializing.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_INITIALIZING Macro


USB_MSD_INVALID_LUN Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_INVALID_LUN Macro
C
#define USB_MSD_INVALID_LUN (USB_MSD_ERROR | 0x08)              // Invalid LUN specified.
Description

Invalid LUN specified.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_INVALID_LUN Macro


USB_MSD_MEDIA_INTERFACE_ERROR Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_MEDIA_INTERFACE_ERROR Macro
C
#define USB_MSD_MEDIA_INTERFACE_ERROR (USB_MSD_ERROR | 0x09)              // The media interface layer cannot support the device.
Description

The media interface layer cannot support the device.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_MEDIA_INTERFACE_ERROR Macro


USB_MSD_NORMAL_RUNNING Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_NORMAL_RUNNING Macro
C
#define USB_MSD_NORMAL_RUNNING 0x52    // Device is running and available for data transfers.
Description

Device is running and available for data transfers.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_NORMAL_RUNNING Macro


USB_MSD_OUT_OF_MEMORY Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_OUT_OF_MEMORY Macro
C
#define USB_MSD_OUT_OF_MEMORY (USB_MSD_ERROR | 0x03)              // No dynamic memory is available.
Description

No dynamic memory is available.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_OUT_OF_MEMORY Macro


USB_MSD_PHASE_ERROR Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_PHASE_ERROR Macro
C
#define USB_MSD_PHASE_ERROR (USB_MSD_ERROR | MSD_PHASE_ERROR)   // Command had a phase error at the device.
Description

Command had a phase error at the device.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_PHASE_ERROR Macro


USB_MSD_RESET_ERROR Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_RESET_ERROR Macro
C
#define USB_MSD_RESET_ERROR (USB_MSD_ERROR | 0x0A)              // An error occurred while resetting the device.
Description

An error occurred while resetting the device.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_RESET_ERROR Macro


USB_MSD_RESETTING_DEVICE Macro

Contents | Index | Home
Previous | Up | Next
USB_MSD_RESETTING_DEVICE Macro
C
#define USB_MSD_RESETTING_DEVICE 0x53    // Device is being reset.
Description

Device is being reset.

Application Programming Interface (API) > Embedded Host API > Mass Storage Client Driver > Data Types and Constants > USB_MSD_RESETTING_DEVICE Macro


Printer Client Driver

Contents | Index | Home
Previous | Up | Next
Printer Client Driver

Many USB printers utilize the USB Printer Class to communicate with a USB Host. This class defines the USB transfer type, the endpoint structure,a device requests that can be performed. The actual commands sent to the printer, however, are dictated by the printer language used by the particular printer.

Many different printer languages are utilized by the wide variety of printers on the market. Typically, low end printers receive printer-specific binary data, utilizing the processing power of the USB Host to perform all of the complex calculations required to translate text and graphics to a simple binary representation. This works well when a PC is the USB Host, but it is not conducive to an embedded application with limited resources.

Many printers on the market use a command based printer language, relying on the printer itself to interpret commands to produce the desired output. Some languages are standardized across printers from a particular manufacturer, and some are used across multiple manufacturer. This method lends itself better to embedded applications by allowing the printer to take on some of the computational overhead. Microchip provides support for some printer languages, including ESC/POS, PostScript, and PCL 5. Additional printer language can be implemented. Refer to the USB Embedded Host Printer Class application notes for more details on implementing printer language support.

Printer support is loosely divided into two categories: full sheet and point-of-sale (POS). Full sheet printers print on standard letter sized paper, and use printer languages such as PostScript and PCL 5. POS printers typically print on paper rolls, and use printer languages such as ESC/POS. The difference between printing on these two types of printers will be shown below.

Coordinate System - Full Sheet Printers

Locations on the printed page are specified in terms of (X,Y) coordinates. The (0,0) location on the page is located at the upper left corner, in either portrait or landscape mode. Ascending values of X proceed right across the page, and ascending values of Y proceed down the page. The scale of the coordinate system is 72 dots per inch, giving a maximum position of (611,791) in the portrait orientation, and (791,611) in the landscape orientation.

Standard vs. Page Mode - POS Printers

All POS printers support Standard Mode printing. In this mode, the printer prints the output as soon as it receives the command. Output is printed one line at a time, and vertical position is determined simply by the previous lines that were printed. Many POS printers also support Page Mode, where an entire "page" can be described before it is printed. Currently, only Standard Mode is supported.

Colors - Full Sheet Printers

Currently, only black and white printing is supported. All printing is performed with opaque colors; if a a white object is printed over a previously printed black object, the white object will be visible on the printed output. Therefore, it is important to consider the order in which the objects should be printed.

Colors - POS Printers

Most POS printers support only one color. Some printers, particularly impact printers that utilize a printer ribbon, can print in two colors. If the printer supports two color printing, use the commands USB_PRINTER_POS_COLOR_BLACK and USB_PRINTER_POS_COLOR_RED to specify the color.

Printing Commands

The application receives the event EVENT_PRINTER_ATTACH when a USB printer successfully attaches. The application can then send printing commands to the printer, utilizing either USBHostPrinterCommand() or USBHostPrinterCommandWithReadyWait().

Starting a Print Job

To start a print job, issue the command USB_PRINTER_JOB_START (USB_PRINTER_COMMAND enum). This will reset the printer back to its default settings.

Page Orientation - Full Sheet Printers

The page orientation must be set immediately after starting the print job, before any other printing commands. It cannot be changed in the middle of a page. To set portrait orientation, issue the command USB_PRINTER_ORIENTATION_PORTRAIT (USB_PRINTER_COMMAND enum). To set landscape orientation, issue the command USB_PRINTER_ORIENTATION_LANDSCAPE (USB_PRINTER_COMMAND enum). The default orientation is portrait.

Set Position - Full Sheet Printers

Many printer commands will be performed at the current location of the printer cursor. To move the printer cursor to the desired location, issue the command USB_PRINTER_SET_POSITION (USB_PRINTER_COMMAND enum).

Set Justification - POS Printers

Set the horizontal justification of the printed items to left, center, or right justification by issuing the command USB_PRINTER_POS_JUSTIFICATION_LEFT, USB_PRINTER_POS_JUSTIFICATION_CENTER, or USB_PRINTER_POS_JUSTIFICATION_RIGHT (USB_PRINTER_COMMAND enum).

Stop the Job

To finish the print job, issue the command USB_PRINTER_JOB_STOP (USB_PRINTER_COMMAND enum). This will print the page and reset the printer for the next job.

Selecting Fonts - Full Sheet Printers

Before printing text, select the desired font by issuing the command USB_PRINTER_FONT_NAME (USB_PRINTER_COMMAND enum). The available fonts, supported by most printers, are listed in the USB_PRINTER_FONTS enumeration. Select the size of the font in points by issuing the command USB_PRINTER_FONT_SIZE (USB_PRINTER_COMMAND enum). The font can be made italic by issuing the command USB_PRINTER_FONT_ITALIC (USB_PRINTER_COMMAND enum), and returned to upright by issuing the command USB_PRINTER_FONT_UPRIGHT (USB_PRINTER_COMMAND enum). The font can be made bold by issuing the command USB_PRINTER_FONT_BOLD (USB_PRINTER_COMMAND enum), and returned to medium weight be issuing the command USB_PRINTER_FONT_MEDIUM (USB_PRINTER_COMMAND enum).

Note: When the printer receives the font selection commands described above, the printer will select its best matching internal font. Some printers may not be able to support all fonts at all sizes and with all italic and bold combinations. Be sure to test the output on the target printer to ensure that the output appears as desired. In general, PostScript printers provide the best font support.

Bitmapped fonts are currently not supported.

Selecting Fonts - POS Printers

Before printing text, select the desired font by issuing the command USB_PRINTER_FONT_NAME (USB_PRINTER_COMMAND enum). The available fonts, supported by most printers, are listed in the USB_PRINTER_FONTS_POS enumeration. The font name also includes the font size, so the command USB_PRINTER_FONT_SIZE (USB_PRINTER_COMMAND enum) is not supported by POS printers. The font can be made bold by issuing the command USB_PRINTER_FONT_BOLD (USB_PRINTER_COMMAND enum), and returned to medium weight be issuing the command USB_PRINTER_FONT_MEDIUM (USB_PRINTER_COMMAND enum). Use the command USB_PRINTER_POS_FONT_UNDERLINE (USB_PRINTER_COMMAND enum) to enable and disable underlining. If the printer has to ability to do reverse text printing (white characters on a black background), use the command USB_PRINTER_POS_FONT_REVERSE (USB_PRINTER_COMMAND enum) to enable and disable reverse text printing.

User defined characters and fonts are not currently supported.

Printing Text - Full Sheet Printers

To print text, first set the printer cursor to the desired location, and select the desired font, as described above. Initialize text printing by issuing the command USB_PRINTER_TEXT_START (USB_PRINTER_COMMAND enum). After this command, issue the command USB_PRINTER_TEXT (USB_PRINTER_COMMAND enum) with the desired text string to print. Then issue the command USB_PRINTER_TEXT_STOP (USB_PRINTER_COMMAND enum).

This sequence of commands is required in order to support the various ways that the different printer languages handle text printing. Do not insert any other printer commands in this sequence, or the print will fail.

Different printers handle an embedded carriage returns and line feeds differently. For maximum compatibility across all printers, print each line of text separately.

Printing Text - POS Printers

The three command sequence described above can also be for printing text to POS printers. To simplify text printing in standard mode, use the command USB_PRINTER_POS_TEXT_LINE (USB_PRINTER_COMMAND enum) to print a single, null terminated string.

Printing Bitmapped Images

The printer languages supplied with USB Embedded Host Printer Class Support can print bitmapped images that are compatible with the Microchip Graphics Library bitmapped images. The images must be specified with one bit per pixel. A bit value of 0 indicates the color black, and a bit value of 1 indicates the color white. Images are opaque, not transparent. Image data begins at the top left corner, with the data proceeding from left to right, then top to bottom.

To print a bitmapped image, issue the command USB_PRINTER_IMAGE_START (USB_PRINTER_COMMAND enum) to initialize the image print. Be sure to examine the structure USB_PRINTER_IMAGE_INFO, required by this command, and fill in all of the members appropriately for the image. Note that the position of the image on the paper is specified in the structure, so the printer cursor does not have to be explicitly set before this command. Next, send the image data to the printer, one line at a time. For each line, issue the command USB_PRINTER_IMAGE_DATA_HEADER (USB_PRINTER_COMMAND enum), then issue the command USB_PRINTER_IMAGE_DATA (USB_PRINTER_COMMAND enum) with a pointer to the row of bitmapped data. Be sure to correctly indicate the source of the data (RAM, ROM, or external memory). After all of the data has been transferred, issue the command USB_PRINTER_IMAGE_STOP (USB_PRINTER_COMMAND enum) to terminate image printing.

This sequence of commands is required in order to support the various ways that the different printer languages handle bitmapped image printing. Do not insert any other printer commands in this sequence, or the print will fail.

POS printers require image data in a slightly modified format from full sheet printers. Refer to the function USBHostPrinterPOSImageDataFormat() for further information about printing to POS printers.

NOTE: Some printer languages use the reverse polarity to specify black and white. For compatibility, the printer language drivers will automatically convert the image data to the format required by the particular printer, as long as the image data is located in ROM (USB_PRINTER_TRANSFER_FROM_ROM) or it is copied from a RAM buffer (USB_PRINTER_TRANSFER_COPY_DATA). If the data is to be sent directly from its original RAM location, the data must already be in the format required by the printer language. Refer to the main printer language documentation to see if the default polarity differs from 0=black, 1=white.

Vector Graphics - Full Sheet Printers

Some printer languages offer the ability to perform vector graphics, or the ability to print shapes such as lines and arcs via special commands instead of bitmaps. If vector graphics support is enabled, many additional commands are available to easily print shapes. Refer to the enumeration USB_PRINTER_COMMAND for the list of commands and which ones are supported only if vector graphics is enabled.

Multiple Page Output - Full Sheet Printers

If the print job contains multiple pages, issue the command USB_PRINTER_EJECT_PAGE (USB_PRINTER_COMMAND enum) to print and eject the current page. After this command, previous settings for orientation, font, and line type settings should be assumed to be undefined. Re-issue these commands at the beginning of each page to ensure correct output.

See AN1233 - USB Printer Class on an Embedded Host for more information about the Printer Class and this client driver.

Topics
Name | Description
Interface Routines |
Data Types and Constants |
Application Programming Interface (API) > Embedded Host API > Printer Client Driver


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
PrintScreen | This routine will extract the image that is currently on the specified portion of the graphics display, and print it at the specified location.
USBHostPrinterCommand | This is the primary user interface function for the printer client driver. It is used to issue all printer commands.
USBHostPrinterCommandReady | This interface is used to check if the client driver has space available to enqueue another transfer.
USBHostPrinterDeviceDetached | This interface is used to check if the device has been detached from the bus.
USBHostPrinterEventHandler | This routine is called by the Host layer to notify the printer client of events that occur.
USBHostPrinterGetRxLength | This function retrieves the number of bytes copied to user's buffer by the most recent call to the USBHostPrinterRead() function.
USBHostPrinterGetStatus | This function issues the Printer class-specific Device Request to obtain the printer status.
USBHostPrinterInitialize | This function is called by the USB Embedded Host layer when a printer attaches.
USBHostPrinterLanguageESCPOS | This function executes printer commands for an ESC/POS printer.
USBHostPrinterLanguageESCPOSIsSupported | This function determines if the printer with the given device ID string supports the ESC/POS printer language.
USBHostPrinterLanguagePCL5 | This function executes printer commands for a PCL 5 printer.
USBHostPrinterLanguagePCL5IsSupported | This function determines if the printer with the given device ID string supports the PCL 5 printer language.
USBHostPrinterLanguagePostScript | This function executes printer commands for a PostScript printer.
USBHostPrinterLanguagePostScriptIsSupported | This function determines if the printer with the given device ID string supports the PostScript printer language.
USBHostPrinterPOSImageDataFormat | This function formats data for a bitmapped image into the format required for sending to a POS printer.
USBHostPrinterRead | Use this routine to receive from the device and store it into memory.
USBHostPrinterReset | This function issues the Printer class-specific Device Request to perform a soft reset.
USBHostPrinterRxIsBusy | This interface is used to check if the client driver is currently busy receiving data from the device.
USBHostPrinterWrite | Use this routine to transmit data from memory to the device. This routine will not usually be called by the application directly. The application will use the USBHostPrinterCommand() function, which will call the appropriate printer language support function, which will utilize this routine.
USBHostPrinterWriteComplete | This interface is used to check if the client driver is currently transmitting data to the printer, or if it is between transfers but still has transfers queued.
Macros
Name | Description
USBHostPrinterCommandWithReadyWait | This function is intended to be a short-cut to perform blocking calls to USBHostPrinterCommand(). While there is no space available in the printer queue (USBHostPrinterCommandReady() returns FALSE), USBTasks() is called. When space becomes available, USBHostPrinterCommand() is called. The return value from USBHostPrinterCommand() is returned in the returnCode parameter.
USBHostPrinterPosition | This function is used to simplify the call to the printer command USB_PRINTER_SET_POSITION by generating the value needed for the specified (X,Y) coordinate.
USBHostPrinterPositionRelative | This function is used to simplify the call to some of the printer graphics commands by generating the value needed for the specified change in X and change in Y coordinates.
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines


PrintScreen Function

Contents | Index | Home
Previous | Up | Next
PrintScreen Function
C
SHORT PrintScreen(
    BYTE address,
    USB_PRINT_SCREEN_INFO * printScreenInfo
);
Description

This routine is intended for use in an application that is using the Graphics Library to control a graphics display. This routine will extract the image that is currently on the specified portion of the graphics display, and print it at the specified location. Since the display may be in color and the printer can print only black and white, the pixel color to interpret as black must be specified in the USB_PRINT_SCREEN_INFO structure.

The function can be compiled as either a blocking function or a non-blocking function. When compiled as a blocking function, the routine will wait to enqueue all printer instructions. If an error occurs, then this function will return the error. If all printer instructions are enqueued successfully, the function will return -1. When compiled as a non-blocking function, this function will return 0 if the operation is proceeding correctly but has not yet completed. The application must continue to call this function, with the same parameters, until a non-zero value is returned. A value of -1 indicates that all printer instructions have been enqueued successfully. Any other value is an error code, and the state machine will be set back to the beginning state.

Preconditions

None

Parameters
Parameters | Description
BYTE address | USB address of the printer.
USB_PRINT_SCREEN_INFO *printScreenInfo | Information about the screen area to print, how to interpret the screen image, and how and where to print the image. Note that the width and height members of the structure do not need to be filled in by the application.
Return Values
Return Values | Description
0 | Non-blocking configuration only. Image output is not yet complete, but is proceeding normally.
(-1) | Image output was completed successfully.
other | Printing was aborted due to an error. See the return values for USBHostPrinterCommand(). Note that the return code USB_PRINTER_SUCCESS will not be returned. Instead, (-1) will be returned upon successful completion.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > PrintScreen Function


USBHostPrinterCommand Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterCommand Function
C
BYTE USBHostPrinterCommand(
    BYTE deviceAddress,
    USB_PRINTER_COMMAND command,
    USB_DATA_POINTER data,
    DWORD size,
    BYTE flags
);
Description

This is the primary user interface function for the printer client driver. It is used to issue all printer commands. Each generic printer command is translated to the appropriate command for the supported language and is enqueued for transfer to the printer. Before calling this routine, it is recommended to call the function USBHostPrinterCommandReady() to determine if there is space available in the printer's output queue.

Preconditions

None

Parameters
Parameters
Description
BYTE address
Device's address on the bus
USB_PRINTER_COMMAND command
Command to execute. See the enumeration USB_PRINTER_COMMAND for the list of valid commands and their requirements.
USB_DATA_POINTER data
Pointer to the required data. Note that the caller must set transferFlags appropriately to indicate if the pointer is a RAM pointer or a ROM pointer.
DWORD size
Size of the data. For some commands, this parameter is used to hold the data itself.
BYTE transferFlags
Flags that indicate details about the transfer operation. Refer to these flags
  • USB_PRINTER_TRANSFER_COPY_DATA
  • USB_PRINTER_TRANSFER_STATIC_DATA
  • USB_PRINTER_TRANSFER_NOTIFY
  • USB_PRINTER_TRANSFER_FROM_ROM
  • USB_PRINTER_TRANSFER_FROM_RAM
Returns

See the USB_PRINTER_ERRORS enumeration. Also, refer to the printer language command handler function, such as USBHostPrinterLanguagePostScript().

Remarks

When developing new commands, keep in mind that the function USBHostPrinterCommandReady() will be used before calling this function to see if there is space available in the output transfer queue. USBHostPrinterCommandReady() will routine TRUE if a single space is available in the output queue. Therefore, each command can generate only one output transfer.

Example
Copy Code
if (USBHostPrinterCommandReady( address ))
{
    USBHostPrinterCommand( address, USB_PRINTER_JOB_START, USB_NULL, 0, 0 );
}
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterCommand Function


USBHostPrinterCommandReady Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterCommandReady Function
C
BOOL USBHostPrinterCommandReady(
    BYTE deviceAddress
);
Description

This interface is used to check if the client driver has space available to enqueue another transfer.

Preconditions

None

Parameters
Parameters | Description
deviceAddress | USB Address of the device
Return Values
Return Values | Description
TRUE | The printer client driver has room for at least one more transfer request, or the device is not attached. The latter allows this routine to be called without generating an infinite loop if the device detaches.
FALSE | The transfer queue is full.
Remarks

Use the definitions USB_DATA_POINTER_RAM() and USB_DATA_POINTER_ROM() to cast data pointers. For example:

Copy Code
    USBHostPrinterCommand( address, USB_PRINTER_TEXT, USB_DATA_POINTER_RAM(buffer), strlen(buffer), 0 );

This routine will return TRUE if a single transfer can be enqueued. Since this routine is the check to see if USBHostPrinterCommand() can be called, every command can generate at most one transfer.

Example
Copy Code
if (USBHostPrinterCommandReady( address ))
{
    USBHostPrinterCommand( address, USB_PRINTER_JOB_START, USB_NULL, 0, 0 );
}
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterCommandReady Function


USBHostPrinterCommandWithReadyWait Macro

Contents | Index | Home
Previous | Up | Next
USBHostPrinterCommandWithReadyWait Macro
C
#define USBHostPrinterCommandWithReadyWait( returnCode, deviceAddress, command, data, size, flags ) \
        {                                                                                               \
            while (!USBHostPrinterCommandReady( deviceAddress )) USBTasks();                            \
            *(returnCode) = USBHostPrinterCommand( deviceAddress, command, data, size, flags );         \
        }
Description

This function is intended to be a short-cut to perform blocking calls to USBHostPrinterCommand(). While there is no space available in the printer queue (USBHostPrinterCommandReady() returns FALSE), USBTasks() is called. When space becomes available, USBHostPrinterCommand() is called. The return value from USBHostPrinterCommand() is returned in the returnCode parameter.

Preconditions

None

Parameters
Parameters
Description
BYTE address
Device's address on the bus
USB_PRINTER_COMMAND command
Command to execute. See the enumeration USB_PRINTER_COMMAND for the list of valid commands and their requirements.
USB_DATA_POINTER data
Pointer to the required data. Note that the caller must set transferFlags appropriately to indicate if the pointer is a RAM pointer or a ROM pointer.
DWORD size
Size of the data. For some commands, this parameter is used to hold the data itself.
BYTE transferFlags
Flags that indicate details about the transfer operation. Refer to these flags
  • USB_PRINTER_TRANSFER_COPY_DATA
  • USB_PRINTER_TRANSFER_STATIC_DATA
  • USB_PRINTER_TRANSFER_NOTIFY
  • USB_PRINTER_TRANSFER_FROM_ROM
  • USB_PRINTER_TRANSFER_FROM_RAM
Returns

See the USB_PRINTER_ERRORS enumeration. Also, refer to the printer language command handler function, such as USBHostPrinterLanguagePostScript().

Remarks

Use the definitions USB_DATA_POINTER_RAM() and USB_DATA_POINTER_ROM() to cast data pointers. For example:

Copy Code
    USBHostPrinterCommandWithReadyWait( &rc, address, USB_PRINTER_TEXT, USB_DATA_POINTER_RAM(buffer), strlen(buffer), 0 );

In the event that the device detaches during this routine, USBHostPrinterCommandReady() will return TRUE, and this function will return USB_PRINTER_UNKNOWN_DEVICE.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterCommandWithReadyWait Macro


USBHostPrinterDeviceDetached Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterDeviceDetached Function
C
BOOL USBHostPrinterDeviceDetached(
    BYTE deviceAddress
);
Description

This interface is used to check if the device has been detached from the bus.

Preconditions

None

Parameters
Parameters | Description
BYTE deviceAddress | USB Address of the device.
Return Values
Return Values | Description
TRUE | The device has been detached, or an invalid deviceAddress is given.
FALSE | The device is attached
Remarks

The event EVENT_PRINTER_DETACH can also be used to detect a detach.

Example
Copy Code
if (USBHostPrinterDeviceDetached( deviceAddress ))
{
    // Handle detach
}
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterDeviceDetached Function


USBHostPrinterEventHandler Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterEventHandler Function
C
BOOL USBHostPrinterEventHandler(
    BYTE address,
    USB_EVENT event,
    void * data,
    DWORD size
);
Description

This routine is called by the Host layer to notify the printer client of events that occur. If the event is recognized, it is handled and the routine returns TRUE. Otherwise, it is ignored and the routine returns FALSE.

This routine can notify the application with the following events:

  • EVENT_PRINTER_ATTACH
  • EVENT_PRINTER_DETACH
  • EVENT_PRINTER_TX_DONE
  • EVENT_PRINTER_RX_DONE
  • EVENT_PRINTER_REQUEST_DONE
  • EVENT_PRINTER_UNSUPPORTED

Preconditions

None

Parameters
Parameters | Description
BYTE address | Address of device with the event
USB_EVENT event | The bus event that occured
void *data | Pointer to event-specific data
DWORD size | Size of the event-specific data
Return Values
Return Values | Description
TRUE | The event was handled
FALSE | The event was not handled
Remarks

None

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterEventHandler Function


USBHostPrinterGetRxLength Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterGetRxLength Function
C
DWORD USBHostPrinterGetRxLength(
    BYTE deviceAddress
);
Description

This function retrieves the number of bytes copied to user's buffer by the most recent call to the USBHostPrinterRead() function.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
BYTE deviceAddress | USB Address of the device
Returns

Returns the number of bytes most recently received from the Printer device with address deviceAddress.

Remarks

None

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterGetRxLength Function


USBHostPrinterGetStatus Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterGetStatus Function
C
BYTE USBHostPrinterGetStatus(
    BYTE deviceAddress,
    BYTE * status
);
Description

This function issues the Printer class-specific Device Request to obtain the printer status. The returned status should have the following format, per the USB specification. Any deviation will be due to the specific printer implementation.

  • Bit 5 - Paper Empty; 1 = paper empty, 0 = paper not empty
  • Bit 4 - Select; 1 = selected, 0 = not selected
  • Bit 3 - Not Error; 1 = no error, 0 = error
  • All other bits are reserved.

The *status parameter is not updated until the EVENT_PRINTER_REQUEST_DONE event is thrown. Until that point the value of *status is unknown.

The *status parameter will only be updated if this function returns USB_SUCCESS. If this function returns with any other error code then the EVENT_PRINTER_REQUEST_DONE event will not be thrown and the status field will not be updated.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
deviceAddress | USB Address of the device
*status | pointer to the returned status byte
Returns

See the return values for the USBHostIssueDeviceRequest() function.

Remarks

None

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterGetStatus Function


USBHostPrinterInitialize Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterInitialize Function
C
BOOL USBHostPrinterInitialize(
    BYTE address,
    DWORD flags,
    BYTE clientDriverID
);
Description

This routine is a call out from the USB Embedded Host layer to the USB printer client driver. It is called when a "printer" device has been connected to the host. Its purpose is to initialize and activate the USB Printer client driver.

Preconditions

The device has been configured.

Parameters
Parameters | Description
BYTE address | Device's address on the bus
DWORD flags | Initialization flags
BYTE clientDriverID | Client driver identification for device requests
Return Values
Return Values | Description
TRUE | Initialization was successful
FALSE | Initialization failed
Remarks

Multiple client drivers may be used in a single application. The USB Embedded Host layer will call the initialize routine required for the attached device.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterInitialize Function


USBHostPrinterLanguageESCPOS Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterLanguageESCPOS Function
C
BYTE USBHostPrinterLanguageESCPOS(
    BYTE address,
    USB_PRINTER_COMMAND command,
    USB_DATA_POINTER data,
    DWORD size,
    BYTE transferFlags
);
Description

This function executes printer commands for an ESC/POS printer. When the application issues a printer command, the printer client driver determines what language to use to communicate with the printer, and transfers the command to that language support routine. As much as possible, commands are designed to produce the same output regardless of what printer language is used.

Not all printer commands support data from both RAM and ROM. Unless otherwise noted, the data pointer is assumed to point to RAM, regardless of the value of transferFlags. Refer to the specific command to see if ROM data is supported.

Preconditions

None

Parameters
Parameters
Description
BYTE address
Device's address on the bus
USB_PRINTER_COMMAND command
Command to execute. See the enumeration USB_PRINTER_COMMAND for the list of valid commands and their requirements.
USB_DATA_POINTER data
Pointer to the required data. Note that the caller must set transferFlags appropriately to indicate if the pointer is a RAM pointer or a ROM pointer.
DWORD size
Size of the data. For some commands, this parameter is used to hold the data itself.
BYTE transferFlags
Flags that indicate details about the transfer operation. Refer to these flags
  • USB_PRINTER_TRANSFER_COPY_DATA
  • USB_PRINTER_TRANSFER_STATIC_DATA
  • USB_PRINTER_TRANSFER_NOTIFY
  • USB_PRINTER_TRANSFER_FROM_ROM
  • USB_PRINTER_TRANSFER_FROM_RAM
Return Values
Return Values | Description
USB_PRINTER_SUCCESS | The command was executed successfully.
USB_PRINTER_UNKNOWN_DEVICE | A printer with the indicated address is not attached
USB_PRINTER_TOO_MANY_DEVICES | The printer status array does not have space for another printer.
USB_PRINTER_OUT_OF_MEMORY | Not enough available heap space to execute the command.
other | See possible return codes from the function USBHostPrinterWrite().
Remarks

When developing new commands, keep in mind that the function USBHostPrinterCommandReady() will be used before calling this function to see if there is space available in the output transfer queue. USBHostPrinterCommandReady() will routine TRUE if a single space is available in the output queue. Therefore, each command can generate only one output transfer.

Multiple printer languages may be used in a single application. The USB Embedded Host Printer Client Driver will call the routine required for the attached device.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterLanguageESCPOS Function


USBHostPrinterLanguageESCPOSIsSupported Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterLanguageESCPOSIsSupported Function
C
BOOL USBHostPrinterLanguageESCPOSIsSupported(
    char * deviceID,
    USB_PRINTER_FUNCTION_SUPPORT * support
);
Description

This function determines if the printer with the given device ID string supports the ESC/POS printer language.

Preconditions

None

Parameters
Parameters | Description
char *deviceID | Pointer to the "COMMAND SET:" portion of the device ID string of the attached printer.
USB_PRINTER_FUNCTION_SUPPORT *support | Pointer to returned information about what types of functions this printer supports.
Return Values
Return Values | Description
TRUE | The printer supports ESC/POS.
FALSE | The printer does not support ESC/POS.
Remarks

The caller must first locate the "COMMAND SET:" section of the device ID string. To ensure that only the "COMMAND SET:" section of the device ID string is checked, the ";" at the end of the section should be temporarily replaced with a NULL. Otherwise, this function may find the printer language string in the comments or other section, and incorrectly indicate that the printer supports the language.

Device ID strings are case sensitive.

See the file header comments for this file (usb_host_printer_esc_pos.h) for cautions regarding dynamic printer language selection with POS printers.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterLanguageESCPOSIsSupported Function


USBHostPrinterLanguagePCL5 Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterLanguagePCL5 Function
C
BYTE USBHostPrinterLanguagePCL5(
    BYTE address,
    USB_PRINTER_COMMAND command,
    USB_DATA_POINTER data,
    DWORD size,
    BYTE transferFlags
);
Description

This function executes printer commands for a PCL 5 printer. When the application issues a printer command, the printer client driver determines what language to use to communicate with the printer, and transfers the command to that language support routine. As much as possible, commands are designed to produce the same output regardless of what printer language is used.

Not all printer commands support data from both RAM and ROM. Unless otherwise noted, the data pointer is assumed to point to RAM, regardless of the value of transferFlags. Refer to the specific command to see if ROM data is supported.

Preconditions

None

Parameters
Parameters
Description
BYTE address
Device's address on the bus
USB_PRINTER_COMMAND command
Command to execute. See the enumeration USB_PRINTER_COMMAND for the list of valid commands and their requirements.
USB_DATA_POINTER data
Pointer to the required data. Note that the caller must set transferFlags appropriately to indicate if the pointer is a RAM pointer or a ROM pointer.
DWORD size
Size of the data. For some commands, this parameter is used to hold the data itself.
BYTE transferFlags
Flags that indicate details about the transfer operation. Refer to these flags
  • USB_PRINTER_TRANSFER_COPY_DATA
  • USB_PRINTER_TRANSFER_STATIC_DATA
  • USB_PRINTER_TRANSFER_NOTIFY
  • USB_PRINTER_TRANSFER_FROM_ROM
  • USB_PRINTER_TRANSFER_FROM_RAM
Return Values
Return Values | Description
USB_PRINTER_SUCCESS | The command was executed successfully.
USB_PRINTER_UNKNOWN_DEVICE | A printer with the indicated address is not attached
USB_PRINTER_TOO_MANY_DEVICES | The printer status array does not have space for another printer.
USB_PRINTER_OUT_OF_MEMORY | Not enough available heap space to execute the command.
other | See possible return codes from the function USBHostPrinterWrite().
Remarks

When developing new commands, keep in mind that the function USBHostPrinterCommandReady() will be used before calling this function to see if there is space available in the output transfer queue. USBHostPrinterCommandReady() will routine TRUE if a single space is available in the output queue. Therefore, each command can generate only one output transfer.

Multiple printer languages may be used in a single application. The USB Embedded Host Printer Client Driver will call the routine required for the attached device.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterLanguagePCL5 Function


USBHostPrinterLanguagePCL5IsSupported Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterLanguagePCL5IsSupported Function
C
BOOL USBHostPrinterLanguagePCL5IsSupported(
    char * deviceID,
    USB_PRINTER_FUNCTION_SUPPORT * support
);
Description

This function determines if the printer with the given device ID string supports the PCL 5 printer language.

Unfortunately, printer language support is not always advertised correctly by the printer. Some printers advertise only PCL 6 support when they also support PCL 5. Therefore, this routine will return TRUE if any PCL language support is advertised. It is therefore highly recommended to test the target application with the specific printer(s) that will be utilized.

Preconditions

None

Parameters
Parameters | Description
char *deviceID | Pointer to the "COMMAND SET:" portion of the device ID string of the attached printer.
USB_PRINTER_FUNCTION_SUPPORT *support | Pointer to returned information about what types of functions this printer supports.
Return Values
Return Values | Description
TRUE | The printer supports PCL 5.
FALSE | The printer does not support PCL 5.
Remarks

The caller must first locate the "COMMAND SET:" section of the device ID string. To ensure that only the "COMMAND SET:" section of the device ID string is checked, the ";" at the end of the section should be temporarily replaced with a NULL. Otherwise, this function may find the printer language string in the comments or other section, and incorrectly indicate that the printer supports the language.

Device ID strings are case sensitive.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterLanguagePCL5IsSupported Function


USBHostPrinterLanguagePostScript Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterLanguagePostScript Function
C
BYTE USBHostPrinterLanguagePostScript(
    BYTE address,
    USB_PRINTER_COMMAND command,
    USB_DATA_POINTER data,
    DWORD size,
    BYTE transferFlags
);
Description

This function executes printer commands for a PostScript printer. When the application issues a printer command, the printer client driver determines what language to use to communicate with the printer, and transfers the command to that language support routine. As much as possible, commands are designed to produce the same output regardless of what printer language is used.

Not all printer commands support data from both RAM and ROM. Unless otherwise noted, the data pointer is assumed to point to RAM, regardless of the value of transferFlags. Refer to the specific command to see if ROM data is supported.

Preconditions

None

Parameters
Parameters
Description
BYTE address
Device's address on the bus
USB_PRINTER_COMMAND command
Command to execute. See the enumeration USB_PRINTER_COMMAND for the list of valid commands and their requirements.
USB_DATA_POINTER data
Pointer to the required data. Note that the caller must set transferFlags appropriately to indicate if the pointer is a RAM pointer or a ROM pointer.
DWORD size
Size of the data. For some commands, this parameter is used to hold the data itself.
BYTE transferFlags
Flags that indicate details about the transfer operation. Refer to these flags
  • USB_PRINTER_TRANSFER_COPY_DATA
  • USB_PRINTER_TRANSFER_STATIC_DATA
  • USB_PRINTER_TRANSFER_NOTIFY
  • USB_PRINTER_TRANSFER_FROM_ROM
  • USB_PRINTER_TRANSFER_FROM_RAM
Return Values
Return Values | Description
USB_PRINTER_SUCCESS | The command was executed successfully.
USB_PRINTER_UNKNOWN_DEVICE | A printer with the indicated address is not attached
USB_PRINTER_TOO_MANY_DEVICES | The printer status array does not have space for another printer.
USB_PRINTER_OUT_OF_MEMORY | Not enough available heap space to execute the command.
other | See possible return codes from the function USBHostPrinterWrite().
Remarks

When developing new commands, keep in mind that the function USBHostPrinterCommandReady() will be used before calling this function to see if there is space available in the output transfer queue. USBHostPrinterCommandReady() will routine TRUE if a single space is available in the output queue. Therefore, each command can generate only one output transfer.

Multiple printer languages may be used in a single application. The USB Embedded Host Printer Client Driver will call the routine required for the attached device.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterLanguagePostScript Function


USBHostPrinterLanguagePostScriptIsSupported Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterLanguagePostScriptIsSupported Function
C
BOOL USBHostPrinterLanguagePostScriptIsSupported(
    char * deviceID,
    USB_PRINTER_FUNCTION_SUPPORT * support
);
Description

This function determines if the printer with the given device ID string supports the PostScript printer language.

Preconditions

None

Parameters
Parameters | Description
char *deviceID | Pointer to the "COMMAND SET:" portion of the device ID string of the attached printer.
USB_PRINTER_FUNCTION_SUPPORT *support | Pointer to returned information about what types of functions this printer supports.
Return Values
Return Values | Description
TRUE | The printer supports PostScript.
FALSE | The printer does not support PostScript.
Remarks

The caller must first locate the "COMMAND SET:" section of the device ID string. To ensure that only the "COMMAND SET:" section of the device ID string is checked, the ";" at the end of the section should be temporarily replaced with a NULL. Otherwise, this function may find the printer language string in the comments or other section, and incorrectly indicate that the printer supports the language.

Device ID strings are case sensitive.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterLanguagePostScriptIsSupported Function


USBHostPrinterPOSImageDataFormat Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterPOSImageDataFormat Function
C
USB_DATA_POINTER USBHostPrinterPOSImageDataFormat(
    USB_DATA_POINTER image,
    BYTE imageLocation,
    WORD imageHeight,
    WORD imageWidth,
    WORD * currentRow,
    BYTE byteDepth,
    BYTE * imageData
);
Description

This function formats data for a bitmapped image into the format required for sending to a POS printer. Bitmapped images are stored one row of pixels at a time. Suppose we have an image with vertical black bars, eight pixels wide and eight pixels deep. The image would appear as the following pixels, where 0 indicates a black dot and 1 indicates a white dot:

Copy Code
0 1 0 1 0 1 0 1
0 1 0 1 0 1 0 1
0 1 0 1 0 1 0 1
0 1 0 1 0 1 0 1
0 1 0 1 0 1 0 1
0 1 0 1 0 1 0 1
0 1 0 1 0 1 0 1
0 1 0 1 0 1 0 1

The stored bitmap of the data would contain the data bytes, where each byte is one row of data:

Copy Code
0x55 0x55 0x55 0x55 0x55 0x55 0x55 0x55

When printing to a full sheet printer, eight separate USB_PRINTER_IMAGE_DATA_HEADER / USB_PRINTER_IMAGE_DATA command combinations are required to print this image.

POS printers, however, require image data formated either 8 dots or 24 dots deep, depending on the desired (and supported) vertical print density. For a POS printer performing an 8-dot vertical density print, the data needs to be in this format:

Copy Code
0x00 0xFF 0x00 0xFF 0x00 0xFF 0x00 0xFF

When printing to a POS printer, only one USB_PRINTER_IMAGE_DATA_HEADER / USB_PRINTER_IMAGE_DATA command combination is required to print this image.

This function supports 8-dot and 24-dot vertical densities by specifying the byteDepth parameter as either 1 (8-dot) or 3 (24-dot).

Preconditions

None

Returns

The function returns a pointer to the next byte of image data.

Remarks

This routine currently does not support 36-dot density printing. Since the output for 36-dot vertical density is identical to 24-dot vertical density, 24-dot vertical density should be used instead.

This routine does not yet support reading from external memory.

Example

The following example code will send a complete bitmapped image to a POS printer.

Copy Code
    WORD                    currentRow;
    BYTE                    depthBytes;
    BYTE                    *imageDataPOS;
    USB_PRINTER_IMAGE_INFO  imageInfo;
    BYTE                    returnCode;
    #if defined (__C30__)
        BYTE __prog__       *ptr;
        ptr = (BYTE __prog__ *)logoMCHP.address;
    #elif defined (__PIC32MX__)
        const BYTE          *ptr;
        ptr = (const BYTE *)logoMCHP.address;
    #endif

    imageInfo.densityVertical   = 24;   // 24-dot density
    imageInfo.densityHorizontal = 2;    // Double density

    // Extract the image height and width
    imageInfo.width    = ((WORD)ptr[5] << 8) + ptr[4];
    imageInfo.height   = ((WORD)ptr[3] << 8) + ptr[2];

    depthBytes         = imageInfo.densityVertical / 8;
    imageDataPOS       = (BYTE *)malloc( imageInfo.width *
                                   depthBytes );

    if (imageDataPOS == NULL)
    {
        // Error - not enough heap space
    }

    USBHostPrinterCommandWithReadyWait( &returnCode,
          printerInfo.deviceAddress, USB_PRINTER_IMAGE_START,
          USB_DATA_POINTER_RAM(&imageInfo),
          sizeof(USB_PRINTER_IMAGE_INFO ),
          0 );

    ptr += 10; // skip the header info

    currentRow = 0;
    while (currentRow < imageInfo.height)
    {
        USBHostPrinterCommandWithReadyWait( &returnCode,
          printerInfo.deviceAddress,
          USB_PRINTER_IMAGE_DATA_HEADER, USB_NULL,
          imageInfo.width, 0 );

        ptr = USBHostPrinterPOSImageDataFormat(
          USB_DATA_POINTER_ROM(ptr),
          USB_PRINTER_TRANSFER_FROM_ROM, imageInfo.height,
          imageInfo.width, &currentRow, depthBytes,
          imageDataPOS ).pointerROM;

        USBHostPrinterCommandWithReadyWait( &returnCode,
          printerInfo.deviceAddress, USB_PRINTER_IMAGE_DATA,
          USB_DATA_POINTER_RAM(imageDataPOS), imageInfo.width,
          USB_PRINTER_TRANSFER_COPY_DATA);
    }

    free( imageDataPOS );

    USBHostPrinterCommandWithReadyWait( &returnCode,
          printerInfo.deviceAddress, USB_PRINTER_IMAGE_STOP,
          USB_NULL, 0, 0 );
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterPOSImageDataFormat Function


USBHostPrinterPosition Macro

Contents | Index | Home
Previous | Up | Next
USBHostPrinterPosition Macro
C
#define USBHostPrinterPosition( X, Y ) (((DWORD)(X) << 16) | ((DWORD)(Y) & 0xFFFF))
Description

This function is used to simplify the call to the printer command USB_PRINTER_SET_POSITION by generating the value needed for the specified (X,Y) coordinate. The USB_PRINTER_SET_POSITION command requires that the (X,Y) coordinate be passed in the (DWORD) size parameter of the USBHostPrinterCommand() function. This function takes the specified coordinate and packs it in the DWORD as required.

Preconditions

None

Parameters
Parameters | Description
X | X coordinate (horizontal)
Y | Y coordinate (vertical)
Returns

DWORD value that can be used in the USBHostPrinterCommand() function call with the command USB_PRINTER_SET_POSITION.

Remarks

None

Example
Copy Code
USBHostPrinterCommand( printer, USB_PRINTER_SET_POSITION, USB_NULL,
                USBHostPrinterPosition( 100, 100 ), 0 );
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterPosition Macro


USBHostPrinterPositionRelative Macro

Contents | Index | Home
Previous | Up | Next
USBHostPrinterPositionRelative Macro
C
#define USBHostPrinterPositionRelative( dX, dY ) (((DWORD)(dX) << 16) | ((DWORD)(dY) & 0xFFFF))
Description

This function is used to simplify the call to some of the printer graphics commands by generating the value needed for the specified change in X and change in Y coordinates. The USB_PRINTER_GRAPHICS_MOVE_RELATIVE and the USB_PRINTER_GRAPHICS_LINE_TO_RELATIVE commands requires that the change in the (X,Y) coordinates be passed in the (DWORD) size parameter of the USBHostPrinterCommand() function. This function takes the specified coordinate changes and packs them in the DWORD as required.

Preconditions

None

Parameters
Parameters | Description
dX | Change in the X coordinate (horizontal)
dY | Change in the Y coordinate (vertical)
Returns

DWORD value that can be used in the USBHostPrinterCommand() function call with the commands USB_PRINTER_GRAPHICS_MOVE_RELATIVE and USB_PRINTER_GRAPHICS_LINE_TO_RELATIVE.

Remarks

None

Example
Copy Code
USBHostPrinterCommand( printer, USB_PRINTER_GRAPHICS_LINE_TO_RELATIVE, USB_NULL,
                USBHostPrinterPositionRelative( 0, -100 ), 0 );
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterPositionRelative Macro


USBHostPrinterRead Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterRead Function
C
BYTE USBHostPrinterRead(
    BYTE deviceAddress,
    void * buffer,
    DWORD length,
    BYTE transferFlags
);
Description

Use this routine to receive from the device and store it into memory.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
deviceAddress | USB Address of the device.
buffer | Pointer to the data buffer
length | Number of bytes to be transferred
transferFlags | Flags for how to perform the operation
Return Values
Return Values | Description
USB_SUCCESS | The Read was started successfully
(USB error code) | The Read was not started. See USBHostRead() for a list of errors.
Remarks

None

Example
Copy Code
if (!USBHostPrinterRxIsBusy( deviceAddress ))
{
    USBHostPrinterRead( deviceAddress, &buffer, sizeof(buffer), 0 );
}
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterRead Function


USBHostPrinterReset Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterReset Function
C
BYTE USBHostPrinterReset(
    BYTE deviceAddress
);
Description

This function issues the Printer class-specific Device Request to perform a soft reset.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
BYTE deviceAddress | USB Address of the device
Returns

See the return values for the USBHostIssueDeviceRequest() function.

Remarks

Not all printers support this command.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterReset Function


USBHostPrinterRxIsBusy Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterRxIsBusy Function
C
BOOL USBHostPrinterRxIsBusy(
    BYTE deviceAddress
);
Description

This interface is used to check if the client driver is currently busy receiving data from the device.

Preconditions

None

Parameters
Parameters | Description
deviceAddress | USB Address of the device
Return Values
Return Values | Description
TRUE | The device is receiving data or an invalid deviceAddress is given.
FALSE | The device is not receiving data
Remarks

None

Example
Copy Code
if (!USBHostPrinterRxIsBusy( deviceAddress ))
{
    USBHostPrinterRead( deviceAddress, &buffer, sizeof( buffer ) );
}
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterRxIsBusy Function


USBHostPrinterWrite Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterWrite Function
C
BYTE USBHostPrinterWrite(
    BYTE deviceAddress,
    void * buffer,
    DWORD length,
    BYTE flags
);
Description

Use this routine to transmit data from memory to the device. This routine will not usually be called by the application directly. The application will use the USBHostPrinterCommand() function, which will call the appropriate printer language support function, which will utilize this routine.

Preconditions

The device must be connected and enumerated.

Parameters
Parameters | Description
BYTE deviceAddress | USB Address of the device.
void *buffer | Pointer to the data buffer
DWORD length | Number of bytes to be transferred
BYTE transferFlags | Flags for how to perform the operation
Return Values
Return Values | Description
USB_SUCCESS | The Write was started successfully.
USB_PRINTER_UNKNOWN_DEVICE | Device not found or has not been initialized.
USB_PRINTER_BUSY | The printer's output queue is full.
(USB error code) | The Write was not started. See USBHostWrite() for a list of errors.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterWrite Function


USBHostPrinterWriteComplete Function

Contents | Index | Home
Previous | Up | Next
USBHostPrinterWriteComplete Function
C
BOOL USBHostPrinterWriteComplete(
    BYTE deviceAddress
);
Description

This interface is used to check if the client driver is currently transmitting data to the printer, or if it is between transfers but still has transfers queued.

Preconditions

None

Parameters
Parameters | Description
deviceAddress | USB Address of the device
Return Values
Return Values | Description
TRUE | The device is done transmitting data or an invalid deviceAddress is given.
FALSE | The device is transmitting data or has a transfer in the queue.
Remarks

None

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Interface Routines > USBHostPrinterWriteComplete Function


Data Types and Constants

Contents | Index | Home
Previous | Up | Next
Data Types and Constants
Enumerations
Name | Description
USB_PRINTER_COMMAND | USB Printer Client Driver Commands The main interface to the USB Printer Client Driver is through the function USBHostPrinterCommand(). These are the commands that can be passed to that function.
USB_PRINTER_ERRORS | Printer Errors These are errors that can be returned by the printer client driver. Note that USB Embedded Host errors can also be returned.
USB_PRINTER_FONTS | Printer Fonts This enumeration defines the various printer fonts. If new fonts are added, they must be added at the end of the list, just before the USB_PRINTER_FONT_MAX_FONT definition, as the printer language support files may utilize them for indexing purposes.
USB_PRINTER_FONTS_POS | POS Printer Fonts This enumeration defines the various printer fonts used by POS printers. If new fonts are added, they must be added at the end of the list, just before the USB_PRINTER_FONT_POS_MAX_FONT definition, as the printer language support files may utilize them for indexing purposes.
USB_PRINTER_POS_BARCODE_FORMAT | Bar Code Formats These are the bar code formats for printing bar codes on POS printers. They are used in conjuction with the USB_PRINTER_POS_BARCODE command (USB_PRINTER_COMMAND). Bar code information is passed using the sBarCode structure within the USB_PRINTER_GRAPHICS_PARAMETERS union. The exact values to send for each bar code type can vary for the particular POS printer, and not all printers support all bar code types. Be sure to test the output on the target printer, and adjust the values specified in usb_host_printer_esc_pos.c if necessary. Refer to the printer's technical documentation for the required values. Do not alter this... more
Macros
Name | Description
_USB_HOST_PRINTER_PRIMITIVES_H | This is macro _USB_HOST_PRINTER_PRIMITIVES_H.
BARCODE_CODE128_CODESET_A_CHAR | For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the second data byte of the bar code data to specify character code set CODE A. This code set should be used if control characters (0x00-0x1F) are included in the data.
BARCODE_CODE128_CODESET_A_STRING | For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the second data byte of the bar code data to specify character code set CODE A. This code set should be used if control characters (0x00-0x1F) are included in the data.
BARCODE_CODE128_CODESET_B_CHAR | For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the second data byte of the bar code data to specify character code set CODE B. This code set should be used if lower case letters and higher ASCII characters (0x60-0x7F) are included in the data.
BARCODE_CODE128_CODESET_B_STRING | For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the second data byte of the bar code data to specify character code set CODE B. This code set should be used if lower case letters and higher ASCII characters (0x60-0x7F) are included in the data.
BARCODE_CODE128_CODESET_C_CHAR | For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the second data byte of the bar code data to specify character code set CODE C. This code set can be used only if the data values are between 0 and 99 (0x00-0x63).
BARCODE_CODE128_CODESET_C_STRING | For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the second data byte of the bar code data to specify character code set CODE C. This code set can be used only if the data values are between 0 and 99 (0x00-0x63).
BARCODE_CODE128_CODESET_CHAR | For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the first data byte of the bar code data, which begins the character code specification. The next byte must be 'A', 'B', or 'C'.
BARCODE_CODE128_CODESET_STRING | For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the first data byte of the bar code data, which begins the character code specification. The next byte must be 'A', 'B', or 'C'.
BARCODE_TEXT_12x24 | For use with POS printers. May not be valid for all printers. Print the bar code text in 12x24 dot font. Do not alter this value.
BARCODE_TEXT_18x36 | For use with POS printers. May not be valid for all printers. Print the bar code text in 18x36 dot font. Do not alter this value.
BARCODE_TEXT_ABOVE | For use with POS printers. Print readable text above the bar code. Do not alter this value.
BARCODE_TEXT_ABOVE_AND_BELOW | For use with POS printers. Print readable text above and below the bar code. Do not alter this value.
BARCODE_TEXT_BELOW | For use with POS printers. Print readable text below the bar code. Do not alter this value.
BARCODE_TEXT_OMIT | For use with POS printers. Do not print readable bar code text. Do not alter this value.
EVENT_PRINTER_ATTACH | This event indicates that a Printer device has been attached. When USB_HOST_APP_EVENT_HANDLER is called with this event, the *data parameter points to a structure of the type USB_PRINTER_DEVICE_ID, which provides important information about the attached printer. The size parameter is the size of this structure.
EVENT_PRINTER_DETACH | This event indicates that the specified device has been detached from the USB. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to a BYTE that contains the device address, and size is the size of a BYTE.
EVENT_PRINTER_OFFSET | This is an optional offset for the values of the generated events. If necessary, the application can use a non-zero offset for the generic events to resolve conflicts in event number.
EVENT_PRINTER_REQUEST_DONE | This event indicates that the printer request has completed. These requests occur on endpoint 0 and include getting the printer status and performing a soft reset.
EVENT_PRINTER_REQUEST_ERROR | This event indicates that a bus error occurred while trying to perform a device request. The error code is returned in the size parameter. The data parameter is returned as NULL.
EVENT_PRINTER_RX_DONE | This event indicates that a previous read request has completed. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to the receive buffer, and size is the actual number of bytes read from the device.
EVENT_PRINTER_RX_ERROR | This event indicates that a bus error occurred while trying to perform a read. The error code is returned in the size parameter. The data parameter is returned as NULL.
EVENT_PRINTER_TX_DONE | This event indicates that a previous write request has completed. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to the buffer that completed transmission, and size is the actual number of bytes that were written to the device.
EVENT_PRINTER_TX_ERROR | This event indicates that a bus error occurred while trying to perform a write. The error code is returned in the size parameter. The data parameter is returned as NULL.
EVENT_PRINTER_UNSUPPORTED | This event indicates that a printer has attached for which we do not have printer language support. Therefore, we cannot talk to this printer. This event can also occur if there is not enough dynamic memory available to read the device ID string.
LANGUAGE_ID_STRING_ESCPOS | This is the string that the printer language support determination routine will look for to determine if the printer supports this printer language. This string is case sensive. See the function USBHostPrinterLanguageESCPOSIsSupported() for more information about using or changing this string. Dynamic language determination is not recommended when using POS printers.
LANGUAGE_ID_STRING_PCL | This is the string that the printer language support determination routine will look for to determine if the printer supports this printer language. This string is case sensive. Some printers that report only PCL 6 support also support PCL 5. So it is recommended to use "PCL" as the search string, rather than "PCL 5", and verify that the correct output is produced by the target printer.
LANGUAGE_ID_STRING_POSTSCRIPT | This is the string that the printer language support determination routine will look for to determine if the printer supports this printer language. This string is case sensive.
LANGUAGE_SUPPORT_FLAGS_ESCPOS | These are the support flags that are set for this language.
LANGUAGE_SUPPORT_FLAGS_PCL3 | These are the support flags that are set for the PCL 3 version of this language.
LANGUAGE_SUPPORT_FLAGS_PCL5 | These are the support flags that are set for the PCL 5 version of this language.
LANGUAGE_SUPPORT_FLAGS_POSTSCRIPT | These are the support flags that are set for this language.
PRINTER_COLOR_BLACK | Indicates a black line for drawing graphics objects.
PRINTER_COLOR_WHITE | Indicates a white line for drawing graphics objects.
PRINTER_DEVICE_REQUEST_GET_DEVICE_ID | bRequest value for the GET_DEVICE_ID USB class-specific request.
PRINTER_DEVICE_REQUEST_GET_PORT_STATUS | bRequest value for the GET_PORT_STATUS USB class-specific request.
PRINTER_DEVICE_REQUEST_SOFT_RESET | bRequest value for the SOFT_RESET USB class-specific request.
PRINTER_FILL_CROSS_HATCHED | Indicates a cross-hatched fill for graphics objects. Requires a specified line spacing and angle.
PRINTER_FILL_HATCHED | Indicates a hatched fill for graphics objects. Requires a specified line spacing and angle.
PRINTER_FILL_SHADED | Indicates a shaded fill for filled graphics objects. Requires a specified fill percentage.
PRINTER_FILL_SOLID | Indicates a solid color fill for filled graphics objects.
PRINTER_LINE_END_BUTT | Drawn lines will have a butt end.
PRINTER_LINE_END_ROUND | Drawn lines will have a round end.
PRINTER_LINE_END_SQUARE | Drawn lines will have a square end.
PRINTER_LINE_JOIN_BEVEL | Drawn lines will be joined with a bevel.
PRINTER_LINE_JOIN_MITER | Drawn lines will be joined with a miter.
PRINTER_LINE_JOIN_ROUND | Drawn lines will be joined with a round.
PRINTER_LINE_TYPE_DASHED | Indicates a dashed line for drawing graphics objects.
PRINTER_LINE_TYPE_DOTTED | Indicates a dotted line for drawing graphics objects.
PRINTER_LINE_TYPE_SOLID | Indicates a solid line for drawing graphics objects.
PRINTER_LINE_WIDTH_NORMAL | Indicates a normal width line for drawing graphics objects.
PRINTER_LINE_WIDTH_THICK | Indicates a thick line for drawing graphics objects.
PRINTER_PAGE_LANDSCAPE_HEIGHT | The height of the page in points when in landscape mode.
PRINTER_PAGE_LANDSCAPE_WIDTH | The width of the page in points when in landscape mode.
PRINTER_PAGE_PORTRAIT_HEIGHT | The height of the page in points when in portrait mode.
PRINTER_PAGE_PORTRAIT_WIDTH | The width of the page in points when in portrait mode.
PRINTER_POS_BOTTOM_TO_TOP | POS print direction bottom to top, starting at the bottom left corner.
PRINTER_POS_DENSITY_HORIZONTAL_DOUBLE | Image print with double horizontal density.
PRINTER_POS_DENSITY_HORIZONTAL_SINGLE | Image print with single horizontal density.
PRINTER_POS_DENSITY_VERTICAL_24 | Image print with 24-dot vertical density.
PRINTER_POS_DENSITY_VERTICAL_8 | Image print with 8-dot vertical density.
PRINTER_POS_LEFT_TO_RIGHT | POS print direction left to right, starting at the top left corner.
PRINTER_POS_RIGHT_TO_LEFT | POS print direction right to left, startin at the bottom right corner.
PRINTER_POS_TOP_TO_BOTTOM | POS print direction top to bottom, starting at the top right corner.
USB_DATA_POINTER_RAM | Use this definition to cast a pointer being passed to the function USBHostPrinterCommand() that points to data in RAM.
USB_DATA_POINTER_ROM | Use this definition to cast a pointer being passed to the function USBHostPrinterCommand() that points to data in ROM.
USB_MAX_PRINTER_DEVICES | Max Number of Supported Devices This value represents the maximum number of attached devices this class driver can support. If the user does not define a value, it will be set to 1. Currently this must be set to 1, due to limitations in the USB Host layer.
USB_NULL | Use this definition to pass a NULL pointer to the function USBHostPrinterCommand().
USB_PRINTER_FUNCTION_SUPPORT_POS | Constant to use to set the supportsPOS member of the USB_PRINTER_FUNCTION_SUPPORT union.
USB_PRINTER_FUNCTION_SUPPORT_VECTOR_GRAPHICS | Constant to use to set the supportsVectorGraphics member of the USB_PRINTER_FUNCTION_SUPPORT union.
USB_PRINTER_TRANSFER_COPY_DATA | This flag indicates that the printer client driver should make a copy of the data passed to the command. This allows the application to reuse the data storage immediately instead of waiting until the transfer is sent to the printer. The client driver will allocate space in the heap for the data copy. If there is not enough available memory, the command will terminate with a USB_PRINTER_OUT_OF_MEMORY error. Otherwise, the original data will be copied to the temporary data space. This temporary data will be freed upon completion, regardless of whether or not the command was performed successfully. NOTE: If... more
USB_PRINTER_TRANSFER_FROM_RAM | This flag indicates that the source of the command data is in RAM. The application can then choose whether or not to have the printer client driver make a copy of the data.
USB_PRINTER_TRANSFER_FROM_ROM | This flag indicates that the source of the command data is in ROM. The data will be copied to RAM, since the USB Host layer cannot read data from ROM. If there is not enough available heap space to make a copy of the data, the command will fail. If using this flag, do not set the USB_PRINTER_TRANSFER_COPY_DATA flag.
USB_PRINTER_TRANSFER_NOTIFY | This flag indicates that the application layer wants to receive an event notification when the command completes.
USB_PRINTER_TRANSFER_STATIC_DATA | This flag indicates that the data will not change in the time between the printer command being issued and the data actually being sent to the printer.
USBHOSTPRINTER_SETFLAG_COPY_DATA | Use this macro to set the USB_PRINTER_TRANSFER_COPY_DATA flag in a variable.
USBHOSTPRINTER_SETFLAG_NOTIFY | Use this macro to set the USB_PRINTER_TRANSFER_NOTIFY flag in a variable.
USBHOSTPRINTER_SETFLAG_STATIC_DATA | Use this macro to clear the USB_PRINTER_TRANSFER_COPY_DATA flag in a variable.
Structures
Name | Description
_USB_PRINTER_DEVICE_ID | Printer Device ID Information This structure contains identification information about an attached device.
USB_PRINT_SCREEN_INFO | Print Screen Information This structure is designed for use when the USB Embedded Host Printer support is integrated with the graphics library. The structure contains the information needed to print a portion of the graphics screen as a bitmapped graphic image.
USB_PRINTER_DEVICE_ID | Printer Device ID Information This structure contains identification information about an attached device.
USB_PRINTER_IMAGE_INFO | Bitmapped Image Information This structure contains the information needed to print a bitmapped graphic image. When using a full sheet printer, utilize the resolution and the scale members to specify the size of the image. Some printer languages (e.g. PostScript) utilize a scale factor, while others (e.g. PCL 5) utilize a dots-per-inch resolution. Also, some printers that utilize the resolution specification support only certain values for the resolution. For maximum compatibility, specify both members of this structure. The following table shows example values that will generate similarly sized output.
USB_PRINTER_INTERFACE | USB Printer Interface Structure This structure represents the information needed to interface with a printer language. An array of these structures must be created in usb_config.c, so the USB printer client driver can determine what printer language to use to communicate with the printer.
USB_PRINTER_SPECIFIC_INTERFACE | USB Printer Specific Interface Structure This structure is used to explicitly specify what printer language to use for a particular printer, and what print functions the printer supports. It can be used when a printer supports multiple languages with one language preferred over the others. It is required for printers that do not support the GET_DEVICE_ID printer class request. These printers do not report what printer languages they support. Typically, these printers also do not report Printer Class support in their Interface Descriptors, and must be explicitly supported by their VID and PID in the TPL. This structure links the... more
Types
Name | Description
USB_PRINTER_LANGUAGE_HANDLER | This is a typedef to use when defining a printer language command handler.
USB_PRINTER_LANGUAGE_SUPPORTED | This is a typedef to use when defining a function that determines if the printer with the given "COMMAND SET:" portion of the device ID string supports the particular printer language.
Unions
Name
Description
USB_DATA_POINTER
This type is used to represent a generic RAM or ROM pointer when passed to the function USBHostPrinterCommand() or a printer language function of the type USB_PRINTER_LANGUAGE_HANDLER. Note that the caller must indicate whether the point is actually pointing to RAM or to ROM, so we can tell which pointer is valid. Not all printer commands can actually use data in ROM. Refer to the specific printer command in the USB_PRINTER_COMMAND enumeration for more information.
USB_PRINTER_FUNCTION_SUPPORT
Printer Device Function support Information
This structure contains information about the functions that the attached printer supports. See the related constants for setting these flags via the val member:
  • USB_PRINTER_FUNCTION_SUPPORT_POS
  • USB_PRINTER_FUNCTION_SUPPORT_VECTOR_GRAPHICS
USB_PRINTER_GRAPHICS_PARAMETERS
USB Printer Graphics Parameter Structures
This union can be used to declare a variable that can hold the parameters for any printer graphics or POS printer command (USB_PRINTER_COMMAND). The union allows a single variable to be declared and then reused for any printer graphics command.
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants


_USB_HOST_PRINTER_PRIMITIVES_H Macro

Contents | Index | Home
Previous | Up | Next
_USB_HOST_PRINTER_PRIMITIVES_H Macro
C
#define _USB_HOST_PRINTER_PRIMITIVES_H
Description

This is macro _USB_HOST_PRINTER_PRIMITIVES_H.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > _USB_HOST_PRINTER_PRIMITIVES_H Macro


BARCODE_CODE128_CODESET_A_CHAR Macro

Contents | Index | Home
Previous | Up | Next
BARCODE_CODE128_CODESET_A_CHAR Macro
C
#define BARCODE_CODE128_CODESET_A_CHAR 'A'
Description

For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the second data byte of the bar code data to specify character code set CODE A. This code set should be used if control characters (0x00-0x1F) are included in the data.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > BARCODE_CODE128_CODESET_A_CHAR Macro


BARCODE_CODE128_CODESET_A_STRING Macro

Contents | Index | Home
Previous | Up | Next
BARCODE_CODE128_CODESET_A_STRING Macro
C
#define BARCODE_CODE128_CODESET_A_STRING "A"
Description

For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the second data byte of the bar code data to specify character code set CODE A. This code set should be used if control characters (0x00-0x1F) are included in the data.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > BARCODE_CODE128_CODESET_A_STRING Macro


BARCODE_CODE128_CODESET_B_CHAR Macro

Contents | Index | Home
Previous | Up | Next
BARCODE_CODE128_CODESET_B_CHAR Macro
C
#define BARCODE_CODE128_CODESET_B_CHAR 'B'
Description

For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the second data byte of the bar code data to specify character code set CODE B. This code set should be used if lower case letters and higher ASCII characters (0x60-0x7F) are included in the data.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > BARCODE_CODE128_CODESET_B_CHAR Macro


BARCODE_CODE128_CODESET_B_STRING Macro

Contents | Index | Home
Previous | Up | Next
BARCODE_CODE128_CODESET_B_STRING Macro
C
#define BARCODE_CODE128_CODESET_B_STRING "B"
Description

For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the second data byte of the bar code data to specify character code set CODE B. This code set should be used if lower case letters and higher ASCII characters (0x60-0x7F) are included in the data.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > BARCODE_CODE128_CODESET_B_STRING Macro


BARCODE_CODE128_CODESET_C_CHAR Macro

Contents | Index | Home
Previous | Up | Next
BARCODE_CODE128_CODESET_C_CHAR Macro
C
#define BARCODE_CODE128_CODESET_C_CHAR 'C'
Description

For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the second data byte of the bar code data to specify character code set CODE C. This code set can be used only if the data values are between 0 and 99 (0x00-0x63).

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > BARCODE_CODE128_CODESET_C_CHAR Macro


BARCODE_CODE128_CODESET_C_STRING Macro

Contents | Index | Home
Previous | Up | Next
BARCODE_CODE128_CODESET_C_STRING Macro
C
#define BARCODE_CODE128_CODESET_C_STRING "C"
Description

For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the second data byte of the bar code data to specify character code set CODE C. This code set can be used only if the data values are between 0 and 99 (0x00-0x63).

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > BARCODE_CODE128_CODESET_C_STRING Macro


BARCODE_CODE128_CODESET_CHAR Macro

Contents | Index | Home
Previous | Up | Next
BARCODE_CODE128_CODESET_CHAR Macro
C
#define BARCODE_CODE128_CODESET_CHAR '{'
Description

For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the first data byte of the bar code data, which begins the character code specification. The next byte must be 'A', 'B', or 'C'.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > BARCODE_CODE128_CODESET_CHAR Macro


BARCODE_CODE128_CODESET_STRING Macro

Contents | Index | Home
Previous | Up | Next
BARCODE_CODE128_CODESET_STRING Macro
C
#define BARCODE_CODE128_CODESET_STRING "{"
Description

For use with POS printers that support Code128 bar codes (extended barcodes). This is the value of the first data byte of the bar code data, which begins the character code specification. The next byte must be 'A', 'B', or 'C'.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > BARCODE_CODE128_CODESET_STRING Macro


BARCODE_TEXT_12x24 Macro

Contents | Index | Home
Previous | Up | Next
BARCODE_TEXT_12x24 Macro
C
#define BARCODE_TEXT_12x24 1
Description

For use with POS printers. May not be valid for all printers. Print the bar code text in 12x24 dot font. Do not alter this value.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > BARCODE_TEXT_12x24 Macro


BARCODE_TEXT_18x36 Macro

Contents | Index | Home
Previous | Up | Next
BARCODE_TEXT_18x36 Macro
C
#define BARCODE_TEXT_18x36 0
Description

For use with POS printers. May not be valid for all printers. Print the bar code text in 18x36 dot font. Do not alter this value.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > BARCODE_TEXT_18x36 Macro


BARCODE_TEXT_ABOVE Macro

Contents | Index | Home
Previous | Up | Next
BARCODE_TEXT_ABOVE Macro
C
#define BARCODE_TEXT_ABOVE 1
Description

For use with POS printers. Print readable text above the bar code. Do not alter this value.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > BARCODE_TEXT_ABOVE Macro


BARCODE_TEXT_ABOVE_AND_BELOW Macro

Contents | Index | Home
Previous | Up | Next
BARCODE_TEXT_ABOVE_AND_BELOW Macro
C
#define BARCODE_TEXT_ABOVE_AND_BELOW 3
Description

For use with POS printers. Print readable text above and below the bar code. Do not alter this value.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > BARCODE_TEXT_ABOVE_AND_BELOW Macro


BARCODE_TEXT_BELOW Macro

Contents | Index | Home
Previous | Up | Next
BARCODE_TEXT_BELOW Macro
C
#define BARCODE_TEXT_BELOW 2
Description

For use with POS printers. Print readable text below the bar code. Do not alter this value.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > BARCODE_TEXT_BELOW Macro


BARCODE_TEXT_OMIT Macro

Contents | Index | Home
Previous | Up | Next
BARCODE_TEXT_OMIT Macro
C
#define BARCODE_TEXT_OMIT 0
Description

For use with POS printers. Do not print readable bar code text. Do not alter this value.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > BARCODE_TEXT_OMIT Macro


EVENT_PRINTER_ATTACH Macro

Contents | Index | Home
Previous | Up | Next
EVENT_PRINTER_ATTACH Macro
C
#define EVENT_PRINTER_ATTACH (EVENT_PRINTER_BASE+EVENT_PRINTER_OFFSET+0)
Description

This event indicates that a Printer device has been attached. When USB_HOST_APP_EVENT_HANDLER is called with this event, the *data parameter points to a structure of the type USB_PRINTER_DEVICE_ID, which provides important information about the attached printer. The size parameter is the size of this structure.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > EVENT_PRINTER_ATTACH Macro


EVENT_PRINTER_DETACH Macro

Contents | Index | Home
Previous | Up | Next
EVENT_PRINTER_DETACH Macro
C
#define EVENT_PRINTER_DETACH (EVENT_PRINTER_BASE+EVENT_PRINTER_OFFSET+1)
Description

This event indicates that the specified device has been detached from the USB. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to a BYTE that contains the device address, and size is the size of a BYTE.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > EVENT_PRINTER_DETACH Macro


EVENT_PRINTER_OFFSET Macro

Contents | Index | Home
Previous | Up | Next
EVENT_PRINTER_OFFSET Macro
C
#define EVENT_PRINTER_OFFSET 0
Description

This is an optional offset for the values of the generated events. If necessary, the application can use a non-zero offset for the generic events to resolve conflicts in event number.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > EVENT_PRINTER_OFFSET Macro


EVENT_PRINTER_REQUEST_DONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_PRINTER_REQUEST_DONE Macro
C
#define EVENT_PRINTER_REQUEST_DONE (EVENT_PRINTER_BASE+EVENT_PRINTER_OFFSET+4)
Description

This event indicates that the printer request has completed. These requests occur on endpoint 0 and include getting the printer status and performing a soft reset.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > EVENT_PRINTER_REQUEST_DONE Macro


EVENT_PRINTER_REQUEST_ERROR Macro

Contents | Index | Home
Previous | Up | Next
EVENT_PRINTER_REQUEST_ERROR Macro
C
#define EVENT_PRINTER_REQUEST_ERROR (EVENT_PRINTER_BASE+EVENT_PRINTER_OFFSET+7)
Description

This event indicates that a bus error occurred while trying to perform a device request. The error code is returned in the size parameter. The data parameter is returned as NULL.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > EVENT_PRINTER_REQUEST_ERROR Macro


EVENT_PRINTER_RX_DONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_PRINTER_RX_DONE Macro
C
#define EVENT_PRINTER_RX_DONE (EVENT_PRINTER_BASE+EVENT_PRINTER_OFFSET+3)
Description

This event indicates that a previous read request has completed. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to the receive buffer, and size is the actual number of bytes read from the device.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > EVENT_PRINTER_RX_DONE Macro


EVENT_PRINTER_RX_ERROR Macro

Contents | Index | Home
Previous | Up | Next
EVENT_PRINTER_RX_ERROR Macro
C
#define EVENT_PRINTER_RX_ERROR (EVENT_PRINTER_BASE+EVENT_PRINTER_OFFSET+6)
Description

This event indicates that a bus error occurred while trying to perform a read. The error code is returned in the size parameter. The data parameter is returned as NULL.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > EVENT_PRINTER_RX_ERROR Macro


EVENT_PRINTER_TX_DONE Macro

Contents | Index | Home
Previous | Up | Next
EVENT_PRINTER_TX_DONE Macro
C
#define EVENT_PRINTER_TX_DONE (EVENT_PRINTER_BASE+EVENT_PRINTER_OFFSET+2)
Description

This event indicates that a previous write request has completed. When USB_HOST_APP_EVENT_HANDLER is called with this event, *data points to the buffer that completed transmission, and size is the actual number of bytes that were written to the device.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > EVENT_PRINTER_TX_DONE Macro


EVENT_PRINTER_TX_ERROR Macro

Contents | Index | Home
Previous | Up | Next
EVENT_PRINTER_TX_ERROR Macro
C
#define EVENT_PRINTER_TX_ERROR (EVENT_PRINTER_BASE+EVENT_PRINTER_OFFSET+5)
Description

This event indicates that a bus error occurred while trying to perform a write. The error code is returned in the size parameter. The data parameter is returned as NULL.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > EVENT_PRINTER_TX_ERROR Macro


EVENT_PRINTER_UNSUPPORTED Macro

Contents | Index | Home
Previous | Up | Next
EVENT_PRINTER_UNSUPPORTED Macro
C
#define EVENT_PRINTER_UNSUPPORTED (EVENT_PRINTER_BASE+EVENT_PRINTER_OFFSET+8)
Description

This event indicates that a printer has attached for which we do not have printer language support. Therefore, we cannot talk to this printer. This event can also occur if there is not enough dynamic memory available to read the device ID string.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > EVENT_PRINTER_UNSUPPORTED Macro


LANGUAGE_ID_STRING_ESCPOS Macro

Contents | Index | Home
Previous | Up | Next
LANGUAGE_ID_STRING_ESCPOS Macro
C
#define LANGUAGE_ID_STRING_ESCPOS "ESC"
Description

This is the string that the printer language support determination routine will look for to determine if the printer supports this printer language. This string is case sensive. See the function USBHostPrinterLanguageESCPOSIsSupported() for more information about using or changing this string. Dynamic language determination is not recommended when using POS printers.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > LANGUAGE_ID_STRING_ESCPOS Macro


LANGUAGE_ID_STRING_PCL Macro

Contents | Index | Home
Previous | Up | Next
LANGUAGE_ID_STRING_PCL Macro
C
#define LANGUAGE_ID_STRING_PCL "PCL"
Description

This is the string that the printer language support determination routine will look for to determine if the printer supports this printer language. This string is case sensive. Some printers that report only PCL 6 support also support PCL 5. So it is recommended to use "PCL" as the search string, rather than "PCL 5", and verify that the correct output is produced by the target printer.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > LANGUAGE_ID_STRING_PCL Macro


LANGUAGE_ID_STRING_POSTSCRIPT Macro

Contents | Index | Home
Previous | Up | Next
LANGUAGE_ID_STRING_POSTSCRIPT Macro
C
#define LANGUAGE_ID_STRING_POSTSCRIPT "POSTSCRIPT"
Description

This is the string that the printer language support determination routine will look for to determine if the printer supports this printer language. This string is case sensive.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > LANGUAGE_ID_STRING_POSTSCRIPT Macro


LANGUAGE_SUPPORT_FLAGS_ESCPOS Macro

Contents | Index | Home
Previous | Up | Next
LANGUAGE_SUPPORT_FLAGS_ESCPOS Macro
C
#define LANGUAGE_SUPPORT_FLAGS_ESCPOS USB_PRINTER_FUNCTION_SUPPORT_POS
Description

These are the support flags that are set for this language.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > LANGUAGE_SUPPORT_FLAGS_ESCPOS Macro


LANGUAGE_SUPPORT_FLAGS_PCL3 Macro

Contents | Index | Home
Previous | Up | Next
LANGUAGE_SUPPORT_FLAGS_PCL3 Macro
C
#define LANGUAGE_SUPPORT_FLAGS_PCL3 0
Description

These are the support flags that are set for the PCL 3 version of this language.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > LANGUAGE_SUPPORT_FLAGS_PCL3 Macro


LANGUAGE_SUPPORT_FLAGS_PCL5 Macro

Contents | Index | Home
Previous | Up | Next
LANGUAGE_SUPPORT_FLAGS_PCL5 Macro
C
#define LANGUAGE_SUPPORT_FLAGS_PCL5 USB_PRINTER_FUNCTION_SUPPORT_VECTOR_GRAPHICS
Description

These are the support flags that are set for the PCL 5 version of this language.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > LANGUAGE_SUPPORT_FLAGS_PCL5 Macro


LANGUAGE_SUPPORT_FLAGS_POSTSCRIPT Macro

Contents | Index | Home
Previous | Up | Next
LANGUAGE_SUPPORT_FLAGS_POSTSCRIPT Macro
C
#define LANGUAGE_SUPPORT_FLAGS_POSTSCRIPT USB_PRINTER_FUNCTION_SUPPORT_VECTOR_GRAPHICS
Description

These are the support flags that are set for this language.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > LANGUAGE_SUPPORT_FLAGS_POSTSCRIPT Macro


PRINTER_COLOR_BLACK Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_COLOR_BLACK Macro
C
#define PRINTER_COLOR_BLACK 0
Description

Indicates a black line for drawing graphics objects.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_COLOR_BLACK Macro


PRINTER_COLOR_WHITE Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_COLOR_WHITE Macro
C
#define PRINTER_COLOR_WHITE 1
Description

Indicates a white line for drawing graphics objects.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_COLOR_WHITE Macro


PRINTER_DEVICE_REQUEST_GET_DEVICE_ID Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_DEVICE_REQUEST_GET_DEVICE_ID Macro
C
#define PRINTER_DEVICE_REQUEST_GET_DEVICE_ID 0x00
Description

bRequest value for the GET_DEVICE_ID USB class-specific request.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_DEVICE_REQUEST_GET_DEVICE_ID Macro


PRINTER_DEVICE_REQUEST_GET_PORT_STATUS Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_DEVICE_REQUEST_GET_PORT_STATUS Macro
C
#define PRINTER_DEVICE_REQUEST_GET_PORT_STATUS 0x01
Description

bRequest value for the GET_PORT_STATUS USB class-specific request.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_DEVICE_REQUEST_GET_PORT_STATUS Macro


PRINTER_DEVICE_REQUEST_SOFT_RESET Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_DEVICE_REQUEST_SOFT_RESET Macro
C
#define PRINTER_DEVICE_REQUEST_SOFT_RESET 0x02
Description

bRequest value for the SOFT_RESET USB class-specific request.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_DEVICE_REQUEST_SOFT_RESET Macro


PRINTER_FILL_CROSS_HATCHED Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_FILL_CROSS_HATCHED Macro
C
#define PRINTER_FILL_CROSS_HATCHED 3
Description

Indicates a cross-hatched fill for graphics objects. Requires a specified line spacing and angle.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_FILL_CROSS_HATCHED Macro


PRINTER_FILL_HATCHED Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_FILL_HATCHED Macro
C
#define PRINTER_FILL_HATCHED 2
Description

Indicates a hatched fill for graphics objects. Requires a specified line spacing and angle.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_FILL_HATCHED Macro


PRINTER_FILL_SHADED Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_FILL_SHADED Macro
C
#define PRINTER_FILL_SHADED 1
Description

Indicates a shaded fill for filled graphics objects. Requires a specified fill percentage.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_FILL_SHADED Macro


PRINTER_FILL_SOLID Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_FILL_SOLID Macro
C
#define PRINTER_FILL_SOLID 0
Description

Indicates a solid color fill for filled graphics objects.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_FILL_SOLID Macro


PRINTER_LINE_END_BUTT Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_LINE_END_BUTT Macro
C
#define PRINTER_LINE_END_BUTT 0
Description

Drawn lines will have a butt end.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_LINE_END_BUTT Macro


PRINTER_LINE_END_ROUND Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_LINE_END_ROUND Macro
C
#define PRINTER_LINE_END_ROUND 1
Description

Drawn lines will have a round end.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_LINE_END_ROUND Macro


PRINTER_LINE_END_SQUARE Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_LINE_END_SQUARE Macro
C
#define PRINTER_LINE_END_SQUARE 2
Description

Drawn lines will have a square end.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_LINE_END_SQUARE Macro


PRINTER_LINE_JOIN_BEVEL Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_LINE_JOIN_BEVEL Macro
C
#define PRINTER_LINE_JOIN_BEVEL 0
Description

Drawn lines will be joined with a bevel.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_LINE_JOIN_BEVEL Macro


PRINTER_LINE_JOIN_MITER Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_LINE_JOIN_MITER Macro
C
#define PRINTER_LINE_JOIN_MITER 1
Description

Drawn lines will be joined with a miter.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_LINE_JOIN_MITER Macro


PRINTER_LINE_JOIN_ROUND Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_LINE_JOIN_ROUND Macro
C
#define PRINTER_LINE_JOIN_ROUND 2
Description

Drawn lines will be joined with a round.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_LINE_JOIN_ROUND Macro


PRINTER_LINE_TYPE_DASHED Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_LINE_TYPE_DASHED Macro
C
#define PRINTER_LINE_TYPE_DASHED 1
Description

Indicates a dashed line for drawing graphics objects.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_LINE_TYPE_DASHED Macro


PRINTER_LINE_TYPE_DOTTED Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_LINE_TYPE_DOTTED Macro
C
#define PRINTER_LINE_TYPE_DOTTED 2
Description

Indicates a dotted line for drawing graphics objects.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_LINE_TYPE_DOTTED Macro


PRINTER_LINE_TYPE_SOLID Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_LINE_TYPE_SOLID Macro
C
#define PRINTER_LINE_TYPE_SOLID 0
Description

Indicates a solid line for drawing graphics objects.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_LINE_TYPE_SOLID Macro


PRINTER_LINE_WIDTH_NORMAL Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_LINE_WIDTH_NORMAL Macro
C
#define PRINTER_LINE_WIDTH_NORMAL 0
Description

Indicates a normal width line for drawing graphics objects.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_LINE_WIDTH_NORMAL Macro


PRINTER_LINE_WIDTH_THICK Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_LINE_WIDTH_THICK Macro
C
#define PRINTER_LINE_WIDTH_THICK 1
Description

Indicates a thick line for drawing graphics objects.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_LINE_WIDTH_THICK Macro


PRINTER_PAGE_LANDSCAPE_HEIGHT Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_PAGE_LANDSCAPE_HEIGHT Macro
C
#define PRINTER_PAGE_LANDSCAPE_HEIGHT 612
Description

The height of the page in points when in landscape mode.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_PAGE_LANDSCAPE_HEIGHT Macro


PRINTER_PAGE_LANDSCAPE_WIDTH Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_PAGE_LANDSCAPE_WIDTH Macro
C
#define PRINTER_PAGE_LANDSCAPE_WIDTH 792
Description

The width of the page in points when in landscape mode.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_PAGE_LANDSCAPE_WIDTH Macro


PRINTER_PAGE_PORTRAIT_HEIGHT Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_PAGE_PORTRAIT_HEIGHT Macro
C
#define PRINTER_PAGE_PORTRAIT_HEIGHT 792
Description

The height of the page in points when in portrait mode.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_PAGE_PORTRAIT_HEIGHT Macro


PRINTER_PAGE_PORTRAIT_WIDTH Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_PAGE_PORTRAIT_WIDTH Macro
C
#define PRINTER_PAGE_PORTRAIT_WIDTH 612
Description

The width of the page in points when in portrait mode.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_PAGE_PORTRAIT_WIDTH Macro


PRINTER_POS_BOTTOM_TO_TOP Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_POS_BOTTOM_TO_TOP Macro
C
#define PRINTER_POS_BOTTOM_TO_TOP 1
Description

POS print direction bottom to top, starting at the bottom left corner.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_POS_BOTTOM_TO_TOP Macro


PRINTER_POS_DENSITY_HORIZONTAL_DOUBLE Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_POS_DENSITY_HORIZONTAL_DOUBLE Macro
C
#define PRINTER_POS_DENSITY_HORIZONTAL_DOUBLE 2
Description

Image print with double horizontal density.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_POS_DENSITY_HORIZONTAL_DOUBLE Macro


PRINTER_POS_DENSITY_HORIZONTAL_SINGLE Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_POS_DENSITY_HORIZONTAL_SINGLE Macro
C
#define PRINTER_POS_DENSITY_HORIZONTAL_SINGLE 1
Description

Image print with single horizontal density.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_POS_DENSITY_HORIZONTAL_SINGLE Macro


PRINTER_POS_DENSITY_VERTICAL_24 Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_POS_DENSITY_VERTICAL_24 Macro
C
#define PRINTER_POS_DENSITY_VERTICAL_24 24
Description

Image print with 24-dot vertical density.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_POS_DENSITY_VERTICAL_24 Macro


PRINTER_POS_DENSITY_VERTICAL_8 Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_POS_DENSITY_VERTICAL_8 Macro
C
#define PRINTER_POS_DENSITY_VERTICAL_8 8
Description

Image print with 8-dot vertical density.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_POS_DENSITY_VERTICAL_8 Macro


PRINTER_POS_LEFT_TO_RIGHT Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_POS_LEFT_TO_RIGHT Macro
C
#define PRINTER_POS_LEFT_TO_RIGHT 0
Description

POS print direction left to right, starting at the top left corner.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_POS_LEFT_TO_RIGHT Macro


PRINTER_POS_RIGHT_TO_LEFT Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_POS_RIGHT_TO_LEFT Macro
C
#define PRINTER_POS_RIGHT_TO_LEFT 2
Description

POS print direction right to left, startin at the bottom right corner.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_POS_RIGHT_TO_LEFT Macro


PRINTER_POS_TOP_TO_BOTTOM Macro

Contents | Index | Home
Previous | Up | Next
PRINTER_POS_TOP_TO_BOTTOM Macro
C
#define PRINTER_POS_TOP_TO_BOTTOM 3
Description

POS print direction top to bottom, starting at the top right corner.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > PRINTER_POS_TOP_TO_BOTTOM Macro


USB_DATA_POINTER Union

Contents | Index | Home
Previous | Up | Next
USB_DATA_POINTER Union
C
typedef union {
  void * pointerRAM;
  const void * pointerROM;
} USB_DATA_POINTER;
Description

This type is used to represent a generic RAM or ROM pointer when passed to the function USBHostPrinterCommand() or a printer language function of the type USB_PRINTER_LANGUAGE_HANDLER. Note that the caller must indicate whether the point is actually pointing to RAM or to ROM, so we can tell which pointer is valid. Not all printer commands can actually use data in ROM. Refer to the specific printer command in the USB_PRINTER_COMMAND enumeration for more information.

Members
Members | Description
void * pointerRAM; | Pointer to data in RAM.
const void * pointerROM; | Pointer to data in ROM.
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_DATA_POINTER Union


USB_DATA_POINTER_RAM Macro

Contents | Index | Home
Previous | Up | Next
USB_DATA_POINTER_RAM Macro
C
#define USB_DATA_POINTER_RAM(x) ((USB_DATA_POINTER)(void *)x)
Description

Use this definition to cast a pointer being passed to the function USBHostPrinterCommand() that points to data in RAM.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_DATA_POINTER_RAM Macro


USB_DATA_POINTER_ROM Macro

Contents | Index | Home
Previous | Up | Next
USB_DATA_POINTER_ROM Macro
C
#define USB_DATA_POINTER_ROM(x) ((USB_DATA_POINTER)(const void *)x)
Description

Use this definition to cast a pointer being passed to the function USBHostPrinterCommand() that points to data in ROM.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_DATA_POINTER_ROM Macro


USB_MAX_PRINTER_DEVICES Macro

Contents | Index | Home
Previous | Up | Next
USB_MAX_PRINTER_DEVICES Macro
C
#define USB_MAX_PRINTER_DEVICES 1
Description

Max Number of Supported Devices

This value represents the maximum number of attached devices this class driver can support. If the user does not define a value, it will be set to 1. Currently this must be set to 1, due to limitations in the USB Host layer.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_MAX_PRINTER_DEVICES Macro


USB_NULL Macro

Contents | Index | Home
Previous | Up | Next
USB_NULL Macro
C
#define USB_NULL (USB_DATA_POINTER)(void *)NULL
Description

Use this definition to pass a NULL pointer to the function USBHostPrinterCommand().

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_NULL Macro


USB_PRINT_SCREEN_INFO Structure

Contents | Index | Home
Previous | Up | Next
USB_PRINT_SCREEN_INFO Structure
C
typedef struct {
  WORD xL;
  WORD yT;
  WORD xR;
  WORD yB;
  WORD colorBlack;
  USB_PRINTER_FUNCTION_SUPPORT printerType;
  USB_PRINTER_IMAGE_INFO printerInfo;
} USB_PRINT_SCREEN_INFO;
Description

Print Screen Information

This structure is designed for use when the USB Embedded Host Printer support is integrated with the graphics library. The structure contains the information needed to print a portion of the graphics screen as a bitmapped graphic image.

Members
Members | Description
WORD xL; | X-axis position of the left side of the screen image.
WORD yT; | Y-axis position of the top of the screen image.
WORD xR; | X-axis position of the right side of the screen image.
WORD yB; | Y-axis position of the bottom of the screen image.
WORD colorBlack; | Screen color that should be printed as black.
USB_PRINTER_FUNCTION_SUPPORT printerType; | The capabilities of the current printer, so we know what structure members are valid.
USB_PRINTER_IMAGE_INFO printerInfo; | Store all the info needed to print the image. The width and height parameters will be determined by the screen coordinates specified above. The application must provide the other values.
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINT_SCREEN_INFO Structure


USB_PRINTER_COMMAND Enumeration

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_COMMAND Enumeration
C
typedef enum {
  USB_PRINTER_ATTACHED,
  USB_PRINTER_DETACHED,
  USB_PRINTER_TRANSPARENT,
  USB_PRINTER_JOB_START,
  USB_PRINTER_JOB_STOP,
  USB_PRINTER_ORIENTATION_PORTRAIT,
  USB_PRINTER_ORIENTATION_LANDSCAPE,
  USB_PRINTER_FONT_NAME,
  USB_PRINTER_FONT_SIZE,
  USB_PRINTER_FONT_ITALIC,
  USB_PRINTER_FONT_UPRIGHT,
  USB_PRINTER_FONT_BOLD,
  USB_PRINTER_FONT_MEDIUM,
  USB_PRINTER_EJECT_PAGE,
  USB_PRINTER_TEXT_START,
  USB_PRINTER_TEXT,
  USB_PRINTER_TEXT_STOP,
  USB_PRINTER_SET_POSITION,
  USB_PRINTER_IMAGE_START,
  USB_PRINTER_IMAGE_DATA_HEADER,
  USB_PRINTER_IMAGE_DATA,
  USB_PRINTER_IMAGE_STOP,
  USB_PRINTER_VECTOR_GRAPHICS_START,
  USB_PRINTER_GRAPHICS_LINE_TYPE,
  USB_PRINTER_GRAPHICS_LINE_WIDTH,
  USB_PRINTER_GRAPHICS_LINE_END,
  USB_PRINTER_GRAPHICS_LINE_JOIN,
  USB_PRINTER_GRAPHICS_FILL_TYPE,
  USB_PRINTER_GRAPHICS_COLOR,
  USB_PRINTER_GRAPHICS_MOVE_TO,
  USB_PRINTER_GRAPHICS_MOVE_RELATIVE,
  USB_PRINTER_GRAPHICS_LINE,
  USB_PRINTER_GRAPHICS_LINE_TO,
  USB_PRINTER_GRAPHICS_LINE_TO_RELATIVE,
  USB_PRINTER_GRAPHICS_ARC,
  USB_PRINTER_GRAPHICS_CIRCLE,
  USB_PRINTER_GRAPHICS_CIRCLE_FILLED,
  USB_PRINTER_GRAPHICS_BEVEL,
  USB_PRINTER_GRAPHICS_BEVEL_FILLED,
  USB_PRINTER_GRAPHICS_RECTANGLE,
  USB_PRINTER_GRAPHICS_RECTANGLE_FILLED,
  USB_PRINTER_GRAPHICS_POLYGON,
  USB_PRINTER_VECTOR_GRAPHICS_END,
  USB_PRINTER_POS_START,
  USB_PRINTER_POS_PAGE_MODE,
  USB_PRINTER_POS_STANDARD_MODE,
  USB_PRINTER_POS_FEED,
  USB_PRINTER_POS_TEXT_LINE,
  USB_PRINTER_POS_CUT,
  USB_PRINTER_POS_CUT_PARTIAL,
  USB_PRINTER_POS_JUSTIFICATION_CENTER,
  USB_PRINTER_POS_JUSTIFICATION_LEFT,
  USB_PRINTER_POS_JUSTIFICATION_RIGHT,
  USB_PRINTER_POS_FONT_REVERSE,
  USB_PRINTER_POS_FONT_UNDERLINE,
  USB_PRINTER_POS_COLOR_BLACK,
  USB_PRINTER_POS_COLOR_RED,
  USB_PRINTER_POS_BARCODE,
  USB_PRINTER_POS_END
} USB_PRINTER_COMMAND;
Description

USB Printer Client Driver Commands

The main interface to the USB Printer Client Driver is through the function USBHostPrinterCommand(). These are the commands that can be passed to that function.

Members
Members
Description
USB_PRINTER_ATTACHED
This command is used internally by the printer client driver. Applications do not issue this command. This command informs the language support code that a new device has attached. Some language support requires the maintenance of certain information about the printering status. This command, with the USB_PRINTER_DETACHED command, allows the language support information to be maintained properly as printers are attached and detached. The data and size parameters are not used by this command, and can be passed as USB_NULL and 0 respectively.
USB_PRINTER_DETACHED
This command is used internally by the printer client driver. Applications do not issue this command. This command informs the language support code that a device has detached. Some language support requires the maintenance of certain information about the printering status. This command, with the USB_PRINTER_ATTACHED command, allows the language support information to be maintained properly as printers are attached and detached. The data and size parameters are not used by this command, and can be passed as USB_NULL and 0 respectively.
USB_PRINTER_TRANSPARENT
This command instructs the printer driver to send the buffer directly to the printer, without interpretation by the printer driver. This is normally used only when debugging new commands. The data parameter should point to the data to be sent, and size should indicate the number of bytes to send. This command supports sending data from either RAM or ROM. If the data is in ROM, be sure to set the USB_PRINTER_TRANSFER_FROM_ROM flag. If the data is in RAM but the application may overwrite it, set the USB_PRINTER_TRANSFER_COPY_DATA flag to tell the printer client driver to make a local copy of the data, allowing the application to overwrite the original buffer when USBHostPrinterCommand() terminates.
USB_PRINTER_JOB_START
This command should be issued at the beginning of every print job. It ensures that the printer is set back to a default state. The data and size parameters are not used by this command, and can be passed as USB_NULL and 0 respectively.
USB_PRINTER_JOB_STOP
This command should be issued at the end of every print job. It ejects the currently printing page, and ensures that the printer is set back to a default state. The data and size parameters are not used by this command, and can be passed as USB_NULL and 0 respectively.
USB_PRINTER_ORIENTATION_PORTRAIT
This command sets the current page orientation to portrait. This command must be issued immediately after the USB_PRINTER_JOB_START and USB_PRINTER_EJECT_PAGE commands in order for the command to take effect properly. Only one orientation command should be sent per page, or the output may not be properly generated. The default orientation is portrait. The data and size parameters are not used by this command, and can be passed as USB_NULL and 0 respectively.
USB_PRINTER_ORIENTATION_LANDSCAPE
This command sets the current page orientation to landscape. This command must be issued immediately after the USB_PRINTER_JOB_START and USB_PRINTER_EJECT_PAGE commands in order for the command to take effect properly. Only one orientation command should be sent per page, or the output may not be properly generated. The default orientation is portrait. The data and size parameters are not used by this command, and can be passed as USB_NULL and 0 respectively.
USB_PRINTER_FONT_NAME
This command selects the text font. To make usage easier, the size parameter is used to hold the font name indication. The data pointer should be passed in as USB_NULL. Refer to the enums USB_PRINTER_FONTS and USB_PRINTER_FONTS_POS for the valid values for the font name. With POS printers, the font name also indicates the font size.
USB_PRINTER_FONT_SIZE
(Full sheet printers only.) This command selects the font size in terms of points. To make usage easier, the size parameter is used to hold the font size. The data pointer should be passed in as USB_NULL. For POS printers, the size is specified as a scale factor. The value of bits [3:0] plus one is the vertical scale, and the value of bits [7:4] plus one is the horizontal scale. Each direction can be scaled a maximum of x10. For example, the value 0x00 is x1 scaling in both directions, and 0x95 is x10 scaling horizontally and x6 scaling vertically.
USB_PRINTER_FONT_ITALIC
This command sets the current font to italic. The data and size parameters are not used by this command, and can be passed as USB_NULL and 0 respectively.
USB_PRINTER_FONT_UPRIGHT
This command sets the current font to upright (not italic). The data and size parameters are not used by this command, and can be passed as USB_NULL and 0 respectively.
USB_PRINTER_FONT_BOLD
This command sets the current font to bold. The data and size parameters are not used by this command, and can be passed as USB_NULL and 0 respectively.
USB_PRINTER_FONT_MEDIUM
This command sets the current font to regular weight (not bold). The data and size parameters are not used by this command, and can be passed as USB_NULL and 0 respectively.
USB_PRINTER_EJECT_PAGE
This command ejects the currently printing page. The command USB_PRINTER_JOB_STOP will also eject the page. After this command, the selected paper orientation (portrait or landscape) and selected font must be reset. The data and size parameters are not used by this command, and can be passed as USB_NULL and 0 respectively.
USB_PRINTER_TEXT_START
This command initiates a text print. To print text, first issue a USB_PRINTER_TEXT_START command. Then issue a USB_PRINTER_TEXT command with the text to be printed, setting the transferFlags parameter correctly for the location of the source text (RAM, ROM, or external memory. Finally, use the USB_PRINTER_TEXT_STOP command to terminate the text print. For best compatibility across printers, do not insert other commands into this sequence. The data and size parameters are not used by this command, and can be passed as USB_NULL and 0 respectively.
USB_PRINTER_TEXT
This command specifies text to print. The data parameter should point to the buffer of data to send, and size should indicate how many bytes of data to print. This command supports printing text from either RAM or ROM. Be sure to set the transferFlags parameter correctly for the location of the data source. If the data is in RAM but the application may overwrite it, set the USB_PRINTER_TRANSFER_COPY_DATA flag to tell the printer client driver to make a local copy of the data, allowing the application to overwrite the original buffer when USBHostPrinterCommand() terminates. Refer to the USB_PRINTER_TEXT_START command for the sequence required to print text.
USB_PRINTER_TEXT_STOP
This command terminates a text print. Refer to the USB_PRINTER_TEXT_START command for the sequence required to print text. The data and size parameters are not used by this command, and can be passed as USB_NULL and 0 respectively. For POS printers, size is the number of lines to feed after the print. To get the best result, a minimum of one line is recommended. The data parameter is not used, and can be passed as USB_NULL.
USB_PRINTER_SET_POSITION
This command sets the current printing position on the page. Refer to the documentation for a description of the page coordinates. Both X and Y coordinates are passed in the size parameter. The X coordinate is passed in the most significant (upper) WORD, and the Y coordinate is passed in the least significant (lower) WORD. The macro USBHostPrinterPosition( X, Y ) can be used to create the paramater. POS printers support specifying the Y-axis position while in page mode only. The data pointer should be passed in as USB_NULL.
USB_PRINTER_IMAGE_START
This command is used to initialize the printing of a bitmapped image. This command requires a pointer to a variable of type USB_PRINTER_IMAGE_INFO. To print a bitmapped image, obtain the information required by the USB_PRINTER_IMAGE_INFO structure, and issue this command. Each row of bitmapped data can now be sent to the printer. For each row, first issue the USB_PRINTER_IMAGE_DATA_HEADER command. Then issue the USB_PRINTER_IMAGE_DATA command, with the transferFlags parameter set appropriately for the location of the bitmapped data. After all rows of data have been sent, terminate the image print with the USB_PRINTER_IMAGE_STOP command. Be sure that adequate heap space is available, particularly when printing from ROM or external memory, and when printing to a POS printer. When printing images on POS printers, ensure that the dot density capabilities of the printer are set correctly. If they are not, the printer will print garbage characters. Refer to the Printer Client Driver section of the Help file for more information about printing images.
USB_PRINTER_IMAGE_DATA_HEADER
This command is issued before each row of bitmapped image data. The size parameter is the width of the image in terms of pixels. The *data parameter is not used and should be passed in as USB_NULL. Refer to the USB_PRINTER_IMAGE_START command for the sequence required to print an image. When printing images on POS printers, ensure that the dot density capabilities of the printer are set correctly. If they are not, the printer will print garbage characters.
USB_PRINTER_IMAGE_DATA
This command is issued for each row of bitmapped image data. The *data parameter should point to the data, and size should be the number of bits of data to send to the printer, which should match the value passed in the USB_PRINTER_IMAGE_DATA_HEADER command. This command supports reading image data from either RAM or ROM. Be sure to set the transferFlags parameter appropriately to indicate the location of the bitmapped data. If the data is in RAM but the application may overwrite it, set the USB_PRINTER_TRANSFER_COPY_DATA flag to tell the printer client driver to make a local copy of the data, allowing the application to overwrite the original buffer when USBHostPrinterCommand() terminates. Refer to the USB_PRINTER_IMAGE_START command for the sequence required to print an image. Be sure that adequate heap space is available, particularly when printing from ROM or external memory, and when printing to a POS printer. When printing images on POS printers, ensure that the dot density capabilities of the printer are set correctly. If they are not, the printer will print garbage characters. Refer to the Printer Client Driver section of the Help file for more information about printing images.
USB_PRINTER_IMAGE_STOP
This command is used to terminate printing a bitmapped image. Refer to the USB_PRINTER_IMAGE_START command for the sequence required to print an image.
USB_PRINTER_VECTOR_GRAPHICS_START
Commands between USB_PRINTER_VECTOR_GRAPHICS_START and USB_PRINTER_VECTOR_GRAPHICS_END are valid only with printers that support vector graphics. This support is determined by the interface function of the type USB_PRINTER_LANGUAGE_SUPPORTED that is specified in the usb_config.c configuration file.
USB_PRINTER_GRAPHICS_LINE_TYPE
(Vector graphics support required.) This command sets the line type for drawing graphics. The line type indication is passed in the size parameter. Valid values are PRINTER_LINE_TYPE_SOLID, PRINTER_LINE_TYPE_DOTTED, and PRINTER_LINE_TYPE_DASHED. The data pointer parameter is not used and should be set to USB_NULL.
USB_PRINTER_GRAPHICS_LINE_WIDTH
(Vector graphics support required.) This command sets the width of the line for drawing vector graphics. The width indication is passed in the size parameter. For full sheet printers, valid values are PRINTER_LINE_WIDTH_NORMAL and PRINTER_LINE_WIDTH_THICK. For POS printers, the size is specified in dots (1-255). The data pointer parameter is not used and should be set to USB_NULL.
USB_PRINTER_GRAPHICS_LINE_END
(Vector graphics support required.) This command sets the style of the end of the lines used for drawing vector graphics. The style indication is passed in the size parameter. Valid values are PRINTER_LINE_END_BUTT, PRINTER_LINE_END_ROUND, and PRINTER_LINE_END_SQUARE. The data pointer parameter is not used and should be set to USB_NULL.
USB_PRINTER_GRAPHICS_LINE_JOIN
(Vector graphics support required.) This commands sets the style of how lines are joined when drawing vector graphics. The style indication is passed in the size parameter. Valid values are PRINTER_LINE_JOIN_BEVEL, PRINTER_LINE_JOIN_MITER, and PRINTER_LINE_JOIN_ROUND. The data pointer parameter is not used and should be set to USB_NULL.
USB_PRINTER_GRAPHICS_FILL_TYPE
(Vector graphics support required.) This command sets the fill type for drawing filled vector graphics. The data pointer should point to a data structure that matches the sFillType structure in the USB_PRINTER_GRAPHICS_PARAMETERS union. Valid values for the fillType member are:
  • PRINTER_FILL_SOLID. Other structure members are ignored.
  • PRINTER_FILL_SHADED. 0 <= shading <= 100
  • PRINTER_FILL_HATCHED. The spacing is specified in points, angle is specified in degrees.
  • PRINTER_FILL_CROSS_HATCHED. The spacing is specified in points, angle is specified in degrees.
USB_PRINTER_GRAPHICS_COLOR
(Vector graphics support required.) This command sets the color of the line for drawing vector graphics. The color indication is passed in the size parameter. Valid values are PRINTER_COLOR_BLACK and PRINTER_COLOR_WHITE. The data pointer parameter is not used and should be set to USB_NULL.
USB_PRINTER_GRAPHICS_MOVE_TO
(Vector graphics support required.) This command moves the graphics pen to the specified position. The position is specified in terms of points. The X-axis position value is passed in the most significant word of the size parameter, and the Y-axis position value is passed in the least significant word of the size parameter. POS printers support specifying the Y-axis position while in page mode only. The data pointer parameter is not used and should be set to USB_NULL.
USB_PRINTER_GRAPHICS_MOVE_RELATIVE
(Vector graphics support required.) This command moves the graphics pen to the specified relative position. The change in position is specified in terms of points. The X-axis position change is passed in the most significant word of the size parameter, and the Y-axis position change is passed in the least significant word of the size parameter. POS printers do not support specifying the Y-axis position.
USB_PRINTER_GRAPHICS_LINE
(Vector graphics support required.) This command draws a line from one specified x,y position to another specified x,y position. The data pointer should point to a data structure that matches the sLine structure in the USB_PRINTER_GRAPHICS_PARAMETERS union.
USB_PRINTER_GRAPHICS_LINE_TO
(Vector graphics support required.) This command draws a line from the current x,y position to the specified x,y position. The new x,y position is passed in the size parameter. The X-axis position value is passed in the most significant word of the size parameter, and the Y-axis position value is passed in the least significant word of the size parameter. The data pointer parameter is not used and should be set to USB_NULL.
USB_PRINTER_GRAPHICS_LINE_TO_RELATIVE
(Vector graphics support required.) This command draws a line from the current x,y position to the x,y position defined by the indicated displacement. The x and y displacements are passed in the size parameter. The X-axis displacement is passed in the most significant word of the size parameter, and the Y-axis displacement is passed in the least significant word of the size parameter. The data pointer parameter is not used and should be set to USB_NULL.
USB_PRINTER_GRAPHICS_ARC
(Vector graphics support required.) This command draws an arc, or a piece of a circle. The data pointer should point to a data structure that matches the sArc structure in the USB_PRINTER_GRAPHICS_PARAMETERS union. This command can print only one arc of a circle, unlike the Graphics library, which can print multiple separated arcs of the same circle.
USB_PRINTER_GRAPHICS_CIRCLE
(Vector graphics support required.) This command draws a circle using the current pen color and width. The inside of the circle is not filled. To draw a filled circle, use the command USB_PRINTER_GRAPHICS_CIRCLE_FILLED. The data pointer should point to a data structure that matches the sCircle structure in the USB_PRINTER_GRAPHICS_PARAMETERS union.
USB_PRINTER_GRAPHICS_CIRCLE_FILLED
(Vector graphics support required.) This command draws a filled circle using the current pen color. To draw the outline of a circle, use the command USB_PRINTER_GRAPHICS_CIRCLE_FILLED. The data pointer should point to a data structure that matches the sCircle structure in the USB_PRINTER_GRAPHICS_PARAMETERS union.
USB_PRINTER_GRAPHICS_BEVEL
(Vector graphics support required.) This command draws an outlined bevel (rectangle with rounded corners) using the current pen color and width. The inside of the bevel is not filled. To draw a filled bevel, use the command USB_PRINTER_GRAPHICS_BEVEL_FILLED. The data pointer should point to a data structure that matches the sBevel structure in the USB_PRINTER_GRAPHICS_PARAMETERS union.
USB_PRINTER_GRAPHICS_BEVEL_FILLED
(Vector graphics support required.) This command draws a filled bevel using the current pen color. To draw the outline of a bevel, use the command USB_PRINTER_GRAPHICS_BEVEL_FILLED. The data pointer should point to a data structure that matches the sBevel structure in the USB_PRINTER_GRAPHICS_PARAMETERS union.
USB_PRINTER_GRAPHICS_RECTANGLE
(Vector graphics support required.) This command draws a rectangle using the current pen color and width. The inside of the rectangle is not filled. To draw a filled rectangle, use the command USB_PRINTER_GRAPHICS_RECTANGLE_FILLED. The data pointer should point to a data structure that matches the sRectangle structure in the USB_PRINTER_GRAPHICS_PARAMETERS union.
USB_PRINTER_GRAPHICS_RECTANGLE_FILLED
(Vector graphics support required.) This command draws a filled rectangle using the current pen color. To draw the outline of a rectangle, use the command USB_PRINTER_GRAPHICS_RECTANGLE. The data pointer should point to a data structure that matches the sRectangle structure in the USB_PRINTER_GRAPHICS_PARAMETERS union.
USB_PRINTER_GRAPHICS_POLYGON
(Vector graphics support required.) This command draws the outline of a polygon with a specified number of sides, using the current pen color and width. The data pointer should point to a data structure that matches the sPolygon structure in the USB_PRINTER_GRAPHICS_PARAMETERS union. This structure contains the number of verticies of the polygon and a pointer to an array containing x,y coordinates of the verticies. Line segments are drawn to each vertex in the order that they appear in the array.
USB_PRINTER_VECTOR_GRAPHICS_END
Commands between USB_PRINTER_VECTOR_GRAPHICS_START and USB_PRINTER_VECTOR_GRAPHICS_END are valid only with printers that support vector graphics. This support is determined by the interface function of the type USB_PRINTER_LANGUAGE_SUPPORTED that is specified in the usb_config.c configuration file.
USB_PRINTER_POS_START
Commands between USB_PRINTER_POS_START and USB_PRINTER_POS_END are valid only with point-of-sale printers. This support is determined by the interface function of the type USB_PRINTER_LANGUAGE_SUPPORTED that is specified in the usb_config.c configuration file.
USB_PRINTER_POS_PAGE_MODE
(POS support required.) This command sets the printer into page mode. In this mode, print commands are retained by the printer until it receives the USB_PRINTER_EJECT_PAGE command. This allows the application to create more sophisticated output. The data pointer should point to a data struture that matches the sPage structure in the USB_PRINTER_GRAPHICS_PARAMETERS union. This structure contains the horizontal and vertical starting point, the horizontal and vertical print length, and the print direction and starting point. Valid values for the print direction and starting point are:
  • PRINTER_POS_LEFT_TO_RIGHT
  • PRINTER_POS_BOTTOM_TO_TOP
  • PRINTER_POS_RIGHT_TO_LEFT
  • PRINTER_POS_TOP_TO_BOTTOM
USB_PRINTER_POS_STANDARD_MODE
(POS support required.) This command sets the printer into standard mode. In this mode, print commands are processed and printed immediately. This is typically the default mode for a POS printer.
USB_PRINTER_POS_FEED
(POS support required.) This command feeds the specified number of lines, as dictated by the size parameter (between 0 and 255). The data parameter is not used, and should be set to USB_NULL.
USB_PRINTER_POS_TEXT_LINE
(POS support required.) This command is a simplified method of printing a text line to a POS printer. This command prints a single, null terminated string and feeds a specified number of lines after the print. The data pointer must point to a null terminated string located in RAM. Printing strings from ROM is not supported. The size parameter should be set to the number of lines to feed after the text is printed.
USB_PRINTER_POS_CUT
(POS support required.) This command cuts the paper completely. The data parameter is not used, and should be passed as USB_NULL. The least significant byte of the size parameter indicates the number of vertical motion units (printer dependent, typical values are 1/360 inch to 1/144 inch) to feed before the cut. Not all POS printer models support this command.
USB_PRINTER_POS_CUT_PARTIAL
(POS support required.) This command cuts the paper, leaving one point uncut. The data parameter is not used, and should be passed as USB_NULL. The least significant byte of the size parameter indicates the number of vertical motion units (printer dependent, typical values are 1/360 inch to 1/144 inch) to feed before the cut. Not all POS printer models support this command.
USB_PRINTER_POS_JUSTIFICATION_CENTER
(POS support required.) This command sets the printing justification to the center of the print area. The data and size parameters are not used, and should be set to USB_NULL and 0 respectively.
USB_PRINTER_POS_JUSTIFICATION_LEFT
(POS support required.) This command sets the printing justification to the left side of the print area. The data and size parameters are not used, and should be set to USB_NULL and 0 respectively.
USB_PRINTER_POS_JUSTIFICATION_RIGHT
(POS support required.) This command sets the printing justification to the right side of the print area. The data and size parameters are not used, and should be set to USB_NULL and 0 respectively.
USB_PRINTER_POS_FONT_REVERSE
(POS support required.) This command enables or disables white/black reverse printing of characters. When enabled, characters are printed in white on a black background, and underlining is not performed. To enable reverse printing, set the size parameter to 1. To disable reverse printing, set the size parameter to 0. (Only the least significant bit of the size parameter is examined.) The data parameter is not used, and should be set to USB_NULL. Not all POS printer models support this command.
USB_PRINTER_POS_FONT_UNDERLINE
(POS support required.) This command enables or disables underlining. Underlining is not performed if reverse printing is enabled. To enable underlining, set the size parameter to 1. To disable underlining, set the size parameter to 0. (Only the least significant bit of the size parameter is examined.) The data parameter is not used, and should be set to USB_NULL.
USB_PRINTER_POS_COLOR_BLACK
(POS support required.) This command changes the print color to black. This command is available only with printers that support two color printing. The data and size parameters are not used, and should be set to USB_NULL and 0 respectively.
USB_PRINTER_POS_COLOR_RED
(POS support required.) This command changes the print color to red. This command is available only with printers that support two color printing. The data and size parameters are not used, and should be set to USB_NULL and 0 respectively.
USB_PRINTER_POS_BARCODE
(POS support required.) This command prints a bar code. Not all POS printers provide bar code support, and the types of bar codes supported may vary; check the technical documentation for the desired target printer. The data pointer should point to a data structure that matches the sBarCode structure in the USB_PRINTER_GRAPHICS_PARAMETERS union. This structure contains the type of bar code (as specified by the USB_PRINTER_POS_BARCODE_FORMAT enumeration) and the bar code data.
USB_PRINTER_POS_END
Commands between USB_PRINTER_POS_START and USB_PRINTER_POS_END are valid only with point-of-sale printers. This support is determined by the interface function of the type USB_PRINTER_LANGUAGE_SUPPORTED that is specified in the usb_config.c configuration file.
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_COMMAND Enumeration


USB_PRINTER_DEVICE_ID Structure

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_DEVICE_ID Structure
C
typedef struct _USB_PRINTER_DEVICE_ID {
  WORD vid;
  WORD pid;
  USB_PRINTER_FUNCTION_SUPPORT support;
  BYTE deviceAddress;
} USB_PRINTER_DEVICE_ID;
Description

Printer Device ID Information

This structure contains identification information about an attached device.

Members
Members | Description
WORD vid; | Vendor ID of the device
WORD pid; | Product ID of the device
USB_PRINTER_FUNCTION_SUPPORT support; | Function support flags.
BYTE deviceAddress; | Address of the device on the USB
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_DEVICE_ID Structure


USB_PRINTER_ERRORS Enumeration

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_ERRORS Enumeration
C
typedef enum {
  USB_PRINTER_SUCCESS = 0,
  USB_PRINTER_BUSY = USB_ERROR_CLASS_DEFINED,
  USB_PRINTER_UNKNOWN_COMMAND,
  USB_PRINTER_UNKNOWN_DEVICE,
  USB_PRINTER_OUT_OF_MEMORY,
  USB_PRINTER_TOO_MANY_DEVICES,
  USB_PRINTER_BAD_PARAMETER
} USB_PRINTER_ERRORS;
Description

Printer Errors

These are errors that can be returned by the printer client driver. Note that USB Embedded Host errors can also be returned.

Members
Members | Description
USB_PRINTER_SUCCESS = 0 | The command was successful.
USB_PRINTER_BUSY = USB_ERROR_CLASS_DEFINED | The command cannot be performed because the printer client driver's command queue is full. Use the function USBHostPrinterCommandReady() to determine if there is space available in the queue.
USB_PRINTER_UNKNOWN_COMMAND | An invalid printer command was requested. Refer to the enumeration USB_PRINTER_COMMAND for the list of valid commands.
USB_PRINTER_UNKNOWN_DEVICE | A device with the indicated address is not attached or is not a printer.
USB_PRINTER_OUT_OF_MEMORY | Not enough free heap space is available to perform the command.
USB_PRINTER_TOO_MANY_DEVICES | The number of attached printers exceeds the maximum specified by USB_MAX_PRINTER_DEVICES. Refer to the USB configuration tool.
USB_PRINTER_BAD_PARAMETER | An invalid or out of range parameter was passed. Run time checking of graphics coordinates must be enabled by defining PRINTER_GRAPHICS_COORDINATE_CHECKING.
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_ERRORS Enumeration


USB_PRINTER_FONTS Enumeration

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_FONTS Enumeration
C
typedef enum {
  USB_PRINTER_FONT_AVANT_GARDE = 0,
  USB_PRINTER_FONT_BOOKMAN,
  USB_PRINTER_FONT_COURIER,
  USB_PRINTER_FONT_HELVETICA,
  USB_PRINTER_FONT_HELVETICA_NARROW,
  USB_PRINTER_FONT_NEW_CENTURY_SCHOOLBOOK,
  USB_PRINTER_FONT_PALATINO,
  USB_PRINTER_FONT_TIMES_NEW_ROMAN,
  USB_PRINTER_FONT_MAX_FONT
} USB_PRINTER_FONTS;
Description

Printer Fonts

This enumeration defines the various printer fonts. If new fonts are added, they must be added at the end of the list, just before the USB_PRINTER_FONT_MAX_FONT definition, as the printer language support files may utilize them for indexing purposes.

Members
Members | Description
USB_PRINTER_FONT_AVANT_GARDE = 0 | Avant Garde font
USB_PRINTER_FONT_BOOKMAN | Bookman font
USB_PRINTER_FONT_COURIER | Courier font
USB_PRINTER_FONT_HELVETICA | Helvetica font
USB_PRINTER_FONT_HELVETICA_NARROW | Helvetica Narrow font
USB_PRINTER_FONT_NEW_CENTURY_SCHOOLBOOK | New Century Schoolbook font
USB_PRINTER_FONT_PALATINO | Palatino font
USB_PRINTER_FONT_TIMES_NEW_ROMAN | Times New Roman font
USB_PRINTER_FONT_MAX_FONT | Font out of range
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_FONTS Enumeration


USB_PRINTER_FONTS_POS Enumeration

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_FONTS_POS Enumeration
C
typedef enum {
  USB_PRINTER_FONT_POS_18x36,
  USB_PRINTER_FONT_POS_18x72,
  USB_PRINTER_FONT_POS_36x36,
  USB_PRINTER_FONT_POS_36x72,
  USB_PRINTER_FONT_POS_12x24,
  USB_PRINTER_FONT_POS_12x48,
  USB_PRINTER_FONT_POS_24x24,
  USB_PRINTER_FONT_POS_24x48,
  USB_PRINTER_FONT_POS_MAX_FONT
} USB_PRINTER_FONTS_POS;
Description

POS Printer Fonts

This enumeration defines the various printer fonts used by POS printers. If new fonts are added, they must be added at the end of the list, just before the USB_PRINTER_FONT_POS_MAX_FONT definition, as the printer language support files may utilize them for indexing purposes.

Members
Members | Description
USB_PRINTER_FONT_POS_18x36 | Character size 18x36
USB_PRINTER_FONT_POS_18x72 | Character size 18x36, double height
USB_PRINTER_FONT_POS_36x36 | Character size 18x36, double width
USB_PRINTER_FONT_POS_36x72 | Character size 18x36, double height and width
USB_PRINTER_FONT_POS_12x24 | Character size 12x24
USB_PRINTER_FONT_POS_12x48 | Character size 12x24, double height
USB_PRINTER_FONT_POS_24x24 | Character size 12x24, double width
USB_PRINTER_FONT_POS_24x48 | Character size 12x24, double height and width
USB_PRINTER_FONT_POS_MAX_FONT | Font out of range
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_FONTS_POS Enumeration


USB_PRINTER_FUNCTION_SUPPORT Union

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_FUNCTION_SUPPORT Union
C
typedef union {
  WORD val;
  struct {
    WORD supportsVectorGraphics : 1;
    WORD supportsPOS : 1;
  } supportFlags;
} USB_PRINTER_FUNCTION_SUPPORT;
Description

Printer Device Function support Information

This structure contains information about the functions that the attached printer supports. See the related constants for setting these flags via the val member:

  • USB_PRINTER_FUNCTION_SUPPORT_POS
  • USB_PRINTER_FUNCTION_SUPPORT_VECTOR_GRAPHICS

Members
Members
Description
WORD val;
The WORD representation of the support flags.
struct {
WORD supportsVectorGraphics : 1;
WORD supportsPOS : 1;
} supportFlags;
Various printer function support flags.
WORD supportsVectorGraphics : 1;
The printer supports vector graphics.
WORD supportsPOS : 1;
The printer is a POS printer.
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_FUNCTION_SUPPORT Union


USB_PRINTER_FUNCTION_SUPPORT_POS Macro

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_FUNCTION_SUPPORT_POS Macro
C
#define USB_PRINTER_FUNCTION_SUPPORT_POS 0x0002
Description

Constant to use to set the supportsPOS member of the USB_PRINTER_FUNCTION_SUPPORT union.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_FUNCTION_SUPPORT_POS Macro


USB_PRINTER_FUNCTION_SUPPORT_VECTOR_GRAPHICS Macro

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_FUNCTION_SUPPORT_VECTOR_GRAPHICS Macro
C
#define USB_PRINTER_FUNCTION_SUPPORT_VECTOR_GRAPHICS 0x0001
Description

Constant to use to set the supportsVectorGraphics member of the USB_PRINTER_FUNCTION_SUPPORT union.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_FUNCTION_SUPPORT_VECTOR_GRAPHICS Macro


USB_PRINTER_GRAPHICS_PARAMETERS Union

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_GRAPHICS_PARAMETERS Union
C
typedef union {
  struct {
    WORD xL;
    WORD yT;
    WORD xR;
    WORD yB;
    WORD r1;
    WORD r2;
    WORD octant;
  } sArc;
  struct {
    BYTE height;
    BYTE type;
    BYTE textPosition;
    BYTE textFont;
    BYTE * data;
    BYTE dataLength;
    union {
      BYTE value;
      struct {
        BYTE bPrintCheckDigit : 1;
      } bits;
    } flags;
  } sBarCode;
  struct {
    WORD xL;
    WORD yT;
    WORD xR;
    WORD yB;
    WORD r;
  } sBevel;
  struct {
    WORD x;
    WORD y;
    WORD r;
  } sCircle;
  struct {
    WORD fillType;
    WORD spacing;
    WORD angle;
    WORD shading;
  } sFillType;
  struct {
    WORD x1;
    WORD y1;
    WORD x2;
    WORD y2;
  } sLine;
  struct {
    WORD startPointHorizontal;
    WORD startPointVertical;
    WORD lengthHorizontal;
    WORD lengthVertical;
    BYTE printDirection;
  } sPage;
  struct {
    SHORT numPoints;
    WORD * points;
  } sPolygon;
  struct {
    WORD xL;
    WORD yT;
    WORD xR;
    WORD yB;
  } sRectangle;
} USB_PRINTER_GRAPHICS_PARAMETERS;
Description

USB Printer Graphics Parameter Structures

This union can be used to declare a variable that can hold the parameters for any printer graphics or POS printer command (USB_PRINTER_COMMAND). The union allows a single variable to be declared and then reused for any printer graphics command.

Members
Members
Description
struct {
WORD xL;
WORD yT;
WORD xR;
WORD yB;
WORD r1;
WORD r2;
WORD octant;
} sArc;
This structure is used by the USB_PRINTER_GRAPHICS_ARC command (USB_PRINTER_COMMAND).
WORD xL;
X-axis position of the upper left corner.
WORD yT;
Y-axis position of the upper left corner.
WORD xR;
X-axis position of the lower right corner.
WORD yB;
Y-axis position of the lower right corner.
WORD r1;
The inner radius of the two concentric cicles that defines the thickness of the arc.
WORD r2;
The outer of radius the two concentric circles that defines the thickness of the arc.
WORD octant;
Bitmask of the octant that will be drawn. Moving in a clockwise direction from x = 0, y = +radius
  • bit0 : first octant
  • bit1 : second octant
  • bit2 : third octant
  • bit3 : fourth octant
  • bit4 : fifth octant
  • bit5 : sixth octant
  • bit6 : seventh octant
  • bit7 : eigth octant
struct {
BYTE height;
BYTE type;
BYTE textPosition;
BYTE textFont;
BYTE * data;
BYTE dataLength;
union {
BYTE value;
struct {
BYTE bPrintCheckDigit : 1;
} bits;
} flags;
} sBarCode;
This structure is used by the USB_PRINTER_POS_BARCODE command (USB_PRINTER_COMMAND).
BYTE height;
Bar code height in dots.
BYTE type;
Bar code type. See the USB_PRINTER_POS_BARCODE_FORMAT enumeration.
BYTE textPosition;
Position of the readable text. Valid values are BARCODE_TEXT_OMIT, BARCODE_TEXT_ABOVE, BARCODE_TEXT_BELOW, BARCODE_TEXT_ABOVE_AND_BELOW.
BYTE textFont;
Font of the readable text. Valid values are dependent on the particular POS printer (BARCODE_TEXT_12x24 and BARCODE_TEXT_18x36 for ESC/POS).
BYTE * data;
Pointer to the bar code data.
BYTE dataLength;
Number of bytes of bar code data.
BYTE bPrintCheckDigit : 1;
Whether or not to print an optional check digit. Valid for Code39 (USB_PRINTER_POS_BARCODE_FORMAT USB_PRINTER_POS_BARCODE_CODE39) and CODABAR (USB_PRINTER_POS_BARCODE_FORMAT USB_PRINTER_POS_BARCODE_CODABAR) formats only.
struct {
WORD xL;
WORD yT;
WORD xR;
WORD yB;
WORD r;
} sBevel;
This structure is used by the USB_PRINTER_GRAPHICS_BEVEL and USB_PRINTER_GRAPHICS_BEVEL_FILLED commands (USB_PRINTER_COMMAND).
WORD xL;
X-axis position of the left side of the bevel.
WORD yT;
Y-axis position of the top of the bevel.
WORD xR;
X-axis position of the right side of the bevel.
WORD yB;
Y-axis position of the bottom of the bevel.
WORD r;
The radius of the cicle that defines the rounded corner
struct {
WORD x;
WORD y;
WORD r;
} sCircle;
This structure is used by the USB_PRINTER_GRAPHICS_CIRCLE and USB_PRINTER_GRAPHICS_CIRCLE_FILLED commands (USB_PRINTER_COMMAND).
WORD x;
X-axis position of the center of the circle.
WORD y;
Y-axis position of the center of the circle.
WORD r;
Radius of the circle.
struct {
WORD fillType;
WORD spacing;
WORD angle;
WORD shading;
} sFillType;
This structure is used by the USB_PRINTER_GRAPHICS_FILL_TYPE command (USB_PRINTER_COMMAND).
WORD fillType;
The type of fill. See USB_PRINTER_GRAPHICS_FILL_TYPE for valid values.
WORD spacing;
Line spacing for hatched fill (if supported).
WORD angle;
Line angle for hatched fill (if supported).
WORD shading;
Shading level for shaded fill. Printer support may be limited.
struct {
WORD x1;
WORD y1;
WORD x2;
WORD y2;
} sLine;
This structure is used by the USB_PRINTER_GRAPHICS_LINE command (USB_PRINTER_COMMAND).
WORD x1;
X-axis position of the first point.
WORD y1;
Y-axis position of the first point.
WORD x2;
X-axis position of the second point.
WORD y2;
Y-axis position of the second point.
struct {
WORD startPointHorizontal;
WORD startPointVertical;
WORD lengthHorizontal;
WORD lengthVertical;
BYTE printDirection;
} sPage;
This structure is used by POS printers and the USB_PRINTER_POS_PAGE_MODE command (USB_PRINTER_COMMAND).
WORD startPointHorizontal;
The horizontal page starting point.
WORD startPointVertical;
The vertical page starting point.
WORD lengthHorizontal;
The horizontal print length.
WORD lengthVertical;
The vertical print length.
BYTE printDirection;
The print direction and starting point.
struct {
SHORT numPoints;
WORD * points;
} sPolygon;
This structure is used by the USB_PRINTER_GRAPHICS_POLYGON command (USB_PRINTER_COMMAND).
SHORT numPoints;
The number of points of the polygon.
WORD * points;
The array of polygon points {x1, y1, x2, y2, ... xn, yn}.
struct {
WORD xL;
WORD yT;
WORD xR;
WORD yB;
} sRectangle;
This structure is used by the USB_PRINTER_GRAPHICS_RECTANGLE and USB_PRINTER_GRAPHICS_RECTANGLE_FILLED commands (USB_PRINTER_COMMAND).
WORD xL;
X-axis position of the left side of the rectangle.
WORD yT;
Y-axis position of the top of the rectangle.
WORD xR;
X-axis position of the right side of the rectangle.
WORD yB;
Y-axis position of the bottom of the rectangle.
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_GRAPHICS_PARAMETERS Union


USB_PRINTER_IMAGE_INFO Structure

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_IMAGE_INFO Structure
C
typedef struct {
  WORD width;
  WORD height;
  WORD positionX;
  WORD positionY;
  union {
    struct {
      WORD resolution;
      float scale;
    }
    struct {
      BYTE densityVertical;
      BYTE densityHorizontal;
    }
  }
} USB_PRINTER_IMAGE_INFO;
Description

Bitmapped Image Information

This structure contains the information needed to print a bitmapped graphic image.

When using a full sheet printer, utilize the resolution and the scale members to specify the size of the image. Some printer languages (e.g. PostScript) utilize a scale factor, while others (e.g. PCL 5) utilize a dots-per-inch resolution. Also, some printers that utilize the resolution specification support only certain values for the resolution. For maximum compatibility, specify both members of this structure. The following table shows example values that will generate similarly sized output.

Copy Code
Resolution (DPI)  Scale
----------------  -----
        75         1.0
       100         0.75
       150         0.5
       200         0.37
       300         0.25
       600         0.13

When using a POS printer, utilize the densityVertical and densityHorizontal members to specify the size of the image. The densityHorizontal can be either single (1) or double (2). The valid values for densityVertical are printer dependent. Most printers support 8-dot, many support 8 and 24-dot, and a few support 8, 24, and 36-dot (represented by the values 8, 24, and 36 respectively). This value affects how the bit image data is sent to the printer. The set of allowable values must be configured correctly, since the image configuration method differs depending on the set of allowed values. To maintain the aspect ratio, the following selections are recommended:

Copy Code
Supported Horizontal Densities  densityVertical  densityHorizontal
------------------------------------------------------------------
8-dot                                 8              1 (single)
8 and 24-dot                         24              2 (double)
8, 24, and 36-dot                    24              2 (double)

The 36-bit density is not recommended, as it requires a great deal of available heap space, is not supported by the USBHostPrinterPOSImageDataFormat() function, and produces the same output as the 24-dot density print.

Members
Members | Description
WORD width; | The width of the image in pixels.
WORD height; | The height of the image in pixels.
WORD positionX; | The position of the image on the X axis.
WORD positionY; | The position of the image on the Y axis.
WORD resolution; | (Full sheet printers only.) The resolution of the printed image. This parameter is not supported by all printer languages.
float scale; | (Full sheet printers only.) The scaling of the printed image. Both the X axis and the Y axis are scaled by this amount. This parameter is not supported by all printer languages.
BYTE densityVertical; | (POS printers only.) The vertical dot density of the bit image. Valid values are printer dependent. See above.
BYTE densityHorizontal; | (POS printers only.) The horizontal dot density of the bit image. Valid values are 1 (single) and 2 (double). See above.
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_IMAGE_INFO Structure


USB_PRINTER_INTERFACE Structure

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_INTERFACE Structure
C
typedef struct {
  USB_PRINTER_LANGUAGE_HANDLER languageCommandHandler;
  USB_PRINTER_LANGUAGE_SUPPORTED isLanguageSupported;
} USB_PRINTER_INTERFACE;
Description

USB Printer Interface Structure

This structure represents the information needed to interface with a printer language. An array of these structures must be created in usb_config.c, so the USB printer client driver can determine what printer language to use to communicate with the printer.

Members
Members | Description
USB_PRINTER_LANGUAGE_HANDLER languageCommandHandler; | Function in the printer language support file that handles all printer commands.
USB_PRINTER_LANGUAGE_SUPPORTED isLanguageSupported; | Function in the printer language support file that determines if the printer supports this particular printer language.
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_INTERFACE Structure


USB_PRINTER_LANGUAGE_HANDLER Type

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_LANGUAGE_HANDLER Type
C
typedef BYTE (* USB_PRINTER_LANGUAGE_HANDLER)(BYTE address, USB_PRINTER_COMMAND command, USB_DATA_POINTER data, DWORD size, BYTE flags);
Description

This data type defines a pointer to a call-back function that must be implemented by a printer language driver. When the user calls the printer interface function, the appropriate language driver with this prototype will be called to generate the proper commands for the requested operation.

Not all printer commands support data from both RAM and ROM. Unless otherwise noted, the data pointer is assumed to point to RAM, regardless of the value of transferFlags. Refer to the specific command to see if ROM data is supported.

Preconditions

None

Parameters
Parameters
Description
BYTE address
Device's address on the bus
USB_PRINTER_COMMAND command
Command to execute. See the enumeration USB_PRINTER_COMMAND for the list of valid commands and their requirements.
USB_DATA_POINTER data
Pointer to the required data. Note that the caller must set transferFlags appropriately to indicate if the pointer is a RAM pointer or a ROM pointer.
DWORD size
Size of the data. For some commands, this parameter is used to hold the data itself.
BYTE transferFlags
Flags that indicate details about the transfer operation. Refer to these flags
  • USB_PRINTER_TRANSFER_COPY_DATA
  • USB_PRINTER_TRANSFER_STATIC_DATA
  • USB_PRINTER_TRANSFER_NOTIFY
  • USB_PRINTER_TRANSFER_FROM_ROM
  • USB_PRINTER_TRANSFER_FROM_RAM
Return Values
Return Values | Description
USB_PRINTER_SUCCESS | The command was executed successfully.
USB_PRINTER_UNKNOWN_DEVICE | A printer with the indicated address is not attached
USB_PRINTER_TOO_MANY_DEVICES | The printer status array does not have space for another printer.
USB_PRINTER_OUT_OF_MEMORY | Not enough available heap space to execute the command.
other | See possible return codes from the function USBHostPrinterWrite().
Remarks

None

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_LANGUAGE_HANDLER Type


USB_PRINTER_LANGUAGE_SUPPORTED Type

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_LANGUAGE_SUPPORTED Type
C
typedef BOOL (* USB_PRINTER_LANGUAGE_SUPPORTED)(char *deviceID, USB_PRINTER_FUNCTION_SUPPORT *support);
Description

This data type defines a pointer to a call-back function that must be implemented by a printer language driver. When the user calls a function of this type, the language driver will return a BOOL indicating if the language driver supports a printer with the indicated "COMMAND SET:" portion of the device ID string. If the printer is supported, this function also returns information about the types of operations that the printer supports.

Preconditions

None

Parameters
Parameters | Description
char *deviceID | Pointer to the "COMMAND SET:" portion of the device ID string of the attached printer.
USB_PRINTER_FUNCTION_SUPPORT *support | Pointer to returned information about what types of functions this printer supports.
Return Values
Return Values | Description
TRUE | The printer language can be used with the attached printer.
FALSE | The printer language cannot be used with the attached printer.
Remarks

The caller must first locate the "COMMAND SET:" section of the device ID string. To ensure that only the "COMMAND SET:" section of the device ID string is checked, the ";" at the end of the section should be temporarily replaced with a NULL. Otherwise, this function may find the printer language string in the comments or other section, and incorrectly indicate that the printer supports the language.

Device ID strings are case sensitive.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_LANGUAGE_SUPPORTED Type


USB_PRINTER_POS_BARCODE_FORMAT Enumeration

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_POS_BARCODE_FORMAT Enumeration
C
typedef enum {
  USB_PRINTER_POS_BARCODE_UPC_A = 0,
  USB_PRINTER_POS_BARCODE_UPC_E,
  USB_PRINTER_POS_BARCODE_EAN13,
  USB_PRINTER_POS_BARCODE_EAN8,
  USB_PRINTER_POS_BARCODE_CODE39,
  USB_PRINTER_POS_BARCODE_ITF,
  USB_PRINTER_POS_BARCODE_CODABAR,
  USB_PRINTER_POS_BARCODE_CODE93,
  USB_PRINTER_POS_BARCODE_CODE128,
  USB_PRINTER_POS_BARCODE_EAN128,
  USB_PRINTER_POS_BARCODE_MAX
} USB_PRINTER_POS_BARCODE_FORMAT;
Description

Bar Code Formats

These are the bar code formats for printing bar codes on POS printers. They are used in conjuction with the USB_PRINTER_POS_BARCODE command (USB_PRINTER_COMMAND). Bar code information is passed using the sBarCode structure within the USB_PRINTER_GRAPHICS_PARAMETERS union. The exact values to send for each bar code type can vary for the particular POS printer, and not all printers support all bar code types. Be sure to test the output on the target printer, and adjust the values specified in usb_host_printer_esc_pos.c if necessary. Refer to the printer's technical documentation for the required values. Do not alter this enumeration.

Members
Members
Description
USB_PRINTER_POS_BARCODE_UPC_A = 0
UPC-A bar code format. Typically used for making products with a unique code,as well as for coupons, periodicals, and paperback books. The data for this bar code must consist of 11 values from '0' to '9' (ASCII), and the data length for this bar code must be 11. The first digit is the number system character:
  • 0, 6, 7 Regular UPC codes
  • 2 Random weight items
  • 3 National Drug Code and National Health Related Items Code
  • 4 In-store marking of non-food items
  • 5 Coupons
  • 1, 8, 9 Reserved
A check digit will be automatically calculated and appended. For more information, refer to the UPC Symbol Specification Manual from the Uniform Code Council.
USB_PRINTER_POS_BARCODE_UPC_E
UPC-E bar code format. Similar to UPC-A but with restrictions. Data lengths of 6, 7, or 11 bytes are supported. Not all printers support the 6 or 7 byte widths; 11 byte data is recommended. If the data length is not 6, then the first the first digit (the number system character) must be set to '0'. If 11 data bytes are presented, the printer will generate a shortened 6-digit code. The check digit will be automatically calculated and appended.
USB_PRINTER_POS_BARCODE_EAN13
EAN/JAN-13 bar code format. Similar to UPC-A, but there are 12 numeric digits plus a checksum digit. The check digit will be automatically calculated and appended.
USB_PRINTER_POS_BARCODE_EAN8
EAN/JAN-8 bar code format. Similar to UPC-E, but there are 7 numeric digits, and the first digit (the number system character) must be set to '0'. The check digit will be automatically calculated and appended.
USB_PRINTER_POS_BARCODE_CODE39
CODE39 bar code format. Typically used in applications where the data length may change. This format uses encoded numeric characters, uppercase alphabet characters, and the symbols '-' (dash), '.' (period), ' ' (space), '$' (dollar sign), '/' (forward slash), '+' (plus), and '%' (percent). If the bPrintCheckDigit flag is set, then the check digit will be automatically calculated and appended. Otherwise, no check digit will be printed.
USB_PRINTER_POS_BARCODE_ITF
ITF, or Interleaved 2 of 5, bar code format. Used in applications that have a fixed data length for all items. Only the digits 0-9 can be encoded, and there must be an even number of digits.
USB_PRINTER_POS_BARCODE_CODABAR
Codabar bar code format. Useful in applications that contain mostly numeric digits and variable data sizes. This format utilizes the digits 0-9, letters A-D (used as start/stop characters), '-' (dash), '$' (dollar sign), ':' (colon), '/' (forward slash), '.' (period), and '+' (plus). If the bPrintCheckDigit flag is set, then the check digit will be automatically calculated and appended. Otherwise, no check digit will be printed.
USB_PRINTER_POS_BARCODE_CODE93
(Available only if the printer supports extended bar code formats.) CODE93 bar code format. Used in applications that require heavy error checking. It has a variable data size, and uses 128-bit ASCII characters. The start code, stop code, and check digits are added automatically.
USB_PRINTER_POS_BARCODE_CODE128
(Available only if the printer supports extended bar code formats.) Code 128 bar code format. Used in applications that require a large amount of variable length data and extra error checking. It uses 128-bit ASCII plus special symbols. The first two data bytes must be the code set selection character. The first byte must be BARCODE_CODE128_CODESET (0x7B), and the second byte must be 'A', 'B', or 'C'. In general Code A should be used if the data contains control characters (0x00 - 0x1F), and Code B should be used if the data contains lower case letters and higher ASCII values (0x60-0x7F). If an ASCII '{' (left brace, 0x7B) is contained in the data, it must be encoded as two bytes with the value 0x7B.
USB_PRINTER_POS_BARCODE_EAN128
NOT YET SUPPORTED (Available only if the printer supports extended bar code formats.) EAN-128 or UCC-128 bar code format. Used in shipping applications. Refer to the Application Standard for Shopping Container Codes from the Uniform Code Council.
USB_PRINTER_POS_BARCODE_MAX
Bar code type out of range.
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_POS_BARCODE_FORMAT Enumeration


USB_PRINTER_SPECIFIC_INTERFACE Structure

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_SPECIFIC_INTERFACE Structure
C
typedef struct {
  WORD vid;
  WORD pid;
  WORD languageIndex;
  USB_PRINTER_FUNCTION_SUPPORT support;
} USB_PRINTER_SPECIFIC_INTERFACE;
Description

USB Printer Specific Interface Structure

This structure is used to explicitly specify what printer language to use for a particular printer, and what print functions the printer supports. It can be used when a printer supports multiple languages with one language preferred over the others. It is required for printers that do not support the GET_DEVICE_ID printer class request. These printers do not report what printer languages they support. Typically, these printers also do not report Printer Class support in their Interface Descriptors, and must be explicitly supported by their VID and PID in the TPL. This structure links the VID and PID of the printer to the index in the usbPrinterClientLanguages[] array of USB_PRINTER_INTERFACE structures in usb_config.c that contains the appropriate printer language functions.

Members
Members | Description
WORD vid; | Printer vendor ID.
WORD pid; | Printer product ID.
WORD languageIndex; | Index into the usbPrinterClientLanguages[] array of USB_PRINTER_INTERFACE structures defined in usb_config.c.
USB_PRINTER_FUNCTION_SUPPORT support; | Support flags that are set by this printer.
Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_SPECIFIC_INTERFACE Structure


USB_PRINTER_TRANSFER_COPY_DATA Macro

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_TRANSFER_COPY_DATA Macro
C
#define USB_PRINTER_TRANSFER_COPY_DATA 0x01
Description

This flag indicates that the printer client driver should make a copy of the data passed to the command. This allows the application to reuse the data storage immediately instead of waiting until the transfer is sent to the printer. The client driver will allocate space in the heap for the data copy. If there is not enough available memory, the command will terminate with a USB_PRINTER_OUT_OF_MEMORY error. Otherwise, the original data will be copied to the temporary data space. This temporary data will be freed upon completion, regardless of whether or not the command was performed successfully. NOTE: If the data is located in ROM, the flag USB_PRINTER_TRANSFER_FROM_ROM must be used instead.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_TRANSFER_COPY_DATA Macro


USB_PRINTER_TRANSFER_FROM_RAM Macro

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_TRANSFER_FROM_RAM Macro
C
#define USB_PRINTER_TRANSFER_FROM_RAM 0x00
Description

This flag indicates that the source of the command data is in RAM. The application can then choose whether or not to have the printer client driver make a copy of the data.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_TRANSFER_FROM_RAM Macro


USB_PRINTER_TRANSFER_FROM_ROM Macro

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_TRANSFER_FROM_ROM Macro
C
#define USB_PRINTER_TRANSFER_FROM_ROM 0x04
Description

This flag indicates that the source of the command data is in ROM. The data will be copied to RAM, since the USB Host layer cannot read data from ROM. If there is not enough available heap space to make a copy of the data, the command will fail. If using this flag, do not set the USB_PRINTER_TRANSFER_COPY_DATA flag.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_TRANSFER_FROM_ROM Macro


USB_PRINTER_TRANSFER_NOTIFY Macro

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_TRANSFER_NOTIFY Macro
C
#define USB_PRINTER_TRANSFER_NOTIFY 0x02
Description

This flag indicates that the application layer wants to receive an event notification when the command completes.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_TRANSFER_NOTIFY Macro


USB_PRINTER_TRANSFER_STATIC_DATA Macro

Contents | Index | Home
Previous | Up | Next
USB_PRINTER_TRANSFER_STATIC_DATA Macro
C
#define USB_PRINTER_TRANSFER_STATIC_DATA 0x00
Description

This flag indicates that the data will not change in the time between the printer command being issued and the data actually being sent to the printer.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USB_PRINTER_TRANSFER_STATIC_DATA Macro


USBHOSTPRINTER_SETFLAG_COPY_DATA Macro

Contents | Index | Home
Previous | Up | Next
USBHOSTPRINTER_SETFLAG_COPY_DATA Macro
C
#define USBHOSTPRINTER_SETFLAG_COPY_DATA(x) {x |= USB_PRINTER_TRANSFER_COPY_DATA;}
Description

Use this macro to set the USB_PRINTER_TRANSFER_COPY_DATA flag in a variable.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USBHOSTPRINTER_SETFLAG_COPY_DATA Macro


USBHOSTPRINTER_SETFLAG_NOTIFY Macro

Contents | Index | Home
Previous | Up | Next
USBHOSTPRINTER_SETFLAG_NOTIFY Macro
C
#define USBHOSTPRINTER_SETFLAG_NOTIFY(x) {x |= USB_PRINTER_TRANSFER_NOTIFY;}
Description

Use this macro to set the USB_PRINTER_TRANSFER_NOTIFY flag in a variable.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USBHOSTPRINTER_SETFLAG_NOTIFY Macro


USBHOSTPRINTER_SETFLAG_STATIC_DATA Macro

Contents | Index | Home
Previous | Up | Next
USBHOSTPRINTER_SETFLAG_STATIC_DATA Macro
C
#define USBHOSTPRINTER_SETFLAG_STATIC_DATA(x) {x &= ~USB_PRINTER_TRANSFER_COPY_DATA;}
Description

Use this macro to clear the USB_PRINTER_TRANSFER_COPY_DATA flag in a variable.

Application Programming Interface (API) > Embedded Host API > Printer Client Driver > Data Types and Constants > USBHOSTPRINTER_SETFLAG_STATIC_DATA Macro


On-The-Go (OTG)

Contents | Index | Home
Previous | Up | Next
On-The-Go (OTG)

USB OTG (On-The-Go)

USB OTG was defined by the USB-IF to standardize connectivity in mobile devices. USB OTG allows devices to be dual role (Host or Peripheral) and dynamically switch between the two. For example, you could have all in one product, a device that is a peripheral when plugged into a PC, a device that is an embedded host when plugged into a digital camera, a device that is an embedded host when plugged into a printer, and a device that is an embedded host when plugged into a keyboard.

A USB OTG device uses a Micro A/B style receptacle. When a Micro A plug is inserted, the device will take on the default role of being a host. When a Micro B plug is inserted, the device will take on the default role of being a peripheral. When no plug is inserted, the device will take on the role of being a peripheral.

The USB OTG layer provides an interface for a USB OTG device to dynamically switch roles between either being an embedded host or a peripheral. The USB OTG layer is called into by the the Embedded Host and Peripheral Device Stacks. The USB OTG layer is responsible for switching roles using the Host Negotiation Protocol (HNP), requesting sessions using the Session Request Protocol(SRP), providing role status to the application, and displaying any errors.

Switching Roles using Host Negotiation Protocol (HNP)

Switching Roles is easily accomplished using the USBOTGSelectRole() function call. This function is called on the A-side Host when it is ready to become a peripheral and give the B-side peripheral the opportunity to become Host.

Requesting Sessions using Session Request Protocol (SRP)

If the A-side Host has ended a session (turned off VBUS power), the B-side can request a new VBUS session. This is easily accomplished by using the USBOTGRequestSession() function call. This function should only be called on a B-side peripheral.

Main Application

The main application should have the following code at a minimum for initialization, re-initialization of the system when a role switch occurs, maintaining the stack tasks, and maintaining the application tasks.

InitializeSystem();
USBOTGInitialize();

while(1)
{
    //If Role Switch Occurred Then
    if (USBOTGRoleSwitch())
    {
        //Re-Initialize
        InitializeSystem();

        //Clear Role Switch Flag
        USBOTGClearRoleSwitch();
    }

    //If currently a Peripheral and HNP is not Active Then
    if (USBOTGCurrentRoleIs() == ROLE_DEVICE && !USBOTGHnpIsActive())
    {
        //Call Device Tasks
        USBDeviceTasks();

        //Call Process IO
        ProcessIO();
    }

    //If currently a Host and HNP is not Active Then
    else if (USBOTGCurrentRoleIs() == ROLE_HOST && !USBOTGHnpIsActive())
    {
        //Call Host Tasks
        USBHostTasks();

        //Call Manage Demo
        ManageDemoState();
    }
}

See AN1140 USB Embedded Host Stack for more information about the Embedded Host Stack layer.

See the Microchip USB Device Firmware Framework User's Guide from the [image] www.microchip.com/usb Documentation link for more information about the USB Device Stack layer.

Topics
Name | Description
Interface Routines |
Data Types and Constants |
Application Programming Interface (API) > On-The-Go (OTG)


Interface Routines

Contents | Index | Home
Previous | Up | Next
Interface Routines
Functions
Name | Description
USBOTGClearRoleSwitch | This function clears the RoleSwitch variable. After the main function detects the RoleSwitch and re-initializes the system, this function should be called to clear the RoleSwitch flag
USBOTGCurrentRoleIs | This function returns whether the current role is ROLE_HOST or ROLE_DEVICE
USBOTGDefaultRoleIs | This function returns whether the default role is ROLE_HOST or ROLE_DEVICE
USBOTGInitialize | This function initializes an OTG application and initializes a default role of Host or Device
USBOTGRequestSession | This function requests a Session from an A side Host using the Session Request Protocol (SRP). The function will return TRUE if the request was successful or FALSE otherwise.
USBOTGRoleSwitch | This function returns whether a role switch occurred or not. This is used by the main application function to determine when to reinitialize the system (InitializeSystem())
USBOTGSelectRole | This function initiates a role switch via the Host Negotiation Protocol (HNP). The parameter role that is passed to this function is the desired role to switch to.
USBOTGSession | This function starts, ends, or toggles a VBUS session.
Application Programming Interface (API) > On-The-Go (OTG) > Interface Routines


USBOTGClearRoleSwitch Function

Contents | Index | Home
Previous | Up | Next
USBOTGClearRoleSwitch Function
C
void USBOTGClearRoleSwitch();
Description

This function clears the RoleSwitch variable. After the main function detects the RoleSwitch and re-initializes the system, this function should be called to clear the RoleSwitch flag

Preconditions

None

Remarks

None

Application Programming Interface (API) > On-The-Go (OTG) > Interface Routines > USBOTGClearRoleSwitch Function


USBOTGCurrentRoleIs Function

Contents | Index | Home
Previous | Up | Next
USBOTGCurrentRoleIs Function
C
BYTE USBOTGCurrentRoleIs();
Description

This function returns whether the current role is ROLE_HOST or ROLE_DEVICE

Preconditions

None

Return Values
Return Values | Description
BYTE | ROLE_HOST or ROLE_DEVICE
Remarks

None

Application Programming Interface (API) > On-The-Go (OTG) > Interface Routines > USBOTGCurrentRoleIs Function


USBOTGDefaultRoleIs Function

Contents | Index | Home
Previous | Up | Next
USBOTGDefaultRoleIs Function
C
BYTE USBOTGDefaultRoleIs();
Description

This function returns whether the default role is ROLE_HOST or ROLE_DEVICE

Preconditions

None

Return Values
Return Values | Description
BYTE | ROLE_HOST or ROLE_DEVICE
Remarks

If using a Micro AB USB OTG Cable, the A-side plug of the cable when plugged in will assign a default role of ROLE_HOST. The B-side plug of the cable when plugged in will assign a default role of ROLE_DEVICE.

If using a Standard USB Cable, ROLE_HOST or ROLE_DEVICE needs to be manually configured in usb_config.h.

Both of these items can be easily configured using the USB Config Tool which will automatically generate the apropriate information for your application

Application Programming Interface (API) > On-The-Go (OTG) > Interface Routines > USBOTGDefaultRoleIs Function


USBOTGInitialize Function

Contents | Index | Home
Previous | Up | Next
USBOTGInitialize Function
C
void USBOTGInitialize();
Description

This function initializes an OTG application and initializes a default role of Host or Device

Preconditions

None

Remarks

#define USB_MICRO_AB_OTG_CABLE should be commented out in usb_config.h if not using a micro AB OTG cable

Application Programming Interface (API) > On-The-Go (OTG) > Interface Routines > USBOTGInitialize Function


USBOTGRequestSession Function

Contents | Index | Home
Previous | Up | Next
USBOTGRequestSession Function
C
BOOL USBOTGRequestSession();
Description

This function requests a Session from an A side Host using the Session Request Protocol (SRP). The function will return TRUE if the request was successful or FALSE otherwise.

Preconditions

None

Remarks

This function should only be called by a B side Device.

Application Programming Interface (API) > On-The-Go (OTG) > Interface Routines > USBOTGRequestSession Function


USBOTGRoleSwitch Function

Contents | Index | Home
Previous | Up | Next
USBOTGRoleSwitch Function
C
BOOL USBOTGRoleSwitch();
Description

This function returns whether a role switch occurred or not. This is used by the main application function to determine when to reinitialize the system (InitializeSystem())

Preconditions

None

Return Values
Return Values | Description
BOOL | TRUE or FALSE
Remarks

None

Application Programming Interface (API) > On-The-Go (OTG) > Interface Routines > USBOTGRoleSwitch Function


USBOTGSelectRole Function

Contents | Index | Home
Previous | Up | Next
USBOTGSelectRole Function
C
void USBOTGSelectRole(
    BOOL role
);
Description

This function initiates a role switch via the Host Negotiation Protocol (HNP). The parameter role that is passed to this function is the desired role to switch to.

Preconditions

None

Parameters
Parameters | Description
BOOL role | ROLE_DEVICE or ROLE_HOST
Remarks

None

Application Programming Interface (API) > On-The-Go (OTG) > Interface Routines > USBOTGSelectRole Function


USBOTGSession Function

Contents | Index | Home
Previous | Up | Next
USBOTGSession Function
C
BOOL USBOTGSession(
    BYTE Value
);
Description

This function starts, ends, or toggles a VBUS session.

Preconditions

This function assumes I/O controlling DC/DC converter has already been initialized

Parameters
Parameters | Description
Value | START_SESSION, END_SESSION, TOGGLE_SESSION
Return Values
Return Values | Description
TRUE | Session Started, FALSE - Session Not Started
Remarks

This function should only be called by an A-side Host

Application Programming Interface (API) > On-The-Go (OTG) > Interface Routines > USBOTGSession Function


Data Types and Constants

Contents | Index | Home
Previous | Up | Next
Data Types and Constants
Macros
Name | Description
CABLE_A_SIDE | Cable Defines
CABLE_B_SIDE | This is macro CABLE_B_SIDE.
DELAY_TA_AIDL_BDIS | This is macro DELAY_TA_AIDL_BDIS.
DELAY_TA_BDIS_ACON | This is macro DELAY_TA_BDIS_ACON.
DELAY_TA_BIDL_ADIS | 150
DELAY_TA_WAIT_BCON | This is macro DELAY_TA_WAIT_BCON.
DELAY_TA_WAIT_VRISE | This is macro DELAY_TA_WAIT_VRISE.
DELAY_TB_AIDL_BDIS | 100
DELAY_TB_ASE0_BRST | This is macro DELAY_TB_ASE0_BRST.
DELAY_TB_DATA_PLS | This is macro DELAY_TB_DATA_PLS.
DELAY_TB_SE0_SRP | This is macro DELAY_TB_SE0_SRP.
DELAY_TB_SRP_FAIL | This is macro DELAY_TB_SRP_FAIL.
DELAY_VBUS_SETTLE | This is macro DELAY_VBUS_SETTLE.
END_SESSION | This is macro END_SESSION.
OTG_EVENT_CONNECT | This is macro OTG_EVENT_CONNECT.
OTG_EVENT_DISCONNECT | OTG Events
OTG_EVENT_HNP_ABORT | This is macro OTG_EVENT_HNP_ABORT.
OTG_EVENT_HNP_FAILED | This is macro OTG_EVENT_HNP_FAILED.
OTG_EVENT_NONE | This is macro OTG_EVENT_NONE.
OTG_EVENT_RESUME_SIGNALING | This is macro OTG_EVENT_RESUME_SIGNALING.
OTG_EVENT_SRP_CONNECT | This is macro OTG_EVENT_SRP_CONNECT.
OTG_EVENT_SRP_DPLUS_HIGH | This is macro OTG_EVENT_SRP_DPLUS_HIGH.
OTG_EVENT_SRP_DPLUS_LOW | This is macro OTG_EVENT_SRP_DPLUS_LOW.
OTG_EVENT_SRP_FAILED | This is macro OTG_EVENT_SRP_FAILED.
OTG_EVENT_SRP_VBUS_HIGH | This is macro OTG_EVENT_SRP_VBUS_HIGH.
OTG_EVENT_SRP_VBUS_LOW | This is macro OTG_EVENT_SRP_VBUS_LOW.
ROLE_DEVICE | Role Defines
ROLE_HOST | This is macro ROLE_HOST.
START_SESSION | Session Defines
TOGGLE_SESSION | This is macro TOGGLE_SESSION.
USB_OTG_FW_DOT_VER | Firmware version, dot release number.
USB_OTG_FW_MAJOR_VER | Firmware version, major release number.
USB_OTG_FW_MINOR_VER | Firmware version, minor release number.
Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants


CABLE_A_SIDE Macro

Contents | Index | Home
Previous | Up | Next
CABLE_A_SIDE Macro
C
#define CABLE_A_SIDE 0
Description

Cable Defines

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > CABLE_A_SIDE Macro


CABLE_B_SIDE Macro

Contents | Index | Home
Previous | Up | Next
CABLE_B_SIDE Macro
C
#define CABLE_B_SIDE 1
Description

This is macro CABLE_B_SIDE.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > CABLE_B_SIDE Macro


DELAY_TA_AIDL_BDIS Macro

Contents | Index | Home
Previous | Up | Next
DELAY_TA_AIDL_BDIS Macro
C
#define DELAY_TA_AIDL_BDIS 255
Description

This is macro DELAY_TA_AIDL_BDIS.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > DELAY_TA_AIDL_BDIS Macro


DELAY_TA_BDIS_ACON Macro

Contents | Index | Home
Previous | Up | Next
DELAY_TA_BDIS_ACON Macro
C
#define DELAY_TA_BDIS_ACON 1
Description

This is macro DELAY_TA_BDIS_ACON.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > DELAY_TA_BDIS_ACON Macro


DELAY_TA_BIDL_ADIS Macro

Contents | Index | Home
Previous | Up | Next
DELAY_TA_BIDL_ADIS Macro
C
#define DELAY_TA_BIDL_ADIS 10//150
Description

150

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > DELAY_TA_BIDL_ADIS Macro


DELAY_TA_WAIT_BCON Macro

Contents | Index | Home
Previous | Up | Next
DELAY_TA_WAIT_BCON Macro
C
#define DELAY_TA_WAIT_BCON 1100
Description

This is macro DELAY_TA_WAIT_BCON.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > DELAY_TA_WAIT_BCON Macro


DELAY_TA_WAIT_VRISE Macro

Contents | Index | Home
Previous | Up | Next
DELAY_TA_WAIT_VRISE Macro
C
#define DELAY_TA_WAIT_VRISE 100
Description

This is macro DELAY_TA_WAIT_VRISE.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > DELAY_TA_WAIT_VRISE Macro


DELAY_TB_AIDL_BDIS Macro

Contents | Index | Home
Previous | Up | Next
DELAY_TB_AIDL_BDIS Macro
C
#define DELAY_TB_AIDL_BDIS 10 //100
Description

100

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > DELAY_TB_AIDL_BDIS Macro


DELAY_TB_ASE0_BRST Macro

Contents | Index | Home
Previous | Up | Next
DELAY_TB_ASE0_BRST Macro
C
#define DELAY_TB_ASE0_BRST 100
Description

This is macro DELAY_TB_ASE0_BRST.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > DELAY_TB_ASE0_BRST Macro


DELAY_TB_DATA_PLS Macro

Contents | Index | Home
Previous | Up | Next
DELAY_TB_DATA_PLS Macro
C
#define DELAY_TB_DATA_PLS 6
Description

This is macro DELAY_TB_DATA_PLS.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > DELAY_TB_DATA_PLS Macro


DELAY_TB_SE0_SRP Macro

Contents | Index | Home
Previous | Up | Next
DELAY_TB_SE0_SRP Macro
C
#define DELAY_TB_SE0_SRP 2
Description

This is macro DELAY_TB_SE0_SRP.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > DELAY_TB_SE0_SRP Macro


DELAY_TB_SRP_FAIL Macro

Contents | Index | Home
Previous | Up | Next
DELAY_TB_SRP_FAIL Macro
C
#define DELAY_TB_SRP_FAIL 5100
Description

This is macro DELAY_TB_SRP_FAIL.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > DELAY_TB_SRP_FAIL Macro


DELAY_VBUS_SETTLE Macro

Contents | Index | Home
Previous | Up | Next
DELAY_VBUS_SETTLE Macro
C
#define DELAY_VBUS_SETTLE 500
Description

This is macro DELAY_VBUS_SETTLE.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > DELAY_VBUS_SETTLE Macro


END_SESSION Macro

Contents | Index | Home
Previous | Up | Next
END_SESSION Macro
C
#define END_SESSION 1
Description

This is macro END_SESSION.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > END_SESSION Macro


OTG_EVENT_CONNECT Macro

Contents | Index | Home
Previous | Up | Next
OTG_EVENT_CONNECT Macro
C
#define OTG_EVENT_CONNECT 1
Description

This is macro OTG_EVENT_CONNECT.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > OTG_EVENT_CONNECT Macro


OTG_EVENT_DISCONNECT Macro

Contents | Index | Home
Previous | Up | Next
OTG_EVENT_DISCONNECT Macro
C
#define OTG_EVENT_DISCONNECT 0
Description

OTG Events

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > OTG_EVENT_DISCONNECT Macro


OTG_EVENT_HNP_ABORT Macro

Contents | Index | Home
Previous | Up | Next
OTG_EVENT_HNP_ABORT Macro
C
#define OTG_EVENT_HNP_ABORT 8
Description

This is macro OTG_EVENT_HNP_ABORT.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > OTG_EVENT_HNP_ABORT Macro


OTG_EVENT_HNP_FAILED Macro

Contents | Index | Home
Previous | Up | Next
OTG_EVENT_HNP_FAILED Macro
C
#define OTG_EVENT_HNP_FAILED 9
Description

This is macro OTG_EVENT_HNP_FAILED.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > OTG_EVENT_HNP_FAILED Macro


OTG_EVENT_NONE Macro

Contents | Index | Home
Previous | Up | Next
OTG_EVENT_NONE Macro
C
#define OTG_EVENT_NONE 2
Description

This is macro OTG_EVENT_NONE.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > OTG_EVENT_NONE Macro


OTG_EVENT_RESUME_SIGNALING Macro

Contents | Index | Home
Previous | Up | Next
OTG_EVENT_RESUME_SIGNALING Macro
C
#define OTG_EVENT_RESUME_SIGNALING 11
Description

This is macro OTG_EVENT_RESUME_SIGNALING.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > OTG_EVENT_RESUME_SIGNALING Macro


OTG_EVENT_SRP_CONNECT Macro

Contents | Index | Home
Previous | Up | Next
OTG_EVENT_SRP_CONNECT Macro
C
#define OTG_EVENT_SRP_CONNECT 7
Description

This is macro OTG_EVENT_SRP_CONNECT.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > OTG_EVENT_SRP_CONNECT Macro


OTG_EVENT_SRP_DPLUS_HIGH Macro

Contents | Index | Home
Previous | Up | Next
OTG_EVENT_SRP_DPLUS_HIGH Macro
C
#define OTG_EVENT_SRP_DPLUS_HIGH 3
Description

This is macro OTG_EVENT_SRP_DPLUS_HIGH.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > OTG_EVENT_SRP_DPLUS_HIGH Macro


OTG_EVENT_SRP_DPLUS_LOW Macro

Contents | Index | Home
Previous | Up | Next
OTG_EVENT_SRP_DPLUS_LOW Macro
C
#define OTG_EVENT_SRP_DPLUS_LOW 4
Description

This is macro OTG_EVENT_SRP_DPLUS_LOW.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > OTG_EVENT_SRP_DPLUS_LOW Macro


OTG_EVENT_SRP_FAILED Macro

Contents | Index | Home
Previous | Up | Next
OTG_EVENT_SRP_FAILED Macro
C
#define OTG_EVENT_SRP_FAILED 10
Description

This is macro OTG_EVENT_SRP_FAILED.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > OTG_EVENT_SRP_FAILED Macro


OTG_EVENT_SRP_VBUS_HIGH Macro

Contents | Index | Home
Previous | Up | Next
OTG_EVENT_SRP_VBUS_HIGH Macro
C
#define OTG_EVENT_SRP_VBUS_HIGH 5
Description

This is macro OTG_EVENT_SRP_VBUS_HIGH.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > OTG_EVENT_SRP_VBUS_HIGH Macro


OTG_EVENT_SRP_VBUS_LOW Macro

Contents | Index | Home
Previous | Up | Next
OTG_EVENT_SRP_VBUS_LOW Macro
C
#define OTG_EVENT_SRP_VBUS_LOW 6
Description

This is macro OTG_EVENT_SRP_VBUS_LOW.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > OTG_EVENT_SRP_VBUS_LOW Macro


ROLE_DEVICE Macro

Contents | Index | Home
Previous | Up | Next
ROLE_DEVICE Macro
C
#define ROLE_DEVICE 0
Description

Role Defines

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > ROLE_DEVICE Macro


ROLE_HOST Macro

Contents | Index | Home
Previous | Up | Next
ROLE_HOST Macro
C
#define ROLE_HOST 1
Description

This is macro ROLE_HOST.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > ROLE_HOST Macro


START_SESSION Macro

Contents | Index | Home
Previous | Up | Next
START_SESSION Macro
C
#define START_SESSION 0
Description

Session Defines

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > START_SESSION Macro


TOGGLE_SESSION Macro

Contents | Index | Home
Previous | Up | Next
TOGGLE_SESSION Macro
C
#define TOGGLE_SESSION 2
Description

This is macro TOGGLE_SESSION.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > TOGGLE_SESSION Macro


USB_OTG_FW_DOT_VER Macro

Contents | Index | Home
Previous | Up | Next
USB_OTG_FW_DOT_VER Macro
C
#define USB_OTG_FW_DOT_VER 0       // Firmware version, dot release number.
Description

Firmware version, dot release number.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > USB_OTG_FW_DOT_VER Macro


USB_OTG_FW_MAJOR_VER Macro

Contents | Index | Home
Previous | Up | Next
USB_OTG_FW_MAJOR_VER Macro
C
#define USB_OTG_FW_MAJOR_VER 1       // Firmware version, major release number.
Description

Firmware version, major release number.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > USB_OTG_FW_MAJOR_VER Macro


USB_OTG_FW_MINOR_VER Macro

Contents | Index | Home
Previous | Up | Next
USB_OTG_FW_MINOR_VER Macro
C
#define USB_OTG_FW_MINOR_VER 0       // Firmware version, minor release number.
Description

Firmware version, minor release number.

Application Programming Interface (API) > On-The-Go (OTG) > Data Types and Constants > USB_OTG_FW_MINOR_VER Macro


Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.)

Contents | Index | Home
Previous | Next
Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.)
Topics
Name | Description
Using breakpoints in USB host applications | This section describes how to use breakpoints when running a USB host application without causing communication issues.
Bootloader Details | This section covers some of the implementation and usage details about the boot loaders.
Notes on .inf Files | Describes important information about .inf file usage and behavior.
Vendor IDs (VID) and Product IDs (PID) | Describes important information about Vendor IDs (VID) and Product IDs (PID).
Using a diff tool | This section will cover the basics of using a diff tool to compare two different sets of code to evaluate the differences. This section will cover a couple of different tools available and their basic functionality. This section doesn't cover all of the features available in each tool nor does this section cover all of the possible diff tools available.
Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.)


Using breakpoints in USB host applications

Contents | Index | Home
Previous | Up | Next
Using breakpoints in USB host applications

This section describes how to use breakpoints when running a USB host application without causing communication issues.

USB has a periodic packet that is sent on the bus once every millisecond, called the start of frame (SOF) packet, that is used to keep the bus from going into an idle/suspended state. When a the microcontroller hits a breakpoint, both the CPU and the modules on the device stop operation. This will cause the attached USB device to enter the suspend mode. Some programmers implement a method that allows specified peripherals to continue to run even after a breakpoint occurs. This section describes how to enable this feature for the USB peripheral on PIC24F and PIC32 devices.

MPLAB v8.x

1) Select the desired debugger from the debugger menu

2) Go to the “Debugger->Settings” menu option

3) Go to the Freeze on Halt tab. For PIC24F devices, uncheck the UCNFG1 box. For PIC32 devices, uncheck the “All other peripherals” box located below the scrolling menu.

PIC24F

PIC32

MPLAB X

1) In the projects window, right click on the project you are working on and select properties from the menu that appears.

2) In the properties window, select the debugger that you are currently using from the Categories navigation pane.

3) In the resulting form, select "Freeze Peripherals" in the "Option Categories" drop down box.

4) In the resulting list uncheck the box corresponding to the USB peripheral. If there is not one on the list, uncheck "All other peripherals". Please note that on PIC24F the USB module may be named UCNFG1.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Using breakpoints in USB host applications


Bootloader Details

Contents | Index | Home
Previous | Up | Next
Bootloader Details

The detailed descriptions of the boot loader implementations are very part specific. They often involve modified linker scripts and discussions of part specific features and architectural differences (like interrupts and resets). For this reason this section is broken down into sections for each processor product line.

Topics
Name | Description
PIC24F Implementation Specific Details | This section covers the PIC24F product line USB boot loaders.
Important Considerations | There are some important topics that need to be considered when developing an application for a boot loader. This section will cover some of these topics that need to be considered.
Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details


PIC24F Implementation Specific Details

Contents | Index | Home
Previous | Up | Next
PIC24F Implementation Specific Details
Topics
Name | Description
Adding a boot loader to your project | This section covers how to add a boot loader to your application.
Memory Map | This section discusses the various memory regions in the PIC24F device and how they are arranged between the boot loaders and the target applications.
Startup Sequence and Reset Remapping | This section discusses how the device comes out of reset and how the control passes between the boot loader and the application.
Interrupt Remapping | This section discusses how interrupts are handled between the boot loader and application.
Understanding and Customizing the Boot Loader Implementation | This sections discusses the customizations that have been made from the default linker scripts in order to make the boot loader work and how to customize these implementations if you wish to change the behavior or location of the boot loader.
Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > PIC24F Implementation Specific Details


Adding a boot loader to your project

Contents | Index | Home
Previous | Up | Next
Adding a boot loader to your project

The boot loader implementations available in the MCHPFSUSB take a two application approach. What this means is that the boot loader and the application are development, compiled, and loaded separately.

With this approach there are two separate linker scripts that are required, one for the boot loader, and one for the application.

For the PIC24F applications intended to be used with a boot loader, all that is required is to attach the specific linker file designed for the applications of that boot loader to the project.

  • No modifications are required to the linker file. Just attach the provided application linker file to the application project without modification.
  • No modifications are required to the application code. Just write your code as you always would and attach the provided application linker file to the application project without modification.
The required application linker files are found in the folders that contain the targeted boot loaders. These linker files can be referenced directly from the application projects, or can be copied locally to the project folder.

These provided linker files generate the required code to handle the reset and interrupt remapping sections that are required.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > PIC24F Implementation Specific Details > Adding a boot loader to your project


Memory Map

Contents | Index | Home
Previous | Up | Next
Memory Map

The PIC24F boot loaders have several different special memory regions. Some of these regions are defined by the hardware. Others are part of the boot loader implementation and usage. This section discusses what each of these memory regions are. For more information about how these sections are implemented or how to change them, please refer to the Understanding and Customizing the Boot Loader Implementation section.

The different memory regions are shown below:

1) Reset Vector - the reset vector is defined by the hardware. This is located at address 0x0000. Any reset of the CPU will go to the reset vector. The main responsibility of the reset vector is to jump to the code that needs to be run. In the case of the boot loader, this means jumping to the boot loader code (section 4).

2) The interrupt vector table (IVT) is another section that is defined by the PIC24F hardware. The IVT is a fixed set of addresses that specify where the CPU should jump to in the case of an interrupt event. Each interrupt has it's own vector in the table. When that interrupt occurs, the CPU fetches the address in the table corresponding to that interrupt and jumps to that address.

3) The alternate interrupt vector table (AIVT) behaves just like the IVT. The user must set a bit to select if they are using the IVT or AIVT for their interrupt handling. The IVT is the default. For the current boot loader applications, the AIVT is either used by the boot loader or is not remapped to user space so the AIVT is not available for application use.

4) The boot loader code - This section is where the boot loader code resides. This section handles all of the loading of the new application code.

5) User Remapped Reset Vector - This is a section that is defined by the boot loader. The boot loader must always know how to exit to the application on startup. The User Remapped Reset Vector is used as a fixed address that the boot loader can jump to in order to start an application. The application must place code at this address that starts their application. In the PIC24F implementations this is handled by the application linker file.

6) User Remapped Interrupt Vectors - Since the IVT is located in the boot loader space, the boot loader must remap all of the interrupts to the application space. This is done using the User remapped interrupt vectors. The IVT in the boot loader will jump to a specific address in the User remapped interrupt vector. The User remapped interrupt vector table jumps to the interrupt handler code defined in the user code. In the PIC24F implementations this table is generated by the application linker file and doesn't require any user modifications.

7) The user application code - this is the main application code for the project that needs to be loaded by the boot loader. In the PIC24F implementation, only the application linker file for the specific boot loader needs to be added to the project. No other files are required. No changes or additions are required to the user application code either in order to get the code working.

The boot loader and application linker files provided with the MCHPFSUSB enforce all of the memory regions specified above. If an application tries to specify an address outside of the valid range, the user should get a linker error.

Separate linker files are required for the boot loader and the application. These linker files generate the material required for several of the different memory regions in the device. Below is a diagram showing which sections of the final device image are created by the linker files. All of the regions of the device are specified within one of the two linker files. This image merely shows where the content for each of those regions is generated.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > PIC24F Implementation Specific Details > Memory Map


Startup Sequence and Reset Remapping

Contents | Index | Home
Previous | Up | Next
Startup Sequence and Reset Remapping

Before continuing with this section, please review the preceding sections to understand some of the implementation details that aren't discussed in detail in this section. Some of the implementation details of how this works is described the Understanding and Customizing the Boot Loader Implementation section. This section covers the basic flow and how it passes between the boot loader and the application.

In the boot loader implementations provided in MCHPFSUSB library, the boot loader controls the reset vector. This is true for the PIC24F boot loaders as well. The reset vector resides within the boot loader memory space. This means that the boot loader must jump to the target application. This processes in show below in the following diagram and described in the following paragraphs.

1) On PIC24F devices, when a reset occurs the hardware automatically jumps to the reset vector. This is located at address 0x0000. This address resides within the boot loader memory. The compiler/linker for the boot loader code places a 'goto' instruction at the reset vector to the boot loader startup code.

2) The 'goto" instruction at the reset address will jump to the main() function for the boot loader.

3) In the boot loader startup sequence there is a check to determine if the boot loader should run or if the boot loader should jump to the application instead. In the provided examples the code checks a switch to determine if it should remain in the boot loader. If the switch is not pressed then the boot loader jumps to the user_remapped_reset_vector. At this point the control of the processor has just changed from the boot loader to the application.

4) The code at the user_remapped_reset_vector is controlled by the application project, not the boot loader. This vector effectively emulates the behavior that the normal reset vector would if a boot loader wasn't used. In this case it should jump to the startup code for the application. This is done by modified linker script for the application.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > PIC24F Implementation Specific Details > Startup Sequence and Reset Remapping


Interrupt Remapping

Contents | Index | Home
Previous | Up | Next
Interrupt Remapping

Before continuing with this section, please review the preceding sections to understand some of the implementation details that aren't discussed in detail in this section. Some of the implementation details of how this works is described the Understanding and Customizing the Boot Loader Implementation section. This section covers the basic flow and how it passes between the boot loader and the application.

In the boot loader implementations provided in MCHPFSUSB library, the boot loader controls the interrupt vectors for PIC24F devices. The hardware interrupt vector table resides within the boot loader memory space. This means that the boot loader must jump to the appropriate user target application interrupt handler when an interrupt occurs. This processes in show below in the following diagram and described in the following paragraphs.

1) During the course of normal code execution, an interrupt occurs. The CPU vectors to the interrupt vector table (IVT) as described in the appropriate PIC24F datasheet.

2) The IVT is located in boot loader space, but the application needs to handle the interrupt. The boot loader jumps to the correct entry in the User Remapped Interrupt Vector Table. At this point the CPU is jumping from the boot loader memory space to the application memory space and effectively transferring control to the application.

3) At the entry in the User Remapped Interrupt Vector table there is placed a 'goto' instruction that will jump to the appropriate interrupt handler if one is defined in your application and to the default interrupt if there isn't a handler defined. In this way the behavior of the application with or without the boot loader is identical. The User Remapped Interrupt Vector table is created by the application linker file for the specific boot loader in use. This table is automatically generated and doesn't need to be modified. More about how this table is generated can be found in the Understanding and Customizing the Boot Loader Implementation.

4) Finally once the interrupt handler code is complete, the code will return from the interrupt handler. This will return the CPU to the instruction that the interrupt occurred before.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > PIC24F Implementation Specific Details > Interrupt Remapping


Understanding and Customizing the Boot Loader Implementation

Contents | Index | Home
Previous | Up | Next
Understanding and Customizing the Boot Loader Implementation
Topics
Name | Description
Memory Region Definitions | This section describes how each of the memory regions gets defined.
Special Region Creation | This section covers how each of the special memory regions are created/populated within the linker files.
Changing the memory foot print of the boot loader | This section covers how to modify how much memory is used by the boot loader. This can be useful when adding features to the boot loader that increase the size beyond the default example or if a version of the compiler is used that doesn't provide a sufficient level of optimizations to fit the default boot loader.
Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > PIC24F Implementation Specific Details > Understanding and Customizing the Boot Loader Implementation


Memory Region Definitions

Contents | Index | Home
Previous | Up | Next
Memory Region Definitions

First let's take a look how each of the memory regions are defined. The address ranges for each of the regions seen in the diagram below must be defined in either the application linker file or the boot loader linker files.

Below is an excerpt from one of the HID boot loader linker files. This is from the linker script for the boot loader itself so this will be covering sections (1), (2), (3), and (4).

/*
** Memory Regions
*/
MEMORY
{
  data  (a!xr) : ORIGIN = 0x800,         LENGTH = 0x4000
  reset        : ORIGIN = 0x0,           LENGTH = 0x4
  ivt          : ORIGIN = 0x4,           LENGTH = 0xFC
  aivt         : ORIGIN = 0x104,         LENGTH = 0xFC
  program (xr) : ORIGIN = 0x400,         LENGTH = 0x1000
  config4      : ORIGIN = 0x2ABF8,       LENGTH = 0x2
  config3      : ORIGIN = 0x2ABFA,       LENGTH = 0x2
  config2      : ORIGIN = 0x2ABFC,       LENGTH = 0x2
  config1      : ORIGIN = 0x2ABFE,       LENGTH = 0x2
}

The region named "reset" is defined to start at address 0x0 and has a length of 0x4. This means that the first two instructions of the device are used for the reset vector. This is just enough for one 'goto' instruction. This corresponds to hardware implementation and should not be changed. This defines section (1).

Section (2) is the IVT table. This is defined with the "ivt" memory entry. It starts at address 0x4 and is 0xFC bytes long. This corresponds to hardware implementation and should not be changed.

Section (3) is the AIVT table. This is defined with the "aivt" memory entry. It starts at address 0x104 and is 0xFC bytes long. This corresponds to hardware implementation and should not be changed.

Section (4) is the section for the boot loader code. This section is covered by the "program" entry in the memory table. This section starts at address 0x400 and is 0x1000 bytes long in this example (ends at 0x1400). As you can see with this section it has been decreased from the total size of the device to limit the boot loader code to this specific area. This is how the linker knows where the boot loader code is allowed to reside.

Looking in the corresponding application linker file will result in a similar table.

/*
** Memory Regions
*/
MEMORY
{
  data  (a!xr)   : ORIGIN = 0x800,         LENGTH = 0x4000
  reset          : ORIGIN = 0x0,           LENGTH = 0x4
  ivt            : ORIGIN = 0x4,           LENGTH = 0xFC
  aivt           : ORIGIN = 0x104,         LENGTH = 0xFC
  app_ivt        : ORIGIN = 0x1400,        LENGTH = 0x10C
  program (xr)   : ORIGIN = 0x1510,        LENGTH = 0x296E8
  config4        : ORIGIN = 0x2ABF8,       LENGTH = 0x2
  config3        : ORIGIN = 0x2ABFA,       LENGTH = 0x2
  config2        : ORIGIN = 0x2ABFC,       LENGTH = 0x2
  config1        : ORIGIN = 0x2ABFE,       LENGTH = 0x2
}

Note that the "reset", "ivt", and "aivt" sections are all still present in the application linker script. These sections remain here so that applications compiled with the boot loader can be programmed with or without the boot loader. This aids in the development of the application without having to use the boot loader while maintaining identical interrupt latency and memory positioning.

Sections (5) and (6) are created in the special "app_ivt" section. The following discussion topic describes how the content of this section is created. This entry in the memory table is how the space for that area is allocated. Note that the "app_ivt" section starts at address 0x1400 (the same address that the boot loader ended at). Since different parts have different number of interrupts, the size of the "app_ivt" section may change.

The "program" memory section has changed for the application space. It starts at address 0x1510 in this example. This will vary from part to part based on the size of the "app_ivt" section. The "program" memory section corresponds to the user application code (section (7)). Note that it takes up the rest of the memory of the device that is available to load.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > PIC24F Implementation Specific Details > Understanding and Customizing the Boot Loader Implementation > Memory Region Definitions


Special Region Creation

Contents | Index | Home
Previous | Up | Next
Special Region Creation

The Memory Region Definitions section described how each of the memory regions are defined. This allocates the room for each of the memory regions.

This discussion covers how the values of some of the special memory regions are created/populated. Please refer to the earlier sections for an understanding of how the reset and interrupt remapping works before proceeding through this section.

Let's take a look at each of the memory regions in order. Please note that there are two linker scripts, one for the boot loader and one for the application. In order for some of these section definitions to make sense, we will be showing excerpts from either or both of these files for any given section. Please pay close attention to which linker file we are referring to when we show an example.

1) Section (1) is the reset vector. This belongs to the boot loader space so this is located in the boot loader linker file. What we need at the reset vector is a jump to the start of the boot loader code. In the boot loader linker script:

Copy Code
  /*
  ** Reset Instruction
  */
  .reset :
  {
        SHORT(ABSOLUTE(__reset));
        SHORT(0x04);
        SHORT((ABSOLUTE(__reset) >> 16) & 0x7F);
        SHORT(0);
  } >reset

The code in this section generates a "goto __reset" instruction located in the "reset" memory section. This will cause the CPU to jump to the boot loader startup code after any device reset. This is common code that is present in any default linker script for PIC24F.

2) The second section is the IVT. In the IVT we need to jump to the user's remapped IVT table.

Copy Code
__APP_IVT_BASE = 0x1400;
.ivt __IVT_BASE :
  {
    LONG(ABSOLUTE(__APP_IVT_BASE) + 0x004); /* __ReservedTrap0*/
    LONG(ABSOLUTE(__APP_IVT_BASE) + 0x008); /* __OscillatorFail*/
    LONG(ABSOLUTE(__APP_IVT_BASE) + 0x00C); /* __AddressError*/
    LONG(ABSOLUTE(__APP_IVT_BASE) + 0x010); /* __StackError*/
    LONG(ABSOLUTE(__APP_IVT_BASE) + 0x014); /* __MathError*/
...
    LONG(ABSOLUTE(__DEFAULT_VECTOR)); /* __Interrupt116 not implemented */
    LONG(ABSOLUTE(__DEFAULT_VECTOR)); /* __Interrupt117 not implemented */
  } >ivt

This linker code will place the _APP_IVT_BASE constant + an offset address at each of the IVT vector entries. This will cause the CPU to jump to the specified vector in the user's remapped IVT table.

Note that each entry is 4 bytes away from the previous entry. Is is because the resulting remapped IVT will need to use "goto" instructions at each entry in order to reach the desired handler. The "goto" instruction takes two instruction words at 2 bytes of memory address each.

3) Section (3), the AIVT, is either not used or is used by the boot loader and shouldn't be used by the application. If the boot loader requires interrupts, then it uses the AIVT and switches to AIVT interrupts before starting and switches back to the IVT before jumping to the customer code. No linker modifications are required here. For boot loaders that don't require interrupts, some have the AIVT section removed since they are not remapped to the user space and not used by the boot loader.

4) Section (4), the boot loader code - the only modification required in the linker script for the boot loader code is the changes to the memory region definitions discussed previously in the Memory Region Definitions section.

5) Section (5) is the user remapped reset. This is the address where the boot loader jumps upon completion. This address needs to be at a fixed location in code that both the boot loader and the application know about. At this address there needs to be a jump to the user application code. In the application linker script:

Copy Code
  .application_ivt __APP_IVT_BASE :
  {
    SHORT(ABSOLUTE(__reset)); SHORT(0x04); SHORT((ABSOLUTE(__reset) >> 16) & 0x7F); SHORT(0);
    SHORT(DEFINED(__ReservedTrap0) ? ABSOLUTE(__ReservedTrap0) : ABSOLUTE(__DefaultInterrupt));  SHORT(0x04);  SHORT(DEFINED(__ReservedTrap0) ? (ABSOLUTE(__ReservedTrap0) >> 16) & 0x7F : (ABSOLUTE(__DefaultInterrupt) >> 16) & 0x7F);  SHORT(0);
    SHORT(DEFINED(__OscillatorFail) ? ABSOLUTE(__OscillatorFail) : ABSOLUTE(__DefaultInterrupt));  SHORT(0x04);  SHORT(DEFINED(__OscillatorFail) ? (ABSOLUTE(__OscillatorFail) >> 16) & 0x7F : (ABSOLUTE(__DefaultInterrupt) >> 16) & 0x7F);  SHORT(0);
    SHORT(DEFINED(__AddressError) ? ABSOLUTE(__AddressError) : ABSOLUTE(__DefaultInterrupt));  SHORT(0x04);  SHORT(DEFINED(__AddressError) ? (ABSOLUTE(__AddressError) >> 16) & 0x7F : (ABSOLUTE(__DefaultInterrupt) >> 16) & 0x7F);  SHORT(0);

This section of code has been added to the default linker script. This creates a section in code located at __APP_IVT_BASE address. In this case the __APP_IVT_BASE address is also defined in the application linker file:

Copy Code
__APP_IVT_BASE = 0x1400;

This address must match exactly between the boot loader code, boot loader linker file, and the application linker file. If any of these do not match then the linkage between the interrupt remapping or reset remapping will not work and the application will fail to run properly.

The first entry in this table is the user remapped reset. This code generates a "goto __reset" at address __APP_IVT_BASE. This allows the boot loader to jump to this fixed address to then jump to the start of the user code (located at the __reset label).

6) Section (6) is the remapped IVT table. This section allows the interrupt to be remapped from the boot loader space to the application space. In order to do this the boot loader must either know the exact address of every interrupt handler, or must have another jump table that it jumps to in order to redirect it to the correct interrupt handler. The second approach is the one used in the implemented boot loaders. This is implemented in the following table:

  .application_ivt __APP_IVT_BASE :
  {
    SHORT(ABSOLUTE(__reset)); SHORT(0x04); SHORT((ABSOLUTE(__reset) >> 16) & 0x7F); SHORT(0);
    SHORT(DEFINED(__ReservedTrap0) ? ABSOLUTE(__ReservedTrap0) : ABSOLUTE(__DefaultInterrupt));  SHORT(0x04);  SHORT(DEFINED(__ReservedTrap0) ? (ABSOLUTE(__ReservedTrap0) >> 16) & 0x7F : (ABSOLUTE(__DefaultInterrupt) >> 16) & 0x7F);  SHORT(0);
    SHORT(DEFINED(__OscillatorFail) ? ABSOLUTE(__OscillatorFail) : ABSOLUTE(__DefaultInterrupt));  SHORT(0x04);  SHORT(DEFINED(__OscillatorFail) ? (ABSOLUTE(__OscillatorFail) >> 16) & 0x7F : (ABSOLUTE(__DefaultInterrupt) >> 16) & 0x7F);  SHORT(0);
    SHORT(DEFINED(__AddressError) ? ABSOLUTE(__AddressError) : ABSOLUTE(__DefaultInterrupt));  SHORT(0x04);  SHORT(DEFINED(__AddressError) ? (ABSOLUTE(__AddressError) >> 16) & 0x7F : (ABSOLUTE(__DefaultInterrupt) >> 16) & 0x7F);  SHORT(0);

This first entry in the table is the remapped reset vector that we just discussed. The second entry in the table is the first possible interrupt. In this case it is the ReservedTrap0 interrupt. This line of linker code will look for the __ReservedTrap0 interrupt function. If it exists it will insert a "goto __ReservedTrap0" at the second address in this table. If it doesn't find the __ReservedTrap0 function, it will put a "goto __DefaultInterrupt" at this entry in the table. In this way just by defining the appropriate interrupt handler function in the application code, the linker will automatically create the jump table entry .required.

Looking at an example application_ivt table as generated by the linker script where the ReservedTrap0 interrupt is not defined and the OscillatorFail and AddressError handlers are defined, starting at address _APP_IVT_BASE you will have the following entries in program memory:

goto __reset

goto __DefaultInterrupt

goto __OscillatorFail

goto __AddressError

...

7) Section (7), the user application code - the only modification to the linker script required for the application code is the changes to the memory region definitions discussed previously in the Memory Region Definitions section.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > PIC24F Implementation Specific Details > Understanding and Customizing the Boot Loader Implementation > Special Region Creation


Changing the memory foot print of the boot loader

Contents | Index | Home
Previous | Up | Next
Changing the memory foot print of the boot loader

This section covers how to modify how much memory is used by the boot loader. This can be useful when adding features to the boot loader that increase the size beyond the default example or if a version of the compiler is used that doesn't provide a sufficient level of optimizations to fit the default boot loader.

Each boot loader has different memory sections and implementations so there is a section covering each boot loader individually. Please refer to the section corresponding to the boot loader in question.

Topics
Name | Description
HID boot loader | This section covers how to modify the size of the HID boot loader.
MSD boot loader | This section covers how to modify the size of the MSD boot loader.
Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > PIC24F Implementation Specific Details > Understanding and Customizing the Boot Loader Implementation > Changing the memory foot print of the boot loader


HID boot loader

Contents | Index | Home
Previous | Up | Next
HID boot loader

This section covers how to modify the size of the HID boot loader. This can be useful when adding features to the boot loader that increase the size beyond the default example or if a version of the compiler is used that doesn't provide a sufficient level of optimizations to fit the default boot loader. The boot loaders provided by default assume full optimizations and may not work with compilers that don't have access to full optimizations.

Please read all of the other topics in the PIC24F boot loader section before proceeding in this topic. This topic will show where the modifications need to be made and how they need to match up, but will not describe what the sections that are being modified are or how they are implemented. This information is in previous sections.

There are three places that require corresponding changes: the boot loader linker script, the application linker script, and the boot loader code. You may wish to make copies of the original files so that you preserve the original non-modified files.

In the following examples we will be increasing the size of the boot loader from 0x1400 to 0x2400 in length.

First start by determining the size that you want the boot loader to be. This must be a multiple of an erase page. On many PIC24F devices there is a 512 instruction word erase page (1024 addresses per page). Please insure that the address you select for the end of the boot loader corresponds to a page boundary. There are several ways to determine the size of the boot loader application. Below is an example of one method.

1) Remove the boot loader linker script provided if it is causing link errors due either to optimization settings or added code.

2) Build the project

3) Open the memory window and find the last non-blank address in the program memory space.

4) Find the next flash erase page address after this address. Add any additional buffer room that you might want for future boot loader development, growth, or changes. Use this address as your new boot loader end address.

Once the end address of the boot loader is known, start by modifying the boot loader linker script program memory region to match that change. The boot loader linker script can either be found in the folder containing the boot loader project file or in a folder that is specified for boot loader linker scripts. In the linker script find the memory regions.

Copy Code
MEMORY
{
  data  (a!xr) : ORIGIN = 0x800,         LENGTH = 0x4000
  reset        : ORIGIN = 0x0,           LENGTH = 0x4
  ivt          : ORIGIN = 0x4,           LENGTH = 0xFC
  aivt         : ORIGIN = 0x104,         LENGTH = 0xFC
  program (xr) : ORIGIN = 0x400,         LENGTH = 0x2000
  config4      : ORIGIN = 0x2ABF8,       LENGTH = 0x2
  config3      : ORIGIN = 0x2ABFA,       LENGTH = 0x2
  config2      : ORIGIN = 0x2ABFC,       LENGTH = 0x2
  config1      : ORIGIN = 0x2ABFE,       LENGTH = 0x2
}

Change the LENGTH field of the program memory section to match the new length. Note that this is length and not the end address. To get the end address, please add LENGTH + ORIGIN.

Next, locate the __APP_IVT_BASE definition in the linker file. Change this to equal the end address of your boot loader.

Copy Code
__APP_IVT_BASE = 0x2400;

Once the length of the boot loader is changed, you will need to make similar changes in the application boot loader linker script. The application boot loader linker scripts are typically found in a folder with the boot loader project. In the application linker file, locate the memory regions section. In this section there are three items that need to change.

  1. The first is the ORIGIN of the app_ivt section. This needs to be modified to match the new end address of the boot loader.
  2. Second, move the ORIGIN of the program memory section to the ORIGIN of app_ivt + the LENGTH of the app_ivt section so that the program memory starts immediately after the app_ivt section.
  3. Last, change the LENGTH field of the program section so that it goes to the end of the program memory of the device. Remember that the LENGTH field is the length starting from the origin and not the end address. An easy way to make sure that this address is correct is by just subtracting off from the LENGTH the same amount that was added to the ORIGIN.

Copy Code
MEMORY
{
  data  (a!xr)   : ORIGIN = 0x800,         LENGTH = 0x4000
  reset          : ORIGIN = 0x0,           LENGTH = 0x4
  ivt            : ORIGIN = 0x4,           LENGTH = 0xFC
  aivt           : ORIGIN = 0x104,         LENGTH = 0xFC
  app_ivt        : ORIGIN = 0x2400,        LENGTH = 0x110
  program (xr)   : ORIGIN = 0x2510,        LENGTH = 0x286E8
  config4        : ORIGIN = 0x2ABF8,       LENGTH = 0x2
  config3        : ORIGIN = 0x2ABFA,       LENGTH = 0x2
  config2        : ORIGIN = 0x2ABFC,       LENGTH = 0x2
  config1        : ORIGIN = 0x2ABFE,       LENGTH = 0x2
}

The final changes that needs to be made are in the boot loader code itself. Open up the boot loader project.

  1. Find the ProgramMemStart definition in the main.c file. Change the start address to match the new address.

Copy Code
#define ProgramMemStart                    0x00002400

  2. Next find the #ifdef section that applies to the device that you are working with. This section will contain definitions used by the boot loader to determine what memory is should erase and re-write.

Copy Code
#if defined(__PIC24FJ256GB110__) || defined(__PIC24FJ256GB108__) || defined(__PIC24FJ256GB106__)
    #define BeginPageToErase             5          //Bootloader and vectors occupy first six 1024 word (1536 bytes due to 25% unimplemented bytes) pages
    #define MaxPageToEraseNoConfigs      169        //Last full page of flash on the PIC24FJ256GB110, which does not contain the flash configuration words.
    #define MaxPageToEraseWithConfigs    170        //Page 170 contains the flash configurations words on the PIC24FJ256GB110.  Page 170 is also smaller than the rest of the (1536 byte) pages.
    #define ProgramMemStopNoConfigs      0x0002A800 //Must be instruction word aligned address.  This address does not get updated, but the one just below it does:
                                                    //IE: If AddressToStopPopulating = 0x200, 0x1FF is the last programmed address (0x200 not programmed)
    #define ProgramMemStopWithConfigs    0x0002ABF8 //Must be instruction word aligned address.  This address does not get updated, but the one just below it does: IE: If AddressToStopPopulating = 0x200, 0x1FF is the last programmed address (0x200 not programmed)
    #define ConfigWordsStartAddress      0x0002ABF8 //0x2ABFA is start of CW3 on PIC24FJ256GB110 Family devices
    #define ConfigWordsStopAddress       0x0002AC00

  3. Modify the BeginPageToErase to indicate which page is the first page it should erase. This will be the ProgramMemStart/Page Size. In this case we are starting at 0x2400 and each page is 0x400 so this should now be 9.

Copy Code
    #define BeginPageToErase             9

  4. Locate the start of the main() function. In the first few lines of code there is a check to determine of the code should stay in the boot loader or jump to the application code. Change the address in the "goto" statement to match the new end of the boot loader and start of the application.

Copy Code
__asm__("goto 0x2400");

This should be all of the changes required in order to change the size of the HID boot loader.

Please note that since the boot loader and the application code are developed as two separate applications, they do not need to use the same optimization settings.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > PIC24F Implementation Specific Details > Understanding and Customizing the Boot Loader Implementation > Changing the memory foot print of the boot loader > HID boot loader


MSD boot loader

Contents | Index | Home
Previous | Up | Next
MSD boot loader

This section covers how to modify the size of the MSD boot loader. This can be useful when adding features to the boot loader that increase the size beyond the default example or if a version of the compiler is used that doesn't provide a sufficient level of optimizations to fit the default boot loader. The boot loaders provided by default assume full optimizations and may not work with compilers that don't have access to full optimizations.

Please read all of the other topics in the PIC24F boot loader section before proceeding in this topic. This topic will show where the modifications need to be made and how they need to match up, but will not describe what the sections that are being modified are or how they are implemented. This information is in previous sections.

There are three places that require corresponding changes: the boot loader linker script, the application linker script, and the boot loader code. You may wish to make copies of the original files so that you preserve the original non-modified files.

In the following examples we will be increasing the size of the boot loader from 0xA000 to 0xC000.

First start by determining the size that you want the boot loader to be. This must be a multiple of an erase page. On many PIC24F devices there is a 512 instruction word erase page (1024 addresses per page). Please insure that the address you select for the end of the boot loader corresponds to a page boundary. There are several ways to determine the size of the boot loader application. Below is an example of one method.

1) Remove the boot loader linker script provided if it is causing link errors due either to optimization settings or added code.

2) Build the project

3) Open the memory window and find the last non-blank address in the program memory space.

4) Find the next flash erase page address after this address. Add any additional buffer room that you might want for future boot loader development, growth, or changes. Use this address as your new boot loader end address.

Once the end address of the boot loader is known, start by modifying the boot loader linker script program memory region to match that change. The boot loader linker script can either be found in the folder containing the boot loader project file or in a folder that is specified for boot loader linker scripts. In the linker script find the memory regions.

MEMORY
{
  data  (a!xr) : ORIGIN = 0x800,         LENGTH = 0x4000
  reset        : ORIGIN = 0x0,           LENGTH = 0x4
  ivt          : ORIGIN = 0x4,           LENGTH = 0xFC
  aivt         : ORIGIN = 0x104,         LENGTH = 0xFC
  program (xr) : ORIGIN = 0x400,         LENGTH = 0xBC00
  config4      : ORIGIN = 0x2ABF8,       LENGTH = 0x2
  config3      : ORIGIN = 0x2ABFA,       LENGTH = 0x2
  config2      : ORIGIN = 0x2ABFC,       LENGTH = 0x2
  config1      : ORIGIN = 0x2ABFE,       LENGTH = 0x2
}

Change the LENGTH field of the program memory section to match the new length. Note that this is length and not the end address. To get the end address, please add LENGTH + ORIGIN.

Next, locate the __APP_IVT_BASE definition in the linker file. Change this to equal the end address of your boot loader.

__APP_IVT_BASE = 0xC000;

Once the length of the boot loader is changed, you will need to make similar changes in the application boot loader linker script. The application boot loader linker scripts are typically found in a folder with the boot loader project. In the application linker file, locate the memory regions section. In this section there are three items that need to change.

  1. The first is the ORIGIN of the app_ivt section. This needs to be modified to match the new end address of the boot loader.
  2. Second, move the ORIGIN of the program memory section to the ORIGIN of app_ivt + the LENGTH of the app_ivt section so that the program memory starts immediately after the app_ivt section.
  3. Last, change the LENGTH field of the program section so that it goes to the end of the program memory of the device. Remember that the LENGTH field is the length starting from the origin and not the end address. An easy way to make sure that this address is correct is by just subtracting off from the LENGTH the same amount that was added to the ORIGIN.

MEMORY
{
  data  (a!xr)   : ORIGIN = 0x800,         LENGTH = 0x4000
  reset          : ORIGIN = 0x0,           LENGTH = 0x4
  ivt            : ORIGIN = 0x4,           LENGTH = 0xFC
  aivt           : ORIGIN = 0x104,         LENGTH = 0xFC
  app_ivt        : ORIGIN = 0xC000,        LENGTH = 0x110
  program (xr)   : ORIGIN = 0xC110,        LENGTH = 0x1EAE8
  config4        : ORIGIN = 0x2ABF8,       LENGTH = 0x2
  config3        : ORIGIN = 0x2ABFA,       LENGTH = 0x2
  config2        : ORIGIN = 0x2ABFC,       LENGTH = 0x2
  config1        : ORIGIN = 0x2ABFE,       LENGTH = 0x2
}

The final changes that needs to be made are in the boot loader code itself. Open up the boot loader project.

  1. Find the processor section in boot_config.h that applies to the processor that you are using. This section should contain a definition APPLICATION_ADDRESS. This address indicates the address where the user application reset vector resides. Change this address to match the new user reset address.

#define APPLICATION_ADDRESS         0xC000ul

  2. Next find the PROGRAM_FLASH_BASE. This address specifies the starting address of memory where the device will start to erase and reprogram. Please make sure to make this address at the start of an erase page on the device.

#define PROGRAM_FLASH_BASE          0xC000ul

  3. Next modify the PROGRAM_FLASH_LENGTH to match the new flash length. This length specifies the number of bytes starting from the PROGRAM_FLASH_BASE that is valid for the application.

#define PROGRAM_FLASH_LENGTH        0x1EB00

This should be all of the changes required in order to change the size of the HID boot loader.

Please note that since the boot loader and the application code are developed as two separate applications, they do not need to use the same optimization settings.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > PIC24F Implementation Specific Details > Understanding and Customizing the Boot Loader Implementation > Changing the memory foot print of the boot loader > MSD boot loader


Important Considerations

Contents | Index | Home
Previous | Up | Next
Important Considerations
Topics
Name | Description
Configuration Bits | This section covers some topics related to configuration bits.
Boot Loader Entry | This section covers topics related to boot loader entry.
Interrupts | This section covers some topics related to interrupts.
Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > Important Considerations


Configuration Bits

Contents | Index | Home
Previous | Up | Next
Configuration Bits
Matching configuration bits between application and boot loader

While the code code space of the application and the boot loader are separate, they both must run on the same device. As such they both use the same configuration bits. Some boot loaders are able to update configuration bits. Others are not. If the boot loader is able to load configuration bits, the application designer should be careful to select a setting that works for both the application as well as the boot loader. It is possible to change the configuration bits into a setting that isn't compatible with the boot loader.

For example: if the boot loader wasn't design to handle a watch dog timer (doesn't clear the watch dog timer) and the application enables the watch dog timer through the configuration bits, it is possible that the boot loader will never be able to load a new set of code again because it gets a watch dog timer event before the loading of a file is complete.

The previous example is just one of many ways that changes in configuration bits by the loaded application files can be dangerous to future use of the boot loader. Caution should be used when changing the configuration bits if the boot loader enables that feature.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > Important Considerations > Configuration Bits


Boot Loader Entry

Contents | Index | Home
Previous | Up | Next
Boot Loader Entry

While some applications it is desirable to enter the boot loader after starting the application, designers should consider have a mechanism to enter the boot loader without jumping to the application in case of an application failure.

Example: An application wants to run and when the user selects that they want to load a new firmware, they go to the boot loader. If there is a power failure during the loading process it is possible that there isn't a valid application image that will run successfully. If there isn't a mechanism to detect this failure or a method to enter the boot loader directly without going to the application, then this device could be rendered useless.

Even if the main method of boot loader entry is directly from the application, a secondary method that doesn't require an application should be considered for such circumstances.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > Important Considerations > Boot Loader Entry


Interrupts

Contents | Index | Home
Previous | Up | Next
Interrupts
PIC24F

Because the interrupts must be remapped from the the IVT to the application space, there is additional latency from the time that the interrupt is generated to the time that the first line in the interrupt handler is executed. There is one additional inserted "goto" instruction resulting in a 2 cycle increased interrupt latency.

Note that the provided application linker files allow projects built for the PIC24F boot loaders to be either programmed or boot loaded. In both cases the interrupt latency and memory organization are identical allowing users to develop their application without having to use the boot loader but having identical performance and memory usage as if they were using the boot loader.

The PIC24F boot loaders only remap the main interrupt vector table (IVT). They don't remap the alternate interrupt vector table (AIVT). Please see the PIC24F Implementation details for more information.

PIC32MX

The PIC32MX processor has a programmable interrupt vector table address, both the boot loader and the application projects can have their own interrupt vector tables. The boot loader and application code vector from their interrupt tables directly thus there are no special requirements or changes in latency for the PIC32MX family while using the USB boot loaders.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Bootloader Details > Important Considerations > Interrupts


Notes on .inf Files

Contents | Index | Home
Previous | Up | Next
Notes on .inf Files

Upon initially plugging in a USB device, in some cases Windows will prompt the user for a driver. Rather than having users manually copy .sys files (driver binary files) into important system directories (such as within the “\Windows\system32\” directory structure) and manually add registry entries, Windows automates the driver installation process through the use of .INF files. INF files are plain text (can be edited with notepad) installation instruction script files.

Some types of USB devices will not require .INF files or user provided drivers (for example, a HID class mouse). For these types of devices, the operating system makes use of drivers already built into/distributed with the operating system, so no user provided driver or .INF file is necessary.

For other types of devices, Windows will prompt the user for a driver. In these cases, point Windows to the .INF file relevant for the USB device. All of the example projects included in the MCHPFSUSB framework which need an INF file are provided with an example INF file. The INF file will need slight modification (most importantly to change the VID and PID) before commercial distribution.

The INF file for the custom demo can be found in <Install Directory>\USB Tools\MCHPUSB Custom Driver\MCHPUSB Driver\Release.

The INF file for the CDC demos can be found in <Install Directory>\USB Tools\USB CDC Serial Demo\inf\win2k_winxp.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Notes on .inf Files


Vendor IDs (VID) and Product IDs (PID)

Contents | Index | Home
Previous | Up | Next
Vendor IDs (VID) and Product IDs (PID)

Every USB product line must have a unique combination of VID and PID. All firmware examples use Microchip's VID (0x04d8) and a unique PID. Prior to manufacturing and marketing a new USB product, the VID and PID need to be changed. New VID and PID numbers can be obtained by purchasing a VID from the USB Implementers Forum:

http://www.usb.org/developers/vendor

Alternatively, Microchip has a free VID sublicensing program. An application form for obtaining a PID (for use with Microchip’s VID: 0x04d8) from Microchip can be obtained by clicking here for the direct link.

Once a new VID/PID combination is obtained, both the firmware and the .INF file (when applicable) will need to be updated.

To modify the VID/PID in one of the example USB firmware projects, open the usb_descriptors.c file (found in each of the demo folders). They should appear in the table used for the USB Device Descriptor. Change both values as needed.

To modify the VID/PID in the .INF file, open the relevant INF file and search for the “[DeviceList]” sections. There are two sections, one for 32-bit and one for 64-bit, both sections should be identical. In these sections, some text will appear with the form “USB\VID_xxxx&PID_yyyy”. Update the “xxxx” and “yyyy” sections with the new hexadecimal format VID/PID values.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Vendor IDs (VID) and Product IDs (PID)


Using a diff tool

Contents | Index | Home
Previous | Up | Next
Using a diff tool

This section will cover the basics of using a diff tool to compare two different sets of code to evaluate the differences. This section will cover a couple of different tools available and their basic functionality. This section doesn't cover all of the features available in each tool nor does this section cover all of the possible diff tools available.

Topics
Name | Description
Beyond Compare | Beyond Compare is a commercial available differencing software from Scooter Software, Inc (http://www.scootersoftware.com/). This demonstration is based on Beyond Compare v2.2.7. There may be interface or features changes in other versions of this software. Please refer to the software's documentation for a more detailed and updated description of the functionality. Creating a comparison There are a couple of ways to create a comparison with Beyond Compare. The first is to open the Beyond Compare program from the Start menu. This opens a window that allows you to either compare two files or two folders. Beyond compare also has a right... more
MPLAB X (NetBeans) | MPLAB X (NetBeans) is an open source IDE that has built in differencing functionality ( [image] www.microchip.com/mplabx and [image] http://netbeans.org/). This demonstration is based on NetBeans v6.5.1 but also applies to MPLAB X beta 7.02. There may be interface or features changes in other versions of this software. Please refer to the software's documentation for a more detailed and updated description of the functionality. Creating a comparison To compare two files in MPLAB X (NetBeans), one of the files must first be opened. This can be done using the "File->Open File" menu option. Once one file is open, right click on... more
Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Using a diff tool


Beyond Compare

Contents | Index | Home
Previous | Up | Next
Beyond Compare

Beyond Compare is a commercial available differencing software from Scooter Software, Inc (http://www.scootersoftware.com/).

This demonstration is based on Beyond Compare v2.2.7. There may be interface or features changes in other versions of this software. Please refer to the software's documentation for a more detailed and updated description of the functionality.

Creating a comparison

There are a couple of ways to create a comparison with Beyond Compare. The first is to open the Beyond Compare program from the Start menu. This opens a window that allows you to either compare two files or two folders.

Beyond compare also has a right click menu option that allows the user to right click on two files and compare them to each other.

When two files are compared together, the differences between the two files are highlighted. On the left of the main windows there is also a difference navigation bar that shows where the differences are in the file. You can click on this bar to go to that location in the code.

Moving changes

Once a difference between two files is detected, it is easy to move that change from one file to the other. In Beyond Compare simply highlight the lines that need to move, and click on the "Copy to other side" button that is shown below.

Comparing Folders

A feature of Beyond Compare is that it allows you to compare two folders against each other. Once two folders are selected in the program (or through the right-click menu option discussed before), the folders are compared against each other. At this point of time the contents of the folders aren't compared to see if they are different, just if the files are present or not.

Double clicking on a file will open a file difference instance showing the difference between the two files.

To compare all of the contents against each other you can select all of the files by expanding all of the folders,

selecting all of the files,

and running the file comparison tool.

To see only files that are different, select the "Only mismatch" from the comparison tool.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Using a diff tool > Beyond Compare


MPLAB X (NetBeans)

Contents | Index | Home
Previous | Up | Next
MPLAB X (NetBeans)

MPLAB X (NetBeans) is an open source IDE that has built in differencing functionality ( [image] www.microchip.com/mplabx and [image] http://netbeans.org/).

This demonstration is based on NetBeans v6.5.1 but also applies to MPLAB X beta 7.02. There may be interface or features changes in other versions of this software. Please refer to the software's documentation for a more detailed and updated description of the functionality.

Creating a comparison

To compare two files in MPLAB X (NetBeans), one of the files must first be opened. This can be done using the "File->Open File" menu option.

Once one file is open, right click on the tab with the file name. In this menu there should be a "Diff to..." option that is available.

This option will open a new file window. In this file window select the file that you want to compare against. Once this file is selected the two files will sit side by side. On the right hand side of the window there is a difference navigation bar. By clicking on any of these highlighted sections, it will bring you to the difference in the two files.

Moving changes

Changes in MPLAB X (NetBeans) are always made from the left file to the right file. If the files were opened in the opposite order as the changes that need to be made, you can click the "Swap" button that is just above both of the two files. This will exchange the position of the two files.

To move a change, click on the icon that is near the center bar between the differences. An arrow "->" indicator on the left window indicates that the changes in that section will be moved from the left file to the right file. An "X" found on the right file in a green section indicates that the source found in that section will be deleted when you click the "X".

Please note that changes made to the files via the MPLAB X (NetBeans) comparison tool may be final. You may not be able to undo these effects to please use caution when making changes.

Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.) > Using a diff tool > MPLAB X (NetBeans)


Trademark Information

Contents | Index | Home
Previous
Trademark Information

The Microchip name and logo, the Microchip logo, MPLAB, and PIC are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries.

PICDEM and PICTail are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries.

Microsoft, Windows, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

SD is a trademark of the SD Association in the U.S.A and other countries

Trademark Information


Contents

Contents | Index | Home
Contents
Introduction
Software License Agreement
Release Notes
What's New
What's Next
Support
Online Reference and Resources
Demo Board Support and Limitations
Operating System Support and Limitations
Tool Information
Revision History
v2.9e
v2.9d
v2.9c
v2.9b
v2.9a
v2.9
v2.8
v2.7a
v2.7
Library Migration
From v2.9d to v2.9e
From v2.9c to v2.9d
From v2.9b to v2.9c
From v2.9a to v2.9b
From v2.9 to v2.9a
From v2.8 to v2.9
From v2.7a to v2.8
From v2.7 to v2.7a
From v2.6a to v2.7
From v2.6 to v2.6a
From v2.5 to v2.6
Demos
Device - Audio Microphone Basic Demo
Supported Demo Boards
Configuring the Hardware
Running the Demo
Device - Audio MIDI Demo
Supported Demo Boards
Configuring the Hardware
Running the Demo
Garage Band '08 [Macintosh Computers]
Using Linux MultiMedia Studio (LMMS) [Linux and Windows Computers]
Device - Audio Speaker Demo
Supported Demo Boards
Configuring the Hardware
Running the Demo
Device - Boot Loader - HID
Supported Demo Boards
Configuring the Demo
Running the Demo
Implementation and Customization Details
Configuration Bits
Vendor ID (VID) and Product ID (PID)
Part Specific Details
PIC18F
PIC24F
Device - Boot Loader - MCHPUSB
Supported Demo Boards
Configuring the Demo
Running the Demo
Implementation and Customization Details
Device - CCID Smart Card Reader
Supported Demo Boards
Configuring the Hardware
Running the Demo
Device - CDC Basic Demo
Supported Demo Boards
Configuring the Hardware
Running the Demo
Device - CDC - Serial Emulator
Supported Demo Boards
Configuring the Demo
Running the Demo
Device - Composite - HID + MSD Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Device - Composite - MSD + CDC Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Device - Composite - WinUSB + MSD Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Device - HID - Custom Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Device - HID - Digitizer Demos
Supported Demo Boards
Configuring the Hardware
Running the Demo
Device - HID - Joystick Demo
Supported Demo Boards
Configuring the Hardware
Running the Demo
Device - HID - Keyboard Demo
Supported Demo Boards
Configuring the Hardware
Running the Demo
Device - HID - Mouse Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Device - HID - Uninterruptible Power Supply
Supported Demo Boards
Configuring the Demo
Running the Demo
Device - LibUSB Generic Driver Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Windows
Linux
Android 3.1+
Device - Mass Storage - Internal Flash Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Troubleshooting
Device - Mass Storage - SD Card Data Logger
Supported Demo Boards
Configuring the Demo
Running the Demo
Device - Mass Storage - SD Card Reader
Supported Demo Boards
Configuring the Demo
Running the Demo
Device - MCHPUSB Generic Driver Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Installing Windows Drivers
PDFSUSB
MCHPUSB PnP Demo
Running the Demo (Android v3.1+)
Device - Personal Healthcare Device Class (PHDC) Demo
Supported Demo Boards
Configuring the Demo
Running the PHDC Blood Pressure Monitor Demo
Running the PHDC Glucose Meter Demo
Running the PHDC Themometer Demo
Running the PHDC Weigh Scale Demo
Performing the Continua Precertification Tests
Device - WinUSB Generic Driver Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Windows
Android v3.1+
Device - WinUSB High Bandwidth Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Dual Role - MSD Host + HID Device
Supported Demo Boards
Configuring the Demo
Running the Demo
Host - Audio MIDI Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Host - Boot Loader - Thumb Drive Boot Loader
Supported Demo Boards
Configuring the Demo
Running the Demo
Creating a Hex File to Load
Customizing the Boot Loader and Target Application Linker Scripts for PIC32 devices
Host - CDC Serial Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Host - Charger - Simple Charger
Supported Demo Boards
Configuring the Demo
Running the Demo
Host - Composite - MSD+ CDC
Supported Demo Boards
Configuring the Demo
Running the Demo
Host - Composite - HID + MSD
Supported Demo Boards
Configuring the Demo
Running the Demo
Host - HID - Keyboard Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Host - HID - Mouse Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Host - Mass Storage (MSD) - Simple Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Host - Mass Storage - Thumb Drive Data Logger
Supported Demo Boards
Configuring the Demo
Running the Demo
Host - MCHPUSB - Generic Driver Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Host - Printer - Print Screen Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Host - Printer - Simple Full Sheet
Supported Demo Boards
Configuring the Demo
Running the demo
Host - Printer - Simple Point of Sale (POS)
Supported Demo Boards
Configuring the Demo
Running the Demo
Loading a precompiled demo
MPLAB 8
PC - WM_DEVICECHANGE Demo
OTG - MCHPUSB Device/MCHPUSB Host Demo
Supported Demo Boards
Configuring the Demo
Running the Demo
Demo Board Information
Low Pin Count USB Development Board
PICDEM FS USB Board
PIC18F46J50 Plug-In-Module (PIM)
PIC18F47J53 Plug-In-Module (PIM)
PIC18F87J50 Plug-In-Module (PIM) Demo Board
PIC18 Starter Kit
PIC24FJ64GB004 Plug-In-Module (PIM)
PIC24FJ64GB502 Microstick
PIC24FJ256GB110 Plug-In-Module (PIM)
PIC24FJ256GB210 Plug-In-Module (PIM)
PIC24FJ256DA210 Development Board
PIC24F Starter Kit
PIC24EP512GU810 Plug-In-Module (PIM)
dsPIC33EP512MU810 Plug-In-Module (PIM)
PIC32MX460F512L Plug-In-Module (PIM)
PIC32MX795F512L Plug-In-Module (PIM)
PIC32 USB Starter Kit
PIC32 USB Starter Kit II
USB PICTail Plus Daughter Board
Explorer 16
PC Tools and Example Code
Application Programming Interface (API)
Stack Configuration
Device/Peripheral
Device Stack
Configuration Options
usb_config.h
Ping Pong buffering (USB_PING_PONG_MODE)
Endpoint 0 size (USB_EP0_BUFF_SIZE)
Endpoints Used (USB_MAX_EP_NUMBER)
Interface mode (USB_POLLING or USB_INTERRUPT)
Speed selection (USB_SPEED_OPTION)
D+/D- Internal Pull-ups (USB_PULLUP_OPTION)
Device Mode Enable (USB_SUPPORT_DEVICE)
Transceiver Option (USB_TRANSCEIVER_OPTION)
Number of Interfaces (USB_MAX_NUM_INT)
Status Stage Timout Enable (USB_ENABLE_STATUS_STAGE_TIMEOUTS and USB_STATUS_STAGE_TIMEOUT)
String Descriptor Array size (USB_NUM_STRING_DESCRIPTORS)
Event Notifications
Disable DTS checking (USB_DEVICE_DISABLE_DTS_CHECKING)
Interface Routines
USB_APPLICATION_EVENT_HANDLER Function
USBCancelIO Function
USBCtrlEPAllowDataStage Function
USBCtrlEPAllowStatusStage Function
USBDeferINDataStage Function
USBDeferOUTDataStage Function
USBDeferStatusStage Function
USBDeviceAttach Function
USBDeviceDetach Function
USBDeviceInit Function
USBDeviceTasks Function
USBEnableEndpoint Function
USBEP0Receive Function
USBEP0SendRAMPtr Function
USBEP0SendROMPtr Function
USBEP0Transmit Function
USBGetDeviceState Function
USBGetNextHandle Function
USBGetRemoteWakeupStatus Function
USBGetSuspendState Function
USBHandleBusy Function
USBHandleGetAddr Function
USBHandleGetLength Function
USBINDataStageDeferred Function
USBIsBusSuspended Function
USBIsDeviceSuspended Function
USBRxOnePacket Function
USBSoftDetach Function
USBOUTDataStageDeferred Function
USBStallEndpoint Function
USBTransferOnePacket Function
USBTxOnePacket Function
Data Types and Constants
USB_DEVICE_STATE Enumeration
USB_DEVICE_STACK_EVENTS Enumeration
USB_EP0_BUSY Macro
USB_EP0_INCLUDE_ZERO Macro
USB_EP0_NO_DATA Macro
USB_EP0_NO_OPTIONS Macro
USB_EP0_RAM Macro
USB_EP0_ROM Macro
USB_HANDLE Macro
Macros
DESC_CONFIG_BYTE Macro
DESC_CONFIG_DWORD Macro
DESC_CONFIG_WORD Macro
Audio Function Driver
Interface Routines
USBCheckAudioRequest Function
Data Types and Constants
CCID (Smart/Sim Card) Function Driver
Interface Routines
USBCCIDBulkInService Function
USBCCIDInitEP Function
USBCCIDSendDataToHost Function
USBCheckCCIDRequest Function
CDC Function Driver
Interface Routines
CDCInitEP Function
CDCTxService Function
getsUSBUSART Function
putrsUSBUSART Function
putsUSBUSART Function
putUSBUSART Function
USBCheckCDCRequest Function
CDCSetBaudRate Macro
CDCSetCharacterFormat Macro
CDCSetDataSize Macro
CDCSetLineCoding Macro
CDCSetParity Macro
USBUSARTIsTxTrfReady Macro
Data Types and Constants
NUM_STOP_BITS_1 Macro
NUM_STOP_BITS_1_5 Macro
NUM_STOP_BITS_2 Macro
PARITY_EVEN Macro
PARITY_MARK Macro
PARITY_NONE Macro
PARITY_ODD Macro
PARITY_SPACE Macro
HID Function Driver
Interface Routines
HIDRxHandleBusy Macro
HIDRxPacket Macro
HIDTxHandleBusy Macro
HIDTxPacket Macro
Data Types and Constants
BOOT_INTF_SUBCLASS Macro
BOOT_PROTOCOL Macro
HID_PROTOCOL_KEYBOARD Macro
HID_PROTOCOL_MOUSE Macro
HID_PROTOCOL_NONE Macro
MSD Function Driver
Interface Routines
MSDTasks Function
USBCheckMSDRequest Function
USBMSDInit Function
Data Types and Constants
LUN_FUNCTIONS Type
Personal Healthcare Device Class (PHDC) Function Driver
Interface Routines
PHDAppInit Function
PHDSendAppBufferPointer Function
PHDConnect Function
PHDDisConnect Function
PHDSendMeasuredData Function
PHDTimeoutHandler Function
USBDevicePHDCInit Function
USBDevicePHDCReceiveData Function
USBDevicePHDCSendData Function
USBDevicePHDCTxRXService Function
USBDevicePHDCCheckRequest Function
USBDevicePHDCUpdateStatus Function
Vendor Class (Generic) Function Driver
Interface Routines
USBGenRead Macro
USBGenWrite Macro
Embedded Host API
Embedded Host Stack
Interface Routines
USB_HOST_APP_EVENT_HANDLER Function
USBHostClearEndpointErrors Function
USBHostDeviceSpecificClientDriver Function
USBHostDeviceStatus Function
USBHostGetCurrentConfigurationDescriptor Macro
USBHostGetDeviceDescriptor Macro
USBHostGetStringDescriptor Macro
USBHostInit Function
USBHostRead Function
USBHostResetDevice Function
USBHostResumeDevice Function
USBHostSetDeviceConfiguration Function
USBHostSetNAKTimeout Function
USBHostSuspendDevice Function
USBHostTerminateTransfer Function
USBHostTransferIsComplete Function
USBHostVbusEvent Function
USBHostWrite Function
Data Types and Constants
CLIENT_DRIVER_TABLE Structure
HOST_TRANSFER_DATA Structure
TRANSFER_ATTRIBUTES Union
USB_TPL Structure
USB_CLIENT_INIT Type
USB_CLIENT_EVENT_HANDLER Type
USB_NUM_BULK_NAKS Macro
USB_NUM_COMMAND_TRIES Macro
USB_NUM_CONTROL_NAKS Macro
USB_NUM_ENUMERATION_TRIES Macro
USB_NUM_INTERRUPT_NAKS Macro
TPL_SET_CONFIG Macro
TPL_CLASS_DRV Macro
TPL_ALLOW_HNP Macro
Macros
INIT_CL_SC_P Macro
INIT_VID_PID Macro
Audio Client Driver
Interface Routines
USBHostAudioV1DataEventHandler Function
USBHostAudioV1EventHandler Function
USBHostAudioV1Initialize Function
USBHostAudioV1ReceiveAudioData Function
USBHostAudioV1SetInterfaceFullBandwidth Function
USBHostAudioV1SetInterfaceZeroBandwidth Function
USBHostAudioV1SetSamplingFrequency Function
USBHostAudioV1SupportedFrequencies Function
USBHostAudioV1TerminateTransfer Function
Data Types and Constants
EVENT_AUDIO_ATTACH Macro
EVENT_AUDIO_DETACH Macro
EVENT_AUDIO_FREQUENCY_SET Macro
EVENT_AUDIO_INTERFACE_SET Macro
EVENT_AUDIO_NONE Macro
EVENT_AUDIO_OFFSET Macro
EVENT_AUDIO_STREAM_RECEIVED Macro
Audio MIDI Client Driver
Interface Functions
USBHostMIDIDeviceDetached Macro
USBHostMIDIEndpointDirection Macro
USBHostMIDINumberOfEndpoints Macro
USBHostMIDIRead Function
USBHostMIDISizeOfEndpoint Macro
USBHostMIDITransferIsBusy Macro
USBHostMIDITransferIsComplete Function
USBHostMIDIWrite Function
Data Types and Constants
EVENT_MIDI_ATTACH Macro
EVENT_MIDI_DETACH Macro
EVENT_MIDI_OFFSET Macro
EVENT_MIDI_TRANSFER_DONE Macro
Android Accessory Client Driver
Interface Routines
AndroidAppIsReadComplete Function
AndroidAppIsWriteComplete Function
AndroidAppRead Function
AndroidAppStart Function
AndroidAppWrite Function
AndroidTasks Function
Data Type and Constants
ANDROID_ACCESSORY_INFORMATION Structure
Macros
ANDROID_BASE_OFFSET Macro
EVENT_ANDROID_ATTACH Macro
EVENT_ANDROID_DETACH Macro
NUM_ANDROID_DEVICES_SUPPORTED Macro
USB_ERROR_BUFFER_TOO_SMALL Macro
ANDROID_INIT_FLAG_BYPASS_PROTOCOL Macro
Internal Members
CDC Client Driver
Interface Routines
USBHostCDC_Api_ACM_Request Function
USBHostCDC_Api_Get_IN_Data Function
USBHostCDC_ApiTransferIsComplete Function
USBHostCDCDeviceStatus Function
USBHostCDCEventHandler Function
USBHostCDCInitAddress Function
USBHostCDCInitialize Function
USBHostCDCRead_DATA Macro
USBHostCDCResetDevice Function
USBHostCDCSend_DATA Macro
USBHostCDCTransfer Function
USBHostCDCTransferIsComplete Function
Data Types and Constants
COMM_INTERFACE_DETAILS Structure
DATA_INTERFACE_DETAILS Structure
USB_CDC_ACM_FN_DSC Structure
USB_CDC_CALL_MGT_FN_DSC Structure
USB_CDC_CONTROL_SIGNAL_BITMAP Union
USB_CDC_DEVICE_INFO Structure
USB_CDC_HEADER_FN_DSC Structure
USB_CDC_LINE_CODING Union
USB_CDC_UNION_FN_DSC Structure
DEVICE_CLASS_CDC Macro
EVENT_CDC_COMM_READ_DONE Macro
EVENT_CDC_COMM_WRITE_DONE Macro
EVENT_CDC_DATA_READ_DONE Macro
EVENT_CDC_DATA_WRITE_DONE Macro
EVENT_CDC_NAK_TIMEOUT Macro
EVENT_CDC_NONE Macro
EVENT_CDC_OFFSET Macro
EVENT_CDC_RESET Macro
USB_CDC_ABSTRACT_CONTROL_MODEL Macro
USB_CDC_ATM_NETWORKING_CONTROL_MODEL Macro
USB_CDC_CAPI_CONTROL_MODEL Macro
USB_CDC_CLASS_ERROR Macro
USB_CDC_COMM_INTF Macro
USB_CDC_COMMAND_FAILED Macro
USB_CDC_COMMAND_PASSED Macro
USB_CDC_CONTROL_LINE_LENGTH Macro
USB_CDC_CS_ENDPOINT Macro
USB_CDC_CS_INTERFACE Macro
USB_CDC_DATA_INTF Macro
USB_CDC_DEVICE_BUSY Macro
USB_CDC_DEVICE_DETACHED Macro
USB_CDC_DEVICE_HOLDING Macro
USB_CDC_DEVICE_MANAGEMENT Macro
USB_CDC_DEVICE_NOT_FOUND Macro
USB_CDC_DIRECT_LINE_CONTROL_MODEL Macro
USB_CDC_DSC_FN_ACM Macro
USB_CDC_DSC_FN_CALL_MGT Macro
USB_CDC_DSC_FN_COUNTRY_SELECTION Macro
USB_CDC_DSC_FN_DLM Macro
USB_CDC_DSC_FN_HEADER Macro
USB_CDC_DSC_FN_RPT_CAPABILITIES Macro
USB_CDC_DSC_FN_TEL_OP_MODES Macro
USB_CDC_DSC_FN_TELEPHONE_RINGER Macro
USB_CDC_DSC_FN_UNION Macro
USB_CDC_DSC_FN_USB_TERMINAL Macro
USB_CDC_ETHERNET_EMULATION_MODEL Macro
USB_CDC_ETHERNET_NETWORKING_CONTROL_MODEL Macro
USB_CDC_GET_COMM_FEATURE Macro
USB_CDC_GET_ENCAPSULATED_REQUEST Macro
USB_CDC_GET_LINE_CODING Macro
USB_CDC_ILLEGAL_REQUEST Macro
USB_CDC_INITIALIZING Macro
USB_CDC_INTERFACE_ERROR Macro
USB_CDC_LINE_CODING_LENGTH Macro
USB_CDC_MOBILE_DIRECT_LINE_MODEL Macro
USB_CDC_MULTI_CHANNEL_CONTROL_MODEL Macro
USB_CDC_NO_PROTOCOL Macro
USB_CDC_NO_REPORT_DESCRIPTOR Macro
USB_CDC_NORMAL_RUNNING Macro
USB_CDC_OBEX Macro
USB_CDC_PHASE_ERROR Macro
USB_CDC_REPORT_DESCRIPTOR_BAD Macro
USB_CDC_RESET_ERROR Macro
USB_CDC_RESETTING_DEVICE Macro
USB_CDC_SEND_BREAK Macro
USB_CDC_SEND_ENCAPSULATED_COMMAND Macro
USB_CDC_SET_COMM_FEATURE Macro
USB_CDC_SET_CONTROL_LINE_STATE Macro
USB_CDC_SET_LINE_CODING Macro
USB_CDC_TELEPHONE_CONTROL_MODEL Macro
USB_CDC_V25TER Macro
USB_CDC_WIRELESS_HANDSET_CONTROL_MODEL Macro
Charger Client Driver
Interface Routines
USBHostChargerDeviceDetached Function
USBHostChargerEventHandler Function
USBHostChargerGetDeviceAddress Function
Data Type and Constants
EVENT_CHARGER_ATTACH Macro
EVENT_CHARGER_DETACH Macro
EVENT_CHARGER_OFFSET Macro
USB_MAX_CHARGING_DEVICES Macro
Generic Client Driver
Interface Routines
USBHostGenericDeviceDetached Macro
USBHostGenericEventHandler Function
USBHostGenericGetDeviceAddress Function
USBHostGenericGetRxLength Macro
USBHostGenericInit Function
USBHostGenericRead Function
USBHostGenericRxIsBusy Macro
USBHostGenericRxIsComplete Function
USBHostGenericTxIsBusy Macro
USBHostGenericTxIsComplete Function
USBHostGenericWrite Function
Data Types and Constants
GENERIC_DEVICE Type
GENERIC_DEVICE_ID Type
EVENT_GENERIC_ATTACH Macro
EVENT_GENERIC_DETACH Macro
EVENT_GENERIC_OFFSET Macro
EVENT_GENERIC_RX_DONE Macro
EVENT_GENERIC_TX_DONE Macro
USB_GENERIC_EP Macro
HID Client Driver
Interface Routines
USBHostHID_ApiFindBit Function
USBHostHID_ApiFindValue Function
USBHostHID_ApiGetCurrentInterfaceNum Function
USBHostHID_ApiGetReport Macro
USBHostHID_ApiImportData Function
USBHostHID_ApiSendReport Macro
USBHostHID_ApiTransferIsComplete Macro
USBHostHID_GetCurrentReportInfo Macro
USBHostHID_GetItemListPointers Macro
USBHostHID_HasUsage Function
USBHostHIDDeviceDetect Function
USBHostHIDDeviceStatus Function
USBHostHIDEventHandler Function
USBHostHIDInitialize Function
USBHostHIDRead Macro
USBHostHIDResetDevice Function
USBHostHIDResetDeviceWithWait Function
USBHostHIDTasks Function
USBHostHIDTerminateTransfer Function
USBHostHIDTransfer Function
USBHostHIDTransferIsComplete Function
USBHostHIDWrite Macro
Data Types and Constants
DEVICE_CLASS_HID Macro
DSC_HID Macro
DSC_PHY Macro
DSC_RPT Macro
EVENT_HID_ATTACH Macro
EVENT_HID_BAD_REPORT_DESCRIPTOR Macro
EVENT_HID_DETACH Macro
EVENT_HID_NONE Macro
EVENT_HID_OFFSET Macro
EVENT_HID_READ_DONE Macro
EVENT_HID_RESET Macro
EVENT_HID_RESET_ERROR Macro
EVENT_HID_RPT_DESC_PARSED Macro
EVENT_HID_WRITE_DONE Macro
HID_COLLECTION Structure
HID_DATA_DETAILS Structure
HID_DESIGITEM Structure
HID_GLOBALS Structure
HID_ITEM_INFO Structure
HID_REPORT Structure
HID_REPORTITEM Structure
HID_STRINGITEM Structure
HID_TRANSFER_DATA Structure
HID_USAGEITEM Structure
HIDReportTypeEnum Enumeration
USB_HID_CLASS_ERROR Macro
USB_HID_COMMAND_FAILED Macro
USB_HID_COMMAND_PASSED Macro
USB_HID_DEVICE_BUSY Macro
USB_HID_DEVICE_DETACHED Macro
USB_HID_DEVICE_HOLDING Macro
USB_HID_DEVICE_ID Structure
USB_HID_DEVICE_NOT_FOUND Macro
USB_HID_DEVICE_RPT_INFO Structure
USB_HID_ILLEGAL_REQUEST Macro
USB_HID_INITIALIZING Macro
USB_HID_INTERFACE_ERROR Macro
USB_HID_ITEM_LIST Structure
USB_HID_NO_REPORT_DESCRIPTOR Macro
USB_HID_NORMAL_RUNNING Macro
USB_HID_PHASE_ERROR Macro
USB_HID_REPORT_DESCRIPTOR_BAD Macro
USB_HID_RESET_ERROR Macro
USB_HID_RESETTING_DEVICE Macro
USB_HID_RPT_DESC_ERROR Enumeration
USB_PROCESSING_REPORT_DESCRIPTOR Macro
Mass Storage Client Driver
Interface Routines
USBHostMSDDeviceStatus Function
USBHostMSDEventHandler Function
USBHostMSDInitialize Function
USBHostMSDRead Macro
USBHostMSDResetDevice Function
USBHostMSDSCSIEventHandler Function
USBHostMSDSCSIInitialize Function
USBHostMSDSCSISectorRead Function
USBHostMSDSCSISectorWrite Function
USBHostMSDTerminateTransfer Function
USBHostMSDTransfer Function
USBHostMSDTransferIsComplete Function
USBHostMSDWrite Macro
Data Types and Constants
DEVICE_CLASS_MASS_STORAGE Macro
DEVICE_INTERFACE_PROTOCOL_BULK_ONLY Macro
DEVICE_SUBCLASS_CD_DVD Macro
DEVICE_SUBCLASS_FLOPPY_INTERFACE Macro
DEVICE_SUBCLASS_RBC Macro
DEVICE_SUBCLASS_REMOVABLE Macro
DEVICE_SUBCLASS_SCSI Macro
DEVICE_SUBCLASS_TAPE_DRIVE Macro
EVENT_MSD_MAX_LUN Macro
EVENT_MSD_NONE Macro
EVENT_MSD_OFFSET Macro
EVENT_MSD_RESET Macro
EVENT_MSD_TRANSFER Macro
MSD_COMMAND_FAILED Macro
MSD_COMMAND_PASSED Macro
MSD_PHASE_ERROR Macro
USB_MSD_CBW_ERROR Macro
USB_MSD_COMMAND_FAILED Macro
USB_MSD_COMMAND_PASSED Macro
USB_MSD_CSW_ERROR Macro
USB_MSD_DEVICE_BUSY Macro
USB_MSD_DEVICE_DETACHED Macro
USB_MSD_DEVICE_NOT_FOUND Macro
USB_MSD_ERROR Macro
USB_MSD_ERROR_STATE Macro
USB_MSD_ILLEGAL_REQUEST Macro
USB_MSD_INITIALIZING Macro
USB_MSD_INVALID_LUN Macro
USB_MSD_MEDIA_INTERFACE_ERROR Macro
USB_MSD_NORMAL_RUNNING Macro
USB_MSD_OUT_OF_MEMORY Macro
USB_MSD_PHASE_ERROR Macro
USB_MSD_RESET_ERROR Macro
USB_MSD_RESETTING_DEVICE Macro
Printer Client Driver
Interface Routines
PrintScreen Function
USBHostPrinterCommand Function
USBHostPrinterCommandReady Function
USBHostPrinterCommandWithReadyWait Macro
USBHostPrinterDeviceDetached Function
USBHostPrinterEventHandler Function
USBHostPrinterGetRxLength Function
USBHostPrinterGetStatus Function
USBHostPrinterInitialize Function
USBHostPrinterLanguageESCPOS Function
USBHostPrinterLanguageESCPOSIsSupported Function
USBHostPrinterLanguagePCL5 Function
USBHostPrinterLanguagePCL5IsSupported Function
USBHostPrinterLanguagePostScript Function
USBHostPrinterLanguagePostScriptIsSupported Function
USBHostPrinterPOSImageDataFormat Function
USBHostPrinterPosition Macro
USBHostPrinterPositionRelative Macro
USBHostPrinterRead Function
USBHostPrinterReset Function
USBHostPrinterRxIsBusy Function
USBHostPrinterWrite Function
USBHostPrinterWriteComplete Function
Data Types and Constants
_USB_HOST_PRINTER_PRIMITIVES_H Macro
BARCODE_CODE128_CODESET_A_CHAR Macro
BARCODE_CODE128_CODESET_A_STRING Macro
BARCODE_CODE128_CODESET_B_CHAR Macro
BARCODE_CODE128_CODESET_B_STRING Macro
BARCODE_CODE128_CODESET_C_CHAR Macro
BARCODE_CODE128_CODESET_C_STRING Macro
BARCODE_CODE128_CODESET_CHAR Macro
BARCODE_CODE128_CODESET_STRING Macro
BARCODE_TEXT_12x24 Macro
BARCODE_TEXT_18x36 Macro
BARCODE_TEXT_ABOVE Macro
BARCODE_TEXT_ABOVE_AND_BELOW Macro
BARCODE_TEXT_BELOW Macro
BARCODE_TEXT_OMIT Macro
EVENT_PRINTER_ATTACH Macro
EVENT_PRINTER_DETACH Macro
EVENT_PRINTER_OFFSET Macro
EVENT_PRINTER_REQUEST_DONE Macro
EVENT_PRINTER_REQUEST_ERROR Macro
EVENT_PRINTER_RX_DONE Macro
EVENT_PRINTER_RX_ERROR Macro
EVENT_PRINTER_TX_DONE Macro
EVENT_PRINTER_TX_ERROR Macro
EVENT_PRINTER_UNSUPPORTED Macro
LANGUAGE_ID_STRING_ESCPOS Macro
LANGUAGE_ID_STRING_PCL Macro
LANGUAGE_ID_STRING_POSTSCRIPT Macro
LANGUAGE_SUPPORT_FLAGS_ESCPOS Macro
LANGUAGE_SUPPORT_FLAGS_PCL3 Macro
LANGUAGE_SUPPORT_FLAGS_PCL5 Macro
LANGUAGE_SUPPORT_FLAGS_POSTSCRIPT Macro
PRINTER_COLOR_BLACK Macro
PRINTER_COLOR_WHITE Macro
PRINTER_DEVICE_REQUEST_GET_DEVICE_ID Macro
PRINTER_DEVICE_REQUEST_GET_PORT_STATUS Macro
PRINTER_DEVICE_REQUEST_SOFT_RESET Macro
PRINTER_FILL_CROSS_HATCHED Macro
PRINTER_FILL_HATCHED Macro
PRINTER_FILL_SHADED Macro
PRINTER_FILL_SOLID Macro
PRINTER_LINE_END_BUTT Macro
PRINTER_LINE_END_ROUND Macro
PRINTER_LINE_END_SQUARE Macro
PRINTER_LINE_JOIN_BEVEL Macro
PRINTER_LINE_JOIN_MITER Macro
PRINTER_LINE_JOIN_ROUND Macro
PRINTER_LINE_TYPE_DASHED Macro
PRINTER_LINE_TYPE_DOTTED Macro
PRINTER_LINE_TYPE_SOLID Macro
PRINTER_LINE_WIDTH_NORMAL Macro
PRINTER_LINE_WIDTH_THICK Macro
PRINTER_PAGE_LANDSCAPE_HEIGHT Macro
PRINTER_PAGE_LANDSCAPE_WIDTH Macro
PRINTER_PAGE_PORTRAIT_HEIGHT Macro
PRINTER_PAGE_PORTRAIT_WIDTH Macro
PRINTER_POS_BOTTOM_TO_TOP Macro
PRINTER_POS_DENSITY_HORIZONTAL_DOUBLE Macro
PRINTER_POS_DENSITY_HORIZONTAL_SINGLE Macro
PRINTER_POS_DENSITY_VERTICAL_24 Macro
PRINTER_POS_DENSITY_VERTICAL_8 Macro
PRINTER_POS_LEFT_TO_RIGHT Macro
PRINTER_POS_RIGHT_TO_LEFT Macro
PRINTER_POS_TOP_TO_BOTTOM Macro
USB_DATA_POINTER Union
USB_DATA_POINTER_RAM Macro
USB_DATA_POINTER_ROM Macro
USB_MAX_PRINTER_DEVICES Macro
USB_NULL Macro
USB_PRINT_SCREEN_INFO Structure
USB_PRINTER_COMMAND Enumeration
USB_PRINTER_DEVICE_ID Structure
USB_PRINTER_ERRORS Enumeration
USB_PRINTER_FONTS Enumeration
USB_PRINTER_FONTS_POS Enumeration
USB_PRINTER_FUNCTION_SUPPORT Union
USB_PRINTER_FUNCTION_SUPPORT_POS Macro
USB_PRINTER_FUNCTION_SUPPORT_VECTOR_GRAPHICS Macro
USB_PRINTER_GRAPHICS_PARAMETERS Union
USB_PRINTER_IMAGE_INFO Structure
USB_PRINTER_INTERFACE Structure
USB_PRINTER_LANGUAGE_HANDLER Type
USB_PRINTER_LANGUAGE_SUPPORTED Type
USB_PRINTER_POS_BARCODE_FORMAT Enumeration
USB_PRINTER_SPECIFIC_INTERFACE Structure
USB_PRINTER_TRANSFER_COPY_DATA Macro
USB_PRINTER_TRANSFER_FROM_RAM Macro
USB_PRINTER_TRANSFER_FROM_ROM Macro
USB_PRINTER_TRANSFER_NOTIFY Macro
USB_PRINTER_TRANSFER_STATIC_DATA Macro
USBHOSTPRINTER_SETFLAG_COPY_DATA Macro
USBHOSTPRINTER_SETFLAG_NOTIFY Macro
USBHOSTPRINTER_SETFLAG_STATIC_DATA Macro
On-The-Go (OTG)
Interface Routines
USBOTGClearRoleSwitch Function
USBOTGCurrentRoleIs Function
USBOTGDefaultRoleIs Function
USBOTGInitialize Function
USBOTGRequestSession Function
USBOTGRoleSwitch Function
USBOTGSelectRole Function
USBOTGSession Function
Data Types and Constants
CABLE_A_SIDE Macro
CABLE_B_SIDE Macro
DELAY_TA_AIDL_BDIS Macro
DELAY_TA_BDIS_ACON Macro
DELAY_TA_BIDL_ADIS Macro
DELAY_TA_WAIT_BCON Macro
DELAY_TA_WAIT_VRISE Macro
DELAY_TB_AIDL_BDIS Macro
DELAY_TB_ASE0_BRST Macro
DELAY_TB_DATA_PLS Macro
DELAY_TB_SE0_SRP Macro
DELAY_TB_SRP_FAIL Macro
DELAY_VBUS_SETTLE Macro
END_SESSION Macro
OTG_EVENT_CONNECT Macro
OTG_EVENT_DISCONNECT Macro
OTG_EVENT_HNP_ABORT Macro
OTG_EVENT_HNP_FAILED Macro
OTG_EVENT_NONE Macro
OTG_EVENT_RESUME_SIGNALING Macro
OTG_EVENT_SRP_CONNECT Macro
OTG_EVENT_SRP_DPLUS_HIGH Macro
OTG_EVENT_SRP_DPLUS_LOW Macro
OTG_EVENT_SRP_FAILED Macro
OTG_EVENT_SRP_VBUS_HIGH Macro
OTG_EVENT_SRP_VBUS_LOW Macro
ROLE_DEVICE Macro
ROLE_HOST Macro
START_SESSION Macro
TOGGLE_SESSION Macro
USB_OTG_FW_DOT_VER Macro
USB_OTG_FW_MAJOR_VER Macro
USB_OTG_FW_MINOR_VER Macro
Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.)
Using breakpoints in USB host applications
Bootloader Details
PIC24F Implementation Specific Details
Adding a boot loader to your project
Memory Map
Startup Sequence and Reset Remapping
Interrupt Remapping
Understanding and Customizing the Boot Loader Implementation
Memory Region Definitions
Special Region Creation
Changing the memory foot print of the boot loader
HID boot loader
MSD boot loader
Important Considerations
Configuration Bits
Boot Loader Entry
Interrupts
Notes on .inf Files
Vendor IDs (VID) and Product IDs (PID)
Using a diff tool
Beyond Compare
MPLAB X (NetBeans)
Trademark Information


Index

Contents | Index | Home
Index
_ | A | B | C | D | E | F | G | H | I | L | M | N | O | P | R | S | T | U | V | W
_
_CLIENT_DRIVER_TABLE structure
_COMM_INTERFACE_DETAILS structure
_DATA_INTERFACE_DETAILS structure
_HID_COLLECTION structure
_HID_DATA_DETAILS structure
_HID_GLOBALS structure
_HID_ITEM_INFO structure
_HID_REPORT structure
_HID_REPORTITEM structure
_HID_STRINGITEM structure
_HID_TRANSFER_DATA structure
_HID_USAGEITEM structure
_HOST_TRANSFER_DATA structure
_USB_CDC_ACM_FN_DSC structure
_USB_CDC_CALL_MGT_FN_DSC structure
_USB_CDC_CONTROL_SIGNAL_BITMAP union
_USB_CDC_DEVICE_INFO structure
_USB_CDC_HEADER_FN_DSC structure
_USB_CDC_LINE_CODING union
_USB_CDC_UNION_FN_DSC structure
_USB_HID_DEVICE_ID structure
_USB_HID_DEVICE_RPT_INFO structure
_USB_HID_ITEM_LIST structure
_USB_HOST_PRINTER_PRIMITIVES_H macro
_USB_PRINTER_DEVICE_ID structure
_USB_TPL structure
A
Adding a boot loader to your project
Android 3.1+
Android Accessory Client Driver
Android v3.1+
ANDROID_ACCESSORY_INFORMATION structure
ANDROID_BASE_OFFSET macro
ANDROID_INIT_FLAG_BYPASS_PROTOCOL macro
AndroidAppIsReadComplete function
AndroidAppIsWriteComplete function
AndroidAppRead function
AndroidAppStart function
AndroidAppWrite function
AndroidTasks function
Appendix (Frequently Asked Questions, Important Information, Reference Material, etc.)
Application Programming Interface (API)
Audio Client Driver
Audio Function Driver
Audio MIDI Client Driver
B
BARCODE_CODE128_CODESET_A_CHAR macro
BARCODE_CODE128_CODESET_A_STRING macro
BARCODE_CODE128_CODESET_B_CHAR macro
BARCODE_CODE128_CODESET_B_STRING macro
BARCODE_CODE128_CODESET_C_CHAR macro
BARCODE_CODE128_CODESET_C_STRING macro
BARCODE_CODE128_CODESET_CHAR macro
BARCODE_CODE128_CODESET_STRING macro
BARCODE_TEXT_12x24 macro
BARCODE_TEXT_18x36 macro
BARCODE_TEXT_ABOVE macro
BARCODE_TEXT_ABOVE_AND_BELOW macro
BARCODE_TEXT_BELOW macro
BARCODE_TEXT_OMIT macro
Beyond Compare
Boot Loader Entry
BOOT_INTF_SUBCLASS macro
BOOT_PROTOCOL macro
Bootloader Details
C
CABLE_A_SIDE macro
CABLE_B_SIDE macro
CCID (Smart/Sim Card) Function Driver
CDC Client Driver
CDC Function Driver
CDCInitEP function
CDCSetBaudRate macro
CDCSetCharacterFormat macro
CDCSetDataSize macro
CDCSetLineCoding macro
CDCSetParity macro
CDCTxService function
Changing the memory foot print of the boot loader
Charger Client Driver
CLIENT_DRIVER_TABLE structure
COMM_INTERFACE_DETAILS structure
Configuration Bits
Configuration Options
Configuring the Demo
Configuring the Hardware
Creating a Hex File to Load
Customizing the Boot Loader and Target Application Linker Scripts for PIC32 devices
D
D+/D- Internal Pull-ups (USB_PULLUP_OPTION)
Data Type and Constants
Data Types and Constants
DATA_INTERFACE_DETAILS structure
DELAY_TA_AIDL_BDIS macro
DELAY_TA_BDIS_ACON macro
DELAY_TA_BIDL_ADIS macro
DELAY_TA_WAIT_BCON macro
DELAY_TA_WAIT_VRISE macro
DELAY_TB_AIDL_BDIS macro
DELAY_TB_ASE0_BRST macro
DELAY_TB_DATA_PLS macro
DELAY_TB_SE0_SRP macro
DELAY_TB_SRP_FAIL macro
DELAY_VBUS_SETTLE macro
Demo Board Information
Demo Board Support and Limitations
Demos
DESC_CONFIG_BYTE macro
DESC_CONFIG_DWORD macro
DESC_CONFIG_WORD macro
Device - Audio Microphone Basic Demo
Device - Audio MIDI Demo
Device - Audio Speaker Demo
Device - Boot Loader - HID
Device - Boot Loader - MCHPUSB
Device - CCID Smart Card Reader
Device - CDC - Serial Emulator
Device - CDC Basic Demo
Device - Composite - HID + MSD Demo
Device - Composite - MSD + CDC Demo
Device - Composite - WinUSB + MSD Demo
Device - HID - Custom Demo
Device - HID - Digitizer Demos
Device - HID - Joystick Demo
Device - HID - Keyboard Demo
Device - HID - Mouse Demo
Device - HID - Uninterruptible Power Supply
Device - LibUSB Generic Driver Demo
Device - Mass Storage - Internal Flash Demo
Device - Mass Storage - SD Card Data Logger
Device - Mass Storage - SD Card Reader
Device - MCHPUSB Generic Driver Demo
Device - Personal Healthcare Device Class (PHDC) Demo
Device - WinUSB Generic Driver Demo
Device - WinUSB High Bandwidth Demo
Device Mode Enable (USB_SUPPORT_DEVICE)
Device Stack
Device/Peripheral
DEVICE_CLASS_CDC macro
DEVICE_CLASS_HID macro
DEVICE_CLASS_MASS_STORAGE macro
DEVICE_INTERFACE_PROTOCOL_BULK_ONLY macro
DEVICE_SUBCLASS_CD_DVD macro
DEVICE_SUBCLASS_FLOPPY_INTERFACE macro
DEVICE_SUBCLASS_RBC macro
DEVICE_SUBCLASS_REMOVABLE macro
DEVICE_SUBCLASS_SCSI macro
DEVICE_SUBCLASS_TAPE_DRIVE macro
Disable DTS checking (USB_DEVICE_DISABLE_DTS_CHECKING)
DSC_HID macro
DSC_PHY macro
DSC_RPT macro
dsPIC33EP512MU810 Plug-In-Module (PIM)
Dual Role - MSD Host + HID Device
E
Embedded Host API
Embedded Host Stack
END_SESSION macro
Endpoint 0 size (USB_EP0_BUFF_SIZE)
Endpoints Used (USB_MAX_EP_NUMBER)
Event Notifications
EVENT_ANDROID_ATTACH macro
EVENT_ANDROID_DETACH macro
EVENT_AUDIO_ATTACH macro
EVENT_AUDIO_DETACH macro
EVENT_AUDIO_FREQUENCY_SET macro
EVENT_AUDIO_INTERFACE_SET macro
EVENT_AUDIO_NONE macro
EVENT_AUDIO_OFFSET macro
EVENT_AUDIO_STREAM_RECEIVED macro
EVENT_CDC_COMM_READ_DONE macro
EVENT_CDC_COMM_WRITE_DONE macro
EVENT_CDC_DATA_READ_DONE macro
EVENT_CDC_DATA_WRITE_DONE macro
EVENT_CDC_NAK_TIMEOUT macro
EVENT_CDC_NONE macro
EVENT_CDC_OFFSET macro
EVENT_CDC_RESET macro
EVENT_CHARGER_ATTACH macro
EVENT_CHARGER_DETACH macro
EVENT_CHARGER_OFFSET macro
EVENT_GENERIC_ATTACH macro
EVENT_GENERIC_DETACH macro
EVENT_GENERIC_OFFSET macro
EVENT_GENERIC_RX_DONE macro
EVENT_GENERIC_TX_DONE macro
EVENT_HID_ATTACH macro
EVENT_HID_BAD_REPORT_DESCRIPTOR macro
EVENT_HID_DETACH macro
EVENT_HID_NONE macro
EVENT_HID_OFFSET macro
EVENT_HID_READ_DONE macro
EVENT_HID_RESET macro
EVENT_HID_RESET_ERROR macro
EVENT_HID_RPT_DESC_PARSED macro
EVENT_HID_WRITE_DONE macro
EVENT_MIDI_ATTACH macro
EVENT_MIDI_DETACH macro
EVENT_MIDI_OFFSET macro
EVENT_MIDI_TRANSFER_DONE macro
EVENT_MSD_MAX_LUN macro
EVENT_MSD_NONE macro
EVENT_MSD_OFFSET macro
EVENT_MSD_RESET macro
EVENT_MSD_TRANSFER macro
EVENT_PRINTER_ATTACH macro
EVENT_PRINTER_DETACH macro
EVENT_PRINTER_OFFSET macro
EVENT_PRINTER_REQUEST_DONE macro
EVENT_PRINTER_REQUEST_ERROR macro
EVENT_PRINTER_RX_DONE macro
EVENT_PRINTER_RX_ERROR macro
EVENT_PRINTER_TX_DONE macro
EVENT_PRINTER_TX_ERROR macro
EVENT_PRINTER_UNSUPPORTED macro
Explorer 16
F
From v2.5 to v2.6
From v2.6 to v2.6a
From v2.6a to v2.7
From v2.7 to v2.7a
From v2.7a to v2.8
From v2.8 to v2.9
From v2.9 to v2.9a
From v2.9a to v2.9b
From v2.9b to v2.9c
From v2.9c to v2.9d
From v2.9d to v2.9e
G
Garage Band '08 [Macintosh Computers]
Generic Client Driver
GENERIC_DEVICE type
GENERIC_DEVICE_ID type
getsUSBUSART function
H
HID boot loader
HID Client Driver
HID Function Driver
HID_COLLECTION structure
HID_DATA_DETAILS structure
HID_DESIGITEM structure
HID_GLOBALS structure
HID_ITEM_INFO structure
HID_PROTOCOL_KEYBOARD macro
HID_PROTOCOL_MOUSE macro
HID_PROTOCOL_NONE macro
HID_REPORT structure
HID_REPORTITEM structure
HID_STRINGITEM structure
HID_TRANSFER_DATA structure
HID_USAGEITEM structure
HIDReportTypeEnum enumeration
HIDRxHandleBusy macro
HIDRxPacket macro
HIDTxHandleBusy macro
HIDTxPacket macro
Host - Audio MIDI Demo
Host - Boot Loader - Thumb Drive Boot Loader
Host - CDC Serial Demo
Host - Charger - Simple Charger
Host - Composite - HID + MSD
Host - Composite - MSD+ CDC
Host - HID - Keyboard Demo
Host - HID - Mouse Demo
Host - Mass Storage - Thumb Drive Data Logger
Host - Mass Storage (MSD) - Simple Demo
Host - MCHPUSB - Generic Driver Demo
Host - Printer - Print Screen Demo
Host - Printer - Simple Full Sheet
Host - Printer - Simple Point of Sale (POS)
HOST_TRANSFER_DATA structure
I
Implementation and Customization Details
Important Considerations
INIT_CL_SC_P macro
INIT_VID_PID macro
Installing Windows Drivers
Interface Functions
Interface mode (USB_POLLING or USB_INTERRUPT)
Interface Routines
Internal Members
Interrupt Remapping
Interrupts
Introduction
L
LANGUAGE_ID_STRING_ESCPOS macro
LANGUAGE_ID_STRING_PCL macro
LANGUAGE_ID_STRING_POSTSCRIPT macro
LANGUAGE_SUPPORT_FLAGS_ESCPOS macro
LANGUAGE_SUPPORT_FLAGS_PCL3 macro
LANGUAGE_SUPPORT_FLAGS_PCL5 macro
LANGUAGE_SUPPORT_FLAGS_POSTSCRIPT macro
Library Migration
Linux
Loading a precompiled demo
Low Pin Count USB Development Board
LUN_FUNCTIONS type
M
Macros
Mass Storage Client Driver
MCHPUSB PnP Demo
Memory Map
Memory Region Definitions
MPLAB 8
MPLAB X (NetBeans)
MSD boot loader
MSD Function Driver
MSD_COMMAND_FAILED macro
MSD_COMMAND_PASSED macro
MSD_PHASE_ERROR macro
MSDTasks function
N
Notes on .inf Files
NUM_ANDROID_DEVICES_SUPPORTED macro
NUM_STOP_BITS_1 macro
NUM_STOP_BITS_1_5 macro
NUM_STOP_BITS_2 macro
Number of Interfaces (USB_MAX_NUM_INT)
O
Online Reference and Resources
On-The-Go (OTG)
Operating System Support and Limitations
OTG - MCHPUSB Device/MCHPUSB Host Demo
OTG_EVENT_CONNECT macro
OTG_EVENT_DISCONNECT macro
OTG_EVENT_HNP_ABORT macro
OTG_EVENT_HNP_FAILED macro
OTG_EVENT_NONE macro
OTG_EVENT_RESUME_SIGNALING macro
OTG_EVENT_SRP_CONNECT macro
OTG_EVENT_SRP_DPLUS_HIGH macro
OTG_EVENT_SRP_DPLUS_LOW macro
OTG_EVENT_SRP_FAILED macro
OTG_EVENT_SRP_VBUS_HIGH macro
OTG_EVENT_SRP_VBUS_LOW macro
P
PARITY_EVEN macro
PARITY_MARK macro
PARITY_NONE macro
PARITY_ODD macro
PARITY_SPACE macro
Part Specific Details
PC - WM_DEVICECHANGE Demo
PC Tools and Example Code
PDFSUSB
Performing the Continua Precertification Tests
Personal Healthcare Device Class (PHDC) Function Driver
PHDAppInit function
PHDConnect function
PHDDisConnect function
PHDSendAppBufferPointer function
PHDSendMeasuredData function
PHDTimeoutHandler function
PIC18 Starter Kit
PIC18F
PIC18F46J50 Plug-In-Module (PIM)
PIC18F47J53 Plug-In-Module (PIM)
PIC18F87J50 Plug-In-Module (PIM) Demo Board
PIC24EP512GU810 Plug-In-Module (PIM)
PIC24F
PIC24F Implementation Specific Details
PIC24F Starter Kit
PIC24FJ256DA210 Development Board
PIC24FJ256GB110 Plug-In-Module (PIM)
PIC24FJ256GB210 Plug-In-Module (PIM)
PIC24FJ64GB004 Plug-In-Module (PIM)
PIC24FJ64GB502 Microstick
PIC32 USB Starter Kit
PIC32 USB Starter Kit II
PIC32MX460F512L Plug-In-Module (PIM)
PIC32MX795F512L Plug-In-Module (PIM)
PICDEM FS USB Board
Ping Pong buffering (USB_PING_PONG_MODE)
Printer Client Driver
PRINTER_COLOR_BLACK macro
PRINTER_COLOR_WHITE macro
PRINTER_DEVICE_REQUEST_GET_DEVICE_ID macro
PRINTER_DEVICE_REQUEST_GET_PORT_STATUS macro
PRINTER_DEVICE_REQUEST_SOFT_RESET macro
PRINTER_FILL_CROSS_HATCHED macro
PRINTER_FILL_HATCHED macro
PRINTER_FILL_SHADED macro
PRINTER_FILL_SOLID macro
PRINTER_LINE_END_BUTT macro
PRINTER_LINE_END_ROUND macro
PRINTER_LINE_END_SQUARE macro
PRINTER_LINE_JOIN_BEVEL macro
PRINTER_LINE_JOIN_MITER macro
PRINTER_LINE_JOIN_ROUND macro
PRINTER_LINE_TYPE_DASHED macro
PRINTER_LINE_TYPE_DOTTED macro
PRINTER_LINE_TYPE_SOLID macro
PRINTER_LINE_WIDTH_NORMAL macro
PRINTER_LINE_WIDTH_THICK macro
PRINTER_PAGE_LANDSCAPE_HEIGHT macro
PRINTER_PAGE_LANDSCAPE_WIDTH macro
PRINTER_PAGE_PORTRAIT_HEIGHT macro
PRINTER_PAGE_PORTRAIT_WIDTH macro
PRINTER_POS_BOTTOM_TO_TOP macro
PRINTER_POS_DENSITY_HORIZONTAL_DOUBLE macro
PRINTER_POS_DENSITY_HORIZONTAL_SINGLE macro
PRINTER_POS_DENSITY_VERTICAL_24 macro
PRINTER_POS_DENSITY_VERTICAL_8 macro
PRINTER_POS_LEFT_TO_RIGHT macro
PRINTER_POS_RIGHT_TO_LEFT macro
PRINTER_POS_TOP_TO_BOTTOM macro
PrintScreen function
putrsUSBUSART function
putsUSBUSART function
putUSBUSART function
R
Release Notes
Revision History
ROLE_DEVICE macro
ROLE_HOST macro
Running the demo
Running the Demo
Running the Demo (Android v3.1+)
Running the PHDC Blood Pressure Monitor Demo
Running the PHDC Glucose Meter Demo
Running the PHDC Themometer Demo
Running the PHDC Weigh Scale Demo
S
Software License Agreement
Special Region Creation
Speed selection (USB_SPEED_OPTION)
Stack Configuration
START_SESSION macro
Startup Sequence and Reset Remapping
Status Stage Timout Enable (USB_ENABLE_STATUS_STAGE_TIMEOUTS and USB_STATUS_STAGE_TIMEOUT)
String Descriptor Array size (USB_NUM_STRING_DESCRIPTORS)
Support
Supported Demo Boards
T
TOGGLE_SESSION macro
Tool Information
TPL_ALLOW_HNP macro
TPL_CLASS_DRV macro
TPL_SET_CONFIG macro
Trademark Information
Transceiver Option (USB_TRANSCEIVER_OPTION)
TRANSFER_ATTRIBUTES union
Troubleshooting
U
Understanding and Customizing the Boot Loader Implementation
USB PICTail Plus Daughter Board
USB_APPLICATION_EVENT_HANDLER function
USB_CDC_ABSTRACT_CONTROL_MODEL macro
USB_CDC_ACM_FN_DSC structure
USB_CDC_ATM_NETWORKING_CONTROL_MODEL macro
USB_CDC_CALL_MGT_FN_DSC structure
USB_CDC_CAPI_CONTROL_MODEL macro
USB_CDC_CLASS_ERROR macro
USB_CDC_COMM_INTF macro
USB_CDC_COMMAND_FAILED macro
USB_CDC_COMMAND_PASSED macro
USB_CDC_CONTROL_LINE_LENGTH macro
USB_CDC_CONTROL_SIGNAL_BITMAP union
USB_CDC_CS_ENDPOINT macro
USB_CDC_CS_INTERFACE macro
USB_CDC_DATA_INTF macro
USB_CDC_DEVICE_BUSY macro
USB_CDC_DEVICE_DETACHED macro
USB_CDC_DEVICE_HOLDING macro
USB_CDC_DEVICE_INFO structure
USB_CDC_DEVICE_MANAGEMENT macro
USB_CDC_DEVICE_NOT_FOUND macro
USB_CDC_DIRECT_LINE_CONTROL_MODEL macro
USB_CDC_DSC_FN_ACM macro
USB_CDC_DSC_FN_CALL_MGT macro
USB_CDC_DSC_FN_COUNTRY_SELECTION macro
USB_CDC_DSC_FN_DLM macro
USB_CDC_DSC_FN_HEADER macro
USB_CDC_DSC_FN_RPT_CAPABILITIES macro
USB_CDC_DSC_FN_TEL_OP_MODES macro
USB_CDC_DSC_FN_TELEPHONE_RINGER macro
USB_CDC_DSC_FN_UNION macro
USB_CDC_DSC_FN_USB_TERMINAL macro
USB_CDC_ETHERNET_EMULATION_MODEL macro
USB_CDC_ETHERNET_NETWORKING_CONTROL_MODEL macro
USB_CDC_GET_COMM_FEATURE macro
USB_CDC_GET_ENCAPSULATED_REQUEST macro
USB_CDC_GET_LINE_CODING macro
USB_CDC_HEADER_FN_DSC structure
USB_CDC_ILLEGAL_REQUEST macro
USB_CDC_INITIALIZING macro
USB_CDC_INTERFACE_ERROR macro
USB_CDC_LINE_CODING union
USB_CDC_LINE_CODING_LENGTH macro
USB_CDC_MOBILE_DIRECT_LINE_MODEL macro
USB_CDC_MULTI_CHANNEL_CONTROL_MODEL macro
USB_CDC_NO_PROTOCOL macro
USB_CDC_NO_REPORT_DESCRIPTOR macro
USB_CDC_NORMAL_RUNNING macro
USB_CDC_OBEX macro
USB_CDC_PHASE_ERROR macro
USB_CDC_REPORT_DESCRIPTOR_BAD macro
USB_CDC_RESET_ERROR macro
USB_CDC_RESETTING_DEVICE macro
USB_CDC_SEND_BREAK macro
USB_CDC_SEND_ENCAPSULATED_COMMAND macro
USB_CDC_SET_COMM_FEATURE macro
USB_CDC_SET_CONTROL_LINE_STATE macro
USB_CDC_SET_LINE_CODING macro
USB_CDC_TELEPHONE_CONTROL_MODEL macro
USB_CDC_UNION_FN_DSC structure
USB_CDC_V25TER macro
USB_CDC_WIRELESS_HANDSET_CONTROL_MODEL macro
USB_CLIENT_EVENT_HANDLER type
USB_CLIENT_INIT type
usb_config.h
USB_DATA_POINTER union
USB_DATA_POINTER_RAM macro
USB_DATA_POINTER_ROM macro
USB_DEVICE_STACK_EVENTS enumeration
USB_DEVICE_STATE enumeration
USB_EP0_BUSY macro
USB_EP0_INCLUDE_ZERO macro
USB_EP0_NO_DATA macro
USB_EP0_NO_OPTIONS macro
USB_EP0_RAM macro
USB_EP0_ROM macro
USB_ERROR_BUFFER_TOO_SMALL macro
USB_GENERIC_EP macro
USB_HANDLE macro
USB_HID_CLASS_ERROR macro
USB_HID_COMMAND_FAILED macro
USB_HID_COMMAND_PASSED macro
USB_HID_DEVICE_BUSY macro
USB_HID_DEVICE_DETACHED macro
USB_HID_DEVICE_HOLDING macro
USB_HID_DEVICE_ID structure
USB_HID_DEVICE_NOT_FOUND macro
USB_HID_DEVICE_RPT_INFO structure
USB_HID_ILLEGAL_REQUEST macro
USB_HID_INITIALIZING macro
USB_HID_INTERFACE_ERROR macro
USB_HID_ITEM_LIST structure
USB_HID_NO_REPORT_DESCRIPTOR macro
USB_HID_NORMAL_RUNNING macro
USB_HID_PHASE_ERROR macro
USB_HID_REPORT_DESCRIPTOR_BAD macro
USB_HID_RESET_ERROR macro
USB_HID_RESETTING_DEVICE macro
USB_HID_RPT_DESC_ERROR enumeration
USB_HOST_APP_EVENT_HANDLER function
USB_MAX_CHARGING_DEVICES macro
USB_MAX_PRINTER_DEVICES macro
USB_MSD_CBW_ERROR macro
USB_MSD_COMMAND_FAILED macro
USB_MSD_COMMAND_PASSED macro
USB_MSD_CSW_ERROR macro
USB_MSD_DEVICE_BUSY macro
USB_MSD_DEVICE_DETACHED macro
USB_MSD_DEVICE_NOT_FOUND macro
USB_MSD_ERROR macro
USB_MSD_ERROR_STATE macro
USB_MSD_ILLEGAL_REQUEST macro
USB_MSD_INITIALIZING macro
USB_MSD_INVALID_LUN macro
USB_MSD_MEDIA_INTERFACE_ERROR macro
USB_MSD_NORMAL_RUNNING macro
USB_MSD_OUT_OF_MEMORY macro
USB_MSD_PHASE_ERROR macro
USB_MSD_RESET_ERROR macro
USB_MSD_RESETTING_DEVICE macro
USB_NULL macro
USB_NUM_BULK_NAKS macro
USB_NUM_COMMAND_TRIES macro
USB_NUM_CONTROL_NAKS macro
USB_NUM_ENUMERATION_TRIES macro
USB_NUM_INTERRUPT_NAKS macro
USB_OTG_FW_DOT_VER macro
USB_OTG_FW_MAJOR_VER macro
USB_OTG_FW_MINOR_VER macro
USB_PRINT_SCREEN_INFO structure
USB_PRINTER_COMMAND enumeration
USB_PRINTER_DEVICE_ID structure
USB_PRINTER_ERRORS enumeration
USB_PRINTER_FONTS enumeration
USB_PRINTER_FONTS_POS enumeration
USB_PRINTER_FUNCTION_SUPPORT union
USB_PRINTER_FUNCTION_SUPPORT_POS macro
USB_PRINTER_FUNCTION_SUPPORT_VECTOR_GRAPHICS macro
USB_PRINTER_GRAPHICS_PARAMETERS union
USB_PRINTER_IMAGE_INFO structure
USB_PRINTER_INTERFACE structure
USB_PRINTER_LANGUAGE_HANDLER type
USB_PRINTER_LANGUAGE_SUPPORTED type
USB_PRINTER_POS_BARCODE_FORMAT enumeration
USB_PRINTER_SPECIFIC_INTERFACE structure
USB_PRINTER_TRANSFER_COPY_DATA macro
USB_PRINTER_TRANSFER_FROM_RAM macro
USB_PRINTER_TRANSFER_FROM_ROM macro
USB_PRINTER_TRANSFER_NOTIFY macro
USB_PRINTER_TRANSFER_STATIC_DATA macro
USB_PROCESSING_REPORT_DESCRIPTOR macro
USB_TPL structure
USBCancelIO function
USBCCIDBulkInService function
USBCCIDInitEP function
USBCCIDSendDataToHost function
USBCheckAudioRequest function
USBCheckCCIDRequest function
USBCheckCDCRequest function
USBCheckMSDRequest function
USBCtrlEPAllowDataStage function
USBCtrlEPAllowStatusStage function
USBDeferINDataStage function
USBDeferOUTDataStage function
USBDeferStatusStage function
USBDeviceAttach function
USBDeviceDetach function
USBDeviceInit function
USBDevicePHDCCheckRequest function
USBDevicePHDCInit function
USBDevicePHDCReceiveData function
USBDevicePHDCSendData function
USBDevicePHDCTxRXService function
USBDevicePHDCUpdateStatus function
USBDeviceTasks function
USBEnableEndpoint function
USBEP0Receive function
USBEP0SendRAMPtr function
USBEP0SendROMPtr function
USBEP0Transmit function
USBGenRead macro
USBGenWrite macro
USBGetDeviceState function
USBGetNextHandle function
USBGetRemoteWakeupStatus function
USBGetSuspendState function
USBHandleBusy function
USBHandleGetAddr function
USBHandleGetLength function
USBHostAudioV1DataEventHandler function
USBHostAudioV1EventHandler function
USBHostAudioV1Initialize function
USBHostAudioV1ReceiveAudioData function
USBHostAudioV1SetInterfaceFullBandwidth function
USBHostAudioV1SetInterfaceZeroBandwidth function
USBHostAudioV1SetSamplingFrequency function
USBHostAudioV1SupportedFrequencies function
USBHostAudioV1TerminateTransfer function
USBHostCDC_Api_ACM_Request function
USBHostCDC_Api_Get_IN_Data function
USBHostCDC_ApiTransferIsComplete function
USBHostCDCDeviceStatus function
USBHostCDCEventHandler function
USBHostCDCInitAddress function
USBHostCDCInitialize function
USBHostCDCRead_DATA macro
USBHostCDCResetDevice function
USBHostCDCSend_DATA macro
USBHostCDCTransfer function
USBHostCDCTransferIsComplete function
USBHostChargerDeviceDetached function
USBHostChargerEventHandler function
USBHostChargerGetDeviceAddress function
USBHostClearEndpointErrors function
USBHostDeviceSpecificClientDriver function
USBHostDeviceStatus function
USBHostGenericDeviceDetached macro
USBHostGenericEventHandler function
USBHostGenericGetDeviceAddress function
USBHostGenericGetRxLength macro
USBHostGenericInit function
USBHostGenericRead function
USBHostGenericRxIsBusy macro
USBHostGenericRxIsComplete function
USBHostGenericTxIsBusy macro
USBHostGenericTxIsComplete function
USBHostGenericWrite function
USBHostGetCurrentConfigurationDescriptor macro
USBHostGetDeviceDescriptor macro
USBHostGetStringDescriptor macro
USBHostHID_ApiFindBit function
USBHostHID_ApiFindValue function
USBHostHID_ApiGetCurrentInterfaceNum function
USBHostHID_ApiGetReport macro
USBHostHID_ApiImportData function
USBHostHID_ApiSendReport macro
USBHostHID_ApiTransferIsComplete macro
USBHostHID_GetCurrentReportInfo macro
USBHostHID_GetItemListPointers macro
USBHostHID_HasUsage function
USBHostHIDDeviceDetect function
USBHostHIDDeviceStatus function
USBHostHIDEventHandler function
USBHostHIDInitialize function
USBHostHIDRead macro
USBHostHIDResetDevice function
USBHostHIDResetDeviceWithWait function
USBHostHIDTasks function
USBHostHIDTerminateTransfer function
USBHostHIDTransfer function
USBHostHIDTransferIsComplete function
USBHostHIDWrite macro
USBHostInit function
USBHostMIDIDeviceDetached macro
USBHostMIDIEndpointDirection macro
USBHostMIDINumberOfEndpoints macro
USBHostMIDIRead function
USBHostMIDISizeOfEndpoint macro
USBHostMIDITransferIsBusy macro
USBHostMIDITransferIsComplete function
USBHostMIDIWrite function
USBHostMSDDeviceStatus function
USBHostMSDEventHandler function
USBHostMSDInitialize function
USBHostMSDRead macro
USBHostMSDResetDevice function
USBHostMSDSCSIEventHandler function
USBHostMSDSCSIInitialize function
USBHostMSDSCSISectorRead function
USBHostMSDSCSISectorWrite function
USBHostMSDTerminateTransfer function
USBHostMSDTransfer function
USBHostMSDTransferIsComplete function
USBHostMSDWrite macro
USBHOSTPRINTER_SETFLAG_COPY_DATA macro
USBHOSTPRINTER_SETFLAG_NOTIFY macro
USBHOSTPRINTER_SETFLAG_STATIC_DATA macro
USBHostPrinterCommand function
USBHostPrinterCommandReady function
USBHostPrinterCommandWithReadyWait macro
USBHostPrinterDeviceDetached function
USBHostPrinterEventHandler function
USBHostPrinterGetRxLength function
USBHostPrinterGetStatus function
USBHostPrinterInitialize function
USBHostPrinterLanguageESCPOS function
USBHostPrinterLanguageESCPOSIsSupported function
USBHostPrinterLanguagePCL5 function
USBHostPrinterLanguagePCL5IsSupported function
USBHostPrinterLanguagePostScript function
USBHostPrinterLanguagePostScriptIsSupported function
USBHostPrinterPOSImageDataFormat function
USBHostPrinterPosition macro
USBHostPrinterPositionRelative macro
USBHostPrinterRead function
USBHostPrinterReset function
USBHostPrinterRxIsBusy function
USBHostPrinterWrite function
USBHostPrinterWriteComplete function
USBHostRead function
USBHostResetDevice function
USBHostResumeDevice function
USBHostSetDeviceConfiguration function
USBHostSetNAKTimeout function
USBHostSuspendDevice function
USBHostTerminateTransfer function
USBHostTransferIsComplete function
USBHostVbusEvent function
USBHostWrite function
USBINDataStageDeferred function
USBIsBusSuspended function
USBIsDeviceSuspended function
USBMSDInit function
USBOTGClearRoleSwitch function
USBOTGCurrentRoleIs function
USBOTGDefaultRoleIs function
USBOTGInitialize function
USBOTGRequestSession function
USBOTGRoleSwitch function
USBOTGSelectRole function
USBOTGSession function
USBOUTDataStageDeferred function
USBRxOnePacket function
USBSoftDetach function
USBStallEndpoint function
USBTransferOnePacket function
USBTxOnePacket function
USBUSARTIsTxTrfReady macro
Using a diff tool
Using breakpoints in USB host applications
Using Linux MultiMedia Studio (LMMS) [Linux and Windows Computers]
V
v2.7
v2.7a
v2.8
v2.9
v2.9a
v2.9b
v2.9c
v2.9d
v2.9e
Vendor Class (Generic) Function Driver
Vendor ID (VID) and Product ID (PID)
Vendor IDs (VID) and Product IDs (PID)
W
What's New
What's Next
Windows


Introduction

Contents | Index
Next
Introduction

MCHPFSUSB v2.9e

for Microchip PIC18/PIC24F/PIC32MX Microcontrollers

MCHPFSUSB is a distribution package containing a variety of USB related firmware projects, USB drivers and resources intended for use on the PC. The MCHPFSUSB firmware examples include projects for USB peripheral/device, Embedded Host, OTG, and Dual Role.

Introduction