AP_Compass Detailed Reference¶

Class Documentation ¶

Warning

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

AP_Compass (also known as Compass) is the digital compass/magnetometer driver for ArduPilot. It provides heading determination using the Earth’s magnetic field, which is essential for autonomous navigation and flight stability.

Key Features:

Multiple magnetometer backend support (HMC5843, LIS3MDL, QMC5883L, etc.)
Hard/soft iron calibration
Motor compensation for interference from motors
Automatic declination calculation
Priority-based sensor selection

Inheritance ¶

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

Derived Classes:

:doxygen:`AP_Compass_AK09916` - AKM AK09916 magnetometer
:doxygen:`AP_Compass_AK8963` - AKM AK8963 magnetometer
:doxygen:`AP_Compass_BMM150` - Bosch BMM150 magnetometer
:doxygen:`AP_Compass_HMC5843` - Honeywell HMC5843 magnetometer
:doxygen:`AP_Compass_LIS3MDL` - ST LIS3MDL magnetometer
:doxygen:`AP_Compass_QMC5883L` - QMC QMC5883L magnetometer

Related Classes:

:doxygen:`AP_Compass_Backend` - Base class for compass backends

Public Types ¶

enum AP_Compass::LearnType¶

Compass calibration learning type.

Noindex:

NONE = 0,        // Do not learn offsets
INFLIGHT = 1,    // Learn in-flight
EKF = 2,         // Learn via EKF
SAVE = 3         // Save learned values

Public Member Variables ¶

This class uses internal state structures. Access via member functions below.

Public Member Functions ¶

Singleton ¶

static Compass *AP_Compass::get_singleton()¶

Get singleton instance of the compass driver.

Returns:: Pointer to Compass instance, or nullptr if not available

Compass *compass = Compass::get_singleton();
if (compass == nullptr) {
    // Compass not available
}

Initialization & Reading ¶

bool AP_Compass::read()¶

Read compass data from all sensors. Must be called in main loop.

Returns:: true if data was read successfully

bool AP_Compass::available() const¶

Check if compass is available and enabled.

Returns:: true if compass is available

Health & Status ¶

bool AP_Compass::healthy(uint8_t i) const¶

Check if specific compass instance is healthy.

Parameters:: i – Compass instance index
Returns:: true if healthy

bool AP_Compass::healthy(void) const¶

Check if primary compass is healthy.

Returns:: true if healthy

uint8_t AP_Compass::get_healthy_mask() const¶

Get bitmask of healthy compass instances.

Returns:: Bitmask of healthy compasses

bool AP_Compass::consistent() const¶

Check if all compass readings are consistent.

Returns:: true if readings are consistent

Heading Calculation ¶

float AP_Compass::calculate_heading(const Matrix3f &dcm_matrix) const¶

Calculate heading using DCM rotation matrix.

Parameters:: dcm_matrix – Direction Cosine Matrix
Returns:: Heading in radians (0 = North)

float AP_Compass::calculate_heading(const Matrix3f &dcm_matrix, uint8_t i) const¶

Calculate heading for specific compass instance.

Parameters:

dcm_matrix – Direction Cosine Matrix
i – Compass instance index

Returns:

Heading in radians

Magnetic Field Data ¶

const Vector3f &AP_Compass::get_field(uint8_t i) const¶

Get magnetic field vector from specific compass.

Parameters:: i – Compass instance index
Returns:: Magnetic field vector in milliGauss

const Vector3f &AP_Compass::get_field(void) const¶

Get magnetic field from primary compass.

Returns:: Magnetic field vector

uint8_t AP_Compass::get_count(void) const¶

Get number of compass instances.

Returns:: Number of compasses

Calibration ¶

void AP_Compass::set_offsets(uint8_t i, const Vector3f &offsets)¶

Set calibration offsets for compass.

Parameters:

i – Compass instance index
offsets – Offset vector (X, Y, Z)

void AP_Compass::save_offsets(uint8_t i)¶

Save calibration offsets to persistent storage.

Parameters:: i – Compass instance index

void AP_Compass::set_and_save_offsets(uint8_t i, const Vector3f &offsets)¶

Set and save calibration offsets.

Parameters:

i – Compass instance index
offsets – Offset vector

void AP_Compass::set_and_save_diagonals(uint8_t i, const Vector3f &diagonals)¶

Set soft iron calibration diagonal matrix.

Parameters:

i – Compass instance index
diagonals – Diagonal values

void AP_Compass::set_and_save_offdiagonals(uint8_t i, const Vector3f &diagonals)¶

Set soft iron calibration off-diagonal matrix.

Parameters:

i – Compass instance index
diagonals – Off-diagonal values

bool AP_Compass::start_calibration_all(bool retry = false, bool autosave = false, float delay_sec = 0.0f, bool autoreboot = false)¶

Start calibration for all compasses.

Parameters:

retry – Allow retry on failure
autosave – Auto-save after calibration
delay_sec – Delay before starting
autoreboot – Reboot after calibration

Returns:

true if calibration started

void AP_Compass::cancel_calibration_all()¶: Cancel ongoing calibration.

bool AP_Compass::is_calibrating() const¶

Check if calibration is in progress.

Returns:: true if calibrating

Offset Access ¶

const Vector3f &AP_Compass::get_offsets(uint8_t i) const¶

Get calibration offsets for compass.

Parameters:: i – Compass instance index
Returns:: Offset vector

const Vector3f &AP_Compass::get_diagonals(uint8_t i) const¶

Get soft iron diagonal values.

Parameters:: i – Compass instance index
Returns:: Diagonal vector

const Vector3f &AP_Compass::get_offdiagonals(uint8_t i) const¶

Get soft iron off-diagonal values.

Parameters:: i – Compass instance index
Returns:: Off-diagonal vector

Declination ¶

void AP_Compass::set_declination(float radians, bool save_to_eeprom = true)¶

Set magnetic declination.

Parameters:

radians – Declination in radians
save_to_eeprom – Whether to save

float AP_Compass::get_declination() const¶

Get current magnetic declination.

Returns:: Declination in radians

Motor Compensation ¶

void AP_Compass::set_motor_compensation(uint8_t i, const Vector3f &motor_comp_factor)¶

Set motor compensation factors.

Parameters:

i – Compass instance index
motor_comp_factor – Compensation vector

const Vector3f &AP_Compass::get_motor_compensation(uint8_t i) const¶

Get motor compensation factors.

Parameters:: i – Compass instance index
Returns:: Compensation vector

void AP_Compass::set_throttle(float thr_pct)¶

Set current throttle percentage for motor compensation.

Parameters:: thr_pct – Throttle percentage (0-1)

void AP_Compass::motor_compensation_type(const uint8_t comp_type)¶

Set motor compensation type.

Parameters:: comp_type – Compensation type (0=disabled, 1=throttle, 2=current)

Usage Example ¶

#include <AP_Compass.h>

Compass *compass;

void setup() {
    compass = Compass::get_singleton();
    if (compass == nullptr) {
        Serial.println("Compass not available");
        return;
    }

    // Start calibration
    compass->start_calibration_all(false, true);
}

void loop() {
    // Read compass
    compass->read();

    // Check health
    if (compass->healthy()) {
        // Get magnetic field
        Vector3f field = compass->get_field();
        Serial.printf("Field: %.2f, %.2f, %.2f mGauss\n",
                    field.x, field.y, field.z);

        // Calculate heading (requires DCM from AHRS)
        // float heading = compass->calculate_heading(dcm);
        // Serial.printf("Heading: %.2f degrees\n", degrees(heading));
    }
}

AP_Compass Detailed Reference¶

Header ¶

Class Documentation ¶

Detailed Description ¶

Inheritance ¶

Public Types ¶

Public Member Variables ¶

Public Member Functions ¶

Singleton ¶

Initialization & Reading ¶

Health & Status ¶

Heading Calculation ¶

Magnetic Field Data ¶

Calibration ¶

Offset Access ¶

Declination ¶

Motor Compensation ¶

Usage Example ¶

See Also ¶