Files
PX4-Autopilot/docs/en/hardware/serial_port_mapping.md
T
Hamish Willee 272f3280d7 docs(boards): restructure Pixhawk 4 page to the board template (#29590)
* docs(boards): restructure Pixhawk 4 page to the board page template

Move the existing content into the flight-controller page template's
sections, headings and anchors, with no change to what the page says,
so that the content additions that follow can be reviewed on their own.

The Quick Summary list becomes Specifications sub-sections, the
connector image moves into Pinouts and the dimensions image into
Mechanical Data, Voltage Ratings moves before Serial Port Mapping,
and Further info becomes Further Information. Port labels are in code
style, and units follow the docs style guide. Links to the changed
anchors are updated.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Hamish Willee <hamishwillee@gmail.com>

* docs(boards): add Pixhawk 4 PWM outputs, power and setup sections

Fill in the sections the board page template expects, from the board
source (boards/px4/fmu-v5) and Holybro's datasheet, pinouts and
product page.

- Mark the board discontinued by Holybro but still supported by PX4,
  with matching SUMMARY, sidebar and category entries
- Specifications: current IO processor, sensor buses, USB, parameter
  storage, SD card, max input voltage and current sensing, and the
  datasheet weight
- PWM Outputs: IO and FMU outputs, no DShot, timer groups, and the
  capture inputs on CAP & ADC IN
- Power, SD Card, Radio Control, GPS & Compass, Telemetry and CAN
- Serial Port Mapping: USART1, flow control column, printed port
  labels, and the same table on the serial port mapping page
- Debug Port: Pixhawk Debug Mini, and the console UART

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Hamish Willee <hamishwillee@gmail.com>

* docs(boards): fix Pixhawk 4 specs, links and wording from review

Take the weight and operating temperature from Holybro's latest
datasheet, and link that datasheet in place of the older in-repo copy,
which contradicted the page.

Give the serial and I2C interface lines in the board page template's
form, where the board source and Holybro's pinout agree, and add the
template content the page was missing: the servo rail note, capture
pins as outputs, DSM/S.BUS receiver power pins, the internal compass,
and how to enable a second GPS (GPS_2_CONFIG has no default).

Also fix the wiring quick start's link text for the renamed Pinouts
heading, and make S.BUS spelling and port labels consistent.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Hamish Willee <hamishwillee@gmail.com>

* docs(boards): apply Holybro corrections and discontinued markers to Pixhawk 4

Holybro confirmed the board is discontinued and corrected the weight,
operating temperature, input voltage limits, RC port routing and DShot
support. The discontinued markers follow the earlier discontinued board
pages, and the Pixhawk Standard list now separates discontinued boards.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Hamish Willee <hamishwillee@gmail.com>

---------

Signed-off-by: Hamish Willee <hamishwillee@gmail.com>
2026-11-05 08:45:43 +11:00

5.3 KiB

Serial Port Mapping

This topic shows how to determine the mapping between USART/UART serial port device names (e.g. "ttyS0") and the associated ports on a flight controller, such as TELEM1, TELEM2, GPS1, RC SBUS, Debug console.

The instructions are used to generate serial port mapping tables in flight controller documentation. For example: Pixhawk 4 > Serial Port Mapping.

::: info The function assigned to each port does not have to match the name (in most cases), and is set using a Serial Port Configuration. Usually the port function is configured to match the name, which is why the port labelled GPS1 will work with a GPS out of the box. :::

NuttX on STMxxyyy

This section shows how to get the mappings for NuttX builds on STMxxyyy architectures by inspecting the board configuration files. The instructions use FMUv5, but can similarly be extended for other FMU versions/NuttX boards.

default.px4board

The default.px4board lists a number of serial port mappings (search for the text "SERIAL_PORTS").

From /boards/px4/fmu-v5/default.px4board:

CONFIG_BOARD_SERIAL_GPS1="/dev/ttyS0"
CONFIG_BOARD_SERIAL_TEL1="/dev/ttyS1"
CONFIG_BOARD_SERIAL_TEL2="/dev/ttyS2"
CONFIG_BOARD_SERIAL_TEL4="/dev/ttyS3"

Alternatively you can launch boardconfig using make px4_fmu-v5 boardconfig and access the serial port menu

    Serial ports  --->
        (/dev/ttyS0) GPS1 tty port
        ()  GPS2 tty port
        ()  GPS3 tty port
        ()  GPS4 tty port
        ()  GPS5 tty port
        (/dev/ttyS1) TEL1 tty port
        (/dev/ttyS2) TEL2 tty port
        ()  TEL3 tty port
        (/dev/ttyS3) TEL4 tty port
        ()  TEL5 tty port

nsh/defconfig

The nsh/defconfig allows you to determine which ports are defined, whether they are UART or USARTs, and the mapping between USART/UART and device. You can also determine which port is used for the serial/debug console.

Open the board's defconfig file, for example: /boards/px4/fmu-v5/nuttx-config/nsh/defconfig

Search for the text "ART" until you find a section like with entries formatted like CONFIG_STM32xx_USARTn=y (where xx is a processor type and n is a port number). For example:

CONFIG_STM32F7_UART4=y
CONFIG_STM32F7_UART7=y
CONFIG_STM32F7_UART8=y
CONFIG_STM32F7_USART1=y
CONFIG_STM32F7_USART2=y
CONFIG_STM32F7_USART3=y
CONFIG_STM32F7_USART6=y

The entries tell you which ports are defined, and whether they are UART or USART.

Copy the section above and reorder numerically by "n". Increment the device number ttySn alongside (zero based) to get the device-to-serial-port mapping.

ttyS0 CONFIG_STM32F7_USART1=y
ttyS1 CONFIG_STM32F7_USART2=y
ttyS2 CONFIG_STM32F7_USART3=y
ttyS3 CONFIG_STM32F7_UART4=y
ttyS4 CONFIG_STM32F7_USART6=y
ttyS5 CONFIG_STM32F7_UART7=y
ttyS6 CONFIG_STM32F7_UART8=y

To get the DEBUG console mapping we search the defconfig file for SERIAL_CONSOLE. Below we see that the console is on UART7:

CONFIG_UART7_SERIAL_CONSOLE=y

board_config.h

For flight controllers that have an IO board, determine the PX4IO connection from board_config.h by searching for PX4IO_SERIAL_DEVICE.

For example, /boards/px4/fmu-v5/src/board_config.h:

#define PX4IO_SERIAL_DEVICE            "/dev/ttyS6"
#define PX4IO_SERIAL_TX_GPIO           GPIO_UART8_TX
#define PX4IO_SERIAL_RX_GPIO           GPIO_UART8_RX
#define PX4IO_SERIAL_BASE              STM32_UART8_BASE

So the PX4IO is on ttyS6 (we can also see that this maps to UART8, which we already knew from the preceding section).

Putting it all together

The final mapping is:

ttyS0 CONFIG_STM32F7_USART1=y GPS1
ttyS1 CONFIG_STM32F7_USART2=y TEL1
ttyS2 CONFIG_STM32F7_USART3=y TEL2
ttyS3 CONFIG_STM32F7_UART4=y TEL4
ttyS4 CONFIG_STM32F7_USART6=y
ttyS5 CONFIG_STM32F7_UART7=y DEBUG
ttyS6 CONFIG_STM32F7_UART8=y PX4IO

In the flight controller docs the resulting table is:

UART Device Port Flow Control
USART1 /dev/ttyS0 GPS MODULE (GPS1)
USART2 /dev/ttyS1 TELEM1 Yes
USART3 /dev/ttyS2 TELEM2 Yes
UART4 /dev/ttyS3 UART & I2C B (TELEM4)
USART6 /dev/ttyS4 RC SBUS
UART7 /dev/ttyS5 FMU Debug (Console)
UART8 /dev/ttyS6 PX4IO

Other Architectures

::: info Contributions welcome! :::

See Also