# How to Read Betaflight Blackbox Logs for Precision PID Tuning
Blackbox is the closest thing FPV pilots have to a flight data recorder. Every gyro twitch, every motor command, every PID correction — it’s all logged at your configured sample rate. Learning to read Blackbox logs transforms PID tuning from guesswork into data-driven precision. This guide covers how to record, open, and interpret Blackbox data.
## Enabling Blackbox Logging
First, confirm your flight controller supports Blackbox. Most F4/F7/H7 boards include either onboard flash memory or an SD card slot. Check the Betaflight Ports tab — if you see a “Blackbox Logging” option, you’re good.
| Storage Type | Capacity | Speed | Best For |
|————-|———-|——-|———-|
| Onboard Flash (8-16MB) | 5-10 minutes at 2kHz | Fast | Short tuning sessions |
| SD Card (up to 32GB) | Hours at 2kHz | Fast | Full-day flying analysis |
| OpenLager (external) | Up to 32GB via SD | Very fast | Professional tuning, high-rate logs |
### Configuration
1. Betaflight Configurator → **Blackbox** tab.
2. Set **Blackbox logging device** to your available storage.
3. Set **Blackbox logging rate** to 2kHz (2000 samples/second) for PID tuning. 1kHz is sufficient for general troubleshooting. Lower rates miss critical oscillation data.
4. Enable **Debug Mode**: Set to `GYRO_SCALED` for tuning. This logs the raw gyro data before and after filtering — essential for identifying noise sources.
5. For SD card users: format the card as FAT32 first. A full card silently stops logging with no warning.
### Triggering a Log
– **Arm switch**: The simplest method. Logging starts when you arm and stops when you disarm. Each flight is one log file.
– **Manual switch**: Assign a switch in the Modes tab to `Blackbox Log`. Useful for logging specific maneuvers.
– Always log at least 30 seconds of hover, a punchout, and several flips/rolls for a useful tuning dataset.
## Opening and Navigating a Log
1. Download the log file from your FC (via USB mass storage mode or by removing the SD card).
2. Open [Betaflight Blackbox Explorer](https://github.com/betaflight/blackbox-log-viewer) in Chrome/Edge (it’s a web app — no installation needed).
3. Drag your `.BFL` or `.BBL` file into the browser window.
The interface has three main panels:
| Panel | What It Shows |
|——-|————–|
| Graph (top) | Time-series plots of gyro, PID, motor, and RC signals |
| Legend (right) | Toggle which traces are visible on the graph |
| Spectrogram (bottom) | Frequency-domain view — where noise lives in the spectrum |
## The Three Graphs That Matter Most
### 1. Gyro vs. Setpoint (The “Tracking” Graph)
Enable these traces: `gyro_scaled[0]` (roll), `rcCommand[0]` (your stick input), and `setpoint[0]` (what the PID loop is targeting).
**What good tracking looks like:**
– The gyro trace follows the setpoint trace closely with minimal lag.
– After a sharp stick movement, the gyro overshoots slightly (5-10%) then settles within 2-3 oscillations.
– During steady hover, the gyro trace is a flat line with noise under ±5 deg/s.
**What bad tracking looks like and what to do:**
| Pattern | Symptom | Tuning Action |
|———|———|—————|
| Gyro lags behind setpoint by >50ms | P gain too low | Increase P gain by 5 |
| Gyro overshoots setpoint by >20% | P gain too high | Decrease P gain by 5 |
| Gyro wobbles 4+ times after a move | D gain too low | Increase D gain by 3 |
| Gyro trace is thick with noise | D gain too high or motor noise | Decrease D, check motors |
| Steady-state slow oscillation | I gain too low | Increase I gain by 5 |
### 2. Motor Output Trace
Enable `motor[0]` through `motor[3]`. This shows what the PID loop is commanding each motor to do.
**What to look for:**
– During a punchout, all 4 motors should rise symmetrically to 100%.
– During hover, they should hover around the same value (typically 20-30%).
– A motor trace that’s consistently 10%+ higher or lower than the others during straight flight indicates a thrust imbalance — check the motor or prop on that arm.
– Rapid sawtooth patterns on a single motor indicate a desync or bad ESC.
### 3. Spectrogram (Frequency Analysis)
The spectrogram is the single most powerful tool for diagnosing vibration and oscillation issues. It shows the frequency of noise at each moment in the flight.
**Reading the spectrogram:**
– The X-axis is time, Y-axis is frequency (Hz), color intensity = amplitude.
– **Vertical lines**: Noise at all frequencies simultaneously = impact (crash, hard landing, prop strike).
– **Horizontal lines that move with throttle**: Motor-related noise. The line frequency will be roughly `motor RPM / 60`. This is where RPM filtering helps.
– **Horizontal lines at a fixed frequency**: Frame resonance. Add a notch filter at this exact frequency.
**Common spectrogram signatures:**
| Signature | Meaning | Fix |
|———–|———|—–|
| Thick band at 200-300Hz, increases with throttle | Motor bearing noise | Replace bearings or motor |
| Thin line at 150-180Hz, constant | Frame resonance | Notch filter at that frequency |
| Noise spikes at exactly 50Hz or 60Hz | Electrical interference | Check FC ground, add capacitor |
| Wideband noise across all frequencies | Bent prop or loose frame | Inspect props, tighten all screws |
## A Complete Tuning Workflow Using Blackbox
1. **Log a test flight**: 30s hover → punchout to 100% → 3x full-deflection rolls → 3x full-deflection flips → land.
2. **Open in Explorer**: Check the gyro vs. setpoint graph first. Identify any tracking problems.
3. **Check the spectrogram**: Look for motor bands and frame resonances. Address mechanical issues before touching PIDs.
4. **Tune P**: Adjust P gain based on overshoot/undershoot. Fly again. Repeat until the gyro tracks setpoint with 5-10% overshoot.
5. **Tune D**: Look at the gyro trace after sharp moves. Reduce D if the trace is noisy, increase D if oscillations continue beyond 2-3 cycles.
6. **Tune I**: Check for steady-state drift on the gyro during hover or constant-rate turns. Increase I to eliminate it.
7. **Fly aggressive**: Repeat the test with faster, sharper moves. PIDs that work for cruising may not hold during snap rolls.
8. **Save**: Once dialed, save your PID profile. Take a final log as a “good” baseline for future comparison.
## Tooling Beyond Blackbox Explorer
| Tool | Purpose | Platform |
|——|———|———-|
| Betaflight Blackbox Explorer | Standard log viewer | Web (Chrome/Edge) |
| Plasmatree PID Analyzer | Automated PID recommendations from logs | Web |
| Betaflight TXT Log Converter | Converts BFL to CSV for Excel analysis | Cross-platform |
| PID Toolbox | Community tool for batch log analysis | Windows |
—
**Get your FPV build flying perfectly with precision components from UAVMODEL.** Flight controllers, ESCs, and motors — everything you need for a locked-in tune. [Shop at uavmodel.com](https://uavmodel.com)