Need help with PIDtoolbox?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

138 Stars 22 Forks GNU General Public License v3.0 249 Commits 23 Opened issues


PIDtoolbox is a set of graphical tools for analyzing blackbox log data

Services available


Need anything else?

Contributors list

No Data


PIDtoolbox is a set of graphical tools for analyzing blackbox log data for multirotors. It is available as a standalone program for Windows, Mac and Linux, and is tailored to work for Betaflight and INAV logfiles, but should also run EMU flight logfiles. 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. Below is everything you need to begin using PIDtoolbox.


Download the latest version of PIDtoolbox. Unzip and place entire folder in a preferred location on your computer. For first time installation, use the

file included in the package (under
). 64 bit only! This will install Matlab Runtime, which contains the standalone set of libraries that enables the execution of compiled MATLAB application. It's a fairly big download so hang in there :-)

NOTE: if you already have a running version of Ptb, you DON'T need to re-run the installer. Just grab the new PIDtoolbox program file and replace with your old version!


program file can be found under
. The contents of the
folder should not be moved. PIDtoolbox uses
from Betaflight/Cleanflight Blackbox Tools, which is conveniently packaged within this download. The
program file should also remain in the main folder (or at the very least must be in the same folder as your
log files. 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), and Linux. 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 for Betaflight specific issues, or INAV official Facebook group for INAV specific issues.

  • If you have Matlab and all the required toolboxes you can simply download the source code (download from the zip file on the releases page for the most up to date and platform-specific source code), and run from the command window.

Quick Guide

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

For a quick guide, follow the steps below:

(i) PIDtoolbox (versions 0.2 onward) reads

files directly by decoding them using
(Betaflight/Cleanflight Blackbox Tools), which is conveniently packaged within the PIDtoolbox download (earlier versions required users to convert
files into
files). Just place your
files right in the main folder where the
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 by clicking the
select file
button, then click
. 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.

  • Linux users: In most cases you'll have to run PTB from the command terminal, so navigate to the
    PIDtoolbox folder from the command prompt and execute
    . You can try double clicking the '' icon directly in the
    folder (not the PIDtoolbox icon). If it doesn't work, run via the command prompt AND provide the path of the runtime installation as an argument: e.g.
    [[./]] /opt/matlab/matlab_runtime/v93
    . (Many thanks to Christoph Herndler (Ghostface) for helping get PTB for Linux working and providing these details!).

(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

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
, 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, or INAV official Facebook group for INAV specific issues.


I have to give a long overdue shoutout to several people who contributed to this project outside GitHub. Mark Spatz (UAVtech) has been a huge source of information for me in general and it was through conversations with him that motivated the development of this tool in the first place. Chris Thompson (ctzsnooze) has always supported the project and continues to contribute great ideas that are continually integrated into various revisions of the tools. DusKing converted the tooltips to Simplified Chinese language, and maintained and compiled this version for Chinese users. Many others have contributed thoughts and ideas that worked there way into various versions of the software, some of whom I only know by their Slack or Github name: Qopter, Qratz, Zach Young, Zak Smiley, Stephen Wright, McGiverGim, Bizmar, Martin Hapl, Ken Kammerer, Paweł Spychalski, Christoph Herndler. I will continue to update this list. Thanks for your help!

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

Cheers! -Brian

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.