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

Driver for the MAX17841B ASCI and MAX1785x analog front-end. More...

#include "general.h"
#include "mxm_1785x.h"
#include "afe_plausibility.h"
#include "database.h"
#include "diag.h"
#include "fassert.h"
#include "fstd_types.h"
#include "mxm_1785x_tools.h"
#include "mxm_battery_management.h"
#include "mxm_registry.h"
#include "os.h"
#include "tsi.h"
#include <math.h>
#include <stdbool.h>
#include <stdint.h>
Include dependency graph for mxm_1785x.c:

Go to the source code of this file.

Macros

#define MXM_OFFSET_CELL_1   (0u)
 
#define MXM_OFFSET_CELL_2   (1u)
 
#define MXM_OFFSET_CELL_3   (2u)
 
#define MXM_OFFSET_CELL_4   (3u)
 
#define MXM_OFFSET_CELL_5   (4u)
 
#define MXM_OFFSET_CELL_6   (5u)
 
#define MXM_OFFSET_CELL_7   (6u)
 
#define MXM_OFFSET_CELL_8   (7u)
 
#define MXM_OFFSET_CELL_9   (8u)
 
#define MXM_OFFSET_CELL_10   (9u)
 
#define MXM_OFFSET_CELL_11   (10u)
 
#define MXM_OFFSET_CELL_12   (11u)
 
#define MXM_OFFSET_CELL_13   (12u)
 
#define MXM_OFFSET_CELL_14   (13u)
 
#define MXM_OFFSET_AUX0   (0u)
 
#define MXM_OFFSET_AUX2   (2u)
 
#define MXM_OFFSET_AUX3   (3u)
 
#define MXM_OFFSET_BLOCK   (0u)
 
#define MXM_MAXIMUM_ERROR_COUNT   (10u)
 
#define MXM_TIMEOUT_RESET_ERROR_COUNTER_ms   (500)
 
#define MXM_TEST_BUFFER_MAXIMUM_LENGTH   (120u)
 
#define MXM_REF_VAA_mV   (3300u)
 VAA reference voltage (3.3V) More...
 

Functions

static void MXM_GetDataFrom5XStateMachine (MXM_MONITORING_INSTANCE_s *pInstance)
 Retrieves data from lower state machine 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 measurementType, uint32_t fullScaleReference_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 GEN_MUST_CHECK_RETURN MXM_ParseVoltageReadallTest (MXM_MONITORING_INSTANCE_s *pInstance)
 Test the MXM_ParseVoltageReadall()-function. More...
 
void MXM_CheckIfErrorCounterCanBeReset (MXM_MONITORING_INSTANCE_s *pInstance)
 Function that checks if the error counter can be reset. More...
 
void MXM_ErrorHandlerReset (MXM_MONITORING_INSTANCE_s *pInstance, bool immediateReset)
 This error handler is used as a last resort and tries a reset of the complete driver. More...
 
void MXM_HandleStateWriteall (MXM_MONITORING_INSTANCE_s *pInstance, MXM_STATEMACHINE_OPERATION_STATES_e nextState)
 Handle the state machine-transactions for a WRITEALL. More...
 
bool GEN_MUST_CHECK_RETURN MXM_HandleStateReadall (MXM_MONITORING_INSTANCE_s *pInstance, MXM_REG_NAME_e registerName, MXM_STATEMACHINE_OPERATION_STATES_e nextState)
 Handle the state machine-transactions for a READALL. More...
 
STD_RETURN_TYPE_e MXM_ProcessOpenWire (const MXM_MONITORING_INSTANCE_s *const kpkInstance)
 Processes the retrieved information on open wire. More...
 
STD_RETURN_TYPE_e MXM_ConstructBalancingBuffer (MXM_BALANCING_STATE_s *pBalancingInstance)
 Fill the balancing data structure. More...
 
STD_RETURN_TYPE_e MXM_ParseVoltagesIntoDB (const MXM_MONITORING_INSTANCE_s *const kpkInstance)
 Copies measured voltage data into the database. More...
 
void MXM_InitializeStateStruct (MXM_BALANCING_STATE_s *pBalancingInstance, MXM_MONITORING_INSTANCE_s *pMonitoringInstance)
 Initializes the state structs with default values. More...
 
STD_RETURN_TYPE_e MXM_PreInitSelfCheck (MXM_MONITORING_INSTANCE_s *pState)
 Execute all preinit selfchecks. More...
 
MXM_MONITORING_STATE_e GEN_MUST_CHECK_RETURN MXM_MonGetVoltages (MXM_MONITORING_INSTANCE_s *pState, MXM_REG_NAME_e regAddress)
 Encapsulation for reading voltages from a register. More...
 
void MXM_StateMachine (MXM_MONITORING_INSTANCE_s *pInstance)
 Main state-machine implementation. More...
 

Variables

static const AFE_PLAUSIBILITY_VALUES_s mxm_plausibleCellVoltages
 

Detailed Description

Driver for the MAX17841B ASCI and MAX1785x analog front-end.

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
2023-10-12 (date of last update)
Version
v1.6.0
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_MAXIMUM_ERROR_COUNT

#define MXM_MAXIMUM_ERROR_COUNT   (10u)

maximum number of errors that may occur before the next error triggers a reset

Definition at line 100 of file mxm_1785x.c.

◆ MXM_OFFSET_AUX0

#define MXM_OFFSET_AUX0   (0u)

storage offset for AUX0

Definition at line 94 of file mxm_1785x.c.

◆ MXM_OFFSET_AUX2

#define MXM_OFFSET_AUX2   (2u)

storage offset for AUX2

Definition at line 95 of file mxm_1785x.c.

◆ MXM_OFFSET_AUX3

#define MXM_OFFSET_AUX3   (3u)

storage offset for AUX3

Definition at line 96 of file mxm_1785x.c.

◆ MXM_OFFSET_BLOCK

#define MXM_OFFSET_BLOCK   (0u)

storage offset for block voltage

Definition at line 97 of file mxm_1785x.c.

◆ MXM_OFFSET_CELL_1

#define MXM_OFFSET_CELL_1   (0u)

storage offset for cell 1

Definition at line 80 of file mxm_1785x.c.

◆ MXM_OFFSET_CELL_10

#define MXM_OFFSET_CELL_10   (9u)

storage offset for cell 10

Definition at line 89 of file mxm_1785x.c.

◆ MXM_OFFSET_CELL_11

#define MXM_OFFSET_CELL_11   (10u)

storage offset for cell 11

Definition at line 90 of file mxm_1785x.c.

◆ MXM_OFFSET_CELL_12

#define MXM_OFFSET_CELL_12   (11u)

storage offset for cell 12

Definition at line 91 of file mxm_1785x.c.

◆ MXM_OFFSET_CELL_13

#define MXM_OFFSET_CELL_13   (12u)

storage offset for cell 13

Definition at line 92 of file mxm_1785x.c.

◆ MXM_OFFSET_CELL_14

#define MXM_OFFSET_CELL_14   (13u)

storage offset for cell 14

Definition at line 93 of file mxm_1785x.c.

◆ MXM_OFFSET_CELL_2

#define MXM_OFFSET_CELL_2   (1u)

storage offset for cell 2

Definition at line 81 of file mxm_1785x.c.

◆ MXM_OFFSET_CELL_3

#define MXM_OFFSET_CELL_3   (2u)

storage offset for cell 3

Definition at line 82 of file mxm_1785x.c.

◆ MXM_OFFSET_CELL_4

#define MXM_OFFSET_CELL_4   (3u)

storage offset for cell 4

Definition at line 83 of file mxm_1785x.c.

◆ MXM_OFFSET_CELL_5

#define MXM_OFFSET_CELL_5   (4u)

storage offset for cell 5

Definition at line 84 of file mxm_1785x.c.

◆ MXM_OFFSET_CELL_6

#define MXM_OFFSET_CELL_6   (5u)

storage offset for cell 6

Definition at line 85 of file mxm_1785x.c.

◆ MXM_OFFSET_CELL_7

#define MXM_OFFSET_CELL_7   (6u)

storage offset for cell 7

Definition at line 86 of file mxm_1785x.c.

◆ MXM_OFFSET_CELL_8

#define MXM_OFFSET_CELL_8   (7u)

storage offset for cell 8

Definition at line 87 of file mxm_1785x.c.

◆ MXM_OFFSET_CELL_9

#define MXM_OFFSET_CELL_9   (8u)

storage offset for cell 9

Definition at line 88 of file mxm_1785x.c.

◆ MXM_REF_VAA_mV

#define MXM_REF_VAA_mV   (3300u)

VAA reference voltage (3.3V)

Definition at line 116 of file mxm_1785x.c.

◆ MXM_TEST_BUFFER_MAXIMUM_LENGTH

#define MXM_TEST_BUFFER_MAXIMUM_LENGTH   (120u)

maximum length of a test buffer

Definition at line 106 of file mxm_1785x.c.

◆ MXM_TIMEOUT_RESET_ERROR_COUNTER_ms

#define MXM_TIMEOUT_RESET_ERROR_COUNTER_ms   (500)

timeout after which the error counter will be reset

Definition at line 103 of file mxm_1785x.c.

Function Documentation

◆ MXM_CheckIfErrorCounterCanBeReset()

void MXM_CheckIfErrorCounterCanBeReset ( MXM_MONITORING_INSTANCE_s pInstance)

Function that checks if the error counter can be reset.

Parameters
[in,out]pInstancepointer to the state struct

Definition at line 896 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_ConstructBalancingBuffer()

STD_RETURN_TYPE_e MXM_ConstructBalancingBuffer ( MXM_BALANCING_STATE_s pBalancingInstance)

Fill the balancing data structure.

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

Parameters
[in,out]pBalancingInstancepointer to the balancing state
Returns
STD_NOT_OK in case of invalid access

Definition at line 1024 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_ErrorHandlerReset()

void MXM_ErrorHandlerReset ( MXM_MONITORING_INSTANCE_s pInstance,
bool  immediateReset 
)

This error handler is used as a last resort and tries a reset of the complete driver.

A reset is done by setting the relevant flag in the state struct and waiting for the reset to occur (done by AFE on next tick). Before this last resort measure is taken, a error counter has to be counted up.

Parameters
[in,out]pInstancepointer to the state struct in order to write the reset flag
[in]immediateResetif set to true, a reset will be requested independently of the error counter

Definition at line 909 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 state machine and writes it to the rx buffer.

Definition at line 199 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_HandleStateReadall()

bool GEN_MUST_CHECK_RETURN MXM_HandleStateReadall ( MXM_MONITORING_INSTANCE_s pInstance,
MXM_REG_NAME_e  registerName,
MXM_STATEMACHINE_OPERATION_STATES_e  nextState 
)

Handle the state machine-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 948 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_HandleStateWriteall()

void MXM_HandleStateWriteall ( MXM_MONITORING_INSTANCE_s pInstance,
MXM_STATEMACHINE_OPERATION_STATES_e  nextState 
)

Handle the state machine-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 920 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_InitializeStateStruct()

void MXM_InitializeStateStruct ( MXM_BALANCING_STATE_s pBalancingInstance,
MXM_MONITORING_INSTANCE_s pMonitoringInstance 
)

Initializes the state structs with default values.

This function is called through the startup of the driver in order to ensure proper default values.

Parameters
[out]pBalancingInstanceinstance of the balancing state struct that shall be initialized
[out]pMonitoringInstanceinstance of the monitoring state struct that shall be initialized

Definition at line 1169 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_MonGetVoltages()

MXM_MONITORING_STATE_e GEN_MUST_CHECK_RETURN MXM_MonGetVoltages ( MXM_MONITORING_INSTANCE_s pState,
MXM_REG_NAME_e  regAddress 
)

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 1280 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  measurementType,
uint32_t  fullScaleReference_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]measurementTypewhether the measurement is temperature or cell
[in]fullScaleReference_mVreference voltage of full scale

Definition at line 207 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_s::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 278 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_ParseVoltageReadallTest()

static STD_RETURN_TYPE_e GEN_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_s::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 493 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_ParseVoltagesIntoDB()

STD_RETURN_TYPE_e MXM_ParseVoltagesIntoDB ( const MXM_MONITORING_INSTANCE_s *const  kpkInstance)

Copies measured voltage data into the database.

This function copies the acquired voltage data from MXM_MONITORING_INSTANCE_s::localVoltages into the database-struct mxm_tableCellVoltages 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

< invalid configuration!

Definition at line 1083 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_PreInitSelfCheck()

STD_RETURN_TYPE_e MXM_PreInitSelfCheck ( MXM_MONITORING_INSTANCE_s pState)

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 1242 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_ProcessOpenWire()

STD_RETURN_TYPE_e MXM_ProcessOpenWire ( const MXM_MONITORING_INSTANCE_s *const  kpkInstance)

Processes the retrieved information on open wire.

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

Parameters
[in,out]kpkInstancepointer to instance of the Maxim monitoring state-machine
Returns
returns the return value of the database write function DATA_Write1DataBlock()

Definition at line 979 of file mxm_1785x.c.

Here is the call graph for this function:

◆ MXM_StateMachine()

void MXM_StateMachine ( MXM_MONITORING_INSTANCE_s pInstance)

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 1319 of file mxm_1785x.c.

Here is the call graph for this function:

Variable Documentation

◆ mxm_plausibleCellVoltages

const AFE_PLAUSIBILITY_VALUES_s mxm_plausibleCellVoltages
static
Initial value:
= {
.maximumPlausibleVoltage_mV = 5000,
.minimumPlausibleVoltage_mV = -2500,
}

local definition of plausible cell voltage values

Definition at line 109 of file mxm_1785x.c.