AP_BattMonitor Detailed Reference

Header

File: libraries/AP_BattMonitor/AP_BattMonitor.h

#include <AP_BattMonitor.h>

Class Documentation

Warning

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

Detailed Description

AP_BattMonitor is the battery monitoring system for ArduPilot. It handles battery voltage, current sensing, capacity tracking, and provides failsafe functionality for low battery conditions.

Key Features:

• Multiple battery monitor backends (Analog, SMBus, DroneCAN, INA2XX, etc.)

• Voltage and current monitoring

• Capacity tracking (mAh consumed)

• Cell voltage monitoring for smart batteries

• Battery failsafe functionality

• Current prediction for remaining flight time

Inheritance

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

Derived Classes (Backends):

• :doxygen:`AP_BattMonitor_Analog` - Analog voltage/current sensor

• :doxygen:`AP_BattMonitor_SMBus` - SMBus smart battery

• :doxygen:`AP_BattMonitor_DroneCAN` - DroneCAN battery monitor

• :doxygen:`AP_BattMonitor_INA2XX` - INA2XX current/voltage sensor

• :doxygen:`AP_BattMonitor_INA239` - INA239 high-precision sensor

• :doxygen:`AP_BattMonitor_LTC2946` - LTC2946 gas gauge

• :doxygen:`AP_BattMonitor_Generator` - Generator/EFI fuel monitor

• :doxygen:`AP_BattMonitor_EFI` - EFI engine fuel monitoring

Related Classes:

• :doxygen:`AP_BattMonitor_Backend` - Base class for battery monitor backends

Public Types

enum AP_BattMonitor::Failsafe

Battery failsafe state.

Noindex:

None = 0,           // No failsafe
Low = 1,            // Low voltage/capacity
Critical = 2,       // Critical level
Emergency = 3       // Emergency level

enum AP_BattMonitor::ChargingState

Battery charging state.

Noindex:

Not_Charging = 0,
Charging = 1,
Charged = 2,
Discharged = 3,
Error = 4

Public Member Functions

Singleton

static AP_BattMonitor *AP_BattMonitor::get_singleton()

Get singleton instance of battery monitor.

Returns:

Pointer to AP_BattMonitor instance, or nullptr if not available

Initialization & Update

void AP_BattMonitor::read()

Read battery data from all monitors. Must be called in main loop.

Health & Status

bool AP_BattMonitor::healthy(uint8_t instance) const

Check if specific battery instance is healthy.

Parameters:

instance – Battery instance index

Returns:

true if healthy

bool AP_BattMonitor::healthy() const

Check if primary battery is healthy.

Returns:

true if healthy

Voltage & Current

float AP_BattMonitor::voltage(uint8_t instance) const

Get battery voltage.

Parameters:

instance – Battery instance index

Returns:

Voltage in Volts

float AP_BattMonitor::voltage() const

Get primary battery voltage.

Returns:

Voltage in Volts

float AP_BattMonitor::current(uint8_t instance) const

Get battery current draw.

Parameters:

instance – Battery instance index

Returns:

Current in Amperes (negative when discharging)

float AP_BattMonitor::current() const

Get primary battery current.

Returns:

Current in Amperes

float AP_BattMonitor::current_total() const

Get total current across all batteries.

Returns:

Total current in Amperes

Capacity & Energy

float AP_BattMonitor::capacity_remaining_pct(uint8_t instance) const

Get remaining capacity as percentage.

Parameters:

instance – Battery instance index

Returns:

Remaining capacity (0-100%)

float AP_BattMonitor::capacity_remaining_pct() const

Get primary battery remaining capacity.

Returns:

Remaining capacity (0-100%)

int32_t AP_BattMonitor::capacity_consumed_mah(uint8_t instance) const

Get capacity consumed.

Parameters:

instance – Battery instance index

Returns:

Consumed capacity in mAh

int32_t AP_BattMonitor::capacity_consumed_mah() const

Get primary battery consumed capacity.

Returns:

Consumed capacity in mAh

float AP_BattMonitor::wh_remaining(uint8_t instance) const

Get remaining energy.

Parameters:

instance – Battery instance index

Returns:

Remaining energy in Watt-hours

float AP_BattMonitor::total_energy() const

Get total battery capacity.

Returns:

Total energy in Watt-hours

Cell Voltage

float AP_BattMonitor::cell_voltage(uint8_t instance, uint8_t cell) const

Get cell voltage for smart batteries.

Parameters:

• instance – Battery instance index

• cell – Cell index (0-based)

Returns:

Cell voltage in Volts

uint8_t AP_BattMonitor::cell_count(uint8_t instance) const

Get number of cells.

Parameters:

instance – Battery instance index

Returns:

Number of cells

Temperature

float AP_BattMonitor::temperature(uint8_t instance) const

Get battery temperature.

Parameters:

instance – Battery instance index

Returns:

Temperature in Celsius

float AP_BattMonitor::temperature() const

Get primary battery temperature.

Returns:

Temperature in Celsius

Power

float AP_BattMonitor::power(uint8_t instance) const

Get instantaneous power consumption.

Parameters:

instance – Battery instance index

Returns:

Power in Watts

float AP_BattMonitor::power() const

Get primary battery power.

Returns:

Power in Watts

Failsafe

AP_BattMonitor::Failsafe AP_BattMonitor::get_failsafe_state(uint8_t instance) const

Get battery failsafe state.

Parameters:

instance – Battery instance index

Returns:

Failsafe state enum

bool AP_BattMonitor::has_failsafed(uint8_t instance) const

Check if battery has triggered failsafe.

Parameters:

instance – Battery instance index

Returns:

true if failsafe was triggered

bool AP_BattMonitor::in_failsafe() const

Check if any battery is in failsafe.

Returns:

true if in failsafe

State of Charge

AP_BattMonitor::ChargingState AP_BattMonitor::get_charging_state(uint8_t instance) const

Get charging state.

Parameters:

instance – Battery instance index

Returns:

Charging state enum

bool AP_BattMonitor::is_charging(uint8_t instance) const

Check if battery is charging.

Parameters:

instance – Battery instance index

Returns:

true if charging

uint8_t AP_BattMonitor::get_failsafe_priorities() const

Get failsafe priority bitmask.

Returns:

Priority bitmask

Usage Example

#include <AP_BattMonitor.h>

AP_BattMonitor *battery;

void setup() {
    battery = AP_BattMonitor::get_singleton();
    if (battery == nullptr) {
        Serial.println("Battery monitor not available");
        return;
    }
}

void loop() {
    // Read battery data
    battery->read();

    // Check health
    if (battery->healthy()) {
        // Get voltage
        float voltage = battery->voltage();
        Serial.printf("Voltage: %.2f V\n", voltage);

        // Get current
        float current = battery->current();
        Serial.printf("Current: %.2f A\n", current);

        // Get power
        float power = battery->power();
        Serial.printf("Power: %.2f W\n", power);

        // Get remaining capacity
        float remaining = battery->capacity_remaining_pct();
        Serial.printf("Remaining: %.1f %%\n", remaining);

        // Get consumed capacity
        int32_t consumed = battery->capacity_consumed_mah();
        Serial.printf("Consumed: %d mAh\n", (int)consumed);

        // Get temperature
        float temp = battery->temperature();
        if (temp > 0) {
            Serial.printf("Temperature: %.1f C\n", temp);
        }

        // Check failsafe
        if (battery->in_failsafe()) {
            Serial.println("WARNING: Battery failsafe active!");
        }
    }
}

See Also

• Sensor Libraries - Overview of sensor libraries

• api/ap_gps - GPS (for flight time estimation)

• AP_BattMonitor_Backend - Backend driver base class

• AP_BattMonitor_Analog - Analog battery monitor

• AP_BattMonitor_SMBus - SMBus smart battery