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, but will also run EMU and INAV 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_web file 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 :-)
Once the installation is complete, the
PIDtoolbox program is automatically placed under the program files or apps directory (in windows it's under
C:\Program Files\PIDtoolbox\application), but a copy of the program file can also be found under
PIDtoolbox\main\ that you downloaded. Clicking either will start the program, but the shortcut that was created from the installation process links to the copy under the program files directory. I realize this may cause some confusion to have two copies of the same program but either should work fine, and as you update to later versions it is okay to keep old versions, and both will continue to function no problem. However, it's important to note that PIDtoolbox uses
blackbox_decode which you can see along side the PIDtoolbox program (it's there in the main folder you downlaoded but also in the PIDtoolbox program files directory). The
blackbox_decode program file should be placed anywhere your logfiles are placed; it MUST to be in the same folder as the logfiles, and you can copy
blackbox_decode multiple times all over your computer, that's fine. It doesn't take up much storage. FYI,
Blackbox_decode is part of the blackbox_tools software Betaflight/Cleanflight Blackbox Tools, but that application is just conveniently packaged within this download. 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, it might sometimes be best to keep it next to the PIDtoolbox program and place logfiles in there, but feel free to experiment.
There have been reports of PIDtoolbox hanging at different stages. If it hangs at the splash screen this may be indicative of the user rights and write access of the folder where PIDtoolbox is located. Right click on the
PIDtoolbox_vxx_win folder and make sure it is NOT "read only" and that you have full rights to that folder. The same might apply to the program if used from the program files directory. It has also been noted that you should run PIDtoolbox as an administrator in Windows if possible. If instead PIDtoolbox hangs or gives an error message during loading of a logfile this is usually an issue with
blackbox_decode described above (i.e., blackbox_decode is probably not in the folder of the logfile you're trying to open). I've also seen cases were logfiles with the same name but in different folders downstream of PIDtoolbox get confused by the program, so to avoid this try naming logfiles uniquely. Hopefully this solves some of the main reported issues. You can also look at the Github Issues reported here which have described some solutions to common problems. I requested that these issues remain posted to help future users.
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!. In fact never try to install Matlab runtime without the provided installer because the version is critically linked to the program, and if you downloaded a different version of Runtime than the one in which PTB was compiled, it wont work. So if you had a working version of PIDtoolbox but then it stops working from some reason, I've never seen a case where reinstalling runtime resolved the issue, so that should be a last resort. When you download a new version of PTB, you can either remove the old executable
PIDtoolbox.app and simply copy paste the new one in its place, or keep both in different folders. I.e., you may have multiple versions of the PIDtoolbox program on your computer. Both will run using the same Matlab Runtime that was installed during the original download. So whenever a new version of PTB appears, just download the
PIDtoolbox_vxx_osc folder and navigate to the
main folder in there and run the program. That's all there is to it, no more downloading!!!
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.
For more advanced users, 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 reads
.bfl files directly by decoding them using
blackbox_decode (Betaflight/Cleanflight Blackbox Tools), which is conveniently packaged within the PIDtoolbox download. Just place your
.bfl files right in the main folder where the
blackbox_decode program files are already located. Start the program, select the file(s) you wish to load by clicking the
select file(s) button. 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. 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.
- Linux users:
The latest working version for Linux users is v0.392. In most cases you'll have to run PTB from the command terminal, so navigate to the
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!).
Huge shout out to several people who contributed to this project outside GitHub. Mark Spatz (UAVtech), Chris Thompson (ctzsnooze), Hugo Chiang (DusKing1), Qopter, Qratz, Zach Young, Zak Smiley, Stephen Wright, McGiverGim, Bizmar, Martin Hapl, Ken Kammerer, Paweł Spychalski, Christoph Herndler. Thanks for your help!
I hope you find PIDtoolbox useful, and I welcome feedback from the FPV community.