VOXL 2 PX4 Developer Guide

Table of contents

1. Preface
   1. Introduction
   2. For the PX4 Developer
   3. Key PX4 Differences to Note
   4. Block Diagram - Details
2. Component Walkthrough
   1. Processors
   2. Onboard Sensors
   3. External Sensors and Interfaces
   4. Software Interfaces
   5. Image Sensor Interfaces
3. Theory of Operation
   1. Startup
4. Common Use Cases
   1. How to Access the PX4 Shell (pxh)
   2. Show a PX4 Parameter
   3. Backup Parameters from Device
   4. Spin Motors
      1. Using UART ESC
   5. View uORB Data
5. Source Code

Preface

This guide is geared towards someone interested in all the bits and bytes that make PX4 on VOXL 2 work. If you are looking instead for a general user’s guide, please refer to the VOXL 2 PX4 User Guide

Introduction

VOXL 2 is a flight controller that runs PX4. On VOXL 2, it runs flight critical parts of PX4 software on a real time DSP, and other parts in Ubuntu 18.04 Linux on an 8 core 64-bit ARMv8 processor.

Typical of other flight controllers, there are connectors for external sensors, power, and ESC actuation. There are sensors like IMUs and barometers, file systems for logging flights, and interfaces for connecting to ground control stations.

But unlike most other flight controllers, PX4 is actually also running in a companion computer with that is capable of doing things like stream 7 image sensors simultaneously for computer vision and support multiple data links like 5G. Although we will use the companion computer as a “front end” in some of the instructions below, the other guides here (TODO) contain more detailed usage of that part of the system.

For the PX4 Developer

If you are a PX4 developer who is used to developing on microcontollers. On VOXL 2:

• PX4 is installed using apt package manager (see boards/modalai/rb5-flight/debian/DEBIAN/ to see how)
• Connection to QGC is over IP, not USB or serial
• The Non-RTOS parts of PX4 run in Ubuntu 18 (on the applications processor), these are defined boards/modalai/rb5-flight/default.cmake, and can be built in a docker container available here
• The RTOS parts of PX4 run in an RTOS called QuRT (on the sensors DSP), these are defined boards/modalai/rb5-flight/qurt.cmake, and can be built in the same docker container available here
• PX4 is installed via the VOXL SDK (aka voxl-suite), and this guide is meant to allow users to customize this component.
  • You currently cannot install the PX4 for SLPI build via QGroundControl
• The ‘guest OS’ firmware that runs in the sDSP is included in the system image, providing access to the drivers for UART/I2C/SPI etc.
• When you are connected to VOXL 2’s shell, all the normal PX4 command (like listener) get a px4- prefix, e.g. to use the listener command, try px4-listener

Key PX4 Differences to Note

• Currently, there’s no connection from QGroundControl to PX4 through the USBC connector
  • The USBC connection provides ADB access only, which brings you to a shell and you can interface with PX4 command line from Linux
• Communications from VOXL 2 to the ground station are over IP. Please see the Connecting Quickstart

Block Diagram - Details

The following provides details about the architecture:

View in fullsize

Component Walkthrough

Processors

Onboard Sensors

External Sensors and Interfaces

For detailed pinouts, please reference the VOXL 2 connectors page.

Software Interfaces

Image Sensor Interfaces

Shown called out as Z, QTY6 4-lane MIPI-CSI2 + QTY4 CCI interfaces are available via the J6, J7 and J8 connectors. See VOXL 2 camera configs for more details.

Theory of Operation

Startup

• A service defined by /etc/systemd/system/voxl-px4.service is started on bootup by systemd
• The voxl-px4.service runs the voxl-px4 bash script which serves as a CLI wrapper utility for starting px4
• Before starting px4, if the PX4 parameters are not present in /data/px4/parameters, they are initialized by /etc/modalai/voxl-px4-set-default-parameters.config
• A px4 instance is then started as a daemon process, executing the startup script defined by /etc/modalai/voxl-px4.config

Common Use Cases

How to Access the PX4 Shell (pxh)

You can access the PX4 shell from the VOXL2 command line by using a px4- prefix on commands, which will route them to the PX4 daemon process.

Sometimes, it’s easier to debug and get access to the PX4 shell by instead running PX4 as a process:

• adb onto VOXL2

adb shell
voxl2:/$

• disable the voxl-px4 deamon by running systemctl disable voxl-px4

voxl2:/$ systemctl disable voxl-px4
Removed /etc/systemd/system/multi-user.target.wants/voxl-px4.service.

• also disable voxl-mavlink-server using systemctl disable voxl-mavlink-server which can start voxl-px4 as a dependency

voxl2:/$ systemctl disable voxl-mavlink-server
Removed /etc/systemd/system/multi-user.target.wants/voxl-mavlink-server.service.

• reboot VOXL2

exit
adb reboot

• adb back on VOXL2

adb shell
voxl2:/$

• manually run voxl-px4

voxl2:/$ voxl-px4
Found DSP signature file
INFO  [px4] mlockall() enabled. PX4's virtual address space is locked into RAM.
INFO  [px4] assuming working directory is rootfs, no symlinks needed.

______  __   __    ___
| ___ \ \ \ / /   /   |
| |_/ /  \ V /   / /| |
|  __/   /   \  / /_| |
| |     / /^\ \ \___  |
\_|     \/   \/     |_/

px4 starting.

INFO  [px4] Calling startup script: /bin/sh /etc/modalai/voxl-px4.config 0
Running on M0054
...

• Hit ENTER to get the shell to show up after the console stops updating

...
INFO  [uorb] Advertising remote topic vehicle_attitude
INFO  [uorb] Advertising remote topic vehicle_attitude_setpoint
INFO  [uorb] Advertising remote topic vehicle_rates_setpoint

pxh>

• Some drivers run on the applications processor. You can issue these commands directly, like:

pxh> commander status
INFO  [commander] arming: STANDBY

• Some drivers run on the DSP, and can be accessed using qshell like:

qshell px4io status

...

INFO  [muorb] SLPI: Direct PWM values: 0 0 0 0 0 0 0 0
INFO  [muorb] SLPI: Ok executing command: px4io status
INFO  [muorb] SLPI: Sending qshell retval with timestamp 151805206, current timestamp 151805206
INFO  [qshell] qshell return value timestamp: 151805206, local time: 151808943

Show a PX4 Parameter

px4-param show | grep UART

Backup Parameters from Device

The parameters are stored in /data/px4/param/parameters.

Spin Motors

Using UART ESC

The following would spin, sequentially, PX4 motors 1, 2, 3 and 4 at 1000 RPM for ~1 second.

px4-qshell modalai_esc -i 1 -r 1000 rpm
px4-qshell modalai_esc -i 2 -r 1000 rpm
px4-qshell modalai_esc -i 4 -r 1000 rpm
px4-qshell modalai_esc -i 8 -r 1000 rpm

View uORB Data

voxl2:/$ px4-listener sensor_accel

TOPIC: sensor_accel
 sensor_accel_s
	timestamp: 126098074  (0.002515 seconds ago)
	timestamp_sample: 126097753  (321 us before timestamp)
	y: -0.2508
	z: -9.7809
	temperature: 32.4728
	error_count: 0
	clip_counter: [0, 0, 0]

Other useful topics:

• px4-listener sensor_accel
• px4-listener sensor_gyro
• px4-listener sensor_gps
• px4-listener sensor_baro
• px4-listener battery_status
• px4-listener input_rc

Source Code

The current PX4 branch is here.

To build, see the docker container project available here

Next: VOXL 2 HITL Guide