Program PIC Microcontrollers with PICkit 2 in Linux
$DOCS/*nix

%!encoding: utf-8
%!target: html
%!style: ../docs.css
%!options: --css-sugar
% %!options: --toc


We all know PICkit is a good thing. But the officially supported software of PICkit 2 which you use to burn the instructions
to PIC microcontrollers is only for MS Windows. It is quite itchy for some Linux users.  Fortunately Microchip
community also provides an unsupported Linux counterpart called "pk2cmd". It does the same job except you have to use it in
command line. Here I document how I install and use it. 


=Installation=

First download the source of pk2cmd at Microchip's PICKit 2 homepage, or download from my [local archive ./img/pk2cmdv1.20linuxmacsource.tar.gz] (at this time the
newest version is 1.20). Unpack it and you will see some C source files and readme docs. You can just go ahead and read the
docs and figure
out everything, but here I just show what I do.


There is no "configure" file but it is not a big problem since the most important dependency is something called **libusb**.
What
libusb does is that it recognizes your USB device and runs from user mode instead of kernel mode once you plug in some USB
drive to the computer. Luckily, for modern
mainstream system like Fedora and Debian, it uses udev by default so you don't have to change anything. If your distribution
does not come with libusb, check "usbhotplug.txt" for details.

In Fedora, first make sure you have "g++" (GNU C++ compiler), "libusb" and its development files "libusb-devel", by 

```
sudo yum install gcc libusb libusb-devel
```

In Debian (I use Debian 5 (Lenny)), the name is different. You should first activate Debian backports (go to backports.org for
instructions) and install libusb++ package: 

```
sudo apt-get install libusb++-dev
```

Then cd into the unpacked directory, and compile the source: 

```
make linux
```

If there are errors (most likely some dependencies problems), fix it by installing the the dependencies. In Fedora it should
just shut up and be fine. Then install the compiled binary by 

```
sudo make install
```

This step does the following: 

```
mkdir -p /usr/share/pk2
cp pk2cmd /usr/local/bin
chmod u+s /usr/local/bin/pk2cmd
cp PK2DeviceFile.dat /usr/share/pk2/PK2DeviceFile.dat
```

Basically it puts the executable pk2cmd and its dependency PK2DeviceFile.dat into the right place.

The last thing is to add the dependency PK2DeviceFile.dat into your searching path. If you use BASH, edit ~/.bashrc or
~/.bash_profile (or some login initialization files like that) and add this line: 

```
export PATH=$PATH:/usr/share/pk2
```

source the file ~/.bash_profile and see if it works by 

```
pk2cmd ?
```

If it gives you some help information, it means pk2cmd works in your computer. 


=Use pk2cmd=

After correctly compiling and installing, using pk2cmd is not that hard. Connect PICkit 2 with the computer and circuit board,
type this after the computer recognizes the USB device: 

```
pk2cmd -PPIC16F690 -Fexample.hex -M
```

Here -P means the processor type (here is PIC16F690), -F means the path of hex file(here is example.hex), -M means the entire
device to be programmed. Also check out the readme files (e.g. ReadmeForPK2CMDLinux2-6.txt) to see if your device is
supported. 


=Appendices=

- PICKit 2 pinout (from PICkit 2 documentation) 

[./img/pickit2_pinout.png]

- [PICKit 2 documentation ./img/pickit2.pdf]

-------------------------------------------------------
[../img/t2tpowered-old-2.png] ([%%infile %%infile])