PX4 Guide (main)
PX4
QGroundControl
MAVSDK
MAVLINK
QGroundControl Guide
Dronecode Camera Manager
Support
main
v1.17 (stable)
v1.16
v1.15
v1.14
v1.13
v1.12

English

中文 (Chinese)
한국어 (Korean)
Мови (Ukrainian)

English

中文 (Chinese)
한국어 (Korean)
Мови (Ukrainian)

Appearance

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 ​

Board startup and configuration files are located under /boards in each board's vendor-specific directory (i.e. boards/VENDOR/MODEL/).

For example, for FMUv5:

  • (All) Board-specific files: /boards/px4/fmu-v5.
  • Build configuration: /boards/px4/fmu-v5/default.px4board.
  • Board-specific initialisation file: /boards/px4/fmu-v5/init/rc.board_defaults
    • A board-specific initialisation file is automatically included in startup scripts if found under the boards directory at init/rc.board.
    • The file is used to start sensors (and other things) that only exist on a particular board. It may also be used to set a board's default parameters, UART mappings, and any other special cases.
    • For FMUv5 you can see all the Pixhawk 4 sensors being started, and it also sets a larger LOGGER_BUF.

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.

NuttX ​

See NuttX Board Porting Guide.

Linux ​

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/boards. TODO: ADD BUS 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.

Getting Your Board Supported ​

This page covers the technical work of porting PX4 to new hardware. The process for getting that port reviewed, merged, and listed on the PX4 website, including board IDs, USB VID/PID, flight-test evidence, and maintenance expectations, is documented separately:

In short: build your own firmware target based on PX4, demonstrate stable flight on the current release, and open a pull request with your board support code, documentation, and flight logs. The board support guide explains each step.

The PX4 project supports and maintains the FMU standard reference hardware and any boards compatible with the standard, including the Pixhawk series (see the full list of supported hardware). Boards merged into PX4 benefit from a port in the repository, firmware builds accessible from QGroundControl, compatibility with the rest of the ecosystem, and automated CI checks.

TIP

The cost of maintaining a port is proportional to how far it diverges from the standard. Consider that cost before deviating: staying close to the reference design lets you benefit from day-to-day PX4 development with minimal maintenance burden.

Manufacturers are responsible for keeping their port up to date and working across PX4 releases. The PX4 project reserves the right to refuse or remove ports that do not meet the project's requirements, and all contributors are expected to follow the Code of Conduct.