Follow Vertical Acceleration Limit (FOLL_ACCEL_D)

Description

This parameter sets the maximum vertical acceleration the drone is allowed to use while tracking a target in Follow mode.

By limiting the acceleration, you ensure that the drone transitions smoothly between climbing and descending, preventing sudden throttle spikes that could waste battery or destabilize a camera gimbal.

The Mathematics

The input shaper constrains the second derivative of position ($Z$):

$$ |\frac{d^2Z}{dt^2}| \le FOLL\_ACCEL\_D $$

This acts as a "ceiling" on the throttle demand logic. Even if the target suddenly drops 10 meters, the drone will only accelerate downwards at this specified rate until it reaches its maximum descent speed.

The Engineer's View

In AP_Follow, this parameter is part of the kinematic shaping configuration passed to the position controller.

• 0: Disabled. The system uses the vehicle's standard vertical acceleration limits (e.g., PILOT_ACCEL_Z).
• Non-Zero: Overrides the default limits specifically for Follow mode. This allows you to have a very aggressive "Sport Mode" for manual flying but a gentle, cinematic behavior for Follow mode.

Tuning & Behavior

• Default Value: 0 (Disabled).
• Range: 0 to 50 $m/s^2$.
• Smooth Filming: Set to 1 or 2 $m/s^2$.
• Aggressive Tracking: Set to 5+ $m/s^2$ or leave at 0.

Follow Altitude Type (FOLL_ALT_TYPE)

Description

This parameter defines the "Vertical Reference Frame" used when calculating the target's position. It tells the drone whether it should try to match the target's absolute height above sea level or its relative height above the launch point.

This is critical for terrain following. If the target climbs a hill, you need to know if the drone should also climb (Relative) or stay at a fixed barometric altitude (Absolute).

The Mathematics

The parameter selects the altitude source mode:

• 0: Absolute (AMSL). The drone targets the raw GPS Mean Sea Level altitude reported by the lead vehicle.
  $$ Alt\_{target} = Alt\_{Lead\_AMSL} + Offset\_Z $$
• 1: Relative (Above Home). The drone targets an altitude relative to its own home position.
  $$ Alt\_{target} = (Alt\_{Lead\_AMSL} - Alt\_{Home}) + Offset\_Z $$

The Engineer's View

In AP_Follow::handle_global_position_int_message() (libraries/AP_Follow/AP_Follow.cpp):

1. The code receives a GLOBAL_POSITION_INT MAVLink message.
2. If _alt_type == 1 (Relative), it converts the packet's relative_alt field into an ABOVE_HOME frame location.
3. If _alt_type == 0 (Absolute), it uses the packet's raw alt (AMSL) field directly.

Tuning & Behavior

• Default Value: 1 (Relative).
• Rover/Boat: Usually set to 1. If the boat is at "0m" relative to the water, the drone will fly "0m + Offset" above the water.
• Aircraft: Set to 0 if you want the follower to stay at a specific barometric altitude regardless of where the leader goes (e.g., for formation flight at a safe ATC-cleared altitude).

Follow Max Distance (FOLL_DIST_MAX)

Description

FOLL_DIST_MAX is the "Leash" length.

If the target vehicle speeds away and the distance between your drone and the target exceeds this value, the autopilot will stop chasing and switch to a safe mode (usually Loiter). This prevents the drone from blindly flying over the horizon if it loses its connection to the target.

Follow Mode Enable (FOLL_ENABLE)

Description

FOLL_ENABLE activates the dedicated control logic for chasing a target.

When enabled, the drone can receive position data from another vehicle (Lead drone) or a GCS-enabled device (like a phone in your pocket) and automatically fly to maintain a specific distance and orientation relative to that target.

• 0: Disabled.
• 1: Enabled.

Tuning & Behavior

• Reboot Required: Yes.
• Requirement: You must also set the Target's MAVLink System ID in FOLL_SYSID.

Follow Vertical Jerk Limit (FOLL_JERK_D)

Description

This parameter limits the "Jerk" (rate of change of acceleration) for vertical movements in Follow mode. It is part of the kinematic input shaper, which smooths out the target's movements before they are passed to the flight controller.

A lower jerk limit makes the drone's altitude changes feel smoother and more "organic," reducing mechanical stress and camera shake. A higher limit allows the drone to react more violently to sudden altitude changes by the target.

The Mathematics

The input shaper limits the third derivative of position ($Z$):

$$ |\frac{d^3Z}{dt^3}| \le FOLL\_JERK\_D $$

This effectively puts a "ramp" on the acceleration command. Instead of instantly demanding 2G climb, the system ramps up to that acceleration over a period defined by this limit.

The Engineer's View

In AP_Follow, this parameter is passed to the AC_InputManager or similar kinematic shaping libraries used by the vehicle's position controller.

• 0: Disabled. The system uses the vehicle's default maximum jerk limits (e.g., PILOT_JERK).
• Non-Zero: Overrides the default jerk limit specifically for Follow mode operations.

Tuning & Behavior

• Default Value: 0 (Disabled/Use Vehicle Defaults).
• Filming: Set to a low value (e.g., 5 $m/s^2$/s) for ultra-smooth cinematic following.
• Racing/Tracking: Set higher or leave at 0 for maximum responsiveness.

Follow offsets (FOLL_OFS)

Description

This vector parameter defines the positional offset of the follower vehicle relative to the lead vehicle. It allows the follower to maintain a specific formation (e.g., flying 5 meters behind and 2 meters above the leader).

The Mathematics

The offsets are applied in the NED (North-East-Down) or Forward-Right-Down frame, depending on FOLL_OFS_TYPE.
$$ \vec{P}{target} = \vec{P}{lead} + \begin{bmatrix} \text{FOLL\_OFS\_X} \ \text{FOLL\_OFS\_Y} \ \text{FOLL\_OFS\_Z} \end{bmatrix} $$

The Engineer's View

Defined in libraries/AP_Follow/AP_Follow.cpp as a Vector3f parameter _offset. This creates three sub-parameters in the GCS: FOLL_OFS_X, FOLL_OFS_Y, and FOLL_OFS_Z.

• X: Forward/North offset.
• Y: Right/East offset.
• Z: Down offset (Positive = Below, Negative = Above).

Tuning & Behavior

• FOLL_OFS_X: +ve is ahead, -ve is behind.
• FOLL_OFS_Y: +ve is right, -ve is left.
• FOLL_OFS_Z: +ve is below, -ve is above.

Follow Offset Type (FOLL_OFS_TYPE)

Description

FOLL_OFS_TYPE determines how the drone calculates where to sit in relation to the target.

• 0: North-East-Down. The drone stays at a fixed compass offset (e.g., 5m North and 5m East). Even if the target turns, the drone stays on the North side.
• 1: Relative to Target. The drone stays at a fixed offset relative to the target's nose (e.g., 5m behind and 5m to the right). If the target turns, the drone "Orbits" around to stay in the same spot relative to the target's view. (Best for filming vehicles).

Follow options (FOLL_OPTIONS)

Description

This parameter allows the user to enable specialized behaviors for Follow mode via a bitmask. Currently, it primarily controls how camera gimbals interact with the target tracking system.

The Mathematics

The parameter is a bitmask ($B$):

• Bit 0 (Value 1): Mount Follows lead vehicle on mode enter.
  When this bit is set and the vehicle enters Follow mode, the autopilot will automatically command any connected gimbal (Mount) to point at the Lead Vehicle's calculated position.

The Engineer's View

In AP_Follow (and consumed by vehicle-specific code like mode_follow.cpp), this parameter maps to _options.

• Mount Tracking: If Bit 0 is set, the Follow library or the main vehicle code will set the Gimbal's Region of Interest (ROI) to the target's coordinates. This creates a "Cinematic Follow" effect where the drone chases the target while keeping it centered in the camera frame, regardless of the drone's actual orientation.

Tuning & Behavior

• Default Value: 0 (Disabled).
• Bit 0 (1): Enable this for filming applications. Note that this overrides manual gimbal control while in Follow mode.

Follow position error P gain (FOLL_POS_P)

Description

This parameter tunes the aggressiveness of the drone when chasing a moving target. It is the Proportional gain of the position controller used specifically in Follow mode.

If the drone falls behind the target, this gain determines how hard it accelerates to catch up.

• High P: The drone reacts instantly to target movement but may twitch or overshoot if the target stops suddenly.
• Low P: The drone reacts smoothly but may lag behind the target, effectively "rubber-banding" as the distance increases.

The Mathematics

The controller calculates the position error ($E\_{pos}$) between the drone and the target (plus offsets). The desired velocity adjustment is proportional to this error:

$$ V\_{correction} = FOLL\_POS\_P \times E\_{pos} $$

This velocity demand is then passed to the vehicle's standard velocity controller (which has its own PIDs).

The Engineer's View

In AP_Follow.cpp, this is defined as _p_pos.
The Follow library does not control the motors directly. Instead, it calculates a 3D target position and feeds it into the vehicle's position controller (e.g., AC_PosControl for Copters). This P-gain works "upstream" of the main flight controller PIDs, shaping the demand signal.

Tuning & Behavior

• Default Value: 0.1.
• Range: 0.01 to 1.0.
• Recommendation: Start with the default. If the drone lags too far behind a fast-moving target, increase by 0.05 increments.
• Overshoot: If the drone flies past the target when the target stops, decrease this value.

Follow Target System ID (FOLL_SYSID)

Description

FOLL_SYSID identifies who your drone is supposed to be chasing.

Every device on a MAVLink network (Drones, Laptops, Phones) has a unique ID number. By setting this parameter, you tell your drone to ignore other traffic and only follow the position updates coming from the specific ID entered here.

• Default: 0 (Follow the first target detected).
• Recommendation: Set this explicitly to your phone or lead drone's ID for safety and reliability.

Follow Mode Data Timeout (FOLL_TIMEOUT)

Description

This parameter is intended to set the failsafe timeout for Follow Mode. If the drone stops receiving position updates from the target vehicle for this duration, it will stop tracking and potentially switch flight modes or loiter in place.

CRITICAL NOTE: As of the current codebase analysis, this parameter does not exist in the AP_Follow parameter table (var_info). The timeout is currently hardcoded to 3000ms (3 seconds) via the macro AP_FOLLOW_TIMEOUT_MS.

The Mathematics

The logic checks the age of the last valid packet:

$$ T\_{now} - T\_{last\_update} > 3000ms $$

If this condition is met, have_target() returns false, causing the vehicle to stop updating its target position.

The Engineer's View

In AP_Follow.cpp, line 29:

#define AP_FOLLOW_TIMEOUT_MS    3000    // position estimate timeout after 1 second (comment says 1s, code is 3s)

The parameter FOLL_TIMEOUT appears in some documentation scaffolds but is not exposed in the var_info struct for user configuration. It is effectively a compile-time constant.

Tuning & Behavior

• Default Value: 3000 (Hardcoded).
• Behavior: If the MAVLink stream from the lead vehicle is interrupted (e.g., telemetry loss), the follower will continue on its last known trajectory for 3 seconds before giving up.
• Correction: Do not attempt to change FOLL_TIMEOUT in your Ground Control Station; it will likely not be found or will have no effect.

Follow Yaw Behavior (FOLL_YAW_BEHAVE)

Description

FOLL_YAW_BEHAVE defines what the drone points its "Face" (camera) at while it is chasing a target.

• 0: None. The drone keeps its current heading and does not automatically rotate.
• 1: Face Target (Default). The drone always turns to point its nose directly at the person or object it is following. Good for filming yourself.
• 2: Face Next Waypoint.
• 3: Face Direction of Travel. The drone points its nose where it is going, like a real airplane.