Product Information
Community and Support

ChibiOS/HAL Integration Guide

This guide describes what is needed in order to integrate ChibiOS/HAL in a build environment different from the default one provided in ChibiOS distribution.

What this guide does not cover

This guide has a limited scope, the following topics are handled elsewhere:

  • Porting the HAL to different architectures or different compilers is not covered in this guide
  • This guide does not describe any specific environment or development tool, it is assumed you already know in detail the environment you want to work with.

Integrating the HAL

This section covers the scenario where you want to use the ChibiOS/HAL framework into an existing application. In order to accomplish this you need to import in your project two components:

  • The portable HAL.
  • The HAL port layer for your MCU.
  • The OSAL layer for your RTOS.

You need also to consider the port-specific requirements, random startup files and linker files are likely not going to work. It is advised to use the provided support files before trying to use alternatives.

Portable HAL

You need to add the following files to your build process:

  • ./os/hal/src/*.c

Also add to the search paths for headers the HAL portable headers located in:

  • ./os/hal/include
HAL Port Layer

Port layers can differ from each other but the general layout is similar. The provided example paths are taken from the STM32 port, You need to include the source code from:

  • ./os/hal/ports/<family>/<subfamily>/*.c
  • ./os/hal/ports/<family>/LLD/<peripheral>/*.c

The directory containing pertinent headers are:

  • ./os/hal/ports/<family>/<subfamily>
  • ./os/hal/ports/<family>/LLD/<peripheral>
OSAL Layer

HAL interacts with the (optional) underlying RTOS using an abstraction layer called OSAL. You need to include in your project the OSAL for your RTOS or an OSAL for bare metal (without RTOS).

There are several OSALs provided in ChibiOS, include in your project one of the following:

  • ./os/hal/osal/rt
  • ./os/hal/osal/nil
  • ./os/hal/osal/os-less/<architecture>

Other Files

The HAL framework requires a configuration file, it is usually placed under the project root directory but it can be placed in any directory reachable by the compiler. The file is named halconf.h and a template can be taken from:

  • ./os/hal/templates/halconf.h

Do not use the file directly, copy it in your project and edit the copy.

Another platform-dependent configuration file named mcuconf.h is required. This file greatly changes from micro to micro, take this one from one of the demos for the MCU you need to use. Demos are located under:

  • ./demos/<family>


If in doubt remember that the provided makefiles are the ultimate guide for the integrator, all required the paths and options are necessarily present there. It is a good idea to look at the Makefile present in all demos if some detail is not clear. By compiling the demo all compiler options are printed on the console, that should remove any doubt about the required paths, files and options.

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