Files
PX4-Autopilot/docs/en/features_mc/gain_compression.md
T
Andrea Bernasconi 0d104226d3 feat(mc_rate_control): add rate loop gain compression for MC (#28719)
* feat(mc_rate_control): add rate loop gain compression

Extend the gain compression already available on fixed-wing to the
multicopter rate controller, so that an oscillation (limit cycle) on the
torque setpoint dynamically reduces the loop gain instead of requiring a
manual retune. The gain recovers to 1.0 once the oscillation stops.

GainCompression3d is templated on the enable and minimum gain parameter
IDs so both airframe types share one implementation while keeping their
own MC_GC_* / FW_GC_* parameters. Behaviour is opt-in: MC_GC_EN defaults
to disabled.

The dt clamp in the spectral damper is widened from 1 ms to 0.125 ms
because multicopter rate loops run well above the 1 kHz that the previous
floor assumed, which would otherwise mis-scale the filter coefficients.
Compression is reset while landed so that ground contact vibration does
not compress the gains before takeoff.

Assisted-by: Claude:claude-opus-5
Signed-off-by: Andrea Bernasconi <andrea.bernasconi@auterion.com>

* fix(rate_control): fully restart gain compression on reset

reset() only restored the scalar compression gains, leaving the spectral
damper history and the cached gain vector untouched. A reset therefore did
not really restart at gain 1: the next cycle still multiplied the torque
setpoint by the previously compressed vector, and the stale HPF/LPF state
could immediately recreate compression. Clear the detector history and the
cached gains so that disarming, a non-rotary-wing transition or ground
contact genuinely restart from an uncompressed loop.

Seed the high-pass filter from the first sample after a reset instead of
zeroing the input history. Since the multicopter controller resets on every
cycle while landed, a zeroed history would make the first airborne sample
look like a step edge and inject a spurious spike into the spectral damper
right at takeoff.

Assisted-by: Claude:claude-opus-5
Signed-off-by: Andrea Bernasconi <andrea.bernasconi@auterion.com>

* docs(mc_rate_control): document multicopter gain compression

Add a feature page for gain compression on multicopters, mirroring the
fixed-wing one but covering the multicopter specifics: it is opt-in
(MC_GC_EN defaults to disabled), and compression is reset while disarmed
or landed so ground contact cannot compress the gains before takeoff.

The fixed-wing block diagram is linked rather than duplicated, since it
contains an airspeed scaling stage that does not exist in the multicopter
rate loop.

Also note in the multicopter PID tuning guide that compression should be
off during manual tuning, as it damps out the very oscillation the tuning
process looks for.

Assisted-by: Claude:claude-opus-5
Signed-off-by: Andrea Bernasconi <andrea.bernasconi@auterion.com>

---------

Signed-off-by: Andrea Bernasconi <andrea.bernasconi@auterion.com>
2026-09-29 12:22:31 +02:00

2.0 KiB

Gain compression

Automatic gain compression reduces the gains of the angular-rate PID whenever oscillations are detected. It monitors the angular-rate controller output (the torque setpoint) through a band-pass filter to identify these oscillations, and scales the output down until they stop. The gain recovers to 1.0 once the oscillation is gone.

This approach is a safe adaptive mechanism: the PID gains remain unchanged when no oscillations are present, they are never increased beyond their nominal values, and they are bounded by a minimum limit (MC_GC_GAIN_MIN).

Gain compression can help prevent actuator damage, and even loss of the vehicle, when the rate loop becomes oscillatory in flight: for example after a payload change that shifts the CG or inertia, a partial propeller failure, or gains that were tuned for a different configuration. It removes the need to retune manually for the oscillation to stop.

The algorithm is the same one used on fixed-wing vehicles, where you can also find a block diagram of the adaptive law (the multicopter rate loop has no airspeed scaling stage).

Usage

Gain compression is disabled by default and is enabled with MC_GC_EN.

It should be disabled during multicopter manual tuning to avoid over-tuning: with compression active, an oscillation caused by gains that are too high is damped out, which hides the very symptom the tuning process relies on. It does not need to be disabled when autotuning.

Compression is automatically reset (gain back to 1.0) while the vehicle is disarmed or landed, so that vibration from ground contact cannot compress the gains before takeoff.

Parameters