电池接口

[English]

公共头文件： #include "brookesia/hal_interface/interfaces/power/battery.hpp"

类名： PowerBatteryIface

PowerBatteryIface 用于描述电池与充电器相关能力。它既可以查询电池是否存在、电量百分比、电压、电源来源和充电状态，也可以在底层硬件支持时读取或设置充电配置、启停充电。

并非所有开发板都具备完整的电池与充电控制能力。调用方应先通过 Info::abilities 或 Info::has_ability() 判断当前实现支持的能力，再访问对应状态字段或控制接口。

API 参考

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.

参数

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.

返回

Battery information.

virtual bool get_state(State &state) = 0

Get the current battery state.

参数

state -- [out] Runtime battery state snapshot.

返回

true on success; otherwise false.

virtual bool get_charge_config(ChargeConfig &config) = 0

Get charger configuration.

参数

config -- [out] Charger configuration.

返回

true on success; otherwise false.

virtual bool set_charge_config(const ChargeConfig &config) = 0

Set charger configuration.

参数

config -- [in] Charger configuration.

返回

true on success; otherwise false.

virtual bool set_charging_enabled(bool enabled) = 0

Enable or disable charging.

参数

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

返回

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.

参数

ability -- [in] Ability to query.

返回

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.