On this tutorial, I’ll clarify how you can allow Blackbox logging in Betaflight, the really useful logging settings, how you can use Blackbox Explorer, and present examples of how you can interpret key graphs for fundamental tuning and troubleshooting on a Betaflight FPV drone.
A few of the hyperlinks on this web page are affiliate hyperlinks. I obtain a fee (at no additional price to you) when you make a purchase order after clicking on one among these affiliate hyperlinks. This helps assist the free content material for the group on this web site. Please learn our Affiliate Hyperlink Coverage for extra data.
What Is Betaflight Blackbox?
Blackbox is a flight-data recording characteristic in Betaflight. A Blackbox log captures important data corresponding to:
Stick inputs
Gyro measurements
PID controller responses
Motor outputs
And far more
By replaying a flight log, you possibly can analyze whether or not your quad is behaving as anticipated—whether or not it tracks your stick instructions accurately, overshoots, lags, or hits motor limits.
It’s an especially highly effective device for evaluating and tuning FPV drone efficiency, in addition to diagnosing points.
Whereas blackbox could be very useful for tuning, it’s not obligatory. You may nonetheless tune a quad with out Blackbox, as defined on this tutorial: https://oscarliang.com/fpv-drone-tuning/
To report Blackbox logs, your flight controller will need to have both:
A built-in flash reminiscence chip
or, an SD card slot
If it has neither, you possibly can join an exterior logger (lined later).
Flash Reminiscence Chip
Within the picture instance, the chip labeled “Winbond” is a 16MB flash reminiscence chip devoted to Blackbox logging.
Most fashionable flight controllers embrace a flash chip by default. A 16MB chip sometimes shops 5–10 minutes of flight knowledge relying in your logging price. That is enough for basic tuning and troubleshooting—you’ll simply must emptying logs between flights to keep away from working out of area.
In Betaflight Configurator, the highest bar shows how a lot reminiscence area is on the market:
SD Card Slot
If Betaflight says “no knowledge chip discovered”, your FC possible has an SD card slot, as proven within the picture beneath.
An SD card offers you just about limitless logging area. A 4GB card can simply final a full 12 months of flying with out emptying it.
Nonetheless:
Use a card with excessive write pace, or it’s possible you’ll expertise lacking/corrupted log knowledge.
Onboard Flash → in case your FC has a built-in flash reminiscence chip
SD Card → in case your FC has a micro SD card slot
1. Logging Price
Choose 2 kHz.
1 kHz is sufficient for basic PID tuning.
2 kHz (or 1.6 kHz for BMI270 gyro) is really useful for filter tuning and noise evaluation, as a result of it lets you observe vibrations as much as 1 kHz.
For comfort, I usually depart it at 2 kHz, however if you wish to save file area, it’s possible you’ll select a decrease price.
2. Logged Fields
Disable pointless knowledge fields to scale back log dimension. These are hardly ever wanted for tuning:
Accelerometer
Perspective
RSSI
Altitude
Magnetometer
Battery
GPS
Servo
3. Debug Mode
If you wish to save area or hold the logs easy, set Debug Mode = NONE and uncheck debug logging.
If you need deeper perception, set Debug Mode = FFT_FREQ. This data the frequencies the place Betaflight’s dynamic notch filters are locking onto body vibrations—helpful when working with superior instruments like PIDToolbox.
Click on Save and Reboot.
On the identical web page, you can even see how a lot logging area is on the market. Attempt to erase logs earlier than every flying session; as soon as storage is full, Blackbox will cease recording.
How one can Report Blackbox Logs
By default, Blackbox will routinely:
Begin recording the second you arm the quad
Cease recording once you disarm or when reminiscence turns into full
When you want handbook management, assign Blackbox to a change within the Modes tab.
Saving Blackbox Logs
Join your drone to Betaflight Configurator.
Go to the Blackbox tab.
Click on Activate Mass Storage System Mode.
Your FC will seem as an exterior drive in your pc. Merely browse to the drive and duplicate the .bbl information onto your pc.
This technique is way sooner than utilizing “Save flash to file…”.
You may even see a number of log information. The final file, btfl_all.bbl, accommodates all logs mixed. When you already know which log you need, you possibly can safely ignore this file.
Professional Tip: How Log Information Are Created
Onboard flash reminiscence: Logs are saved in a single file till you energy cycle the quad. Solely rebooting the FC and power-cycling creates a brand new log file. When you arm/disarm a number of instances throughout the identical battery, the log file will comprise a number of sub-logs, accessible in Blackbox Explorer utilizing the dropdown record on the prime proper.
SD Card: Every time Blackbox is activated (e.g., disarm → arm), a brand new log file is created—even with out energy biking.
Obtain Blackbox Explorer
Blackbox Explorer is the software program used to view Blackbox logs.
Click on “Open Log File” and find the Blackbox .bbl file you need to open.
Click on the Data icon (“View Log Header”) within the top-left nook. This shows the Betaflight configuration of the drone throughout that flight — extraordinarily useful when evaluating logs or confirming PID/filter settings.
High-Left: Drone Perspective & Motor Outputs
A small drone mannequin exhibits:
Present angle (roll, pitch, yaw)
Actual-time motor outputs
High-Proper: Transmitter Stick Inputs
The highest-right exhibits your stick instructions in the course of the flight.
Proper Column: Hint Choice
That is the place you select which graphs or indicators to show:
Pitch
Roll
Yaw
Motors
RC Instructions
And lots of others
You may toggle particular person traces or complete hint teams.
On the backside, there are graph choices:
Expo: to see traces with a bit greater constancy.
Smoothing: to do away with extreme vibration within the traces when you simply within the common pattern of the traces.
Under Graph: Timeline
Under the graph is the timeline, which additionally shows throttle place all through the flight.
Keyboard Shortcuts
Click on the query mark icon (top-right) to view all obtainable shortcuts.
Essentially the most helpful shortcuts are:
Log Part Isolation
I → set “in” level
O → set “out” level
Nice for trimming away takeoff/touchdown, which regularly provides deceptive noise that we aren’t all for.
Markers
Blackbox Explorer will then show time distinction and frequency between markers. For example, it’s helpful for measuring delays between setpoint and gyro, and the frequency of vibration.
Hidden Hotkeys (Extraordinarily Helpful)
Alt + ← or →: transfer one knowledge pattern at a time
Shift + ← or →: change view scale by 10% increments
Alt + click on a hint (in legend): toggle grid strains for that hint
Alt + click on a hint group: cut up grouped traces into particular person strains
Spectrum Analyzer mode:
Shift + transfer cursor: show actual frequency
Left-click: place marker at that frequency
Syncing Video to Your Blackbox Log
In case you have onboard footage, Blackbox Explorer can overlay graphs on prime of it, making it simpler to grasp what the quad was bodily doing at any second.
Is syncing vital?
In no way. I hardly ever sync video myself as a result of it provides additional time. However it could possibly assist:
Visualize oscillations
Verify propwash
See precisely when crash occasions happen
Evaluate precise movement with stick inputs
Tip: At all times use uncooked, unstabilized footage. Stabilized video might disguise wobble, vibrations, overshoots, and bounce-back.
Video Necessities
MP4 format solely
Stabilization off (most popular)
How one can Sync Video and Log
The best technique is to sync utilizing your first roll or flip:
Within the log, scrub to the second you provoke a roll/flip.
Press M to position a marker at the place your stick start to maneuver.
Within the video, scroll to the body the place the roll/flip begins.
Press Alt + M to sync the log with the video.
Now you possibly can play the log and the video collectively in good alignment.
What Strikes to Carry out for Blackbox Logging
For troubleshooting, merely carry out no matter strikes reproduce the problem you’re making an attempt to diagnose.
For basic tuning, listed here are the maneuvers I usually carry out to seize helpful, repeatable knowledge:
Hover for a couple of seconds, then cruise ahead steadily for one more few seconds.
Do 2–3 throttle punches, ramp up throttle cleanly and progressively over 3–5 seconds. This helps detect oscillations at varied throttle ranges with out shock-loading the quad.
Full rolls, flips, and yaw spins. Carry out a number of in each instructions. Keep away from mixing axes — hold strikes remoted (pure roll, pure pitch, pure yaw).
Speedy throttle pumps. For instance: 20% → 70% → 20%, repeated a couple of instances. This may reveal nostril dips brought on by insufficient I time period authority or poor tune.
Break up-S and sharp 180° turns. These maneuvers are nice for revealing propwash, particularly when you carry out them easily and repeatedly.
Enter-less cruising. In an open secure space, fly ahead with out touching the sticks. Gentle wind is OK; heavy gusts introduce noise into the information. That is nice for evaluating straight-line stability and I achieve.
Keep away from random cruising or simply hovering. These produce logs with little or no significant data. You need clear, distinct, repeatable stick inputs (step inputs) so you possibly can clearly see how the quad responds.
What Graphs/Traces To Look At?
This relies on what you’re troubleshooting, however for basic tuning I like to recommend utilizing a pre-made workspace.
A “Workspace” in Blackbox Explorer is basically a preset of traces so that you don’t must configure all the things manually each time.
You may obtain my workspace file right here (17KB):
Use quantity keys 1–9 or the dropdown menu to modify between workspaces if in case you have a number of templates loaded.
Specializing in a Particular Hint Group
Click on on the identify of a hint group (e.g., [-] Roll) to isolate simply that group. This hides the remainder of the graphs for readability.
Press 0 to return to the unique workspace view.
How one can Learn and Perceive Traces
That is how traces appear to be in a full roll or flip. The cursor (purple line) is within the heart of the roll, and within the legend on the fitting, you possibly can see Gyro is reporting 702 deg/s, which is precisely what I set in my max charges.
Within the traces, you possibly can see how P, I, D and Feedforward are doing their jobs throughout this transfer:
P is pushing the quad into the roll as commanded
Feedforward helps to push the quad sooner to carry gyro nearer to setpoint to reduce delay
D goes the wrong way to stop overshoot
And right here’s a punch out, you possibly can see motor outputs (the very messy strains) are ramping up with throttle (purple line).
Discover Motor 1 (gentle inexperienced) enters saturation (hitting 100%) lengthy earlier than all the opposite motors, even earlier than throttle reaching 100%. This may very well be an indication of uneven mass distribution of the drone, possibly it’s tail heavy since motor 1 is the rear left motor. Or maybe that motor isn’t producing as a lot thrust as different motors and requires additional investigation. You don’t must guess from the way it “feels” – you possibly can truly see it with proof.
I hope you see why Blackbox is such an attention-grabbing and useful gizmo 🙂
How one can Analyse Noise?
Blackbox Explorer features a built-in Spectrum Analyzer that exhibits noise ranges throughout frequencies of any traces, we’re significantly all for gyro and D_term.
Click on the “View Analyser Show” button within the menu bar, then choose a hint you need to analyse within the Legend, then click on Zoom Analyser Window.
To see the precise frequency, press SHIFT and transfer your cursor, left click on to create a marker.
On the highest left drop down menu, you possibly can change to a different sort of graph – frequency vs Throttle.
Examples
Listed below are a couple of examples exhibiting how you can use Blackbox logs for basic tuning and troubleshooting.
How Properly Is Your Drone Monitoring the Sticks?
The 2 most essential traces for evaluating management efficiency are:
Setpoint – what we wish the drone to do (i.e., your stick enter after RC smoothing)
Gyro – what the drone is definitely doing
By evaluating these two traces, you possibly can shortly see how precisely your quad responds to your instructions.
Ideally suited Monitoring
In an ideal world, the Gyro hint sits immediately on prime of the Setpoint hint. In actuality, this isn’t bodily potential — motors want time to speed up and decelerate — however the nearer they’re, the extra locked-in, exact, and responsive the quad feels.
PID Tuning Is a Stability Act
If the gyro is lagging behind the setpoint, think about growing Feedforward or P achieve. If there’s overshoot, D achieve is there to dampen it. But when D achieve is just too excessive it may amplify any present noise subject and make your quad fly worse and even trigger scorching motors. So there’s a stability to strike between these phrases.
When PID Doesn’t Assist
And if growing Feedforward or P achieve doesn’t carry gyro nearer to setpoint, test motor traces and see if any of them has reached their limits. If they’re already working at 100%, it simply means your drone has attain its bodily restrict and also you simply can’t push efficiency any additional. If gyro lags behind setpoint rather a lot and motors are already saturated, that’s an excellent indication your motors don’t have sufficient torque, to enhance efficiency you in all probability must improve the motors.
Know When To Cease Tweaking PID
Your drone has an honest tune in case your gyro carefully follows your setpoint in Blackbox with minimal overshoot. At this level, additional PID tweaks are largely about private really feel, not large efficiency positive aspects. You can transfer the Grasp slider barely up/down for extra/much less sharpness, nevertheless, when you push it too far you’ll hear fluttering / oscillation throughout flips and excessive throttle and ends in scorching motors.
Measuring Gyro Filter Delay
In Blackbox Graphs, Gyro_Scaled is the uncooked gyro knowledge (noisier), and Gyro is the filtered gyro knowledge (smoother however with delay).
You may measure the time distinction between the 2 strains, and that offers you the delay brought on by all of the gyro filtering.
Press “M” key to create a marker. Zoom in for higher accuracy.
P Features Too Excessive or D Achieve Too Low
To attain essential damped response, P and D ought to be in an excellent ratio.
When P is just too excessive (or D is just too low), P will overshoot and even oscillate in worse instances as you progress the stick, and people wiggles can get into the gyro hint. To repair it, you possibly can enhance D to dampen it, or lower P.
Extreme I Achieve Inflicting Overshoot
Not solely excessively excessive P achieve may cause overshoot, I time period can do this too however the overshoot is slower as you possibly can see right here.
Feedforward Too Excessive
Feedforward might help gyro observe setpoint higher, however an excessive amount of Feedforward may cause it to overshoot. On this case you possibly can see the gyro line strikes earlier than the setpoint, it truly causes P and D to maneuver the wrong way of the follow attempt to decelerate the gyro.
Prop Wash
That is what propwash appears to be like like. When among the motors enter saturation (working at 100%) for a couple of ms, your drone is working at its hardest to fight propwash and that’s good!
Measuring RC Hyperlink Packet Price
RC instructions have steps, every step is an information packet. By measuring the time between steps offers you the packet price (in Hz) of the RC hyperlink.
Press “M” key to create a marker. Zoom in for greater accuracy.
Alternatively you will discover out within the noise evaluation graph. The stepping frequency could be proven as a peak within the noise in RC instructions. Generally it may very well be off by a few Hz.
PID and Feedforward Oscillation Induced By Stick
Whenever you let go of the stick at full deflection, it could possibly bounce across the heart level and trigger ringing oscillation to feedforward and PID. That’s why it is best to hold your fingers on the sticks in any respect time when flying.
Anti Gravity is Working
When shifting throttle quickly, drones can get nostril dips once I achieve is low. Anti Gravity can enhance I time period throughout these excessive actions to stabilize the drone higher.
One motor working tougher than the remaining
When hovering, one motor is working tougher than the remaining. That is normally a sign of an ESC or motor subject. attempt swapping across the motors. On this instance, motor 1 clearly has subject, so after swapping the motors round, if the identical motor nonetheless having subject, then the ESC is the perpetrator.
ESC Desync
An ESC desync happens when one of many motors stalls (stops spinning and thus stops producing thrust), prompting the drone to command that motor to spin tougher, inflicting the motor sign to succeed in its most of 100%. Discover ways to repair ESC desync right here: https://oscarliang.com/fix-esc-desync/
Confirm If RC Smoothing Is Sufficient
To confirm in case your radio hyperlink is clean and responsive, test these traces:
RC Command: These are uncooked inputs from the radio hyperlink, they need to have small, evenly spaced steps once you transfer the sticks
Setpoint: That is principally the filtered RC instructions, ought to be clean with none steps if RC smoothing is working.
Feedforward: Also needs to be clean; when you see spikes, it could be brought on by setpoint being too steppy as a result of inadequate RC smoothing
When you’re utilizing Crossfire or a protocol with dynamic packet charges, you may see inconsistent RC steps. On this case, set your packet charges within the radio to a hard and fast one, or enhance RC smoothing settings in Betaflight as required.
Extra Blackbox Ideas
I plan so as to add extra troubleshooting ideas utilizing Blackbox, please let me know within the feedback what different blackbox log examples you need to see.
Conclusion
Blackbox is without doubt one of the strongest instruments obtainable in Betaflight, and when you perceive how you can use it, tuning and troubleshooting your FPV drone turns into way more predictable and much much less mysterious. As an alternative of relying solely on “really feel,” guesses, or trial-and-error PID adjustments, Blackbox helps you to see precisely what your quad is doing — how nicely it tracks your inputs, the place noise is coming from, whether or not motors are saturating, and the way your PID phrases work together in actual flight.
Edit Historical past
Oct 2022 – tutorial revealed
Dec 2025 – up to date for Betaflight Model 2025.12.0
