Tiny command-line program to control the USB Microchip PICkit 1 FLASH Starter Kit from Linux. Orion Sky Lawlor, olawlor@acm.org ------------------ Introduction ---------------- This is a little text-based utility to control the excellent and very cheap Microchip(tm) PICkit(tm) 1 FLASH Starter Kit device programmer from Linux. The PICkit is a little board that plugs into your USB port, and lets you upload programs into the flash memory of the 8-pin and 14-pin Microchip Programmable Interrupt Controllers (PICs), which are some of the best computers you can buy new for $2 apiece. The programmer is only $35 direct from Microchip, and comes with a pile of useful (but Windows) software. Buy one-- you can't beat the price. This program can upload and download .hex files to/from the PIC chip plugged into the PICkit's socket, as shown in the usage: usb_pickit (Writes .hex file to chip) usb_pickit --program (Verbose version of above) usb_pickit --extract (Read from chip into .hex file) usb_pickit --config (Show configuration data) usb_pickit --reset (Power cycle the chip) usb_pickit --programall (Overwrite osccal and bg (!)) usb_pickit --help (This message) is an Intel MDS .hex file; the standard format used by almost all compilers, assemblers, and disassemblers. ------------------ Installation ------------------ 1.) Compile the program. I've included a prebuilt binary, statically linked to a working libusb if you don't want to deal with this, and you happen to be on a MacOS X or an x86 Linux box with a compatible glibc. To compile, you'll need the absolute latest and greatest libusb (or a version greater than 0.1.7) installed for your executable to work on all kernels. I use: cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/libusb login (press enter when it stupidly asks for a password) cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/libusb co libusb cd libusb ./autogen.sh ./configure --disable-shared make sudo make install Now cd back to usb_pickit and build it with make To build using the older "bulk writes" with an older libusb on an older (pre 2.6) kernel, you could also say: make OPTS=-DHAVE_LIBUSB_INTERRUPT_MODE=0 2.) Install the new program "usb_pickit" anywhere you like. You can use the handy > make install to copy it to /usr/local/bin. 2b.) usb_pickit accesses the USB hardware directly, so you have to run it as root. If you're willing to accept the (small) security risk, run > sudo make suid-install to make usb_pickit setuid root and copy it to /usr/local/bin. You'll then be able to run it as a non-root user. I've reviewed the code for security holes, but let me know if I missed any. 3.) Finally, the moment of truth: plug in the PICkit and run > usb_pickit examples/flash_4.hex This should install a little "flash 4 LED's in sequence" program on your PICkit. The red PICkit LEDs should now be flashing in triumph! -------------------- Runtime Troubleshooting ----------------- ./usb_pickit.linux: /lib/libc.so.6: version `GLIBC_2.3' not found -> The binary is linked to the RedHat 9 glibc. You'll have to recompile for your system, as described in step (1) above. ./usb_pickit: error while loading shared libraries: libusb-0.1.so.4: cannot open shared object file: No such file or directory -> You're linked to a shared libary version of libusb, but your shared libraries aren't installed right. You may be able to make this work temporarily by doing a > export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH" The better way is to use ./configure --disable-shared when you build libusb, so shared libraries aren't involved. Fatal error> This program must be run as root, or made setuid root -> It's gotta run as root. See 2b in the installation instructions above. Fatal error> Could not find USB PICkit device-- you might try lsusb to see if it's actually there. -> Make sure you've got everything plugged in, and your USB stack is working properly (try some other USB peripheral, like a USB mouse or keyboard). If it looks like it should work, I'd be interested in seeing the lsusb output! Fatal error> Claim failed-- the USB PICkit is in use by another driver. Do a `dmesg` to see which kernel driver has claimed it-- You may need to `rmmod hid` or patch your kernel's hid driver. -> Is anything else running? You might check the "Older Troubleshooting" section below. usb PICkit write: Invalid argument Fatal error> USB write failed -> You may be encountering a problem with bulk USB writes. See the changelog entry for version 1.2 below, and recompile using the latest libusb. ----------------- Compilation Troubleshooting ------------- usb_pickit.c:7:37: usb.h: No such file or directory -> You're missing libusb. See 1 in the installation instructions above. usb_pickit.o(.text+0x3b): In function `send_usb': : undefined reference to `usb_interrupt_write' usb_pickit.o(.text+0x108): In function `recv_usb': : undefined reference to `usb_interrupt_read' -> You need the latest, CVS version of libusb, not the version installed with most current Linux distributions. See 1 in the installation instructions above. ------------ Older Troubleshooting ----------- For version 1.0, you'll need to disable the USB hid driver somehow, because the hid driver claims the pickit, because the pickit (for Windows compatability) claims it's a Human Input Device in its default configuration. (Configuration 2 doesn't have this problem.) The easy way to detach the hid driver in Linux is just > rmmod hid which blows away the USB hid driver completely (assuming it's built as a module, which it should be). Sadly, the easy fix will kill off your USB keyboard and mouse, so a cleaner fix is to add the lines #define USB_VENDOR_ID_MICROCHIP 0x04d8 #define USB_DEVICE_ID_PICKIT1 0x0032 to linux/drivers/usb/hid-core.c, and add this line to that file's big "hid_blacklist": { USB_VENDOR_ID_MICROCHIP, USB_DEVICE_ID_PICKIT1, HID_QUIRK_IGNORE }, and finally rebuild and reinstall your kernel modules. (This fix might never go into the mainstream kernel) On anything else, like BSD or MacOS X (which both should work otherwise), just use Version 1.1 or later, which should work fine. ------------------ Versions ----------------- I've run this program with no problems on a RedHat 9 box (running Linux 2.4.22/glibc 2.3.2) and a Mandrake 8 box (running Linux 2.4.18-6mdk/glibc 2.2.4). You may have to recompile the program to use an older glibc-- see steps 1 and 2 above. ------------------ Links ------------------ Scott Dattalo maintains an excellent page of PIC-related free software at http://www.gnupic.org/ HI-TECH gives away a full-featured "lite" version of their excellent PIC C compiler PICC, including a Linux version http://www.htsoft.com/products/piclite/piclite.html ------------------ Version History ------------- 2004/11/12: Version 1.21 Added *beta* support for version 2.0 of the PICkit onboard firmware. Dunno if it'll work with new 10F devices. WARNING: *programming* 12F and 16F devices seems to work; but --extract hangs a new board hard: you've got to unplug and replug the USB connector to make it work again. Everything else seems to work fine, though -- thanks to Mattew Wilson for sending me a v2.0 16C745! Added small startup bugfix pointed out by Curtis Sell. Previously, if the chip power was not off, programming or even configuration read could fail intermittently. usb_pickit now turns power off before doing anything. Added --on and --off commands, as suggested by Rogier Wolff to turn off the annoying blinking lights. Fixed command-line handling so USB isn't touched unless you've specifically asked usb_pickit to do something. MacOS X version is unchanged, since my OS X machine has moved to Alaska, but I haven't (yet!). 2004/2/6: Version 1.2 Updated to latest libusb to use USB interrupt mode. This should fix an "invalid argument" error using the latest Linux kernels. Thanks to Steven Michalske for diagnosing the cause of this problem. RANT: In an excellent example of sacrificing backward compatability for conformance to some proported "standard", the latest Linux kernel USB drivers (uhci-alternate in 2.4.24+, and uhci in 2.6.x) no longer support low speed bulk mode transfers-- they give "invalid argument", errno=-22, on any attempt to do a low speed bulk write. 2004/2/3: Version 1.11 Source code is identical; the README file is updated and the Linux executable now linked against glibc 2.2.4. 2004/1/19: Version 1.1 Now this program works on OS X, and out-of-the box on Linux--no bizarre HID troubles. Thanks to Joseph Julicher, a friendly Microchip engineer that (out of the blue!) recommended the usb_set_configuration technique that fixes this. 2003/8/3: Version 1.0 Initial version. -------------------- Support ----------------- I'd love to hear what you're doing with this program, and I'd be glad to include any improvements you make. I am in no way affiliated with the company Microchip, so don't bug them about problems with this program. If you have problems, please read this file completely, and check google, *before* sending me e-mail. I probably couldn't debug your Linux installation, even if I wanted to. No, I can't help you with your EE homework/project/thesis. No, not even (and especially) if you really, really need help.