# How to Use Betaflight Blackbox Log Viewer: Analyzing Gyro, PID, and Motor Data
Blackbox logging is the FPV equivalent of an airplane’s flight data recorder. Every oscillation, every desync, every poorly tuned PID — it is all recorded in the blackbox log. Learning to read these logs transforms you from a pilot who guesses at tuning into one who diagnoses with precision. This guide walks you through setting up Blackbox, opening logs, and extracting actionable tuning insights.
## What Is Blackbox?
Blackbox records flight controller sensor data at a configurable rate during flight. The log contains:
| Data Stream | What It Records | Sample Rate |
|—|—|—|
| Gyro (Raw) | Angular velocity on all 3 axes | Up to 8 kHz |
| PID Sum | Total PID output per axis | Gyro rate |
| P, I, D (Individual) | Each PID component separately | Gyro rate |
| Motor Output | PWM signal to each motor (0-100%) | Gyro rate |
| RC Command | Your stick inputs | Gyro rate |
| Setpoint | The target angular velocity | Gyro rate |
This means you can see exactly what the gyro measured, what you commanded, and how the PID controller responded — all timestamped to the millisecond.
## Setting Up Blackbox Logging
### Option 1: Onboard Flash (Recommended)
Many F7/H7 flight controllers include 8-128 MB of onboard flash. Enable in Betaflight:
1. Go to the **Blackbox** tab
2. Set **Blackbox logging device** to “Onboard Flash”
3. Set **Blackbox logging rate** to 2 kHz (4 kHz if tuning PIDs, 1 kHz if just checking for issues)
4. Click **Save and Reboot**
### Option 2: OpenLager / SD Card Logger
If your FC has no onboard flash, wire an external OpenLager module to a UART:
– OpenLager TX → FC RX (any free UART)
– OpenLager RX → FC TX
– Power (5V/GND)
– Set **Blackbox logging device** to “Serial Port” and select the UART
### What to Log
| Logging Goal | Rate | Why |
|—|—|—|
| General diagnostics | 1 kHz | Small files, covers motor/gyro health checks |
| PID tuning | 2 kHz | Enough resolution to see oscillations and overshoot |
| Noise analysis | 4 kHz+ | Reveals high-frequency motor/prop noise |
| Debug mode (specific) | 2 kHz | Use when chasing a specific debug flag |
Set `blackbox_mode = NORMAL` in CLI. Do NOT use GYRO_SCALED unless you are doing an expert-level noise analysis — it fills flash 4x faster with minimal benefit.
## Opening and Navigating Logs
### Step 1: Download Betaflight Blackbox Explorer
Available at: [https://github.com/betaflight/blackbox-log-viewer](https://github.com/betaflight/blackbox-log-viewer) — works in your browser (Chrome/Edge). No install needed.
### Step 2: Download the Log
Connect your FC via USB, go to the Blackbox tab, click “Save Flash to File.” This downloads a `.BFL` or `.BBL` file to your computer.
### Step 3: Open in Explorer
Drag the log file into Blackbox Explorer. You will see a graph window with multiple fields.
### Step 4: Set Up the Graph Layout
For PID tuning, open these fields (checkbox on the right):
– `gyroADC[roll]`
– `rcCommand[roll]`
– `PID[roll]`
– `motor[0]` through `motor[3]`
– (Repeat for pitch and yaw as needed)
## Interpreting the Data: Key Patterns
### Pattern 1: Oscillations (P-Term Too High)
**What it looks like:** Gyro trace shows rapid sawtooth at the end of a move. Motor traces show matching rapid fluctuations.
**Fix:** Reduce P gain on the affected axis by 5-10 points. Re-log and compare.
### Pattern 2: Bounce-Back (D-Term Too Low)
**What it looks like:** After a sharp roll stop, gyro overshoots past zero, then bounces back. Setpoint is a clean step — gyro should follow it smoothly.
**Fix:** Increase D gain by 3-5 points or increase D-Min.
### Pattern 3: Slow Response (P-Term Too Low)
**What it looks like:** Gyro lags significantly behind rcCommand (setpoint). The quad does not rotate as fast as you commanded.
**Fix:** Increase P gain by 5-10 points.
### Pattern 4: Motor Saturation
**What it looks like:** Any motor channel reaches 100% output. This means the PID controller has run out of headroom.
**Fix:**
– Check if one motor is consistently higher than others (bent prop, bad bearing)
– Check if the battery is sagging (voltage drops below 3.3V/cell under load)
– Reduce P and D gains to leave headroom
– Consider higher-KV motors or lighter props
### Pattern 5: Noisy Gyro
**What it looks like:** Gyro trace has persistent high-frequency “fuzz” even during steady flight (no stick movement). This indicates mechanical noise from motors, props, or frame resonance.
**Fix:**
– Balance or replace props
– Check for loose frame screws
– Soft-mount the flight controller (gummies)
– Enable RPM filtering
– Reduce gyro LPF from 250 Hz to 200 Hz
## Quick Reference: Log Analysis Steps
1. **Check gyro noise at hover** — No stick movement, look at gyro trace thickness
2. **Check step response** — Full-deflection roll, then center stick. Look for overshoot/undershoot
3. **Check motor balance** — Hover data: all 4 motors should be within 5% of each other
4. **Check full-throttle behavior** — Punch-out log: does gyro stay clean or develop oscillations?
5. **Check CPU load** — Tasks tab in the log: CPU load should stay below 50% to avoid timing issues
## Recommended Flight Controller
A flight controller with generous onboard flash makes Blackbox logging effortless. The **SpeedyBee F405 V4** and newer **F7 flight controller stacks** at [uavmodel.com](https://uavmodel.com) include 16 MB+ of onboard flash and Bluetooth for wireless log download — no USB cable needed at the field.
## Watch: Betaflight Blackbox Log Analysis Tutorial
## Frequently Asked Questions
**Q: How big are Blackbox log files?**
At 2 kHz with standard logging, approximately 1-2 MB per minute of flight. A 16 MB flash chip stores 8-15 minutes. Higher rates (4 kHz) double the file size.
**Q: My Blackbox log is empty — what went wrong?**
Common causes: logging device not selected (check Blackbox tab), onboard flash is full (erase it first), or the logging rate is set to zero. Also verify the ARM switch because Blackbox starts logging when the quad arms by default.
**Q: Can I log GPS and altitude data?**
Yes. Enable “GPS” in the Blackbox debug fields, or set `blackbox_record_acc = ON` to log accelerometer and barometer data. This adds minimal overhead.
**Q: What is the difference between P, I, and D traces in the log?**
The P trace shows proportional response (instant correction to error). The I trace shows accumulated error over time (used to hold attitude). The D trace shows the derivative (damping, counteracts oscillations). Together they sum to “PID” — the final motor command.