foxBMS  1.1.2
The foxBMS Battery Management System API Documentation
redundancy.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 redundancy.h
44  * @author foxBMS Team
45  * @date 2020-07-31 (date of creation)
46  * @updated 2020-07-31 (date of last update)
47  * @ingroup APPLICATION
48  * @prefix MRC
49  *
50  * @brief Header fileS for handling redundancy between redundant cell voltage
51  * and cell temperature measurements
52  *
53  */
54 
55 #ifndef FOXBMS__REDUNDANCY_H_
56 #define FOXBMS__REDUNDANCY_H_
57 
58 /*========== Includes =======================================================*/
59 #include "general.h"
60 
61 #include "database.h"
62 
63 /*========== Macros and Definitions =========================================*/
64 /**
65  * Maximum time between measurements before the
66  * redundancy module raises an error because a
67  * measurement is not updated anymore.
68  *
69  * The redundancy module will wait a maximum of this time for new current
70  * values. If no new values are updated within this timeframe it
71  * will invalidate the measurement values.
72  */
73 #define MRC_CURRENT_MEASUREMENT_PERIOD_TIMEOUT_ms (250u)
74 
75 /**
76  * Maximum time between MIC measurements before the
77  * redundancy module raises an error because a
78  * measurement is not updated anymore.
79  *
80  * The redundancy module will wait a maximum of this
81  * time for new values from the base MIC measurement and
82  * MIC redundant measurements. If no new values are updated
83  * from both measurement sources within this timeframe
84  * it will validate the measurement values it has up to
85  * this point if possible.
86  */
87 #define MRC_MIC_MEASUREMENT_PERIOD_TIMEOUT_ms (250u)
88 
89 /**
90  * Maximum time between current sensor high voltage, current
91  * and power measurements before the redundancy module raises
92  * an error because a measurement is not updated anymore.
93  *
94  * The redundancy module will wait a maximum of this
95  * time for new values from the current sensor. If no
96  * new values are updated within this timeframe it will
97  * validate the measurement values it has up to this point
98  * if possible.
99  */
100 #define MRC_CURRENT_SENSOR_MEASUREMENT_TIMEOUT_ms (300u)
101 
102 /**
103  * If both, the current sensor and the MIC measurement have no valid values
104  * we try to construct the string voltage by replacing invalid cell voltage
105  * measurements with the average cell voltage in this string. The result of
106  * this estimation will be flagged as invalid if more than the number of
107  * allowed invalid cell voltages are detected. The result will be markes as
108  * valid if less then this number of cells are detected as invalid.
109  */
110 #define MRC_ALLOWED_NUMBER_OF_INVALID_CELL_VOLTAGES (5u)
111 
112 /*========== Extern Constant and Variable Declarations ======================*/
113 /**
114  * This structure contains all the variables relevant for the redundancy state machine.
115  */
116 typedef struct MRC_STATE {
124 
125 /*========== Extern Function Prototypes =====================================*/
126 /**
127  * @brief Function to initalize redundancy module
128  *
129  * @return #STD_OK if module has been initialized successfully, otherwise #STD_NOT_OK
130  */
131 extern STD_RETURN_TYPE_e MRC_Initialize(void);
132 
133 /**
134  * @brief Function to validate the measurement between redundant measurement
135  * values for cell voltage and cell temperature
136  *
137  * @return #STD_OK if measurement has been validated successfully, otherwise i.e.
138  * if no new values have been measured since the last call #STD_NOT_OK
139  */
141 
142 /**
143  * @brief Function to validate the measurements of pack values (string values,
144  * pack values)
145  *
146  * @return #STD_OK if measurement has been validated successfully, otherwise i.e.
147  * if no new values have been measured since the last call #STD_NOT_OK
148  */
150 
151 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
152 #ifdef UNITY_UNIT_TEST
153 extern bool TEST_MRC_MeasurementUpdatedAtLeastOnce(uint32_t timestamp, uint32_t previousTimestamp);
154 extern STD_RETURN_TYPE_e TEST_MRC_MeasurementUpdatedRecently(
155  uint32_t timestamp,
156  uint32_t previousTimestamp,
157  uint32_t timeInterval);
158 extern bool TEST_MRC_ValidateCellVoltageMeasurement(
159  DATA_BLOCK_CELL_VOLTAGE_s *pCellVoltageBase,
160  DATA_BLOCK_CELL_VOLTAGE_s *pCellVoltageRedundancy0);
161 extern bool TEST_MRC_ValidateCellTemperatureMeasurement(
162  DATA_BLOCK_CELL_TEMPERATURE_s *pCellTemperatureBase,
163  DATA_BLOCK_CELL_TEMPERATURE_s *pCellTemperatureRedundancy0);
164 extern void TEST_MRC_ValidateCurrentMeasurement(DATA_BLOCK_CURRENT_SENSOR_s *pTableCurrentSensor);
165 extern void TEST_MRC_ValidatePowerMeasurement(DATA_BLOCK_CURRENT_SENSOR_s *pTableCurrentSensor);
166 extern void TEST_MRC_ValidateStringVoltageMeasurement(
167  DATA_BLOCK_CURRENT_SENSOR_s *pTableCurrentSensor,
168  DATA_BLOCK_CELL_VOLTAGE_s *pTableCellVoltage);
169 extern void TEST_MRC_ValidateHighVoltageMeasurement(DATA_BLOCK_CURRENT_SENSOR_s *pTableCurrentSensor);
170 extern STD_RETURN_TYPE_e TEST_MRC_CalculateCellVoltageMinMaxAverage(
171  DATA_BLOCK_CELL_VOLTAGE_s *pValidatedVoltages,
172  DATA_BLOCK_MIN_MAX_s *pMinMaxAverageValues);
173 extern STD_RETURN_TYPE_e TEST_MRC_CalculateCellTemperatureMinMaxAverage(
174  DATA_BLOCK_CELL_TEMPERATURE_s *pValidatedTemperatures,
175  DATA_BLOCK_MIN_MAX_s *pMinMaxAverageValues);
176 extern STD_RETURN_TYPE_e TEST_MRC_ValidateCellVoltage(
177  DATA_BLOCK_CELL_VOLTAGE_s *pCellvoltageBase,
178  DATA_BLOCK_CELL_VOLTAGE_s *pCellvoltageRedundancy0,
179  DATA_BLOCK_CELL_VOLTAGE_s *pValidatedVoltages);
180 extern STD_RETURN_TYPE_e TEST_MRC_UpdateCellVoltageValidation(
181  DATA_BLOCK_CELL_VOLTAGE_s *pCellvoltage,
182  DATA_BLOCK_CELL_VOLTAGE_s *pValidatedVoltages);
183 extern STD_RETURN_TYPE_e TEST_MRC_ValidateCellTemperature(
184  DATA_BLOCK_CELL_TEMPERATURE_s *pCelltemperatureBase,
185  DATA_BLOCK_CELL_TEMPERATURE_s *pCelltemperatureRedundancy0,
186  DATA_BLOCK_CELL_TEMPERATURE_s *pValidatedTemperatures);
187 extern STD_RETURN_TYPE_e TEST_MRC_UpdateCellTemperatureValidation(
188  DATA_BLOCK_CELL_TEMPERATURE_s *pCellTemperature,
189  DATA_BLOCK_CELL_TEMPERATURE_s *pValidatedTemperature);
190 #endif
191 
192 #endif /* FOXBMS__REDUNDANCY_H_ */
#define BS_NR_OF_STRINGS
Database module header.
enum STD_RETURN_TYPE STD_RETURN_TYPE_e
General macros and definitions for the whole platform.
STD_RETURN_TYPE_e MRC_Initialize(void)
Function to initalize redundancy module.
Definition: redundancy.c:1069
STD_RETURN_TYPE_e MRC_ValidatePackMeasurement(void)
Function to validate the measurements of pack values (string values, pack values)
Definition: redundancy.c:1127
struct MRC_STATE MRC_STATE_s
STD_RETURN_TYPE_e MRC_ValidateMicMeasurement(void)
Function to validate the measurement between redundant measurement values for cell voltage and cell t...
Definition: redundancy.c:1094
uint32_t lastRedundancy0CellvoltageTimestamp
Definition: redundancy.h:118
uint32_t lastRedundancy0CelltemperatureTimestamp
Definition: redundancy.h:120
uint32_t lastStringCurrentTimestamp[BS_NR_OF_STRINGS]
Definition: redundancy.h:121
uint32_t lastBaseCellvoltageTimestamp
Definition: redundancy.h:117
uint32_t lastBaseCelltemperatureTimestamp
Definition: redundancy.h:119
uint32_t lastStringPowerTimestamp[BS_NR_OF_STRINGS]
Definition: redundancy.h:122