On this tutorial, I’ll clarify how you can allow Blackbox logging in Betaflight, the really helpful 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) if you happen to make a purchase order after clicking on one among these affiliate hyperlinks. This helps help 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 reminiscent of:
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 a particularly 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 necessary. 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 should 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 fashionable flight controllers embrace a flash chip by default. A 16MB chip sometimes shops 5ā10 minutes of flight knowledge relying in your logging charge. That is enough for normal tuning and troubleshootingāyouāll simply must emptying logs between flights to keep away from working 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 knowledge chip discoveredā, your FC possible has an SD card slot, as proven within the picture under.
An SD card offers you nearly limitless logging house. 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 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 normal 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 lets you observe vibrations as much as 1 kHz.
For comfort, I usually go away it at 2 kHz, however if you wish to save file house, you might select a decrease charge.
2. Logged Fields
Disable pointless knowledge fields to scale 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 house or hold the logs easy, set Debug Mode = NONE and uncheck debug logging.
If you would 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 may also 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 Report 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
In the event 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 Gadget 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 far sooner than utilizing āSave flash to fileā¦ā.
You might even see a number of log information. The final file, btfl_all.bbl, incorporates all logs mixed. In the event you already know which log you need, you possibly can safely ignore this file.
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.Ā In the event you arm/disarm a number of occasions 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.
High-Left: Drone Angle & Motor Outputs
A small drone mannequin reveals:
Present angle (roll, pitch, yaw)
Actual-time motor outputs
High-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 alerts to show:
Pitch
Roll
Yaw
Motors
RC Instructions
And lots of others
You may toggle particular person traces or whole hint teams.
On the backside, there are graph choices:
Expo: to see traces with a bit larger constancy.
Smoothing: to do away with extreme vibration within the traces if you happen to 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 out there 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 fascinated about.
Markers
Blackbox Explorer will then show time distinction and frequency between markers. As an illustration, 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: break 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
You probably 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?
By no means. I not often sync video myself as a result of it provides additional time. However it could actually 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 might conceal 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 simplest 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 excellent 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 normal tuning, listed below are the maneuvers I usually carry out to seize helpful, repeatable knowledge:
Hover for a number of seconds, then cruise ahead steadily for an additional few seconds.
Do 2ā3 throttle punches, ramp up throttle cleanly and step by step over 3ā5 seconds. This helps detect oscillations at numerous 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 number of occasions. This may reveal nostril dips brought on by insufficient I time period authority or poor tune.
Cut up-S and sharp 180Ā° turns. These maneuvers are nice for revealing propwash, particularly if you happen to 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 info. 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 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 normal 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 the whole lot 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 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.
The best way to Learn and Perceive Traces
That is how traces seem like in a full roll or flip. The cursor (pink line) is within the heart of the roll, and within the legend on the precise, 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 stop overshoot
And right hereās a punch out, you possibly can see motor outputs (the very messy traces) are ramping up with throttle (pink line).
Discover Motor 1 (mild inexperienced) enters saturation (hitting 100%) lengthy earlier than all the opposite motors, even earlier than throttle reaching 100%. This might 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 possibly can really see it with proof.
I hope you see why Blackbox is such an attention-grabbing and useful gizmo š
The best way to Analyse Noise?
Blackbox Explorer features a built-in Spectrum Analyzer that reveals noise ranges throughout frequenciesĀ of any traces, we’re notably fascinated 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 possibly can change to a different sort of graph ā frequency vs Throttle.
Examples
Listed below are a number of examples exhibiting how you can use Blackbox logs for normal tuning and troubleshooting.
How Nicely Is Your Drone Monitoring the Sticks?
The 2 most vital 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.
Preferrred 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, think about 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 may amplify any present noise challenge 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 acquire doesnāt deliver gyro nearer to setpoint, examine 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 loads and motors are already saturated, thatās an excellent 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 a good 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 big efficiency positive factors. You could possibly transfer the Grasp slider barely up/down for extra/much less sharpness, nevertheless, if you happen to push it too far youāll hear fluttering / oscillation throughout flips and excessive throttle and leads to 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 traces, 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 Beneficial properties Too Excessive or D Acquire Too Low
To realize important damped response, P and D needs to 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 may 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 help gyro monitor 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 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 number of ms, you realize 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 charge (in Hz) of the RC hyperlink.
Press āMā key to create a marker. Zoom in for larger 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. Typically it might 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 actually bounce across the heart level and trigger ringing oscillation to feedforward and PID. Thatās why it’s best 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 acquire 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 normally a sign of an ESC or motor challenge. strive swapping across the motors. On this instance, motor 1 clearly has challenge, so after swapping the motors round, if the identical motor nonetheless having challenge, 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 succeed in 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, examine 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 principally the filtered RC instructions, needs to be easy with none steps if RC smoothing is working.
Feedforward: Also needs to be easy; if you happen to see spikes, it may be brought on by setpoint being too steppy as a result of inadequate RC smoothing
In the event youā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 wish to see.
Conclusion
Blackbox is among the strongest instruments out there in Betaflight, and when you perceive how you can use it, tuning and troubleshooting your FPV drone turns into much more predictable and much much less mysterious. As a substitute of relying solely on āreally feel,ā guesses, or trial-and-error PID modifications, Blackbox helps 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 revealed
Dec 2025 ā up to date for Betaflight Model 2025.12.0
