AP_RangeFinder Detailed Reference

Header

File: libraries/AP_RangeFinder/AP_RangeFinder.h

#include <AP_RangeFinder.h>

Class Documentation

Warning

doxygenclass: Cannot find class “AP_RangeFinder” in doxygen xml output for project “ArduPilot” from directory: /home/runner/work/APMapi/APMapi/docs/../build/output-xml

Detailed Description

AP_RangeFinder is the range finder (distance sensor) driver for ArduPilot. It provides distance measurements used for terrain following, obstacle avoidance, precision landing, and altitude estimation.

Key Features:

• Multiple rangefinder backend support (Sonar, Laser, PWM, etc.)

• Orientation-based sensor selection

• Signal quality monitoring

• Terrain height estimation

• MAVLink distance sensor support

Inheritance

This class does not inherit from any other class. It is a top-level driver class.

Derived Classes (Backends):

• :doxygen:`AP_RangeFinder_Ping` - Ping sonar

• :doxygen:`AP_RangeFinder_Maxsonar` - MaxBotix sonar

• :doxygen:`AP_RangeFinder_LightWareSFxx` - LightWare SFxx laser

• :doxygen:`AP_RangeFinder_LeddarOne` - LeddarOne laser

• :doxygen:`AP_RangeFinder_USD1` - USDigital sensor

• :doxygen:`AP_RangeFinder_DroneCAN` - DroneCAN rangefinder

• :doxygen:`AP_RangeFinder_Backend` - Base class for backends

Related Classes:

• :doxygen:`AP_RangeFinder_Backend` - Base class for rangefinder backends

Public Types

enum AP_RangeFinder::Type

Rangefinder type/sensor model.

Noindex:

NONE = 0,
Sonar = 1,
Laser = 2,
PWM = 3,
BBQ10 = 4,
LeddarOne = 5,
USD1 = 6,
VL53L0X = 7,
NMEA = 8,
uLanding = 9,
USD1_CAN = 10,
Benewake = 11,
VL53L1X = 12,
TF02Pro = 13,
TF01 = 14,
LightWareSF40C = 15,
PWFMS_UAVCAN = 16,
DroneCAN = 17,
IQ6xx = 18,
SDP3X = 19,
DPS280 = 20,
ZFP20 = 21,
Multi = 22

enum AP_RangeFinder::Status

Rangefinder status.

Noindex:

NotConnected = 0,
NoData = 1,
OutOfRangeLow = 2,
OutOfRangeHigh = 3,
Good = 4

Public Member Functions

Singleton

static RangeFinder *AP_RangeFinder::get_singleton(void)

Get singleton instance of rangefinder driver.

Returns:

Pointer to AP_RangeFinder instance, or nullptr if not available

Initialization & Update

void AP_RangeFinder::init(enum Rotation orientation_default)

Initialize rangefinder driver.

Parameters:

orientation_default – Default orientation for sensors

void AP_RangeFinder::update(void)

Update rangefinder readings. Must be called in main loop.

Distance Reading

float AP_RangeFinder::distance_orient(enum Rotation orientation) const

Get distance for sensor at specific orientation.

Parameters:

orientation – Sensor orientation (ROTATION_*)

Returns:

Distance in meters, or -1 if invalid

uint16_t AP_RangeFinder::distance_cm_orient(enum Rotation orientation) const

Get distance in centimeters.

Parameters:

orientation – Sensor orientation

Returns:

Distance in centimeters

float AP_RangeFinder::distance(void) const

Get distance from primary rangefinder.

Returns:

Distance in meters

uint16_t AP_RangeFinder::distance_cm(void) const

Get primary distance in centimeters.

Returns:

Distance in centimeters

Range Limits

float AP_RangeFinder::max_distance_orient(enum Rotation orientation) const

Get maximum range for orientation.

Parameters:

orientation – Sensor orientation

Returns:

Maximum distance in meters

float AP_RangeFinder::min_distance_orient(enum Rotation orientation) const

Get minimum range for orientation.

Parameters:

orientation – Sensor orientation

Returns:

Minimum distance in meters

float AP_RangeFinder::ground_clearance_orient(enum Rotation orientation) const

Get ground clearance for orientation.

Parameters:

orientation – Sensor orientation

Returns:

Ground clearance in meters

Status & Health

AP_RangeFinder::Status AP_RangeFinder::status_orient(enum Rotation orientation) const

Get status for orientation.

Parameters:

orientation – Sensor orientation

Returns:

Status enum

bool AP_RangeFinder::has_data_orient(enum Rotation orientation) const

Check if sensor has valid data.

Parameters:

orientation – Sensor orientation

Returns:

true if data is valid

int8_t AP_RangeFinder::signal_quality_pct_orient(enum Rotation orientation) const

Get signal quality as percentage.

Parameters:

orientation – Sensor orientation

Returns:

Signal quality (0-100%), or -1 if unavailable

uint8_t AP_RangeFinder::range_valid_count_orient(enum Rotation orientation) const

Get number of consecutive valid readings.

Parameters:

orientation – Sensor orientation

Returns:

Count of valid readings

uint32_t AP_RangeFinder::last_reading_ms(enum Rotation orientation) const

Get time of last reading.

Parameters:

orientation – Sensor orientation

Returns:

Milliseconds since last reading

Sensor Information

uint8_t AP_RangeFinder::num_sensors(void) const

Get number of configured sensors.

Returns:

Number of sensors

AP_RangeFinder::Type AP_RangeFinder::get_type(uint8_t id) const

Get type of sensor by ID.

Parameters:

id – Sensor instance ID

Returns:

Sensor type enum

bool AP_RangeFinder::has_orientation(enum Rotation orientation) const

Check if orientation has a sensor.

Parameters:

orientation – Orientation to check

Returns:

true if sensor exists

AP_RangeFinder_Backend *AP_RangeFinder::find_instance(enum Rotation orientation) const

Find sensor instance by orientation.

Parameters:

orientation – Orientation to find

Returns:

Pointer to backend, or nullptr

Terrain

void AP_RangeFinder::set_estimated_terrain_height(float height)

Set estimated terrain height (from terrain database).

Parameters:

height – Terrain height in meters

MAVLink

void AP_RangeFinder::handle_msg(const mavlink_message_t &msg)

Handle MAVLink distance sensor message.

Parameters:

msg – MAVLink message

Usage Example

#include <AP_RangeFinder.h>

RangeFinder *rangefinder;

void setup() {
    rangefinder = RangeFinder::get_singleton();
    if (rangefinder == nullptr) {
        Serial.println("Rangefinder not available");
        return;
    }

    // Initialize with default orientation
    rangefinder->init(ROTATION_PITCH_270);
}

void loop() {
    // Update rangefinder
    rangefinder->update();

    // Get distance from primary sensor
    float distance = rangefinder->distance();
    if (distance > 0) {
        Serial.printf("Distance: %.2f m\n", distance);
    }

    // Get distance from downward-facing sensor
    float down_dist = rangefinder->distance_orient(ROTATION_PITCH_270);
    if (down_dist > 0) {
        Serial.printf("Downward: %.2f m\n", down_dist);
    }

    // Check status
    auto status = rangefinder->status_orient(ROTATION_PITCH_270);
    switch (status) {
        case RangeFinder::Good:
            Serial.println("Status: Good");
            break;
        case RangeFinder::NoData:
            Serial.println("Status: No Data");
            break;
        case RangeFinder::OutOfRangeLow:
            Serial.println("Status: Too Low");
            break;
        case RangeFinder::OutOfRangeHigh:
            Serial.println("Status: Too High");
            break;
        default:
            Serial.println("Status: Not Connected");
            break;
    }

    // Get signal quality
    int8_t quality = rangefinder->signal_quality_pct_orient(ROTATION_PITCH_270);
    if (quality >= 0) {
        Serial.printf("Signal Quality: %d %%\n", quality);
    }
}

Common Orientations

Rangefinders are typically mounted in specific orientations:

• ROTATION_PITCH_270 (downward) - Terrain following, landing

• ROTATION_PITCH_90 (forward) - Obstacle avoidance

• ROTATION_YAW_180 (backward) - Rear obstacle avoidance

• ROTATION_YAW_90 (right) - Side obstacle avoidance

See Also

• Sensor Libraries - Overview of sensor libraries

• api/ap_gps - GPS (used with rangefinder for terrain following)

• api/ap_ahrs - AHRS (orientation data)

• AP_RangeFinder_Backend - Backend driver base class