Skip to content
PIDtoolbox is a set of graphical tools for analyzing Betaflight blackbox log data
Branch: master
Clone or download
Latest commit 1e12abb Apr 9, 2019


PIDtoolbox is a set of graphical tools for analyzing Betaflight blackbox log data for multirotors. It is available as a standalone program for both Windows and Mac. Although PIDtoolbox is designed for the person who likes to tinker and get the best performance possible out of their miniquad, it should be relatively straightforward for those new to the hobby as well, and there is a detailed Wiki page to help.

The motivation for the development of this tool was to create a user-friendly GUI for analyzing blackbox data, using a high-level language with simple plotting and visualization tools that are more accessible to a larger part of the FPV community. A second goal was to develop an objective method for comparing between flights. It was inspired by the way we often troubleshoot flight performance issues (e.g., vibrations, mid-throttle oscillation, propwash), where we make back to back test flights with slight changes in software/hardware/mechanical settings with each test, and then make subjective inferences about flight performance. The problem is subjective bias becomes a real issue when the differences between tests are subtle. PIDtoolbox was designed with this in mind.

PIDtoolbox v0.2+ is aimed at being a "one stop shop" set of tools centered around the main interests/issues of multirotor pilots. Version 0.2 features an extensive data Log Viewer, four independent Spectral Analyzers, Step Response and PID error analyses tools, as well as numerical summaries of results superimposed on the plots for more accurate, objective, comparisons (for a detailed guide to PIDtoolbox, visit the PIDtoolbox Wiki page). Below is everything you need to begin using PIDtoolbox.


1) If you have Matlab, you can download the source code (Windows or Mac), place the mfiles in a folder, and run PIDtoolbox.m from the Matlab command prompt. You will need several toolboxes installed for this to work (control toolbox, signal processing toolbox, image processing toolbox and statistics toolbox), as well as blackbox_decode, which is included in the package. I am also working towards porting the src code to Octave, a free high-level programming language very similar to Matlab, which would allow users to more easily contribute to the development of the project. If you are a programmer and would like to get involved in this, please feel free to download Octave and start testing the PIDtoolbox source code.

2) If you do not have Matlab, you can download standalone Windows or Mac versions of PIDtoolbox. You must first install Matlab runtime using the MyAppInstaller_web file included in the package (under PIDtoolbox\runtime_installation_file\). 64 bit only! It's a fairly big download so hang in there :-) If you already have Matlab runtime with an older version of PIDtoolbox, you do not need to reinstall it, but I would recommend deleting/archiving the old version of PIDtoolbox before running the latest version.

  • Download the latest version of PIDtoolbox standalone for Windows or Mac 64 bit only!. Unzip and place entire folder in a preferred location on your computer. The PIDtoolbox program file can be found under PIDtoolbox\main\. The contents of the main folder should not be moved. PIDtoolbox uses blackbox_decode from Betaflight/Cleanflight Blackbox Tools, which is conveniently packaged within this download. The blackbox_decode program file should also remain in the main folder. Please place your .bbl or .bfl log files right in that same main folder. Disclaimer: Personally I've had no issue with placing my log files anywhere on my computer as long as blackbox_decode is in there with them, but in the interest of having less reported issues, I'm erring on the side of caution with these recommendations, but feel free to experiment.

  • PIDtoolbox has been confirmed to run on Windows7/8/10 64bit machines, and Mac 10.11 (El capitan), 10.13 (Sierra) and 10.14 (Mojave). If you have issues installing Matlab runtime, or running PIDtoolbox, please post feedback here, or post a response in the Betaflight BlackBox Log Review Facebook group.

Quick Guide

For a detailed guide to PIDtoolbox, please visit the PIDtoolbox Wiki page.

For a quick guide, follow the steps below:

(i) Older versions of PIDtoolbox (pre v0.2) used .csv files exported from Betaflight Blackbox-log-viewer. PIDtoolbox v0.2+ has done away with that step, and now reads .bbl or .bfl files directly by decoding them using blackbox_decode (Betaflight/Cleanflight Blackbox Tools), which is conveniently packaged within the PIDtoolbox download. Just place your .bbl or .bfl files right in the main folder where the PIDtoolbox and blackbox_decode program files are already located. As stated earlier, the contents of this folder should not be moved. Start the program, select the file(s) you wish to load, then click load+run. NOTE: the Mac version does not show a "splash screen" when you run the program (an issue with Matlab for Mac), so it may seem like nothing is happening, but please be patient while it to loads.

(ii) It is recommended to log at 2k (unless you're running 1k loop rate in which case log at 1k), because the spectrograms only go to 1k. It is not recommended to log higher than 4k. It'll run, but much slower.

(iii) It is recommended that you set debug mode to GYRO_SCALED for PIDtoolbox. This is because the program expects the debug variables to contain the unfiltered gyro data, which is used to plot the filtered vs unfiltered gyro spectrograms, and compute gyro phase latency online. If you are using RPM filter in BF4.0, PIDtoolbox v0.2+ will recognize if you have debug mode set to DSHOT_RPM_TELEMETRY, and will plot RPM data along with motor signals in the Log Viewer. Just be aware that the debug mode you choose will result in different data contained in the 'gyro unfiltered' variable. For a list of debug modes and the data contained in the debug variable, see the Betaflight debug modes wiki.

If you have issues installing Matlab runtime, or running PIDtoolbox, please post feedback here, or post a response in the Betaflight BlackBox Log Review Facebook group.

I hope you find PIDtoolbox useful, and I welcome feedback from the FPV community.

Cheers! -Brian

You can’t perform that action at this time.