# Serial Port Configuration
PX4 defines default functions for many flight controller ports, which is why you can plug a GPS module into the port labelled
GPS 1, an RC receiver into
RC IN, or a telemetry module into
TELEM 1, and generally they will just work.
The functions assigned to ports are fully configurable using appropriate parameters (in most cases). You can assign any unused port to any function, or reassign a port to use it for something else.
The configuration makes it easy to (for example):
- Run MAVLink on a different port, change the streamed messages, or switch a TELEM port to use ROS 2/XRCE-DDS.
- Change the baud rate on a port or set the UDP port
- Setup dual GPS.
- Enable sensors that run on a serial port, such as some distance sensors.
- Some ports cannot be configured because they are used for a very specific purpose such as the system console.
- The mapping of specific devices to port names on the flight controller is explained in Serial Port Mapping.
# Configuration Parameters
The serial port configuration parameters allow you to assign a particular function or support for particular hardware to a particular port.
These parameters follow the naming pattern
QGroundControl only displays the parameters for services/drivers that are present in firmware.
At time of writing the current set is:
- GPS configuration: GPS_1_CONFIG, GPS_2_CONFIG
- Iridium Satellite radio: ISBD_CONFIG
- MAVLink Ports: MAV_0_CONFIG, MAV_1_CONFIG, MAV_2_CONFIG
- Modal IO ESC: MODAL_IO_CONFIG
- MSP OSD: MSP_OSD_CONFIG
- RC Port: RC_PORT_CONFIG
- FrSky Telemetry: TEL_FRSKY_CONFIG
- HoTT Telemetry: TEL_HOTT_CONFIG
- uXRCE-DDS port: UXRCE_DDS_CFG,
- Sensors (optical flow, distance sensors): SENS_CM8JL65_CFG, SENS_LEDDAR1_CFG, SENS_SF0X_CFG, SENS_TFLOW_CFG, SENS_TFMINI_CFG, SENS_ULAND_CFG, SENS_VN_CFG,
- CRSF RC Input Driver: RC_CRSF_PRT_CFG
- Sagetech MXS: MXS_SER_CFG
- Ultrawideband position sensor: UWB_PORT_CFG
- DShot driver: DSHOT_TEL_CFG
Some functions/features may define additional configuration parameters, which will follow a similar naming pattern to the port configuration prefix.
MAV_0_CONFIG enables MAVLink on a particular port, but you may also need to set MAV_0_FLOW_CTRL, MAV_0_FORWARD, MAV_0_MODE and so on.
# How to Configure a Port
All the serial drivers/ports are configured in the same way:
- Set the configuration parameter for the service/peripheral to the port it will use.
- Reboot the vehicle in order to make the additional configuration parameters visible.
- Set the baud rate parameter for the selected port to the desired value.
- Configure module-specific parameters (i.e. MAVLink streams and data rate configuration).
The GPS/Compass > Secondary GPS section provides a practical example of how to configure a port in QGroundControl (it shows how to use
GPS_2_CONFIG to run a secondary GPS on the
TELEM 2 port).
Similarly PX4 Ethernet Setup > PX4 MAVLink Serial Port Configuration explains the setup for Ethernet serial ports, and MAVLink Peripherals (OSD/GCS/Companion Computers/etc.) explains the configuration for MAVLink serial ports.
# Deconflicting Ports
Port conflicts are handled by system startup, which ensures that at most one service is run on a specific port. For example, it is not possible to start a MAVLink instance on a specific serial device, and then launch a driver that uses the same serial device.
At time of writing there is no user feedback about conflicting ports.
# Default Serial Port Configuration
These port mappings can be disabled by setting the associated configuration parameter to Disabled.
The following ports are commonly mapped to specific functions on all boards:
GPS 1is configured as a GPS port (using GPS_1_CONFIG).
This maps the gps driver to the port with a baud rate of Auto (with this setting a GPS will automatically detect the baudrate - except for the Trimble MB-Two, which requires 115200 baud rate).
RC INis configured as an RC input (using RC_PORT_CONFIG).
TELEM 1is configured as a MAVLink serial port suitable for connection to a GCS via a telemetry module.
The configuration uses MAV_0_CONFIG to set the port, MAV_0_RATE to set the baud rate to 57600, and MAV_0_MODE to set the messages streamed to "Normal". For more information see: MAVLink Peripherals (OSD/GCS/Companion Computers/etc.).
TELEM 2is configured by default as a MAVLink serial port suitable for connection to an Onboard/Companion computer via a wired connection.
The configuration uses MAV_1_CONFIG to set the port, MAV_1_RATE to set the baud rate, and MAV_1_MODE to set the messages streamed to "Onboard". For more information see: MAVLink Peripherals (OSD/GCS/Companion Computers/etc.).
Ethernetis mapped as a MAVLink port on Pixhawk devices that have an Ethernet port.
The configuration uses MAV_2_CONFIG and appropriate settings for the UDP port etc. For more information see PX4 Ethernet Setup > PX4 MAVLink Serial Port Configuration and MAVLink Peripherals (OSD/GCS/Companion Computers/etc.).
Other ports generally have no assigned functions by default (are disabled).
# Configuration Parameter Missing from QGroundControl
QGroundControl only displays the parameters for services/drivers that are present in firmware. If a parameter is missing, then you may need to add it in firmware.
PX4 firmware includes most drivers by default on Pixhawk-series boards. Flash-limited boards may comment out/omit the driver (at time of writing this only affects boards based on FMUv2).
You can include the missing driver in firmware by enabling the driver in the default.px4board config file that corresponds to the board (opens new window) you want to build for. For example, to enable the SRF02 driver, you would a the following line to the px4board.
An easier method would be using boardconfig which launches a GUI where you can easily search, disable and enable modules. To launch boardconfig type:
make <vendor>_<board>_<label> boardconfig
You will then need to build the firmware for your platform, as described in Building PX4 Software.