PIDtoolbox is a set of graphical tools for analyzing blackbox log 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
MyAppInstaller_webfile included in the package (under
PIDtoolbox\runtime_installation_file\). 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!
PIDtoolboxprogram file can be found under
PIDtoolbox\main\. The contents of the
mainfolder should not be moved. PIDtoolbox uses
blackbox_decodefrom Betaflight/Cleanflight Blackbox Tools, which is conveniently packaged within this download. The
blackbox_decodeprogram file should also remain in the main folder (or at the very least must be in the same folder as your
.bfllog 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.
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
.bflfiles directly by decoding them using
blackbox_decode(Betaflight/Cleanflight Blackbox Tools), which is conveniently packaged within the PIDtoolbox download (earlier versions required users to convert
.csvfiles). Just place your
.bflfiles right in the main folder where the
blackbox_decodeprogram 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 filebutton, 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.
mainPIDtoolbox folder from the command prompt and execute
./run_PIDtoolbox.sh. You can try double clicking the 'run_PIDtoolbox.sh' icon directly in the
mainfolder (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.
[[./run_PIDtoolbox.sh]] /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
GYRO_SCALEDfor 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, 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.