When Freescale decided to make available an inexpensive development platform for their then-new Kinetis ARM Cortex-M microcontrollers – which they called the FRDM (“Freedom”) platform – they partnered with P&E Micro to build an on-board debug solution, just as they had with their DEMO boards for the S08 series of 8-bit microcontrollers, and in both cases it was a huge failure and bad for Freescale’s customers.

Customer-hostile debug firmware

The S08 story – which I painstakingly documented in 2009 – was that Freescale’s S08 DEMO boards, which had an on-board debug solution from P&E called USB-BDM, were locked down. The USB-BDM could only be used to debug the chip on the board, not external hardware – even if that external hardware was based on the same family of S08 chip. This obviously infuriated people, and I said, back then, that we needed to call out Freescale and P&E for their shitty behavior.

The Freescale “Freedom” boards – was that an intentional irony? – sport a P&E debug “solution” called OpenSDA: the “open <something> debug architecture”. However, there is nothing about it that is open. Supposedly a document describing how to write OpenSDA “apps” exists, but I could never find it on Freescale’s or P&E’s web sites. The .SDA files that I could find all had some kind of weird scrambling or encryption applied to them.

The OpenSDA “architecture” is that there are two pieces of firmware on the board: a bootloader (essentially permanently resident), and a debug app (which can be replaced). The boards ship with an OpenSDA bootloader and a debug app that is tied to a proprietary P&E product.

When I first discovered this lovely situation I thought, “No problem. I’ll just write a simple debug app of my own and put it on there.” But without a specification, or documentation of any kind, and with the existing .SDA files unreadable, I had no model to base my work on.

I also discovered serious problems with the bootloader itself. It is based on a USB mass-storage device, but because of their shitty implementation, it only works on Windows, and only on select versions of Windows.

I’m not sure why they thought a mass-storage bootloader was a good idea. There is this belief that drag-and-drop is easier for the user (I happen to disagree), but in practice it’s a bad choice. It requires a lot of code on the target (correct USB “storage class” device metadata, a USB mass storage firmware layer, and code to “parse” the file being copied and turn that into blocks of code to write to Flash). The user interface feedback is poor: it’s difficult to know if it “took” or not. It doesn’t work on OSX, which insists on scribbling random files and directories onto newly-inserted USB media. It’s hard to get right.

Had they made a simpler choice – a trivial bootloader for instance, with a simple, published interface (like on Freescale’s S08JS16) – it could easily be cross-platform. Instead, the board at first appeared to be a very light paperweight.

These problems were fixed in a later version of OpenSDA, but in order to download it from the P&E site you have to fill out a form with an email address, but then when you submit the form you get another form that says, “Oh, actually, we want to know everything about your company”. When I first saw this I laughed at how stupid and customer-hostile this was, and filled out the form with a throw-away email address and a contact and company name that basically read “You Have Got To Be Kidding”.

Saner, kinder debug firmware

Thankfully, there is a way out of this mess.

While Freescale was partnering with P&E on their idiotic firmware, ARM had other ideas. As part of its CMSIS effort (in case you were wondering, that stands for “Cortex Microcontroller Software Interface Standard”) they developed their own debug architecture – called CMSIS-DAP – which was much more sane and open than OpenSDA. It first showed up in a Keil app note (which included the source code for the implementation!), and after doing some digging I also found copies of it in various Freescale-supplied “quick start packages” (QSPs) for the original FRDM boards.

CMSIS-DAP has since been extended somewhat. The new standard interface is called DAPlink and adds a USB-CDC serial port (yay) and a mass-storage interface of its own (ugh) to the original CMSIS-DAP HID device. Unlike the OpenSDA bootloader, which is used to replace the debug app, this mass-storage interface is used to program the target microcontroller.

Rescue your FRDM board from idiocy

There are two things you need to do.

First, replace the original, broken, OpenSDA bootloader with the updated one. If your FRDM board shipped with a P&E bootloader, don’t bother going through the hassle with their web site. I’ve archived a copy of the updated bootloader here: BOOTUPDATEAPP_Pemicro_v111.SDA.

Second, replace P&E’s proprietary debug firmware with something more useful – probably CMSIS-DAP or DAPlink.

To upgrade the bootloader:

To upgrade the debug firmware, you have to find the correct blob for your board, and that’s not entirely straightforward.

I would start at NXP’s OpenSDA resources page. Find your FRDM board on the list and scroll down to the “Latest firmware application” section. Download the CMSIS-DAP or DAPlink binary archive listed. After unzipping it, put your board into BOOTLOADER mode as above, and copy over the .bin version of the app. Eject or unplug the board. Then plug it back in – this time not pressing the reset button – and it should enumerate. In the case of DAPlink, it should also create a mass-storage device called DAPLINK.

CMSIS-DAP or DAPlink is the firmware that Freescale should have put onto the FRDM boards in the first place. I’m really not sure what they were thinking!

If you are interested in the original CMSIS-DAP firmware, you should read the Keil app note, and download Keil’s source code. You can also download my archived copy of the Freescale-provided CMSIS-DAP S19 file (for the FRDM KL25Z).

Have a drink to celebrate the beginning of a new life for your FRDM board!

Not totally out of the (firmware) woods?

Alas, there are still problems. For one, both the CMSIS-DAP and DAPlink firmware, while essentially open-source, are only buildable with the Keil toolchain, which costs money and only runs on Windows. So building your own copy of either will be a costly and/or involved undertaking, especially if your chosen dev platform isn’t Windows.

The mass-storage (drag-and-drop) interface that DAPlink adds to the original CMSIS-DAP firmware has – SURPRISE! – suffered from problems similar to those encountered by the P&E OpenSDA bootloader. On Windows 10, for example, some boards would get totally bricked, requiring use of an external SWD/JTAG probe to get them running again!

What I would love to see is a version of DAPlink that has the USB UART channel, but lacks the ridiculous mass storage interface. Unfortunately, because of the dependence on the Keil toolchain and Windows, I’m unlikely to undertake this.

Actually, what is truly crazy is that the CMSIS-DAP and DAPlink projects have not been ported to mbed! They could use the mbed OS, USB libraries, etc, and be buildable in the cloud! That would be super cool: configure a version of DAPlink without the mass storage crap, build it in the cloud, and burn it onto your board. Done!