PIDtoolbox user guide
My apologies, but his wiki is very outdated. I intend on updating it soon!
This wiki assumes the reader has some knowledge about tuning and filtering for multirotors, but may not be perfectly up to date with the latest release. For those who prefer 1-on-1 help, I have a Professional PID tuning service.
If you are new to blackbox log analyses there are plenty of online resources. Here are a few I recommend:
- PIDtoolbox YouTube Channel
- UAVtech YouTube Channel
- Betaflight Wiki
- Betaflight filtering 101 by Stephen Wright (SupaflyFPV.com).
The wiki is divided into 5 main sections:
(i) PIDtoolbox reads .bbl or .bfl files directly by decoding them using blackbox_decode (a part of the 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. The contents of this folder should not be moved. Assuming you've successfully installed Matlab Runtime (otherwise see Download instructions on the main page), click PIDtoolbox to run the program. 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 for spectral analyses, but 1k is sufficient for step response curves. 2k allows you to see noise up to 1000Hz (1k is limited to 500Hz; half the lograte because of the Nyquist limit). Estimated phase latency precision is also tied to the lograte. If logging at 1k, estimated phase delay precision is 1ms, at 2k precision is 0.5ms, 4k 0.25ms and so on. Just note that 4k+ logfiles will be slow to process so the only reason you'd want to log at such high rates would be for testing phase delay with higher precision, but it's best to do this with very short logfiles, hovering with some roll input line of sight for 20sec should be sufficient (it calculates phase delay from the roll axis only).
(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. 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.
The log viewer is the first window you will see when running PIDtoolbox, and is the main control window for the program. After you've selected the file(s) the data should begin automatically loading. Once the data are loaded, you should see several plots showing the roll, pitch, and yaw axes for the logfile highlighted in the dropdown menu (see below). By default the plots are zoomed all the way out showing the entire duration of each flight. At the top is a list of check-boxes that turn on or off a given trace. Each plot is divided into an upper portion that shows the variables coded in degs/s, and the lower portion (separated by a horizontal line at the 100% point) plots the variables that are coded in % output, such as throttle and motor signals. Generally speaking, you should always set debug mode to GYRO_SCALED which puts scaled unfiltered gyro data in the debug variable, and is what PIDtoolbox expects. Just be aware that the debug mode you choose changes what "gyro unfiltered" means. For a list of debug modes and the data they output see Betaflight's debug mode wiki.
The control panel on the right side of the Log Viewer contains several buttons and input boxes. Besides the select files button mentioned earlier, there are several buttons, each of which opens a new window for its specific tool. The input boxes specify the start and end point of each data file in seconds. The temporal window you set here dictates the data range in which all other tools/analyses operate. The goal here is to set the window to include only actual flight data, and to exclude data before you took off and after you landed, which can contain jumps in the gyro response that you do not want to include in analyses. There might be instances where it is best to set the window so that the duration is the same for [A] and [B], but in general this is not necessary since the results are normalized (that's just a fancy way of saying they are all on a comparable scale). This allows for apples-to-apples comparisons.
If you click on the white space of any of the 6 panels, it expands to full screen (see below). Click the magnify+ tool to zoom in on any section of the plot, by selecting and dragging the cursor over the trace region you would like to zoom. NOTE, for Windows, this is found in the upper left of the main window, and for Mac, this is superimposed at the upper right portion the panel/plot in which your cursor is currently located. To return to full view, simply click within the white space again (remember to turn off the magnify tool, or any other that is highlighted, to do this). Another useful tool in this upper panel is the data cursor, which allows you to see detailed information associated with any point on any trace (time in sec with 3 decimals, and degs/s). Another feature worth mentioning is that PIDtoolbox reads your screen size and the size you have the window opened to, and then scales font size and other buttons accordingly. For example, if you have a large screen and you open the window to full, everything will scale accordingly, once you make a new selection. The Save Fig button will save whatever is in the current view, and put it in a folder named after the logfile names in the main folder. It will never overwrite a figure. A Save Fig button exists on all analysis tools/windows. Lastly, the setup info button opens a new window with a list of all the Betaflight settings associated with each log file.
Click the spectrogram button in the Log Viewer to open the Spectral Analyzer window. At the top of this window is its main control panel. It is divided into 4 columns each with a main dropdown menu. Select from each dropdown the variable you want to plot. The options are Gyro, Gyro unfiltered, PID error, Set point, Pterm, Dterm, Dterm unfiltered, Motors, and RPMs (when debug mode = DSHOT_RPM_TELEMETRY). Notice that each variable name ends with [A] or [B] denoting the given log file. Typically, you might assign [A] and [B] variables for the left and right columns, respectively, to make direct comparisons between them, but any combination of variables can be plotted. You can think of these as 4 independent spectral analyzers (e.g., all 4 columns can plot variables from log file [A] or [B] or any combination of the two). Next, click run. This will take a minute or so to compute and generate the plots, and will depend on lograte and file length (2k logging is optimal). In the plots below you can see the spectrograms for unfiltered and filtered gyro data for log file [A] and [B]. The unfiltered plots show the characteristic motor noise band and harmonics as a function of % throttle. If you select the data cursor tool then click on any part of the plot you will see the exact frequency (Hz), throttle (%T), and amplitude of the noise (Z) at that point. You can drag it around, and add multiple data cursors as well. This can be a very useful tool.
Each column of plots has its own scaling factor input-box next to each colorbar. The default is 0.5 and works well in most cases, but sometimes it helps to change the scale to see better detail. Just remember when comparing between plots that it is best to set the scales the same.
The % throttle / % motor dropdown menu (top left) specifies whether you want the data plotted against % throttle output, or % motor output. Traditionally, we are use to seeing % throttle on the x-axis (from Plasmatree PID-analyzer), but the % motor option is included because technically there are many cases in which throttle might be at 0 yet motor output is high (e.g., when doing flips/rolls), and will therefore induce relevant vibration that would otherwise show up at the zero throttle position in the spectrogram. Generally speaking, the results do not usually look that different using either, but the option is there. Note, you will have to click run to re-plot each time you change this option. Most of the other options work instantaneously.
Next to this is the colormap dropdown menu. This simply specifies the color profile of the spectrograms. Default is hot. Some are more "linear" looking colormaps, but I chose hot as default because it tends to show detail really well. Some may prefer viridis because it resembles the colormap used in the Plasmatree PID-analyzer. linearREDcmap and linearGREYcmap are decent options for more linear looking color grading. Next to this is the smoothing dropdown menu, which is self explanatory. The default of 3 seems to work fine, but sometimes more is better for sub 100Hz views.
Next to this you will see a subsampling dropdown menu. NOTE: Lower subsampling will compute faster, but may be less reliable for small/short log files, but if your log file is long, you might want to try the lowest subsampling option, since the function will have lots of data to work with.
Next to this you will see a check-box labeled 2-D. This toggles between the 3-D spectrograms and 2-D line versions (see below) of the spectra (the 2-D version is essentially what you see in Betaflight's blackbox log viewer. Note however, here both the spectrograms and 2-D spectral plots are normalized and do not require log files to be the same duration, which allows for apples-to-apples comparisons between flight logs without having to select a subset of the data to conform to a certain duration.
The < 100Hz check-boxes allow you to see the same data zoomed in from 0-100Hz (see example figure below). Here you will see a yellow dashed line at the 20Hz point. This delineates the point between "commanded motion" (i.e., everything below 20Hz is 'good' motion related to the real flight characteristics you are interested in), and "uncommanded motion" (i.e., ~20Hz to ~100Hz which is where we see things like propwash, midthrottle oscillation, and other undesirable vibrations). As a rule of thumb, you want to see little activity between ~20Hz to ~100Hz. Some is normal, but too much may be indicative of undesirable vibrations/oscillations (as in the example below which shows a clear oscillation centered at ~40Hz across several variables). It is certainly not recommended to filter down this low (for reasons related to phase latency), but analyzing sub 100Hz spectra can give you insight into vibration or mid throttle oscillation issues you may be having, and might also be useful as an index of how well the copter is handing propwash scenarios.
One of the unique features of PIDtoolbox in general is that most of the plots also have superimposed numerical results right on the plots which allow for more accurate, and objective, comparisons between log files. For the spectrograms, you will notice mean and peak values, which refer to the average and maximum over a specified freqency range. In full 1000Hz mode, the range over which the mean and peak are computed is 100Hz to 1000Hz (covering the complete motor noise bands of most copters). When in sub 100Hz mode, the range over which the mean and peak are computed is 20Hz to 100Hz (the uncommanded motion range).
Lastly, the upper right shows the estimated phase delay associated with the current filter settings of each log. NOTE, this is an estimation using cross correlation lag technique and is computed on the roll axis only since this is usually the axis with the greatest modulation in RC input, which is required for a reliable estimate (after all, you can't see a delay between two signals that are flat). Debug mode must be set to GYRO_SCALED for meaningful results. As a rule of thumb, less filtering will result in lower phase latency, and ideally the lower this number the better for handling of propwash and other vibration inducing turbulent air. You should aim for < 5ms total latency if possible, but this will depend on how little filtering you need.
PID error is the difference between the input (what you want the copter to do) and output (what the copter actually does). Specifically, the input is called the set point (which is essentially RC input in deg/s) and output is the gyro's response to the copter's motion. Thus, the ideal copter is one in which PID error is minimal. This makes PID error analyses another good measure of a copter's performance.
Clicking the PID error button in the Log Viewer will open a new window and immediately formulate several plots (see below). The left 3 panels show PID error distributions for roll, pitch and yaw, respectively, with orange indicating log file [A], and blue log file [B]. Another way to think about these distributions is in the next figure, which shows a PID error distribution rotated 90deg. You can see that these distributions are just a normalized summation of the PID error trace (purple trace on right), collapsed across time. The basic take home here is the narrower these distributions are the better. Superimposed in the upper right of the three PID error distributions in the main figure shows the standard deviation (s.d.), which is just a fancy way of quantifying the spread or width of the distributions. The 'p' statistic represents the probability that the observed difference between the distributions is due to chance. An '*' after the number indicates they are statistically different (i.e., p<.05, meaning there's less than 5% probability the difference is due to chance). For now, don't worry too much about the p values. The main thing is narrower = better, generally speaking. The panels on the right side show the average (mean) of the absolute value of PID error across different stick inputs. We take the absolute value of PID error here because otherwise the average would always be ~zero. The take home here is lower = better. The motivation for plotting as a function of stick deflection is because greater deflection tends to produces greater error, which is expected during snap flips/rolls where the Set point quickly gets ahead of the gyro. Thus, we might want to know the state of PID error without these large impacts due to fast maneuvers (for example if we just want to get an index of how smooth the copter is flying during steady cruising). For this reason, we included an input box above the PID error distributions which sets a cut off. By default it is set at 100, which means the distributions only contain data in which Set point (RC input or 'max stick') was <= 100 deg/s.
A PID toolbox would not be complete without a step response tool. The step response function provides an objective measure of a copter's tune. Tuning and interpreting the step response has been well described in many on line sources (see example below), so I will not go into too much detail. Here, I will describe what is new and different about this tool.
- Animation illustrating the effect of each term on the step response (from https://en.wikipedia.org/wiki/PID_controller#Manual_tuning)
First, click on the Step Response button in the Log Viewer. You will see a few options at the top. The only one you may want to adjust is the subsampling dropdown menu. NOTE: Lower subsampling will compute faster, but may be less reliable for small/short log files, but if your log file is long, you might want to try the lowest subsampling option, since the function will have lots of data to work with. Next, click run to start generating the plots. Generally speaking, this step response tool works very similar to Plasmatree in that it uses a sophisticated method called Wiener deconvolution. For those interested, the details can be found in PTstepcalc.m. Below is an example, showing mean (+/-s.d) step response functions for logfile [A] (orange) and [B] (blue). The shading represents the +/-standard deviation. What is new here is the information provided and superimposed at the right side of each panel. There you can see detailed info regarding the quality of the response, including the peak, peak time (in ms), % overshoot, rise time (in ms) and settling points. N refers to the number of data segments that went into the mean (average) trace. As always, the goal of a good tune is the have the step response track the set point as quickly as possible without too much overshoot and subsequent ringing, which you can see is a bit of an issue for log file [A]. Thus, the goal is fast rise time and peak time with not too much overshoot and quick settling on the set point target of 1.
The step response is shaped by your PIDs. Generally speaking, higher P gains will produce more overshoot, faster rise time, and earlier peak times, but may induce a ringing or ripple, usually fairly close together in time (as in example [A]). Increasing D gain tends to oppose this, and will generally reduce overshoot and ringing, but will also result in slower rise time and peak time. If P is too low and/or D too high, the initial peak may not reach the set point target of 1, and in these cases the peak may be shifted fairly late in the curve. It is important to understand that many of the new features in Betaflight may also impact aspects of the step response (for example feed forward, or d_min in Betaflight 4.0, which dynamically changes D gain depending when it's needed).
Below are another couple of examples with higher D gains than the example above. Notice the reduced overshoot but also slower rise time and peak time in comparison to the previous example.
The > 500deg/s button plots the step response for the data where set point (RC input) exceeded 500deg/s, for example during snap flips and rolls. This will require that you actually did fast manoeuvres on each axis, so when recording blackbox data for tuning purposes you should keep this in mind. Usually it’s the yaw axis that is missing here because we don’t often do fast yaw moves, but it’s worth doing them if you really want to see how your copter performs at the extremes.