Flight Controller Porting Guide

This topic is for developers who want to port PX4 to work with new flight controller hardware.

PX4 Architecture

PX4 consists of two main layers: The board support and middleware layer on top of the host OS (NuttX, Linux or any other POSIX platform like Mac OS), and the applications (Flight Stack in src/modules). Please reference the PX4 Architectural Overview for more information.

This guide is focused only on the host OS and middleware as the applications/flight stack will run on any board target.

Flight Controller Configuration File Layout

In addition to the host operating system specific configuration files described below, there are several groups of configuration files for each board located throughout the code base:

Host Operating System Configuration

This section describes the purpose and location of the configuration files required for each supported host operating system to port them to new flight controller hardware.


In order to port PX4 on NuttX to a new hardware target, that hardware target must be supported by NuttX. The NuttX project maintains an excellent porting guide for porting NuttX to a new computing platform.

For all NuttX based flight controllers (e.g. the Pixhawk series) the OS is loaded as part of the application build.

The configuration files for NuttX based boards, including linker scripts and other required settings are located under platforms/nuttx/nuttx-configs.

The following example uses FMUv5 as it is a recent reference configuration for NuttX based flight controllers:

The function of each of these files, and perhaps more, will need to be duplicated for a new flight controller board.

NuttX Menuconfig

If you need to modify the NuttX OS configuration, you can do this via menuconfig using the PX4 shortcuts:

make px4fmu-v5_default menuconfig
make px4fmu-v5_default qconfig

For fresh installs of PX4 onto Ubuntu using ubuntu_sim_nuttx.sh you will also need to install kconfig tools from NuttX tools.

The following steps are not required if using the px4-dev-nuttx docker container or have installed to macOS using our normal instructions (as these includekconfig-mconf).

Run the following commands from any directory:

git clone https://bitbucket.org/nuttx/tools.git
cd tools/kconfig-frontends
sudo apt install gperf
./configure --enable-mconf --disable-nconf --disable-gconf --enable-qconf --prefix=/usr
sudo make install

The --prefix=/usr is essential as it determines the specific installation location where PX4 is hardcoded to look for kconfig-tools. The --enable-mconf and --enable-qconf options will enable the menuconfig and qconfig options respectively.

To run qconfig you may need to install additional Qt dependencies.


Linux boards do not include the OS and kernel configuration. These are already provided by the Linux image available for the board (which needs to support the inertial sensors out of the box).

Middleware Components and Configuration

This section describes the various middleware components, and the configuration file updates needed to port them to new flight controller hardware.

QuRT / Hexagon

  • The start script is located in posix-configs/.
  • The OS configuration is part of the default Linux image (TODO: Provide location of LINUX IMAGE and flash instructions).
  • The PX4 middleware configuration is located in src/drivers/boards. TODO: ADD BUS CONFIG
  • Drivers: DriverFramework.
  • Reference config: Running make eagle_default builds the Snapdragon Flight reference config.

RC UART Wiring Recommendations

It is generally recommended to connect RC via separate RX and TX pins to the microcontroller. If however RX and TX are connected together, the UART has to be put into singlewire mode to prevent any contention. This is done via board config and manifest files. One example is px4fmu-v5.

results matching ""

    No results matching ""