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.