foxBMS  1.1.0
The foxBMS Battery Management System API Documentation
mxm_1785x.c File Reference

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"
Include dependency graph for mxm_1785x.c:

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...
 

Detailed Description

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:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

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 product uses parts of foxBMS®″
  • ″This product includes parts of foxBMS®″
  • ″This product is derived from foxBMS®″
Author
foxBMS Team
Date
2019-01-15 (date of creation)
Updated
2021-07-14 (date of last update)
Prefix
MXM

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.

Macro Definition Documentation

◆ MXM_DELAY_BALANCING

#define MXM_DELAY_BALANCING   10000u

Delay in milliseconds before the balancing status is updated.

Definition at line 173 of file mxm_1785x.c.

◆ MXM_REF_VAA_mV

#define MXM_REF_VAA_mV   (3300u)

VAA reference voltage (3.3V)

Definition at line 176 of file mxm_1785x.c.

◆ MXM_VOLTAGE_READ_ARRAY_LENGTH

#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.

Function Documentation

◆ MXM_ConstructBalancingBuffer()

static STD_RETURN_TYPE_e MXM_ConstructBalancingBuffer ( void  )
static

Fill the balancing datastructure.

This function fills the data-structure that describes which balancing channels of the monitoring ICs should be activated.

Returns
STD_NOT_OK in case of invalid access

Definition at line 505 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_GetDataFrom5XStateMachine()

static void MXM_GetDataFrom5XStateMachine ( MXM_MONITORING_INSTANCE_s pInstance)
static

Retrieves data from lower statemachine and writes it to the rx buffer.

Definition at line 402 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_HandleStateReadall()

static bool must_check_return MXM_HandleStateReadall ( MXM_MONITORING_INSTANCE_s pInstance,
MXM_REG_NAME_e  registerName,
MXM_STATEMACHINE_OPERATION_STATES_e  nextState 
)
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.

Parameters
[in,out]pInstancepointer to instance of the mxm monitoring state-machine
[in]registerNameregister that should be read
[in]nextStatestate that should be entered upon successful completion
Returns
true when the state has been handled, false otherwise, use this to execute additional code when the message has been read.

Definition at line 433 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_HandleStateWriteall()

static void MXM_HandleStateWriteall ( MXM_MONITORING_INSTANCE_s pInstance,
MXM_STATEMACHINE_OPERATION_STATES_e  nextState 
)
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.

Parameters
[in,out]pInstancepointer to instance of the mxm monitoring state-machine
[in]nextStatestate that should be entered upon successful completion

Definition at line 407 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_MonGetVoltages()

static MXM_MONINTORING_STATE_e must_check_return MXM_MonGetVoltages ( MXM_MONITORING_INSTANCE_s pState,
MXM_REG_NAME_e  regAddress 
)
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.

Parameters
[in,out]pStatepointer to the state-machine struct
[in]regAddressregister address that shall be queried
Returns
current state of the action:
  • MXM_MON_STATE_PASS upon completion
  • MXM_MON_STATE_PENDING as long as the action is ongoing
  • MXM_MON_STATE_FAIL if the function failed and could not recover on its own

Definition at line 1213 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_ParseVoltageLineReadall()

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 
)
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).

Parameters
[in]kpkVoltRxBufferarray-pointer to the RX buffer
[in]voltRxBufferLengthlength of the RX buffer
[in]measurementOffsetoffset of the data in the cell voltage array (target)
[in]conversionTypetype of conversion that has been used for the measured data
[out]pVoltagesTargetarray-pointer to the cell voltages array
[in]meas_typewhether the measurement is temperature or cell
[in]full_scale_reference_mVreference 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.

Here is the call graph for this function:

◆ MXM_ParseVoltageReadall()

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 
)
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.

Parameters
[in]kpkVoltageRxBufferarray-pointer to the RX buffer
[in]voltageRxBufferLengthlength of the RX buffer
[out]datastoragecontains all measured voltages for local consumption in the module
[in]conversionTypetype of conversion that has been used for the measured data
Returns
STD_NOT_OK in the case that the RX buffer does not contain a valid message or the conversion-type is unknown, otherwise STD_OK

Definition at line 618 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_ParseVoltageReadallTest()

static STD_RETURN_TYPE_e must_check_return MXM_ParseVoltageReadallTest ( MXM_MONITORING_INSTANCE_s pInstance)
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.

Returns
STD_OK if the self-check has been performed successfully, otherwise STD_NOT_OK

Definition at line 850 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_ParseVoltagesIntoDB()

static STD_RETURN_TYPE_e MXM_ParseVoltagesIntoDB ( const MXM_MONITORING_INSTANCE_s *const  kpkInstance)
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.

Parameters
[in]kpkInstancepointer to the MXM_MONITORING_INSTANCE_s struct
Returns
STD_OK if the action was successful or STD_NOT_OK otherwise

Definition at line 1243 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_PreInitSelfCheck()

static STD_RETURN_TYPE_e must_check_return MXM_PreInitSelfCheck ( MXM_MONITORING_INSTANCE_s pState)
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.

Parameters
[in,out]pStatepointer to the state-struct, will write status into
Returns
STD_OK on success, STD_NOT_OK on failure, return value has to be used

Definition at line 1300 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_ProcessOpenWire()

static void MXM_ProcessOpenWire ( const MXM_MONITORING_INSTANCE_s *const  kpkInstance,
DATA_BLOCK_OPEN_WIRE_s pDataOpenWire 
)
static

Processes the retrieved information on openwire.

Parses through a retrieved RX buffer and writes into the database.

Parameters
[in,out]kpkInstancepointer to instance of the Maxim monitoring state-machine
[in,out]pDataOpenWirepointer to the local copy of the data-base entry

Definition at line 462 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_StateMachine()

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().

Parameters
[in,out]pInstanceused as both input and output (stores state-information, requests and intermediate values)

Definition at line 1934 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_StateMachineOperation()

static void MXM_StateMachineOperation ( MXM_MONITORING_INSTANCE_s pState)
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.

Parameters
[in,out]pStateused as both input and output (stores state-information, requests and intermediate values)

Definition at line 1321 of file mxm_1785x.c.

Here is the call graph for this function:

Variable Documentation

◆ mxm_balancingControl

DATA_BLOCK_BALANCING_CONTROL_s mxm_balancingControl = {.header.uniqueId = DATA_BLOCK_ID_BALANCING_CONTROL}
static

Balancing control.

This variable stores information about which cells need balancing

Definition at line 129 of file mxm_1785x.c.

◆ mxm_cellsToBalance

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.

◆ mxm_cellTemperatures

DATA_BLOCK_CELL_TEMPERATURE_s mxm_cellTemperatures = {.header.uniqueId = DATA_BLOCK_ID_CELL_TEMPERATURE_BASE}
static

Local cell temperature data block.

This local instance stores the measured cell temperatures.

Definition at line 120 of file mxm_1785x.c.

◆ mxm_cellVoltages

DATA_BLOCK_CELL_VOLTAGE_s mxm_cellVoltages = {.header.uniqueId = DATA_BLOCK_ID_CELL_VOLTAGE_BASE}
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.

◆ mxm_currentTime

uint32_t mxm_currentTime = {0}
static

Timers used to guarantee that balancing is performed periodically.

Definition at line 169 of file mxm_1785x.c.

◆ mxm_evenCellsBalancingProcessed

uint8_t mxm_evenCellsBalancingProcessed = {0}
static

Even cells group balancing done.

Odd cells can be balanced now

Definition at line 153 of file mxm_1785x.c.

◆ mxm_evenCellsNeedBalancing

uint8_t mxm_evenCellsNeedBalancing = {0}
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.

◆ mxm_moduleBalancingIndex

uint8_t mxm_moduleBalancingIndex = {0}
static

Module index in the daisy chain.

Used for balancing

Definition at line 135 of file mxm_1785x.c.

◆ mxm_oddCellsBalancingProcessed

uint8_t mxm_oddCellsBalancingProcessed = {0}
static

Odd cells group balancing done.

Even cells can be balanced now

Definition at line 159 of file mxm_1785x.c.

◆ mxm_oddCellsNeedBalancing

uint8_t mxm_oddCellsNeedBalancing = {0}
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.

◆ mxm_openwire

DATA_BLOCK_OPEN_WIRE_s mxm_openwire = {.header.uniqueId = DATA_BLOCK_ID_OPEN_WIRE_BASE}
static

Local data structure for openwire results.

Definition at line 123 of file mxm_1785x.c.

◆ mxm_previousTime

uint32_t mxm_previousTime = {0}
static

Timers used to guarantee that balancing is performed periodically.

Definition at line 168 of file mxm_1785x.c.

◆ mxm_voltageCellAddresses

const MXM_REG_NAME_e mxm_voltageCellAddresses[MXM_VOLTAGE_READ_ARRAY_LENGTH]
static
Initial value:

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.