foxBMS
1.1.1
The foxBMS Battery Management System API Documentation
|
Driver for the MAX17841B ASCI and MAX1785x monitoring chip. More...
#include "mxm_1785x.h"
#include "database.h"
#include "diag.h"
#include "mxm_1785x_tools.h"
#include "mxm_battery_management.h"
#include "mxm_registry.h"
#include "os.h"
#include "tsi.h"
Go to the source code of this file.
Macros | |
#define | MXM_VOLTAGE_READ_ARRAY_LENGTH (MXM_MAXIMUM_NR_OF_CELLS_PER_MODULE + 3u) |
#define | MXM_DELAY_BALANCING 10000u |
Delay in milliseconds before the balancing status is updated. More... | |
#define | MXM_REF_VAA_mV (3300u) |
VAA reference voltage (3.3V) More... | |
#define | MXM_I2C_MUX0_ADDRESS (0x4Cu) |
address of MUX0 More... | |
#define | MXM_I2C_MUX1_ADDRESS (0x4Du) |
address of MUX1 More... | |
Functions | |
static void | MXM_GetDataFrom5XStateMachine (MXM_MONITORING_INSTANCE_s *pInstance) |
Retrieves data from lower statemachine and writes it to the rx buffer. More... | |
static void | MXM_ParseVoltageLineReadall (const uint8_t *const kpkVoltRxBuffer, uint16_t voltRxBufferLength, uint8_t measurementOffset, MXM_CONVERSION_TYPE_e conversionType, uint16_t *pVoltagesTarget, MXM_MEASURE_TYPE_e meas_type, uint32_t full_scale_reference_mV) |
Parse voltage values from a READALL receive buffer into an array. More... | |
static STD_RETURN_TYPE_e | MXM_ParseVoltageReadall (const uint8_t *const kpkVoltageRxBuffer, uint16_t voltageRxBufferLength, MXM_DATA_STORAGE_s *datastorage, MXM_CONVERSION_TYPE_e conversionType) |
Parse a RX buffer containing voltage values. More... | |
static STD_RETURN_TYPE_e must_check_return | MXM_ParseVoltageReadallTest (MXM_MONITORING_INSTANCE_s *pInstance) |
Test the MXM_ParseVoltageReadall()-function. More... | |
static MXM_MONINTORING_STATE_e must_check_return | MXM_MonGetVoltages (MXM_MONITORING_INSTANCE_s *pState, MXM_REG_NAME_e regAddress) |
Encapsulation for reading voltages from a register. More... | |
static STD_RETURN_TYPE_e | MXM_ParseVoltagesIntoDB (const MXM_MONITORING_INSTANCE_s *const kpkInstance) |
Copies measured voltage data into the database. More... | |
static STD_RETURN_TYPE_e must_check_return | MXM_PreInitSelfCheck (MXM_MONITORING_INSTANCE_s *pState) |
Execute all preinit selfchecks. More... | |
static void | MXM_StateMachineOperation (MXM_MONITORING_INSTANCE_s *pState) |
State-Machine implementation for operation state. More... | |
static STD_RETURN_TYPE_e | MXM_ConstructBalancingBuffer (void) |
Fill the balancing datastructure. More... | |
static void | MXM_HandleStateWriteall (MXM_MONITORING_INSTANCE_s *pInstance, MXM_STATEMACHINE_OPERATION_STATES_e nextState) |
Handle the statemachine-transactions for a WRITEALL. More... | |
static bool must_check_return | MXM_HandleStateReadall (MXM_MONITORING_INSTANCE_s *pInstance, MXM_REG_NAME_e registerName, MXM_STATEMACHINE_OPERATION_STATES_e nextState) |
Handle the statemachine-transactions for a READALL. More... | |
static void | MXM_ProcessOpenWire (const MXM_MONITORING_INSTANCE_s *const kpkInstance, DATA_BLOCK_OPEN_WIRE_s *pDataOpenWire) |
Processes the retrieved information on openwire. More... | |
void | MXM_StateMachine (MXM_MONITORING_INSTANCE_s *pInstance) |
Battery monitoring driver for MAX1785x battery monitoring ICs. More... | |
Variables | |
static const MXM_REG_NAME_e | mxm_voltageCellAddresses [MXM_VOLTAGE_READ_ARRAY_LENGTH] |
Mapping of voltage registers. More... | |
static DATA_BLOCK_CELL_VOLTAGE_s | mxm_cellVoltages = {.header.uniqueId = DATA_BLOCK_ID_CELL_VOLTAGE_BASE} |
Local cell voltage data block. More... | |
static DATA_BLOCK_CELL_TEMPERATURE_s | mxm_cellTemperatures = {.header.uniqueId = DATA_BLOCK_ID_CELL_TEMPERATURE_BASE} |
Local cell temperature data block. More... | |
static DATA_BLOCK_OPEN_WIRE_s | mxm_openwire = {.header.uniqueId = DATA_BLOCK_ID_OPEN_WIRE_BASE} |
Local data structure for openwire results. More... | |
static DATA_BLOCK_BALANCING_CONTROL_s | mxm_balancingControl = {.header.uniqueId = DATA_BLOCK_ID_BALANCING_CONTROL} |
Balancing control. More... | |
static uint8_t | mxm_moduleBalancingIndex = {0} |
Module index in the daisy chain. More... | |
static uint8_t | mxm_evenCellsNeedBalancing = {0} |
Even cells group needs to be balanced. More... | |
static uint8_t | mxm_oddCellsNeedBalancing = {0} |
Odd cells group needs to be balanced. More... | |
static uint8_t | mxm_evenCellsBalancingProcessed = {0} |
Even cells group balancing done. More... | |
static uint8_t | mxm_oddCellsBalancingProcessed = {0} |
Odd cells group balancing done. More... | |
uint16_t | mxm_cellsToBalance = 0x00 |
Mask to control balacing. More... | |
static uint32_t | mxm_previousTime = {0} |
Timers used to guarantee that balancing is performed periodically. More... | |
static uint32_t | mxm_currentTime = {0} |
Timers used to guarantee that balancing is performed periodically. More... | |
Driver for the MAX17841B ASCI and MAX1785x monitoring chip.
SPDX-License-Identifier: BSD-3-Clause
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
We kindly request you to use one or more of the following phrases to refer to foxBMS in your hardware, software, documentation or advertising materials:
This file contains the main-state-machine that drives the monitoring ICs of the MAX1785x family by Maxim Integrated.
Definition in file mxm_1785x.c.
#define MXM_DELAY_BALANCING 10000u |
Delay in milliseconds before the balancing status is updated.
Definition at line 173 of file mxm_1785x.c.
#define MXM_REF_VAA_mV (3300u) |
VAA reference voltage (3.3V)
Definition at line 176 of file mxm_1785x.c.
#define MXM_VOLTAGE_READ_ARRAY_LENGTH (MXM_MAXIMUM_NR_OF_CELLS_PER_MODULE + 3u) |
length of voltage-read array
Definition at line 71 of file mxm_1785x.c.
|
static |
Fill the balancing datastructure.
This function fills the data-structure that describes which balancing channels of the monitoring ICs should be activated.
Definition at line 505 of file mxm_1785x.c.
|
static |
Retrieves data from lower statemachine and writes it to the rx buffer.
Definition at line 402 of file mxm_1785x.c.
|
static |
Handle the statemachine-transactions for a READALL.
Call this function and pass on the state-variable, the register to be read and the next state. The function will handle the communication with the lower state-machine and will transition into the next state, if the command has been sent successfully. Moreover it will return true when transitioning. The return value has to be checked and used to execute additional code if necessary.
[in,out] | pInstance | pointer to instance of the mxm monitoring state-machine |
[in] | registerName | register that should be read |
[in] | nextState | state that should be entered upon successful completion |
Definition at line 433 of file mxm_1785x.c.
|
static |
Handle the statemachine-transactions for a WRITEALL.
Before calling this function, update the command buffer of the state-variable. Then call this function and pass on the state-variable and the next state. The function will handle the communication with the lower state-machine and will transition into the next state, if the command has been sent successfully.
[in,out] | pInstance | pointer to instance of the mxm monitoring state-machine |
[in] | nextState | state that should be entered upon successful completion |
Definition at line 407 of file mxm_1785x.c.
|
static |
Encapsulation for reading voltages from a register.
This function encapsulates the request of state-changes and following conversion for the reading of an arbitrary measurement voltage of the daisy-chain. Its parameters are a variable for tracking the state of the underlying state-machines and the register address that has to be queried. It returns whether the action has been successful or not. In order to obtain all cell voltages this function has to be called for every relevant register address.
[in,out] | pState | pointer to the state-machine struct |
[in] | regAddress | register address that shall be queried |
Definition at line 1213 of file mxm_1785x.c.
|
static |
Parse voltage values from a READALL receive buffer into an array.
This function expects a preprocessed RX buffer with an answer to a READALL command. It will parse the data bytes from this message into an array structured like mxm_local_cellvoltages. The offset of the measured cell has to be defined. For example cell 1 has an offset of 0 and cell 4 has an offset of 3. The offset for the READALL command is always defined in reference to module 0.
If is_temperature_measurement is set to true, the function expects an auxiliary measurement (e.g. temperatures).
[in] | kpkVoltRxBuffer | array-pointer to the RX buffer |
[in] | voltRxBufferLength | length of the RX buffer |
[in] | measurementOffset | offset of the data in the cell voltage array (target) |
[in] | conversionType | type of conversion that has been used for the measured data |
[out] | pVoltagesTarget | array-pointer to the cell voltages array |
[in] | meas_type | whether the measurement is temperature or cell |
[in] | full_scale_reference_mV | reference voltage of full scale |
< buffer-length - length of start - length of end divided by two (LSB and MSB)
Definition at line 560 of file mxm_1785x.c.
|
static |
Parse a RX buffer containing voltage values.
This function parses a RX buffer containing the answer to a READALL command. It will check whether the message contains a READALL command and whether a supported register has been queried. Depending on the queried register, it will pass the proper parameters to MXM_ParseVoltageLineReadall(). The contained data from this message will be parsed into a struct structured like MXM_MONITORING_INSTANCE::localVoltages.
[in] | kpkVoltageRxBuffer | array-pointer to the RX buffer |
[in] | voltageRxBufferLength | length of the RX buffer |
[out] | datastorage | contains all measured voltages for local consumption in the module |
[in] | conversionType | type of conversion that has been used for the measured data |
Definition at line 618 of file mxm_1785x.c.
|
static |
Test the MXM_ParseVoltageReadall()-function.
Test the function MXM_ParseVoltageReadall() by passing predefined RX buffer to it and checking the outcome. This function writes to the variable MXM_MONITORING_INSTANCE::localVoltages and nulls it completely after execution. It is intended as a self-check that can be performed during startup of the driver.
Definition at line 850 of file mxm_1785x.c.
|
static |
Copies measured voltage data into the database.
This function copies the acquired voltage data from MXM_MONITORING_INSTANCE::localVoltages into the database-struct mxm_cellVoltages and copies this struct into the database. This action is required due to different data layouts. This driver always stores its cell-voltages in an array with 14*32 = 448 cells in order to reduce the amount of different configurations and variants.
This function maps these values into the database-struct which scales with the number of connected cells and monitoring ICs.
[in] | kpkInstance | pointer to the MXM_MONITORING_INSTANCE_s struct |
Definition at line 1243 of file mxm_1785x.c.
|
static |
Execute all preinit selfchecks.
Executes the following self-checks:
These self-checks do not need an initialized daisy-chain and can therefore be executed at startup of the state-machine.
After execution of each test, the return value is stored in the supplied state-struct. The function returns whether the self-check has successfully passed.
[in,out] | pState | pointer to the state-struct, will write status into |
Definition at line 1300 of file mxm_1785x.c.
|
static |
Processes the retrieved information on openwire.
Parses through a retrieved RX buffer and writes into the database.
[in,out] | kpkInstance | pointer to instance of the Maxim monitoring state-machine |
[in,out] | pDataOpenWire | pointer to the local copy of the data-base entry |
Definition at line 462 of file mxm_1785x.c.
void MXM_StateMachine | ( | MXM_MONITORING_INSTANCE_s * | pInstance | ) |
Battery monitoring driver for MAX1785x battery monitoring ICs.
This module supplies a driver for the Battery Monitoring ICs of the MAX1785x-family by Maxim Integrated.
Entry point for the module is the function MXM_Tick() in mxm_mic.c. It handles the measurement flow and the coordination of the underlying state-machines. Below this layer two state-machines are implemented.
The state-machine in mxm_battery_management.c is executed with the MXM_5XStateMachine()-function. This state-machine exposes commands of the Maxim Battery Management Protocol to the upper layers. Below, it translates these commands into state-changes for the underlying state-machine. This state-machine is implemented in mxm_17841b.c and executed with MXM_41BStateMachine(). It handles the register- and buffer-transactions required for the MAX17841B communication interface (Maxim calls this chip ASCI).
Main state-machine implementation
This state-machine handles the main state of the driver. It runs the self-check, initializes communication and then transitions into the operation state in which it executes the state-machine described in MXM_StateMachineOperation().
[in,out] | pInstance | used as both input and output (stores state-information, requests and intermediate values) |
Definition at line 1934 of file mxm_1785x.c.
|
static |
State-Machine implementation for operation state.
This state-machine contains the "program" with which the connected monitoring satellites are controlled. It is entered by MXM_StateMachine() once the daisy-chain has been initialized and is in operation state.
[in,out] | pState | used as both input and output (stores state-information, requests and intermediate values) |
Definition at line 1321 of file mxm_1785x.c.
|
static |
Balancing control.
This variable stores information about which cells need balancing
Definition at line 129 of file mxm_1785x.c.
uint16_t mxm_cellsToBalance = 0x00 |
Mask to control balacing.
Bitfield masked with register BALSWCTRL, 16 bits => up to 14 cells
Definition at line 165 of file mxm_1785x.c.
|
static |
Local cell temperature data block.
This local instance stores the measured cell temperatures.
Definition at line 120 of file mxm_1785x.c.
|
static |
Local cell voltage data block.
This local instance stores the measured cell voltages. In contrast to MXM_MONITORING_INSTANCE::localVoltages, the layout of this structure changes with the defined battery-system as it is described by the database_cfg.h. Mapping the values from MXM_MONITORING_INSTANCE::localVoltages to mxm_cellVoltages and copying these entries into the database is handled by MXM_ParseVoltagesIntoDB().
Definition at line 114 of file mxm_1785x.c.
|
static |
Timers used to guarantee that balancing is performed periodically.
Definition at line 169 of file mxm_1785x.c.
|
static |
Even cells group balancing done.
Odd cells can be balanced now
Definition at line 153 of file mxm_1785x.c.
|
static |
Even cells group needs to be balanced.
Even and odd cells can't be balanced at the same time
Definition at line 141 of file mxm_1785x.c.
|
static |
|
static |
Odd cells group balancing done.
Even cells can be balanced now
Definition at line 159 of file mxm_1785x.c.
|
static |
Odd cells group needs to be balanced.
Even and odd cells can't be balanced at the same time
Definition at line 147 of file mxm_1785x.c.
|
static |
Local data structure for openwire results.
Definition at line 123 of file mxm_1785x.c.
|
static |
Timers used to guarantee that balancing is performed periodically.
Definition at line 168 of file mxm_1785x.c.
|
static |
Mapping of voltage registers.
This array maps registers of the monitoring IC onto cell-numbers. The register values are defined in the MXM_REG_NAME_e enum. For now the length of this array is MXM_VOLTAGE_READ_ARRAY_LENGTH as it is enabled for the measurement of all cells, two AUX-voltages and one block voltage. This has to be adapted once this driver is enabled for general operation.
Definition at line 84 of file mxm_1785x.c.