On this tutorial, I’ll clarify the best way to allow Blackbox logging in Betaflight, the advisable logging settings, the best way to use Blackbox Explorer, and present examples of the best way to 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 price 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 neighborhood on this web site. Please learn our Affiliate Hyperlink Coverage for extra info.
What Is Betaflight Blackbox?
Blackbox is a flight-data recording function in Betaflight. A Blackbox log captures important info resembling:
Stick inputs
Gyro measurements
PID controller responses
Motor outputs
And way 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 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 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 possibly can 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 trendy 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 adequate for basic tuning and troubleshooting—you’ll simply have to 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 obtainable:
[xxx configurator memory space ]
SD Card Slot
If Betaflight says “no knowledge chip discovered”, your FC probably has an SD card slot, as proven within the picture under.
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 velocity, or chances are 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
[xxx – update screenshot]
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, chances are you’ll select a decrease price.
2. Logged Fields
Disable pointless knowledge fields to cut back log measurement. These are not often wanted for tuning:
GPS
Accelerometer
Perspective
RSSI
Altitude
Magnetometer
Battery
3. Debug Mode
If you wish to save area or hold the logs easy, set Debug Mode = NONE and uncheck debug logging.
In order for you 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 may as well see how a lot logging area is obtainable. Attempt to erase logs earlier than every flying session; as soon as storage is full, Blackbox will cease recording.
[xxx space left on blackbox tab]
Find out how to Report Blackbox Logs
By default, Blackbox will robotically:
Begin recording the second you arm the quad
Cease recording once you disarm or when reminiscence turns into full
When you choose guide 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 System Mode.
Your FC will seem as an exterior drive in your laptop. Merely browse to the drive and replica the .bbl recordsdata onto your laptop.
This technique is way sooner than utilizing “Save flash to file…”.
You may even see a number of log recordsdata. The final file, btfl_all.bbl, comprises all logs mixed. When you already know which log you need, you possibly can safely ignore this file.
[xxx show btfl_all]
Professional Tip: How Log Recordsdata 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 include a number of sub-logs, accessible in Blackbox Explorer utilizing the dropdown checklist 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 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 Perspective & Motor Outputs
A small drone mannequin reveals:
Present perspective (roll, pitch, yaw)
Actual-time motor outputs
Prime-Proper: Transmitter Stick Inputs
The highest-right reveals your stick instructions through 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 may toggle particular person traces or total hint teams.
On the backside, there are graph choices:
Expo: to see traces with a bit increased 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 all in favour of.
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 precise frequency
Left-click: place marker at that frequency
Syncing Video to Your Blackbox Log
When you have onboard footage, Blackbox Explorer can overlay graphs on prime of it, making it simpler to know what the quad was bodily doing at any second.
Is syncing obligatory?
By no means. I not often sync video myself as a result of it provides further time. However it could assist:
Visualize oscillations
Affirm propwash
See precisely when crash occasions happen
Evaluate precise movement with stick inputs
Tip: At all times use uncooked, unstabilized footage. Stabilized video could conceal wobble, vibrations, overshoots, and bounce-back.
Video Necessities
MP4 format solely
Stabilization off (most popular)
Find out how 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 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 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).
Speedy 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. Mild wind is OK; heavy gusts introduce noise into the information. That is nice for evaluating straight-line stability and I acquire.
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 possibly can clearly see how the quad responds.
What Graphs/Traces To Look At?
This will depend 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 pieces 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 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.
Find out how to Learn and Perceive Traces
That is how traces seem like in a full roll or flip. The cursor (purple line) is within the heart of the roll, and within the legend on the proper, 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 deliver gyro nearer to setpoint to attenuate delay
D goes the wrong way to forestall overshoot
And right here’s a punch out, you possibly can see motor outputs (the very messy traces) 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 could possibly be an indication of uneven mass distribution of the drone, perhaps 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 fascinating and useful gizmo 🙂
Find out how to Analyse Noise?
Blackbox Explorer features a built-in Spectrum Analyzer that reveals noise ranges throughout frequencies of any traces, we’re significantly all in favour of 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 possibly can swap to a different sort of graph – frequency vs Throttle.
Examples
Listed here are a couple of examples displaying the best way to use Blackbox logs for basic 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 possibly can rapidly see how precisely your quad responds to your instructions.
Preferrred Monitoring
In an ideal world, the Gyro hint sits straight on prime of the Setpoint hint. In actuality, this isn’t bodily attainable — 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 growing Feedforward or P acquire. If there’s overshoot, D acquire is there to dampen it. But when D acquire is simply too excessive it might amplify any present noise concern and make your quad fly worse and even trigger sizzling motors. So there’s a stability to strike between these phrases.
When PID Doesn’t Assist
And if growing Feedforward or P acquire 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 so much 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 intently follows your setpoint in Blackbox with minimal overshoot. At this level, additional PID tweaks are largely about private really feel, not big efficiency features. You would transfer the Grasp slider barely up/down for extra/much less sharpness, nevertheless, 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 may 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 Features Too Excessive or D Acquire Too Low
To attain vital damped response, P and D must be in an excellent 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 possibly can improve D to dampen it, or lower P.
Extreme I Acquire Inflicting Overshoot
Not solely excessively excessive P acquire could cause overshoot, I time period can try this too however the overshoot is slower as you possibly can see right here.
Feedforward Too Excessive
Feedforward may also help gyro monitor setpoint higher, however an excessive amount of Feedforward could 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 persist with attempt to decelerate the gyro.
Prop Wash
That is what propwash seems to be like. When a few of the motors enter saturation (working at 100%) for a couple of ms, you understand 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 price (in Hz) of the RC hyperlink.
Press “M” key to create a marker. Zoom in for increased accuracy.
Alternatively you will discover out within the noise evaluation graph. The stepping frequency can be proven as a peak within the noise in RC instructions. Generally it could possibly be off by a few Hz.
PID and Feedforward Oscillation Prompted By Stick
Whenever you let go of the stick at full deflection, it could 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 after I acquire 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 normally a sign of an ESC or motor concern. attempt 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 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 achieve its most of 100%. Learn 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 once 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; should you see spikes, it may be attributable to setpoint being too steppy resulting from 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 set one, or improve 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 wish to see.
Conclusion
Blackbox is among the strongest instruments accessible in Betaflight, and when you perceive the best way 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 properly 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
