foxBMS  1.1.0
The foxBMS Battery Management System API Documentation
mxm_1785x_tools.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_1785x_tools.h
44  * @author foxBMS Team
45  * @date 2020-07-15 (date of creation)
46  * @updated 2021-07-14 (date of last update)
47  * @ingroup DRIVERS
48  * @prefix MXM
49  *
50  * @brief This is a collection of helper functions for the MAX1785x ICs
51  *
52  * @details This collection of helper functions for the MAX1785x ICs helps to
53  * calculate the lsb and msb for register values and similar tasks.
54  *
55  */
56 
57 #ifndef FOXBMS__MXM_1785X_TOOLS_H_
58 #define FOXBMS__MXM_1785X_TOOLS_H_
59 
60 /*========== Includes =======================================================*/
61 #include "mxm_cfg.h"
62 
63 #include "mxm_basic_defines.h"
64 #include "mxm_battery_management.h"
65 #include "mxm_register_map.h"
66 
67 /*========== Macros and Definitions =========================================*/
68 /**
69  * @brief States of the global Maxim state-machine
70  *
71  * State transitions are currently autonomous and will have to be integrated into
72  * the Battery System state-machine.
73  */
75  MXM_STATEMACHINE_STATES_UNINITIALIZED, /*!< uninitialized state */
76  MXM_STATEMACHINE_STATES_SELFCHECK_PRE_INIT, /*!< self-check that has to be executed before initialization */
77  MXM_STATEMACHINE_STATES_INIT, /*!< initialization sequence */
78  MXM_STATEMACHINE_STATES_SELFCHECK_POST_INIT, /*!< self-check that has to be executed after initialization */
79  MXM_STATEMACHINE_STATES_IDLE, /*!< idle state, the driver waits for operation here */
80  MXM_STATEMACHINE_STATES_OPERATION, /*!< operating state, the measurement cycle is executed here */
81  MXM_STATEMACHINE_STATES_MAXSTATE, /*!< highest state */
83 
84 /** states of the #MXM_StateMachineOperation() statemachine */
149 
150 /** intermediate state-definition for #MXM_MonGetVoltages() */
151 typedef enum MXM_MONITORING_STATE {
152  MXM_MONITORING_STATE_PENDING, /*!< state completion is pending */
153  MXM_MONITORING_STATE_PASS, /*!< state passed successfully */
154  MXM_MONITORING_STATE_FAIL, /*!< unrecoverable failure that has to be handled by e.g., reset (function has already tried recovery) */
156 
157 /**
158  * struct describing the different return values of selfchecks that the driver can execute
159  */
160 typedef struct MXM_SELFCHECK {
161  STD_RETURN_TYPE_e crc; /*!< CRC self-check; stores the return value of #MXM_CRC8SelfTest(). */
162  STD_RETURN_TYPE_e conv; /*!< Conversion self-check; stores the return value of #MXM_ConvertTest(). */
163  STD_RETURN_TYPE_e firstSetBit; /*!< First Set Bit self-check; stores the return value of #MXM_FirstSetBitTest(). */
165  extractValueFromRegister; /*!< Extract value from Register self-check; stores the return value of #MXM_ExtractValueFromRegisterTest(). */
167  parseVoltageReadall; /*!< Voltage parsing of READALL; stores the return value of #MXM_ParseVoltageReadallTest(). */
169  addressSpaceChecker; /*!< Address space checker; stores the return value of #MXM_5XUserAccessibleAddressSpaceCheckerSelfCheck(). */
171  fmeaStatusASCI; /*!< MAX17841B FMEA register; stores the value of the FMEA check conducted in the state #MXM_STATEMACH_41B_CHECK_FMEA. */
173 
174 /* TODO implement filling of values */
175 /* TODO read and verify OTP register */
176 
177 /** struct describing an entry into the monitoring registry */
178 typedef struct MXM_REGISTRY_ENTRY {
179  bool connected; /*!< state variable, indicates whether monitoring IC is connected */
180  uint8_t deviceAddress; /*!< address that has been assigned during enumeration */
181  MXM_MODEL_ID_e model; /*!< model (e.g. 17853) */
182  MXM_siliconVersion_e siliconVersion; /*!< silicon version of chip */
183  uint32_t deviceID; /*!< 24-bit unique device ID */
185 
186 /**
187  * @brief Length of RX buffer
188  * @details This define describes the length of the array
189  * #MXM_MONITORING_INSTANCE_s::rxBuffer. It is large enough to fit the largest
190  * message that can be written into a single buffer which consists of
191  * 6 command bytes and #MXM_MAXIMUM_NR_OF_MODULES times 2 receive
192  * bytes for the maximum number of connected monitoring ICs.
193  */
194 #define MXM_RX_BUFFER_LENGTH 100
195 
196 /** Status of the Maxim-main-state-machine. */
197 typedef struct MXM_MONITORING_INSTANCE {
198  MXM_STATEMACHINE_STATES_e state; /*!< state of the maxim state-machine */
199  MXM_STATEMACHINE_OPERATION_STATES_e operationSubstate; /*!< substate during operation of monitoring */
200  bool allowStartup; /*!< indicates whether start of state-machine has been requested */
201  bool operationRequested; /*!< indicates whether the measurement cycle should run */
202  bool firstMeasurementDone; /*!< this bit is set after the first measurement cycle */
203  bool stopRequested; /*!< indicates that no new measurement cycles should be run */
204  bool openwireRequested; /*!< indicates that an openwire-check has been requested */
206  /*!< whether undervoltage alert has occurred */ /* TODO remove? replaced by DC? */
207  uint8_t muxCounter; /*!< counter for the currently selected mux channel */
208  MXM_DC_BYTE_e dcByte; /*!< content of the data-check-byte */
209  uint8_t mxmVoltageCellCounter; /*!< counter for getting all cellvoltages */
210  uint8_t highest5xDevice; /*!< address of highest monitoring device of the 5x family */
211  MXM_5X_STATE_REQUEST_STATUS_e requestStatus5x; /*!< status of request to 5x */
212  MXM_5X_COMMAND_PAYLOAD_s batteryCmdBuffer; /*!< buffer for Battery Management Commands */
213  STD_RETURN_TYPE_e resultSelfCheck; /*!< Status of driver-wide self-check */
214  MXM_SELFCHECK_s selfCheck; /*!< stores self check return values */
215  MXM_41B_INSTANCE_s *pInstance41B; /*!< instance-pointer of the 41b-state-machine */
216  MXM_5X_INSTANCE_s *pInstance5X; /*!< instance-pointer of the 5x-state-machine */
217  /**
218  * @brief Local storage for cell-voltages
219  *
220  * This local variable stores the measured cell- and AUX-voltages. Independent
221  * of the actual configuration, it stores the measurement values always at the
222  * same place and never changes in size.
223  * As an example the voltage of cell 5 (cells are numbered from 1 to 14)
224  * in module 0 (modules are numbered from 0 to 31) will be in entry 4.
225  * The voltage of cell 14 of module 1 will be in entry 27. This is independent
226  * of the size of the setup which is defined in the defines
227  * #BS_NR_OF_CELLS_PER_MODULE and #BS_NR_OF_MODULES.
228  * Therefore, the size of the arrays inside this struct is defined as
229  * #MXM_MAXIMUM_NR_OF_MODULES times #MXM_MAXIMUM_NR_OF_CELLS_PER_MODULE.
230  */
232  MXM_REGISTRY_ENTRY_s registry[MXM_MAXIMUM_NR_OF_MODULES]; /*!< registry for connected monitoring ICs */
233  uint8_t rxBuffer[MXM_RX_BUFFER_LENGTH]; /*!< buffer that stores the incoming data from the lower state-machines.
234  It contains the command sequence as it is received on the ASCI together with the Battery Management Protocol command. */
236 
237 /*========== Extern Constant and Variable Declarations ======================*/
238 
239 /*========== Extern Function Prototypes =====================================*/
240 /**
241  * @brief Convert a measurement value to a voltage value.
242  * @details This function converts measurement values from the monitoring
243  * IC into a voltage value. It assumes that measurement values are
244  * spread over the LSB and MSB according to the datasheet. This
245  * means that the two lowest bits are 0 and the 14-bit measurement
246  * is spread over the 14 highest bits.
247  *
248  * The conversion type describes the kind of measurement that has
249  * been executed.
250  * @param[in] lsb LSB of the value
251  * @param[in] msb MSB of the value
252  * @param[out] pTarget pointer in which the converted value
253  * shall be written
254  * @param[in] convType type of conversion (bipolar or unipolar)
255  * @param[in] fullScaleReference_mV reference voltage of full scale
256  * (for voltage measurements 5000)
257  */
258 extern void MXM_Convert(
259  uint8_t lsb,
260  uint8_t msb,
261  uint16_t *pTarget,
262  MXM_CONVERSION_TYPE_e convType,
263  uint32_t fullScaleReference_mV);
264 
265 /**
266  * @brief Test the #MXM_Convert()-function.
267  * @details This test-function is intended as a self-check. It tests whether
268  * the #MXM_Convert()-function computes the values as expected.
269  * @return #STD_OK on successful execution, otherwise #STD_NOT_OK
270  */
272 
273 /**
274  * @brief Extract a value from a single register.
275  * @details This function extracts a single value from a single register.
276  * The register has to be supplied as MSB and LSB. The bitmask has to
277  * be of type #MXM_REG_BM. The extracted value will be written into
278  * value.
279  *
280  * The function can only extract values from single registers
281  * (MSB and LSB)and does not handle values that span multiple
282  * registers.
283  * @param[in] lsb least significant byte of the register
284  * @param[in] msb most significant byte of the register
285  * @param[in] bitmask bitmask for the value
286  * @param[out] pValue pointer to a variable in which the value
287  * should be written
288  */
289 extern void MXM_ExtractValueFromRegister(uint8_t lsb, uint8_t msb, MXM_REG_BM bitmask, uint16_t *pValue);
290 
291 /**
292  * @brief Test #MXM_ExtractValueFromRegister().
293  * @details Self-check that tests whether #MXM_ExtractValueFromRegister() works
294  * as expected.
295  * @return #STD_OK if the self-check has passed successfully
296  */
298 
299 /**
300  * @brief Find Position of first set bit in bitmask
301  * @details Searches a bitmask starting from the lowest bit and returns the
302  * position of the first set bit.
303  * @param[in] bitmask bitmask that should be searched
304  * @return position of first set bit
305  */
306 extern uint8_t MXM_FirstSetBit(uint16_t bitmask);
307 
308 /**
309  * @brief Test #MXM_FirstSetBit().
310  * @details Tests the function #MXM_FirstSetBit() if it works as expected.
311  * @return #STD_OK if the self-check has passed successfully
312  */
314 
315 /**
316  * @brief convert a unipolar 14bit-value and shifts it into the 16bit-format
317  * @details Takes a value in the unipolar 14bit format and transforms it into
318  * a 16bit register entry for the monitoring IC (separated into LSB
319  * and MSB).
320  * @param[in] inputValue unipolar 14bit-value
321  * @param[out] lsb LSB in 16bit-format
322  * @param[out] msb MSB in 16bit-format
323  */
324 extern void MXM_Unipolar14BitInto16Bit(uint16_t inputValue, uint8_t *lsb, uint8_t *msb);
325 
326 /**
327  * @brief convert a voltage value into a unipolar 14bit value
328  * @details Takes a voltage value in mV together with a reference for fullscale
329  * values into a unipolar 14bit value.
330  * @param[in] voltage_mV voltage in mV
331  * @param[in] fullscaleReference_mV value of the fullscale in mV;
332  * typically 5000
333  * @return unipolar 14bit value for usage with
334  * #MXM_Unipolar14BitInto16Bit()
335  */
336 extern uint16_t MXM_VoltageIntoUnipolar14Bit(uint16_t voltage_mV, uint16_t fullscaleReference_mV);
337 
338 /**
339  * @brief Get the string and module number from a global module number
340  * @details Maxim driver knows only one string internally and maps on demand
341  * this one string onto several strings (for instances where several
342  * modules are in the same daisy-chain but belong to different
343  * strings).
344  *
345  * This function assumes that a string contains #BS_NR_OF_MODULES modules
346  * in #BS_NR_OF_STRINGS strings and that they are connected in
347  * a daisy-chain.
348  * @param[in] moduleNumber number of the module in the daisy-chain (starts with 0)
349  * @param[out] pStringNumber pointer where the string number will be written
350  * @param[out] pModuleNumberInString module number in the string
351  */
352 extern void MXM_ConvertModuleToString(
353  const uint16_t moduleNumber,
354  uint8_t *pStringNumber,
355  uint16_t *pModuleNumberInString);
356 
357 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
358 
359 #endif /* FOXBMS__MXM_1785X_TOOLS_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
MXM_MONITORING_STATE
@ MXM_MONITORING_STATE_PASS
@ MXM_MONITORING_STATE_PENDING
@ MXM_MONITORING_STATE_FAIL
uint8_t MXM_FirstSetBit(uint16_t bitmask)
Find Position of first set bit in bitmask.
struct MXM_SELFCHECK MXM_SELFCHECK_s
void MXM_Unipolar14BitInto16Bit(uint16_t inputValue, uint8_t *lsb, uint8_t *msb)
convert a unipolar 14bit-value and shifts it into the 16bit-format
void MXM_ConvertModuleToString(const uint16_t moduleNumber, uint8_t *pStringNumber, uint16_t *pModuleNumberInString)
Get the string and module number from a global module number.
struct MXM_MONITORING_INSTANCE MXM_MONITORING_INSTANCE_s
STD_RETURN_TYPE_e must_check_return MXM_ConvertTest(void)
Test the MXM_Convert()-function.
STD_RETURN_TYPE_e must_check_return MXM_FirstSetBitTest(void)
Test MXM_FirstSetBit().
struct MXM_REGISTRY_ENTRY MXM_REGISTRY_ENTRY_s
uint16_t MXM_VoltageIntoUnipolar14Bit(uint16_t voltage_mV, uint16_t fullscaleReference_mV)
convert a voltage value into a unipolar 14bit value
STD_RETURN_TYPE_e must_check_return MXM_ExtractValueFromRegisterTest(void)
Test MXM_ExtractValueFromRegister().
void MXM_Convert(uint8_t lsb, uint8_t msb, uint16_t *pTarget, MXM_CONVERSION_TYPE_e convType, uint32_t fullScaleReference_mV)
Convert a measurement value to a voltage value.
MXM_STATEMACHINE_OPERATION_STATES_e
@ MXM_INIT_I2C_GET_STAT1
@ MXM_INIT_BALEXP5
@ MXM_OP_WRITE_MUX0
@ MXM_INIT_BALEXP6
@ MXM_INIT_STATUS1
@ MXM_INIT_BALEXP13
@ MXM_INIT_OVTHSETREG
@ MXM_INIT_BALEXP1
@ MXM_INIT_BALEXP9
@ MXM_OP_PINOPEN_RESTORE_CURRENT_SOURCE_CONF
@ MXM_INIT_I2C_SEND_MUX1
@ MXM_INIT_MEASUREEN1
@ MXM_OP_PINOPEN_SET_CURRENT_SOURCES
@ MXM_INIT_GET_ID2
@ MXM_INIT_MEASUREEN2
@ MXM_OP_PINOPEN_GET_SCAN_STROBE
@ MXM_INIT_I2C_PNTR
@ MXM_OP_BAL_START
@ MXM_INIT_BALEXP8
@ MXM_INIT_UVTHSETREG
@ MXM_OP_PINOPEN_COMPSCAN
@ MXM_INIT_SET_FMEA2
@ MXM_INIT_I2C_SEND_MUX0
@ MXM_INIT_BALSWDLY
@ MXM_INIT_GET_VERSION
@ MXM_OP_BAL_CONTROL_SET_ALL
@ MXM_INIT_GET_ID1
@ MXM_INIT_GET_I2C_STAT2
@ MXM_OP_PINOPEN_EXIT
@ MXM_OP_PINOPEN_ENTRY
@ MXM_OP_PINOPEN_PROCESS_OPENWIRE
@ MXM_INIT_BALEXP10
@ MXM_INIT_BALEXP14
@ MXM_INIT_BALEXP12
@ MXM_OP_INCREMENT_MUX_COUNTER
@ MXM_OP_BAL_EXIT
@ MXM_OP_PARSE_VOLTAGES_INTO_DB
@ MXM_INIT_I2C_CFG
@ MXM_INIT_ALRTUVEN
@ MXM_INIT_BALEXP3
@ MXM_OP_SELECT_MUX_CHANNEL
@ MXM_INIT_BALEXP2
@ MXM_OP_WRITE_MUX1
@ MXM_INIT_ALRTOVEN
@ MXM_OP_ENTRY_STATE
@ MXM_INIT_BALEXP7
@ MXM_OP_CYCLE_END_EXIT
@ MXM_OP_GET_VOLTAGES
@ MXM_OP_GET_ALRTSUM
@ MXM_OP_CYCLE_END_ENTRY
@ MXM_OP_BAL_CONTROL_RESET_ALL
@ MXM_OP_BAL_ENTRY
@ MXM_INIT_ACQCFG
@ MXM_INIT_COMPOPNTHREG
@ MXM_OP_PINOPEN_GET_ALRT
@ MXM_INIT_BALEXP4
@ MXM_OP_SET_SCAN_STROBE
@ MXM_OP_GET_SCAN_STROBE
@ MXM_INIT_DEVCFG1
@ MXM_INIT_BALEXP11
@ MXM_INIT_AUXTIMEREG
@ MXM_INIT_AUXGPIOCFG
enum MXM_MONITORING_STATE MXM_MONINTORING_STATE_e
enum MXM_STATEMACHINE_STATES MXM_STATEMACHINE_STATES_e
States of the global Maxim state-machine.
MXM_STATEMACHINE_STATES
States of the global Maxim state-machine.
@ MXM_STATEMACHINE_STATES_OPERATION
@ MXM_STATEMACHINE_STATES_INIT
@ MXM_STATEMACHINE_STATES_SELFCHECK_POST_INIT
@ MXM_STATEMACHINE_STATES_UNINITIALIZED
@ MXM_STATEMACHINE_STATES_IDLE
@ MXM_STATEMACHINE_STATES_SELFCHECK_PRE_INIT
@ MXM_STATEMACHINE_STATES_MAXSTATE
#define MXM_RX_BUFFER_LENGTH
Length of RX buffer.
void MXM_ExtractValueFromRegister(uint8_t lsb, uint8_t msb, MXM_REG_BM bitmask, uint16_t *pValue)
Extract a value from a single register.
Basic defines for the complete Maxim driver.
enum MXM_MODEL_ID MXM_MODEL_ID_e
Type of monitoring device.
enum MXM_siliconVersion MXM_siliconVersion_e
enum MXM_DC_BYTE MXM_DC_BYTE_e
enum MXM_CONVERSION_TYPE MXM_CONVERSION_TYPE_e
#define MXM_MAXIMUM_NR_OF_MODULES
Maximum number of modules.
Headers for the driver for the MAX17841B ASCI and MAX1785x monitoring chip.
MXM_5X_STATE_REQUEST_STATUS_e
Request status of Battery Management Protocol states.
Header for the configuration for the Maxim monitoring chip.
Register map of the MAX1785x monitoring IC.
uint16_t MXM_REG_BM
Type for register access for monitoring ICs.
Struct for the state-variable of state-machine.
Definition: mxm_17841b.h:149
5x statemachine structure
uint8_t rxBuffer[MXM_RX_BUFFER_LENGTH]
STD_RETURN_TYPE_e resultSelfCheck
MXM_41B_INSTANCE_s * pInstance41B
MXM_STATEMACHINE_OPERATION_STATES_e operationSubstate
MXM_SELFCHECK_s selfCheck
MXM_DATA_STORAGE_s localVoltages
Local storage for cell-voltages.
MXM_5X_COMMAND_PAYLOAD_s batteryCmdBuffer
MXM_5X_INSTANCE_s * pInstance5X
MXM_STATEMACHINE_STATES_e state
MXM_5X_STATE_REQUEST_STATUS_e requestStatus5x
MXM_REGISTRY_ENTRY_s registry[MXM_MAXIMUM_NR_OF_MODULES]
uint8_t deviceAddress
MXM_siliconVersion_e siliconVersion
MXM_MODEL_ID_e model
bool connected
uint32_t deviceID
STD_RETURN_TYPE_e parseVoltageReadall
STD_RETURN_TYPE_e extractValueFromRegister
STD_RETURN_TYPE_e conv
STD_RETURN_TYPE_e fmeaStatusASCI
STD_RETURN_TYPE_e firstSetBit
STD_RETURN_TYPE_e addressSpaceChecker
STD_RETURN_TYPE_e crc