Release Notes for MPLAB PM3 Command Line Interface

MPLAB® IDE v8.92
Software and Firmware versions:
 MPPm3.dll	v2.40.1.56	
 PM3Cmd.exe	v2.30.95
 PM3 Suite (OS/FW)	v2.13.12	(pm3021312.mjc)


July 8, 2013


-----------------------------------------------------------------------------
Table of Contents
-----------------------------------------------------------------------------
1.  Tool Definition
2.  Device Support List
3.  Operating System Support List
4.  What's New or Updated
5.  Known Problems
6.  Important Notes
7.  Socket Support
8.  Installation
9.  Upgrading the MPLAB PM3 Operating System
10. Command Line Options
11. Command Line Examples
12. Customer Support

----------------------------------------------------------------------------
1. Tool Definition
----------------------------------------------------------------------------
MPLAB PM3 Command Line Interface (PM3CMD) is a 32-bit 
command-line interface to the MPLAB PM3 device programmer.
This interface is designed for programming devices in a 
production environment with limited resource PCs (Pentium or 
better). Possible uses for this interface include:
 - Setting up a MPLAB PM3 for stand-alone programming
 - Updating device programmer firmware
 - SQTP programming

The PM3CMD executable may be found, by default, in:
C:\Program Files\Microchip\MPLAB IDE\Programmer Utilities\PM3Cmd

This Readme is targeted to users of the command-line
interface. Refer to "Readme for MPLAB PM3.txt" for more 
information about the MPLAB IDE interface to MPLAB PM3.

----------------------------------------------------------------------------
2. Device Support List
----------------------------------------------------------------------------
Device support is dependent on the firmware version installed
in the MPLAB PM3 device programmer. Refer to the file
"Readme for MPLAB PM3.txt" for the list of supported devices 
and what firmware files support which devices.

When selecting a part using the "P" option (section 9), use the 
following:

- PICmicro devices: drop "PIC", e.g., PIC16F877 becomes 16F877
- dsPIC devices:    drop "dsPIC", e.g., dsPIC30F6014 becomes 30F6014
- rfPIC devices:    drop "rfPIC" and appended letters, e.g., 
                    rfPIC12C509AG becomes 12C509

----------------------------------------------------------------------------
3. Operating System Support List
----------------------------------------------------------------------------
Windows 98, Windows® 2000 SP4, Windows XP SP2, and Windows Vista™ (32-Bit)* OSs

* Only initial testing has been performed on 32-bit Vista for this release. 
64-bit Vista is not supported at this time.

NOTE: Windows NT® and Windows ME OSs are NOT supported.

----------------------------------------------------------------------------
4. What's New or Updated
----------------------------------------------------------------------------
A new command line switch (u) has been added to indicate that the 
calibration memory value should be programmed is now available.


Program Calibration Memory: It is now possible to program the calibration 
memory of flash devices such as the 12F675, which display the calibration 
value in the last address of Program memory by use of the Calibration tab 
page in the Settings dialog. For OTP devices that have the calibration 
memory, programming has not changed – it will only be performed if the 
calibration value in the last address of Program memory is blank.

----------------------------------------------------------------------
5. Known Problems
----------------------------------------------------------------------

PM3-362: PM3CMD does not save the '/w'setting to an Environment.

29377:  The calibration value for the 16C433, if blank, cannot be 
programmed using PM3CMD.  The workaround is to use the calibration 
tab page in the Settings dialog in the MPLAB IDE or Visual PROCMD.

Downloading Non-MPLAB IDE Generated Hex Files:
Directly downloading a hex file not generated by MPLAB IDE, such as an 
Intel 32 Byte (INHX32), with the PM3CMD.exe programmer standalone utility,
may result in an error message. As a workaround, import the hex file into 
MPLAB IDE then export the hex file from MPLAB IDE in order to create a 
hex file compatible with PM3CMD.

----------------------------------------------------------------------------
6. Important Notes
----------------------------------------------------------------------------
- After installing a socket module, it is good practice to do
a blank check on a known blank device to verify that the
socket module is seated properly.  To perform a blank check
in stand-alone mode on the MPLAB PM3, select the desired device 
type, insert a blank device, and select All Functions>Blank Check 
Device.  If the device reads back blank, the message "Device Blank" 
will be displayed.

- Serial Baud Rate is 57600. 

----------------------------------------------------------------------------
7. Socket Support
----------------------------------------------------------------------------
Refer to the Development Tools Selector (DTS) located on:
- the Microchip web site (www.microchip.com) 
  Select "Development Tools" under "Design", then select
  "Development Tool Selector" under "Resources".
- the MPLAB IDE CD-ROM you used to install MPLAB 

----------------------------------------------------------------------------
8. Installation
----------------------------------------------------------------------------
From the MPLAB IDE installation, choose to install PM3CMD. Its default
installation location is listed under "1. Tool Definition".

----------------------------------------------------------------------------
9. Upgrading the MPLAB PM3 Operating System
----------------------------------------------------------------------------
If MPLAB PM3 did not recognize your socket module (i.e.,
socket not supported), you may need to update the firmware.
You can obtain the latest MPLAB PM3 firmware from our website
(www.microchip.com). Once you have the firmware, you will need
to download this file to the MPLAB PM3.

----------------------------------------------------------------------------
10. Command Line Options
----------------------------------------------------------------------------
The following commands are available in the command line interface.
                           PM3 COMMAND LINE HELP
Options              Description                              Default
----------------------------------------------------------------------------
#                    Communication Ports 1 thru 5 supported.  1
                     Com ports 1-4 indicates RS232, Com Port
                     5 indicates USB.
A                    VddApp                                   Device Specific
B<Operation><path>   Environment Operation                    None
                     Operation L: = Load Environment,
                                  All paths = full file
                                  path. All paths located
                                  on the PM3Card must be
                                  preceeded by a 'P' All
                                  Paths on the computer
                                  must be preceeded by a
                                  'C'
                     Operation S: = Save Environment,
                                  All paths = full environment
                                  path. All paths located
                                  on the PM3Card must be
                                  preceeded by a 'P' All
                                  Paths on the computer
                                  must be preceeded by a
                                  'C'
                     Operation D: = Delete Environment,
                                  All paths = full file
                                  path. All paths located
                                  on the PM3Card must be
                                  preceeded by a 'P' All
                                  Paths on the computer
                                  must be preceeded by a
                                  'C'
                     Operation C: = Copy Environment,
                                  path = full file path to
                                  the environment file of
                                  the environemnt to be copied,
                                  followed by the path to
                                  the destination directory.
                                  The two paths must be
                                  separated by an asterisk
                                  (*), and each path must
                                  be preceded by either 'C'
                                  if the path is on the
                                  computer or 'P' if the
                                  path is on the PM3.
                      Operation V: = View Environment,
                                  path = full file path to
                                  the environment file of
                                  the environemnt to be viewed.
                                  All paths located
                                  on the PM3Card must be
                                  preceeded by a 'P' All
                                  Paths on the computer
                                  must be preceeded by a
                                  'C'
C                    Blank Check Device                       Do not Blank Check
D<file>              OSSuite File Selection                   None
E                    Erase Flash Device                       Do Not Erase
F<file>              Hex File Selection                       None
G<Type><range/path>  Read functions                           None
                     Type F: = read into hex file, 
                             path = full file path,
                             range is not used
                     Types P,E,I,C: = ouput read of Program,
                             EEPROM, ID and/or Configuration
                             Memory to the screen. P and E 
                             must be followed by an address 
                             range in the form of x-y where
                             x is the start address and y is
                             the end address both in hex,
                             path is not used
H                    Read Checksum                            Do Not Read Checksum
I                    Display Device ID                        Do Not Display
K                    Display Hex File Checksum                Do Not Display
L                    Low voltage programming                  Not Selected
M<memory region>     Program Device                           Do Not Program
                     memory regions:
                         P = Program memory
                         E = EEPROM
                         I = ID memory
                         C = Configuration memory
                         If no region is entered, the entire
                         device will be programmed.
N                    Vdd Min                                  Device Specific
P<part>              Part Selection. Example: 16f877          None
Q                    Quiet Mode, no screen output             Quiet mode off
R<on> <off>          Safe/Restricted Mode                     None
S<file>              SQTP File Selection                      None
T                    Vdd Nominal.                             Device Specific
U                    Overwrite calibration memory             Do Not overwrite
V                    Vpp                                      Device Specific
W                    Externally power target                  Power from PM3
X                    Vdd Max                                  Device Specific
Y<memory region>     Verify Device                            Do Not Verify
                         P = Program memory
                         E = EEPROM
                         I = ID memory
                         C = Configuration memory
                         If no region is entered, the entire
                         device will be verified.
Z                    Preserve EEData on Program              Do Not Preserve
?                    Help Screen                              Not Shown

     Each option must be immediately preceeded by a switch, Which can
     be either a dash <-> or a slash </> and options must be separated
     by a single space.

     Example:   PM3CMD /1 /P16F877 /Fc:\mycode /M
                               or
                PM3CMD -1 -P16F877 -Fc:\mycode -M

     Any option immediately followed by a question mark will envoke
     a more detailed description of how to use that option.

     Commands and their parameters are not case sensitive. Commands will
     be processed according to command order of precedence, not the order
     in which they appear on the command line. To see a list of the command
     order of precedence type -?? on the command line.

     The program will return an exit code upon completion which will
     indicate either successful completion, or describe the reason for 
     failure. To view the list of exit codes and their descriptions,
     type -?E on the command line.

     Version 02.30.66


----------------------------------------------------------------------------
11. Command Line Examples
----------------------------------------------------------------------------
COMMAND LINE
   OPERATION PERFORMED
-----------------------------------------------------------------------------
PM3CMD /?
   Help screen displayed.

PM3CMD /?E
   All eXit (error) codes displayed.

PM3CMD /M?
   Help for the /M option displayed.

PM3CMD /DPIC60000.HEX
 Or
PM3CMD /1 /DPIC60000.HEX
   Firmware file PIC60000.HEX downloaded to MPLAB PM3 on COM1.
   COM1 is chosen by default.

PM3CMD /1 /P16F84A
   MPLAB PM3 on COM1 set to a PIC16F84A.

PM3CMD /1 /P16F84A /RON
   MPLAB PM3 on COM1 set to a PIC16F84A. MPLAB PM3 set to
   safe mode.

PM3CMD /1 /P16F877 /N4.5 /X5.5 /FPROGRAM.HEX
   MPLAB PM3 on COM1 set to a PIC16F877. Vdd Min set to 4.5v.
   Vdd Max set to 5.5v.  Vpp set to the device's default
   value.  File PROGRAM.HEX sent to the MPLAB PM3.

PM3CMD /1 /P16F877 /N4.5 /X5.5 /FPROGRAM.HEX /MP
   MPLAB PM3 on COM1 set to a PIC16F877. Vdd Min set to 4.5v.
   Vdd Max set to 5.5v.  Vpp set to the device's default
   value.  File PROGRAM.HEX sent to the MPLAB PM3. The 
   device's program memory is programmed, with blank values 
   in the locations not specified by PROGRAM.HEX.

PM3CMD /1 /P16F877 /T2.5 /FPROGRAM.HEX
   MPLAB PM3 on COM1 set to a PIC16F877. Low Voltage Programming 
   algorithm used to program the hex file PROGRAM.HEX.

PM3CMD /2 /P12C508A /FVOLTS.HEX
   MPLAB PM3 on COM2 set to a PIC12C508A. Hex file VOLTS.HEX
   sent to the MPLAB PM3. Voltages set to devices default
   values.

PM3CMD /2 /P12C508A /FVOLTS.HEX /SSQTP.NUM /M
   MPLAB PM3 on COM2 set to a PIC12C508A. Hex file VOLTS.HEX
   sent to the MPLAB PM3. Voltages are set to the device's
   default values, and one entry from the SQTP file
   SQTP.NUM is sent.  All of the device's memory is programmed, 
   with blank values in the locations not specified by VOLTS.HEX 
   and SQTP.NUM.  If programming is successful, the SQTP entry 
   is marked as used.

PM3CMD /3 /P17C42A /FAPPCODE.HEX /M
   MPLAB PM3 on COM3 is set to a PIC17C42A. The file
   APPCODE.HEX is sent to PRO MATE. Voltages are set to the
   device's default values. All of the device's memory is 
   programmed, with blank values in the locations not 
   specified by APPCODE.HEX.

PM3CMD /3 /P17C42A /M
   MPLAB PM3 on COM3 is set to a PIC17C42A. The device is
   programmed with the current contents of the device
   programmer at the currently selected voltage levels.

PM3CMD /3 /P17C42A /SSERIAL.NUM /M
   MPLAB PM3 on COM3 is set to PIC17C42A, and one entry from
   the SQTP file SERIAL.NUM is sent.  A device is programmed
   with the current contents of the device programmer
   and the serial number at the currently selected voltages.
   If programming is successful, the entry is marked as used.

PM3CMD /2 /P16F84 /FHEXCODE.HEX /Y
   MPLAB PM3 on COM2 is set to a PIC16F84. Voltages are set
   to the device's default values. The device is verified 
   against the contents of HEXCODE.HEX.

PM3CMD /2 /P16F84 /FHEXCODE.HEX /M /Y
   MPLAB PM3 on COM2 is set to a PIC16F84. The file
   HEXCODE.HEX is sent to MPLAB PM3. Voltages are set to the
   device's default values and the device is programmed.
   After programming, the device is verified against the 
   contents of HEXCODE.HEX.

   Note: The Verify (/M) operation implicitly performs a
   Verify when it completes the programming portion of the 
   operation. Specifying a Verify (/Y) in the above manner 
   effectively causes two Verify operations to be performed.

PM3CMD /3 /P18F4220 /FAPPCODE.HEX /Z /M
   MPLAB PM3 on COM3 is set to a P18F4220. The file
   APPCODE.HEX is sent to MPLAB PM3. Voltages are set to the
   device's default values. All of the device's memory is 
   programmed, with blank values in the locations not 
   specified by APPCODE.HEX. The /z switch specifies PRO MATE
   to preserve EEData.

PM3CMD /3 /P18F4220 /FAPPCODE.HEX  /E /Z /M
   MPLAB PM3 on COM3 is set to a P18F4220. The file
   APPCODE.HEX is sent to MPLAB PM3. Voltages are set to the
   device's default values. All of the device's memory is 
   programmed, with blank values in the locations not 
   specified by APPCODE.HEX. 

   Note: The Erase Flash device (/E) Erases EEData,even though
   /Z switch specifies MPLAB PM3 to preserve EEData, because 
   /E switch overrides /Z switch.

PM3CMD /P30F6014 /FDSPIC.HEX /MP0-FF
   MPLAB PM3 on COM1 is set to a dsPIC30F6014. The file 
   DSPIC.HEX is sent to MPLAB PM3. Voltages are set to the 
   device's default values. Device memory from location 0x00
   to 0xFF is programmed.

-blcc:\environment1\environment1.pm3
   Loads the environment data from the PC. This option must 
   be followed by the source of the environment, in this case
   'C' for the environment which resides on the computer. The
   complete file path of the environment file must then follow
   the source.

-blpenvironment1\environment1.pm3
   Loads the environment data from the PM3 Card. This option must 
   be followed by the source of the environment, in this case
   'P' for the environment which resides on the MPLAB PM3. The
   complete file path of the environment file must then follow
   the source.

-bscc:\environment1
   Saves the environment data from the PC. THis option must be 
   followed by the destination of the saved environment, in this
   case 'C' for the computer. The complete path of the environment,
   including the environment name, must follow the destination. See
   the help (-b?) for additional information regarding setting up
   the environment.

-bspenvironment1
   Saves the environment data from the PM3 Card.This option must be 
   followed by the destination of the saved environment, in this
   case 'P' for the PM3 Card. The complete path of the environment,
   including the environment name, must follow the destination. See
   the help (-b?) for additional information regarding setting up
   the environment.

-bccc:\Environment1\Environment1.pm3*pEnvironment1
   Copies the Environment1 data from the computer, to an 
   Environment1 folder on the PM3 Card.

Notes
-----

The communication port will use the default COM port.

If downloading firmware, only the communications port and
the /d option can be specified.

If not downloading firmware, a device must be specified.

It is not necessary to send the hex file every time a device
is programmed.  In a production environment, it would be
beneficial to use one command line execution to transfer
the hex file and set up any voltages, and then use
subsequent command line executions to program or program
with SQTP numbers.

If a hex file is specified, only the locations specified in
the hex file are programmed.  If an SQTP file is also
specified, then all of the device is programmed.

If a hex file is not specified, the entire contents of the
MPLAB PM3 device programmer are programmed into the device.

All values not specified in the hex file are set to blank
(erased) values.

SQTP information is only sent to the device programmer if
the device is programmed.

SQTP lines are marked as used only if programming is
successful.

----------------------------------------------------------------------------
12. Customer Support
----------------------------------------------------------------------------
The Microchip Web Site
----------------------

Microchip provides online support via our web site at 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, 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

myMICROCHIP Personalized Notification Service
---------------------------------------------

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

Please visit http://www.microchip.com/pcn to begin the registration process 
and select your preferences to receive personalized notifications. A FAQ and registration details are available on the page, which can be opened by 
selecting the link above.

When you are selecting your preferences, choosing “Development Systems” will populate the list with available development tools. The main categories of 
tools are listed below:

Compilers – These include all MPLAB C compilers; all MPLAB assemblers 
(including MPASM™ assembler); all MPLAB linkers (including MPLINK™ object 
linker); and all MPLAB librarians (including MPLIB™ object librarian), 
as well as HI-TECH C compilers.

Emulators – These include the MPLAB REAL ICE™ and MPLAB ICE 2000 in-circuit emulators

In-Circuit Debuggers – These include the MPLAB ICD 3 in-circuit debugger, 
MPLAB ICD 2 in-circuit debugger, PICkit™ 3 debug express and PICkit 2 debug express.

MPLAB IDE – This includes MPLAB IDE, the Windows® Integrated Development Environment for development systems tools, MPLAB IDE Project Manager, 
MPLAB Editor and MPLAB SIM simulator, as well as general editing and 
debugging features.

Programmers –These include the MPLAB PM3 and PRO MATE II device programmers
and the PICSTART® Plus and PICkit 1, 2 and 3 development programmers.

Starter/Demo Boards – These include MPLAB Starter Kit boards,
PICDEM demo boards, and various other evaluation boards.

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
