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

#include "general.h"
#include "database_cfg.h"
#include "mxm_cfg.h"
#include "fstd_types.h"
#include "mxm_17841b.h"
#include "mxm_1785x_tools.h"
#include "mxm_basic_defines.h"
#include "mxm_battery_management.h"
#include "mxm_crc8.h"
#include <stdbool.h>
#include <stdint.h>

Include dependency graph for mxm_1785x.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	MXM_THRESHOLD_DIAGNOSTIC_AFTER_CYCLES (10u)
	Battery monitoring driver for MAX1785x battery monitoring ICs. More...

#define	MXM_VOLTAGE_READ_ARRAY_LENGTH (MXM_MAXIMUM_NR_OF_CELLS_PER_MODULE + 3u)

#define	MXM_CELLS_IN_LSB (8u)

#define	MXM_REF_UNIPOLAR_CELL_mV (5000u)

Functions
void	MXM_StateMachine (MXM_MONITORING_INSTANCE_s *pInstance)
	Main state-machine implementation. More...

void	MXM_InitializeStateStruct (MXM_BALANCING_STATE_s pBalancingInstance, MXM_MONITORING_INSTANCE_s pMonitoringInstance)
	Initializes the state structs with default values. More...

void	MXM_CheckIfErrorCounterCanBeReset (MXM_MONITORING_INSTANCE_s *pInstance)
	Function that checks if the error counter can be reset. More...

STD_RETURN_TYPE_e	MXM_ConstructBalancingBuffer (MXM_BALANCING_STATE_s *pBalancingInstance)
	Fill the balancing data structure. 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...

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_StateMachineOperation (MXM_MONITORING_INSTANCE_s *pState)
	State-Machine implementation for operation state. 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...

STD_RETURN_TYPE_e	MXM_ParseVoltagesIntoDB (const MXM_MONITORING_INSTANCE_s *const kpkInstance)
	Copies measured voltage data into the database. More...

MXM_MODEL_ID_e	MXM_GetModelIdOfDaisyChain (void)
	returns the model ID of the daisy chain More...

STD_RETURN_TYPE_e	MXM_PreInitSelfCheck (MXM_MONITORING_INSTANCE_s *pState)
	Execute all preinit selfchecks. More...

Detailed Description

Headers for the driver for the MAX17841B ASCI and MAX1785x analog front-end.

Copyright: © 2010 - 2023, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V. All rights reserved.

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:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
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.
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

def

Definition in file mxm_1785x.h.

Macro Definition Documentation

◆ MXM_CELLS_IN_LSB

#define MXM_CELLS_IN_LSB (8u)

number of cells that are in the LSB register of i.e. pin open diagnostic

Definition at line 108 of file mxm_1785x.h.

◆ MXM_REF_UNIPOLAR_CELL_mV

#define MXM_REF_UNIPOLAR_CELL_mV (5000u)

unipolar full-scale reference value for cell voltage in mV

Definition at line 111 of file mxm_1785x.h.

◆ MXM_THRESHOLD_DIAGNOSTIC_AFTER_CYCLES

#define MXM_THRESHOLD_DIAGNOSTIC_AFTER_CYCLES (10u)

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_afe.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 analog front-end ASCI). threshold of iterations after which a diagnostic cycle is entered by the state-machine

Definition at line 102 of file mxm_1785x.h.

◆ 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 105 of file mxm_1785x.h.

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] pInstance pointer 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] pBalancingInstance pointer 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]	pInstance	pointer to the state struct in order to write the reset flag
[in]	immediateReset	if 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_GetModelIdOfDaisyChain()

MXM_MODEL_ID_e MXM_GetModelIdOfDaisyChain ( void )

returns the model ID of the daisy chain

this function is to be implemented by the driver in order to tell the rest of the driver which model is used. Currently, this implementation does not support mixed model daisy-chains.

Returns: model ID of daisy-chain

Definition at line 96 of file mxm_17852.c.

◆ 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]	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

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]	pInstance	pointer to instance of the mxm monitoring state-machine
[in]	nextState	state 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]	pBalancingInstance	instance of the balancing state struct that shall be initialized
[out]	pMonitoringInstance	instance 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]	pState	pointer to the state-machine struct
[in]	regAddress	register 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_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] kpkInstance pointer 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] pState pointer 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] kpkInstance pointer 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] pInstance used 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:

◆ MXM_StateMachineOperation()

void MXM_StateMachineOperation ( MXM_MONITORING_INSTANCE_s * pState )

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] pState used as both input and output (stores state-information, requests and intermediate values)

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 100 of file mxm_17852.c.

Here is the call graph for this function:

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ MXM_CELLS_IN_LSB

◆ MXM_REF_UNIPOLAR_CELL_mV

◆ MXM_THRESHOLD_DIAGNOSTIC_AFTER_CYCLES

◆ MXM_VOLTAGE_READ_ARRAY_LENGTH

Function Documentation

◆ MXM_CheckIfErrorCounterCanBeReset()

◆ MXM_ConstructBalancingBuffer()

◆ MXM_ErrorHandlerReset()

◆ MXM_GetModelIdOfDaisyChain()

◆ MXM_HandleStateReadall()

◆ MXM_HandleStateWriteall()

◆ MXM_InitializeStateStruct()

◆ MXM_MonGetVoltages()

◆ MXM_ParseVoltagesIntoDB()

◆ MXM_PreInitSelfCheck()

◆ MXM_ProcessOpenWire()

◆ MXM_StateMachine()

◆ MXM_StateMachineOperation()