Pk2cmd

pk2cmd is a command-line tool by Microchip to control a PICkit 2 programmer, which serves as an interface between software and PIC microcontrollers.

Here's what we know.

Before we begin

PK2DeviceFile.dat

Due to its Windows progeny, for the time being this program prefers to run in its own directory. However, it seems to run okay as long as the included "PK2DeviceFile.dat" is symlinked into cwd.

USB permissions

The program apparently uses libusb or some other user-space USB access method. Hence, for most of these commands to work you may have to run them as root, or sudo them.

Firmware

pk2cmd requires version 2 firmware. Unfortunately, no other Linux-based programmer so far seems to support anything but version 1. If you plan to alternate between programs, you'll also need to alternate between firmwares. Keep a copy of version 1 handy. It's hard to track down.

Installing into a $PREFIX

There is no ./configure script to run to change the installation prefix (as of 1.21RC1). This functionality is needed to use any other prefix than /usr or /usr/local, such as under a user's home dir or the system stow dir.

However, enabling an alternative prefix just involves a couple of adjustments to the Makefile.

First, add a PREFIX variable near the top of the Makefile that contains the desired value:

PREFIX=/your/prefix/of/choice

For example, we might install to the prefix /usr/local/stow/pk2cmd-VERSION to install systemwide via stow.

Then, later in the file, the install target contains the hardcoded prefixes:

install: 
	mkdir -p /usr/share/pk2
	cp $(APP) /usr/local/bin
	chmod u+s /usr/local/bin/$(APP)
	cp PK2DeviceFile.dat /usr/share/pk2/PK2DeviceFile.dat

Change this to the following:

install: 
	mkdir -p "$(PREFIX)/share/pk2"
	mkdir -p "$(PREFIX)/bin"
	cp $(APP) "$(PREFIX)/bin"
	chmod u+s "$(PREFIX)/bin/$(APP)"
	cp PK2DeviceFile.dat "$(PREFIX)/share/pk2/PK2DeviceFile.dat"

Script to run

pk2cmd needs to run with Pk2DeviceFile.dat somewhere in $PATH, and on my system it must be run sudo (though that may be because I don't know how to configure libusb).

The following does this. It is installed in a directory that appears earlier in my $PATH than the actual pk2cmd, and so overrides it.

#!/bin/sh
PK2CMD_PREFIX="/home/psmay/opt/pk2cmd-master"

# The actual executable
PK2CMD_COMMAND="$PK2CMD_PREFIX/bin/pk2cmd"
# The directory containing the device file
PK2CMD_SHARE_PK2="$PK2CMD_PREFIX/share/pk2"

# The device file dir is prepended so the device file is automatically found
sudo PATH="$PK2CMD_SHARE_PK2:$PATH" "$PK2CMD_COMMAND" "$@"

If you installed using the original Makefile instead of the modified version, delete the PK2CMD_PREFIX line and replace it in the next two variables with /usr/local and /usr, respectively.

Preemptive troubleshooting

Vpp before Vdd

There are certain configurations upon the chip itself (for example, if MCLR is in I/O mode) wherein the chip will behave erratically without Vpp rising before Vdd. This applies to any action involving the programming mode.

If your stuff is behaving erratically, use -X on the command line to enable Vpp first:

sudo ./pk2cmd -PPIC16F88 -X ...

Incidentally, I've been told that MCLR set to I/O is a bad idea unless absolutely necessary. You'll probably need Vpp-first to unset it.

Operations

-I: Identify connected chip

pk2cmd apparently won't tell you which model of device you've connected; hopefully you already know. It will give you a device ID if you suggest what chip it might be and your guess is somewhat close:

sudo ./pk2cmd -PPIC16F628 -I

However, the above worked for a 16F88, so the fact that it returns doesn't make it right. Here's a hint, though: It returned

Device ID = 0765

with a chip that's been identified by other programs as 16F88 rev. 5. According to the file pk2.cfg in the source for Jeff Post's other programmer software, the aptly named pk2, says that the device ID for 16F88 is 0x0760. I'm going to assume that this means the first 12 bits represent the device and the last 4 represent the revision. Your mileage may vary. Just know what you have attached...

-C: Blank check

sudo ./pk2cmd -PPIC16F88 -C

returns messages including, but possibly not limited to:

• Program memory is NOT blank.
• Device is blank

-E: Erase

sudo ./pk2cmd -PPIC16F88 -E

'nuff said.

Programming the device

It's more than just one option. I'm led to believe the typical case is:

sudo ./pk2cmd -PPIC16F88 -Ffile.hex -M

This erases the device and then overwrites with file.hex. -M can be followed by P (program memory), E (EEPROM), I (ID memory), C (configuration memory) to only overwrite the specified area, in which case the erase is not performed.

Verifying the device contents

Same as programming, but replace -M with -Y:

sudo ./pk2cmd -PPIC16F88 -Ffile.hex -Y

Verify can be specific to P, E, I, C as with -M.

Reading the device contents

If you're not checking against an existing file but just need a .hex dump to program something else (for example), you'd do

sudo ./pk2cmd -PPIC16F88 -GFfile.hex

Note the suddenly inconsistent syntax.

F can be replaced with P, E, I, C, but instead of specifying a file you specify an address range and the result is printed to the screen. Run pk2cmd with no args for details.

Turning the device on or off

If the circuit properly runs from 5V and won't overload the Pk2, this will turn it on:

sudo ./pk2cmd -PPIC16F88 -R -T

-R raises /MCLR while -T turns on Vdd. Since neither is default, the following will turn the device back off:

sudo ./pk2cmd -PPIC16F88

Example: Compiling and loading to 16F527

Use with 16F527 requires an updated non-stock PK2DeviceFile.dat such as the one found in this forum post. That file doesn't work with pk2cmd 1.20, but will work with the 1.21RC1 modifications as incorporated in my github branch.

Compiling to 16F527 also requires a newer version of gputils than the one which came with my distro; this was tested with version gputils 1.20.

   WORKDIR=~/exp
   CMDDIR=~/src/pk2cmd-1.21RC1
   PROCESSOR=16F527
   PROGRAM_BASENAME="blink-527"
   
   cd "$WORKDIR"
   # Compile asm to hex
   gpasm "$PROGRAM_BASENAME.asm"
   
   # You might not have to cd to the pk2cmd dir to run pk2cmd, but I didn't 
   # install mine system-wide and PK2DeviceFile.dat has to be sitting in cwd
   # for it to work. Fixing that is a TODO.
   cd "$CMDDIR"
   # Write via PK2
   sudo ./pk2cmd -PPIC"$PROCESSOR" -F"$WORKDIR/$PROGRAM_BASENAME.hex" -M
   # Verify write
   sudo ./pk2cmd -PPIC"$PROCESSOR" -F"$WORKDIR/$PROGRAM_BASENAME.hex" -Y
   # Turn on PK2 to test target circuit (optional)
   sudo ./pk2cmd -PPIC"$PROCESSOR" -R -T