foxBMS - Unit Tests  1.4.1
The foxBMS Unit Tests API Documentation
mxm_1785x.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2022, 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 2022-10-27 (date of last update)
47  * @version v1.4.1
48  * @ingroup DRIVERS
49  * @prefix MXM
50  *
51  * @brief Headers for the driver for the MAX17841B ASCI and MAX1785x monitoring chip
52  *
53  * @details def
54  *
55  */
56 
57 /**
58  * @brief Battery monitoring driver for MAX1785x battery monitoring ICs.
59  *
60  * This module supplies a driver for the Battery Monitoring ICs of the
61  * MAX1785x-family by Maxim Integrated.
62  *
63  * Entry point for the module is the function #MXM_Tick() in mxm_afe.c. It handles
64  * the measurement flow and the coordination of the underlying state-machines.
65  * Below this layer two state-machines are implemented.
66  *
67  * The state-machine in mxm_battery_management.c is executed with the
68  * #MXM_5XStateMachine()-function.
69  * This state-machine exposes commands of the Maxim Battery Management Protocol
70  * to the upper layers. Below, it translates these commands into state-changes
71  * for the underlying state-machine.
72  * This state-machine is implemented in mxm_17841b.c and executed with
73  * #MXM_41BStateMachine(). It handles the register- and buffer-transactions
74  * required for the MAX17841B communication interface (Maxim calls
75  * this chip ASCI).
76  *
77  */
78 
79 #ifndef FOXBMS__MXM_1785X_H_
80 #define FOXBMS__MXM_1785X_H_
81 
82 /*========== Includes =======================================================*/
83 #include "database_cfg.h"
84 #include "mxm_cfg.h"
85 
86 #include "mxm_17841b.h"
87 #include "mxm_1785x_tools.h"
88 #include "mxm_basic_defines.h"
89 #include "mxm_battery_management.h"
90 #include "mxm_crc8.h"
91 
92 /*========== Macros and Definitions =========================================*/
93 
94 /** threshold of iterations after which a diagnostic cycle is entered by the state-machine */
95 #define MXM_THRESHOLD_DIAGNOSTIC_AFTER_CYCLES (10u)
96 
97 /** length of voltage-read array */
98 #define MXM_VOLTAGE_READ_ARRAY_LENGTH (MXM_MAXIMUM_NR_OF_CELLS_PER_MODULE + 3u)
99 
100 /** number of cells that are in the LSB register of i.e. pin open diagnostic */
101 #define MXM_CELLS_IN_LSB (8u)
102 
103 /** unipolar full-scale reference value for cell voltage in mV */
104 #define MXM_REF_UNIPOLAR_CELL_mV (5000u)
105 
106 /*========== Extern Constant and Variable Declarations ======================*/
107 
108 /*========== Extern Function Prototypes =====================================*/
109 /**
110  * @brief Main state-machine implementation
111  * @details This state-machine handles the main state of the driver.
112  * It runs the self-check, initializes communication and then
113  * transitions into the operation state in which it
114  * executes the state-machine described in
115  * #MXM_StateMachineOperation().
116  * @param[in,out] pInstance used as both input and output (stores
117  * state-information, requests and intermediate
118  * values)
119  */
120 extern void MXM_StateMachine(MXM_MONITORING_INSTANCE_s *pInstance);
121 
122 /**
123  * @brief Initializes the state structs with default values
124  * @details This function is called through the startup of the driver in order
125  * to ensure proper default values.
126  * @param[out] pBalancingInstance instance of the balancing state struct that shall be initialized
127  * @param[out] pMonitoringInstance instance of the monitoring state struct that shall be initialized
128  */
129 extern void MXM_InitializeStateStruct(
130  MXM_BALANCING_STATE_s *pBalancingInstance,
131  MXM_MONITORING_INSTANCE_s *pMonitoringInstance);
132 
133 /**
134  * @brief Function that checks if the error counter can be reset
135  * @param[in,out] pInstance pointer to the state struct
136  */
138 
139 /**
140  * @brief Fill the balancing datastructure
141  * @details This function fills the data-structure that describes
142  * which balancing channels of the monitoring ICs should be
143  * activated.
144  * @param[in,out] pBalancingInstance pointer to the balancing state
145  * @return #STD_NOT_OK in case of invalid access
146  */
148 
149 /**
150  * @brief Handle the statemachine-transactions for a WRITEALL
151  * @details Before calling this function, update the command buffer of
152  * the state-variable. Then call this function and pass on the
153  * state-variable and the next state. The function will
154  * handle the communication with the lower state-machine and
155  * will transition into the next state, if the command has
156  * been sent successfully.
157  * @param[in,out] pInstance pointer to instance of the mxm
158  * monitoring state-machine
159  * @param[in] nextState state that should be entered upon successful
160  * completion
161  */
162 extern void MXM_HandleStateWriteall(
163  MXM_MONITORING_INSTANCE_s *pInstance,
165 
166 /**
167  * @brief Handle the statemachine-transactions for a READALL
168  * @details Call this function and pass on the state-variable, the
169  * register to be read and the next state. The function will
170  * handle the communication with the lower state-machine and
171  * will transition into the next state, if the command has
172  * been sent successfully. Moreover it will return true when
173  * transitioning. The return value has to be checked and used
174  * to execute additional code if necessary.
175  * @param[in,out] pInstance pointer to instance of the mxm
176  * monitoring state-machine
177  * @param[in] registerName register that should be read
178  * @param[in] nextState state that should be entered upon successful
179  * completion
180  * @return true when the state has been handled, false otherwise, use
181  * this to execute additional code when the message has been
182  * read.
183  */
185  MXM_MONITORING_INSTANCE_s *pInstance,
186  MXM_REG_NAME_e registerName,
188 
189 /**
190  * @brief Processes the retrieved information on openwire
191  * @details Parses through a retrieved RX buffer and writes into the
192  * database.
193  * @param[in,out] kpkInstance pointer to instance of the Maxim monitoring
194  * state-machine
195  * @return returns the return value of the database write function #DATA_Write1DataBlock()
196  */
197 extern STD_RETURN_TYPE_e MXM_ProcessOpenWire(const MXM_MONITORING_INSTANCE_s *const kpkInstance);
198 
199 /**
200  * @brief This error handler is used as a last resort and tries a reset of the complete driver
201  * @details A reset is done by setting the relevant flag in the state struct
202  * and waiting for the reset to occur (done by AFE on next tick).
203  * Before this last resort measure is taken, a error counter has to
204  * be counted up.
205  * @param[in,out] pInstance pointer to the state struct in order to write the reset flag
206  * @param[in] immediateReset if set to true, a reset will be requested independently of the error counter
207  */
208 extern void MXM_ErrorHandlerReset(MXM_MONITORING_INSTANCE_s *pInstance, bool immediateReset);
209 
210 /**
211  * @brief State-Machine implementation for operation state
212  * @details This state-machine contains the "program" with which the
213  * connected monitoring satellites are controlled. It is
214  * entered by #MXM_StateMachine() once the daisy-chain has
215  * been initialized and is in operation state.
216  * @param[in,out] pState used as both input and output (stores
217  * state-information, requests and intermediate values)
218  */
220 
221 /**
222  * @brief Encapsulation for reading voltages from a register
223  * @details This function encapsulates the request of state-changes and
224  * following conversion for the reading of an arbitrary
225  * measurement voltage of the daisy-chain. Its parameters are
226  * a variable for tracking the state of the underlying
227  * state-machines and the register address that has to be
228  * queried. It returns whether the action has been successful
229  * or not.
230  * In order to obtain all cell voltages this function has to
231  * be called for every relevant register address.
232  * @param[in,out] pState pointer to the state-machine struct
233  * @param[in] regAddress register address that shall be queried
234  * @return current state of the action:
235  * - MXM_MON_STATE_PASS upon completion
236  * - MXM_MON_STATE_PENDING as long as the action is
237  * ongoing
238  * - MXM_MON_STATE_FAIL if the function failed and could
239  * not recover on its own
240  */
243 
244 /**
245  * @brief Copies measured voltage data into the database.
246  * @details This function copies the acquired voltage data from
247  * #MXM_MONITORING_INSTANCE_s::localVoltages into the database-struct
248  * #mxm_tableCellVoltages and copies this struct into the database.
249  * This action is required due to different data layouts. This driver
250  * always stores its cell-voltages in an array with 14*32 = 448 cells
251  * in order to reduce the amount of different configurations and
252  * variants.
253  *
254  * This function maps these values into the database-struct which
255  * scales with the number of connected cells and monitoring ICs.
256  * @param[in] kpkInstance pointer to the #MXM_MONITORING_INSTANCE_s struct
257  * @return #STD_OK if the action was successful or #STD_NOT_OK otherwise
258  */
260 
261 /**
262  * @brief returns the model ID of the daisy chain
263  * @details this function is to be implemented by the driver in order to
264  * tell the rest of the driver which model is used. Currently, this
265  * implementation does not support mixed model daisy-chains.
266  * @returns model ID of daisy-chain
267  */
269 
270 /**
271  * @brief Execute all preinit selfchecks.
272  * @details Executes the following self-checks:
273  * - #MXM_CRC8SelfTest()
274  * - #MXM_ConvertTest()
275  * - #MXM_FirstSetBitTest()
276  * - #MXM_ExtractValueFromRegisterTest()
277  * - #MXM_ParseVoltageReadallTest()
278  * - #MXM_5XUserAccessibleAddressSpaceCheckerSelfCheck()
279  *
280  * These self-checks do not need an initialized daisy-chain
281  * and can therefore be executed at startup of the
282  * state-machine.
283  *
284  * After execution of each test, the return value is stored in
285  * the supplied state-struct. The function returns whether the
286  * self-check has successfully passed.
287  * @param[in,out] pState pointer to the state-struct, will write status into
288  * @return #STD_OK on success, #STD_NOT_OK on failure,
289  * return value has to be used
290  */
292 
293 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
294 #ifdef UNITY_UNIT_TEST
298  uint8_t *voltRxBuffer,
299  uint16_t voltRxBufferLength,
300  MXM_DATA_STORAGE_s *datastorage,
301  MXM_CONVERSION_TYPE_e conversionType);
302 #endif
303 
304 #endif /* FOXBMS__MXM_1785X_H_ */
Database configuration header.
STD_RETURN_TYPE_e
Definition: fstd_types.h:81
#define GEN_MUST_CHECK_RETURN
Allows functions to generate warnings in GCC for unused returns.
Definition: general.h:88
Headers for the driver for the MAX17841B ASCI and MAX1785x monitoring chip.
void MXM_CheckIfErrorCounterCanBeReset(MXM_MONITORING_INSTANCE_s *pInstance)
Function that checks if the error counter can be reset.
Definition: mxm_1785x.c:888
STD_RETURN_TYPE_e MXM_PreInitSelfCheck(MXM_MONITORING_INSTANCE_s *pState)
Execute all preinit selfchecks.
Definition: mxm_1785x.c:1237
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:901
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:940
MXM_MODEL_ID_e MXM_GetModelIdOfDaisyChain(void)
returns the model ID of the daisy chain
Definition: mxm_17852.c:91
STD_RETURN_TYPE_e MXM_ProcessOpenWire(const MXM_MONITORING_INSTANCE_s *const kpkInstance)
Processes the retrieved information on openwire.
Definition: mxm_1785x.c:971
void MXM_StateMachineOperation(MXM_MONITORING_INSTANCE_s *pState)
State-Machine implementation for operation state.
Definition: mxm_17852.c:95
STD_RETURN_TYPE_e TEST_MXM_ParseVoltagesIntoDB(MXM_MONITORING_INSTANCE_s *pInstance)
Definition: mxm_1785x.c:1426
STD_RETURN_TYPE_e MXM_ParseVoltagesIntoDB(const MXM_MONITORING_INSTANCE_s *const kpkInstance)
Copies measured voltage data into the database.
Definition: mxm_1785x.c:1075
STD_RETURN_TYPE_e MXM_ConstructBalancingBuffer(MXM_BALANCING_STATE_s *pBalancingInstance)
Fill the balancing datastructure.
Definition: mxm_1785x.c:1016
void MXM_StateMachine(MXM_MONITORING_INSTANCE_s *pInstance)
Main state-machine implementation.
Definition: mxm_1785x.c:1314
void MXM_InitializeStateStruct(MXM_BALANCING_STATE_s *pBalancingInstance, MXM_MONITORING_INSTANCE_s *pMonitoringInstance)
Initializes the state structs with default values.
Definition: mxm_1785x.c:1164
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:1275
STD_RETURN_TYPE_e TEST_MXM_ParseVoltageReadallTest(MXM_MONITORING_INSTANCE_s *pInstance)
Definition: mxm_1785x.c:1423
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:912
STD_RETURN_TYPE_e TEST_MXM_ParseVoltageReadall(uint8_t *voltRxBuffer, uint16_t voltRxBufferLength, MXM_DATA_STORAGE_s *datastorage, MXM_CONVERSION_TYPE_e conversionType)
Definition: mxm_1785x.c:1429
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 monitoring chip.
Header for the configuration for the Maxim monitoring chip.
Headers for the CRC8 calculation for Maxim Integrated Monitoring devices.
MXM_REG_NAME_e
MAX1785x register names.