nrf_fuel_gauge.h

Go to the documentation of this file.

/*
 * Copyright (c) 2023 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef __NRF_FUEL_GAUGE_H__
#define __NRF_FUEL_GAUGE_H__
 
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
 
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define NRF_FUEL_GAUGE_DEFAULT_INIT_PARAMETERS_PRIMARY(_v0, _i0, _t0, _battery_model)\
        ((struct nrf_fuel_gauge_init_parameters) {\
                .v0 = _v0,\
                .i0 = _i0,\
                .t0 = _t0,\
                .model_primary = _battery_model,\
                .opt_params = NULL,\
                .state = NULL,\
                .lock_func = NULL,\
        })
 
#define NRF_FUEL_GAUGE_DEFAULT_INIT_PARAMETERS_SECONDARY(_v0, _i0, _t0, _battery_model)\
        ((struct nrf_fuel_gauge_init_parameters) {\
                .v0 = _v0,\
                .i0 = _i0,\
                .t0 = _t0,\
                .model = _battery_model,\
                .opt_params = NULL,\
                .state = NULL,\
                .lock_func = NULL,\
        })
 
enum nrf_fuel_gauge_variant_type {
        NRF_FUEL_GAUGE_VARIANT_PRIMARY,
        NRF_FUEL_GAUGE_VARIANT_SECONDARY,
};
 
extern const char *nrf_fuel_gauge_version;
 
extern const char *nrf_fuel_gauge_build_date;
 
extern const enum nrf_fuel_gauge_variant_type nrf_fuel_gauge_variant;
 
extern const size_t nrf_fuel_gauge_state_size;
 
struct battery_model {
        float param_1[201];
        float temps[3];
        float param_2[122];
        float param_3[201];
        float param_4[201];
        float param_5[201];
        float param_6[201];
        float param_7[122];
        float param_8[122];
        float param_9[3];
        float param_10[6];
        float param_11[6];
        float param_12[3];
        char name[64];
};
 
struct battery_model_primary {
        float param_4[201];
        float param_3[201];
        float param_1[201];
        float param_5[201];
        float param_6[201];
        float param_2[88];
        float param_8[88];
        float param_7[88];
        float param_13[201];
        float param_14[201];
        float param_12;
        float param_15;
        float param_16;
        signed char param_17[20];
        float param_18[2];
        float param_19;
        char name[64];
};
 
struct nrf_fuel_gauge_state_info {
        float yhat;
        float r0;
        float T_truncated;
        float i_corrected;
        float soc_raw;
        float soh_raw;
        uint16_t cycle_count;
        float cycle_count_cumulative_mah;
        float k1;
        float k2;
};
 
struct nrf_fuel_gauge_config_parameters {
        bool discard_positive_deltaz;
        float tte_min_time;
        float tte_reset_threshold;
        bool soh_estimate_enable;
        bool soh_partial_charge_enable;
        float soh;
        float soh_calc_threshold;
        float battery_min_capacity;
        uint16_t cycle_count;
        float cycle_count_cumulative_mah;
        /* The following parameters are purposefully undocumented */
        float tau1;
        float tau2;
        float neta1;
        float neta2;
        float beta1;
        float beta2;
        float gating;
        float volt_drop;
        uint8_t vk_buffer_length;
        float soh_alpha1;
        float soh_alpha2;
        float soh_raw;
        float a;
        float b;
        float c;
        float d;
        float cycle_repl_min;
        float soh_up_cap_cycle_min;
        float soh_up_max;
        float soh_rep_up_max;
        float soh_jump_thr;
        float soh_partial_min_deltaSOC;
        float soh_partial_R_penalty;
};
 
struct nrf_fuel_gauge_init_parameters {
        float v0;
        float i0;
        float t0;
        union {
                const struct battery_model *model;
                const struct battery_model_primary *model_primary;
        };
        const struct nrf_fuel_gauge_config_parameters *opt_params;
        int (*lock_func)(const void *context, bool lock);
        const void *lock_context;
        const void *state;
        size_t state_size;
};
 
enum nrf_fuel_gauge_charge_state {
        NRF_FUEL_GAUGE_CHARGE_STATE_IDLE,
        NRF_FUEL_GAUGE_CHARGE_STATE_TRICKLE,
        NRF_FUEL_GAUGE_CHARGE_STATE_CC,
        NRF_FUEL_GAUGE_CHARGE_STATE_CC_LIMITED,
        NRF_FUEL_GAUGE_CHARGE_STATE_CV,
        NRF_FUEL_GAUGE_CHARGE_STATE_COMPLETE,
};
 
enum nrf_fuel_gauge_ext_state_info_type {
        NRF_FUEL_GAUGE_EXT_STATE_INFO_VBUS_CONNECTED,
        NRF_FUEL_GAUGE_EXT_STATE_INFO_VBUS_DISCONNECTED,
        NRF_FUEL_GAUGE_EXT_STATE_INFO_CHARGE_STATE_CHANGE,
        NRF_FUEL_GAUGE_EXT_STATE_INFO_CHARGE_CURRENT_CORRECTION,
        NRF_FUEL_GAUGE_EXT_STATE_INFO_DISCHARGE_CURRENT_CORRECTION,
        NRF_FUEL_GAUGE_EXT_STATE_INFO_CHARGE_CURRENT_LIMIT,
        NRF_FUEL_GAUGE_EXT_STATE_INFO_TERM_CURRENT,
        NRF_FUEL_GAUGE_EXT_STATE_INFO_BATTERY_REPLACED,
};
 
union nrf_fuel_gauge_ext_state_info_data {
        enum nrf_fuel_gauge_charge_state charge_state;
        float current_correction_factor;
        float charge_current_limit;
        float charge_term_current;
};
 
int nrf_fuel_gauge_config_params_default_get(struct nrf_fuel_gauge_config_parameters *params);
 
int nrf_fuel_gauge_config_params_current_get(struct nrf_fuel_gauge_config_parameters *params);
 
int nrf_fuel_gauge_state_compatible_check(const void *state, size_t state_size);
 
int nrf_fuel_gauge_init(const struct nrf_fuel_gauge_init_parameters *parameters, float *v0);
 
int nrf_fuel_gauge_process(float v, float i, float T, float t_delta, float *soc,
                             struct nrf_fuel_gauge_state_info *state);
 
int nrf_fuel_gauge_soc_get(float *soc);
 
int nrf_fuel_gauge_tte_get(float *tte);
 
int nrf_fuel_gauge_ttf_get(float *ttf);
 
int nrf_fuel_gauge_soh_get(float *soh);
 
int nrf_fuel_gauge_idle_set(float v, float T, float i_avg);
 
int nrf_fuel_gauge_state_get(void *state, size_t size);
 
int nrf_fuel_gauge_ext_state_update(enum nrf_fuel_gauge_ext_state_info_type type,
        union nrf_fuel_gauge_ext_state_info_data *data);
 
int nrf_fuel_gauge_config_params_adjust(const struct nrf_fuel_gauge_config_parameters *params);
 
#ifdef __cplusplus
}
#endif
 
#endif /* __NRF_FUEL_GAUGE_H__ */