Why do we tune? We tune to get more responsiveness out of our quad. What does responsiveness mean? It means getting our quad to do what we want as accurately and as quickly as possible. Therefore, the goal of tuning is to ensure the accuracy of and minimize the timing lag between our radio stick commands (“setpoint”) and what our quad is doing (“gyro”). In blackbox speak, we want our gyro to track setpoint as closely as possible.
This guide is a holistic, step-by-step process involving 12 flights covering filter, PID, and feed forward tuning. The approach has been used to good effect on 150mm (3 inch) to 350mm (7 inch) class quadcopters. Notwithstanding, this guide is just that – a guide. Use it as a framework, modified to suit your needs. Lastly, this guide is not meant to be an in-depth discussion of filter and PID theory.
Much of the information from this guide is based on information from UAV Tech as well as from Joshua Bardwell and Pawel Spychalski. Additional thanks to the support from the great community at IntoFPV.
This guide makes use of general rules of thumb which typically apply to most builds. However, you are encouraged to deviate from these generalities if there is a valid reason to do so. In particular, quads smaller than 150mm or larger than 350mm will likely require a modified approach.
Filter Discipline
The first step is to set up the filters. A significant amount of filtering is achieved by the Dynamic Notch and RPM Filters, so we will be disabling most other filters. A good frame and a good build should not require so much filtering. This is filter discipline.
In the Configuration tab:
Set ESC /Motor Protocol to at least DSHOT 600.
Turn on Bidirectional DShot (ensure that motor pole count is accurate).
Set the PID loop frequency to 8.00 kHz.
Under Other Features, set Dynamic Filter on.
In the PID Tuning tab under Filter Settings:
For the D Term Lowpass 1 Dynamic Filter:
Min Cutoff Frequency = 70 kHz
Max Cutoff Frequency = 170 kHz
Filter Type = BIQUAD
For the Gyro RPM Filter:
Harmonics Number = 1
Min Frequency = 100 kHz
For the Dynamic Notch Filter
Width Percent = 0
Q = 250
Min Hz = 70
Max Hz = 350
Turn off all other filters (ignore warnings). This is what your filter settings should look like:
It is important to note that while these filter settings are aggressive, they are reasonable to the extent that your build has a reasonably low noise profile. If you are finding that your motors are running hot regardless, you may need to re-activate filters which were disabled above. In such a case, enable the sliders and adjust accordingly to your observed motor operating temperatures. As a general rule of thumb, if the motors are too hot to hold, they are likely operating above acceptable temperature ranges.
Blackbox Settings
On the Blackbox tab:
If you are using an SD card or have a lot of onboard memory, set the logging rate to 2 kHz, otherwise set it to 1 kHz.
Set the debug mode to GYRO_SCALE.
This mode tracks the raw noise being detected by the gyro before any filtering. The degree of raw noise will significantly inform how aggressive your filtering can be.
Format the SD card or erase the flash memory.
In some cases, 1 kHz logging speed can result in gaps in blackbox traces. Increasing this to 2 kHz usually results in complete traces. Note however that you double the memory required in addition to utilizing additional CPU resources.
Pre-Tune Settings
These settings serve to disable software assists and PID sum limits to make it easier to isolate changes in PID tuning.
On the PID Tuning tab under I Term Relax:
Axes = RP
Type = Gyro
Cutoff = 10
The following CLI commands will reset PID settings, disable D-Min and Feed Forward, as well as certain assists:
set d_min_pitch = 0
set d_min_roll = 0
set f_pitch = 0
set f_roll = 0
set f_yaw = 0
set pidsum_limit = 1000
set pidsum_limit_yaw = 1000
set feedforward_transition = 0
set abs_control_gain = 0
set use_integrated_yaw = OFF
set iterm_relax_cutoff = 10
set vbat_sag_compensation = 100
set vbat_pid_gain = off
save
The PID tab should now look like the following:
P/D Tuning
That was not a typo. The focus is on the P and D terms only. This process involves “bracketing” P and D terms to determine the optimal levels.
The optimal P is the point at which gyro is tracking setpoint as well as it can without overshooting or inducing high frequency oscillations.
The optimal D is the point at which prop wash is diminished but motors remain within reasonable operating temperatures.
It all starts with the D term …
The starting D term is based on your power system (lipo cell count):
Note that this is generally independent of the quad size. You would use the same starting D term range for a 150mm (3 inch) build and a 350mm (7 inch) build both using a 4S lipo based power system. The difference will be in the relationship between the P and D terms.
The D term is a noise amplifier…
If your motors become too hot to hold even on the low end of the starting D term range based on your power system, you may have an inherently noisy build. As discussed earlier, the gyro_scaled blackbox debug trace reflects your build’s noise profile before any filtering. A clean gyro_scaled spectrograph will look similar to this:
Noise in the gryo_scaled spectrograph that manifests between the low frequency noise (approx <25Hz) and motor harmonics (approx 200Hz) will typically burden the gyro and necessitate more filtering. In such cases, insufficient filtering will result in motors overheating beyond operating temperatures. In essence, the gyro will need to work more and may cause the motors to spin in an erratic behavior resulting in the excessive heat. Additional filtering will mitigate the noise reaching the gyro but will also introduce latency in the process since additional calculations are being required.
Bracketing the P/D …
In this next step, you will be choosing a range of two starting D terms and performing four tuning flights with incrementally higher P terms for each of the two D term scenarios. Each run should include at least a roll left and right, a forward and back flip, and 180-degree hard turns for a total of eight tuning runs.
For example, for a 4S build, the selected D terms are 40 and 45. The following tuning runs would be performed. Note that the multiple ranges and P term increments are for illustrative purposes only and may be altered so suit your preference.
Particularly for larger builds, P term can be well over twice the selected D term.
Be sure to check motor temperatures after every flight. Excessively high operating temperatures will damage motors and potentially other components. As a general rule of thumb, if the motors are too hot to hold, they are too hot.
Open each tuning run scenario in Blackbox Explorer and enable these traces for pitch and roll:
Gyro
Setpoint
PID P
PID I
PID D
Make Gyro and Setpoint traces bold since these will be of particular focus. For each scenario, take a screenshot of a representative pitch and roll.
Recall that the Setpoint trace reflects your stick input commands while the Gyro trace reflects what the quad is actually doing.
Too little P term …
Each progressively higher P Term scenario for a given D Term should depict a closing gap between the Setpoint and Gyro traces. The following screenshot (Setpoint is orange while Gyro is blue) shows a large gap between these traces suggesting that the P Term needs to be increased (which was 1.8x in this scenario).
Too much P term …
In the following scenario, although Gyro is tracking Setpoint very well, it overshoots at the exit of the flip. This would suggest too much P term (which was 2.1x in this scenario).
Create a file folder for each tuning flight scenario containing the respective blacbox log, video file, and screenshots. The following reflects two D term scenarios each with four P term runs.
Flight controllers with onboard blackbox memory will only create separate blackbox log files if the quad is power cycled. Instead, a single file containing all logs is created. Those with SD card memory will save blackbox logs as separate files if blackbox logging is switch activated without the need of power cycling.
The four image files in the top-level folder show the P scenarios for a given axis (roll or pitch) and a D starting point to facilitate scenario comparisons.
It’s the ratio that matters …
Once the optimal P term has been determined for the respective D term scenario, note the ratio. Changes can be made to the P term (e.g., change in motor KV) and D term (e.g., props damaged) provided that the ratio remains the same. For example, a tuning run yielded the following optimal P and D terms:
However, the pilot determined that while motors ran cool at D=40, they ran too hot at D=45. The pilot selects D=42 to provide some cushion while still getting the most out of the D term. The midpoint of the P term multiples are used to arrive at the P term. The following would be the selected P and D terms:
Roll: D=42 at 1.71x P=72
Pitch: D=42 at 1.83x P=77
Bring on the D-Min …
Once the optimal D term is determined, reactivate D-Min. This allows for a dynamic D term to be used depending on the situation increasing or decreasing D as needed. Note that for the majority of a flight, the D term will be closer to the D-Min.
On the PID Tuning tab, turn on D-Min:
Gain = 15
Advance = 0
Set D-Min to the selected D term for pitch and roll.
Set D-Max equal to the selected P term for pitch and roll (re-enter D-Min after this step).
I Term & Yaw
Generally, you can leave these at default settings for most builds.
The I term should inform very little of normal course flight and therefore does not require exhaustive PID tuning. The I term is meant to offset external disturbances such as physical objects and wind gusts. As such, the I term was never intended to react as quickly as the P term. In situations where the P term is insufficient, the I term will take over and a slow bounce back will manifest as a result of it being asked to do what it was never designed to do. This is known as I term induced oscillations and is often mistaken as high frequency P term oscillations. If misidentified as such, reducing P term serves only to worsen the problem. Note the I term trace below (cyan) practically unmoved throughout the execution of this sharp roll.
Now note the I term trace below completely take over when the quad bumps the ground.
Unlike pitch and roll which are based on thrust vectoring dictated by the propellers, yaw is based on the inertia generated by propeller rotation. Therefore, yaw will inherently be too slow to overshoot Setpoint. This essentially negates the need for exhaustive PID tuning on the yaw axis.
Feed Forward Tuning
PD tuning alone will tighten the gap between gyro and setpoint only so far. The remaining difference can be tightened further using Feed Forward.
The same bracketing approach is applied to determine the optimal Feed Forward settings for both pitch and roll. Perform four tuning flights with Feed Forwards starting at 125 or 150 increasing at increments of 25 (e.g., 125, 150, 175, 200).
Too little Feed Forward …
At this starting feed forward of 125, there remains some lag beteen gyro (blue) and setpoint (orange) throughout the execution of this roll.
Too much Feed Forward …
At a far more aggressive Feed Forward of 200, gyro overshoots setpoint through drastic transitions while executing this roll.
As was done for PD tuning, create folders for each Feed Forward tuning flight scenario containing respective the blackbox log, video file, and screenshots.
The image files in the top-level folder depict all four Feed Forward scenarios for each of pitch and roll for ease of comparison.
Betaflight 4.2 introduced refined Feed Forward algorithms designed for specific flying styles which can set via CLI commands:
Freestyle: set ff_interpolate_sp = averaged_3
Racer: set ff_interpolate_sp = on
Cine: set ff_interpolate_sp = averaged_4
Congratulations! Once the optimal Feed Forward is selected for each of pitch and roll, the tuning process is complete.
Fly hard, fly fast.
73
This tuning guide is meant for informational purposes only. The author of this guide or any authors referenced in this guide hold no responsibility for damages resulting from actions taken by the reader from this guide.
Betaflight Blackbox Tuning Guide
Updated on February 16, 2022
Why do we tune? We tune to get more responsiveness out of our quad. What does responsiveness mean? It means getting our quad to do what we want as accurately and as quickly as possible. Therefore, the goal of tuning is to ensure the accuracy of and minimize the timing lag between our radio stick commands (“setpoint”) and what our quad is doing (“gyro”). In blackbox speak, we want our gyro to track setpoint as closely as possible.
This guide is a holistic, step-by-step process involving 12 flights covering filter, PID, and feed forward tuning. The approach has been used to good effect on 150mm (3 inch) to 350mm (7 inch) class quadcopters. Notwithstanding, this guide is just that – a guide. Use it as a framework, modified to suit your needs. Lastly, this guide is not meant to be an in-depth discussion of filter and PID theory.
The topics covered in this guide include:
This guide assumes you …
This version of this guide is based on Betaflight v4.2.3, Configurator v10.7.0, and Blackbox Explorer v3.5.0.
This guide makes use of general rules of thumb which typically apply to most builds. However, you are encouraged to deviate from these generalities if there is a valid reason to do so. In particular, quads smaller than 150mm or larger than 350mm will likely require a modified approach.
Filter Discipline
The first step is to set up the filters. A significant amount of filtering is achieved by the Dynamic Notch and RPM Filters, so we will be disabling most other filters. A good frame and a good build should not require so much filtering. This is filter discipline.
In the Configuration tab:
In the PID Tuning tab under Filter Settings:
Turn off all other filters (ignore warnings). This is what your filter settings should look like:
It is important to note that while these filter settings are aggressive, they are reasonable to the extent that your build has a reasonably low noise profile. If you are finding that your motors are running hot regardless, you may need to re-activate filters which were disabled above. In such a case, enable the sliders and adjust accordingly to your observed motor operating temperatures. As a general rule of thumb, if the motors are too hot to hold, they are likely operating above acceptable temperature ranges.
Blackbox Settings
On the Blackbox tab:
Pre-Tune Settings
These settings serve to disable software assists and PID sum limits to make it easier to isolate changes in PID tuning.
On the PID Tuning tab under I Term Relax:
The following CLI commands will reset PID settings, disable D-Min and Feed Forward, as well as certain assists:
The PID tab should now look like the following:
P/D Tuning
That was not a typo. The focus is on the P and D terms only. This process involves “bracketing” P and D terms to determine the optimal levels.
It all starts with the D term …
The starting D term is based on your power system (lipo cell count):
Note that this is generally independent of the quad size. You would use the same starting D term range for a 150mm (3 inch) build and a 350mm (7 inch) build both using a 4S lipo based power system. The difference will be in the relationship between the P and D terms.
The D term is a noise amplifier…
If your motors become too hot to hold even on the low end of the starting D term range based on your power system, you may have an inherently noisy build. As discussed earlier, the gyro_scaled blackbox debug trace reflects your build’s noise profile before any filtering. A clean gyro_scaled spectrograph will look similar to this:
Noise in the gryo_scaled spectrograph that manifests between the low frequency noise (approx <25Hz) and motor harmonics (approx 200Hz) will typically burden the gyro and necessitate more filtering. In such cases, insufficient filtering will result in motors overheating beyond operating temperatures. In essence, the gyro will need to work more and may cause the motors to spin in an erratic behavior resulting in the excessive heat. Additional filtering will mitigate the noise reaching the gyro but will also introduce latency in the process since additional calculations are being required.
Bracketing the P/D …
In this next step, you will be choosing a range of two starting D terms and performing four tuning flights with incrementally higher P terms for each of the two D term scenarios. Each run should include at least a roll left and right, a forward and back flip, and 180-degree hard turns for a total of eight tuning runs.
For example, for a 4S build, the selected D terms are 40 and 45. The following tuning runs would be performed. Note that the multiple ranges and P term increments are for illustrative purposes only and may be altered so suit your preference.
Open each tuning run scenario in Blackbox Explorer and enable these traces for pitch and roll:
Make Gyro and Setpoint traces bold since these will be of particular focus. For each scenario, take a screenshot of a representative pitch and roll.
Too little P term …
Each progressively higher P Term scenario for a given D Term should depict a closing gap between the Setpoint and Gyro traces. The following screenshot (Setpoint is orange while Gyro is blue) shows a large gap between these traces suggesting that the P Term needs to be increased (which was 1.8x in this scenario).
Too much P term …
In the following scenario, although Gyro is tracking Setpoint very well, it overshoots at the exit of the flip. This would suggest too much P term (which was 2.1x in this scenario).
Create a file folder for each tuning flight scenario containing the respective blacbox log, video file, and screenshots. The following reflects two D term scenarios each with four P term runs.
The four image files in the top-level folder show the P scenarios for a given axis (roll or pitch) and a D starting point to facilitate scenario comparisons.
It’s the ratio that matters …
Once the optimal P term has been determined for the respective D term scenario, note the ratio. Changes can be made to the P term (e.g., change in motor KV) and D term (e.g., props damaged) provided that the ratio remains the same. For example, a tuning run yielded the following optimal P and D terms:
However, the pilot determined that while motors ran cool at D=40, they ran too hot at D=45. The pilot selects D=42 to provide some cushion while still getting the most out of the D term. The midpoint of the P term multiples are used to arrive at the P term. The following would be the selected P and D terms:
Bring on the D-Min …
Once the optimal D term is determined, reactivate D-Min. This allows for a dynamic D term to be used depending on the situation increasing or decreasing D as needed. Note that for the majority of a flight, the D term will be closer to the D-Min.
On the PID Tuning tab, turn on D-Min:
I Term & Yaw
Generally, you can leave these at default settings for most builds.
The I term should inform very little of normal course flight and therefore does not require exhaustive PID tuning. The I term is meant to offset external disturbances such as physical objects and wind gusts. As such, the I term was never intended to react as quickly as the P term. In situations where the P term is insufficient, the I term will take over and a slow bounce back will manifest as a result of it being asked to do what it was never designed to do. This is known as I term induced oscillations and is often mistaken as high frequency P term oscillations. If misidentified as such, reducing P term serves only to worsen the problem. Note the I term trace below (cyan) practically unmoved throughout the execution of this sharp roll.
Now note the I term trace below completely take over when the quad bumps the ground.
Unlike pitch and roll which are based on thrust vectoring dictated by the propellers, yaw is based on the inertia generated by propeller rotation. Therefore, yaw will inherently be too slow to overshoot Setpoint. This essentially negates the need for exhaustive PID tuning on the yaw axis.
Feed Forward Tuning
PD tuning alone will tighten the gap between gyro and setpoint only so far. The remaining difference can be tightened further using Feed Forward.
The same bracketing approach is applied to determine the optimal Feed Forward settings for both pitch and roll. Perform four tuning flights with Feed Forwards starting at 125 or 150 increasing at increments of 25 (e.g., 125, 150, 175, 200).
Too little Feed Forward …
At this starting feed forward of 125, there remains some lag beteen gyro (blue) and setpoint (orange) throughout the execution of this roll.
Too much Feed Forward …
At a far more aggressive Feed Forward of 200, gyro overshoots setpoint through drastic transitions while executing this roll.
As was done for PD tuning, create folders for each Feed Forward tuning flight scenario containing respective the blackbox log, video file, and screenshots.
The image files in the top-level folder depict all four Feed Forward scenarios for each of pitch and roll for ease of comparison.
Congratulations! Once the optimal Feed Forward is selected for each of pitch and roll, the tuning process is complete.
Fly hard, fly fast.
73