How to use Blackbox in Betaflight FPV Drones

by Oscar
How To Use Blackbox Betaflight 4.3

In this tutorial I will explain how to record Blackbox logs, the ins and outs of Blackbox Explorer, and show you some examples on how to interpret the graphs for basic tuning and troubleshooting of a Betaflight FPV drone.

Some of the links on this page are affiliate links. I receive a commission (at no extra cost to you) if you make a purchase after clicking on one of these affiliate links. This helps support the free content for the community on this website. Please read our Affiliate Link Policy for more information.

What’s Betaflight Blackbox?

Blackbox is a flight data recording feature in Betaflight. A Blackbox log contains a lot of data, such as the attitude of the drone, gyro sensor measurements, RC commands, motor outputs etc. It’s an extremely powerful tool for tuning and troubleshooting an FPV drone.

But Blackbox is by no mean the only way to tune your quad, check out my 10 simple steps to tune a quad without Blackbox.

Here’s a complete guide on how to use Blackbox to tune filters and PID on your drone.

Hardware Requirement

To record Blackbox log, you flight controller must have either flash memory chip (more common) or a SD card recorder.

In this image, the chip on the left that says “Winbond” is a 16MB flash memory chip dedicated for Blackbox logging. Most flight controllers these days have a built-in flash memory chip and no extra setup is required.

The flight controller shown in the following image has an SD card slot designed for Blackbox.

Holybro Kakute H7 Bt Fc Flight Controller Close Up Bottom

Alternatively you can hook up an external recording device (such as Openlog) to a spare UART, find this UART in the Ports tab and select Blackbox Logging, click Save. But I highly recommend getting an FC with either flash memory or SD card slot if you want to use Blackbox, it’s just so much easier.

Flash memory capacity doesn’t need to be massive, typically 16MB should be enough in most cases and should be enough for 5-10 mins of flight depending on the logging rate. Using an SD card is normally an overkill for Blackbox, a 4GB card would probably be enough to last the whole year without ever emptying it. But you will need a card with fairly high write speed, and format it in FAT32. 4GB or larger is a good size.

How to Record Blackbox

Go to the Blackbox tab in Betaflight Configurator, select the appropriate Blackbox logging device. For flash memory chip, select “Onboard Flash”.

Two important settings:

  • Set logging rate to 2Khz (for BMI270 gyro, choose 1.6Khz) for PID tuning, noise analysis and filter tuning. 1KHz is enough for just normal PID tuning – personally I just leave it at 2KHz for convenience, however you can save some space choosing the slower logging rate
  • Set debug mode to “GYRO_SCALED“, this will record the unfiltered raw gyro data which is useful for filter tuning/troubleshooting
  • hit the Save button

On the same page, you can see how much space you have left for logging, you should erase it before every session, when it’s full it will stop recording.

Betaflight 4.3 Configurator 10.8 Blackbox

Blackbox will start recording as soon as you arm, and it will stop when you disarm or when memory is full. Personally I prefer to start/stop Blackbox whenever I want using a switch. You can do this in the Modes tab by assigning an AUX channel to Blackbox.

Betaflight Configurator Modes Blackbox Arm Beeper Flip Over After Crash

Saving Blackbox Logs

In the Blackbox tab, click Activate Mass Storage Device Mode, an external drive will appear on your computer. There, just copy the blackbox files to your computer. This way is much faster and more reliable than clicking the “Save flash to file…” button.

You might find a bunch of blackbox files in the drive, note that the last file “btfl_all.bbl” is just a combination of all your other blackbox log files. If you know which file you need, you can just ignore “btfl_all.bbl” as it’s usually quite large.

Pro Tip – How log files are created?

FC with onboard memory will only create separate log files after a power cycle, otherwise all logs are stored in the same file. Using SD card however, will save the logs in separate files when Blackbox is activated every time (e.g. disarm and arm) without power cycling the quad.

Finally, if during the same lipo, you have armed and disarmed your quad several times, the log will be divided into several parts. You will be able to access each of the flights made on the LiPo using the drop-down list at the top of the right column in Blackbox Explorer.

Download Blackbox Explorer

Blackbox Explorer is a software used to open and view Blackbox log, you can download it here:

How to use Blackbox Explorer

Click the Info icon (“View Log Header”) on the top left, it displays the whole Betaflight FC configuration for the current log.

On the top left of the graph, you have a representation of the drone, it shows the current attitude and the outputs of the motors. On the top right you have the current stick inputs. These are overlays and you can turn them off if you want.

On the right hand column, you can select what traces and graphs you want to look at. On the bottom, there are 3 options above the Graph Setup button. You can use Expo to see traces with a bit higher fidelity, Smoothing to get rid of excessive vibration in the traces if you just interested in the average trend of the traces.

Below the graph is the timeline with throttle levels.

Blackbox Log Explorer Interface Explained

For full shortcuts (hot keys), click the question mark on the top right.

The really useful shortcuts are:

  • The “I” and “O” keys allow you to analyse a portion of the log. This is particularly useful for removing the take-off and landing parts which can potentially add undesired noise that is not interested in our noise analysis
  • The “M” key allows you to place a marker and measure the time elapsed since this marker (as well as the frequency). One useful application would be determining the time delay between setpoint and gyro

Hidden hotkeys:

  1. Alt + <- or -> arrows moves one data sample at a time
  2. Shift + <- or -> arrows changes view scale in 10% increments
  3. Alt + [click a trace (in legend)] -> turns on grid lines
  4. Alt + [click a trace group] -> splits the traces into individual lines
  5. (in spectrum analyser) Shift + moving your curser indicates the exact frequency, left click to create a marker

Syncing Video to Blackbox Log

If you have the video of the flight , you can display it in the background in Blackbox Explorer underneath the graphs.

Syncing flight video is not necessary but makes it easier to understand what the drone is actually doing as looking at traces alone can be confusing. DVR footage is preferred, but you can also use GoPro footage as long as it’s not stabilized.

Video file has to be in MP4 format.

The best way to sync is to find the spot where you do the first roll or flip. Press the M key (marker) in the log where your stick begin to move to do a roll/flip. Then scroll through your video until you see the moment you start to flip/roll, then press ALT + M, it will sync the log and video together.

Blackbox Log Roll Flip Traces Video Overlay

What Moves to Perform For Blackbox Log

For troubleshooting, do whatever moves that can replicate the issue.

For tuning:

  • Hover for a few seconds, then start cruising forward for a few seconds
  • Do 2-3 punch out, slowly ramp up throttle, checks for oscillations at different throttle level
  • Some snap rolls, some snap flips, some snap yaw spins, do both directions. Make sure there’s no coordinated movements, keep the move isolated
  • Some rapid throttle movements to test nose dip
  • Finally some split-S and sharp turns to test prop wash handling

What Traces To Look At?

It depends on what you are troubleshooting, but for general tuning, I mostly use this workspace. Workspace in Blackbox Explorer is like a preset of graphs and traces.

You can download my workspace here (17KB):

You can also download an blackbox log of mine to have a go, it’s a 4S 5″ freestyle FPV drone (5.5MB):

Blackbox Log Workspace Graphs Traces

To focus on a specific group of traces, click on name of the group. It will remove all the other groups of graph. To go back to the original view, just press 0 on your keyboard (back to the original workspace).

For example, if you click on [-] Roll, it takes you to this view:

Blackbox Log Roll Flip Traces

How to Read and Understand Traces

This is how traces look like in a roll/flip. The cursor is in the center of the roll, and in the legend, you can see Gyro is reporting 703 deg/s, which corresponds to the maximum rotational velocity set in the Rates.

And you can see how P, I, D and Feedforward are doing their jobs during the move. I still remember how fascinated I was when I first started using Blackbox.

Blackbox Log Roll Flip Traces

And here’s a punch out, you can see motor outputs (the very messy lines) are ramping up with throttle (red line).

Notice Motor 1 (light green) enters saturation (hitting 100%) before all the other motors, even before throttle reaching 100%. This could be a sign of uneven mass distribution of the drone, maybe it’s tail heavy since motor 1 is the rear left motor. Or perhaps that motor isn’t producing as much thrust as other motors and requires further investigation.

I hope you see why Blackbox is such an interesting and useful tool :)

Blackbox Log Punch Out Ramping Up Throttle Motor Outputs

How to Analyse Noise?

You can check noise level of any traces, we are particularly interested in gyro and D_term.

Click the “View Analyser Display” button in the menu bar, then select a trace you want to analyse in the Legend, then click Zoom Analyser Window.

Blackbox Log Analyser Noise

Noise analysis is beyond the scope of this tutorial, but I wrote another tutorial on how to tune your filter and PID using Blackbox here if you are interested:

To see the exact frequency, press SHIFT and move your cursor, left click to create a marker.

Blackbox Log Analyser Noise Frequency Spectrum

On the top left drop down menu, you can switch to another type of graph – frequency vs Throttle.

Blackbox Log Analyser Noise Frequency Vs Throttle


I will show you a few examples how to use Blackbox logs for general tuning and troubleshooting.

Is Gyro Tracking Setpoint?

Setpoint is what we want the drone to do, while Gyro is what the drone is actually doing.

One important goal of tuning is to try to make the drone feel responsive and precise, one way to determine is checking if the Gyro is tracking Setpoint. It’s impossible to have Gyro right on top of Setpoint at all times, but the closer the better.

Blackbox Log Setpoint Tracking Gyro Traces

Measuring Gyro Filter Delay

In Blackbox Graphs, Gyro_Scaled is the raw gyro data (noisier), and Gyro is the filtered gyro data (smoother but with delay).

You can measure the time difference between the two lines, and that gives you the delay caused by all the gyro filtering.

Press “M” key to create a marker. Zoom in for better accuracy.

Blackbox Log Explorer Gyro Filter Delay

P Gains Too High or D Gain Too Low

To achieve critical damped response, P and D should be in a good ratio.

When P is too high (or D is too low), P will overshoot or even oscillate in worse cases as you move the stick, and those wiggles can get into the gyro trace. To fix it, you can increase D to dampen it, or decrease P.

Blackbox Log D Too Low Or P Too High Overshoot

Excessive I Gain Causing Overshoot

Not only excessively high P gain can cause overshoot, I term can do that too but the overshoot is slower as you can see here.

Blackbox Log I Term Too High Overshoot

Feedforward Too High

Feedforward can help gyro track setpoint better, but too much Feedforward can cause it to overshoot. In this case you can see the gyro line moves before the setpoint, it actually causes P and D to move the opposite direction of the stick to try to slow down the gyro.

Blackbox Log Too Much Feedforward

Prop Wash

This is what propwash looks like. When some of the motors enter saturation (working at 100%) for a few ms, you know your drone is working at its hardest to combat propwash and that’s good!

Blackbox Log Propwash

Measuring RC Link Packet Rate

RC commands have steps, each step is a data packet. By measuring the time between steps gives you the packet rate (in Hz) of the RC link.

Press “M” key to create a marker. Zoom in for higher accuracy.

Blackbox Log Explorer Measure Rc Command Link Packat Rate Step

Alternatively you can find out in the noise analysis graph. The stepping frequency would be shown as a peak in the noise in RC commands. Sometimes it could be off by a couple of Hz.

Blackbox Log Find Rc Packet Rate Command Noise Hz

PID and Feedforward Oscillation Caused By Stick

When you let go of the stick at full deflection, it can bounce around the center point and cause ringing oscillation to feedforward and PID. That’s why you should keep your fingers on the sticks at all time when flying.

Blackbox Log Let Go Stick Bounce Ringing

Anti Gravity is Working

When moving throttle rapidly, drones can get nose dips when I gain is low. Anti Gravity can boost I term during these extreme movements to stabilize the drone better.

Blackbox Log Antigravity I Term Nose Dip One motor working harder than the rest

When hovering, one motor is working harder than the rest. This is usually an indication of an ESC or motor issue. try swapping around the motors. In this example, motor 1 clearly has issue, so after swapping the motors around, if the same motor still having issue, then the ESC is the culprit.

Blackbox Log Hovering Motor Outputs One Working Harder Esc Issue

ESC Desync

An ESC desync occurs when one of the motors stalls (stops spinning and thus stops producing thrust), prompting the drone to command that motor to spin harder, causing the motor signal to reach its maximum of 100%. Learn how to fix ESC desync here:

Esc Desync Blackbox Log

More Blackbox Tips

I plan to add more troubleshooting tips using Blackbox, please let me know in the comments what other blackbox log examples you want to see.

Leave a Comment

By using this form, you agree with the storage and handling of your data by this website. Note that all comments are held for moderation before appearing.


joel joseph 28th December 2023 - 5:00 am

motor diagnosis using blackbox

Ojo 23rd December 2023 - 4:08 pm

I have a KM55 ESC from Skystarts with AM32, when I look in the ESC Configurator I see that startup power is 100.
Do you know the recommend value for AM32 when desyncs happen? I’m very happy that AM32 has a desync recovery, otherwise I would have had another bag of broken parts…

Illia 3rd December 2023 - 8:22 am

I have a problem with open black box log files. Only the first file is successfully opened, the second and subsequent ones show an error. Can you suggest a solution or reason?
SD card 32GB

Dmitry 5th July 2023 - 11:01 am

Just had my drone fall out of the sky literally, I was cruising and then it started spinning and went down. Luckly I managed to recover it and now can use BB data for analysis. Blackbox shows that right before it starts spinning one of motors goes to zero output. Diagonal motor goes to 100% apparently one compensating the other. Am I safe to assume that my prop just fell off (and if so, which one, on the motor that goes to 0 or the one that goes to 100 trying to grasp thin air without a prop?) If not, what does it make sense to look for further?

Srdjan Trumic 7th April 2023 - 8:51 pm

just one question, if I’m using onboard dataflash chip to save the logs, how much of a log I can save with 1kHZ logging if my memory is only 16MB?

Oscar 7th April 2023 - 9:07 pm

10 to 20 mins?

Michael 20th March 2023 - 6:52 pm

Sorry for a maybe dumb question. My spectrum analyse windiw always stops at 400Hz. No matter what I do. In all tutorials and screenshots it stops at 100Hz. Can somone tell me what I’m doing wrong, so that it doesn’t sho me any noise with more than 400Hz frequency? I’m looking aince hours and can’t find a setting for the max. Frequency on the x axis.

Oscar 21st March 2023 - 1:01 am

Did you configure your Blackbox settings as shown here before logging?
I have a feeling you left it at default (800Hz for BMI270), that’s why it only show you up to 400Hz.

Michael 21st March 2023 - 1:48 pm

Thank you for the quick reply. It was just as you suspected. The setting was at 800Hz. I have now increased to 1600Hz. 2000Hz I can not set (BMI270).
Thanks for the good support and all the info.

Fariz 6th October 2022 - 1:51 am

Thanks Oscar, greatly appreciate your tutorial, your site has been my go-to reference aside from youtube. For me, i find it easier to use PidToolBox to tune the P/D ratio, it’s just so much easier to see the critically damped step response compared to BE. But I resort to BE when tuning the filter, I term & feedforward. I’m looking forward to the tutorial on ESC Desync.

Oscar 6th October 2022 - 11:50 am

Yea I am planning to do some content on PIDtoolbox.
I still find it faster to tune quads by ears and looking at googles, then fine tune looking at blackbox. But if someone has no idea how to tune at all, PIDtoolbox is foolproof for sure.

Lixx 5th October 2022 - 5:05 am

Exactly what I needed👌

I have one left question, what about Pid Toolbox? I don’t know what It’s used for and how to use it (didn’t find any Video explaining it)

Oscar 5th October 2022 - 9:07 am

I might do another post about it later. It’s a great tool too!