Tutorial: Using Eclipse + ST-LINK/v2 + OpenOCD to debug

Getting Started
1

1 Introduction

Since I spent quite some time figuring out what the best way is to debug the Spark-Core using ST-Link/v2 and how to do it, I thought I'd share my findings hoping it would save someone else some time. My aim is to make this tutorial usable for both beginners and advanced users so I'll start with the basics.

Hardware Requirements:

  1. PC
  2. Spark Core
  3. ST-LINK/v2 ( if you're going to buy one, you might wanna check ebay too )
  4. JTAG Shield ( buy one or make one )

2 Software Installation

I assume you already have downloaded and installed Eclipse IDE for C/C++ Developers otherwise download it from here and unpack it to a local folder.

2.1 Installing ST-LINK/v2 Device Drivers

Download and install the appropriate driver matching your Windows version from here. You might also want to install ST-Link Utility which not being necessary is a useful program. Once you did that, you should be able to see your STM32 STLink device in Device Manager.

2.2 Installing GNU Tools for ARM Embedded Processors

In order to be able to compile your projects and debug them, you need to download and install the latest version of GNU Tools for ARM Embedded Processors from here.

2.3 Installing EGit.

In order to be able to work with Git repositories, you might wanna consider installing Eclipse Git Team Provider. Go to Help > Install New Software and install Eclipse Git Team Provider.

2.4 Installing GNU ARM Eclipse Plug-ins

This set of Eclipse extensions are an easy, fast, great and portable way of creating, building, debugging and managing your project. You can read more about them here.
Go to Help > Install New Software and click Add. Type in "GNU ARM Eclipse Plug-ins" as the Name and "http://gnuarmeclipse.sourceforge.net/updates" as the Location. Select all the items and continue with the installation.

2.5 Installing The GNU ARM Eclipse OpenOCD

The Open On-Chip Debugger (OpenOCD) aims to provide debugging, in-system programming and boundary-scan testing for embedded target devices. It supports many different adapters including ST-LINK/v2 and has recently added support for SWO tracing which allows you to see the output of STDOUT e.g. printf, right inside your Eclipse terminal. In my opinion, this is an incredible and priceless debugging tool.

  1. Download the The GNU ARM Eclipse OpenOCD which is basically a compiled and hassle-free binary of the latest OpenOCD source from here.
  2. Run the setup and install it preferably in the default location.
  3. Navigate to C:\Program Files\GNU ARM Eclipse\OpenOCD\scripts\board, create a new file called sparkcore.cfg and populate it with the following lines:

This is a SPARK-CORE board with a single STM32F103MD chip.

source [find interface/stlink-v2.cfg]
set WORKAREASIZE 0x4000
source [find target/stm32f1x_stlink.cfg]
# use hardware reset, connect under reset
reset_config srst_only srst_nogate

3 Configuration

3.1 Creating a new project

Now since the Spark Core firmware is currently not compilable on Windows due to makefile issues, for the sake of demonstration, we will create a new project from scratch.

  1. Go to File > New > C++ Project.

  2. Select STM32F10x C/C++ Project and Cross ARM GCC and give your project a name.

  3. Fill in the Target processor settings according to the picture below.

  4. Change the directory structure if you so wish.

  5. Select the configurations you want to include.

  6. Check the path of the Toolchain you installed in section 2.2.

  7. Right click on your project and choose Build Project. The build should succeed and you should get a Debug folder containing a .elf file named after you project.

3.2 Creating a Debug Configuration

The next step would be to setup a debug configuration and begin debugging!

  1. Go to Window > Preferences > Run/Debug > String Substitution and make sure openocd_path refers to the bin folder of the OpenOCD installation. Click OK.

  2. Click on the little green bug icon in the Eclipse toolbar and select Debug Configurations...

  3. Right-click on GDB OpenOCD Debugging and select New. The Main tab should already be good to go.

  4. In the Debugger tab, enter "-f board\sparkcore.cfg" to pass in the configuration file we created to the OpenOCD.

  5. The Startup tab should already be all set as well.

  6. In the Common tab, make sure you select Shared file to force the settings to be saved in the project rather than the Workspace.

  7. Press the Debug button to flash the firmware to your board and start debugging! The debugger will stop in the beginning of the main function and once you press F8, the CPU will start the execution of your main function.

At this point, your firmware should already be flashed to the Spark Core and you will see the debug messages in the console which counts the seconds.

Happy debugging!

10 Likes
2

Awesome tutorial! :smile:

1 Like
3

Thanks bro!

4

@omidontop, this rocks! I can’t wait to give this a go tonight. Great job! :smiley:

1 Like
5

Cheers! :smiley: let me know if I neglected to mention anything!

6

@omidontop, which version of Eclipse are you assuming is installed (link please)?

1 Like
7

Well, I have the following Eclipse version installed:

Eclipse IDE for C/C++ Developers
Version: Luna Service Release 1 (4.4.1)
Build id: 20140925-1800

Eclipse IDE for C/C++ Developers Luna can be downloaded from here.

1 Like
8

Second the awesome comment. Thanks for your generosity in taking the time to share this info. Though I have the JTAG shield, I’ve been using a simpler non-debugging Eclipse setup and have not had time to pursue debugging. Not only have you made the effort to get this working, but have also made your work available to the rest of us, both of which no doubt took a great deal of time and frustration.

BTW: what tool did you use to create the very professional looking tutorial and post it to the Spark community? I’m a bit in the dark as to how to do much beyond text posts here.

Thanks again!

1 Like
9

@Neurofrantic: That was a very kind and nice comment! I really appreciate it and I’m very happy to have been of a little help. I think SparkCore is a great platform and has a very good potential for serious projects. I will continue working on it and will try to share more as I go along.

And as for the editor I used, I actually used the same web editor everyone uses, but the key is to make more effective use of headers, images and numbered lists.

Thanks again :smiley:

1 Like
10

What about Mac? If we can't build locally with the core firmware - how do we debug? Maybe I'm missing something?

11

@mtnscott: Well, yes it can be built on Mac as it is. It can also be built on Windows if you make some modifications in the makefile. However as the main focus of this tutorial is how to debug SparkCore, it is based on creating a clean project from scratch rather than compiling the Spark Core original firmware.

12

@omidontop Is not the point to be able to move from building your App in the webIDE to building locally and debugging it? In order to debug your application running under the Spark firmware you have to build and link your app with the Spark firmware. So your tutorial is awesome! It gets someone setup building and debugging an STM32f10x native application. Would be great is how to build an application that compiles and flashes in the webIDE or using spark compile or even the local IDE development - and transition to building + debugging under this environment.

We just need to take it one more step - I understand there is a mess on how applications are built with the core-firmware but aside from that. If you are building that way - can you share how it’s done?

13

YES - this is what we want to do - but I think your tutorial really gets people to

how to debug the STM32f103

you are not really debugging the Spark core as you are not using the firmware on the core - so you won't get cloud services this way. Or am I missing something?

BTW - your tutorial is excellent in getting us this far.

14

Are you sure? Compiling the Core firmware on Windows is pretty easy for me.

This actually brings up another question for me, but ... I think it would be best if I started another thread for that, actually.

15

@mtnscott:

You are absolutely right and that was my goal from the beginning. But as I explained and due to the makefile issues I experienced during my tests, although I have actually fixed those issues on my machine, but I couldn't proceed with the original core firmware in this tutorial as people would've wondered how is it that I can build it and they can't. I do although have it in my agenda to share my fix and complete this tutorial when I get the time.

Again you're right. You don't. But I also wanted to show how easy it is to create a firmware from scratch for those like me whom would for example like to run an RTOS on their core or do things their own way.

16

@naikrovek:

Well, as you can see in the picture below:

Since there are slight differences in the shell commands between Windows and UNIX-based systems and also in the use of / in Linux and \ in Windows, the build fails in the very beginning. I think you can continue if you try to create the folder structure of the build folder yourself but you'll still have issues with a clean build.

The way I'd solve it is to define different commands based on the build environment. For example for Linux:

RM := rm -f
RMDIR := rm -f -r
MKDIR := mkdir -p

And on Windows:

RM := del /q /f
RMDIR := rd /s /q
MKDIR := mkdir

You would also need to convert all the slashes to back-slashes when passing file names and paths e.g. something like this:

fixdir = $(subst /,\,$(dir $1))

I did this a long time ago and there might still be some more minor changes required but these were the major ones.

17

Hi @omidontop

I don’t build Spark on Windows but I do some building of other programs. Instead of making the makefile more complex, what most people do is run make in a shell that allows more Unix-like paths and commands. There are lots of choices–at work I have used Cygwin.

Maybe @peekay123 who I know builds locally on Windows can comment on what he uses.

1 Like
18

I think if you launched Eclipse from a Git Shell prompt that the firmware would compile without modification. I haven’t tried it, however.

2 Likes
19

@bko & @naikrovek

You are right. But I always compile everything in native Windows environment. Since both the GNU ARM Toolchain and the GNU Make are available for the native Windows environment, using a Unix shell might be an unnecessary overhead. Of course it’s a matter of preference.

20

True, you don’t have to compile from there, though, just launch Eclipse via the shell, then exit the shell. The environment present in the shell (with the correct unix command syntax) will propagate through to Eclipse, so you won’t need to modify any code.

In theory. Again, I haven’t tried.

1 Like