Intro

Hackflight is a simple, platform-independent, header-only C++ toolkit for building multirotor flight controllers. It is geared toward people like me who want to tinker with flight-control firmware, and use it to teach students about ideas like inertial measurement and PID tuning. If you are in the 99% percent of users who just want to get your vehicle flying without getting into firmware hacking, I recommend Betaflight (great for getting started when you're on a budget) or the Ardupilot system (for sophisticated mission planning with waypoint navigation and the like). In addition to big user communities and loads of great features, these platforms have safety mechanisms that Hackflight lacks, which will help avoid injury to you and damage to your vehicle.

Supported platforms

Hackflight is currently working on the following platforms:

• TinyPICO

• Ladybug Flight Controller from Tlera Corp

• Butterfly DIY brushless flight controller (components from from Tlera Corp. and Pesky Products)

• MulticopterSim flight simulator based on UnrealEngine4

Standard units

By supporting floating-point operations, these platforms allow us to write simpler code based on standard units:

• Distances in meters
• Time in seconds
• Quaternions in the interval [-1,+1]
• Euler angles in radians
• Accelerometer values in Gs
• Barometric pressure in Pascals
• Stick demands in the interval [-1,+1]
• Motor demands in [0,1]

Design principles

Thanks to some help from Sytelus, the core Hackflight firmware adheres to standard practices for C++, notably, short, simple methods and minimal use of compiler macros like #ifdef that can make it difficult to follow what the code is doing.

A typical Arduino sketch for hackflight is written as follows:

1. Construct a Hackflight objecting using a Board, Receiver, and Mixer object.

2. Add sensors (Gyrometer, Quaternion)

3. Add PID controllers (Rate, Level)

4. In the loop() function, call Hackflight::update()

RoboFirmwareToolkit

Hackflight is built on top of RoboFirmwareToolkit (RFT), a general-purpose toolkit for building robot firmware. So before trying out Hackflight you should also install RFT. It is also worth checking out the README for RFT in order to see some of the design principles supporting Hackflight (see also the note on PID controllers below.)

Ground Control Station

Because it is useful to get some visual feedback on things like vehicle orientation and RC receiver channel values, we also provide a very simple “Ground Control Station” (GCS) program that allows you to connect to the board and see what's going on. Windows users can run this program directly: just clone the HackflightGCS repository and double-click on hackflight.exe. Others can run the hackflight.py Python script in the extras/gcs/python folder. To run the Python script you'll need to install MSPPG, a parser generator for the Multiwii Serial Protocol (MSP) messages used by the firmware. Follow the directions in that folder to install MSPPG for Python.

PID Controllers

Note these two important points about PID controllers in Hackflight:

1. A PID controller is not the same as a flight mode. For example, so-called Acro mode requires a PID controller based on angular velocity (a.k.a. rate, computed from the gyrometer) for each of the three angles (roll, pitch yaw). So-called Stabilize mode requires these three angular-velocity controllers, plus a PID controller based on angle (computed from the quaternion) for the roll and pitch axes. To support this arrangement in Hackflight, PID controllers for aux state 0 will also run in aux states 1 and 2, and PID controllers for aux state 1 will also run in aux state 2.

2. It matters in which order you add PID controllers, because the output of one PID controller is the input to the next. For example, to get Stabilize mode, you want the Level controller to go first, setting the desired pitch/roll angles, and the Rate controller to go next, to control the rate at which the desired angle will be reached.