foxBMS  1.2.1
The foxBMS Battery Management System API Documentation
mxm_17841b.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_17841b.h
44  * @author foxBMS Team
45  * @date 2018-12-14 (date of creation)
46  * @updated 2021-12-06 (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_17841B_H_
58 #define FOXBMS__MXM_17841B_H_
59 
60 /*========== Includes =======================================================*/
61 #include "mxm_cfg.h"
62 
63 #include "mxm_bitextract.h"
64 
65 /*========== Macros and Definitions =========================================*/
66 
67 /**
68  * @brief SPI TX buffer length
69  *
70  * This define defines the length of the SPI TX buffer.
71  * This TX buffer is declared in #MXM_41B_INSTANCE_s::spiTXBuffer.
72  * The buffer has to be large enough to accommodate every
73  * relevant SPI transaction.
74  */
75 #define MXM_SPI_TX_BUFFER_LENGTH (10u)
76 
77 /** SPI RX buffer length */
78 #define MXM_SPI_RX_BUFFER_LENGTH (100u)
79 
80 /**
81  * @brief States of the MAX17841B state-machine
82  */
83 typedef enum {
84  MXM_STATEMACH_41B_UNINITIALIZED, /*!< Uninitialized state that the state-machine starts in */
85  MXM_STATEMACH_41B_INIT, /*!< Initialization sequence, afterwards transition into idle state */
86  MXM_STATEMACH_41B_IDLE, /*!< Idle state, transition into other states is available here */
87  MXM_STATEMACH_41B_CHECK_FMEA, /*!< Checks the FMEA register of MAX17841B. */
88  MXM_STATEMACH_41B_GET_VERSION, /*!< Retrieves the version of the connected ASCI. */
89  MXM_STATEMACH_41B_WRITE_CONF_AND_INT_REGISTER, /*!< Writes the copy of configuration and interrupt register to the MAX17841B. */
90  MXM_STATEMACH_41B_READ_STATUS_REGISTER, /*!< Reads the status registers of MAX17841B. */
91  MXM_STATEMACH_41B_UART_TRANSACTION, /*!< Sends a complete UART transaction. */
92  MXM_STATEMACH_41B_CLEAR_RECEIVE_BUFFER, /*!< Clears the receive buffer. */
93  MXM_STATEMACH_41B_CLEAR_TRANSMIT_BUFFER, /*!< Clears the transmit buffer */
94  MXM_STATEMACH_41B_MAXSTATE, /*!< Highest state */
96 
97 /**
98  * @brief Substates of the MAX17841B state-machine
99  */
100 typedef enum {
111  /* MXM_41B_UART_CLEAR_TRANSMIT_BUFFER, */
123 
124 /**
125  * @brief Request status of MAX17841B states.
126  *
127  * This enum describes the states that a state in the
128  * #MXM_41BStateMachine() can have.
129  */
130 typedef enum {
131  MXM_41B_STATE_UNSENT, /*!< The request has not been sent to the state-machine yet. */
132  MXM_41B_STATE_UNPROCESSED, /*!< The request has been received by the state-machine, but not been processed yet. */
133  MXM_41B_STATE_PROCESSED, /*!< The request has been process successfully */
134  MXM_41B_STATE_ERROR, /*!< An error has occurred during processing of the request. */
136 
137 /**
138  * @brief Register functions
139  */
140 typedef enum {
141  MXM_41B_REG_FUNCTION_RX_BUSY_STATUS, /*!< read the rx busy bit from rx status register */
142  MXM_41B_REG_FUNCTION_RX_OVERFLOW_STATUS, /*!< read the rx overflow bit from rx status register */
143  MXM_41B_REG_FUNCTION_RX_STOP_STATUS, /*!< read the rx stop bit from rx status register */
144  MXM_41B_REG_FUNCTION_RX_EMPTY_STATUS, /*!< read the rx empty bit from rx status register */
145  MXM_41B_REG_FUNCTION_TX_PREAMBLES, /*!< set the tx preambles bit */
146  MXM_41B_REG_FUNCTION_KEEP_ALIVE, /*!< set the keep alive bits */
147  MXM_41B_REG_FUNCTION_RX_ERROR_INT, /*!< read the rx error bit */
150 
151 /**
152  * @brief Struct for the state-variable of state-machine
153  *
154  * This struct defines the state-variable of
155  * the #MXM_41BStateMachine().
156  */
157 typedef struct {
158  MXM_STATEMACH_41B_e state; /*!< state of Driver State Machine */
159  MXM_41B_SUBSTATES_e substate; /*!< substate of current Driver State */
160  uint16_t *pPayload; /*!< payload that is processed by the state-machine */
161  uint8_t payloadLength; /*!< length of the payload array */
162  uint16_t *pRxBuffer; /*!< pointer to an RX-buffer that will be filled by the state-machine */
163  uint16_t rxBufferLength; /*!< length of the RX-buffer-array */
164  MXM_41B_STATE_REQUEST_STATUS_e *processed; /*!< status-indicator of the state-machine */
165  uint8_t extendMessageBytes; /*!< pass on number of bytes by which the TX-message shall be extended */
166  uint8_t waitCounter; /*!< general error counter, will be reset in funtions */
167  uint8_t regRXIntEnable; /*!< local storage for the RX Interrupt Enable register */
168  uint8_t regTXIntEnable; /*!< local storage for the TX Interrupt Enable register */
169  uint8_t regRXStatus; /*!< local storage for the RX Status register */
170  uint8_t regTXStatus; /*!< local storage for the TX status register */
171  uint8_t regConfig1; /*!< local storage for the Config 1 register */
172  uint8_t regConfig2; /*!< local storage for the Config 2 register */
173  uint8_t regConfig3; /*!< local storage for the Config 3 register */
174  uint8_t regRxSpace; /*!< RX space register (shows the left space in RX buffer) */
175  uint16_t hwModel; /*!< model number of the connected IC */
176  uint8_t hwMaskRevision; /*!< mask revision of the connected IC */
177  uint32_t shutdownTimeStamp; /*!< timestamp of the last shutdown (or startup) action */
178  uint16_t spiRXBuffer[MXM_SPI_RX_BUFFER_LENGTH]; /*!< rx buffer for SPI */
179  uint16_t spiTXBuffer[MXM_SPI_TX_BUFFER_LENGTH]; /*!< tx buffer for SPI */
181 
182 /*========== Extern Constant and Variable Declarations ======================*/
183 
184 /*========== Extern Function Prototypes =====================================*/
185 /**
186  * @brief Write a register function
187  *
188  * Functions of the ASCI are mapped onto parts of the register.
189  * This function is used to write the proper values into the register copy
190  * of the ASCI that is inside the driver.
191  * In order to use the function, provide the name of the ASCI function that you
192  * want to write (#MXM_41B_REG_FUNCTION_e) and the value that
193  * should be written (#MXM_41B_REG_BIT_VALUE).
194  * Currently, only a relevant subset of the ASCI features is implemented.
195  *
196  * After updating the register copy, it has to be written to the ASCI memory.
197  * For the configuration registers this is done with the function
198  * MXM_41BConfigRegisterWrite(). This function is for example called
199  * in state #MXM_STATEMACH_41B_WRITE_CONF_AND_INT_REGISTER.
200  *
201  * @param[in,out] pInstance pointer to the state of the
202  * MAX17841B-state-machine
203  * @param[in] registerFunction name of the function that shall be
204  * written
205  * @param[in] value value of the bits that shall be written
206  * @return #STD_NOT_OK for unknown or unimplemented register
207  * functions, otherwise #STD_OK
208  */
210  MXM_41B_INSTANCE_s *pInstance,
211  MXM_41B_REG_FUNCTION_e registerFunction,
212  MXM_41B_REG_BIT_VALUE value);
213 
214 /**
215  * @brief Read the value of a register function
216  *
217  * Corresponding read-function to MXM_41BWriteRegisterFunction().
218  * This function reads a value from the register-copy of MAX17841B and writes
219  * it into a supplied pointer.
220  * The register function is specified by the
221  * corresponding #MXM_41B_REG_FUNCTION_e value.
222  *
223  * This function implements only the needed subset of register functions.
224  *
225  * @param[in,out] kpkInstance pointer to the state of the
226  * MAX17841B-state-machine
227  * @param[in] registerFunction name of the function that shall be
228  * written
229  * @param[out] pValue pointer to a variable in which the bits
230  * shall be written
231  * @return #STD_NOT_OK for unknown or unimplemented register function,
232  * otherwise #STD_OK
233  */
235  const MXM_41B_INSTANCE_s *const kpkInstance,
236  MXM_41B_REG_FUNCTION_e registerFunction,
237  MXM_41B_REG_BIT_VALUE *pValue);
238 
239 /**
240  * @brief Execute state-machine for the MAX17841B.
241  *
242  * This function executes the state-machine that communicates
243  * with the MAX17841B over SPI.
244  */
245 extern void MXM_41BStateMachine(MXM_41B_INSTANCE_s *pInstance);
246 
247 /**
248  * @brief Set state transition for MAX17841B-state-machine.
249  *
250  * This function is used to transition into another state of the
251  * state-machine which is handled in MXM_41BStateMachine().
252  * The user sets a state that should be transitioned into.
253  * For most states a payload and a payload-length can be supplied.
254  * The payload-length has to be consistent with the length in payload.
255  * Typically, this supplied payload describes the byte-sequence that
256  * should be written into the load-queue.
257  *
258  * For the case of a e.g. READALL-command the message-length has to
259  * be stretched by the number of connected monitoring ICs times two.
260  * This is achieved by passing on extendMessageBytes.
261  *
262  * In case that the state generates data that has to be handled in the
263  * higher layers, the pointer pRxBuffer will be used. Please make sure that
264  * the length of pRxBuffer is also consistent.
265  *
266  * In order to determine success or failure of the requested state,
267  * the higher layer supplies a pointer into which the current status
268  * of the requested state will be written.
269  *
270  * @param[in,out] pInstance pointer to the state of the
271  * MAX17841B-state-machine
272  * @param[in] state state into which the state-machine
273  * shall transition
274  * @param[in] pPayload pointer to an array with data that will
275  * be processed in the requested state
276  * @param[in] payloadLength length of the payload-array
277  * @param[in] extendMessageBytes number of bytes that shall be appended
278  * by the ASCI
279  * @param[out] pRxBuffer pointer to an array that will be filled
280  * by the requested state with data that
281  * has to be processed in higher layers
282  * @param[in] rxBufferLength length of the RX buffer array
283  * @param[out] processed pointer of the status of the requested
284  * state
285  * @return #STD_NOT_OK for inconsistent input or forbidden state
286  * transitions, otherwise #STD_OK
287  */
289  MXM_41B_INSTANCE_s *pInstance,
290  MXM_STATEMACH_41B_e state,
291  uint16_t *pPayload,
292  uint8_t payloadLength,
293  uint8_t extendMessageBytes,
294  uint16_t *pRxBuffer,
295  uint16_t rxBufferLength,
296  MXM_41B_STATE_REQUEST_STATUS_e *processed);
297 
298 /**
299  * @brief Initializes the state struct with default values
300  * @details This function is called through the startup of the driver in order
301  * to ensure proper default values.
302  * @param[out] pInstance instance of the state struct that shall be initialized
303  */
304 extern void MXM_41BInitializeStateStruct(MXM_41B_INSTANCE_s *pInstance);
305 
306 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
307 
308 #endif /* FOXBMS__MXM_17841B_H_ */
enum STD_RETURN_TYPE STD_RETURN_TYPE_e
STD_RETURN_TYPE_e MXM_41BSetStateRequest(MXM_41B_INSTANCE_s *pInstance, MXM_STATEMACH_41B_e state, uint16_t *pPayload, uint8_t payloadLength, uint8_t extendMessageBytes, uint16_t *pRxBuffer, uint16_t rxBufferLength, MXM_41B_STATE_REQUEST_STATUS_e *processed)
Set state transition for MAX17841B-state-machine.
Definition: mxm_17841b.c:775
void MXM_41BStateMachine(MXM_41B_INSTANCE_s *pInstance)
Execute state-machine for the MAX17841B.
Definition: mxm_17841b.c:910
#define MXM_SPI_TX_BUFFER_LENGTH
SPI TX buffer length.
Definition: mxm_17841b.h:75
STD_RETURN_TYPE_e MXM_41BWriteRegisterFunction(MXM_41B_INSTANCE_s *pInstance, MXM_41B_REG_FUNCTION_e registerFunction, MXM_41B_REG_BIT_VALUE value)
Write a register function.
Definition: mxm_17841b.c:831
MXM_STATEMACH_41B_e
States of the MAX17841B state-machine.
Definition: mxm_17841b.h:83
@ MXM_STATEMACH_41B_MAXSTATE
Definition: mxm_17841b.h:94
@ MXM_STATEMACH_41B_GET_VERSION
Definition: mxm_17841b.h:88
@ MXM_STATEMACH_41B_CLEAR_RECEIVE_BUFFER
Definition: mxm_17841b.h:92
@ MXM_STATEMACH_41B_CLEAR_TRANSMIT_BUFFER
Definition: mxm_17841b.h:93
@ MXM_STATEMACH_41B_UNINITIALIZED
Definition: mxm_17841b.h:84
@ MXM_STATEMACH_41B_INIT
Definition: mxm_17841b.h:85
@ MXM_STATEMACH_41B_WRITE_CONF_AND_INT_REGISTER
Definition: mxm_17841b.h:89
@ MXM_STATEMACH_41B_CHECK_FMEA
Definition: mxm_17841b.h:87
@ MXM_STATEMACH_41B_READ_STATUS_REGISTER
Definition: mxm_17841b.h:90
@ MXM_STATEMACH_41B_IDLE
Definition: mxm_17841b.h:86
@ MXM_STATEMACH_41B_UART_TRANSACTION
Definition: mxm_17841b.h:91
MXM_41B_SUBSTATES_e
Substates of the MAX17841B state-machine.
Definition: mxm_17841b.h:100
@ MXM_41B_FMEA_REQUEST_REGISTER
Definition: mxm_17841b.h:107
@ MXM_41B_INIT_RESET_BRIDGE_IC
Definition: mxm_17841b.h:102
@ MXM_41B_UART_WAIT_FOR_RX_STATUS_CHANGE_WRITE
Definition: mxm_17841b.h:117
@ MXM_41B_VERSION_VERIFY
Definition: mxm_17841b.h:110
@ MXM_41B_UART_READ_RX_SPACE
Definition: mxm_17841b.h:112
@ MXM_41B_INIT_CHECK_INITIALIZATION
Definition: mxm_17841b.h:106
@ MXM_41B_FMEA_VERIFY
Definition: mxm_17841b.h:108
@ MXM_41B_UART_READ_BACK_RECEIVE_BUFFER_SAVE
Definition: mxm_17841b.h:119
@ MXM_41B_VERSION_REQUEST_REGISTER
Definition: mxm_17841b.h:109
@ MXM_41B_ENTRY_SUBSTATE
Definition: mxm_17841b.h:101
@ MXM_41B_UART_WRITE_LOAD_QUEUE
Definition: mxm_17841b.h:114
@ MXM_41B_UART_READ_LOAD_QUEUE
Definition: mxm_17841b.h:115
@ MXM_41B_INIT_START_BRIDGE_IC
Definition: mxm_17841b.h:103
@ MXM_41B_UART_READ_RX_SPACE_PARSE
Definition: mxm_17841b.h:113
@ MXM_41B_INIT_READ_CONFIG_REGISTERS
Definition: mxm_17841b.h:105
@ MXM_41B_UART_VERIFY_LOAD_QUEUE_AND_TRANSMIT
Definition: mxm_17841b.h:116
@ MXM_41B_READ_STATUS_REGISTER_SEND
Definition: mxm_17841b.h:120
@ MXM_41B_READ_STATUS_REGISTER_PROCESS
Definition: mxm_17841b.h:121
@ MXM_41B_INIT_WRITE_DEFAULT_VALUES
Definition: mxm_17841b.h:104
@ MXM_41B_UART_WAIT_FOR_RX_STATUS_CHANGE_READ_AND_READ_BACK_RCV_BUF
Definition: mxm_17841b.h:118
#define MXM_SPI_RX_BUFFER_LENGTH
Definition: mxm_17841b.h:78
void MXM_41BInitializeStateStruct(MXM_41B_INSTANCE_s *pInstance)
Initializes the state struct with default values.
Definition: mxm_17841b.c:956
STD_RETURN_TYPE_e MXM_41BReadRegisterFunction(const MXM_41B_INSTANCE_s *const kpkInstance, MXM_41B_REG_FUNCTION_e registerFunction, MXM_41B_REG_BIT_VALUE *pValue)
Read the value of a register function.
Definition: mxm_17841b.c:875
MXM_41B_REG_FUNCTION_e
Register functions.
Definition: mxm_17841b.h:140
@ MXM_41B_REG_FUNCTION_RX_BUSY_STATUS
Definition: mxm_17841b.h:141
@ MXM_41B_REG_FUNCTION_RX_EMPTY_STATUS
Definition: mxm_17841b.h:144
@ MXM_41B_REG_FUNCTION_RX_STOP_STATUS
Definition: mxm_17841b.h:143
@ MXM_41B_REG_FUNCTION_RX_OVERFLOW_STATUS
Definition: mxm_17841b.h:142
@ MXM_41B_REG_FUNCTION_TX_PREAMBLES
Definition: mxm_17841b.h:145
@ MXM_41B_REG_FUNCTION_RX_ERROR_INT
Definition: mxm_17841b.h:147
@ MXM_41B_REG_FUNCTION_KEEP_ALIVE
Definition: mxm_17841b.h:146
@ MXM_41B_REG_FUNCTION_RX_OVERFLOW_INT
Definition: mxm_17841b.h:148
MXM_41B_STATE_REQUEST_STATUS_e
Request status of MAX17841B states.
Definition: mxm_17841b.h:130
@ MXM_41B_STATE_UNSENT
Definition: mxm_17841b.h:131
@ MXM_41B_STATE_ERROR
Definition: mxm_17841b.h:134
@ MXM_41B_STATE_UNPROCESSED
Definition: mxm_17841b.h:132
@ MXM_41B_STATE_PROCESSED
Definition: mxm_17841b.h:133
Bit extraction function for MXM_17841b.
uint8_t MXM_41B_REG_BIT_VALUE
Bit-values for registers.
Header for the configuration for the Maxim monitoring chip.
Struct for the state-variable of state-machine.
Definition: mxm_17841b.h:157
uint8_t regRXIntEnable
Definition: mxm_17841b.h:167
uint16_t * pRxBuffer
Definition: mxm_17841b.h:162
uint16_t * pPayload
Definition: mxm_17841b.h:160
uint8_t regTXIntEnable
Definition: mxm_17841b.h:168
uint8_t hwMaskRevision
Definition: mxm_17841b.h:176
uint16_t rxBufferLength
Definition: mxm_17841b.h:163
MXM_41B_STATE_REQUEST_STATUS_e * processed
Definition: mxm_17841b.h:164
uint32_t shutdownTimeStamp
Definition: mxm_17841b.h:177
MXM_41B_SUBSTATES_e substate
Definition: mxm_17841b.h:159
MXM_STATEMACH_41B_e state
Definition: mxm_17841b.h:158
uint8_t extendMessageBytes
Definition: mxm_17841b.h:165
uint8_t payloadLength
Definition: mxm_17841b.h:161