Betaflight Tuning Skill — Log-Based Tuning Reference

Expert knowledge for analyzing Betaflight Blackbox logs and translating observations into PID/filter/parameter changes. This document is the tuning brain behind the Betaflight Tuning Helper app.

Table of Contents

1. Blackbox Log Fundamentals
2. PID Controller Theory for Betaflight
3. Filter System
4. Log-Based Issue Identification
5. Hardware & Physical Issues Diagnosable from Logs
6. Tuning Workflow
7. Parameter Reference
8. Frame & Hardware Considerations
9. Mapping to App Rules

1. Blackbox Log Fundamentals

Key Signals in a Blackbox Log

Reading the Gyro Trace

• Clean gyro: Thin trace, minimal fuzz. The noise floor is low.
• Noisy gyro: Thick/fuzzy trace. High-frequency vibration from motors/props/frame.
• Oscillation: Periodic waveform visible — the frequency tells you the source.
  • < 20 Hz: Likely I-term windup, mechanical looseness, or low-frequency frame resonance
  • 20-80 Hz: P-term oscillation, bounceback, propwash
  • 80-150 Hz: Motor/prop resonance, needs filtering or mechanical fix
  • 150+ Hz: Electrical noise, bearing noise, very high motor resonance

Setpoint vs Gyro (Tracking)

The single most important comparison. Overlay setpoint and gyro:

• Gyro tracks setpoint closely: Tune is good on that axis.
• Gyro overshoots setpoint: P too high, or D too low (underdamped).
• Gyro undershoots / lags behind setpoint: P too low (overdamped), or too much filtering adding delay.
• Gyro oscillates around setpoint after stop: Bounceback — feedforward transition or D-min issue.
• Phase lag visible: Gyro follows setpoint but delayed — excessive filtering or low P.

Motor Traces

• All 4 motors relatively even: Good mechanical balance.
• One motor consistently higher: CG offset, bent arm, weak motor, or bad prop.
• Motors hitting 100%: Saturation — quad physically can't do what PID asks. Reduce gains or throttle.
• Motor traces very noisy/spiky: PID noise passing through to motors, causing hot motors and premature wear.

2. PID Controller Theory for Betaflight

P (Proportional)

• What it does: Pushes the quad toward the setpoint. Force is proportional to error.
• Too high: Oscillation (fast wobble), especially visible at stick center and after maneuvers. Warm/hot motors.
• Too low: Sluggish, mushy feel. Doesn't track setpoint well. Slow response to disturbances (wind, propwash).
• Log signature of P oscillation: Fast oscillation (30-80 Hz) in gyro trace that tracks with stick input. axisP trace is large and in-phase with the oscillation.

I (Integral)

• What it does: Accumulates error over time. Corrects for persistent steady-state error (drift, wind, CG offset).
• Too high: Slow oscillation ("wobble"), bouncy/floaty feel, tendency to overshoot after long stick inputs. I-term windup on fast maneuvers.
• Too low: Drifts in hover, doesn't hold attitude in wind, uneven flip/roll rates.
• Log signature of I problems: Low-frequency oscillation (< 20 Hz) in gyro. axisI trace drifts and overcompensates. Visible as a slow "hunting" pattern.

D (Derivative)

• What it does: Opposes rate of change — a damper. Predicts where error is going and brakes early.
• Too high: Hot motors, amplifies high-frequency noise (D is a high-pass amplifier), propwash response may actually get worse due to delayed motor response.
• Too low: Overshoot on fast moves, bounceback after flips, poor propwash handling.
• Log signature of D issues: axisD trace is very noisy/spiky (too high). Or gyro overshoots setpoint consistently on direction changes (too low).

D-min (Dynamic D)

• What it does: D floats between D-min (low activity) and D (high activity). Gives clean flight at cruise while having full D available for active maneuvers.
• D-min advance: How aggressively D ramps up. Higher = more responsive to stick inputs.
• Key insight: If propwash is the main issue, raising D-min (the floor) is often better than raising D (the ceiling), because propwash happens during low-activity descents.

Feedforward (FF)

• What it does: Adds a term based on stick movement speed (derivative of setpoint). Provides instant response without waiting for error to build.
• Too high: Overshoot on fast stick moves, jittery response on noisy RC link.
• Too low: Latency feeling, PID has to do all the work, feels sluggish on fast direction changes.
• FF transition: Controls how feedforward behaves during stick deceleration. Lower values reduce bounceback. Higher values keep response sharp.
• FF smoothing (jitter_factor): Filters RC link noise from feedforward. Higher = smoother but more latency.

TPA (Throttle PID Attenuation)

• What it does: Reduces PID gains (primarily P and D) at high throttle to prevent oscillation as motors become more responsive.
• TPA rate: How much to reduce (0 = disabled, 0.75 = 75% reduction at full throttle).
• TPA breakpoint: Throttle value where attenuation begins (typically 1250-1500).
• Log signature: Clean at low/mid throttle but oscillation appears above a certain throttle threshold.

3. Filter System

Betaflight's filter pipeline runs between the gyro and the PID controller (gyro filters) and after the PID D-term output (D-term filters).

Gyro Filters

1. Lowpass 1 (default: PT1 at ~275 Hz): First stage of noise removal.
2. Lowpass 2 (default: PT1 at ~275 Hz): Second stage, catches what LP1 missed.
3. Dynamic Notch Filter: Automatically targets the strongest noise peaks (motor RPM harmonics). Adapts in real-time via FFT.
4. RPM Filter: Uses motor RPM telemetry to place notch filters exactly on motor harmonics. Most effective filter — minimal phase delay because it targets exactly the right frequencies.

D-term Filters

1. D-term Lowpass 1 (default: PT1 at ~150 Hz): Critical — D amplifies noise, so this catches it.
2. D-term Lowpass 2 (default: PT1 at ~150 Hz): Additional filtering stage.

Filter Tuning Philosophy

• Filters add latency. More filtering = more phase delay = slower PID response = worse propwash handling.
• Goal: Use the minimum filtering that keeps motors cool and noise acceptable.
• RPM filter is king: If available (requires bidirectional DShot), it allows raising or even disabling other filters because it's so precise.
• Dynamic notch: Good fallback when RPM filter isn't available. Wider = catches more but adds more latency.

Log Signs of Filter Issues

• Over-filtered: Gyro trace is very smooth but tracking is poor (big phase lag between setpoint and gyro). Propwash is bad because PID can't react fast enough.
• Under-filtered: Gyro trace is noisy/fuzzy. Motor traces are spiky. Motors get hot. Listen for audible high-pitched motor whine.
• Resonance not caught by filters: Specific frequency peak visible in FFT that rises with throttle. Usually a motor or frame resonance.

4. Log-Based Issue Identification

Propwash Oscillation

What it is: Oscillation when descending through own prop turbulence (dirty air).

Log signature:

• Occurs during throttle drops (rcCommand[throttle] decreasing)
• Gyro shows oscillation (typically 20-60 Hz) while setpoint is near zero
• Most visible on pitch and roll
• Motor outputs become uneven as PID fights the turbulence

Causes & fixes (in priority order):

1. Raise D-min — gives the damper more authority during low-activity descent
2. Lower I-term relax cutoff — prevents I-term from fighting propwash (which it can't win)
3. Increase dynamic idle — keeps props spinning faster, cleaner airflow
4. Ensure RPM filter is working — allows less overall filtering = faster PID response
5. Reduce filtering (if motors are cool) — less latency = faster correction

Bounceback

What it is: Overshoot/oscillation when sticks return to center after a fast move (flip, roll, sharp turn).

Log signature:

• Setpoint returns to zero but gyro overshoots past zero and oscillates
• 1-3 visible oscillation cycles after the maneuver
• axisI may show windup — it accumulated during the move and overshoots

Causes & fixes:

1. Lower feedforward transition — less aggressive FF during deceleration
2. Raise D / D-min — more damping to absorb the overshoot
3. Lower I-term relax cutoff — I relaxes earlier during fast moves, reducing windup
4. Check I value — may be accumulating too aggressively

Mid-Throttle Wobble

What it is: Low-frequency oscillation during steady forward flight or hover, no stick input.

Log signature:

• Slow oscillation (5-30 Hz) in gyro while setpoint is flat/zero
• Typically visible during mid-throttle cruise
• axisI may show a "hunting" pattern

Causes & fixes by frequency band:

• Low frequency (< 15 Hz): I-term hunting. Reduce I, or check for mechanical issues (loose FC mount, wobbly motor).
• Mid frequency (15-50 Hz): P oscillation. Reduce P, or increase D to damp it.
• High frequency (50+ Hz): Filter issue — noise is getting through. Lower filter cutoffs or verify RPM filter.

High-Throttle Oscillation

What it is: Oscillation that only appears at high throttle (punches, power loops).

Log signature:

• Clean at low/mid throttle
• Oscillation in gyro above ~70% throttle
• Often visible on all axes simultaneously

Causes & fixes:

1. Increase TPA rate — more gain reduction at high throttle
2. Lower TPA breakpoint — start reducing gains earlier
3. Reduce P on affected axis — if TPA alone doesn't fix it
4. Check motor balance — thrust imbalances magnify at high power

Motor Saturation

What it is: One or more motors hitting max output, PID can't physically achieve the requested correction.

Log signature:

• motor[n] values at or near 100% for sustained periods
• Tracking error increases during saturation
• May see asymmetric saturation (e.g., motor 1 and 3 saturate but not 2 and 4)

Causes & fixes:

1. Reduce master multiplier — globally lower PID authority
2. Increase TPA — reduce authority at high throttle where saturation is most likely
3. Reduce P and D — less aggressive corrections
4. Check physical setup — CG balance, prop condition, motor health

D-Term Noise

What it is: D-term amplifying high-frequency gyro noise and passing it to motors.

Log signature:

• axisD trace is very spiky/noisy
• Motor traces show the same noise pattern
• FFT of axisD shows energy above 100-150 Hz

Causes & fixes:

1. Lower D-term filter cutoff — catch more noise before it reaches motors
2. Reduce D gain — less amplification of noise
3. Enable/verify RPM filter — cleaner gyro signal means D has less noise to amplify
4. Check hardware — damaged props, loose motors, or frame resonance creating the noise

Gyro Noise

What it is: Excessive broadband noise in the gyro signal.

Log signature:

• Thick/fuzzy gyro trace even at low throttle
• FFT shows elevated energy across wide frequency band
• Noise increases with throttle (motor-driven) or is constant (electrical/mounting issue)

Causes & fixes:

1. Soft-mount FC — if hard-mounted, vibrations pass directly through
2. Balance props — most common mechanical noise source
3. Check motors — bad bearings, bent shafts
4. Increase gyro filter cutoffs — only if the above are addressed; don't mask bad hardware
5. Enable dynamic notch with wider range — catch more resonant peaks

5. Hardware & Physical Issues Diagnosable from Logs

These are problems no amount of PID/filter tuning can fix. The log can reveal them, and the correct recommendation is a physical intervention — not a parameter change.

Insufficient Motor Authority (Underpowered Setup)

What it is: The motors don't have enough thrust headroom for the quad's weight and the pilot's demands. The PID controller runs out of control authority.

Log signature:

• Motor outputs consistently high (70%+ average) during normal flight, not just punches
• Frequent saturation (100%) on one or more motors during moderate maneuvers — not just full-throttle punches
• Tracking error is large during active flying because PID literally can't push harder
• Asymmetric saturation: opposite motors both saturate during rolls/flips (PID is maxing out the differential)
• Motor output "compression" — the spread between highest and lowest motor narrows at higher throttle, leaving no room for corrections

How to distinguish from bad PID tune:

• Bad tune: saturation happens at specific throttle ranges or during specific events (oscillation driving motors to limit)
• Insufficient authority: saturation is pervasive across the flight, especially during ANY moderate maneuver

Recommendation: Not a software fix. User needs to:

• Use higher-KV motors or larger props
• Reduce all-up weight (lighter battery, lighter frame)
• Reduce motor_output_limit if set below 100%
• Consider that the build simply can't do the maneuvers being attempted

Damaged or Dying Motor

What it is: One motor is mechanically degraded — higher resistance, worn bearings, demagnetized, or physically damaged.

Log signature:

• One motor consistently outputs significantly higher than the others at hover (>10-15% offset)
• The offset is constant regardless of maneuver — it's always motor N working harder
• May see increased noise on the axis that motor primarily affects
• In extreme cases: sudden spikes or dropouts in that motor's output
• Motor asymmetry doesn't correlate with stick input — it's a baseline offset

How to distinguish from CG offset:

• CG offset: two adjacent motors are higher (the "heavy" side). Offset is proportional to throttle.
• Bad motor: single motor is higher. Offset may be relatively constant or worsen with load.

Recommendation: Physical inspection. Spin each motor by hand feeling for roughness. Measure motor resistance with multimeter. Replace the suspect motor.

Bad Motor Bearings

What it is: Worn or damaged bearings create vibration at specific frequencies tied to motor RPM.

Log signature:

• Narrow-band noise peak in gyro FFT that tracks linearly with throttle/RPM
• The peak is at 1x motor RPM frequency (fundamental) — not a harmonic
• Noise is worse on the axis closest to the affected motor
• RPM filter (if enabled) may partially mask this, but the underlying vibration is still there
• The noise peak may be broader/wider than a balanced motor's peak — bearings create "messy" vibration

Recommendation: Replace the motor or bearings. Spinning the motor by hand should reveal roughness, gritty feeling, or play in the shaft.

Bent Motor Shaft

What it is: A bent shaft causes wobble at 1x RPM frequency, creating strong vibration.

Log signature:

• Very strong, clean peak at exactly 1x motor RPM in FFT
• Amplitude is unusually high compared to other motors' fundamental peaks
• Scales linearly and strongly with throttle
• Usually affects one axis more than others depending on which motor has the bent shaft

Recommendation: Visual inspection — spin the motor and watch the prop/bell for wobble. Replace shaft or motor.

Unbalanced or Damaged Props

What it is: Props with weight imbalance or physical damage (nicks, bends, missing material) create vibration.

Log signature:

• Broadband noise increase that scales with throttle
• Noise floor elevation across a wide frequency range (not a single peak)
• All axes affected roughly equally (unlike a single bad motor)
• FFT shows elevated energy at 1x RPM across all motors — broad hump, not sharp peak
• Noise may be intermittent if a prop is cracked and flexing under load
• Sudden change in noise characteristics mid-flight = prop damage during flight

How to distinguish from frame vibration:

• Props: noise scales smoothly with throttle (RPM)
• Frame resonance: specific frequency that's excited at certain RPM bands but not others

Recommendation: Replace props. If the issue persists with fresh props, balance them with a prop balancer. Always check props after any crash.

Center of Gravity (CG) Offset

What it is: The weight distribution is off-center, so some motors must work harder to maintain level flight.

Log signature:

• Two adjacent motors consistently higher output than the other two at hover
• The pattern is: if CG is shifted toward motors 1&2, motors 3&4 compensate by running higher
• Offset is proportional to throttle — larger at higher throttle
• I-term on the affected axis builds up to compensate for the constant error
• The offset is consistent across the entire flight, not transient

How to quantify:

• Hover motor average: if the spread between highest and lowest average motor output at hover is >8-10%, CG is significantly off
• The axis of the offset tells you which direction the weight is shifted

Recommendation: Move battery position. The battery is usually the heaviest single component and the primary CG adjustment. Shift it toward the lighter side.

Frame Flex and Structural Resonance

What it is: The frame has a mechanical resonance at a specific frequency, or arms flex under load.

Log signature:

• Sharp, persistent peak in gyro FFT at a specific frequency that does NOT track with motor RPM
• The resonance may be excited more at certain throttle ranges (where motor RPM harmonics land on the frame's natural frequency)
• Often visible as a "spike" in the noise spectrum that stays at the same frequency regardless of throttle
• May affect one axis more than others (e.g., pitch if the arms flex forward/back)
• Arm flex specifically: increased noise on the axis perpendicular to the flexing arms, worsening under high-G loads

How to distinguish from motor noise:

• Motor noise: peak frequency shifts with throttle (RPM changes)
• Frame resonance: peak frequency stays constant, but amplitude changes with throttle

Recommendation: Stiffer frame (thicker carbon, reinforced arms), add bracing, or change prop/motor combo to avoid exciting the resonance. Frame resonance is a hard problem — sometimes the answer is a different frame.

ESC Desync

What it is: An ESC momentarily loses sync with its motor, causing a brief loss of thrust.

Log signature:

• Sudden, brief motor output spike to maximum (ESC trying to recover) followed by a drop
• Corresponding sudden gyro disturbance — a sharp transient that doesn't match stick input
• May see the quad "twitch" or lose attitude momentarily
• Often happens during rapid throttle changes or at very low throttle (idle)
• If severe: motor output goes to zero briefly, then recovers

How to distinguish from PID oscillation:

• PID oscillation: periodic, repeating pattern
• Desync: isolated, sudden, non-periodic event with sharp onset

Recommendation:

• Increase motor timing in ESC firmware
• Raise dynamic idle (dyn_idle_min_rpm) to keep motors above desync-prone low RPM
• Update ESC firmware
• If persistent: ESC or motor may be damaged

Voltage Sag / Weak Battery

What it is: Battery can't sustain voltage under load, causing motor performance to degrade.

Log signature:

• vbat (if logged) drops significantly under load and recovers when throttle is reduced
• Motor output values increase over the flight to achieve the same maneuvers (PID compensating for reduced motor authority)
• Performance visibly degrades in the second half of the flight — same stick inputs produce weaker gyro response
• Tracking quality worsens later in the flight compared to early
• In extreme cases: motor saturation events increase toward end of flight that weren't present at start

Recommendation:

• Use a battery with higher C-rating or lower internal resistance
• Reduce flight aggression on aging batteries
• This is NOT a tuning issue — it's a power supply limitation

Electrical Noise / EMI

What it is: Electromagnetic interference from switching regulators, ESCs, video transmitters, or other electronics coupling into the gyro signal.

Log signature:

• Constant-frequency noise that does NOT change with throttle or RPM
• Often at specific frequencies related to switching regulators (100-500 kHz, but aliases down to gyro sample range)
• Present even at zero throttle / motors off (if source is VTX or other always-on electronics)
• May appear as a single sharp peak or a comb of peaks at regular intervals in FFT
• Noise floor is elevated even with props off — this is the key differentiator

Recommendation:

• Add capacitor to battery lead (if not already present)
• Route gyro wires away from high-current / switching noise sources
• Use shielded cables
• Power sensitive components from a filtered regulator
• Check for ground loops in wiring

Loose Flight Controller Mount

What it is: FC is not securely mounted, allowing it to vibrate independently of the frame.

Log signature:

• Exaggerated low-frequency noise (< 50 Hz) in gyro that seems disproportionate to motor noise
• Noise characteristics change with G-forces — sudden spikes during direction changes as FC shifts on mount
• Inconsistent noise floor — sometimes clean, sometimes noisy, depending on how the FC is sitting
• If soft-mounted: excessive low-frequency oscillation that soft-mount is amplifying rather than isolating (resonance of the soft mount itself, typically 10-30 Hz)

Recommendation:

• Check and tighten mounting hardware
• If soft-mounted: ensure grommets are the right stiffness. Too soft = the mount itself resonates. Too hard = no isolation.
• Add foam padding for additional dampening
• Ensure no wires are pulling on the FC creating asymmetric stress

Prop Strike Damage (Mid-Flight)

What it is: A prop contacts something during flight, damaging it and changing vibration characteristics.

Log signature:

• Sudden, dramatic change in noise characteristics at a specific point in the log
• Before the event: normal noise floor. After: significantly elevated noise
• The change is permanent for the rest of the flight (unlike a transient desync)
• May be accompanied by a large gyro/motor transient at the moment of impact
• One axis may be affected more than others depending on which prop was struck

Recommendation: Land immediately. Inspect all props and replace any that are damaged. Check motors for bent shafts from the impact.

Motor / Prop Mismatch

What it is: Props are too heavy or aggressive for the motors, or motors are too weak for the prop size.

Log signature:

• Motors running hot (can't see in log directly, but high average motor output % is a proxy)
• Sluggish throttle response — gyro response lags behind throttle input more than expected
• Motor authority issues similar to "underpowered" but specifically caused by wrong component pairing
• Excessive current draw (if logged) relative to the maneuvers being performed
• Higher-than-expected noise because motors are straining

Recommendation: Match props to motor specifications. Use the motor manufacturer's recommended prop range. Going 1" size down on props is the easiest fix for an overly aggressive setup.

5b. Summary: Hardware Issue Detection Cheat Sheet

6. Tuning Workflow

Recommended Log Analysis Order

1. Motor health check: Are all 4 motors roughly balanced? Any saturating?
2. Gyro noise floor: How clean is the raw gyro? Sets the ceiling for how aggressive the tune can be.
3. Tracking quality: How well does gyro follow setpoint? This is the overall grade.
4. Issue identification: Propwash? Bounceback? Wobble? Oscillation at specific throttle?
5. Frequency analysis (FFT): What frequencies are the problems at? This narrows causes.
6. Parameter recommendations: Based on all of the above, suggest specific changes.

The Golden Rules of Tuning

1. Fix hardware before software — No amount of PID tuning fixes a broken prop or loose motor.
2. One change at a time — Change one parameter, fly, log, compare. Otherwise you can't attribute improvements.
3. Filters first, PIDs second — If the signal is noisy, PID tuning is fighting a losing battle.
4. RPM filter changes everything — With bidirectional DShot and RPM filtering, you can run much higher P and D with less filtering.
5. Trust the motors — If motors are cool after a hard flight, you likely have room to push gains higher. If they're hot, back off D first, then P.
6. Context matters — A 5" freestyle quad and a 5" race quad have very different ideal tunes. Frame, weight, prop choice, and flying style all affect what's optimal.

Severity & Priority

When multiple issues exist, fix them in this priority:

Hardware issues (fix first — tuning can't compensate):

1. ESC desync (safety — can cause crash)
2. Damaged motor / bent shaft (will mask all other tuning)
3. Bad props (noise source makes everything else worse)
4. Insufficient motor authority (PID has nothing to work with)
5. CG offset / voltage sag / loose mount (creates persistent baseline problems)
6. Frame resonance / EMI (noise source that filtering is compensating for)

Software tuning issues (fix after hardware is healthy):

1. Motor saturation (safety — can cause desync/crash)
2. High-frequency oscillation / excessive noise (motor damage)
3. High-throttle oscillation (dangerous during power moves)
4. Propwash (most common complaint, moderate flight impact)
5. Bounceback (annoying but not dangerous)
6. Tracking quality fine-tuning (polish)

7. Parameter Reference

PID Gains (per axis: roll, pitch, yaw)

Filter Parameters

Other Key Parameters

8. Frame & Hardware Considerations

Frame Type Affects Tune

• Stretched X: Pitch and roll behave differently. Pitch arm is longer = more leverage = may need lower P on pitch, or higher D.
• True X / Squished X: More symmetric. Roll and pitch can often share similar PIDs.
• Dead cat: Long-body. Similar to stretched X — pitch typically needs different tuning.
• Cinewhoop (ducted): Ducts amplify propwash significantly. Usually needs high D-min, high dynamic idle, aggressive I-term relax.

Prop Size & KV

• High KV / small props: More responsive, more noise. Needs more filtering, potentially lower P.
• Low KV / large props: Smoother, more inertia. Can run higher P, less filtering needed.
• Damaged/unbalanced props: Massive noise source. The first thing to check if gyro is noisy.

FC Mounting

• Soft-mounted (rubber grommets): Isolates FC from frame vibrations. Allows less aggressive filtering.
• Hard-mounted: All vibrations pass through. Needs more filtering. Consider adding foam or TPU standoffs.

ESC Protocol

• Bidirectional DShot: Required for RPM filtering. If available, use it — single biggest tune improvement.
• Regular DShot: No RPM telemetry. Rely on dynamic notch filter instead.
• ESC timing/frequency: Higher DShot speed (600/1200) gives faster motor response.

9. Mapping to App Rules

How the tuning knowledge maps to the app's TuningRule implementations:

Detection Pipeline

Raw Log Frames
  → Segment into 100ms windows (50% overlap)
  → Classify flight phase per window (idle/hover/cruise/punch/propwash/flip/roll)
  → Run relevant rules per window + axis
  → Temporal dedup (merge issues < 100ms apart)
  → Collapse to one issue per type+axis
  → Generate recommendations per issue
  → Dedup recommendations by parameter:axis key
  → Conflict resolution (weighted merge for opposing changes)
  → Output exact parameter values (CLI commands support arbitrary numbers)

Confidence & Severity

• Confidence: How certain the detection is. Based on signal clarity, metric strength, consistency across windows.
• Severity: How bad the issue is. Critical (motor saturation, dangerous oscillation) > Warning (propwash, bounceback) > Info (minor tracking issues).
• Both affect recommendation priority. A high-confidence critical issue always takes precedence.

Appendix: Quick Diagnostic Flowchart

Start: Load log
  │
  ╔══════════════════════════════════════════════╗
  ║  STEP 1: Hardware Health (fix before tuning) ║
  ╚══════════════════════════════════════════════╝
  │
  ├─ Noise present at zero throttle / motors off? → EMI / electrical noise → Fix wiring/shielding
  │
  ├─ One motor 10%+ higher at hover? → Dying motor or CG offset
  │   ├─ Single motor offset? → Bad motor → Replace it
  │   └─ Two adjacent motors higher? → CG offset → Move battery
  │
  ├─ Sharp FFT peak at fixed frequency (doesn't track RPM)? → Frame resonance → Stiffer frame
  │
  ├─ Sharp FFT peak tracking 1x RPM, one motor? → Bent shaft or bad bearings → Replace motor
  │
  ├─ Broadband noise scaling with throttle, all axes? → Bad/unbalanced props → Replace props
  │
  ├─ Sudden noise change mid-flight? → Prop strike → Land, replace props, check motors
  │
  ├─ Sudden motor spike + gyro transient (isolated event)? → ESC desync → Raise idle, update ESC FW
  │
  ├─ Motors 70%+ average, pervasive saturation? → Underpowered → Lighter build / stronger motors
  │
  ├─ Performance degrades over flight? → Voltage sag → Better battery
  │
  ├─ Erratic low-freq noise changing with G-forces? → Loose FC mount → Fix mounting
  │
  ╔══════════════════════════════════════╗
  ║  STEP 2: Software Tuning Issues      ║
  ╚══════════════════════════════════════╝
  │
  ├─ Motors hitting 100%? → Motor Saturation → Reduce gains / master multiplier
  │
  ├─ Motors very noisy? → Check gyro noise
  │   ├─ Gyro noisy? → Filter tuning needed
  │   └─ Gyro clean? → D-term noise → Lower D or D-term filter
  │
  ├─ Oscillation at high throttle only? → TPA issue → Increase TPA rate / lower breakpoint
  │
  ├─ Oscillation during descent? → Propwash → Raise D-min, I-term relax, dynamic idle
  │
  ├─ Oscillation after flips/rolls? → Bounceback → Lower FF transition, raise D
  │
  ├─ Slow wobble in hover/cruise? → I-term or P issue
  │   ├─ Low frequency (< 15 Hz)? → Reduce I
  │   └─ Mid frequency (15-50 Hz)? → Reduce P or raise D
  │
  └─ Sluggish/laggy response? → Overdamped
      ├─ Too much filtering? → Raise filter cutoffs (if motors are cool)
      └─ P too low? → Raise P