Readme for the PICkit(TM) 3 Programmer Application with scripting support

Beta Release: v3.00beta
Device File:  v1.62.14

Updated: 19 April 2012

-------------------------------------------------------------------------------
Table of Contents
-------------------------------------------------------------------------------
1. Introduction
2. Installing with the PICkit 3 Programmer Application
3. Working with the PICkit 3 Programmer Application
4. Building the Firmware
5. Known Limitations
6. Supported Devices
-------------------------------------------------------------------------------
1. Introduction
-------------------------------------------------------------------------------
This release of software/firmware allows the PICkit 3 to be compatible with the 
scripting framework that was originally developed for the PICkit 2. This allows
sharing device files and application support between PICkit 2 and PICkit 3.

The software adds other features that were only available on the PICkit 2 such
as the logic analyzer, logic output, and auto detection of devices. Future 
support is also planned for UART and other features not available in this Beta
release.

Since PICkit 3 is supported under MPLAB(R) IDE with non-scripting firmware, 
special firmware is needed to understand PICkit 2 scripts. A bootloader is used
to switch seamlessly between both operating systems.

-------------------------------------------------------------------------------
2. Installing with the PICkit 3 Programmer Application
-------------------------------------------------------------------------------
The PICkit 3 Programmer Application with scripting support is a modified version
of the PICkit 2 programmer application that was specially modified to work with
PICkit 3 scripting firmware.

To install the Application, unzip the contents of the zip file:
<PICkit3_scripting_app_v03.00beta.zip> into C:\Program Files\Microchip

The .NET framework version 4.00 is required. You can download it at:

http://www.microsoft.com/download/en/details.aspx?id=17718 (standalone)

or

http://www.microsoft.com/download/en/details.aspx?id=17851 (web version)

-------------------------------------------------------------------------------
3. Working with the PICkit 3 Programmer Application
-------------------------------------------------------------------------------
The GUI will recognize MPLAB IDE compatible firmware when started with a
PICkit 3 connected that is loaded with MPLAB IDE compatible firmware. 
A message indicating that an OS update is needed will be displayed. 
To change to PICkit 3 Programmer Application firmware, choose 
<Tools/Download PICkit Operating System> and then point to the path where an OS 
file and a bootloader file reside. This is typically in the same place where 
the PICkit 3 scripting executable resides. 

An OS file name format is <PK3OSxxxxxx.hex> where xxxxxx is the version number.
The bootloader hex file name format is <PK3BLxxxxxx.hex> where xxxxxx is the
version number. Once an OS is downloaded, the GUI will try to reestablish 
communication.

Please be aware that this OS is not compatible with MPLAB IDE, so to be able to
talk to MPLAB IDE again, <Tools/Revert to MPLAB mode> will need to be selected.
This reverts the PICkit 3 to bootloader mode so that MPLAB IDE can update the 
PICkit 3 with MPLAB IDE compatible firmware.

If an external programmer is used to program the firmware image, the bootloader 
should also be programmed into the device to allow updating of firmware or 
restoring MPLAB compatibility. A complete firmware image <PK3IMGxxxxxx.hex> 
is bundled with firmware source and the application. It includes startup code,
the bootloader, and the main OS.

If the GUI is used, it will automatically program the bootloader to flash memory 
and will remain resident until you switch to MPLAB IDE mode and update 
the firmware.

-------------------------------------------------------------------------------
4. Building the Firmware
-------------------------------------------------------------------------------

Below are the steps to build a firmware image which can be used with the GUI.

===========================================================================
NOTE:	These steps are only necessary if the firmware is modified by the 
        user. A pre-built firmware image <PK3IMGxxxxxx.hex> is bundled with
		this release for use with an externam programmer, and a pre-built
		OS image <PK3OSxxxxxx.hex> is bundled for use with the GUI.
		xxxxxx is the version number.
===========================================================================

===========================================================================
NOTE:   An MPLAB C30 compiler later than 3.30 is recommended.
===========================================================================

------------------------------------
Building a complete firmware image:
------------------------------------

These steps will produce a hex file that can be used for programming the 
PICkit 3 with an external programmer or for restoring the scripting firmware if
the image gets corrupted.

1- Unzip the firmware package file PICkit3_scripting_fw_beta.zip
2- Open MPLAB IDE.
3- Go to <Configure/Settings/Projects> and make sure that "Use one-to-one 
   project-workspace model is unchecked.
4- Open the workspace: <PICkit3.mcw> from the unzipped directory. You should see
   two projects loaded <branch.mcp> and <PICkit3OS.mcp>
5- Go to <Configure/Setting/Program Loading> and make sure "Clear program memory
   upon loading a program" is unchecked. This should be already saved in the 
   workspace. It allows the output of both projects to reside in MPLAB memory 
   side by side when building.
6- Build <branch.mcp> and <PICkit3OS.mcp> by right clicking on each project name
   in the project window and choosing "Build All".
7- After building, click on File/Import and point to the unzipped firmware
   directory. Select the file PK3BLxxxxxx.hex.
8- It is recommended verifying that the proper sections are loaded into memory, 
   by opening View/Program Memory and checking that the different sections of 
   code are loaded. There should be some data loaded (a goto instruction) at 
   the Reset address 0. The OS is loaded starting at 0x800 and the bootloader 
   at 0xF000. CTRL-G can be used to go jump to each of those addresses and 
   verify that some data is loaded there.
9- Finally do a File/Export to export an image. Make sure Program Memory from 
   0 to 0x2abf6 is selected as well as Configuration bits. This exported image
   can be used for programming with an external programmer.

------------------------------------
Building the OS only:
------------------------------------

These steps will produce an OS file that is suitable for downloading into the 
PICkit 3 using the GUI.

1- Repeat steps <1-6>. Keep in mind that building <branch.mcp> is not necessary
   for this step.
2- A hex file PICkit3OS.hex will be produced under the following path:
   <firmware unzip directory>\PICkit3OS\obj
3- Copy this file into the same place where the GUI executable and device file
   reside.

-------------------------------------------------------------------------------
5. Known Limitations
-------------------------------------------------------------------------------
- This beta release does not include UART support. This will be added in a future
  release.
- Programmer-To-Go is not supported under this software. To use this feature, 
  please use the MPLAB IDE.
- This beta release does not support automatic generation of an OSCCAL value.
- Aside from this README file, documentation for this release is identical to
  the documentation bundled with the PICkit 2 GUI. Most of that documentation
  applies to this release.

-------------------------------------------------------------------------------
6. Device Support
-------------------------------------------------------------------------------
This release contains device file 1.62.14. Please refer to the PICkit 2 README
file for a list of supported devices. 

===========================================================================
NOTE:   The following devices are not supported yet in the PICkit 3 version:

		KEELOQ HCS devices
		MCP250xx CAN devices
		Serial EEPROM Devices
		
===========================================================================

-------------------------------------------------------------------------------
