What is Betaflight Air Mode?

Better late than never, so here is mine explanation what is AirMode implemented in Cleanflights fork Betaflight and hopefully soon available also in Cleanflight. Before we will go to any details, please read this to understand how PID controller works. If you know, you might skip it.

In normal flight mode, No Air Mode, flight controller is not using I term from PID controller when throttle stick is low. Why? To make landing nice and easy. It zeroes it. If it would not do it, drone would want to fight pilot attempts to land. That makes sense, right? I term is also not desired during take off. Why? Gyro error might accumulate in I term even before drone takes off, that would result in spinning motors faster and faster (since machine can not correct anything while still on the ground) and in worst case scenario, drone might flip before going into the air. So, zeroing I term on low throttle is good. Or is it not?

Continue reading “What is Betaflight Air Mode?” »

Read More

Cleanflight software low pass filters

Back in version 1.9, Cleanflight introduced new software low pass filters for gyro readouts, P term and D term of PID controller. They are designed to smooth control loop output and filter gyro inputs from undesired high frequency noise. Unfortunately, Cleanflight documentation was not yet updated and says very little about them. Here are few things that I was able to find out about them.


This low pass filter (LPF) is a software filter for gyroscope readouts. Most probably the less useful from software LPF filters in Cleanflight. Why? It duplicates (sits on top) of hardware gyro_lpf LPF filter build into MPU6050 or other gyroscope used in flight controller. The only advantage of gyro_cut_hz is a possibility to set any frequency while gyro_lpf accepts only limited set of frequencies. Can be left at 0 (disabled) unless there is a good reason to use it.

To enable it and set cutoff frequency to, for example, 64Hz, enter CLI mode and type:

set gyro_cut_hz=64


This LPF is slightly more useful than gyro_cut_hz since P term of PID controller depends on both gyro readout (filtered by hardware gyro_lpf) and user input. So, in some cases P term frequency can be higher than gyro trace. On the other hand, frequency change is so small, that gain from using pterm_cut_hz is minimal. Setting it below gyro_lpf or gyro_cut_hz will make PID control loop react slower than expected and decrease flight performance. Can be left at 0 (disabled) unless there is a good reason to use it.

To enable it and set cutoff frequency to, for example, 32Hz, enter CLI mode and type:

set pterm_cut_hz=64


Finally something useful! D term of PID controller, since it is trying to look into a future, can be a source of huge noise and vibrations. After all, looking into a future is always a tricky business. This is why D term and change with totally different frequency than gyro input and there is a very good reason to limit D term change. Too see how excess D noise can affect gyro traces take a look at my Blackbox tutorial.

Limit how much? I have no idea, since it all depends on a machine PID controller is trying to stabilize. Betaflight (Cleanflight fork aiming at 250 and smaller racers) sets it at 42Hz. My personal experience with big and prone to vibration Reptile 500 frame ended at dterm_cut_hz at 14Hz. Rule of thumb is: smaller and more rigid frames allows for higher D term cutoff frequency and 42Hz is a good place to start. Bigger frames might require lower cutoff frequency and 10Hz is lower boundary. On the other hand, I was using dterm_cut_hz at 16Hz on a 250 quad and was happy with results.

To enable it and set cutoff frequency to, for example, 16Hz, enter CLI mode and type:

set dterm_cut_hz=64

This entry is outdated, please refer to June 2016 update

Read More

Detecting Cleanflight PID tuning issues with Blackbox: not enough P

This is third part of Cleanflight PID tuning tutorial with Blackbox. Previously I’ve showed examples of:

This time it is time for something slightly different: not enough P gain. Usually this problem can be identified without any log analysis. Symptoms are quite visible: multirotor is sluggish during maneuvers, has a tendency to change attitude on its own, constant course corrections are required. In worse cases, it is unflyable. But how does it look like on Blackbox logs.

First of all, symptoms are not so clearly visible. There are no huge oscillations for example. Zoomed out log might event look good on a first glance. For example like this:

blackbox pid tuning not enough P overview

Continue reading “Detecting Cleanflight PID tuning issues with Blackbox: not enough P” »

Read More

Detecting Cleanflight PID tuning issues with Blackbox: excess D gain

Welcome to second part of Blackbox PID tuning tutorial. Last time I have showed few examples how excess P gain might look like. Today I will write few words about next common PID tuning problem: too much D. Derivative (future) part of PID controller is very useful, since it allows to smoothen control loop output when it is reaching the target. So, at the end of move (roll, pitch, yaw, anything else) multicopter will start to “slow down” before target is reached. It’s just like accelerator pedal in a car. When you want to reach 50 you start to release it before you reach 50, and not in the exact moment you reached target speed. If you would, you would have to use brake to slow down to 50. Derivative part helps not to overshoot. Without it, movement would be shaky, not smooth.

Unfortunately, D is tricky. Like everything that tries to see the future, it is unreliable and can introduce noise. We do not like noise. Not enough D = shaky, mechanical, movement and overshooting. Too much D = extra noise, vibrations, damped response.

How excess D would look like in Blackbox logs? Like this:

Too much D gain on Cleanflight Continue reading “Detecting Cleanflight PID tuning issues with Blackbox: excess D gain” »

Read More

Detecting Cleanflight PID tuning issues with Blackbox: excess P gain

Almost all quadcopter PID tuning tutorials can be summarized into one sentence: “Increase P until you see oscillations, then lower it”. Plus some thoughts about I and very vague advices about D and that is all. When I got into the hobby, I’ve read all of those tutorials. And I did know more about PID tuning than before that. I even had more questions than before. How to recognize high frequency oscillations, how to recognize low frequency oscillations. Lower P? OK, but how much? And D? How to tune this bloody D? As a result, every time I tried, I ended up with very snappy but shaky quadcopter that maybe responded very quickly to commands, but was very shaky and was making strange noises.

And then came Cleanflight and Blackbox. Live became simpler. What I’ve learned from Blackbox logs is that I wanted high P so much, I had too much of it in the end. Actual oscillations begins before we see or hear them and excess D introduces jello. Blackbox simplified things, but still, logs analysis is something like an art. You have to know what to look for. Continue reading “Detecting Cleanflight PID tuning issues with Blackbox: excess P gain” »

Read More

What is PID controller?

Multicopter is an unstable machine. It requires constant corrections to keep is stable in the air. This is done with PID control loop. When quadcopter does not fly like you hoped, you will hear: “Tune your PIDs“.  Nice. But what exactly is PID? If you did not studied control theory, and you do not want to start, you read internet. And internet tries to explain PID in various ways. Some are better, some are worse, and there is always room for a new one. So here we go.

Officially, PID goes for Proportional, Integral, Derivative. Wikipedia provides enough of long and boring theory. If it’s TL;DR, here is a short summary:

  • PID controller measures error of current output and desired output,
  • This error is processed separately by P, I and D modules,
  • Then, output of each module is multiplied by it’s coefficient (Kp, Ki, Kd) and added all together as an controllers output,
  • Controller can be tuned by changing Kp, Ki and Kd values,
  • In a multicopter, there is separate controller for each axis (roll, pitch, yaw) working based on rotation speed provided by gyros. This is called and “inner loop”.
  • Some flight modes adds “outer loop” with separate PID controller that is translating user input into values used by “inner loop”. Outer loop is much less important than inner loop and usually there is not need to tune it,
  • Flight modes like Attitude, Angle, Horizon (all with self leveling) are using both outer and inner loop,
  • Flight modes like Rate, Acro and using only inner loop,
  • When speaking on PID tuning, in 99% of cases we will be talking about tuning the “inner loop”,
  • Inner loop tuning should be done only in Rate/Acro flight modes (no self leveling) and avoid complex outer-inner loop interactions.

Continue reading “What is PID controller?” »

Read More