foxBMS  1.1.0
The foxBMS Battery Management System API Documentation
mxm_battery_management.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2021, 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 2021-06-16 (date of last update)
47  * @ingroup DRIVERS
48  * @prefix MXM
49  *
50  * @brief Headers for the driver for the MAX17841B ASCI and
51  * MAX1785x monitoring chip
52  *
53  * @details def
54  *
55  */
56 
57 #ifndef FOXBMS__MXM_BATTERY_MANAGEMENT_H_
58 #define FOXBMS__MXM_BATTERY_MANAGEMENT_H_
59 
60 /*========== Includes =======================================================*/
61 #include "mxm_cfg.h"
62 
63 #include "mxm_17841b.h"
64 #include "mxm_basic_defines.h"
65 #include "mxm_crc8.h"
66 #include "mxm_register_map.h"
67 
68 /*========== Macros and Definitions =========================================*/
69 
70 /** length of the command buffer */
71 #define COMMAND_BUFFER_LENGTH (6u)
72 
73 /** length of the rx buffer */
74 #define MXM_5X_RX_BUFFER_LEN 100u
75 
76 /** seed for helloall, should be 0x00u except for special edge cases */
77 #define HELLOALL_START_SEED 0x00u
78 /** seed for data check, should be 0x00u */
79 #define DATA_CHECK_BYTE_SEED 0x00u
80 /** seed for the alive counter, should be 0x00u except for special edge cases */
81 #define ALIVE_COUNTER_SEED 0x00u
82 
83 /**
84  * @brief Type for Battery Management Protocol commands.
85  * @details This type describes the hex-numbers of all Maxim Battery
86  * Management Protocol commands. For details see the
87  * datasheet of MAX1785x devices.
88  */
90 
91 /**
92  * @brief HELLOALL message
93  */
94 #define BATTERY_MANAGEMENT_HELLOALL ((BATTERY_MANAGEMENT_COMMAND_t)0x57u)
95 
96 /**
97  * @brief ALERTPACKET message
98  */
99 #define BATTERY_MANAGEMENT_ALERTPACKET ((BATTERY_MANAGEMENT_COMMAND_t)0x21u)
100 
101 /**
102  * @brief WRITEDEVICE message (write single register of a single device)
103  */
104 #define BATTERY_MANAGEMENT_WRITEDEVICE ((BATTERY_MANAGEMENT_COMMAND_t)0x04u)
105 
106 /**
107  * @brief WRITEALL message (write single register of all daisy-chain devices)
108  */
109 #define BATTERY_MANAGEMENT_WRITEALL ((BATTERY_MANAGEMENT_COMMAND_t)0x02u)
110 
111 /**
112  * @brief READDEVICE message (read single register of a single device)
113  */
114 #define BATTERY_MANAGEMENT_READDEVICE ((BATTERY_MANAGEMENT_COMMAND_t)0x05u)
115 
116 /**
117  * @brief READALL message (read single register of all daisy-chain devices)
118  */
119 #define BATTERY_MANAGEMENT_READALL ((BATTERY_MANAGEMENT_COMMAND_t)0x03u)
120 
121 /**
122  * @brief READBLOCK message (read block of registers of a single device)
123  */
124 #define BATTERY_MANAGEMENT_READBLOCK ((BATTERY_MANAGEMENT_COMMAND_t)0x06u)
125 
126 /**
127  * @brief DOWNHOST message (make the downhost writing)
128  * @details This feature is only useable on downhost line.
129  */
130 #define BATTERY_MANAGEMENT_DOWNHOST ((BATTERY_MANAGEMENT_COMMAND_t)0x09u)
131 
132 /**
133  * @brief UPHOST message (make the uphost writing, only useable on uphost line)
134  */
135 #define BATTERY_MANAGEMENT_UPHOST ((BATTERY_MANAGEMENT_COMMAND_t)0x08u)
136 
137 /**
138  * @brief Battery Management Protocol lengths of TX buffer
139  * @details Reference values for the lengths of the respective TX buffers
140  * for Battery Management Protocol messages.
141  */
142 
143 /**
144  * @brief length of a READALL command without stuffing bytes
145  */
146 #define BATTERY_MANAGEMENT_TX_LENGTH_READALL ((uint8_t)4u)
147 
148 /**
149  * @brief States of the Battery Management Protocol state-machine
150  */
151 typedef enum {
152  MXM_STATEMACH_5X_UNINITIALIZED, /*!< Uninitialized state that the state-machine starts in */
153  MXM_STATEMACH_5X_INIT, /*!< Initialization state */
154  MXM_STATEMACH_5X_41B_FMEA_CHECK, /*!< Requests a FMEA-check from the 41B-state-machine */
155  MXM_STATEMACH_5X_IDLE, /*!< Idle state, transitions are possible in this state */
156  MXM_STATEMACH_5X_WRITEALL, /*!< WRITEALL state, sends a WRITEALL to the daisy-chain */
157  MXM_STATEMACH_5X_WRITE_DEVICE, /*!< WRITEDEVICE state, sends a WRITEDEVICE to a specific address */
158  MXM_STATEMACH_5X_READALL, /*!< READALL state, sends a READALL to the daisy-chain */
159  MXM_STATEMACH_5X_MAXSTATE, /*!< Highest state */
161 
162 /**
163  * @brief Sub-states of the Battery Management Protocol state-machine
164  */
165 typedef enum {
166  /** default value indicating no selected substate */
168  /** substate for the initialization of the MAX17841 bridge IC */
170  /** substate for the initialization, enable the keep alive feature in the
171  * bridge IC */
173  /** substate for the initialization, enable RX interrupt flags */
175  /** substate for the wake-up routine, clear the receive buffer in the
176  * bridge IC */
178  /** substate for the wake-up routine, enable the sending of preambles in
179  * order to wake up the daisy-chain devices */
181  /** substate for the wake-up routine, wait for the daisy-chain devices to
182  * return an answer, resulting in status RX busy of the bridge IC */
184  /** substate for the wake-up routine, disable the sending of preambles */
186  /** substate for the wake-up routine, wait for the RX transmission to
187  * finish */
189  /** substate for the wake-up routine, clear the transmit buffer */
191  /** substate for the wake-up routine, clear the receive buffer */
193  /** substate for the wake-up routine, sending helloall to the daisy-chain */
195  /** substate for the wake-up routine, verifying the result of helloall */
197  /** substate for requesting an FMEA check on the bridge IC */
199  /** substate for the verification of the FMEA check done in
200  * #MXM_5X_41B_FMEA_REQUEST */
202  /** substate for the initiation of a uart transaction for the WRITEALL
203  * command */
205  /** substate for the verifying the buffer of a WRITEALL transaction */
207  /** substate for the initiation of a uart transaction for the WRITEALL
208  * command */
210  /** substate for checking the received CRC in a WRITEDEVICE transaction */
212  /** substate for the initiation of a uart transaction for the READALL
213  * command */
215  /** substate for checking the received CRC in a READALL transaction */
217  /** substate for retrieving the data check byte from a READALL transaction */
220 
221 /**
222  * @brief Request status of Battery Management Protocol states.
223  * @details This enum describes the states that a state in the
224  * #MXM_5XStateMachine() can have.
225  *
226  * Alternating bit patterns are used for better distinction
227  * and to make sure that there is no accidental overlap.
228  */
229 typedef enum {
230  MXM_5X_STATE_UNSENT = 0x56, /*!< The request has not been sent to the state-machine yet. */
232  0x67, /*!< The request has been received by the state-machine, but not been processed yet. */
233  MXM_5X_STATE_PROCESSED = 0x9A, /*!< The request has been process successfully */
234  MXM_5X_STATE_ERROR = 0xAB, /*!< An error has occurred during processing of the request. */
236 
237 /**
238  * @brief Payload command
239  */
240 typedef struct {
241  MXM_REG_NAME_e regAddress; /*!< register address that shall be written */
242  uint8_t lsb; /*!< least significant bit */
243  uint8_t msb; /*!< most significant bit */
244  uint8_t blocksize; /*!< blocksize for the READBLOCK command */
245  uint8_t deviceAddress; /*!< device address for commands that address specific devices */
247 
248 /**
249  * @brief 5x statemachine structure
250  **/
251 typedef struct MXM_5X_INSTANCE {
252  MXM_STATEMACHINE_5X_e state; /*!< state of Driver State Machine */
253  MXM_5X_SUBSTATES_e substate; /*!< substate of current Driver State */
254  MXM_5X_COMMAND_PAYLOAD_s commandPayload; /*!< command payload of the Battery Management Protocol */
255  MXM_5X_STATE_REQUEST_STATUS_e *processed; /*!< status-indicator of the underlying state-machine */
256  MXM_41B_STATE_REQUEST_STATUS_e status41b; /*!< for tracking of 41B state-machine */
257  /**
258  * @brief Number of satellites
259  * @details This variable tracks the number of monitoring ICs that have been
260  * found during the enumeration of all connected monitoring ICs.
261  * Therefore this variable is initialized with 0. This value will be
262  * compared with the expected number of monitoring ICs which is set in
263  * #BS_NR_OF_MODULES.
264  */
266  /**
267  * @brief Command Buffer
268  * @details This variable contains a buffer for Battery Management Protocol
269  * commands. The content is constructed by calling functions like
270  * #MXM_5XConstructCommandBufferHelloall() and similar.
271  *
272  * Afterwards this buffer can be passed on to the lower state-machine
273  * as payload. The length of this buffer is described in
274  * #MXM_5X_INSTANCE::commandBufferCurrentLength.
275  */
276  /**
277  * @brief Number of monitoring ICs matches the expected number.
278  * @details This status variable indicates whether the number of found
279  * monitoring ICs in #MXM_5X_INSTANCE::numberOfSatellites
280  * matches with the configured number of monitoring ICs in
281  * #BS_NR_OF_MODULES. This variable is updated during execution of
282  * the substate
283  * #MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_HELLOALL_VERIFY_MSG_AND_COUNT
284  * in the state #MXM_STATEMACH_5X_INIT in #MXM_5XStateMachine().
285  *
286  * In case the numbers are the same, the variable will read #STD_OK,
287  * otherwise it will be set to #STD_NOT_OK.
288  */
290  /**
291  * @brief Tracks the last received DC byte.
292  */
293  uint8_t lastDCByte;
294  /**
295  * @brief Length of Command Buffer
296  * @details Length of the array #MXM_5X_INSTANCE::commandBuffer.
297  */
299  uint16_t commandBuffer[COMMAND_BUFFER_LENGTH]; /*!< buffer for BMS commands */
300  uint16_t rxBuffer[MXM_5X_RX_BUFFER_LEN]; /*!< array containing the buffer for received data */
302 
303 /*========== Extern Constant and Variable Declarations ======================*/
304 
305 /*========== Extern Function Prototypes =====================================*/
306 
307 /**
308  * @brief Execute state-machine for Battery Management Protocol.
309  * @details This function executes the state-machine that exposes an interface
310  * for the Maxim Battery Management Protocol for monitoring ICs
311  * of the MAX1785x family.
312  */
313 extern void MXM_5XStateMachine(MXM_41B_INSTANCE_s *pInstance41b, MXM_5X_INSTANCE_s *pInstance5x);
314 
315 /**
316  * @brief Returns the last received DC byte.
317  * @param[in] kpkInstance pointer to the instance struct
318  */
319 extern MXM_DC_BYTE_e MXM_5XGetLastDCByte(const MXM_5X_INSTANCE_s *const kpkInstance);
320 
321 /**
322  * @brief Get the value of #MXM_5X_INSTANCE::numberOfSatellitesIsGood
323  * @param[in] kpkInstance pointer to the instance struct
324  *
325  * @return #MXM_5X_INSTANCE::numberOfSatellitesIsGood
326  */
328 
329 /**
330  * @brief Copy RX buffer into variable.
331  * @details This function copies the RX buffer which is locally available in
332  * the #MXM_5XStateMachine() into a supplied array pointer.
333  * It will make sure that both the length of the local as also the
334  * supplied length of the RX buffer are not violated.
335  * In case of the supplied RX buffer being longer than the locally
336  * available one, the remaining entries of the buffer will be
337  * filled with 0.
338  * @param[in,out] kpkInstance pointer to the state-struct
339  * @param[in] rxBuffer array-pointer to a RX buffer that shall be filled
340  * @param[in] rxBufferLength length of the supplied array
341  * @return #STD_NOT_OK for rxBuffer being a #NULL_PTR or rxBufferLength
342  * having length 0
343  */
345  const MXM_5X_INSTANCE_s *const kpkInstance,
346  uint8_t *rxBuffer,
347  uint16_t rxBufferLength);
348 
349 /**
350  * @brief Get number of satellites
351  * @details Getter-function for the number of satellites
352  * (variable #MXM_5X_INSTANCE::numberOfSatellites).
353  * @param[in] kpkInstance pointer to the state struct
354  * @return value of #MXM_5X_INSTANCE::numberOfSatellites
355  */
356 extern uint8_t MXM_5XGetNumberOfSatellites(const MXM_5X_INSTANCE_s *const kpkInstance);
357 
358 /**
359  * @brief Set state request for the Battery Management Statemachine
360  * @details This function sets the state requests for the #MXM_5XStateMachine().
361  * @param[in,out] pInstance5x pointer to the 5x state
362  * @param[in] state State that is requested
363  * @param[in] commandPayload additional payload that is handled by the state
364  * @param[in,out] processed pointer to the status of the request
365  * @return #STD_OK if the request has been successfully placed,
366  * #STD_NOT_OK if not
367  */
369  MXM_5X_INSTANCE_s *pInstance5x,
370  MXM_STATEMACHINE_5X_e state,
371  MXM_5X_COMMAND_PAYLOAD_s commandPayload,
372  MXM_5X_STATE_REQUEST_STATUS_e *processed);
373 
374 /**
375  * @brief runs a selfcheck for the address space check
376  * @details Runs a selfcheck for the function which is checking if a register
377  * address is inside the user accessible address space of the
378  * monitoring IC.
379  * @return #STD_OK if the selfcheck has been successful
380  */
382 
383 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
384 
385 #endif /* FOXBMS__MXM_BATTERY_MANAGEMENT_H_ */
enum STD_RETURN_TYPE STD_RETURN_TYPE_e
#define must_check_return
Allows functions to generate warnings in GCC for unused returns.
Definition: general.h:95
Headers for the driver for the MAX17841B ASCI and MAX1785x monitoring chip.
enum MXM_41B_STATE_REQUEST_STATUS MXM_41B_STATE_REQUEST_STATUS_e
Request status of MAX17841B states.
Basic defines for the complete Maxim driver.
enum MXM_DC_BYTE 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
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
struct MXM_5X_INSTANCE MXM_5X_INSTANCE_s
5x statemachine structure
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_WRITE_DEVICE_CHECK_CRC
@ MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_CLEAR_RECEIVE_BUFFER
@ MXM_5X_WRITEALL_UART_TRANSACTION
@ MXM_5X_WRITEALL_UART_VERIFY_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_READALL_GET_DC
@ MXM_5X_41B_FMEA_REQUEST
@ MXM_5X_INIT_ENABLE_RX_INTERRUPT_FLAGS
@ MXM_5X_WRITE_DEVICE_UART_TRANSACTION
@ 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_WAKE_UP_SATELLITE_DEVICES_CLEAR_TRANSMIT_BUFFER
@ MXM_5X_INIT_ENABLE_KEEP_ALIVE
@ MXM_5X_41B_FMEA_CHECK
@ MXM_5X_INIT_WAKE_UP_SATELLITE_DEVICES_DIS_PREAMBLES
uint8_t 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::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.
enum MXM_REG_NAME MXM_REG_NAME_e
MAX1785x register names.
Struct for the state-variable of state-machine.
Definition: mxm_17841b.h:149
5x statemachine structure
uint8_t commandBufferCurrentLength
Length of Command Buffer.
MXM_5X_COMMAND_PAYLOAD_s commandPayload
MXM_5X_SUBSTATES_e substate
MXM_41B_STATE_REQUEST_STATUS_e status41b
MXM_STATEMACHINE_5X_e state
STD_RETURN_TYPE_e numberOfSatellitesIsGood
Command Buffer.
uint8_t lastDCByte
Tracks the last received DC byte.
uint16_t commandBuffer[COMMAND_BUFFER_LENGTH]
uint8_t numberOfSatellites
Number of satellites.
uint16_t rxBuffer[MXM_5X_RX_BUFFER_LEN]
MXM_5X_STATE_REQUEST_STATUS_e * processed