pkcmd_lx_usage - Anobium/PICKitPlus GitHub Wiki

-2

No parameter

-2    Selects a PICKit 2 programmer only.  

The application can be forced to use a PICKit 2 programmer.   This is useful when you have more than one programmer attached.  

Usage:

-2

Will select a PICKit 2 only for programming operations.

-3

No parameter

-3    Selects a PICKit 3 programmer only.

The application can be forced to use a PICKit 3 programmer and ignore any PICKit 2 devices. This is useful when you have more than one programmer attached.

Usage:

-3

Will select a PICKit 3 only for programming operations.

--devicelist

--devicelist    List all supported devices.

This is an exclusive command. Other command line parameters will be ignored.

Usage:

--devicelist

Will show the revision of the devices database and a complete list of the supported devices in this database.

You may wish to pipe or redirect the output to a file. For example:

--devicelist | more Will show the information in pages using the more command.

--devicelist-csv

--devicelist-csv    List all supported devices in CSV format.

This is an exclusive command. Other command line parameters will be ignored.

Usage:

--devicelist-csv

Will show the revision of the devices database and a complete list of the supported devices using a comma delimited format.

You may wish to pipe or redirect the output to a file.

--family

family number

--family        Use automatic selection for the attached microcontroller within the family of microcontrollers.

This is mutually exclusive to -p

Usage:

-- family 22

The software will search through the family 22 microcontrollers.

--firmware

No parameter

--firmware    Flash firmware for a PICKIT 3 programmer.

This an exclusive command. Other command line parameters will be ignored.

PICKit 3 device programmmer hex files are assumed to be in the same folder as the program.

When using this switch you may get an error on the first attempt. This a know condition. Simply try the switch and/or unplug and retry.

Usage:

For PICKIT3 Programmer --firmware

-a

Requires a parameter

-a    Adjust the standard operating voltage.

Can be used with programmers that support changing the operating voltage, such as official PICKit 2 and 3 tools. Not all clone PICKIT programmers support changing the operating voltages.

Examples: -a5 -a3.3 -a2.8

If instructed to leave power on after programming (-zv), the voltage after programming will reflect this parameter.

The -a parameter requires -w to operate. If -w is not specified then -a will not set the operating voltage.

See also: -k to remove programmer power.

Usage:

Example 1. Set to 3.3v

-w -pPIC12f675 -f12f675.hex -u343c -mpec -a3.3 -zv

Example 2. Set to 5.0v

-w -pPIC12f675 -f12f675.hex -u343c -mpec -a5 -zv

Example 3. Set to the default operating voltage. -a is not explicitly stated as -w will set to the standard operating voltage. This is shown for completeness.

-w -pPIC12f675 -f12f675.hex -u343c -mpec -zv

Fixed Voltage Case

Some clone programmers lack the ability to change the voltage. When using such a tool, -a will have no effect.

-b

Requires a filename as parameter

-b    The filename of the PKPlusDeviceFile.dat file.

This an optional switch. The PKPlusDeviceFile.dat file is assumed to be in the same folder as the AppImage, unless otherwise specified.

If present, --devicefile and --devicefile-csv will take this switch into account.

Usage:

-b ”PKPlusDeviceFile.dat”
If the .dat file in NOT in the same folder the complete path and filename must be specified.

-c

No parameter

-c  Blank Check.

Set the errorlevel to 0 if blank and nonzero (usually 16) otherwise.

Usage:

-c

-d

-d Requires a parameter

-d  Delay on exit of the application.

This switch will delay the exit of the application. This allows you time to review the output from the application (for example if you are running it from a script or IDE which will close the output window immediately afterward).

You can specify a time delay or wait for a key press. For a time delay, use -dN, where N is an integer value. To wait for a keypress, use -dK.

Some IDEs do not play well with -dK, because they don’t allow the user to interact with the spawned process using the keyboard. Using -dK with IDEs that do not support user input during programming may cause the IDE to lock up, waiting for a key press that can never arrive. Your mileage may vary.

Usage:

-d1  Delay 1 second

-dK  Wait until key press

-e

--erase

No parameter required

-e Erase device

All memory regions and eeprom (if present) are reset to their default values as specified in the datasheet for that chip.

This is a positional argument. Positional arguments are processed in the order they are given. If -e is placed AFTER -m, the device will first be programmed and then subsequently erased.

The purpose of positional arguments is to permit multiple operations (erase, read, write) to be performed in a single invocation.

-g

Requires a parameter or parameter(s) string

-g get (read, export) memory contents from device.

Full options are: -gpecs

memory regions are:

p = Program memory

e = EEPROM

c = Configuration memory

s = UserIDs

1) At least one memory region MUST be specified. If no memory region is specified as a parameter then the operation will fail.

2) If memory regions are specified then the specified regions are exported to the file specified with -f. For example, -gc will export the config memory region.

3) The export will be to the terminal (STDOUT) if -f is not specified.

4) -f is positional and must be specified BEFORE the -g or -m operation to which it refers.

Usage:

-f output.hex -gpec     Get program, eeprom and config memory regions.

-gs     Display userIDs on terminal

-gc     Display config on terminal

-h

No parameter

-h Show the basic Help.

This switch shows a basic list of the supported arguments and their purposes.

Usage:

`-h ` Shows the list of the command line arguments.

-i

Requires  -p<partname>  

-i  Display device ID and revision.

Shows the Device ID and Revision in hexadecimal.

Usage:

-i   Show the device ID and revision

-i -p16F1825

-j

No parameter

-j  Detect and summarise the attached PICKit programmers.

Unit IDs of all connected PICKit programmers will be displayed.

Usage:

-j  Show the PICKit programmers.

-k

--killpower

No parameter

-k  Remove power previously left on using -zv.

-k is mutually exclusive to -w See also: -a.

Usage:

-k Instructs the programmer to cease providing power to the target

-m

Requires a parameter or parameter(s) string

-m  Program device.

Full options are:  -mpecs

  memory regions are:

    p  = Program memory

    e = EEPROM

    c = Configuration memory                         

    s = UserIDs

The order in which these flags are specified is not important.

1) Memory regions MUST be specified. If no memory region is specified then the operation will fail.

2) Some chips have constraints on what memory types can be written by themselves. For example, some don’t support writing the config without also writing or erasing the program memory. For such chips, invalid programming attempts will fail with an error message.

3) If a memory region is specified then the memory region IS FIRST ERASED, then programmed.   In other words, -e is implied for the memory region(s) specified.

4) All specified memory regions are automatically verified after programming. There is currently no way to disable this.

To specify an output filename, use -f. This is a positional argument, and must appear BEFORE -m. If omitted, the data will be printed to the terminal instead.

Usage:

Example 1. Program all memory regions:

-p16lf18855 -w -zv -f16lf18855.hex -mpec

Example 2. Write program memory and config, but preserve EEPROM contents:

-p16lf18855 -w -zv -f16lf18855.hex -mcp

-n

Requires a PICKit programmer name string as a parameter

-n  Program the device with the specified name.

Use the PICkit programmer with the given Unit ID string (its so-called "serial").  Useful when multiple PICkit programmers units are connected.

Not particularly useful when multiple programmers have the same ID. (Yes, this is a thing.)

Usage:

Example:

-p16lf18855 -nBUR12345678 -w -zv -f16lf18855.hex -mcep

Use a specific programmer with the name of BUR12345678.

-p

Requires a chip model name

-p  Program the device with the specified name.

This argument is mandatory for all chip-related operations (i.e. read, write, erase).

The switch specifies the target chip ("part") to be programmed. The device string needs to match the device being programmed, or the operation will fail.  The device string is used to extract key information from the device database.  An incorrect device string will not work and an error message will be issued.

Specifying an incorrect part name may cause damage to your part. For example, specifying a PIC18F6520 when you have connected the low-voltage PIC18LF6520 will (unless -a is specified) apply 5 volts to the part, potentially damaging it.

You may optionally omit the "PIC" prefix from your part name. For example, -p12F675 and -pPIC12F675 are both valid arguments.

The part name is not case-sensitive.

Usage:

Example 1. Program a PIC16LF8855 chip.

-p16lf18855 -w -zv -f16lf18855.hex -mcep

Example 2. Program a 12F675.

-pPIC12F675 -w -zv -f12F675 -mcp

-r

Requires a parameter

Implemented as -rnnnn where nnnn is the size of the flash memory block to be protected, and where nnn can be any value within the constaints of NVRAM erase row size. Suggest multiples of 0x20.

Currently the largest block HEF/SAF on any PIC is 0x100 (words) but This could possibly change in the future.

So valid values would be 0x20, 0x60, 0x80 up to 0x100

Usage:

Example 1:

-r128  This will protect/preserve the last 0x60 (128) words of flash memory. In the Example 1 above, if the microcontroller has 2048 words of Program Flash Memory, range of memory to be preserved would be from 0x780 to 0x7FF.

Example 2:

-r0xE0  This will preserve the last 0xE0 (224) words of flash memory on a microcontroller with 256 words of SAF memory.

-q

  Set the output to minimal (quiet)

Usage:

-q  The application will issue minimal messages.

-s

Requires a hexadecimal parameter

-s  sets the UserID value for microcontrollers that support UserID bytes/words.

Supports hexadecimal values only. Supports usage of leading 0x and characters 0xhhhh to the specific length stated in the datasheet.

There are two components to the command. The hexadecimal value and the command switch.

1) Hexadecimal value: -s is a positional value. Therefore, it has no effect until a write operation is performed. You must put -s hexadecimal value prior to the -m switch.

2) You must add the s parameter to the -m command. Example -mpecs

Usage:

Example 1.

Set to the UserId to a hexadecimal value 0x0000000000000001 use the following:

-w -p16f1938 -f16f1938.hex -s0x0000000000000001 -mpecs -a5.0 -zv

-u

Requires a hexadecimal parameter

-u  sets the OSCCAL value on devices with OSCCAL support.

Supports hexadecimal values only. Supports usage of leading 0x and four characters 0xhhhh, or, a four character string hhhh. The hexadecimal value must start with 0x34; the next 6 bits determine the OSCCAL; and the lower two bits must be zero. Essentially, the 6 bits adjust the frequency up or down to achieve 4 MHz.

-u is a positional command. Therefore, it has no effect until a write operation is performed. It must be specified before -m.

Changing the OSCCAL value impacts the operating frequency of the device. YOU MUST ENSURE THE VALUE COMPLIES WITH THE SPECIFICATION AS STATED IN THE DATASHEET. Typical values are similar to 0x343C.

NOTE: The PICKit+2 GUI can regenerate the OSCCAL value for you automatically.

Usage:

Example 1. Set to hexadecimal value 343C

-w -pPIC12f675 -f12f675.hex -u343c -mpec -a3.3 -zv

Example 2. Set to hexadecimal value 0x3438

-w -pPIC12f675 -f12f675.hex -u3438 -mpec -a5.0 -zv

-w

--applypower

No parameter

-w Power device from programmer, if safe to do so.

Power will be applied during programming operations. If a specific voltage has not been specified with -a, the default voltage for the selected part will be used.

Before applying power, the software will check if power is already present. If power is found to be present, the software will not attempt to supply more power.

See also: -a, -k

NOTE: These command line switches operate differently from the original Microchip command line utility.

Usage:

-w  Power the device for programming.
Example 1. Enable power to support programming using the default operating voltage.

-w -pPIC12f675 -f12f675.hex -u343c -mpec

Example 2. Enable power to support programming using the default operating voltage and continue to apply power after exiting the application.

-w -pPIC12f675 -f12f675.hex -u343c -mpec -zv

-z

--on-exit

Requires one or more flags

-z  Keep power and/or MCLR asserted upon exit.

-z Must be used with at least one of the flags V or M. The order of these flags is not important, and they are not case-sensitive.

Specifies state on exit where v=power and m=mclr.

See also: -a

Usage:

-zv      Keep power applied after exit
-zm     Keep MCLR asserted after exit
-zvm     Keep both power and MCLR after exit

--nolog

No flag required

Prevent log file creation/updating.

Usage:

--nolog      To prevent logging events being written by application.