Getting Started: Using the “USB Device – Bootloaders”

# Overview:

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.

The MCHPFSUSB distribution comes with two separate USB bootloader example applications (and corresponding firmware projects): “HID Bootloader” and “MCHPUSB Bootloader”.

As of this release the “HID Bootloader” is intended to be used with all released Microchip USB flash microcontrollers, to include all devices from the following microcontroller families:

1. PIC18F14K50 Family

2. PIC18F46J50 Family

3. PIC18F4450 Family

4. PIC18F4550 Family (and PIC18F4553 Family)

5. PIC18F87J50 Family

6. PIC24FJ256GB110 Family

7. PIC24FJ64GB004 Family

8. PIC32MX460F512L Family

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.

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.

# HID Bootloader:

The HID bootloader related source code can be found in the following location “<install directory>\USB Device - Bootloaders\HID - Bootloader”. The bootloader relies on the HID class protocol. Therefore, no driver installation is necessary, as common operating systems ship with HID class USB drivers built in.

As configured by default, the bootloader has the following characteristics:

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 HID class USB device.

The HID 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 HID 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-0xFFF (on PIC18 devices, different for PIC24 and PIC32 devices). Almost immediately after coming out of reset, the bootloader firmware checks an I/O pin. If the I/O pin reads logic low, the microcontroller will enter the bootloader firmware. If the I/O pin is logic high, the bootloader will immediately exit the bootloader and go to the main application firmware “reset vector”. The specific I/O pin that will be checked is different for the various versions of the firmware projects. As configured by default, when used with one of the Microchip USB related demonstration boards/platforms, the I/O pin that is checked will have a pushbutton attached to it.

In other words, at startup the bootloader effectively does this:

//Device powers up, and comes out of POR

if(I/O pin pushbutton is not pressed) --> goto 0x1000 //main application “reset vector”

if(I/O pin pushbutton is pressed) --> goto/stay in the HID bootloader firmware.

Effectively, the “reset” vector for the main application firmware is at address 0x1000. In the main application firmware project, the user should place a “goto _startup” at address 0x1000. 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. By default, most of the project varients are already configured to be able to generate .hex files that can be used with the HID bootloader.

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.

Vector Remapping:

PIC18: 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)

PIC24F: As currently configured, the bootloader occupies the address range 0x0000 – 0x1400, which means it occupies the PIC24F reset, interrupt, and alternate 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 0x0006 (OscillatorFailure interrupt vector), contains a “goto 0x1408”.

Address 0x0008 (AddressError interrupt vector), contains a “goto 0x140C”.

Etc.

For example, if a OscillatorFailure interrupt is enabled and used by the main application firmware, the following will occur:

1. Main application enables the interrupt source.

2. Sometime later, the interrupt event occurs.

3. Microcontroller jumps to 0x0006.

4. Microcontroller executes a “goto 0x1408”

5. Microcontroller executes a “goto _OscillatorFailure” instruction that will jump to the appropriately defined interrupt handler (or the DefaultInterrupt if the interrupt handler is not defined. This jump is located in the modified linker (.gld) file that is used with the application.

In order to appropriately remap the interrupts, the appropriate *.gld file must be copied from the “Application Linker Files” folder to the project folder and attach it to the project.

Note: When using the HID bootloader for PIC32 only (not applicable to other devices), it is important to modify the procdefs.ld file to relocate the sections of code that will hold the bootloader and those sections that will hold the user application. Example modified procdefs.ld files have been provided with each project. This file is currently named “Procdefs.ld.boot”. When using the example project with the bootloader it is required to remove the “.boot” section of the file. This will allow MPLAB to use this file instead of the default linker file. Once the linker file is renamed, however, the project will no longer work without the bootloader. Please rename the file in order to get the project working again with PIC32.

Memory Map Summary (PIC18): 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

Using the HID Bootloader PC Application: 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”) (www.microchipDIRECT.com part number MA180024), 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:

PICDEM FS USB Demo Board (PIC18F4550 based): S2 (RB4) pushbutton

PIC18F46J50 FS USB Demo Board (aka PIM): S2 (RB2) pushbutton

PIC18F87J50 FS USB Demo Board (aka Plug-In Module/PIM): S4 (RB4) pushbutton

PIC24F256GB110 PIM: S3 on Explorer 16 (RD6) pushbutton

PIC32MX460F512L PIM: S3 on Explorer 16 (RD6) pushbutton

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 (except for PIC32) 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).

Usage Tips:

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

Important note concerning VID and 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.

# MCHPUSB Bootloader:

The “<install directory>\USB Device - Bootloaders\Vendor Class - MCHPUSB Bootloader” bootloader is essentially the same as that which is distributed in previous MCHPFSUSB v1.x distributions. This bootloader is meant to be used with the PIC18F4550 family and PIC18F4553 family of USB microcontrollers. However, this bootloader is not recommended for new designs. It is recommended to use the HID Bootloader instead, as the HID Bootloader is superior in many ways.

The MCHPUSB Bootloader relies on the MCHPUSB custom (vendor) class general purpose USB driver. This driver can be found in the “<Install Directory>\USB Tools\MCHPUSB Custom Driver\MCHPUSB Driver\Release” folder.

As currently configured, the bootloader has the following characteristics:

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)

Using the MCHPUSB Bootloader PC Application: 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)

## 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 and PICtail are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries.

Microsoft, Windows, Visual Studio, Visual C++, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.