Avoidance Max Acceleration (AVOID_ACCEL_MAX)

Description

AVOID_ACCEL_MAX limits how hard the drone brakes when it sees a wall.

If a proximity sensor detects an object within the AVOID_DIST_MAX limit, the autopilot commands the drone to stop. This parameter ensures the drone doesn't pitch back so violently that it crashes or destabilizes the payload.

Tuning & Behavior

• Default Value: 3.0 $m/s^2$.
• Recommendation: Set to 1.0 or 2.0 for smoother braking on large, heavy cinema drones. Keep at 3.0 for smaller, agile quads.

Avoidance Minimum Altitude (AVOID_ALT_MIN)

Description

AVOID_ALT_MIN prevents the drone from freaking out near the ground.

Proximity sensors (like 360 Lidar) often detect the ground as an "obstacle" when landing or taking off. If avoidance stays active, the drone might refuse to land because it thinks the floor is a wall. This parameter sets a floor altitude where avoidance is turned off.

• Default Value: 0 (Disabled).
• Recommendation: Set to 1.0 or 2.0 meters.

The Engineer's View

Used in AC_Avoid::adjust_velocity. If current_alt < alt_min, the velocity modification logic is bypassed.

Tuning & Behavior

• Safety: Always set this if you have downward-angled sensors or if you fly in tall grass.

Avoidance Max Lean Angle (AVOID_ANGLE_MAX)

Description

AVOID_ANGLE_MAX limits how aggressively the drone can tilt away from a threat.

• 1000 (Default): 10 degrees. Gentle avoidance.
• 3000: 30 degrees. Aggressive dodge.

Tuning & Behavior

• Default Value: 1000 (10°).
• Recommendation: Keep low (10-15°) to ensure smooth video and prevent the drone from over-reacting to sensor noise.

Avoidance Backup Deadzone (AVOID_BACKUP_DZ)

Description

AVOID_BACKUP_DZ prevents the drone from "jittering" back and forth.

If the drone is exactly at the AVOID_DIST_MAX limit (e.g. 2.0m from a wall), sensor noise might report 1.99m then 2.01m. Without a deadzone, the drone would twitch forward and backward. This parameter adds a buffer.

Tuning & Behavior

• Default Value: 0.1 m.
• Recommendation: Leave at 0.1 or increase to 0.2 if your Lidar is noisy.

Avoidance Backup Speed (AVOID_BACKUP_SPD)

Description

AVOID_BACKUP_SPD controls how fast the drone retreats.

If an obstacle moves towards the drone (or the drone drifts into it), the autopilot can actively fly backwards to maintain the AVOID_DIST_MAX clearance.

Tuning & Behavior

• Default Value: 0.75 m/s.
• Recommendation: Keep low (0.5 - 1.0 m/s). You don't want the drone to bolt backwards into another obstacle that its rear sensors haven't seen yet.

Avoidance Backup Vertical Speed (AVOID_BACKZ_SPD)

Description

AVOID_BACKZ_SPD is the same as AVOID_BACKUP_SPD but for up/down movement.

If you fly too close to the ceiling (with an upward facing Lidar), this controls how fast the drone descends to regain clearance.

Tuning & Behavior

• Default Value: 0.75 m/s.
• Recommendation: Keep conservative.

Avoidance behaviour (AVOID_BEHAVE)

Description

AVOID_BEHAVE determines the drone's "Personality" when it sees an object like a wall or a tree.

• 0: Slide (Default for Copter). The drone will try to "slip" past the obstacle. If you fly straight at a corner, it will veer slightly to one side to maintain speed while keeping a safe distance (AVOID_MARGIN).
• 1: Stop (Default for Rover). The drone will simply come to a full stop in front of the obstacle. It will not try to go around it.

The Mathematics

In Slide (0) mode, the velocity vector $\vec{V}$ is projected onto the tangent of the obstacle boundary:
$$ \vec{V}\_{safe} = \vec{V} - (\vec{V} \cdot \hat{n}) \hat{n} $$
where $\hat{n}$ is the normal vector pointing from the obstacle.

In Stop (1) mode, the component of velocity toward the obstacle is simply zeroed.

Tuning & Behavior

• Default Value: 0 (Slide)
• Recommendation:
  • Multicopters: Use 0 (Slide). It feels much more natural and prevents the drone from "stuttering" when flying near complex structures.
  • Rovers: Use 1 (Stop) to prevent the vehicle from accidentally sliding into a ditch while trying to "veer" around a rock.

Avoidance Max Distance (AVOID_DIST_MAX)

Description

AVOID_DIST_MAX defines the "Reaction Zone."

When an object is further away than this, the drone ignores it. Once it enters this range, the drone starts calculating if it needs to brake. This is effectively the range of your sensor that you trust for avoidance logic.

Tuning & Behavior

• Default Value: 5 meters.
• Recommendation: Set to 80% of your Lidar's reliable range.
  • TFmini: 4m.
  • LIDAR-Lite: 10m.
  • Lightware SF40: 20m.

Avoidance control enable/disable (AVOID_ENABLE)

Description

AVOID_ENABLE activates the logic that prevents the drone from hitting things. While FENCE prevents the drone from leaving a large area, AVOID handles "Local Obstacles" detected by sensors (like Lidars) or boundaries (like the Fence).

Key Bits:

• Bit 0 (1): Use Fence. The drone will treat the geofence as a solid wall it cannot fly into.
• Bit 1 (2): Use Proximity Sensor. Enables avoidance using 360-degree Lidars or rangefinders.
• Bit 2 (4): Use Beacon Fence. Treat beacon-defined boundaries as obstacles.

The Engineer's View

Used in AC_Avoid::adjust_velocity().
When enabled, the avoidance library intercepts the pilot's velocity commands and "pushes back" if they lead toward an obstacle. It effectively creates a virtual "Repulsive Field" around the drone.

Tuning & Behavior

• Default Value: 3 (Use Fence + Proximity) on most systems.
• Recommendation: Keep at 3 if you have any avoidance hardware installed.
• Safety: This logic is active in Loiter, Circle, and Auto modes. In Stabilize or Acro, the drone will NOT automatically stop for obstacles.

Avoidance distance margin (AVOID_MARGIN)

Description

AVOID_MARGIN is the "Social Distancing" rule for your drone. It defines how close the drone is allowed to get to a wall or obstacle before the avoidance logic kicks in.

• 2.0 (Default): The drone will try to stay at least 2 meters away from everything.

The Mathematics

The desired velocity is scaled by the distance to the obstacle $d$ using a square-root deceleration curve:
$$ v\_{max} = \sqrt{2 \cdot \text{AVOID\_ACCEL\_MAX} \cdot (d - \text{AVOID\_MARGIN})} $$

If $d \leq \text{AVOID\_MARGIN}$, $v\_{max} = 0$ (The drone stops).

Tuning & Behavior

• Default Value: 2.0 meters
• Recommendation:
  • Indoors: Decrease to 0.5m or 1.0m to allow flying through doorways.
  • Outdoors: Keep at 2.0m. This provides enough reaction time for the Lidar to see small objects like branches.
• Latency: If your sensor has high latency (e.g., a slow spinning Lidar), you must increase this margin.