A PID tune is a claim about how an aircraft responds to a stick input. Most
tuning advice is a table of defaults applied to a quad nobody measured. The
blackbox log is the measurement — but only if you know which part of it answers
which question.
Two analyses do most of the work: the spectrum and the step response. They answer
different questions, and they fail in different ways.
The spectrum: a peak is not a diagnosis
A gyro trace is a time series, and a time series has a spectrum. Welch's method
cuts the trace into overlapping windows, applies a window function to each (Hann
is the standard choice), takes an FFT, and averages the squared magnitudes. The
averaging is the point. One FFT over a whole flight smears the result, because
throttle — and therefore motor RPM — changes during the recording. Welch trades
frequency resolution for a stable estimate of where energy lives.
What matters is not that a peak exists. It is how the peak behaves while
throttle changes.
A narrow peak whose centre stays at the same frequency from hover to full
throttle is consistent with a structural mode: a frame, an arm, a standoff, a
camera mount. A static notch is meaningful for a tone that does not move, but a
notch does not remove the mode; it hides it from the loop. That distinction
decides whether you spend the afternoon on screws and carbon or in the filter
tab.
A ridge that climbs with RPM, usually with evenly spaced copies at higher
frequencies, is motor and propeller blade-pass energy, with airflow adding to the
broadband floor underneath. A fixed notch is the wrong instrument here: the
energy leaves the notch as soon as the throttle moves. That
is the mechanism an RPM-tracking filter exists for — the dyn_notch_* family in
Betaflight, rather than one static cutoff.
A broad raised floor with no dominant peak is not a mode at all. It is many
small sources at once: a damaged prop, a dirty motor, a hard-mounted flight
controller, wiring that rattles. Point that at hardware. No filter setting fixes
a loose screw.
And a peak at a particular frequency is not a diagnosis on its own. A motor
harmonic, a frame mode, a camera mount and a loose screw can all put energy in
the same bin. The FFT measures energy, not cause. Which axis it appears on,
whether it has harmonics, and whether it survives a prop swap are what turn a
measurement into a hypothesis.
The step response: two faults that feel identical
A step response isolates one fast stick movement and asks a narrow question: how
closely did the gyro follow the setpoint? Normalise both curves over the window
and two features become visible, and they are not the same fault.
Overshoot is the response going past the commanded value and coming back. The
peak sits above the setpoint line. That is a damping and phase problem around the
loop: too much gain for the phase margin available, or a filter delay eating
margin that the gains assume is there. The answer lives on the P/D side of the
loop.
Droop is different. The response rises, then levels off below the commanded rate
while the stick is still held. It never arrives. The loop is stable; it simply
lacks low-frequency authority. That is I-term territory, and it is not fixed by
the same change that fixes overshoot. Push gain into a drooping response and you
can trade a lag for an oscillation.
In the goggles these feel the same: the quad does not do what you asked. A single
"tune quality" score averages them into a meaningless middle. A quad can overshoot
on roll and droop on pitch in the same flight, and the two axes need opposite
corrections.
The hard part is refusing to answer
The FFT is textbook. A step-response estimator is a few hundred lines. The
engineering problem is deciding when the log cannot support a decision, and then
saying so out loud.
A step response needs excitation. A hover-only flight contains no step. A flight
of rolls and flips may give usable roll evidence and no clean pitch step, because
flips couple the axes and often end near motor saturation. A short log gives an
average too unstable to trust. A gyro dominated by a damaged prop produces a best
fit that is a fit to noise. A missing rcCommand channel, or a header sample rate
that disagrees with the timestamps, moves the entire frequency axis.
In each of those cases the correct output is "not enough data". Not a
conservative-looking guess with a confidence badge. The failure mode that matters
is not a wrong estimate; it is an estimate that looks like an answer. A blank
measurement in a lab notebook is honest. A curve drawn through noise is not.
That is why a usable report includes what it could not measure: which axis had no
clean step, which maneuver is missing, whether the log is Chart-ready, Partial or
Not safe to tune from, and why. Refusing is a threshold with a reason attached,
not a mood. It is also the hard part to test: the interesting cases are the ones
where the data is almost good enough.
Betaflight ships defaults, and they are a reasonable place to start. They are not
a measurement of your airframe. The log is.
I built Easyquadtune around that constraint: a Welch PSD over the gyro for the
noise peaks, a per-axis step estimate that reports overshoot and steady-state
ratio separately, and a CLI diff for Cine, Freestyle and Race. It labels a log
Chart-ready, Partial or Not safe, and it says when it cannot answer.
Worked demo with the actual arithmetic, no signup:
https://easyquadtune.vercel.app/?view=demo
The demo is an illustrative render, labelled as such in the app — not a customer
log. The longer writeup is here:
https://easyquadtune.vercel.app/guides/betaflight-blackbox-tuning.html
Top comments (0)