External Modules (Out-of-Tree)

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.

:::tip We encourage you to contribute your changes into PX4, where possible! :::

Usage

To create an external module:

• Create an external directory folder for grouping the external modules:
  • This can be located anywhere outside of the PX4-Autopilot tree.
  • It must have the same structure as PX4-Autopilot (i.e. it must contain a directory called src).
  • Later we refer to this directory using EXTERNAL_MODULES_LOCATION.
• Copy an existing module (e.g. examples/px4_simple_app) to the external directory, or directly create a new module.
• Rename the module (including MODULE in CMakeLists.txt) or remove it from the existing PX4-Autopilot 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 EXTERNAL to the modules/<new_module>/CMakeLists.txt within 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
  	)
  

Out-of-Tree uORB Message Definitions

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/msg directory. The format of these new out-of-tree message definitions are the same as for any other uORB message definition.

• Add a file $EXTERNAL_MODULES_LOCATION/msg/CMakeLists.txt with content:

  set(config_msg_list_external
      <message1>.msg
      <message2>.msg
      <message3>.msg
      PARENT_SCOPE
      )
  

  where <message#>.msg is 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 generated in <build_dir>/msg/topics_sources/.

The new uORB messages can be used like any other uORB message as described here.

:::warning The out-of-tree uORB message definitions cannot have the same name as any of the normal uORB messages. :::

Building External Modules and uORB Messages

Execute make px4_sitl 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.