Battery Interface

[中文]

Public header: #include "brookesia/hal_interface/interfaces/power/battery.hpp"

Class: PowerBatteryIface

PowerBatteryIface describes battery and charger capabilities. It can query battery presence, level percentage, voltage, power source, and charge state, and can also read or update charger configuration and enable or disable charging when supported by the underlying hardware.

Not every board exposes the full set of battery and charger controls. Callers should first inspect Info::abilities or Info::has_ability() before reading capability-specific state fields or invoking control APIs.

API Reference

Header File

Classes

class PowerBatteryIface : public esp_brookesia::hal::Interface

Battery interface for querying battery state and controlling charger settings.

Public Types

enum class Ability

Battery backend capability.

Values:

enumerator Voltage

Battery voltage reading.

enumerator Percentage

Battery level percentage.

enumerator PowerSource

Battery/external power source state.

enumerator ChargeState

Charger state.

enumerator VbusVoltage

VBUS voltage reading.

enumerator SystemVoltage

System voltage reading.

enumerator ChargerControl

Charger enable/disable control.

enumerator ChargeConfig

Charger parameter configuration.

enum class PowerSource

Current power source.

Values:

enumerator Unknown

Power source is unknown.

enumerator Battery

Running from battery.

enumerator External

Running from external power.

enum class ChargeState

Current charge state.

Values:

enumerator Unknown

Charge state is unknown.

enumerator NotCharging

Battery is not charging.

enumerator Charging

Battery is charging, but the phase is unknown.

enumerator Trickle

Trickle charging.

enumerator PreCharge

Pre-charge phase.

enumerator ConstantCurrent

Constant-current phase.

enumerator ConstantVoltage

Constant-voltage phase.

enumerator Full

Battery is full.

enumerator Fault

Charger fault.

enum class LevelSource

Source used to calculate the battery level.

Values:

enumerator Unknown

Level source is unknown.

enumerator FuelGauge

Level comes from a fuel gauge.

enumerator VoltageCurve

Level is estimated from a voltage curve.

Public Functions

inline explicit PowerBatteryIface(Info info)

Construct a battery interface.

Parameters

info -- [in] Static battery capability information.

virtual ~PowerBatteryIface() = default

Virtual destructor for polymorphic battery interfaces.

inline const Info &get_info() const

Get static battery capability information.

Returns

Battery information.

virtual bool get_state(State &state) = 0

Get the current battery state.

Parameters

state -- [out] Runtime battery state snapshot.

Returns

true on success; otherwise false.

virtual bool get_charge_config(ChargeConfig &config) = 0

Get charger configuration.

Parameters

config -- [out] Charger configuration.

Returns

true on success; otherwise false.

virtual bool set_charge_config(const ChargeConfig &config) = 0

Set charger configuration.

Parameters

config -- [in] Charger configuration.

Returns

true on success; otherwise false.

virtual bool set_charging_enabled(bool enabled) = 0

Enable or disable charging.

Parameters

enabled -- [in] true to enable charging; false to disable charging.

Returns

true on success; otherwise false.

Public Static Attributes

static constexpr const char *NAME = "Power:Battery"

Interface registry name.

struct ChargeConfig

Charger configuration.

Public Members

bool enabled = false

Charger enable state.

uint32_t target_voltage_mv = 0

Target charge voltage in mV.

uint32_t charge_current_ma = 0

Main charge current in mA.

uint32_t precharge_current_ma = 0

Pre-charge current in mA.

uint32_t termination_current_ma = 0

Termination current in mA.

struct Info

Static battery capability information.

Public Functions

inline bool has_ability(Ability ability) const

Check whether an ability is supported.

Parameters

ability -- [in] Ability to query.

Returns

true if the ability is present; otherwise false.

Public Members

std::string name

Battery or backend name.

std::string chemistry

Battery chemistry, such as Li-ion.

std::vector<Ability> abilities

Supported backend abilities.

struct State

Runtime battery state snapshot.

Public Members

bool is_present = false

Whether a battery is detected.

PowerSource power_source = PowerSource::Unknown

Current power source.

ChargeState charge_state = ChargeState::Unknown

Current charge state.

LevelSource level_source = LevelSource::Unknown

Battery percentage source.

std::optional<uint32_t> voltage_mv = std::nullopt

Battery voltage in mV.

std::optional<uint8_t> percentage = std::nullopt

Battery percentage in [0, 100].

std::optional<uint32_t> vbus_voltage_mv = std::nullopt

VBUS voltage in mV.

std::optional<uint32_t> system_voltage_mv = std::nullopt

System voltage in mV.

bool is_low = false

Battery is below the low threshold.

bool is_critical = false

Battery is below the critical threshold.