Experimental gain tuning

Changing the airframe changes the plant seen by the controller. The same controller torque command produces a different angular acceleration when the inertia changes. Motor response and available thrust also affect the useful gain range.

For the one-hour walkthrough, inspect the recorded comparison and apply the selected gains. You can run the tuning trials yourself using the commands below when you have more time.

1. Choose a documented starting point

The experiment compares the ArduCopter defaults with roll/pitch rate gains from the Copter 4.6.2 Holybro QAV250 parameter file. The QAV250 supplies a seed from another small frame. Use the measured responses below to decide whether that seed is suitable for this simulated QAV-R. The initial comparison keeps the angle-loop gains the same while varying rate gains and their filters.

# All trial settings and firmware parameters are versioned here.
[experiment]
connect = "udpin:127.0.0.1:14552"
altitude_m = 8.0
settle_s = 4.0
timeout_s = 180.0
monitor_port = 5565
startup_stream_rate_hz = 4
attitude_rate_hz = 50
minimum_attitude_rate_hz = 25
steps = [
  {duration_s=2.0, roll_deg=0.0, pitch_deg=0.0},
  {duration_s=2.0, roll_deg=5.0, pitch_deg=0.0},
  {duration_s=2.0, roll_deg=-5.0, pitch_deg=0.0},
  {duration_s=2.0, roll_deg=0.0, pitch_deg=0.0},
  {duration_s=2.0, roll_deg=0.0, pitch_deg=5.0},
  {duration_s=2.0, roll_deg=0.0, pitch_deg=-5.0},
  {duration_s=2.0, roll_deg=0.0, pitch_deg=0.0},
]

[parameters]
BRD_SAFETY_DEFLT = 0
FS_THR_ENABLE = 0
FS_GCS_ENABLE = 0
DISARM_DELAY = 0
EK3_SRC1_POSZ = 3
EK3_SRC2_POSZ = 3
EK3_SRC3_POSZ = 3
COMPASS_DEC = 0.0
COMPASS_AUTODEC = 0
ARMING_CHECK = 0
GUID_OPTIONS = 0
MOT_PWM_MIN = 1100
MOT_PWM_MAX = 1900
MOT_THST_EXPO = 0.5
MOT_THST_HOVER = 0.2

# ArduCopter 4.6.2 defaults, explicitly recorded for comparison.
[candidates.default]
ATC_RAT_RLL_P = 0.135
ATC_RAT_RLL_I = 0.135
ATC_RAT_RLL_D = 0.0036
ATC_RAT_PIT_P = 0.135
ATC_RAT_PIT_I = 0.135
ATC_RAT_PIT_D = 0.0036
ATC_ANG_RLL_P = 4.5
ATC_ANG_PIT_P = 4.5

# Rate gains/filter values from ArduPilot Copter-4.6.2 Holybro-QAV250.param.
# Keep the same outer-loop settings while comparing the rate controllers.
[candidates.qav250]
ATC_RAT_RLL_P = 0.04598495
ATC_RAT_RLL_I = 0.04598495
ATC_RAT_RLL_D = 0.00120043
ATC_RAT_PIT_P = 0.07421205
ATC_RAT_PIT_I = 0.07421205
ATC_RAT_PIT_D = 0.001949416
ATC_RAT_RLL_FLTT = 40.0
ATC_RAT_RLL_FLTD = 40.0
ATC_RAT_PIT_FLTT = 40.0
ATC_RAT_PIT_FLTD = 40.0
ATC_ANG_RLL_P = 4.5
ATC_ANG_PIT_P = 4.5

2. Run a controlled maneuver

The runner in utils/tune_copter.py creates a fresh run for each candidate, confirms parameter values returned by the firmware, takes off in GUIDED mode, and commands alternating roll and pitch steps. It records actual attitude, controller target rates, altitude, and motor PWM, then lands.

After generating out/qavr.toml in the preceding chapter, type:

python utils/tune_copter.py --config configs/tuning/qavr.toml \
  --run-config out/qavr.toml --output out/tuning

For each successful run, look for [tuning] attitude experiment completed and landed and the per-candidate attitude.csv, mission.tlog, trial.toml, and console.log files, plus a combined results.json.

The helper requests 50 Hz attitude telemetry; analysis refuses runs below 25 Hz. MAVProxy’s periodic stream-rate request is disabled for this experiment so it cannot overwrite the helper’s rates. Each recorded comparison contains 700 attitude samples over 14 seconds.

3. Decide from the response

Compare attitude error during transitions and after settling. RMSE is root-mean-square error; lower values mean closer tracking. Check rate tracking, sustained oscillation, altitude retention, and motor limits. Keep the chosen gains fixed while increasing the maneuver amplitude for a separate validation run, then fly the waypoint mission. Diagnose compiler or startup errors before drawing conclusions about the gains.

These measurements use the current array-based model and Rumoca 21843c11. “Settled” includes samples more than one second after each command change. Both candidates finished and landed, but the default gains produced sustained oscillation. The selected QAV250 seed also passed an independent ±10° experiment: settled roll/pitch RMSE was 0.070°/0.049°, and altitude remained 8.005–8.041 m. This is a tested choice for these maneuvers, not an optimal-gain claim.

Comparison results · Default CSV · Selected CSV · Selected MAVLink log · Validation results · Compiler and model provenance

Reproduce the larger maneuver and plot either batch:

python utils/tune_copter.py --config docs/book/assets/qavr-tuning/validation.toml \
  --candidate qav250 --run-config out/qavr.toml --output out/tuning-validation
python utils/tuning_report.py --input out/tuning --output out/tuning-response.png

4. Use the selected gains for a mission

Export the settings from the source TOML, then apply the controller overlay:

python utils/tune_copter.py --config configs/tuning/qavr.toml \
  --candidate qav250 --export-parameters out/qavr-controller.param
fastdyn-config --base configs/copter462.toml \
  --overlay configs/models/qavr.toml \
  --overlay configs/models/qavr-controller.toml --output out/qavr.toml
fastdyn run -c out/qavr.toml -o out/qavr/work

Expect Wrote out/qavr-controller.param (27 parameters), then mission progress ending in final landing confirmed near ground. This waypoint mission passed with the selected gains. Keep the controller overlay for the next physics experiment so that a model change is the only intended difference.

The procedure follows the distinction between initial stabilization and later tuning in ArduPilot’s tuning process. These experiments tune the simulated plant; transferring gains to hardware requires its own validation.