BMS front-end IC driver

API for different Battery Management System (BMS) front-end ICs.

Defines

BMS_IC_CONF_VOLTAGE_LIMITS

BMS_IC_CONF_TEMP_LIMITS

BMS_IC_CONF_CURRENT_LIMITS

BMS_IC_CONF_BALANCING

BMS_IC_CONF_ALERTS

BMS_IC_CONF_VOLTAGE_REGS

BMS_IC_CONF_ALL

BMS_IC_DATA_CELL_VOLTAGES

BMS_IC_DATA_PACK_VOLTAGES

BMS_IC_DATA_TEMPERATURES

BMS_IC_DATA_CURRENT

BMS_IC_DATA_BALANCING

BMS_IC_DATA_ERROR_FLAGS

BMS_IC_DATA_ALL

BMS_IC_BALANCING_OFF

BMS_IC_BALANCING_AUTO

Enums

enum bms_ic_mode

BMS IC operation modes

Values:

enumerator BMS_IC_MODE_ACTIVE: Normal operation

enumerator BMS_IC_MODE_IDLE: Low-power mode with FETs still enabled

enumerator BMS_IC_MODE_STANDBY: Low-power mode with FETs off, but regulators still enabled, e.g. to power host MCU

enumerator BMS_IC_MODE_OFF: Lowest power mode with all FETs and regulators disabled

Functions

static inline int bms_ic_configure(const struct device *dev, struct bms_ic_conf *ic_conf, uint32_t flags)

Write config to IC.

Most BMS ICs can apply configuration values only in discrete steps or with limited resolution. The actually applied configuration is written back to ic_conf.

Parameters:

dev – Pointer to the device structure for the driver instance.
ic_conf – BMS configuration to apply.
flags – Flags to specify which parts of the configuration should be applied. See BMS_IC_CONF_* defines for valid flags.

Return values:

appl_flags – successfully applied configuration flags (may be different than requested)
-ENOTSUP – if none of the requested flags is supported
-EIO – for communication error

static inline void bms_ic_assign_data(const struct device *dev, struct bms_ic_data *ic_data)

Assign bms_ic_data object to use for reading data from the IC.

This data is updated by calls to bms_ic_read_data.

Parameters:

dev – Pointer to the device structure for the driver instance.
ic_data – Pointer to a statically allocated bms_ic_data object.

Returns:

0 for success or negative error code otherwise.

static inline int bms_ic_read_data(const struct device *dev, uint32_t flags)

Read data from the IC.

bms_ic_assign_data must be called before using this function.

Parameters:

dev – Pointer to the device structure for the driver instance.
flags – Flags to specify which parts of the data should be updated. See BMS_IC_DATA_* defines for valid flags.

Return values:

0 – for success
-EINVAL – if not all requested data is provided by the IC
-EIO – for communication error
-ENOMEM – if the data was not assigned with bms_ic_assign_data

static inline int bms_ic_balance(const struct device *dev, uint32_t cells)

Update the balancing operation of the IC.

Parameters:

dev – Pointer to the device structure for the driver instance.
cells – Bitset defining the cell(s) to be balanced. Set to BMS_IC_BALANCING_OFF to disable balancing and BMS_IC_BALANCING_AUTO to enable automatic balancing.

Returns:

0 for success or negative error code otherwise.

static inline int bms_ic_set_mode(const struct device *dev, enum bms_ic_mode mode)

Request the IC to go into specified operating mode.

Usually used to set the device into different sleep modes for reduced power consumption.

Parameters:

dev – Pointer to the device structure for the driver instance.
mode – Desired BMS IC operating mode.

Returns:

0 for success or negative error code otherwise.

static inline int bms_ic_read_mem(const struct device *dev, const uint16_t addr, uint8_t *data, const size_t len)

static inline int bms_ic_write_mem(const struct device *dev, const uint16_t addr, const uint8_t *data, const size_t len)

static inline int bms_ic_debug_print_mem(const struct device *dev)

struct bms_ic_conf

#include <bms_ic.h>

BMS configuration values, stored in RAM.

Public Members

float cell_chg_voltage_limit: Cell target charge voltage (V)

float cell_dis_voltage_limit: Cell discharge voltage limit (V)

float cell_ov_limit: Cell over-voltage limit (V)

float cell_ov_reset: Cell over-voltage error reset threshold (V)

uint32_t cell_ov_delay_ms: Cell over-voltage delay (ms)

float cell_uv_limit: Cell under-voltage limit (V)

float cell_uv_reset: Cell under-voltage error reset threshold (V)

uint32_t cell_uv_delay_ms: Cell under-voltage delay (ms)

float dis_ot_limit: Discharge over-temperature (DOT) limit (°C)

float dis_ut_limit: Discharge under-temperature (DUT) limit (°C)

float chg_ot_limit: Charge over-temperature (COT) limit (°C)

float chg_ut_limit: Charge under-temperature (CUT) limit (°C)

float temp_limit_hyst: Temperature limit hysteresis (°C)

float bal_cell_voltage_diff: Balancing cell voltage target difference (V)

float bal_cell_voltage_min: Minimum cell voltage to start balancing (V)

float bal_idle_current: Current threshold to be considered idle (A)

uint16_t bal_idle_delay: Minimum idle duration before balancing (s)

uint8_t vregs_enable: Bitfield to enable/disable built-in voltage regulators (usually LDOs). The bit positions correspond to the regulator numbers in the manufacturer datasheet (e.g. 0x2 would enable REG1).

uint32_t alert_mask: Error flags which should trigger an alert action (if supported by the IC)

struct bms_ic_data

#include <bms_ic.h>

Current BMS IC status including measurements and error flags

Public Members

float cell_voltages[CONFIG_BMS_IC_MAX_CELLS]: Single cell voltages (V)

float cell_voltage_max: Maximum cell voltage (V)

float cell_voltage_min: Minimum cell voltage (V)

float cell_voltage_avg: Average cell voltage (V)

float total_voltage: Battery internal stack voltage (V)

float cell_temps[CONFIG_BMS_IC_MAX_THERMISTORS]: Cell temperatures (°C)

float cell_temp_max: Maximum cell temperature (°C)

float cell_temp_min: Minimum cell temperature (°C)

float cell_temp_avg: Average cell temperature (°C)

float ic_temp: Internal BMS IC temperature (°C)

uint8_t connected_cells: Actual number of cells connected (may be less than CONFIG_BMS_IC_MAX_CELLS)

uint8_t used_thermistors: Actual number of thermistors used (may be less than CONFIG_BMS_IC_MAX_THERMISTORS)

uint32_t balancing_status: Balancing channels on/off status

uint32_t error_flags: BMS errors stored as BMS_ERR_* flags