Error414/feature/inav terrain

[error414]

Terrain AGL

Terrain is a system that can show AGL (Above Ground Level) in the "distance" OSD element. It loads pre-generated data from an SD card and uses GPS data and barometric altitude for AGL calculation.

Features

• Shows AGL in the "distance" OSD element
• Can run alongside a rangefinder — rangefinder data is used first, terrain AGL is used as fallback when the rangefinder is out of range
• Can run with blackbox, but terrain needs approximately 150–250ms to load data from cache, so there may be short gaps in the blackbox log

Limitations

• Works only on H7 and F4 boards with an SD card slot
• Works only with SRTM1 resolution (30m). SRTM3 (90m) is not supported, but can be added via settings
• This feature is marked as EXPERIMENTAL in the documentation

Technical details

Terrain uses two tasks: an IO task and a GPS task.

Task	Frequency	Duration
GPS task	5Hz	1–2µs
IO task	50Hz	~40µs

The GPS task reads GPS data and creates requests for the IO task. The IO task reads requests from cache and loads grid data into cache.

The two-task design is needed because AGL data must already be loaded in cache by the time it is requested. In some conditions, AGL data requests should stop, but the IO task must keep running to close files and directories, free memory, and release the blackbox lock.

The IO task needs approximately 10 cycles to load data from the SD card. Task frequency can be adjusted to reduce gaps in the blackbox log.

Board	Cache size
F4	5 grids
H7	8 grids

Protection

When arming, the system checks whether the SD card can be read. If the read fails due to a faulty SD card or missing grid data, the terrain system is disabled for the entire flight. This prevents the first SD card read from happening mid-flight.

Testing

I tested it for few months on two planes
Hewing T1, MatekH743Wlite (blackbox on)
Hewing T2, MatekH743Wlite + dedicated rangerfinder NRA15 (blackbox on)

other testers
Hewing T1, SpeedyBeeF4Wing (blackbox on)
Beluga, SpeedyBeeF4Wing

For testers

Documentation:
https://github.com/error414/inav/blob/4fb0fdb9e28d899f03293d34b60907cadd1dbd2b/docs/Terrain.md

BTW: merge request is agains maintenance-9.x because maintenance-10.x is not up to date. I can rebase it to maintenance-10.x.

[github-actions]

Test firmware build ready — commit 4fb0fdb

Download firmware for PR #11438

227 targets built. Find your board's .hex file by name on that page (e.g. MATEKF405SE.hex). Files are individually downloadable — no GitHub login required.

Development build for testing only. Use Full Chip Erase when flashing.