External modules provide a convenient mechanism for developers to manage/group proprietary modules that they want add to (or update in) PX4 firmware. External modules can use the same includes as internal modules and can interact with internal modules via uORB.
This topic explains how to add an external ("out of tree") module to the PX4 build.
We encourage you to contribute your changes into PX4, where possible!
To create an external module:
- Create an external directory directory for grouping the external modules:
- This can be located anywhere outside of the Firmware tree.
- It must have the same structure as Firmware (i.e. it must contain a directory called src).
- Later we refer to this directory using
- Copy an existing module (e.g. examples/px4_simple_app) to the external directory, or directly create a new module.
- Rename the module (including
MODULEin CMakeLists.txt) or remove it from the existing Firmware cmake build config. This is to avoid conflicts with internal modules.
- Add a file CMakeLists.txt in the external directory with content:
set(config_module_list_external modules/<new_module> PARENT_SCOPE )
Add a line
px4_add_module(), for example like this:
px4_add_module( MODULE modules__test_app MAIN test_app STACK_MAIN 2000 SRCS px4_simple_app.c DEPENDS platforms__common EXTERNAL )
uORB messages can also be defined out-of-tree. For this, the
$EXTERNAL_MODULES_LOCATION/msg folder must exist.
- Place all new message definitions within the
$EXTERNAL_MODULES_LOCATION/msgdirectory. The format of these new out-of-tree message definitions are the same as for any other uORB message definition.
Add a file
set(config_msg_list_external <message1>.msg <message2>.msg <message3>.msg PARENT_SCOPE )
<message#>.msgis the name of the uORB message definition file to be processed and used for uORB message generation.
The out-of-tree uORB messages will be generated in the same locations as the normal uORB messages.
The uORB topic headers are generated in
<build_dir>/uORB/topics/, and the message source files are
The new uORB messages can be used like any other uORB message as described here.
The out-of-tree uORB message definitions cannot have the same name as any of the normal uORB messages.
make posix EXTERNAL_MODULES_LOCATION=<path>.
Any other build target can be used, but the build directory must not yet exist. If it already exists, you can also just set the cmake variable in the build folder.
For subsequent incremental builds
EXTERNAL_MODULES_LOCATION does not need to be specified.