Terrain Following (in Auto, Guided, etc)¶
Copter supports “terrain following” in nearly all autonomous modes AUTO, Guided, RTL and Land. This feature allows the vehicle to climb or descend to maintain a specified distance above the terrain using either a downward facing Lidar or Sonar or from SRTM data (aka terrain altitude data) provided by the ground station using a mapping service such as Google maps or stored on the autopilot’s SD card in the “Terrain” subdirectory. Details of how the SRTM data is used and stored can be found on the plane terrain following page
See Understanding Altitude in ArduPilot for altitude definitions.
Note
Loiter, PosHold and AltHold modes also support low altitude terrain following, called Surface Tracking. Please refer to the Surface Tracking wiki page.
Setting up a Mission to use Terrain data¶
If relying on a downward facing LIDAR ensure it is setup as described here
If using GCS provided terrain data set the TERRAIN_ENABLE parameter to 1
Using a recent version of Mission Planner (or other GCS that supports terrain following) on the Flight Plan screen, set the altitude type to “Terrain”. Once set all mission commands that include an “Alt” fields will be interpreted as altitudes-above-terrain.
Upload the mission to the vehicle and execute the mission as you normally would in AUTO
Warning
Do not set the EK3_SRC1_POSZ to Rangefinder. This parameter should be left at the default.
Do not set EK3_RNG_USE_HGT parameter. This parameter should be left at “-1”.
Sources of Terrain Data¶
The ground station is normally responsible for providing the raw terrain data which is sent to the aircraft via MAVLink. Right now only Mission Planner and MAVProxy support the required TERRAIN_DATA and TERRAIN_REQUEST MAVLink messages needed for terrain following download support. If you are using a different ground station , in order to download terrain data you will need to connect using one of those two ground stations in order to allow ArduPilot to load terrain data onto your board on the ground or in flight. Once it is loaded, it is saved permanently on the microSD card.
Both MissionPlanner and MAVProxy support the global SRTM database for terrain data. The ArduPilot SRTM server used by MAVProxy and Mission Planner has 100m grid spacing. Unless the ground control station uses a server with closer spacing, setting the TERRAIN_SPACING parameter lower than 100m provides no better resolution, and only consumes more space on the SD card.
Terrain Data is downloaded any time you save or connect with a loaded mission with these ground stations, or, if flying, the autopilot will request data if its flying into an area not already downloaded. Assuming the ground station can provide it. Usually an internet connection is required by the ground station.
Alternatively, you can download a set of terrain data tiles for any anticipated flight area using this web utility.
It will create tiles for the specified radius around a geographic location. Then you can download them, unzip and write in the APM/TERRAIN folder of the SD card.
You can also download .zip files for entire continents, or individual tiles from here. Note that ArduPilot 4.0.x and 4.1.x have different tilesets. Use the “continents”/”tiles” folders for ArduPilot 4.0.x, or use the “continentsapm41”/”tilesapm41” folders for ArduPilot 4.1.x.
Beginning with the beta version released on 20th September 2024 you can create terrain dat files from Mission Planner and upload them to the SD card.
Go to FlightPlanner.
Select area with ALT+MouseCLICK and drag
Open context menu and select Make Terrain DAT
if no area is selected the actual displayed area is used.
If you loaded Digital Elevation Model files into Mission Planner, then the generated terrain file will use them as source. You can specify the spacing between 5 and 100 meters. (Smaller spacing is not possible due to a bug in Ardupilot code, which does not allow files larger than 2Gbyte)
A grid spacing of 100 meters is adequate for most uses, especially for fast-flying vehicles. Using a smaller grid spacing often results in unnecessary SD card storage consumption. However, in specific cases where precise terrain following is required—such as when spraying with a copter over uneven terrain—a smaller grid spacing can be beneficial. Don’t forget to match the terrain spacing parameter with the grid size you generated and uploaded.
Terrain data files are always created as one file per one-by-one degree area, the file size depends on the spacing.
Warning
A long standing bug in the downloaded terrain data files, which occasionally caused terrain data to be missing, even though supposedly downloaded, was fixed in Plane 4.0.6, Copter 4.0.4, and Rover 4.1. It will automatically be re-downloaded when connected to a compatible GCS. However, if you are relying on SD terrain data for an area and don’t plan on being connected to a GCS when flying over it, or its not part of a mission, you should download the area data using the utility above, or from the linked tiles data repository and place on your SD card in the Terrain directory.
Warning
ArduPilot 4.0.x and 4.1.x use different terrain tilesets. When upgrading from 4.0.x to 4.1.x, any tiles on the SD card will need to be re-downloaded. This will happen automatically when your GCS is connected to the Internet for areas covered by loaded missions and/or home location. Otherwise, you may set the TERRAIN_MARGIN to 50 to continue using the old tileset.
Using Terrain Altitude during RTL and Land¶
Set the TERRAIN_FOLLOW parameter to 1 to enable using terrain data in RTL and Land flight modes. Also set RTL_ALT_TYPE = 1. If set the vehicle will interpret the RTL_ALT as an altitude-above-terrain instead of above home altitude, meaning it will generally climb over hills on its return path to home. Similarly Land will slow to the LAND_SPEED (normally 50cm/s) when it is 10m above the terrain (instead of 10m above home). Currently setting this parameter is not recommended because of the edge case mentioned below involving the somewhat unlikely situation in which the vehicle is unable to retrieve terrain data during the RTL. In these cases the RTL_ALT will be interpreted as an alt-above home.
In addition, if WPNAV_RFND_USE is also set to 1, the rangefinder will be used instead of the terrain database during RTL. Of course the RTL_ALT must be within the rangefinder’s operating range and it must be healthy.
Failsafe in case of no Terrain data¶
If the vehicle is executing a mission command that requires terrain data but it is unable to retrieve terrain data for two seconds (normally because the range finder fails, goes out of range or the Ground Station is unable to provide terrain data) the vehicle will switch to RTL mode (if it is flying) or disarm (if it is landed).
Note that because it does not immediately have access to terrain data in this situation it will perform a normal RTL interpreting the RTL_ALT as an altitude-above-home regardless of whether TERRAIN_FOLLOW has been set to “1” or not.
One common problem reported by users is the vehicle immediately disarms when the user switches to AUTO mode to start a mission while the vehicle is on the ground. The cause is the altitude reported by the range finder (which can be checked from the MP’s Flight Data screen’s Status tab’s sonar_range field) is shorter than the RNGFNDx_MIN_CM (for example RNGFND1_MIN_CM)parameter which means the range finder reports “unhealthy” when on the ground. The solution is to reduce the RNGFNDx_MIN_CM value (to perhaps “5”).
Terrain Spacing and Accuracy¶
The TERRAIN_SPACING parameter controls the size of the grid used when requesting terrain altitude from the Ground Station (it is not used if using a Lidar). This is 100m by default but reducing to 30 may provide better accuracy at the expense of more telemetry traffic between the GCS and autopilot, and 9x more file storage space on the SD card, but only if the ground station uses a server with that resolution. MavProxy and Mission Planner currently do not. Also, if the vehicle is moving very fast, the autopilot may not be able to retrieve and cache the data quickly enough for the increased resolution to be actually used. It is therefore recommended that you use a TERRAIN_SPACING of 100 meters.
If the ground station does not have terrain data available at the resolution requested by the aircraft then the ground station will interpolate as necessary to provide the requested grid size.
Terrain Accuracy¶
The accuracy of the SRTM database varies over the surface of the earth. Typical accuracy is around 10m but one developer noticed an inaccuracy of 35m at the peak of a ski hill. This makes terrain following suitable for aircraft that are flying at altitudes of 60 meters or more. For very accurate terrain following at lower altitudes it is recommended to use a downward facing Lidar or Sonar.
Warning¶
When planning missions containing commands with different altitudes-above-terrain keep in mind that the vehicle’s altitude-above-terrain will gradually change between the waypoints. I.e. it will not immediately climb or descend to the new target altitude-above-terrain as it starts towards the next waypoint.
In practice it is best to set the initial take-off command’s altitude high enough to clear obstacles.
