# Blackbox Log Analysis: How to Read Logs for PID and Filter Tuning
Tuning a quad without Blackbox logs is like trying to fix a car engine with your eyes closed. You might get lucky, but you’ll probably make things worse. Blackbox logging captures every oscillation, every overshoot, and every filter anomaly — you just need to know what you’re looking at. This guide teaches you how to interpret Blackbox data to achieve a locked-in tune.
## What Is Blackbox and Why Should You Use It?
Blackbox logs are CSV files recorded by your flight controller that capture gyro data, PID outputs, motor commands, and RC inputs at rates up to 2kHz. You can analyze them with [Betaflight Blackbox Explorer](https://github.com/betaflight/blackbox-log-viewer) or the more advanced [Plasmatree PID Analyzer](https://github.com/Plasmatree/PID-Analyzer).
### What Blackbox Reveals That Your Eyes Can’t
| Issue | Visual Symptom | Blackbox Signature |
|——-|—————|——————-|
| P-term oscillation | Shaky/jittery flight | High-frequency gyro noise at motor frequency |
| D-term noise | Hot motors, “angry bee” sound | Amplified D trace with sharp spikes |
| I-term windup | Slow drift after flips | I trace climbing and not returning to zero |
| Yaw overshoot | Tail wag on quick yaw stops | Yaw P/D overshoot with bounce-back |
| Mechanical noise | Inconsistent flight feel | Gyro noise that doesn’t match motor RPM |
## Step 1: Setting Up Blackbox Logging
### Hardware Requirements
| Flight Controller Type | Blackbox Support | Log Rate |
|————————|—————–|———-|
| F7 with onboard flash (16MB+) | Yes — use onboard | 2kHz recommended |
| F405 with SD card slot | Yes — insert SD card | 2kHz |
| F411 or no storage | Use OpenLager external logger | 1-2kHz |
| AIO whoop board | Limited — usually 8MB flash | 1kHz, short logs only |
### Configuration (Betaflight Configurator)
1. **Enable Blackbox**: Configuration tab → “Blackbox logging device” → select your device
2. **Set logging rate**: Blackbox tab → 2kHz for modern FCs, 1kHz for slower processors
3. **Select debug mode**: Blackbox tab → “GYRO_SCALED” for tuning (shows post-filter gyro data)
4. **Arm to start logging**: Most FCs auto-start logging when armed
## Step 2: Reading the Key Traces
When you open a log in Blackbox Explorer, you’ll see several graphs. For tuning purposes, focus on these:
### The Gyro Graph (What the Quad Actually Does)
The gyro trace shows the quad’s actual rotation rate in degrees/second. A perfectly tuned quad shows:
– **Smooth curves** during flips and rolls (no jagged edges)
– **Clean return to zero** after maneuvers (no overshoot/bounce)
– **No high-frequency noise** during punch-outs (motor noise not reaching the gyro)
### The PID Error Graph (What Needs Fixing)
PID Error = Setpoint – Gyro. This is your tuning compass:
– **Near zero during steady-state flight**: Good — P-term is holding the quad where you told it
– **Spikes at start of maneuvers**: Normal — P responds to rapid setpoint changes
– **Overshoot after maneuvers**: P too high or D too low
– **Constant offset**: I-term too low, or mechanical issue
### The Motor Graph (What the FC Is Asking For)
Motor traces show what the FC commands each ESC. Key patterns:
– **All four motors equal during punch-out**: Good weight distribution
– **One motor consistently higher**: Possible bent prop, motor drag, or PID imbalance
– **Rapid motor oscillation**: P-term or D-term noise being amplified
– **Motor saturation (100%)**: Quad is underpowered for the requested move
## Step 3: Common Tuning Signatures
### Problem 1: High P-Gain Oscillation
**Blackbox signature**: Gyro trace shows rapid, regular oscillation at the motor RPM frequency (visible on throttle punches). PID_P trace mirrors the oscillation.
**Fix**: Reduce P-gain on the affected axis by 5-10 points, or increase D-gain slightly to dampen.
### Problem 2: D-Term Noise Amplification
**Blackbox signature**: D trace is noisy and has sharp spikes. Motors sound angry and come down hot. Gyro shows noise being amplified rather than dampened.
**Fix**: Reduce D-gain by 5 points. If the noise persists, check your RPM filter settings or reduce the Dynamic Notch Q factor.
### Problem 3: I-Term Bounce-Back
**Blackbox signature**: After a hard stop (flip, roll, sharp yaw), the quad bounces back slightly in the opposite direction. I trace shows accumulation during the maneuver that takes time to unwind.
**Fix**: Increase I-gain on the affected axis, or enable Anti-Gravity gain (helps I-term respond faster during rapid throttle changes).
### Problem 4: Propwash Oscillation
**Blackbox signature**: During rapid descent or sharp 180° turns, the gyro shows a low-frequency (~20-50Hz) wobble that decays over ~0.5 seconds. Most visible on pitch and roll axes.
**Fix**: Increase D-min and decrease P:D ratio slider. Also consider lowering your camera angle — steeper angles worsen propwash.
## Step 4: Using Plasmatree PID Analyzer
Plasmatree’s PID Analyzer automates much of the analysis:
1. Record a flight with step-response inputs (sharp stick flicks on each axis)
2. Export the Blackbox log
3. Upload to Plasmatree PID Analyzer
4. The tool calculates optimal P, I, and D values based on your quad’s actual response
### What Plasmatree Shows That Manual Analysis Misses
| Metric | What It Tells You |
|——–|——————-|
| Rise Time | How fast the quad responds to input |
| Overshoot % | How much the quad exceeds the target |
| Settling Time | How long until the quad stabilizes after input |
| Phase Margin | Stability headroom — higher is safer |
## Recommended Product
Collecting quality Blackbox logs requires sufficient onboard storage. The [SpeedyBee F7 V3 Flight Controller](https://uavmodel.com) available at uavmodel.com includes 32MB of onboard Blackbox flash — enough for 30+ minutes of 2kHz logging. With an F722 processor, 6 UARTs, and native DJI plug support, it’s the ideal platform for pilots serious about tuning. No more SD cards to lose or external loggers to wire.
## Watch: Blackbox Log Analysis for PID Tuning
## Frequently Asked Questions
### How do I know if my quad needs PID tuning without Blackbox?
Visual signs include: shaking during punch-outs (P too high), slow bounce after flips (I too low), hot motors after gentle flight (D too high), tail wag on yaw (yaw P/D imbalance), and propwash oscillation on descent (P:D ratio off). But only Blackbox confirms the exact cause.
### What’s the difference between Blackbox log rate and PID loop frequency?
The PID loop runs at a fixed frequency (usually 8kHz on F7, 4kHz on F4). Blackbox can log at 1/2, 1/4, or 1/8 of that rate. A 2kHz log rate captures every 4th PID loop iteration, which is sufficient for tuning analysis while keeping log sizes manageable.
### Why does my Blackbox log show “0” for all motor values?
This happens when DShot telemetry or the debug mode isn’t configured. Enable “DShot Beacon Configuration” in the Motors tab and set the debug mode to “GYRO_SCALED” in the Blackbox tab. Restart the FC after changing these settings.
### Can I tune using Blackbox from a single flight?
A single flight with varied maneuvers (punches, flips, sharp turns, descents) can reveal most tuning issues. Record at least 3 minutes covering all flight conditions — hover, cruise, punch-out, descent, and aggressive freestyle moves.