Chargers

The charger subsystem exposes an API to uniformly access battery charger devices.

A charger device, or charger peripheral, is a device used to take external power provided to the system as an input and provide power as an output downstream to the battery pack(s) and system. The charger device can exist as a module, an integrated circuit, or as a functional block in a power management integrated circuit (PMIC).

The action of charging a battery pack is referred to as a charge cycle. When the charge cycle is executed the battery pack is charged according to the charge profile configured on the charger device. The charge profile is defined in the battery pack’s specification that is provided by the manufacturer. On charger devices with a control port, the charge profile can be configured by the host controller by setting the relevant properties, and can be adjusted at runtime to respond to environmental changes.

Basic Operation

Initiating a Charge Cycle

A charge cycle is initiated or terminated using charger_charge_enable().

Properties

Fundamentally, a property is a configurable setting, state, or quantity that a charger device can measure.

Chargers typically support multiple properties, such as temperature readings of the battery-pack or present-time current/voltage.

Properties are fetched by the client one at a time using charger_get_prop(). Properties are set by the client one at a time using charger_set_prop().

API Reference

Related code samples

Charger: Charge a battery using the charger driver API.

group charger_interface

Charger Interface.

Typedefs

typedef uint16_t charger_prop_t

A charger property’s identifier.

See charger_property for a list of identifiers

typedef void (*charger_status_notifier_t)(enum charger_status status)

The charger status change callback to notify the system.

Param status:: Current charging state

typedef void (*charger_online_notifier_t)(enum charger_online online)

The charger online change callback to notify the system.

Param online:: Current external supply state

typedef int (*charger_get_property_t)(const struct device *dev, const charger_prop_t prop, union charger_propval *val)

Callback API for getting a charger property.

See charger_get_property() for argument description

typedef int (*charger_set_property_t)(const struct device *dev, const charger_prop_t prop, const union charger_propval *val)

Callback API for setting a charger property.

See charger_set_property() for argument description

typedef int (*charger_charge_enable_t)(const struct device *dev, const bool enable)

Callback API enabling or disabling a charge cycle.

See charger_charge_enable() for argument description

Enums

enum charger_property

Runtime Dynamic Battery Parameters.

Values:

enumerator CHARGER_PROP_ONLINE = 0

Indicates if external supply is present for the charger.

Value should be of type enum charger_online

enumerator CHARGER_PROP_PRESENT

Reports whether or not a battery is present.

Value should be of type bool

enumerator CHARGER_PROP_STATUS

Represents the charging status of the charger.

Value should be of type enum charger_status

enumerator CHARGER_PROP_CHARGE_TYPE

Represents the charging algo type of the charger.

Value should be of type enum charger_charge_type

enumerator CHARGER_PROP_HEALTH

Represents the health of the charger.

Value should be of type enum charger_health

enumerator CHARGER_PROP_CONSTANT_CHARGE_CURRENT_UA: Configuration of current sink used for charging in µA.

enumerator CHARGER_PROP_PRECHARGE_CURRENT_UA: Configuration of current sink used for conditioning in µA.

enumerator CHARGER_PROP_CHARGE_TERM_CURRENT_UA: Configuration of charge termination target in µA.

enumerator CHARGER_PROP_CONSTANT_CHARGE_VOLTAGE_UV: Configuration of charge voltage regulation target in µV.

enumerator CHARGER_PROP_INPUT_REGULATION_CURRENT_UA

Configuration of the input current regulation target in µA.

This value is a rising current threshold that is regulated by reducing the charge current output

enumerator CHARGER_PROP_INPUT_REGULATION_VOLTAGE_UV

Configuration of the input voltage regulation target in µV.

This value is a falling voltage threshold that is regulated by reducing the charge current output

enumerator CHARGER_PROP_INPUT_CURRENT_NOTIFICATION

Configuration to issue a notification to the system based on the input current level and timing.

Value should be of type struct charger_current_notifier

enumerator CHARGER_PROP_DISCHARGE_CURRENT_NOTIFICATION

Configuration to issue a notification to the system based on the battery discharge current level and timing.

Value should be of type struct charger_current_notifier

enumerator CHARGER_PROP_SYSTEM_VOLTAGE_NOTIFICATION_UV: Configuration of the falling system voltage threshold where a notification is issued to the system, measured in µV.

enumerator CHARGER_PROP_STATUS_NOTIFICATION

Configuration to issue a notification to the system based on the charger status change.

Value should be of type charger_status_notifier_t

enumerator CHARGER_PROP_ONLINE_NOTIFICATION

Configuration to issue a notification to the system based on the charger online change.

Value should be of type charger_online_notifier_t

enumerator CHARGER_PROP_COMMON_COUNT: Reserved to demark end of common charger properties.

enumerator CHARGER_PROP_CUSTOM_BEGIN = CHARGER_PROP_COMMON_COUNT + 1: Reserved to demark downstream custom properties - use this value as the actual value may change over future versions of this API.

enumerator CHARGER_PROP_MAX = UINT16_MAX: Reserved to demark end of valid enum properties.

enum charger_online

External supply states.

Values:

enumerator CHARGER_ONLINE_OFFLINE = 0: External supply not present.

enumerator CHARGER_ONLINE_FIXED: External supply is present and of fixed output.

enumerator CHARGER_ONLINE_PROGRAMMABLE: External supply is present and of programmable output.

enum charger_status

Charging states.

Values:

enumerator CHARGER_STATUS_UNKNOWN = 0: Charging device state is unknown.

enumerator CHARGER_STATUS_CHARGING: Charging device is charging a battery.

enumerator CHARGER_STATUS_DISCHARGING: Charging device is not able to charge a battery.

enumerator CHARGER_STATUS_NOT_CHARGING: Charging device is not charging a battery.

enumerator CHARGER_STATUS_FULL: The battery is full and the charging device will not attempt charging.

enum charger_charge_type

Charge algorithm types.

Values:

enumerator CHARGER_CHARGE_TYPE_UNKNOWN = 0: Charge type is unknown.

enumerator CHARGER_CHARGE_TYPE_NONE: Charging is not occurring.

enumerator CHARGER_CHARGE_TYPE_TRICKLE: Charging is occurring at the slowest desired charge rate, typically for battery detection or preconditioning.

enumerator CHARGER_CHARGE_TYPE_FAST: Charging is occurring at the fastest desired charge rate.

enumerator CHARGER_CHARGE_TYPE_STANDARD: Charging is occurring at a moderate charge rate.

enumerator CHARGER_CHARGE_TYPE_ADAPTIVE

enumerator CHARGER_CHARGE_TYPE_LONGLIFE

enumerator CHARGER_CHARGE_TYPE_BYPASS

enum charger_health

Charger health conditions.

These conditions determine the ability to, or the rate of, charge

Values:

enumerator CHARGER_HEALTH_UNKNOWN = 0: Charger health condition is unknown.

enumerator CHARGER_HEALTH_GOOD: Charger health condition is good.

enumerator CHARGER_HEALTH_OVERHEAT: The charger device is overheated.

enumerator CHARGER_HEALTH_OVERVOLTAGE: The battery voltage has exceeded its overvoltage threshold.

enumerator CHARGER_HEALTH_UNSPEC_FAILURE: The battery or charger device is experiencing an unspecified failure.

enumerator CHARGER_HEALTH_COLD: The battery temperature is below the “cold” threshold.

enumerator CHARGER_HEALTH_WATCHDOG_TIMER_EXPIRE: The charger device’s watchdog timer has expired.

enumerator CHARGER_HEALTH_SAFETY_TIMER_EXPIRE: The charger device’s safety timer has expired.

enumerator CHARGER_HEALTH_CALIBRATION_REQUIRED: The charger device requires calibration.

enumerator CHARGER_HEALTH_WARM: The battery temperature is in the “warm” range.

enumerator CHARGER_HEALTH_COOL: The battery temperature is in the “cool” range.

enumerator CHARGER_HEALTH_HOT: The battery temperature is below the “hot” threshold.

enumerator CHARGER_HEALTH_NO_BATTERY: The charger device does not detect a battery.

enum charger_notification_severity

Charger severity levels for system notifications.

Values:

enumerator CHARGER_SEVERITY_PEAK = 0: Most severe level, typically triggered instantaneously.

enumerator CHARGER_SEVERITY_CRITICAL: More severe than the warning level, less severe than peak.

enumerator CHARGER_SEVERITY_WARNING: Base severity level.

Functions

int charger_get_prop(const struct device *dev, const charger_prop_t prop, union charger_propval *val)

Fetch a battery charger property.

Parameters:

dev – Pointer to the battery charger device
prop – Charger property to get
val – Pointer to charger_propval union

Return values:

0 – if successful
< – 0 if getting property failed

int charger_set_prop(const struct device *dev, const charger_prop_t prop, const union charger_propval *val)

Set a battery charger property.

Parameters:

dev – Pointer to the battery charger device
prop – Charger property to set
val – Pointer to charger_propval union

Return values:

0 – if successful
< – 0 if setting property failed

int charger_charge_enable(const struct device *dev, const bool enable)

Enable or disable a charge cycle.

Parameters:

dev – Pointer to the battery charger device
enable – true enables a charge cycle, false disables a charge cycle

Return values:

0 – if successful
-EIO – if communication with the charger failed
-EINVAL – if the conditions for initiating charging are invalid

struct charger_current_notifier

#include <charger.h>

The input current thresholds for the charger to notify the system.

Public Members

uint8_t severity: The severity of the notification where CHARGER_SEVERITY_PEAK is the most severe.

uint32_t current_ua: The current threshold to be exceeded.

uint32_t duration_us: The duration of excess current before notifying the system.

union charger_propval

#include <charger.h>

container for a charger_property value

Public Members

enum charger_online online: CHARGER_PROP_ONLINE.

bool present: CHARGER_PROP_PRESENT.

enum charger_status status: CHARGER_PROP_STATUS.

enum charger_charge_type charge_type: CHARGER_PROP_CHARGE_TYPE.

enum charger_health health: CHARGER_PROP_HEALTH.

uint32_t const_charge_current_ua: CHARGER_PROP_CONSTANT_CHARGE_CURRENT_UA.

uint32_t precharge_current_ua: CHARGER_PROP_PRECHARGE_CURRENT_UA.

uint32_t charge_term_current_ua: CHARGER_PROP_CHARGE_TERM_CURRENT_UA.

uint32_t const_charge_voltage_uv: CHARGER_PROP_CONSTANT_CHARGE_VOLTAGE_UV.

uint32_t input_current_regulation_current_ua: CHARGER_PROP_INPUT_REGULATION_CURRENT_UA.

uint32_t input_voltage_regulation_voltage_uv: CHARGER_PROP_INPUT_REGULATION_VOLTAGE_UV.

struct charger_current_notifier input_current_notification: CHARGER_PROP_INPUT_CURRENT_NOTIFICATION.

struct charger_current_notifier discharge_current_notification: CHARGER_PROP_DISCHARGE_CURRENT_NOTIFICATION.

uint32_t system_voltage_notification: CHARGER_PROP_SYSTEM_VOLTAGE_NOTIFICATION_UV.

charger_status_notifier_t status_notification: CHARGER_PROP_STATUS_NOTIFICATION.

charger_online_notifier_t online_notification: CHARGER_PROP_ONLINE_NOTIFICATION.

struct charger_driver_api

#include <charger.h>

Charging device API.

Caching is entirely on the onus of the client