View source for Pk2cmd

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



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:

<syntaxhighlight lang=make>
PREFIX=/your/prefix/of/choice
</syntaxhighlight>

For example, we might install to the prefix <code>/usr/local/stow/pk2cmd-VERSION</code> to install systemwide via [[stow]].

Then, later in the file, the <code>install</code> target contains the hardcoded prefixes:

<syntaxhighlight lang=make>
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
</syntaxhighlight>

Change this to the following:

<syntaxhighlight lang=make>
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"
</syntaxhighlight>

==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.

<syntaxhighlight lang=bash>
#!/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" "$@"
</syntaxhighlight>

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 [http://www.microchip.com/forums/FindPost/686135 this forum post]. That file doesn't work with pk2cmd 1.20, but will work with the 1.21RC1 modifications as incorporated in [https://github.com/psmay/pk2cmd 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