On this tutorial, I’ll clarify how one can allow Blackbox logging in Betaflight, the advisable logging settings, how one can use Blackbox Explorer, and present examples of how one can interpret key graphs for fundamental tuning and troubleshooting on a Betaflight FPV drone.
Among the hyperlinks on this web page are affiliate hyperlinks. I obtain a fee (at no further value to you) should you make a purchase order after clicking on certainly one of 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.
Table of Contents
What Is Betaflight Blackbox?
Blackbox is a flight-data recording function in Betaflight. A Blackbox log captures important data reminiscent of:
Stick inputs
Gyro measurements
PID controller responses
Motor outputs
And far more
By replaying a flight log, you’ll be able to 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 instrument for evaluating and tuning FPV drone efficiency, in addition to diagnosing points.
Whereas blackbox could be very useful for tuning, it’s not necessary. You’ll be able to nonetheless tune a quad with out Blackbox, as defined on this tutorial: https://oscarliang.com/fpv-drone-tuning/
To document 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’ll be able to 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 fee. That is enough for basic tuning and troubleshooting—you’ll simply must emptying logs between flights to keep away from operating out of area.
In Betaflight Configurator, the highest bar shows how a lot reminiscence area is offered:
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 nearly limitless logging area. A 4GB card can simply final a full 12 months of flying with out emptying it.
Nevertheless:
Use a card with excessive write pace, or you might 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 Charge
Choose 2 kHz.
1 kHz is sufficient for basic PID tuning.
2 kHz (or 1.6 kHz for BMI270 gyro) is advisable 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, you might select a decrease fee.
2. Logged Fields
Disable pointless knowledge fields to cut back log measurement. These are not often wanted for tuning:
Accelerometer
Angle
RSSI
Altitude
Magnetometer
Battery
GPS
Servo
3. Debug Mode
If you wish to save area or preserve the logs easy, set Debug Mode = NONE and uncheck debug logging.
If you’d like deeper perception, set Debug Mode = FFT_FREQ. This information 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 offered. Attempt to erase logs earlier than every flying session; as soon as storage is full, Blackbox will cease recording.
How you can Report Blackbox Logs
By default, Blackbox will routinely:
Begin recording the second you arm the quad
Cease recording if you disarm or when reminiscence turns into full
In case you favor 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 laptop. Merely browse to the drive and replica the .bbl information onto your laptop.
This technique is way sooner than utilizing “Save flash to file…”.
You might even see a number of log information. The final file, btfl_all.bbl, comprises all logs mixed. In case you already know which log you need, you’ll be able to 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. In case 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 checklist on the high 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 wish 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.
Prime-Left: Drone Angle & Motor Outputs
A small drone mannequin reveals:
Present angle (roll, pitch, yaw)
Actual-time motor outputs
Prime-Proper: Transmitter Stick Inputs
The highest-right reveals 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 plenty of others
You’ll be able to toggle particular person traces or total hint teams.
On the backside, there are graph choices:
Expo: to see traces with a bit larger constancy.
Smoothing: to eliminate extreme vibration within the traces should you simply within the common development of the traces.
Beneath Graph: Timeline
Beneath 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 accessible 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 frequently provides deceptive noise that we aren’t enthusiastic about.
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 traces for that hint
Alt + click on a hint group: cut up grouped traces into particular person traces
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 high of it, making it simpler to know what the quad was bodily doing at any second.
Is syncing crucial?
By no means. I not often sync video myself as a result of it provides further time. However it will probably assist:
Visualize oscillations
Affirm propwash
See precisely when crash occasions happen
Examine precise movement with stick inputs
Tip: At all times use uncooked, unstabilized footage. Stabilized video could cover wobble, vibrations, overshoots, and bounce-back.
Video Necessities
MP4 format solely
Stabilization off (most popular)
How you 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 put 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’ll be able to play the log and the video collectively in excellent alignment.
What Strikes to Carry out for Blackbox Logging
For troubleshooting, merely carry out no matter strikes reproduce the problem you’re attempting to diagnose.
For basic tuning, listed below 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 steadily 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 — preserve strikes remoted (pure roll, pure pitch, pure yaw).
Fast throttle pumps. For instance: 20% → 70% → 20%, repeated a couple of instances. This will reveal nostril dips attributable to insufficient I time period authority or poor tune.
Break up-S and sharp 180° turns. These maneuvers are nice for revealing propwash, particularly should you carry out them easily and repeatedly.
Enter-less cruising. In an open protected 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’ll be able to 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 should configure all the things manually each time.
You’ll be able to 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 title 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 you can Learn and Perceive Traces
That is how traces appear to be in a full roll or flip. The cursor (crimson line) is within the heart of the roll, and within the legend on the appropriate, you’ll be able to see Gyro is reporting 702 deg/s, which is precisely what I set in my max charges.
Within the traces, you’ll be able to 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 forestall overshoot
And right here’s a punch out, you’ll be able to see motor outputs (the very messy traces) are ramping up with throttle (crimson 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 should guess from the way it “feels” – you’ll be able to really see it with proof.
I hope you see why Blackbox is such an attention-grabbing and great tool 🙂
How you can Analyse Noise?
Blackbox Explorer features a built-in Spectrum Analyzer that reveals noise ranges throughout frequencies of any traces, we’re significantly enthusiastic about gyro and D_term.
Click on the “View Analyser Show” button within the menu bar, then choose a hint you wish 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’ll be able to change to a different kind of graph – frequency vs Throttle.
Examples
Listed below are a couple of examples exhibiting how one can use Blackbox logs for basic tuning and troubleshooting.
How Properly Is Your Drone Monitoring the Sticks?
The 2 most necessary 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’ll be able to rapidly see how precisely your quad responds to your instructions.
Ideally suited Monitoring
In an ideal world, the Gyro hint sits instantly on high of the Setpoint hint. In actuality, this isn’t bodily doable — 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, contemplate rising Feedforward or P achieve. If there’s overshoot, D achieve is there to dampen it. But when D achieve is simply too excessive it may amplify any current noise concern and make your quad fly worse and even trigger sizzling motors. So there’s a steadiness to strike between these phrases.
When PID Doesn’t Assist
And if rising Feedforward or P achieve doesn’t carry gyro nearer to setpoint, examine motor traces and see if any of them has reached their limits. If they’re already operating 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 loads and motors are already saturated, that’s indication your motors don’t have sufficient torque, to enhance efficiency you most likely should improve the motors.
Know When To Cease Tweaking PID
Your drone has a good tune in case your gyro intently follows your setpoint in Blackbox with minimal overshoot. At this level, additional PID tweaks are principally about private really feel, not big efficiency positive aspects. You would transfer the Grasp slider barely up/down for extra/much less sharpness, nonetheless, should you push it too far you’ll hear fluttering / oscillation throughout flips and excessive throttle and leads to sizzling 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’ll be able to measure the time distinction between the 2 traces, and that provides you the delay attributable to all of the gyro filtering.
Press “M” key to create a marker. Zoom in for higher accuracy.
P Positive aspects Too Excessive or D Acquire Too Low
To attain important damped response, P and D must be in ratio.
When P is simply too excessive (or D is simply 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’ll be able to improve D to dampen it, or lower P.
Extreme I Acquire Inflicting Overshoot
Not solely excessively excessive P achieve could cause overshoot, I time period can try this too however the overshoot is slower as you’ll be able to see right here.
Feedforward Too Excessive
Feedforward will help gyro observe setpoint higher, however an excessive amount of Feedforward could cause it to overshoot. On this case you’ll be able to see the gyro line strikes earlier than the setpoint, it really causes P and D to maneuver the wrong way of the persist with attempt to decelerate the gyro.
Prop Wash
That is what propwash appears to be like like. When a few of 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 Charge
RC instructions have steps, every step is an information packet. By measuring the time between steps offers you the packet fee (in Hz) of the RC hyperlink.
Press “M” key to create a marker. Zoom in for larger accuracy.
Alternatively you’ll find out within the noise evaluation graph. The stepping frequency can be proven as a peak within the noise in RC instructions. Typically it may very well be off by a few Hz.
PID and Feedforward Oscillation Precipitated By Stick
If you let go of the stick at full deflection, it will probably bounce across the heart level and trigger ringing oscillation to feedforward and PID. That’s why you need to preserve your fingers on the sticks in any respect time when flying.
Anti Gravity is Working
When transferring throttle quickly, drones can get nostril dips after I achieve is low. Anti Gravity can increase I time period throughout these excessive actions to stabilize the drone higher.
One motor working more durable than the remaining
When hovering, one motor is working more durable than the remaining. That is often a sign of an ESC or motor concern. strive swapping across the motors. On this instance, motor 1 clearly has concern, so after swapping the motors round, if the identical motor nonetheless having concern, then the ESC is the wrongdoer.
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 more durable, inflicting the motor sign to achieve 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 easy and responsive, examine these traces:
RC Command: These are uncooked inputs from the radio hyperlink, they need to have small, evenly spaced steps if you transfer the sticks
Setpoint: That is principally the filtered RC instructions, must be easy with none steps if RC smoothing is working.
Feedforward: Also needs to be easy; should you see spikes, it may be attributable to setpoint being too steppy resulting from inadequate RC smoothing
In case 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 improve RC smoothing settings in Betaflight as required.
Extra Blackbox Suggestions
I plan so as to add extra troubleshooting suggestions utilizing Blackbox, please let me know within the feedback what different blackbox log examples you wish to see.
Conclusion
Blackbox is likely one of the strongest instruments accessible in Betaflight, and when you perceive how one can use it, tuning and troubleshooting your FPV drone turns into way more predictable and much much less mysterious. As a substitute of relying solely on “really feel,” guesses, or trial-and-error PID adjustments, Blackbox permits you to see precisely what your quad is doing — how effectively 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 printed
Dec 2025 – up to date for Betaflight Model 2025.12.0
