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

#include "mxm_17841b.h"
#include "fassert.h"
#include "fstd_types.h"
#include "mxm_41b_register_map.h"
#include "mxm_bitextract.h"
#include "os.h"
#include <stdint.h>

Include dependency graph for mxm_17841b.c:

Go to the source code of this file.

Macros
#define	MXM_41B_BIT_SHIFT_HALF_BYTE (4u)

#define	MXM_41B_BIT_MASK_LOW_NIBBLE (0xFu)

#define	MXM_41B_BIT_MASK_HIGH_NIBBLE (0xF0u)

#define	MXM_41B_BIT_MASK_ONE_BYTE (0xFFu)

#define	MXM_41B_WAIT_COUNTER_THRESHOLD (75u)

#define	MXM_41B_BRIDGE_RESET_TIME_MS (100u)

#define	MXM_41B_CONFIG_REGISTER_LENGTH (7u)

Functions
static STD_RETURN_TYPE_e	MXM_41BRegisterWrite (MXM_41B_INSTANCE_s pInstance, MXM_41B_REG_ADD_t command, const uint8_t const kpkPayload, uint8_t lengthPayload)
	Write one or multiple registers of MAX17841B. More...

static STD_RETURN_TYPE_e	MXM_41BRegisterRead (MXM_41B_INSTANCE_s pInstance, MXM_41B_REG_ADD_t command, uint16_t pRxBuffer, uint8_t length)
	Read one or multiple registers of MAX17841B. More...

static STD_RETURN_TYPE_e	MXM_41BConfigRegisterWrite (MXM_41B_INSTANCE_s *pInstance)
	Write the config register of MAX17841B. More...

static STD_RETURN_TYPE_e	MXM_41BBufferWrite (MXM_41B_INSTANCE_s pInstance, const uint16_t const kpkMessage, uint8_t messageLength, uint8_t extendMessage)
	Write a buffer transaction to MAX17841B. More...

static void	MXM_41BTransitionToIdleSuccess (MXM_41B_INSTANCE_s *pInstance)
	Transition into idle, mark as successful. More...

static void	MXM_41BTransitionToIdleError (MXM_41B_INSTANCE_s *pInstance)
	Transition into idle, mark as an error occurred. More...

static void	MXM_41BInitializeRegisterCopies (MXM_41B_INSTANCE_s *pInstance)
	Reset register copies to default. More...

static void	MXM_41BStateHandlerInit (MXM_41B_INSTANCE_s *pInstance)
	init state handler More...

static void	MXM_41BStateHandlerGetVersion (MXM_41B_INSTANCE_s *pInstance)
	state handler for "get version" More...

static void	MXM_41BStateHandlerIdle (MXM_41B_INSTANCE_s *pInstance)
	state handler for "idle" More...

static void	MXM_41BStateHandlerWriteConfAndIntRegister (MXM_41B_INSTANCE_s *pInstance)
	state handler for "write conf and int register" More...

static void	MXM_41BStateHandlerReadStatusRegister (MXM_41B_INSTANCE_s *pInstance)
	state handler for "read status register" More...

static void	MXM_41BStateHandlerUartTransaction (MXM_41B_INSTANCE_s *pInstance)
	state handler for "uart transaction" More...

static void	MXM_41BStateHandlerCheckFmea (MXM_41B_INSTANCE_s *pInstance)
	state handler for "check fmea" More...

static void	MXM_41BStateHandlerClearReceiveBuffer (MXM_41B_INSTANCE_s *pInstance)
	state handler for "clear receive buffer" More...

static void	MXM_41BStateHandlerClearTransmitBuffer (MXM_41B_INSTANCE_s *pInstance)
	state handler for "clear transmit buffer" More...

STD_RETURN_TYPE_e	MXM_41BSetStateRequest (MXM_41B_INSTANCE_s pInstance, MXM_STATEMACH_41B_e state, uint16_t pPayload, uint8_t payloadLength, uint8_t extendMessageBytes, uint16_t pRxBuffer, uint16_t rxBufferLength, MXM_41B_STATE_REQUEST_STATUS_e processed)
	Set state transition for MAX17841B-state-machine. More...

STD_RETURN_TYPE_e	MXM_41BWriteRegisterFunction (MXM_41B_INSTANCE_s *pInstance, MXM_41B_REG_FUNCTION_e registerFunction, MXM_41B_REG_BIT_VALUE value)
	Write a register function. More...

STD_RETURN_TYPE_e	MXM_41BReadRegisterFunction (const MXM_41B_INSTANCE_s const kpkInstance, MXM_41B_REG_FUNCTION_e registerFunction, MXM_41B_REG_BIT_VALUE pValue)
	Read the value of a register function. More...

void	MXM_41BStateMachine (MXM_41B_INSTANCE_s *pInstance)
	Execute state-machine for the MAX17841B. More...

void	MXM_41BInitializeStateStruct (MXM_41B_INSTANCE_s *pInstance)
	Initializes the state struct with default values. More...

Detailed Description

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: 2018-12-14 (date of creation)

Updated: 2023-10-12 (date of last update)

Version: v1.6.0

Prefix: MXM

def

Definition in file mxm_17841b.c.

Macro Definition Documentation

◆ MXM_41B_BIT_MASK_HIGH_NIBBLE

#define MXM_41B_BIT_MASK_HIGH_NIBBLE (0xF0u)

high nibble (of uint8_t) bit mask

Definition at line 76 of file mxm_17841b.c.

◆ MXM_41B_BIT_MASK_LOW_NIBBLE

#define MXM_41B_BIT_MASK_LOW_NIBBLE (0xFu)

low nibble (of uint8_t) bit mask

Definition at line 73 of file mxm_17841b.c.

◆ MXM_41B_BIT_MASK_ONE_BYTE

#define MXM_41B_BIT_MASK_ONE_BYTE (0xFFu)

(uint8_t) one byte bit mask

Definition at line 79 of file mxm_17841b.c.

◆ MXM_41B_BIT_SHIFT_HALF_BYTE

#define MXM_41B_BIT_SHIFT_HALF_BYTE (4u)

bit shift half byte length

Definition at line 70 of file mxm_17841b.c.

◆ MXM_41B_BRIDGE_RESET_TIME_MS

#define MXM_41B_BRIDGE_RESET_TIME_MS (100u)

time interval that shall ensure that the bridge IC is completely reset in ms

Definition at line 90 of file mxm_17841b.c.

◆ MXM_41B_CONFIG_REGISTER_LENGTH

#define MXM_41B_CONFIG_REGISTER_LENGTH (7u)

default config register bank length

Length of the array that writes the registers referenced in mxm_41B_reg_default_values in MXM_41BStateHandlerInit().

Definition at line 97 of file mxm_17841b.c.

◆ MXM_41B_WAIT_COUNTER_THRESHOLD

#define MXM_41B_WAIT_COUNTER_THRESHOLD (75u)

threshold above which a reset in this driver occurs in case of hangup

Definition at line 82 of file mxm_17841b.c.

Function Documentation

◆ MXM_41BBufferWrite()

static STD_RETURN_TYPE_e MXM_41BBufferWrite	(	MXM_41B_INSTANCE_s *	pInstance,
		const uint16_t *const	kpkMessage,
		uint8_t	messageLength,
		uint8_t	extendMessage
	)

static

Write a buffer transaction to MAX17841B.

Writes into the load-queue-buffer. The supplied-message-length marks the length of the Battery Management Protocol message without any stuffing-bytes for read-commands. The extendMessage parameter describes with how much bytes the command shall be stretched. This number will be added to the length of the command and written into the length field of the buffer. After this action the user has to select the next load queue with the appropriate command in order to mark the load queue as sendable.

Parameters

[in,out]	pInstance	pointer to the state of the MAX17841B-state-machine
[in]	kpkMessage	pointer to an array containing the message
[in]	messageLength	length of the supplied array
[in]	extendMessage	stretch the message by number of bytes

Returns: STD_NOT_OK for inconsistent input or a blocked SPI interface, otherwise STD_OK

Definition at line 374 of file mxm_17841b.c.

Here is the call graph for this function:

◆ MXM_41BConfigRegisterWrite()

static STD_RETURN_TYPE_e MXM_41BConfigRegisterWrite ( MXM_41B_INSTANCE_s * pInstance )

static

Write the config register of MAX17841B.

This functions writes the config registers with the values from the local register copies. It puts together a buffer from these register values and calls MXM_41BRegisterWrite() with this data. Calling this function will clear the interrupt registers and reset them to their default values (which is MXM_41B_RX_INT_FLAG_DEFAULT_VALUE and MXM_41B_TX_INT_FLAG_DEFAULT_VALUE).

Parameters

[in,out] pInstance state pointer

Returns: returnvalue of MXM_41BRegisterWrite()

Definition at line 354 of file mxm_17841b.c.

Here is the call graph for this function:

◆ MXM_41BInitializeRegisterCopies()

static void MXM_41BInitializeRegisterCopies ( MXM_41B_INSTANCE_s * pInstance )

static

Reset register copies to default.

Parameters

[out] pInstance pointer to the state-struct

Definition at line 421 of file mxm_17841b.c.

◆ MXM_41BInitializeStateStruct()

void MXM_41BInitializeStateStruct ( MXM_41B_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 974 of file mxm_17841b.c.

Here is the call graph for this function:

◆ MXM_41BReadRegisterFunction()

STD_RETURN_TYPE_e MXM_41BReadRegisterFunction	(	const MXM_41B_INSTANCE_s *const	kpkInstance,
		MXM_41B_REG_FUNCTION_e	registerFunction,
		MXM_41B_REG_BIT_VALUE *	pValue
	)

Read the value of a register function.

Corresponding read-function to MXM_41BWriteRegisterFunction(). This function reads a value from the register-copy of MAX17841B and writes it into a supplied pointer. The register function is specified by the corresponding MXM_41B_REG_FUNCTION_e value.

This function implements only the needed subset of register functions.

Parameters

[in,out]	kpkInstance	pointer to the state of the MAX17841B-state-machine
[in]	registerFunction	name of the function that shall be written
[out]	pValue	pointer to a variable in which the bits shall be written

Returns: STD_NOT_OK for unknown or unimplemented register function, otherwise STD_OK

Definition at line 893 of file mxm_17841b.c.

Here is the call graph for this function:

◆ MXM_41BRegisterRead()

static STD_RETURN_TYPE_e MXM_41BRegisterRead	(	MXM_41B_INSTANCE_s *	pInstance,
		MXM_41B_REG_ADD_t	command,
		uint16_t *	pRxBuffer,
		uint8_t	length
	)

static

Read one or multiple registers of MAX17841B.

This function puts together a SPI message consisting of command and bit-stuffing and writes it to the assigned SPI-interface.

The command should be one of the MXM_41B_REG_ADD_t commands. The function checks whether the chosen command is a read command.

The RX buffer length has to be consistent with the RX buffer. RX buffer lengths of one will read one register only. Longer RX buffers will read also from adjacent registers. Please see the MAX17841B data sheet for reference.

Parameters

[in,out]	pInstance	pointer to the state of the MAX17841B-state-machine
[in]	command	register command of MXM_41B_REG_ADD_t
[out]	pRxBuffer	pointer to an array into which read data will be written
[in]	length	length of the RX buffer array

Returns: STD_NOT_OK for inconsistent input or a blocked SPI interface, otherwise STD_OK

Definition at line 327 of file mxm_17841b.c.

Here is the call graph for this function:

◆ MXM_41BRegisterWrite()

static STD_RETURN_TYPE_e MXM_41BRegisterWrite	(	MXM_41B_INSTANCE_s *	pInstance,
		MXM_41B_REG_ADD_t	command,
		const uint8_t *const	kpkPayload,
		uint8_t	lengthPayload
	)

static

Write one or multiple registers of MAX17841B.

This function puts together a SPI message consisting of command and payload and writes it to the assigned SPI interface.

The command should be one of the MXM_41B_REG_ADD_t commands. The function checks whether the chosen command is a write command.

The payload-length has to be consistent with the payload. Payload-lengths of one will write to one register only. Longer payloads will write to adjacent registers. Please see the MAX17841B data sheet for reference.

Parameters

[in,out]	pInstance	pointer to the state of the MAX17841B-state-machine
[in]	command	register command of MXM_41B_REG_ADD_t
[in]	kpkPayload	pointer to an array of data to be written
[in]	lengthPayload	length of the payload array

Returns: STD_NOT_OK for inconsistent input or a blocked SPI interface, otherwise STD_OK

Definition at line 290 of file mxm_17841b.c.

Here is the call graph for this function:

◆ MXM_41BSetStateRequest()

STD_RETURN_TYPE_e MXM_41BSetStateRequest	(	MXM_41B_INSTANCE_s *	pInstance,
		MXM_STATEMACH_41B_e	state,
		uint16_t *	pPayload,
		uint8_t	payloadLength,
		uint8_t	extendMessageBytes,
		uint16_t *	pRxBuffer,
		uint16_t	rxBufferLength,
		MXM_41B_STATE_REQUEST_STATUS_e *	processed
	)

Set state transition for MAX17841B-state-machine.

This function is used to transition into another state of the state-machine which is handled in MXM_41BStateMachine(). The user sets a state that should be transitioned into. For most states a payload and a payload-length can be supplied. The payload-length has to be consistent with the length in payload. Typically, this supplied payload describes the byte-sequence that should be written into the load-queue.

For the case of a e.g. READALL-command the message-length has to be stretched by the number of connected monitoring ICs times two. This is achieved by passing on extendMessageBytes.

In case that the state generates data that has to be handled in the higher layers, the pointer pRxBuffer will be used. Please make sure that the length of pRxBuffer is also consistent.

In order to determine success or failure of the requested state, the higher layer supplies a pointer into which the current status of the requested state will be written.

Parameters

[in,out]	pInstance	pointer to the state of the MAX17841B-state-machine
[in]	state	state into which the state-machine shall transition
[in]	pPayload	pointer to an array with data that will be processed in the requested state
[in]	payloadLength	length of the payload-array
[in]	extendMessageBytes	number of bytes that shall be appended by the ASCI
[out]	pRxBuffer	pointer to an array that will be filled by the requested state with data that has to be processed in higher layers
[in]	rxBufferLength	length of the RX buffer array
[out]	processed	pointer of the status of the requested state

Returns: STD_NOT_OK for inconsistent input or forbidden state transitions, otherwise STD_OK

Definition at line 785 of file mxm_17841b.c.

◆ MXM_41BStateMachine()

void MXM_41BStateMachine ( MXM_41B_INSTANCE_s * pInstance )

Execute state-machine for the MAX17841B.

This function executes the state-machine that communicates with the MAX17841B over SPI.

Definition at line 928 of file mxm_17841b.c.

Here is the call graph for this function:

◆ MXM_41BTransitionToIdleError()

static void MXM_41BTransitionToIdleError ( MXM_41B_INSTANCE_s * pInstance )

static

Transition into idle, mark as an error occurred.

Parameters

[out] pInstance pointer to the state-struct

Definition at line 413 of file mxm_17841b.c.

◆ MXM_41BTransitionToIdleSuccess()

static void MXM_41BTransitionToIdleSuccess ( MXM_41B_INSTANCE_s * pInstance )

static

Transition into idle, mark as successful.

Parameters

[out] pInstance pointer to the state-struct

Definition at line 405 of file mxm_17841b.c.

◆ MXM_41BWriteRegisterFunction()

STD_RETURN_TYPE_e MXM_41BWriteRegisterFunction	(	MXM_41B_INSTANCE_s *	pInstance,
		MXM_41B_REG_FUNCTION_e	registerFunction,
		MXM_41B_REG_BIT_VALUE	value
	)

Write a register function.

Functions of the ASCI are mapped onto parts of the register. This function is used to write the proper values into the register copy of the ASCI that is inside the driver. In order to use the function, provide the name of the ASCI function that you want to write (MXM_41B_REG_FUNCTION_e) and the value that should be written (MXM_41B_REG_BIT_VALUE). Currently, only a relevant subset of the ASCI features is implemented.

After updating the register copy, it has to be written to the ASCI memory. For the configuration registers this is done with the function MXM_41BConfigRegisterWrite(). This function is for example called in state MXM_STATEMACH_41B_WRITE_CONF_AND_INT_REGISTER.

Parameters

[in,out]	pInstance	pointer to the state of the MAX17841B-state-machine
[in]	registerFunction	name of the function that shall be written
[in]	value	value of the bits that shall be written

Returns: STD_NOT_OK for unknown or unimplemented register functions, otherwise STD_OK

Definition at line 847 of file mxm_17841b.c.

Here is the call graph for this function:

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ MXM_41B_BIT_MASK_HIGH_NIBBLE

◆ MXM_41B_BIT_MASK_LOW_NIBBLE

◆ MXM_41B_BIT_MASK_ONE_BYTE

◆ MXM_41B_BIT_SHIFT_HALF_BYTE

◆ MXM_41B_BRIDGE_RESET_TIME_MS

◆ MXM_41B_CONFIG_REGISTER_LENGTH

◆ MXM_41B_WAIT_COUNTER_THRESHOLD

Function Documentation

◆ MXM_41BBufferWrite()

◆ MXM_41BConfigRegisterWrite()

◆ MXM_41BInitializeRegisterCopies()

◆ MXM_41BInitializeStateStruct()

◆ MXM_41BReadRegisterFunction()

◆ MXM_41BRegisterRead()

◆ MXM_41BRegisterWrite()

◆ MXM_41BSetStateRequest()

◆ MXM_41BStateMachine()

◆ MXM_41BTransitionToIdleError()

◆ MXM_41BTransitionToIdleSuccess()

◆ MXM_41BWriteRegisterFunction()