February 19, 2009 — Phillip Burgess — http://www.PaintYourDragon.com/uc/
Update 3/16/09: Added Linux support.
If you’ve read my prior article on PIC32 development on Mac and Linux hosts, you know what a complex and costly endeavour it can be tooling up to work with this chip on “alternative” operating systems. But as the mighty 800 pound gorilla of the microcontroller world, it’s well worth going to extreme lengths to have access to this device.
Some of the complexity stems from design decisions in Microchip’s own seemingly affordable PIC32 Starter Kit. A mere $50 nets you everything needed to get started with this MCU: evaluation board, C compiler, sample code, even the USB cable. The board has a few buttons and LEDs with which a “Simon” type game can be written. For anything more complex, the board is “conveniently” equipped with a 120 pin Hirose connector that breaks out all of the MCU’s signal lines. This is where the honeymoon ends. Trying to build something using the corresponding mating connector can be a nightmare. It’s a fine-pitch surface-mount part of the sort that typically must be acquired from distant mail order sources, and will need to be fitted to a custom-etched board even for basic breakout functionality. Furthermore, if you’re not a Windows user…well, I already wrote a whole painful article about that.
The solution to these problems has traditionally involved a somewhat pricey expansion board from Microchip and, if you’re using Linux or Mac OS X, a separate PICkit 2 programmer. If you wanted to use Microchip’s existing demo boards for things like audio and color LCD graphics, well that’s great, you’d probably have ended up with the expansion board anyway. But for the simple hobbyist tinkerer, the cost of all these parts may be more than they can stomach, and most will just stick with the Arduino.
The path out of this mess has involved the fortunate alignment of a few planets:
Firstly, the availability of a new generation of PIC microcontrollers with USB support built in. Earlier PICs, or other microcontroller kits like the Arduino or even the PIC32 Starter Kit, have traditionally relied on external parts to interface with USB, increasing cost.
Secondly, the provision of USB bootloader code from Microchip. A bootloader is a small piece of code on a microcontroller that can load new programs into the remaining program space on the chip (over USB in this case). Traditionally this has required a separate programmer device (such as the PICkit 2) to transfer code to the chip. The bootloader — which makes this whole process simple and self-contained — is one of the things that’s helped make the Arduino such a success. Microchip also provides a Windows program for communicating with the bootloader and transferring compiled programs to the chip.
Thirdly, the availability of Brian Schmalz’s UBW32, a PIC32-based development board that not only addresses my biggest gripe with Microchip’s PIC32 Starter Kit (instead of the zany 120-pin surface-mount connector, the UBW32 uses standard 0.1" pin spacing and, with the addition of inexpensive and easily-soldered headers, fits right into a standard breadboard), but also makes use of the aforementioned bootloader (as opposed to the closed and proprietary software interface of the PIC32 Starter Kit). And it’s $10 cheaper. Win, win, win across the board. You can order the UBW32 from SparkFun Electronics.
Bootloader aside, the UBW32 is just plain neat, even if you’re not planning on coding for the PIC32 directly. The board comes preprogrammed with software for interfacing devices with your PC (or Mac or Linux system). Plug in the UBW32 and it shows up as a virtual serial port. You can then use any serial communication program (such as PuTTY or CKermit) to type commands and control various I/O lines. Most programming languages — even the most simple BASIC interpreters — usually have native serial capabilities, so this becomes a simple way for beginners to create “smart” real-world devices using their PC. Most people will probably use the UBW32 this way, and that’s great. But if you need something more intense, or something that operates stand-alone without a PC, you can replace this functionality with your own code. Thankfully they didn’t skimp here: the UBW32 uses the current top-of-the-line PIC32 MCU with 512K program space, 32K RAM and support for both USB “client” and “host” modes.
Finally, if you are interested in the PIC32 programming aspect, and if you’re a Mac or Linux user, the fourth aligned planet is a small utility I wrote that works with the UBW32’s bootloader. Between all of these, and if you’re not after the special PIC32 expansion boards mentioned earlier, the cost of development on the Mac and Linux has suddenly dropped from over $200 to just $40. Dude!
This route is not without its drawbacks; there’s no debugger support, for instance. If you need to do Serious Development, there’s no getting around using the Windows tools with a programmer/debugger such as Microchip’s ICD3. But again, as I’m writing this with hobbyists and beginners in mind, most will be perfectly happy with the UBW32 and this bootloader approach. There’s still a ton of great things that can be done.
Before you get too excited, I should explain that this is all based on command-line tools at present. I’ve never much cared for IDEs, which probably qualifies me as a crotchety old man, but in my little fantasy world want to believe this is “hardcore.” Dang kids, get off my lawn! If this hasn’t scared you away, read on:
First, Mac Users will need Xcode (Apple’s developer tools) installed. This should be on your original Mac OS X install DVD, or can be downloaded at no cost from developer.apple.com (free registration required). Xcode supplies a whole fancy IDE, but we’ll be using just the command-line portions here, in a Terminal window.
Linux users will need the libhid development library (and possibly other dependent libraries) installed. This can be accomplished with most package managers, or installed from the command line by typing:
sudo apt-get install libhid-dev
For either platform, you’ll then need a C compiler for the PIC32. With a little effort (and using the aforementioned tools or libraries), this can be brought together at no expense. Read this prior article on the PIC32 for directions on acquiring and building the compiler; you can ignore everything after the “Hardware” heading and resume here.
Next is the Mac- or Linux-side bootloader utility for talking to the UBW32. You can download the source code package here…I’ll explain in a moment how to compile and make this work.
Finally, once all the software components are acquired and working (I do recommend confirming that you can get all the software operating before spending money on the hardware), order the UBW32 from the SparkFun Electronics web site. You’ll also need a USB A to Mini B cable (if you don’t already have 50,000 around from other devices), and — if you want to use the UBW32 in a breadboard — some basic soldering aptitude and two 40-pin row headers (such as PRT-00116 from SparkFun) — possibly a third if you want to add a PICkit 2 programming header, though you’ll snap off and use only five pins for that.
Extract the previously-downloaded ubw32.tar.bz2 by double-clicking the file in the Finder. This results in a folder called “ubw32”. To make the directions consistent, move that folder to the Desktop if it’s not already there. Then, open a Terminal window and type these two commands:
This should process for just a moment and create the executable, called ubw32 (inside the folder of the same name). If all goes well, then type:
sudo make install
This asks for your administrator password in order to copy the file to /usr/local/bin, so you don't need to specify a complete path to the program each time.
Note to Linux users: on Linux systems, the ubw32 program must be run as root. One option is to use the sudo command each time ubw32 is invoked (i.e. sudo ubw32). Alternately, the setuid bit can be configured to always run the installed program as root:
sudo chmod +s /usr/local/bin/ubw32
A simple demo program confirms that everything is working. To build the demo UBW32 program, type:
Then, to transfer the demo program to the UBW32, connect the device via USB while holding the PRG button (or, if already connected, press the PRG and RESET buttons simultaneously). Make sure the PWR SEL switch is set to USB when connecting. The green and white status LEDs should be alternately flashing, indicating the unit is in Bootloader mode and ready to accept code. Then type:
This will overwrite the firmware currently on the UBW32, so make sure you have a copy of the original firmware HEX file if you want to restore the original Bit Whacker functionality! (D32.hex, available from the project home page.)
If all goes as intended, the program space on the UBW32 will first be erased and the test program downloaded and verified. When finished, the demo program should run, smoothly fading four of the LEDs on the UBW32 board.
The code and makefile in the example directory show the basics of setting up your own UBW32 firmware programs using the C32 compiler.
When creating your own UBW32 programs, it is ABSOLUTELY IMPERATIVE that you place the file procdefs.ld alongside your source (copy this from the example directory). Failure to do so will almost certainly result in your UBW32 getting “bricked” and requiring re-flashing the bootloader (which, if you don’t have a PICkit 2 or similar PIC programmer, you’re screwed and will have to track one down to borrow, or buy one from Microchip for $35).
The ubw32 program is then used to transfer the compiled code to the UBW32 device. It’s a fairly straightforward program with just a few options, each preceded by a hyphen. For instance, to display program help, type:
Most important is the -write command (this can also be abbreviated -w), which specifies the name of a HEX file to download to the device, e.g.:
ubw32 -write test.hex
If you try the above command again while in the example directory, you might receive an error message to the effect that the UBW32 cannot be found, even though it is plugged in and the power LED is on. This is because the UBW32 needs to be placed in Bootloader mode before transferring new code. Press the PRG and RESET buttons simultaneously, then try again:
ubw32 -write test.hex
This will erase and then download the test program as was done before. But once done, you won’t see anything else happen; the green and white LEDs are still alternately flashing as before. The UBW32 is still in Bootloader mode. To run the new code, press the RESET button (you should then see four LEDs fading in sequence). Alternately, you can issue a reset from the command line:
Or perform the write-followed-by-reset in one step like this:
ubw32 -write test.hex -reset
A few other commands are available. If you’re impatient and want to skip the write verification step, add -noverify (or just -n). To erase the UBW32 program space without writing any new code to it, use -erase (-e) (you can erase without writing a HEX file, but there is no option to write a HEX file without erasing; it is an required step). Finally, if for some reason your UBW32 (or other Microchip HID Bootloader device) is using a USB vendor and product ID different from the defaults (04d8 and 003c, respectively — you can find these in System Profiler on the Mac), the -vendor (-v) and -product (-p) commands allow alternate values to be used (each expects a hexidecimal value). A full command line might be:
ubw32 -vendor 04d8 -product 003c -write test.hex -noverify -reset
Commands are not necessarily issued in the order received; there is an implicit sensible order for each step which the program will follow. For instance, putting the -reset command first will not actually reset the device before attempting other steps; this wouldn’t work, as the UBW32 will no longer be in Bootloader mode.
If multiple commands are received, only the last value will be used, e.g.:
ubw32 -write foo.hex -write bar.hex -write baz.hex
will NOT write three HEX files to the device; only the last in line (baz.hex in this case) will be used.
For Mac users: only OS X 10.5 (and later) is supported; this will not work in 10.4 or earlier OS X releases.
For Linux Users: as previously stated, you’ll need to run the ubw32 program as root (either via sudo or by changing the program’s setuid bit after installing), or it might be possible to avoid this if you can decipher the mojo of “HID blacklisting.” Also note that multiple sequential invocations of the program may hang (for example, calling once with a -write command, then a separate invocation for -reset). I’ve not figured out the cause of this; an interim solution is to simply manually reset the UBW32 into bootloader mode prior to each program invocation.
For Windows users: there’s no Windows port of this program, as Microchip’s own PDFUSB.exe program already handles this task.
Much thanks to Benny Hsieh for donating development hardware which made the Linux port possible.