This is a collection of helper functions for the MAX1785x ICs. More...

#include "mxm_cfg.h"
#include "mxm_basic_defines.h"
#include "mxm_battery_management.h"
#include "mxm_register_map.h"

Include dependency graph for mxm_1785x_tools.h:

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

Go to the source code of this file.

Data Structures
struct	MXM_SELFCHECK

struct	MXM_REGISTRY_ENTRY

struct	MXM_MONITORING_INSTANCE

Macros
#define	MXM_RX_BUFFER_LENGTH 100
	Length of RX buffer. More...

Typedefs
typedef enum MXM_STATEMACHINE_STATES	MXM_STATEMACHINE_STATES_e
	States of the global Maxim state-machine. More...

typedef enum MXM_STATEMACHINE_OPERATION_STATES_e	MXM_STATEMACHINE_OPERATION_STATES_e

typedef enum MXM_MONITORING_STATE	MXM_MONINTORING_STATE_e

typedef struct MXM_SELFCHECK	MXM_SELFCHECK_s

typedef struct MXM_REGISTRY_ENTRY	MXM_REGISTRY_ENTRY_s

typedef struct MXM_MONITORING_INSTANCE	MXM_MONITORING_INSTANCE_s

Enumerations
enum	MXM_STATEMACHINE_STATES { MXM_STATEMACHINE_STATES_UNINITIALIZED , MXM_STATEMACHINE_STATES_SELFCHECK_PRE_INIT , MXM_STATEMACHINE_STATES_INIT , MXM_STATEMACHINE_STATES_SELFCHECK_POST_INIT , MXM_STATEMACHINE_STATES_IDLE , MXM_STATEMACHINE_STATES_OPERATION , MXM_STATEMACHINE_STATES_MAXSTATE }
	States of the global Maxim state-machine. More...

enum	MXM_STATEMACHINE_OPERATION_STATES_e { MXM_INIT_DEVCFG1 , MXM_INIT_STATUS1 , MXM_INIT_GET_VERSION , MXM_INIT_GET_ID1 , MXM_INIT_GET_ID2 , MXM_INIT_MEASUREEN1 , MXM_INIT_MEASUREEN2 , MXM_INIT_AUXGPIOCFG , MXM_INIT_AUXTIMEREG , MXM_INIT_ACQCFG , MXM_INIT_UVTHSETREG , MXM_INIT_OVTHSETREG , MXM_INIT_BALEXP1 , MXM_INIT_BALEXP2 , MXM_INIT_BALEXP3 , MXM_INIT_BALEXP4 , MXM_INIT_BALEXP5 , MXM_INIT_BALEXP6 , MXM_INIT_BALEXP7 , MXM_INIT_BALEXP8 , MXM_INIT_BALEXP9 , MXM_INIT_BALEXP10 , MXM_INIT_BALEXP11 , MXM_INIT_BALEXP12 , MXM_INIT_BALEXP13 , MXM_INIT_BALEXP14 , MXM_INIT_BALSWDLY , MXM_INIT_ALRTOVEN , MXM_INIT_ALRTUVEN , MXM_INIT_COMPOPNTHREG , MXM_INIT_I2C_GET_STAT1 , MXM_INIT_I2C_CFG , MXM_INIT_I2C_PNTR , MXM_INIT_I2C_SEND_MUX0 , MXM_INIT_I2C_SEND_MUX1 , MXM_INIT_GET_I2C_STAT2 , MXM_INIT_SET_FMEA2 , MXM_OP_ENTRY_STATE , MXM_OP_SELECT_MUX_CHANNEL , MXM_OP_WRITE_MUX0 , MXM_OP_WRITE_MUX1 , MXM_OP_SET_SCAN_STROBE , MXM_OP_GET_SCAN_STROBE , MXM_OP_GET_VOLTAGES , MXM_OP_GET_ALRTSUM , MXM_OP_PARSE_VOLTAGES_INTO_DB , MXM_OP_PINOPEN_ENTRY , MXM_OP_PINOPEN_EXIT , MXM_OP_PINOPEN_SET_CURRENT_SOURCES , MXM_OP_PINOPEN_COMPSCAN , MXM_OP_PINOPEN_GET_SCAN_STROBE , MXM_OP_PINOPEN_GET_ALRT , MXM_OP_PINOPEN_PROCESS_OPENWIRE , MXM_OP_PINOPEN_RESTORE_CURRENT_SOURCE_CONF , MXM_OP_BAL_ENTRY , MXM_OP_BAL_CONTROL_RESET_ALL , MXM_OP_BAL_CONTROL_SET_ALL , MXM_OP_BAL_START , MXM_OP_BAL_EXIT , MXM_OP_CYCLE_END_ENTRY , MXM_OP_INCREMENT_MUX_COUNTER , MXM_OP_CYCLE_END_EXIT }

enum	MXM_MONITORING_STATE { MXM_MONITORING_STATE_PENDING , MXM_MONITORING_STATE_PASS , MXM_MONITORING_STATE_FAIL }

Functions
void	MXM_Convert (uint8_t lsb, uint8_t msb, uint16_t *pTarget, MXM_CONVERSION_TYPE_e convType, uint32_t fullScaleReference_mV)
	Convert a measurement value to a voltage value. More...

STD_RETURN_TYPE_e must_check_return	MXM_ConvertTest (void)
	Test the MXM_Convert()-function. More...

void	MXM_ExtractValueFromRegister (uint8_t lsb, uint8_t msb, MXM_REG_BM bitmask, uint16_t *pValue)
	Extract a value from a single register. More...

STD_RETURN_TYPE_e must_check_return	MXM_ExtractValueFromRegisterTest (void)
	Test MXM_ExtractValueFromRegister(). More...

uint8_t	MXM_FirstSetBit (uint16_t bitmask)
	Find Position of first set bit in bitmask. More...

STD_RETURN_TYPE_e must_check_return	MXM_FirstSetBitTest (void)
	Test MXM_FirstSetBit(). More...

void	MXM_Unipolar14BitInto16Bit (uint16_t inputValue, uint8_t lsb, uint8_t msb)
	convert a unipolar 14bit-value and shifts it into the 16bit-format More...

uint16_t	MXM_VoltageIntoUnipolar14Bit (uint16_t voltage_mV, uint16_t fullscaleReference_mV)
	convert a voltage value into a unipolar 14bit value More...

void	MXM_ConvertModuleToString (const uint16_t moduleNumber, uint8_t pStringNumber, uint16_t pModuleNumberInString)
	Get the string and module number from a global module number. More...

Detailed Description

This is a collection of helper functions for the MAX1785x ICs.

Copyright: © 2010 - 2021, 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: 2020-07-15 (date of creation)

Updated: 2021-07-14 (date of last update)

Prefix: MXM

This collection of helper functions for the MAX1785x ICs helps to calculate the lsb and msb for register values and similar tasks.

Definition in file mxm_1785x_tools.h.

Macro Definition Documentation

◆ MXM_RX_BUFFER_LENGTH

#define MXM_RX_BUFFER_LENGTH 100

Length of RX buffer.

This define describes the length of the array MXM_MONITORING_INSTANCE_s::rxBuffer. It is large enough to fit the largest message that can be written into a single buffer which consists of 6 command bytes and MXM_MAXIMUM_NR_OF_MODULES times 2 receive bytes for the maximum number of connected monitoring ICs.

Definition at line 194 of file mxm_1785x_tools.h.

Typedef Documentation

◆ MXM_MONINTORING_STATE_e

typedef enum MXM_MONITORING_STATE MXM_MONINTORING_STATE_e

intermediate state-definition for MXM_MonGetVoltages()

◆ MXM_MONITORING_INSTANCE_s

typedef struct MXM_MONITORING_INSTANCE MXM_MONITORING_INSTANCE_s

Status of the Maxim-main-state-machine.

◆ MXM_REGISTRY_ENTRY_s

typedef struct MXM_REGISTRY_ENTRY MXM_REGISTRY_ENTRY_s

struct describing an entry into the monitoring registry

◆ MXM_SELFCHECK_s

typedef struct MXM_SELFCHECK MXM_SELFCHECK_s

struct describing the different return values of selfchecks that the driver can execute

◆ MXM_STATEMACHINE_OPERATION_STATES_e

typedef enum MXM_STATEMACHINE_OPERATION_STATES_e MXM_STATEMACHINE_OPERATION_STATES_e

states of the MXM_StateMachineOperation() statemachine

◆ MXM_STATEMACHINE_STATES_e

typedef enum MXM_STATEMACHINE_STATES MXM_STATEMACHINE_STATES_e

States of the global Maxim state-machine.

State transitions are currently autonomous and will have to be integrated into the Battery System state-machine.

Enumeration Type Documentation

◆ MXM_MONITORING_STATE

enum MXM_MONITORING_STATE

intermediate state-definition for MXM_MonGetVoltages()

Enumerator
MXM_MONITORING_STATE_PENDING	state completion is pending
MXM_MONITORING_STATE_PASS	state passed successfully
MXM_MONITORING_STATE_FAIL	unrecoverable failure that has to be handled by e.g., reset (function has already tried recovery)

Definition at line 151 of file mxm_1785x_tools.h.

◆ MXM_STATEMACHINE_OPERATION_STATES_e

enum MXM_STATEMACHINE_OPERATION_STATES_e

states of the MXM_StateMachineOperation() statemachine

Enumerator
MXM_INIT_DEVCFG1
MXM_INIT_STATUS1
MXM_INIT_GET_VERSION
MXM_INIT_GET_ID1
MXM_INIT_GET_ID2
MXM_INIT_MEASUREEN1
MXM_INIT_MEASUREEN2
MXM_INIT_AUXGPIOCFG
MXM_INIT_AUXTIMEREG
MXM_INIT_ACQCFG
MXM_INIT_UVTHSETREG
MXM_INIT_OVTHSETREG
MXM_INIT_BALEXP1
MXM_INIT_BALEXP2
MXM_INIT_BALEXP3
MXM_INIT_BALEXP4
MXM_INIT_BALEXP5
MXM_INIT_BALEXP6
MXM_INIT_BALEXP7
MXM_INIT_BALEXP8
MXM_INIT_BALEXP9
MXM_INIT_BALEXP10
MXM_INIT_BALEXP11
MXM_INIT_BALEXP12
MXM_INIT_BALEXP13
MXM_INIT_BALEXP14
MXM_INIT_BALSWDLY
MXM_INIT_ALRTOVEN
MXM_INIT_ALRTUVEN
MXM_INIT_COMPOPNTHREG
MXM_INIT_I2C_GET_STAT1
MXM_INIT_I2C_CFG
MXM_INIT_I2C_PNTR
MXM_INIT_I2C_SEND_MUX0
MXM_INIT_I2C_SEND_MUX1
MXM_INIT_GET_I2C_STAT2
MXM_INIT_SET_FMEA2
MXM_OP_ENTRY_STATE
MXM_OP_SELECT_MUX_CHANNEL
MXM_OP_WRITE_MUX0
MXM_OP_WRITE_MUX1
MXM_OP_SET_SCAN_STROBE
MXM_OP_GET_SCAN_STROBE
MXM_OP_GET_VOLTAGES
MXM_OP_GET_ALRTSUM
MXM_OP_PARSE_VOLTAGES_INTO_DB
MXM_OP_PINOPEN_ENTRY
MXM_OP_PINOPEN_EXIT
MXM_OP_PINOPEN_SET_CURRENT_SOURCES
MXM_OP_PINOPEN_COMPSCAN
MXM_OP_PINOPEN_GET_SCAN_STROBE
MXM_OP_PINOPEN_GET_ALRT
MXM_OP_PINOPEN_PROCESS_OPENWIRE
MXM_OP_PINOPEN_RESTORE_CURRENT_SOURCE_CONF
MXM_OP_BAL_ENTRY
MXM_OP_BAL_CONTROL_RESET_ALL
MXM_OP_BAL_CONTROL_SET_ALL
MXM_OP_BAL_START
MXM_OP_BAL_EXIT
MXM_OP_CYCLE_END_ENTRY
MXM_OP_INCREMENT_MUX_COUNTER
MXM_OP_CYCLE_END_EXIT

Definition at line 85 of file mxm_1785x_tools.h.

◆ MXM_STATEMACHINE_STATES

enum MXM_STATEMACHINE_STATES

States of the global Maxim state-machine.

State transitions are currently autonomous and will have to be integrated into the Battery System state-machine.

Enumerator
MXM_STATEMACHINE_STATES_UNINITIALIZED	uninitialized state
MXM_STATEMACHINE_STATES_SELFCHECK_PRE_INIT	self-check that has to be executed before initialization
MXM_STATEMACHINE_STATES_INIT	initialization sequence
MXM_STATEMACHINE_STATES_SELFCHECK_POST_INIT	self-check that has to be executed after initialization
MXM_STATEMACHINE_STATES_IDLE	idle state, the driver waits for operation here
MXM_STATEMACHINE_STATES_OPERATION	operating state, the measurement cycle is executed here
MXM_STATEMACHINE_STATES_MAXSTATE	highest state

Definition at line 74 of file mxm_1785x_tools.h.

Function Documentation

◆ MXM_Convert()

void MXM_Convert	(	uint8_t	lsb,
		uint8_t	msb,
		uint16_t *	pTarget,
		MXM_CONVERSION_TYPE_e	convType,
		uint32_t	fullScaleReference_mV
	)

Convert a measurement value to a voltage value.

This function converts measurement values from the monitoring IC into a voltage value. It assumes that measurement values are spread over the LSB and MSB according to the datasheet. This means that the two lowest bits are 0 and the 14-bit measurement is spread over the 14 highest bits.

The conversion type describes the kind of measurement that has been executed.

Parameters

[in]	lsb	LSB of the value
[in]	msb	MSB of the value
[out]	pTarget	pointer in which the converted value shall be written
[in]	convType	type of conversion (bipolar or unipolar)
[in]	fullScaleReference_mV	reference voltage of full scale (for voltage measurements 5000)

Definition at line 98 of file mxm_1785x_tools.c.

Here is the call graph for this function:

◆ MXM_ConvertModuleToString()

void MXM_ConvertModuleToString	(	const uint16_t	moduleNumber,
		uint8_t *	pStringNumber,
		uint16_t *	pModuleNumberInString
	)

Get the string and module number from a global module number.

Maxim driver knows only one string internally and maps on demand this one string onto several strings (for instances where several modules are in the same daisy-chain but belong to different strings).

This function assumes that a string contains BS_NR_OF_MODULES modules in BS_NR_OF_STRINGS strings and that they are connected in a daisy-chain.

Parameters

[in]	moduleNumber	number of the module in the daisy-chain (starts with 0)
[out]	pStringNumber	pointer where the string number will be written
[out]	pModuleNumberInString	module number in the string

Definition at line 222 of file mxm_1785x_tools.c.

◆ MXM_ConvertTest()

STD_RETURN_TYPE_e must_check_return MXM_ConvertTest ( void )

Test the MXM_Convert()-function.

This test-function is intended as a self-check. It tests whether the MXM_Convert()-function computes the values as expected.

Returns: STD_OK on successful execution, otherwise STD_NOT_OK

Definition at line 125 of file mxm_1785x_tools.c.

Here is the call graph for this function:

◆ MXM_ExtractValueFromRegister()

void MXM_ExtractValueFromRegister	(	uint8_t	lsb,
		uint8_t	msb,
		MXM_REG_BM	bitmask,
		uint16_t *	pValue
	)

Extract a value from a single register.

This function extracts a single value from a single register. The register has to be supplied as MSB and LSB. The bitmask has to be of type MXM_REG_BM. The extracted value will be written into value.

The function can only extract values from single registers (MSB and LSB)and does not handle values that span multiple registers.

Parameters

[in]	lsb	least significant byte of the register
[in]	msb	most significant byte of the register
[in]	bitmask	bitmask for the value
[out]	pValue	pointer to a variable in which the value should be written

Definition at line 155 of file mxm_1785x_tools.c.

Here is the call graph for this function:

◆ MXM_ExtractValueFromRegisterTest()

STD_RETURN_TYPE_e must_check_return MXM_ExtractValueFromRegisterTest ( void )

Test MXM_ExtractValueFromRegister().

Self-check that tests whether MXM_ExtractValueFromRegister() works as expected.

Returns: STD_OK if the self-check has passed successfully

Definition at line 174 of file mxm_1785x_tools.c.

Here is the call graph for this function:

◆ MXM_FirstSetBit()

uint8_t MXM_FirstSetBit ( uint16_t bitmask )

Find Position of first set bit in bitmask.

Searches a bitmask starting from the lowest bit and returns the position of the first set bit.

Parameters

[in] bitmask bitmask that should be searched

Returns: position of first set bit

Definition at line 73 of file mxm_1785x_tools.c.

◆ MXM_FirstSetBitTest()

STD_RETURN_TYPE_e must_check_return MXM_FirstSetBitTest ( void )

Test MXM_FirstSetBit().

Tests the function MXM_FirstSetBit() if it works as expected.

Returns: STD_OK if the self-check has passed successfully

Definition at line 85 of file mxm_1785x_tools.c.

Here is the call graph for this function:

◆ MXM_Unipolar14BitInto16Bit()

void MXM_Unipolar14BitInto16Bit	(	uint16_t	inputValue,
		uint8_t *	lsb,
		uint8_t *	msb
	)

convert a unipolar 14bit-value and shifts it into the 16bit-format

Takes a value in the unipolar 14bit format and transforms it into a 16bit register entry for the monitoring IC (separated into LSB and MSB).

Parameters

[in]	inputValue	unipolar 14bit-value
[out]	lsb	LSB in 16bit-format
[out]	msb	MSB in 16bit-format

Definition at line 203 of file mxm_1785x_tools.c.

◆ MXM_VoltageIntoUnipolar14Bit()

uint16_t MXM_VoltageIntoUnipolar14Bit	(	uint16_t	voltage_mV,
		uint16_t	fullscaleReference_mV
	)

convert a voltage value into a unipolar 14bit value

Takes a voltage value in mV together with a reference for fullscale values into a unipolar 14bit value.

Parameters

[in]	voltage_mV	voltage in mV
[in]	fullscaleReference_mV	value of the fullscale in mV; typically 5000

Returns: unipolar 14bit value for usage with MXM_Unipolar14BitInto16Bit()

Definition at line 214 of file mxm_1785x_tools.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MXM_RX_BUFFER_LENGTH

Typedef Documentation

◆ MXM_MONINTORING_STATE_e

◆ MXM_MONITORING_INSTANCE_s

◆ MXM_REGISTRY_ENTRY_s

◆ MXM_SELFCHECK_s

◆ MXM_STATEMACHINE_OPERATION_STATES_e

◆ MXM_STATEMACHINE_STATES_e

Enumeration Type Documentation

◆ MXM_MONITORING_STATE

◆ MXM_STATEMACHINE_OPERATION_STATES_e

◆ MXM_STATEMACHINE_STATES

Function Documentation

◆ MXM_Convert()

◆ MXM_ConvertModuleToString()

◆ MXM_ConvertTest()

◆ MXM_ExtractValueFromRegister()

◆ MXM_ExtractValueFromRegisterTest()

◆ MXM_FirstSetBit()

◆ MXM_FirstSetBitTest()

◆ MXM_Unipolar14BitInto16Bit()

◆ MXM_VoltageIntoUnipolar14Bit()