foxBMS - Unit Tests  1.3.0
The foxBMS Unit Tests API Documentation
mxm_battery_management.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_battery_management.h
44  * @author foxBMS Team
45  * @date 2019-01-14 (date of creation)
46  * @updated 2022-05-30 (date of last update)
47  * @version v1.3.0
48  * @ingroup DRIVERS
49  * @prefix MXM
50  *
51  * @brief Headers for the driver for the MAX17841B ASCI and
52  * MAX1785x monitoring chip
53  *
54  * @details def
55  *
56  */
57 
58 #ifndef FOXBMS__MXM_BATTERY_MANAGEMENT_H_
59 #define FOXBMS__MXM_BATTERY_MANAGEMENT_H_
60 
61 /*========== Includes =======================================================*/
62 #include "mxm_cfg.h"
63 
64 #include "mxm_17841b.h"
65 #include "mxm_basic_defines.h"
66 #include "mxm_crc8.h"
67 #include "mxm_register_map.h"
68 
69 /*========== Macros and Definitions =========================================*/
70 
71 /** length of the command buffer */
72 #define COMMAND_BUFFER_LENGTH (10u)
73 
74 /** length of the rx buffer */
75 #define MXM_5X_RX_BUFFER_LEN 100u
76 
77 /** seed for helloall, should be 0x00u except for special edge cases */
78 #define HELLOALL_START_SEED 0x00u
79 /** seed for data check, should be 0x00u */
80 #define DATA_CHECK_BYTE_SEED 0x00u
81 
82 /**
83  * @brief Type for Battery Management Protocol commands.
84  * @details This type describes the hex-numbers of all Maxim Battery
85  * Management Protocol commands. For details see the
86  * data sheet of MAX1785x devices.
87  */
89 
90 /**
91  * @brief HELLOALL message
92  */
93 #define BATTERY_MANAGEMENT_HELLOALL ((MXM_BATTERY_MANAGEMENT_COMMAND_t)0x57u)
94 
95 /**
96  * @brief ALERTPACKET message
97  */
98 #define BATTERY_MANAGEMENT_ALERTPACKET ((MXM_BATTERY_MANAGEMENT_COMMAND_t)0x21u)
99 
100 /**
101  * @brief WRITEDEVICE message (write single register of a single device)
102  */
103 #define BATTERY_MANAGEMENT_WRITEDEVICE ((MXM_BATTERY_MANAGEMENT_COMMAND_t)0x04u)
104 
105 /**
106  * @brief WRITEALL message (write single register of all daisy-chain devices)
107  */
108 #define BATTERY_MANAGEMENT_WRITEALL ((MXM_BATTERY_MANAGEMENT_COMMAND_t)0x02u)
109 
110 /**
111  * @brief READDEVICE message (read single register of a single device)
112  */
113 #define BATTERY_MANAGEMENT_READDEVICE ((MXM_BATTERY_MANAGEMENT_COMMAND_t)0x05u)
114 
115 /**
116  * @brief READALL message (read single register of all daisy-chain devices)
117  */
118 #define BATTERY_MANAGEMENT_READALL ((MXM_BATTERY_MANAGEMENT_COMMAND_t)0x03u)
119 
120 /**
121  * @brief READBLOCK message (read block of registers of a single device)
122  */
123 #define BATTERY_MANAGEMENT_READBLOCK ((MXM_BATTERY_MANAGEMENT_COMMAND_t)0x06u)
124 
125 /**
126  * @brief DOWNHOST message (make the downhost writing)
127  * @details This feature is only useable on downhost line.
128  */
129 #define BATTERY_MANAGEMENT_DOWNHOST ((MXM_BATTERY_MANAGEMENT_COMMAND_t)0x09u)
130 
131 /**
132  * @brief UPHOST message (make the uphost writing, only useable on uphost line)
133  */
134 #define BATTERY_MANAGEMENT_UPHOST ((MXM_BATTERY_MANAGEMENT_COMMAND_t)0x08u)
135 
136 /**
137  * @brief Battery Management Protocol lengths of TX buffer
138  * @details Reference values for the lengths of the respective TX buffers
139  * for Battery Management Protocol messages.
140  */
141 
142 /**
143  * @brief length of a READALL command without stuffing bytes
144  */
145 #define BATTERY_MANAGEMENT_TX_LENGTH_READALL ((uint8_t)4u)
146 
147 /**
148  * @brief States of the Battery Management Protocol state-machine
149  */
150 typedef enum {
151  MXM_STATEMACH_5X_UNINITIALIZED, /*!< Uninitialized state that the state-machine starts in */
152  MXM_STATEMACH_5X_INIT, /*!< Initialization state */
153  MXM_STATEMACH_5X_41B_FMEA_CHECK, /*!< Requests a FMEA-check from the 41B-state-machine */
154  MXM_STATEMACH_5X_IDLE, /*!< Idle state, transitions are possible in this state */
155  MXM_STATEMACH_5X_WRITEALL, /*!< WRITEALL state, sends a WRITEALL to the daisy-chain */
156  MXM_STATEMACH_5X_WRITE_DEVICE, /*!< WRITEDEVICE state, sends a WRITEDEVICE to a specific address */
157  MXM_STATEMACH_5X_READALL, /*!< READALL state, sends a READALL to the daisy-chain */
158  MXM_STATEMACH_5X_MAXSTATE, /*!< Highest state */
160 
161 /**
162  * @brief Sub-states of the Battery Management Protocol state-machine
163  */
164 typedef enum {
165  MXM_5X_INIT_41B_INIT, /*!< initialization of the MAX17841 bridge IC */
166  MXM_5X_INIT_41B_GET_VERSION, /*!< retrieves the version of the bridge IC */
167  /** waits for the slave devices to be reset (due to disabled preambles) */
169  /** substate for the initialization, enable RX interrupt flags */
171  /** substate for the wake-up routine, clear the receive buffer in the
172  * bridge IC */
174  /** substate for the wake-up routine, enable the sending of preambles in
175  * order to wake up the daisy-chain devices */
177  MXM_5X_INIT_ENABLE_KEEP_ALIVE, /*!< enables keep alive mode (which will take over after en preambles is off) */
178  /** substate for the wake-up routine, wait for the daisy-chain devices to
179  * return an answer, resulting in status RX busy of the bridge IC */
181  /** substate for the wake-up routine, disable the sending of preambles */
183  /** substate for the wake-up routine, wait for the RX transmission to
184  * finish */
186  /** substate for the wake-up routine, clear the transmit buffer */
188  /** substate for the wake-up routine, clear the receive buffer */
190  /** substate for the wake-up routine, sending helloall to the daisy-chain */
192  /** substate for the wake-up routine, verifying the result of helloall */
194  /** substate for requesting an FMEA check on the bridge IC */
196  /** substate for the verification of the FMEA check done in
197  * #MXM_5X_41B_FMEA_REQUEST */
199  /** substate for the initiation of a uart transaction for the WRITEALL
200  * and WRITEDEVICE command */
202  /** substate for checking the received CRC in a WRITEALL/WRITEDEVICE transaction */
204  /** substate for the initiation of a uart transaction for the READALL
205  * command */
207  /** substate for checking the received CRC in a READALL transaction */
209  /** substate for retrieving the data check byte from a READALL transaction */
211  /** default value indicating no selected substate; has to be last substate in enum */
214 
215 /**
216  * @brief Request status of Battery Management Protocol states.
217  * @details This enum describes the states that a state in the
218  * #MXM_5XStateMachine() can have.
219  *
220  * Alternating bit patterns are used for better distinction
221  * and to make sure that there is no accidental overlap.
222  */
223 typedef enum {
224  MXM_5X_STATE_UNSENT = 0x56, /*!< The request has not been sent to the state-machine yet. */
226  0x67, /*!< The request has been received by the state-machine, but not been processed yet. */
227  MXM_5X_STATE_PROCESSED = 0x9A, /*!< The request has been process successfully */
228  MXM_5X_STATE_ERROR = 0xAB, /*!< An error has occurred during processing of the request. */
230 
231 /**
232  * @brief Payload command
233  */
234 typedef struct {
235  MXM_REG_NAME_e regAddress; /*!< register address that shall be written */
236  uint8_t lsb; /*!< least significant bit */
237  uint8_t msb; /*!< most significant bit */
238  uint8_t blocksize; /*!< blocksize for the READBLOCK command */
239  uint8_t deviceAddress; /*!< device address for commands that address specific devices */
240  MXM_MODEL_ID_e model; /*!< model of device that shall be addressed */
242 
243 /**
244  * @brief 5x statemachine structure
245  **/
246 typedef struct {
247  MXM_STATEMACHINE_5X_e state; /*!< state of Driver State Machine */
248  MXM_5X_SUBSTATES_e substate; /*!< substate of current Driver State */
249  MXM_5X_COMMAND_PAYLOAD_s commandPayload; /*!< command payload of the Battery Management Protocol */
250  MXM_5X_STATE_REQUEST_STATUS_e *processed; /*!< status-indicator of the underlying state-machine */
251  MXM_41B_STATE_REQUEST_STATUS_e status41b; /*!< for tracking of 41B state-machine */
252  /**
253  * @brief Number of satellites
254  * @details This variable tracks the number of monitoring ICs that have been
255  * found during the enumeration of all connected monitoring ICs.
256  * Therefore this variable is initialized with 0. This value will be
257  * compared with the expected number of monitoring ICs which is set in
258  * #BS_NR_OF_MODULES_PER_STRING.
259  */
261  /**
262  * @brief Number of monitoring ICs matches the expected number.
263  * @details This status variable indicates whether the number of found
264  * monitoring ICs in #MXM_5X_INSTANCE_s::numberOfSatellites
265  * matches with the configured number of monitoring ICs in
266  * #BS_NR_OF_MODULES_PER_STRING. This variable is updated during execution of
267  * the substate
268  * #MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_HELLOALL_VERIFY_MSG_AND_COUNT
269  * in the state #MXM_STATEMACH_5X_INIT in #MXM_5XStateMachine().
270  *
271  * In case the numbers are the same, the variable will read #STD_OK,
272  * otherwise it will be set to #STD_NOT_OK.
273  */
275  /**
276  * @brief Tracks the last received DC byte.
277  */
278  uint8_t lastDCByte;
279  uint8_t errorCounter; /*!< counts the number of errors that the underlying state-machine has encountered. */
280  uint32_t resetWaitTimestamp; /*!< timestamp of the moment when waiting for the devices to be reset has started */
281  /**
282  * @brief Length of Command Buffer
283  * @details Length of the array #MXM_5X_INSTANCE_s::commandBuffer.
284  */
286  /**
287  * @brief Command Buffer
288  * @details This variable contains a buffer for Battery Management Protocol
289  * commands. The content is constructed by calling functions like
290  * #MXM_5XConstructCommandBufferHelloall() and similar.
291  *
292  * Afterwards this buffer can be passed on to the lower state-machine
293  * as payload. The length of this buffer is described in
294  * #MXM_5X_INSTANCE_s::commandBufferCurrentLength.
295  */
297  uint16_t rxBuffer[MXM_5X_RX_BUFFER_LEN]; /*!< array containing the buffer for received data */
299 
300 /*========== Extern Constant and Variable Declarations ======================*/
301 
302 /*========== Extern Function Prototypes =====================================*/
303 
304 /**
305  * @brief Execute state-machine for Battery Management Protocol.
306  * @details This function executes the state-machine that exposes an interface
307  * for the Maxim Battery Management Protocol for monitoring ICs
308  * of the MAX1785x family.
309  */
310 extern void MXM_5XStateMachine(MXM_41B_INSTANCE_s *pInstance41b, MXM_5X_INSTANCE_s *pInstance5x);
311 
312 /**
313  * @brief Returns the last received DC byte.
314  * @param[in] kpkInstance pointer to the instance struct
315  */
316 extern MXM_DC_BYTE_e MXM_5XGetLastDCByte(const MXM_5X_INSTANCE_s *const kpkInstance);
317 
318 /**
319  * @brief Get the value of #MXM_5X_INSTANCE_s::numberOfSatellitesIsGood
320  * @param[in] kpkInstance pointer to the instance struct
321  *
322  * @return #MXM_5X_INSTANCE_s::numberOfSatellitesIsGood
323  */
325 
326 /**
327  * @brief Copy RX buffer into variable.
328  * @details This function copies the RX buffer which is locally available in
329  * the #MXM_5XStateMachine() into a supplied array pointer.
330  * It will make sure that both the length of the local as also the
331  * supplied length of the RX buffer are not violated.
332  * In case of the supplied RX buffer being longer than the locally
333  * available one, the remaining entries of the buffer will be
334  * filled with 0.
335  * @param[in,out] kpkInstance pointer to the state-struct
336  * @param[in] rxBuffer array-pointer to a RX buffer that shall be filled
337  * @param[in] rxBufferLength length of the supplied array
338  * @return #STD_NOT_OK for rxBuffer being a #NULL_PTR or rxBufferLength
339  * having length 0
340  */
342  const MXM_5X_INSTANCE_s *const kpkInstance,
343  uint8_t *rxBuffer,
344  uint16_t rxBufferLength);
345 
346 /**
347  * @brief Get number of satellites
348  * @details Getter-function for the number of satellites
349  * (variable #MXM_5X_INSTANCE_s::numberOfSatellites).
350  * @param[in] kpkInstance pointer to the state struct
351  * @return value of #MXM_5X_INSTANCE_s::numberOfSatellites
352  */
353 extern uint8_t MXM_5XGetNumberOfSatellites(const MXM_5X_INSTANCE_s *const kpkInstance);
354 
355 /**
356  * @brief Set state request for the Battery Management Statemachine
357  * @details This function sets the state requests for the #MXM_5XStateMachine().
358  * @param[in,out] pInstance5x pointer to the 5x state
359  * @param[in] state State that is requested
360  * @param[in] commandPayload additional payload that is handled by the state
361  * @param[in,out] processed pointer to the status of the request
362  * @return #STD_OK if the request has been successfully placed,
363  * #STD_NOT_OK if not
364  */
366  MXM_5X_INSTANCE_s *pInstance5x,
367  MXM_STATEMACHINE_5X_e state,
368  MXM_5X_COMMAND_PAYLOAD_s commandPayload,
369  MXM_5X_STATE_REQUEST_STATUS_e *processed);
370 
371 /**
372  * @brief runs a selfcheck for the address space check
373  * @details Runs a selfcheck for the function which is checking if a register
374  * address is inside the user accessible address space of the
375  * monitoring IC.
376  * @return #STD_OK if the selfcheck has been successful
377  */
379 
380 /**
381  * @brief Initializes the state struct with default values
382  * @details This function is called through the startup of the driver in order
383  * to ensure proper default values.
384  * @param[out] pInstance instance of the state struct that shall be initialized
385  */
386 extern void MXM_5X_InitializeStateStruct(MXM_5X_INSTANCE_s *pInstance);
387 
388 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
389 
390 #endif /* FOXBMS__MXM_BATTERY_MANAGEMENT_H_ */
STD_RETURN_TYPE_e
Definition: fstd_types.h:81
#define 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.
MXM_41B_STATE_REQUEST_STATUS_e
Request status of MAX17841B states.
Definition: mxm_17841b.h:131
Basic defines for the complete Maxim driver.
MXM_MODEL_ID_e
Type of monitoring device.
MXM_DC_BYTE_e
MXM_STATEMACHINE_5X_e
States of the Battery Management Protocol state-machine.
@ MXM_STATEMACH_5X_INIT
@ MXM_STATEMACH_5X_IDLE
@ MXM_STATEMACH_5X_READALL
@ MXM_STATEMACH_5X_WRITEALL
@ MXM_STATEMACH_5X_WRITE_DEVICE
@ MXM_STATEMACH_5X_UNINITIALIZED
@ MXM_STATEMACH_5X_MAXSTATE
@ MXM_STATEMACH_5X_41B_FMEA_CHECK
#define MXM_5X_RX_BUFFER_LEN
void MXM_5X_InitializeStateStruct(MXM_5X_INSTANCE_s *pInstance)
Initializes the state struct with default values.
MXM_5X_STATE_REQUEST_STATUS_e
Request status of Battery Management Protocol states.
@ MXM_5X_STATE_UNSENT
@ MXM_5X_STATE_PROCESSED
@ MXM_5X_STATE_UNPROCESSED
@ MXM_5X_STATE_ERROR
STD_RETURN_TYPE_e must_check_return MXM_5XUserAccessibleAddressSpaceCheckerSelfCheck(void)
runs a selfcheck for the address space check
void MXM_5XStateMachine(MXM_41B_INSTANCE_s *pInstance41b, MXM_5X_INSTANCE_s *pInstance5x)
Execute state-machine for Battery Management Protocol.
MXM_5X_SUBSTATES_e
Sub-states of the Battery Management Protocol state-machine.
@ MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_CLEAR_RECEIVE_BUFFER
@ MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_HELLOALL
@ MXM_5X_READALL_UART_TRANSACTION
@ MXM_5X_READALL_CHECK_CRC
@ MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_EN_PREAMBLES
@ MXM_5X_WRITE_CHECK_CRC
@ MXM_5X_INIT_41B_GET_VERSION
@ MXM_5X_READALL_GET_DC
@ MXM_5X_41B_FMEA_REQUEST
@ MXM_5X_INIT_ENABLE_RX_INTERRUPT_FLAGS
@ MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_CLEAR_RECEIVE_BUFFER_2
@ MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_HELLOALL_VERIFY_MSG_AND_COUNT
@ MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_WAIT_FOR_RX_STATUS_BUSY
@ MXM_5X_INIT_41B_INIT
@ MXM_5X_ENTRY_SUBSTATE
@ MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_WAIT_FOR_RX_STATUS_EMPTY
@ MXM_5X_INIT_WAIT_FOR_RESET
@ MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_CLEAR_TRANSMIT_BUFFER
@ MXM_5X_WRITE_UART_TRANSACTION
@ MXM_5X_INIT_ENABLE_KEEP_ALIVE
@ MXM_5X_41B_FMEA_CHECK
@ MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_DIS_PREAMBLES
uint8_t MXM_BATTERY_MANAGEMENT_COMMAND_t
Type for Battery Management Protocol commands.
STD_RETURN_TYPE_e MXM_5XGetRXBuffer(const MXM_5X_INSTANCE_s *const kpkInstance, uint8_t *rxBuffer, uint16_t rxBufferLength)
Copy RX buffer into variable.
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.
STD_RETURN_TYPE_e MXM_5XGetNumberOfSatellitesGood(const MXM_5X_INSTANCE_s *const kpkInstance)
Get the value of MXM_5X_INSTANCE_s::numberOfSatellitesIsGood.
MXM_DC_BYTE_e MXM_5XGetLastDCByte(const MXM_5X_INSTANCE_s *const kpkInstance)
Returns the last received DC byte.
#define COMMAND_BUFFER_LENGTH
uint8_t MXM_5XGetNumberOfSatellites(const MXM_5X_INSTANCE_s *const kpkInstance)
Get number of satellites.
Header for the configuration for the Maxim monitoring chip.
Headers for the CRC8 calculation for Maxim Integrated Monitoring devices.
Register map of the MAX1785x monitoring IC.
MXM_REG_NAME_e
MAX1785x register names.
Struct for the state-variable of state-machine.
Definition: mxm_17841b.h:158
5x statemachine structure
uint8_t lastDCByte
Tracks the last received DC byte.
MXM_41B_STATE_REQUEST_STATUS_e status41b
STD_RETURN_TYPE_e numberOfSatellitesIsGood
Number of monitoring ICs matches the expected number.
uint8_t commandBufferCurrentLength
Length of Command Buffer.
MXM_STATEMACHINE_5X_e state
MXM_5X_COMMAND_PAYLOAD_s commandPayload
uint8_t numberOfSatellites
Number of satellites.
MXM_5X_SUBSTATES_e substate
MXM_5X_STATE_REQUEST_STATUS_e * processed
uint16_t rxBuffer[100]
uint16_t commandBuffer[10]