Terrain Cache Size (TERRAIN_CACHE_SZ)

Description

TERRAIN_CACHE_SZ allocates memory for the terrain map.

The autopilot cannot hold the entire world's map in memory. Instead, it reads small "blocks" (tiles) from the SD card as needed. This parameter determines how many of these blocks can be kept in RAM at once for fast access.

• 0 (Default): Use the board-specific default (usually scaled to available RAM).
• Value: Number of blocks (each block is approx. 2KB).

Tuning & Behavior

• Default: 0.
• Recommendation: Leave at 0.
• Significance: If you fly very fast over varied terrain, a larger cache might prevent "Data Starvation" where the autopilot is waiting for the SD card to load the next hill.

Enable Terrain Following (TERRAIN_FOLLOW)

Description

TERRAIN_FOLLOW switches the autopilot's altitude reference from "Above Home" to "Above Ground Level (AGL)" for semi-autonomous modes.

When enabled, modes like CRUISE and FBWB (Fly-By-Wire B) will attempt to maintain a constant height above the terrain rather than a constant barometric altitude. This is essential for low-level flying in hilly environments.

• 0: Disabled. Altitude is relative to the home takeoff point.
• 1: Enabled. Altitude is relative to the terrain database or rangefinder reading.

Tuning & Behavior

• Default: 0.
• Safety: You MUST have valid terrain data (on SD card) or a long-range lidar for this to work safely. If the terrain data is missing, the plane may climb unexpectedly (failsafe) or fly into a hill.
• RTL: This also affects Return-to-Launch. The plane will climb over hills on its way home.

Terrain Look-Ahead Distance (TERRAIN_LOOKAHD)

Description

TERRAIN_LOOKAHD allows the drone to see a mountain coming and start climbing before it gets there.

Without look-ahead, the drone would only react to the ground directly beneath it. If it flew toward a steep cliff, it might not have enough time to climb over it. This parameter tells the navigation controller to scan the terrain map ahead of the current position. If it sees a hill coming, it will begin the climb early to ensure a safe and smooth clearance.

Tuning & Behavior

• Default: 2000 meters.
• Recommendation:
  • Fast Planes: Keep at 2000m or more. You need time to climb.
  • Slow Copters: You can reduce this to 500m or 1000m, as copters can climb vertically if needed.
• Note: The look-ahead never extends past the next waypoint.

Terrain Data Acceptance Margin (TERRAIN_MARGIN)

Description

TERRAIN_MARGIN is a compatibility setting for older terrain databases.

ArduPilot expects terrain grid points to be aligned perfectly to specific latitude/longitude intervals. If the GCS sends data that is slightly shifted (due to floating point rounding errors in older software), this margin allows the autopilot to accept it anyway.

Tuning & Behavior

• Default: 0.05 m (5 cm).
• Recommendation: Leave at default. Modern Mission Planner and MAVProxy versions do not require adjustment.

Terrain Reference Offset Maximum (TERRAIN_OFS_MAX)

Description

TERRAIN_OFS_MAX is a sanity check for your map data.

When you arm the drone on the ground, ArduPilot checks the terrain database for the current location. Often, the map says the ground is at 100m, but the GPS/Baro says 105m. ArduPilot assumes the drone is on the ground and calculates an "Offset" (e.g. -5m) to shift the map to match reality. This parameter limits how large that shift can be.

Tuning & Behavior

• Default: 30 meters.
• Scenario: If the map says you are at 100m elevation, but the GPS says 150m (a 50m error), and TERRAIN_OFS_MAX is 30, the system will reject the calibration because the map is likely wrong or the GPS glitch is too large.
• 0: Disables automatic terrain offset calibration.

Terrain System Options (TERRAIN_OPTIONS)

Description

TERRAIN_OPTIONS provides fine-grained control over how the terrain database is queried.

• Bit 0 (1): Disable Interpolation. By default, the system smooths out the steps between grid points. Setting this bit forces the system to return the raw grid height, which is faster but "blocky."

Tuning & Behavior

• Default: 0 (Interpolation enabled).
• Recommendation: Leave at 0 for smoother flight paths.

Terrain Grid Spacing (TERRAIN_SPACING)

Description

TERRAIN_SPACING defines the "Resolution" of the map used by the autopilot.

When the drone flies into a new area, it asks the Ground Control Station (GCS) for terrain height data. This parameter tells the GCS how dense that data should be.

• 100m (Default): A good balance. The drone requests the height of the ground every 100 meters. This matches the standard SRTM database resolution used by Mission Planner.
• 30m: High resolution. Useful for very detailed low-level flying, but uses more SD card space and telemetry bandwidth.

Tuning & Behavior

• Default: 100.
• Recommendation: Leave at 100. Setting it lower than your GCS's actual map data (e.g. asking for 10m spacing when the map is only 90m resolution) is wasteful and provides no extra accuracy.

TERRAIN_ENABLE: Terrain data enable

Description

Enable terrain data.

Values

• Default: 1

Description

This parameter enables the autopilot to download, store, and use digital elevation maps (DEM) for Terrain Following.

• Function: When enabled, the drone will request terrain data tiles from the Ground Control Station (Mission Planner or QGroundControl) or download them from the internet if the companion computer has access. These tiles are stored on the SD card.
• Usage: Essential for safe low-altitude flight over hills and mountains. Without this data, the drone assumes the world is flat at Home altitude (unless using a rangefinder).