Driver for the MAX17841B ASCI and MAX1785x monitoring chip. More...

#include "mxm_battery_management.h"
#include "diag.h"
#include "os.h"

Include dependency graph for mxm_battery_management.c:

Macros
#define	MXM_5X_ERROR_THRESHOLD (3u)

#define	MXM_5X_SLAVE_SHUTDOWN_TIMEOUT_MS (400u)

#define	MXM_5X_BIT_MASK_ONE_BYTE (0xFFu)

#define	MXM_5X_BIT_MASK_WRITE_DEVICE_ADDRESS ((uint16_t)0xF8u)
	bit masks for writing the device address in write device command More...


#define	HELLOALL_TX_LENGTH (3u)

#define	HELLOALL_RX_LENGTH HELLOALL_TX_LENGTH

Functions
static void	MXM_5XClearCommandBuffer (MXM_5X_INSTANCE_s *pInstance)
	Clear the command-buffer. More...

static STD_RETURN_TYPE_e	MXM_5XIsUserAccessibleRegister (uint8_t regAddress, MXM_MODEL_ID_e model)
	Check if a register address is user accessible. More...

static STD_RETURN_TYPE_e	MXM_52IsUserAccessibleRegister (uint8_t regAddress)
	Check if a register address is user accessible in MAX17852. More...

static STD_RETURN_TYPE_e	MXM_53IsUserAccessibleRegister (uint8_t regAddress)
	Check if a register address is user accessible in MAX17853. More...

static void	MXM_5XConstructCommandBufferHelloall (MXM_5X_INSTANCE_s *pInstance)
	clears the command buffer and writes HELLOALL into the buffer More...

static STD_RETURN_TYPE_e	MXM_5XConstructCommandBufferWriteall (MXM_5X_INSTANCE_s *pInstance)
	clears the command buffer and writes WRITEALL into the buffer More...

static STD_RETURN_TYPE_e	MXM_5XConstructCommandBufferWriteDevice (MXM_5X_INSTANCE_s *pInstance)
	clears the command buffer and writes a WRITEDEVICE message More...

static STD_RETURN_TYPE_e	MXM_5XConstructCommandBufferReadall (MXM_5X_INSTANCE_s *pInstance)
	clears the command buffer and writes READALL into the buffer More...

static void	MXM_5XHandle41BErrorState (MXM_5X_INSTANCE_s *pInstance)
	handles the error of the underlying state-machine (by resetting it and counting the error) More...

static void	MXM_5XTransitionToSubstate (MXM_5X_INSTANCE_s *pInstance, MXM_5X_SUBSTATES_e substate)
	sets all internal state variables so that upon next execution the next substate is entered More...

static void	MXM_5XRepeatCurrentSubstate (MXM_5X_INSTANCE_s *pInstance)
	repeat the current substate (by resetting to the entry state) More...

static void	MXM_5XSignalSuccess (MXM_5X_INSTANCE_s *pInstance)
	Signal that a chain of substates has been successfully handled. More...

static void	MXM_5XSignalError (MXM_5X_INSTANCE_s *pInstance)
	Signal that an error has occurred in a chain of substates. More...

static void	MXM_5XStateHandler41BFmeaCheck (MXM_5X_INSTANCE_s pInstance5x, MXM_41B_INSTANCE_s pInstance41b)
	Handle the state MXM_STATEMACH_5X_41B_FMEA_CHECK. More...

static void	MXM_5XStateHandlerInit (MXM_5X_INSTANCE_s pInstance5x, MXM_41B_INSTANCE_s pInstance41b)
	Handle the state MXM_STATEMACH_5X_INIT. More...

static void	MXM_5XStateHandlerWrite (MXM_5X_INSTANCE_s pInstance5x, MXM_41B_INSTANCE_s pInstance41b, bool writeDevice)
	Handle the states MXM_STATEMACH_5X_WRITEALL and MXM_STATEMACH_5X_WRITE_DEVICE. More...

static void	MXM_5XStateHandlerReadAll (MXM_5X_INSTANCE_s pInstance5x, MXM_41B_INSTANCE_s pInstance41b)
	Handle the state MXM_STATEMACH_5X_READALL. More...

void	MXM_5X_InitializeStateStruct (MXM_5X_INSTANCE_s *pInstance)
	Initializes the state struct with default values. More...

STD_RETURN_TYPE_e	MXM_5XGetRXBuffer (const MXM_5X_INSTANCE_s const kpkInstance, uint8_t rxBuffer, uint16_t rxBufferLength)
	Copy RX buffer into variable. More...

MXM_DC_BYTE_e	MXM_5XGetLastDCByte (const MXM_5X_INSTANCE_s *const kpkInstance)
	Returns the last received DC byte. More...

uint8_t	MXM_5XGetNumberOfSatellites (const MXM_5X_INSTANCE_s *const kpkInstance)
	Get number of satellites. More...

STD_RETURN_TYPE_e	MXM_5XGetNumberOfSatellitesGood (const MXM_5X_INSTANCE_s *const kpkInstance)
	Get the value of MXM_5X_INSTANCE_s::numberOfSatellitesIsGood. More...

STD_RETURN_TYPE_e	MXM_5XSetStateRequest (MXM_5X_INSTANCE_s pInstance5x, MXM_STATEMACHINE_5X_e state, MXM_5X_COMMAND_PAYLOAD_s commandPayload, MXM_5X_STATE_REQUEST_STATUS_e processed)
	Set state request for the Battery Management Statemachine. More...

void	MXM_5XStateMachine (MXM_41B_INSTANCE_s pInstance41b, MXM_5X_INSTANCE_s pInstance5x)
	Execute state-machine for Battery Management Protocol. More...

STD_RETURN_TYPE_e GEN_MUST_CHECK_RETURN	MXM_5XUserAccessibleAddressSpaceCheckerSelfCheck (void)
	runs a selfcheck for the address space check More...

Detailed Description

Driver for the MAX17841B ASCI and MAX1785x monitoring chip.

Copyright: © 2010 - 2022, 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-14 (date of creation)

Updated: 2022-10-27 (date of last update)

Version: v1.4.1

Prefix: MXM

def

Definition in file mxm_battery_management.c.

Macro Definition Documentation

◆ HELLOALL_RX_LENGTH

#define HELLOALL_RX_LENGTH HELLOALL_TX_LENGTH

length of the helloall command

Definition at line 67 of file mxm_battery_management.c.

◆ HELLOALL_TX_LENGTH

#define HELLOALL_TX_LENGTH (3u)

length of the helloall command

Definition at line 66 of file mxm_battery_management.c.

◆ MXM_5X_BIT_MASK_ONE_BYTE

#define MXM_5X_BIT_MASK_ONE_BYTE (0xFFu)

(uint8_t) one byte bit mask

Definition at line 77 of file mxm_battery_management.c.

◆ MXM_5X_BIT_MASK_WRITE_DEVICE_ADDRESS

#define MXM_5X_BIT_MASK_WRITE_DEVICE_ADDRESS ((uint16_t)0xF8u)

bit masks for writing the device address in write device command

Definition at line 82 of file mxm_battery_management.c.

◆ MXM_5X_ERROR_THRESHOLD

#define MXM_5X_ERROR_THRESHOLD (3u)

threshold above which an error handling procedure is triggered

Definition at line 71 of file mxm_battery_management.c.

◆ MXM_5X_SLAVE_SHUTDOWN_TIMEOUT_MS

#define MXM_5X_SLAVE_SHUTDOWN_TIMEOUT_MS (400u)

time in milliseconds that should be waited in order to ensure that the slaves shut off

Definition at line 74 of file mxm_battery_management.c.

Function Documentation

◆ MXM_52IsUserAccessibleRegister()

static STD_RETURN_TYPE_e MXM_52IsUserAccessibleRegister ( uint8_t regAddress )

static

Check if a register address is user accessible in MAX17852.

Checks if a register address is inside the user accessible memory range. This range is specified in the data sheet of the monitoring IC.

Parameters

[in] regAddress register address to be checked

Returns: STD_OK if the register address is good, otherwise STD_NOT_OK

Definition at line 281 of file mxm_battery_management.c.

◆ MXM_53IsUserAccessibleRegister()

static STD_RETURN_TYPE_e MXM_53IsUserAccessibleRegister ( uint8_t regAddress )

static

Check if a register address is user accessible in MAX17853.

Checks if a register address is inside the user accessible memory range. This range is specified in the data sheet of the monitoring IC as the following:

user memory is contained in the range 0x00 to 0x98
reserved addresses in the user address space are:
- 0x2C, 0x2D, 0x2E, 0x2F
- 0x46
- 0x84 through 0x8B
  Parameters
  
  [in] regAddress register address to be checked
  
  Returns
  STD_OK if the register address is good, otherwise STD_NOT_OK

Definition at line 299 of file mxm_battery_management.c.

◆ MXM_5X_InitializeStateStruct()

void MXM_5X_InitializeStateStruct ( MXM_5X_INSTANCE_s * pInstance )

Initializes the state struct with default values.

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

Parameters

[out] pInstance instance of the state struct that shall be initialized

Definition at line 924 of file mxm_battery_management.c.

◆ MXM_5XClearCommandBuffer()

static void MXM_5XClearCommandBuffer ( MXM_5X_INSTANCE_s * pInstance )

static

Clear the command-buffer.

Clears MXM_5X_INSTANCE_s::commandBuffer by writing 0x00 to every entry.

Parameters

[in,out] pInstance pointer to the state-struct

Returns: always return STD_OK

Definition at line 247 of file mxm_battery_management.c.

◆ MXM_5XConstructCommandBufferHelloall()

static void MXM_5XConstructCommandBufferHelloall ( MXM_5X_INSTANCE_s * pInstance )

static

clears the command buffer and writes HELLOALL into the buffer

Fills the command buffer with a HELLOALL message after having it cleaned.

Parameters

[in,out] pInstance pointer to the state-struct

Definition at line 316 of file mxm_battery_management.c.

Here is the call graph for this function:

◆ MXM_5XConstructCommandBufferReadall()

static STD_RETURN_TYPE_e MXM_5XConstructCommandBufferReadall ( MXM_5X_INSTANCE_s * pInstance )

static

clears the command buffer and writes READALL into the buffer

Fills the command buffer with a READALL command. This command retrieves the LSB and MSB of exactly one register of every device in the daisy-chain. The data to be written has to be set before calling this function in MXM_5X_INSTANCE_s::commandPayload.

Parameters

[in,out] pInstance pointer to the state-struct

Returns: STD_OK if an accessible register address has been selected, STD_NOT_OK if not.

Definition at line 385 of file mxm_battery_management.c.

Here is the call graph for this function:

◆ MXM_5XConstructCommandBufferWriteall()

static STD_RETURN_TYPE_e MXM_5XConstructCommandBufferWriteall ( MXM_5X_INSTANCE_s * pInstance )

static

clears the command buffer and writes WRITEALL into the buffer

Fills the command buffer with a WRITEALL command. This command writes the same lsb and msb to every satellite in the daisy-chain in the same register. The data to be written has to be set before calling this function in MXM_5X_INSTANCE_s::commandPayload.

Parameters

[in,out] pInstance pointer to the state-struct

Returns: STD_OK if an accessible register address has been selected, STD_NOT_OK if not.

Definition at line 325 of file mxm_battery_management.c.

Here is the call graph for this function:

◆ MXM_5XConstructCommandBufferWriteDevice()

static STD_RETURN_TYPE_e MXM_5XConstructCommandBufferWriteDevice ( MXM_5X_INSTANCE_s * pInstance )

static

clears the command buffer and writes a WRITEDEVICE message

Fills the command buffer with a WRITEDEVICE message. This message is addressed to one specific device in the daisy-chain. Therefore the address of the device has to be supplied together with the register and the data that should be written. The data to be written has to be set before calling this function in MXM_5X_INSTANCE_s::commandPayload.

Parameters

[in,out] pInstance pointer to the state-struct

Returns: STD_OK if an accessible register address has been selected, STD_NOT_OK if not.

Definition at line 351 of file mxm_battery_management.c.

Here is the call graph for this function:

◆ MXM_5XGetLastDCByte()

MXM_DC_BYTE_e MXM_5XGetLastDCByte ( const MXM_5X_INSTANCE_s *const kpkInstance )

Returns the last received DC byte.

Parameters

[in] kpkInstance pointer to the instance struct

Definition at line 975 of file mxm_battery_management.c.

◆ MXM_5XGetNumberOfSatellites()

uint8_t MXM_5XGetNumberOfSatellites ( const MXM_5X_INSTANCE_s *const kpkInstance )

Get number of satellites.

Getter-function for the number of satellites (variable MXM_5X_INSTANCE_s::numberOfSatellites).

Parameters

[in] kpkInstance pointer to the state struct

Returns: value of MXM_5X_INSTANCE_s::numberOfSatellites

Definition at line 980 of file mxm_battery_management.c.

◆ MXM_5XGetNumberOfSatellitesGood()

STD_RETURN_TYPE_e MXM_5XGetNumberOfSatellitesGood ( const MXM_5X_INSTANCE_s *const kpkInstance )

Get the value of MXM_5X_INSTANCE_s::numberOfSatellitesIsGood.

Parameters

[in] kpkInstance pointer to the instance struct

Returns: MXM_5X_INSTANCE_s::numberOfSatellitesIsGood

Definition at line 987 of file mxm_battery_management.c.

◆ MXM_5XGetRXBuffer()

STD_RETURN_TYPE_e MXM_5XGetRXBuffer	(	const MXM_5X_INSTANCE_s *const	kpkInstance,
		uint8_t *	rxBuffer,
		uint16_t	rxBufferLength
	)

Copy RX buffer into variable.

This function copies the RX buffer which is locally available in the MXM_5XStateMachine() into a supplied array pointer. It will make sure that both the length of the local as also the supplied length of the RX buffer are not violated. In case of the supplied RX buffer being longer than the locally available one, the remaining entries of the buffer will be filled with 0.

Parameters

[in,out]	kpkInstance	pointer to the state-struct
[in]	rxBuffer	array-pointer to a RX buffer that shall be filled
[in]	rxBufferLength	length of the supplied array

Returns: STD_NOT_OK for rxBuffer being a NULL_PTR or rxBufferLength having length 0

Definition at line 952 of file mxm_battery_management.c.

◆ MXM_5XHandle41BErrorState()

static void MXM_5XHandle41BErrorState ( MXM_5X_INSTANCE_s * pInstance )

static

handles the error of the underlying state-machine (by resetting it and counting the error)

Parameters

[in,out] pInstance pointer to the state-struct

Definition at line 417 of file mxm_battery_management.c.

◆ MXM_5XIsUserAccessibleRegister()

static STD_RETURN_TYPE_e MXM_5XIsUserAccessibleRegister	(	uint8_t	regAddress,
		MXM_MODEL_ID_e	model
	)

static

Check if a register address is user accessible.

Checks if a register address is inside the user accessible memory range. This range is specified in the data sheet of the monitoring IC as following:

user memory is contained in the range 0x00 to 0x98
reserved addresses in the user address space are:
- 0x2C, 0x2D, 0x2E, 0x2F
- 0x46
- 0x84 through 0x8B
  Parameters
  
  [in] regAddress register address to be checked
  
  [in] model model id of the IC that shall be addressed
  
  Returns
  STD_OK if the register address is good, otherwise STD_NOT_OK

Definition at line 255 of file mxm_battery_management.c.

Here is the call graph for this function:

◆ MXM_5XRepeatCurrentSubstate()

static void MXM_5XRepeatCurrentSubstate ( MXM_5X_INSTANCE_s * pInstance )

static

repeat the current substate (by resetting to the entry state)

Parameters

[out] pInstance pointer to the state-struct

Definition at line 436 of file mxm_battery_management.c.

◆ MXM_5XSetStateRequest()

STD_RETURN_TYPE_e MXM_5XSetStateRequest	(	MXM_5X_INSTANCE_s *	pInstance5x,
		MXM_STATEMACHINE_5X_e	state,
		MXM_5X_COMMAND_PAYLOAD_s	commandPayload,
		MXM_5X_STATE_REQUEST_STATUS_e *	processed
	)

Set state request for the Battery Management Statemachine.

This function sets the state requests for the MXM_5XStateMachine().

Parameters

[in,out]	pInstance5x	pointer to the 5x state
[in]	state	State that is requested
[in]	commandPayload	additional payload that is handled by the state
[in,out]	processed	pointer to the status of the request

Returns: STD_OK if the request has been successfully placed, STD_NOT_OK if not

Definition at line 992 of file mxm_battery_management.c.

◆ MXM_5XSignalError()

static void MXM_5XSignalError ( MXM_5X_INSTANCE_s * pInstance )

static

Signal that an error has occurred in a chain of substates.

Parameters

[out] pInstance pointer to the state-struct

Definition at line 451 of file mxm_battery_management.c.

Here is the call graph for this function:

◆ MXM_5XSignalSuccess()

static void MXM_5XSignalSuccess ( MXM_5X_INSTANCE_s * pInstance )

static

Signal that a chain of substates has been successfully handled.

Parameters

[out] pInstance pointer to the state-struct

Definition at line 442 of file mxm_battery_management.c.

Here is the call graph for this function:

◆ MXM_5XStateHandler41BFmeaCheck()

static void MXM_5XStateHandler41BFmeaCheck	(	MXM_5X_INSTANCE_s *	pInstance5x,
		MXM_41B_INSTANCE_s *	pInstance41b
	)

static

Handle the state MXM_STATEMACH_5X_41B_FMEA_CHECK.

Parameters

[in,out]	pInstance5x	pointer to the state-struct of the battery management state machine
[in,out]	pInstance41b	pointer to the state-struct of the bridge IC

Definition at line 460 of file mxm_battery_management.c.

Here is the call graph for this function:

◆ MXM_5XStateHandlerInit()

static void MXM_5XStateHandlerInit	(	MXM_5X_INSTANCE_s *	pInstance5x,
		MXM_41B_INSTANCE_s *	pInstance41b
	)

static

Handle the state MXM_STATEMACH_5X_INIT.

Parameters

[in,out]	pInstance5x	pointer to the state-struct of the battery management state machine
[in,out]	pInstance41b	pointer to the state-struct of the bridge IC

Definition at line 489 of file mxm_battery_management.c.

Here is the call graph for this function:

◆ MXM_5XStateHandlerReadAll()

static void MXM_5XStateHandlerReadAll	(	MXM_5X_INSTANCE_s *	pInstance5x,
		MXM_41B_INSTANCE_s *	pInstance41b
	)

static

Handle the state MXM_STATEMACH_5X_READALL.

Parameters

[in,out]	pInstance5x	pointer to the state-struct of the battery management state machine
[in,out]	pInstance41b	pointer to the state-struct of the bridge IC

Definition at line 861 of file mxm_battery_management.c.

Here is the call graph for this function:

◆ MXM_5XStateHandlerWrite()

static void MXM_5XStateHandlerWrite	(	MXM_5X_INSTANCE_s *	pInstance5x,
		MXM_41B_INSTANCE_s *	pInstance41b,
		bool	writeDevice
	)

static

Handle the states MXM_STATEMACH_5X_WRITEALL and MXM_STATEMACH_5X_WRITE_DEVICE.

Parameters

[in,out]	pInstance5x	pointer to the state-struct of the battery management state machine
[in,out]	pInstance41b	pointer to the state-struct of the bridge IC
[in]	writeDevice	true: write device, false: write all

Definition at line 816 of file mxm_battery_management.c.

Here is the call graph for this function:

◆ MXM_5XStateMachine()

void MXM_5XStateMachine	(	MXM_41B_INSTANCE_s *	pInstance41b,
		MXM_5X_INSTANCE_s *	pInstance5x
	)

Execute state-machine for Battery Management Protocol.

This function executes the state-machine that exposes an interface for the Maxim Battery Management Protocol for monitoring ICs of the MAX1785x family.

Definition at line 1029 of file mxm_battery_management.c.

Here is the call graph for this function:

◆ MXM_5XTransitionToSubstate()

static void MXM_5XTransitionToSubstate	(	MXM_5X_INSTANCE_s *	pInstance,
		MXM_5X_SUBSTATES_e	substate
	)

static

sets all internal state variables so that upon next execution the next substate is entered

Parameters

[out]	pInstance	pointer to the state-struct
[in]	substate	identifier of the next substate

Definition at line 426 of file mxm_battery_management.c.

◆ MXM_5XUserAccessibleAddressSpaceCheckerSelfCheck()

STD_RETURN_TYPE_e GEN_MUST_CHECK_RETURN MXM_5XUserAccessibleAddressSpaceCheckerSelfCheck ( void )

runs a selfcheck for the address space check

Runs a selfcheck for the function which is checking if a register address is inside the user accessible address space of the monitoring IC.

Returns: STD_OK if the selfcheck has been successful

Definition at line 1071 of file mxm_battery_management.c.

Here is the call graph for this function:

[in]	regAddress	register address to be checked
[in]	model	model id of the IC that shall be addressed

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ HELLOALL_RX_LENGTH

◆ HELLOALL_TX_LENGTH

◆ MXM_5X_BIT_MASK_ONE_BYTE

◆ MXM_5X_BIT_MASK_WRITE_DEVICE_ADDRESS

◆ MXM_5X_ERROR_THRESHOLD

◆ MXM_5X_SLAVE_SHUTDOWN_TIMEOUT_MS

Function Documentation

◆ MXM_52IsUserAccessibleRegister()

◆ MXM_53IsUserAccessibleRegister()

◆ MXM_5X_InitializeStateStruct()

◆ MXM_5XClearCommandBuffer()

◆ MXM_5XConstructCommandBufferHelloall()

◆ MXM_5XConstructCommandBufferReadall()

◆ MXM_5XConstructCommandBufferWriteall()

◆ MXM_5XConstructCommandBufferWriteDevice()

◆ MXM_5XGetLastDCByte()

◆ MXM_5XGetNumberOfSatellites()

◆ MXM_5XGetNumberOfSatellitesGood()

◆ MXM_5XGetRXBuffer()

◆ MXM_5XHandle41BErrorState()

◆ MXM_5XIsUserAccessibleRegister()

◆ MXM_5XRepeatCurrentSubstate()

◆ MXM_5XSetStateRequest()

◆ MXM_5XSignalError()

◆ MXM_5XSignalSuccess()

◆ MXM_5XStateHandler41BFmeaCheck()

◆ MXM_5XStateHandlerInit()

◆ MXM_5XStateHandlerReadAll()

◆ MXM_5XStateHandlerWrite()

◆ MXM_5XStateMachine()

◆ MXM_5XTransitionToSubstate()

◆ MXM_5XUserAccessibleAddressSpaceCheckerSelfCheck()