Low level BMS driver specific to ADBMS6380 chip. More...

#include "adbms6380.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "commands.h"
#include "common/freertos/freertos.h"
#include "common/phal/gpio.h"
#include "common/phal/spi.h"
#include "pec.h"

Functions
void	adbms6380_set_cs_low (SPI_InitConfig_t *spi)
	Drive the ADBMS CS line low.

void	adbms6380_set_cs_high (SPI_InitConfig_t *spi)
	Drive the ADBMS CS line to high.

void	adbms6380_wake (SPI_InitConfig_t *spi, size_t module_count)
	Wake a daisy-chained set of ADBMS devices.

uint16_t	adbms6380_get_threshold_voltage_cfg (float threshold_voltage)
	Convert a voltage threshold (V) into 12-bit REG_B threshold encoding.

int16_t	adbms6380_extract_i16 (uint8_t *data, int idx)
	Extract a little-endian 16-bit signed value from a byte buffer.

float	adbms6380_raw_to_v (int16_t raw)
	Convert raw voltage measurement from the ADBMS6380 to volts.

void	adbms6380_adcv (uint8_t output_cmd[ADBMS6380_COMMAND_RAW_SIZE], bool rd, bool cont, bool dcp, bool rstf, uint8_t ow)
	Build ADCV command bytes.

void	adbms6380_adsv (uint8_t output_cmd[ADBMS6380_COMMAND_RAW_SIZE], bool cont, bool dcp, uint8_t ow)
	Build ADSV command bytes.

void	adbms6380_adax (uint8_t output_cmd[ADBMS6380_COMMAND_RAW_SIZE], bool ow, bool pup, uint8_t ch)
	Build ADAX (aux) command bytes.

void	adbms6380_prepare_command (strbuf_t *output_buffer, const uint8_t command[ADBMS6380_COMMAND_RAW_SIZE])
	Append a command and its PEC to an output buffer.

void	adbms6380_prepare_data_packet (strbuf_t *output_buffer, const uint8_t data[ADBMS6380_SINGLE_DATA_RAW_SIZE])
	Append a data payload and its PEC to an output buffer.

void	adbms6380_calculate_cfg_rega (uint8_t output_cfg_rega[ADBMS6380_SINGLE_DATA_RAW_SIZE], bool refon, uint8_t cth)
	Calculate the REG_A configuration register value.

void	adbms6380_calculate_cfg_regb (uint8_t output_cfg_regb[ADBMS6380_SINGLE_DATA_RAW_SIZE], float overvoltage_threshold, float undervoltage_threshold, const bool is_discharging[ADBMS6380_CELL_COUNT])
	Calculate the REG_B configuration register value.

bool	adbms6380_check_data_pec (const uint8_t *rx_bytes, size_t rx_len)
	Verify the PEC of received data.

adbms6380_read_result_t	adbms6380_read (SPI_InitConfig_t spi, size_t module_count, const uint8_t cmd_buffer[ADBMS6380_COMMAND_PKT_SIZE], uint8_t rx_buffer, size_t rx_length_per_module)
	Read a fixed-length response from all modules after a command.

adbms6380_read_result_t	adbms6380_read_data_with_retries (SPI_InitConfig_t spi, size_t max_retries, size_t module_count, const uint8_t cmd_buffer[ADBMS6380_COMMAND_PKT_SIZE], uint8_t rx_buffer)
	Read a single-data-packet response per module and retries on PEC failure.

adbms6380_read_result_t	adbms6380_read_data (SPI_InitConfig_t spi, size_t module_count, const uint8_t cmd_buffer[ADBMS6380_COMMAND_PKT_SIZE], uint8_t rx_buffer)
	Read a single-data-packet response per module.

bool	adbms6380_read_cell_voltages (SPI_InitConfig_t spi, strbuf_t cmd_buffer, uint8_t rx_buffer, float cell_voltages, int16_t *cell_voltages_raw, bool pec_error_flags[ADBMS6380_RDCV_CMD_COUNT], size_t module_count, size_t max_retries_on_pec_failure)
	Read all cell voltages from each module.

bool	adbms6380_read_gpio_voltages (SPI_InitConfig_t spi, strbuf_t cmd_buffer, uint8_t rx_buffer, float *gpio_voltages, bool pec_error_flags[ADBMS6380_RDAUX_CMD_COUNT], size_t module_count, size_t max_retries_on_pec_failure)
	Read all GPIO/aux voltages from each module.

Detailed Description

Low level BMS driver specific to ADBMS6380 chip.

Author: Millan Kumar (kumar.nosp@m.798@.nosp@m.purdu.nosp@m.e.ed.nosp@m.u)

Function Documentation

◆ adbms6380_adax()

void adbms6380_adax	(	uint8_t	output_cmd[ADBMS6380_COMMAND_RAW_SIZE],
		bool	ow,
		bool	pup,
		uint8_t	ch )

Build ADAX (aux) command bytes.

Parameters

output_cmd	Output buffer for 2-byte command.
ow	Open-wire detection enable.
pup	Pull-up enable for open-wire detection.
ch	Channel selection (5-bit). 0 for all.

◆ adbms6380_adcv()

void adbms6380_adcv	(	uint8_t	output_cmd[ADBMS6380_COMMAND_RAW_SIZE],
		bool	rd,
		bool	cont,
		bool	dcp,
		bool	rstf,
		uint8_t	ow )

Build ADCV command bytes.

Parameters

output_cmd	Output buffer for 2-byte command.
rd	Redundant mode.
cont	Continuous conversion enable.
dcp	Discharge permitted during conversion (only affects PWM balancing, not DCC).
rstf	Reset filter.
ow	Open-wire setting (2-bit).

◆ adbms6380_adsv()

void adbms6380_adsv	(	uint8_t	output_cmd[ADBMS6380_COMMAND_RAW_SIZE],
		bool	cont,
		bool	dcp,
		uint8_t	ow )

Build ADSV command bytes.

Parameters

output_cmd	Output buffer for 2-byte command.
cont	Continuous conversion enable.
dcp	Discharge permitted during conversion (only affects PWM balancing, not DCC).
ow	Open-wire setting (2-bit).

◆ adbms6380_calculate_cfg_rega()

void adbms6380_calculate_cfg_rega	(	uint8_t	output_cfg_rega[ADBMS6380_SINGLE_DATA_RAW_SIZE],
		bool	refon,
		uint8_t	cth )

Calculate the REG_A configuration register value.

Populates GPIO pull-downs, reference behavior, and comparator threshold.

Parameters

output_cfg_rega	Output buffer for REG_A configuration (6 bytes).
refon	1 = reference remains powered up until watchdog timeout.
cth	C-ADC vs. S-ADC comparison voltage threshold.

◆ adbms6380_calculate_cfg_regb()

void adbms6380_calculate_cfg_regb	(	uint8_t	output_cfg_regb[ADBMS6380_SINGLE_DATA_RAW_SIZE],
		float	overvoltage_threshold,
		float	undervoltage_threshold,
		const bool	is_discharging[ADBMS6380_CELL_COUNT] )

Calculate the REG_B configuration register value.

Encodes VOV/VUV thresholds and discharge control bits.

Parameters

output_cfg_regb	Output buffer for REG_B configuration (6 bytes).
overvoltage_threshold	Overvoltage threshold in volts.
undervoltage_threshold	Undervoltage threshold in volts.
is_discharging	Per-cell discharge enable flags.

◆ adbms6380_check_data_pec()

bool adbms6380_check_data_pec	(	const uint8_t *	rx_bytes,
		size_t	rx_len )

Verify the PEC of received data.

Parameters

rx_bytes	Pointer to received bytes from a module. PEC10 must follow the raw data bytes.
rx_len	Length of the recieved data from a module in bytes (including PEC, so the raw data is actually rx_len - ADBMS6380_PEC_SIZE).

Returns: True if the received PEC matches calculated value, false otherwise.

◆ adbms6380_extract_i16()

int16_t adbms6380_extract_i16	(	uint8_t *	data,
		int	idx )

Extract a little-endian 16-bit signed value from a byte buffer.

Parameters

data	Pointer to byte buffer containing 16-bit words.
idx	Index of the 16-bit word to extract.

Returns: Signed 16-bit value.

◆ adbms6380_get_threshold_voltage_cfg()

uint16_t adbms6380_get_threshold_voltage_cfg ( float threshold_voltage )

Convert a voltage threshold (V) into 12-bit REG_B threshold encoding.

Parameters

threshold_voltage Threshold voltage in volts.

Returns: 12-bit configuration value suitable for VOV/VUV fields.

◆ adbms6380_prepare_command()

void adbms6380_prepare_command	(	strbuf_t *	output_buffer,
		const uint8_t	command[ADBMS6380_COMMAND_RAW_SIZE] )

Append a command and its PEC to an output buffer.

Parameters

output_buffer	Buffer to append into.
command	2-byte command payload.

◆ adbms6380_prepare_data_packet()

void adbms6380_prepare_data_packet	(	strbuf_t *	output_buffer,
		const uint8_t	data[ADBMS6380_SINGLE_DATA_RAW_SIZE] )

Append a data payload and its PEC to an output buffer.

Parameters

output_buffer	Buffer to append into.
data	6-byte data payload.

◆ adbms6380_raw_to_v()

float adbms6380_raw_to_v ( int16_t raw )

Convert raw voltage measurement from the ADBMS6380 to volts.

Parameters

raw	Raw code from ADBMS.

Returns: Corresponding voltage in volts.

◆ adbms6380_read()

adbms6380_read_result_t adbms6380_read	(	SPI_InitConfig_t *	spi,
		size_t	module_count,
		const uint8_t	cmd_buffer[ADBMS6380_COMMAND_PKT_SIZE],
		uint8_t *	rx_buffer,
		size_t	rx_length_per_module )

Read a fixed-length response from all modules after a command.

Sends the command to the daisy chain, then reads rx_length bytes into rx_buffer. Data is returned in module order (0..N-1).

Parameters

spi	SPI configuration used for the transfer.
module_count	Number of modules in the daisy chain.
cmd_buffer	Command buffer including PEC.
rx_buffer	Output buffer for received bytes.
rx_length_per_module	Number of bytes expected from each module (including PEC).

Returns: A result code indicating success, PEC failure, or SPI failure.

◆ adbms6380_read_cell_voltages()

bool adbms6380_read_cell_voltages	(	SPI_InitConfig_t *	spi,
		strbuf_t *	cmd_buffer,
		uint8_t *	rx_buffer,
		float **	cell_voltages,
		int16_t **	cell_voltages_raw,
		bool	pec_error_flags[ADBMS6380_RDCV_CMD_COUNT],
		size_t	module_count,
		size_t	max_retries_on_pec_failure )

Read all cell voltages from each module.

Issues the RDCVALL command, converts raw values to volts, and fills the provided per-module cell voltage arrays. If any of the commands fail with a PEC error (even with the retries), the successfully read cell voltages will still be updated but the corresponding PEC error flag will be set.

Parameters

spi	SPI configuration used for the transfer.
cmd_buffer	Scratch buffer for command + PEC.
rx_buffer	RX buffer for raw bytes.
cell_voltages	Per-module arrays of cell voltages to populate.
cell_voltages_raw	Per-module arrays of raw cell voltage codes to populate.
pec_error_flags	Output array of flags indicating which command (if any) had PEC failures after retries are exhausted.
module_count	Number of modules in the daisy chain.
max_retries_on_pec_failure	Number of attempts to retry a read if a PEC failure is detected before giving up.

Returns: True on success, false on SPI failure.

◆ adbms6380_read_data()

adbms6380_read_result_t adbms6380_read_data	(	SPI_InitConfig_t *	spi,
		size_t	module_count,
		const uint8_t	cmd_buffer[ADBMS6380_COMMAND_PKT_SIZE],
		uint8_t *	rx_buffer )

Read a single-data-packet response per module.

Convenience wrapper around adbms6380_read() with ADBMS6380_SINGLE_DATA_PKT_SIZE as the expected response length per module.

Parameters

spi	SPI configuration used for the transfer.
module_count	Number of modules in the daisy chain.
cmd_buffer	Command buffer including PEC.
rx_buffer	Output buffer for received bytes.

Returns: A result code indicating success, PEC failure, or SPI failure.

◆ adbms6380_read_data_with_retries()

adbms6380_read_result_t adbms6380_read_data_with_retries	(	SPI_InitConfig_t *	spi,
		size_t	max_retries,
		size_t	module_count,
		const uint8_t	cmd_buffer[ADBMS6380_COMMAND_PKT_SIZE],
		uint8_t *	rx_buffer )

Read a single-data-packet response per module and retries on PEC failure.

Convenience wrapper around adbms6380_read_data() that retries the read up to a fixed number of attempts if a PEC failure is detected.

Parameters

spi	SPI configuration used for the transfer.
max_retries	Maximum number of read attempts if PEC failures occur.
module_count	Number of modules in the daisy chain.
cmd_buffer	Command buffer including PEC.
rx_buffer	Output buffer for received bytes.

Returns: A result code indicating success, PEC failure, or SPI failure.

◆ adbms6380_read_gpio_voltages()

bool adbms6380_read_gpio_voltages	(	SPI_InitConfig_t *	spi,
		strbuf_t *	cmd_buffer,
		uint8_t *	rx_buffer,
		float **	gpio_voltages,
		bool	pec_error_flags[ADBMS6380_RDAUX_CMD_COUNT],
		size_t	module_count,
		size_t	max_retries_on_pec_failure )

Read all GPIO/aux voltages from each module.

Issues RDAUXA/B/C/D commands, converts raw values to volts, and fills the provided per-module GPIO voltage arrays. If any of the commands fail with a PEC error (even with the retries), the successfully read GPIO voltages will still be updated but the corresponding PEC error flag will be set.

Parameters

spi	SPI configuration used for the transfer.
cmd_buffer	Scratch buffer for command + PEC.
rx_buffer	RX buffer for raw bytes.
gpio_voltages	Per-module arrays of GPIO voltages to populate.
pec_error_flags	Output array of flags indicating which command (if any) had PEC failures after retries are exhausted.
module_count	Number of modules in the daisy chain.
max_retries_on_pec_failure	Number of attempts to retry a read if a PEC failure is detected before giving up.

Returns: True on success, false on SPI failure.

◆ adbms6380_set_cs_high()

void adbms6380_set_cs_high ( SPI_InitConfig_t * spi )

Drive the ADBMS CS line to high.

Parameters

spi	SPI configuration containing the CS GPIO.

◆ adbms6380_set_cs_low()

void adbms6380_set_cs_low ( SPI_InitConfig_t * spi )

Drive the ADBMS CS line low.

Parameters

spi	SPI configuration containing the CS GPIO.

◆ adbms6380_wake()

void adbms6380_wake	(	SPI_InitConfig_t *	spi,
		size_t	module_count )

Wake a daisy-chained set of ADBMS devices.

Toggles CS with blocking delays to bring each module out of sleep.

Parameters

spi	SPI configuration containing the CS GPIO.
module_count	Number of modules in the daisy chain.

Functions

Detailed Description

Function Documentation

◆ adbms6380_adax()

◆ adbms6380_adcv()

◆ adbms6380_adsv()

◆ adbms6380_calculate_cfg_rega()

◆ adbms6380_calculate_cfg_regb()

◆ adbms6380_check_data_pec()

◆ adbms6380_extract_i16()

◆ adbms6380_get_threshold_voltage_cfg()

◆ adbms6380_prepare_command()

◆ adbms6380_prepare_data_packet()

◆ adbms6380_raw_to_v()

◆ adbms6380_read()

◆ adbms6380_read_cell_voltages()

◆ adbms6380_read_data()

◆ adbms6380_read_data_with_retries()

◆ adbms6380_read_gpio_voltages()

◆ adbms6380_set_cs_high()

◆ adbms6380_set_cs_low()

◆ adbms6380_wake()