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