How to Read a Betaflight Blackbox Log
The blackbox is the flight recorder of your quad. Once you can read it, PID and filter tuning stops being guesswork. This guide walks through the traces that matter and what each one tells you.
1. Get the log off your quad
Betaflight records to onboard flash or an SD card. Download it from the Blackbox tab in Configurator (or pull the SD card) — you'll get a .bbl/.bfl file. Drop that file into Drone PID Helper and it decodes and analyses it locally, in your browser. Nothing is uploaded.
2. Gyro vs setpoint — the tracking trace
This is the single most useful view. Setpoint is what you (via the sticks) asked the craft to do; gyro is what it actually did. A good tune has the gyro line hugging the setpoint with only a small delay. Large gaps mean sluggish response (P/FF too low); the gyro crossing back and forth over the setpoint means oscillation (often too much P or not enough D).
3. PID error and the D-term
Error is the difference between setpoint and gyro — you want it small and quick to settle. The D-term resists rapid change; it's what damps overshoot, but it also amplifies noise. If the D-term trace looks fuzzy and hot, your filters are letting too much gyro noise through — that heats motors and can cause the classic hot-motor problem.
4. Motor outputs
The four motor traces should move smoothly and stay off the rails. If motors are constantly hitting 100% (saturating), the flight controller has no headroom left to correct — expect washout in fast moves. Constant high-frequency jitter on the motor outputs is noise being fed straight to the ESCs.
5. Noise and the FFT / spectrogram
An FFT turns the gyro trace into a frequency spectrum so you can see where the noise lives. A sharp peak that climbs with throttle is usually a motor/prop resonance the RPM filter or dynamic notch should catch. Broadband haze across the whole spectrum points to mechanical problems (bent prop, worn bearing, loose frame) that no filter will fully fix. See the filter tuning guide.
6. Step response
The step response is a derived view of how the craft reacts to a sudden stick input: rise time, overshoot, and how fast it settles. Fast rise with a small (5–15%) overshoot that settles cleanly is a healthy, responsive tune. A big overshoot that rings is too little D or too much P; a slow, lazy rise is an under-damped, under-powered tune.
Turn reading into fixes
Reading the log tells you what's wrong; the next step is knowing which numbers to change. Drone PID Helper reads all of the above automatically and hands you concrete PID/filter suggestions with a ready-to-paste CLI diff.