Using an Eclipse-based IDE

This article will explain how to use an Eclipse based toolchain, as explained in “Setting up an Eclipse-based IDE” to develop general or ChibiOS-based applications. This guide will teach you to:

  • Importing ChibiOS demos into the Eclipse environment.
  • Edit and reformat your source code.
  • Compile and examine errors and warnings.
  • Upload your program on the target board.
  • Debug your code on the target board both in high level language and/or assembler.
  • Develop embedded applications with or without ChibiOS.

What this guide does not cover

This guide assumes knowledge in following areas:

  • OpenOCD setup is not covered by this guide because the setup changes depending on the JTAG probe used, the target MCU and also the target board. The guide will show the setup for a specific JTAG probe and a specific target, a valuable source for the OpenOCD setup is the OpenOCD dedicated forum, most questions you may have about OpenOCD have most likely already been answered there.
  • Hardware setup.

Required Components

You will need:

  • An Eclipse/GCC/OpenOCD based toolchain, for example the one described in the article “Setting up an Eclipse-based IDE”.
  • An Olimex ARM-USB-OCD JTAG probe, this guide applies to any other ARM JTAG probe as long it is supported by OpenOCD.
  • An Olimex STM32-P103 target board, this guide applies to any other ARM target except for the OpenOCD setup part.
  • A terminal emulator for capturing the board serial output, Windows users may use Hyper Terminal (not recommended), Linux and MAC OS-X users may use CuteCom. All ChibiOS/RT demos generate a test report on the serial port when a button on the target board is pressed, other demos may activate a command shell on the serial port, in both cases a terminal emulator is required.

Working with Projects

Project-related tasks.

Preparing your Workspace

The default settings in Eclipse CDT are not ideal for embedded development, before starting importing projects into the workspace please execute the following steps:

  1. Open Eclipse preferences: “Window→Preferences”.
  2. Navigate the left tree into “C/C++→Code Analysis” and disable everything, without doing this you will see a lot of Errors and Warnings from the static analyzer mixed to the errors found by the compiler and that is very confusing.
  3. Navigate the left tree into “C/C++→New CDT Project Wizard→Makefile Project” then select the “Discovery Options” tab. Select “Automatic discovery of paths and symbols” and then “GCC per project scanner info profile”. This will enable Eclipse CDT to automatically find all the projects paths when the project is first compiled.
  4. Select the “Behaviour” tab and select “Use parallel build” then “Use optimal jobs number”. This will enable the projects build using all the available cores, much much faster.
  5. Navigate the left tree into “Run/Debug→Launching→Default Launchers”.
  6. Select “GDB Hardware Debugging→[debug]” then select “Standard GDB Hardware Debugging Launcher”. This will select the proper debugging mode when using various extensions plugins like the ChibiOS/RT debugging plugin.
  7. Press “Apply” and close the properties dialog.

Note that the above settings will be copied into newly created projects but will not affect existing projects. You can set the same options into existing project's properties.

Importing Makefile projects into Eclipse

The first step is to import a makefile project into the Eclipse environment. ChibiOS/RT demos do not include Eclipse project files but just a normal Makefile. Eclipse is able to import a Makefile project and create its own project file so this is not a problem. This is how it is done:

  • Open you Eclipse environment and select the workspace created into the ChibiOS/RT project directory.
  • From within Eclipse select “File→New→C_Project”, a dialog box will show.
  • Select “Makefile_project→Empty_Project” in the “Project type:” box.
  • Select “– Other Toolchain --” in the “Toolchains:” box.
  • Unselect the “Use default location” check box.
  • Select the demo directory using the “Browse…” button. Something like “C:\Projects\ChibiOS\demos\STM32\RT-STM32F103-OLIMEX_STM32_P103” will appear in the “Location:” box.
  • In the project name box put the same name of the directory containing the demo, “RT-STM32F103-OLIMEX_STM32_P103” in this example. eclipse2-003.jpg
  • Press the “Finish” button and the project will be created and shown in the “Project Explorer”.
  • Create two “linked” folders named “os” and “board” inside the newly created project. Make them link to the “./os” and “./os/hal/boards/<boardname>” directories inside the ChibiOS installation. In order to do so follow this procedure (twice, one for each folder):
    1. Right click on the project name in the project explorer then select “New→Folder” a dialog will appear.
    2. Select “Advanced»” then “Link to an alternate location (Linked Folder)”.
    3. Write the destination directory for each of linked directories (for example “${PROJECT_LOC}/os” and “${PROJECT_LOC}/os/hal/boards/OLIMEX_STM32_P103”).
    4. Press “Finish”.
  • Compile the project at least once, this will allow Eclipse CDT to discover all the paths used by the project.
  • Right click on the imported project and select “Index→Rebuild”, this will make Eclipse build its internal symbols database.
  • Repeat the above steps for each ChibiOS demo you want to import in Eclipse, all the demos that have a makefile can be imported.
Creating a new Makefile project

If you want to create a new application it is recommended that you create a Makefile project first then you can import it into eclipse using the above procedure. Makefile projects have the advantage that can be compiled everywhere even without Eclipse. Creation steps:

  • Create your own development directory under the ChibiOS installation directory, for example “./myprojects”.
  • Copy an existing demo, of course choose a demo using your same target, into the new directory and rename it, for example “./myprojects/myapplication”.
  • Customize the Makefile if needed, usually you just need to do this if your application is composed by more than one source file. You may also want to remove the ChibiOS test code from your application.
  • Once your makefile is ready, import the project under the Eclipse workspace using the procedure described in the previous section.


Build-related tasks.

Compiling projects

Once imported, an application can be compiled by using the “Build All” button in the toolbar or by right clicking on the project and selecting “Build Project”.


The compilation result is visible as a complete log in the “Console” window, the detail of all errors an warnings is available in the “Problems” window.


The build process produces the binary files specified in the Makefile, all the ChibiOS demos produce binary files named ch.elf, ch.bin and/or ch.hex. The image must be loaded on the target board in order to execute it. The build process usually creates also some other useful files containing details about the built application (usually named and ch.dmp).

Cleaning projects

In order to clean a project (removing all the temporary and binary files) right click on the project and select “Clean Project”.


Debug-related tasks.

Creating a GDB Debug Configuration

Note, the following procedure applies when OpenOCD is used as GDB server, the following steps may differ if using a different GDB server but the concept is the same.

In order to debug your application a debug configuration must be created. The configuration instructs GDB (the source debugger used by Eclipse) on how to load the image, load the symbols and place the initial breakpoint in the make function. Note that GDB performs its function by connecting to a “GDB server”, the GDB server implements the low level communication with the target device through the JTAG probe. A target specific debug configuration is required in order to:

  • Establish a connection with the GDB server.
  • Stop and reset the target.
  • Upload the binary code in Flash or RAM.
  • Set an initial breakpoint in the main function.
  • Start the target (which will immediately stop on the breakpoint).

The first thing to do is to open the “Debug Configurations…” dialog:


The configuration dialog will appear, now we must create a debug configuration:


Note that the “GDB Hardware Debugging” extension must be already installed or you will not see that.

Now we must give the configuration a name, “ARMCM3-STM32F103 (Flash and Run)” in this example, then setup the various configuration pages as follow. The “Main” tab:


Please make sure that at the bottom of this dialog “Using Standard GDB Hardware Debugging Launcher” appears, if not change the mode by pressing “Select other…”.

The “Debugger” tab:


The “Startup” tab:


Note that the “Commands” tab contains the part that changes depending on the target. The complete commands sequence (it is not fully visible in the image) for STM32 is:

monitor soft_reset_halt
monitor soft_reset_halt
monitor wait_halt
monitor poll
monitor flash probe 0
monitor stm32f1x mass_erase 0
monitor flash write_bank 0 build/ch.bin 0
monitor soft_reset_halt

The “Common” tab:


Now the debug configuration is complete.

Preparing for Debug

In our scenario the GDB server functionality is performed by OpenOCD, this mean that OpenOCD must be running while performing a debug session within Eclipse. Please refer to the OpenOCD manual in order to configure it for your probe and launch it.

Now we are ready to debug an application on the target. Note that Eclipse have a mechanism called “Perspectives”, you edit and compile your source code while you are in the “C/C++ perspective” while the debugging is performed in the “Debug perspective”. You can switch perspective at any time, even while there is an active debug session. If you install more of the many Eclipse extension plugins (there are thousands) you may have even more perspectives available.

Starting a Debug Session

In order to start a debugging session first make sure that OpenOCD is running then press the drop down menu on the right side of the debug icon in the toolbar (the small green bug) and select your debug configuration (we created just one but you may have multiple debug configurations in your project, for example I usually create another debug configuration that just starts the target without uploading the code).


The debugger will be initialized, you will see the operation in progress on the console then Eclipse will switch to the debug perspective and you will see your program stopped on the default breakpoint in the main function.


From there you can perform all the usual debugging tasks, set breakpoints, single step execution, variables, memory and registers inspection etc. Please refer to the Eclipse documentation about those “normal” operations. Note that if the debugging start procedure hangs then there is probably an error in your configuration or problems with the target, read the console log and/or the OpenOCD output in order to understand where the problem is.

Stopping a Debug Session

From the debug perspective press the stop button (small red square) in the debug window, the target will be stopped and you may both return to the C/C++ perspective or start it again.


The package ChibiStudio contains a workspace alread prepared with all ChibiOS demo applications, you don't need to import projects. Just compile and launch the application.

See also the video guides on PlayEmbedded, all points covered by this guide are also covered there and in more detail.

More articles and guides are available on the technical wiki.

learn more

Need Tutorials?

Try the video tutorials and guides on Play Embedded.

learn more

Need Support?

The forums is the best place, registration required.

learn more