Program PIC_PROG
27 February 2013
pic_prog [options]
Write the program to a Microchip PIC (registered trademark of Microchip
Inc, http://www.microchip.com) microcontroller via a PIC programmer
conforming to the Embed Inc PIC programmer protocol. The protocol is
described in the PICPRG_PROT documentation file. Conforming programmers
include the Embed Inc USBProg, ProProg and EasyProg.
The programmer must be on and the target chip properly connected before
this program is run. The programmer must also be connected to the
computer running this program.
The default operation is to report the programmer type, firmware version,
and target chip type and perform no other operation.
This program always returns a zero processes exit status when all
requested operations were perform, and non-zero when any error was
detected. This can be used, for example, to determine if the programming
operation succeeded when PIC_PROG is launched from higher level production
test or calibration software.
The command line options are:
-HEX filename
filename
Specifies the input file name. This must be a HEX file as produced
by MPLAB. The ".hex" file name suffix will be assumed and may be
omitted from the FILENAME argument.
The first command line option that does not start with a dash (-)
is assumed to be the HEX input file name. This is a short form of
supplying the file name for convenience, but can not be used when
the file name starts with a dash. The full form of this option
using the -HEX keyword works whether the file name starts with a
dash or not. In either case, if the file name includes spaces or
some other special characters, it must be enclosed in quotes ("")
or apostrophies ('').
The default operation when a HEX file is supplied is to program the
contents of the HEX file into the target system and perform two
verify passes, one at each of the Vdd limits for that target chip.
This command line option is mutually exclusive with -ERASE. The
default is to report the target chip type and perform no other
operations.
-SIO n
Selects the system serial line number to use in communicating with
the programmer. Only that programmer is accessed.
The default is to use the first available programmer known to be
connected to the system. If no known connected programmer exists,
then the programmer connected to serial line 1 is used.
-N name
Selects the programmer by name.
If no other command line option specifies a connection means to the
programmer (like -SIO), then the first programmer of this name from
those known to be connected to the system is used. A programmer is
known to be connected to the system if it is connected and uses a
connection type that the system can enumerate, such as USB.
If a connection type is specified, the first programmer found with
that name and connection type is used. Note that some connection
types inherently specify a unique programmer, such as serial line,
since only a single device can be attached to any one serial line.
In that case it is an error if the programmer does not have the
indicated name or does not have a name.
The NAME parameter is case-sensitive. Programmer names can
generally be set by the user (see the PIC_CTRL command). It is
strongly recommended that all programmers connected to a system
have a unique name. Otherwise the choice of programmer used when a
non-unique name is given is arbitrary, and there is no way to
select between multiple programmers of the same name. All Embed
Inc programmers that have names are initially given globally unique
names by Embed Inc.
-PIC name
Explicitly identifies the target PIC. Example names are "16F876",
"18F452", and "16LF628". Note that the suffixes denoting package
type, temperature range, etc, are not included. The NAME argument
is case-insensitive.
If this command line option is omitted, then the programmer
attempts to determine the target chip type by reading its hard
coded ID. If successful, the program will proceed assuming the
most generic variant with that ID. For example, the 16F628 and
16LF628 have the same ID word. If that ID is found, then the
16F628 will be assumed unless this command line option is used and
16LF628 specified.
Some PICs do not contain hard coded IDs, and it is not possible to
determine the exact target chip type. It appears that PICs with
the 12 bit "baseline" core, such as the 10F2xx, do not contain
target IDs. In case of such a target PIC, this command line option
is required. The program will abort with an error condition if
this command line option is omitted and the target PIC type can not
be determined.
If this command line option is supplied, then that particular
target PIC is verified to the extent possible. If that target type
has a unique ID, then the ID is read and checked against the
expected value. If the target has no unique ID, some test are
performed to verify the target chip, but these are not guaranteed
to be conclusive. The program will abort with an error condition
only if it can conclusively determine that the target PIC is not
the one specified with this command line option.
-ERASE
Erase the target chip without writing new information to it. This
command line option is mutually exclusive with specifying a HEX
file. The default is to report the firmware version and type and
the target chip type, when possible, and perform no other
operations.
-V
Verify the data in the target chip only. The target chip is not
erased or written to. If a mismatch between the data in the HEX
file and the target chip is found, the program will write an error
message and exit with error status. The default when a HEX file is
supplied but without the -V option is to program the HEX file data
into the target PIC and perform two verify passes, one at each of
the Vdd limits of that target PIC type.
-RUN Vdd
Power up and let the target circuit run after all other operations
have been completed. The default is to disengage from the target
circuit or chip to the extent possible. Programmers with dedicated
programming sockets generally passively hold all lines low. In-
circuit programmers generally set all lines to high impedence.
The VDD parameter is the level in volts to drive the target Vdd
(power) line to. Only values from 0.0 to 6.0 are valid. All other
lines are set to sufficiently high impedence so that most target
circuits will operate as if the programmer is not connected.
The program is aborted with error status before any target chip
operations are performed if the programmer is not capable of the
requested -RUN operation. This may be because this feature is not
implemented, the programmer is not capable of supplying significant
Vdd current, is not capable of releasing the Vpp line to high
impedence, etc.
By default, the program exits when -RUN mode is started. This can
be changed with the -BEND command line option (below). Note that
-RUN and -LOOP used together imply -BEND.
-BEND
Wait after programming and after -RUN mode is entered (if enabled)
until the user button is pressed, then release all target circuit
lines to high impedence and exit the program. By default, the
program exits when done performing the programming operation, or
when -RUN mode is entered if -RUN was specified. -BEND may be
useful to terminate -RUN mode, or to prevent other software from
communicating with the programmer until the button is pressed.
-BEND is implied when both -RUN and -LOOP are specified. This
means two separate button presses are required to program each
unit. The first is indicated with the App LED brightly lit, and
starts programming. After programming -RUN mode will automatically
start. The Status LED will be flashing and the App LED will be
off. Pressing the button now ends -RUN mode, sets all target lines
to high impedence and lights the App LED to indicate waiting to
program a new unit. In this case, target units should only be
connected and disconnected when the App LED is brightly lit.
-WAIT
Wait to interact with the target circuit or chip until the user
button on the programmer is pressed. The "App" LED will be lit
brightly indicating that operation is suspended until the button is
pressed. The App LED will be switched off as confirmation when the
button press is detected.
A single button press starts the operation. However the button can
also be double clicked (two button presses within 3/10 of a second)
to abort the operation. By default, this causes the program to
abort with error status. This behaviour is different when the
-LOOP command line option is used. See the -LOOP command line
option for details.
The program is aborted with error status before any target chip
operations are performed if the programmer has no user button or
App LED.
-LOOP
Repeatedly perform the indicated operation. -LOOP implies -WAIT.
If -RUN and -LOOP are both specified, then -BEND is also implied.
Since the program will continue indefinitely until the button is
double clicked, this is considered the normal way to exit the
program. The program will exit with normal status on double click.
The last line written to standard output will show the number of
operations performed. Note that this may be zero if the button was
double clicked the first time.
The purpose of this command is to streamline production where a
number of target systems are programmed in succession. The
operator can swap in a new target system and initiate programming
without performing actions on the host computer.
-NPROG
Do not program or verify the target chip. The target chip non-
volatile memory is not altered or read back, but all other
operations are performed. This option can be useful for validating
a HEX file for the particular target chip.
-D18
Assume the EEPROM address offsets in the HEX file are doubled for
PIC 18 target types. This is the case if the CODE directive was
used to define the EEPROM segment instead of the CODE_PACK
directive. While CODE_PACK is the correct method, it was poorly
documented by Microchip and many users were not aware of it. This
command line option allows for compatibility when CODE was used.
The default is compatible with CODE_PACK, meaning EEPROM bytes are
assumed to be stored at sequential addresses in the HEX file. When
this command line option is used, EEPROM data is still assumed to
start at address F00000h in the HEX file, but each odd offset is
unused.
For example, the first 4 bytes of EEPROM are to be set to 1, 2, 3,
and 4. In the default case without -D18 the HEX file must contain
(all values are in hexadecimal):
Address Data
F00000 01
F00001 02
F00002 03
F00003 04
If the -D18 option is used, the HEX file must contain:
Address Data
F00000 01
F00001 -- ignored --
F00002 02
F00003 -- ignored --
F00004 03
F00005 -- ignored --
F00006 04
-VDD v
Indicate that all operations are to be performed at the single Vdd
level of V volts. The default is to use the three voltage levels
specified in the PICPRG.ENV file for the particular target PIC.
See the PICPRG_ENV documentation file for a description of the
PICRPG.ENV file. Note that some programming functions, like bulk
erase, are often specified to work over a narrower range of
voltages than normal PIC operation. It is up to the user to ensure
a valid Vdd voltage is selected.
This option should be used if the target circuit is separately
powered from the programmer, although this is not recommended for
programmers that are intended to drive Vdd. In that case there
should be no connection to the output Vdd of the programmer.
However, the programmer may still need to adjust the level it uses
for the PGC and PGD lines according to the target circuit fixed Vdd
level. This command line option provides a means of indicating
what that level is.
Only a single verify pass will be performed if this command line
option is used.
-NOVERIFY
Perform no verification of the data programmed into the target
chip. This command line option is provided to decrease overall
programming time when other external means are used to verify the
programmed data.
THIS COMMAND LINE OPTION IS NEVER RECOMMENDED BY EMBED INC. Use it
at your own risk only if you know exactly what you're doing.
The default is to verify the data programmed into the target twice,
once at each of the Vdd limits for that target.
-QV
Quick verify. Verify only those target locations explicitly
specified in the HEX file. The default is to verify all target
locations, whether mentioned in the HEX file or not. All locations
not mentioned in the HEX file will be set to the erased value of
all bits set to 1. The purpose of this command line option is to
decrease the verification time.
This command line option should ONLY be used if it is absolutely
certain that the values of any locations not listed in the HEX file
do not matter to the operation of the program. With this command
line option, locations that were not correctly erased may not be
detected as errors.
Some locations not mentioned in the HEX file may still be verified
when this command line option is used, but generally large chunks
of unused program memory are not verified.
The default is to verify all target locations twice, once at each
of the Vdd limits for the particular target device.
-LVP
Forces use of low voltage program mode entry in cases where the PIC
supports both high and low voltage over the same PGC/PGD interface.
High voltage means raising the MCLR pin above Vdd. Low voltage
usually means clocking in a special key sequence while MCLR is held
low. Most PICs require one or the other method, but some, like the
16F1xxx series support both.
By default, the high voltage method is chosen when it is supported
both by the PIC and the programmer. The high voltage method is
generally more desirable in that it unambiguously enters program
mode, and sometimes more features are available when program mode
is entered that way.
It may be necessary to force low voltage program mode entry due to
hardware limitations. For example, other circuitry connected to
MCLR may not tolerate voltages above Vdd, or the connection to the
programmer may prevent voltages above Vdd from reaching the MCLR
pin. In those cases, and if the programmer and the PIC both
supported high voltage mode, the program would fail due to not
being able to establish communication with the PIC.
In cases where the target hardware can be damaged by a higher
voltage on MCLR than Vdd, the -PIC command line option must also be
used.
The low voltage mode program entry described here is not the same
as on some older parts that required use of a separate PGM pin. In
all cases discussed here, the programmer is still connected to Vdd,
MCLR, PGC, PGD, and ground, never PGM. Although the PGM method is
also sometimes called "low voltage programming", that is not what
is referred to here.