Tuning guide

How to read a Betaflight blackbox log

Most tuning advice is a table of defaults applied to a quad nobody has measured. Your blackbox log is the measurement. This is what it contains, what the FFT and the step response actually tell you, and which of the two faults you should fix first.

1. What is actually in the log

A blackbox log is a time series, not a verdict. Four groups of channels matter for tuning:

• Gyro — what the frame actually did, in deg/s. The gyro sees propeller noise, frame resonance and every oscillation.
• Setpoint — what your sticks asked for. In acro this is your stick input after rates and expo.
• PID terms — the P, I, D and FF contributions per axis. This is where you see why the quad fell short, not just that it did.
• Motors and eRPM — motor output per motor, and RPM data if your ESC sends it. Motor divergence is the clearest sign of too much D.

The log header also carries the PID and filter values that were active during the flight. That matters more than it sounds: a tune is only meaningful relative to its starting point, and a log without its header cannot be tuned from.

2. The FFT: which frequencies are actually noisy

The gyro trace is a signal, and a signal has a spectrum. Take the gyro from one axis, cut it into overlapping windows, apply a window function (Hann is the usual choice) to stop the edges from inventing frequencies, and average the magnitude spectrum of each window. That is Welch's method, and it is what every serious log analyser computes.

Two numbers define the resolution, and both come straight from the log:

• bin width = sample rate / window size — how finely frequency is divided.
• Nyquist = sample rate / 2 — the highest frequency the log can represent at all.

At a 1.72 kHz sample rate with 512-sample windows, each bin is about 3.36 Hz wide and the spectrum stops at 859.75 Hz. Nothing above that exists in your log, so a "peak" reported at 1.2 kHz would be an artefact of the analysis, not your quad.

Reading the peaks

A peak is only interesting if it stands well above the noise floor around it. Then its behaviour tells you what it is:

Peak	How it behaves	What it is
Moves with throttle	Its centre frequency rises as RPM rises	Motor and propeller noise
Fixed frequency	Same centre regardless of throttle	Frame or arm resonance
Very low	Broad, below ~40 Hz	Control oscillation, not noise

That distinction is the whole point of doing the FFT. A filter set for a fixed frame resonance will not help a motor-noise peak, and turning the gyro lowpass down to treat an oscillation that is really a gain problem costs you phase margin for nothing. If the frequency does not move with throttle, filtering harder is not the fix.

3. Step response: the two faults that look alike

A step response isolates one fast stick movement — a flick — and asks a simple question: how closely did the gyro follow the setpoint?

Align the step, slice out a couple of hundred milliseconds, and you can measure four things:

• Rise time — how long to get from 10% to 90% of the step.
• Overshoot — how far past the target it went.
• Settling time — how long until it stops moving around the target.
• Tracking error (RMS) — the average distance between gyro and setpoint across the window. This is the honest global score.

Overshoot versus settling below commanded

These are the two faults that get confused constantly, and they need opposite corrections:

What you see	What it means	Direction
Overshoots the setpoint, then rings back	Too much gain for the phase you have left	Reduce D first, then P
Settles below the commanded rate and stays there	Steady-state error: not enough I, or I is being relaxed away	Raise I, check iterm_relax

A single "tune quality" number hides this. A quad can overshoot on roll and droop on pitch in the same flight, and one global score would average those into a meaningless middle. Per-axis, per-fault reporting is the only version you can act on.

Droop has a second common cause worth knowing: iterm_relax deliberately bleeds I off during fast stick movements to stop I from fighting your flicks. Set too aggressively it bleeds more than intended, and the quad sags out of turns. If your log shows droop only during the fastest inputs, look there before adding I.

4. Why the airframe is a constraint, not an input

Frame size, all-up weight and motor KV are useful, but not for the reason most tools use them. They do not tell you what your tune should be.

What they do tell you is what is physically plausible. A 5-inch quad at 650 g cannot meaningfully use the same motor output limit as a 3-inch at 250 g, and a 6S build with high KV will saturate differently from a 4S build with low KV. Those are bounds. They are not answers.

The distinction matters because a craft profile that selects a tune is really a table of defaults with extra steps: it will confidently produce the same numbers for two quads with identical frames and completely different flight behaviour. A profile that only rejects a value — "this gain is not plausible for this airframe" — leaves the decision with the data, where it belongs.

5. The order that actually works

1. Check the log is worth tuning from. Props intact, one battery, a flight with real flicks on all axes. A hover-only log cannot show you a step response, and no amount of analysis will fix that.
2. Find the noise peaks. Fixed or throttle-dependent, and how far above the floor.
3. Set the filters. Only as low as the peaks justify. Filtering below the noise buys nothing and costs phase.
4. Judge the step response per axis. Overshoot and droop separately.
5. Change one family at a time. Filters, then D, then P, then I, then FF. Re-log after each change.
6. Verify by flying. A hover test, a motor temperature check and a second log. The log said what it said; the motors still get a vote.

6. Mistakes that ruin an otherwise good tune

• Changing several things at once. Then you learn nothing from the next log.
• Comparing logs from different batteries or props. You changed the plant, not the controller.
• Tuning a damaged prop. Impossible to filter out and it looks like a frame resonance.
• Judging from one axis. Roll and pitch rarely need the same correction.
• Chasing a low tracking error on a soft tune. A sluggish quad tracks smoothly and feels terrible.

More on the questions this guide raises

• Why a quad wobbles on hard stops — separate idle instability, I-term bounce, propwash and excess gain.
• Overshoot vs droop — the two step-response faults that need opposite answers.
• Frame resonance vs prop noise — fixed tones, moving ridges and what the FFT cannot name.
• I-term relax — why the cutoff moves opposite to intuition, and when relax causes droop.
• Dips in fast turns — yaw washout, pitch droop, saturation and voltage sag.
• When a log cannot support a tune — the missing evidence behind a flat chart.

Easyquadtune is not affiliated with the Betaflight project. Always fly responsibly and perform an initial hover test in a safe environment after any tuning change. The worked example on this site is an illustrative render, not a customer log.