fuel_gauge.h

Go to the documentation of this file.

/*
 * Copyright 2022 Google LLC
 * Copyright 2023 Microsoft Corporation
 * Copyright (c) 2025 Philipp Steiner <philipp.steiner1987@gmail.com>
 * Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
 * Copyright (c) 2026 Analog Devices Inc.
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_DRIVERS_FUEL_GAUGE_H_
#define ZEPHYR_INCLUDE_DRIVERS_FUEL_GAUGE_H_

 
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
 
#include <errno.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#include <zephyr/device.h>
 
enum fuel_gauge_prop_type {
        FUEL_GAUGE_AVG_CURRENT_UA = 0,
        FUEL_GAUGE_AVG_CURRENT __deprecated = FUEL_GAUGE_AVG_CURRENT_UA,

        FUEL_GAUGE_CURRENT_UA,
        FUEL_GAUGE_CURRENT __deprecated = FUEL_GAUGE_CURRENT_UA,
        FUEL_GAUGE_CHARGE_CUTOFF,
        FUEL_GAUGE_CYCLE_COUNT,
        FUEL_GAUGE_CONNECT_STATE,
        FUEL_GAUGE_FLAGS,
        FUEL_GAUGE_FULL_CHARGE_CAPACITY_UAH,
        FUEL_GAUGE_FULL_CHARGE_CAPACITY __deprecated = FUEL_GAUGE_FULL_CHARGE_CAPACITY_UAH,
        FUEL_GAUGE_PRESENT_STATE,
        FUEL_GAUGE_REMAINING_CAPACITY_UAH,
        FUEL_GAUGE_REMAINING_CAPACITY __deprecated = FUEL_GAUGE_REMAINING_CAPACITY_UAH,
        FUEL_GAUGE_RUNTIME_TO_EMPTY_MINS,
        FUEL_GAUGE_RUNTIME_TO_EMPTY __deprecated = FUEL_GAUGE_RUNTIME_TO_EMPTY_MINS,
        FUEL_GAUGE_RUNTIME_TO_FULL_MINS,
        FUEL_GAUGE_RUNTIME_TO_FULL __deprecated = FUEL_GAUGE_RUNTIME_TO_FULL_MINS,
        FUEL_GAUGE_SBS_MFR_ACCESS,
        FUEL_GAUGE_ABSOLUTE_STATE_OF_CHARGE_PCT,
        FUEL_GAUGE_ABSOLUTE_STATE_OF_CHARGE __deprecated = FUEL_GAUGE_ABSOLUTE_STATE_OF_CHARGE_PCT,
        FUEL_GAUGE_RELATIVE_STATE_OF_CHARGE_PCT,
        FUEL_GAUGE_RELATIVE_STATE_OF_CHARGE __deprecated = FUEL_GAUGE_RELATIVE_STATE_OF_CHARGE_PCT,
        FUEL_GAUGE_TEMPERATURE_DK,
        FUEL_GAUGE_TEMPERATURE __deprecated = FUEL_GAUGE_TEMPERATURE_DK,
        FUEL_GAUGE_VOLTAGE_UV,
        FUEL_GAUGE_VOLTAGE __deprecated = FUEL_GAUGE_VOLTAGE_UV,
        FUEL_GAUGE_SBS_MODE,
        FUEL_GAUGE_CHARGE_CURRENT_UA,
        FUEL_GAUGE_CHARGE_CURRENT __deprecated = FUEL_GAUGE_CHARGE_CURRENT_UA,
        FUEL_GAUGE_CHARGE_VOLTAGE_UV,
        FUEL_GAUGE_CHARGE_VOLTAGE __deprecated = FUEL_GAUGE_CHARGE_VOLTAGE_UV,
        FUEL_GAUGE_STATUS,
        FUEL_GAUGE_DESIGN_CAPACITY,
        FUEL_GAUGE_DESIGN_VOLTAGE_MV,
        FUEL_GAUGE_DESIGN_VOLTAGE __deprecated = FUEL_GAUGE_DESIGN_VOLTAGE_MV,
        FUEL_GAUGE_SBS_ATRATE,
        FUEL_GAUGE_SBS_ATRATE_TIME_TO_FULL_MINS,
        FUEL_GAUGE_SBS_ATRATE_TIME_TO_FULL __deprecated = FUEL_GAUGE_SBS_ATRATE_TIME_TO_FULL_MINS,
        FUEL_GAUGE_SBS_ATRATE_TIME_TO_EMPTY_MINS,
        FUEL_GAUGE_SBS_ATRATE_TIME_TO_EMPTY __deprecated = FUEL_GAUGE_SBS_ATRATE_TIME_TO_EMPTY_MINS,
        FUEL_GAUGE_SBS_ATRATE_OK,
        FUEL_GAUGE_SBS_REMAINING_CAPACITY_ALARM,
        FUEL_GAUGE_SBS_REMAINING_TIME_ALARM_MINS,
        FUEL_GAUGE_SBS_REMAINING_TIME_ALARM __deprecated = FUEL_GAUGE_SBS_REMAINING_TIME_ALARM_MINS,
        FUEL_GAUGE_MANUFACTURER_NAME,
        FUEL_GAUGE_DEVICE_NAME,
        FUEL_GAUGE_DEVICE_CHEMISTRY,
        FUEL_GAUGE_CURRENT_DIRECTION,
        FUEL_GAUGE_STATE_OF_CHARGE_ALARM_PCT,
        FUEL_GAUGE_STATE_OF_CHARGE_ALARM __deprecated = FUEL_GAUGE_STATE_OF_CHARGE_ALARM_PCT,
        FUEL_GAUGE_LOW_VOLTAGE_ALARM_UV,
        FUEL_GAUGE_LOW_VOLTAGE_ALARM __deprecated = FUEL_GAUGE_LOW_VOLTAGE_ALARM_UV,
        FUEL_GAUGE_HIGH_VOLTAGE_ALARM_UV,
        FUEL_GAUGE_HIGH_VOLTAGE_ALARM __deprecated = FUEL_GAUGE_HIGH_VOLTAGE_ALARM_UV,
        FUEL_GAUGE_LOW_CURRENT_ALARM_UA,
        FUEL_GAUGE_LOW_CURRENT_ALARM __deprecated = FUEL_GAUGE_LOW_CURRENT_ALARM_UA,
        FUEL_GAUGE_HIGH_CURRENT_ALARM_UA,
        FUEL_GAUGE_HIGH_CURRENT_ALARM __deprecated = FUEL_GAUGE_HIGH_CURRENT_ALARM_UA,
        FUEL_GAUGE_LOW_TEMPERATURE_ALARM_DK,
        FUEL_GAUGE_LOW_TEMPERATURE_ALARM __deprecated = FUEL_GAUGE_LOW_TEMPERATURE_ALARM_DK,
        FUEL_GAUGE_HIGH_TEMPERATURE_ALARM_DK,
        FUEL_GAUGE_HIGH_TEMPERATURE_ALARM __deprecated = FUEL_GAUGE_HIGH_TEMPERATURE_ALARM_DK,
        FUEL_GAUGE_LOW_GPIO_ALARM_UV,
        FUEL_GAUGE_LOW_GPIO_ALARM __deprecated = FUEL_GAUGE_LOW_GPIO_ALARM_UV,
        FUEL_GAUGE_HIGH_GPIO_ALARM_UV,
        FUEL_GAUGE_HIGH_GPIO_ALARM __deprecated = FUEL_GAUGE_HIGH_GPIO_ALARM_UV,
        FUEL_GAUGE_GPIO_VOLTAGE_UV,
        FUEL_GAUGE_GPIO_VOLTAGE __deprecated = FUEL_GAUGE_GPIO_VOLTAGE_UV,
        FUEL_GAUGE_ADC_MODE,
        FUEL_GAUGE_CC_CONFIG,
        FUEL_GAUGE_STATE_OF_HEALTH,
        FUEL_GAUGE_THERM_VOLTAGE_UV,

        FUEL_GAUGE_COMMON_COUNT,
        FUEL_GAUGE_CUSTOM_BEGIN,

        FUEL_GAUGE_PROP_MAX = UINT16_MAX,
};
 
typedef uint16_t fuel_gauge_prop_t;

typedef int32_t fuel_gauge_custom_value_int_t;

typedef uint32_t fuel_gauge_custom_value_uint_t;

typedef bool fuel_gauge_custom_value_bool_t;

union fuel_gauge_prop_val {
        /* Fields have the format: */
        /* FUEL_GAUGE_PROPERTY_FIELD */
        /* type property_field; */
 
        /* Dynamic Battery Info */
        __deprecated int avg_current;
        int32_t avg_current_ua;
        bool cutoff;
        __deprecated int current;
        int32_t current_ua;
        uint32_t cycle_count;
        uint32_t connect_state;
        uint32_t flags;
        __deprecated uint32_t full_charge_capacity;
        uint32_t full_charge_capacity_uah;
        bool present_state;
        __deprecated uint32_t remaining_capacity;
        uint32_t remaining_capacity_uah;
        __deprecated uint32_t runtime_to_empty;
        uint32_t runtime_to_empty_mins;
        __deprecated uint32_t runtime_to_full;
        uint32_t runtime_to_full_mins;
        uint16_t sbs_mfr_access_word;
        __deprecated uint8_t absolute_state_of_charge;
        uint8_t absolute_state_of_charge_pct;
        __deprecated uint8_t relative_state_of_charge;
        uint8_t relative_state_of_charge_pct;
        __deprecated uint16_t temperature;
        uint16_t temperature_dk;
        __deprecated int voltage;
        int32_t voltage_uv;
        uint16_t sbs_mode;
        __deprecated uint32_t chg_current;
        uint32_t chg_current_ua;
        __deprecated uint32_t chg_voltage;
        uint32_t chg_voltage_uv;
        uint16_t fg_status;
        uint16_t design_cap;
        __deprecated uint16_t design_volt;
        uint16_t design_volt_mv;
        int16_t sbs_at_rate;
        __deprecated uint16_t sbs_at_rate_time_to_full;
        uint16_t sbs_at_rate_time_to_full_mins;
        __deprecated uint16_t sbs_at_rate_time_to_empty;
        uint16_t sbs_at_rate_time_to_empty_mins;
        bool sbs_at_rate_ok;
        uint16_t sbs_remaining_capacity_alarm;
        __deprecated uint16_t sbs_remaining_time_alarm;
        uint16_t sbs_remaining_time_alarm_mins;
        uint16_t current_direction;
        __deprecated uint8_t state_of_charge_alarm;
        uint8_t state_of_charge_alarm_pct;
        __deprecated uint32_t low_voltage_alarm;
        uint32_t low_voltage_alarm_uv;
        __deprecated uint32_t high_voltage_alarm;
        uint32_t high_voltage_alarm_uv;
        __deprecated int32_t low_current_alarm;
        int32_t low_current_alarm_ua;
        __deprecated int32_t high_current_alarm;
        int32_t high_current_alarm_ua;
        __deprecated uint16_t low_temperature_alarm;
        uint16_t low_temperature_alarm_dk;
        __deprecated uint16_t high_temperature_alarm;
        uint16_t high_temperature_alarm_dk;
        __deprecated int32_t gpio_voltage;
        int32_t gpio_voltage_uv;
        __deprecated int32_t low_gpio_alarm;
        int32_t low_gpio_alarm_uv;
        __deprecated int32_t high_gpio_alarm;
        int32_t high_gpio_alarm_uv;
        uint8_t adc_mode;
        uint8_t cc_config;
        uint8_t state_of_health;
        uint32_t therm_voltage_uv;
        fuel_gauge_custom_value_int_t custom_int;
        fuel_gauge_custom_value_uint_t custom_uint;
        fuel_gauge_custom_value_bool_t custom_bool;
};

#define SBS_GAUGE_MANUFACTURER_NAME_MAX_SIZE 20
#define SBS_GAUGE_DEVICE_NAME_MAX_SIZE       20
#define SBS_GAUGE_DEVICE_CHEMISTRY_MAX_SIZE  4
 
struct sbs_gauge_manufacturer_name {
        uint8_t manufacturer_name_length;
        char manufacturer_name[SBS_GAUGE_MANUFACTURER_NAME_MAX_SIZE];
} __packed;
 
struct sbs_gauge_device_name {
        uint8_t device_name_length;
        char device_name[SBS_GAUGE_DEVICE_NAME_MAX_SIZE];
} __packed;
 
struct sbs_gauge_device_chemistry {
        uint8_t device_chemistry_length;
        char device_chemistry[SBS_GAUGE_DEVICE_CHEMISTRY_MAX_SIZE];
} __packed;


typedef int (*fuel_gauge_get_property_t)(const struct device *dev, fuel_gauge_prop_t prop,
                                         union fuel_gauge_prop_val *val);

typedef int (*fuel_gauge_set_property_t)(const struct device *dev, fuel_gauge_prop_t prop,
                                         union fuel_gauge_prop_val val);

typedef int (*fuel_gauge_get_buffer_property_t)(const struct device *dev,
                                                fuel_gauge_prop_t prop_type, void *dst,
                                                size_t dst_len);

typedef int (*fuel_gauge_battery_cutoff_t)(const struct device *dev);
 
/* Caching is entirely on the onus of the client */

__subsystem struct fuel_gauge_driver_api {
        /*
         * Note: Historically this API allowed drivers to implement a custom multi-get/set property
         * function, this was added so drivers could potentially optimize batch read with their
         * specific chip. However, it was removed because of no existing concrete case upstream.
         * If this need is demonstrated, we can add this back in as an API field.
         */
        fuel_gauge_get_property_t get_property;
        fuel_gauge_set_property_t set_property;
        fuel_gauge_get_buffer_property_t get_buffer_property;
        fuel_gauge_battery_cutoff_t battery_cutoff;
};


__syscall int fuel_gauge_get_prop(const struct device *dev, fuel_gauge_prop_t prop,
                                  union fuel_gauge_prop_val *val);
 
static inline int z_impl_fuel_gauge_get_prop(const struct device *dev, fuel_gauge_prop_t prop,
                                             union fuel_gauge_prop_val *val)
{
        const struct fuel_gauge_driver_api *api = DEVICE_API_GET(fuel_gauge, dev);
 
        if (api->get_property == NULL) {
                return -ENOSYS;
        }
 
        return api->get_property(dev, prop, val);
}

 
__syscall int fuel_gauge_get_props(const struct device *dev, const fuel_gauge_prop_t *props,
                                   union fuel_gauge_prop_val *vals, size_t len);
static inline int z_impl_fuel_gauge_get_props(const struct device *dev,
                                              const fuel_gauge_prop_t *props,
                                              union fuel_gauge_prop_val *vals, size_t len)
{
        int ret;
 
        for (size_t i = 0; i < len; i++) {
                ret = DEVICE_API_GET(fuel_gauge, dev)->get_property(dev, props[i], vals + i);
 
                if (ret) {
                        return ret;
                }
        }
 
        return 0;
}

__syscall int fuel_gauge_set_prop(const struct device *dev, fuel_gauge_prop_t prop,
                                  union fuel_gauge_prop_val val);
 
static inline int z_impl_fuel_gauge_set_prop(const struct device *dev, fuel_gauge_prop_t prop,
                                             union fuel_gauge_prop_val val)
{
        const struct fuel_gauge_driver_api *api = DEVICE_API_GET(fuel_gauge, dev);
 
        if (api->set_property == NULL) {
                return -ENOSYS;
        }
 
        return api->set_property(dev, prop, val);
}
__syscall int fuel_gauge_set_props(const struct device *dev, const fuel_gauge_prop_t *props,
                                   const union fuel_gauge_prop_val *vals, size_t len);
 
static inline int z_impl_fuel_gauge_set_props(const struct device *dev,
                                              const fuel_gauge_prop_t *props,
                                              const union fuel_gauge_prop_val *vals, size_t len)
{
        for (size_t i = 0; i < len; i++) {
                int ret = fuel_gauge_set_prop(dev, props[i], vals[i]);
 
                if (ret) {
                        return ret;
                }
        }
 
        return 0;
}

 
__syscall int fuel_gauge_get_buffer_prop(const struct device *dev, fuel_gauge_prop_t prop_type,
                                         void *dst, size_t dst_len);
 
static inline int z_impl_fuel_gauge_get_buffer_prop(const struct device *dev,
                                                    fuel_gauge_prop_t prop_type, void *dst,
                                                    size_t dst_len)
{
        const struct fuel_gauge_driver_api *api = DEVICE_API_GET(fuel_gauge, dev);
 
        if (api->get_buffer_property == NULL) {
                return -ENOSYS;
        }
 
        return api->get_buffer_property(dev, prop_type, dst, dst_len);
}

__syscall int fuel_gauge_battery_cutoff(const struct device *dev);
 
static inline int z_impl_fuel_gauge_battery_cutoff(const struct device *dev)
{
        const struct fuel_gauge_driver_api *api = DEVICE_API_GET(fuel_gauge, dev);
 
        if (api->battery_cutoff == NULL) {
                return -ENOSYS;
        }
 
        return api->battery_cutoff(dev);
}

 
#ifdef __cplusplus
}
#endif /* __cplusplus */
 
#include <zephyr/syscalls/fuel_gauge.h>
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_FUEL_GAUGE_H_ */