Every pilot has been there — you land a pack, something felt off mid-flight, and you have no idea if it was your P gains, a bent prop, or just the wind. Blackbox logging gives you the answer. It records every gyro reading, every PID calculation, every motor command your flight controller processes, and lets you replay it all on your computer.
Instead of the classic “feels twitchy, lower P” guessing game, you actually see P-term oscillation on the trace. Instead of wondering why your motors run hot, you see D-term noise amplification in the spectrum. Blackbox turns vague feelings into measurable data — and that data is what separates a decent tune from a dialed-in one.
This guide covers everything from initial setup to advanced frequency analysis, with real diagnostic examples you’ll actually encounter on the bench.
Note: This guide contains affiliate links. If you purchase through our links, we may earn a commission at no extra cost to you. This helps support our testing and content creation.
What Blackbox Actually Records
Your flight controller logs a comprehensive dataset at whatever rate you set (typically 2 kHz). Here’s what matters:
Gyro data — the actual rotation rates your FC measures on roll, pitch, and yaw axes. This is the ground truth of what your quad is physically doing.
Setpoint — the target rotation rate derived from your stick inputs. This is what your quad should be doing based on your commands.
PID outputs — the individual P, I, and D term contributions calculated by the PID loop. These show you exactly how each component responds to the error between setpoint and gyro.
Motor outputs — the actual commands sent to your ESCs. Critical for spotting motor saturation (when a motor hits 100% and can’t give more).
Battery voltage — logged continuously, useful for correlating performance changes with voltage sag under load.
RC inputs — your raw stick data, including any RC smoothing applied.
The real power isn’t in any single data stream — it’s in seeing how they all interact. When you spot oscillation in the gyro trace, you can check whether it’s P-term driven, whether D is reacting to it, and whether the motors are saturating trying to correct it. That kind of multi-layer diagnosis is impossible by feel alone.
Setting Up Blackbox in Betaflight
Configurator Settings
Open the Blackbox tab in Betaflight Configurator. Here’s what to set:
Logging device: Pick SD Card if your FC has a slot — you’ll get hours of logging on a 16GB card. Onboard flash works too but limits you to roughly 2-4 minutes at 2 kHz depending on your FC’s flash chip size. For serious tuning sessions, SD card is the move.
Logging rate: Set 2 kHz. This is the sweet spot recommended by most tuning experts, including the Betaflight dev team. At 2 kHz, you can observe vibrations up to 1 kHz in the spectrum analyzer — plenty for identifying motor noise, frame resonances, and filter effectiveness. If your FC runs a BMI270 gyro, you’ll be limited to 1.6 kHz, which is still fine for all practical analysis. Bump to 4 kHz only if you’re specifically doing deep filter work and have the SD card space.
Debug mode: For basic tuning and PID analysis, leave it at NONE — the default gyro and PID fields give you everything you need. If you want deeper insight into how your dynamic notch filters are tracking vibrations, set it to FFT_FREQ. This logs the frequencies where Betaflight’s dynamic notch is locking on, which is invaluable when using tools like PIDtoolbox.
The old recommendation of GYRO_SCALED debug mode is less relevant in modern Betaflight (4.4+), since the gyroUnfilt field is now logged separately, giving you the pre-filter gyro data without needing a special debug mode.
Disable unneeded fields to save space. Accelerometer data, GPS fields, and altitude aren’t useful for PID tuning. Uncheck them.
Click Save and Reboot.
SD Card Prep
Format your card as FAT32 — not exFAT, not NTFS. Use a Class 10 or UHS-I card minimum for reliable write speeds at 2 kHz. A 16-32GB card is more than enough. Leave at least 1GB free — some FCs get weird when the card is nearly full.
Transfer and delete old logs regularly. I keep a folder structure on my PC: Blackbox > [Quad Name] > [Date]_[Change Notes]. Naming your files properly saves massive time when you’re comparing logs from different tuning sessions.
Pro Tip: Logging Switch
In the Modes tab, assign Blackbox logging to a switch on your radio. This lets you start/stop recording without disarming — perfect for running multiple test passes on a single battery. Fly out, flip the switch, do your test maneuver, flip it off, reposition, repeat. Keeps your log files focused on the data that matters instead of 3 minutes of hovering and taxiing.
Blackbox Analysis Tools
Betaflight Blackbox Explorer
The primary tool. It’s free, open-source, and available as a web app at blackbox.betaflight.com or as a downloadable desktop app from the Betaflight GitHub. Works on Windows, Mac, and Linux.
To open a log: pull the SD card from your FC, plug it into your computer, and either drag the .BBL file into the web app or open it in the desktop version. The timeline appears at the bottom, graph traces above.
The key graph types you’ll use:
Gyro trace — your primary diagnostic view. A clean, smooth line tracking setpoint = good tune. Jagged noise, persistent wiggles, or significant lag = problems to diagnose.
Setpoint overlay — shows setpoint (desired) and gyro (actual) together. The gap between them tells you about responsiveness. Overshoot past setpoint tells you about P/D balance.
PID term breakdown — P, I, and D plotted individually. Shows which term is contributing what. Essential for understanding why your quad behaves the way it does.
Motor outputs — the raw commands. If any motor is consistently hitting max (2000μs or 100%), you’ve got a motor authority problem — your PID loop is asking for more than the motors can deliver.
Spectrum analyzer — the FFT view. Shows frequency content of your gyro and motor traces. This is where you identify motor resonance peaks, verify filter effectiveness, and spot frame vibrations.
Use keyboard shortcuts: I and O to trim the log start/end points (cut out arming and landing), M to place markers for measuring time intervals and frequencies, arrow keys to scrub frame-by-frame.
PIDtoolbox
For more advanced analysis, PIDtoolbox offers spectral analysis tools and step response visualization that Blackbox Explorer doesn’t match. The original PIDtoolbox by bw1129 ended active development in May 2024, but it still works well with current Betaflight logs. It’s a standalone app (Windows/Mac) that reads .BBL files directly.
PIDtoolbox excels at two things: its Spectral Analyzer shows noise across the throttle range with more detail than Blackbox Explorer’s built-in FFT, and its Step Response view gives you a clear picture of how critically damped your tune is — whether P and D are balanced, whether you’re overshooting, and by how much. If you’re serious about tuning, learning PIDtoolbox alongside Blackbox Explorer is worth the effort.
Plasmatree PID Analyzer
A lightweight Python-based alternative that calculates PID step response from your logs. It’s free on GitHub and useful for quick step response analysis without installing PIDtoolbox. Less feature-rich, but it does one thing well.
Reading Gyro Traces: What to Look For
This is the core skill. Pull up your gyro trace on any axis (roll is usually most revealing) and learn to read it like an ECG.
A Healthy Trace
Smooth lines that follow setpoint closely with minimal delay. When the stick moves, the gyro responds quickly and settles cleanly — maybe a tiny overshoot (under 5%), then locks on. During steady flight, the trace is quiet with no sustained oscillation. After a quick roll or flip, the quad stops cleanly without ringing.
This is what a well-tuned 5-inch freestyle quad looks like in the log. The P-term does the heavy lifting on stick inputs, D dampens any overshoot, and I-term handles the steady-state hold. The three terms work in harmony.
High-Frequency Oscillation
You’ll see rapid, tight oscillation superimposed on the gyro trace — the signal looks “fuzzy” or has a fast wobble. This usually means:
P too high relative to D. The P-term is overshooting repeatedly, and D can’t dampen it fast enough. The oscillation frequency is typically 50-150 Hz, faster than you can perceive as a distinct vibration but you’ll hear it as a high-pitched whine from the motors.
Fix: Drop P by 5-10 points on the affected axis. If that cleans it up but feels too mushy, bring P back up halfway and add D instead. The P/D ratio matters more than the absolute values. A common target is D at roughly 50-70% of P value as a starting point, though this varies with the build.
Verify your RPM filter is enabled — on builds with bidirectional DShot, the RPM filter is the single most effective tool against motor-frequency oscillation. If you’re not running it, enable it before touching P and D.
Prop Wash Oscillation
The signature pattern: clean gyro during forward flight, then visible oscillation during throttle chops, power loops, or any time you fly through your own prop wash. You’ll see it in the log as distinct oscillation events that correlate with aggressive maneuvers, not constant noise.
Prop wash is an aerodynamic problem — dirty, turbulent air hitting your props — and no amount of PID tuning completely eliminates it. But you can minimize it:
Increase D slightly (2-5 points at a time). Enable or tune the D-term lowpass filter — though don’t over-filter or you’ll add latency that makes prop wash worse. Check your propeller selection — lighter, more responsive props recover from disturbed air faster. Make sure RPM filtering is active and tracking properly (check FFT for clean motor peak suppression).
On a well-tuned freestyle quad, you’ll still see some prop wash during aggressive reversals. That’s physics. The goal is to reduce it to a level where it doesn’t affect your flow, not to eliminate it entirely.
Noisy Gyro Trace
The whole gyro signal looks grainy, like static overlaid on your actual flight data. Motors run hot after flights. You might hear a harsh buzzing tone. In the spectrum analyzer, you’ll see elevated noise across a broad frequency range rather than clean, distinct peaks.
This is usually a mechanical problem amplified by the D-term. D reacts to high-frequency changes in the gyro signal — if your build is vibrating excessively, D amplifies that vibration into motor commands, creating a feedback loop that heats motors and wastes battery.
Physical fixes first: Check motor condition — bent shafts and worn bearings are the #1 cause. Balance your props (or at least throw away visibly damaged ones). Verify nothing is loose on the frame — a single loose standoff can resonate and flood the gyro with noise. Soft-mount your FC if it isn’t already, or check that existing soft mounts aren’t crushed.
Then software: Lower D gain if motors are consistently hot. Increase D-term lowpass cutoff cautiously — every Hz you filter adds latency. If your build is inherently noisy (old motors, budget frame), accept that you’ll need more filtering than a clean build, and your tune will have slightly more latency as a trade-off.
Slow, Mushy Response
Large, visible gap between setpoint and gyro trace. The quad feels laggy, like flying through syrup. Stick movements produce a delayed, rounded response instead of a snappy one.
Check P gain first — if it’s low, the PID loop simply isn’t correcting fast enough. Bump P by 5-10 points and re-test.
If P is already reasonable, your filters might be too aggressive. Over-filtering adds latency to the PID loop, which manifests as exactly this kind of mushy response. Look at your gyro lowpass settings — if they’re set very low (below 150 Hz on a clean build), you’re likely over-filtered. Compare your gyro_scaled (unfiltered) and gyro (filtered) traces in Blackbox Explorer and check the delay between them.
Also verify motor authority — if your motors are weak relative to your quad’s weight, or your battery voltage is sagging hard under load, the PID loop can request corrections that the motors simply can’t deliver. The motor trace will show them hitting max output during stick inputs.
Frequency Analysis: Reading the Spectrum
The spectrum analyzer (FFT) in Blackbox Explorer transforms your time-domain gyro data into frequency-domain — showing you what frequencies are present in your vibration profile. This is where the diagnostic magic happens.
What a Clean Spectrum Looks Like
Strong energy below 20 Hz — that’s your actual flight movements, totally normal. Motor frequency peak visible but well-suppressed by the RPM filter (you’ll see a dip or reduced amplitude at the motor fundamental frequency). Minimal energy above 200-300 Hz. Overall, a smooth downward slope from low to high frequency.
Identifying Motor Noise
Your motor fundamental frequency = RPM ÷ 60. At mid-throttle, a typical 5-inch setup might spin at 18,000-25,000 RPM, putting the fundamental around 300-420 Hz. You’ll also see harmonics at 2x and sometimes 3x that frequency.
With RPM filtering enabled and working correctly, you should see clear suppression at these exact frequencies. If the motor peaks are still prominent despite RPM filtering being on, check that bidirectional DShot is actually enabled and that your ESCs support it — RPM filtering needs real-time RPM data from the ESCs to work.
Frame Resonance
A strong, sharp peak at a specific frequency that doesn’t shift with throttle (unlike motor noise, which tracks RPM). This is your frame vibrating at its natural resonant frequency. Common on frames with long arms or thin carbon.
The dynamic notch filter in Betaflight should target this automatically. If it’s not catching it, you may need a manual notch filter in the gyro filter settings. Use the FFT to identify the exact frequency, then set a notch there.
Throttle-Dependent Noise
Use the Freq vs Throttle heatmap view in Blackbox Explorer. This shows noise intensity across frequencies at different throttle positions. Motor noise appears as a diagonal line (frequency increases with throttle/RPM). Frame resonance appears as a horizontal line (constant frequency). If motor noise and frame resonance intersect at a certain throttle position, that’s where your quad gets noisiest — and where your tune will be weakest.
Practical Tuning Workflow
Here’s the systematic approach that actually works. No shortcuts — each step builds on the previous one.
Step 1: Baseline Flight
Start with Betaflight defaults (or your current tune if you’re refining). Fly a varied pack: some hover, some forward flight, some rolls and flips, a few throttle punches, and some prop wash-inducing moves (tight power loops, quick direction reversals). Log the entire flight.
Step 2: Analyze the Baseline
Open in Blackbox Explorer. Scrub through and identify the biggest issues:
- Is the gyro trace noisy overall? → Mechanical or filter issue
- Oscillation during specific maneuvers? → PID balance or prop wash
- Lag between setpoint and gyro? → P too low or over-filtered
- Motors saturating? → Authority problem
Check the spectrum analyzer for noise peaks. Note what frequencies are problematic.
Step 3: Make ONE Change
This is the discipline that separates productive tuning from chasing your tail. Change exactly one thing — P gain on roll by +10, or D lowpass cutoff by +20 Hz, or enable RPM filtering. One variable per test flight.
Step 4: Comparison Flight
Fly the same mix of maneuvers. Log it. Then use Blackbox Explorer’s overlay feature (File → Add comparison log) to see both logs on top of each other. The improvement — or regression — will be visually obvious.
Step 5: Evaluate and Iterate
Compare the key metrics:
- Noise floor — did it go up or down?
- Overshoot — more or less after stick inputs?
- Tracking delay — tighter or looser gap between setpoint and gyro?
- Motor temperatures — physically check motors after each flight
If the change helped, keep it and move to the next issue. If it made things worse, revert and try a different approach.
Step 6: Document Everything
Name your log files descriptively: 2026-02-08_Nazgul5_P42_D38_RPMon.bbl. Keep a tuning log (even a simple text file) noting what you changed and what the result was. After a few sessions, you’ll have a clear picture of your quad’s behavior and what settings work for your specific build.
Quick Reference: Symptoms and Fixes
Motors whining, high-pitched: P too high or RPM filter not active. Check FFT for unfiltered motor peaks. Lower P or enable bidirectional DShot + RPM filter.
Quad bounces at end of rolls/flips: P/D imbalance causing overshoot. Add D, or reduce P. Check step response in PIDtoolbox for overshoot percentage.
Mushy, delayed stick response: P too low, filters too aggressive, or weak motor authority. Raise P, loosen filters, or check battery health.
Oscillation only during throttle chops: Prop wash. Increase D slightly, verify RPM filter, consider lighter props.
Hot motors after every flight: D-term noise amplification. Lower D, increase D lowpass filtering, fix mechanical vibration sources. Check motor bearings and prop balance.
Random twitches or jolts mid-flight: Could be electrical noise (check wiring), ESC desync (check motor/ESC compatibility), or a failing gyro sensor. Blackbox will show the event clearly — a sudden spike in gyro data with no corresponding stick input points to hardware.
FAQ
Do I really need blackbox to tune?
No. Plenty of great pilots tune entirely by feel, and for most flying, that’s fine. Blackbox becomes valuable when you hit a problem you can’t diagnose by feel — persistent vibration that could be P, D, or mechanical; prop wash that you’ve tried everything for; motors running hot for no obvious reason. It’s also the fastest way to verify that your tune is actually improving, not just different. Think of it as a diagnostic tool you reach for when needed, not something required for every flight.
What if my FC only has onboard flash?
You’ll get 2-4 minutes of logging at 2 kHz, depending on flash chip size and how many fields you log. That’s enough for focused test flights — arm, do your test maneuver, disarm. Trim unnecessary fields to maximize recording time. For extended logging sessions, consider upgrading to an FC with an SD card slot.
What’s the difference between Gyro and Gyro_Scaled in Blackbox Explorer?
This trips up a lot of people. In Blackbox Explorer’s graph panel, Gyro is the filtered gyro signal — after all your lowpass and notch filters have been applied. Gyro_Scaled is the unfiltered (raw) gyro signal, before any filtering. Gyro_Scaled will always look noisier. The time delay between the two tells you how much latency your filtering is adding. Press M to place markers and measure this delay — it’s a useful diagnostic.
Can F4 flight controllers handle blackbox?
Yes. Most F4 and all F7 FCs support blackbox logging. The CPU overhead is minimal at 2 kHz to SD card. Some budget F4 boards may only have onboard flash rather than an SD card slot — check the FC specs before buying if extensive logging matters to you.
How do I know when my tune is “done”?
When the gyro trace is smooth with minimal overshoot, motors come down warm but not hot after aggressive flying, and — most importantly — the quad feels the way you want it to feel. Data-driven tuning should serve your flying, not replace it. If you’re spending more time analyzing logs than actually flying, you’ve gone too far. Get it to 90% with blackbox, then fly and enjoy the last 10% by feel.
What to Buy for Blackbox Logging
You don’t need much. A decent SD card and a USB card reader are the only hardware additions if your FC already has an SD card slot.
SD Cards: Any reputable Class 10/UHS-I card in the 16-32GB range works. SanDisk Ultra or Samsung EVO are proven reliable. Format FAT32 before first use.
USB Card Reader: Any USB 3.0 microSD reader. Fast transfers when you’re iterating quickly between flights and analysis.
Flight Controllers with SD Card Slot: If you’re building new and want hassle-free logging, prioritize FCs with a microSD slot. The SpeedyBee F405 V4, Mamba F722, and most F7 boards include one.
Blackbox analysis has a learning curve — your first few logs will look like abstract art. Stick with it. Start by just comparing “smooth vs jagged” in the gyro trace. Then learn to read P and D contributions. Then start using the spectrum analyzer. Within a few tuning sessions, you’ll wonder how you ever tuned without it.
Your quad is generating thousands of data points per second. Learn to read them, and tuning stops being guesswork.
