How to use Blackbox in Betaflight FPV Drones

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.

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”, otherwise select “SD card”.

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“.
• If you want to save some space to record for longer, you can de-select some data in the “Data included” dropdown list, things like Altitude, GPS, Magnetometer etc are not needed for filter/PID tuning.
• hit Save and reboot.

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.

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.

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:

https://github.com/betaflight/blackbox-log-viewer/releases/latest

Update (Jun 2024): There’s now a browser based Blackbox Explorer, so there’s no need to download it: https://blackbox.betaflight.com/

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.

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.

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):

https://drive.google.com/file/d/123jl99VpY8j1-Q7HyY_OR3kw8WtCk8t0/view?usp=sharing

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

https://drive.google.com/file/d/1zarNkFDwxzKRsfbaEa_JKAg7UPtCJlam/view?usp=sharing

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:

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.

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 :)

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.

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: https://oscarliang.com/pid-filter-tuning-blackbox/

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

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

Examples

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.

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.

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.

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.

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.

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!

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.

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.

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.

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.

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.

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: https://oscarliang.com/fix-esc-desync/

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.