VOXL Vision PX4

Table of contents

  1. Overview
  2. Installation
  3. Configuring the PX4
    1. PX4 Parameters File
    2. Radio Channel Configuration
    3. UART Connection VOXL to Flight Controller
      1. VOXL to FMU-v5m
      2. VOXL to Pixhawk
    4. Network Connection for Telemetry
  4. Flying
    1. Confirm PX4 is Getting VIO Data
    2. Confirm Data is in the Right Coordinate Frame
    3. Take Off in Manual Mode
    4. Take off in Position Mode
    5. Flip to Offboard Mode


The voxl-vision-px4 package provides integration of the ModalAI Vision Lib with PX4 to enable GPS-denied position control via Visual Inertial Odometry (VIO), Visual Obstacle Avoidance (VOA), and AprilTag detection.

This project is a work in progress and the master (stable) branch currently does the following functions:

  • responds to PX4’s mavlink timesync requests
  • Sends VIO data as mavlink_msg_vision_position_estimate packets
  • Sends a mavlink_msg_set_position_target_local_ned packet with position 2m above takeoff point
  • PX4 will fly to this position when put in offboard mode
  • passthrough all other mavlink packets to specified IP address over UDP


1) Follow the instructions to install and setup the ModalAI Vision Lib

2) Download the latest stable voxl-vision-px4 ipk package from the downloads page. Or build from source at https://gitlab.com/voxl-public/voxl-vision-px4

3) Push to VOXL and install

adb push voxl-vision-px4_0.0.4_8x96.ipk /home/root/ipk/
adb shell opkg install --force-reinstall /home/root/ipk/voxl-vision-px4_0.0.4_8x96.ipk

Configuring the PX4

PX4 Parameters File

A PX4 parameter file is included with this project’s source: https://gitlab.com/voxl-public/voxl-vision-px4/tree/master/px4_params

Currently this project is tested on a ModalAI M500 platform with a VOXL and FMU-v5m flight controller. The flight controller orientation is taken into consideration in this parameter file.

The provided parameter files in that directory are trimmed of any sensor or radio calibration so they can be uploaded via QGroundControl without recalibrating.

Radio Channel Configuration

For testing we use a Spektrum DX8 radio with a CLEAN model, e.g. no mixing, no trimming, default limits. By default, the Spektrum DX8 exposes channels 6 and 7 on the two 3-position toggle switches to the left and right of the “DX8” logo respectively. These are easy to reach switches which we assign to flight mode and motor-kill respectively.

  • “Flap Gyro” switch left of DX8 Logo
  • Channel 6
  • Up position: Manual Flight Mode
  • Middle Position: Position Flight Mode
  • Down Position: Offboard Flight mode

  • “Aux2 Gov” switch right of DX8 Logo
  • Channel 7
  • Up position: Motor Kill Switch Engaged
  • Down Position: Motor Kill Switch Disengaged (required to fly)

Since we have a manual kill switch on the radio there is no need for the “safety switch” on the Pixhawk GPS module as so it is disabled in our params file in favor of the kill switch.

The associated QGroundControl settings for this configuration should look as follows:


UART Connection VOXL to Flight Controller

VOXL communicates with a PX4 flight controller via Mavlink Protocol over a 921600 baud UART link at 5V logic level.

VOXL to FMU-v5m

On the FMU-v5m the VOXL should be connected to the J1 port which is enumerated as the “telem2” serial port in PX4 software.

For more details see FMU-v5m Connectors.

  • VOXL J12 Header <–> FMU-v5m J1

VOXL to Pixhawk

VOXL talks to the Pixhawk via UART at 912600 baud at 5V logic level. For now you will need to make a cable that connects VOXL Port J12 to the Pixhawk’s “UART/I2C” port. You could also plug into the Pixhawk “telem1” port but then you lose use of the 915mhz telemetry modules and the VOXL will receive a lot of unnecessary telemetry data intended for QGroundControl.

  • VOXL J12 Header <–> PX4 “UART/I2C” Port
  • Pin 2 (TX) <–> Pin 3 (RX)
  • Pin 3 (RX) <–> Pin 2 (TX)
  • Pin 5 (GND) <–> Pin 6 (GND)

For more details on Header J12 see the voxl-datasheet page. Note this is the only header that runs at 5V logic level which matches the Pixhawk.

Network Connection for Telemetry

Instead of using a pixhawk telemetry radio, it is possible (and recommended) to use the VOXL as a telemetry proxy. To configure this, first set up a network connection between the VOXL and the computer you wish to run QGroundControl on. This can be in softAP mode or on a wifi network. For whichever network connection you choose, you need to know the IP address of the ground station computer. Enter this IP address into the voxl-vision-px4 config file on the VOXL: /etc/modalai/voxl_vision_px4.conf

After updating this file it’s necessary to restart the voxl-vision-px4 service. For experimentation, voxl-vision-px4 can also be provided with a temporary override IP address via the -i argument. Make sure the voxl-vision-px4 systemd service is stopped if you are going to start it manually.

systemctl restart voxl-vision-px4

Open QGroundControl on your ground station computer. The PX4 flight board (FMU-v5m or pixhawk) should now be able to find QGroundControl using VOXL as a proxy from UDP to UART. Via the Mavlink section in QGroundControl parameters you can configure this connection (mavlink 1).

If you are having dificulty establishing a connection, make sure the PX4 flight control board is powered up and has been configured with one of the included parameters file which configures the right baud rate and serial port in PX4.


Confirm PX4 is Getting VIO Data

As part of the IPK package installation a voxl-vision-px4 systemd service is created which starts the interface and ModalAI Vision Lib automatically on boot. This takes up to about 30 seconds to start. By the time you have plugged in a battery, walked back to your laptop, and opened QGroundControl voxl-vision-px4 should be running. Confirm before flight by opening the mavlink inspector and checking that X&Y values are non-zero in the ODOMETRY mavlink telemetry packets.


Alternatively, if your computer running QGroundControl has its volume turned up you should hear it announce the swap from “manual” to “position” mode when you flip the flight mode switch from up to middle. If VIO data is not being transmitted, the system will fall back to altitude mode and you will hear “position mode rejected, altitude flight mode”. In this case, go back to manual flight mode (switch up) and wait a few more seconds for voxl-vision-px4 to finish initializating.

If this doesn’t work, go back to Installation Step 1 and reconfirm VIO is working. You can also check the voxl-vision-px4 systemd service for indications of what might have gone wrong.

adb shell
systemctl status voxl-vision-px4

Confirm Data is in the Right Coordinate Frame

While looking at the ODOMETRY data in QGroundControl’s Mavlink Inspector, observe the xyz data as you move the quadcopter around. Make sure it aligns with NED coordinate frame. If there is a coordinate system mismatch PX4 will initially take off then very quickly run away out of control.

Take Off in Manual Mode

First take off in Manual Flight Mode just to confirm the basic functionality of the quadcopter (motor rotation directions, sensor calibration, radio stick directions).

  • Flip the motor Kill switch DOWN
  • Flip the Flight Mode switch UP (manual mode)
  • Hold the right stick centered and left stick down and right to ARM
  • Move left stick to bottom-middle position.
  • Slowly raise left stick up to spool up the motors and take off.

To Land:

  • Slowly drop throttle until the quadcopter touches the ground.
  • Hold the throttle stick all the way down until the system DISARMS
  • QGroundControl will verbally confirm that the system is DISARMED
  • The motors will keep spinning slowly (idling) even after disarming.
  • Flip the motor kill switch UP to kill the motors.

Take off in Position Mode

It is safer to take off in Position Flight Mode than it is to flip to this mode mid-flight from Manual Flight Mode.

Take off and land with the same instructions as listed above but this time with the Flight Mode switch in the middle position. The quadcopter should take off straight up and be much easier to control than in manual mode.

Be ready to flip back to manual mode should anything go wrong. It is safer to flip to manual mode and land than to kill the motors mid-flight. Killing the motors mid-flight may result in the propellers loosening from the reverse-torque and flying straight up off the quadcopter. Only kill the motors after landing and spooling down the motors OR in a serious emergency.

Flip to Offboard Mode

While flying in Position Mode, you may flip the Flight Mode Switch all the way down to enable offboard mode. The quadcopter should immediately fly back to a position 2 meters above wherever VIO initialized. If you plugged in the battery and let the VOXL and PX4 power up at the takeoff location (suggested normal practice) then it should hold a position 2 meters anove the takeoff location.

In Offboard Mode the 2 joysticks on the RC controller are ignored and the PX4 follows any commands given to it by VOXL over the UART link. In this case VOXL just sends a static location.

Copyright (c) 2019 ModalAI Inc.