MAVLINKHUD

LOITER Mode (Plane)

Executive Summary

LOITER Mode is the standard GPS-position-hold mode for fixed-wing aircraft. When engaged, the plane captures its current location and altitude, then orbits that point indefinitely. It uses the L1 Navigation Controller to maintain a precise ground track, automatically banking into the wind to ensure the circle remains perfectly round and centered relative to the ground.

Theory & Concepts

1. The Geometry of the Loiter

A fixed-wing plane cannot stop in the air. To "Hold Position," it must fly in a circle.

  • The Problem: In a 10 m/s wind, a circular flight path relative to the air looks like a "Slinky" relative to the ground.
  • The Solution: The L1 controller. It constantly varies the bank angle. It banks steeper on the downwind leg (to turn faster) and shallower on the upwind leg (to turn slower).
  • The Result: A perfect circular ground track.

2. Tangential Exit

When a plane leaves a Loiter to fly to a new waypoint, it doesn't just turn.

  • The Math: ArduPilot calculates the Tangent Point on the circle that aligns with the next path.
  • The Benefit: Smooth, efficient transitions without awkward "wiggles" as the plane leaves the orbit.

Hardware Dependency Matrix

LOITER is a navigation mode.

Sensor Requirement Code Implementation Notes
GPS CRITICAL Required to define the center point and track ground speed/course. Without GPS, the L1 controller cannot function.
Compass CRITICAL Required for heading.
Barometer REQUIRED Primary source for altitude control.
Airspeed RECOMMENDED Improves TECS performance (altitude/speed management) during the turn.

Control Architecture (Engineer's View)

LOITER mode combines L1 Lateral Navigation with TECS Longitudinal Control.

  1. Entry Logic:
    • On engagement, the code captures the Current Location (Lat/Lon) and sets it as the "Loiter Center".
    • It captures the Current Altitude as the target altitude.
    • Code Path: ModeLoiter::_enter().
  2. Lateral Control (L1 Orbit):
    • The L1 Controller calculates the bank angle required to stay on the circle's perimeter (WP_LOITER_RAD).
    • Wind Compensation: If there is a crosswind, the plane will "crab" (yaw into the wind) and bank steeper on the downwind leg to prevent being blown off course.
    • Code Path: ModeLoiter::navigate() calls plane.update_loiter().
  3. Longitudinal Control (TECS):
    • The plane manages throttle and pitch to maintain the target altitude and airspeed (TRIM_ARSPD_CM).

Pilot Interaction

  • Default: The pilot has no control. The plane flies the circle automatically.
  • Alt Control Option: If FLIGHT_OPTIONS bit ENABLE_LOITER_ALT_CONTROL is set, the pilot can use the Elevator stick to change altitude (Climb/Descend) and the Throttle stick to change target Airspeed, similar to FBWB.
    • Note: You cannot "nudge" the circle's center horizontally in standard Plane Loiter.

Failsafe Logic

  • GPS Loss: The L1 controller will fail. The plane may enter a "Dead Reckoning" mode or drift. It is safer to switch to Stabilize or CIRCLE (non-GPS) if GPS is lost.

Key Parameters

Parameter Default Description
WP_LOITER_RAD 60 (m) Radius of the orbit. Positive = Clockwise, Negative = Counter-Clockwise.
MIN_GNDSPD_CM 0 Minimum ground speed to maintain even in strong headwinds.

Source Code Reference