Weathervaning min angle (WVANE_ANG_MIN)

Description

This parameter sets a "Deadzone" for the weather vane controller. It defines the minimum amount of roll (or pitch) lean the aircraft must experience before the controller begins to apply any yaw correction.

This prevents the aircraft from constantly "hunting" or jittering in response to small turbulence or minor trim offsets. It ensures the controller only reacts to significant wind forces.

The Mathematics

The deadzone is subtracted from the absolute error angle.

$ Error\_{effective} = \max( |Angle\_{measured}| - ANG\_MIN, 0 ) $

If the measured angle is less than ANG_MIN, the error is zero, and no yaw output is generated.

The Engineer's View

In AC_WeatherVane::get_yaw_out, the parameter is converted to centi-degrees (deadzone_cdeg) and used as a threshold.
It is applied to both Roll and Pitch (if PITCH_ENABLE is set) axes.

Tuning & Behavior

• Default Value: 1.0 degree
• Range: 0 to 10 degrees
• Effect of Increasing: Increases the deadzone. The aircraft will tolerate more lean before correcting. Useful if the aircraft is poorly trimmed or if you want to allow some side-slip.
• Effect of Decreasing: Makes the controller more sensitive. Setting it to 0 means it will react to even the slightest roll angle, which may cause continuous small yaw corrections.

Weathervaning Enable (WVANE_ENABLE)

Description

WVANE_ENABLE activates a feature that allows the drone to act like a weather vane. When enabled, the drone will automatically rotate (yaw) so that it is always facing into the wind while hovering in a position-controlled mode (like Loiter or QLoiter).

This is extremely beneficial for QuadPlanes and Long-Endurance Multirotors. By pointing the nose into the wind, the drone minimizes its surface area and drag, which reduces the motor power needed to maintain position, leading to significantly longer flight times and better stability in gusty conditions.

• 0: Disabled. No automatic rotation.
• 1: Nose into wind. The drone points its front toward the wind.
• 2: Nose or tail into wind.
• 3: Side into wind.
• 4: Tail into wind.

The Mathematics

The controller monitors the drone's current "Leaning Angle" (Roll/Pitch). Since the drone must lean against the wind to stay stationary, the roll angle $\phi$ is used as an error signal:
$$ \text{YawRate}\_{cmd} = \text{WVANE\_GAIN} \cdot (\phi - \text{WVANE\_ANG\_MIN}) $$

The drone yaws until the roll angle required to maintain position is minimized (i.e., it is facing directly into the wind).

The Engineer's View

Used in AC_WeatherVane::get_yaw_out().
The logic includes a 2-second stability buffer to prevent the drone from spinning wildly during momentary gusts. Pilot yaw stick input always overrides the weathervaning action.

Tuning & Behavior

• Default Value: 0 (Disabled)
• Recommendation:
  • QuadPlanes: Set to 1 (Nose into wind). This prevents the large wings from acting as a sail and destabilizing the hover.
  • Multicopters: Set to 1 if you frequently fly in windy conditions to improve battery efficiency.
• Dependencies: Requires a healthy position estimate (GPS) and WVANE_GAIN set correctly (usually 1.0).

Weathervaning gain (WVANE_GAIN)

Description

This parameter controls the "strength" of the weather vaning response. It acts as a multiplier that converts the aircraft's lean angle (caused by wind) into a command to rotate (yaw) into the wind.

A higher gain means the aircraft will turn faster into the wind for a given amount of lean. A lower gain results in a gentler, slower turn.

The Mathematics

The output is calculated by applying a Low Pass Filter (LPF) to the product of the error and the gain.

$ Rate\_{yaw} = LPF( Error\_{deg} \cdot Gain ) $

Where:

• $ Error\_{deg} $ is the calculated misalignment (mostly Roll angle, or Pitch angle if options enabled).
• $ Gain $ is WVANE_GAIN.
• $ LPF $ is a smoothing filter: $ y\_n = 0.98 y\_{n-1} + 0.02 x\_n $

For example, if the aircraft is rolled 10 degrees due to wind and the Gain is 2.0, the target yaw rate will settle at 20 degrees per second.

The Engineer's View

The parameter is used in AC_WeatherVane::get_yaw_out.
The heavy low-pass filter ($ \alpha = 0.02 $) is hardcoded to prevent oscillation and ensure smooth yaw changes. This means the weathervaning response is intentionally damped and will lag slightly behind the instantaneous roll angle.

Tuning & Behavior

• Default Value: 1 (Plane/Copter), 0 (Disabled/Other)
• Range: 0.5 to 4.0
• Effect of Increasing: The aircraft will yaw more aggressively into the wind. If set too high, it may overshoot or oscillate (wag its tail).
• Effect of Decreasing: The aircraft will take longer to align with the wind.
• Dependencies: WVANE_ENABLE must be active. WVANE_OPTIONS affects how the error is calculated.

Weathervaning Minimum Height (WVANE_HGT_MIN)

Description

WVANE_HGT_MIN prevents the drone from rotating while it is still very close to the ground. This ensures that the drone is safely clear of landing pads, grass, or personnel before it begins its automatic alignment with the wind.

Weathervaning Land Enable (WVANE_LAND)

Description

WVANE_LAND determines if the drone should face into the wind while it is touching down. This is highly recommended for QuadPlanes, as landing with a strong tailwind or crosswind can cause the drone to tip over or lose stability just as the motors spool down.

Weathervaning options (WVANE_OPTIONS)

Description

This parameter controls advanced behavior modifiers for the Weather Vane controller. The Weather Vane controller automatically yaws the aircraft into the wind during VTOL flight to reduce drag and improve stability.

By default, the controller primarily uses the Roll angle to detect if the aircraft is being blown sideways and applies a Yaw correction. Enabling specific options here allows the controller to also use Pitch information, providing a faster and more robust response when the wind is coming from the front or back.

The Mathematics

When Bit 0 (PITCH_ENABLE) is active, the controller adds the pitch error to the total error term, increasing the aggressiveness of the yaw correction.

Standard Logic (Bit 0 = 0):
$$ Error = \max(|Roll\_{deg}| - Deadzone, 0) $$

Enhanced Logic (Bit 0 = 1):
For Nose In weather vaning:
$$ Error = |Roll\_{deg}| + \max(Pitch\_{deg} - Deadzone, 0) $$
(Only applied if Pitch > Deadzone)

This effectively means that if the aircraft is pitching up to fight the wind (while nose-in), that pitch effort is treated as "misalignment" energy that needs to be converted into a yaw correction to face the wind more directly.

The Engineer's View

This parameter is read in AC_WeatherVane::get_yaw_out inside libraries/AC_AttitudeControl/AC_WeatherVane.cpp.

It is cast to the AC_WeatherVane::Options enum.

• Bit 0 (PITCH_ENABLE):
  • Defined as (1<<0).
  • When set, it modifies the error calculation for Direction::NOSE_IN and Direction::TAIL_IN.
  • For NOSE_IN: It checks if pitch_cdeg is positive (nose up) and exceeds the deadzone.
  • For TAIL_IN: It checks if pitch_cdeg is negative (nose down) and exceeds the deadzone (in the negative direction).

This is particularly useful for QuadPlanes or Tailsitters where wind resistance manifests as both a roll moment (side force) and a pitch moment (drag).

Tuning & Behavior

• Bit 0 (Value 1): Enable Pitch Input.
  • Recommended For: Aircraft that tend to "hang" in the wind with a high pitch angle but fail to yaw into it aggressively enough.
  • Effect: Increases weathervaning gain effectively when the aircraft is pitching to hold position against the wind.

Weathervaning max ground speed (WVANE_SPD_MAX)

Description

This parameter defines a maximum ground speed threshold for active weathervaning. If the aircraft is moving across the ground faster than this speed, the weather vane controller is automatically disabled.

This is typically used to ensure that weathervaning only occurs during hover or slow maneuvering, and not during high-speed forward flight where the aerodynamics of the airframe (like a vertical tail) or other navigation controllers should take precedence.

The Mathematics

The controller checks the magnitude of the horizontal velocity vector ($V\_{xy}$).

$ If \quad ||V\_{xy}|| > SPD\_MAX \quad \rightarrow \quad Disable \quad Weathervaning $

The logic requires a valid velocity estimate from the AHRS/EKF. If speed is unknown, weathervaning is disabled for safety.

The Engineer's View

In AC_WeatherVane::get_yaw_out, this check uses vel_ned.xy().length_squared() against _max_vel_xy squared to avoid square root operations.
If SPD_MAX is set to 0, this check is skipped (weathervaning allowed at any speed).

Tuning & Behavior

• Default Value: 0 (Disabled/Unlimited) for Plane, typically higher for Copter.
• Range: 0 to 50 m/s.
• Effect of Increasing: Allows weathervaning at higher ground speeds.
• Effect of Decreasing: Restricts weathervaning to lower speeds.
• Note: If set to 0, the speed check is ignored.

Weathervaning Takeoff Enable (WVANE_TAKEOFF)

Description

WVANE_TAKEOFF allows the drone to automatically rotate to face the wind as soon as it leaves the ground. This ensures that the climb-out phase of a mission is as efficient and stable as possible.

Weathervaning Max Vertical Speed (WVANE_VELZ_MAX)

Description

WVANE_VELZ_MAX sets a "Safety Cap" on weathervaning during climbs and descents.

If the drone is climbing or descending very fast, the aerodynamic forces on the airframe change significantly. This parameter ensures that the autopilot stops trying to rotate the drone into the wind if the vertical speed is too high, which could cause instability.

• 0 (Default): Always allowed (Disabled vertical speed limit).
• Recommendation: Leave at 0 unless you notice heading instability specifically during fast climbs or descents.