| /* |
| * Copyright 2022 Google LLC |
| * |
| * SPDX-License-Identifier: Apache-2.0 |
| */ |
| |
| #ifndef ZEPHYR_INCLUDE_DRIVERS_BATTERY_H_ |
| #define ZEPHYR_INCLUDE_DRIVERS_BATTERY_H_ |
| |
| /** |
| * @brief Fuel Gauge Interface |
| * @defgroup fuel_gauge_interface Fuel Gauge Interface |
| * @ingroup io_interfaces |
| * @{ |
| */ |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif /* __cplusplus */ |
| |
| #include <stdbool.h> |
| #include <stddef.h> |
| #include <stdint.h> |
| |
| #include <zephyr/device.h> |
| |
| /* Keep these alphabetized wrt property name */ |
| |
| /** Runtime Dynamic Battery Parameters */ |
| /** |
| * Provide a 1 minute average of the current on the battery. |
| * Does not check for flags or whether those values are bad readings. |
| * See driver instance header for details on implementation and |
| * how the average is calculated. Units in uA negative=discharging |
| */ |
| #define FUEL_GAUGE_AVG_CURRENT 0 |
| |
| /** Battery current (uA); negative=discharging */ |
| #define FUEL_GAUGE_CURRENT FUEL_GAUGE_AVG_CURRENT + 1 |
| /** Whether the battery underlying the fuel-gauge is cut off from charge */ |
| #define FUEL_GAUGE_CHARGE_CUTOFF FUEL_GAUGE_CURRENT + 1 |
| /** Cycle count in 1/100ths (number of charge/discharge cycles) */ |
| #define FUEL_GAUGE_CYCLE_COUNT FUEL_GAUGE_CHARGE_CUTOFF + 1 |
| /** Connect state of battery */ |
| #define FUEL_GAUGE_CONNECT_STATE FUEL_GAUGE_CYCLE_COUNT + 1 |
| /** General Error/Runtime Flags */ |
| #define FUEL_GAUGE_FLAGS FUEL_GAUGE_CONNECT_STATE + 1 |
| /** Full Charge Capacity in uAh (might change in some implementations to determine wear) */ |
| #define FUEL_GAUGE_FULL_CHARGE_CAPACITY FUEL_GAUGE_FLAGS + 1 |
| /** Is the battery physically present */ |
| #define FUEL_GAUGE_PRESENT_STATE FUEL_GAUGE_FULL_CHARGE_CAPACITY + 1 |
| /** Remaining capacity in uAh */ |
| #define FUEL_GAUGE_REMAINING_CAPACITY FUEL_GAUGE_PRESENT_STATE + 1 |
| /** Remaining battery life time in minutes */ |
| #define FUEL_GAUGE_RUNTIME_TO_EMPTY FUEL_GAUGE_REMAINING_CAPACITY + 1 |
| /** Remaining time in minutes until battery reaches full charge */ |
| #define FUEL_GAUGE_RUNTIME_TO_FULL FUEL_GAUGE_RUNTIME_TO_EMPTY + 1 |
| /** Absolute state of charge (percent, 0-100) - expressed as % of design capacity */ |
| #define FUEL_GAUGE_STATE_OF_CHARGE FUEL_GAUGE_RUNTIME_TO_FULL + 1 |
| /** Temperature in 0.1 K */ |
| #define FUEL_GAUGE_TEMPERATURE FUEL_GAUGE_STATE_OF_CHARGE + 1 |
| /** Battery voltage (uV) */ |
| #define FUEL_GAUGE_VOLTAGE FUEL_GAUGE_TEMPERATURE + 1 |
| |
| /** Reserved to demark end of common fuel gauge properties */ |
| #define FUEL_GAUGE_COMMON_COUNT FUEL_GAUGE_VOLTAGE + 1 |
| /** |
| * Reserved to demark downstream custom properties - use this value as the actual value may change |
| * over future versions of this API |
| */ |
| #define FUEL_GAUGE_CUSTOM_BEGIN FUEL_GAUGE_COMMON_COUNT + 1 |
| |
| /** Reserved to demark end of valid enum properties */ |
| #define FUEL_GAUGE_PROP_MAX UINT16_MAX |
| |
| struct fuel_gauge_get_property { |
| /** Battery fuel gauge property to get */ |
| uint16_t property_type; |
| |
| /** Negative error status set by callee e.g. -ENOTSUP for an unsupported property */ |
| int status; |
| |
| /** Property field for getting */ |
| union { |
| /* Fields have the format: */ |
| /* FUEL_GAUGE_PROPERTY_FIELD */ |
| /* type property_field; */ |
| |
| /* Dynamic Battery Info */ |
| /** FUEL_GAUGE_AVG_CURRENT */ |
| int avg_current; |
| /** FUEL_GAUGE_CUTOFF */ |
| bool cutoff; |
| /** FUEL_GAUGE_CURRENT */ |
| int current; |
| /** FUEL_GAUGE_CYCLE_COUNT */ |
| uint32_t cycle_count; |
| /** FUEL_GAUGE_FLAGS */ |
| uint32_t flags; |
| /** FUEL_GAUGE_FULL_CHARGE_CAPACITY */ |
| uint32_t full_charge_capacity; |
| /** FUEL_GAUGE_REMAINING_CAPACITY */ |
| uint32_t remaining_capacity; |
| /** FUEL_GAUGE_RUNTIME_TO_EMPTY */ |
| uint32_t runtime_to_empty; |
| /** FUEL_GAUGE_RUNTIME_TO_FULL */ |
| uint32_t runtime_to_full; |
| /** FUEL_GAUGE_STATE_OF_CHARGE */ |
| uint8_t state_of_charge; |
| /** FUEL_GAUGE_TEMPERATURE */ |
| uint16_t temperature; |
| /** FUEL_GAUGE_VOLTAGE */ |
| int voltage; |
| } value; |
| }; |
| |
| /** |
| * @brief Fetch a battery fuel-gauge property |
| * |
| * @param dev Pointer to the battery fuel-gauge device |
| * @param props pointer to array of fuel_gauge_get_property struct where the property struct |
| * field is set by the caller to determine what property is read from the |
| * fuel gauge device into the fuel_gauge_get_property struct's value field. |
| * @param props_len number of properties in props array |
| * |
| * @return return=0 if successful, return < 0 if getting all properties failed, return > 0 if some |
| * properties failed where return=number of failing properties. |
| */ |
| typedef int (*fuel_gauge_get_property_t)(const struct device *dev, |
| struct fuel_gauge_get_property *props, size_t props_len); |
| |
| /* Caching is entirely on the onus of the client */ |
| |
| __subsystem struct battery_driver_api { |
| fuel_gauge_get_property_t get_property; |
| }; |
| |
| /** |
| * @} |
| */ |
| |
| #ifdef __cplusplus |
| } |
| #endif /* __cplusplus */ |
| |
| #endif /* ZEPHYR_INCLUDE_DRIVERS_BATTERY_H_ */ |