OpenSDA/OpenSDAv2 is a serial and debug adapter that is built into several Freescale evaluation boards. It provides a bridge between your computer (or other USB host) and the embedded target processor, which can be used for debugging, flash programming, and serial communication, all over a simple USB cable.
The OpenSDA hardware consists of a circuit featuring a Freescale Kinetis K20 microcontroller (MCU) with an integrated USB controller. On the software side, it implements a mass storage device bootloader which offers a quick and easy way to load OpenSDA applications such as flash programmers, run-control debug interfaces, serial to USB converters, and more. Details on OpenSDA can be found in the OpenSDA User Guide.
The bootloader and app firmware that lay on top of the original OpenSDA circuit was proprietary. But recently ARM decided to open source their CMSIS-DAP interface, and now a truly open debug platform could be created. This new open-sourced firmware solution is known as OpenSDAv2.
OpenSDAv2 uses the exact same hardware circuit as the original OpenSDA solution, and out of the box it still provides a debugger, drag-and-drop flash programmer, and virtual serial port over a single USB cable.
The difference is the firmware implementation:
- OpenSDA: Programmed with the proprietary P&E Micro developed bootloader. P&E Micro is the default debug interface app.
- OpenSDAv2: Programmed with the open-sourced CMSIS-DAP/mbed bootloader. CMSIS-DAP is the default debug interface app.
Kinetis K20 Based Hardware Circuit
Default Debug Interface
Drag-and-drop Target MCU
Virtual Serial Port
Source Code Available
The bootloader and app firmware used by OpenSDAv2 is developed by the community at mbed.org, and is known as “CMSIS-DAP Interface Firmware”. If you explore that site, you will find that this firmware was also ported to run on other hardware, but the combination of this mbed.org firmware with the Kinetis K20 MCU is known as OpenSDAv2.
It is important to understand however that it is possible to run a P&E Micro debug app on the CMSIS-DAP/mbed bootloader found on OpenSDAv2. Likewise it is possible to run a CMSIS-DAP debug app on the P&E Micro bootloader found on OpenSDA. The debug application used needs to be targeted towards a specific bootloader though, as a single binary cannot be used on both the OpenSDA and OpenSDAv2 bootloaders.
During development of OpenSDAv2 features and bug fixes, it was found that the reserved bootloader space was too small. Thus a new version of OpenSDAv2 had to be created, which was named OpenSDAv2.1. The difference between the OpenSDAv2.0 and v2.1 is the address where the debug application starts: for OpenSDAv2.0 it expects the application at address 0x5000, while OpenSDAv2.1 expects the application to start at address 0x8000.
The only board with OpenSDAv2.0 is the FRDM-K64F. All other OpenSDAv2 boards (such as the just released FRDM-K22F) use OpenSDAv2.1.
Unfortunately this means that new OpenSDAv2 apps are needed. From a user perspective this mostly affects the JLink app since it was shared across all boards. Make sure you download the correct app for your board based on the OpenSDAv2 version.
- mbed CMSIS-DAP for FRDM-K64F
- mbed CMSIS-DAP for FRDM-K22F
- P&E Micro (use the Firmware Apps link)
- Segger JLink (look at bottom of page for OpenSDAv2.0 or OpenSDAv2.1 app)
The key difference between OpenSDA and OpenSDAv2 is the bootloader.
- Boards with OpenSDA use a proprietary bootloader developed by P&E Micro, and it cannot be erased or reprogrammed by an external debugger due to the security restrictions in the firmware.
- Boards with OpenSDAv2 use the open-source bootloader developed by mbed.org, and it can be erased and reprogrammed with an external debugger.
Apps need to be specifically created to work with either the P&E bootloader (Original OpenSDA) or the CMSIS-DAP/mbed bootloader (OpenSDAv2/OpenSDAv2.1) as the bootloader memory map is different. Thus it’s important to know which type of bootloader is on your board to determine which version of an app to load.
You can determine the bootloader version by holding the reset button while plugging in a USB cable into the OpenSDA USB port. A BOOTLOADER drive will appear for both OpenSDA and OpenSDAv2.
The OpenSDAv2.0 bootloader (may also be called the CMSIS-DAP/mbed bootloader) developed by mbed.org will have the following files inside. Viewing the HTML source of the bootload.htm file with Notepad will tell you the build version, date, and git hash commit. For the OpenSDAv2.1 bootloader, this file will be named mbed.htm instead.
The OpenSDAv1 bootloader developed by P&E Micro will have the following inside. Clicking on SDA_INFO.HTM will take you to the P&E website.
When you connect a Freedom board that has OpenSDAv2 (such as the FRDM-K64F) to your computer with a USB cable, it will begin running the default CMSIS_DAP/mbed application which has three main features.
1. Drag and Drop MSD Flash Programming
You will see a new disk drive appear labeled “MBED”.
You can then drag-and-drop binary (.bin) files onto the virtual hard disk to program the internal flash of the target MCU.
2.Virtual Serial Port
OpenSDAv2 will also enumerate as a virtual serial port, which you can use a terminal program such as TeraTerm (shown below), to connect to. You may need to install the mbed Windows serial port driver first before the serial port will enumerate on Windows properly. It should work without a driver for MacOS and Linux.
The CMSIS-DAP app also allows you to debug the target MCU via the CMSIS-DAP interface. Select the CMSIS-DAP interface in your IDE of choice, and inside the CMSIS-DAP options select the Single Wire Debug (SWD) option:
Kinetis Design Studio (KDS):
Note: OpenOCD with CMSIS-DAP for FRDM-K22F is not supported in KDS V1.1.0. You must use either the P&E app instructions or the JLink app instructions to use KDS with the FRDM-K22F at this time. This will be fixed over the next few weeks.
OpenSDAv2 uses the OpenOCD debug interface which uses the CMSIS-DAP protocol.
Make sure '-f kinetis.cfg' is specified as 'Other Options':
Appendix A: Building the CMSIS-DAP Debug Application
The open source CMSIS-DAP Interface Firmware app is the default app used on boards with OpenSDAv2. It provides:
- Debugging via the CMSIS-DAP interface
- Drag-and-drop flash programming
- Virtual Serial Port providing USB-to-Serial convertor
While binaries of this app are provided for supported boards, some developers would like to build the CMSIS-DAP debug application themselves.
This debug application can be built for either the OpenSDAv2/mbed bootloader, or for the original OpenSDA bootloader developed by P&E Micro. If you are not sure which bootloader your board has, refer to the bootloader section in this document.
Building the CMSIS-DAP debug application requires Keil MDK. You will also need to have the “Legacy Support for Cortex-M Devices” software pack installed for Keil.
You will also need Python 2.x installed. Due to the python script used, Python 3.x will not work.
The code is found in the MBED git repository, so it can be downloaded using a git clone command:
“git clone https://github.com/mbedmicro/CMSIS-DAP.git”
Note that there is a Download Zip option, but you will run into a issue when trying to compile that version, so you must download it via git instead.
The source code can be seen below:
This repository contains the files for both the bootloader and the CMSIS-DAP debug interface application. We will concentrate on the interface application at the moment.
Open up Keil MDK, and open up the project file located at \CMSIS-DAP\interface\mdk\k20dx128\k20dx128_interface.uvproj
In the project configuration drop-down box, you will notice there are a lot of options. Since different chips may have slightly different flash programming algorithms, there is a target for each specific evaluation board. In this case, we will be building for the FRDM-K64F board. Scroll down until you get to that selection:
Notice there are three options for the K64:
- k20dx128_k64f_if: Used for debugging the CMSIS-DAP application with Keil. Code starts at address 0x0000_0000
- k20dx128_k64_if_openSDA_bootloader: Creates a binary to drag-and-drop on the P&E developed bootloader (Original OpenSDA)
- k20dx128_k64_if_mbed_bootloader: Creates a binary to drag-and-drop onto the CMSIS-DAP/mbed developed bootloader (OpenSDAv2)
Since the FRDM-K64F comes with the OpenSDAv2 bootloader, we will use the 3rd option. If we were building the mbed app for another Freedom board which had the original OpenSDA bootloader, we would choose the 2nd option instead.
Now click on the compile icon. You may get some errors
- If you get an error similar to the one shown below, make sure you have installed the Legacy pack for ARM as previously described earlier:
..\..\Common\src\RTX_Config.c(184): error: #5: cannot open source input file "RTX_lib.c": No such file or directory
..\..\..\shared\USBStack\INC\usb_lib.c(18): error: #5: cannot open source input file "..\..\RL\USB\INC\usb.h": No such file or directory
- If you get an error regarding a missing version_git.h file, make sure that Python 2.x and git are in your path. A Python build script fetches that file. It's called from the User tab in the project options, under "Run User Programs Before Build/Rebuild".
- If there is a warning about “invalid syntax” when running the Python script, make sure your using Python 2.x. Python 3.x will not work with the build script.
Now recompile again, and it should successfully compile. If you look now in \CMSIS-DAP\interface\mdk\k20dx128 you will see a new k20dx128_k64f_if_mbed.bin file
If you compiled the project for the OpenSDA bootloader, there would be a new k20dx128_k64f_if_openSDA.S19 file instead.
Loading the CMSIS-DAP Debug Application:
Now take the Freedom board, press and hold the reset button as you plug in the USB cable. Then, drag-and-drop the .bin file (for OpenSDAv2) or .S19 file (for OpenSDA) into the BOOTLOADER drive that enumerated.
Perform a power cycle, and you should see a drive called “MBED” come up and you can start using the CMSIS-DAP debug interface, as well as drag-and-drop programming and virtual serial port as described earlier in this document.
Appendix B: Building the CMSIS-DAP Bootloader
All Freedom boards already come with a bootloader pre-flashed onto the K20. But for those building their own boards that would like to use CMSIS-DAP, or those who would like to tinker with the bootloader, it possible to flash it to the Kinetis K20 device. Flashing the bootloader will require an external debugger, such as the Keil ULink programmer or Segger JLink.
Also note that the OpenSDA/PE Micro Bootloader cannot be erased! Due to the proprietary nature of the P&E firmware used by the original OpenSDA, it can only be programmed at the board manufacturer and JTAG is disabled. So these instructions are applicable for boards with OpenSDAv2 only.
First, open up the bootloader project which is located at \CMSIS-DAP\bootloader\mdk\k20dx128\k20dx128_bootloader.uvproj
There is only one target available because all OpenSDAv2 boards will use the same bootloader firmware as the hardware circuitry is the same.
Click on the compile icon and it should compile successfully. If you see errors about a missing version_git.h file, note that Python 2.x must be in the path to run a pre-build script which fetches that file.
Now connect a Keil ULink to J10 and then insert a USB cable to provide power to J26. Note that if you have the 20-pin connector, you’ll want to use the first 10 pins.
Then for Keil 5 you will need to change some debug options (CMSIS-DAP is built under Keil 4.x).
Right click on the bootloader project, and go to the Debug tab and next to ULINK Pro Cortex Debugger, click on Settings:
Then under “Cortex-M Target Driver Setup”, change the “Connect” drop down box to “under Reset” and “Reset” dropdown box to “HW RESET”. Hit OK to save the settings.
Then in Keil, click on Flash->Erase.
And then on Flash->Download.
If you get an “Invalid ROM Table” error when flashing the CMSIS-DAP bootloader, make sure you made the changes to the debugger settings listed above.
After some text scrolls by, you should see:
Now power cycle while holding down the reset button, and you should see the bootloader drive come up. You’ll then need to drag and drop the mbed application built earlier onto it. And that’s all there is to it!
The binaries for the bootloader and CMSIS-DAP debug app for the FRDM-K64F board created in writing this guide are attached.