Terrain following added to APM:Plane

3689591584?profile=originalIn preparation for the upcoming APM:Plane 3.1.0 release I thought it would be useful to showcase some of the new features that have been added.

The biggest new feature in this release is automatic terrain following. That is something I have wanted to add for a long time, and it is now finally done, prompted by the need for better terrain following for the upcoming Outback Challenge 2014 competition.

How it works

Terrain following works by maintaining a terrain database on the microSD card on the autopilot which gives the terrain height in meters above sea level for a grid of geographic locations. On the Pixhawk this database is stored in the APM\TERRAIN directory on the microSD card. Unfortunately code side limitations and the lack of a microSD card mean terrain following is not available for the APM1 or APM2.

The terrain database is populated automatically by the autopilot requesting terrain data from the ground station over a MAVLink telemetry link. This can happen either during flight planning when the autopilot is connected over USB, or during flight when connected over a radio link. Once the terrain data is sent from the GCS to the autopilot it is stored on the microSD card so that it is available even when the GCS is not connected. This makes it possible for the autopilot to use terrain data to perform a terrain following RTL (Return To Launch) even when it is not able to talk to the ground station.

During flight the ardupilot code automatically reads in the needed terrain data from the microSD card into memory as the aircraft approaches a new area. It maintains an area of about 7km by 8km in memory if the default terrain grid spacing is used.

In addition to any terrain data for the immediate vicinity of the aircraft, ardupilot also asks the ground station for terrain data for any mission waypoints which are loaded, and for any rally points which are loaded. This ensures that terrain data is available on the microSD card for a whole mission even if the GCS becomes unavailable.

Terrain Following Flight Modes

In APM:Plane terrain following is available in the following flight modes:

  • RTL – Return to launch
  • LOITER – circle a point
  • CRUISE – long distance cruising
  • FBWB – speed/height maintenance
  • GUIDED – “fly to” waypoints
  • AUTO – fully autonomous missions

Use of terrain following in RTL, LOITER, CRUISE, FBWB and GUIDED modes is controlled by the TERRAIN_FOLLOW parameter. That parameter defaults to off, so no terrain following will be used in those modes by default. Set TERRAIN_FOLLOW to 1 to enable terrain following in those modes.

Use of terrain following in AUTO missions is controlled on a waypoint by waypoint basis using the reference frame of the waypoint. Normal (non terrain following) waypoints have a “Relative” reference frame, and altitudes are specified relative to the home location. Terrain following waypoints have a “Terrain” reference frame, and altitudes are relative to the ground level given in the terrain database.

Terrain Following in CRUISE mode

CRUISE mode is a flight mode which is designed for long distance flying, especially for things like FPV. When you enable terrain following with the TERRAIN_FOLLOW=1 parameter CRUISE mode will hold an altitude above the terrain rather than a barometric altitude. This allows easier flying at a set AGL altitude which makes terrain avoidance easier, and also makes it easier to stay within regulatory altitude limits.

Terrain Following in RTL mode

When you engage RTL (either as a flight mode or as a failsafe) the plane flies back to either the home location or the closest rally point. If you have TERRAIN_FOLLOW=1 then the plane will follow the contours of the terrain on the way to the RTL location, which makes RTL much safer in hilly areas.

Uses of Terrain Following

Terrain following is very useful when flying ardupilot in areas where the terrain may vary significantly. Key uses are:

  • Safe RTL. Being able to come over a hill rather than trying to fly through it when you enter RTL in a hilly area is very useful!
  • Aerial Photography. It is useful to be able to maintain a constant altitude over the ground when taking a sequence of aerial photos
  • FPV flying. When flying FPV in CRUISE mode it is useful to maintain constant height above the ground so you can spend more time enjoying the scenery and less time avoiding hills

Sources of terrain data

The ground station is responsible for providing the raw terrain data which is sent to the aircraft via MAVLink. Right now only MissionPlanner (beta version as of 6th August 2014) and MAVProxy support the required TERRAIN_DATA and TERRAIN_REQUEST messages needed for terrain following support. If you are using a different ground station then to load terrain data you will need to connect using one of the two supported ground stations to allow ardupilot to load terrain data onto your board. It typically takes around 2 minutes to load all the terrain data for a mission. Once it is loaded it is saved permanently on the microSD card.

Both MissionPlanner and MAVProxy support the global SRTM database for terrain data. That database has a global grid spacing of 3 arc-seconds (around 100 meters), but has a smaller grid spacing in some parts of the world (around 30 meters in the US). Support for other terrain databases can be added by extending the ground station code without changes to the ardupilot code.

Terrain Spacing

The ardupilot terrain code has a user settable parameter called TERRAIN_SPACING which controls the grid spacing which is used for requests for terrain data from the aircraft to the ground station. The default TERRAIN_SPACING is 100 meters, but users may set a different grid spacing for specialist applications. When ardupilot uses the terrain data it interpolates between grid points.

The amount of terrain data kept in memory is directly related to the grid spacing. If you decrease the TERRAIN_SPACING by a factor of 2 then the amount of terrain area kept in memory is reduced by a factor of 4. It is recommended that you use a TERRAIN_SPACING of at least 30 meters to prevent the aircraft running off the side of a grid in flight and not having data available.

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 10 to 20 meters, although some areas are worse. This makes terrain following suitable for aircraft that are flying at altitudes of 60 meters or more. Using terrain data for low flights is not recommended.

Setting up for terrain following

To setup your fixed wing aircraft for terrain following follow these steps

  • make sure you have APM:Plane 3.1.0 or later loaded
  • make sure you have the latest MissionPlanner installed (latest beta version as of August 2014)
  • connect to your vehicle over USB when you have GPS lock
  • check the FlightData->Status page in MissionPlanner and look for the terrain status data:


When the autopilot has finished loading terrain data you should see “ter_pend” goes to zero and the current terrain altitude in meters showing up in “ter_alt”. The “ter_pend” value is the number of terrain blocks that the autopilot is waiting to load from the ground station.

Terrain Lookahead

The terrain following code “looks ahead” of the current position along the flight path to try to ensure that the aircraft climbs soon enough to avoid upcoming terrain. The amount of lookahead is controlled by the TERRAIN_LOOKAHD parameter, which defaults to 2000 meters. The lookahead is also limited by the distance to the next waypoint in AUTO mode, so you need to ensure that you don’t have any legs of your mission which include climb rates your aircraft cannot achieve.

The climb rate used in the terrain look ahead is based on the TECS_MAX_CLIMB parameter, combined with your current ground speed.

Give it a try!

If you like the sound of terrain following then please give it a try! I've just released a 3.1.0-beta1 release that you can try now. Please let me know how it goes!

E-mail me when people leave their comments –

You need to be a member of diydrones to add comments!

Join diydrones


  • I'm trying to find out how to change the source of the terrain data.  I see it hinted that one can, but I haven't been able to find out how yet.  It sounds like it needs to be changed in the code of Mission Planner, or maybe it can be pre-loaded onto the SD card?

  • +1 this would be wonderful. The MinimOSD-Extra is on github now, but development has died out. Hopefully people like yourself can contribute to keep the project moving along. There is no space left on the board, so to add new features we either need different versions, or better, a Config Tool that compiles custom firmware according to the options selected. OpenTx does it this way.
    Anyway, sorry to ramble, I'm just excited to see someone making such useful improvements to the neglected OSD.
    I have several github issues open for MP to integrate Terrain visualization, the OSD would be fantastic.
  • I would like to show the altitude above terrain in my minimosd for fixed wing plane. The terrain information should be a part of the Extra3 mavlink data stream if I understand it correctly. I get all relevant data in the APM Planner but I didn’t get TERRAIN_REPORT message (#136) in minimiosd even if some of messages from extra3 are there. The question is: do I need request this report for every new lat/lon by sending mavlink message from minimosd to pixhawk? (TERRAIN_CHECK #135). Do this APM planner? Actually, I have tried this but without any success. So, I need to ensure it is the correct way.
    Thanks for any thoughts and ideas.

  • If I read this right, I (or autoWP) can set waypoints down low on either side of a hill and arduplane _should_ miss the hill. Is that correct? If so, how do you specify by how much to miss the top of the hill (for trees / errors)?

  • Is there a way to download and process terrain data for a region and then manually add it to the SD card on the Pixhawk? We are using our drone in a remote area where the drone and GCS cannot connect to the internet, but we can manually carry data to the field from the town where there is internet.

  • ICYMI, there's now 30m SRTM data for Africa

  • We will be at a top of mountain, the tracker will be able to see the plane all the time and the line of sight (LOS) will be maximum 20km. We have a long distance radio for that. 

    We will draw a mission of hexagon as a path for 100km, there are few mountains and valleys, so I want to make sure the elevation profile can work more than 50km. 

    I have been told that the limitation is done by google earth, but we found a limitation in the mission planner source code which is 50km. 

  • You might want to rethink your use of the term LOS... either that or your vision is a lot better than mine!

  • HI Gary,

    The maximum LOS will be 20km, but my mission plan distance will be around 80km within 20km of LOS. 

  • Moderator

    A reliable radio link that would operate at low level at 100km, if you are say searching for somebody would cost a fortune. In fact due to the curve of the earth I am not even sure how high you have to be at 100km to be heard. All those videos of folks miles out always have them at a silly height. A height where a camera could not pick out a person. I am derailing this thread, perhaps you should start one with you exact requirements Elios. One that details how much you hope to spend. 

This reply was deleted.