Guide
Optimal tuning flight
A complete guide so every detector — Bode, step response, spectrum, heatmap, Vbat, frame resonance — gets the most useful data possible.
1. Betaflight Configurator — Blackbox tab
Set these values exactly:
| Setting | Value |
|---|---|
| Logging Rate | 1/1 (1/1 — every frame, max resolution) |
Erase flash before the flight
Configurator → Blackbox tab → 'Erase Flash' — otherwise the previous flight overwrites yours or the log gets fragmented.
Debug Fields — which boxes to tick
At the bottom of the Blackbox tab there's a 'Debug Fields included' list. Picking the wrong ones makes half the analysis worthless. These 8 fields on, the rest off:
| Field | State | Why |
|---|---|---|
| PID | ON | Logs P/I/D output per axis — shows what the loop actually does |
| RC Commands | ON | Your stick inputs — needed for prop-wash detection and step-input correlation |
| Setpoint | ON — critical | Smoothed target signal after RC smoothing and feedforward. Without setpoint, neither step response nor Bode metrics can be computed; the tune score remains incomplete |
| Battery | ON | Vbat + current → sag detection, cell-count check |
| Gyro | ON — critical | The filtered gyro readings. The core signal of any analysis — without this data, no evaluation is possible |
| Motor | ON | Per-motor output → motor imbalance, motor harmonic detection |
| RPM | ON | Real RPM per motor (only with Bidir DSHOT) → precise harmonic tracking, RPM filter validation |
| Gyro (Unfiltered) | ON — critical | Raw gyro prior to any filtering. Without this reference, filter effectiveness cannot be determined |
| Magnetometer | OFF | Rarely fitted, irrelevant for tuning |
| Altitude | OFF | Baro/GPS altitude — consumes storage, not relevant for tuning |
| RSSI | OFF | Receiver signal — irrelevant for tuning |
| Attitude | OFF | Pitch/roll/yaw angles — derived from gyro, redundant |
| Accelerometer | OFF | Not evaluated by PIDoctor, yet consumes storage |
| Debug Log | OFF | Only useful if you intentionally have a debug_mode active |
| GPS | OFF | Position — consumes considerable storage, not relevant for tuning |
| Servo | OFF | Fixed-wing/tilt only, not for multirotors |
Why not enable every field?
Each additional field consumes storage. On an 8 MB flash with all fields enabled at 8 kHz gyro sampling, the available space is filled after roughly 20 seconds. With this selection and logging rate 1/1 at 4 kHz gyro sampling, typical recording durations exceed 90 seconds — sufficient for the flight plan described below.
2. Pre-flight checklist
- Fresh LiPo, fully charged (4.20V/cell) — Vbat sag analysis needs a defined starting voltage
- Props fresh — avoids false 'motor imbalance' findings
- No wind or light breeze — wind contaminates the step response
3. The flight plan — 90 seconds, 7 sections
Total duration approximately 90 seconds. Recording begins on arming — all phases before that (setup, ground hover) are automatically excluded from the analysis.
§ 1 · Clean hover
10 sWhat: Stabilize around 2 m altitude, don't move the sticks.
Why: Baseline gyro spectrum → frame resonance, motor idle noise, RPM filter effectiveness.
§ 2 · Throttle sweep
15 sWhat: Slowly idle → full → idle, ~10 s up, 5 s down. Keep the quad upright (coordinated).
Why: Throttle × frequency heatmap — shows where your motor harmonics travel, separates filter cutoffs from real resonances.
§ 3 · Step inputs on every axis
20 sWhat: At roughly half throttle, give short, sharp stick stabs — several per axis: flick the stick quickly (about half deflection is enough) and immediately release back to center, let the quad settle briefly (~1 s), then the next stab. Pitch first (fwd/back, 3–4× each), then Roll (left/right), then Yaw. IMPORTANT: do NOT hold full deflection — that just makes the quad keep rotating. It's about the sharp tap and cleanly catching it afterwards.
Why: Produces the step response (rise/overshoot/settling) and Bode metrics (Ms, phase margin). These sharp impulses are exactly what generates the coherence needed — without them the tracking analysis stays empty or is flagged “inconclusive”.
§ 4 · High-frequency small inputs
10 sWhat: Sticks etwa 10 % deflection, move them rapidly back and forth on roll and pitch simultaneously — a high-frequency jitter input.
Why: Excite the bandwidth range (20–80 Hz) → better coherence → more accurate phase margin.
§ 5 · Flip + roll
10 sWhat: One front flip, one left roll. Clean catches.
Why: Maximum D-term stress → prop wash + D-term noise findings.
§ 6 · Forward flight + throttle variation
15 sWhat: Forward flight at approximately 30–50 km/h with deliberate throttle variations: short full-throttle bursts, followed by glide phases, followed by further bursts.
Why: Prop wash on throttle drops + Vbat sag on full punches + motor harmonics across the full RPM range.
§ 7 · Clean hover, finale
10 sWhat: Return to stable hover, no inputs.
Why: Comparison baseline against section 1 → reveals thermal drift (hot motors = shifted frequency).
4. What PIDoctor extracts from this
With this flight every sub-score becomes a real measurement:
| Sub-score | Source |
|---|---|
| Overshoot | Step response from section 3 |
| Rise | Step response from section 3 |
| Margin (ϕm) | Bode FRF from section 3+4 (higher coherence thanks to the small inputs in 4) |
| Ms | Bode from section 3+4 |
| Noise | Spectrum from section 1+7 (hover baseline) |
Plus findings from:
- Prop wash: Section 5 (flip) + 6 (throttle drops)
- Vbat sag: Section 6 (punches)
- Motor harmonics across throttle: Section 2 (sweep) + 6 (variation)
- Frame resonance: Section 1+7 (quiet hover conditions)
- Motor imbalance: Section 1+7 (static load)
5. After the flight
- Land and disarm immediately. Do not enter CLI mode, as doing so closes the log and may block subsequent writes.
- Configurator → Blackbox → 'Save log file' → get the .bbl
- Drag and drop the file into pidoctor.app/upload — or pull it straight from the FC via USB (beta, Chrome/Edge).
- Multiple logs on the flash? The biggest one is usually your last flight.
Notes
- For multiple consecutive tuning sessions, erase the flash before each new recording and keep only a single flight per file. This simplifies later attribution.
- If the available storage does not accommodate the full 90 seconds, review gyro_sync_denom in the Configuration tab. On small flash, a value of 1 (8 kHz gyro) is unsuitable; a value of 2 (4 kHz) or a reduced logging rate of 1/2 is preferable.
- For reproducible comparisons, keep flight location, battery and stick inputs as consistent as possible. Two analyses can then be compared directly, for example 'before PID adjustment' versus 'after PID adjustment'.
- Indoor variant: perform only sections §1, §3, §4 and §7 — no full-throttle bursts and no forward flight. The score is less expressive but remains usable for PID tuning.