Betaflight blackbox analysis: which tool for what?

You have a blackbox log and want to know what it tells you? This guide covers what Betaflight 2026.6.2 writes into the log, which trace answers which question and which tool analyzes it: the Blackbox Explorer in the Betaflight App, PIDtoolbox, PIDscope, PID-Analyzer, FPVtune, PIDoctor and fpvrates. Backed by the source code, the Betaflight docs and the tools’ own pages. The guide How to use Blackbox Explorer explains how to operate the Explorer.

Quick: which question, which trace, which tool

The trace names are the ones from the Blackbox Viewer tab of the Betaflight App, where they are in English in every language. Click a question to jump to its section.

Which question each blackbox log trace answers and which tool analyzes it
Your questionWhat to look at in the logTool
Do my rates fit my stick?RC Command and Setpoint per axis, counted over the whole flight; the flight’s rates are in the header linesfpvrates (zones, unused stick travel, steepness); Blackbox Viewer for single moments
Does the quad follow my stick?Gyro against Setpoint; the viewer computes PID Error from themBlackbox Viewer (“Error vs Setpoint”); step response: PIDtoolbox, PIDscope, PID-Analyzer
Propwash: does it wobble in descents?Gyro against Setpoint during speed changes and descents, throttle in RC Command [throttle]Blackbox Viewer (gyro and setpoint on top of each other, PID Error)
Is it vibrating, where does the noise come from?Gyro and Unfiltered Gyro, 2 kHz log rate; debug modes such as RPM_FILTER or FFT_FREQAnalyser in the Blackbox Viewer (spectrum, PSD); PIDtoolbox, PIDscope, PID-Analyzer
Which PIDs and filters should I use?Gyro, setpoint, PID terms and spectrum; for the Autotune tab a log with a chirp sweepValues are suggested by: FPVtune, PIDoctor, the Autotune tab of the Betaflight App, PIDscope. Not fpvrates
Do the motors hit their limit?Motor [1] to [4] in %, seek bar “Maximum motor differential”Blackbox Viewer
Does the battery sag?Battery volt. (total and per cell), AmperageBlackbox Viewer (“Statistics” for the lowest value)
I want to crunch the numbers myself (spreadsheet, Python)all fields as CSVCSV export in the Blackbox Viewer; blackbox_decode from the blackbox-tools

About what the blackbox records, the Betaflight docs say: “This is all stored without any approximation or loss of precision, so even quite subtle problems should be detectable from the flight data log.” Which traces your log contains depends on what you switched on; more on that under What Betaflight writes into the log.

Do your rates fit? Stick and setpoint

RC Command is the stick position as Betaflight processes it, for roll, pitch, yaw and throttle; since Betaflight 4.3 it is logged un-smoothed (4.3 Tuning Notes). Setpoint, according to the source code, is the target turn rate in °/s handed to the PID controller, in other words what your rates make of the stick position (blackbox.c). Put both traces on top of each other and you see your rates curve at work. The header lines tell you which rates the log was flown with; the Explorer guide shows how to read them.

A single moment doesn’t tell you whether the rates suit you, though. That takes the distribution: how often is your stick where, how far do you go in normal flying, how much stick travel goes unused? The Explorer doesn’t add that up; its “Statistics” only know minimum, maximum and mean (more in the Explorer guide).

That is exactly what fpvrates works out from the same log: from RC Command, setpoint and gyro it measures five zones on your stick (fine, precision, normal flying, unused, flips & rolls) and whether your curve gets too steep towards the edge. Only acro counts; fpvrates sorts out angle and horizon flights, because there the quad stabilizes itself and the rotation doesn’t come straight from your stick. The free check shows you this without an account and without suggested rates. Matching Actual Rates as a CLI block for the Betaflight App come with the Tuning Pass for €19 (1 quad) or €29 (5 quads), paid once. The analysis runs in your browser, the file stays with you. The guide Setting up Betaflight rates explains how to set rates.

How well do your rates fit your stick? The free check measures it on your blackbox log. No account, the file stays with you.

Check my log for free

No log yet? See a real example · Turn on logging, with pictures

For your next flying day
  • Betaflight App, Blackbox tab: logging device onboard flash or SD card, logging rate 1 kHz
  • RC Commands, Setpoint and Gyro on, then “Save and reboot”
  • Fly 3 to 5 packs of normal acro
  • Then get the log off the quad and drop it into the free check

Does the quad follow? Setpoint, gyro and propwash

Gyro is the turn rate the quad actually flies, after the filters (blackbox.c). If gyro sits on setpoint, the quad does what you ask for. The Blackbox Viewer computes the gap itself as the trace PID Error: setpoint minus gyro (flightlog.js). In the spectrum analyzer, “Error vs Setpoint” shows the mean error per turn rate (graph_spectrum_calc.js).

According to the PID Tuning Guide in the docs, “Prop wash happens when changing speed or if you suddenly accelerate from a dead stop”; the turbulence from the props makes the quad unsteady while steering, worst “in vertical descents”. The docs evaluate propwash by “How gyro is following setpoint” and note that “propwash also generates PID error”. So in the log you look for speed changes and descents, such as the moments after you chop the throttle (RC Command [throttle]), and compare gyro with setpoint there. What helps against propwash, from flying style to the D-term, is in Propwash: what it is, what helps.

The step response shows how cleanly gyro follows a quick stick input. PIDtoolbox, PIDscope and Plasmatree’s PID-Analyzer compute it; according to its README, the PID-Analyzer works it out from setpoint and gyro. This guide deliberately doesn’t cover what to change in your PIDs: fpvrates measures rates, not PIDs and filters. If your quad flies twitchy, Twitchy quad: causes and fixes goes through the causes one by one.

Vibration and noise: gyro, spectrum, filters

Next to gyro there is Unfiltered Gyro, the turn rate before the filters (blackbox.c). The difference between the two shows what the filters take out. Press A and the viewer opens its spectrum analyzer. It shows the spectra “Frequency”, “Freq. vs Throttle”, “Freq. vs RPM”, “Power Spectral Density”, “PSD vs Throttle” and “PSD vs RPM” (SpectrumAnalyser.vue). According to the Betaflight blog it draws your configured filter cutoffs on top, “so you can see exactly where each one sits against the noise you actually recorded”. According to the docs, the view against RPM helps most when the RPM filter is running.

Noise needs a high log rate, see Log rate and debug mode. A debug mode adds more traces: according to the docs, “RPM_FILTER logs the frequency of each motor as reported by the ESC”, and FFT_FREQ logs the center frequencies of the dynamic notch filters (Debug Modes).

Spectra and heatmaps over throttle or time are also in PIDtoolbox and PIDscope, noise plots in the PID-Analyzer. The docs recommend PID Toolbox for spectral analysis in several places, for example on the RPM filter page: “Black box logging, before and after, and using PID Toolbox to look at the spectral graphs is very useful.”

Motors and battery

Motor [1] to [4] is the output to each motor; the viewer shows it in percent (flightlog_fields_presenter.js). For the seek bar you can pick “Maximum motor differential” to jump to the moments with the biggest difference between the motors. The 4.2 Tuning Notes explain what that means, with fast yaw inputs as the example: with “one pair at 100% and the other at zero”, “the quad cannot deliver what you are asking it to do.”

With bidirectional DShot, Betaflight also logs the speed of each motor (RPM [1] and so on); the viewer converts it to rpm and Hz using the motor pole count from the log. Battery volt. shows the voltage in total and per cell, Amperage the current. The lowest value of a flight is under “Statistics”.

What Betaflight writes into the log

You choose which fields end up in the log in the Blackbox tab of the App, in the “Debug Fields included” box; all are on by default. The guide Blackbox logging: setup and downloading your log shows how. This is what the switches stand for (source code blackbox.c, Betaflight 2026.6.2):

  • PID: P, I, D and feedforward per axis, in the viewer “PID P”, “PID I”, “PID D” and “PID Feedforward”. D is only logged for axes whose D is not zero. The viewer computes “PID Sum” itself.
  • RC Commands: the stick positions of roll, pitch, yaw and throttle.
  • Setpoint: the target turn rate per axis and the throttle the mixer finally uses.
  • Gyro and Gyro (Unfiltered): the measured turn rate after and before the filters.
  • Motor and RPM: the output to each motor and, with DShot telemetry, its speed.
  • Battery and RSSI: voltage, current and signal strength.
  • Accelerometer, Attitude, Magnetometer, Altitude, GPS, Servo: acceleration, attitude, compass, altitude, position and servos.
  • Debug Log: eight values whose content the debug mode decides.

On top of that Betaflight writes header lines with the flight’s settings: firmware version, board, craft name, rates, PIDs, filters and feedforward (blackbox.c). According to the Betaflight blog, the viewer in the App reads these header lines too, “so the settings that produced a trace are never more than a tab away”.

Log rate and debug mode

By default Betaflight logs every fourth pass of the control loop. The docs: “1/4 gives approximately 2 kHz logging and 1/8 gives approximately 1 kHz. A rate of 2 kHz is recommended for detailed tuning analysis; 1 kHz is sufficient for general use and reduces storage requirements.” The 4.3 Tuning Notes name “1kHz for normal purposes, 2Khz for filter tuning”, and at 1/16, according to the blackbox docs, you only catch gross problems, not vibration. For fpvrates, 1 kHz with RC Commands, setpoint and gyro is enough.

The debug mode is NONE by default, so Betaflight writes no debug values. You set it in the Blackbox tab or in the CLI with debug_mode; only one is active at a time. Watch out with older guides: the PID Tuning Guide in the docs still names GYRO_SCALED, which Betaflight 2026.6.2 no longer knows (debug.c). Today you get the unfiltered gyro through the Gyro (Unfiltered) field.

The tools at a glance

The Betaflight docs list four tools under “Analysis Tools” in the PID Tuning Guide: Blackbox Explorer, PID Toolbox, Plasmatree and blackbox-tools. PIDscope, FPVtune and PIDoctor don’t appear in the docs. Prices and status as stated on the providers’ pages on November 12, 2026.

Blackbox Viewer (Blackbox Explorer) in the Betaflight App

According to the Release Notes 2026.6, you inspect a log “with configurable graphs, a spectrum analyser, a 2D/3D craft attitude view, a GPS map, time-line playback, and CSV export”. Suggested settings are not part of that list. It runs at app.betaflight.com and in the desktop and mobile builds of the App, open source (GPL-3.0). Since 2026.6 it is a tab of the App; the old standalone Explorer is feature frozen, and per its README “This repository will be archived on 1 December 2026”. How to use it: How to use Blackbox Explorer.

Autotune tab of the Betaflight App

New in 2026.6, experimental and only visible in expert mode. It “imports a log containing chirp sweep data” (flight mode CHIRP), computes the frequency response and “recommends Simplified Tuning slider values”; with a flight controller connected, “Apply Gains” writes them back (Release Notes 2026.6).

blackbox-tools

Command-line programs from Betaflight: blackbox_decode turns the log into CSV files, blackbox_render into a series of images for a video (README). Open source (GPL-3.0), last commit on October 25, 2026; GitHub currently lists no ready-made downloads. For a spreadsheet, the CSV export in the Blackbox Viewer is usually enough.

PIDtoolbox

A program with a log viewer, step response, spectrum, heatmaps over throttle and time and a “PID slider tool”; the Pro version adds, among other things, a filter simulation and RPM and notch overlays (feature list on Patreon, October 1, 2026). Since May 2024 new versions are only available through Patreon: the download comes with the paid tiers at 6 Canadian dollars (standard) or 8 Canadian dollars (Pro) a month. Its last GitHub description says it runs on Windows and Mac. Latest version according to Patreon: V094 of August 2, 2026. The GitHub repository and the PIDtoolbox link in the Betaflight docs now return a 404 error.

PIDscope

“A free, open-source GNU Octave fork of PIDtoolbox”: spectra, step response, noise heatmaps, PID balance and filter delay, plus an autotune modeled on the Betaflight App’s. Its README says: “There is no paywall, no "PRO" tier, no subscription”. Open source (GPL-3.0), for Windows, macOS and Linux. Version 26.10.1 of October 30, 2026.

PID-Analyzer (Plasmatree)

A Python program that “reads Betaflight blackbox logs and calculates the PID step response”, plus noise plots; the result comes as a plot and a PNG. It needs blackbox_decode and is available as source code and a Windows program on GitHub. Last version 0.52 of June 8, 2018, per the README tested with Betaflight 3.x logs. Whether it works with current logs isn’t stated anywhere.

FPVtune

A web service: you upload your log and CLI dump and get values for PIDs, filters and feedforward as CLI commands, computed by a neural network according to the provider. For logs from Betaflight 4.5 on. According to the pricing page, $9.90 per tune or a subscription from $19.95 a month billed yearly.

PIDoctor

A web service for Betaflight 4.x: a diagnosis with FFT spectra, filter effectiveness, step response and a tune score, plus “Rule-based suggestions for PIDs and filters” as CLI commands that it can also write straight to the connected flight controller (pidoctor.app). Free according to its terms, donations are voluntary. Per its privacy policy, the provider stores uploaded logs under your account on its server.

fpvrates

Measures how you use your stick: zones, unused stick travel and whether the curve gets too steep towards the edge. The free check shows this without an account and without suggested rates; the Tuning Pass for €19 or €29, paid once, gives you matching Actual Rates as a CLI block, with as many rounds as you like. For Betaflight 4.3 and newer with Actual or Betaflight rates, flown in acro. The analysis runs in your browser, the file stays with you. fpvrates deliberately doesn’t do PIDs and filters.

Sources

As of November 12, 2026, checked against Betaflight 2026.6.2 (firmware and App of September 16, 2026, the latest versions on that day):

Last updated: Nov 12, 2026 · checked with Betaflight 2026.6.2