VTX Air Unit Software Guide

Table of contents

1. VOXL SDK Support
   1. SDK Versions
   2. Core Services
2. voxl-vtx Service
   1. voxl-configure-vtx
   2. Configuration File Reference
      1. Wireless
      2. Forward Error Correction
      3. Video Profiles
      4. Telemetry & Link Behavior
      5. UDP Mode (IP networks)
      6. RF / IP Automatic Fallback
      7. System
   3. Supported Frequencies
   4. TX Power
   5. Encryption Key / Binding
   6. Live Control & Inspection
3. voxl-osd Service
   1. voxl-configure-osd
   2. Configuration File Reference
   3. OSD Menu
4. Using External Flight Controller (MSP DisplayPort)
   1. Betaflight Note (Rotor Riot F7)
5. ADB Access
6. Using VTX as Standard WiFi Modem
   1. WiFi Dongle Modes
   2. VTX WiFi Limitation
   3. Practical Implications

VOXL SDK Support

SDK Versions

VOXL SDK 1.6.X+ recommended (downloads).

Core Services

The VTX runs the standard VOXL SDK. The services below do the video work:

voxl-vtx Service

voxl-vtx is the digital video transmitter service. It pulls encoded video from a camera pipe, applies forward error correction, and transmits it over the RF link (or UDP over an IP network). It runs as the systemd service voxl-vtx.service (starts after voxl-camera-server, restarts automatically).

The service is not enabled by simply installing the package — use voxl-configure-vtx:

voxl-configure-vtx --enable            # load the VTX kernel module and enable the service
voxl-configure-vtx --disable           # restore the standard WiFi driver and disable the service

The VTX radio and standard WiFi share the same hardware. To use WiFi, disable the VTX first — see Using VTX as Standard WiFi Modem.

voxl-configure-vtx

voxl-configure-vtx manages /etc/modalai/voxl-vtx.conf and can push settings live to a running service:

Usage: voxl-configure-vtx -h -l -F -m -s -p -P -t -e -d -f -w

 -h, --help                  Show this help message and exit
 -l, --list                  Show the current configuration
 -F, --frequency             Set frequency
 -m, --mcs                   Set MCS index for the current active profile
 -s, --source                Set pipe to get video from for the current active profile
 -p, --power                 Set power idx (not mW) for the current active profile (does not save to configuration file)
 -P, --power-mw              Set power in milliwatts (mW) for the current active profile
 -t, --toggle                Toggle between Wifibroadcast and SoftAP mode
 -e, --enable                Load modified kernel module for RTL8812AU and enable voxl-vtx service
 -d, --disable               Load default kernel module and disable voxl-vtx service
 -f, --factory_enable        Enable and restore default configuration file
 -w, --wizard                Start interactive wizard

Useful behaviors:

• Running with a missing config file writes factory defaults first.
• --wizard walks every setting interactively, including a video-profile editor.
• Live changes (frequency, MCS, power, profile) are pushed to the running service via its control pipe — no restart needed.
• UDP receiver endpoints can be managed with --add_udp_receiver <ip:port>, --remove_udp_receiver <ip:port>, and --clear_udp_receivers.
• Factory presets exist for common radio setups (--factory_enable_lte, --factory_enable_doodle, --factory_enable_dtc) and supported vehicle SKUs.

Configuration File Reference

/etc/modalai/voxl-vtx.conf (JSON). Created with defaults on first run. The VRX must match frequency, bandwidth, and the FEC settings.

Wireless

Forward Error Correction

Video Profiles

profiles is an array of video stream profiles (e.g. Default, Thermal, Tracking, Long Range, Low Latency), selected by active_profile_idx, an RC switch, joystick buttons, or the OSD menu.

Each profile entry:

Telemetry & Link Behavior

UDP Mode (IP networks)

For streaming over LTE, Doodle Labs, DTC, or wired IP networks instead of (or alongside) the RF link. See the VRX Developer Guide for the full walkthrough.

RF / IP Automatic Fallback

With both RF and UDP configured, the VTX can move video to IP automatically when the RF link degrades, and back when it recovers. Enable with voxl-configure-vtx --enable_ip_fallback.

The VRX shows the current RF/IP source on its OSD.

System

Supported Frequencies

voxl-configure-vtx --frequency accepts the following center frequencies (MHz). Default is 5805 (channel 161); bandwidth may be 20 or 40 MHz.

TX Power

• Per-profile power is set in milliwatts (0-1000); -1 means maximum power.
• voxl-configure-vtx --power-mw <mW> changes the active profile’s power live and persists it.
• PIT mode (enable_pit) keeps TX power at a bench-safe minimum; toggle it from the OSD menu when ready to fly.

Encryption Key / Binding

VTX and VRX bind by sharing an encryption key file — there is no over-the-air pairing.

• Units ship with a default key and will link out of the box.
• Generate a new key with voxl-vtx-keygen (on target, or any Linux host): -b <bind_phrase> makes the key deterministic from the phrase; without -b a random key is generated. Output is vtx.key.
• To install a key, copy vtx.key onto a USB flash drive and plug it into the unit — it is detected and installed to /data/modalai/vtx.key automatically. Do this on both the VTX and VRX.
• The VRX can also generate and provision a new key from its buttons — see the VRX Quick Start Guide.

Live Control & Inspection

A running voxl-vtx accepts commands on its control pipe:

voxl-send-command vtx_latency set_frequency 5805
voxl-send-command vtx_latency set_mcs 3
voxl-send-command vtx_latency set_mw_power 500
voxl-send-command vtx_latency set_profile_idx 1
voxl-send-command vtx_latency set_pit_mode 0

To watch link stats live (latency, throughput, temperature, TX power, FEC):

voxl-inspect-vtx -n

voxl-osd Service

voxl-osd renders the on-screen display: telemetry, flight mode, VIO state, warnings, and more, composited over the FPV video. It never touches pixels directly — it draws a character-cell text canvas and streams it as MSP DisplayPort commands, which voxl-vtx composites into the transmitted video. Source is available at voxl-public/voxl-sdk/services/voxl-osd.

By default it consumes PX4 telemetry over MPA (mavlink_onboard), plus VIO quality, VFC state, VTX temperature/power, and CPU stats pipes.

voxl-configure-osd

voxl-configure-osd factory_enable              # reset config to defaults and enable
voxl-configure-osd factory_enable_no_compass   # defaults without the compass tape
voxl-configure-osd external_fc                 # OSD for an external (MSP) flight controller
voxl-configure-osd hdzero                      # output MSP DisplayPort over UART to an HDZero VTX
voxl-configure-osd enable | disable

Configuration File Reference

/etc/modalai/voxl-osd.conf (JSON), created with defaults on first run.

Positioning: every screen element has a *_col / *_row pair — a character cell on the OSD canvas, origin top-left. Set either to -1 to hide that element. Elements include RSSI, armed/disarmed status, flight mode, lat/lon, MGRS grid, velocity, altitude, distance-to-home, crosshair, compass, craft name, VTX temperature/power, and CPU warnings. Battery voltage, per-cell voltage, and current draw are fixed positions.

Key toggles and behavior fields:

OSD Menu

With the vehicle disarmed, open the on-screen menu with the RC sticks: yaw up + throttle down + roll down + pitch down. The menu adjusts flight modes, OSD debug options, RC channel view, compass, and failsafe behavior, and can change VTX channel/profile/PIT mode directly. When flying over IP with voxl-joystick-server instead of RC, the menu responds to the joystick as well.

Using External Flight Controller (MSP DisplayPort)

The VTX can serve as the digital video system for a non-VOXL flight controller speaking MSP over UART:

voxl-configure-osd external_fc

This switches voxl-osd to poll the external FC over the OSD UART (arm state, RC, status) and render the OSD from it — no MAVLink link required. See the VTX Quick Start Guide for wiring and cable options.

Betaflight Note (Rotor Riot F7)

The UART for DVTX had a bug in the 4.5 Betaflight firmware that we tested against, so we fixed it using the 4.5 maintenance branch. Here’s a docker project that can build the FW like we did:

https://gitlab.com/voxl-public/support/betaflight-build-docker

ADB Access

The USB-C port is a standard VOXL 2 Mini USB-C port, with ADB access as needed.

Using VTX as Standard WiFi Modem

The following procedure applies to VTX-enabled sUAS (e.g. D0013 Stinger) or the stand-alone (MVX-T0001).

The VTX radio and standard WiFi are the same hardware. To switch to SoftAP or Station mode, first disable the VTX (this restores the standard WiFi driver), then configure WiFi with voxl-wifi:

voxl-configure-vtx --disable
voxl-wifi softap5              # or your desired voxl-wifi mode

When you are done using WiFi, re-enable the VTX:

voxl-configure-vtx --enable

WiFi Dongle Modes

When using an external USB WiFi dongle, two operation modes are supported:

• Station Mode: The drone connects to a nearby WiFi access point (such as a router or mobile hotspot). This allows the drone to access the internet through the connected network.

• SoftAP Mode: The drone creates its own WiFi access point (hotspot). Other devices (such as laptops, tablets, or ground control stations) can connect directly to the drone’s hotspot for communication.

VTX WiFi Limitation

If no external WiFi dongle is used and the VTX’s built-in radio is relied upon, there is an important limitation currently:

• Station Mode is not available. The VTX cannot directly connect to an external WiFi network for internet access.

• SoftAP Mode remains available. By running voxl-wifi and selecting the softap5 option, the VTX can still create its own hotspot. This allows ground devices to connect directly to the drone’s WiFi network for data transfer, but does not provide internet connectivity.

Practical Implications

• Use a WiFi dongle if your application requires the drone to join an existing WiFi network and gain internet access.
• Use the built-in VTX SoftAP mode (softap5) when you only need a direct peer-to-peer WiFi link between the drone and a controller device, without internet access.