Release Notes for MCHPFSUSB v2.1

Release Notes for Microchip USB Firmware Framework v2.1 – Microchip Full-Speed USB Solutions

March 31, 2008

Table of Contents

1. What's New/Updated in Release v2.1

2. Important Notes

3. What's in the Package

4. Known Limitations

5. Coming Soon – What’s next?

6. USB Compliance Test ID (TID) Information

7. Alternative Software Solutions

8. Online Reference Documents

9. Customer Support

# 1. What's New/Updated in Release v2.1

· Restructuring of the entire USB framework to be more compatible with other Microchip software libraries. This includes changes to the API of both the stack and several of the device drivers. For more details about what has changed please refer to the Migration Notes.

· Release of the embedded host support for the PIC24FJ256GB110

· Device support for the PIC24FJ256GB110 family.

· Microchip General Purpose USB Windows® Driver, mpusbapi.dll has been updated to v1.0.1.0. This version has changed the requested registry access, which now allows mpusbapi.dll to be used with basic user privileges in Widows Vista®.

· Addition of Mass Storage data logging demo

· Mass storage demo has been converted to use the same physical layer as the MDD file system interface to make the physical layer modular and interchangeable

· Mass storage demo as card removal/detection feature built in.

· Addition of support all ping-pong modes

· All project files and include paths have been created using relative paths. This means that the project files can now be moved or installed in any location without having to change include paths.

· PIC18F87J50 family bootloader firmware and PC application

· Addition of simple HID demo with both firmware and PC example code.

In order to make using each of the provided demos easier to use, a workspace file is provided for each of the demo boards for each of the demos where supported. At the end of the name of each of the work space files is the name of the demo board it supports; “PICDEM FSUSB”, “PIC18F87J50 PIM”, and “C30” (ex: PIC24FJ256GB110 PIM). None of the files inside of the project need to be modified in order to get the project to compile.

# 2. Important Notes

## Migration Issues

Please note that the restructuring of the entire USB framework includes changes to the API of both the stack and several of the device drivers. It is important to review the migration notes as there have been major changes in functionality and behavior of the firmware. For more details about what has changed please refer to the Migration Notes.

## Tool revisions

This release was tested with the following tools:

C18 – v3.13

C30 - v3.02c

MPLAB v8.10

## 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>\Microchip\USB\Utilities\MCHPUSB Custom Driver\MCHPUSB Driver\Release

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

## Notes about MPLAB® C18 C Compiler and MPLAB® C30 C Compiler

The example firmware projects included in the distribution are based around the MPLAB C18 and C30 compilers. Either the commercial version, or the free student version can be used to build the example projects. The compilers may be obtained from http://www.microchip.com/c18 and http://www.microchip.com/c30.

# 1. What's in the Package

## 1.1. Overview

The file directory structure of the v2.1 stack has changed. Details of their contents and purpose are described below.

.\<Install Directory>

\Microchip

\Include

\Help

\USB

\Documentation

\USB Device - Bootloaders

\USB Device – HID - Mouse

\USB Device – HID – Simple Custom Demo

\USB Device – Mass Storage – SD Card data logger

\USB Device – Mass Storage – SD Card reader

\USB Device – MCHPUSB - Generic Driver Demo

\Pdfsusb

\USB Host – Mass Storage - Data Logger

\USB PC – WM_DEVICECHANGE Demo

\USB Precompiled Demos

\USB Tools

## 1.2. 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 several full-speed USB demo board hardware platforms:

The PICDEM FS USB Demo Board (www.microchipDIRECT.com part number DM163025) enables evaluation of USB on the PIC18F4550 family devices.

The PIC18F87J50 FS USB Plug-In Module (PIM) demo board (www.microchipDIRECT.com part number MA180021) enables evaluation of USB on the PIC18F87J50 family devices. This board can be operated by itself or in conjunction with the High Pin Count (HPC) Explorer board (www.microchipdirect.com part number DM183022).

The PIC24FJ256GB110 USB Plug-In Module (www.microchipdirect.com part number MA240014) enables evaluation of USB on the PIC24FJ256GB110 family devices. In addition to the PIM the Explorer 16 (www.microchipdirect.com part number DM240001) and USB Pictail Plus board (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 (www.microchipdirect.com part number AC164122).

### 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 the MPLAB ICD2 programmer, open MPLAB IDE, click “Configure à Select Device”, then choose PIC18F4550 for the PICDEM FS USB Demo Board, or PIC18F87J50 for the PIC18F87J50 FS USB Demo PIM. 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 à 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.

### Device – MCHPUSB - Generic Driver Demo (for use with PDFSUSB.exe)

See: <Install Directory>\USB Device – MCHPUSB - Generic Driver 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). The code provided in the “Demo” project provides the firmware needed for the various features (such as temperature, potentiometer position) used by PDFSUSB.exe. See the below PC utilities section for more information about the PDFSUSB.exe tool.

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>\Microchip\USB\Utilities\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.

### Device - Human Interface Device Class (HID): Mouse in a Circle Demo Firmware

See: <Install Directory>\USB Device – HID - Mouse

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, although it is intended to be readily modified for developing other types of non-mouse HID class USB devices.

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 mouse in a circle demo may be used on these other platforms in addition to Windows.

Note: When using this firmware, the mouse cursor will continue to move in circles until the device is removed from the computer or until the designated push button is pressed on the 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.

### Device – Mass Storage Device (MSD): SD card reader

See: <Install Directory>\USB Device - Mass Storage – SD Card reader

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.

### Device – Mass Storage Device (MSD): SD card data logger

See: <Install Directory>\USB Device - Mass Storage – SD Card data logger

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 data logger. 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. The firmware also allows users to log the potentiometer data into a comma separated file (CSV) file that can be opened once the device is attached 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.

### Host – Mass Storage – Thumb Drive Data logger

See: <Install Directory>\USB Host – Mass Storage – Thumb Drive Data Logger

This project contains USB firmware which enables the embedded host devices (such as the PIC24FJ256GB110 family devices) to talk directly to a FAT16 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. 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.

### WM_DEVICECHANGE example code

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.

### Device - Bootloaders

See: <Install Directory>\USB Device - Bootloaders

This folder contains both the MCHPUSB bootloader for the PIC18F4550 family devices and the HID bootloader for the PIC18F87J50 family devices. Both the firmware projects and the PC side applications are available in this folder.

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.

### Device – HID – Simple Custom Demo

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

The HID class driver is found on nearly every operating system without requiring drivers for installation. This lends itself for creating simple USB devices that do not require drivers when plugged into the computer. This folder contains a simple example of how to create a simple custom HID device to talk over the USB. This folder also contains a PC example of how to access the HID drivers from a PC application.

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.

## 1.3. USB Tools/Code for the PC

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

# 2. Known Limitations

## CDC support

The Communication Device Class (CDC) device driver support has not yet been ported to the v2.1 framework.

## MSD support

The Mass Storage Device (MSD) class driver both in host mode and device mode only support FAT16 formatted media.

The Mass Storage Device (MSD) class driver demos have not currently been ported to the PICDEM FS USB board.

# 3. Coming Soon – What’s next?

- Adding USB On-The-Go (OTG) support.
- Port of the CDC device class driver to the v2.1 framework
- Addition of the HID host driver to the embedded host stack
- Addition of the Microchip custom host driver to the embedded host stack
- USBConfig.exe – Adding support for the USB device stack to the USBConfig.exe tool.
- Port of the MSD device class SD card reader demo to the PICDEM FS USB board.

# 4. USB Compliance Test ID (TID) Information

When getting a USB peripheral officially compliance tested, a peripheral checklist must be filled out and submitted to the USB-IF. These checklists are provided by the USB-IF. On the peripheral checklist, one of the requested items is the TID number associated with the USB silicon used in the device. Test ID numbers can be found at the USB Design Center:

http://www.microchip.com/usb

# 5. Alternative Software Solutions

There are many third party software solutions available in designing your USB application. A few examples are listed below:

SnoopyPro (software based USB traffic logger)

- http://sourceforge.net/projects/usbsnoop/

HIDmaker FS (example USB firmware/software generator)

- http://www.tracesystemsinc.com/usb_tools.ivnu

USB Software Solutions from Jungo® (assorted USB tools and driver generator)

- http://www.jungo.com/products_st.html

# 6. Online Reference Documents

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

## Demo Board User’s Guides

PICDEM™ FS USB Demonstration Board User’s Guide – 51526a

PIC18F87J50 FS USB Plug-In Module User’s Guide – 51678a

## Device Family Data Sheets

PIC18F87J50 Family Data Sheet – 39775b (or link to product page here)

PIC18F4450 Family Data Sheet – 39760d (or link to product page here)

PIC18F4550 Family Data Sheet – 39632d (or link to product page here)

PIC18F4553 Family Data Sheet – 39887b (or link to product page here)

PIC24FJ256GB110 Family Data Sheet – 39897b

## Application Notes

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

AN1003 – USB Mass Storage Device Using a PIC® MCU

AN1140 – USB Embedded Host Stack

AN1141 – USB Embedded Host Stack Programmer’s Guide

AN1142 – USB Mass Storage Class on an Embedded Host

AN1145 – Using a USB Flash Drive on an Embedded Host

## USB Design Center

http://www.microchip.com/usb

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