Setting up a basic ChibiOS project

ChibiOS is a nifty little OS for a selection of microchips, most notably chips from the STM32 family.

There are plenty of examples how you can start working with ChibiOS in Eclipse and other IDE’s, and also how to compile the demos from command line with make but not a lot for working with an actual project without an IDE. Usually the guides say to copy a demo and hack away, which works for IDE’s quite well. While this is also the best way to get started when you use just command line tools it’s not really a clean way to work with a “real” project.

Fortunately, ChibiOS is really easy to set up so that you don’t need to muck about in the ChibiOS code tree at all which is nice when you eventually want to upgrade to a newer ChibiOS version. We have a skeleton project in github (also downloadable as zip for stable 2.2.7 and unstable/trunk versions of ChibiOS) which can be used to bootstrap a new make-based ChibiOS project, but do read on while downloading since it’s useful to know the project structure in case you want to tweak it.

If you look at what the demo projects contain (disregarding the IDE parts), you will notice that they are actually really simple.


This is the application code, for a fresh project you might want to delete all code except for the ChibiOS initialization and a mainloop that blinks a heartbeat led (so you have a way to confirm the basic structure is working before adding more functionality).


These are the configuration headers for ChibiOS core, the Hardware Abstraction Layer and MCU, respectively. Usually you only change the HAL and MCU configurations to match the peripherials used in your project. It’s a good idea to go over these when you copy them and think through which parts to enable as this has a big impact on your code size.


The last bit is the Makefile which is the meat for building from the command line. The ChibiOS build structure is very well thought through so there are just a couple of places where we need to change things. We’ll go through them below.

But first let’s discuss directory structure. As said earlier we don’t want to change anything inside the ChibiOS source tree so it is best to unpack or check out the code in a completely separate directory, not within your project directory. However it is handy to create a symbolic link in your project directory to the ChibiOS directory, as this allows one to try another (compatible) version of ChibiOS simply by changing the target of the link.

While you can keep all the sources and headers in one directory, it is cleaner to have separate directory for the configuration and sources so in this example we create a dedicated directory for configuration, headers and source code:

Project root
- config
- include
- src

So let’s dig into the changes we need to make to the Makefile in our project root to support the chosen structure. Only the changed parts are mentioned below, the rest of the Makefile will stay as it were in the demo.

# Define project name here
PROJECT = myproject

This defines what your binaries will be named, but does little else.

# Imported source files

The CHIBIOS variable defines where the top of the ChibiOS tree is. Here it is set as “ChibiOS” since we had that symbolic link to the tree. If you don’t create one, set this to be the path to where you keep your ChibiOS. This variable is used to locate all the ChibiOS build files and sources so we don’t need to change each reference to them.


# C sources that can be compiled in ARM or THUMB mode depending on the global
# setting.
... \
$(wildcard src/*.c)

This variable defines the list of sources that will get built in our project. All ChibiOS sources must be listed here, though only the ones that are enabled one way or the other by the configuration get actually compiled in the resulting binary. Since we are lazy we use the wildcard function of make to automatically include all C-sources from our source directory. This way we don’t need to change the Makefile when adding new source files.

... \
config include

Here we have the list of directories to search for headers. We had separate directories for configuration headers and project-specific headers so we include them in the end of the list.

…aaand that’s about it! Now we have a clean setup for our project, and can start developing the greatest embedded software ever made. Before doing that there are couple of first steps that are STRONGLY suggested:

  • First and foremost, import this setup into your favourite version control system as a base. There’s nothing like having a clean start for a history of a project. Don’t even consider not using a version control system, you *will* be sorry later! The VCS chosen is not important, but using it is.
  • Second step, and equally important one too, is to include a COPYING file in the toplevel directory. As we include code from the ChibiOS sources, start out by mentioning that and the ChibiOS license (GPL v3 or later currently). After that state the license you want to use for your project. Having a clear copyright and licensing is essential when working with open source, and not harmful if you plan on keeping the code to yourself (which ChibiOS stable releases allow).
  • The final step would be to create a README file where you shortly describe the project and how to build it, which is always nice to have.

Now let’s roll up our sleeves and start hacking!

This entry was posted in Software, Tools and tagged . Bookmark the permalink.

One Response to Setting up a basic ChibiOS project

  1. Evan Foss says:

    Thank you. This will be helpful.