The whole point of gathering Blackbox logs, as we discussed in our last article, is to be able to analyze them and discover possible problems or to better tune our quadcopters. In this article, we discuss how to use Blackbox Explorer – the premiere app for displaying the contents of Blackbox logs and tuning your quadcopter with them.
Like the Configurator software you used to setup Blackbox, Blackbox Explorer is installed as a Chrome App. The good news here is that it is totally multiplatform – you can run it on Windows, Mac, Linux, and of course on Chromebooks. There are two versions of Blackbox Explorer on the Chrome store. We recommend you install Betaflight Blackbox Explorer, regardless of what FC software you use:
Once you launch Blackbox Explorer and open a log, you’ll be presented with a screen that looks like this (without the numbers, of course):
At the end of the article, we’ll break down each of the numbered sections of this app. First, though, let’s do a quick graph setup so that you can get a better idea of what you are actually seeing. For this, you will need to follow these step-by-step instructions:
- Download our sample Blackbox log from here. (Right click and press “Save Target As”)
- Launch Blackbox Explorer and open the log you downloaded.
- Click “Graph setup”.
- You will be presented with a graph set-up window. It may not look exactly like the one below, but it doesn’t matter. Simply click every “Remove” button.
- You’ll now be looking at an empty configuration window, like this:
Click “Add graph” to get started customizing.
- Pick the following graphs, one at a time:
“RC Command”, “Gyro + PID roll”, “Gyro + PID pitch”.
- Hit “Save Changes”. You should be taken back to the main window, which should now look like this:
- Lets scroll to a more interesting part of the log. Go to time “00:26.600”. You can do this in several ways:
- Dragging your mouse in the graph
- Scrolling with the mousewheel in the graph
- Dragging on the timeline in the middle of the window
- Entering your desired time in the “Time” field at the top of the window.
- Pictured below is what you should see.
Lets discuss what is pictured here. First of all, there are three graphs. The top graph shows what the control sticks are doing, while the bottom two graphs show what is actually happening to the quadcopter on the roll and pitch axes. The lines labeled “gyro” is data being fed from the on-board gyroscope and is as close to what is really happening to the quadcopter as you are going to get. The other lines represent the factors from the Proportional, Integral and Derivative (PID) control loops which actually affect which motors spin up or down. At this snapshot in time, you can see I am lowering the throttle and raising the pitch – a clear sign that I intend to flip the quadcopter. If you continue scrolling forwards in the log, you’ll notice the little quadcopter icon indeed does a flip! Let’s look at the graphs a little bit closer, though:
- You can see that almost immediately after the pitch control command in the upper graph shows up, the gyro line in the bottom graph also begins to rise up. Likewise, the roll control command is staying centered and thus the middle graph shows no change whatsoever. This is exactly what you want to see when looking at the Blackbox log of a well tuned quadcopter – perfect harmony between your control inputs and the response from the gyro.
- Disable the aircraft icon (this will hide what the quadcopter on screen is doing) by clicking the disable button that looks like this:
- Now scroll to somewhere else in the log (maybe try 00:32.000) and try to figure out what is going on.
- Turn the aircraft indicator back on and see if you are right.
Keep playing with the log. Learning how to read what is happening by reading the graphs and interpreting where problems are occurring are critical to doing the analysis you will eventually need to get a great tune out of your quadcopter.
Blackbox Explorer UI Breakdown
For the remainder of this article, we’ll discuss the different parts of the Blackbox Explorer UI. We recommend you use the log you downloaded above to play with all the UI elements so that you can better understand how to use this fantastic tool. Lets go back to that original screenshot you saw earlier:
We will break down the different controls by number below before providing an overview on how this app can be used:
- Accesses a settings menu from which you can adjust the position and size of the various overlays.
- Set of toggle buttons from which you can turn the four overlays on or off. The overlays are, from left to right:
- Multirotor view which shows the orientation of the quadcopter if the accelerometer was on when the log was taken. (Pictured as ‘5’)
- Sticks display which shows the control inputs at the current time in the log. (Pictured as ‘6’)
- Statistics display which shows the state of all of the logged variables at the current log time. (Pictured as ’10’)
- Spectrograph view which allows you to see the frequency spectrum for a given variable – useful for tuning filters.
- Playback controls which let you play the log back like a video.
- A zoom control which allows you to zoom the graph in or out across the X-axis.
- This is a live view of your multirotor. It is only valid when you have the accelerometer enabled. In this case, the pictured quadcopter will display the orientation of the quadcopter at the current log time.
- Shows the position of your control sticks at the current log time. This is useful to help you find places where you fly at full throttle or command full-rate flips or rolls. It can also be helpful to diagnose drift.
- This drop down is one of the most important controls in Blackbox Explorer – I have no idea why it is so poorly labeled and positioned. To explain it’s use, you need to understand how Blackbox logging works. Every time you flip the arming switch, a new sub-log is created. Thus, it is possible to have a single Blackbox log file which contains many sublogs from many different flights. You use this drop down to flip between different arming cycles contained in a single Blackbox log. Here is an example of what the drop down looked like in a recent flight where I flipped the arming switch several times after a crash to try to find the quadcopter:
The number in between the ‘’ brackets is the total time for that arming cycle. In the situation above, the [00:00] entries are the ones where I simply blipped the arming switch to get the quad to make noise so I could find it. The log entries I was interested in were the ones with 1 minute or more of flight time (for instance [2:03] and [2:10]). The first step after opening a log in Blackbox Explorer should always be to check that you are viewing the correct arming cycle using this drop down.
- This is the graph legend. It shows you the values currently being plotted, what color they are and what their values are for the current playback time. The little spectrum icon next to each plot line can be clicked to bring up a spectrum view. See our guide on tuning the notch filters for an example on how this can be used.
- This is the timeline of the graph, and shows an overview of the entire time range for the Blackbox log along with a chart that indicates overall motor usage. Areas with thick blue lines are times when you are flying at full power or using a lot of motor power for some other reason. You can think of this area like a really handy scroll bar. You can click on sections with a lot of blue to instantly scroll to that part of the log to do further analysis on why so much motor power is being used.
- This shows all of the data being logged by Blackbox. The data will automatically update as you play the log forward or select new points on the timeline.
In order to get the most out of Blackbox Explorer, you need to know how to set-up the graphs that show up in the main display. This menu is accessed by clicking the “Graph Setup” button. Once it is pressed you will be presented with the following dialog:
As seen above, Blackbox Explorer lets you show multiple graphs concurrently. Each graph can then have multiple plot lines in it. This is useful for plotting closely related data, such as control inputs, PID factors and gyro responses all in the same graph for close comparison. These combinations are so often used that when you click the “Add Graph” button, you are presented with a list of pre-configured graphs to select from.
You can also configure different aspects of the plot lines. This includes:
- Smooth – Configures the amount of artificial smoothing applied to the line to make it more readable.
- Expo – Configures how the range of values is displayed. A higher number makes the lower range of values more visible but lessens the visibility of the higher range of values.
- Zoom – Configures the auto-scaling of the values along the Y-axis. 100% means the greatest Y-value will be assigned the highest Y-axis value while 50% means the plot line will only use 50% of the Y-axis at most.
- Line – The thickness of the plot line.
- Color – The color of the plot line.
We recommend new users stick to using the pre-configured graphs, which have optimal settings for all of these values for analyzing the most common things you will be using Blackbox for. Here are the Pre-configured graphs:
- Motors – Shows a plot of all the motors commands being sent to the ESCs on your quadcopter. This can be useful for diagnosing ESC desync problems or failing motors/ESCs.
- Gyros – Shows a plot of all 3 axes of the gyroscope in your flight controller. This can be compared with the RC Command plot to view the overall performance of your flight controller.
- RC Command – Shows the control stick inputs from your Transmitter. This is a useful graph to show what you are commanding at any given time (e.g. flip, roll, fast flight, etc).
- PIDs – Shows the PID sums on all 3 axes, which are the combined factor by the motors are commanded. Not a terribly useful graph.
- PID Error – Shows the difference between the gyroscope reading and the control inputs. This graph does a good job showing the total performance of your tune – the optimal situation is that there is always 0 error. In reality, this is absolutely impossible – but deviations that last for a minimal amount of time are desired – indicating “snappy” performance with no oscillations or overshoot.
- Gyro + PID roll – Shows the roll Proportional, Integral and Derivative PID factors alongside the gyro trace. Essential for tuning your quadcopters roll PID values.
- Gyro + PID pitch – Shows the pitch Proportional, Integral and Derivative PID factors alongside the gyro trace. Essential for tuning your quadcopters pitch PID values.
- Gyro + PID yaw – Shows the yaw Proportional, Integral and Derivative PID factors alongside the gyro trace. Essential for tuning your quadcopters yaw PID values.
- Accelerometers – Shows a plot of all 3 axes from the Accelerometer, which reads “g” forces experienced by your quadcopter in addition to the affect from the force of gravity – integrated to compute your quadcopter’s orientation. This can be used to tune the performance of “Level” mode but is generally useless for miniquad racers.
More reading and watching
If you prefer videos, or want to dig a little deeper into how to use Blackbox, Joshua Bardwell has an amazing two-part series on using Blackbox to tune and diagnose issues on your quadcopter. You can view this yere:
Now, go analyze some logs!
Now it is time to analyze your own logs! Use the information here to start analyzing and better understand exactly what your quadcopter is doing in flight. This will really help you lock in your control of your quadcopter, and help diagnose issues that occur. Questions? Let us know, as we would be happy to help!