Home
This wiki assumes the reader has some knowledge about tuning and filtering for multirotors. PIDtoolbox is certainly designed for the person who likes to tinker in the details to get the best possible flight performance, but it is mostly straightforward and this wiki should help people new to the hobby as well. If you are new to blackbox log analyses in general, and tuning/filtering in particular, there are lots of relevant videos. Here are a couple I recommend:
UAVtech (Mark Spatz) was kind enough to feature an earlier version of PIDtoolbox on his YouTube channel (video on PIDtoolbox v0.12), and some of that info is still relevant here. Please stay tuned to his channel for an update on the latest version!
The wiki contains a detailed user guide divided into 5 main sections:
- Basic setup
- Log Viewer
- Spectral Analyzer
- PID Error Tool
- Step Response Tool
(i) PIDtoolbox_v0.2 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 v0.2 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.
(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.
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) and clicked the green load+run button, the data should begin loading. It's usually fast but will depend on the file log rate and log length (2kHz log rate is recommended). Once the data are loaded, you should see several plots showing the roll, pitch, and yaw axes for log files [A] and [B], respectively (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 (if you are using RPM filters in BF4.0+ and debug mode is set to DSHOT_RPM_TELEMETRY, RPM data will be plotted in black along with each colored motor signal). 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 and load+run buttons mentioned earlier, there are several grey 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 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. 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 direct accurate 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.
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 detailed by others (see for example the Plasmatree PID analyzer wiki), so I will not go into too much detail. Mainly, I will describe what is new and different about this tool.
First, click on the Step Response button in the Log Viewer. This will automatically start computing step response functions for the roll, pitch and yaw axes for both log files. Generally speaking, this 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 dashed traces represent 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.
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.
Here is another couple of examples with higher D gains resulting in less overshoot but much slower rise time and peak time. The ideal tune is probably somewhere between the above and below examples.
