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
- 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.
-
enumerator CHARGER_PROP_ONLINE = 0
-
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.
-
enumerator CHARGER_ONLINE_OFFLINE = 0
-
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.
-
enumerator CHARGER_STATUS_UNKNOWN = 0
-
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
-
enumerator CHARGER_CHARGE_TYPE_UNKNOWN = 0
-
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.
-
enumerator CHARGER_HEALTH_UNKNOWN = 0
-
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.
-
enumerator CHARGER_SEVERITY_PEAK = 0
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.
-
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.
-
enum charger_online online
-
struct charger_driver_api
- #include <charger.h>
Charging device API.
Caching is entirely on the onus of the client
-
typedef uint16_t charger_prop_t