Chargers

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

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