foxBMS  1.2.0
The foxBMS Battery Management System API Documentation
sof.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 sof.h
44  * @author foxBMS Team
45  * @date 2020-10-07 (date of creation)
46  * @updated 2020-10-07 (date of last update)
47  * @ingroup APPLICATION
48  * @prefix SOX
49  *
50  * @brief Header for SOX module, responsible for current derating calculation
51  *
52  */
53 
54 #ifndef FOXBMS__SOF_H_
55 #define FOXBMS__SOF_H_
56 
57 /*========== Includes =======================================================*/
58 #include "sof_cfg.h"
59 
60 /*========== Macros and Definitions =========================================*/
61 /**
62  * struct definition for 4 different values: in two current directions (charge,
63  * discharge) for two use cases (peak and continuous)
64  */
65 typedef struct SOF_CURRENT_LIMITS {
66  float continuousChargeCurrent_mA; /*!< maximum current for continues charging */
67  float peakChargeCurrent_mA; /*!< maximum current for peak charging */
68  float continuousDischargeCurrent_mA; /*!< maximum current for continues discharging */
69  float peakDischargeCurrent_mA; /*!< maximum current for peak discharging */
71 
72 /**
73  * struct definition for calculating the linear SOF curve. The SOF curve is
74  * voltage, temperature and charge/discharge dependent.
75  */
76 typedef struct SOF_CURVE {
77  float slopeLowTemperatureDischarge; /*!< low temperature dependent derating slope for discharge current */
78  float offsetLowTemperatureDischarge; /*!< discharge current offset for low temperature dependent derating */
79  float slopeHighTemperatureDischarge; /*!< high temperature dependent derating slope for discharge current */
80  float offsetHighTemperatureDischarge; /*!< discharge current offset for high temperature dependent derating */
81 
82  float slopeLowTemperatureCharge; /*!< low temperature dependent derating slope for charge current */
83  float offsetLowTemperatureCharge; /*!< charge current offset for low temperature dependent derating */
84  float slopeHighTemperatureCharge; /*!< high temperature dependent derating slope for charge current */
85  float offsetHighTemperatureCharge; /*!< charge current offset for high temperature dependent derating */
86 
87  float slopeUpperCellVoltage; /*!< upper cell voltage derating slope for charge and discharge current */
88  float offsetUpperCellVoltage; /*!< charge/discharge current offset for upper voltage derating */
89  float slopeLowerCellVoltage; /*!< lower cell voltage derating slope for charge and discharge current */
90  float offsetLowerCellVoltage; /*!< charge/discharge current offset for lower voltage derating */
92 
93 /*========== Extern Constant and Variable Declarations ======================*/
94 
95 /*========== Extern Function Prototypes =====================================*/
96 /**
97  * @brief initializes the area for SOF (where derating starts and is fully
98  * active).
99  * @details Pseudocode for linear function parameter extraction with 2 points:
100  * - slope = (y2 - y1) / (x2-x1)
101  * - offset = y1 - (slope) * x1
102  * - function y= slope * x + offset
103  */
104 extern void SOF_Init(void);
105 
106 /**
107  * @brief triggers SOF calculation
108  * @details TODO
109  */
110 extern void SOF_Calculation(void);
111 
112 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
113 #ifdef UNITY_UNIT_TEST
114 extern void TEST_SOF_CalculateVoltageBasedCurrentLimit(
115  int16_t minimumCellVoltage_mV,
116  int16_t maximumCellVoltage_mV,
117  SOF_CURRENT_LIMITS_s *pAllowedVoltageBasedCurrent,
118  const SOF_CONFIG_s *pConfigLimitValues,
119  SOF_CURVE_s *pCalculatedSofCurves);
120 extern void TEST_SOF_CalculateTemperatureBasedCurrentLimit(
121  int16_t minimumCellTemperature_ddegC,
122  int16_t maximumCellTemperature_ddegC,
123  SOF_CURRENT_LIMITS_s *pAllowedTemperatureBasedCurrent,
124  const SOF_CONFIG_s *pConfigLimitValues,
125  SOF_CURVE_s *pCalculatedSofCurves);
126 extern SOF_CURRENT_LIMITS_s TEST_SOF_MinimumOfTwoSofValues(
127  SOF_CURRENT_LIMITS_s voltageBasedLimits,
128  SOF_CURRENT_LIMITS_s temperatureBasedLimits);
129 #endif /* UNITY_UNIT_TEST */
130 #endif /* FOXBMS__SOF_H_ */
void SOF_Calculation(void)
triggers SOF calculation
Definition: sof.c:358
struct SOF_CURRENT_LIMITS SOF_CURRENT_LIMITS_s
struct SOF_CURVE SOF_CURVE_s
void SOF_Init(void)
initializes the area for SOF (where derating starts and is fully active).
Definition: sof.c:342
Header for SOF configuration.
float peakDischargeCurrent_mA
Definition: sof.h:69
float peakChargeCurrent_mA
Definition: sof.h:67
float continuousDischargeCurrent_mA
Definition: sof.h:68
float continuousChargeCurrent_mA
Definition: sof.h:66
Definition: sof.h:76
float slopeHighTemperatureDischarge
Definition: sof.h:79
float offsetLowerCellVoltage
Definition: sof.h:90
float offsetLowTemperatureCharge
Definition: sof.h:83
float offsetHighTemperatureDischarge
Definition: sof.h:80
float slopeUpperCellVoltage
Definition: sof.h:87
float slopeLowerCellVoltage
Definition: sof.h:89
float offsetUpperCellVoltage
Definition: sof.h:88
float slopeLowTemperatureCharge
Definition: sof.h:82
float slopeLowTemperatureDischarge
Definition: sof.h:77
float slopeHighTemperatureCharge
Definition: sof.h:84
float offsetLowTemperatureDischarge
Definition: sof.h:78
float offsetHighTemperatureCharge
Definition: sof.h:85