Altitude calculated from terrain data

[error414]

User description

Terrain ASL from SD Card

Description

Loads ASL (Above Sea Level) values from a file stored on an SD card.
This feature is supported only on MATEKH743 and is recommended to be used only on flight controllers that access the SD card via SDIO.

Terrain files can be generated at:
https://terrain.ardupilot.org/

Currently, INAV supports only SRTM1 (30 m spacing).

The terrain file must be copied to the root of the SD card. If SD seems full, delete FREESPACE file from root of SDCARD
This limitation will be addressed later and is not critical at the moment.

---

Technical Notes

1. Blackbox interaction

When the terrain feature is enabled, blackbox is disabled.

All SD card access is handled in a single function using a state machine. All asyncfatfs handlers are processed correctly, which allows implementing proper locking.

Blackbox uses a more complex state machine and accesses the SD card from multiple locations. Many asyncfatfs handlers are not handled correctly or are missing.
Running blackbox and terrain simultaneously would require refactoring (rewriting) the blackbox implementation.

---

2. SD card failure handling

Any SD card failure disables the terrain feature.

This behavior protects the UAV and prevents infinite loops in asyncfatfs. If an invalid state of the terrain state machine is detected, the entire subsystem is disabled.

---

3. File open retry limit

If the terrain file cannot be opened three times, it is marked as invalid and loading is stopped.

---

Testing

Outdoor testing was successful, especially regarding precision.

Maximum deviation was approximately ±5 meters, which is more than sufficient for this use case.

https://www.youtube.com/watch?v=BHLAbzi2vbY

---

PR Type

New Feature

---

Description

• Implements terrain altitude feature using SD card data

• Integrates terrain as virtual rangefinder device

• Loads SRTM1 terrain data with grid caching system

• Disables blackbox when terrain feature is active on SDCARD

• Adds terrain support exclusively to MATEKH743 target

---

Diagram Walkthrough

flowchart LR
  SD["SD Card<br/>SRTM1 Data"]
  IO["Terrain I/O<br/>State Machine"]
  CACHE["Grid Cache<br/>LRU Management"]
  CALC["Height Calculation<br/>Interpolation"]
  RF["Virtual Rangefinder<br/>Device"]
  NAV["Navigation<br/>System"]
  
  SD -->|Load Grid| IO
  IO -->|Store Block| CACHE
  CACHE -->|Retrieve Grid| CALC
  CALC -->|Distance cm| RF
  RF -->|Altitude Data| NAV

Loading

File Walkthrough

	Relevant files
New feature	8 files terrain.c Core terrain altitude calculation and rangefinder integration +170/-0  terrain.h Terrain data structures and grid definitions                          +137/-0  terrain_io.c SD card file I/O state machine for terrain data                    +296/-0  terrain_io.h Terrain I/O state machine and file handling definitions    +76/-0    terrain_utils.c Grid cache management and location calculations                    +233/-0  terrain_utils.h Grid utility function declarations                                              +42/-0    terrain_location.c GPS location offset and distance calculations                        +91/-0    terrain_location.h Location utility function and constant definitions              +44/-0
Enhancement	4 files rangefinder.c Add terrain rangefinder type detection and initialization +10/-2    rangefinder.h Add RANGEFINDER_TERRAIN enum value                                              +1/-0      rangefinder.h Export terrain virtual rangefinder vtable                                +1/-0      fc_init.c Initialize SD card before blackbox when terrain enabled    +13/-8
Bug fix	1 files blackbox.c Prevent blackbox and terrain simultaneous SD card usage    +5/-1
Configuration changes	3 files target.h Enable terrain feature for MATEKH743 with SDIO                      +6/-1      settings.yaml Add TERRAIN option to rangefinder hardware settings            +1/-1      CMakeLists.txt Add terrain source files to build system                                  +9/-0
Tests	2 files terrain_unittest.cc Unit tests for terrain grid calculations                                  +86/-0    CMakeLists.txt Configure terrain unit test build dependencies                      +3/-0

---

[github-actions]

Branch Targeting Suggestion

You've targeted the master branch with this PR. Please consider if a version branch might be more appropriate:

• maintenance-9.x - If your change is backward-compatible and won't create compatibility issues between INAV firmware and Configurator 9.x versions. This will allow your PR to be included in the next 9.x release.

• maintenance-10.x - If your change introduces compatibility requirements between firmware and configurator that would break 9.x compatibility. This is for PRs which will be included in INAV 10.x

If master is the correct target for this change, no action is needed.

---

This is an automated suggestion to help route contributions to the appropriate branch.

[qodo-code-review]

PR Compliance Guide 🔍

All compliance sections have been disabled in the configurations.

[error414]

Integration to inav rewrittten by discusion on discord.

1. terrain system is only showed in OSD, it uses same OSD element as rangerfinder, if data from ranger finder are not avaiable, then terrain is used.
2. new settings in cli "terrain_enabled". Terrain system can be turn on "set terrain_enabled = ON"

I found another bug. If the SD card is removed during operation and then inserted back, CDC gets broken and the DMA handlers stop being called. It's not terrain system issue, it's in inav for a long time. I can't find what happens there.

However, the terrain system can detect this and will stop reading from the SD card.