Modules in RIOT are well-defined units of code that provide a set of features to your application. This includes also drivers and to a certain extent ports for CPUs and boards (with some exceptions, see the porting guide for further information).
Like applications, modules are directories containing source files and a Makefile. Additionally their API can be defined in one or more header files, residing in the include path of their super-module.
E.g. the Shell module is implemented in
sys/shell and defines its API in
sys/include/shell.h and the ISL29020 light sensor driver is implemented in
drivers/isl29020 and defines its API in
A module's Makefile just needs to include
Makefile.base in the RIOT repository:
If your module's name differs from the name of the directory it resides in you need to set the
MODULE macro in addition.
When compiled a module always provides a
MODULE_<MODULENAME> macro to the system. This way, other modules can check if the module is available in the current configuration or not.
Modules can be used by adding their name to the
USEMODULE macro of your application's Makefile.
MODULE name should be unique or build breaks as modules overwrite the same output file. This might for example lead to
undefined reference to errors in the linker which can be hard to track down.
This problem happened in the past for:
Note: even if all boards and cpus implement the
cpu modules, only one is used in an application so there is no conflict.
Your module may depend on other modules to minimize code duplication. These dependencies are defined in
Makefile.dep with the following syntax:
Makefile.dep is processed only once so you have to take care to add the dependency block for your module before your dependencies pull in their dependencies.
Modules can be defined outside
RIOTBASE. In addition to add it to
USEMODULE the user needs to add the module path to
The external module can optionally define the following files:
Makefile.includefile to set global build configuration like
CFLAGSor add API headers include paths to the
Makefile.depfile to set module dependencies
An example can be found in
Pseudomodules are modules that do not have any code. Their main use cases are to provide base information for dependencies to other modules or information to the code base via the
MODULE_<MODULENAME> macro. Pseudomodules can provide header files too, if need be. To create a pseudomodule just add its name to the
PSEUDOMODULES macro in