Product Information
Community and Support

Migrating to ChibiOS or update to a newer version

Updating ChibiOS to a newer version is a common task for those project that are maintained for long periods.

Version numbers explained

ChibiOS version numbers are composed as follow: year.month.patch. Patch number is increased for bug fixing only within the same branch. Year and month define the branch.

The rule is that within a released branch only bug fixes are performed unless a change is required for bug fixing.

New features and API changes only occur between branches.

How changes are tracked

All changes are listed in the change log (the readme.txt file in the ChibiOS root). It is always a good idea to read in in case one of the fixes impacted a feature that is used in your project.

All bugs have a tracking number like #789 which is used to find the ticket in our bug tracker on SourceForge. Note that ticket very often are also discussed in our Bug Reports forum, you may obtain more information reading both sources.


There are several distinct update cases:

  • Updating to a newer version in the same branch.
  • Upgrading to a new branch.
  • Not really an update but you may want to update from a different RTOS or start using an RTOS.
Updating in the same branch

Updating within the same branch just means replacing your old ChibiOS source tree with the new one. The rule is that versions have to be compatible unless a change is reported in the change log.

Upgrading to a different branch

This is more complex because API changes can occur between major releases and new features are added. It can also happen that features are removed and replaced by better equivalents. ChibiOS is an alive project and it grows and changes.

There is not a single recipe for an upgrade but there are several rules that are always true and must be followed.

  • Makefiles evolve, use a makefile from a project of the new version and make the required changes.
  • Configuration files must come from the new version so update your chconf.h, halconf.h and mcuconf.h. Also update files from the external projects (FatFS, lwIP etc).
  • API changes are usually detected as compilation errors, if a function is no more present then it has been renamed (with same functionality) or replaced by a new one with an enhanced functionality.
  • The change log must be examined carefully, big changes in API are listed there and, for sure, there is a discussion topic in the Development and Feedback forum with the rationale for changes and migration hints.
Migrating from a different RTOS

It is hard to write a guide about this but some recommendations can be made:

  • ChibiOS has a very rich API, most likely anything you use from another RTOS has a direct equivalent in ChibiOS. Your first step should be to do a mapping of used functionality on the ChibiOS API.
  • ChibiOS has usually an higher level of abstraction when compared to similar products, you never manipulates interrupts directly or write ISRs like recommended by your compiler, you need to use the primitives provided by ChibiOS that are then translated to the best implementation for the compiler you are using. In general you don't need non-standard C extensions, if you have some then you should verify if it can be replaced by a ChibiOS-provided construct.
  • ChibiOS has very strict rules about the API usage, API can only be invoked from the proper context and things are checked at runtime when the debug options are enabled. This means that if the system hits an assertion, it is actually good news, you just found a latent problem that could have bitten you later.
  • It is recommended that you adopt the ChibiOS project structure, startup files, build system and conventions, be compliant and make your life easier. It will also make easier for us to help you.
  • Starting from an existing demo or template application then integrating your code is the safest and cleanest approach.

ChibiOS has been developed for more than 10 years now and is a set of well balanced tools, adopting it as a whole can really make your life easier. Of course is also possible to just take bits and pieces, for example just the RT RTOS, and integrate it in your project to replace another RTOS, in this case you would not benefit from the rest of the ecosystem and you will need to take care of all integration details.

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