foxBMS  1.5.0
The foxBMS Battery Management System API Documentation
mxm_1785x.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2023, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V.
4  * All rights reserved.
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions are met:
10  *
11  * 1. Redistributions of source code must retain the above copyright notice, this
12  * list of conditions and the following disclaimer.
13  *
14  * 2. Redistributions in binary form must reproduce the above copyright notice,
15  * this list of conditions and the following disclaimer in the documentation
16  * and/or other materials provided with the distribution.
17  *
18  * 3. Neither the name of the copyright holder nor the names of its
19  * contributors may be used to endorse or promote products derived from
20  * this software without specific prior written permission.
21  *
22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
25  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
26  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
28  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32  *
33  * We kindly request you to use one or more of the following phrases to refer to
34  * foxBMS in your hardware, software, documentation or advertising materials:
35  *
36  * - ″This product uses parts of foxBMS®″
37  * - ″This product includes parts of foxBMS®″
38  * - ″This product is derived from foxBMS®″
39  *
40  */
41 
42 /**
43  * @file mxm_1785x.h
44  * @author foxBMS Team
45  * @date 2019-01-15 (date of creation)
46  * @updated 2023-02-03 (date of last update)
47  * @version v1.5.0
48  * @ingroup DRIVERS
49  * @prefix MXM
50  *
51  * @brief Headers for the driver for the MAX17841B ASCI and MAX1785x
52  * analog front-end
53  *
54  * @details def
55  *
56  */
57 
58 /**
59  * @brief Battery monitoring driver for MAX1785x battery monitoring ICs.
60  *
61  * This module supplies a driver for the Battery Monitoring ICs of the
62  * MAX1785x-family by Maxim Integrated.
63  *
64  * Entry point for the module is the function #MXM_Tick() in mxm_afe.c. It handles
65  * the measurement flow and the coordination of the underlying state-machines.
66  * Below this layer two state-machines are implemented.
67  *
68  * The state-machine in mxm_battery_management.c is executed with the
69  * #MXM_5XStateMachine()-function.
70  * This state-machine exposes commands of the Maxim Battery Management Protocol
71  * to the upper layers. Below, it translates these commands into state-changes
72  * for the underlying state-machine.
73  * This state-machine is implemented in mxm_17841b.c and executed with
74  * #MXM_41BStateMachine(). It handles the register- and buffer-transactions
75  * required for the MAX17841B communication interface (Maxim calls
76  * this analog front-end ASCI).
77  *
78  */
79 
80 #ifndef FOXBMS__MXM_1785X_H_
81 #define FOXBMS__MXM_1785X_H_
82 
83 /*========== Includes =======================================================*/
84 #include "general.h"
85 
86 #include "database_cfg.h"
87 #include "mxm_cfg.h"
88 
89 #include "fstd_types.h"
90 #include "mxm_17841b.h"
91 #include "mxm_1785x_tools.h"
92 #include "mxm_basic_defines.h"
93 #include "mxm_battery_management.h"
94 #include "mxm_crc8.h"
95 
96 #include <stdbool.h>
97 #include <stdint.h>
98 
99 /*========== Macros and Definitions =========================================*/
100 
101 /** threshold of iterations after which a diagnostic cycle is entered by the state-machine */
102 #define MXM_THRESHOLD_DIAGNOSTIC_AFTER_CYCLES (10u)
103 
104 /** length of voltage-read array */
105 #define MXM_VOLTAGE_READ_ARRAY_LENGTH (MXM_MAXIMUM_NR_OF_CELLS_PER_MODULE + 3u)
106 
107 /** number of cells that are in the LSB register of i.e. pin open diagnostic */
108 #define MXM_CELLS_IN_LSB (8u)
109 
110 /** unipolar full-scale reference value for cell voltage in mV */
111 #define MXM_REF_UNIPOLAR_CELL_mV (5000u)
112 
113 /*========== Extern Constant and Variable Declarations ======================*/
114 
115 /*========== Extern Function Prototypes =====================================*/
116 /**
117  * @brief Main state-machine implementation
118  * @details This state-machine handles the main state of the driver.
119  * It runs the self-check, initializes communication and then
120  * transitions into the operation state in which it
121  * executes the state-machine described in
122  * #MXM_StateMachineOperation().
123  * @param[in,out] pInstance used as both input and output (stores
124  * state-information, requests and intermediate
125  * values)
126  */
127 extern void MXM_StateMachine(MXM_MONITORING_INSTANCE_s *pInstance);
128 
129 /**
130  * @brief Initializes the state structs with default values
131  * @details This function is called through the startup of the driver in order
132  * to ensure proper default values.
133  * @param[out] pBalancingInstance instance of the balancing state struct that shall be initialized
134  * @param[out] pMonitoringInstance instance of the monitoring state struct that shall be initialized
135  */
136 extern void MXM_InitializeStateStruct(
137  MXM_BALANCING_STATE_s *pBalancingInstance,
138  MXM_MONITORING_INSTANCE_s *pMonitoringInstance);
139 
140 /**
141  * @brief Function that checks if the error counter can be reset
142  * @param[in,out] pInstance pointer to the state struct
143  */
145 
146 /**
147  * @brief Fill the balancing datastructure
148  * @details This function fills the data-structure that describes
149  * which balancing channels of the monitoring ICs should be
150  * activated.
151  * @param[in,out] pBalancingInstance pointer to the balancing state
152  * @return #STD_NOT_OK in case of invalid access
153  */
155 
156 /**
157  * @brief Handle the statemachine-transactions for a WRITEALL
158  * @details Before calling this function, update the command buffer of
159  * the state-variable. Then call this function and pass on the
160  * state-variable and the next state. The function will
161  * handle the communication with the lower state-machine and
162  * will transition into the next state, if the command has
163  * been sent successfully.
164  * @param[in,out] pInstance pointer to instance of the mxm
165  * monitoring state-machine
166  * @param[in] nextState state that should be entered upon successful
167  * completion
168  */
169 extern void MXM_HandleStateWriteall(
170  MXM_MONITORING_INSTANCE_s *pInstance,
172 
173 /**
174  * @brief Handle the statemachine-transactions for a READALL
175  * @details Call this function and pass on the state-variable, the
176  * register to be read and the next state. The function will
177  * handle the communication with the lower state-machine and
178  * will transition into the next state, if the command has
179  * been sent successfully. Moreover it will return true when
180  * transitioning. The return value has to be checked and used
181  * to execute additional code if necessary.
182  * @param[in,out] pInstance pointer to instance of the mxm
183  * monitoring state-machine
184  * @param[in] registerName register that should be read
185  * @param[in] nextState state that should be entered upon successful
186  * completion
187  * @return true when the state has been handled, false otherwise, use
188  * this to execute additional code when the message has been
189  * read.
190  */
192  MXM_MONITORING_INSTANCE_s *pInstance,
193  MXM_REG_NAME_e registerName,
195 
196 /**
197  * @brief Processes the retrieved information on open wire
198  * @details Parses through a retrieved RX buffer and writes into the
199  * database.
200  * @param[in,out] kpkInstance pointer to instance of the Maxim monitoring
201  * state-machine
202  * @return returns the return value of the database write function #DATA_Write1DataBlock()
203  */
204 extern STD_RETURN_TYPE_e MXM_ProcessOpenWire(const MXM_MONITORING_INSTANCE_s *const kpkInstance);
205 
206 /**
207  * @brief This error handler is used as a last resort and tries a reset of the complete driver
208  * @details A reset is done by setting the relevant flag in the state struct
209  * and waiting for the reset to occur (done by AFE on next tick).
210  * Before this last resort measure is taken, a error counter has to
211  * be counted up.
212  * @param[in,out] pInstance pointer to the state struct in order to write the reset flag
213  * @param[in] immediateReset if set to true, a reset will be requested independently of the error counter
214  */
215 extern void MXM_ErrorHandlerReset(MXM_MONITORING_INSTANCE_s *pInstance, bool immediateReset);
216 
217 /**
218  * @brief State-Machine implementation for operation state
219  * @details This state-machine contains the "program" with which the
220  * connected monitoring satellites are controlled. It is
221  * entered by #MXM_StateMachine() once the daisy-chain has
222  * been initialized and is in operation state.
223  * @param[in,out] pState used as both input and output (stores
224  * state-information, requests and intermediate values)
225  */
227 
228 /**
229  * @brief Encapsulation for reading voltages from a register
230  * @details This function encapsulates the request of state-changes and
231  * following conversion for the reading of an arbitrary
232  * measurement voltage of the daisy-chain. Its parameters are
233  * a variable for tracking the state of the underlying
234  * state-machines and the register address that has to be
235  * queried. It returns whether the action has been successful
236  * or not.
237  * In order to obtain all cell voltages this function has to
238  * be called for every relevant register address.
239  * @param[in,out] pState pointer to the state-machine struct
240  * @param[in] regAddress register address that shall be queried
241  * @return current state of the action:
242  * - MXM_MON_STATE_PASS upon completion
243  * - MXM_MON_STATE_PENDING as long as the action is
244  * ongoing
245  * - MXM_MON_STATE_FAIL if the function failed and could
246  * not recover on its own
247  */
250 
251 /**
252  * @brief Copies measured voltage data into the database.
253  * @details This function copies the acquired voltage data from
254  * #MXM_MONITORING_INSTANCE_s::localVoltages into the database-struct
255  * #mxm_tableCellVoltages and copies this struct into the database.
256  * This action is required due to different data layouts. This driver
257  * always stores its cell-voltages in an array with 14*32 = 448 cells
258  * in order to reduce the amount of different configurations and
259  * variants.
260  *
261  * This function maps these values into the database-struct which
262  * scales with the number of connected cells and monitoring ICs.
263  * @param[in] kpkInstance pointer to the #MXM_MONITORING_INSTANCE_s struct
264  * @return #STD_OK if the action was successful or #STD_NOT_OK otherwise
265  */
267 
268 /**
269  * @brief returns the model ID of the daisy chain
270  * @details this function is to be implemented by the driver in order to
271  * tell the rest of the driver which model is used. Currently, this
272  * implementation does not support mixed model daisy-chains.
273  * @returns model ID of daisy-chain
274  */
276 
277 /**
278  * @brief Execute all preinit selfchecks.
279  * @details Executes the following self-checks:
280  * - #MXM_CRC8SelfTest()
281  * - #MXM_ConvertTest()
282  * - #MXM_FirstSetBitTest()
283  * - #MXM_ExtractValueFromRegisterTest()
284  * - #MXM_ParseVoltageReadallTest()
285  * - #MXM_5XUserAccessibleAddressSpaceCheckerSelfCheck()
286  *
287  * These self-checks do not need an initialized daisy-chain
288  * and can therefore be executed at startup of the
289  * state-machine.
290  *
291  * After execution of each test, the return value is stored in
292  * the supplied state-struct. The function returns whether the
293  * self-check has successfully passed.
294  * @param[in,out] pState pointer to the state-struct, will write status into
295  * @return #STD_OK on success, #STD_NOT_OK on failure,
296  * return value has to be used
297  */
299 
300 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
301 #ifdef UNITY_UNIT_TEST
302 extern STD_RETURN_TYPE_e TEST_MXM_ParseVoltageReadallTest(MXM_MONITORING_INSTANCE_s *pInstance);
303 extern STD_RETURN_TYPE_e TEST_MXM_ParseVoltagesIntoDB(MXM_MONITORING_INSTANCE_s *pInstance);
304 extern STD_RETURN_TYPE_e TEST_MXM_ParseVoltageReadall(
305  uint8_t *voltRxBuffer,
306  uint16_t voltRxBufferLength,
307  MXM_DATA_STORAGE_s *datastorage,
308  MXM_CONVERSION_TYPE_e conversionType);
309 #endif
310 
311 #endif /* FOXBMS__MXM_1785X_H_ */
Database configuration header.
Definition of foxBMS standard types.
STD_RETURN_TYPE_e
Definition: fstd_types.h:82
General macros and definitions for the whole platform.
#define GEN_MUST_CHECK_RETURN
Allows functions to generate warnings in GCC for unused returns.
Definition: general.h:87
Headers for the driver for the MAX17841B ASCI and MAX1785x analog front-end.
void MXM_CheckIfErrorCounterCanBeReset(MXM_MONITORING_INSTANCE_s *pInstance)
Function that checks if the error counter can be reset.
Definition: mxm_1785x.c:896
STD_RETURN_TYPE_e MXM_PreInitSelfCheck(MXM_MONITORING_INSTANCE_s *pState)
Execute all preinit selfchecks.
Definition: mxm_1785x.c:1245
void MXM_ErrorHandlerReset(MXM_MONITORING_INSTANCE_s *pInstance, bool immediateReset)
This error handler is used as a last resort and tries a reset of the complete driver.
Definition: mxm_1785x.c:909
bool GEN_MUST_CHECK_RETURN MXM_HandleStateReadall(MXM_MONITORING_INSTANCE_s *pInstance, MXM_REG_NAME_e registerName, MXM_STATEMACHINE_OPERATION_STATES_e nextState)
Handle the statemachine-transactions for a READALL.
Definition: mxm_1785x.c:948
MXM_MODEL_ID_e MXM_GetModelIdOfDaisyChain(void)
returns the model ID of the daisy chain
Definition: mxm_17852.c:96
STD_RETURN_TYPE_e MXM_ProcessOpenWire(const MXM_MONITORING_INSTANCE_s *const kpkInstance)
Processes the retrieved information on open wire.
Definition: mxm_1785x.c:979
void MXM_StateMachineOperation(MXM_MONITORING_INSTANCE_s *pState)
State-Machine implementation for operation state.
Definition: mxm_17852.c:100
STD_RETURN_TYPE_e MXM_ParseVoltagesIntoDB(const MXM_MONITORING_INSTANCE_s *const kpkInstance)
Copies measured voltage data into the database.
Definition: mxm_1785x.c:1083
STD_RETURN_TYPE_e MXM_ConstructBalancingBuffer(MXM_BALANCING_STATE_s *pBalancingInstance)
Fill the balancing datastructure.
Definition: mxm_1785x.c:1024
void MXM_StateMachine(MXM_MONITORING_INSTANCE_s *pInstance)
Main state-machine implementation.
Definition: mxm_1785x.c:1322
void MXM_InitializeStateStruct(MXM_BALANCING_STATE_s *pBalancingInstance, MXM_MONITORING_INSTANCE_s *pMonitoringInstance)
Initializes the state structs with default values.
Definition: mxm_1785x.c:1172
MXM_MONITORING_STATE_e GEN_MUST_CHECK_RETURN MXM_MonGetVoltages(MXM_MONITORING_INSTANCE_s *pState, MXM_REG_NAME_e regAddress)
Encapsulation for reading voltages from a register.
Definition: mxm_1785x.c:1283
void MXM_HandleStateWriteall(MXM_MONITORING_INSTANCE_s *pInstance, MXM_STATEMACHINE_OPERATION_STATES_e nextState)
Handle the statemachine-transactions for a WRITEALL.
Definition: mxm_1785x.c:920
This is a collection of helper functions for the MAX1785x ICs.
MXM_MONITORING_STATE_e
MXM_STATEMACHINE_OPERATION_STATES_e
Basic defines for the complete Maxim driver.
MXM_MODEL_ID_e
Type of monitoring device.
MXM_CONVERSION_TYPE_e
Headers for the driver for the MAX17841B ASCI and MAX1785x analog front-end.
Header for the configuration for the Maxim analog front-end.
Headers for the CRC8 calculation for Maxim Integrated Monitoring devices.
MXM_REG_NAME_e
MAX1785x register names.