voxl-osd

Renders the on-screen telemetry overlay for FPV video as MSP DisplayPort text, sent to voxl-vtx or an HDZero VTX.

Table of contents

1. Overview
2. Data Flow
3. voxl-configure-osd
4. Configuration File
   1. Input and Output
   2. Display Toggles
   3. Element Positions
   4. Menu and Flight Mode Fields
5. OSD Menu
6. External Flight Controller (MSP)
7. HDZero Output
8. Debugging
9. Source Code

Overview

voxl-osd draws the on-screen display (OSD) for FPV video: battery, RC link, flight mode, arm state, position, heading, VIO state, VTX temperature and power, and warnings. It does not touch video pixels. It lays out a character-cell text canvas and streams it as MSP DisplayPort commands, which the video transmitter composites over the live video. On ModalAI FPV products the consumer is voxl-vtx; the same canvas can also be sent over UART to a third-party HDZero VTX.

Since voxl-osd 1.0.0 the service also sends structured MSP messages on the same output: MSP_VOXL_TELEM (190, flight, power, and status data at about 10 Hz), MSP_VOXL_STRINGS (191, craft name and other strings at about 2 Hz and on change), and MSP_VOXL_MENU (192, the menu state and rows). voxl-vtx relays them to the VRX, which in SDK 1.8.0 draws its own OSD from them. The character canvas is still sent, so older receivers keep working.

voxl-osd 1.2.0 (SDK 1.8.0) uses version 2 of MSP_VOXL_STRINGS, and voxl-vtx 3.3 requires it. Run the same SDK version on the drone and the VRX Ground Unit.

The service also owns the OSD menu, a stick-driven menu shown in the goggles for changing flight modes, failsafe behavior, logging, and VTX settings without a ground station.

voxl-osd is enabled by voxl-configure-mpa on FPV SKUs such as Stinger and the VTX Air Unit, and disabled by default everywhere else. It runs as the systemd service voxl-osd.service, starting after voxl-px4 (without requiring it) and restarting automatically.

Data Flow

By default the service reads everything it displays from MPA pipes and writes the finished canvas to one output pipe.

In external flight controller mode (see below) the MAVLink, VIO, and VFC inputs are replaced by an MSP UART link to the other flight controller.

voxl-configure-osd

voxl-configure-osd writes /etc/modalai/voxl-osd.conf and enables or disables the service. It must be run as root.

voxl-configure-osd factory_enable              # reset the config to defaults and enable
voxl-configure-osd factory_enable_no_compass   # defaults with the compass tape and degrees hidden
voxl-configure-osd external_fc                 # take input from an external MSP flight controller over UART
voxl-configure-osd hdzero                      # send the canvas over UART to an HDZero VTX
voxl-configure-osd enable                      # enable the service without touching the config
voxl-configure-osd disable                     # stop and disable the service

external_fc and hdzero pick the UART by platform:

Other platforms fall back to /dev/ttyHS1 for input and leave the output port empty; on M0197, set output_port by hand for hdzero. Edit input_port or output_port in the config file if your wiring differs.

Configuration File

/etc/modalai/voxl-osd.conf is JSON. It is created with defaults the first time the service runs, and any missing keys are added with their defaults on load. To print the loaded values without starting the service:

voxl-osd -c

Input and Output

Display Toggles

Element Positions

Every movable element has a *_col / *_row pair giving its character cell, origin top left. Set either value to -1 to hide the element. Defaults are for the HD 50x18 canvas.

Current draw, pack voltage, and per-cell voltage are pinned to the bottom right (column 43, rows 17 to 19) and cannot be moved.

Menu and Flight Mode Fields

Menu thresholds were 1650 / 1350 / 1850 / 1150 in voxl-osd 0.4.x. Versions from 1.0.0 on use the values above, so the menu needs less stick travel.

OSD Menu

With the vehicle disarmed, hold yaw up, throttle down, roll down, pitch down to open the menu. It always opens at the main menu. Pitch up and down moves the cursor. Roll left and right changes the value on the selected row or enters the highlighted submenu. Submenus end with BACK, EXIT (discard), and SAVE AND EXIT rows; the main menu ends with EXIT and SAVE AND EXIT. When flying over IP with voxl-joystick-server instead of an RC link, the same inputs come from the joystick.

FLIGHT MODE on the main menu, like FAILSAFE, appears only with PX4 over MPA. The VTX settings behind CHANNEL, PROFILE, and PIT are described in the VTX Air Unit Software Guide.

External Flight Controller (MSP)

The VTX can act as the digital video system for a non-VOXL flight controller that speaks MSP over UART, such as Betaflight:

voxl-configure-osd external_fc

This sets input_type to UART and input_protocol to MSP. The service then polls the external flight controller at 20 Hz for RC channels, status, box IDs, battery, analog, and GPS, renders the OSD from those, and publishes the arm state on msp_ext_fc_status. No MAVLink or PX4 is involved. Wiring and cable options are in the VTX Air Unit Quick Start Guide.

HDZero Output

To drive a third-party HDZero VTX instead of, or as well as, voxl-vtx:

voxl-configure-osd hdzero

This sets output_type to UART and the platform’s default output_port. Set output_type to 3 to keep the MPA output as well. See VOXL 2 with Third-Party VTX for the hardware side.

Debugging

voxl-inspect-services              # is voxl-osd running and enabled?
journalctl -u voxl-osd -f          # live service log
voxl-osd -c                        # print the loaded config and exit
ls /run/mpa/                       # msp_osd should exist once the service is up

• No OSD in the goggles but video is fine: check that voxl-osd is running and that output_type is 1 or 3. voxl-vtx must be running to composite the canvas.
• Telemetry fields blank: the service is up but mavlink_onboard has no data. Check voxl-mavlink-server and voxl-px4.
• Menu does not open: the vehicle must be disarmed, and the sticks must pass the thresholds in the config. The RC Channels menu is the quickest way to see the values the service is reading.
• After editing the config file, restart the service with systemctl restart voxl-osd.

Source Code

Source is at voxl-public/voxl-sdk/services/voxl-osd. It builds in the voxl-cross docker image per the repository README. Package versions shipped in each SDK are in the release notes.