Simple Avoidance (Stop & Slide)

Executive Summary

Simple Avoidance is the most basic form of collision prevention, used primarily in pilot-controlled modes (Loiter, AltHold, PosHold). It does not path-plan; it simply modifies the pilot's input to prevent the drone from touching a predefined boundary (fence or proximity sensor).

Theory & Concepts

1. The Physics of "Stop"

When AVOID_BEHAVE is set to Stop:

The controller projects the vehicle's stopping position based on current velocity and max deceleration (AVOID_ACCEL_MAX).
If the stopping point breaches the AVOID_MARGIN, the controller overwrites the pilot's input velocity to 0 in that direction.

2. The Physics of "Slide"

When AVOID_BEHAVE is set to Slide:

Instead of stopping, the velocity vector is "deflected" along the tangent of the obstacle boundary.
Feel: It feels like the drone is pressing against a glass wall. You can push it sideways along the wall, but not through it.

Codebase Investigation

1. The Stop Logic: `AC_Avoid::limit_velocity_2D()`

Located in libraries/AC_Avoidance/AC_Avoid.cpp.

It calculates the component of velocity towards the obstacle.
If that component exceeds the safe speed for the given distance, it is reduced.
```
const float max_speed = get_max_speed(kP, accel_cmss, limit_distance_cm, dt);
```
- get_max_speed uses a square-root controller ($\sqrt{2ax}$) to determine the maximum speed that allows stopping within limit_distance_cm.

2. The Margin Calculation

Input: _margin (User parameter, e.g., 2m).
Logic: The system treats the obstacle as being _margin meters closer than it actually is.
Breach: If the vehicle drifts inside the margin, adjust_velocity generates a Repulsive Vector to back the vehicle out.

Source Code Reference

Velocity Limiting: AC_Avoid::limit_velocity_2D
Stopping Distance: AC_Avoid::get_stopping_distance

Practical Guide: Tuning the Feel

Jerky Stops: If the drone brakes too hard at the fence, reduce AVOID_ACCEL_MAX.
Drifting Through: If the drone slides through the fence at high speed, increase AVOID_MARGIN. The loop latency might be too high for the speed.
Oscillation: If it bounces off the invisible wall, increase AVOID_BACKUP_DZ (Deadzone) to add hysteresis to the backing-up logic.

How To: Enable "Stop at Fence"

This is the most common use case: preventing a drone from flying out of a designated zone.

1. Define the Fence

In Mission Planner, go to Plan screen.
Select Polygon Fence.
Draw a boundary around your safe flight area.
Right-click -> GeoFence -> Upload.

2. Enable Fencing Logic

Set these parameters to tell ArduPilot to respect the boundary:

Parameter	Value	Description
FENCE_ENABLE	`1`	Enables the Geo-Fence subsystem.
FENCE_TYPE	`4`	Select "Polygon". (Add `2` for Circle, `1` for Altitude).
FENCE_ACTION	`1`	Typically "RTL" or "Brake" on breach. Avoidance happens before this triggers.

3. Enable Avoidance Logic

Now tell the controller to stop before hitting the fence:

Parameter	Value	Description
AVOID_ENABLE	`7`	Enable All (Fence + Proximity).
AVOID_BEHAVE	`1`	Set to Stop. (0 = Slide).
AVOID_MARGIN	`2.0`	Stop 2 meters before the line.

Test It: Fly slowly towards the boundary in Loiter mode. The drone should brake and refuse to fly further, like hitting an invisible wall.