AC_AttitudeControl: Rotary-Wing Attitude Controller

AC_AttitudeControl is the core library that bridges high-level flight mode commands and low-level motor outputs for all ArduPilot rotary-wing vehicles. It implements a two-layer control hierarchy: an outer angle loop that produces angular rate targets, and an inner rate loop (running in the derived class) that drives the motors via body-frame PID controllers. Every attitude command — whether a pilot stick input, an auto-mode waypoint, or an acro-rate demand — passes through this library before reaching the motors.

Control hierarchy

The library separates attitude control into two layers, each running at a different rate.

Angle loop (outer)

Compares the desired attitude quaternion against the current AHRS estimate. A proportional (P) controller on each Euler axis produces a body-frame angular velocity target.

Rate loop (inner)

Pure PID controllers run on body-frame gyro measurements to follow the angular velocity targets produced by the angle loop. Implemented in subclasses such as AC_AttitudeControl_Multi.

Input shaping

Before being handed to the angle loop, rate and angle demands pass through an input shaping stage that enforces acceleration limits (ATC_ACCEL_R_MAX, ATC_ACCEL_P_MAX, ATC_ACCEL_Y_MAX) and smoothes the command with a configurable time constant (ATC_INPUT_TC). This prevents abrupt step inputs from saturating the actuators and limits structural loads.

Key methods

The following methods are the primary entry points used by flight modes to command attitude.

input_euler_angle_roll_pitch_euler_rate_yaw_rad()

Sets desired roll and pitch angles (radians) while commanding a yaw rate (rad/s). This is the standard interface used by stabilize-type modes where the pilot directly controls roll and pitch angle but yaw is a rate demand.

virtual void input_euler_angle_roll_pitch_euler_rate_yaw_rad(
    float euler_roll_angle_rad,
    float euler_pitch_angle_rad,
    float euler_yaw_rate_rads);

A centidegree overload (_cd suffix) is also available for legacy callers.

input_euler_angle_roll_pitch_yaw_rad()

Commands absolute roll, pitch, and yaw angles (radians). Optional yaw slew limiting constrains how fast the yaw target can change. Used in autonomous modes (Auto, Guided, RTL) where the heading is set by the mission planner.

virtual void input_euler_angle_roll_pitch_yaw_rad(
    float euler_roll_angle_rad,
    float euler_pitch_angle_rad,
    float euler_yaw_angle_rad,
    bool slew_yaw);

input_rate_bf_roll_pitch_yaw_rads()

Commands body-frame angular rates directly (rad/s). Used by acro flight modes. When body-frame feed-forward is enabled, the inputs are shaped with acceleration limits before being passed to the rate controller.

virtual void input_rate_bf_roll_pitch_yaw_rads(
    float roll_rate_bf_rads,
    float pitch_rate_bf_rads,
    float yaw_rate_bf_rads);

input_quaternion()

Accepts a full quaternion attitude target plus a body-frame angular velocity feed-forward (rad/s). The desired quaternion is advanced incrementally each timestep using the velocity input, giving smooth interpolation between attitudes.

virtual void input_quaternion(
    Quaternion& attitude_desired_quat,
    Vector3f ang_vel_body_rads);

set_throttle_out()

Sets the throttle output and optionally applies angle boost — a throttle increase that compensates for the reduced vertical thrust component when the vehicle is tilted. Implemented per subclass.

virtual void set_throttle_out(
    float throttle_in,
    bool apply_angle_boost,
    float filt_cutoff) = 0;

rate_controller_run()

Runs the inner rate PID loop and sends outputs to the motors. Must be called every loop at the highest available rate (typically 400 Hz on STM32 hardware). Pure virtual — implemented in each subclass.

virtual void rate_controller_run() = 0;

relax_attitude_controllers()

Zeros attitude errors so the rate controller produces no corrective output. Called on arming, mode transitions, and during landing to prevent integrator wind-up.

void relax_attitude_controllers();

PID accessor methods

The angle P controllers and rate PIDs are accessible for parameter tuning and logging:

AC_P&   get_angle_roll_p();    // ATC_ANG_RLL_P
AC_P&   get_angle_pitch_p();   // ATC_ANG_PIT_P
AC_P&   get_angle_yaw_p();     // ATC_ANG_YAW_P

// Pure virtual — implemented in derived classes:
virtual AC_PID& get_rate_roll_pid()  = 0;   // ATC_RAT_RLL_*
virtual AC_PID& get_rate_pitch_pid() = 0;   // ATC_RAT_PIT_*
virtual AC_PID& get_rate_yaw_pid()   = 0;   // ATC_RAT_YAW_*

Subclasses

AC_AttitudeControl_Multi

Used by ArduCopter for multirotor vehicles. Provides concrete implementations of the three rate PIDs (roll, pitch, yaw), rate_controller_run(), set_throttle_out(), and the throttle-RPY mix logic. Default rate PID gains: roll/pitch P=0.135, I=0.135, D=0.0036; yaw P=0.180, I=0.018.

AC_AttitudeControl_Heli

Used by ArduCopter for traditional helicopters. Overrides the rate controllers with leaky integrator logic suited to collective-pitch rotor dynamics, and exposes a roll trim to counteract tail-rotor thrust in hover.

Additional subclasses exist for tail-sitters (AC_AttitudeControl_TS), submarines (AC_AttitudeControl_Sub), and 6-DoF multirotors (AC_AttitudeControl_Multi_6DoF). Each overrides only the methods that differ from the multirotor base.

Key parameters

Angle loop gains

Parameter	Description	Default
`ATC_ANG_RLL_P`	Roll angle P gain	4.5
`ATC_ANG_PIT_P`	Pitch angle P gain	4.5
`ATC_ANG_YAW_P`	Yaw angle P gain	4.5

Rate loop gains (multirotor)

Parameter	Description	Default
`ATC_RAT_RLL_P`	Roll rate proportional gain	0.135
`ATC_RAT_RLL_I`	Roll rate integral gain	0.135
`ATC_RAT_RLL_D`	Roll rate derivative gain	0.0036
`ATC_RAT_PIT_P`	Pitch rate proportional gain	0.135
`ATC_RAT_PIT_I`	Pitch rate integral gain	0.135
`ATC_RAT_PIT_D`	Pitch rate derivative gain	0.0036
`ATC_RAT_YAW_P`	Yaw rate proportional gain	0.180
`ATC_RAT_YAW_I`	Yaw rate integral gain	0.018
`ATC_RAT_YAW_D`	Yaw rate derivative gain	0.0

Acceleration and slew limits

Parameter	Description	Default
`ATC_ACCEL_R_MAX`	Maximum roll acceleration (deg/s²)	1100
`ATC_ACCEL_P_MAX`	Maximum pitch acceleration (deg/s²)	1100
`ATC_ACCEL_Y_MAX`	Maximum yaw acceleration (deg/s²)	270
`ATC_RATE_P_MAX`	Maximum yaw slew rate in auto modes (deg/s)	60
`ATC_INPUT_TC`	Input smoothing time constant (s)	(vehicle-specific)

Setting ATC_ACCEL_R_MAX and ATC_ACCEL_P_MAX to zero disables acceleration limiting, which is useful when running AutoTune so the square-root controller does not interfere with P-gain measurement.

Slew rate limiting

Yaw slew rate limiting is enforced by get_slew_yaw_max_rads() during angle commands with slew_yaw = true. This prevents the yaw target from jumping, which would otherwise produce large yaw-rate transients that disturb altitude and position hold. The limit is derived from ATC_RATE_P_MAX (maximum yaw rate in waypoint navigation modes). For output-level slew limiting on the rate PIDs, see AC_PID’s _slew_rate_max (SMAX) parameter.

Motor mixing integration

AC_AttitudeControl does not write motor outputs directly. After rate_controller_run() computes normalized roll, pitch, and yaw torque values (range –1 to +1), these are passed to AP_Motors, which performs the vehicle-specific mixing matrix multiplication and scales the results to the ESC PWM range. Throttle is blended with attitude torques via _throttle_rpy_mix, which is slewed between _thr_mix_min (landing) and _thr_mix_max (active flight) to balance vertical thrust against attitude authority.

Feed-forward

Body-frame rate feed-forward (ATC_RATE_FF_ENAB, default enabled) shapes the angular velocity targets using the configured acceleration limits and time constants before passing them to the rate PIDs. Disabling it causes the attitude target to be integrated directly, without shaping — useful for diagnosing oscillations.

Source location

libraries/AC_AttitudeControl/AC_AttitudeControl.h — base class
libraries/AC_AttitudeControl/AC_AttitudeControl_Multi.h — multirotor subclass
libraries/AC_AttitudeControl/AC_AttitudeControl_Heli.h — helicopter subclass

Sensors & Navigation

Control & Planning

Communication & Peripherals

AC_AttitudeControl: Rotary-Wing Attitude Controller

Control hierarchy

Angle loop (outer)

Rate loop (inner)

Input shaping

Key methods

PID accessor methods

Subclasses

AC_AttitudeControl_Multi

AC_AttitudeControl_Heli

Key parameters

Angle loop gains

Rate loop gains (multirotor)

Acceleration and slew limits

Slew rate limiting

Motor mixing integration

Feed-forward

Source location

Build docs developers (and LLMs) love

Sensors & Navigation

Control & Planning

Communication & Peripherals

Documentation Index

​Control hierarchy

Angle loop (outer)

Rate loop (inner)

​Input shaping

​Key methods

​PID accessor methods

​Subclasses

AC_AttitudeControl_Multi

AC_AttitudeControl_Heli

​Key parameters

​Angle loop gains

​Rate loop gains (multirotor)

​Acceleration and slew limits

​Slew rate limiting

​Motor mixing integration

​Feed-forward

​Source location

Build docs developers (and LLMs) love

Control hierarchy

Input shaping

Key methods

PID accessor methods

Subclasses

Key parameters

Angle loop gains

Rate loop gains (multirotor)

Acceleration and slew limits

Slew rate limiting

Motor mixing integration

Feed-forward

Source location