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

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