PID Tuning
Tune only after the hardware passes bench testing; use small, reversible changes and treat the v1 app values as configuration to send, not live PID readback from the board.
# Before touching PID
Do not tune around a wrong motor map, reversed propeller, bad IMU direction, loose frame, damaged motor, unstable power, or unreliable connection. Return to the documented bench baseline first.
The v1 application does not read the active PID set back from the board. Record the known baseline used for this controller (firmware defaults or your own previously saved set) before changing values, and do not assume a value shown in the app is live board readback.
# What P, I, and D do in the v1 controller
Swipe horizontally to see all columns.
| Term | Controller role | What to watch during a controlled test |
|---|---|---|
| P — proportional | Applies correction in proportion to the current control error. | Too little can feel weak; excessive response can contribute to fast oscillation. |
| I — integral | Accumulates persistent error over time, with the firmware limiting the integral state. | Useful for persistent bias/error; excessive integral action can create slow recovery or oscillatory behavior. |
| D — derivative | Responds to the change in controller error from one update to the next. | Can damp rapid changes, but excessive D makes noise/vibration more important. Fix mechanical vibration before increasing it. |
# Safe tuning workflow
- 1
Start from a known baseline
Write down the complete PID set you intend to use and the exact hardware/battery/propeller configuration.
- 2
Change one axis or term at a time
Do not change Roll/Pitch/Yaw and several P/I/D terms together; you need to know which change produced the result.
- 3
Use a small reversible adjustment
ESPFlight v1 does not define one universal tuning increment for every frame. Make a small change relative to your known-good baseline rather than copying an arbitrary value.
- 4
Save only while safely DISARMED
Use the app configuration path from a safe propeller-off or landed state and wait for the application/firmware result before treating the change as active.
- 5
Run a controlled observation
Re-check bench behavior as appropriate, then use only a brief controlled flight test when the build is ready. Observe one symptom at a time.
- 6
Keep or revert
If the result is worse, unstable, or unclear, return to the last known-good set instead of stacking another change on top.
# Stop conditions
Do not continue tuning through a flip tendency, strong vibration, rapid oscillation, unexpected motor behavior, unstable power, stale telemetry, or a failsafe condition. Land/stop safely, DISARM, remove propellers for diagnosis, and fix the underlying layer first.