foxBMS  1.1.0
The foxBMS Battery Management System API Documentation
mxm_battery_management.c File Reference

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

Include dependency graph for mxm_battery_management.c:

Go to the source code of this file.

Macros

#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)
 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, uint8_t regAddress, uint8_t dataLSB, uint8_t dataMSB)
 clears the command buffer and writes WRITEALL into the buffer More...
 
static STD_RETURN_TYPE_e MXM_5XConstructCommandBufferWriteDevice (MXM_5X_INSTANCE_s *pInstance, uint8_t deviceAddress, uint8_t regAddress, uint8_t dataLSB, uint8_t dataMSB)
 clears the command buffer and writes a WRITEDEVICE message More...
 
static STD_RETURN_TYPE_e MXM_5XConstructCommandBufferReadall (MXM_5X_INSTANCE_s *pInstance, uint8_t regAddress)
 clears the command buffer and writes READALL into the buffer 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::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 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.

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:

  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
2021-06-16 (date of last update)
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 63 of file mxm_battery_management.c.

◆ HELLOALL_TX_LENGTH

#define HELLOALL_TX_LENGTH   (3u)

length of the helloall command

Definition at line 62 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 datasheet of the monitoring IC.

Parameters
[in]regAddressregister address to be checked
Returns
STD_OK if the register address is good, otherwise STD_NOT_OK

Definition at line 209 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 datasheet 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]regAddressregister address to be checked
      Returns
      STD_OK if the register address is good, otherwise STD_NOT_OK

Definition at line 225 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]pInstancepointer to the state-struct
Returns
always return STD_OK

Definition at line 182 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]pInstancepointer to the state-struct

Definition at line 242 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,
uint8_t  regAddress 
)
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.

Parameters
[in,out]pInstancepointer to the state-struct
[in]regAddressaddress of the register that should be read
Returns
STD_OK if an accessible register address has been selected, STD_NOT_OK if not.

Definition at line 309 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,
uint8_t  regAddress,
uint8_t  dataLSB,
uint8_t  dataMSB 
)
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.

Parameters
[in,out]pInstancepointer to the state-struct
[in]regAddressaddress of the register that should be written
[in]dataLSBLSB of the register that should be written
[in]dataMSBMSB of the register that should be written
Returns
STD_OK if an accessible register address has been selected, STD_NOT_OK if not.

Definition at line 250 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,
uint8_t  deviceAddress,
uint8_t  regAddress,
uint8_t  dataLSB,
uint8_t  dataMSB 
)
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.

Parameters
[in,out]pInstancepointer to the state-struct
[in]deviceAddressaddress for the satellite that should be written to
[in]regAddressaddress of the register that should be written
[in]dataLSBLSB of the register that should be written
[in]dataMSBMSB of the register that should be written
Returns
STD_OK if an accessible register address has been selected, STD_NOT_OK if not.

Definition at line 276 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]kpkInstancepointer to the instance struct

Definition at line 360 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::numberOfSatellites).

Parameters
[in]kpkInstancepointer to the state struct
Returns
value of MXM_5X_INSTANCE::numberOfSatellites

Definition at line 364 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::numberOfSatellitesIsGood.

Parameters
[in]kpkInstancepointer to the instance struct
Returns
MXM_5X_INSTANCE::numberOfSatellitesIsGood

Definition at line 368 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]kpkInstancepointer to the state-struct
[in]rxBufferarray-pointer to a RX buffer that shall be filled
[in]rxBufferLengthlength of the supplied array
Returns
STD_NOT_OK for rxBuffer being a NULL_PTR or rxBufferLength having length 0

Definition at line 339 of file mxm_battery_management.c.

◆ MXM_5XIsUserAccessibleRegister()

static STD_RETURN_TYPE_e MXM_5XIsUserAccessibleRegister ( uint8_t  regAddress)
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 datasheet 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]regAddressregister address to be checked
      Returns
      STD_OK if the register address is good, otherwise STD_NOT_OK

Definition at line 189 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]pInstance5xpointer to the 5x state
[in]stateState that is requested
[in]commandPayloadadditional payload that is handled by the state
[in,out]processedpointer to the status of the request
Returns
STD_OK if the request has been successfully placed, STD_NOT_OK if not

Definition at line 372 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 404 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 971 of file mxm_battery_management.c.

Here is the call graph for this function: