mxm_battery_management.h File Reference

Headers for the driver for the MAX17841B ASCI and MAX1785x monitoring chip. More...

#include "mxm_cfg.h"
#include "mxm_17841b.h"
#include "mxm_basic_defines.h"
#include "mxm_crc8.h"
#include "mxm_register_map.h"

Include dependency graph for mxm_battery_management.h:

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

Go to the source code of this file.

Data Structures
struct	MXM_5X_COMMAND_PAYLOAD_s
	Payload command. More...
struct	MXM_5X_INSTANCE
	5x statemachine structure More...

Macros
#define	COMMAND_BUFFER_LENGTH   (6u)
#define	MXM_5X_RX_BUFFER_LEN   100u
#define	HELLOALL_START_SEED   0x00u
#define	DATA_CHECK_BYTE_SEED   0x00u
#define	ALIVE_COUNTER_SEED   0x00u
#define	BATTERY_MANAGEMENT_HELLOALL   ((BATTERY_MANAGEMENT_COMMAND_t)0x57u)
	HELLOALL message. More...
#define	BATTERY_MANAGEMENT_ALERTPACKET   ((BATTERY_MANAGEMENT_COMMAND_t)0x21u)
	ALERTPACKET message. More...
#define	BATTERY_MANAGEMENT_WRITEDEVICE   ((BATTERY_MANAGEMENT_COMMAND_t)0x04u)
	WRITEDEVICE message (write single register of a single device) More...
#define	BATTERY_MANAGEMENT_WRITEALL   ((BATTERY_MANAGEMENT_COMMAND_t)0x02u)
	WRITEALL message (write single register of all daisy-chain devices) More...
#define	BATTERY_MANAGEMENT_READDEVICE   ((BATTERY_MANAGEMENT_COMMAND_t)0x05u)
	READDEVICE message (read single register of a single device) More...
#define	BATTERY_MANAGEMENT_READALL   ((BATTERY_MANAGEMENT_COMMAND_t)0x03u)
	READALL message (read single register of all daisy-chain devices) More...
#define	BATTERY_MANAGEMENT_READBLOCK   ((BATTERY_MANAGEMENT_COMMAND_t)0x06u)
	READBLOCK message (read block of registers of a single device) More...
#define	BATTERY_MANAGEMENT_DOWNHOST   ((BATTERY_MANAGEMENT_COMMAND_t)0x09u)
	DOWNHOST message (make the downhost writing) More...
#define	BATTERY_MANAGEMENT_UPHOST   ((BATTERY_MANAGEMENT_COMMAND_t)0x08u)
	UPHOST message (make the uphost writing, only useable on uphost line) More...
#define	BATTERY_MANAGEMENT_TX_LENGTH_READALL   ((uint8_t)4u)
	Battery Management Protocol lengths of TX buffer. More...

Typedefs
typedef uint8_t	BATTERY_MANAGEMENT_COMMAND_t
	Type for Battery Management Protocol commands. More...
typedef struct MXM_5X_INSTANCE	MXM_5X_INSTANCE_s
	5x statemachine structure More...

Enumerations
enum	MXM_STATEMACHINE_5X_e {   MXM_STATEMACH_5X_UNINITIALIZED, MXM_STATEMACH_5X_INIT, MXM_STATEMACH_5X_41B_FMEA_CHECK, MXM_STATEMACH_5X_IDLE,   MXM_STATEMACH_5X_WRITEALL, MXM_STATEMACH_5X_WRITE_DEVICE, MXM_STATEMACH_5X_READALL, MXM_STATEMACH_5X_MAXSTATE }
	States of the Battery Management Protocol state-machine. More...
enum	MXM_5X_SUBSTATES_e {   MXM_5X_ENTRY_SUBSTATE, MXM_5X_INIT_41B_INIT, MXM_5X_INIT_ENABLE_KEEP_ALIVE, MXM_5X_INIT_ENABLE_RX_INTERRUPT_FLAGS,   MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_CLEAR_RECEIVE_BUFFER, MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_EN_PREAMBLES, MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_WAIT_FOR_RX_STATUS_BUSY, MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_DIS_PREAMBLES,   MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_WAIT_FOR_RX_STATUS_EMPTY, MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_CLEAR_TRANSMIT_BUFFER, MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_CLEAR_RECEIVE_BUFFER_2, MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_HELLOALL,   MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_HELLOALL_VERIFY_MSG_AND_COUNT, MXM_5X_41B_FMEA_REQUEST, MXM_5X_41B_FMEA_CHECK, MXM_5X_WRITEALL_UART_TRANSACTION,   MXM_5X_WRITEALL_UART_VERIFY_BUFFER, MXM_5X_WRITE_DEVICE_UART_TRANSACTION, MXM_5X_WRITE_DEVICE_CHECK_CRC, MXM_5X_READALL_UART_TRANSACTION,   MXM_5X_READALL_CHECK_CRC, MXM_5X_READALL_GET_DC }
	Sub-states of the Battery Management Protocol state-machine. More...
enum	MXM_5X_STATE_REQUEST_STATUS_e { MXM_5X_STATE_UNSENT = 0x56, MXM_5X_STATE_UNPROCESSED, MXM_5X_STATE_PROCESSED = 0x9A, MXM_5X_STATE_ERROR = 0xAB }
	Request status of Battery Management Protocol states. More...

Functions
void	MXM_5XStateMachine (MXM_41B_INSTANCE_s *pInstance41b, MXM_5X_INSTANCE_s *pInstance5x)
	Execute state-machine for Battery Management Protocol. More...
MXM_DC_BYTE_e	MXM_5XGetLastDCByte (MXM_5X_INSTANCE_s *pInstance)
	Returns the last received DC byte. More...
STD_RETURN_TYPE_e	MXM_5XGetNumberOfSatellitesGood (MXM_5X_INSTANCE_s *pInstance)
	Get the value of MXM_5X_INSTANCE::numberOfSatellitesIsGood. More...
STD_RETURN_TYPE_e	MXM_5XGetRXBuffer (MXM_5X_INSTANCE_s *pInstance, uint8_t *rxBuffer, uint16_t rxBufferLength)
	Copy RX buffer into variable. More...
uint8_t	MXM_5XGetNumberOfSatellites (MXM_5X_INSTANCE_s *pInstance)
	Get number of satellites. 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...
STD_RETURN_TYPE_e must_check_return	MXM_5XUserAccessibleAddressSpaceCheckerSelfCheck (void)
	runs a selfcheck for the address space check More...

Detailed Description

Headers for the driver for the MAX17841B ASCI and MAX1785x monitoring chip.

Copyright

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

BSD 3-Clause License 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-14 (date of creation)

Updated

2020-09-10 (date of last update)

Prefix

MXM

def

Definition in file mxm_battery_management.h.

Macro Definition Documentation

ALIVE_COUNTER_SEED

#define ALIVE_COUNTER_SEED   0x00u

seed for the alive counter, should be 0x00u except for special edge cases

Definition at line 81 of file mxm_battery_management.h.

BATTERY_MANAGEMENT_ALERTPACKET

#define BATTERY_MANAGEMENT_ALERTPACKET   ((BATTERY_MANAGEMENT_COMMAND_t)0x21u)

ALERTPACKET message.

Definition at line 99 of file mxm_battery_management.h.

BATTERY_MANAGEMENT_DOWNHOST

#define BATTERY_MANAGEMENT_DOWNHOST   ((BATTERY_MANAGEMENT_COMMAND_t)0x09u)

DOWNHOST message (make the downhost writing)

This feature is only useable on downhost line.

Definition at line 130 of file mxm_battery_management.h.

BATTERY_MANAGEMENT_HELLOALL

#define BATTERY_MANAGEMENT_HELLOALL   ((BATTERY_MANAGEMENT_COMMAND_t)0x57u)

HELLOALL message.

Definition at line 94 of file mxm_battery_management.h.

BATTERY_MANAGEMENT_READALL

#define BATTERY_MANAGEMENT_READALL   ((BATTERY_MANAGEMENT_COMMAND_t)0x03u)

READALL message (read single register of all daisy-chain devices)

Definition at line 119 of file mxm_battery_management.h.

BATTERY_MANAGEMENT_READBLOCK

#define BATTERY_MANAGEMENT_READBLOCK   ((BATTERY_MANAGEMENT_COMMAND_t)0x06u)

READBLOCK message (read block of registers of a single device)

Definition at line 124 of file mxm_battery_management.h.

BATTERY_MANAGEMENT_READDEVICE

#define BATTERY_MANAGEMENT_READDEVICE   ((BATTERY_MANAGEMENT_COMMAND_t)0x05u)

READDEVICE message (read single register of a single device)

Definition at line 114 of file mxm_battery_management.h.

BATTERY_MANAGEMENT_TX_LENGTH_READALL

#define BATTERY_MANAGEMENT_TX_LENGTH_READALL   ((uint8_t)4u)

Battery Management Protocol lengths of TX buffer.

Reference values for the lengths of the respective TX buffers for Battery Management Protocol messages.

length of a READALL command without stuffing bytes

Definition at line 146 of file mxm_battery_management.h.

BATTERY_MANAGEMENT_UPHOST

#define BATTERY_MANAGEMENT_UPHOST   ((BATTERY_MANAGEMENT_COMMAND_t)0x08u)

UPHOST message (make the uphost writing, only useable on uphost line)

Definition at line 135 of file mxm_battery_management.h.

BATTERY_MANAGEMENT_WRITEALL

#define BATTERY_MANAGEMENT_WRITEALL   ((BATTERY_MANAGEMENT_COMMAND_t)0x02u)

WRITEALL message (write single register of all daisy-chain devices)

Definition at line 109 of file mxm_battery_management.h.

BATTERY_MANAGEMENT_WRITEDEVICE

#define BATTERY_MANAGEMENT_WRITEDEVICE   ((BATTERY_MANAGEMENT_COMMAND_t)0x04u)

WRITEDEVICE message (write single register of a single device)

Definition at line 104 of file mxm_battery_management.h.

COMMAND_BUFFER_LENGTH

#define COMMAND_BUFFER_LENGTH   (6u)

length of the command buffer

Definition at line 71 of file mxm_battery_management.h.

DATA_CHECK_BYTE_SEED

#define DATA_CHECK_BYTE_SEED   0x00u

seed for data check, should be 0x00u

Definition at line 79 of file mxm_battery_management.h.

HELLOALL_START_SEED

#define HELLOALL_START_SEED   0x00u

seed for helloall, should be 0x00u except for special edge cases

Definition at line 77 of file mxm_battery_management.h.

MXM_5X_RX_BUFFER_LEN

#define MXM_5X_RX_BUFFER_LEN   100u

length of the rx buffer

Definition at line 74 of file mxm_battery_management.h.

Typedef Documentation

BATTERY_MANAGEMENT_COMMAND_t

typedef uint8_t BATTERY_MANAGEMENT_COMMAND_t

Type for Battery Management Protocol commands.

This type describes the hex-numbers of all Maxim Battery Management Protocol commands. For details see the datasheet of MAX1785x devices.

Definition at line 89 of file mxm_battery_management.h.

MXM_5X_INSTANCE_s

typedef struct MXM_5X_INSTANCE MXM_5X_INSTANCE_s

5x statemachine structure

Enumeration Type Documentation

MXM_5X_STATE_REQUEST_STATUS_e

enum MXM_5X_STATE_REQUEST_STATUS_e

Request status of Battery Management Protocol states.

This enum describes the states that a state in the MXM_5XStateMachine() can have.

Alternating bit patterns are used for better distinction and to make sure that there is no accidental overlap.

Enumerator
MXM_5X_STATE_UNSENT	The request has not been sent to the state-machine yet.
MXM_5X_STATE_UNPROCESSED	The request has been received by the state-machine, but not been processed yet.
MXM_5X_STATE_PROCESSED	The request has been process successfully
MXM_5X_STATE_ERROR	An error has occurred during processing of the request.

Definition at line 229 of file mxm_battery_management.h.

MXM_5X_SUBSTATES_e

enum MXM_5X_SUBSTATES_e

Sub-states of the Battery Management Protocol state-machine.

Enumerator
MXM_5X_ENTRY_SUBSTATE	default value indicating no selected substate
MXM_5X_INIT_41B_INIT	substate for the initialization of the MAX17841 bridge IC
MXM_5X_INIT_ENABLE_KEEP_ALIVE	substate for the initialization, enable the keep alive feature in the bridge IC
MXM_5X_INIT_ENABLE_RX_INTERRUPT_FLAGS	substate for the initialization, enable RX interrupt flags
MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_CLEAR_RECEIVE_BUFFER	substate for the wake-up routine, clear the receive buffer in the bridge IC
MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_EN_PREAMBLES	substate for the wake-up routine, enable the sending of preambles in order to wake up the daisy-chain devices
MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_WAIT_FOR_RX_STATUS_BUSY	substate for the wake-up routine, wait for the daisy-chain devices to return an answer, resulting in status RX busy of the bridge IC
MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_DIS_PREAMBLES	substate for the wake-up routine, disable the sending of preambles
MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_WAIT_FOR_RX_STATUS_EMPTY	substate for the wake-up routine, wait for the RX transmission to finish
MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_CLEAR_TRANSMIT_BUFFER	substate for the wake-up routine, clear the transmit buffer
MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_CLEAR_RECEIVE_BUFFER_2	substate for the wake-up routine, clear the receive buffer
MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_HELLOALL	substate for the wake-up routine, sending helloall to the daisy-chain
MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_HELLOALL_VERIFY_MSG_AND_COUNT	substate for the wake-up routine, verifying the result of helloall
MXM_5X_41B_FMEA_REQUEST	substate for requesting an FMEA check on the bridge IC
MXM_5X_41B_FMEA_CHECK	substate for the verification of the FMEA check done in MXM_5X_41B_FMEA_REQUEST
MXM_5X_WRITEALL_UART_TRANSACTION	substate for the initiation of a uart transaction for the WRITEALL command
MXM_5X_WRITEALL_UART_VERIFY_BUFFER	substate for the verifying the buffer of a WRITEALL transaction
MXM_5X_WRITE_DEVICE_UART_TRANSACTION	substate for the initiation of a uart transaction for the WRITEALL command
MXM_5X_WRITE_DEVICE_CHECK_CRC	substate for checking the received CRC in a WRITEDEVICE transaction
MXM_5X_READALL_UART_TRANSACTION	substate for the initiation of a uart transaction for the READALL command
MXM_5X_READALL_CHECK_CRC	substate for checking the received CRC in a READALL transaction
MXM_5X_READALL_GET_DC	substate for retrieving the data check byte from a READALL transaction

Definition at line 165 of file mxm_battery_management.h.

MXM_STATEMACHINE_5X_e

enum MXM_STATEMACHINE_5X_e

States of the Battery Management Protocol state-machine.

Enumerator
MXM_STATEMACH_5X_UNINITIALIZED	Uninitialized state that the state-machine starts in
MXM_STATEMACH_5X_INIT	Initialization state
MXM_STATEMACH_5X_41B_FMEA_CHECK	Requests a FMEA-check from the 41B-state-machine
MXM_STATEMACH_5X_IDLE	Idle state, transitions are possible in this state
MXM_STATEMACH_5X_WRITEALL	WRITEALL state, sends a WRITEALL to the daisy-chain
MXM_STATEMACH_5X_WRITE_DEVICE	WRITEDEVICE state, sends a WRITEDEVICE to a specific address
MXM_STATEMACH_5X_READALL	READALL state, sends a READALL to the daisy-chain
MXM_STATEMACH_5X_MAXSTATE	Highest state

Definition at line 151 of file mxm_battery_management.h.

Function Documentation

MXM_5XGetLastDCByte()

MXM_DC_BYTE_e MXM_5XGetLastDCByte

(

MXM_5X_INSTANCE_s *

pInstance

)

Returns the last received DC byte.

Definition at line 368 of file mxm_battery_management.c.

MXM_5XGetNumberOfSatellites()

uint8_t MXM_5XGetNumberOfSatellites

(

MXM_5X_INSTANCE_s *

pInstance

)

Get number of satellites.

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

Returns

value of MXM_5X_INSTANCE::numberOfSatellites

Definition at line 372 of file mxm_battery_management.c.

MXM_5XGetNumberOfSatellitesGood()

STD_RETURN_TYPE_e MXM_5XGetNumberOfSatellitesGood

(

MXM_5X_INSTANCE_s *

pInstance

)

Get the value of MXM_5X_INSTANCE::numberOfSatellitesIsGood.

Returns

MXM_5X_INSTANCE::numberOfSatellitesIsGood

Definition at line 376 of file mxm_battery_management.c.

MXM_5XGetRXBuffer()

STD_RETURN_TYPE_e MXM_5XGetRXBuffer	(	MXM_5X_INSTANCE_s *	pInstance,
		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]	pInstance	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 350 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 380 of file mxm_battery_management.c.

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 412 of file mxm_battery_management.c.

Here is the call graph for this function:

MXM_5XUserAccessibleAddressSpaceCheckerSelfCheck()

STD_RETURN_TYPE_e 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 981 of file mxm_battery_management.c.

Here is the call graph for this function: