Update rangefinder documentation

docs/Rangefinder.md

@@ -1,47 +1,161 @@
 # Rangefinder
 
-Rangefinders are devices used to measure Above Ground Altitude.
+Rangefinders are devices used to measure altitude Above Ground Level (AGL), the distance to the ground directly beneath the aircraft.
 
-## Current state
+## Features
 
-Current support of rangefinders in INAV is very limited. They are used only to:
+Rangefinders in INAV are used for:
 
-* landing detection for multirotors
-* automated landing support for fixed wings
-* _Experimental_ terrain following (Surface) flight mode activated with _SURFACE_ and _ALTHOLD_ flight mode
+* **Landing detection** for multirotors - precise touchdown detection
+* **Automated landing support** for fixed wings - smooth descent control
+* **Terrain following (Surface mode)** - maintain constant height above ground (multirotors only)
+* **Position estimation** - when combined with optical flow sensors, enables GPS-free navigation
 
 ## Hardware
 
-Following rangefinders are supported:
+INAV supports the following rangefinder types:
 
-* SRF10 - experimental
-* INAV_I2C - is a simple [DIY rangefinder interface with Arduino Pro Mini 3.3V](https://github.com/iNavFlight/inav-rangefinder). Can be used to connect when flight controller has no Trigger-Echo ports. 
-* VL53L0X - simple laser rangefinder usable up to 75cm
-* UIB - experimental
-* MSP - experimental
-* TOF10120 - small & lightweight laser range sensor, usable up to 200cm
-* TERARANGER EVO - 30cm to 600cm, depends on version https://www.terabee.com/sensors-modules/lidar-tof-range-finders/#individual-distance-measurement-sensors
-* NRA15/NRA24 - experimental, UART version
+### Time-of-Flight (ToF) Laser Sensors
 
-#### NRA15/NRA24
-NRA15/NRA24 from nanoradar use US-D1_V0 or NRA protocol, it depends which firmware you use. Radar can be set by firmware
-to two different resolutions. See table below.
+* **VL53L0X** - STMicroelectronics laser rangefinder, 0-75cm range (I2C)
+* **VL53L1X** - STMicroelectronics laser rangefinder, 0-400cm range (I2C)
+* **TOF10120** - Small & lightweight laser sensor, 0-200cm range (I2C)
+* **TERARANGER_EVO** - TeraRanger Evo series, 30-600cm range depending on model (I2C/UART)
+  - https://www.terabee.com/sensors-modules/lidar-tof-range-finders/#individual-distance-measurement-sensors
+
+### Ultrasonic Sensors
+
+* **SRF10** - Devantech SRF10, 0-600cm range (I2C)
+* **US42** - Maxbotix US-42, 0-645cm range (I2C)
+* **USD1_V0** - USD1 ultrasonic sensor variant (UART)
+
+### Radar Sensors
+
+* **NRA** - NanoRadar NRA15/NRA24 millimeter-wave radar (UART)
+
+NRA15/NRA24 sensors can use US-D1_V0 or NRA protocol depending on firmware configuration:
 
 | Radar | Protocol | Resolution      | Name in configurator |
 |-------|----------|-----------------|----------------------|
-| NRA15 | US-D1_V0 | 0-30m (+-4cm)   | USD1_V0              |
-| NRA15 | NRA      | 0-30m (+-4cm)   | NRA                  | 
-| NRA15 | NRA      | 0-100m (+-10cm) | NRA                  | 
-| NRA24 | US-D1_V0 | 0-50m (+-4cm)   | USD1_V0              |
-| NRA24 | US-D1_V0 | 0-200m (+-10cm) | USD1_V0              |
-| NRA24 | NRA      | 0-50m (+-4cm)   | NRA                  | 
-| NRA24 | NRA      | 0-200m (+-10cm) | NRA                  | 
+| NRA15 | US-D1_V0 | 0-30m (±4cm)    | USD1_V0              |
+| NRA15 | NRA      | 0-30m (±4cm)    | NRA                  |
+| NRA15 | NRA      | 0-100m (±10cm)  | NRA                  |
+| NRA24 | US-D1_V0 | 0-50m (±4cm)    | USD1_V0              |
+| NRA24 | US-D1_V0 | 0-200m (±10cm)  | USD1_V0              |
+| NRA24 | NRA      | 0-50m (±4cm)    | NRA                  |
+| NRA24 | NRA      | 0-200m (±10cm)  | NRA                  |
+
+### Serial/External Sensors
+
+* **MSP** - External rangefinder via MSP protocol (UART/MSP)
+* **BENEWAKE** - Benewake LIDAR modules (TFmini, etc.) via serial protocol (UART)
+
+### Development/Testing
+
+* **FAKE** - Simulated rangefinder for testing without hardware
+
+## Configuration
+
+Enable rangefinder in CLI:
+
+```
+set rangefinder_hardware = VL53L0X  # or your sensor type
+save
+```
+
+Optional median filtering for smoother readings:
+
+```
+set rangefinder_median_filter = ON
+save
+```
+
+### Position Estimation Weights
+
+Control how rangefinder data is fused into altitude estimates:
+
+```
+set inav_max_surface_altitude = 200      # Max rangefinder range to use (cm)
+set inav_w_z_surface_p = 3.5             # Position weight
+set inav_w_z_surface_v = 6.1             # Velocity weight
+```
+
+## Surface Mode (Terrain Following)
+
+Surface mode enables terrain following on **multirotors only** by maintaining constant altitude above ground instead of absolute altitude.
 
+**Activation:** Enable SURFACE mode via RC switch (requires rangefinder configured)
+
+**Compatible with:**
+- ALTHOLD - Maintains height above ground
+- POSHOLD - Holds position with terrain-relative altitude
+- CRUISE - Velocity control with terrain following
+
+**Settings:**
+
+```
+set nav_max_terrain_follow_alt = 100    # Max altitude in Surface mode (cm)
+```
+
+**Important:** Always set `nav_max_terrain_follow_alt` **less than** `inav_max_surface_altitude` to prevent attempting to use the sensor beyond its reliable range. For example, if your rangefinder is reliable up to 200cm, set `inav_max_surface_altitude = 200` and `nav_max_terrain_follow_alt = 100` (or lower).
+
+**Note:** Surface mode is NOT available on fixed wing aircraft.
 
 ## Connections
 
-I2C solutions like `VL53L0X` or `INAV_I2C` can be connected to I2C port and used as any other I2C device.
+### I2C Rangefinders
+
+I2C sensors (VL53L0X, VL53L1X, TOF10120, SRF10, US42, TERARANGER_EVO) connect to the flight controller's I2C port and are auto-detected when configured.
+
+### Serial Rangefinders
+
+UART-based sensors (MSP, BENEWAKE, NRA, USD1_V0) require:
+1. Assign UART port in Ports tab
+2. Configure `rangefinder_hardware` setting
+3. Set appropriate baud rate
+
+## Optical Flow Integration
+
+When a rangefinder is combined with an optical flow sensor:
+- Rangefinder provides altitude (Z-axis)
+- Optical flow provides horizontal movement (X/Y axes)
+- Together they enable GPS-free position hold indoors
+
+See wiki for optical flow setup: https://github.com/iNavFlight/inav/wiki/Optic-Flow-and-Rangefinder
+
+## Constraints
+
+**Not Supported:**
+- HC-SR04 ultrasonic sensors
+- US-100 ultrasonic sensors
+
+**Limitations:**
+- Surface mode: Multirotors only
+- Tilt angle: Rangefinder disabled if aircraft tilt exceeds sensor detection cone
+- Range: Set `inav_max_surface_altitude` to sensor's reliable range, not maximum range
+
+## Troubleshooting
+
+**No rangefinder readings:**
+- Verify correct `rangefinder_hardware` selection
+- Check wiring and power (3.3V or 5V depending on sensor)
+- Ensure I2C address is unique (no conflicts)
+- Check sensor has clear line of sight to ground
+
+**Erratic readings:**
+- Enable `rangefinder_median_filter = ON`
+- Check for vibration - mount sensor rigidly
+- Verify sensor is not affected by propeller wash
+- Ensure ground surface has sufficient texture (not smooth/reflective)
+
+**Surface mode not working:**
+- Verify SURFACE mode is enabled via switch
+- Check rangefinder is providing valid data
+- Ensure altitude is below `nav_max_terrain_follow_alt` (operational limit)
+- Ensure altitude is within sensor's reliable range (set by `inav_max_surface_altitude`)
+- Confirm platform is multirotor (fixed wings not supported)
 
-#### Constraints
+## References
 
-INAV does not support `HC-SR04` and `US-100`. No constrains for I2C like `VL53L0X` or `INAV_I2C`.
+- [INAV Wiki: Optic Flow and Rangefinder Setup](https://github.com/iNavFlight/inav/wiki/Optic-Flow-and-Rangefinder)
+- [Settings Reference](Settings.md)