The STM32 Primer is a nifty microcontroller evaluation/development unit that can serve as the basis of all manner of clever DIY electronics projects. The device is quite affordable (under $40), similar in cost to an Arduino…but it’s a very different animal, packed with bonus doohickeys that geeks will really enjoy playing with:

A substantial processor core: 72 MHz 32-bit ARM CPU with 128K flash program space and 20K RAM
Color graphics: 1" backlit 128x128 pixel 16-bit LCD
Interfaces: 3-axis accelerometer, button, LEDs, buzzer
Portability: NiMH batteries, charged through USB port
An embarrassment of I/O riches: ADC, DAC, USB client, CAN, SPI, I2C, USART

With its 3-inch round transparent case and single button, the STM32 Primer bears a passing resemblance to the old iMac “hockey puck” mouse. The case is designed to pop open easily to access and modify the internal hardware (there are a number of accessible solder pads on the back of the board).

As is to be expected, the included development tools are Windows based. While the IDE and compiler can work under virtualization environments such as Parallels Desktop or VMware, the USB programming functionality unfortunately does not — it demands Boot Camp or an actual PC.

The good news is that there’s a way to get a cross-compiler toolchain working natively on the Macintosh, and a utility available on the STM32 Primer side that allows us to download compiled programs. A similar sequence will likely work for Linux, though I have not tested this combination yet.

With a broadband net connection and a middle-of-the-road Mac (basic DSL and a MacBook here), it should be possible to complete this process in a couple of hours. You’ll need to have the Apple developer tools (Xcode) installed, several hundred megabytes of disk space (there’s about 25 megabytes to download — 85 megs if retrieving the all the source code — but additional space is needed to extract and build the software — a full gigabyte if installing Xcode), and one stage of the process absolutely requires access to either a real PC or a Mac running Boot Camp (virtualization software will not cut it). The latter is only an interim step — once complete, all work can then be done entirely on the Mac.

Also, before proceeding, let me mention some caveats: these are strictly command-line tools; there is no graphical IDE (integrated development environment) unless you run the Windows tools. And there is no debug support, programming only.

Acquiring the Hardware

Due to the uncertain complexity of acquiring and installing the software components, you might want to verify first that you can complete the subsequent steps before buying one of these units, lest you end up with a costly paperweight (albeit one that can play Pac Man). Once you’re ready, Primer units can usually be found at Mouser Electronics, Digi-Key, and a few other sources listed on the STMicroelectronics web site. One source missing there is Rapid Electronics in the UK. Prices range from about $34 to $49 (plus tax and shipping) depending on the source.

The kit includes the Primer unit with neck lanyard (such a medallion serving as an irresistable chick magnet, no doubt), a USB A to Mini B cable, and a 3-inch CD-ROM that will likely send your slot-loading Mac on a trip to the Genius Bar, so don’t use it — all the software and documentation you need can be downloaded online.

Acquiring the Software

The STM32 toolchain — the combination of compiler, assember, linker, etc. that work together to convert C code into executable programs — is legitimately derived from a commercial open-source product, Sourcery G++ Lite, in accordance with the license terms for that software. Please note however that this build does not constitute a CodeSourcery™ product, and they must not be burdened with any support issues that result. Bring any problems to my attention first. The source code contains specific license information regarding distribution requirements, restrictions and legal disclaimers.

The toolchain is available here in several formats depending on your needs:

The simplest method uses these pre-built binaries (.tar.gz, 20 MB) that run on Mac OS X 10.5 (Intel). Extracting this archive results in a folder (stm32-bin) containing a second archive and a README file with directions to complete the installation in a Terminal window. You'll still need to acquire and compile some additional software as explained later.
The source code for the same (.tar.bz2.gz, 73 MB) is available for building the tools on different hardware or OS releases (you do not need both). As with the binary version, extracting the archive in the Finder will produce a folder (stm32-src in this case) with a README file explaining how to complete the build process in the Terminal.
If you’re wary of running some random stranger’s software on your system, you can instead download just my patch file and build script (.tar.gz, 5KB) to examine the scripts and code changes prior to compiling and installing the software. Should you choose this route, you will also need to download the original CodeSourcery G++ Lite product source code (.tar.bz2, 101 MB) and two open source libraries: GMP and MPFR. You’ll also need libusb as described below.
Linux users: a prepackaged Linux toolchain installer is available from CodeSourcery; you do not need to build from the source code and should avoid using my Mac-specific scripts for that anyway.

Regardless whether you’re using the source or the pre-built binaries, you’ll still need to compile some other prerequisite code, and for that you’ll need:

Xcode — Apple’s developer tools — if you don’t already have this installed. This can be found as an optional installer on your original Mac OS X disc, or downloaded from Apple’s developer site after free online registration. About 1GB.
libusb is required by code that accesses the STM32 Primer. If you chose the source code download option above, this library is already included as part of that. Otherwise, if you opted for either the binary installer or the patch-and-build methods, you’ll need to download the source code for this library (version 0.1.12, not the 1.0 beta).

Because the remaining pieces are ambiguous about licensing issues, no pre-built version is available at this time. It’s necessary to download each piece from its respective source, then build the tools with the instructions that follow.

STM32 Firmware Library — provides functions for accessing STM32 peripherals. Presently at version 2.0.3 as I write this, downloaded here. About 1.3 MB.
CircleOS — this is the small operating system that runs on the STM3 Primer itself. It’s a requirement for building part of the toolchain, but you’ll also want to update the OS on the device with the same version, as it likely shipped with an earlier release. I’ve used both version 2.0 (327K download) and 1.7 (185K) successfully, or newer versions might be available on the site’s Projects page. IMPORTANT NOTE: You will need to register for an account before downloading either of these files. There is no cost involved, but you’ll likely end up on a marketing list somewhere.
FatFryer is the critical bit that allows the STM32 Primer to communicate with a Mac (or Linux) system. The full project archive contains files both for the host development system and the STM32 target. NOTE: as with the prior item, you’ll need to have registered with an account to access this file.

Building the Toolchain

If you do not have Xcode installed, take care of that first. Note that the Xcode IDE is not actually used during this build process, just the command-line tools (via Terminal.app). Some editing of text files will be necessary, so I hope you’re reasonably comfortable with a terminal-based editor like pico, vi or emacs. Unpacking the downloaded archives, or deleting the interim results once installed, can be done using the Finder. I created a folder on my desktop called “stm32” and placed all of the previously-downloaded items into that common location.

Install or Build GCC (the ARM cross-compiler)

If you downloaded the pre-built toolchain, use these steps:

Double-click the file stm32-bin.tar.gz. Two progress bars will appear as the archive is extracted. You should be left with a folder (stm32-bin) containing two items: a large bzip2 archive and a README file essentially containing these directions.
Open a Terminal window and type these two commands:

cd ~/Desktop/stm32/stm32-bin (or whatever directory contains the extracted files)

sudo tar xjPvf stm32.tar.bz2 (this will request your Administrator password)
Add the following line to ~/.profile

export PATH=$PATH:/usr/local/stm32/bin

Enter the same line of text on the command line, or close and open a new Terminal window before issuing further commands.
If everything compiled and installed without incident, the uncompressed folder is no longer needed and can be removed. All of the compiler-related files are located in the directory /usr/local/stm32.

Or, if you chose to download the source instead, use these steps:

Double-click the file stm32-src.tar.bz2.gz. Three progress bars will appear as the archive is extracted. You should be left with a folder (stm32-src) containing several items: a subdirectory (src) containing the original open-source components, and three files; build.sh, patchfile and README, the latter essentially containing these directions.
Open a Terminal window and type these two commands:

cd ~/Desktop/stm32/stm32-src (or whatever directory contains the extracted files)

sudo sh ./build.sh (this will request your Administrator password)
The entire build process may take 30 minutes or more.
Add the following line to ~/.profile

export PATH=$PATH:/usr/local/stm32/bin

Enter the same line of text on the command line, or close and open a new Terminal window before issuing further commands.
If everything compiled and installed without incident, the uncompressed folder is no longer needed and can be removed. All of the compiler-related files are located in the directory /usr/local/stm32.

Build and Install libusb

(You can disregard this section if you opted for the source package; libusb is already included with that, and the build process is automated.)

Extract the libusb source by double-clicking the file libusb-0.1.12.tar
In a Terminal window, run these four commands:
cd ~/Desktop/stm32/libusb-0.1.12 ./configure make all-am sudo make install-am
If this step completed successfully, the uncompressed folder is no longer needed and can be removed.

Edit, Build and Install FatFryer on the Mac

Extract the FatFryer source and STM32 Primer-related files by double-clicking the files CircleOS-2.0.zip, fatfryer-1.0.zip and um0427.zip (the latter is the STM32 firmware library).
In the Terminal:
cd ~/Desktop/stm32/fatfryer-1.0/fatfryer-1.0
Because FatFryer 1.0 expects an earlier version of the STM32 firmware library, we need to change the configuration script slightly to acknowledge a change of filename. Edit the “configure” file, changing this line:
testfile=stm32lib_contents.htm
to this:
testfile=stm32f10xfwlib_contents.htm
Provide the configuration command with paths to the CircleOS and STM32 firmware library:

./configure --with-circle-os=`pwd`/../../CircleOS --with-stm32-fw=`pwd`/../../um0427

(Yes, the back-quoted `pwd` is necessary; normal relative paths won’t work in this case.)
One line in the FatFryer source must be changed to work with the Mac. Edit the file tools/fatfryer-flash.c, changing this line:

// usb_close (usbDevice);

To this:

usb_close (usbDevice);

(This is line #172 in the version 1.0 source.)
Edit the file lib/Makefile.in, deleting the three lines that reference the files stm32f10x_tim1.c (and .o and .h — but not stm32f10x_tim.c, etc., just the “tim1” files), then proceed with the build and installation:

make (fairly quick, and OK to ignore the warnings)

sudo make install
If this completed without errors, you’re done with the toolchain side! The CircleOS, FatFryer source and STM32 firmware directories can be removed at this point. All the needed files have been installed in /usr/local/share and /usr/local/bin.

Install FatFryer on the STM32 Primer

To regurgitate a prior point, this sequence of steps absolutely must be performed either using Boot Camp or a separate Windows PC. It will not work under any virtualization software at this time.

If you’re using Boot Camp, have a slot-loading optical drive and are concerned about the 3" CD-ROM getting stuck, a disc image containing the current software can be downloaded from the STM32circle web site. The usual disclaimer applies of requiring a site account to access files. You should already have downloaded the current CircleOS and the FatFryer project files in a prior step. We’ll be needing those files again, so either transfer them to the PC or download them again via the previously mentioned links.

Insert the STM32 Development Suite CD-ROM (or extract the disc image) and follow the installation directions. There are check boxes for the Ride7 IDE and RKitARM for RIDE7 — install both. There’s also a USB device driver in a separate folder that will need to be installed.
While the software installs, and if you haven’t already done so, open the STM32 Primer and move the jumper on the back of the board to join the two contacts, then press the button on the front to turn it on. You can turn it off by holding down the button for several seconds.
Power up the SMT32 Primer and connect a USB cable to the port labeled DEBUG (not the port under the power button).
Update the operating system first. This will wipe out any demo applications on the Primer, but replacements (and many others) can be downloaded from the web site. After extracting the Zip file, inside the CircleOS folder is a batch file called Update_Circle_OS.bat. Double-click this file and follow the instructions. If there are any problems, the program offers some guidance for debugging the most common issues.
Next, install FatFryer: after extracting the Zip file, inside the fatfryer-1.0 folder is a batch file called add_to_Circle.bat. Double-click this file and follow the directions.
You’re done with the PC side now, and can put it away.

Using FatFryer

The README file included with FatFryer is quite thorough, but for posterity, here’s the walkthrough:

Move the USB cable from the DEBUG USB port to the STM32 port (under the power button).
Power up the STM32 Primer and run the FatFryer application. The display will show the text “FatFryer” in large letters, along with a couple of diagnostic values.
Run one of the Mac-side FatFryer apps. For example, fatfryer-flash displays the contents of the STM32 flash memory and can be used to remove previously-installed applications.
fatfryer-start outputs an example program source file (toggle_with_CircleOS.c) and associated Makefile. A subsequent make will then compile this program, and make program will download the application to the Primer. If everything is working correctly, when you run toggle from the Primer’s application menu, the red and green LEDs on the front of the unit should alternately flash.

Source code and applications generated with this toolchain and FatFryer are entirely compatible with the Raisonance development tools in Windows, and the inverse is true as well. Only the build process is different. It should be possible to update CircleOS and FatFryer without returning to the PC; this is explained in the FatFryer README file. Another nicety of working with FatFryer is that no special USB driver is required; everything works in user space and, with some tweaking, the entire development kit could conceivably be stored on a USB thumb drive for easy portability.

A tip: you’ll need to unplug/reconnect the USB cable each time you use FatFryer; it’s just one of those quirks of the STM32 Primer.

Acknowledgments

FatFryer is the work of Andrew Bardsley. Binutils, Newlib and GCC represent the efforts of countless thousands; STM32 support therein was developed by CodeSourcery, and this project is descended directly from their source. Bogdan Marinescu’s tutorial on Building GCC for Cortex, though I was working from different source packages, provided essential insights that eventually got this working on Mac OS X.