Waypoint Horizontal Acceleration (WPNAV_ACCEL)

Description

WPNAV_ACCEL is the "Gas Pedal" limit for your drone's autonomous brain. It determines how hard the drone should lean forward to reach its cruising speed (WPNAV_SPEED) and how hard it should lean back to stop at a waypoint.

• Low Value (e.g. 50): The drone accelerates and brakes very gently. Flight feels very smooth and "lazy." Ideal for cinematography.
• High Value (e.g. 200): The drone snaps to its target speed instantly. Flight feels very robotic and aggressive.
• Default (100): 1.0 m/s². A standard, safe value that is comfortable for most payloads.

Physical Context: 100 cm/s² is roughly 0.1G. Setting this to 500 would be 0.5G, which requires a steep lean angle and high battery current.

The Mathematics

This parameter defines the acceleration limit ($a\_{max}$) for the 2D path shaper. When starting a mission segment:

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

Where:

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

The Total 2D Acceleration is limited, meaning the combination of North and East acceleration will never exceed this value, resulting in smooth, circular turn profiles rather than "square" corners.

The Engineer's View

This parameter is the _wp_accel_cmss member in AC_WPNav.

It is a core input to the S-Curve Kinematic path generator. One subtle detail is that WPNAV_ACCEL also determines the Braking Distance.

$$ \text{Stop\_Dist} = \frac{V^2}{2 \cdot a\_{max}} $$

If you set WPNAV_SPEED very high but WPNAV_ACCEL very low, the drone will have to start braking 50 meters before the waypoint, which can make the mission feel very slow.

Tuning & Behavior

• Default Value: 100 cm/s² (1.0 m/s²)
• Range: 50 - 500 cm/s²
• Effect of Increasing: Faster stop-and-go maneuvers. Drone reaches waypoint speed sooner. Better for high-wind handling in missions.
• Effect of Decreasing: Smoother cinematic motion. Less "jerking" of the gimbal. Safer for unstable payloads.

Use Case Recommendations

• Cinematography: Decrease to 50. Provides extremely smooth transitions between waypoints.
• Rapid Delivery / Rescue: Increase to 150 - 200. Every second counts; you want the drone at its cruise speed as fast as possible.
• Mapping: Keep Default. Standard values are sufficient for consistent overlap.

Troubleshooting

• Scenario: Drone "lunges" forward violently at the start of a mission segment.
  • Diagnosis: WPNAV_ACCEL is too high for the vehicle's power-to-weight ratio.
  • Fix: Reduce to 80.
• Scenario: Drone consistently overshoots the waypoint during a mission.
  • Diagnosis: WPNAV_ACCEL is too low, and the drone doesn't have enough "braking power" to stop from its current speed.
  • Fix: Increase WPNAV_ACCEL or reduce WPNAV_SPEED.

Waypoint Cornering Acceleration (WPNAV_ACCEL_C)

Description

WPNAV_ACCEL_C controls how "hard" the drone turns at waypoints during an autonomous mission.

It defines the maximum centripetal acceleration allowed during a cornering maneuver. This parameter determines whether the drone will slow down significantly to hit a sharp point, or maintain speed by flying a wider, more graceful arc.

• 0 (Default): Uses 2x the value of WPNAV_ACCEL. This is usually the best setting for a smooth mission.
• High Value: The drone will maintain high speed through corners, pulling high Gs. This looks aggressive and "jerky" but completes missions faster.
• Low Value: The drone will slow down significantly as it approaches waypoints to avoid high lateral forces.

The Mathematics

The maximum cornering speed $v\_{max}$ is calculated based on the radius of the turn $r$ and this acceleration limit $a\_c$:
$$ v\_{max} = \sqrt{a\_c \cdot r} $$

Where $a\_c$ is WPNAV_ACCEL_C.

If the drone is flying at WPNAV_SPEED and encounters a turn where the radius is too tight for the current $a\_c$, it must decelerate before entering the turn.

The Engineer's View

Used in AC_WPNav::advance_wp_target_along_track() and passed to the S-Curve trajectory generator.
The S-Curve logic uses this to calculate the "cornering arc" that connects two mission legs. If WPNAV_ACCEL_C is very high, the drone will start the turn much closer to the physical waypoint.

Tuning & Behavior

• Default Value: 0 (Defaults to $2 \times \text{WPNAV\_ACCEL}$)
• Recommendation: Leave at 0 for general use.
• Racing/Speed Missions: Increase to 400 or 500 to maintain maximum momentum. Ensure your ANGLE_MAX and motor thrust can handle the resulting lean angles.
• Cinematography: Decrease to 50 or 100 (or keep default 0) to ensure the camera gimbal isn't subjected to high lateral G-forces during turns.

Waypoint Vertical Acceleration (WPNAV_ACCEL_Z)

Description

WPNAV_ACCEL_Z is the "Vertical Gas Pedal" limit for autonomous flight. It determines how aggressively the drone initiates a climb or starts braking for a descent during a mission.

• Low Value (e.g. 50): The drone starts and stops its climbs very gently. Ideal for delicate payloads or cinematography.
• High Value (e.g. 200): The drone "punches" its way into climbs. Flight feels more robotic and rapid.
• Default (100): 1.0 m/s². A safe, balanced setting for most multirotors.

Constraint: This value should generally be set equal to or lower than PSC_ACCZ_P authority. If you set WPNAV_ACCEL_Z higher than what the drone can physically achieve, you will get "Altitude Slop" where the drone falls behind its mission path.

The Mathematics

This parameter sets the acceleration limit ($a\_{z\_max}$) for the vertical path shaper:

$$ V\_z(t) = V\_{z\_initial} + \text{constrain}(a\_{z\_calc}, -a\_{z\_max}, a\_{z\_max}) \cdot dt $$

Where:

• $a\_{z\_max}$ is WPNAV_ACCEL_Z.

The vertical shaper uses this to ensure that the transition between different vertical speeds follows a smooth ramp, preventing the "instant torque" shocks that can damage motor mounts.

The Engineer's View

This parameter is the _wp_accel_z_cmss member in AC_WPNav.

One important engineering detail: This limit is combined with the Jerk limit (WPNAV_JERK). The shaper will prioritize the jerk limit during the start of a move, and only reach full WPNAV_ACCEL_Z if the move is long enough.

// AC_WPNav.cpp
// Vertical shaper logic uses _wp_accel_z_cmss to calculate the velocity profile.

Tuning & Behavior

• Default Value: 100 cm/s² (1.0 m/s²)
• Range: 50 - 500 cm/s²
• Effect of Increasing: Snappier altitude corrections. Drone handles vertical "staircase" missions more efficiently.
• Effect of Decreasing: Smoother, more flowing altitude changes. Greatly reduces the "bobbing" often seen in camera gimbal footage.

Use Case Recommendations

• Cinematography: Decrease to 50 - 80. Prevents the "jerk" seen on the horizon when the drone finishes a climb.
• Rapid Mapping (Terrain Following): Increase to 150. When flying close to hills, the drone needs to accelerate vertically fast enough to follow the ground without crashing.
• Heavy Lift Cargo: Decrease to 50. Minimizes the vertical G-load on the airframe during transitions.

Troubleshooting

• Scenario: Drone makes a loud "thump" sound from the motors at the very top of a climb.
  • Diagnosis: WPNAV_ACCEL_Z is too high, causing a sudden motor current drop that triggers mechanical ringing.
  • Fix: Reduce WPNAV_ACCEL_Z to 80.

Waypoint Jerk Limit (WPNAV_JERK)

Description

WPNAV_JERK is the "refinement" setting for mission flight. While WPNAV_ACCEL tells the drone how hard to accelerate, WPNAV_JERK tells it how smoothly to apply that acceleration.

In physics, Jerk is the rate at which acceleration changes. High jerk means the drone snaps into a lean instantly; low jerk means it rolls into the lean gracefully. By setting this limit, ArduPilot ensures that autonomous missions (Auto, RTL) look professional and don't place unnecessary mechanical stress on the frame.

• Low Value (e.g. 1.0): Flight is extremely fluid. The drone takes a noticeable moment to "roll into" its forward flight. Best for high-end cinematography.
• High Value (e.g. 10.0): The drone snaps into its acceleration ramps instantly. Flight looks more robotic and "aggressive."
• Default (1.0): Optimized for standard, smooth multirotor flight.

The Mathematics

Jerk ($j$) is the third derivative of position ($p$):

$$ j(t) = \frac{da}{dt} = \frac{d^3p}{dt^3} $$

In the ArduPilot shaper, this parameter limits the curvature of the velocity graph. A mission segment's acceleration ($a$) must satisfy:

$$ |\Delta a| \leq \text{WPNAV\_JERK} \cdot dt $$

This creates the characteristic S-Curve velocity profile, where the transition from hover to cruising speed is rounded off at both the beginning and the end.

The Engineer's View

This parameter is the _wp_jerk member in AC_WPNav.

It defines the "snappiness" of the SCurve path shaper. One interesting technical detail is that WPNAV_JERK is expressed in m/s³, whereas WPNAV_ACCEL is in cm/s².

• A value of 1.0 m/s³ means the drone can increase its acceleration by 100 cm/s² every second.
• With the default WPNAV_ACCEL of 100, it would take exactly 1.0 second to reach full acceleration.

Tuning & Behavior

• Default Value: 1.0 m/s³
• Range: 1.0 - 20.0 m/s³
• Effect of Increasing: The drone reacts faster to the mission path. Corners are tighter (less drift).
• Effect of Decreasing: Maximum smoothness. Essential for capturing professional aerial video without any "horizon jitter."

Use Case Recommendations

• Cinematography: Keep at 1.0. This is the professional standard.
• High-Speed Grid Mapping: Increase to 2.0 - 5.0. When flying a tight survey grid at 15 m/s, a higher jerk value is needed to ensure the drone can stop and turn fast enough at the end of each line.
• Small Rigid Racers (Auto-Mission): Set to 10.0. Smaller frames have very little inertia and can handle high jerk rates with ease.

Troubleshooting

• Scenario: Drone "bobs" or twitches when starting or ending a mission leg.
  • Diagnosis: WPNAV_JERK is too high, exciting a frame resonance.
  • Fix: Reduce to 1.0 or 0.5.

Waypoint Hit Radius (WPNAV_RADIUS)

Description

WPNAV_RADIUS defines the "bullseye" size for your autonomous missions. It tells the drone exactly how close it needs to get to a waypoint before it can move on to the next one.

• Small Radius (e.g. 50cm): The drone will be extremely precise. It will slow down almost to a hover to ensure it crosses the exact coordinate. This makes the mission very accurate but "jerky" as the drone stops at every point.
• Large Radius (e.g. 500cm): The drone will "fly past" the waypoints in a smooth, flowing curve. It doesn't need to reach the exact center, so it can maintain its speed. This is known as Corner Cutting.

Recommendation: For standard mapping, a radius of 200 (2 meters) is ideal. For precision delivery or drop-off, reduce to 50 - 100.

The Mathematics

The path planner constantly monitors the 2D distance ($d$) between the current EKF position and the waypoint coordinate:

$$ d = \sqrt{(X\_{target} - X\_{actual})^2 + (Y\_{target} - Y\_{actual})^2} $$

A waypoint transition is triggered when:
$$ d < \text{WPNAV\_RADIUS} $$

Spline Interaction: If you are using "Spline" waypoints, this parameter is less critical because the drone follows a pre-calculated curve. However, for standard "Waypoints," this parameter determines the smoothness of the turns.

The Engineer's View

This parameter is the _wp_radius_cm member in AC_WPNav.

It is used in AC_WPNav::check_wp_hit(). A critical engineering detail is that higher speeds require larger radii. If the drone is flying at 15 m/s, it may physically be unable to turn tight enough to stay within a 2-meter radius. In this case, the drone will circle the waypoint (Toilet Bowling) trying to get inside the radius.

// AC_WPNav.cpp
// Logic for waypoint transition based on _wp_radius_cm.

Tuning & Behavior

• Default Value: 200 cm (2 meters)
• Range: 10 - 1000 cm
• Effect of Increasing: Smoother mission flight. Higher average speed. Drone "rounds off" the corners of the path.
• Effect of Decreasing: More precise path tracking. Drone "stops and turns" at each waypoint.

Use Case Recommendations

• Aerial Mapping (Photogrammetry): Set to 200 - 300. You want smooth flight to avoid motion blur in the photos, and a 2-3 meter error is usually acceptable for the photo center.
• Precision Spraying (Agriculture): Decrease to 100. You need to ensure the chemicals are applied exactly to the edge of the field.
• Search and Rescue: Set to 500. Speed and coverage area are more important than hitting the exact center of a search grid.

Troubleshooting

• Scenario: Drone reaches a waypoint but then starts doing wide circles around it instead of going to the next one.
  • Diagnosis: WPNAV_RADIUS is too small for the current WPNAV_SPEED. The drone's turn radius is larger than the hit radius.
  • Fix: Increase WPNAV_RADIUS or reduce WPNAV_SPEED.

Waypoint Mission Rangefinder Usage (WPNAV_RFND_USE)

Description

WPNAV_RFND_USE is the master switch for Terrain Following in autonomous missions. It determines whether the drone's height is measured from where it started (Barometer) or from the surface directly beneath it (Rangefinder).

• Enabled (1): The drone uses its rangefinder (Lidar/Sonar) to maintain its height above the ground. If the drone flies over a hill, it will climb to maintain the requested altitude relative to the slope.
• Disabled (0): The drone uses the Barometer or GPS to maintain a fixed altitude relative to its takeoff point ("Home"). If it flies over a hill, it will stay at the same absolute height, potentially crashing into the terrain.

Pre-requisite: You must have a functioning rangefinder configured (RNGFND1_TYPE > 0) for this parameter to have any effect.

The Mathematics

This parameter toggles the Altitude Reference in the vertical control loop:

$$ Z\_{target} = \begin{cases} \text{Ground\_Level} + \text{Alt\_WP}, & \text{if } \text{RFND\_USE} = 1 \ \text{Home\_Level} + \text{Alt\_WP}, & \text{if } \text{RFND\_USE} = 0 \end{cases} $$

Where Alt_WP is the altitude specified in the mission file (MAVLink MISSION_ITEM).

The Engineer's View

This parameter is the _rangefinder_use member in AC_WPNav.

It is checked in AC_WPNav::update_z_controller(). When enabled, the code continuously queries the rangefinder for the current distance to ground. One critical safety feature is that ArduPilot will ignore this parameter if the rangefinder health is low. If the Lidar loses its signal (e.g., flying over water), the system will automatically fall back to Barometric altitude to prevent a crash.

Tuning & Behavior

• Default Value: 1 (Enabled)
• Range: 0 (Off) or 1 (On)
• Effect of Enabling: Drone follows the contours of the ground. Essential for low-altitude mapping and agriculture.
• Effect of Disabling: Drone stays at a constant barometric height. Safer for high-altitude flight where ground texture may be unreliable.

Use Case Recommendations

• Agricultural Spraying: Always Enable (1). You must maintain a precise distance from the crops regardless of the field's slope.
• Power Line Inspection: Always Enable (1). Ensures the drone tracks the vertical profile of the terrain accurately.
• High-Altitude Photography (>50m): Disable (0). Most hobbyist rangefinders are unreliable above 30-40 meters. Using the Barometer is safer at these heights.

Troubleshooting

• Scenario: Drone "bobs" up and down violently during a mission over tall grass.
  • Diagnosis: The rangefinder is getting inconsistent readings from the grass.
  • Fix: Disable WPNAV_RFND_USE or increase EK3_HGT_DELAY.

Waypoint Horizontal Speed (WPNAV_SPEED)

Description

WPNAV_SPEED sets the "Cruise Speed" for your autonomous missions.

• 500 (Default): 5 meters per second (11 mph). Good for stable surveying.
• 1000: 10 m/s (22 mph). Faster transit.

Tuning & Behavior

• Default Value: 500 cm/s.
• Recommendation: Set based on your drone's power and the requirements of your mission.

Waypoint Vertical Speed Down (WPNAV_SPEED_DN)

Description

WPNAV_SPEED_DN controls how fast the drone drops when moving between waypoints.

• 150 (Default): 1.5 meters per second.

Tuning & Behavior

• Default Value: 150 cm/s.
• Recommendation: Keep lower than WPNAV_SPEED_UP to prevent the drone from falling into its own propwash (vortex ring state).

Waypoint Vertical Speed Up (WPNAV_SPEED_UP)

Description

WPNAV_SPEED_UP controls how fast the drone climbs when moving between waypoints of different altitudes.

• 250 (Default): 2.5 meters per second.

Tuning & Behavior

• Default Value: 250 cm/s.
• Recommendation: Keep at or below 250 to avoid overwhelming the vertical controller.

Terrain Following Margin (WPNAV_TER_MARGIN)

Description

WPNAV_TER_MARGIN is the "safety cushion" for drones using a digital map to stay away from the ground.

ArduPilot can maintain its altitude by downloading a Terrain Database (SRTM data) which contains the elevation of the entire earth. However, this data is often low-resolution (typically 30-90 meters per pixel) and does not include objects like tall trees, power lines, or new buildings.

WPNAV_TER_MARGIN adds a fixed vertical offset to your mission altitude to ensure you clear these unknown obstacles.

• Low Value (e.g. 2m): Extremely risky. The drone will follow the ground map precisely, but even a small tree or a mistake in the map data will cause a crash.
• High Value (e.g. 20m): Very safe. The drone stays well above any potential unmapped obstacles.
• Default (10m): A robust setting for most cross-country autonomous missions.

The Mathematics

The target altitude ($Z\_{target}$) is calculated by summing the Terrain Elevation ($E$), the Mission Altitude ($A$), and the Margin ($M$):

$$ Z\_{target} = E\_{database} + A\_{mission} + \text{WPNAV\_TER\_MARGIN} $$

Example: If you set a mission altitude of 50 meters, and the map says the hill is 100 meters high, the drone will fly at an absolute height of 160 meters ($100 + 50 + 10$).

The Engineer's View

This parameter is the _terrain_margin member in AC_WPNav.

It is applied in the altitude calculation logic. One critical technical detail is that Terrain Margin is only used when the Rangefinder is NOT available or is out of range. If you have a Lidar sensor and it sees the ground, ArduPilot will prioritize the real sensor data and ignore the WPNAV_TER_MARGIN.

Tuning & Behavior

• Default Value: 10.0 m
• Range: 1.0 - 100.0 m
• Effect of Increasing: Safer autonomous missions. Drone stays higher above potential obstacles.
• Effect of Decreasing: Drone flies closer to the terrain. Better for low-level tactical or inspection flight.

Use Case Recommendations

• Long-Distance BVLOS: Increase to 20m. You cannot see the drone, so you must assume the map data might be old or inaccurate.
• Copter Mapping (Flat Area): Keep Default (10m).
• Precision Low-Level Flight: Decrease to 5m. Only do this if you have visually confirmed there are no unmapped obstacles in the path.

Troubleshooting

• Scenario: Drone "climbs" unexpectedly during a mission over a flat desert.
  • Diagnosis: The terrain database thinks the ground is higher than it actually is.
  • Fix: Reduce WPNAV_TER_MARGIN or switch to a high-accuracy custom terrain map.