On this tutorial, I’ll clarify methods to allow Blackbox logging in Betaflight, the really helpful logging settings, methods to use Blackbox Explorer, and present examples of methods to 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 further price to you) in the event you make a purchase order after clicking on one in every of these affiliate hyperlinks. This helps assist the free content material for the neighborhood on this web site. Please learn our Affiliate Hyperlink Coverage for extra info.
What Is Betaflight Blackbox?
Blackbox is a flight-data recording characteristic in Betaflight. A Blackbox log captures important info equivalent to:
Stick inputs
Gyro measurements
PID controller responses
Motor outputs
And way more
By replaying a flight log, you may analyze whether or not your quad is behaving as anticipated—whether or not it tracks your stick instructions appropriately, overshoots, lags, or hits motor limits.
It’s an especially highly effective software 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 file 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 may join an exterior logger (coated 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 information relying in your logging price. That is adequate for common tuning and troubleshooting—you’ll simply have to emptying logs between flights to keep away from operating out of house.
In Betaflight Configurator, the highest bar shows how a lot reminiscence house is out there:
SD Card Slot
If Betaflight says “no information chip discovered”, your FC possible has an SD card slot, as proven within the picture beneath.
An SD card provides you nearly limitless logging house. A 4GB card can simply final a full 12 months of flying with out emptying it.
Nonetheless:
Use a card with excessive write velocity, or you might expertise lacking/corrupted log information.
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 Fee
Choose 2 kHz.
1 kHz is sufficient for common PID tuning.
2 kHz (or 1.6 kHz for BMI270 gyro) is really helpful for filter tuning and noise evaluation, as a result of it means that you can observe vibrations as much as 1 kHz.
For comfort, I usually depart it at 2 kHz, however if you wish to save file house, you might select a decrease price.
2. Logged Fields
Disable pointless information 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 house or hold 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 house is out there. Attempt to erase logs earlier than every flying session; as soon as storage is full, Blackbox will cease recording.
The best way to File Blackbox Logs
By default, Blackbox will mechanically:
Begin recording the second you arm the quad
Cease recording while you disarm or when reminiscence turns into full
If you happen to choose handbook management, assign Blackbox to a swap within the Modes tab.
Saving Blackbox Logs
Join your drone to Betaflight Configurator.
Go to the Blackbox tab.
Click on Activate Mass Storage Gadget Mode.
Your FC will seem as an exterior drive in your laptop. Merely browse to the drive and duplicate the .bbl information onto your laptop.
This technique is way quicker 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. If you happen to already know which log you need, you may 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. If you happen to arm/disarm a number of occasions throughout the identical battery, the log file will include 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 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 perspective (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 alerts to show:
Pitch
Roll
Yaw
Motors
RC Instructions
And plenty 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 eliminate extreme vibration within the traces in the event you simply within the common pattern 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 obtainable shortcuts.
Probably 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 fascinated with.
Markers
Blackbox Explorer will then show time distinction and frequency between markers. As an example, it’s helpful for measuring delays between setpoint and gyro, and the frequency of vibration.
Hidden Hotkeys (Extraordinarily Helpful)
Alt + ← or →: transfer one information 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 precise frequency
Left-click: place marker at that frequency
Syncing Video to Your Blackbox Log
If in case you have onboard footage, Blackbox Explorer can overlay graphs on high of it, making it simpler to grasp what the quad was bodily doing at any second.
Is syncing essential?
In no way. I hardly ever sync video myself as a result of it provides further time. However it could possibly assist:
Visualize oscillations
Affirm propwash
See precisely when crash occasions happen
Examine precise movement with stick inputs
Tip: All the time use uncooked, unstabilized footage. Stabilized video might cover wobble, vibrations, overshoots, and bounce-back.
Video Necessities
MP4 format solely
Stabilization off (most well-liked)
The best way to 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 may 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 difficulty you’re making an attempt to diagnose.
For common tuning, listed below are the maneuvers I usually carry out to seize helpful, repeatable information:
Hover for just a few seconds, then cruise ahead steadily for an additional 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 — hold strikes remoted (pure roll, pure pitch, pure yaw).
Fast throttle pumps. For instance: 20% → 70% → 20%, repeated just a few occasions. This will 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 in the event 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 info. 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 info. You need clear, distinct, repeatable stick inputs (step inputs) so you may clearly see how the quad responds.
What Graphs/Traces To Look At?
This is dependent upon what you’re troubleshooting, however for common 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 every thing 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 when you’ve got 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.
The best way to Learn and Perceive Traces
That is how traces seem like in a full roll or flip. The cursor (crimson line) is within the heart of the roll, and within the legend on the precise, you may see Gyro is reporting 702 deg/s, which is precisely what I set in my max charges.
Within the traces, you may 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 quicker to deliver gyro nearer to setpoint to attenuate delay
D goes the other way to forestall overshoot
And right here’s a punch out, you may see motor outputs (the very messy strains) are ramping up with throttle (crimson line).
Discover Motor 1 (mild inexperienced) enters saturation (hitting 100%) lengthy earlier than all the opposite motors, even earlier than throttle reaching 100%. This could possibly 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 may really see it with proof.
I hope you see why Blackbox is such an fascinating and great tool 🙂
The best way to Analyse Noise?
Blackbox Explorer features a built-in Spectrum Analyzer that exhibits noise ranges throughout frequencies of any traces, we’re notably fascinated with 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 may swap to a different sort of graph – frequency vs Throttle.
Examples
Listed below are just a few examples exhibiting methods to use Blackbox logs for common tuning and troubleshooting.
How Properly Is Your Drone Monitoring the Sticks?
The 2 most vital traces for evaluating management efficiency are:
Setpoint – what we would like 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 may rapidly see how precisely your quad responds to your instructions.
Preferrred Monitoring
In an ideal world, the Gyro hint sits immediately on high 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 Steadiness Act
If the gyro is lagging behind the setpoint, contemplate growing Feedforward or P achieve. If there’s overshoot, D achieve is there to dampen it. But when D achieve is simply too excessive it might amplify any current noise subject 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 growing Feedforward or P achieve doesn’t deliver gyro nearer to setpoint, test 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 in all probability should 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 principally about private really feel, not large efficiency positive factors. You would transfer the Grasp slider barely up/down for extra/much less sharpness, nevertheless, in the event you push it too far you’ll hear fluttering / oscillation throughout flips and excessive throttle and ends in sizzling motors.
Measuring Gyro Filter Delay
In Blackbox Graphs, Gyro_Scaled is the uncooked gyro information (noisier), and Gyro is the filtered gyro information (smoother however with delay).
You may measure the time distinction between the 2 strains, and that provides you the delay brought on by all of the gyro filtering.
Press “M” key to create a marker. Zoom in for higher accuracy.
P Positive factors Too Excessive or D Achieve 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 may improve D to dampen it, or lower P.
Extreme I Achieve 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 may see right here.
Feedforward Too Excessive
Feedforward can assist gyro observe setpoint higher, however an excessive amount of Feedforward could cause it to overshoot. On this case you may see the gyro line strikes earlier than the setpoint, it really causes P and D to maneuver the other way of the follow attempt to decelerate the gyro.
Prop Wash
That is what propwash seems like. When among the motors enter saturation (working at 100%) for just a few ms, your drone is working at its hardest to fight propwash and that’s good!
Measuring RC Hyperlink Packet Fee
RC instructions have steps, every step is an information packet. By measuring the time between steps provides you the packet price (in Hz) of the RC hyperlink.
Press “M” key to create a marker. Zoom in for greater accuracy.
Alternatively you could find out within the noise evaluation graph. The stepping frequency could be proven as a peak within the noise in RC instructions. Typically it could possibly be off by a few Hz.
PID and Feedforward Oscillation Brought about By Stick
Once 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 you need to hold your fingers on the sticks in any respect time when flying.
Anti Gravity is Working
When transferring 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 remainder
When hovering, one motor is working tougher than the remainder. That is often a sign of an ESC or motor subject. strive 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 Ample
To confirm in case your radio hyperlink is easy and responsive, test these traces:
RC Command: These are uncooked inputs from the radio hyperlink, they need to have small, evenly spaced steps while you transfer the sticks
Setpoint: That is mainly the filtered RC instructions, must be easy with none steps if RC smoothing is working.
Feedforward: Must also be easy; in the event you see spikes, it is perhaps brought on by setpoint being too steppy attributable to inadequate RC smoothing
If you happen to’re utilizing Crossfire or a protocol with dynamic packet charges, you would possibly see inconsistent RC steps. On this case, set your packet charges within the radio to a set 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 need to see.
Conclusion
Blackbox is without doubt one of the strongest instruments obtainable in Betaflight, and when you perceive methods to 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 permits 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
