Tuning guide

When a blackbox log cannot support a tune

More analysis cannot invent excitation. If the flight never asked the quad to do the thing you are trying to measure, no FFT, no curve fit and no language model can recover the answer. The honest response is a better log, not a more confident guess.

1. The log is the measurement

A tune is a claim about how the aircraft responds to a command. The log is the only record of that response. For a PID decision it has to contain:

• A fast stick input the controller had to follow, not just gentle cruising.
• A held portion after the input, so the response can settle and a plateau can be measured.
• Both roll and pitch, because they rarely need the same correction.
• A clean gyro that is not dominated by a damaged prop, a loose mount or a failing motor.
• Enough sample rate to represent the frequencies you are trying to see.
• The PID and filter values that were active, so the change has a starting point.

Remove any one of those and the answer gets weaker in a specific way. That is why a good analyser does not just say "here is your tune"; it says what it could and could not measure.

2. The ways a log fails

What the log is	What it can support	What it cannot
Hover only	Noise, motor health, hover trim, filter behaviour	A step response or a hard-stop diagnosis. There is no step to measure.
Rolls and flips only	Some roll behaviour; gross overshoot; mechanical flags	A clean pitch step. Flips couple the axes and often end near motor saturation.
Very short	Gross problems and obvious noise	An average that is stable enough to trust. A handful of samples is not a measurement.
Low logging rate	Low-frequency behaviour and gross trends	High-frequency peaks, which can alias or disappear. The spectrum ends at Nyquist.
Noisy or damaged build	The mechanical fault itself	Fine PID changes, because the controller is reacting to vibration as well as the command.
Mixed acro with impacts	Mechanical flags, saturation, voltage sag	Clean controlled-response measurements. Crashes and bumps are not steps.
Missing header	The gyro and motor traces	A relative tune. Without the starting values, a change has no baseline.

3. Why "analyse harder" cannot fix it

A step-response estimator solves for the response that best explains the relationship between the setpoint and the gyro. If the setpoint never moved fast, there is nothing to explain. If the gyro was mostly noise, the best fit is a fit to noise. If the log only has one axis, the other axis is not "neutral"; it is unmeasured.

This is also why a longer flight is not automatically better. An hour of gentle cruising gives a very stable average of a signal that contains no step. More data improves the estimate only when the data contains the excitation you are trying to measure.

4. What a weak log can still tell you

• Mechanical health. A fixed tone, a broad raised floor, a one-sided motor load or a high-frequency peak can be flagged from a short flight, provided the flight included enough throttle range.
• Motor saturation and voltage sag. These are visible whenever the quad was actually pushed, even if the step chart is unusable.
• Filter problems. A noisy gyro is a reason to do mechanical and filter work before any gain change, and that conclusion is often supportable from a poor log.
• Gross instability. If the quad is oscillating in a hover, the log can show it even without a clean step. That is a "stop and fix this first" finding, not a tuning value.

What a weak log cannot do is justify a fine change to P, I, D or feedforward. Those changes are claims about a measured response, and the response was not measured.

5. How to fly a log that answers the question

1. Start from a healthy build. Straight props, tight motors and arms, a secure battery, a camera mount that does not flap. A tuning flight on a damaged quad measures the damage.
2. Use one battery and one prop set. If you change either between logs, you changed the aircraft, not just the tune.
3. Hover, then flick. Centre the sticks, hold a steady throttle, make one quick roll flick, return to centre and pause. Do the same on pitch, separately.
4. Repeat the flicks. Several clean examples per axis, with pauses, give the estimator something to average. A single move can be unrepresentative.
5. Add a slow throttle sweep. Climb gradually from hover into the high-throttle band and back. That is what separates a fixed frame tone from motor noise that moves with RPM.
6. Add a propwash dive and a punchout. These test damping and high-throttle authority, and they give the analyser a view of the throttle range that a hover never provides.
7. Keep the crashes and the landing out. Trim to the clean part before analysis. An impact is a large, broadband input that contaminates everything around it.

Betaflight's own documentation recommends a 2 kHz-class logging rate for detailed tuning and notes that a lower rate reduces storage but also detail. Use the highest rate the controller and storage can sustain without dropped frames; a log full of gaps is not better than a slower clean one.

6. What the tool should say when the log is poor

It should say so, plainly, and shrink the part of the answer the data cannot support. Easyquadtune uses three trust labels:

• Chart-ready — both roll and pitch produced usable step evidence, the flight contains the protocol maneuvers, and the gyro is clean enough for the fine work.
• Partial — some usable evidence exists, but at least one axis or maneuver is missing. Suggestions are kept conservative.
• Not safe — the log does not contain a usable step response, or is too short or too poor to tune from. The output should be "fix the log or the build", not a confident script.

The labels are not marketing. They are the difference between a measured change and a guess with a nice chart around it.

7. Sometimes the right answer is no PID change

A clean log of a healthy quad can show that the tune is already doing what it should. In that case the correct output is "no change" — check motor temperature, fly it, and spend the next flight on something else. A tool that always finds a change is not measuring; it is generating.

The same applies to a log that shows a mechanical fault. The honest recommendation may be a prop, a screw, a mount or a bearing, and no PID edit at all. That is a successful diagnosis, not a failure to tune.

Questions pilots actually ask

Can I tune from a hover-only log?

You can learn about noise, motor health and hover trim. You cannot measure a step response, because there is no step.

Is a 1 kHz log good enough?

Betaflight's docs call 1 kHz sufficient for general use and recommend a 2 kHz-class rate for detailed tuning. A lower rate also lowers the highest frequency the log can represent.

Why is the step chart flat?

The analyser found no clean step on that axis. That is missing evidence, not a good result.

Should I still apply a tune from a poor log?

Only the part the log can support: mechanical and filter work, gross problems, saturation and sag. Fine PID changes need a measured response.

Where these questions come from

• Betaflight: Blackbox logging and usage — sample rate, logging fraction, dropped frames and what the log records.
• FPV PID Tune: How to read a step response — why a short or unexcited log produces an unreliable average.
• Airframe: Step response — accepted windows, evidence limits and why the curve describes the recording, not a diagnosis.
• r/fpv: Pitch response info — a pilot asking why a short tuning flight produced a jagged response chart.
• r/fpv: Anyone know how to read blackbox files? — the common "I have a log but do not know if it is usable" starting point.
• tune-betaflight-pid — an independent project that also refuses to tune without stable windows and verified evidence.

More guides: how to read a blackbox log, wobble on hard stops, overshoot vs droop, frame resonance vs prop noise, I-term relax, dips in fast turns.

Easyquadtune is not affiliated with the Betaflight project. Always fly responsibly and perform an initial hover test in a safe environment after any tuning change. The worked example on this site is an illustrative render, not a customer log.