How to read a Blackbox log

Why you should care

Your memory of a flight is a story you tell yourself. It is assembled after the fact, out of what you expected to happen and what you felt through the sticks, and it is wrong far more often than you would like. The log is not a story. It is a recording, at hundreds or thousands of samples a second, of what the gyro measured and what the controller did about it.

Look at the questions in the rest of this knowledge base. Is that wobble P or D? Is the buzz mechanical vibration or a control-loop oscillation? Is the aircraft under-tuned or simply out of thrust? Is that one hot motor a bearing or a bent arm? Every one of those is answered in a log, and none of them is answerable without one. Everything else is guessing with confidence.

Getting a log

Blackbox logging is built into Betaflight and iNAV. Two things to sort out.

Where it writes. Most flight controllers have onboard flash; some have an SD card slot. If you have a card slot, use it — it is faster, bigger, and you pull the card rather than waiting on a slow serial download. Onboard flash works fine, but it fills up and it must be erased between sessions, and people routinely fly a whole battery with a full chip and no log to show for it.

How fast it writes. The logging rate is configurable, and it is a real trade-off. A high rate gives you the resolution to see high-frequency oscillation and to run a useful spectral analysis; but a high rate can outrun the write speed of slow onboard flash, and you get dropped frames — gaps in the data that will quietly lie to you, especially in the frequency view. If your logs look corrupted or your spectrum looks strange, suspect the logging rate before you suspect the aircraft. Card users can generally afford full rate. Flash users often cannot.

Then fly the manoeuvre that shows the problem. This is the part people skip. A gentle hover tells you almost nothing about a fault that only appears in a hard descent. Arm, do the specific thing that goes wrong, do it two or three times, land, download. A thirty-second log of the actual problem beats a five-minute log of general flying.

Open it in the Betaflight Blackbox Explorer, which is the standard tool. iNAV maintains its own fork of the Explorer, because the two firmwares log different fields — use the one that matches your firmware rather than assuming either will read the other's logs. PIDtoolbox is a well-known third-party analysis tool that does more sophisticated step-response and spectral work; it is worth graduating to, but start with the Explorer.

The four traces that matter

A log has dozens of fields. You can ignore nearly all of them. Four carry most of the diagnosis.

Gyro — what the aircraft actually did

The gyro trace is the aircraft's measured rotation rate on each axis: roll, pitch, yaw. This is ground truth. Everything the flight controller believes about the world starts here, and every fault ends up visible here. Most logs let you look at both the raw and the filtered gyro; the gap between them is your filtering, and it is worth knowing how much of the signal your filters are actually eating.

Setpoint — what you asked it to do

The setpoint is the rotation rate the controller is trying to achieve — your stick input, run through your rates. It is the target. The gyro is the result.

The gap between setpoint and gyro is the error, and the shape of that gap is the entire diagnosis. If you learn one thing from this article, learn to look at those two traces overlaid on the same axis, and to read the space between them. Everything else is commentary.

PID terms — who is doing the work

The log can record the individual P, I and D contributions to the output. This tells you which part of the controller is responsible for what you are seeing. A large, ringing D contribution during a manoeuvre where nothing much is happening is D amplifying noise. A P term that is doing all the work while I sits near zero is a controller with no steady-state authority. An I term that grows and grows on one axis, in level flight, is the controller quietly holding out against something physical — a twisted motor mount, a bent arm, a genuinely asymmetric aircraft.

Motor outputs — whether the aircraft still has authority left

The four motor commands. These are the last thing the controller says before physics takes over, and they answer a question no other trace can: does the aircraft still have room to obey?

Reading the gap

Overlay setpoint and gyro on one axis. Do a flick — a fast, decisive stick input and release — and look at how the gyro chases the setpoint.

• It arrives late, lags behind, and never quite catches up. The controller is under-gained, or over-filtered, or both. Filtering is delay; every low-pass you add buys you cleanliness and pays for it in lag. Sluggish tracking with a clean trace is usually too much filter, not too little P.
• It overshoots and bounces. The gyro shoots past the setpoint and rings around it a few times before settling. That is classic too much P, or too little D to damp the overshoot. One or two small bounces is a normal, well-damped response. A decaying train of them is not.
• It never gets there at all. The gyro tops out well below the setpoint and stays there. Before you touch a single gain, go and look at the motors — see the next section. An aircraft that physically cannot rotate that fast is not a tuning problem.
• It tracks beautifully, but the trace is fuzzy. Good tracking with high-frequency fuzz riding on top is a noise problem, not a gain problem. Go to the spectral view.

Motor saturation

Look at the motor outputs. If any motor is pinned at its maximum, or pinned at its minimum, for any length of time, the flight controller has run out of authority. It is asking for more than the aircraft can give, and it cannot correct any further in that direction.

Say it plainly, because this is the single most commonly missed thing in log analysis: nothing downstream of a saturation event means anything. The wobble you are staring at, the overshoot, the oscillation that appears "when I pull hard" — if a motor was flat against the rail at that moment, you are not looking at a tuning fault. You are looking at an aircraft that has been asked to do something it cannot do, and the loop breaking down as a result. Retune all you like; you will not fix it, because it is not broken.

This matters enormously on heavy platforms. A 5 kg airframe that is under-propped, or flying at a hover throttle of 60% and above, has very little headroom left for the controller to work with. It will saturate on any aggressive input, and it will saturate on hard descents where it is fighting to arrest a sink rate. The fix is thrust — more prop, more motor, less mass — not gains, and often the honest fix is asking for a rate the airframe can actually deliver.

Check saturation first, before you interpret anything else. It invalidates the rest of the log.

Noise: the spectral view

The frequency analysis view is where you separate mechanical vibration from control-loop oscillation. These two look nearly identical in the time-domain gyro trace, and they have opposite fixes, which is exactly why why does my quadcopter shake is a whole article.

The rule of thumb:

• A peak that moves with RPM is mechanical. It slides up the frequency axis as you throttle up, because it is the motors — an unbalanced prop, a damaged bell, a dying bearing. Filtering can hide it. It will not fix it. Go and find the physical fault.
• A peak at a roughly fixed frequency, or a broad hump, that grows as you raise D, is the control loop. That is the loop oscillating against itself, and it is a gains-and-filtering problem, not a hardware one.

Fly a slow throttle sweep in a hover and watch which of those two you have. That one manoeuvre answers the question.

A short triage checklist

Open a log. Look at these things, in this order.

1. Motor outputs. Anything saturated? If so, that is the story. Stop, fix the thrust problem, fly again.
2. Setpoint versus gyro, on the axis that misbehaves. Late, bouncy, or absent?
3. The spectral view. Is the noise tracking RPM, or is it the loop?
4. The PID terms. Which one is doing the work, and which one is ringing?
5. The I term in level flight. Growing steadily on one axis? You have a physical asymmetry, not a tune.

One honest warning

Reading logs has a learning curve, and staring at a single log for an hour teaches you very little. The first genuinely useful skill is much simpler than it looks: fly the same manoeuvre twice, change exactly one thing between them, and compare the two logs side by side.

That comparison is worth more than any amount of interpretation of a single trace, because it removes the guesswork about what the trace should look like. You have a before and an after, and the difference between them is entirely attributable to the one thing you changed. That is not log analysis — that is an experiment, and it is the only way anybody ever learned to do this.