docs(peripherals): add On-Screen Display (OSD) page (#27134)

2026-05-21 21:55:34 +08:00 · 2026-04-22 17:50:09 -08:00
parent fdd00fbd31
commit c459caaa2a
6 changed files with 110 additions and 4 deletions
@@ -372,6 +372,7 @@
      - [Servo Gripper](peripherals/gripper_servo.md)
  - [Peripherals](peripherals/index.md)
    - [ADSB/FLARM/UTM (Traffic Avoidance)](peripherals/adsb_flarm.md)
+    - [On-Screen Display (OSD)](peripherals/osd.md)
    - [Parachute](peripherals/parachute.md)
    - [Remote ID](peripherals/remote_id.md)
  - [I2C Peripherals](sensor_bus/i2c_general.md)
@@ -371,6 +371,7 @@
      - [Servo Gripper](/peripherals/gripper_servo.md)
  - [Peripherals](/peripherals/index.md)
    - [ADSB/FLARM/UTM (Traffic Avoidance)](/peripherals/adsb_flarm.md)
+    - [On-Screen Display (OSD)](/peripherals/osd.md)
    - [Parachute](/peripherals/parachute.md)
    - [Remote ID](/peripherals/remote_id.md)
  - [I2C Peripherals](/sensor_bus/i2c_general.md)
@@ -13,7 +13,7 @@ The available profiles (in source-code declaration order) are:
 - _Gimbal_ (`MAVLINK_MODE_GIMBAL`): Messages for a gimbal. Note this also enables message forwarding.
 - _External Vision_ (`MAVLINK_MODE_EXTVISION`): Messages for offboard vision systems.
 - _External Vision Minimal_ (`MAVLINK_MODE_EXTVISIONMIN`): Messages for offboard vision systems on slower links.
- _OSD_ (`MAVLINK_MODE_OSD`): Set of messages for an OSD system.
+- _OSD_ (`MAVLINK_MODE_OSD`): Set of messages for an [On-Screen Display (OSD)](../peripherals/osd.md#mavlink-osd) system.
 - _Magic_ (`MAVLINK_MODE_MAGIC`): No messages streamed by default. Used when configuring streaming dynamically via MAVLink.
 - _Custom_ (`MAVLINK_MODE_CUSTOM`): Same as `MAVLINK_MODE_MAGIC`.
 - _Config_ (`MAVLINK_MODE_CONFIG`): Set of messages for configuration interface, sent at higher rates. This is used, for example, to send the `MAVLINK_MODE_NORMAL` message set via USB to a GCS.
@@ -29,7 +29,7 @@ The profile defines the _default_ messages and rates.
 A connected MAVLink system can still request the streams/rates it wants using [MAV_CMD_SET_MESSAGE_INTERVAL](https://mavlink.io/en/messages/common.html#MAV_CMD_SET_MESSAGE_INTERVAL).
 :::

-To find the exact messages in each profile, search for ` configure_streams_to_default` (or the above profile names) in [mavlink_main.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_main.cpp).
+To find the exact messages in each profile, search for `configure_streams_to_default` (or the above profile names) in [mavlink_main.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_main.cpp).

 ## Assigning Profiles to Ports

@@ -2,8 +2,9 @@

 This section contains topics about peripheral hardware that can be connected to a flight controller (not including [cameras and other payloads](../payloads/index.md)).

-The peripherals are not _required_ for flight, but may support it by providing improved safety, or allowing the vehicle to meet regulartory requirements:
+The peripherals are not _required_ for flight, but may support it by providing improved safety, or allowing the vehicle to meet regulatory requirements:

 - [ADSB/FLARM/UTM (Traffic Avoidance)](../peripherals/adsb_flarm.md)
+- [On-Screen Display (OSD)](../peripherals/osd.md)
 - [Parachute](../peripherals/parachute.md)
 - [Remote ID](../peripherals/remote_id.md)
@@ -1,6 +1,6 @@
 # MAVLink Peripherals (GCS/OSD/Gimbal/Camera/Companion)

-Ground Control Stations (GCS), On-Screen Displays (OSD), MAVLink Cameras & Gimbals, Remote IDs, Companion Computers, ADS-B receivers, and other MAVLink peripherals interact with PX4 using separate MAVLink streams, sent via different serial ports.
+Ground Control Stations (GCS), [MAVLink On-Screen Displays (OSD)](../peripherals/osd.md#mavlink-osd), MAVLink [Cameras](../camera/mavlink_v2_camera.md) and [Gimbals](../advanced/gimbal_control.md), [Remote IDs](../peripherals/remote_id.md), Companion Computers, [ADS-B receivers](../peripherals/adsb_flarm.md), and other MAVLink peripherals interact with PX4 using separate MAVLink streams, sent via different serial ports.

 In order to configure that a particular serial port is used for MAVLink traffic with a particular peripheral, we use [Serial Port Configuration](../peripherals/serial_configuration.md), assigning one of the abstract "MAVLink instance" configuration parameters to the desired port.
 We then set other properties of the MAVLink channel using the parameters associated with our selected MAVLink instance, so that they match the requirements of our particular peripheral.
@@ -0,0 +1,103 @@
+# On-Screen Display (OSD)
+
+An **On-Screen Display (OSD)** overlays flight telemetry — battery, altitude, GPS, RSSI, attitude, etc. — onto a pilot's video feed.
+OSDs are commonly used in FPV and long-range flying so the pilot can see live flight data without looking away from the video.
+
+PX4 supports three distinct OSD mechanisms, each targeting a different class of video system:
+
+| Mechanism                               | Use case                                                                                                                        | Transport            | Runs on FC?                                                    |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------- |
+| [MSP OSD](#msp-osd)                     | Digital FPV air units and video goggles that speak Betaflight MSP (e.g. DJI O3/O4, Walksnail, HDZero, Caddx Vista)              | Serial, MSPv1        | Yes — [`msp_osd`](../modules/modules_driver.md#msp-osd) driver |
+| [ATXXXX Analog OSD](#atxxxx-analog-osd) | Legacy analog video with an on-board MAX7456/ATXXXX overlay chip (e.g. OmnibusF4SD)                                             | SPI to on-board chip | Yes — [`atxxxx`](../modules/modules_driver.md#atxxxx) driver   |
+| [MAVLink OSD](#mavlink-osd)             | MAVLink-aware ground stations and displays that render their own OSD from telemetry (e.g. Yaapu on EdgeTX/OpenTX, Skydroid, mLRS HUDs) | Serial, MAVLink      | No — streams MAVLink; the display renders the OSD              |
+
+Which one you use is determined by your video hardware, not by PX4 preference.
+If you're unsure, start with your video system's documentation and match the OSD mechanism it expects.
+
+## MSP OSD
+
+**MSP (MultiWii Serial Protocol) OSD** is the mechanism used by digital FPV systems (DJI, Walksnail, HDZero) and by many digital goggles/air units to render telemetry over the pilot's video feed.
+PX4 implements the subset of MSP used for OSD telemetry, matching what Betaflight and INAV send.
+
+The [`msp_osd`](../modules/modules_driver.md#msp-osd) driver converts uORB topics (battery, GPS, attitude, etc.) to MSP packets and sends them out a serial port at 115200 baud.
+
+### Supported displays
+
+PX4 currently sends a subset of MSP messages.
+Reliably-working display items include:
+
+- Craft name and flight mode / arming state
+- Battery voltage, current draw, mAh consumed, average cell voltage
+- GPS latitude, longitude, satellite count, ground speed
+- Home distance and direction
+- Altitude (from GNSS / baro)
+- RSSI
+- Crosshairs toggle
+
+Some items in [`OSD_SYMBOLS`](../advanced_config/parameter_reference.md#OSD_SYMBOLS) are reserved but not yet implemented — see the parameter's `(unused)` bit labels.
+For feature-completeness work, see the tracking issues on GitHub.
+
+### Hardware setup
+
+1. Connect the digital air unit's MSP / telemetry input to a free UART on the flight controller (TX → RX, RX → TX, GND → GND).
+2. Power the air unit from its own BEC or a VTX power pad — most air units expect 5 V or battery voltage, not autopilot 5 V.
+3. Note which PX4 serial device the UART maps to on your board (e.g. `TELEM2` → `/dev/ttyS2`).
+   See [Serial Port Mapping](../hardware/serial_port_mapping.md).
+
+### Firmware requirements
+
+The `msp_osd` driver is included in the default build for most modern Pixhawk and FPV-oriented boards (e.g. `px4_fmu-v5x`, `px4_fmu-v6x`, `ark_fpv`, `cuav_7-nano`, `micoair_h743*`).
+If your board does not include it by default, enable it via [board config](../hardware/porting_guide_config.md#px4-menuconfig-setup):
+
+```sh
+make <board>_default boardconfig
+# drivers → OSD → msp_osd
+```
+
+Then rebuild and flash.
+
+### PX4 configuration
+
+1. Assign the selected serial port to MSP OSD with [`MSP_OSD_CONFIG`](../advanced_config/parameter_reference.md#MSP_OSD_CONFIG).
+2. Set the matching `SER_<PORT>_BAUD` to `115200`.
+3. Reboot.
+4. Tune the display via the [`OSD_*` parameters](../advanced_config/parameter_reference.md#osd):
+   - [`OSD_SYMBOLS`](../advanced_config/parameter_reference.md#OSD_SYMBOLS) — bitmask selecting which items appear.
+   - [`OSD_CH_HEIGHT`](../advanced_config/parameter_reference.md#OSD_CH_HEIGHT) — vertical position of the crosshairs.
+   - [`OSD_LOG_LEVEL`](../advanced_config/parameter_reference.md#OSD_LOG_LEVEL) — minimum severity for on-screen warnings.
+   - [`OSD_SCROLL_RATE`](../advanced_config/parameter_reference.md#OSD_SCROLL_RATE) / [`OSD_DWELL_TIME`](../advanced_config/parameter_reference.md#OSD_DWELL_TIME) — scrolling of long messages.
+   - [`OSD_RC_STICK`](../advanced_config/parameter_reference.md#OSD_RC_STICK) — forward RC sticks to the VTX when disarmed, so you can navigate the VTX menu.
+
+### Worked examples
+
+- [Reptile Dragon 2 > msp_osd Module](../frames_plane/reptile_dragon_2.md#msp-osd-module) — end-to-end wiring and configuration for a Caddx Vista build.
+- [Turbo Timber Evolution](../frames_plane/turbo_timber_evolution.md) — references the same setup pattern.
+
+## MAVLink OSD
+
+Some OSDs render their own overlay directly from the MAVLink telemetry stream — the flight controller simply streams MAVLink at a rate the display can parse.
+PX4 exposes this via a dedicated MAVLink stream profile.
+
+To use a MAVLink OSD:
+
+1. Choose an unused MAVLink instance ([`MAV_X_CONFIG`](../peripherals/mavlink_peripherals.md#default_ports)) and assign it to the serial port connected to the display.
+2. Configure the mode of the selected MAVLink instance with [`MAV_X_MODE`](./mavlink_peripherals.md#MAV_X_MODE) by setting it to **`OSD`**.
+   The `OSD` mode uses a built-in rate table tuned for low-bandwidth OSD consumption.
+3. Set the matching `SER_<PORT>_BAUD` to the baud rate the display expects.
+
+The stream content is fixed (defined in `src/modules/mavlink/mavlink_main.cpp`) and cannot be customised from parameters.
+See [MAVLink Peripherals (GCS/OSD/Gimbal/Camera/Companion)](./mavlink_peripherals.md) for the full MAVLink-side configuration.
+
+## ATXXXX Analog OSD
+
+The [`atxxxx`](../modules/modules_driver.md#atxxxx) driver targets boards with an on-board MAX7456 / ATXXXX chip that overlays characters onto an analog video stream (PAL or NTSC).
+This was common on older F4-class FCs such as OmnibusF4SD and is largely superseded by digital systems.
+
+No external wiring is required on boards that include the chip; to enable it, set [`OSD_ATXXXX_CFG`](../advanced_config/parameter_reference.md#OSD_ATXXXX_CFG) to `1` (NTSC) or `2` (PAL) and reboot.
+
+## See also
+
+- [Parameter Reference > OSD](../advanced_config/parameter_reference.md#osd) — all OSD parameters.
+- [MAVLink Peripherals (GCS/OSD/Gimbal/Camera/Companion)](./mavlink_peripherals.md) — MAVLink serial configuration.
+- [Serial Port Configuration](./serial_configuration.md) — assigning modules to UARTs.
+- [`msp_osd` module reference](../modules/modules_driver.md#msp-osd) — CLI usage and source.