Release Notes

Microchip PIC32 USB Embedded Host Stack and Applications

Version 1.04

5 December 2008

What's New/Updated in Release v1.04

At a Glance

1. Getting started guides added to each demo project
2. Added PIC32 USB Starter Board support to all demos
3. PIC32 Starter Kit demos now use the debug print libraries to display output and receive user input from the MPLAB IDE console window
4. Added suspend, resume, and remote wake-up support
5. Added MDD File System v1.2 support for FAT16, FAT32
6. General library improvements and bug fixes

Details

General

- Demos have been updated to run at 80 MHz
- General clean up has been performed to make the source more readable and consistent
- LCD timings have been adjusted (in ex16lcd.c) to eliminate display errors
- FAT file system support (MDD FS) has been updated to v1.2, supporting FAT16 and FAT32
- WM_DEVICECHANGE demo has been updated to be consistent with PIC18/24 USB release v2.3

PIC32 USB Starter Kit

- Versions of the USB demos that support the PIC32 USB Starter Kit have been added
- Starter kit demos use the debug IO capability of the PIC32 starter kit debugger to display output to or receive input from the MPLAB IDE

- db_utils library has been added to support PIC32 Starter Kit debug IO

USB

- USB headers have been updated to eliminate warnings
- A disable interface (USBDisable) has been added
- Mpusbapi Microchip "Custom" Windows PC driver and API DLL have been updated to be consistent with the PIC18/24 USB release v2.3
- The USBConfig.exe USB configuration tool has been updated to version 2.0.0.0

USB Device

- Sleep, Resume, & Remote wake up support has been added to the device library
- Attach event support has been added to the device library
- Detach event support has been fixed in the device layer
- Several HID Device driver parameters have been made "overridable" by the application (see usb_device_hid.h)
- FIXED: Enumeration failures with PIC32 USB hosts
- Default attach de-bounce (USB_DEVICE_ATTACH_DEBOUNCE_TIME) time has been increased to 100 ms
- The HID Mouse demo has been modified to demonstrate suspend, resume, & remote wake up capabilities

USB Host

- Host support has been updated to be more consistent with the PIC24 v2.3 release
- The default number of control "NAKs" (USB_NUM_CONTROL_NAKS) has been increased
- An interface has been added to control the "NAK" timeout (USBHostSetNAKTimeout)
- The Generic Host demo supports both Interrupt and Bulk transfers, enabling support for recent updates to the PIC18 PICDEM(TM) FS USB board

IMPORTANT NOTES

Tool revisions

This release was tested with the following tools:

- C32 – v1.03
- MPLAB v8.15 – Some of the changes in this release require MPLAB v8.10 or later.

Library revisions

This release includes the following Microchip libraries:

- Microchip Memory Disk (MDD) File System v1.2

Notes about .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.

Notes about Vendor ID (VID) and Product ID (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.

Getting Started

Getting Started with the USB Library

Thank you for installing the USB Library! We hope that this library will allow you to quickly and easily add USB Device or Embedded Host capability to your application.

What is Installed

The installation program allows you to select the root directory of your install. The default root directory is C:\pic32_solutions. Under that directory, the following directories and files will be installed.

- .\Microchip\Help - Help files for the installed Microchip libraries.
- .\Microchip\Include\ - Header files used by the Microchip libraries. Files for generic support functions are stored in the root directory. Library-specific headers are stored under library-specific subdirectories.
- .\Microchip\Include\USB - Header files used by the USB library.
- .\Microchip\USB - Source files of the USB library.
- .\Microchip\USB\<class><Host|Device>Driver - Source files for the client or function driver for the specific class.
- .\Microchip\USB\Documentation - Getting Started documentation for the library.

The following demos and directories are are also installed, and are described below:

- \USB Data Logger
- \USB Generic Host Demo
- \USB PC – WM_DEVICECHANGE Demo
- \USB Precompiled Demos
- \USB Tools\usb_cdc_serial_device_demo
- \usb_generic_device_demo
- \usb_hid_mouse_device_demo
- \usb_msd_device_demo
- \usb_sk_cdc_serial_device_demo
- \usb_sk_generic_device_demo
- \usb_sk_hid_mouse_device_demo
- \usb_sk_msd_device_demo
- \usb_sk_msd_host_demo

MPLAB IDE Firmware Projects and hardware

Several USB example firmware projects and hex files are included in the installation. Documentation explaining how to program and run each of the provided demos is available in each of the demo folders as well as the <Install Directory>\Microchip\USB\Documentation folder.

Microchip provides two full-speed USB hardware platforms for PIC32:

- The PIC32 USB Starter Kit (http://www.microchipDIRECT.com/ part number DM320003) enables evaluation of USB on the PIC32MX family devices.
- The PIC32MX460F512L USB Plug-In Module (http://www.microchipDIRECT.com/ part number MA320002) enables evaluation of USB on the PIC32MX family devices. In addition to the PIM the Explorer 16 (http://www.microchipDIRECT.com/ part number DM240001) and USB Pictail Plus board (http://www.microchipDIRECT.com/ part number AC164131) are required for evaluation.

In addition to the USB specific hardware, the SD Card Pictail Plus board is used for all of the mass storage demos (http://www.microchipDIRECT.com/ part number AC164122).

USB Data logger

See: <Install Directory>\USB Data Logger

This project contains USB firmware which enables the embedded host devices to talk directly to a FAT16 or FAT32 formatted thumb drive (memory stick). In this demo the thumb drive is connected to the USB PICtail Plus board attached to the Explorer 16. The embedded host reads the contents of the drive and sends that information through the serial port a computer so it can be more easily read by a user. The example program allows users to navigate the directories of the thumb drive, create new files, and log either the potentiometer data or the temperature sensor data into a comma separated (CSV) file (not supported on the Starter Board). Once the new files are create the thumb drive can be removed from the Explorer 16 and attached to a computer so that the data written to the thumb drive and be viewed by the user.

For more information about how to use the demo please see the getting started guide for this demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

USB Generic Host Demo

See: <Install Directory>\USB Generic Host Demo

This project contains USB firmware which handles the USB chapter 9 requests needed for enumeration, and it also provides an implementation example of a custom or ‘vendor’ class host using Microchip’s USB general purpose driver.

This project serves as a hosting option for the “usb_generic_device_demo” device demo. This demo allows a user to connect a demo programmed with the device demo and display the temperature and potentiometer data on the Explorer 16 LCD screen.

For more information about how to use the demo please see the getting started guide for this demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

USB PC - WM_DEVICECHANGE Demo

See: <Install Directory>\USB PC - WM_DEVICECHANGE Demo

This is a simple application written in Visual C++.net Express™ edition. This application gives an example of how to register for a WM_DEVICECHANGE notification on Windows operating systems. The WM_DEVICECHANGE feature allows applications to be notified when a hardware change has occurred on the computer. This example can be used to determine when a targeted device is plugged into a computer or removed from a computer. By registering for these notifications, application no longer need to periodically search to see if the device has arrived. Instead they are actively notified and can only look for their device when a change has occurred.

For more information about how to use the demo please see the getting started guide for this demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

USB Precompiled Demos

See: <Install Directory>\USB Precompiled Demos

Precompiled demos can be found in the <Install Directory>\USB – Precompiled Demos folder for each of the previously mentioned hardware platforms. To use these hex files with standard Microchip development tools such as MPLAB IDE and programmer, open MPLAB IDE, click “Configure à Select Device”, then choose PIC32MX460F512L. Make sure an appropriate programmer is connected and has been selected. Then click “File à Import” and import the .hex file to be used. Then use the “Programmer's Program” menu choice to restore the device.

For more information about how to use each of these demos, please see the getting started guides for each demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

usb_cdc_serial_device_demo

See: <Install Directory>\usb_cdc_serial_device_demo

This project contains USB firmware which handles the USB chapter 9 requests needed for device enumeration, and it also provides an implementation example of a communication device class (CDC) device. The firmware emulates a COM port. In this demo the CDC firmware either echos keypresses back to the user and prints a message to the screen when the pushbutton is pressed. For more information about how to use the demo please see the getting started guide for this demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

Along with the firmware, some PC resources are also provided. Windows operating systems will ask for a .inf file associated with any CDC device that is plugged in. This file can be located in the “<Install Directory>\USB Tools\USB CDC Serial Demo\inf” folder.

Neither the USB hardware on the PIC® microcontroller, nor the firmware used is platform specific. Several different types of operating systems, including modern Macintosh and Linux® operating systems have built in CDC drivers. The CDC basic demo may be used on these other platforms in addition to Windows.

For more information about how to use the demo please see the getting started guide for this demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

usb_generic_device_demo

See: <Install Directory>\usb_generic_device_demo

This project contains USB firmware which handles the USB chapter 9 requests needed for enumeration, and it also provides an implementation example of a custom or ‘vendor’ class device using Microchip’s USB general purpose driver.

This project serves as the basis for the firmware intended to be used with the “PICDEM FS USB Demo Tool” (launched with PDFSUSB.exe) or the "USB Generic Host Demo". The code provided in the project provides the firmware needed for the various features (such as temperature, potentiometer position) used by PDFSUSB.exe.

When using this firmware, Windows should prompt the user for a driver when the USB cable is first connected. Upon receiving this prompt, point Windows to the .INF file located in the “<Install Directory>\USB Tools\MCHPUSB Custom Driver\MCHPUSB Driver\Release” directory.

For more information about how to use the demo please see the getting started guide for this demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

usb_hid_mouse_device_demo

See: <Install Directory>\usb_hid_mouse_device_demo

This project contains USB firmware which handles the USB chapter 9 requests needed for device enumeration, and it also provides an implementation example of a HID class device. The firmware emulates a basic USB mouse device.

When using this firmware, Windows should not prompt the user for any kind of driver or .INF files. The HID driver is provided with the operating system, so no additional files are needed. Several different types of operating systems, including modern Macintosh and Linux® operating systems have built in HID drivers. Neither the USB hardware on the PIC® microcontroller, nor the firmware used is platform specific. The HID mouse demo may be used on these other platforms in addition to Windows.

For more information about how to use the demo please see the getting started guide for this demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

usb_msd_device_demo

See: <Install Directory>\usb_msd_device_demo

This project contains USB firmware which handles the USB chapter 9 requests needed for device enumeration, and it also provides an implementation example of a MSD class device. The firmware turns the hardware platform into a basic SD card reader. When the device is attached to the computer a new drive appears. If an SD card is inserted into the SD card PICTail Plus board, then the contents of the card are sent to the computer.

When using this firmware, Windows should not prompt the user for any kind of driver or .INF files. The MSD driver is provided with the operating system, so no additional files are needed. Several different types of operating systems, including modern Macintosh and Linux® operating systems have built in MSD drivers. Neither the USB hardware on the PIC® microcontroller, nor the firmware used is platform specific. The SD card reader demo may be used on these other platforms in addition to Windows.

For more information about how to use the demo please see the getting started guide for this demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

usb_sk_cdc_serial_device_demo

See: <Install Directory>\usb_sk_cdc_serial_device_demo

This project contains USB firmware for the Starter Kit version of the usb_cdc_serial_device_demo, essentially unmodified.

For more information about how to use the demo please see the getting started guide for this demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

usb_sk_generic_device_demo

See: <Install Directory>\usb_sk_generic_device_demo

This project contains USB firmware for the Starter Kit version of the usb_generic_device_demo. It is modified to use the buttons to simulate changes to the temperature and potentiometer readings.

For more information about how to use the demo please see the getting started guide for this demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

usb_sk_generic_host_demo

See: <Install Directory>\usb_sk_generic_host_demo

This project contains USB firmware for the Starter Kit version of the USB Generic Host Demo. It has been modified so that the information received from the device is displayed on the MPLAB IDE using the db_utils debug IO support. A button can be pressed on the Starter Board to display the temperature and potentiometer data.

For more information about how to use the demo please see the getting started guide for this demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

usb_sk_hid_mouse_device_demo

See: <Install Directory>\usb_sk_hid_mouse_device_demo

This project contains USB firmware for the Starter Kit version of the usb_hid_mouse_device_demo. It has been modified to support the switches and LEDs available on the Starter Board.

For more information about how to use the demo please see the getting started guide for this demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

usb_sk_msd_device_demo

See: <Install Directory>\usb_sk_msd_device_demo

This project contains USB firmware for the Starter Kit version of the usb_msd_device_demo. It is essentially unmodified from the usb_msd_device_demo. However, usage of this demo with the USB Starter Board, requires an additional I/O Expansion board and PICtail(TM) board for SD(TM) and MMC cards.

For more information about how to use the demo please see the getting started guide for this demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

usb_sk_msd_host_demo

See: <Install Directory>\usb_sk_msd_host_demo

This project contains USB firmware for the Starter Kit version of the USB Data Logger demo. It has been modified to remove temperature and potentiometer data logging support and to use the MPLAB IDE for command input and terminal output via the db_utils Starter Kit debugger IO.

For more information about how to use the demo please see the getting started guide for this demo located in the “<Install Directory>\Microchip\USB\Documentation\Getting Started” directory.

USB Tools (code for the PC)

MCHPUSB Custom Driver (Custom/General Purpose)

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/generic 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 Tools\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/generic 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.

Pdfsusb (FS USB Demo Tool)

See: <Install Directory>\USB Tools\Pdfsusb

This Windows PC program demonstrates basic USB communication using the Microchip Custom class driver with a Windows GUI based application. The usb_generic_device_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 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.

USB CDC Serial Demo (Windows INF file)

See: <Install Directory>\USB Tools\USB CDC Serial Demo\inf

This file is required by the usb_cdc_serial_device_demo. Refer to the "Getting Started" guide for that demo for additional details.

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.

KNOWN LIMITATIONS

MCHPUSB Driver Example .inf

- 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"

Online Reference Documents

Note: Links provided below point to the latest version of the documents to date. Please check http://www.microchip.com/ for the latest version.

Application Notes

- AN1140 – USB Embedded Host Stack
- AN1141 – USB Embedded Host Stack Programmer’s Guide
- AN1142 – USB Mass Storage Class on an Embedded Host
- AN1144 - USB Human Interface Device Class on an Embedded Host
- AN1145 – Using a USB Flash Drive on an Embedded Host
- AN1176 - USB Device Stack for PIC32 Programmer's Guide
- AN1166 - USB Generic Function on an Embedded Device
- AN1163 - USB HID Class on an Embedded Device
- AN1169 - USB Mass Storage Class on an Embedded Device
- AN1164 - USB CDC Class on an Embedded Device

USB Design Center

- http://www.microchip.com/usb

PIC32 Design Center

- http://www.microchip.com/pic32

Customer 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 (http://support.microchip.com), online discussion groups/forums (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

Trademarks:

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 is a trademark 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.

Borland, and C++ Builder are trademarks or registered trademarks of Borland Software Corporation in the United States and other countries.

Linux is the registered trademark of Linus Torvalds in the U.S. and other countries.

PostScript is a registered trademark of Adobe®