How to Read a Blackbox Log: From Squiggly Lines to a Diagnosis

You open a log in Blackbox Explorer and get thirty traces. Explorer shows everything the flight controller recorded; the conclusions are yours. Below: a seven-step manual read, then one real log with every bbdoctor finding, its numbers and how to check it by eye, and when automation has to say "I don't know".

Tools for reading a log

They don't compete: Explorer studies one second of the flight, automation tells you which second and what to change.

Reading a log by hand in 7 steps

Field names as stored in the log. Index 0 is roll, 1 pitch, 2 yaw. In Explorer, View → Analyser (or the A key) opens the spectrum analyser; then click a trace in the legend.

1. Timeline and modes. One file can hold several flights, one per arm. Check flightModeFlags: PID response reads far worse in ANGLE and HORIZON than in ACRO. rcCommand[3] shows hovers, chops and punch-outs. Don't trust spectra across logging gaps.
2. Gyro vs setpoint on flips. gyroADC[0] and setpoint[0] together. Gyro past the target: overshoot. Wobble after the stick stops: low damping or bounce-back. Trailing 20–30 ms behind: sluggish. Add axisP[0], axisD[0], axisF[0] to see which term pushes the quad.
3. Motors. motor[0..3]. 100% on a full-throttle punch or briefly on a snap flip is fine; pinned there through moves at mid throttle means no headroom. A motor parked at idle after a chop is a common propwash cause. One pair higher than the other all through a hover points to the CG.
4. Spectrum before and after filters. gyroUnfilt against gyroADC. Above about 80 Hz it's noise, not flying. What survives the filters goes into the PIDs and heats the motors.
5. Frequency against throttle. A diagonal moving right with throttle is motors and props. A vertical band at every throttle is the frame, stack or an antenna (fig. 1).
6. I-term in a hover. axisI[0] and axisI[1] should wander around zero. One that holds a value all flight is compensating for an imbalance: CG, a tilted or tired motor.
7. Voltage and current. vbatLatest and amperageLatest: sag per cell on current peaks, voltage at the end. Voltage step over current step is a rough internal resistance.

Steps 4 and 5 need a fast enough log: anything above half the logging rate folds into fake peaks. Setup: blackbox setup guide.

One real log, start to finish

The public log behind the sample report: Betaflight 4.5.2, SpeedyBee F405 Mini, 4S, a 3.5-inch judging by the craft name VX3.5. 110 s of log, 107 airborne, all ACRO. Gyro 8 kHz, PID 4 kHz, logging 1 kHz with raw gyro and eRPM. Of the report's 20 items, here are the main ones and where each number comes from.

Rear motors loaded 50% more: the CG

Average command: rear M1 and M3 28.7%, front 19.2%. Over 12% is a warning, over 30% critical. Confirmation: the pitch I-term median is 45, not near zero, so the controller adds rear thrust all flight. Usually the battery or camera sits too far back; otherwise it's lots of fast forward flight, and a calm hover shows almost no gap. Not a PID problem: move the battery until the quad hangs level on your fingers under the frame's centre.

Roll: 36% overshoot, caused by feedforward

Roll step response: 36% overshoot (90% interval 29–44%), from 165 usable one-second windows (overlapping) of 372 with stick movement; half the requested rate in 8 ms. Lower bound above 15%: a finding. But the advice isn't "lower P" or "raise D". On fast stick moves feedforward does 60% of the work (FF against P), and the gyro runs on average 3 ms ahead of the setpoint: FF is dragging the quad. So only FF changes: f_roll 120 → 102, 15% off your header value, P and D untouched. If overshoot remains only on snappy flips, next comes feedforward_boost 15 → 8. Pitch, same story: 28% (23–37%), FF 56%, f_pitch 125 → 106.

set f_roll = 102
set f_pitch = 106
set simplified_pids_mode = OFF
save

Why simplified_pids_mode: this log's PIDs don't match the sliders, and the Configurator would overwrite them on the next save.

By eye you won't see 36%: here the peak is only 22 deg/s (9%) over target. Step response is the reaction to an ideal instant step, deconvolved from 165 windows; a real stick input is a ~100 ms ramp. The ramp shows the same thing another way: gyro ahead of setpoint, FF spikes nearly five times P. More in PID tuning from blackbox.

Raw noise 4.1 deg/s: mechanics, not filters

Raw gyro noise above 80 Hz: roll 4.1, pitch 2.4, yaw 2.5 deg/s, just over the 4 deg/s warning line. Filtered: 0.53 deg/s at about 1.4 ms delay, and the report calls the filters fine. So leave them and check props, bearings and stack mounting. 1× vibration per motor is even (M1 1.1, M2 0.5, M3 1.8, M4 1.9 deg/s), and RPM at equal command differs by 1.9% at most. Hunting a bad motor when the spread is large: motor vibration guide.

Motors up to 610 Hz, logged at 1 kHz

eRPM shows motors up to 610 Hz, but a 1000 Hz log sees only up to 500; above that, frequencies fold down, so 610 Hz shows at 390. The per-motor analysis copes (it uses rotation phase from eRPM), but the spectrum and resonance frequencies are ambiguous. The fix:

set blackbox_sample_rate = 1/2
save

FF jitter from the radio: 2.1% of motor range

While the sticks move, FF above 40 Hz (a kick on every radio step) is 2.1% of motor range on roll, 1.7% on pitch, with 34 and 28 kicks per second over 5%. Useful FF below 12 Hz: 1.5 and 1.2%. Sticks still: 0.40%, so stick steps are the source. Link 494 Hz, stick smoothing 185 Hz. FF makes 89% of the high-frequency PID output noise, D 10%, so don't lower D or D-term filters for it; that only adds delay. Lower FF first, smooth it next flight:

set feedforward_averaging = 2_POINT
set feedforward_smooth_factor = 65
save

The D boost barely kicks in

Configured: d_min_roll = 30, d_roll = 45, boost up to ×1.50. bbdoctor measures the real multiplier from the logged D-term (slope of axisD against the gyro derivative at 8–40 Hz, 0.25 s blocks, TPA removed). On the sharpest moves D reaches only ×1.06 on roll, ×1.04 on pitch. You fly on d_min, so change damping via base D (the Derivative column), not D Max. In 2025.12 the names follow the UI (base d_roll, ceiling d_max_roll); see the PID tuning guide.

Propwash 1.1 deg/s: fine

A chop: throttle drops over 25% of travel within 0.15 s from above 35%. There are 46; two rolled straight into a flip, and bbdoctor drops those since stick motion produces the same 15–80 Hz. Over 44 clean chops, gyro minus setpoint at 15–80 Hz, 0.08–0.6 s after the chop: 1.1 deg/s RMS, mostly ~20 Hz; normal is up to 4. Nothing to fix; see the propwash guide if it still bugs you.

Battery: 3.23 V per cell at 72 A

Started at 3.84 V per cell, not full. Sustained minimum (over 0.5 s) 3.23 V, peak 72 A, 3.66 V at the end, about 248 mAh. Internal resistance ≈ 7 mΩ per cell from 182 sharp current changes, wiring included. The pack is at its limit: warning.

The rest

• Setpoint-to-rotation delay: roll 4.1 ms, yaw 4.6 ms (normal with FF: 4–12 ms), plus 1.3 ms radio to setpoint; pitch: no reliable value.
• 34 punch-outs: within 0.4 s the quad tilts 2.5° on pitch, 0.5° on roll; normal is under 3°.
• Too few sharp stops (roll 2, pitch 1, 6 needed): bounce-back unchecked.

How to verify each finding in Explorer

Why some findings say "not enough data"

With thin data, an analyser must stay quiet or it confidently recommends nonsense. bbdoctor's minimums:

Example: a Betaflight 4.2.5 log (2 kHz, 4S, 215 s airborne) has 15 chops, but 12 roll straight into a flip or roll. Averaged, "propwash" is 18.4 deg/s: critical (threshold 10). Per chop it runs from 1.4 to 58.6 deg/s, the big numbers being the flips. The three clean chops: 1.8 deg/s, normal. A tool that keeps maneuvers would have you raising D and idle on a quad with no propwash.

Second safeguard: "method bias already subtracted". Deconvolution shows a little overshoot even for a perfect response, especially when setpoint isn't logged and is rebuilt from the sticks. bbdoctor runs the same calculation on a setpoint shifted by the same delay and subtracts it. A Betaflight 4.5.1 log without setpoint (801 Hz, 6S): pitch 29% raw overshoot, 9% of it bias, reported as 20%. On yaw the raw 9.6% was all bias: no overshoot.

How to tell whether to trust the numbers

• Intervals. The response is computed per one-second window and overshoot read off the median curve; the 90% interval comes from resampling the windows and recomputing the curve 200 times (bootstrap). "36% (29–44%)" means even the low estimate is above 15%.
• Verdicts. Lower bound above 15%: a finding with commands; above 35% with 50+ windows: critical. Estimate up to 15% with the upper bound under 25%: normal. A narrow interval just above normal is "borderline", nothing to change (roll on that 4.5.1 log: 17%, 15–24%). A wide one is "uncertain": fly 5–6 more maneuvers.
• Cross-checks. Noisy motors or noise through D: no advice to raise D. FF doing 45%+ of the work with P adding little: FF gets cut, not P.
• No invented overshoot. A hard deconvolution cutoff (25 Hz, as in PID-Analyzer) adds about 10% fake overshoot (Gibbs effect). bbdoctor uses a 30 Hz Gaussian kernel instead; on synthetic logs a pure delay gives 0%, damping ζ = 0.5 gives 15% against a true 16%.

Workflow: one change per flight

1. Record 1–2 minutes in ACRO: hover, smooth turns, 5–6 chops, 6–8 flips and as many rolls with a sharp return to centre, 6–8 punch-outs with the sticks still.
2. Upload it to the online blackbox analyzer. Start with critical items and mechanics; tuning PIDs on an unbalanced frame with chipped props is pointless.
3. One change per flight. Here: battery, then FF, then FF smoothing. blackbox_sample_rate can ride along with any step, since it doesn't affect flight. Props off when configuring on battery.
4. Same props, a similar pack at similar charge, the same flying style.
5. Use "Compare analyses" under your history. Overlapping 90% intervals before and after mean "no change"; flights of different style (average throttle 10% of travel or more apart, or one three times longer) get flagged.

Limitations

• INAV and EmuFlight don't log per-motor RPM, so no per-motor vibration or RPM comparison. See INAV blackbox analysis.
• ArduPilot and PX4 log the gyro slowly by default; spectra, step response and propwash need about 200 Hz. ArduPilot: bit 19 (IMU_RAW) in LOG_BITMASK and INS_RAW_LOG_OPT = 9 (4.5+); PX4: SDLOG_PROFILE bits 4 (High rate) and 8 (Raw FIFO gyro). Details: ArduPilot, PX4.
• Rotorflight helicopters: no motor balance checks, no critical verdicts, PID response for information only.
• ArduPlane, Rover, Sub and PX4 fixed-wing logs aren't accepted; simulator (SITL) logs skip hardware and battery checks.
• Thresholds are tuned on Betaflight FPV quads; on bigger drones treat them as rough and compare with the same craft's earlier logs.
• Gaps alone are fine (analysis uses the continuous stretches). A damaged log (10%+ of frames dropped, or corrupt frames with frequent gaps) drops PID, noise and resonance findings to info, without commands.

Next, by problem: noise and filters, propwash, PIDs from the step response.

Updated: 2026-10-22