Loiter Horizontal Maximum Acceleration (LOIT_ACC_MAX)

Description

LOIT_ACC_MAX is the "throttle response" setting for your drone's horizontal movement in Loiter mode. It determines how fast the drone can transition from a hover to full speed (LOIT_SPEED) when you slam the stick forward.

• Low Value (e.g. 100): The drone accelerates very slowly and "lazily." It feels like a massive ship. Ideal for smooth cinematic pans.
• High Value (e.g. 800): The drone accelerates instantly and aggressively. It feels like a high-performance sports car.
• Default (500): 5.0 m/s² (roughly 0.5G). A standard setting that feels snappy but controllable for most pilots.

The Mathematics

This parameter provides the acceleration limit ($a\_{max}$) for the pilot-driven path shaper:

$$ \vec{V}{target}(t) = \vec{V}{target}(t-dt) + \text{constrain}(\vec{a}{calc}, -a{max}, a\_{max}) \cdot dt $$

Where:

• $a\_{max}$ is LOIT_ACC_MAX.

Physical Consequence: If LOIT_ACC_MAX is set to 500, and your drone has a Hover Throttle of 50%, it will have to tilt by about 27 degrees ($ \tan^{-1}(500/980) $) to achieve this acceleration. If your ANGLE_MAX is lower than this, you will never reach full acceleration.

The Engineer's View

This parameter is the _accel_cmss member in AC_Loiter.

Unlike Auto mode (which uses WPNAV_ACCEL), Loiter mode uses this parameter to calculate the "Inertia" felt by the pilot. A critical feature of this controller is that Acceleration is prioritized over Speed. If the drone is hit by a gust, it will use the full LOIT_ACC_MAX authority to hold its position before it even considers the pilot's speed request.

Tuning & Behavior

• Default Value: 500 cm/s² (5.0 m/s²)
• Range: 50 - 1000 cm/s²
• Effect of Increasing: Snappier, more "connected" feel to the sticks. Better performance for manual object tracking.
• Effect of Decreasing: Smoother, "floaty" feel. Greatly reduces the chance of accidental jerky movements appearing on camera.

Use Case Recommendations

• Aerial Cinematography: Decrease to 200 - 300. Makes every start and stop look smooth and professionally damped.
• Precision Industrial Work: Keep at 500. You want the drone to move exactly when you tell it to, with no lazy ramp-up.
• Racing / Freestyle: Increase to 800 - 1000. Provides the instant authority needed to change directions at the edge of the flight envelope.

Troubleshooting

• Scenario: Drone feels "nervous" or "jittery" in Loiter, even though P-gains are low.
  • Diagnosis: LOIT_ACC_MAX is too high, causing the drone to over-react to tiny finger twitches.
  • Fix: Reduce LOIT_ACC_MAX to 250.

Loiter Maximum Lean Angle (LOIT_ANG_MAX)

Description

LOIT_ANG_MAX is the "tilt limiter" specifically for Loiter mode.

When you fly in Loiter, the flight controller is doing two things at once: following your stick commands and fighting the wind. If both of these require a steep lean, the drone might tilt too far and lose altitude. LOIT_ANG_MAX allows you to cap the "aggression" of Loiter mode, making it gentler and safer than manual flight modes like Stabilize.

• Set to 0 (Default): The drone uses the global ANGLE_MAX (typically 30-45 degrees).
• Set > 0: The drone will never lean further than this angle in Loiter, even if you push the sticks to the limit and a strong wind is blowing.

Physical Meaning: A lower lean angle means a lower maximum speed and slower braking. If you set this to 15 degrees, the drone will feel very calm and stable, but it won't be able to fly fast.

The Mathematics

The controller uses a ternary selector to determine the active limit ($\theta\_{limit}$):

$$ \theta\_{limit} = \begin{cases} \text{LOIT\_ANG\_MAX}, & \text{if } \text{LOIT\_ANG\_MAX} > 0 \ \text{ANGLE\_MAX}, & \text{otherwise} \end{cases} $$

Where $\theta\_{limit}$ is in degrees. This limit is applied to the final output of the 2D position and velocity controllers before the lean angle is sent to the attitude controller.

The Engineer's View

This parameter is the _angle_max member in AC_Loiter.

It is applied at the end of the AC_Loiter::update() cycle. One important technical detail is that this limit includes wind compensation. If the wind requires 10 degrees of tilt to hold position, and LOIT_ANG_MAX is set to 20 degrees, the pilot only has 10 degrees of "leftover" tilt to use for movement. This ensures the drone never exceeds its safety envelope.

Tuning & Behavior

• Default Value: 0 (Inherit Global)
• Range: 0 - 45 degrees
• Effect of Increasing: Allows the drone to fly faster and stop more aggressively in Loiter mode.
• Effect of Decreasing: Makes the drone feel much more stable and predictable. Safe for beginners.

Use Case Recommendations

• Aerial Cinematography: Set to 20. Ensures the drone never tilts so aggressively that it jerks the gimbal or brings the propellers into the camera's view.
• Underpowered Drones / Large Payload: Set to 25. Prevents the drone from leaning so far that it doesn't have enough vertical thrust to stay in the air.
• Standard build: Keep at 0. Let the global safety limits handle the drone's behavior.

Troubleshooting

• Scenario: My drone hovers perfectly, but it's incredibly slow in Loiter mode, even with LOIT_SPEED set to 2000.
  • Diagnosis: LOIT_ANG_MAX is set too low, preventing the drone from tilting far enough to reach the target speed.
  • Fix: Set LOIT_ANG_MAX to 0 or increase to 30.

Loiter Braking Acceleration (LOIT_BRK_ACCEL)

Description

LOIT_BRK_ACCEL determines the "stopping distance" of your drone in Loiter mode. It defines the maximum deceleration the drone is allowed to use when you let go of the control sticks.

Think of it as the difference between a car with standard brakes and one with racing brakes.

• Low Value (e.g. 50): The drone will "coast" for a long distance after you release the stick. This looks very graceful on camera but can be dangerous if you need to stop quickly to avoid a tree.
• High Value (e.g. 400): The drone will "slam on the brakes," pitching up aggressively to stop in its tracks.
• Default (250): 2.5 m/s². A balanced stop that doesn't stress the frame but keeps the drone safe.

The Mathematics

The path shaper calculates the required deceleration ($a\_{brake}$) to reach zero velocity:

$$ a\_{brake} = \text{constrain}\left( \frac{V\_{current}^2}{2 \cdot \text{Dist}\_{to\_target}}, 0, \text{LOIT\_BRK\_ACCEL} \right) $$

If you release the sticks while flying at 10 m/s, and LOIT_BRK_ACCEL is 250 (2.5 m/s²), it will take exactly 4 seconds and 20 meters for the drone to come to a complete stop.

The Engineer's View

This parameter is the _brake_accel_cmss member in AC_Loiter.

It is specifically triggered when the sticks return to the Deadzone (THR_DZ). One advanced technical detail is that Braking uses a different Jerk limit (LOIT_BRK_JERK). This allows you to have a very high LOIT_BRK_ACCEL (for safety) but a low Jerk limit so the start of the braking maneuver isn't too violent for the gimbal.

// AC_Loiter.cpp
// Logic for entering the "Braking State" and applying _brake_accel_cmss.

Tuning & Behavior

• Default Value: 250 cm/s² (2.5 m/s²)
• Range: 25 - 500 cm/s²
• Effect of Increasing: Shorter stopping distance. Drone feels more "responsive" to stick centering.
• Effect of Decreasing: Smoother, "lazier" stops. Much better for cinematic "flow."

Use Case Recommendations

• Cinematography: Decrease to 100 - 150. This prevents the drone from jerking the horizon every time you finish a move.
• Precision Industrial Flight: Increase to 350 - 400. If you are flying 1 meter away from a building, you want the drone to stop instantly when you release the stick.
• Racing: Keep Default or Increase. You need reliable stopping power to hit gates in Loiter mode.

Troubleshooting

• Scenario: I release the stick, and the drone tilts back so hard that the landing gear appears in the camera shot.
  • Diagnosis: LOIT_BRK_ACCEL is too high, or LOIT_BRK_JERK is too high.
  • Fix: Reduce LOIT_BRK_ACCEL to 150.
• Scenario: I release the stick, but the drone keeps drifting for 5-10 meters before stopping.
  • Diagnosis: LOIT_BRK_ACCEL is too low.
  • Fix: Increase LOIT_BRK_ACCEL to 300.

Loiter Brake Start Delay (LOIT_BRK_DELAY)

Description

LOIT_BRK_DELAY is a small but important "usability" setting for Loiter mode. It determines how long the drone should wait before it starts its active braking maneuver.

When you center your control sticks, the drone can either stop immediately or "coast" for a fraction of a second. This delay is useful because it prevents the drone from "jerking" its brakes if you are just passing the stick through the center point (e.g., when switching from flying forward to flying backward).

• Low Value (0.0): The drone brakes the instant the stick enters the deadzone. This is the most responsive setting but can feel "twitchy" for your fingers.
• High Value (e.g. 1.0): The drone will coast for a full second before it actively tries to stop. This feels very "loose" and is generally not recommended for precise flight.
• Default (0.1): A tiny 100ms buffer that makes stick-centering feel natural without adding noticeable lag.

The Mathematics

This parameter acts as a Deadzone Timer ($\Delta t\_{idle}$). The Braking state is only entered if:

$$ \text{Stick\_In\_Deadzone\_Time} \geq \text{LOIT\_BRK\_DELAY} $$

If the pilot moves the stick out of the deadzone before the delay expires, the braking state is cancelled and the drone continues to follow the pilot's speed command.

The Engineer's View

This parameter is the _brake_delay member in AC_Loiter.

It is a simple time-logic gate. In the AC_Loiter::update() loop, a counter tracks how many milliseconds have passed since the sticks were last outside the THR_DZ. This prevents the "SCurve Shaper" from resetting its target every time a pilot has a shaky finger.

// AC_Loiter.cpp
// Timer logic for initiating the brake shaper.

Tuning & Behavior

• Default Value: 0.1s
• Range: 0.0 - 2.0s
• Effect of Increasing: The drone feels "smoother" to pilot commands but takes longer to come to a stop.
• Effect of Decreasing: The drone stops instantly. Stick feel is much more "robotic."

Use Case Recommendations

• High-Resolution Photography: Keep at 0.1. This small buffer prevents tiny finger movements from triggering a gimbal-shaking brake maneuver.
• Tactical / FPV Loitering: Decrease to 0.0. You want the absolute maximum responsiveness. If you center the stick, the drone must stop now.
• Beginner Training: Increase to 0.3. Makes the drone feel more forgiving of "nervous" stick movements through the center point.

Troubleshooting

• Scenario: Drone seems to "hesitate" for a split second after I release the sticks before it finally starts to brake.
  • Diagnosis: LOIT_BRK_DELAY is set too high.
  • Fix: Reduce to 0.1 or 0.0.

Loiter Braking Jerk (LOIT_BRK_JERK)

Description

LOIT_BRK_JERK determines the "Feel" of the brakes. While LOIT_BRK_ACCEL determines the force used to stop, LOIT_BRK_JERK determines how quickly that force is applied.

• Low Value (500): The drone will "ease into" its braking move. This prevents the drone from jerking the camera gimbal when you release the stick.
• High Value (2000+): The drone will "snap" into its braking move instantly. This feels very responsive but can be mechanically stressful.

Pro-Tip: If you want your drone to stop fast but not look jerky on camera, use a High LOIT_BRK_ACCEL combined with a Low LOIT_BRK_JERK. This allows the drone to reach a high braking power, but ramps that power up smoothly.

The Mathematics

This parameter limits the rate of change of the braking acceleration ($a\_{brake}$):

$$ \left| \frac{da\_{brake}}{dt} \right| \leq \text{LOIT\_BRK\_JERK} $$

Where:

• $\text{LOIT\_BRK\_JERK}$ is in cm/s³.
• Example: If set to 500, it will take 0.5 seconds to reach a full 250 cm/s² braking acceleration.

The Engineer's View

This parameter is the _brake_jerk_max_cmsss member in AC_Loiter.

It is applied at the transition between the Pilot Input State and the Braking State. When the pilot centers the sticks, the EKF position at that moment is used as the target, and this jerk-limited shaper is used to calculate the deceleration path.

// AC_Loiter.cpp
// Braking shaper logic uses _brake_jerk_max_cmsss to smooth the transition to zero velocity.

Tuning & Behavior

• Default Value: 500 cm/s³ (0.5 m/s³)
• Range: 500 - 5000 cm/s³
• Effect of Increasing: The drone reacts faster when you let go of the stick. Stops feel "robotic" and crisp.
• Effect of Decreasing: Stops feel "organic" and fluid. Reduces gimbal oscillation during the braking phase.

Use Case Recommendations

• High-End Cinematography: Keep Default (500). This is the sweet spot for smooth camera work.
• Search and Rescue / Industrial: Increase to 1500. When searching for an object, you want the drone to stop exactly where you saw it, with no lazy "gliding."
• Small Stiff Frames (Racing): Set to 2500. These frames handle jerk well and benefit from the faster response.

Troubleshooting

• Scenario: When I let go of the stick, the drone makes a sudden "thump" sound from the motors before it starts to slow down.
  • Diagnosis: LOIT_BRK_JERK is too high, commanding a torque change faster than the frame can handle.
  • Fix: Reduce LOIT_BRK_JERK to 500.

QLoiter mode options (LOIT_OPTIONS)

Note: This parameter is an alias for Q_LOIT_OPTIONS.

Loiter radius (LOIT_RADIUS)

Description

LOIT_RADIUS is a Rover-specific parameter. It defines an "acceptance circle" around the loiter target.

Unlike a Multicopter (which tries to stay on a single pixel), a Rover (especially a Boat) often has to deal with currents or momentum that make perfect station-keeping difficult. LOIT_RADIUS creates a dead-zone where the Rover doesn't constantly fight small errors, saving battery and reducing mechanical wear on the steering/motors.

The Mathematics

The error $e$ is the distance to target.
$$ \text{Correction} = \begin{cases} \text{PID}(e) & \text{if } e > \text{LOIT\_RADIUS} \ 0 & \text{if } e \leq \text{LOIT\_RADIUS} \end{cases} $$
(Note: Actual implementation uses a smoother blend, but this logic captures the intent).

The Engineer's View

In the Rover codebase, this is handled in ModeLoiter. It prevents "hunting" around the target point. For boats, this is often set to match the accuracy of the GPS or the length of the hull.

Tuning & Behavior

• Default Value: 2 meters
• Range: 0 to 20 meters
• Recommendation:
  • Boats: Set to 5.0m or higher if in a current. This prevents the motor from constantly pulsing on and off.
  • Precision Rovers: Set to 0.5m or 1.0m if using RTK GPS and you need tight positioning.
  • Sailboats: This parameter is critical for "heaving-to" or staying within a start box.

Loiter Horizontal Maximum Speed (LOIT_SPEED)

Description

LOIT_SPEED is the "Speed Limiter" for your drone's most common flight mode: Loiter.

When you push the pitch or roll stick all the way to the edge in Loiter mode, the drone doesn't just lean over to a fixed angle—it attempts to reach a specific ground speed. LOIT_SPEED defines what that maximum speed is.

• Standard Speed (1250): 12.5 meters per second (45 km/h). A fast but manageable speed for general flight.
• High Speed: Makes the drone feel much more capable during transits, but makes fine position adjustments more difficult because the stick sensitivity is higher.
• Low Speed: Excellent for precision inspection or when learning to fly. It effectively makes the drone "un-crashable" from over-speeding.

The Mathematics

The pilot's stick position ($S$, from -1 to 1) is linearly mapped to a Target Velocity ($V\_{target}$):

$$ V\_{target} = S \cdot \text{LOIT\_SPEED} $$

This target velocity is then passed to the S-Curve shaper, which ensures the drone accelerates smoothly to reach that speed without exceeding the LOIT_ACC_MAX limit.

Precision Mode: At very small stick deflections, ArduPilot uses a different sensitivity curve to allow for centimeter-level positioning even if LOIT_SPEED is set very high.

The Engineer's View

This parameter is the _speed_cms member in AC_Loiter.

It is fundamentally different from Stabilize mode. In Stabilize, the stick controls Angle. In Loiter, the stick controls Velocity. This means that if you are flying at LOIT_SPEED and you let go of the sticks, the drone will automatically calculate the required "braking acceleration" to bring the velocity back to zero as quickly as possible.

// AC_Loiter.cpp
// Stick input scaling logic uses _speed_cms.

Tuning & Behavior

• Default Value: 1250 cm/s (12.5 m/s)
• Range: 20 - 3500 cm/s
• Effect of Increasing: Faster travel between points in Loiter. Drone feels more powerful.
• Effect of Decreasing: Drone feels "gentle" and safe. Stick movements result in smaller, more controlled speed changes.

Use Case Recommendations

• Industrial Inspection: Decrease to 500. When flying near a cell tower or bridge, you want the drone to move slowly even if you accidentally bump the stick.
• Standard Hobby Flight: Set to 1500 - 2000. Allows for spirited flying while still maintaining the safety of a GPS-locked hover.
• Search and Rescue: Increase to 2500. Speed is critical when searching large areas manually.

Troubleshooting

• Scenario: Drone feels very "twitchy" in Loiter—even a tiny stick move makes it lurch forward.
  • Diagnosis: LOIT_SPEED is set too high for the pilot's skill level or the frame's agility.
  • Fix: Reduce LOIT_SPEED to 1000.
• Scenario: Drone can't fly against a 10 m/s wind in Loiter.
  • Diagnosis: LOIT_SPEED must be higher than the wind speed to make progress.
  • Fix: Increase LOIT_SPEED to 1500.

Loiter speed gain (LOIT_SPEED_GAIN)

Description

LOIT_SPEED_GAIN is a Rover-specific parameter. It acts like a "Volume Knob" for how aggressively the vehicle tries to get back into its loiter circle.

• Low Value: The rover gently rolls back toward the center when it drifts out.
• High Value: The rover snaps back quickly, potentially causing "overshoot" or rapid motor pulsing.

The Mathematics

This gain $K\_{loit}$ scales the desired velocity $v\_{des}$ derived from the distance error $e$:
$$ v\_{des} = K\_{loit} \cdot \sqrt{2 \cdot a \cdot e} $$
(Following standard ArduPilot square-root controller logic for stopping distance).

The Engineer's View

Maps to g2.loiter_speed_gain in the Rover codebase.
It allows users to tune the responsiveness of loiter without having to touch the lower-level ATC_SPEED_P or ATC_STR_RAT_P gains, which affect all modes.

Tuning & Behavior

• Default Value: 0.5
• Recommendation:
  • If the rover "oscillates" (driving back and forth over the loiter point), decrease this to 0.2 or 0.3.
  • If the rover drifts way too far before reacting, increase this toward 1.0.

Loiter type (LOIT_TYPE)

Description

LOIT_TYPE is a Rover-specific parameter that tells the vehicle how to move when it drifts outside its loiter circle.

• 0: Forward or Reverse. The rover will take the shortest path back to the center, even if it means driving backward. (Recommended for standard rovers).
• 1: Always Face Forward. The vehicle will only drive forward to return to the point. It will perform a U-turn if necessary. (Recommended for boats without a reverse gear or large scale rovers).
• 2: Always Face Stern. The vehicle will only move backward to return. (Rarely used).

The Mathematics

This parameter toggles the logic branch in the steering/throttle controller:
$$ \text{TargetHeading} = \begin{cases} \theta\_{direct} & \text{if Type 1} \ \theta\_{direct} \pm 180^\circ & \text{if Type 0 and } dist < limit \end{cases} $$

The Engineer's View

Controlled in Rover::ParametersG2::loit_type.
Affects path planning within ModeLoiter. If Type 1 is selected, the "Pivot Turn" logic may be triggered depending on the angle error.

Tuning & Behavior

• Default Value: 0 (Shortest path)
• Recommendation:
  • Cars/Mowers: Use 0. It's the most efficient for battery life.
  • Boats: Use 1 if your motor setup doesn't handle reverse well or if you want the boat to always face the wind/waves while loitering.